attocode 0.1.0

package/dist/src/tracing/trace-collector.d.ts

@@ -0,0 +1,274 @@
+/**
+ * Lesson 26: Trace Collector
+ *
+ * Central hub that coordinates tracing, metrics, and cache analysis.
+ * Subscribes to agent events and produces comprehensive JSONL output.
+ *
+ * Key responsibilities:
+ * 1. Capture full LLM request/response details
+ * 2. Track tool execution with timing
+ * 3. Analyze cache efficiency per request
+ * 4. Export structured JSONL for analysis
+ *
+ * @example
+ * ```typescript
+ * const collector = new TraceCollector({
+ *   outputDir: '.traces',
+ *   captureMessageContent: true,
+ * });
+ *
+ * collector.startSession('task-id', 'Write a fizzbuzz function', 'claude-3-sonnet');
+ *
+ * // During agent execution...
+ * collector.recordLLMRequest(requestData);
+ * collector.recordLLMResponse(responseData);
+ * collector.recordToolExecution(toolData);
+ *
+ * // When done
+ * const trace = await collector.endSession({ success: true });
+ * ```
+ */
+import { Tracer } from '../observability/tracer.js';
+import { CacheBoundaryTracker } from './cache-boundary-tracker.js';
+import type { TraceCollectorConfig, SessionTrace, TracedToolCall } from './types.js';
+/**
+ * Event types the collector can receive.
+ */
+export type TraceEvent = {
+    type: 'llm.request';
+    data: LLMRequestData;
+} | {
+    type: 'llm.response';
+    data: LLMResponseData;
+} | {
+    type: 'tool.start';
+    data: ToolStartData;
+} | {
+    type: 'tool.end';
+    data: ToolEndData;
+} | {
+    type: 'iteration.start';
+    data: {
+        iterationNumber: number;
+    };
+} | {
+    type: 'iteration.end';
+    data: {
+        iterationNumber: number;
+    };
+} | {
+    type: 'error';
+    data: ErrorData;
+};
+/**
+ * LLM request data.
+ */
+export interface LLMRequestData {
+    requestId: string;
+    model: string;
+    provider: string;
+    messages: Array<{
+        role: 'system' | 'user' | 'assistant' | 'tool';
+        content: string;
+        toolCallId?: string;
+        toolCalls?: TracedToolCall[];
+    }>;
+    tools?: Array<{
+        name: string;
+        description: string;
+        parametersSchema: Record<string, unknown>;
+    }>;
+    parameters: {
+        maxTokens?: number;
+        temperature?: number;
+        topP?: number;
+        stopSequences?: string[];
+    };
+    systemPrompt?: string;
+}
+/**
+ * LLM response data.
+ */
+export interface LLMResponseData {
+    requestId: string;
+    content: string;
+    toolCalls?: TracedToolCall[];
+    stopReason: 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence';
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+        /** Actual cost from provider (e.g., OpenRouter returns this directly) */
+        cost?: number;
+    };
+    durationMs: number;
+}
+/**
+ * Tool start data.
+ */
+export interface ToolStartData {
+    executionId: string;
+    toolName: string;
+    arguments: Record<string, unknown>;
+}
+/**
+ * Tool end data.
+ */
+export interface ToolEndData {
+    executionId: string;
+    status: 'success' | 'error' | 'timeout' | 'blocked';
+    result?: unknown;
+    error?: Error;
+    durationMs: number;
+}
+/**
+ * Error data.
+ */
+export interface ErrorData {
+    code: string;
+    message: string;
+    context: string;
+    recoverable: boolean;
+    error?: Error;
+}
+/**
+ * Central trace collection hub.
+ */
+export declare class TraceCollector {
+    private config;
+    private tracer;
+    private cacheTracker;
+    private sessionId;
+    private traceId;
+    private task;
+    private model;
+    private startTime;
+    private currentIteration;
+    private iterationSpan;
+    private iterationStartTime;
+    private currentIterationTrace;
+    private iterations;
+    private pendingRequests;
+    private pendingTools;
+    private outputPath;
+    private writeQueue;
+    constructor(config?: Partial<TraceCollectorConfig>);
+    /**
+     * Start a new tracing session.
+     */
+    startSession(sessionId: string, task: string, model: string, metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * End the current session and return the complete trace.
+     */
+    endSession(result: {
+        success: boolean;
+        output?: string;
+        failureReason?: string;
+    }): Promise<SessionTrace>;
+    /**
+     * Record an event.
+     */
+    record(event: TraceEvent): Promise<void>;
+    /**
+     * Record an LLM request.
+     */
+    private recordLLMRequest;
+    /**
+     * Record an LLM response.
+     */
+    private recordLLMResponse;
+    /**
+     * Record tool execution start.
+     */
+    private recordToolStart;
+    /**
+     * Record tool execution end.
+     */
+    private recordToolEnd;
+    /**
+     * Record an error.
+     */
+    private recordError;
+    /**
+     * Start a new iteration.
+     */
+    private startIteration;
+    /**
+     * End the current iteration.
+     */
+    private endIteration;
+    /**
+     * Initialize output file.
+     */
+    private initializeOutput;
+    /**
+     * Write a JSONL entry.
+     */
+    private writeEntry;
+    /**
+     * Flush pending writes.
+     */
+    flush(): Promise<void>;
+    /**
+     * Convert messages to traced format.
+     */
+    private traceMessages;
+    /**
+     * Estimate tokens from text.
+     */
+    private estimateTokens;
+    /**
+     * Estimate input tokens for a request.
+     */
+    private estimateInputTokens;
+    /**
+     * Estimate tokens for tool definitions.
+     */
+    private estimateToolTokens;
+    /**
+     * Truncate result if too large.
+     */
+    private truncateResult;
+    /**
+     * Calculate cost for tokens.
+     */
+    private calculateCost;
+    /**
+     * Simple content hash.
+     */
+    private hashContent;
+    /**
+     * Calculate aggregated metrics across all iterations.
+     */
+    private calculateAggregatedMetrics;
+    /**
+     * Get the underlying tracer.
+     */
+    getTracer(): Tracer;
+    /**
+     * Get the cache tracker.
+     */
+    getCacheTracker(): CacheBoundaryTracker;
+    /**
+     * Get current session ID.
+     */
+    getSessionId(): string | null;
+    /**
+     * Get current trace ID.
+     */
+    getTraceId(): string | null;
+    /**
+     * Check if a session is active.
+     */
+    isSessionActive(): boolean;
+    /**
+     * Get iteration count.
+     */
+    getIterationCount(): number;
+}
+/**
+ * Create a new trace collector.
+ */
+export declare function createTraceCollector(config?: Partial<TraceCollectorConfig>): TraceCollector;
+//# sourceMappingURL=trace-collector.d.ts.map

package/dist/src/tracing/trace-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-collector.d.ts","sourceRoot":"","sources":["../../../src/tracing/trace-collector.ts"],"names":[],"mappings":"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"}