@od-oneapp/ai-platform 0.1.0

package/src/agents/observability/index.ts

@@ -0,0 +1,914 @@
+/**
+ * Agent Observability Module
+ *
+ * Decision tracing and debugging for AI agents:
+ * - Step-by-step execution traces
+ * - Tool decision logging
+ * - Token usage tracking
+ * - Performance metrics
+ * - Structured trace export
+ *
+ * @module agents/observability
+ */
+
+import { logDebug, logInfo, logWarn } from '@repo/shared/logs';
+
+/** Default capture setting for tool data. */
+const DEFAULT_CAPTURE_TOOL_DATA = true;
+
+/** Default maximum tool data size in bytes. */
+const DEFAULT_MAX_TOOL_DATA_SIZE = 10000;
+
+/** Default capture setting for messages. */
+const DEFAULT_CAPTURE_MESSAGES = false;
+
+/** Default console logging setting. */
+const DEFAULT_CONSOLE_LOG = false;
+
+/** Current trace schema version. */
+const TRACE_SCHEMA_VERSION = 1;
+
+// -----------------------------------------------------------------------------
+// Types
+// -----------------------------------------------------------------------------
+
+/** Trace event types */
+export type TraceEventType =
+  | 'step_start'
+  | 'step_end'
+  | 'tool_call'
+  | 'tool_result'
+  | 'model_call'
+  | 'model_response'
+  | 'error'
+  | 'decision'
+  | 'escalation'
+  | 'handoff'
+  | 'checkpoint';
+
+/** Severity levels */
+export type TraceSeverity = 'debug' | 'info' | 'warn' | 'error';
+
+/** Model information */
+export interface ModelInfo {
+  readonly id: string;
+  readonly provider?: string;
+  readonly temperature?: number;
+  readonly maxTokens?: number;
+}
+
+/** Tool call details */
+export interface ToolCallDetail {
+  readonly toolName: string;
+  readonly toolCallId: string;
+  readonly input: unknown;
+  readonly inputSize?: number;
+}
+
+/** Tool result details */
+export interface ToolResultDetail {
+  readonly toolName: string;
+  readonly toolCallId: string;
+  readonly output: unknown;
+  readonly outputSize?: number;
+  readonly success: boolean;
+  readonly error?: string;
+}
+
+/** Model call details */
+export interface ModelCallDetail {
+  readonly model: ModelInfo;
+  readonly messageCount: number;
+  readonly inputTokens?: number;
+  readonly systemPromptLength?: number;
+}
+
+/** Model response details */
+export interface ModelResponseDetail {
+  readonly model: ModelInfo;
+  readonly outputTokens?: number;
+  readonly finishReason?: string;
+  readonly toolCalls?: number;
+  readonly hasText?: boolean;
+}
+
+/** Decision details */
+export interface DecisionDetail {
+  readonly type: 'tool_choice' | 'model_escalation' | 'context_trim' | 'handoff' | 'custom';
+  readonly reason: string;
+  readonly from?: string;
+  readonly to?: string;
+  readonly context?: Record<string, unknown>;
+}
+
+/** Error details */
+export interface ErrorDetail {
+  readonly name: string;
+  readonly message: string;
+  readonly code?: string;
+  readonly stack?: string;
+  readonly retryable?: boolean;
+}
+
+/** Generic trace event */
+export interface TraceEvent<T = unknown> {
+  /** Event ID */
+  readonly id: string;
+  /** Parent event ID */
+  readonly parentId?: string;
+  /** Event type */
+  readonly type: TraceEventType;
+  /** Timestamp */
+  readonly timestamp: Date;
+  /** Duration in milliseconds (for completed events) */
+  readonly durationMs?: number;
+  /** Severity */
+  readonly severity: TraceSeverity;
+  /** Event-specific details */
+  readonly detail: T;
+  /** Arbitrary metadata */
+  readonly metadata?: Record<string, unknown>;
+}
+
+/** Agent execution trace */
+export interface AgentTrace {
+  /** Trace ID */
+  readonly traceId: string;
+  /** Agent ID */
+  readonly agentId: string;
+  /** Session ID */
+  readonly sessionId?: string;
+  /** User prompt */
+  readonly prompt: string;
+  /** Start time */
+  readonly startedAt: Date;
+  /** End time */
+  readonly endedAt?: Date;
+  /** Total duration */
+  readonly durationMs?: number;
+  /** All events */
+  readonly events: TraceEvent[];
+  /** Total steps */
+  readonly totalSteps: number;
+  /** Total tool calls */
+  readonly totalToolCalls: number;
+  /** Token usage */
+  readonly usage: {
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly totalTokens: number;
+    readonly totalCost?: number;
+  };
+  /** Final result */
+  readonly result?: {
+    readonly success: boolean;
+    readonly output?: unknown;
+    readonly error?: string;
+  };
+  /** Trace schema version */
+  readonly version: number;
+}
+
+/** Trace export format */
+export type TraceExportFormat = 'json' | 'opentelemetry' | 'langsmith' | 'custom';
+
+/** Tracer configuration */
+export interface TracerConfig {
+  /** Agent ID */
+  agentId: string;
+  /** Session ID */
+  sessionId?: string;
+  /** Initial prompt */
+  prompt: string;
+  /** Whether to capture tool inputs/outputs */
+  captureToolData?: boolean;
+  /** Max size for tool data capture */
+  maxToolDataSize?: number;
+  /** Whether to capture model messages */
+  captureMessages?: boolean;
+  /** Custom event handlers */
+  onEvent?: (event: TraceEvent) => void;
+  /** Log events to console */
+  consoleLog?: boolean;
+}
+
+// -----------------------------------------------------------------------------
+// Agent Tracer
+// -----------------------------------------------------------------------------
+
+/**
+ * Traces agent execution for debugging and observability.
+ *
+ * @example
+ * ```typescript
+ * const tracer = new AgentTracer({
+ *   agentId: 'research-agent',
+ *   prompt: 'Research quantum computing',
+ * });
+ *
+ * tracer.startStep(1);
+ * tracer.recordModelCall({ model: { id: 'claude-sonnet' }, messageCount: 3 });
+ * tracer.recordToolCall({ toolName: 'search', toolCallId: 'tc_1', input: { query: 'quantum' } });
+ * tracer.recordToolResult({ toolName: 'search', toolCallId: 'tc_1', output: results, success: true });
+ * tracer.endStep(1);
+ *
+ * const trace = tracer.finalize();
+ * ```
+ */
+export class AgentTracer {
+  private readonly config: {
+    agentId: string;
+    sessionId?: string;
+    prompt: string;
+    captureToolData: boolean;
+    maxToolDataSize: number;
+    captureMessages: boolean;
+    onEvent?: (event: TraceEvent) => void;
+    consoleLog: boolean;
+  };
+  private readonly traceId: string;
+  private readonly events: TraceEvent[] = [];
+  private readonly startTime: Date;
+  private currentStepId: string | null = null;
+  private stepCount = 0;
+  private toolCallCount = 0;
+  private usage = {
+    promptTokens: 0,
+    completionTokens: 0,
+    totalTokens: 0,
+    totalCost: 0,
+  };
+
+  constructor(config: TracerConfig) {
+    this.traceId = generateTraceId();
+    this.startTime = new Date();
+    this.config = {
+      agentId: config.agentId,
+      sessionId: config.sessionId,
+      prompt: config.prompt,
+      captureToolData: config.captureToolData ?? DEFAULT_CAPTURE_TOOL_DATA,
+      maxToolDataSize: config.maxToolDataSize ?? DEFAULT_MAX_TOOL_DATA_SIZE,
+      captureMessages: config.captureMessages ?? DEFAULT_CAPTURE_MESSAGES,
+      onEvent: config.onEvent,
+      consoleLog: config.consoleLog ?? DEFAULT_CONSOLE_LOG,
+    };
+  }
+
+  /**
+   * Get current trace ID.
+   * @returns The trace identifier.
+   */
+  public get id(): string {
+    return this.traceId;
+  }
+
+  /**
+   * Get event count.
+   * @returns The number of events recorded.
+   */
+  public get eventCount(): number {
+    return this.events.length;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Step Tracking
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Start tracking a new step.
+   * @param stepNumber - The step number to start.
+   * @param metadata - Optional metadata for the step.
+   * @returns The event ID for the step.
+   */
+  public startStep(stepNumber: number, metadata?: Record<string, unknown>): string {
+    const eventId = this.generateEventId();
+    this.currentStepId = eventId;
+    this.stepCount = Math.max(this.stepCount, stepNumber);
+
+    this.addEvent({
+      id: eventId,
+      type: 'step_start',
+      timestamp: new Date(),
+      severity: 'info',
+      detail: { stepNumber },
+      metadata,
+    });
+
+    return eventId;
+  }
+
+  /**
+   * End the current step.
+   * @param stepNumber - The step number to end.
+   * @param metadata - Optional metadata for the step.
+   */
+  public endStep(stepNumber: number, metadata?: Record<string, unknown>): void {
+    const startEvent = this.events.find(
+      e =>
+        e.type === 'step_start' && (e.detail as { stepNumber: number }).stepNumber === stepNumber,
+    );
+
+    const durationMs = startEvent ? Date.now() - startEvent.timestamp.getTime() : undefined;
+
+    this.addEvent({
+      id: this.generateEventId(),
+      parentId: this.currentStepId ?? undefined,
+      type: 'step_end',
+      timestamp: new Date(),
+      durationMs,
+      severity: 'info',
+      detail: { stepNumber },
+      metadata,
+    });
+
+    this.currentStepId = null;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Model Tracking
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Record a model call.
+   * @param detail - Model call details.
+   * @param metadata - Optional metadata.
+   * @returns The event ID.
+   */
+  public recordModelCall(detail: ModelCallDetail, metadata?: Record<string, unknown>): string {
+    const eventId = this.generateEventId();
+
+    this.addEvent({
+      id: eventId,
+      parentId: this.currentStepId ?? undefined,
+      type: 'model_call',
+      timestamp: new Date(),
+      severity: 'debug',
+      detail,
+      metadata,
+    });
+
+    if (detail.inputTokens) {
+      this.usage.promptTokens += detail.inputTokens;
+      this.usage.totalTokens += detail.inputTokens;
+    }
+
+    return eventId;
+  }
+
+  /**
+   * Record a model response.
+   * @param callEventId - The ID of the model call event.
+   * @param detail - Model response details.
+   * @param metadata - Optional metadata.
+   */
+  public recordModelResponse(
+    callEventId: string,
+    detail: ModelResponseDetail,
+    metadata?: Record<string, unknown>,
+  ): void {
+    const callEvent = this.events.find(e => e.id === callEventId);
+    const durationMs = callEvent ? Date.now() - callEvent.timestamp.getTime() : undefined;
+
+    this.addEvent({
+      id: this.generateEventId(),
+      parentId: callEventId,
+      type: 'model_response',
+      timestamp: new Date(),
+      durationMs,
+      severity: 'debug',
+      detail,
+      metadata,
+    });
+
+    if (detail.outputTokens) {
+      this.usage.completionTokens += detail.outputTokens;
+      this.usage.totalTokens += detail.outputTokens;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Tool Tracking
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Record a tool call.
+   */
+  recordToolCall(detail: ToolCallDetail, metadata?: Record<string, unknown>): string {
+    const eventId = this.generateEventId();
+    this.toolCallCount++;
+
+    const capturedDetail = this.config.captureToolData
+      ? {
+          ...detail,
+          input: this.truncateData(detail.input),
+          inputSize: this.getDataSize(detail.input),
+        }
+      : { toolName: detail.toolName, toolCallId: detail.toolCallId };
+
+    this.addEvent({
+      id: eventId,
+      parentId: this.currentStepId ?? undefined,
+      type: 'tool_call',
+      timestamp: new Date(),
+      severity: 'info',
+      detail: capturedDetail,
+      metadata,
+    });
+
+    return eventId;
+  }
+
+  /**
+   * Record a tool result.
+   */
+  recordToolResult(
+    callEventId: string,
+    detail: ToolResultDetail,
+    metadata?: Record<string, unknown>,
+  ): void {
+    const callEvent = this.events.find(e => e.id === callEventId);
+    const durationMs = callEvent ? Date.now() - callEvent.timestamp.getTime() : undefined;
+
+    const capturedDetail = this.config.captureToolData
+      ? {
+          ...detail,
+          output: detail.success ? this.truncateData(detail.output) : undefined,
+          outputSize: this.getDataSize(detail.output),
+        }
+      : {
+          toolName: detail.toolName,
+          toolCallId: detail.toolCallId,
+          success: detail.success,
+          error: detail.error,
+        };
+
+    this.addEvent({
+      id: this.generateEventId(),
+      parentId: callEventId,
+      type: 'tool_result',
+      timestamp: new Date(),
+      durationMs,
+      severity: detail.success ? 'info' : 'warn',
+      detail: capturedDetail,
+      metadata,
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Decision Tracking
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Record a decision point.
+   */
+  recordDecision(detail: DecisionDetail, metadata?: Record<string, unknown>): void {
+    this.addEvent({
+      id: this.generateEventId(),
+      parentId: this.currentStepId ?? undefined,
+      type: 'decision',
+      timestamp: new Date(),
+      severity: 'info',
+      detail,
+      metadata,
+    });
+
+    if (this.config.consoleLog) {
+      logInfo(`[AgentTracer] Decision: ${detail.type} - ${detail.reason}`);
+    }
+  }
+
+  /**
+   * Record a model escalation.
+   */
+  recordEscalation(
+    fromModel: string,
+    toModel: string,
+    reason: string,
+    metadata?: Record<string, unknown>,
+  ): void {
+    this.addEvent({
+      id: this.generateEventId(),
+      parentId: this.currentStepId ?? undefined,
+      type: 'escalation',
+      timestamp: new Date(),
+      severity: 'info',
+      detail: { from: fromModel, to: toModel, reason },
+      metadata,
+    });
+
+    if (this.config.consoleLog) {
+      logInfo(`[AgentTracer] Escalation: ${fromModel} -> ${toModel} (${reason})`);
+    }
+  }
+
+  /**
+   * Record a handoff between agents.
+   */
+  recordHandoff(
+    fromAgent: string,
+    toAgent: string,
+    reason: string,
+    metadata?: Record<string, unknown>,
+  ): void {
+    this.addEvent({
+      id: this.generateEventId(),
+      parentId: this.currentStepId ?? undefined,
+      type: 'handoff',
+      timestamp: new Date(),
+      severity: 'info',
+      detail: { from: fromAgent, to: toAgent, reason },
+      metadata,
+    });
+
+    if (this.config.consoleLog) {
+      logInfo(`[AgentTracer] Handoff: ${fromAgent} -> ${toAgent} (${reason})`);
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Error Tracking
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Record an error.
+   */
+  recordError(error: Error | ErrorDetail, metadata?: Record<string, unknown>): void {
+    const detail: ErrorDetail =
+      error instanceof Error
+        ? {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+          }
+        : error;
+
+    this.addEvent({
+      id: this.generateEventId(),
+      parentId: this.currentStepId ?? undefined,
+      type: 'error',
+      timestamp: new Date(),
+      severity: 'error',
+      detail,
+      metadata,
+    });
+
+    if (this.config.consoleLog) {
+      logWarn(`[AgentTracer] Error: ${detail.message}`);
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Checkpoint Tracking
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Record a checkpoint.
+   */
+  recordCheckpoint(checkpointId: string, metadata?: Record<string, unknown>): void {
+    this.addEvent({
+      id: this.generateEventId(),
+      parentId: this.currentStepId ?? undefined,
+      type: 'checkpoint',
+      timestamp: new Date(),
+      severity: 'info',
+      detail: { checkpointId },
+      metadata,
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Token Usage
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Update token usage.
+   */
+  updateUsage(usage: { promptTokens?: number; completionTokens?: number; cost?: number }): void {
+    if (usage.promptTokens !== undefined) {
+      this.usage.promptTokens += usage.promptTokens;
+      this.usage.totalTokens += usage.promptTokens;
+    }
+    if (usage.completionTokens !== undefined) {
+      this.usage.completionTokens += usage.completionTokens;
+      this.usage.totalTokens += usage.completionTokens;
+    }
+    if (usage.cost !== undefined) {
+      this.usage.totalCost += usage.cost;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Finalization
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Finalize and return the complete trace.
+   * @param result - Optional result information.
+   * @returns The complete agent trace.
+   */
+  public finalize(result?: { success: boolean; output?: unknown; error?: string }): AgentTrace {
+    const endedAt = new Date();
+
+    return {
+      traceId: this.traceId,
+      agentId: this.config.agentId,
+      sessionId: this.config.sessionId,
+      prompt: this.config.prompt,
+      startedAt: this.startTime,
+      endedAt,
+      durationMs: endedAt.getTime() - this.startTime.getTime(),
+      events: [...this.events],
+      totalSteps: this.stepCount,
+      totalToolCalls: this.toolCallCount,
+      usage: { ...this.usage },
+      result,
+      version: TRACE_SCHEMA_VERSION,
+    };
+  }
+
+  /**
+   * Get current trace snapshot without finalizing.
+   * @returns A snapshot of the current trace state.
+   */
+  public snapshot(): AgentTrace {
+    return {
+      traceId: this.traceId,
+      agentId: this.config.agentId,
+      sessionId: this.config.sessionId,
+      prompt: this.config.prompt,
+      startedAt: this.startTime,
+      durationMs: Date.now() - this.startTime.getTime(),
+      events: [...this.events],
+      totalSteps: this.stepCount,
+      totalToolCalls: this.toolCallCount,
+      usage: { ...this.usage },
+      version: TRACE_SCHEMA_VERSION,
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Query
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Get events by type.
+   * @param type - The event type to filter by.
+   * @returns Events matching the specified type.
+   */
+  public getEventsByType(type: TraceEventType): TraceEvent[] {
+    return this.events.filter(e => e.type === type);
+  }
+
+  /**
+   * Get events for a specific step.
+   * @param stepNumber - The step number to get events for.
+   * @returns Events for the specified step.
+   */
+  public getStepEvents(stepNumber: number): TraceEvent[] {
+    const stepStart = this.events.find(
+      e =>
+        e.type === 'step_start' && (e.detail as { stepNumber: number }).stepNumber === stepNumber,
+    );
+
+    if (!stepStart) return [];
+
+    // Find all events with this step as parent
+    return this.events.filter(e => e.parentId === stepStart.id || e.id === stepStart.id);
+  }
+
+  /**
+   * Get decision trace (filtered view).
+   * @returns Decision events from the trace.
+   */
+  public getDecisionTrace(): TraceEvent<DecisionDetail>[] {
+    return this.events.filter(e => e.type === 'decision') as TraceEvent<DecisionDetail>[];
+  }
+
+  /**
+   * Get error events.
+   * @returns Error events from the trace.
+   */
+  public getErrors(): TraceEvent<ErrorDetail>[] {
+    return this.events.filter(e => e.type === 'error') as TraceEvent<ErrorDetail>[];
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private
+  // ---------------------------------------------------------------------------
+
+  private addEvent(event: TraceEvent): void {
+    this.events.push(event);
+
+    if (this.config.onEvent) {
+      this.config.onEvent(event);
+    }
+
+    if (this.config.consoleLog) {
+      logDebug(`[AgentTracer] ${event.type}: ${JSON.stringify(event.detail)}`);
+    }
+  }
+
+  private generateEventId(): string {
+    return `evt_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+  }
+
+  private truncateData(data: unknown): unknown {
+    const str = JSON.stringify(data);
+    if (str.length <= this.config.maxToolDataSize) {
+      return data;
+    }
+    return `[truncated: ${str.length} bytes]`;
+  }
+
+  private getDataSize(data: unknown): number {
+    try {
+      return JSON.stringify(data).length;
+    } catch {
+      return 0;
+    }
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Trace Exporter
+// -----------------------------------------------------------------------------
+
+/** Export options */
+export interface TraceExportOptions {
+  /** Format to export */
+  format: TraceExportFormat;
+  /** Include full tool data */
+  includeToolData?: boolean;
+  /** Include full messages */
+  includeMessages?: boolean;
+  /** Pretty print JSON */
+  pretty?: boolean;
+}
+
+/**
+ * Export a trace to various formats.
+ */
+export function exportTrace(trace: AgentTrace, options: TraceExportOptions): string | object {
+  switch (options.format) {
+    case 'json':
+      return options.pretty ? JSON.stringify(trace, null, 2) : JSON.stringify(trace);
+
+    case 'opentelemetry':
+      return exportToOpenTelemetry(trace);
+
+    case 'langsmith':
+      return exportToLangSmith(trace);
+
+    case 'custom':
+      return trace;
+
+    default:
+      throw new Error(`Unknown export format: ${options.format}`);
+  }
+}
+
+function exportToOpenTelemetry(trace: AgentTrace): object {
+  // Convert to OpenTelemetry span format
+  return {
+    resourceSpans: [
+      {
+        resource: {
+          attributes: [
+            { key: 'service.name', value: { stringValue: 'ai-agent' } },
+            { key: 'agent.id', value: { stringValue: trace.agentId } },
+          ],
+        },
+        scopeSpans: [
+          {
+            scope: { name: '@od-oneapp/ai-platform' },
+            spans: trace.events.map(event => ({
+              traceId: trace.traceId,
+              spanId: event.id,
+              parentSpanId: event.parentId,
+              name: event.type,
+              startTimeUnixNano: event.timestamp.getTime() * 1e6,
+              endTimeUnixNano: event.durationMs
+                ? (event.timestamp.getTime() + event.durationMs) * 1e6
+                : event.timestamp.getTime() * 1e6,
+              attributes: Object.entries(event.detail as Record<string, unknown>).map(([k, v]) => ({
+                key: k,
+                value: { stringValue: String(v) },
+              })),
+            })),
+          },
+        ],
+      },
+    ],
+  };
+}
+
+function exportToLangSmith(trace: AgentTrace): object {
+  // Convert to LangSmith run format
+  return {
+    id: trace.traceId,
+    name: `agent-${trace.agentId}`,
+    run_type: 'chain',
+    start_time: trace.startedAt.toISOString(),
+    end_time: trace.endedAt?.toISOString(),
+    inputs: { prompt: trace.prompt },
+    outputs: trace.result,
+    child_runs: trace.events.map(event => ({
+      id: event.id,
+      parent_run_id: event.parentId ?? trace.traceId,
+      name: event.type,
+      run_type: event.type.includes('tool') ? 'tool' : 'llm',
+      start_time: event.timestamp.toISOString(),
+      inputs: event.detail,
+      outputs: event.metadata,
+    })),
+  };
+}
+
+// -----------------------------------------------------------------------------
+// Factory Functions
+// -----------------------------------------------------------------------------
+
+/**
+ * Create a new agent tracer.
+ */
+export function createAgentTracer(config: TracerConfig): AgentTracer {
+  return new AgentTracer(config);
+}
+
+/**
+ * Create a tracer with OpenTelemetry integration.
+ */
+export function createOTelTracer(
+  config: TracerConfig,
+  spanExporter?: (event: TraceEvent) => void,
+): AgentTracer {
+  return new AgentTracer({
+    ...config,
+    onEvent: event => {
+      if (spanExporter) {
+        spanExporter(event);
+      }
+      config.onEvent?.(event);
+    },
+  });
+}
+
+// -----------------------------------------------------------------------------
+// Utilities
+// -----------------------------------------------------------------------------
+
+function generateTraceId(): string {
+  return `trace_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/**
+ * Summarize a trace for logging.
+ */
+export function summarizeTrace(trace: AgentTrace): string {
+  const lines = [
+    `Trace: ${trace.traceId}`,
+    `Agent: ${trace.agentId}`,
+    `Duration: ${trace.durationMs ?? 0}ms`,
+    `Steps: ${trace.totalSteps}`,
+    `Tool Calls: ${trace.totalToolCalls}`,
+    `Tokens: ${trace.usage.totalTokens} (${trace.usage.promptTokens} prompt, ${trace.usage.completionTokens} completion)`,
+  ];
+
+  if (trace.result) {
+    lines.push(`Result: ${trace.result.success ? 'Success' : 'Failed'}`);
+    if (trace.result.error) {
+      lines.push(`Error: ${trace.result.error}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Get trace metrics.
+ */
+export function getTraceMetrics(trace: AgentTrace): {
+  totalDuration: number;
+  avgStepDuration: number;
+  avgToolDuration: number;
+  modelCallCount: number;
+  errorCount: number;
+  tokensPerStep: number;
+} {
+  const stepEndEvents = trace.events.filter(e => e.type === 'step_end');
+  const toolResultEvents = trace.events.filter(e => e.type === 'tool_result');
+  const modelCallEvents = trace.events.filter(e => e.type === 'model_call');
+  const errorEvents = trace.events.filter(e => e.type === 'error');
+
+  const totalStepDuration = stepEndEvents.reduce((sum, e) => sum + (e.durationMs ?? 0), 0);
+  const totalToolDuration = toolResultEvents.reduce((sum, e) => sum + (e.durationMs ?? 0), 0);
+
+  return {
+    totalDuration: trace.durationMs ?? 0,
+    avgStepDuration: stepEndEvents.length > 0 ? totalStepDuration / stepEndEvents.length : 0,
+    avgToolDuration: toolResultEvents.length > 0 ? totalToolDuration / toolResultEvents.length : 0,
+    modelCallCount: modelCallEvents.length,
+    errorCount: errorEvents.length,
+    tokensPerStep: trace.totalSteps > 0 ? trace.usage.totalTokens / trace.totalSteps : 0,
+  };
+}