lemura 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -1,19 +1,51 @@
-import { C as ContextWindow, T as Turn, a as ContentBlock } from './adapters-BSkhv5ac.js';
-export { A as AudioChunk, b as CompletionChunk, c as CompletionRequest, d as CompletionResponse, I as IContextStrategy, e as IProviderAdapter, f as ImageGenRequest, g as ImageGenResponse, M as ModelInfo, N as NormalizedMessage, S as SynthesisRequest, h as TokenUsage, i as ToolCall, j as ToolResult, k as TranscriptionRequest, l as TranscriptionResponse, V as VisionRequest, m as VisionResponse } from './adapters-BSkhv5ac.js';
-import { SessionConfig, IToolResponseProcessor, ToolResponseEvaluation } from './types/index.js';
-export { LemuraAdapterError, LemuraContextOverflowError, LemuraError, LemuraMaxIterationsError, LemuraSkillInjectionError, LemuraToolNotFoundError, LemuraToolTimeoutError, LemuraToolValidationError } from './types/index.js';
-export { I as ILogger, L as LogLevel, a as LogMetadata, S as Severity } from './logger-DxvKliuk.js';
+import { a as IProviderAdapter, T as TranscriptionRequest, c as TranscriptionResponse, d as SynthesisRequest, A as AudioChunk, V as VisionRequest, e as VisionResponse, f as ImageGenRequest, g as ImageGenResponse, M as ModelInfo, C as ContextWindow, h as Turn, i as ContentBlock, I as IToolDefinition } from './storage-DBt_q0wO.js';
+export { j as CompletionChunk, k as CompletionRequest, l as CompletionResponse, b as IContextStrategy, m as IStorageAdapter, N as NormalizedMessage, n as STMItem, o as STMRegistryConfig, S as ShortTermMemoryRegistry, p as TokenUsage, q as ToolCall, r as ToolContext, s as ToolResult } from './storage-DBt_q0wO.js';
+import { S as SessionConfig, I as IToolResponseProcessor, T as ToolResponseEvaluation, M as MCPServerConfig, a as MCPToolDefinition } from './agent-DxRd93wl.js';
+export { b as MCPJsonRpcRequest, c as MCPJsonRpcResponse, d as MCPTransportType, e as MediaConfig, f as ToolDecision, g as ToolExecutionBudget, h as ToolFirewallConfig, i as ToolFirewallRule, j as TraceEvent } from './agent-DxRd93wl.js';
+export { LemuraAdapterError, LemuraContextOverflowError, LemuraError, LemuraMCPConnectionError, LemuraMCPError, LemuraMCPTimeoutError, LemuraMaxIterationsError, LemuraSkillInjectionError, LemuraToolNotFoundError, LemuraToolTimeoutError, LemuraToolValidationError } from './types/index.js';
+import { I as ILogger } from './logger-DxvKliuk.js';
+export { L as LogLevel, a as LogMetadata, S as Severity } from './logger-DxvKliuk.js';
 export { I as IRAGAdapter, R as RAGDocument, a as RAGIngestOptions, b as RAGIngestRequest, c as RAGIngestResponse, d as RAGQueryRequest, e as RAGQueryResponse, f as RAGResult } from './rag-La_Bo-J8.js';
 export { I as ISkill } from './skills-wc8S-OvC.js';
-import { I as IToolDefinition } from './storage-BGu4Loao.js';
-export { a as IStorageAdapter, S as STMItem, b as STMRegistryConfig, c as ShortTermMemoryRegistry, T as ToolContext } from './storage-BGu4Loao.js';
 export { OpenAICompatibleAdapter, OpenAICompatibleAdapterConfig, RetryConfig } from './adapters/index.js';
 export { ContextManager, HistoryCompressionConfig, HistoryCompressionStrategy, InMemoryStorageAdapter, SandwichCompressionConfig, SandwichCompressionStrategy, ScratchpadStrategy } from './context/index.js';
-export { ToolRegistry } from './tools/index.js';
+export { SchemaValidationError, ToolFirewallResult, ToolRegistry, ToolRegistryOptions, evaluateToolFirewall, validateJsonSchema } from './tools/index.js';
 export { SkillInjector } from './skills/index.js';
 export { InMemoryRAGAdapter } from './rag/index.js';
 export { DefaultLogger } from './logger/index.js';
 
