lemura 1.2.0 → 1.4.0

package/dist/index.d.ts

@@ -1,16 +1,17 @@
-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';
+import { a as IProviderAdapter, T as TranscriptionRequest, d as TranscriptionResponse, e as SynthesisRequest, A as AudioChunk, V as VisionRequest, f as VisionResponse, g as ImageGenRequest, h as ImageGenResponse, M as ModelInfo, C as ContextWindow, i as Turn, j as ContentBlock, I as IToolDefinition } from './adapters-CVcfWf85.js';
+export { k as CompletionChunk, l as CompletionRequest, m as CompletionResponse, b as IContextStrategy, c as IScratchpadAdapter, n as IStorageAdapter, N as NormalizedMessage, o as STMItem, p as STMRegistryConfig, S as ShortTermMemoryRegistry, q as TokenUsage, r as ToolCall, s as ToolContext, t as ToolResult } from './adapters-CVcfWf85.js';
+import { S as SessionConfig, I as IToolResponseProcessor, T as ToolResponseEvaluation, M as MCPServerConfig, a as MCPToolDefinition } from './agent-38El9_yp.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-38El9_yp.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';
+export { I as ISkill, S as SkillStrategy } from './skills-Y6D7zSSw.js';
 export { OpenAICompatibleAdapter, OpenAICompatibleAdapterConfig, RetryConfig } from './adapters/index.js';
-export { ContextManager, HistoryCompressionConfig, HistoryCompressionStrategy, InMemoryStorageAdapter, SandwichCompressionConfig, SandwichCompressionStrategy, ScratchpadStrategy } from './context/index.js';
-export { SchemaValidationError, ToolFirewallResult, ToolRegistry, ToolRegistryOptions, evaluateToolFirewall, validateJsonSchema } from './tools/index.js';
-export { SkillInjector } from './skills/index.js';
+export { ContextManager, HistoryCompressionConfig, HistoryCompressionStrategy, InMemoryScratchpadAdapter, InMemoryStorageAdapter, SandwichCompressionConfig, SandwichCompressionStrategy, ScratchpadStrategy, SummaryInjectionConfig, SummaryInjectionStrategy } from './context/index.js';
+import { ToolRegistry } from './tools/index.js';
+export { SchemaValidationError, ToolFirewallResult, ToolRegistryOptions, evaluateToolFirewall, validateJsonSchema } from './tools/index.js';
+import { SkillInjector } from './skills/index.js';
 export { InMemoryRAGAdapter } from './rag/index.js';
 export { DefaultLogger } from './logger/index.js';
 
@@ -29,22 +30,186 @@ declare class MediaBridge {
     supportsVision(): boolean;
 }
 
