@animalabs/agent-framework 0.1.0

package/dist/src/framework.d.ts

@@ -0,0 +1,309 @@
+import { JsStore } from '@animalabs/chronicle';
+import type { Membrane } from '@animalabs/membrane';
+import { ContextManager } from '@animalabs/context-manager';
+import type { FrameworkConfig, TraceEventListener, InferenceLogQuery, InferenceLogQueryResult, InferenceLogEntryWithId, ProcessLogQuery, ProcessLogQueryResult, ProcessLogEntryWithId, ProcessEvent, ToolCall, ToolResult, AgentConfig, Module } from './types/index.js';
+import { Agent } from './agent.js';
+/**
+ * The main agent framework.
+ */
+export declare class AgentFramework {
+    private store;
+    private ownsStore;
+    private membrane;
+    private queue;
+    private agents;
+    private moduleRegistry;
+    private inferencePolicy;
+    private errorPolicy;
+    private pendingRequests;
+    private running;
+    private loopPromise;
+    private traceListeners;
+    private syncIntervalMs;
+    private syncTimer;
+    private processLoggingPersist;
+    private processLoggingBroadcast;
+    private activeStreams;
+    private pendingAssistantBlocks;
+    /** Name of the primary (non-ephemeral) agent for routing framework messages. */
+    private primaryAgentName;
+    private deferredMessages;
+    private turnCounters;
+    private redoStacks;
+    private mcplServerRegistry;
+    private featureSetManager;
+    private scopeManager;
+    private hookOrchestrator;
+    private pushHandler;
+    private inferenceRouter;
+    private channelRegistry;
+    private checkpointManager;
+    private mcplTools;
+    private mcplToolRefreshInFlight;
+    private mcplToolRefreshPending;
+    /** Maps tool prefix → serverId for dispatch routing. */
+    private mcplPrefixMap;
+    /** Maps serverId → McplServerConfig for prefix lookup. */
+    private mcplServerConfigs;
+    private eventGate;
+    private constructor();
+    /**
+     * Create and start the framework.
+     */
+    static create(config: FrameworkConfig): Promise<AgentFramework>;
+    /**
+     * Start the event loop.
+     */
+    start(): void;
+    /**
+     * Stop the event loop.
+     */
+    stop(): Promise<void>;
+    /**
+     * Push a process event to the queue.
+     */
+    pushEvent(event: ProcessEvent): void;
+    /**
+     * Add a trace event listener for observability.
+     */
+    onTrace(listener: TraceEventListener): void;
+    /**
+     * Remove a trace event listener.
+     */
+    offTrace(listener: TraceEventListener): void;
+    /**
+     * Add a module at runtime.
+     */
+    addModule(module: Module): Promise<void>;
+    /**
+     * Remove a module at runtime.
+     */
+    removeModule(name: string): Promise<void>;
+    /**
+     * Get an agent by name.
+     */
+    getAgent(name: string): Agent | null;
+    /**
+     * Get all agents.
+     */
+    getAllAgents(): Agent[];
+    /**
+     * Abort an in-flight inference for an agent.
+     */
+    abortInference(agentName: string, reason?: string): boolean;
+    /**
+     * Get all registered modules.
+     */
+    getAllModules(): Module[];
+    /**
+     * Get all available tools from all modules and MCPL servers.
+     */
+    getAllTools(): import('./types/index.js').ToolDefinition[];
+    /**
+     * Check if process logging is enabled.
+     */
+    isProcessLoggingEnabled(): {
+        persist: boolean;
+        broadcast: boolean;
+    };
+    /**
+     * Get the underlying store.
+     */
+    getStore(): JsStore;
+    /**
+     * Get a registered module by name.
+     */
+    getModule(name: string): Module | null;
+    /**
+     * Get the Membrane instance.
+     */
+    getMembrane(): Membrane;
+    /**
+     * Create an ephemeral agent that is NOT registered in the main event loop.
+     *
+     * Used by SubagentModule (and similar) to create short-lived agents
+     * that are driven externally (not by the framework's event loop).
+     * The returned agent has its own ContextManager on a namespaced state
+     * within the framework's shared Chronicle store — messages go to
+     * `{namespace}/messages`, context log to `{namespace}/context`.
+     *
+     * Data persists after cleanup for investigation and cross-revert.
+     * Call cleanup() when done to release the ContextManager.
+     */
+    createEphemeralAgent(config: AgentConfig): Promise<{
+        agent: Agent;
+        contextManager: ContextManager;
+        cleanup: () => void;
+    }>;
+    /**
+     * Run an ephemeral agent to completion through the framework's event loop.
+     *
+     * The agent is temporarily registered, inference is triggered, and the
+     * framework drives the stream (emitting traces, logging, dispatching tools).
+     * Returns the agent's speech output when it finishes (no more tool calls).
+     *
+     * The caller provides a pre-created agent + contextManager (from createEphemeralAgent).
+     * The task message should already be in the context manager.
+     */
+    runEphemeralToCompletion(agent: Agent, contextManager: ContextManager): Promise<{
+        speech: string;
+        toolCallsCount: number;
+    }>;
+    /**
+     * Get queue depth.
+     */
+    getQueueDepth(): number;
+    /**
+     * Query inference logs.
+     * Returns entries with summary info (doesn't resolve blobs).
+     */
+    queryInferenceLogs(query?: InferenceLogQuery): InferenceLogQueryResult;
+    /**
+     * Get a specific inference log entry by sequence number.
+     * Resolves blob references to full content.
+     */
+    getInferenceLog(sequence: number, resolveBlobs?: boolean): InferenceLogEntryWithId | null;
+    /**
+     * Get the most recent inference logs (tail).
+     */
+    tailInferenceLogs(count?: number, agentName?: string): InferenceLogEntryWithId[];
+    /**
+     * Query process logs.
+     * Returns entries with summary info (doesn't resolve blobs).
+     */
+    queryProcessLogs(query?: ProcessLogQuery): ProcessLogQueryResult;
+    /**
+     * Get a specific process log entry by sequence number.
+     * Resolves blob references to full content.
+     */
+    getProcessLog(sequence: number, resolveBlobs?: boolean): ProcessLogEntryWithId | null;
+    /**
+     * Get the most recent process logs (tail).
+     */
+    tailProcessLogs(count?: number, eventType?: string): ProcessLogEntryWithId[];
+    /**
+     * Undo the last inference turn for an agent.
+     *
+     * Creates a new branch at the Chronicle sequence recorded before that turn
+     * and switches to it, atomically rolling back all state (messages, context
+     * log, inference log, MCPL checkpoints).
+     *
+     * The undone branch is saved so `redo()` can restore it.
+     * Returns the checkpoint that was undone, or null if nothing to undo.
+     */
+    undoLastTurn(agentName: string): {
+        undone: boolean;
+        turnIndex?: number;
+        fromBranch?: string;
+        toBranch?: string;
+    };
+    /**
+     * Redo a previously undone turn for an agent.
+     *
+     * Switches back to the branch that was active before the last undo.
+     * Returns false if there's nothing to redo.
+     */
+    redo(agentName: string): {
+        redone: boolean;
+        fromBranch?: string;
+        toBranch?: string;
+    };
+    /**
+     * Check if undo/redo is available for an agent.
+     */
+    getUndoRedoState(agentName: string): {
+        canUndo: boolean;
+        canRedo: boolean;
+        undoDepth: number;
+        redoDepth: number;
+    };
+    private recordTurnCheckpoint;
+    private getTurnCheckpoints;
+    private saveTurnCheckpoints;
+    /**
+     * Run until the queue is empty and all agents are idle.
+     * Useful for testing.
+     */
+    runUntilIdle(): Promise<void>;
+    private createAgent;
+    private runLoop;
+    private processNextEvent;
+    private handleProcessEvent;
+    private applyProcessResponse;
+    /**
+     * Convert an incoming MCPL channel message to a context message.
+     * This replaces the old MCPLModule.onProcess() message conversion.
+     */
+    private handleMcplChannelIncoming;
+    /**
+     * Convert an MCPL push event to a context message.
+     */
+    private handleMcplPushEvent;
+    private processInferenceRequests;
+    private startAgentStream;
+    private driveStream;
+    /**
+     * Execute a tool call and return the result.
+     * Routes to the appropriate handler (module registry or MCPL).
+     * Used by SubagentModule to dispatch tool calls for ephemeral agents.
+     */
+    executeToolCall(call: ToolCall): Promise<ToolResult>;
+    private executeMcplToolCall;
+    private toMembraneToolResult;
+    private getMaxToolResultChars;
+    private logInference;
+    private logProcessEvent;
+    /**
+     * Find the MCPL server for a tool call by checking against the prefix map.
+     * Returns [serverId, prefix] if found, null otherwise.
+     */
+    private resolveMcplTool;
+    private dispatchToolCall;
+    private dispatchToolCallEvent;
+    private addMessage;
+    private editMessage;
+    private removeMessage;
+    private getMessage;
+    private queryMessages;
+    private createFrameworkState;
+    private emitTrace;
+    /**
+     * Initialize all MCPL subsystems and connect configured servers.
+     * Fail-open: individual server connection failures don't prevent framework startup.
+     */
+    private initializeMcpl;
+    /**
+     * Wire event listeners on an MCPL server connection.
+     * Push events and inference requests are deferred to Steps 6/7.
+     */
+    private wireMcplEvents;
+    /**
+     * Discover tools from all connected MCPL servers and cache them.
+     * Tools are namespaced as `{toolPrefix}--{toolName}` per server config.
+     */
+    private refreshMcplTools;
+    /**
+     * Handle a tools/list_changed notification with collapse logic.
+     * At most 2 refresh cycles can be in-flight: one running and one pending.
+     */
+    private handleToolsListChanged;
+    /**
+     * Emit a trace event and push an external-message listing newly added tools.
+     */
+    private emitMcplToolDiff;
+    /**
+     * Dispatch a tool call to an MCPL server.
+     * Strips the configured toolPrefix and routes to the server.
+     */
+    private dispatchMcplToolCall;
+    /**
+     * Build BeforeInferenceParams from agent state and trigger context.
+     */
+    /**
+     * Dispatch a synthesized channel tool call.
+     */
+    private dispatchChannelToolCall;
+    private dispatchGateToolCall;
+    private buildBeforeInferenceParams;
+}
+//# sourceMappingURL=framework.d.ts.map

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

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