lemura 1.5.4 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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.6.0] - 2026-06-05
+
+### Added
+
+- **MetaRouter — per-turn intent classification + tool narrowing** (`SessionConfig.enableRouting`): An optional router runs once at the start of each turn, before the ReAct loop, to (1) classify the message as `chat` or `task`, and (2) select which tool categories are relevant. Tools whose `category` is not selected are hidden from the model for that turn — fewer, more relevant tools means less confusion and lower token cost. A `chat` verdict also suppresses goal planning and verification for that turn. Off by default; when disabled, all tools are exposed exactly as before (fully backward-compatible).
+- **`IRouterAdapter` interface** (`src/types/agent.ts`): `route(userMessage, availableCategories) => RouterDecision`. Supply a custom router via `SessionConfig.router`, or use the built-in `LLMRouter`. Implementations should fail safe — return `{ mode: 'task', categories: <all> }` on error so the agent never loses tool access.
+- **`LLMRouter`** (`src/agent/execution/Router.ts`): Built-in router. Single temperature-0 LLM classification call, a conversational fast-path that skips the LLM for greetings/acknowledgements, and a fail-safe fallback to all categories on any parse/LLM error. Hallucinated categories not in the offered set are dropped.
+- **`RouterDecision` / `ToolCategoryInfo` interfaces** (`src/types/agent.ts`): `RouterDecision` = `{ mode: 'chat' | 'task'; categories: string[]; reason?: string }`. `ToolCategoryInfo` = `{ name: string; tools: string[] }`, passed to the router so it knows what each category contains.
+- **`IToolDefinition.category?: string`**: Optional category tag used by the router to group tools. Open string — lemura does not own a fixed catalog. Uncategorized tools are never filtered out (treated as always available).
+- **`SessionConfig.router`**: Custom `IRouterAdapter`. Takes precedence over the built-in router when `enableRouting` is true.
+- **`SessionConfig.routerModel`**: Model used by the built-in router. Defaults to `config.model` — point this at a small/cheap model for fast classification.
+- **`SessionConfig.alwaysAvailableCategories?: string[]`**: Categories always exposed regardless of the router decision (e.g. a scratchpad category).
+- **`TraceEvent.type: 'routing'`**: New trace type. Emitted as `route_decision` with `mode`, `categories`, and `reason`.
+- **`Router.test.ts`**: Unit tests covering tool narrowing, always-available categories, the routing-disabled default, the no-categorized-tools fallback, and the built-in `LLMRouter` (fast-path, hallucinated-category dropping, fail-safe).
+
+## [1.5.5] - 2026-06-01
+
+### Fixed
+
+- **Duplicated response in `stream()` during goal correction** (significant): `stream()` yielded the model's first answer to the caller *live*, then ran goal verification *afterwards*. When the verifier returned `achieved: false` and a correction re-entry followed, the corrected answer was streamed immediately after the already-emitted first answer — surfacing both as one duplicated response (contradicting the documented "delivers only the clean final response" contract). The final response is now **buffered** until verification settles; a rejected attempt is silently discarded and corrected, so the stream emits only the single approved answer. `run()` was unaffected (it already buffered).
+
 ## [1.5.4] - 2026-05-30
 
 ### Fixed

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, 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-DAzmrg4l.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-BN6und82.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, 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-CIRkrCHl.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-CnsgefYR.js';
 import '../rag-La_Bo-J8.js';
 import '../logger-DxvKliuk.js';
 

package/dist/{adapters-DAzmrg4l.d.mts → adapters-BN6und82.d.mts}

@@ -151,6 +151,15 @@ interface IToolDefinition {
     parameters: Record<string, unknown>;
     /** Per-call timeout in milliseconds. Falls back to ToolRegistry.defaultTimeoutMs when omitted. */
     timeoutMs?: number;
+    /**
+     * Optional category used by the router (see `SessionConfig.enableRouting`) to
+     * narrow which tools are exposed to the model on a given turn. Open string —
+     * lemura does not own a fixed catalog. Tools left uncategorized are never
+     * filtered out (treated as always available).
+     *
+     * @since 1.6.0
+     */
+    category?: string;
     execute(params: unknown, context: ToolContext): Promise<unknown>;
 }
 

