lemura 1.4.2 → 1.4.4

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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-DTcDIKIn.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-DTcDIKIn.js';
+import { S as SessionConfig, I as IToolResponseProcessor, T as ToolResponseEvaluation, M as MCPServerConfig, a as MCPToolDefinition } from './agent-BH_uE2nT.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-BH_uE2nT.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';
@@ -30,67 +30,6 @@ 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`.
@@ -101,6 +40,44 @@ interface StepCondition {
     /** Substring that must be present in the prior step's output to allow this step to run */
     outputContains: string;
 }
+/**
+ * Result returned by a `StepVerifier.check` function.
+ * - `pass`  — the sub-goal is achieved; the step is marked `done`.
+ * - `fail`  — the sub-goal failed; the step is marked `failed` and BFS propagates to dependants.
+ * - `retry` — the output is unsatisfactory but retriable; the step is reset to `pending`.
+ */
+interface StepVerifierResult {
+    status: 'pass' | 'fail' | 'retry';
+    reason?: string;
+}
+/**
+ * Optional semantic verifier attached to a `ContinuationStep`.
+ * Called after the tool executes successfully to confirm the sub-goal is actually met.
+ *
+ * @example
+ * verify: {
+ *   maxRetries: 2,
+ *   check: (output) => {
+ *     const data = JSON.parse(output);
+ *     return data.rows?.length > 0
+ *       ? { status: 'pass' }
+ *       : { status: 'retry', reason: 'Empty result set' };
+ *   }
+ * }
+ */
+interface StepVerifier {
+    /**
+     * Inspects the tool output and decides whether the sub-goal is satisfied.
+     * @param output  - Serialised tool result string
+     * @param args    - The resolved arguments that were passed to the tool
+     */
+    check: (output: string, args: Record<string, unknown>) => Promise<StepVerifierResult> | StepVerifierResult;
+    /**
+     * Maximum number of `retry` verdicts allowed before the step is forced to `failed`.
+     * Defaults to 0 (no retries — a `retry` verdict immediately becomes `failed`).
+     */
+    maxRetries?: number;
+}
 interface ContinuationStep {
     stepId: string;
     toolName: string;
@@ -124,6 +101,14 @@ interface ContinuationStep {
      * contains the given substring. When the condition is not met, the step is skipped.
      */
     condition?: StepCondition;
+    /**
+     * Optional semantic verifier: called after the tool executes to confirm the
+     * sub-goal is actually satisfied. Supports `pass / fail / retry` verdicts
+     * with a configurable `maxRetries` count.
+     *
+     * @since 1.4.4
+     */
+    verify?: StepVerifier;
 }
 interface ContinuationPlan {
     steps: ContinuationStep[];
@@ -152,7 +137,13 @@ interface ContinuationPlan {
 declare class ContinuationPlanner {
     private plan;
     private outputs;
-    constructor(plan: ContinuationPlan);
+    private retryCount;
+    private onStepSkipped;
+    private onStepFailed;
+    constructor(plan: ContinuationPlan, callbacks?: {
+        onStepSkipped?: (stepId: string, reason: string) => void;
+        onStepFailed?: (stepId: string, reason: string) => void;
+    });
     /** Returns the current plan (deep copy) */
     getPlan(): ContinuationPlan;
     /** Returns a human-readable status string with icons (injected before each iteration) */
@@ -172,11 +163,18 @@ declare class ContinuationPlanner {
     /**
      * Marks a step as failed and propagates `skipped` to all transitively dependent steps.
      */
-    markStepFailed(stepId: string): void;
+    markStepFailed(stepId: string, reason?: string): void;
     /**
      * Marks a step as skipped (e.g., condition not met) and propagates to its dependants.
      */
-    markStepSkipped(stepId: string): void;
+    markStepSkipped(stepId: string, reason?: string): void;
+    /**
+     * Resets a step back to `pending` for a retry attempt.
+     * Increments the internal retry counter for the step.
+     */
+    markStepPending(stepId: string): void;
+    /** Returns how many times a step has been retried. */
+    getRetryCount(stepId: string): number;
     /** Retrieves an output stored by `outputKey` from a completed step */
     getOutput(key: string): string | undefined;
     /**
@@ -190,6 +188,67 @@ declare class ContinuationPlanner {
     private _advanceIndex;
 }
 
+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;
+}
+
 /**
  * Core entry point for lemura agent sessions.
  *
@@ -320,6 +379,22 @@ declare class SessionManager {
      * ```
      */
     setPlan(steps: ContinuationStep[], strategy?: ContinuationPlan['strategy']): void;
