@animalabs/agent-framework 0.1.0

package/src/types/inference-log.ts

@@ -0,0 +1,64 @@
+/**
+ * Types for inference logging - captures raw LLM requests and responses
+ */
+
+// Re-export InferenceLogEntry from framework.ts for convenience
+export type { InferenceLogEntry } from './framework.js';
+
+/**
+ * Query options for inference logs
+ */
+export interface InferenceLogQuery {
+  /** Filter by agent name */
+  agentName?: string;
+  /** Max number of logs to return */
+  limit?: number;
+  /** Skip first N logs (for pagination) */
+  offset?: number;
+  /** Search pattern for content (regex) */
+  pattern?: string;
+  /** Only show failures */
+  errorsOnly?: boolean;
+}
+
+/**
+ * Result from querying inference logs
+ */
+export interface InferenceLogQueryResult {
+  /** Matching entries */
+  entries: InferenceLogEntryWithId[];
+  /** Total count matching query (before pagination) */
+  total: number;
+  /** Whether more entries exist beyond limit */
+  hasMore: boolean;
+}
+
+/**
+ * Inference log entry with Chronicle sequence ID
+ */
+export interface InferenceLogEntryWithId {
+  /** Chronicle sequence number (acts as ID) */
+  sequence: number;
+  /** The log entry data (may contain blob references) */
+  entry: import('./framework.js').InferenceLogEntry;
+  /** Summary info for display without resolving blobs */
+  summary?: InferenceLogSummary;
+}
+
+/**
+ * Summary view of an inference log (without full request/response)
+ */
+export interface InferenceLogSummary {
+  timestamp: number;
+  agentName: string;
+  requestId: string;
+  success: boolean;
+  error?: string;
+  durationMs: number;
+  tokenUsage?: { input: number; output: number; cacheCreation?: number; cacheRead?: number };
+  stopReason?: string;
+  /** Whether request is stored as blob */
+  requestIsBlob: boolean;
+  /** Whether response is stored as blob */
+  responseIsBlob: boolean;
+}

package/src/types/module.ts

