lemura 1.5.5 → 1.7.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.7.0] - 2026-06-13
+
+### Added
+
+- **Progressive skills — model-driven skill selection** (`strategy: 'progressive'`): A third skill strategy alongside `fixed` and `dynamic`. The model sees a lightweight catalog (`name: description`) of progressive skills in its system prompt and decides which to pull in by calling a built-in `load_skill` tool; only the chosen skill's full content is then injected. This is the "progressive disclosure" pattern — the host wires nothing, the agent selects its own skills. Fully backward-compatible (default strategy remains `fixed`).
+- **Built-in `load_skill` tool** (`src/tools/builtin/load_skill.ts`, `createLoadSkillTool`): Auto-registered by `SessionManager` whenever a `progressive` skill is present, and auto-trusted by the tool firewall (it only toggles skill injection, no external side effects). The `name` parameter is constrained to the available progressive skills; unknown names and `maxConcurrent` violations return soft errors that keep the ReAct loop going.
+- **`SkillSelectionConfig`** (`SessionConfig.skillSelection`): Tunes progressive selection — `persistence` (`'per_turn'` default, or `'session'`), `maxConcurrent` (cap on simultaneously loaded skills), and `catalogHeader` (override the catalog preamble). Ignored when no progressive skills are present.
+- **`SkillInjector.buildCatalog(header?)`**: Builds the `name: description` catalog block for progressive skills. Plus `resetProgressiveSkills()`, `getProgressiveSkills()`, and `countEnabledProgressive()` helpers. `enableSkill`/`disableSkill`/`enableByTags`/`disableByTags` now operate on both `dynamic` and `progressive` skills.
+- **Full skill-lifecycle tracing**: `skill_load` now fires for **every registered skill** (not just active ones) and carries an `enabled` flag, so inactive `dynamic`/`progressive` skills are visible from session init. New `skill_enable` trace (`{ name, source: 'load_skill' }`) records the model's selection decision when it loads a progressive skill, and new `skill_reset` trace (`{ skills, reason: 'per_turn' }`) records per-turn clearing. `session_init` reports a `progressive` skill count; `skill_inject` fires for both dynamic and progressive injections.
+- **Tests**: `tests/unit/skills/ProgressiveSkills.test.ts` (catalog, activation, `load_skill` tool, `maxConcurrent`) and new `SessionManager` cases (auto-registration, per-turn vs session persistence).
+
+## [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

package/README.md

@@ -25,6 +25,7 @@
 ### ✨ Key Features
 
 - **🧠 Dynamic Skill Market**: Switch skills on/off at runtime via tags, names, or tool dependencies.
+- **📖 Progressive Skills**: Let the agent pick its own skills — it reads a catalog and loads only what's relevant via the built-in `load_skill` tool (`strategy: 'progressive'`).
 - **🔌 Native MCP Support**: Connect to any Model Context Protocol server with custom header support (Auth).
 - **🛡️ Tool Firewall**: Fully integrated ask/accept/deny policy layer for secure tool execution — fail-safe by design.
 - **🎯 Goal Maintenance & Verification**: LLM-powered sub-goal decomposition, progress reconciliation, and post-run goal verification that re-enters the loop with full tool access to finish incomplete answers.

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-CknicweT.d.ts → agent-BcAg3gCz.d.ts}

@@ -1,6 +1,6 @@
-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 ISkill, S as SkillSelectionConfig } from './skills-DWCC0K1B.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 */
@@ -274,6 +323,17 @@ interface SessionConfig {
      * @since 1.4.0
      */
     activeDynamicTags?: string[];
+    /**
+     * Configuration for model-driven (`progressive`) skill selection. When any
+     * skill in `skills` has `strategy: 'progressive'`, Lemura automatically appends
+     * a skill catalog to the system prompt, registers the built-in `load_skill`
+     * tool (auto-trusted by the firewall), and resets progressive skills according
+     * to `persistence`. This object tunes that behaviour; it is ignored when no
+     * progressive skills are present.
+     *
+     * @since 1.7.0
+     */
+    skillSelection?: SkillSelectionConfig;
     /** RAG adapter */
     ragAdapter?: IRAGAdapter;
     /** Context compression strategies */
@@ -403,11 +463,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 +513,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-UBaqufhp.d.mts → agent-Dus44yQd.d.mts}

