open-index/open-npm huggingface dataset:
npm package: @kb-labs/agent-history
Description: File change history, snapshots and conflict resolution for KB Labs Agents
Author: KB Labs
Latest version: 0.6.0

# @kb-labs/agent-history

File change tracking, snapshots, and conflict resolution for KB Labs agents. Enables rollback of agent modifications and safe retry of failed tasks.

## Components

### FileChangeTracker

Tracks all file operations (create, modify, delete) performed by an agent.

```typescript
import { FileChangeTracker } from '@kb-labs/agent-history';

const tracker = new FileChangeTracker();

tracker.recordChange({
  path: 'src/auth.ts',
  type: 'modify',
  before: originalContent,
  after: newContent,
});

const changes = tracker.getChanges();
```

### SnapshotStorage

Persists file snapshots for recovery. Stores original content before modifications.

```typescript
import { SnapshotStorage } from '@kb-labs/agent-history';

const storage = new SnapshotStorage({ baseDir: '.kb/snapshots' });

await storage.save(sessionId, changes);
const snapshot = await storage.load(sessionId);
```

### ConflictDetector

Detects conflicts when agent modifications overlap with external changes (concurrent edits by user or another agent).

```typescript
import { ConflictDetector } from '@kb-labs/agent-history';

const detector = new ConflictDetector();
const conflicts = detector.detect(agentChanges, currentFileState);
```

### ConflictResolver

Resolves detected conflicts with configurable strategies (keep-agent, keep-external, merge).

```typescript
import { ConflictResolver } from '@kb-labs/agent-history';

const resolver = new ConflictResolver();
const result = resolver.resolve(conflict, strategy);
```

## Types

```typescript
import type {
  FileChange,
  RollbackResult,
  ConflictInfo,
  StorageConfig,
  DetectedConflict,
  ConflictType,       // 'modified' | 'deleted' | 'created'
  ResolutionResult,
} from '@kb-labs/agent-history';
```

## Dependencies

- `@kb-labs/agent-contracts` — shared types
npm package: @kb-labs/agent-tools
Description: Agent management tools for planning, coordination, and execution
Author: KB Labs
Latest version: 0.6.0

# @kb-labs/agent-tools

Tool registry and implementations for KB Labs agents. Provides all tools an agent can call through LLM function calling.

## Tools

| Tool | Module | Description |
|------|--------|-------------|
| `fs_read` | filesystem | Read file contents |
| `fs_write` | filesystem | Write/create files |
| `fs_list` | filesystem | List directory contents |
| `fs_search` | filesystem | Search files by pattern |
| `grep_search` | search | Regex search across files |
| `glob_search` | search | Find files by glob pattern |
| `semantic_search` | search | Semantic code search (Mind RAG) |
| `shell_exec` | shell | Execute shell commands (sandboxed) |
| `memory_read` | memory | Read agent memory |
| `memory_write` | memory | Write to agent memory |
| `todo_create` | reporting | Create todo items |
| `todo_update` | reporting | Update todo status |
| `delegate_task` | delegation | Delegate subtask to another agent |
| `ask_user` | interaction | Request user input |
| `mass_replace` | mass-replace | Bulk find-and-replace across files |

## Usage

```typescript
import { createToolRegistry } from '@kb-labs/agent-tools';

const registry = createToolRegistry(context);

// Get tool definitions for LLM function calling
const tools = registry.getDefinitions();

// Execute a tool call
const result = await registry.execute('fs_read', { path: 'src/index.ts' });
```

## Tool Configuration

Permissions and sandbox rules defined in `src/config.ts`:
- File system access boundaries
- Shell command allowlists
- Memory size limits
- Network access rules

## Structure

```
src/
├── types.ts          # Tool interface definitions
├── registry.ts       # Tool registry (register, get, execute)
├── config.ts         # Permissions and sandbox configuration
├── utils.ts          # Shared utilities
└── tools/
    ├── index.ts      # createToolRegistry factory
    ├── filesystem.ts # File read/write/list/search
    ├── search.ts     # grep, glob, semantic search
    ├── shell.ts      # Shell command execution
    ├── memory.ts     # Agent memory operations
    ├── reporting.ts  # Todo and reporting tools
    ├── delegation.ts # Task delegation
    ├── interaction.ts# User interaction
    └── mass-replace.ts
```

## Dependencies

- `@kb-labs/agent-contracts` — shared types
- `@kb-labs/core-platform` — platform services (semantic search)
- `glob` — file pattern matching
npm package: @kb-labs/agent-tracing
Description: Tracing infrastructure for KB Labs Agents — NDJSON writer, privacy redaction, trace loading and analysis
Author: KB Labs
Latest version: 0.6.0

# @kb-labs/agent-tracing

Execution tracing and observability for KB Labs agents. Writes crash-safe NDJSON trace files with privacy redaction and provides tools for loading and analyzing traces.

## Features

- **Crash-safe NDJSON** — append-only writes, no data loss on crash
- **Incremental flushing** — traces available in real-time during execution
- **Privacy redaction** — strips API keys, tokens, personal paths
- **Trace indexing** — fast lookups by event type, tool name, iteration
- **Helper factories** — type-safe builders for all event types

## Components

### IncrementalTraceWriter

Main tracer for production. Writes events to NDJSON file with automatic flushing and indexing.

```typescript
import { IncrementalTraceWriter } from '@kb-labs/agent-tracing';

const writer = new IncrementalTraceWriter({
  outputPath: './traces/run-001.ndjson',
  flushIntervalMs: 1000,
});

writer.write(traceAgentStart({ task, tier, maxIterations, toolCount }));
// ... agent execution ...
writer.write(traceAgentEnd({ success, summary, iterations, tokensUsed, durationMs }));

await writer.close();
```

### FileTracer

In-memory tracer for tests and development.

### TraceLoader

Loads and validates existing NDJSON trace files for CLI analysis commands.

```typescript
import { loadTrace } from '@kb-labs/agent-tracing';

const result = loadTrace('./traces/run-001.ndjson');
if (result.ok) {
  console.log(`${result.events.length} events loaded`);
}
```

### PrivacyRedactor

Redacts sensitive data before persistence:
- API keys and tokens (`sk-...`, `Bearer ...`)
- Personal file paths (`/Users/name/...` → `~/...`)
- Environment variables with secrets

### Trace Helpers

Factory functions for all trace event types:

```typescript
import {
  traceAgentStart,
  traceToolStart,
  traceToolEnd,
  traceLLMEnd,
} from '@kb-labs/agent-tracing';
```

## Trace Format

Each line in an NDJSON file is a JSON object:

```json
{"type":"agent:start","timestamp":"...","data":{"task":"Fix bug","tier":"medium"}}
{"type":"tool:start","timestamp":"...","data":{"toolName":"fs_read","input":{"path":"src/auth.ts"}}}
{"type":"tool:end","timestamp":"...","data":{"toolName":"fs_read","success":true,"durationMs":12}}
```

Default location: `.kb/traces/incremental/`.

## Dependencies

- `@kb-labs/agent-contracts` — event type definitions
- `@kb-labs/sdk` — platform SDK