@kb-labs/agent-tracing 0.2.0

package/README.md

@@ -0,0 +1,86 @@
+# @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

package/dist/index.d.ts

@@ -0,0 +1,582 @@
+import * as _kb_labs_agent_contracts from '@kb-labs/agent-contracts';
+import { Tracer, DetailedTraceEntry, TraceEntry, IterationDetailEvent, LLMCallEvent, ToolExecutionEvent, MemorySnapshotEvent, DecisionPointEvent, SynthesisForcedTraceEvent, ErrorCapturedEvent, FactAddedEvent, ArchiveStoreEvent, SummarizationLLMCallEvent, SummarizationResultEvent } from '@kb-labs/agent-contracts';
+import { LLMMessage, LLMToolCallResponse } from '@kb-labs/sdk';
+
+/**
+ * Incremental Trace Writer - NDJSON append-only tracer with crash safety
+ *
+ * Design principle: reliability > speed.
+ * Every event is written synchronously to disk immediately.
+ * Even if the agent crashes mid-execution, all events up to the crash are on disk.
+ *
+ * Features:
+ * - NDJSON format (newline-delimited JSON) for append-only writes
+ * - Synchronous writes — zero event loss, even on crash
+ * - Privacy redaction on trace() call
+ * - Auto-cleanup (keep last 30 traces)
+ * - Index generation for fast CLI queries
+ */
+
+/**
+ * Trace configuration interface
+ */
+interface TraceConfig {
+    version: string;
+    enabled: boolean;
+    level: 'minimal' | 'standard' | 'detailed' | 'debug';
+    incremental: {
+        enabled: boolean;
+        flushIntervalMs: number;
+        maxBufferSize: number;
+        format: 'ndjson';
+    };
+    capture: {
+        prompts: boolean;
+        toolOutputs: boolean;
+        memorySnapshots: boolean;
+        decisions: boolean;
+    };
+    retention: {
+        maxTraces: number;
+        maxDays: number;
+        cleanupOnFinalize: boolean;
+        archiveOlderThan: number;
+        compressArchived: boolean;
+    };
+    privacy: {
+        redactSecrets: boolean;
+        redactPaths: boolean;
+        secretPatterns: string[];
+        pathReplacements: Record<string, string>;
+    };
+    storage: {
+        path: string;
+        indexPath: string;
+    };
+}
+/**
+ * Trace index for fast CLI queries
+ */
+interface TraceIndex {
+    version: string;
+    taskId: string;
+    createdAt: string;
+    finalizedAt: string;
+    summary: {
+        totalEvents: number;
+        iterations: number;
+        status: 'success' | 'failed' | 'incomplete';
+        eventCounts: Record<string, number>;
+    };
+    timing: {
+        startedAt: string;
+        completedAt: string;
+        totalDurationMs: number;
+    };
+    cost: {
+        totalCost: number;
+        currency: 'USD';
+    };
+    errors: number;
+    /** Two-tier memory statistics (aggregated from memory:* events) */
+    memory?: {
+        totalFactsAdded: number;
+        totalArchiveStores: number;
+        summarizationRuns: number;
+        avgCompressionRatio: number;
+        avgNewFactRate: number;
+        finalFactSheetSize: number;
+        finalFactSheetTokens: number;
+        finalArchiveEntries: number;
+        finalArchiveUniqueFiles: number;
+    };
+    iterations: Array<{
+        iteration: number;
+        eventCount: number;
+        llmCalls: number;
+        toolCalls: number;
+    }>;
+}
+/**
+ * Default trace configuration
+ */
+declare const DEFAULT_TRACE_CONFIG: TraceConfig;
+/**
+ * Incremental Trace Writer - crash-safe NDJSON tracer
+ */
+declare class IncrementalTraceWriter implements Tracer {
+    private seq;
+    private filepath;
+    private indexPath;
+    private config;
+    private taskId;
+    private startTime;
+    constructor(taskId: string, config?: Partial<TraceConfig>, outputDir?: string);
+    /**
+     * Record a trace entry — writes synchronously to disk.
+     *
+     * Every call = one appendFileSync. No buffering, no async, no lost events.
+     * If the agent crashes on iteration 5, you have all events from iterations 1-5.
+     */
+    trace(entry: any): void;
+    /**
+     * Get all trace entries (reads from NDJSON file to avoid memory leak)
+     * Returns TraceEntry[] for backward compatibility, but actual format is DetailedTraceEntry[]
+     */
+    getEntries(): any[];
+    /**
+     * Save trace to file (backward compat — no-op, already written synchronously)
+     */
+    save(_filePath: string): Promise<void>;
+    /**
+     * Clear all entries
+     */
+    clear(): void;
+    /**
+     * Finalize trace (generate index, cleanup old traces)
+     */
+    finalize(): Promise<void>;
+    /**
+     * Create index file for fast CLI queries
+     */
+    createIndex(): Promise<void>;
+    /**
+     * Cleanup old traces (keep last N traces)
+     */
+    private cleanupOldTraces;
+    /**
+     * Redact sensitive data from entry using optimized privacy-redactor
+     *
+     * Uses shallow clone optimization - only clones objects that need redaction,
+     * not the entire trace event tree. Returns original if no secrets found.
+     */
+    private redact;
+    /**
+     * Calculate index statistics from trace entries
+     */
+    private calculateIndexStatistics;
+    /**
+     * Ensure directory exists
+     */
+    private ensureDirectoryExists;
+}
+
+/**
+ * File-based tracer that saves execution traces to JSON files
+ */
+
+type AnyEntry = Omit<DetailedTraceEntry, 'seq' | 'timestamp'>;
+/**
+ * File tracer implementation
+ */
+declare class FileTracer implements Tracer {
+    private entries;
+    private taskId;
+    private sessionId?;
+    constructor(taskId: string, sessionId?: string);
+    /**
+     * Record a trace entry
+     */
+    trace(entry: AnyEntry): void;
+    /**
+     * Get all trace entries
+     */
+    getEntries(): TraceEntry[];
+    /**
+     * Save trace to file
+     */
+    save(filePath: string): Promise<void>;
+    /**
+     * Clear all entries
+     */
+    clear(): void;
+    /**
+     * Get trace summary statistics
+     */
+    getSummary(): {
+        totalEntries: number;
+        llmCalls: number;
+        toolCalls: number;
+        totalDuration: number;
+        avgLLMDuration: number;
+        avgToolDuration: number;
+    };
+}
+
+/**
+ * TraceLoader — loads and validates NDJSON trace files for CLI commands.
+ *
+ * Centralizes the logic duplicated across all trace commands:
+ * - taskId format validation (prevent path traversal)
+ * - file existence check
+ * - file size guard (prevent memory exhaustion)
+ * - NDJSON parsing with graceful line-error handling
+ */
+
+declare const TRACE_DIR_RELATIVE: string;
+type TraceLoadError = {
+    kind: 'invalid_task_id';
+    message: string;
+} | {
+    kind: 'not_found';
+    taskId: string;
+} | {
+    kind: 'too_large';
+    sizeBytes: number;
+} | {
+    kind: 'empty';
+    taskId: string;
+} | {
+    kind: 'io_error';
+    message: string;
+};
+type TraceLoadResult = {
+    ok: true;
+    events: DetailedTraceEntry[];
+    taskId: string;
+    filePath: string;
+} | {
+    ok: false;
+    error: TraceLoadError;
+};
+/**
+ * Load and parse a trace file by taskId.
+ *
+ * @param taskId - The task ID (validated against alphanumeric + hyphens/underscores)
+ * @param workingDir - Base directory to resolve `.kb/traces/incremental/` from (default: process.cwd())
+ */
+declare function loadTrace(taskId: string | undefined, workingDir?: string): Promise<TraceLoadResult>;
+/**
+ * Format a TraceLoadError into a human-readable string for CLI output.
+ */
+declare function formatTraceLoadError(error: TraceLoadError): string;
+
+/**
+ * Create iteration:detail event
+ */
+declare function createIterationDetailEvent(params: {
+    iteration: number;
+    maxIterations: number;
+    mode: 'instant' | 'auto' | 'thinking';
+    temperature: number;
+    availableTools: string[];
+    messages: LLMMessage[];
+    totalTokens: number;
+}): Omit<IterationDetailEvent, 'seq' | 'timestamp'>;
+/**
+ * Create llm:call event
+ */
+declare function createLLMCallEvent(params: {
+    iteration: number;
+    model: string;
+    temperature: number;
+    maxTokens: number;
+    tools: string[];
+    response: LLMToolCallResponse;
+    startTime: number;
+    endTime: number;
+}): Omit<LLMCallEvent, 'seq' | 'timestamp'>;
+/**
+ * Create tool:execution event
+ */
+declare function createToolExecutionEvent(params: {
+    iteration: number;
+    toolName: string;
+    callId: string;
+    input: unknown;
+    output: {
+        success: boolean;
+        result?: unknown;
+        error?: {
+            message: string;
+            code?: string;
+            stack?: string;
+        };
+    };
+    startTime: number;
+    endTime: number;
+    metadata?: Record<string, unknown>;
+}): Omit<ToolExecutionEvent, 'seq' | 'timestamp'>;
+/**
+ * Create memory:snapshot event
+ */
+declare function createMemorySnapshotEvent(params: {
+    iteration: number;
+    conversationHistory: number;
+    userPreferences: Record<string, unknown>;
+    facts: string[];
+    findings: string[];
+    filesRead: string[];
+    searchesMade: number;
+    toolsUsed: Record<string, number>;
+}): Omit<MemorySnapshotEvent, 'seq' | 'timestamp'>;
+/**
+ * Create decision:point event
+ */
+declare function createDecisionPointEvent(params: {
+    iteration: number;
+    decision: 'tool_selection' | 'stopping_condition' | 'synthesis';
+    toolSelection?: {
+        chosenTool: string;
+        reasoning: string;
+        alternatives: Array<{
+            tool: string;
+            reason: string;
+        }>;
+    };
+    stoppingCondition?: {
+        shouldStop: boolean;
+        reason: string;
+    };
+}): Omit<DecisionPointEvent, 'seq' | 'timestamp'>;
+/**
+ * Create synthesis:forced event
+ */
+declare function createSynthesisForcedEvent(params: {
+    iteration: number;
+    reason: 'last_iteration' | 'max_iterations' | 'no_tool_call' | 'user_request';
+    lastIteration: number;
+    lastToolCall?: string;
+    synthesisPrompt: string;
+    synthesisResponse: {
+        content: string;
+        tokens: number;
+        durationMs: number;
+    };
+}): Omit<SynthesisForcedTraceEvent, 'seq' | 'timestamp'>;
+/**
+ * Create error:captured event
+ */
+declare function createErrorCapturedEvent(params: {
+    iteration: number;
+    error: Error;
+    lastLLMCall?: {
+        request: unknown;
+        response: unknown;
+        durationMs: number;
+    };
+    lastToolCall?: {
+        name: string;
+        input: unknown;
+        output?: unknown;
+        error?: string;
+    };
+    currentMessages: LLMMessage[];
+    memoryState: {
+        filesRead: string[];
+        searchesMade: number;
+    };
+    availableTools: string[];
+    agentStack: {
+        currentPhase?: string;
+        currentStep?: string;
+        iterationHistory: number[];
+    };
+}): Omit<ErrorCapturedEvent, 'seq' | 'timestamp'>;
+/**
+ * Create prompt:diff event
+ */
+declare function createPromptDiffEvent(params: {
+    iteration: number;
+    messagesAdded: number;
+    messagesRemoved: number;
+    totalMessages: number;
+    changes: Array<{
+        type: 'added' | 'removed' | 'modified';
+        role: 'system' | 'user' | 'assistant';
+        contentPreview: string;
+        index: number;
+    }>;
+    tokensBefore: number;
+    tokensAfter: number;
+}): Omit<_kb_labs_agent_contracts.PromptDiffEvent, 'seq' | 'timestamp'>;
+/**
+ * Create tool:filter event
+ */
+declare function createToolFilterEvent(params: {
+    iteration: number;
+    beforeTools: string[];
+    afterTools: string[];
+    filtered: Array<{
+        name: string;
+        reason: 'last_iteration' | 'mode_restriction' | 'tier_restriction' | 'custom';
+        explanation: string;
+    }>;
+}): Omit<_kb_labs_agent_contracts.ToolFilterEvent, 'seq' | 'timestamp'>;
+/**
+ * Create context:trim event
+ */
+declare function createContextTrimEvent(params: {
+    iteration: number;
+    trigger: 'max_tokens' | 'max_messages' | 'manual';
+    messageCountBefore: number;
+    messageCountAfter: number;
+    tokensBefore: number;
+    tokensAfter: number;
+    messagesRemoved: number;
+    tokensRemoved: number;
+    contentPreview: string;
+    strategy: 'sliding_window' | 'summarization' | 'importance_based';
+}): Omit<_kb_labs_agent_contracts.ContextTrimEvent, 'seq' | 'timestamp'>;
+/**
+ * Create stopping:analysis event
+ */
+declare function createStoppingAnalysisEvent(params: {
+    iteration: number;
+    conditions: {
+        maxIterationsReached: boolean;
+        timeoutReached: boolean;
+        foundTarget: boolean;
+        sufficientContext: boolean;
+        diminishingReturns: boolean;
+        userInterrupt: boolean;
+        error: boolean;
+    };
+    reasoning: string;
+    iterationsUsed: number;
+    iterationsRemaining: number;
+    timeElapsedMs: number;
+    timeRemainingMs?: number;
+    toolCallsInLast3Iterations: number;
+    confidenceScore?: number;
+}): Omit<_kb_labs_agent_contracts.StoppingAnalysisEvent, 'seq' | 'timestamp'>;
+/**
+ * Create llm:validation event
+ */
+declare function createLLMValidationEvent(params: {
+    iteration: number;
+    stopReason: 'tool_use' | 'end_turn' | 'max_tokens' | 'stop_sequence';
+    isValid: boolean;
+    hasContent: boolean;
+    hasToolCalls: boolean;
+    toolCallsValid: boolean;
+    jsonParseable: boolean;
+    schemaValid: boolean;
+    issues: Array<{
+        severity: 'error' | 'warning' | 'info';
+        check: string;
+        message: string;
+        recovery?: string;
+    }>;
+}): Omit<_kb_labs_agent_contracts.LLMValidationEvent, 'seq' | 'timestamp'>;
+/**
+ * Create memory:fact_added event
+ */
+declare function createFactAddedEvent(params: {
+    iteration: number;
+    fact: {
+        id: string;
+        category: string;
+        fact: string;
+        confidence: number;
+        source: string;
+        merged: boolean;
+        superseded?: string;
+    };
+    factSheetStats: {
+        totalFacts: number;
+        estimatedTokens: number;
+        byCategory: Record<string, number>;
+    };
+}): Omit<FactAddedEvent, 'seq' | 'timestamp'>;
+/**
+ * Create memory:archive_store event
+ */
+declare function createArchiveStoreEvent(params: {
+    iteration: number;
+    entry: {
+        id: string;
+        toolName: string;
+        filePath?: string;
+        outputLength: number;
+        estimatedTokens: number;
+        keyFactsExtracted: number;
+    };
+    archiveStats: {
+        totalEntries: number;
+        totalChars: number;
+        uniqueFiles: number;
+        evicted: number;
+    };
+}): Omit<ArchiveStoreEvent, 'seq' | 'timestamp'>;
+/**
+ * Create memory:summarization_llm_call event.
+ * Records the raw LLM interaction for fact extraction debugging.
+ */
+declare function createSummarizationLLMCallEvent(params: {
+    iteration: number;
+    prompt: string;
+    rawResponse: string;
+    parseSuccess: boolean;
+    parseError?: string;
+    durationMs: number;
+    outputTokens: number;
+}): Omit<SummarizationLLMCallEvent, 'seq' | 'timestamp'>;
+/**
+ * Create memory:summarization_result event
+ */
+declare function createSummarizationResultEvent(params: {
+    iteration: number;
+    input: {
+        iterationRange: [number, number];
+        messagesCount: number;
+        inputChars: number;
+        inputTokens: number;
+    };
+    output: {
+        factsExtracted: number;
+        factsByCategory: Record<string, number>;
+        outputTokens: number;
+        llmDurationMs: number;
+    };
+    delta: {
+        factSheetBefore: number;
+        factSheetAfter: number;
+        tokensBefore: number;
+        tokensAfter: number;
+        newFacts: number;
+        mergedFacts: number;
+        evictedFacts: number;
+    };
+    efficiency: {
+        compressionRatio: number;
+        factDensity: number;
+        newFactRate: number;
+    };
+}): Omit<SummarizationResultEvent, 'seq' | 'timestamp'>;
+
+/**
+ * Privacy redaction for trace events
+ *
+ * Uses shallow clone optimization - only clones objects that need redaction,
+ * not the entire trace event tree.
+ */
+
+/**
+ * Redact secrets from a string
+ */
+declare function redactSecretsFromString(str: string, patterns?: RegExp[]): string;
+/**
+ * Redact file paths (replace absolute paths with relative)
+ */
+declare function redactPaths(str: string, replacements: Record<string, string>): string;
+/**
+ * Redact secrets from unknown value (recursive shallow clone)
+ *
+ * Only clones objects/arrays that contain secrets.
+ * Primitives and clean objects are returned as-is (no clone).
+ */
+declare function redactValue(value: unknown, config: TraceConfig['privacy'], depth?: number): unknown;
+/**
+ * Redact secrets from a trace event (shallow clone optimization)
+ *
+ * Only clones parts of the event that need redaction.
+ * Returns original event if no redaction needed.
+ */
+declare function redactTraceEvent(event: DetailedTraceEntry, config: TraceConfig['privacy']): DetailedTraceEntry;
+/**
+ * Create default privacy config
+ */
+declare function createDefaultPrivacyConfig(): TraceConfig['privacy'];
+
+export { DEFAULT_TRACE_CONFIG, FileTracer, IncrementalTraceWriter, TRACE_DIR_RELATIVE, type TraceConfig, type TraceIndex, type TraceLoadError, type TraceLoadResult, createArchiveStoreEvent, createContextTrimEvent, createDecisionPointEvent, createDefaultPrivacyConfig, createErrorCapturedEvent, createFactAddedEvent, createIterationDetailEvent, createLLMCallEvent, createLLMValidationEvent, createMemorySnapshotEvent, createPromptDiffEvent, createStoppingAnalysisEvent, createSummarizationLLMCallEvent, createSummarizationResultEvent, createSynthesisForcedEvent, createToolExecutionEvent, createToolFilterEvent, formatTraceLoadError, loadTrace, redactPaths, redactSecretsFromString, redactTraceEvent, redactValue };