@animalabs/agent-framework 0.1.0

package/src/queue.ts

@@ -0,0 +1,106 @@
+import type { ProcessEvent, ProcessQueue } from './types/index.js';
+
+/**
+ * Process queue for the framework.
+ * ProcessEvents from external sources and internal operations flow through here.
+ */
+export class ProcessQueueImpl implements ProcessQueue {
+  private queue: ProcessEvent[] = [];
+  private waiters: Array<(event: ProcessEvent) => void> = [];
+  private closed = false;
+
+  /**
+   * Push a process event to the queue.
+   */
+  push(event: ProcessEvent): void {
+    if (this.closed) {
+      throw new Error('Queue is closed');
+    }
+
+    // If someone is waiting, deliver immediately
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter(event);
+    } else if (event.type === 'external-message') {
+      // User input jumps to front so it's processed before queued internal events
+      this.queue.unshift(event);
+    } else {
+      this.queue.push(event);
+    }
+  }
+
+  /**
+   * Pop the next process event from the queue.
+   * Returns immediately if an event is available, otherwise waits.
+   */
+  async pop(): Promise<ProcessEvent> {
+    if (this.closed) {
+      throw new Error('Queue is closed');
+    }
+
+    // If there's an event waiting, return it
+    const event = this.queue.shift();
+    if (event) {
+      return event;
+    }
+
+    // Otherwise, wait for one
+    return new Promise((resolve) => {
+      this.waiters.push(resolve);
+    });
+  }
+
+  /**
+   * Try to pop a process event without waiting.
+   * Returns null if queue is empty.
+   */
+  tryPop(): ProcessEvent | null {
+    return this.queue.shift() ?? null;
+  }
+
+  /**
+   * Peek at the next process event without removing it.
+   */
+  peek(): ProcessEvent | null {
+    return this.queue[0] ?? null;
+  }
+
+  /**
+   * Get current queue depth.
+   */
+  get depth(): number {
+    return this.queue.length;
+  }
+
+  /**
+   * Check if queue is empty.
+   */
+  get isEmpty(): boolean {
+    return this.queue.length === 0;
+  }
+
+  /**
+   * Clear all events from the queue.
+   */
+  clear(): void {
+    this.queue = [];
+  }
+
+  /**
+   * Close the queue.
+   * Rejects any pending waiters.
+   */
+  close(): void {
+    this.closed = true;
+    // Reject pending waiters by not resolving them
+    // In a real implementation, we might want to reject with an error
+    this.waiters = [];
+  }
+
+  /**
+   * Check if queue is closed.
+   */
+  get isClosed(): boolean {
+    return this.closed;
+  }
+}

package/src/safe-slice.ts

@@ -0,0 +1,18 @@
+/**
+ * Slice a string without splitting surrogate pairs.
+ *
+ * Regular String.prototype.slice can cut in the middle of a surrogate pair,
+ * producing invalid UTF-16. This function adjusts the end index to avoid that.
+ */
+export function safeSlice(str: string, start: number, end: number): string {
+  if (end >= str.length) return str.slice(start);
+
+  // If we're about to cut between a high and low surrogate, back up one char
+  const code = str.charCodeAt(end - 1);
+  if (code >= 0xd800 && code <= 0xdbff) {
+    // end-1 is a high surrogate — don't split the pair
+    return str.slice(start, end - 1);
+  }
+
+  return str.slice(start, end);
+}

package/src/types/agent.ts

