lemura 1.4.3 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,68 @@ 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.5.0] - 2026-05-27
+
+### Added
+
+- **`SessionManager.stream()`**: New `async *stream(userMessage)` method that runs the full ReAct loop (tool calls, goal verification, corrections) and then streams the final assistant response token-by-token as an `AsyncIterable<string>`. All tool use and verification completes before the first token is yielded, so callers always receive a clean, final response.
+
+- **`GoalVerifierResult` interface** (`src/types/agent.ts`): Return type for `goalVerifier` callbacks and the built-in LLM-based checker. Fields: `achieved: boolean`, `missing?: string` (injected as a follow-up user message when false), `reason?: string` (surfaced in trace events).
+
+- **`SessionConfig.goalVerifier`**: Optional user-supplied async callback `(goal: Goal, turns: Turn[]) => Promise<GoalVerifierResult> | GoalVerifierResult`. Called after the ReAct loop reaches a `stop` finish reason when `enableGoalPlanning` is `true`. Returning `{ achieved: false, missing: '...' }` injects a silent correction loop (capped at one retry). When omitted and `successCriteria` is non-empty, Lemura falls back to a built-in LLM check.
+
+- **`SessionConfig.enableGoalVerification`**: Boolean flag to opt out of post-run goal verification. Defaults to `true` when `enableGoalPlanning` is set. Set to `false` to skip the verifier step entirely without removing `enableGoalPlanning`.
+
+- **`SessionManager._executeLoop()`**: Internal refactor — `run()` and `stream()` now share a single `_executeLoop()` core that handles tool dispatch, goal injection, step budgets, and verification. Only the final-response step differs between the two public methods.
+
+- **`GoalVerification.test.ts`**: Unit tests covering the `goalVerifier` callback path, the built-in LLM verifier fallback, and the `enableGoalVerification: false` opt-out.
+
+## [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/README.md

@@ -86,6 +86,11 @@ async function main() {
 
   const response = await session.run('What is lemura?');
   console.log(response);
+
+  // Or stream the final response token-by-token
+  for await (const token of session.stream('What is lemura?')) {
+    process.stdout.write(token);
+  }
 }
 
 main();

package/dist/adapters/index.d.mts

@@ -1,4 +1,4 @@
-import { a as IProviderAdapter, l as CompletionRequest, m as CompletionResponse, k as CompletionChunk, M as ModelInfo, T as TranscriptionRequest, d as TranscriptionResponse, e as SynthesisRequest, A as AudioChunk, V as VisionRequest, f as VisionResponse, g as ImageGenRequest, h as ImageGenResponse } from '../adapters-BhTAnrOM.mjs';
+import { a as IProviderAdapter, l as CompletionRequest, m as CompletionResponse, k as CompletionChunk, M as ModelInfo, d as TranscriptionRequest, e as TranscriptionResponse, f as SynthesisRequest, A as AudioChunk, V as VisionRequest, g as VisionResponse, h as ImageGenRequest, i as ImageGenResponse } from '../adapters-S96Ka9wt.mjs';
 import '../rag-La_Bo-J8.mjs';
 import '../logger-DxvKliuk.mjs';
 

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { a as IProviderAdapter, l as CompletionRequest, m as CompletionResponse, k as CompletionChunk, M as ModelInfo, T as TranscriptionRequest, d as TranscriptionResponse, e as SynthesisRequest, A as AudioChunk, V as VisionRequest, f as VisionResponse, g as ImageGenRequest, h as ImageGenResponse } from '../adapters-CVcfWf85.js';
+import { a as IProviderAdapter, l as CompletionRequest, m as CompletionResponse, k as CompletionChunk, M as ModelInfo, d as TranscriptionRequest, e as TranscriptionResponse, f as SynthesisRequest, A as AudioChunk, V as VisionRequest, g as VisionResponse, h as ImageGenRequest, i as ImageGenResponse } from '../adapters-DHQOGl8Y.js';
 import '../rag-La_Bo-J8.js';
 import '../logger-DxvKliuk.js';
 