+interface Goal {
+    id: string;
+    statement: string;
+    /** High-level sub-goals decomposed from the main statement */
+    decomposition: string[];
+    successCriteria: string[];
+    injectionFrequency: 'always' | 'every_N_turns' | 'on_compression';
+    injectionPosition: 'system_prompt' | 'pre_turn';
+    /** Sub-goals already completed — updated via `markSubGoalDone()` */
+    completedSubGoals?: string[];
+}
+/**
+ * GoalInjector keeps the original task objective visible throughout the ReAct loop,
+ * preventing goal drift after many tool calls and context compressions.
+ *
+ * Usage in SessionManager:
+ * - For `system_prompt` position: call `injectInto(prompt)` which appends the goal block.
+ * - For `pre_turn` position: call `getFormattedBlock()` and push as a system message.
+ */
+declare class GoalInjector {
+    private goal;
+    private turnsSinceInjection;
+    constructor(goal: Goal);
+    /**
+     * Returns the formatted `[CURRENT GOAL]` block string — without caring about
+     * where it will be placed. Callers decide whether to append to a system prompt
+     * or push as a separate message.
+     */
+    getFormattedBlock(): string;
+    /**
+     * Appends the goal block to the given prompt string (for `system_prompt` position).
+     * For `pre_turn` position, use `getFormattedBlock()` directly.
+     *
+     * @param prompt - The existing system prompt to append to.
+     */
+    injectInto(prompt: string): string;
+    /**
+     * Returns true when the goal should be re-injected this turn,
+     * based on `injectionFrequency`.
+     *
+     * @param turnIndex - The current turn index in the ReAct loop (0-based)
+     * @param compressionOccurred - Whether context was compressed this iteration
+     * @param injectionN - The N for 'every_N_turns' frequency (default: 3)
+     */
+    shouldInjectThisTurn(turnIndex: number, compressionOccurred?: boolean, injectionN?: number): boolean;
+    /**
+     * Updates the goal with new sub-goal decomposition and success criteria,
+     * typically populated by the mini-planning LLM call.
+     */
+    updateDecomposition(decomposition: string[], successCriteria?: string[]): void;
+    /**
+     * Marks a sub-goal as completed so it moves to the "completed" section
+     * in subsequent injections.
+     */
+    markSubGoalDone(subGoal: string): void;
+    /** Returns a snapshot of the current goal state (safe to store in context.metadata). */
+    getGoal(): Goal;
+    /** Increments the internal turn counter (used for `every_N_turns` frequency). */
+    incrementTurn(): void;
+}
+
+/**
+ * An optional condition that gates a step's execution on the output of a prior step.
+ * When the condition is not met, the step is automatically marked `skipped`.
+ */
+interface StepCondition {
+    /** stepId whose output is inspected */
+    step: string;
+    /** Substring that must be present in the prior step's output to allow this step to run */
+    outputContains: string;
+}
+interface ContinuationStep {
+    stepId: string;
+    toolName: string;
+    description: string;
+    /** stepIds that must be `done` before this step may run */
+    dependsOn: string[];
+    status: 'pending' | 'running' | 'done' | 'failed' | 'skipped';
+    /**
+     * When provided, the step's output is stored under this key in
+     * `context.metadata['toolOutputs']` for downstream steps to reference.
+     */
+    outputKey?: string;
+    /**
+     * Maps prior step `outputKey` values to this step's tool parameter names.
+     * E.g. `{ data: 'rawData' }` means the tool's `data` param gets the value
+     * stored under the `rawData` output key from an earlier step.
+     */
+    inputMapping?: Record<string, string>;
+    /**
+     * Optional condition: the step only runs if the referenced prior step's output
+     * contains the given substring. When the condition is not met, the step is skipped.
+     */
+    condition?: StepCondition;
+}
+interface ContinuationPlan {
+    steps: ContinuationStep[];
+    currentStepIndex: number;
+    strategy: 'sequential' | 'parallel' | 'conditional';
+}
+/**
+ * Manages a structured multi-step continuation plan for the ReAct loop.
+ *
+ * Steps are tracked by status (`pending`, `running`, `done`, `failed`, `skipped`).
+ * Dependency failures automatically propagate `skipped` to all downstream steps.
+ * Step outputs are stored by `outputKey` and made available for `inputMapping`.
+ *
+ * @example
+ * ```typescript
+ * const planner = new ContinuationPlanner({
+ *   steps: [
+ *     { stepId: 'fetch', toolName: 'fetch_data', description: 'Get raw data', dependsOn: [], outputKey: 'rawData' },
+ *     { stepId: 'analyze', toolName: 'analyze', description: 'Run analysis', dependsOn: ['fetch'], inputMapping: { data: 'rawData' } },
+ *   ],
+ *   currentStepIndex: 0,
+ *   strategy: 'sequential',
+ * });
+ * ```
+ */
+declare class ContinuationPlanner {
+    private plan;
+    private outputs;
+    constructor(plan: ContinuationPlan);
+    /** Returns the current plan (deep copy) */
+    getPlan(): ContinuationPlan;
+    /** Returns a human-readable status string with icons (injected before each iteration) */
+    getPlanStatusString(): string;
+    private _icon;
+    /** Returns all steps whose dependencies are satisfied and that are still pending */
+    getReadySteps(): ContinuationStep[];
+    /** Returns true when all steps have reached a terminal state */
+    isComplete(): boolean;
+    /** Marks a step as running */
+    markStepRunning(stepId: string): void;
+    /**
+     * Marks a step as done, stores its output under `outputKey` (if set),
+     * and advances `currentStepIndex` to the next pending step.
+     */
+    markStepDone(stepId: string, output?: string): void;
+    /**
+     * Marks a step as failed and propagates `skipped` to all transitively dependent steps.
+     */
+    markStepFailed(stepId: string): void;
+    /**
+     * Marks a step as skipped (e.g., condition not met) and propagates to its dependants.
+     */
+    markStepSkipped(stepId: string): void;
+    /** Retrieves an output stored by `outputKey` from a completed step */
+    getOutput(key: string): string | undefined;
+    /**
+     * Resolves the `inputMapping` for a step into a concrete parameter map,
+     * substituting `outputKey` values from prior steps. Static (non-key) values
+     * in the mapping are passed through unchanged.
+     */
+    resolveInputs(step: ContinuationStep, baseArgs?: Record<string, unknown>): Record<string, unknown>;
+    private _updateStep;
+    private _skipDependants;
+    private _advanceIndex;
+}
+
 /**
  * Core entry point for lemura agent sessions.
  *
  * `SessionManager` owns the full ReAct loop lifecycle:
  * - Context window management and compression
- * - Skill injection
+ * - Skill injection (with optional token budget)
  * - 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`)
+ * - Tool response compression (via `ToolResponseProcessor`)
+ * - Goal injection + mini-planning step (via `enableGoalPlanning`)
+ * - Continuation planning with dependency tracking (via `enableContinuationPlanning`)
  * - Streaming output (`stream()`)
+ * - Session lifecycle: `reset()`, `close()`
  *
  * @example
+ * ```typescript
  * 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;
@@ -56,44 +221,146 @@ declare class SessionManager {
     private iterations;
     private logger;
     private media;
+    private sessionId;
+    private scratchpadLoaded;
+    private pendingScratchpadClear;
     private stepCounter;
     private toolResponseProcessor;
     private goalInjector;
     private continuationPlanner;
     private mcpRegistry;
-    /** Resolves when all MCP servers are connected; used by run() and stream() */
+    /** Resolves when all MCP servers are connected; awaited by run() and stream() */
     private mcpReady;
     private totalToolCallCount;
     private perToolCallCount;
     private totalTokens;
     constructor(config: SessionConfig);
     private emitTrace;