@@ -0,0 +1,119 @@
+import type { ContentBlock, YieldingStream } from '@animalabs/membrane';
+import type { ContextStrategy } from '@animalabs/context-manager';
+import type { ToolCallId, ToolResult, ToolCall } from './events.js';
+
+/**
+ * Configuration for an agent.
+ */
+export interface AgentConfig {
+  /** Unique name for this agent */
+  name: string;
+
+  /** Model to use (e.g., 'claude-sonnet-4-20250514') */
+  model: string;
+
+  /** System prompt */
+  systemPrompt: string;
+
+  /** Context management strategy */
+  strategy?: ContextStrategy;
+
+  /**
+   * Which tools this agent can use.
+   * - 'all': all available tools
+   * - string[]: specific tool names (with module prefix)
+   */
+  allowedTools?: 'all' | string[];
+
+  /**
+   * Which modules can trigger inference for this agent.
+   * - 'all': any module
+   * - string[]: specific module names
+   */
+  triggerSources?: 'all' | string[];
+
+  /** Maximum tokens for response */
+  maxTokens?: number;
+
+  /** Temperature for inference */
+  temperature?: number;
+
+  /** Max input tokens before framework breaks a yielding stream and
+   *  restarts with recompiled (compressed) context. Default: 150000. */
+  maxStreamTokens?: number;
+}
+
+/**
+ * Result of running inference.
+ */
+export interface InferenceResult {
+  /** Tool calls to execute */
+  toolCalls: ToolCall[];
+  /** Speech content (text blocks) to send to handlers */
+  speechContent: ContentBlock[];
+  /** Raw request/response for logging */
+  raw?: {
+    request: unknown;
+    response: unknown;
+  };
+  /** Usage stats */
+  usage?: {
+    inputTokens: number;
+    outputTokens: number;
+  };
+  /** Stop reason */
+  stopReason?: string;
+  /** Whether inference was aborted */
+  aborted?: boolean;
+  /** Reason for abort, if available */
+  abortReason?: string;
+}
+
+/**
+ * Options for running inference.
+ */
+export interface InferenceOptions {
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+}
+
+/**
+ * Internal state of an agent.
+ */
+export type AgentState =
+  | { status: 'idle' }
+  | { status: 'inferring'; promise: Promise<InferenceResult>; abortController: AbortController }
+  | { status: 'streaming'; stream: YieldingStream }
+  | { status: 'waiting_for_tools'; pending: Map<ToolCallId, PendingToolCall>; completed: CompletedToolCall[]; stream?: YieldingStream }
+  | { status: 'ready'; toolResults: CompletedToolCall[]; stream?: YieldingStream };
+
+/**
+ * A tool call that's in progress.
+ */
+export interface PendingToolCall {
+  id: ToolCallId;
+  name: string;
+  input: unknown;
+  startedAt: number;
+}
+
+/**
+ * A tool call that has completed.
+ */
+export interface CompletedToolCall {
+  id: ToolCallId;
+  name: string;
+  input: unknown;
+  result: ToolResult;
+  durationMs: number;
+}
+
+/**
+ * Inference request for an agent.
+ */
+export interface InferenceRequest {
+  agentName: string;
+  reason: string;
+  source: string;
+  timestamp: number;
+}

package/src/types/events.ts