+    /**
+     * Returns a snapshot of the current continuation plan, or `null` if no plan
+     * has been set via `setPlan()`.
+     *
+     * Use this after `run()` to inspect which steps completed, failed, or were skipped.
+     *
+     * @since 1.4.4
+     *
+     * @example
+     * ```typescript
+     * await session.run('Run the pipeline');
+     * const plan = session.getPlan();
+     * const failed = plan?.steps.filter(s => s.status === 'failed');
+     * ```
+     */
+    getPlan(): ContinuationPlan | null;
     /**
      * Manually sets the agent's goal, bypassing the automatic mini-planning LLM call.
      *
@@ -612,4 +687,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, SkillInjector, type StepCondition, StepCounter, SynthesisRequest, ToolRegistry, ToolResponseEvaluation, ToolResponseProcessor, type ToolResponseProcessorConfig, 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, type StepVerifier, type StepVerifierResult, SynthesisRequest, ToolRegistry, ToolResponseEvaluation, ToolResponseProcessor, type ToolResponseProcessorConfig, TranscriptionRequest, TranscriptionResponse, Turn, VisionRequest, VisionResponse };

package/dist/index.js

@@ -1925,8 +1925,13 @@ ${block}` : block;
 var ContinuationPlanner = class {
   plan;
   outputs = /* @__PURE__ */ new Map();