package/dist/{adapters-CVcfWf85.d.ts → adapters-DHQOGl8Y.d.ts}

@@ -363,4 +363,4 @@ interface IProviderAdapter {
     healthCheck(): Promise<boolean>;
 }
 
-export { type AudioChunk as A, type ContextWindow as C, type IToolDefinition as I, type ModelInfo as M, type NormalizedMessage as N, ShortTermMemoryRegistry as S, type TranscriptionRequest as T, type VisionRequest as V, type IProviderAdapter as a, type IContextStrategy as b, type IScratchpadAdapter as c, type TranscriptionResponse as d, type SynthesisRequest as e, type VisionResponse as f, type ImageGenRequest as g, type ImageGenResponse as h, type Turn as i, type ContentBlock as j, type CompletionChunk as k, type CompletionRequest as l, type CompletionResponse as m, type IStorageAdapter as n, type STMItem as o, type STMRegistryConfig as p, type TokenUsage as q, type ToolCall as r, type ToolContext as s, type ToolResult as t };
+export { type AudioChunk as A, type ContextWindow as C, type IToolDefinition as I, type ModelInfo as M, type NormalizedMessage as N, ShortTermMemoryRegistry as S, type Turn as T, type VisionRequest as V, type IProviderAdapter as a, type IContextStrategy as b, type IScratchpadAdapter as c, type TranscriptionRequest as d, type TranscriptionResponse as e, type SynthesisRequest as f, type VisionResponse as g, type ImageGenRequest as h, type ImageGenResponse as i, type ContentBlock as j, type CompletionChunk as k, type CompletionRequest as l, type CompletionResponse as m, type IStorageAdapter as n, type STMItem as o, type STMRegistryConfig as p, type TokenUsage as q, type ToolCall as r, type ToolContext as s, type ToolResult as t };

package/dist/{adapters-BhTAnrOM.d.mts → adapters-S96Ka9wt.d.mts}

@@ -363,4 +363,4 @@ interface IProviderAdapter {
     healthCheck(): Promise<boolean>;
 }
 
-export { type AudioChunk as A, type ContextWindow as C, type IToolDefinition as I, type ModelInfo as M, type NormalizedMessage as N, ShortTermMemoryRegistry as S, type TranscriptionRequest as T, type VisionRequest as V, type IProviderAdapter as a, type IContextStrategy as b, type IScratchpadAdapter as c, type TranscriptionResponse as d, type SynthesisRequest as e, type VisionResponse as f, type ImageGenRequest as g, type ImageGenResponse as h, type Turn as i, type ContentBlock as j, type CompletionChunk as k, type CompletionRequest as l, type CompletionResponse as m, type IStorageAdapter as n, type STMItem as o, type STMRegistryConfig as p, type TokenUsage as q, type ToolCall as r, type ToolContext as s, type ToolResult as t };
+export { type AudioChunk as A, type ContextWindow as C, type IToolDefinition as I, type ModelInfo as M, type NormalizedMessage as N, ShortTermMemoryRegistry as S, type Turn as T, type VisionRequest as V, type IProviderAdapter as a, type IContextStrategy as b, type IScratchpadAdapter as c, type TranscriptionRequest as d, type TranscriptionResponse as e, type SynthesisRequest as f, type VisionResponse as g, type ImageGenRequest as h, type ImageGenResponse as i, type ContentBlock as j, type CompletionChunk as k, type CompletionRequest as l, type CompletionResponse as m, type IStorageAdapter as n, type STMItem as o, type STMRegistryConfig as p, type TokenUsage as q, type ToolCall as r, type ToolContext as s, type ToolResult as t };

package/dist/{agent-DfN5nNXc.d.mts → agent-BefjpRHZ.d.mts}