@@ -0,0 +1,252 @@
+import type { ContentBlock, ToolDefinition as MembraneToolDefinition } from '@animalabs/membrane';
+import type { MessageId } from '@animalabs/context-manager';
+
+/**
+ * Unique identifier for a tool call.
+ */
+export type ToolCallId = string;
+
+/**
+ * Re-export membrane's ToolDefinition for modules to use.
+ */
+export type ToolDefinition = MembraneToolDefinition;
+
+/**
+ * Events that flow through the framework's processing queue.
+ *
+ * ProcessEvents represent work to be done — modules respond to them via onProcess().
+ * They are distinct from TraceEvents, which are observability-only notifications.
+ *
+ * Modules can define their own namespaced events (e.g., 'api:message', 'discord:reaction').
+ */
+export type ProcessEvent =
+  | ExternalMessageEvent
+  | ToolCallEvent
+  | ToolResultEvent
+  | TimerFiredEvent
+  | InferenceRequestEvent
+  | MessageEditedEvent
+  | MessageRemovedEvent
+  | ModuleEvent
+  | ApiMessageEvent
+  | ApiInferenceRequestEvent
+  | McplPushEvent
+  | McplChannelIncomingEvent
+  | CustomEvent;
+
+/**
+ * API message event - from the API server.
+ */
+export interface ApiMessageEvent {
+  type: 'api:message';
+  participant: string;
+  content: string;
+  metadata?: Record<string, unknown>;
+  triggerInference?: boolean;
+  targetAgents?: string[];
+}
+
+/**
+ * API inference request - from the API server.
+ */
+export interface ApiInferenceRequestEvent {
+  type: 'api:inference-request';
+  agentName?: string;
+  reason?: string;
+}
+
+/**
+ * Generic custom event for module-specific namespaced events.
+ * Use this for events like 'discord:message', 'slack:reaction', etc.
+ */
+export interface CustomEvent {
+  type: `${string}:${string}`;
+  [key: string]: unknown;
+}
+
+/**
+ * Message from an external source (Discord, HTTP, CLI, etc.)
+ */
+export interface ExternalMessageEvent {
+  type: 'external-message';
+  /** Module that produced this event */
+  source: string;
+  /** Raw content from external system */
+  content: unknown;
+  /** External system metadata */
+  metadata: Record<string, unknown>;
+  /** Whether this should trigger inference */
+  triggerInference?: boolean;
+  /** Specific agents to trigger (if not all) */
+  targetAgents?: string[];
+}
+
+/**
+ * Result of a tool call.
+ */
+export interface ToolResultEvent {
+  type: 'tool-result';
+  /** ID of the original tool call */
+  callId: ToolCallId;
+  /** Agent that made the call */
+  agentName: string;
+  /** Module that handled the call */
+  moduleName: string;
+  /** Result of the tool call */
+  result: ToolResult;
+}
+
+/**
+ * Tool call scheduled for execution.
+ */
+export interface ToolCallEvent {
+  type: 'tool-call';
+  /** ID of the tool call */
+  callId: ToolCallId;
+  /** Agent that made the call */
+  agentName: string;
+  /** Module that will handle the call */
+  moduleName: string;
+  /** Un-prefixed tool name */
+  toolName: string;
+  /** Full tool call payload */
+  call: ToolCall;
+}
+
+/**
+ * Scheduled timer fired.
+ */
+export interface TimerFiredEvent {
+  type: 'timer-fired';
+  /** Timer identifier */
+  timerId: string;
+  /** Reason for the timer */
+  reason: string;
+  /** Specific agent to wake (if any) */
+  agentName?: string;
+}
+
+/**
+ * Explicit request to run inference.
+ */
+export interface InferenceRequestEvent {
+  type: 'inference-request';
+  /** Agent to run inference for */
+  agentName: string;
+  /** Reason for the request */
+  reason: string;
+  /** Module that requested it */
+  source: string;
+}
+
+/**
+ * External message was edited.
+ */
+export interface MessageEditedEvent {
+  type: 'message-edited';
+  /** Module that produced this event */
+  source: string;
+  /** Our internal message ID */
+  messageId: MessageId;
+  /** New content */
+  newContent: ContentBlock[];
+}
+
+/**
+ * External message was removed.
+ */
+export interface MessageRemovedEvent {
+  type: 'message-removed';
+  /** Module that produced this event */
+  source: string;
+  /** Our internal message ID */
+  messageId: MessageId;
+}
+
+/**
+ * Generic module-specific event.
+ */
+export interface ModuleEvent {
+  type: 'module-event';
+  /** Module that produced this event */
+  source: string;
+  /** Module-specific event type */
+  eventType: string;
+  /** Module-specific payload */
+  payload: unknown;
+}
+
+/**
+ * Result of a tool execution.
+ */
+export interface ToolResult {
+  /** Whether the tool succeeded */
+  success: boolean;
+  /** Result data (if success) */
+  data?: unknown;
+  /** Error message (if failure) */
+  error?: string;
+  /** Whether this was an error (for LLM) */
+  isError?: boolean;
+  /**
+   * When true, the framework saves tool_use + tool_result messages to context,
+   * cancels the active stream, and resets the agent to idle.
+   * This is a "sleep until next event" primitive — the LLM expects the call to block.
+   * Adapted from Anarchid/agent-framework@mcpl-module-proto.
+   */
+  endTurn?: boolean;
+}
+
+/**
+ * A tool call from the LLM.
+ */
+export interface ToolCall {
+  /** Unique ID for this call */
+  id: ToolCallId;
+  /** Full tool name (module:tool) */
+  name: string;
+  /** Tool input */
+  input: unknown;
+  /** The agent that made this tool call. Set by the framework dispatch layer. */
+  callerAgentName?: string;
+}
+
+// ============================================================================
+// MCPL Events (Steps 6-7)
+// ============================================================================
+
+/**
+ * Push event from an MCPL server (Section 9).
+ * Converted from wire-format McplContentBlock to membrane ContentBlock.
+ */
+export interface McplPushEvent {
+  type: 'mcpl:push-event';
+  serverId: string;
+  featureSet: string;
+  eventId: string;
+  content: ContentBlock[];
+  origin?: Record<string, unknown>;
+  timestamp: string;
+  inferenceId: string;
+  triggerInference?: boolean;
+  targetAgents?: string[];
+}
+
+/**
+ * Incoming channel message from an MCPL server (Section 14).
+ * Converted from wire-format McplContentBlock to membrane ContentBlock.
+ */
+export interface McplChannelIncomingEvent {
+  type: 'mcpl:channel-incoming';
+  serverId: string;
+  channelId: string;
+  messageId: string;
+  threadId?: string;
+  author: { id: string; name: string };
+  content: ContentBlock[];
+  timestamp: string;
+  metadata?: Record<string, unknown>;
+  triggerInference?: boolean;
+  targetAgents?: string[];
+}
+