-  constructor(plan) {
+  retryCount = /* @__PURE__ */ new Map();
+  onStepSkipped;
+  onStepFailed;
+  constructor(plan, callbacks) {
     this.plan = { ...plan, steps: plan.steps.map((s) => ({ ...s })) };
+    this.onStepSkipped = callbacks?.onStepSkipped;
+    this.onStepFailed = callbacks?.onStepFailed;
   }
   // -------------------------------------------------------------------------
   // State queries
@@ -2007,17 +2012,31 @@ var ContinuationPlanner = class {
   /**
    * Marks a step as failed and propagates `skipped` to all transitively dependent steps.
    */
-  markStepFailed(stepId) {
+  markStepFailed(stepId, reason = "step failed") {
     this._updateStep(stepId, { status: "failed" });
+    this.onStepFailed?.(stepId, reason);
     this._skipDependants(stepId);
   }
   /**
    * Marks a step as skipped (e.g., condition not met) and propagates to its dependants.
    */
-  markStepSkipped(stepId) {
+  markStepSkipped(stepId, reason = "condition not met") {
     this._updateStep(stepId, { status: "skipped" });
+    this.onStepSkipped?.(stepId, reason);
     this._skipDependants(stepId);
   }
+  /**
+   * Resets a step back to `pending` for a retry attempt.
+   * Increments the internal retry counter for the step.
+   */
+  markStepPending(stepId) {
+    this._updateStep(stepId, { status: "pending" });
+    this.retryCount.set(stepId, (this.retryCount.get(stepId) ?? 0) + 1);
+  }
+  /** Returns how many times a step has been retried. */
+  getRetryCount(stepId) {
+    return this.retryCount.get(stepId) ?? 0;
+  }
   // -------------------------------------------------------------------------
   // Output / input mapping helpers
   // -------------------------------------------------------------------------
@@ -2059,6 +2078,7 @@ var ContinuationPlanner = class {
       for (const step of this.plan.steps) {
         if (step.status === "pending" && step.dependsOn.some((d) => toSkip.has(d))) {
           this._updateStep(step.stepId, { status: "skipped" });
+          this.onStepSkipped?.(step.stepId, `dependency '${failedStepId}' failed or was skipped`);
           toSkip.add(step.stepId);
           changed = true;
         }
@@ -2587,6 +2607,21 @@ var SessionManager = class {
     }
     this.media = new MediaBridge(this.adapter);
     this.stepCounter = new StepCounter(config.maxSteps ?? 20);
+    if (config.maxSteps !== void 0 && config.maxIterations === void 0) {
+      const defaultMaxIts = 10;
+      if (config.maxSteps > defaultMaxIts) {
+        this.logger.warn(
+          `[Config] maxSteps=${config.maxSteps} is set but maxIterations is not. The default maxIterations=${defaultMaxIts} may stop the agent before maxSteps is reached. Consider setting maxIterations to at least Math.ceil(maxSteps / avgToolCallsPerTurn).`
+        );
+      }
+    }
+    if (config.maxSteps !== void 0 && config.maxIterations !== void 0) {
+      if (config.maxSteps > config.maxIterations * 10) {
+        this.logger.warn(
+          `[Config] maxSteps (${config.maxSteps}) is much larger than maxIterations (${config.maxIterations}). The agent will be stopped by maxIterations before maxSteps is ever reached.`
+        );
+      }
+    }
     this.toolResponseProcessor = config.toolResponseProcessor instanceof ToolResponseProcessor ? config.toolResponseProcessor : config.toolResponseProcessor ? config.toolResponseProcessor : new ToolResponseProcessor();
     for (const strategy of config.compressionStrategies || []) {
       this.contextManager.registerStrategy(strategy);
@@ -2786,16 +2821,39 @@ var SessionManager = class {
    * ```
    */
   setPlan(steps, strategy = "sequential") {
-    this.continuationPlanner = new ContinuationPlanner({
-      steps,
-      currentStepIndex: 0,
-      strategy
-    });
+    this.continuationPlanner = new ContinuationPlanner(
+      { steps, currentStepIndex: 0, strategy },
+      {
+        onStepFailed: (stepId, reason) => this.emitTrace("planning", "step_failed", { stepId, reason }),
+        onStepSkipped: (stepId, reason) => this.emitTrace("planning", "step_skipped", { stepId, reason })
+      }
+    );
     this.context.metadata["continuationPlan"] = this.continuationPlanner.getPlan();
     this.logger.debug(`[ContinuationPlanner] Plan set with ${steps.length} steps (strategy: ${strategy})`);
     this.emitTrace("planning", "plan_set", { stepCount: steps.length, strategy });
   }
   // -----------------------------------------------------------------------
+  // Plan inspection API
+  // -----------------------------------------------------------------------
+  /**
+   * Returns a snapshot of the current continuation plan, or `null` if no plan
+   * has been set via `setPlan()`.
+   *
+   * Use this after `run()` to inspect which steps completed, failed, or were skipped.
+   *
+   * @since 1.4.4
+   *
+   * @example
+   * ```typescript
+   * await session.run('Run the pipeline');
+   * const plan = session.getPlan();
+   * const failed = plan?.steps.filter(s => s.status === 'failed');
+   * ```
+   */
+  getPlan() {
+    return this.continuationPlanner ? this.continuationPlanner.getPlan() : null;
+  }
+  // -----------------------------------------------------------------------
   // Goal planning API
   // -----------------------------------------------------------------------
   /**
@@ -2887,7 +2945,7 @@ Respond ONLY with valid JSON (no markdown, no explanations):
       const response = await this.adapter.complete({
         model: this.config.model,
         messages: [{ role: "user", content: planningPrompt }],
-        maxTokens: this.config.maxCompletionTokens ?? 2e3
+        maxTokens: this.config.maxCompletionTokens ?? 4e3
       });
       const raw = response.content.replace(/```json|```/g, "").trim();
       const parsed = JSON.parse(raw);
@@ -3204,6 +3262,36 @@ ${planStatus}`;
         (s) => s.toolName === tc.name && s.status === "running"
       );
       if (runningStep) {
+        if (runningStep.verify) {
+          const maxRetries = runningStep.verify.maxRetries ?? 0;
+          const retryCount = this.continuationPlanner.getRetryCount(runningStep.stepId);
+          let verdict;
+          try {
+            verdict = await runningStep.verify.check(content, args);
+          } catch (verifyErr) {
+            verdict = { status: "fail", reason: `Verifier threw: ${verifyErr.message}` };
+          }
+          if (verdict.status === "fail" || verdict.status === "retry" && retryCount >= maxRetries) {
+            this.continuationPlanner.markStepFailed(runningStep.stepId);
+            this.context.metadata["continuationPlan"] = this.continuationPlanner.getPlan();
+            this.emitTrace("planning", "step_failed", {
+              stepId: runningStep.stepId,
+              reason: verdict.reason ?? "verifier returned fail",
+              retryCount
+            });
+            return content;
+          }
+          if (verdict.status === "retry") {
+            this.continuationPlanner.markStepPending(runningStep.stepId);
+            this.context.metadata["continuationPlan"] = this.continuationPlanner.getPlan();
+            this.emitTrace("planning", "step_retry", {
+              stepId: runningStep.stepId,
+              reason: verdict.reason,
+              retryCount: this.continuationPlanner.getRetryCount(runningStep.stepId)
+            });
+            return content;
+          }
+        }
         this.continuationPlanner.markStepDone(runningStep.stepId, content);
         if (runningStep.outputKey) {
           const outputs = this.context.metadata["toolOutputs"] ?? {};
@@ -3274,7 +3362,7 @@ ${planStatus}`;
     const maxIts = this.config.maxIterations || 10;
     this.iterations = 0;
     this.stepCounter = new StepCounter(this.config.maxSteps ?? 20);
-    const maxCompletionTokens = this.config.maxCompletionTokens ?? 2e3;
+    const maxCompletionTokens = this.config.maxCompletionTokens ?? 4e3;
     while (this.iterations < maxIts) {
       this.iterations++;
       this.logger.debug(`ReAct Iteration ${this.iterations}/${maxIts}`);
@@ -3471,7 +3559,7 @@ ${planStatus}`;
     const maxIts = this.config.maxIterations || 10;
     this.iterations = 0;
     this.stepCounter = new StepCounter(this.config.maxSteps ?? 20);
-    const maxCompletionTokens = this.config.maxCompletionTokens ?? 2e3;
+    const maxCompletionTokens = this.config.maxCompletionTokens ?? 4e3;
     while (this.iterations < maxIts) {
       this.iterations++;
       this.logger.debug(`[stream] ReAct Iteration ${this.iterations}/${maxIts}`);