@animus-labs/cortex 0.2.0

package/src/error-classifier.ts

@@ -0,0 +1,199 @@
+/**
+ * Error classifier for LLM and network errors.
+ *
+ * Maps error strings to actionable categories using regex pattern matching.
+ * Follows the same pattern pi-ai uses for context overflow detection,
+ * extended to cover authentication, rate limits, server errors, and network errors.
+ *
+ * The classifier is a pure function. It does not throw, does not modify state.
+ * It takes an error (or error string) and returns a classification.
+ *
+ * Reference: error-recovery.md
+ */
+
+import type { ClassifiedError, ErrorCategory, ErrorSeverity } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Pattern definitions per category (checked in priority order)
+// ---------------------------------------------------------------------------
+
+const AUTHENTICATION_PATTERNS: RegExp[] = [
+  /invalid.api.key/i,
+  /unauthorized/i,
+  /not.logged.in/i,
+  /authentication.required/i,
+  /expired.*token/i,
+  /invalid.*credentials/i,
+  /api.key.*invalid/i,
+  /permission.denied.*key/i,
+  /Could not resolve API key/i,
+];
+
+const RATE_LIMIT_PATTERNS: RegExp[] = [
+  /rate.limit/i,
+  /too.many.requests/i,
+  /\b429\b/,
+  /rate_limit_exceeded/i,
+  /throttl/i,
+  /request.limit.reached/i,
+  /quota.exceeded/i,
+];
+
+// Full context overflow detection delegates to pi-ai's isContextOverflow() when available.
+// These minimal patterns serve as a fallback when pi-ai is not installed.
+const CONTEXT_OVERFLOW_PATTERNS: RegExp[] = [
+  /context.*overflow/i,
+  /too.many.tokens/i,
+  /token.limit/i,
+  /prompt.is.too.long/i,
+];
+
+const SERVER_ERROR_PATTERNS: RegExp[] = [
+  /internal.server.error/i,
+  /\b500\b/,
+  /\b502\b.*bad.gateway/i,
+  /\b503\b.*service.unavailable/i,
+  /\b504\b.*gateway.timeout/i,
+  /server.*error/i,
+  /overloaded/i,
+];
+
+const NETWORK_PATTERNS: RegExp[] = [
+  /ECONNREFUSED/,
+  /ENOTFOUND/,
+  /ETIMEDOUT/,
+  /ECONNRESET/,
+  /network.*error/i,
+  /fetch.failed/i,
+  /socket.hang.up/i,
+  /DNS.*resolution/i,
+];
+
+// ---------------------------------------------------------------------------
+// Severity and action mappings
+// ---------------------------------------------------------------------------
+
+const SEVERITY_MAP: Record<ErrorCategory, ErrorSeverity> = {
+  authentication: 'fatal',
+  rate_limit: 'retry',
+  context_overflow: 'recoverable',
+  server_error: 'retry',
+  network: 'retry',
+  cancelled: 'recoverable',
+  unknown: 'recoverable',
+};
+
+const SUGGESTED_ACTIONS: Record<ErrorCategory, string | undefined> = {
+  authentication: 'Check your API key or re-authenticate in Settings.',
+  rate_limit: 'Rate limit hit. The next tick will be delayed.',
+  context_overflow: 'Context window exceeded. Compaction will run.',
+  server_error: 'The provider is experiencing issues. Retrying.',
+  network: 'Network error. Check your connection.',
+  cancelled: undefined,
+  unknown: undefined,
+};
+
+// ---------------------------------------------------------------------------
+// Pattern matching helpers
+// ---------------------------------------------------------------------------
+
+function matchesAny(message: string, patterns: RegExp[]): boolean {
+  return patterns.some((pattern) => pattern.test(message));
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for the error classifier.
+ */
+export interface ClassifyErrorOptions {
+  /**
+   * The model's context window size in tokens.
+   * Used for context overflow detection when delegating to pi-ai.
+   */
+  contextWindow?: number;
+
+  /**
+   * Whether the agent was aborted (user or system cancellation).
+   * When true, the error is immediately classified as 'cancelled'.
+   * The caller checks agent.state or AbortSignal.aborted and passes this flag;
+   * the classifier itself remains pure.
+   */
+  wasAborted?: boolean;
+}
+
+/**
+ * Classify an error into an actionable category.
+ *
+ * Checks error strings against regex patterns in priority order (first match wins):
+ * 1. Cancelled (if wasAborted is true)
+ * 2. Authentication (9 patterns)
+ * 3. Rate limit (7 patterns)
+ * 4. Context overflow (4 fallback patterns; delegates to pi-ai isContextOverflow when available)
+ * 5. Server error (7 patterns)
+ * 6. Network (8 patterns)
+ * 7. Unknown (catch-all)
+ *
+ * @param error - The error to classify (Error object or string)
+ * @param options - Optional classification options
+ * @returns A ClassifiedError with category, severity, original message, and suggested action
+ */
+export function classifyError(
+  error: Error | string,
+  options?: ClassifyErrorOptions,
+): ClassifiedError {
+  const message = typeof error === 'string' ? error : error.message;
+
+  // 1. Cancelled (highest priority if wasAborted flag is set)
+  if (options?.wasAborted) {
+    return buildResult('cancelled', message);
+  }
+
+  // 2. Authentication
+  if (matchesAny(message, AUTHENTICATION_PATTERNS)) {
+    return buildResult('authentication', message);
+  }
+
+  // 3. Rate limit
+  if (matchesAny(message, RATE_LIMIT_PATTERNS)) {
+    return buildResult('rate_limit', message);
+  }
+
+  // 4. Context overflow
+  // Uses built-in patterns. In Phase 1B, this will also delegate to
+  // pi-ai's isContextOverflow() when available.
+  if (matchesAny(message, CONTEXT_OVERFLOW_PATTERNS)) {
+    return buildResult('context_overflow', message);
+  }
+
+  // 5. Server error
+  if (matchesAny(message, SERVER_ERROR_PATTERNS)) {
+    return buildResult('server_error', message);
+  }
+
+  // 6. Network
+  if (matchesAny(message, NETWORK_PATTERNS)) {
+    return buildResult('network', message);
+  }
+
+  // 7. Unknown (catch-all)
+  return buildResult('unknown', message);
+}
+
+/**
+ * Build a ClassifiedError from a category and original message.
+ */
+function buildResult(category: ErrorCategory, originalMessage: string): ClassifiedError {
+  const action = SUGGESTED_ACTIONS[category];
+  const result: ClassifiedError = {
+    category,
+    severity: SEVERITY_MAP[category],
+    originalMessage,
+  };
+  if (action !== undefined) {
+    result.suggestedAction = action;
+  }
+  return result;
+}

package/src/event-bridge.ts

@@ -0,0 +1,508 @@
+/**
+ * Event bridge: maps pi-agent-core events to normalized consumer events.
+ *
+ * Pi-agent-core emits 10 events across 4 scopes (agent, turn, message, tool).
+ * The event bridge normalizes these into a consumer-facing event stream for
+ * logging, monitoring, and lifecycle hooks.
+ *
+ * Key mappings:
+ *   agent_start  -> loop_start
+ *   agent_end    -> loop_end (onLoopComplete fires here)
+ *   turn_start   -> turn_start
+ *   turn_end     -> turn_end + AgentTextOutput (parse working tags)
+ *   message_start  -> response_start
+ *   message_update -> response_chunk
+ *   message_end    -> response_end
+ *   tool_execution_start  -> tool_call_start
+ *   tool_execution_update -> tool_call_update
+ *   tool_execution_end    -> tool_call_end
+ *
+ * Child event forwarding:
+ *   forwardFrom(childBridge, childTaskId) subscribes to a child agent's
+ *   event bridge and re-emits events on this bridge with childTaskId set.
+ *   Consumers use event.childTaskId to distinguish parent vs child events.
+ *
+ * Reference: cortex-architecture.md (Event Bridge section)
+ */
+
+import type {
+  AgentTextOutput,
+  CortexLogger,
+  CortexUsage,
+  ToolCallStartPayload,
+  ToolCallUpdatePayload,
+  ToolCallEndPayload,
+  ToolContentDetails,
+} from './types.js';
+import { NOOP_LOGGER } from './noop-logger.js';
+import { parseWorkingTags } from './working-tags.js';
+
+// ---------------------------------------------------------------------------
+// Normalized event types emitted to consumers
+// ---------------------------------------------------------------------------
+
+export type CortexEventType =
+  | 'loop_start'
+  | 'loop_end'
+  | 'turn_start'
+  | 'turn_end'
+  | 'response_start'
+  | 'response_chunk'
+  | 'response_end'
+  | 'tool_call_start'
+  | 'tool_call_update'
+  | 'tool_call_end';
+
+/**
+ * Normalized event data emitted by the event bridge.
+ */
+export interface CortexEvent {
+  type: CortexEventType;
+  /** The original pi-agent-core event data (opaque to the bridge). */
+  data?: unknown;
+  /** Parsed text output, present only for turn_end events. */
+  textOutput?: AgentTextOutput;
+  /**
+   * Typed payload for tool events (tool_call_start, tool_call_update, tool_call_end).
+   * Provides typed access to tool event data without casting `data`.
+   */
+  payload?: ToolCallStartPayload | ToolCallUpdatePayload | ToolCallEndPayload;
+  /**
+   * Extracted usage data from the LLM response, present on turn_end events.
+   * Centralizes extraction from pi-ai's AssistantMessage.usage structure so
+   * subscribers (BudgetGuard, CortexAgent, consumers) read typed data instead
+   * of parsing the opaque `data` field themselves.
+   */
+  usage?: CortexUsage;
+  /**
+   * Present when this event originates from a child (sub-agent) event bridge.
+   * The value is the sub-agent's task ID, allowing consumers to route events
+   * to the correct UI component. Absent for parent agent events.
+   */
+  childTaskId?: string;
+}
+
+/**
+ * Callback type for event listeners.
+ */
+export type CortexEventListener = (event: CortexEvent) => void;
+
+// ---------------------------------------------------------------------------
+// Pi-agent-core event types (minimal contract, no runtime dependency)
+// ---------------------------------------------------------------------------
+
+export type PiEventType =
+  | 'agent_start'
+  | 'agent_end'
+  | 'turn_start'
+  | 'turn_end'
+  | 'message_start'
+  | 'message_update'
+  | 'message_end'
+  | 'tool_execution_start'
+  | 'tool_execution_update'
+  | 'tool_execution_end';
+
+export interface PiEvent {
+  type: PiEventType;
+  [key: string]: unknown;
+}
+
+/**
+ * Minimal interface for pi-agent-core's Agent.subscribe().
+ * Returns an unsubscribe function.
+ */
+export interface PiEventSource {
+  subscribe(handler: (event: PiEvent) => void): () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Event type mapping
+// ---------------------------------------------------------------------------
+
+const PI_TO_CORTEX_MAP: Partial<Record<PiEventType, CortexEventType>> = {
+  agent_start: 'loop_start',
+  agent_end: 'loop_end',
+  turn_start: 'turn_start',
+  turn_end: 'turn_end',
+  message_start: 'response_start',
+  message_update: 'response_chunk',
+  message_end: 'response_end',
+  tool_execution_start: 'tool_call_start',
+  tool_execution_update: 'tool_call_update',
+  tool_execution_end: 'tool_call_end',
+};
+
+// ---------------------------------------------------------------------------
+// EventBridge
+// ---------------------------------------------------------------------------
+
+export class EventBridge {
+  private readonly listeners = new Map<CortexEventType, Set<CortexEventListener>>();
+  private readonly allListeners = new Set<CortexEventListener>();
+  private unsubscribeFromPi: (() => void) | null = null;
+  private workingTagsEnabled: boolean;
+  private readonly logger: CortexLogger;
+
+  /**
+   * Create an EventBridge.
+   *
+   * @param workingTagsEnabled - Whether to parse working tags on turn_end
+   * @param logger - Optional logger for diagnostics (defaults to silent no-op)
+   */
+  constructor(workingTagsEnabled = true, logger?: CortexLogger) {
+    this.workingTagsEnabled = workingTagsEnabled;
+    this.logger = logger ?? NOOP_LOGGER;
+  }
+
+  /**
+   * Wire the bridge to a pi-agent-core Agent's event stream.
+   * Stores the unsubscribe function for cleanup.
+   *
+   * @param source - The pi-agent-core Agent (or any PiEventSource)
+   */
+  wire(source: PiEventSource): void {
+    // Clean up previous wiring if any
+    this.unwire();
+
+    this.unsubscribeFromPi = source.subscribe((piEvent: PiEvent) => {
+      this.handlePiEvent(piEvent);
+    });
+  }
+
+  /**
+   * Disconnect from the pi-agent-core event stream.
+   */
+  unwire(): void {
+    if (this.unsubscribeFromPi) {
+      this.unsubscribeFromPi();
+      this.unsubscribeFromPi = null;
+    }
+  }
+
+  /**
+   * Register a listener for a specific event type.
+   *
+   * @param type - The event type to listen for
+   * @param listener - The callback function
+   * @returns An unsubscribe function
+   */
+  on(type: CortexEventType, listener: CortexEventListener): () => void {
+    let typeListeners = this.listeners.get(type);
+    if (!typeListeners) {
+      typeListeners = new Set();
+      this.listeners.set(type, typeListeners);
+    }
+    typeListeners.add(listener);
+
+    return () => {
+      typeListeners!.delete(listener);
+    };
+  }
+
+  /**
+   * Register a listener for all event types.
+   *
+   * @param listener - The callback function
+   * @returns An unsubscribe function
+   */
+  onAll(listener: CortexEventListener): () => void {
+    this.allListeners.add(listener);
+    return () => {
+      this.allListeners.delete(listener);
+    };
+  }
+
+  /**
+   * Forward all events from a child agent's event bridge onto this bridge.
+   *
+   * Each forwarded event gets `childTaskId` set so consumers can distinguish
+   * parent events from child events. Returns an unsubscribe function that
+   * stops forwarding (call when the child agent completes or is destroyed).
+   *
+   * @param childBridge - The child agent's EventBridge
+   * @param childTaskId - The sub-agent task ID to tag forwarded events with
+   * @returns An unsubscribe function
+   */
+  forwardFrom(childBridge: EventBridge, childTaskId: string): () => void {
+    return childBridge.onAll((event) => {
+      this.emit({
+        ...event,
+        childTaskId,
+      });
+    });
+  }
+
+  /**
+   * Update whether working tags parsing is enabled.
+   */
+  setWorkingTagsEnabled(enabled: boolean): void {
+    this.workingTagsEnabled = enabled;
+  }
+
+  /**
+   * Clean up all listeners and disconnect from the pi-agent-core event stream.
+   */
+  destroy(): void {
+    this.unwire();
+    this.listeners.clear();
+    this.allListeners.clear();
+  }
+
+  /**
+   * Handle a pi-agent-core event by mapping and emitting to consumers.
+   */
+  private handlePiEvent(piEvent: PiEvent): void {
+    const cortexType = PI_TO_CORTEX_MAP[piEvent.type];
+    if (!cortexType) {
+      return;
+    }
+
+    const cortexEvent: CortexEvent = {
+      type: cortexType,
+      data: piEvent,
+    };
+
+    // Populate typed payload for tool events
+    const payload = this.extractToolPayload(cortexType, piEvent);
+    if (payload) {
+      cortexEvent.payload = payload;
+    }
+
+    // For turn_end, extract typed usage and parse working tags
+    if (cortexType === 'turn_end') {
+      const usage = this.extractUsage(piEvent);
+      if (usage) {
+        cortexEvent.usage = usage;
+      }
+
+      if (this.workingTagsEnabled) {
+        const text = this.extractTurnText(piEvent);
+        if (text) {
+          cortexEvent.textOutput = parseWorkingTags(text);
+        }
+      }
+    }
+
+    this.emit(cortexEvent);
+  }
+
+  /**
+   * Extract a typed payload from a pi-agent-core tool event.
+   * Returns undefined for non-tool events.
+   */
+  private extractToolPayload(
+    cortexType: CortexEventType,
+    piEvent: PiEvent,
+  ): CortexEvent['payload'] {
+    if (cortexType === 'tool_call_start') {
+      return {
+        toolCallId: String(piEvent['toolCallId'] ?? piEvent['id'] ?? ''),
+        toolName: String(piEvent['toolName'] ?? piEvent['name'] ?? 'unknown'),
+        args: (piEvent['args'] ?? piEvent['input'] ?? {}) as Record<string, unknown>,
+      } satisfies ToolCallStartPayload;
+    }
+
+    if (cortexType === 'tool_call_update') {
+      const partialResult = piEvent['partialResult'] as ToolContentDetails<unknown> | undefined;
+      return {
+        toolCallId: String(piEvent['toolCallId'] ?? piEvent['id'] ?? ''),
+        toolName: String(piEvent['toolName'] ?? piEvent['name'] ?? 'unknown'),
+        args: (piEvent['args'] ?? piEvent['input'] ?? {}) as Record<string, unknown>,
+        partialResult: partialResult ?? { content: [], details: {} },
+      } satisfies ToolCallUpdatePayload;
+    }
+
+    if (cortexType === 'tool_call_end') {
+      const result = piEvent['result'] as ToolContentDetails<unknown> | undefined;
+      const isError = Boolean(piEvent['isError']);
+      const explicitError = piEvent['error'];
+      const payload: ToolCallEndPayload = {
+        toolCallId: String(piEvent['toolCallId'] ?? piEvent['id'] ?? ''),
+        toolName: String(piEvent['toolName'] ?? piEvent['name'] ?? 'unknown'),
+        result: result ?? { content: [], details: {} },
+        durationMs: Number(piEvent['durationMs'] ?? piEvent['duration'] ?? 0),
+        isError,
+      };
+      if (isError) {
+        // Extract error text from multiple possible sources:
+        // 1. Explicit error string field
+        // 2. Error object with message
+        // 3. Result content text (pi-agent-core puts error details here)
+        // 4. Fallback
+        let errorText: string | undefined;
+        if (typeof explicitError === 'string') {
+          errorText = explicitError;
+        } else if (explicitError instanceof Error) {
+          errorText = explicitError.message;
+        } else if (typeof explicitError === 'object' && explicitError !== null && 'message' in (explicitError as Record<string, unknown>)) {
+          errorText = String((explicitError as Record<string, unknown>)['message']);
+        }
+
+        // If no explicit error, extract from result content
+        if (!errorText && result?.content) {
+          const textParts = result.content
+            .filter((c): c is { type: 'text'; text: string } => c.type === 'text')
+            .map(c => c.text);
+          if (textParts.length > 0) {
+            errorText = textParts.join('\n');
+          }
+        }
+
+        payload.error = errorText ?? 'unknown error';
+      }
+      return payload;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Extract the text content from a turn_end event.
+   * Pi-agent-core's turn_end event carries the assistant message for that turn.
+   */
+  private extractTurnText(piEvent: PiEvent): string | null {
+    // The turn_end event from pi-agent-core carries the assistant message.
+    // The structure varies, so we try multiple access patterns.
+
+    // Pattern 1: Direct text property
+    if (typeof piEvent['text'] === 'string') {
+      return piEvent['text'];
+    }
+
+    // Pattern 2: message.content as string
+    const message = piEvent['message'] as Record<string, unknown> | undefined;
+    if (message && typeof message['content'] === 'string') {
+      return message['content'];
+    }
+
+    // Pattern 3: message.content as array with text parts
+    if (message && Array.isArray(message['content'])) {
+      const textParts = (message['content'] as Array<{ type: string; text?: string }>)
+        .filter((part) => part.type === 'text' && typeof part.text === 'string')
+        .map((part) => part.text!);
+      if (textParts.length > 0) {
+        return textParts.join('');
+      }
+    }
+
+    // Pattern 4: result.content
+    const result = piEvent['result'] as Record<string, unknown> | undefined;
+    if (result && typeof result['content'] === 'string') {
+      return result['content'];
+    }
+
+    // Pattern 5: content on the content parts of the result
+    if (result && Array.isArray(result['content'])) {
+      const textParts = (result['content'] as Array<{ type: string; text?: string }>)
+        .filter((part) => part.type === 'text' && typeof part.text === 'string')
+        .map((part) => part.text!);
+      if (textParts.length > 0) {
+        return textParts.join('');
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Extract typed CortexUsage from a turn_end event.
+   *
+   * Pi-ai's AssistantMessage carries usage at message.usage with a nested
+   * cost object. This method navigates the opaque event data once so all
+   * subscribers receive clean, typed usage without duplicating extraction.
+   */
+  private extractUsage(piEvent: PiEvent): CortexUsage | null {
+    // Pattern 1: message.usage (pi-ai AssistantMessage, the primary path)
+    const message = piEvent['message'] as Record<string, unknown> | undefined;
+    if (message) {
+      const usage = this.buildUsageFromObject(message['usage']);
+      if (usage) {
+        if (typeof message['model'] === 'string') {
+          usage.model = message['model'];
+        }
+        return usage;
+      }
+    }
+
+    // Pattern 2: Direct usage property on the event
+    const directUsage = this.buildUsageFromObject(piEvent['usage']);
+    if (directUsage) return directUsage;
+
+    // Pattern 3: result.usage
+    const result = piEvent['result'] as Record<string, unknown> | undefined;
+    if (result) {
+      const resultUsage = this.buildUsageFromObject(result['usage']);
+      if (resultUsage) return resultUsage;
+    }
+
+    return null;
+  }
+
+  /**
+   * Build a CortexUsage from a raw usage-shaped object.
+   * Returns null if the object is not a valid usage structure.
+   */
+  private buildUsageFromObject(raw: unknown): CortexUsage | null {
+    if (!raw || typeof raw !== 'object') return null;
+
+    const u = raw as Record<string, unknown>;
+    const input = typeof u['input'] === 'number' ? u['input'] : 0;
+    const output = typeof u['output'] === 'number' ? u['output'] : 0;
+    const cacheRead = typeof u['cacheRead'] === 'number' ? u['cacheRead'] : 0;
+    const cacheWrite = typeof u['cacheWrite'] === 'number' ? u['cacheWrite'] : 0;
+    const totalTokens = typeof u['totalTokens'] === 'number' ? u['totalTokens'] : input + output;
+
+    // At least one non-zero field to consider this a valid usage object
+    if (input === 0 && output === 0 && cacheRead === 0 && totalTokens === 0) return null;
+
+    let cost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+    const costObj = u['cost'];
+    if (costObj && typeof costObj === 'object') {
+      const c = costObj as Record<string, unknown>;
+      cost = {
+        input: typeof c['input'] === 'number' ? c['input'] : 0,
+        output: typeof c['output'] === 'number' ? c['output'] : 0,
+        cacheRead: typeof c['cacheRead'] === 'number' ? c['cacheRead'] : 0,
+        cacheWrite: typeof c['cacheWrite'] === 'number' ? c['cacheWrite'] : 0,
+        total: typeof c['total'] === 'number' ? c['total'] : 0,
+      };
+    }
+
+    return { input, output, cacheRead, cacheWrite, totalTokens, cost };
+  }
+
+  /**
+   * Emit a normalized event to all matching listeners.
+   * Each listener is wrapped in try/catch so a throwing listener
+   * does not prevent subsequent listeners from receiving the event.
+   */
+  private emit(event: CortexEvent): void {
+    // Notify type-specific listeners
+    const typeListeners = this.listeners.get(event.type);
+    if (typeListeners) {
+      for (const listener of typeListeners) {
+        try {
+          listener(event);
+        } catch (err) {
+          this.logger.error('[EventBridge] listener threw', {
+            eventType: event.type,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    // Notify catch-all listeners
+    for (const listener of this.allListeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        this.logger.error('[EventBridge] catch-all listener threw', {
+          eventType: event.type,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  }
+}