lemura 1.4.3 → 1.4.4

package/CHANGELOG.md

@@ -5,6 +5,52 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.4] - 2026-05-21
+
+### Added
+
+- **`StepVerifier` on `ContinuationStep`** (`verify?: StepVerifier`): Optional semantic verifier called after a tool executes to confirm the sub-goal is actually satisfied — independent of the LLM's own assessment. Returns `pass`, `fail`, or `retry`. A `retry` verdict resets the step to `pending` and re-queues it for the next iteration; `fail` triggers BFS propagation to dependant steps. Supports `maxRetries?: number` (default: `0`) before a `retry` verdict is forced to `fail`. Verifier exceptions are caught and treated as `fail`.
+
+- **`StepVerifierResult` interface**: `{ status: 'pass' | 'fail' | 'retry'; reason?: string }` — the return type of `StepVerifier.check()`.
+
+- **`ContinuationPlanner.markStepPending(stepId)`**: Resets a step to `pending` for a retry attempt and increments its internal retry counter.
+
+- **`ContinuationPlanner.getRetryCount(stepId)`**: Returns how many times a step has been retried.
+
+- **`SessionManager.getPlan()`**: New public method returning a snapshot of the current `ContinuationPlan` (or `null` if no plan is active). Use this after `run()` for post-mortem inspection of step statuses without relying on `onTrace`.
+
+- **`TraceEvent.type: 'verification'`**: New trace type. Emitted as `step_retry` when a verifier returns `retry`, and supplements the existing `step_failed` / `step_skipped` events now emitted by the planner.
+
+- **`onStepFailed` / `onStepSkipped` callbacks on `ContinuationPlanner`**: Internal callbacks wired at `setPlan()` time to emit `planning/step_failed` and `planning/step_skipped` trace events — including BFS-propagated skips, which were previously invisible to `onTrace`.
+
+### Changed
+
+- **`maxCompletionTokens` default raised from `2_000` to `4_000`**: The previous default was too low for complex reasoning chains, causing silent mid-thought truncations. Fully backward-compatible — any explicit `maxCompletionTokens` in existing configs is unchanged.
+
+- **`ContinuationPlanner.markStepFailed(stepId, reason?)`** and **`markStepSkipped(stepId, reason?)`**: Both methods now accept an optional `reason` string surfaced in trace events and BFS-propagated skip messages.
+
+### Fixed
+
+- **BFS-propagated step skips were invisible to `onTrace`**: When a step failed and its dependants were automatically skipped, no trace events were emitted for the skipped steps. The new `onStepSkipped` callback fires for every BFS-propagated skip, making silent plan collapses visible.
+
+- **No way to inspect plan state after `run()`**: `continuationPlanner` was private with no public accessor. The new `getPlan()` method exposes a safe snapshot for post-run debugging.
+
+### Other
+
+- **Config coherence warning** (`maxSteps` vs `maxIterations`): The `SessionManager` constructor now logs a `warn`-level message when `maxSteps` is explicitly set without a matching `maxIterations`, or when `maxSteps` is so large relative to `maxIterations` that it can never be reached. No behavior change — purely diagnostic, fully backward-compatible.
+
+## [1.4.3] - 2026-05-14
+
+### Changed
+
+- **npm package metadata**: Added `repository`, `bugs`, `homepage`, `keywords`, `author`, `license`, `engines`, `sideEffects`, and `files` fields to `package.json` to meet npm publishing standards.
+
+## [1.4.2] - 2026-05-14
+
+### Fixed
+
+- **OpenAI wire format for tool calls**: `OpenAICompatibleAdapter.toOpenAIMessages()` now converts lemura's internal camelCase `toolCalls` (assistant turns) and `name`-keyed tool results (tool turns) to the proper OpenAI wire format (`tool_calls` / `tool_call_id`). Previously, providers enforcing strict OpenAI compatibility (e.g. Cerebras) would reject these messages with a 400/422 error.
+
 ## [1.4.1] - 2026-05-07
 
 ### Added

package/dist/{agent-DfN5nNXc.d.mts → agent-81ZUiP-T.d.mts}

@@ -221,7 +221,7 @@ interface SessionConfig {
     skillTokenBudget?: number;
     /**
      * Maximum tokens the provider may generate per completion call.
-     * Defaults to 2 000 when not set. This is separate from `maxTokens`
+     * Defaults to 4 000 when not set. This is separate from `maxTokens`
      * which controls the total context window size.
      */
     maxCompletionTokens?: number;
@@ -271,7 +271,7 @@ interface SessionConfig {
 /** Rich trace event for observability */
 interface TraceEvent {
     sessionId?: string;
-    type: 'planning' | 'budget' | 'tool_call' | 'tool_result' | 'thinking' | 'system' | 'compression' | 'error' | 'skill';
+    type: 'planning' | 'budget' | 'tool_call' | 'tool_result' | 'thinking' | 'system' | 'compression' | 'error' | 'skill' | 'verification';
     name: string;
     input?: any;
     output?: any;

package/dist/{agent-DTcDIKIn.d.ts → agent-BH_uE2nT.d.ts}

@@ -221,7 +221,7 @@ interface SessionConfig {
     skillTokenBudget?: number;
     /**
      * Maximum tokens the provider may generate per completion call.
-     * Defaults to 2 000 when not set. This is separate from `maxTokens`
+     * Defaults to 4 000 when not set. This is separate from `maxTokens`
      * which controls the total context window size.
      */
     maxCompletionTokens?: number;
@@ -271,7 +271,7 @@ interface SessionConfig {
 /** Rich trace event for observability */
 interface TraceEvent {
     sessionId?: string;
-    type: 'planning' | 'budget' | 'tool_call' | 'tool_result' | 'thinking' | 'system' | 'compression' | 'error' | 'skill';
+    type: 'planning' | 'budget' | 'tool_call' | 'tool_result' | 'thinking' | 'system' | 'compression' | 'error' | 'skill' | 'verification';
     name: string;
     input?: any;
     output?: any;

package/dist/index.d.mts

@@ -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-BhTAnrOM.mjs';
 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-BhTAnrOM.mjs';
-import { S as SessionConfig, I as IToolResponseProcessor, T as ToolResponseEvaluation, M as MCPServerConfig, a as MCPToolDefinition } from './agent-DfN5nNXc.mjs';
-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-DfN5nNXc.mjs';
+import { S as SessionConfig, I as IToolResponseProcessor, T as ToolResponseEvaluation, M as MCPServerConfig, a as MCPToolDefinition } from './agent-81ZUiP-T.mjs';
+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-81ZUiP-T.mjs';
 export { LemuraAdapterError, LemuraContextOverflowError, LemuraError, LemuraMCPConnectionError, LemuraMCPError, LemuraMCPTimeoutError, LemuraMaxIterationsError, LemuraSkillInjectionError, LemuraToolNotFoundError, LemuraToolTimeoutError, LemuraToolValidationError } from './types/index.mjs';
 import { I as ILogger } from './logger-DxvKliuk.mjs';
 export { L as LogLevel, a as LogMetadata, S as Severity } from './logger-DxvKliuk.mjs';
@@ -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.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 };