package/src/types/framework.ts

@@ -0,0 +1,211 @@
+import type { JsStore } from '@animalabs/chronicle';
+import type { Membrane } from '@animalabs/membrane';
+import type { Module, EventResponse } from './module.js';
+import type { AgentConfig, InferenceRequest } from './agent.js';
+import type { ProcessEvent } from './events.js';
+import type { McplServerConfig, InferenceRoutingPolicy } from '../mcpl/types.js';
+import type { GateOptions } from '../gate/types.js';
+
+// Re-export trace types
+export type { TraceEvent, TraceEventListener } from './trace.js';
+
+/**
+ * A module's response to a process event, tagged with the module name.
+ */
+export interface ModuleProcessResponse {
+  moduleName: string;
+  response: EventResponse;
+}
+
+/**
+ * Configuration for process event logging.
+ */
+export interface ProcessLoggingConfig {
+  /** Persist process logs to Chronicle (default: false) */
+  persist?: boolean;
+  /** Broadcast process:completed trace events (default: false) */
+  broadcast?: boolean;
+}
+
+/**
+ * Configuration for the agent framework.
+ */
+export interface FrameworkConfig {
+  /** Path to Chronicle store */
+  storePath?: string;
+
+  /** Or existing store (app-owned) */
+  store?: JsStore;
+
+  /** Membrane instance for LLM calls */
+  membrane: Membrane;
+
+  /** Agent configurations */
+  agents: AgentConfig[];
+
+  /** Modules to load */
+  modules: Module[];
+
+  /** Custom inference policy */
+  inferencePolicy?: InferencePolicy;
+
+  /** Custom error policy */
+  errorPolicy?: ErrorPolicy;
+
+  /** Interval for periodic store sync in milliseconds (default: 1000ms, 0 to disable) */
+  syncIntervalMs?: number;
+
+  /** Process logging configuration (default: disabled) */
+  processLogging?: ProcessLoggingConfig;
+
+  /** MCPL server configurations. If omitted or empty, no MCPL subsystems are created. */
+  mcplServers?: McplServerConfig[];
+
+  /** Inference routing policy for server-initiated inference (optional). */
+  inferenceRouting?: InferenceRoutingPolicy;
+
+  /** EventGate config. If omitted, all events trigger inference (unchanged default). */
+  gate?: GateOptions;
+}
+
+/**
+ * Policy for deciding when to run inference.
+ */
+export interface InferencePolicy {
+  /**
+   * Decide whether to run inference for an agent.
+   */
+  shouldInfer(
+    agentName: string,
+    requests: InferenceRequest[],
+    state: FrameworkState
+  ): boolean;
+}
+
+/**
+ * Policy for handling errors.
+ */
+export interface ErrorPolicy {
+  /**
+   * Handle an inference error.
+   */
+  onInferenceError(
+    error: Error,
+    agentName: string,
+    attempt: number
+  ): ErrorAction;
+
+  /** Maximum retry attempts */
+  maxRetries: number;
+}
+
+/**
+ * Action to take after an error.
+ */
+export type ErrorAction =
+  | { retry: true; delayMs: number }
+  | { retry: false; emit?: ProcessEvent };
+
+/**
+ * Framework state exposed to policies.
+ */
+export interface FrameworkState {
+  /** Get agent status */
+  getAgentStatus(name: string): import('./agent.js').AgentState | null;
+
+  /** Get module by name */
+  getModule(name: string): Module | null;
+
+  /** Get all pending inference requests */
+  getPendingRequests(): InferenceRequest[];
+
+  /** Current queue depth */
+  queueDepth: number;
+}
+
+/**
+ * Entry in the inference log.
+ */
+export interface InferenceLogEntry {
+  timestamp: number;
+  agentName: string;
+  requestId: string;
+  /** Whether inference succeeded */
+  success: boolean;
+  /** Error message if failed */
+  error?: string;
+  /** Request data or blob ID if large */
+  request: unknown | { blobId: string };
+  /** Response data or blob ID if large (only if successful) */
+  response?: unknown | { blobId: string };
+  durationMs: number;
+  tokenUsage?: {
+    input: number;
+    output: number;
+    cacheCreation?: number;
+    cacheRead?: number;
+  };
+  /** Stop reason from the model */
+  stopReason?: string;
+}
+
+/**
+ * Entry in the process log - records a processed event with all module responses.
+ */
+export interface ProcessLogEntry {
+  timestamp: number;
+  /** The process event that was handled */
+  processEvent: ProcessEvent;
+  /** Responses from all modules, or blob ID if large */
+  responses: ModuleProcessResponse[] | { blobId: string };
+}
+
+/**
+ * Query options for process logs.
+ */
+export interface ProcessLogQuery {
+  /** Filter by process event type */
+  eventType?: string;
+  /** Filter by module name (modules that responded) */
+  moduleName?: string;
+  /** Max number of logs to return */
+  limit?: number;
+  /** Skip first N logs (for pagination) */
+  offset?: number;
+  /** Search pattern for content (regex) */
+  pattern?: string;
+}
+
+/**
+ * Result from querying process logs.
+ */
+export interface ProcessLogQueryResult {
+  entries: ProcessLogEntryWithId[];
+  total: number;
+  hasMore: boolean;
+}
+
+/**
+ * Process log entry with Chronicle sequence ID.
+ */
+export interface ProcessLogEntryWithId {
+  sequence: number;
+  entry: ProcessLogEntry;
+  /** Summary for display without resolving blobs */
+  summary?: ProcessLogSummary;
+}
+
+/**
+ * Summary view of a process log (without full responses).
+ */
+export interface ProcessLogSummary {
+  timestamp: number;
+  eventType: string;
+  moduleCount: number;
+  /** Modules that requested inference */
+  modulesRequestingInference: string[];
+  /** Modules that added messages */
+  modulesAddingMessages: string[];
+  /** Whether responses are stored as blob */
+  responsesIsBlob: boolean;
+}

package/src/types/index.ts

@@ -0,0 +1,6 @@
+export * from './events.js';
+export * from './module.js';
+export * from './agent.js';
+export * from './framework.js';
+export * from './trace.js';
+export * from './inference-log.js';