@@ -0,0 +1,367 @@
+import type { ContentBlock } from '@animalabs/membrane';
+import type {
+  MessageId,
+  MessageMetadata,
+  StoredMessage,
+  ContextInjection,
+} from '@animalabs/context-manager';
+import type { ProcessEvent, ToolDefinition, ToolCall, ToolResult } from './events.js';
+
+/**
+ * Filter criteria for querying messages.
+ * All fields are optional; messages must match all specified criteria.
+ */
+export interface MessageQuery {
+  /** Filter by external source (e.g., 'discord') */
+  source?: string;
+  /** Filter by participant name */
+  participant?: string;
+  /** Filter by metadata fields (shallow match) */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Result of a message query.
+ */
+export interface MessageQueryResult {
+  messages: StoredMessage[];
+  totalCount: number;
+}
+
+/**
+ * A pluggable module that provides capabilities to the framework.
+ */
+export interface Module {
+  /** Unique name, used for tool namespacing and state storage */
+  readonly name: string;
+
+  /**
+   * Start the module.
+   * Called when the framework starts or when the module is added.
+   */
+  start(ctx: ModuleContext): Promise<void>;
+
+  /**
+   * Stop the module.
+   * Called when the framework stops or when the module is removed.
+   */
+  stop(): Promise<void>;
+
+  /**
+   * Get currently available tools.
+   * Can change over time (e.g., based on connection state).
+   */
+  getTools(): ToolDefinition[];
+
+  /**
+   * Handle a tool call.
+   * Tool name is without module prefix.
+   */
+  handleToolCall(call: ToolCall): Promise<ToolResult>;
+
+  /**
+   * Handle a process event from the queue.
+   * Return response indicating what actions to take.
+   *
+   * @param event - The event to process
+   * @param state - Read-only state snapshot for accessing module state and lookups
+   */
+  onProcess(event: ProcessEvent, state: ProcessState): Promise<EventResponse>;
+
+  /**
+   * Handle agent speech (if registered as speech handler).
+   * Called when an agent produces text output.
+   */
+  onAgentSpeech?(
+    agentName: string,
+    content: ContentBlock[],
+    context: SpeechContext
+  ): Promise<void>;
+
+  /**
+   * Gather context injections before agent inference.
+   * Called before each inference to collect data (e.g., HUD overlays, game state)
+   * that should be injected into the compiled context.
+   * Complementary to MCPL push-based hooks — modules pull via gatherContext.
+   * Adapted from Anarchid/agent-framework@mcpl-module-proto.
+   */
+  gatherContext?(agentName: string): Promise<ContextInjection[]>;
+}
+
+/**
+ * Context provided to modules for interacting with the framework.
+ */
+export interface ModuleContext {
+  /**
+   * Get persistent state for this module.
+   * State is namespaced to the module.
+   */
+  getState<T>(): T | null;
+
+  /**
+   * Set persistent state for this module.
+   */
+  setState<T>(state: T): void;
+
+  /**
+   * Process queue for pushing events from external listeners.
+   * @deprecated Use pushEvent() instead — it also emits process:received traces.
+   */
+  readonly queue: ProcessQueue;
+
+  /**
+   * Push a process event to the queue and emit a process:received trace.
+   * Preferred over direct queue.push() for proper observability.
+   */
+  pushEvent(event: ProcessEvent): void;
+
+  /**
+   * Get another module by name.
+   */
+  getModule<T extends Module>(name: string): T | null;
+
+  /**
+   * Add a message to the conversation.
+   */
+  addMessage(
+    participant: string,
+    content: ContentBlock[],
+    metadata?: MessageMetadata & { external?: ExternalIdRef }
+  ): MessageId;
+
+  /**
+   * Edit a message.
+   */
+  editMessage(id: MessageId, content: ContentBlock[]): void;
+
+  /**
+   * Remove a message.
+   */
+  removeMessage(id: MessageId): void;
+
+  /**
+   * Find a message by external ID.
+   */
+  findMessageByExternalId(source: string, externalId: string): MessageId | null;
+
+  /**
+   * Get a message by ID.
+   */
+  getMessage(id: MessageId): StoredMessage | null;
+
+  /**
+   * Query messages by filter criteria.
+   * Useful for finding messages from external sources, by participant, etc.
+   */
+  queryMessages(filter: MessageQuery): MessageQueryResult;
+
+  /**
+   * Get info about all agents.
+   */
+  getAgents(): AgentInfo[];
+
+  /**
+   * Get all currently available tools.
+   */
+  getActiveTools(): ToolDefinition[];
+
+  /**
+   * Whether this is a restart (state existed) vs fresh start.
+   */
+  readonly isRestart: boolean;
+
+  /**
+   * Register this module as a speech handler for agents.
+   * @param agents - '*' for all agents, or array of agent names
+   * @param options - Speech handler options
+   */
+  registerSpeechHandler(
+    agents: '*' | string[],
+    options?: SpeechHandlerOptions
+  ): void;
+
+  /**
+   * Unregister this module as a speech handler.
+   */
+  unregisterSpeechHandler(): void;
+}
+
+/**
+ * Read-only state snapshot provided to modules during event processing.
+ * State writes happen via EventResponse, not through this interface.
+ */
+export interface ProcessState {
+  /**
+   * Get this module's state.
+   */
+  getState<T>(): T | null;
+
+  /**
+   * Get another module's state by name.
+   */
+  getModuleState<T>(name: string): T | null;
+
+  /**
+   * Find a message by external ID.
+   */
+  findMessageByExternalId(source: string, externalId: string): MessageId | null;
+
+  /**
+   * Get info about all agents.
+   */
+  getAgents(): AgentInfo[];
+
+  /**
+   * Get all currently available tools.
+   */
+  getActiveTools(): ToolDefinition[];
+
+  /**
+   * Queue for emitting follow-up events.
+   * @deprecated Use pushEvent() instead — it also emits process:received traces.
+   */
+  readonly queue: ProcessQueue;
+
+  /**
+   * Push a process event to the queue and emit a process:received trace.
+   * Preferred over direct queue.push() for proper observability.
+   */
+  pushEvent(event: ProcessEvent): void;
+}
+
+/**
+ * Reference to an external system's ID.
+ */
+export interface ExternalIdRef {
+  source: string;
+  id: string;
+}
+
+/**
+ * Process queue interface for modules.
+ */
+export interface ProcessQueue {
+  /**
+   * Push a process event to the queue.
+   */
+  push(event: ProcessEvent): void;
+}
+
+/**
+ * Basic info about an agent.
+ */
+export interface AgentInfo {
+  name: string;
+  model: string;
+  status: AgentStatus;
+}
+
+/**
+ * Agent execution status.
+ */
+export type AgentStatus = 'idle' | 'inferring' | 'streaming' | 'waiting_for_tools' | 'ready';
+
+/**
+ * Response from a module's event handler.
+ */
+export interface EventResponse {
+  /**
+   * Messages to add to the conversation.
+   */
+  addMessages?: NewMessage[];
+
+  /**
+   * Messages to edit.
+   */
+  editMessages?: MessageEdit[];
+
+  /**
+   * Messages to remove.
+   */
+  removeMessages?: MessageId[];
+
+  /**
+   * Request inference.
+   * - true: request for all agents
+   * - string[]: request for specific agents
+   * - false/undefined: no request
+   */
+  requestInference?: boolean | string[];
+
+  /**
+   * Signal that this module's tools have changed.
+   */
+  toolsChanged?: boolean;
+
+  /**
+   * Module state update. Applied atomically with message operations.
+   * The framework will call setState() with this value after applying
+   * message changes, ensuring consistent state.
+   */
+  stateUpdate?: unknown;
+}
+
+/**
+ * A new message to add.
+ */
+export interface NewMessage {
+  participant: string;
+  content: ContentBlock[];
+  metadata?: MessageMetadata & { external?: ExternalIdRef };
+}
+
+/**
+ * An edit to an existing message.
+ */
+export interface MessageEdit {
+  messageId: MessageId;
+  content: ContentBlock[];
+}
+
+// ============================================================================
+// Speech Handler Types
+// ============================================================================
+
+/**
+ * Context provided to speech handlers.
+ */
+export interface SpeechContext {
+  /**
+   * Whether this is a complete turn or tool calls are pending.
+   * If false, more output may follow after tool results.
+   */
+  turnComplete: boolean;
+
+  /**
+   * The inference request that triggered this speech.
+   */
+  trigger: {
+    reason: string;
+    source: string;
+    timestamp: number;
+  };
+
+  /**
+   * Pre-tool preamble text blocks that preceded tool calls.
+   * Modules can display these as "thoughts" (e.g. Discord spoiler tags).
+   * Empty when no tool calls were made.
+   */
+  thoughts?: ContentBlock[];
+}
+
+/**
+ * Options for speech handler registration.
+ */
+export interface SpeechHandlerOptions {
+  /**
+   * If true, add to existing handlers rather than replacing.
+   * Multiple handlers will all receive speech.
+   */
+  additive?: boolean;
+
+  /**
+   * Priority for handler ordering (higher = called first).
+   * Default: 0
+   */
+  priority?: number;
+}

package/src/types/trace.ts

@@ -0,0 +1,196 @@
+import type { ProcessEvent } from './events.js';
+import type { ModuleProcessResponse } from './framework.js';
+
+/**
+ * Base for all trace events.
+ * TraceEvents are observability-only — they NEVER drive logic.
+ */
+export interface TraceEventBase {
+  /** When this trace was emitted */
+  timestamp: number;
+  /** Optional correlation ID for distributed tracing */
+  traceId?: string;
+}
+
+/**
+ * Observability events emitted by the framework.
+ * Subscribe via framework.onTrace() to monitor system behavior.
+ *
+ * These are purely informational — use them for:
+ * - UI updates (showing inference progress, tool execution)
+ * - Logging and debugging
+ * - Metrics and monitoring
+ * - Broadcasting to WebSocket clients
+ *
+ * They should NEVER be used to drive application logic.
+ * For that, use ProcessEvent via the event queue.
+ */
+export type TraceEvent =
+  // Process lifecycle
+  | (TraceEventBase & { type: 'process:received'; processEvent: ProcessEvent })
+  | (TraceEventBase & {
+      type: 'process:completed';
+      processEvent: ProcessEvent;
+      responses: ModuleProcessResponse[];
+      durationMs: number;
+    })
+
+  // Inference lifecycle
+  | (TraceEventBase & { type: 'inference:started'; agentName: string })
+  | (TraceEventBase & {
+      type: 'inference:completed';
+      agentName: string;
+      durationMs: number;
+      tokenUsage?: { input: number; output: number; cacheCreation?: number; cacheRead?: number };
+    })
+  | (TraceEventBase & {
+      type: 'inference:aborted';
+      agentName: string;
+      durationMs: number;
+      reason?: string;
+    })
+  | (TraceEventBase & {
+      type: 'inference:failed';
+      agentName: string;
+      error: string;
+      stack?: string;
+    })
+  | (TraceEventBase & {
+      type: 'inference:exhausted';
+      agentName: string;
+      error: string;
+    })
+
+  // Streaming inference lifecycle
+  | (TraceEventBase & {
+      type: 'inference:tokens';
+      agentName: string;
+      content: string;
+    })
+  | (TraceEventBase & {
+      type: 'inference:tool_calls_yielded';
+      agentName: string;
+      calls: Array<{ id: string; name: string; input?: unknown }>;
+    })
+  | (TraceEventBase & {
+      type: 'inference:usage';
+      agentName: string;
+      tokenUsage: { input: number; output: number };
+    })
+  | (TraceEventBase & {
+      type: 'inference:stream_resumed';
+      agentName: string;
+    })
+  | (TraceEventBase & {
+      type: 'inference:stream_restarted';
+      agentName: string;
+      reason: string;
+      inputTokens: number;
+      budget: number;
+    })
+  | (TraceEventBase & {
+      type: 'inference:turn_ended';
+      agentName: string;
+    })
+
+  // Tool lifecycle
+  | (TraceEventBase & {
+      type: 'tool:started';
+      module: string;
+      tool: string;
+      callId: string;
+      input?: unknown;
+    })
+  | (TraceEventBase & {
+      type: 'tool:completed';
+      module: string;
+      tool: string;
+      callId: string;
+      durationMs: number;
+    })
+  | (TraceEventBase & {
+      type: 'tool:failed';
+      module: string;
+      tool: string;
+      callId: string;
+      error: string;
+      stack?: string;
+    })
+  | (TraceEventBase & {
+      type: 'tool:result_dropped';
+      agentName: string;
+      callId: string;
+      agentStatus: string;
+      result: unknown;
+    })
+
+  // Module lifecycle
+  | (TraceEventBase & { type: 'module:added'; moduleName: string })
+  | (TraceEventBase & { type: 'module:removed'; moduleName: string })
+
+  // Inference request health
+  | (TraceEventBase & {
+      type: 'inference:request_dropped';
+      agentName: string;
+      reason: string;
+      requestCount: number;
+      oldestRequestAge: number;
+    })
+  | (TraceEventBase & {
+      type: 'inference:request_stale';
+      agentName: string;
+      agentStatus: string;
+      requestCount: number;
+      oldestRequestAge: number;
+    })
+
+  // Message lifecycle
+  | (TraceEventBase & {
+      type: 'message:added';
+      messageId: string;
+      source: string;
+    })
+
+  // EventGate lifecycle
+  | (TraceEventBase & {
+      type: 'gate:policy-matched';
+      policyName: string;
+      behavior: string;
+      eventType: string;
+      source?: string;
+    })
+  | (TraceEventBase & {
+      type: 'gate:config-error';
+      error: string;
+      configPath: string;
+    })
+  | (TraceEventBase & {
+      type: 'gate:debounce-delivered';
+      policyName: string;
+      eventCount: number;
+    })
+  | (TraceEventBase & {
+      type: 'gate:config-reloaded';
+      configPath: string;
+      policyCount: number;
+    })
+
+  // Undo/redo lifecycle
+  | (TraceEventBase & {
+      type: 'undo:completed';
+      agentName: string;
+      turnIndex: number;
+      fromBranch: string;
+      toBranch: string;
+    })
+  | (TraceEventBase & {
+      type: 'redo:completed';
+      agentName: string;
+      fromBranch: string;
+      toBranch: string;
+    });
+
+/**
+ * Listener for trace events.
+ */
+export type TraceEventListener = (event: TraceEvent) => void;