@@ -1,6 +1,6 @@
-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 ISkill, S as SkillSelectionConfig } from './skills-DWCC0K1B.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 */
@@ -274,6 +323,17 @@ interface SessionConfig {
      * @since 1.4.0
      */
     activeDynamicTags?: string[];
+    /**
+     * Configuration for model-driven (`progressive`) skill selection. When any
+     * skill in `skills` has `strategy: 'progressive'`, Lemura automatically appends
+     * a skill catalog to the system prompt, registers the built-in `load_skill`
+     * tool (auto-trusted by the firewall), and resets progressive skills according
+     * to `persistence`. This object tunes that behaviour; it is ignored when no
+     * progressive skills are present.
+     *
+     * @since 1.7.0
+     */
+    skillSelection?: SkillSelectionConfig;
     /** RAG adapter */
     ragAdapter?: IRAGAdapter;
     /** Context compression strategies */
@@ -403,11 +463,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 +513,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,12 +1,12 @@
-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-Dus44yQd.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-Dus44yQd.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';
 export { I as IRAGAdapter, R as RAGDocument, a as RAGIngestOptions, b as RAGIngestRequest, c as RAGIngestResponse, d as RAGQueryRequest, e as RAGQueryResponse, f as RAGResult } from './rag-La_Bo-J8.mjs';
-export { I as ISkill, S as SkillStrategy } from './skills-Y6D7zSSw.mjs';
+export { I as ISkill, S as SkillSelectionConfig, a as SkillStrategy } from './skills-DWCC0K1B.mjs';
 export { OpenAICompatibleAdapter, OpenAICompatibleAdapterConfig, RetryConfig } from './adapters/index.mjs';
 export { ContextManager, HistoryCompressionConfig, HistoryCompressionStrategy, InMemoryScratchpadAdapter, InMemoryStorageAdapter, SandwichCompressionConfig, SandwichCompressionStrategy, ScratchpadStrategy, SummaryInjectionConfig, SummaryInjectionStrategy } from './context/index.mjs';
 import { ToolRegistry } from './tools/index.mjs';
@@ -213,6 +213,8 @@ declare class SessionManager {
     private contextManager;
     private toolRegistry;
     private skillInjector;
+    /** True when any registered skill uses `strategy: 'progressive'`. */
+    private hasProgressiveSkills;
     private context;
     private adapter;
     private config;
@@ -226,6 +228,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 +368,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
@@ -404,6 +430,13 @@ declare class SessionManager {
      * @throws {LemuraMaxIterationsError} When the loop exceeds `maxIterations`
      */
     run(userMessage: string | ContentBlock[]): Promise<string>;
+    /**
+     * Resets progressive skills at the start of a turn when
+     * `skillSelection.persistence` is `'per_turn'` (the default), so each user
+     * message re-decides which skills to load from the catalog. No-op when
+     * persistence is `'session'` or there are no progressive skills.
+     */
+    private _resetProgressiveSkillsForTurn;
     /**
      * Runs the ReAct loop and streams the final assistant response token-by-token.
      *
@@ -529,6 +562,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 +726,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,12 +1,12 @@
-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-BcAg3gCz.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-BcAg3gCz.js';
 export { LemuraAdapterError, LemuraContextOverflowError, LemuraError, LemuraMCPConnectionError, LemuraMCPError, LemuraMCPTimeoutError, LemuraMaxIterationsError, LemuraSkillInjectionError, LemuraToolNotFoundError, LemuraToolTimeoutError, LemuraToolValidationError } from './types/index.js';
 import { I as ILogger } from './logger-DxvKliuk.js';
 export { L as LogLevel, a as LogMetadata, S as Severity } from './logger-DxvKliuk.js';
 export { I as IRAGAdapter, R as RAGDocument, a as RAGIngestOptions, b as RAGIngestRequest, c as RAGIngestResponse, d as RAGQueryRequest, e as RAGQueryResponse, f as RAGResult } from './rag-La_Bo-J8.js';
-export { I as ISkill, S as SkillStrategy } from './skills-Y6D7zSSw.js';
+export { I as ISkill, S as SkillSelectionConfig, a as SkillStrategy } from './skills-DWCC0K1B.js';
 export { OpenAICompatibleAdapter, OpenAICompatibleAdapterConfig, RetryConfig } from './adapters/index.js';
 export { ContextManager, HistoryCompressionConfig, HistoryCompressionStrategy, InMemoryScratchpadAdapter, InMemoryStorageAdapter, SandwichCompressionConfig, SandwichCompressionStrategy, ScratchpadStrategy, SummaryInjectionConfig, SummaryInjectionStrategy } from './context/index.js';
 import { ToolRegistry } from './tools/index.js';
@@ -213,6 +213,8 @@ declare class SessionManager {
     private contextManager;
     private toolRegistry;
     private skillInjector;
+    /** True when any registered skill uses `strategy: 'progressive'`. */
+    private hasProgressiveSkills;
     private context;
     private adapter;
     private config;
@@ -226,6 +228,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 +368,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
@@ -404,6 +430,13 @@ declare class SessionManager {
      * @throws {LemuraMaxIterationsError} When the loop exceeds `maxIterations`
      */
     run(userMessage: string | ContentBlock[]): Promise<string>;
+    /**
+     * Resets progressive skills at the start of a turn when
+     * `skillSelection.persistence` is `'per_turn'` (the default), so each user
+     * message re-decides which skills to load from the catalog. No-op when
+     * persistence is `'session'` or there are no progressive skills.
+     */
+    private _resetProgressiveSkillsForTurn;
     /**
      * Runs the ReAct loop and streams the final assistant response token-by-token.
      *
@@ -529,6 +562,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 +726,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 };