+/**
+ * MediaBridge provides a single, app-friendly entry point for audio/vision/image features.
+ */
+declare class MediaBridge {
+    private adapter;
+    constructor(adapter: IProviderAdapter);
+    transcribe(request: TranscriptionRequest): Promise<TranscriptionResponse>;
+    synthesize(request: SynthesisRequest): AsyncIterable<AudioChunk>;
+    synthesizeToArray(request: SynthesisRequest): Promise<AudioChunk[]>;
+    describeImage(request: VisionRequest): Promise<VisionResponse>;
+    generateImage(request: ImageGenRequest): Promise<ImageGenResponse>;
+    getModelInfo(): ModelInfo;
+    supportsVision(): boolean;
+}
+
+/**
+ * Core entry point for lemura agent sessions.
+ *
+ * `SessionManager` owns the full ReAct loop lifecycle:
+ * - Context window management and compression
+ * - Skill injection
+ * - Tool firewall + schema validation + timeout enforcement
+ * - Parallel tool execution (opt-in via `parallelToolCalls`)
+ * - maxSteps guard → forced graceful conclusion
+ * - Tool response compression (via `toolResponseProcessor`)
+ * - Goal injection (via `enableGoalPlanning`)
+ * - Streaming output (`stream()`)
+ *
+ * @example
+ * const session = new SessionManager({ adapter, model: 'gpt-4o', maxTokens: 16_000 });
+ * const answer = await session.run('What is the capital of France?');
+ */
 declare class SessionManager {
     private contextManager;
     private toolRegistry;
@@ -23,10 +55,97 @@ declare class SessionManager {
     private config;
     private iterations;
     private logger;
+    private media;
+    private stepCounter;
+    private toolResponseProcessor;
+    private goalInjector;
+    private continuationPlanner;
+    private mcpRegistry;
+    /** Resolves when all MCP servers are connected; used by run() and stream() */
+    private mcpReady;
+    private totalToolCallCount;
+    private perToolCallCount;
+    private totalTokens;
     constructor(config: SessionConfig);
+    private emitTrace;
+    /**
+     * Returns a shallow copy of the current context window.
+     */
     getContext(): ContextWindow;
+    /**
+     * Returns the current conversation history.
+     */
     getHistory(): Turn[];
+    /**
+     * Returns the `MediaBridge` for direct ASR / TTS / Vision / Image-gen calls.
+     */
+    getMedia(): MediaBridge;
+    /**
+     * Connects all configured MCP servers and registers their bridged tools.
+     * Called from the constructor as a fire-and-start async task; `run()` and
+     * `stream()` await `this.mcpReady` before executing.
+     */
+    private _initMCP;
+    /** Builds the system prompt, injecting skills and goal if configured. */
+    private buildSystemPrompt;
+    /** Builds the messages array for the provider from the current context */
+    private buildMessages;
+    /** Checks the tool execution budget and throws descriptively if exceeded */
+    private checkExecutionBudget;
+    /** Records a tool call in budget counters */
+    private recordToolCall;
+    /**
+     * Processes a firewall decision for a tool call.
+     * Returns true to proceed, false to block.
+     */
+    private passesFirewall;
+    /**
+     * Executes a single parsed tool call and returns the serialised result string.
+     */
+    private executeSingleToolCall;
+    /**
+     * Runs the full ReAct loop for a user message and returns the final assistant response.
+     *
+     * @param userMessage - The user's message (string or multimodal content blocks)
+     * @returns The assistant's final response string
+     * @throws {LemuraMaxIterationsError} When the loop exceeds `maxIterations`
+     */
     run(userMessage: string | ContentBlock[]): Promise<string>;
+    /**
+     * Runs the ReAct loop and streams the final assistant response token-by-token.
+     *
+     * Tool calls within the loop are still executed synchronously (they must complete
+     * before streaming the conclusion). Only the final LLM text output is streamed.
+     *
+     * @param userMessage - The user's message (string or multimodal content blocks)
+     * @returns An `AsyncIterable<string>` of delta tokens from the final response
+     *
+     * @example
+     * for await (const token of session.stream('Tell me a story')) {
+     *   process.stdout.write(token);
+     * }
+     */
+    stream(userMessage: string | ContentBlock[]): AsyncIterable<string>;
+    /**
+     * Resets the session: clears conversation history, resets iteration counters,
+     * and resets tool execution budgets. The adapter, config, and tools are retained.
+     */
+    reset(): void;
+    /**
+     * Closes the session and disconnects all MCP servers.
+     *
+     * Call this when you are done with the session and have registered MCP servers,
+     * to ensure child processes are terminated and HTTP connections are released.
+     *
+     * @example
+     * const session = new SessionManager({ ..., mcpServers: [...] });
+     * try {
+     *   await session.run('Hello');
+     * } finally {
+     *   await session.close();
+     * }
+     */
+    close(): Promise<void>;
 }
 
 /**
@@ -51,6 +170,7 @@ declare class GoalInjector {
     private goal;
     constructor(goal: Goal);
     injectInto(prompt: string): string;
+    getGoal(): Goal;
 }
 
 interface ContinuationStep {
@@ -88,4 +208,132 @@ declare class FinalResponseFormatter {
     static validateStructure(response: string): boolean;
 }
 
-export { ContentBlock, ContextWindow, type ContinuationPlan, ContinuationPlanner, type ContinuationStep, FinalResponseFormatter, type Goal, GoalInjector, IToolDefinition, IToolResponseProcessor, SessionConfig, SessionManager, StepCounter, ToolResponseEvaluation, ToolResponseProcessor, Turn };
+/**
+ * Low-level MCP server client.
+ *
+ * Supports two transports:
+ * - **stdio** — spawns a child process and communicates over stdin/stdout via newline-delimited JSON-RPC 2.0
+ * - **http** — sends JSON-RPC 2.0 `POST` requests using native `fetch` (Node >= 18 required)
+ *
+ * Lifecycle:
+ * 1. `connect()` — initialize the server and fetch its tool list
+ * 2. `callTool()` — invoke a tool by name
+ * 3. `disconnect()` — terminate the connection / child process
+ *
+ * @example
+ * const client = new MCPClient('github', {
+ *   name: 'github',
+ *   transport: 'stdio',
+ *   command: 'npx',
+ *   args: ['@modelcontextprotocol/server-github'],
+ *   env: { GITHUB_TOKEN: '...' }
+ * }, logger);
+ *
+ * await client.connect();
+ * const result = await client.callTool('create_issue', { title: 'bug' });
+ * await client.disconnect();
+ */
+declare class MCPClient {
+    private readonly config;
+    private readonly logger;
+    private readonly _serverName;
+    private readonly timeoutMs;
+    private _tools;
+    private _connected;
+    private process;
+    private pendingCallbacks;
+    private requestId;
+    private stdioBuffer;
+    constructor(name: string, config: MCPServerConfig, logger: ILogger);
+    get serverName(): string;
+    get tools(): MCPToolDefinition[];
+    get isConnected(): boolean;
+    /**
+     * Connects to the MCP server: sends `initialize` + `notifications/initialized`,
+     * then fetches the tool list via `tools/list`.
+     */
+    connect(): Promise<void>;
+    /**
+     * Calls a tool on this MCP server.
+     *
+     * @param toolName - The tool name as declared by the server
+     * @param args - Tool arguments (must match the tool's inputSchema)
+     * @returns The serialised result from the server
+     */
+    callTool(toolName: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Disconnects from the MCP server.
+     * For stdio: sends the `exit` notification then terminates the process.
+     */
+    disconnect(): Promise<void>;
+    private _connectStdio;
+    /** Parses newline-delimited JSON messages from the stdio buffer */
+    private _flushStdioBuffer;
+    private _nextId;
+    /** Sends a JSON-RPC request and returns the response, honouring the configured timeout. */
+    private _rpc;
+    private _rpcStdio;
+    private _rpcHttp;
+    /** Sends `initialize` then `notifications/initialized` per MCP spec */
+    private _initialize;
+    /** Fetches and caches the tool list from the server */
+    private _discoverTools;
+    private _assertNoError;
+}
+
+/**
+ * Manages the full lifecycle of multiple MCP server connections and routes
+ * tool calls to the correct server.
+ *
+ * Typical usage is handled automatically by `SessionManager` when `mcpServers`
+ * is set in `SessionConfig`. You can also use it standalone for advanced scenarios.
+ *
+ * @example
+ * const registry = new MCPClientRegistry(logger);
+ * await registry.register('github', { transport: 'stdio', command: 'npx', args: ['...'] });
+ * const tools = await registry.discoverTools(); // IToolDefinition[] ready for ToolRegistry
+ */
+declare class MCPClientRegistry {
+    private readonly clients;
+    /** toolName → serverName  */
+    private readonly toolRouter;
+    private readonly logger;
+    constructor(logger: ILogger);
+    /**
+     * Creates an `MCPClient` for the given config, connects to the server, and
+     * registers the server by name.
+     *
+     * @throws {LemuraMCPConnectionError} if connection / initialization fails
+     */
+    register(name: string, config: MCPServerConfig): Promise<void>;
+    /**
+     * Collects tools from all connected MCP servers and returns them as
+     * `IToolDefinition` adapters ready to be registered in `ToolRegistry`.
+     *
+     * Tool names are **not** namespaced — if two servers expose a tool with the
+     * same name, the last-registered server wins and a warning is emitted.
+     */
+    discoverTools(): Promise<IToolDefinition[]>;
+    /**
+     * Calls a tool on the correct MCP server.
+     *
+     * @param toolName - The tool name as registered via `discoverTools()`
+     * @param args - Parsed arguments object
+     * @throws {LemuraMCPConnectionError} if no server is registered for `toolName`
+     */
+    callTool(toolName: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Disconnects all registered MCP servers gracefully.
+     * Called automatically by `SessionManager.close()`.
+     */
+    disconnectAll(): Promise<void>;
+    /** Returns the names of all currently registered servers */
+    getRegisteredServers(): string[];
+    /**
+     * Bridges an `MCPToolDefinition` from the protocol into an `IToolDefinition`
+     * that the existing `ToolRegistry` can execute.
+     */
+    private _bridge;
+}
+
+export { AudioChunk, ContentBlock, ContextWindow, type ContinuationPlan, ContinuationPlanner, type ContinuationStep, FinalResponseFormatter, type Goal, GoalInjector, ILogger, IProviderAdapter, IToolDefinition, IToolResponseProcessor, ImageGenRequest, ImageGenResponse, MCPClient, MCPClientRegistry, MCPServerConfig, MCPToolDefinition, MediaBridge, ModelInfo, SessionConfig, SessionManager, StepCounter, SynthesisRequest, ToolResponseEvaluation, ToolResponseProcessor, TranscriptionRequest, TranscriptionResponse, Turn, VisionRequest, VisionResponse };