+    private ensureScratchpadLoaded;
+    /** Returns a shallow copy of the current context window. */
+    getContext(): ContextWindow;
+    /** Returns the current conversation history. */
+    getHistory(): Turn[];
     /**
-     * Returns a shallow copy of the current context window.
+     * Populates the session context with a pre-existing conversation history.
+     *
+     * Turns are assigned sequential `turnIndex` values starting from 0 and the
+     * context `tokenCount` is recalculated automatically. Call this immediately
+     * after construction and before the first `run()` / `stream()`.
+     *
+     * @param history - Raw history entries (role + content, optional toolCalls/toolResults).
+     *
+     * @example
+     * ```typescript
+     * const session = new SessionManager(config);
+     * session.loadHistory(savedMessages);
+     * const answer = await session.run('Continue where we left off.');
+     * ```
      */
-    getContext(): ContextWindow;
+    loadHistory(history: Array<{
+        role: Turn['role'];
+        content: Turn['content'];
+        toolCalls?: Turn['toolCalls'];
+        toolResults?: Turn['toolResults'];
+    }>): void;
+    /** Returns the `MediaBridge` for direct ASR / TTS / Vision / Image-gen calls. */
+    getMedia(): MediaBridge;
     /**
-     * Returns the current conversation history.
+     * Returns the `ToolRegistry` for runtime tool management.
+     *
+     * Use this to register or unregister tools after session construction:
+     *
+     * ```typescript
+     * // Add a tool after the user authenticates
+     * session.tools.register(paymentTool);
+     *
+     * // Remove a tool when no longer needed
+     * session.tools.unregister('send_payment');
+     *
+     * // Inspect what's registered
+     * const active = session.tools.getAll();
+     * console.log(active.map(t => t.name));
+     * ```
+     *
+     * @since 1.4.0
      */
