@animalabs/agent-framework 0.1.0

package/dist/src/types/events.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=events.js.map

package/dist/src/types/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/types/events.ts"],"names":[],"mappings":""}

package/dist/src/types/framework.d.ts

@@ -0,0 +1,184 @@
+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';
+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;
+}
+//# sourceMappingURL=framework.d.ts.map

package/dist/src/types/framework.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework.d.ts","sourceRoot":"","sources":["../../../src/types/framework.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,oCAAoC;IACpC,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,sCAAsC;IACtC,QAAQ,EAAE,QAAQ,CAAC;IAEnB,2BAA2B;IAC3B,MAAM,EAAE,WAAW,EAAE,CAAC;IAEtB,sBAAsB;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB,8BAA8B;IAC9B,eAAe,CAAC,EAAE,eAAe,CAAC;IAElC,0BAA0B;IAC1B,WAAW,CAAC,EAAE,WAAW,CAAC;IAE1B,uFAAuF;IACvF,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,wDAAwD;IACxD,cAAc,CAAC,EAAE,oBAAoB,CAAC;IAEtC,uFAAuF;IACvF,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAEjC,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAE1C,sFAAsF;IACtF,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,WAAW,CACT,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,gBAAgB,EAAE,EAC5B,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,gBAAgB,CACd,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,WAAW,CAAC;IAEf,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,IAAI,CAAC,EAAE,YAAY,CAAA;CAAE,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,uBAAuB;IACvB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,YAAY,EAAE,UAAU,GAAG,IAAI,CAAC;IAErE,yBAAyB;IACzB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAEvC,yCAAyC;IACzC,kBAAkB,IAAI,gBAAgB,EAAE,CAAC;IAEzC,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,OAAO,EAAE,OAAO,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE;QACX,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,iCAAiC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,YAAY,EAAE,YAAY,CAAC;IAC3B,sDAAsD;IACtD,SAAS,EAAE,qBAAqB,EAAE,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACzD;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,eAAe,CAAC;IACvB,kDAAkD;IAClD,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,0BAA0B,EAAE,MAAM,EAAE,CAAC;IACrC,kCAAkC;IAClC,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,2CAA2C;IAC3C,eAAe,EAAE,OAAO,CAAC;CAC1B"}

package/dist/src/types/framework.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=framework.js.map

package/dist/src/types/framework.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework.js","sourceRoot":"","sources":["../../../src/types/framework.ts"],"names":[],"mappings":""}

package/dist/src/types/index.d.ts

@@ -0,0 +1,7 @@
+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';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC"}

package/dist/src/types/index.js

@@ -0,0 +1,7 @@
+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';
+//# sourceMappingURL=index.js.map

package/dist/src/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC"}

package/dist/src/types/inference-log.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Types for inference logging - captures raw LLM requests and responses
+ */
+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;
+}
+//# sourceMappingURL=inference-log.d.ts.map

package/dist/src/types/inference-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inference-log.d.ts","sourceRoot":"","sources":["../../../src/types/inference-log.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2BAA2B;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,uBAAuB;IACvB,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,KAAK,EAAE,OAAO,gBAAgB,EAAE,iBAAiB,CAAC;IAClD,uDAAuD;IACvD,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,aAAa,EAAE,OAAO,CAAC;IACvB,yCAAyC;IACzC,cAAc,EAAE,OAAO,CAAC;CACzB"}

package/dist/src/types/inference-log.js

@@ -0,0 +1,5 @@
+/**
+ * Types for inference logging - captures raw LLM requests and responses
+ */
+export {};
+//# sourceMappingURL=inference-log.js.map

package/dist/src/types/inference-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inference-log.js","sourceRoot":"","sources":["../../../src/types/inference-log.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/src/types/module.d.ts

@@ -0,0 +1,302 @@
+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[];
+}
+/**
+ * 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;
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/src/types/module.d.ts.map

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

package/dist/src/types/module.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=module.js.map

package/dist/src/types/module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../../../src/types/module.ts"],"names":[],"mappings":""}