package/dist/{adapters-CIRkrCHl.d.ts → adapters-CnsgefYR.d.ts}

@@ -151,6 +151,15 @@ interface IToolDefinition {
     parameters: Record<string, unknown>;
     /** Per-call timeout in milliseconds. Falls back to ToolRegistry.defaultTimeoutMs when omitted. */
     timeoutMs?: number;
+    /**
+     * Optional category used by the router (see `SessionConfig.enableRouting`) to
+     * narrow which tools are exposed to the model on a given turn. Open string —
+     * lemura does not own a fixed catalog. Tools left uncategorized are never
+     * filtered out (treated as always available).
+     *
+     * @since 1.6.0
+     */
+    category?: string;
     execute(params: unknown, context: ToolContext): Promise<unknown>;
 }
 

package/dist/{agent-UBaqufhp.d.mts → agent-B2okLlzq.d.mts}

@@ -1,4 +1,4 @@
-import { I as IToolDefinition, a as IProviderAdapter, b as IContextStrategy, S as ShortTermMemoryRegistry, c as IScratchpadAdapter, T as Turn } from './adapters-DAzmrg4l.mjs';
+import { I as IToolDefinition, a as IProviderAdapter, b as IContextStrategy, S as ShortTermMemoryRegistry, c as IScratchpadAdapter, T as Turn } from './adapters-BN6und82.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';
@@ -242,6 +242,55 @@ interface GoalVerifierResult {
     /** Short human-readable reason for the verdict — surfaced in trace events */
     reason?: string;
 }
+/**
+ * Lightweight description of a tool category, passed to a router so it can
+ * decide which categories are relevant to the current user message.
+ *
+ * @since 1.6.0
+ */
+interface ToolCategoryInfo {
+    /** The category name (matches `IToolDefinition.category`). */
+    name: string;
+    /** Names of the tools belonging to this category — gives the router context. */
+    tools: string[];
+}
+/**
+ * Verdict returned by a router for a single user turn.
+ *
+ * @since 1.6.0
+ */
+interface RouterDecision {
+    /**
+     * `'chat'` marks a purely conversational turn — the consumer/loop should
+     * skip the heavy pipeline (no tool exposure beyond always-available
+     * categories, and goal planning/verification suppressed for this turn).
+     * `'task'` runs the full pipeline.
+     */
+    mode: 'chat' | 'task';
+    /**
+     * Tool categories selected as relevant. Empty implies no categorized tools
+     * are exposed (typical for `mode: 'chat'`). Always-available categories
+     * (see `SessionConfig.alwaysAvailableCategories`) and uncategorized tools
+     * are exposed regardless of this list.
+     */
+    categories: string[];
+    /** Short human-readable reason — surfaced in trace events. */
+    reason?: string;
+}
+/**
+ * Pluggable router. Maps a user message to a {@link RouterDecision} that
+ * narrows the tool surface for the turn. Supply your own, or enable the
+ * built-in LLM router via `SessionConfig.enableRouting`.
+ *
+ * Implementations should **fail safe**: on any internal error, return
+ * `{ mode: 'task', categories: <all categories> }` so the agent never loses
+ * access to tools because routing hiccupped.
+ *
+ * @since 1.6.0
+ */
+interface IRouterAdapter {
+    route(userMessage: string, availableCategories: ToolCategoryInfo[]): Promise<RouterDecision> | RouterDecision;
+}
 /** Configuration for a lemura Session */
 interface SessionConfig {
     /** The provider adapter to use */
@@ -403,11 +452,47 @@ interface SessionConfig {
      * ]
      */
     mcpServers?: MCPServerConfig[];
+    /**
+     * When true, a router runs once at the start of each turn (before the ReAct
+     * loop) to classify the message (`chat`/`task`) and select relevant tool
+     * categories. Tools whose `category` is not selected are hidden from the
+     * model for that turn — fewer, more relevant tools means less confusion and
+     * lower token cost. A `chat` verdict also suppresses goal planning and
+     * verification for that turn.
+     *
+     * If `router` is supplied it is used; otherwise lemura's built-in
+     * {@link LLMRouter} is used. Defaults to false (no routing — all tools
+     * always exposed, identical to pre-1.6.0 behavior).
+     *
+     * @since 1.6.0
+     */
+    enableRouting?: boolean;
+    /**
+     * Custom router implementation. Takes precedence over the built-in router
+     * when `enableRouting` is true.
+     *
+     * @since 1.6.0
+     */
+    router?: IRouterAdapter;
+    /**
+     * Model used by the built-in router. Defaults to `config.model`. Point this
+     * at a small/cheap model for fast, low-cost classification.
+     *
+     * @since 1.6.0
+     */
+    routerModel?: string;
+    /**
+     * Categories that are always exposed regardless of the router decision
+     * (e.g. a scratchpad category). Uncategorized tools are also always exposed.
+     *
+     * @since 1.6.0
+     */
+    alwaysAvailableCategories?: string[];
 }
 /** Rich trace event for observability */
 interface TraceEvent {
     sessionId?: string;
-    type: 'planning' | 'budget' | 'tool_call' | 'tool_result' | 'thinking' | 'system' | 'compression' | 'error' | 'skill' | 'verification';
+    type: 'planning' | 'budget' | 'tool_call' | 'tool_result' | 'thinking' | 'system' | 'compression' | 'error' | 'skill' | 'verification' | 'routing';
     name: string;
     input?: any;
     output?: any;
@@ -417,4 +502,4 @@ interface TraceEvent {
     metadata?: Record<string, any>;
 }
 
-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 };
+export { type Goal as G, type IToolResponseProcessor as I, type MCPServerConfig as M, type RouterDecision as R, type SessionConfig as S, type ToolResponseEvaluation as T, type IRouterAdapter as a, type ToolCategoryInfo as b, type MCPToolDefinition as c, GoalInjector as d, type GoalVerifierResult as e, type MCPJsonRpcRequest as f, type MCPJsonRpcResponse as g, type MCPTransportType as h, type MediaConfig as i, type ToolDecision as j, type ToolExecutionBudget as k, type ToolFirewallConfig as l, type ToolFirewallRule as m, type TraceEvent as n };