-    getHistory(): Turn[];
+    get tools(): ToolRegistry;
     /**
-     * Returns the `MediaBridge` for direct ASR / TTS / Vision / Image-gen calls.
+     * Returns the `SkillInjector` for runtime skill management.
+     *
+     * Use this to enable or disable dynamic skills after session construction:
+     *
+     * ```typescript
+     * session.skills.enableSkill('code-review');
+     * session.skills.enableByTags(['debugging']);
+     * session.skills.disableSkill('verbose-mode');
+     * const requiredTools = session.skills.getRequiredTools();
+     * ```
+     *
+     * @since 1.4.0
      */
-    getMedia(): MediaBridge;
+    get skills(): SkillInjector;
+    /**
+     * Sets an explicit multi-step continuation plan that will be tracked and
+     * injected as a status block before each ReAct iteration.
+     *
+     * Dependency tracking, condition evaluation, `outputKey` storage, and
+     * `inputMapping` resolution are all handled automatically by the planner.
+     *
+     * @param steps    - The ordered list of continuation steps.
+     * @param strategy - Execution strategy ('sequential' | 'parallel' | 'conditional'). Default: 'sequential'.
+     *
+     * @example
+     * ```typescript
+     * await session.setPlan([
+     *   { stepId: 'fetch', toolName: 'fetch_data', description: 'Get data', dependsOn: [], outputKey: 'rawData' },
+     *   { stepId: 'analyze', toolName: 'analyze', description: 'Analyze', dependsOn: ['fetch'], inputMapping: { data: 'rawData' } },
+     * ]);
+     * const result = await session.run('Run the data pipeline.');
+     * ```
+     */
+    setPlan(steps: ContinuationStep[], strategy?: ContinuationPlan['strategy']): void;
+    /**
+     * Manually sets the agent's goal, bypassing the automatic mini-planning LLM call.
+     *
+     * Use this when you already know the goal structure upfront.
+     *
+     * @example
+     * ```typescript
+     * await session.setGoal({
+     *   statement: 'Audit the authentication module',
+     *   decomposition: ['Read src/auth/', 'Identify SQL injection risks', 'Write report'],
+     *   successCriteria: ['Report covers all audit areas', 'Each finding has a severity rating'],
+     * });
+     * const result = await session.run('Begin the security audit.');
+     * ```
+     */
+    setGoal(goal: Omit<Goal, 'id' | 'injectionFrequency' | 'injectionPosition'>): void;
     /**
      * 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;
+    /**
+     * Runs a dedicated planning prompt against the LLM to decompose the user's
+     * message into sub-goals and success criteria. Called once at the start of
+     * the first `run()` when `enableGoalPlanning` is true and no goal has been
+     * manually set via `setGoal()`.
+     */
+    private _runMiniPlanningStep;
     /** Builds the system prompt, injecting skills and goal if configured. */
     private buildSystemPrompt;
-    /** Builds the messages array for the provider from the current context */
+    /** Builds the messages array for the provider from the current context. */
     private buildMessages;
-    /** Checks the tool execution budget and throws descriptively if exceeded */
+    /** Checks the tool execution budget and throws descriptively if exceeded. */
     private checkExecutionBudget;
-    /** Records a tool call in budget counters */
+    /** Records a tool call in budget counters. */
     private recordToolCall;