@@ -1,4 +1,4 @@
-import { I as IToolDefinition, a as IProviderAdapter, b as IContextStrategy, S as ShortTermMemoryRegistry, c as IScratchpadAdapter } from './adapters-BhTAnrOM.mjs';
+import { I as IToolDefinition, a as IProviderAdapter, b as IContextStrategy, S as ShortTermMemoryRegistry, c as IScratchpadAdapter, T as Turn } from './adapters-S96Ka9wt.mjs';
 import { I as ILogger } from './logger-DxvKliuk.mjs';
 import { I as ISkill } from './skills-Y6D7zSSw.mjs';
 import { I as IRAGAdapter } from './rag-La_Bo-J8.mjs';
@@ -102,6 +102,67 @@ interface MCPJsonRpcResponse {
     };
 }
 
+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;
+}
+
 interface ToolResponseEvaluation {
     relevanceScore: number;
     sizeClass: 'small' | 'medium' | 'large' | 'oversized';
@@ -160,6 +221,22 @@ interface ToolExecutionBudget {
     /** Maximum simultaneous parallel tool executions (default: unlimited) */
     maxConcurrentCalls?: number;
 }
+/**
+ * Result returned by a `goalVerifier` callback or the built-in `successCriteria` checker.
+ *
+ * @since 1.5.0
+ */
+interface GoalVerifierResult {
+    /** Whether the original goal was fully achieved */
+    achieved: boolean;
+    /**
+     * When `achieved` is false, describes what is still missing.
+     * This text is injected as a follow-up user message to continue the loop.
+     */
+    missing?: string;
+    /** Short human-readable reason for the verdict — surfaced in trace events */
+    reason?: string;
+}
 /** Configuration for a lemura Session */
 interface SessionConfig {
     /** The provider adapter to use */
@@ -215,13 +292,20 @@ interface SessionConfig {
     continuationStrategy?: 'sequential' | 'parallel' | 'conditional';
     /** Enable goal planning */
     enableGoalPlanning?: boolean;
+    /**
+     * Enable post-run goal verification (Option A + C).
+     * When true, Lemura checks whether the goal was actually achieved after each stop.
+     * Requires `enableGoalPlanning` to also be true. Defaults to true.
+     * @since 1.5.0
+     */
+    enableGoalVerification?: boolean;
     goalInjectionFrequency?: 'always' | 'every_N_turns' | 'on_compression';
     goalInjectionPosition?: 'system_prompt' | 'pre_turn';
     /** Skill budget — max tokens the skill injection block may consume */
     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;
@@ -255,6 +339,27 @@ interface SessionConfig {
     toolRegistryTimeoutMs?: number;
     /** Callback for granular trace events (planning, budgets, tools, etc.) */
     onTrace?: (event: TraceEvent) => void;
+    /**
+     * Optional callback invoked after the ReAct loop reaches a `stop` finish reason.
+     *
+     * Return `{ achieved: false, missing: '...' }` to continue the loop with the
+     * missing work injected as a follow-up user message (capped at one retry).
+     * Return `{ achieved: true }` to stop normally.
+     *
+     * Only called when `enableGoalPlanning` is `true` and a goal statement exists.
+     * When omitted and `successCriteria` is non-empty, Lemura falls back to a
+     * built-in LLM-based check against those criteria.
+     *
+     * @since 1.5.0
+     * @example
+     * goalVerifier: async (goal, turns) => {
+     *   const last = turns.at(-1)?.content ?? '';
+     *   return last.includes('DONE')
+     *     ? { achieved: true }
+     *     : { achieved: false, missing: 'Final DONE marker not found in output' };
+     * }
+     */
+    goalVerifier?: (goal: Goal, turns: Turn[]) => Promise<GoalVerifierResult> | GoalVerifierResult;
     /**
      * MCP (Model Context Protocol) server configurations.
      * Each server is connected at session construction, its tools are discovered
@@ -271,7 +376,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;
@@ -281,4 +386,4 @@ interface TraceEvent {
     metadata?: Record<string, any>;
 }
 
-export type { IToolResponseProcessor as I, MCPServerConfig as M, SessionConfig as S, ToolResponseEvaluation as T, MCPToolDefinition as a, MCPJsonRpcRequest as b, MCPJsonRpcResponse as c, MCPTransportType as d, MediaConfig as e, ToolDecision as f, ToolExecutionBudget as g, ToolFirewallConfig as h, ToolFirewallRule as i, TraceEvent as j };
+export { type Goal as G, type IToolResponseProcessor as I, type MCPServerConfig as M, type SessionConfig as S, type ToolResponseEvaluation as T, type MCPToolDefinition as a, GoalInjector as b, type GoalVerifierResult as c, type MCPJsonRpcRequest as d, type MCPJsonRpcResponse as e, type MCPTransportType as f, type MediaConfig as g, type ToolDecision as h, type ToolExecutionBudget as i, type ToolFirewallConfig as j, type ToolFirewallRule as k, type TraceEvent as l };

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

@@ -1,4 +1,4 @@
-import { I as IToolDefinition, a as IProviderAdapter, b as IContextStrategy, S as ShortTermMemoryRegistry, c as IScratchpadAdapter } from './adapters-CVcfWf85.js';
+import { I as IToolDefinition, a as IProviderAdapter, b as IContextStrategy, S as ShortTermMemoryRegistry, c as IScratchpadAdapter, T as Turn } from './adapters-DHQOGl8Y.js';
 import { I as ILogger } from './logger-DxvKliuk.js';
 import { I as ISkill } from './skills-Y6D7zSSw.js';
 import { I as IRAGAdapter } from './rag-La_Bo-J8.js';
@@ -102,6 +102,67 @@ interface MCPJsonRpcResponse {
     };
 }
 
+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;
+}
+
 interface ToolResponseEvaluation {
     relevanceScore: number;
     sizeClass: 'small' | 'medium' | 'large' | 'oversized';
@@ -160,6 +221,22 @@ interface ToolExecutionBudget {
     /** Maximum simultaneous parallel tool executions (default: unlimited) */
     maxConcurrentCalls?: number;
 }
+/**
+ * Result returned by a `goalVerifier` callback or the built-in `successCriteria` checker.
+ *
+ * @since 1.5.0
+ */
+interface GoalVerifierResult {
+    /** Whether the original goal was fully achieved */
+    achieved: boolean;
+    /**
+     * When `achieved` is false, describes what is still missing.
+     * This text is injected as a follow-up user message to continue the loop.
+     */
+    missing?: string;
+    /** Short human-readable reason for the verdict — surfaced in trace events */
+    reason?: string;
+}
 /** Configuration for a lemura Session */
 interface SessionConfig {
     /** The provider adapter to use */
@@ -215,13 +292,20 @@ interface SessionConfig {
     continuationStrategy?: 'sequential' | 'parallel' | 'conditional';
     /** Enable goal planning */
     enableGoalPlanning?: boolean;
+    /**
+     * Enable post-run goal verification (Option A + C).
+     * When true, Lemura checks whether the goal was actually achieved after each stop.
+     * Requires `enableGoalPlanning` to also be true. Defaults to true.
+     * @since 1.5.0
+     */
+    enableGoalVerification?: boolean;
     goalInjectionFrequency?: 'always' | 'every_N_turns' | 'on_compression';
     goalInjectionPosition?: 'system_prompt' | 'pre_turn';
     /** Skill budget — max tokens the skill injection block may consume */
     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;
@@ -255,6 +339,27 @@ interface SessionConfig {
     toolRegistryTimeoutMs?: number;
     /** Callback for granular trace events (planning, budgets, tools, etc.) */
     onTrace?: (event: TraceEvent) => void;
+    /**
+     * Optional callback invoked after the ReAct loop reaches a `stop` finish reason.
+     *
+     * Return `{ achieved: false, missing: '...' }` to continue the loop with the
+     * missing work injected as a follow-up user message (capped at one retry).
+     * Return `{ achieved: true }` to stop normally.
+     *
+     * Only called when `enableGoalPlanning` is `true` and a goal statement exists.
+     * When omitted and `successCriteria` is non-empty, Lemura falls back to a
+     * built-in LLM-based check against those criteria.
+     *
+     * @since 1.5.0
+     * @example
+     * goalVerifier: async (goal, turns) => {
+     *   const last = turns.at(-1)?.content ?? '';
+     *   return last.includes('DONE')
+     *     ? { achieved: true }
+     *     : { achieved: false, missing: 'Final DONE marker not found in output' };
+     * }
+     */
+    goalVerifier?: (goal: Goal, turns: Turn[]) => Promise<GoalVerifierResult> | GoalVerifierResult;
     /**
      * MCP (Model Context Protocol) server configurations.
      * Each server is connected at session construction, its tools are discovered
@@ -271,7 +376,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;
@@ -281,4 +386,4 @@ interface TraceEvent {
     metadata?: Record<string, any>;
 }
 
-export type { IToolResponseProcessor as I, MCPServerConfig as M, SessionConfig as S, ToolResponseEvaluation as T, MCPToolDefinition as a, MCPJsonRpcRequest as b, MCPJsonRpcResponse as c, MCPTransportType as d, MediaConfig as e, ToolDecision as f, ToolExecutionBudget as g, ToolFirewallConfig as h, ToolFirewallRule as i, TraceEvent as j };
+export { type Goal as G, type IToolResponseProcessor as I, type MCPServerConfig as M, type SessionConfig as S, type ToolResponseEvaluation as T, type MCPToolDefinition as a, GoalInjector as b, type GoalVerifierResult as c, type MCPJsonRpcRequest as d, type MCPJsonRpcResponse as e, type MCPTransportType as f, type MediaConfig as g, type ToolDecision as h, type ToolExecutionBudget as i, type ToolFirewallConfig as j, type ToolFirewallRule as k, type TraceEvent as l };

package/dist/context/index.d.mts

@@ -1,5 +1,5 @@
-import { b as IContextStrategy, C as ContextWindow, a as IProviderAdapter, n as IStorageAdapter, c as IScratchpadAdapter } from '../adapters-BhTAnrOM.mjs';
-export { p as STMRegistryConfig, S as ShortTermMemoryRegistry } from '../adapters-BhTAnrOM.mjs';
+import { b as IContextStrategy, C as ContextWindow, a as IProviderAdapter, n as IStorageAdapter, c as IScratchpadAdapter } from '../adapters-S96Ka9wt.mjs';
+export { p as STMRegistryConfig, S as ShortTermMemoryRegistry } from '../adapters-S96Ka9wt.mjs';
 import '../rag-La_Bo-J8.mjs';
 import '../logger-DxvKliuk.mjs';
 

package/dist/context/index.d.ts

@@ -1,5 +1,5 @@
-import { b as IContextStrategy, C as ContextWindow, a as IProviderAdapter, n as IStorageAdapter, c as IScratchpadAdapter } from '../adapters-CVcfWf85.js';
-export { p as STMRegistryConfig, S as ShortTermMemoryRegistry } from '../adapters-CVcfWf85.js';
+import { b as IContextStrategy, C as ContextWindow, a as IProviderAdapter, n as IStorageAdapter, c as IScratchpadAdapter } from '../adapters-DHQOGl8Y.js';
+export { p as STMRegistryConfig, S as ShortTermMemoryRegistry } from '../adapters-DHQOGl8Y.js';
 import '../rag-La_Bo-J8.js';
 import '../logger-DxvKliuk.js';