package/dist/{agent-CknicweT.d.ts → agent-BppqfsIZ.d.ts}

@@ -1,4 +1,4 @@
-import { I as IToolDefinition, a as IProviderAdapter, b as IContextStrategy, S as ShortTermMemoryRegistry, c as IScratchpadAdapter, T as Turn } from './adapters-CIRkrCHl.js';
+import { I as IToolDefinition, a as IProviderAdapter, b as IContextStrategy, S as ShortTermMemoryRegistry, c as IScratchpadAdapter, T as Turn } from './adapters-CnsgefYR.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';
@@ -242,6 +242,55 @@ interface GoalVerifierResult {
     /** Short human-readable reason for the verdict — surfaced in trace events */
     reason?: string;
 }
+/**
+ * Lightweight description of a tool category, passed to a router so it can
+ * decide which categories are relevant to the current user message.
+ *
+ * @since 1.6.0
+ */
+interface ToolCategoryInfo {
+    /** The category name (matches `IToolDefinition.category`). */
+    name: string;
+    /** Names of the tools belonging to this category — gives the router context. */
+    tools: string[];
+}
+/**
+ * Verdict returned by a router for a single user turn.
+ *
+ * @since 1.6.0
+ */
+interface RouterDecision {
+    /**
+     * `'chat'` marks a purely conversational turn — the consumer/loop should
+     * skip the heavy pipeline (no tool exposure beyond always-available
+     * categories, and goal planning/verification suppressed for this turn).
+     * `'task'` runs the full pipeline.
+     */
+    mode: 'chat' | 'task';
+    /**
+     * Tool categories selected as relevant. Empty implies no categorized tools
+     * are exposed (typical for `mode: 'chat'`). Always-available categories
+     * (see `SessionConfig.alwaysAvailableCategories`) and uncategorized tools
+     * are exposed regardless of this list.
+     */
+    categories: string[];
+    /** Short human-readable reason — surfaced in trace events. */
+    reason?: string;
+}
+/**
+ * Pluggable router. Maps a user message to a {@link RouterDecision} that
+ * narrows the tool surface for the turn. Supply your own, or enable the
+ * built-in LLM router via `SessionConfig.enableRouting`.
+ *
+ * Implementations should **fail safe**: on any internal error, return
+ * `{ mode: 'task', categories: <all categories> }` so the agent never loses
+ * access to tools because routing hiccupped.
+ *
+ * @since 1.6.0
+ */
+interface IRouterAdapter {
+    route(userMessage: string, availableCategories: ToolCategoryInfo[]): Promise<RouterDecision> | RouterDecision;
+}
 /** Configuration for a lemura Session */
 interface SessionConfig {
     /** The provider adapter to use */
@@ -403,11 +452,47 @@ interface SessionConfig {
      * ]
      */
     mcpServers?: MCPServerConfig[];
+    /**
+     * When true, a router runs once at the start of each turn (before the ReAct
+     * loop) to classify the message (`chat`/`task`) and select relevant tool
+     * categories. Tools whose `category` is not selected are hidden from the
+     * model for that turn — fewer, more relevant tools means less confusion and
+     * lower token cost. A `chat` verdict also suppresses goal planning and
+     * verification for that turn.
+     *
+     * If `router` is supplied it is used; otherwise lemura's built-in
+     * {@link LLMRouter} is used. Defaults to false (no routing — all tools
+     * always exposed, identical to pre-1.6.0 behavior).
+     *
+     * @since 1.6.0
+     */
+    enableRouting?: boolean;
+    /**
+     * Custom router implementation. Takes precedence over the built-in router
+     * when `enableRouting` is true.
+     *
+     * @since 1.6.0
+     */
+    router?: IRouterAdapter;
+    /**
+     * Model used by the built-in router. Defaults to `config.model`. Point this
+     * at a small/cheap model for fast, low-cost classification.
+     *
+     * @since 1.6.0
+     */
+    routerModel?: string;
+    /**
+     * Categories that are always exposed regardless of the router decision
+     * (e.g. a scratchpad category). Uncategorized tools are also always exposed.
+     *
+     * @since 1.6.0
+     */
+    alwaysAvailableCategories?: string[];
 }
 /** Rich trace event for observability */
 interface TraceEvent {
     sessionId?: string;
-    type: 'planning' | 'budget' | 'tool_call' | 'tool_result' | 'thinking' | 'system' | 'compression' | 'error' | 'skill' | 'verification';
+    type: 'planning' | 'budget' | 'tool_call' | 'tool_result' | 'thinking' | 'system' | 'compression' | 'error' | 'skill' | 'verification' | 'routing';
     name: string;
     input?: any;
     output?: any;
@@ -417,4 +502,4 @@ interface TraceEvent {
     metadata?: Record<string, any>;
 }
 
-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 };
+export { type Goal as G, type IToolResponseProcessor as I, type MCPServerConfig as M, type RouterDecision as R, type SessionConfig as S, type ToolResponseEvaluation as T, type IRouterAdapter as a, type ToolCategoryInfo as b, type MCPToolDefinition as c, GoalInjector as d, type GoalVerifierResult as e, type MCPJsonRpcRequest as f, type MCPJsonRpcResponse as g, type MCPTransportType as h, type MediaConfig as i, type ToolDecision as j, type ToolExecutionBudget as k, type ToolFirewallConfig as l, type ToolFirewallRule as m, type TraceEvent as n };

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-DAzmrg4l.mjs';
-export { p as STMRegistryConfig, S as ShortTermMemoryRegistry } from '../adapters-DAzmrg4l.mjs';
+import { b as IContextStrategy, C as ContextWindow, a as IProviderAdapter, n as IStorageAdapter, c as IScratchpadAdapter } from '../adapters-BN6und82.mjs';
+export { p as STMRegistryConfig, S as ShortTermMemoryRegistry } from '../adapters-BN6und82.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-CIRkrCHl.js';
-export { p as STMRegistryConfig, S as ShortTermMemoryRegistry } from '../adapters-CIRkrCHl.js';
+import { b as IContextStrategy, C as ContextWindow, a as IProviderAdapter, n as IStorageAdapter, c as IScratchpadAdapter } from '../adapters-CnsgefYR.js';
+export { p as STMRegistryConfig, S as ShortTermMemoryRegistry } from '../adapters-CnsgefYR.js';
 import '../rag-La_Bo-J8.js';
 import '../logger-DxvKliuk.js';
 

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { a as IProviderAdapter, d as TranscriptionRequest, e as TranscriptionResponse, f as SynthesisRequest, A as AudioChunk, V as VisionRequest, g as VisionResponse, h as ImageGenRequest, i as ImageGenResponse, M as ModelInfo, C as ContextWindow, T as Turn, j as ContentBlock, I as IToolDefinition } from './adapters-DAzmrg4l.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-DAzmrg4l.mjs';
-import { S as SessionConfig, G as Goal, I as IToolResponseProcessor, T as ToolResponseEvaluation, M as MCPServerConfig, a as MCPToolDefinition } from './agent-UBaqufhp.mjs';
-export { b as GoalInjector, c as GoalVerifierResult, d as MCPJsonRpcRequest, e as MCPJsonRpcResponse, f as MCPTransportType, g as MediaConfig, h as ToolDecision, i as ToolExecutionBudget, j as ToolFirewallConfig, k as ToolFirewallRule, l as TraceEvent } from './agent-UBaqufhp.mjs';
+import { a as IProviderAdapter, d as TranscriptionRequest, e as TranscriptionResponse, f as SynthesisRequest, A as AudioChunk, V as VisionRequest, g as VisionResponse, h as ImageGenRequest, i as ImageGenResponse, M as ModelInfo, C as ContextWindow, T as Turn, j as ContentBlock, I as IToolDefinition } from './adapters-BN6und82.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-BN6und82.mjs';
+import { S as SessionConfig, G as Goal, I as IToolResponseProcessor, T as ToolResponseEvaluation, a as IRouterAdapter, b as ToolCategoryInfo, R as RouterDecision, M as MCPServerConfig, c as MCPToolDefinition } from './agent-B2okLlzq.mjs';
+export { d as GoalInjector, e as GoalVerifierResult, f as MCPJsonRpcRequest, g as MCPJsonRpcResponse, h as MCPTransportType, i as MediaConfig, j as ToolDecision, k as ToolExecutionBudget, l as ToolFirewallConfig, m as ToolFirewallRule, n as TraceEvent } from './agent-B2okLlzq.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';
@@ -226,6 +226,14 @@ declare class SessionManager {
     private toolResponseProcessor;
     private goalInjector;
     private continuationPlanner;
+    private router;
+    /**
+     * Tool categories selected by the router for the current turn, or `null` when
+     * routing is disabled / not yet run. When non-null, only tools whose
+     * `category` is in this set (plus always-available + uncategorized tools) are
+     * exposed to the model.
+     */
+    private routedCategories;
     /** Frozen goal/plan injection text keyed by turn index — used when staticSystemPrompt is on */
     private _turnInjections;
     private mcpRegistry;
@@ -358,6 +366,22 @@ declare class SessionManager {
      * `stream()` await `this.mcpReady` before executing.
      */
     private _initMCP;
+    /** Groups registered tools into {@link ToolCategoryInfo} by their `category`. */
+    private buildToolCategories;
+    /**
+     * Runs the router for the current turn (when enabled) and stores the selected
+     * categories in `this.routedCategories`. Returns the decision so the loop can
+     * suppress goal planning/verification on a `chat` verdict. Fail-safe: on a
+     * null/failed decision, routing is disabled for the turn (all tools exposed).
+     */
+    private _runRoutingStep;
+    /**
+     * Returns the tools to expose this turn, filtered by the router decision.
+     * Always exposes uncategorized tools and tools in always-available /
+     * routed-in categories. When routing is off (`routedCategories === null`),
+     * returns every tool — identical to pre-routing behavior.
+     */
+    private getActiveTools;
     /**
      * 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
@@ -529,6 +553,42 @@ declare class FinalResponseFormatter {
     static validateStructure(response: string): boolean;
 }
 
+/**
+ * Options for the built-in {@link LLMRouter}.
+ *
+ * @since 1.6.0
+ */
+interface LLMRouterOptions {
+    adapter: IProviderAdapter;
+    model: string;
+    logger: ILogger;
+}
+/**
+ * Built-in MetaRouter. Classifies a user message (`chat` vs `task`) and selects
+ * the relevant tool categories with a single temperature-0 LLM call.
+ *
+ * Two cheap guards run before the LLM:
+ *  - **Conversational fast-path**: short greeting/acknowledgement input is
+ *    classified `chat` with no categories and no LLM call.
+ *  - **No categories**: if no categorized tools exist, routing is moot — returns
+ *    `task` with an empty category list (uncategorized tools are always exposed
+ *    by the caller anyway).
+ *
+ * Fails safe: any error returns `{ mode: 'task', categories: <all> }` so the
+ * agent never loses tool access because routing hiccupped.
+ *
+ * @since 1.6.0
+ */
+declare class LLMRouter implements IRouterAdapter {
+    private adapter;
+    private model;
+    private logger;
+    /** Matches purely conversational input — greetings, thanks, acknowledgements. */
+    private static readonly CHAT_FAST_PATH;
+    constructor(opts: LLMRouterOptions);
+    route(userMessage: string, availableCategories: ToolCategoryInfo[]): Promise<RouterDecision>;
+}
+
 /**
  * Low-level MCP server client.
  *
@@ -657,4 +717,4 @@ declare class MCPClientRegistry {
     private _bridge;
 }
 
-export { AudioChunk, ContentBlock, ContextWindow, type ContinuationPlan, ContinuationPlanner, type ContinuationStep, FinalResponseFormatter, Goal, 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 };
+export { AudioChunk, ContentBlock, ContextWindow, type ContinuationPlan, ContinuationPlanner, type ContinuationStep, FinalResponseFormatter, Goal, ILogger, IProviderAdapter, IRouterAdapter, IToolDefinition, IToolResponseProcessor, ImageGenRequest, ImageGenResponse, LLMRouter, type LLMRouterOptions, MCPClient, MCPClientRegistry, MCPServerConfig, MCPToolDefinition, MediaBridge, ModelInfo, RouterDecision, SessionConfig, SessionManager, SkillInjector, type StepCondition, StepCounter, type StepVerifier, type StepVerifierResult, SynthesisRequest, ToolCategoryInfo, ToolRegistry, ToolResponseEvaluation, ToolResponseProcessor, type ToolResponseProcessorConfig, TranscriptionRequest, TranscriptionResponse, Turn, VisionRequest, VisionResponse };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { a as IProviderAdapter, d as TranscriptionRequest, e as TranscriptionResponse, f as SynthesisRequest, A as AudioChunk, V as VisionRequest, g as VisionResponse, h as ImageGenRequest, i as ImageGenResponse, M as ModelInfo, C as ContextWindow, T as Turn, j as ContentBlock, I as IToolDefinition } from './adapters-CIRkrCHl.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-CIRkrCHl.js';
-import { S as SessionConfig, G as Goal, I as IToolResponseProcessor, T as ToolResponseEvaluation, M as MCPServerConfig, a as MCPToolDefinition } from './agent-CknicweT.js';
-export { b as GoalInjector, c as GoalVerifierResult, d as MCPJsonRpcRequest, e as MCPJsonRpcResponse, f as MCPTransportType, g as MediaConfig, h as ToolDecision, i as ToolExecutionBudget, j as ToolFirewallConfig, k as ToolFirewallRule, l as TraceEvent } from './agent-CknicweT.js';
+import { a as IProviderAdapter, d as TranscriptionRequest, e as TranscriptionResponse, f as SynthesisRequest, A as AudioChunk, V as VisionRequest, g as VisionResponse, h as ImageGenRequest, i as ImageGenResponse, M as ModelInfo, C as ContextWindow, T as Turn, j as ContentBlock, I as IToolDefinition } from './adapters-CnsgefYR.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-CnsgefYR.js';
+import { S as SessionConfig, G as Goal, I as IToolResponseProcessor, T as ToolResponseEvaluation, a as IRouterAdapter, b as ToolCategoryInfo, R as RouterDecision, M as MCPServerConfig, c as MCPToolDefinition } from './agent-BppqfsIZ.js';
+export { d as GoalInjector, e as GoalVerifierResult, f as MCPJsonRpcRequest, g as MCPJsonRpcResponse, h as MCPTransportType, i as MediaConfig, j as ToolDecision, k as ToolExecutionBudget, l as ToolFirewallConfig, m as ToolFirewallRule, n as TraceEvent } from './agent-BppqfsIZ.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';
@@ -226,6 +226,14 @@ declare class SessionManager {
     private toolResponseProcessor;
     private goalInjector;
     private continuationPlanner;
+    private router;
+    /**
+     * Tool categories selected by the router for the current turn, or `null` when
+     * routing is disabled / not yet run. When non-null, only tools whose
+     * `category` is in this set (plus always-available + uncategorized tools) are
+     * exposed to the model.
+     */
+    private routedCategories;
     /** Frozen goal/plan injection text keyed by turn index — used when staticSystemPrompt is on */
     private _turnInjections;
     private mcpRegistry;
@@ -358,6 +366,22 @@ declare class SessionManager {
      * `stream()` await `this.mcpReady` before executing.
      */
     private _initMCP;
+    /** Groups registered tools into {@link ToolCategoryInfo} by their `category`. */
+    private buildToolCategories;
+    /**
+     * Runs the router for the current turn (when enabled) and stores the selected
+     * categories in `this.routedCategories`. Returns the decision so the loop can
+     * suppress goal planning/verification on a `chat` verdict. Fail-safe: on a
+     * null/failed decision, routing is disabled for the turn (all tools exposed).
+     */
+    private _runRoutingStep;
+    /**
+     * Returns the tools to expose this turn, filtered by the router decision.
+     * Always exposes uncategorized tools and tools in always-available /
+     * routed-in categories. When routing is off (`routedCategories === null`),
+     * returns every tool — identical to pre-routing behavior.
+     */
+    private getActiveTools;
     /**
      * 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
@@ -529,6 +553,42 @@ declare class FinalResponseFormatter {
     static validateStructure(response: string): boolean;
 }
 
+/**
+ * Options for the built-in {@link LLMRouter}.
+ *
+ * @since 1.6.0
+ */
+interface LLMRouterOptions {
+    adapter: IProviderAdapter;
+    model: string;
+    logger: ILogger;
+}
+/**
+ * Built-in MetaRouter. Classifies a user message (`chat` vs `task`) and selects
+ * the relevant tool categories with a single temperature-0 LLM call.
+ *
+ * Two cheap guards run before the LLM:
+ *  - **Conversational fast-path**: short greeting/acknowledgement input is
+ *    classified `chat` with no categories and no LLM call.
+ *  - **No categories**: if no categorized tools exist, routing is moot — returns
+ *    `task` with an empty category list (uncategorized tools are always exposed
+ *    by the caller anyway).
+ *
+ * Fails safe: any error returns `{ mode: 'task', categories: <all> }` so the
+ * agent never loses tool access because routing hiccupped.
+ *
+ * @since 1.6.0
+ */
+declare class LLMRouter implements IRouterAdapter {
+    private adapter;
+    private model;
+    private logger;
+    /** Matches purely conversational input — greetings, thanks, acknowledgements. */
+    private static readonly CHAT_FAST_PATH;
+    constructor(opts: LLMRouterOptions);
+    route(userMessage: string, availableCategories: ToolCategoryInfo[]): Promise<RouterDecision>;
+}
+
 /**
  * Low-level MCP server client.
  *
@@ -657,4 +717,4 @@ declare class MCPClientRegistry {
     private _bridge;
 }
 
-export { AudioChunk, ContentBlock, ContextWindow, type ContinuationPlan, ContinuationPlanner, type ContinuationStep, FinalResponseFormatter, Goal, 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 };
+export { AudioChunk, ContentBlock, ContextWindow, type ContinuationPlan, ContinuationPlanner, type ContinuationStep, FinalResponseFormatter, Goal, ILogger, IProviderAdapter, IRouterAdapter, IToolDefinition, IToolResponseProcessor, ImageGenRequest, ImageGenResponse, LLMRouter, type LLMRouterOptions, MCPClient, MCPClientRegistry, MCPServerConfig, MCPToolDefinition, MediaBridge, ModelInfo, RouterDecision, SessionConfig, SessionManager, SkillInjector, type StepCondition, StepCounter, type StepVerifier, type StepVerifierResult, SynthesisRequest, ToolCategoryInfo, ToolRegistry, ToolResponseEvaluation, ToolResponseProcessor, type ToolResponseProcessorConfig, TranscriptionRequest, TranscriptionResponse, Turn, VisionRequest, VisionResponse };