+    private isProbablyBase64;
+    private isBinaryLike;
+    private storeBlob;
+    private scrubBlobFields;
     /**
      * Processes a firewall decision for a tool call.
      * Returns true to proceed, false to block.
@@ -101,11 +368,15 @@ declare class SessionManager {
     private passesFirewall;
     /**
      * Executes a single parsed tool call and returns the serialised result string.
+     * Also handles continuation plan tracking (step status + output storage).
      */
     private executeSingleToolCall;
     /**
      * Runs the full ReAct loop for a user message and returns the final assistant response.
      *
+     * When `enableGoalPlanning` is true and no goal has been manually set, a mini-planning
+     * LLM call is made before the first iteration to decompose the task into sub-goals.
+     *
      * @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`
@@ -121,78 +392,83 @@ declare class SessionManager {
      * @returns An `AsyncIterable<string>` of delta tokens from the final response
      *
      * @example
+     * ```typescript
      * 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.
+     * tool execution budget tallies, and goal/plan state.
+     * The adapter, config, compression strategies, 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.
+     * Call this when you are done with the session to ensure child processes are
+     * terminated and HTTP connections are released.
      *
      * @example
+     * ```typescript
      * const session = new SessionManager({ ..., mcpServers: [...] });
      * try {
      *   await session.run('Hello');
      * } finally {
      *   await session.close();
      * }
+     * ```
      */
     close(): Promise<void>;
 }
 
 /**
- * Advanced Execution: ToolResponseProcessor handles compression
- * and evaluation of tool outputs, flagging errors, mapping tool size classes
- * and compressing large responses to save token bandwidth.
+ * Configuration for `ToolResponseProcessor`.
+ *
+ * Token thresholds define the boundaries between size classes.
+ * `budgetPercent` caps the combined token spend of all tool results per iteration.
+ */
+interface ToolResponseProcessorConfig {
+    /** Max tokens for a `small` response. Responses at or below this are verbatim. Default: 200 */
+    smallMaxTokens?: number;
+    /** Max tokens for a `medium` response. Responses at or below this are verbatim. Default: 800 */
+    mediumMaxTokens?: number;
+    /** Max tokens for a `large` response. Above this threshold → `oversized`. Default: 2000 */
+    largeMaxTokens?: number;
+    /**
+     * Cap total tool-response tokens per iteration as a fraction of session `maxTokens`.
+     * E.g. `0.15` means all tool results combined must fit within 15% of the context window.
+     * Not enforced by the processor itself — SessionManager uses this to decide when to
+     * apply extra compression after all tool results are collected. Default: undefined (no cap).
+     */
+    budgetPercent?: number;
+}
+/**
+ * Evaluates and compresses tool response strings before they are appended to the
+ * context window, preventing large tool outputs from flooding the token budget.
+ *
+ * @example
+ * ```typescript
+ * toolResponseProcessor: new ToolResponseProcessor({
+ *   smallMaxTokens:  200,
+ *   mediumMaxTokens: 800,
+ *   largeMaxTokens:  2000,
+ *   budgetPercent:   0.15,
+ * })
+ * ```
  */
 declare class ToolResponseProcessor implements IToolResponseProcessor {
+    private readonly smallMax;
+    private readonly mediumMax;
+    private readonly largeMax;
+    readonly budgetPercent: number | undefined;
+    constructor(config?: ToolResponseProcessorConfig);
     evaluate(response: string, tool: IToolDefinition, context: unknown): ToolResponseEvaluation;
     compress(response: string, evaluation: ToolResponseEvaluation): string;
 }
 
-interface Goal {
-    id: string;
-    statement: string;
-    decomposition: string[];
-    successCriteria: string[];
-    injectionFrequency: 'always' | 'every_N_turns' | 'on_compression';
-    injectionPosition: 'system_prompt' | 'pre_turn';
-}
-declare class GoalInjector {
-    private goal;
-    constructor(goal: Goal);
-    injectInto(prompt: string): string;
-    getGoal(): Goal;
-}
-
-interface ContinuationStep {
-    stepId: string;
-    toolName: string;
-    description: string;
-    dependsOn: string[];
-    status: 'pending' | 'running' | 'done' | 'failed' | 'skipped';
-    outputKey?: string;
-    inputMapping?: Record<string, string>;
-}
-interface ContinuationPlan {
-    steps: ContinuationStep[];
-    currentStepIndex: number;
-    strategy: 'sequential' | 'parallel' | 'conditional';
-}
-declare class ContinuationPlanner {
-    private plan;
-    constructor(plan: ContinuationPlan);
-    getPlanStatusString(): string;
-}
-
 declare class StepCounter {
     private maxSteps;
     private toolCallCount;
@@ -336,4 +612,4 @@ declare class MCPClientRegistry {
     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 };
+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, SkillInjector, type StepCondition, StepCounter, SynthesisRequest, ToolRegistry, ToolResponseEvaluation, ToolResponseProcessor, type ToolResponseProcessorConfig, TranscriptionRequest, TranscriptionResponse, Turn, VisionRequest, VisionResponse };