@selesai/code 0.13.14 → 0.13.15

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to `@selesai/code` will be documented in this file.
 
+## [0.13.15] - 2026-09-06
+
+### Added
+- **Progressive capability gateway.** Optional extension tools and skills now stay out of the default model context while remaining discoverable through `capability_catalog`, `capability_discover`, and `capability_skill_show`. Built-in tools are unchanged, and the gateway can be disabled with `SELESAI_CAPABILITY_GATEWAY=0`.
+
+### Fixed
+- **Capability catalog metadata.** Disabled skills now recover their frontmatter descriptions, and catalog results are no longer capped at 20 entries.
+- **Zentui stale-session updates.** Timer-driven working-line updates now fail open when a captured extension context becomes stale after session replacement or reload.
+
 ## [0.13.13] - 2026-09-04
 
 ### Added

package/dist/core/agent-session-auto-handoff.test.js

@@ -19,6 +19,8 @@ function createMockSession({ enabled, threshold = 128_000, tokens, mode = "tui",
     const resourceLoader = {
         getExtensions: () => ({ extensions: [], errors: [], runtime: { flagValues: new Map(), pendingProviderRegistrations: [], pendingNativeProviderRegistrations: [], assertActive: () => { } } }),
         getSkills: () => ({ skills: [], diagnostics: [] }),
+        getPromptSkills: () => [],
+        setSkillsIndexFilter: () => { },
         getPrompts: () => ({ prompts: [], diagnostics: [] }),
         getThemes: () => ({ themes: [], diagnostics: [] }),
         getAgents: () => ({ agents: [], diagnostics: [] }),

package/dist/core/agent-session-length-continuation.test.js

@@ -14,6 +14,8 @@ function createMockSession() {
     const resourceLoader = {
         getExtensions: () => ({ extensions: [], errors: [], runtime: { flagValues: new Map(), pendingProviderRegistrations: [], pendingNativeProviderRegistrations: [], assertActive: () => { } } }),
         getSkills: () => ({ skills: [], diagnostics: [] }),
+        getPromptSkills: () => [],
+        setSkillsIndexFilter: () => { },
         getPrompts: () => ({ prompts: [], diagnostics: [] }),
         getThemes: () => ({ themes: [], diagnostics: [] }),
         getAgents: () => ({ agents: [], diagnostics: [] }),

package/dist/core/agent-session.js

@@ -711,6 +711,7 @@ export class AgentSession {
             description: definition.description,
             parameters: definition.parameters,
             promptGuidelines: definition.promptGuidelines,
+            discovery: definition.discovery,
             sourceInfo,
         }));
     }
@@ -819,7 +820,7 @@ export class AgentSession {
         const loaderSystemPrompt = this._resourceLoader.getSystemPrompt();
         const loaderAppendSystemPrompt = this._resourceLoader.getAppendSystemPrompt();
         const appendSystemPrompt = loaderAppendSystemPrompt.length > 0 ? loaderAppendSystemPrompt.join("\n\n") : undefined;
-        const loadedSkills = this._resourceLoader.getSkills().skills;
+        const loadedSkills = this._resourceLoader.getPromptSkills();
         const loadedAgents = this._resourceLoader.getAgents().agents;
         const loadedContextFiles = this._resourceLoader.getAgentsFiles().agentsFiles;
         this._baseSystemPromptOptions = {
@@ -2249,6 +2250,22 @@ export class AgentSession {
             getActiveTools: () => this.getActiveToolNames(),
             getAllTools: () => this.getAllTools(),
             setActiveTools: (toolNames) => this.setActiveToolsByName(toolNames),
+            getResolvedSkills: () => this._resourceLoader.getResolvedSkills().map((resource) => {
+                const skill = this._resourceLoader.getSkills().skills.find((s) => s.filePath === resource.path);
+                return {
+                    name: skill?.name ?? basename(dirname(resource.path)),
+                    description: skill?.description ?? "",
+                    category: skill?.category,
+                    filePath: resource.path,
+                    scope: resource.metadata.scope === "project" ? "project" : "user",
+                    disableModelInvocation: skill?.disableModelInvocation ?? false,
+                };
+            }),
+            setSkillsIndexFilter: (filter) => {
+                this._resourceLoader.setSkillsIndexFilter(filter);
+                this._baseSystemPrompt = this._rebuildSystemPrompt(this.getActiveToolNames());
+                this.agent.state.systemPrompt = this._systemPromptOverride ?? this._baseSystemPrompt;
+            },
             refreshTools: () => this._refreshToolRegistry(),
             getCommands,
             setModel: async (model) => {

package/dist/core/extensions/index.d.ts

@@ -6,6 +6,6 @@ export type { SourceInfo } from "../source-info.ts";
 export { createExtensionRuntime, discoverAndLoadExtensions, loadExtensionFromFactory, loadExtensions, } from "./loader.ts";
 export type { ExtensionErrorListener, ForkHandler, NavigateTreeHandler, NewSessionHandler, ShutdownHandler, SwitchSessionHandler, } from "./runner.ts";
 export { ExtensionRunner } from "./runner.ts";
-export type { AfterProviderResponseEvent, AgentEndEvent, AgentSettledEvent, AgentStartEvent, AgentToolResult, AgentToolUpdateCallback, AppendEntryHandler, AppKeybinding, AutocompleteProviderFactory, BashToolCallEvent, BashToolResultEvent, BeforeAgentStartEvent, BeforeAgentStartEventResult, BeforeProviderHeadersEvent, BeforeProviderRequestEvent, BeforeProviderRequestEventResult, BuildSystemPromptOptions, CompactOptions, ContextEvent, ContextEventResult, ContextUsage, CustomToolCallEvent, CustomToolResultEvent, EditorFactory, EditToolCallEvent, EditToolResultEvent, EntryRenderer, EntryRenderOptions, ExecOptions, ExecResult, Extension, ExtensionActions, ExtensionAPI, ExtensionCommandContext, ExtensionCommandContextActions, ExtensionContext, ExtensionContextActions, ExtensionError, ExtensionEvent, ExtensionFactory, ExtensionFlag, ExtensionHandler, ExtensionMode, ExtensionRuntime, ExtensionShortcut, ExtensionUIContext, ExtensionUIDialogOptions, ExtensionWidgetOptions, FindToolCallEvent, FindToolResultEvent, GetActiveToolsHandler, GetAllToolsHandler, GetCommandsHandler, GetThinkingLevelHandler, GrepToolCallEvent, GrepToolResultEvent, InlineExtension, InputEvent, InputEventResult, InputSource, KeybindingsManager, LoadExtensionsResult, LsToolCallEvent, LsToolResultEvent, MessageEndEvent, MessageRenderer, MessageRenderOptions, MessageStartEvent, MessageUpdateEvent, ModelSelectEvent, ModelSelectSource, ProjectTrustContext, ProjectTrustEvent, ProjectTrustEventDecision, ProjectTrustEventResult, ProjectTrustHandler, ProviderConfig, ProviderModelConfig, ReadToolCallEvent, ReadToolResultEvent, RegisteredCommand, RegisteredTool, ReplacedSessionContext, ResolvedCommand, ResourcesDiscoverEvent, ResourcesDiscoverResult, SendMessageHandler, SendUserMessageHandler, SessionBeforeCompactEvent, SessionBeforeCompactResult, SessionBeforeForkEvent, SessionBeforeForkResult, SessionBeforeSwitchEvent, SessionBeforeSwitchResult, SessionBeforeTreeEvent, SessionBeforeTreeResult, SessionCompactEvent, SessionEvent, SessionInfoChangedEvent, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent, SetActiveToolsHandler, SetLabelHandler, SetModelHandler, SetThinkingLevelHandler, TerminalInputHandler, ToolCallEvent, ToolCallEventResult, ToolDefinition, ToolExecutionEndEvent, ToolExecutionMode, ToolExecutionStartEvent, ToolExecutionUpdateEvent, ToolInfo, ToolRenderResultOptions, ToolResultEvent, ToolResultEventResult, TreePreparation, TurnEndEvent, TurnStartEvent, UIPromptEndEvent, UIPromptKind, UIPromptStartEvent, UserBashEvent, UserBashEventResult, WidgetPlacement, WorkingIndicatorOptions, WriteToolCallEvent, WriteToolResultEvent, } from "./types.ts";
+export type { AfterProviderResponseEvent, AgentEndEvent, AgentSettledEvent, AgentStartEvent, AgentToolResult, AgentToolUpdateCallback, AppendEntryHandler, AppKeybinding, AutocompleteProviderFactory, BashToolCallEvent, BashToolResultEvent, BeforeAgentStartEvent, BeforeAgentStartEventResult, BeforeProviderHeadersEvent, BeforeProviderRequestEvent, BeforeProviderRequestEventResult, BuildSystemPromptOptions, CompactOptions, ContextEvent, ContextEventResult, ContextUsage, CustomToolCallEvent, CustomToolResultEvent, EditorFactory, EditToolCallEvent, EditToolResultEvent, EntryRenderer, EntryRenderOptions, ExecOptions, ExecResult, Extension, ExtensionActions, ExtensionAPI, ExtensionCommandContext, ExtensionCommandContextActions, ExtensionContext, ExtensionContextActions, ExtensionError, ExtensionEvent, ExtensionFactory, ExtensionFlag, ExtensionHandler, ExtensionMode, ExtensionRuntime, ExtensionShortcut, ExtensionUIContext, ExtensionUIDialogOptions, ExtensionWidgetOptions, FindToolCallEvent, FindToolResultEvent, GetActiveToolsHandler, GetAllToolsHandler, GetCommandsHandler, GetThinkingLevelHandler, GrepToolCallEvent, GrepToolResultEvent, InlineExtension, InputEvent, InputEventResult, InputSource, KeybindingsManager, LoadExtensionsResult, LsToolCallEvent, LsToolResultEvent, MessageEndEvent, MessageRenderer, MessageRenderOptions, MessageStartEvent, MessageUpdateEvent, ModelSelectEvent, ModelSelectSource, ProjectTrustContext, ProjectTrustEvent, ProjectTrustEventDecision, ProjectTrustEventResult, ProjectTrustHandler, ProviderConfig, ProviderModelConfig, ReadToolCallEvent, ReadToolResultEvent, RegisteredCommand, RegisteredTool, ReplacedSessionContext, ResolvedCommand, ResolvedSkillInfo, ResourcesDiscoverEvent, ResourcesDiscoverResult, SendMessageHandler, SendUserMessageHandler, SessionBeforeCompactEvent, SessionBeforeCompactResult, SessionBeforeForkEvent, SessionBeforeForkResult, SessionBeforeSwitchEvent, SessionBeforeSwitchResult, SessionBeforeTreeEvent, SessionBeforeTreeResult, SessionCompactEvent, SessionEvent, SessionInfoChangedEvent, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent, SetActiveToolsHandler, SetLabelHandler, SetModelHandler, SetThinkingLevelHandler, TerminalInputHandler, ToolCallEvent, ToolCallEventResult, ToolDefinition, ToolExecutionEndEvent, ToolExecutionMode, ToolExecutionStartEvent, ToolExecutionUpdateEvent, ToolInfo, ToolRenderResultOptions, ToolResultEvent, ToolResultEventResult, TreePreparation, TurnEndEvent, TurnStartEvent, UIPromptEndEvent, UIPromptKind, UIPromptStartEvent, UserBashEvent, UserBashEventResult, WidgetPlacement, WorkingIndicatorOptions, WriteToolCallEvent, WriteToolResultEvent, } from "./types.ts";
 export { defineTool, isBashToolResult, isEditToolResult, isFindToolResult, isGrepToolResult, isLsToolResult, isReadToolResult, isToolCallEventType, isWriteToolResult, } from "./types.ts";
 export { wrapRegisteredTool, wrapRegisteredTools } from "./wrapper.ts";

package/dist/core/extensions/loader.js

@@ -150,6 +150,8 @@ export function createExtensionRuntime() {
         getActiveTools: notInitialized,
         getAllTools: notInitialized,
         setActiveTools: notInitialized,
+        getResolvedSkills: notInitialized,
+        setSkillsIndexFilter: notInitialized,
         // registerTool() is valid during extension load; refresh is only needed post-bind.
         refreshTools: () => { },
         getCommands: notInitialized,
@@ -291,6 +293,14 @@ function createExtensionAPI(extension, runtime, cwd, eventBus) {
             assertActive();
             return runtime.getActiveTools();
         },
+        getResolvedSkills() {
+            assertActive();
+            return runtime.getResolvedSkills();
+        },
+        setSkillsIndexFilter(filter) {
+            assertActive();
+            runtime.setSkillsIndexFilter(filter);
+        },
         getAllTools() {
             assertActive();
             return runtime.getAllTools();

package/dist/core/extensions/runner.js

@@ -168,6 +168,8 @@ export class ExtensionRunner {
         this.runtime.getActiveTools = actions.getActiveTools;
         this.runtime.getAllTools = actions.getAllTools;
         this.runtime.setActiveTools = actions.setActiveTools;
+        this.runtime.getResolvedSkills = actions.getResolvedSkills;
+        this.runtime.setSkillsIndexFilter = actions.setSkillsIndexFilter;
         this.runtime.refreshTools = actions.refreshTools;
         this.runtime.getCommands = actions.getCommands;
         this.runtime.setModel = actions.setModel;

package/dist/core/extensions/types.d.ts

@@ -23,6 +23,7 @@ import type { ModelRegistry } from "../model-registry.ts";
 import type { ScopedModel } from "../model-resolver.ts";
 import type { BranchSummaryEntry, CompactionEntry, CustomEntry, ReadonlySessionManager, SessionEntry, SessionManager } from "../session-manager.ts";
 import type { SlashCommandInfo } from "../slash-commands.ts";
+import type { Skill } from "../skills.ts";
 import type { SourceInfo } from "../source-info.ts";
 import type { BuildSystemPromptOptions } from "../system-prompt.ts";
 import type { BashOperations } from "../tools/bash.ts";
@@ -352,6 +353,20 @@ export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = un
     description: string;
     /** Optional one-line snippet for the Available tools section in the default system prompt. Custom tools are omitted from that section when this is not provided. */
     promptSnippet?: string;
+    /**
+     * Optional discovery metadata for the capability gateway. When present, the
+     * tool is eligible for catalog/discovery; when absent, a conservative
+     * name/first-sentence fallback summary is used. Never contains the full
+     * tool description or schema.
+     */
+    discovery?: {
+        /** Short one-line purpose shown in the catalog. */
+        summary?: string;
+        /** Alternative names the router can match. */
+        aliases?: string[];
+        /** Stable category label. */
+        category?: string;
+    };
     /** Optional guideline bullets appended to the default system prompt Guidelines section when this tool is active. */
     promptGuidelines?: string[];
     /** Parameter schema (TypeBox) */
@@ -972,6 +987,20 @@ export interface ExtensionAPI {
     exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
     /** Get the list of currently active tool names. */
     getActiveTools(): string[];
+    /**
+     * Get the resolved, trust-filtered skill catalog (enabled skills with
+     * metadata). Skills hidden from model invocation are flagged so callers
+     * can exclude them from automatic discovery.
+     */
+    getResolvedSkills(): ResolvedSkillInfo[];
+    /**
+     * Replace the skill view rendered into the system-prompt skill index.
+     * The filter receives the default eligible view (trust-filtered,
+     * model-invocation-eligible) and returns the view to render. Passing
+     * undefined restores the default. The resolved skill catalog is never
+     * mutated; explicit inline skill invocation is unaffected.
+     */
+    setSkillsIndexFilter(filter: ((skills: Skill[]) => Skill[]) | undefined): void;
     /** Get all configured tools with parameter schema, prompt guidelines, and source metadata. */
     getAllTools(): ToolInfo[];
     /** Set the active tools by name. */
@@ -1161,9 +1190,18 @@ export type SetSessionNameHandler = (name: string) => void;
 export type GetSessionNameHandler = () => string | undefined;
 export type GetActiveToolsHandler = () => string[];
 /** Tool info with name, description, parameter schema, prompt guidelines, and source metadata. */
-export type ToolInfo = Pick<ToolDefinition, "name" | "description" | "parameters" | "promptGuidelines"> & {
+export type ToolInfo = Pick<ToolDefinition, "name" | "description" | "parameters" | "promptGuidelines" | "discovery"> & {
     sourceInfo: SourceInfo;
 };
+/** A resolved, trust-filtered skill in the extension-facing catalog. */
+export interface ResolvedSkillInfo {
+    name: string;
+    description: string;
+    category?: string;
+    filePath: string;
+    scope: "user" | "project" | "temporary";
+    disableModelInvocation: boolean;
+}
 export type GetAllToolsHandler = () => ToolInfo[];
 export type GetCommandsHandler = () => SlashCommandInfo[];
 export type SetActiveToolsHandler = (toolNames: string[]) => void;
@@ -1217,6 +1255,8 @@ export interface ExtensionActions {
     getActiveTools: GetActiveToolsHandler;
     getAllTools: GetAllToolsHandler;
     setActiveTools: SetActiveToolsHandler;
+    getResolvedSkills: () => ResolvedSkillInfo[];
+    setSkillsIndexFilter: (filter: ((skills: Skill[]) => Skill[]) | undefined) => void;
     refreshTools: RefreshToolsHandler;
     getCommands: GetCommandsHandler;
     setModel: SetModelHandler;

package/dist/core/resource-loader.d.ts

@@ -35,6 +35,20 @@ export interface ResourceLoader {
         diagnostics: ResourceDiagnostic[];
     };
     getResolvedSkills(): ResolvedResource[];
+    /**
+     * Skills eligible for the system-prompt skill index (trust-filtered,
+     * model-invocation-eligible). Extensions may replace this view via
+     * setSkillsIndexFilter to implement progressive disclosure without
+     * touching the resolved catalog.
+     */
+    getPromptSkills(): Skill[];
+    /**
+     * Replace the skill view used when rendering the system-prompt skill index.
+     * The filter receives the default eligible view and returns the view to
+     * render. Passing undefined restores the default. The resolved catalog
+     * (getSkills/getResolvedSkills) is never mutated.
+     */
+    setSkillsIndexFilter(filter: ((skills: Skill[]) => Skill[]) | undefined): void;
     getPrompts(): {
         prompts: PromptTemplate[];
         diagnostics: ResourceDiagnostic[];
@@ -166,6 +180,7 @@ export declare class DefaultResourceLoader implements ResourceLoader {
     private skills;
     private skillDiagnostics;
     private resolvedSkills;
+    private skillsIndexFilter;
     private agents;
     private agentDiagnostics;
     private prompts;
@@ -193,6 +208,8 @@ export declare class DefaultResourceLoader implements ResourceLoader {
         diagnostics: ResourceDiagnostic[];
     };
     getResolvedSkills(): ResolvedResource[];
+    getPromptSkills(): Skill[];
+    setSkillsIndexFilter(filter: ((skills: Skill[]) => Skill[]) | undefined): void;
     getPrompts(): {
         prompts: PromptTemplate[];
         diagnostics: ResourceDiagnostic[];

package/dist/core/resource-loader.js

@@ -141,6 +141,7 @@ export class DefaultResourceLoader {
     skills;
     skillDiagnostics;
     resolvedSkills = [];
+    skillsIndexFilter;
     agents;
     agentDiagnostics;
     prompts;
@@ -226,6 +227,13 @@ export class DefaultResourceLoader {
     getResolvedSkills() {
         return this.resolvedSkills;
     }
+    getPromptSkills() {
+        const eligible = this.skills.filter((skill) => !skill.disableModelInvocation);
+        return this.skillsIndexFilter ? this.skillsIndexFilter(eligible) : eligible;
+    }
+    setSkillsIndexFilter(filter) {
+        this.skillsIndexFilter = filter;
+    }
     getPrompts() {
         return { prompts: this.prompts, diagnostics: this.promptDiagnostics };
     }

package/dist/extensions/capability-gateway/catalog.ts

@@ -0,0 +1,150 @@
+/**
+ * Capability gateway catalog and deterministic router.
+ *
+ * Pure functions: no host imports, fully unit-testable. The router uses
+ * deterministic local scoring (name/alias matches above token overlap) and
+ * never calls a model.
+ */
+
+import { readFileSync } from "node:fs";
+
+import { parseFrontmatter, type ResolvedSkillInfo, type ToolInfo } from "@selesai/code";
+
+export interface CatalogEntry {
+	name: string;
+	kind: "tool" | "skill";
+	summary: string;
+	aliases: string[];
+	category?: string;
+	eligible: boolean;
+}
+
+/** Built-in tools are never mediated by the gateway. */
+export const BUILTIN_TOOL_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls"]);
+
+/** First sentence of a description, used as the conservative fallback summary. */
+export function firstSentence(text: string): string {
+	const trimmed = text.trim();
+	const end = trimmed.search(/[.!?](?:\s|$)/);
+	return (end === -1 ? trimmed : trimmed.slice(0, end + 1)).trim();
+}
+
+/** Compact summary for a tool: explicit discovery metadata wins, then first sentence, then snippet. */
+export function toolSummary(tool: ToolInfo): string {
+	const explicit = tool.discovery?.summary?.trim();
+	if (explicit) return explicit;
+	const sentence = firstSentence(tool.description);
+	if (sentence) return sentence;
+	return tool.promptSnippet?.trim() || tool.name;
+}
+
+export function buildToolCatalog(tools: ToolInfo[], gatewayToolNames: Set<string>): CatalogEntry[] {
+	return tools
+		.filter((tool) => !BUILTIN_TOOL_NAMES.has(tool.name) && !gatewayToolNames.has(tool.name))
+		.map((tool) => ({
+			name: tool.name,
+			kind: "tool" as const,
+			summary: toolSummary(tool),
+			aliases: tool.discovery?.aliases ?? [],
+			category: tool.discovery?.category,
+			eligible: true,
+		}));
+}
+
+export function buildSkillCatalog(skills: ResolvedSkillInfo[]): CatalogEntry[] {
+	return skills
+		.filter((skill) => !skill.disableModelInvocation)
+		.map((skill) => ({
+			name: skill.name,
+			kind: "skill" as const,
+			summary: skill.description || skillSummaryFromFile(skill.filePath),
+			aliases: [],
+			category: skill.category,
+			eligible: true,
+		}));
+}
+
+// Disabled skills resolve as paths but never parse; read the frontmatter description instead.
+function skillSummaryFromFile(filePath: string): string {
+	try {
+		const { frontmatter } = parseFrontmatter<{ description?: string }>(readFileSync(filePath, "utf-8"));
+		return firstSentence(frontmatter.description ?? "");
+	} catch {
+		return "";
+	}
+}
+
+export function normalizeQuery(text: string): string {
+	return text
+		.toLowerCase()
+		.replace(/[^a-z0-9\s-]/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+export function tokenize(text: string): string[] {
+	return normalizeQuery(text).split(/\s+/).filter(Boolean);
+}
+
+/** Words that carry no routing signal. */
+const STOPWORDS = new Set([
+	"the", "a", "an", "to", "of", "for", "with", "and", "or", "use", "using", "me", "my", "i",
+	"please", "help", "can", "you", "do", "does", "is", "are", "on", "in", "at", "by", "from",
+	"this", "that", "it", "its", "want", "need", "run", "call", "invoke", "find", "show", "list",
+	"get", "load", "activate", "discover", "capability", "tool", "skill", "the", "a",
+]);
+
+export interface RouteResult {
+	action: "activate" | "recommend" | "hint" | "none";
+	entry?: CatalogEntry;
+	candidates?: CatalogEntry[];
+}
+
+/**
+ * Deterministic routing over the compact catalog.
+ *
+ * - Exact name/alias match scores 3; prefix match scores 2; each content token
+ *   shared with the name/alias or summary adds 1.
+ * - A unique tool with score >= 3 is auto-activated.
+ * - A unique skill with score >= 3 is recommended (never auto-loaded).
+ * - Score 2 or a tie at the top produces a catalog-discovery hint.
+ * - No signal produces no hint at all.
+ */
+export function route(query: string, catalog: CatalogEntry[]): RouteResult {
+	const q = normalizeQuery(query);
+	if (!q) return { action: "none" };
+	const contentTokens = tokenize(q).filter((token) => !STOPWORDS.has(token));
+	if (contentTokens.length === 0) return { action: "none" };
+
+	const scored = catalog.map((entry) => {
+		const names = [entry.name, ...entry.aliases].map(normalizeQuery);
+		const nameTokens = new Set(names.flatMap((name) => name.split(/\s+/)));
+		const summaryTokens = new Set(tokenize(entry.summary));
+		let score = 0;
+		for (const name of names) {
+			if (name === q) score = Math.max(score, 3);
+			else if (name.startsWith(q) || q.startsWith(name)) score = Math.max(score, 2);
+		}
+		for (const token of contentTokens) {
+			if (nameTokens.has(token)) score += 3;
+			else if (token.length >= 3 && [...nameTokens].some((nameToken) => nameToken.startsWith(token))) score += 2;
+			if (summaryTokens.has(token)) score += 1;
+		}
+		return { entry, score };
+	});
+
+	const best = Math.max(0, ...scored.map((s) => s.score));
+	if (best === 0) return { action: "none" };
+	const top = scored.filter((s) => s.score === best);
+	if (top.length > 1) {
+		return { action: "hint", candidates: top.map((s) => s.entry) };
+	}
+	const winner = top[0]!.entry;
+	if (best >= 3) {
+		return { action: winner.kind === "tool" ? "activate" : "recommend", entry: winner };
+	}
+	if (best >= 2) {
+		return { action: "hint", candidates: [winner] };
+	}
+	return { action: "none" };
+}

package/dist/extensions/capability-gateway/index.test.ts

@@ -0,0 +1,128 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { describe, expect, it } from "vitest";
+import type { ResolvedSkillInfo, ToolInfo } from "@selesai/code";
+import {
+	buildSkillCatalog,
+	buildToolCatalog,
+	firstSentence,
+	route,
+	toolSummary,
+	type CatalogEntry,
+} from "./catalog.ts";
+
+const tool = (overrides: Partial<ToolInfo>): ToolInfo =>
+	({
+		name: "grep_app_search",
+		description: "Search public GitHub code through grep.app. Returns one page.",
+		parameters: {} as never,
+		sourceInfo: { path: "/ext/index.ts", source: "local", scope: "user", origin: "top-level" },
+		...overrides,
+	}) as ToolInfo;
+
+const skill = (overrides: Partial<ResolvedSkillInfo>): ResolvedSkillInfo => ({
+	name: "research",
+	description: "Investigate a question against high-trust primary sources.",
+	filePath: "/skills/research/SKILL.md",
+	scope: "user",
+	disableModelInvocation: false,
+	...overrides,
+});
+
+describe("catalog metadata", () => {
+	it("uses explicit discovery summary over the description first sentence", () => {
+		const t = tool({ discovery: { summary: "Search public GitHub code" } });
+		expect(toolSummary(t)).toBe("Search public GitHub code");
+	});
+
+	it("falls back to the first sentence of the description", () => {
+		expect(toolSummary(tool({}))).toBe("Search public GitHub code through grep.app.");
+	});
+
+	it("firstSentence handles short text without punctuation", () => {
+		expect(firstSentence("no punctuation here")).toBe("no punctuation here");
+	});
+
+	it("builds a tool catalog excluding built-ins and gateway tools", () => {
+		const tools = [
+			tool({ name: "read" }),
+			tool({ name: "capability_catalog" }),
+			tool({ name: "grep_app_search", discovery: { aliases: ["github-search"], category: "web" } }),
+		];
+		const entries = buildToolCatalog(tools, new Set(["capability_catalog"]));
+		expect(entries.map((e) => e.name)).toEqual(["grep_app_search"]);
+		expect(entries[0]!.aliases).toEqual(["github-search"]);
+		expect(entries[0]!.category).toBe("web");
+		expect(entries[0]!.kind).toBe("tool");
+	});
+
+	it("builds a skill catalog excluding disable-model-invocation skills", () => {
+		const entries = buildSkillCatalog([
+			skill({ name: "research" }),
+			skill({ name: "secret", disableModelInvocation: true }),
+		]);
+		expect(entries.map((e) => e.name)).toEqual(["research"]);
+		expect(entries[0]!.kind).toBe("skill");
+	});
+
+	it("falls back to the file frontmatter description when the resolved description is empty", () => {
+		const dir = mkdtempSync(join(tmpdir(), "gw-skill-"));
+		const filePath = join(dir, "SKILL.md");
+		writeFileSync(
+			filePath,
+			"---\nname: brandkit\ndescription: Premium brand-kit image generation skill for creating high-end brand-guidelines boards.\n---\nbody\n",
+		);
+		try {
+			const entries = buildSkillCatalog([skill({ name: "brandkit", description: "", filePath })]);
+			expect(entries[0]!.summary).toBe("Premium brand-kit image generation skill for creating high-end brand-guidelines boards.");
+		} finally {
+			rmSync(dir, { recursive: true, force: true });
+		}
+	});
+});
+
+describe("deterministic routing", () => {
+	const catalog: CatalogEntry[] = [
+		{ name: "grep_app_search", kind: "tool", summary: "Search public GitHub code", aliases: ["github-search"], category: "web" },
+		{ name: "grep_app_fetch", kind: "tool", summary: "Fetch a public GitHub file", aliases: [], category: "web" },
+		{ name: "research", kind: "skill", summary: "Investigate a question against primary sources", aliases: [], category: "research" },
+	];
+
+	it("auto-activates a unique high-confidence tool match", () => {
+		const result = route("search github code with grep_app_search", catalog);
+		expect(result.action).toBe("activate");
+		expect(result.entry?.name).toBe("grep_app_search");
+	});
+
+	it("matches by alias", () => {
+		const result = route("use github-search", catalog);
+		expect(result.action).toBe("activate");
+		expect(result.entry?.name).toBe("grep_app_search");
+	});
+
+	it("recommends a unique high-confidence skill without auto-loading", () => {
+		const result = route("do research on this topic", catalog);
+		expect(result.action).toBe("recommend");
+		expect(result.entry?.name).toBe("research");
+	});
+
+	it("returns a hint for ambiguous matches", () => {
+		const result = route("grep app", catalog);
+		expect(result.action).toBe("hint");
+		expect(result.candidates?.length).toBeGreaterThan(1);
+	});
+
+	it("returns none for unrelated prompts", () => {
+		expect(route("refactor the auth module", catalog).action).toBe("none");
+		expect(route("", catalog).action).toBe("none");
+		expect(route("   ", catalog).action).toBe("none");
+	});
+
+	it("is deterministic for the same input", () => {
+		const a = route("search github code", catalog);
+		const b = route("search github code", catalog);
+		expect(a).toEqual(b);
+	});
+});

package/dist/extensions/capability-gateway/index.ts

@@ -0,0 +1,318 @@
+/**
+ * Progressive capability gateway (experimental, opt-in).
+ *
+ * Issue #1: keep the full tool/skill ecosystem reachable without paying to
+ * expose every extension-tool schema and skill description on every request.
+ *
+ * Behavior:
+ * - On by default; disable via SELESAI_CAPABILITY_GATEWAY=0.
+ * - At session start, extension tools (except the gateway's own tools) become
+ *   dormant: they stay registered but are removed from the active tool set.
+ *   Built-in tools are never touched.
+ * - A compact catalog tool lists eligible tools/skills with one-line summaries.
+ * - capability_discover validates one catalogued tool and activates its native
+ *   definition for the current agent run; capability_skill_show loads exactly
+ *   the selected skill instructions.
+ * - A deterministic router inspects each user prompt and, for a unique
+ *   high-confidence tool match, activates it before the run; for a unique
+ *   high-confidence skill match it adds a concise recommendation; ambiguous
+ *   matches add a catalog hint; unrelated prompts are untouched.
+ * - Temporary activations reset at agent_settled, restoring the baseline
+ *   active-tool set.
+ * - The system-prompt skill index is replaced by a compact capability
+ *   instruction; full skill instructions load only on explicit show/invoke.
+ * - Telemetry events are emitted on the shared event bus.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { stripFrontmatter, type ExtensionAPI, type ToolInfo } from "@selesai/code";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import {
+	buildSkillCatalog,
+	buildToolCatalog,
+	BUILTIN_TOOL_NAMES,
+	route,
+	type CatalogEntry,
+} from "./catalog.ts";
+
+export const GATEWAY_ENV = "SELESAI_CAPABILITY_GATEWAY";
+export const GATEWAY_TOOLS = new Set(["capability_catalog", "capability_discover", "capability_skill_show"]);
+
+export const CAPABILITY_INSTRUCTION = `Optional capabilities (extension tools and skills) are not listed here by default. To use one:
+- Search the compact catalog with capability_catalog (kind: "tool" or "skill", natural-language query) when no active tool fits or a specialized integration/workflow is requested.
+- Activate a catalogued tool with capability_discover, then call it normally on the next turn.
+- Load a skill's full instructions with capability_skill_show before applying it.
+Never invent optional tool names, actions, or fields; discover them first.`;
+
+function isEnabled(): boolean {
+	return process.env[GATEWAY_ENV] !== "0";
+}
+
+function eligibleTools(pi: ExtensionAPI): ToolInfo[] {
+	return pi
+		.getAllTools()
+		.filter((tool) => !GATEWAY_TOOLS.has(tool.name) && !BUILTIN_TOOL_NAMES.has(tool.name));
+}
+
+function catalogEntries(pi: ExtensionAPI): CatalogEntry[] {
+	const tools = buildToolCatalog(eligibleTools(pi), GATEWAY_TOOLS);
+	const skills = buildSkillCatalog(pi.getResolvedSkills());
+	return [...tools, ...skills];
+}
+
+function formatCatalog(entries: CatalogEntry[]): string {
+	const lines = entries.map(
+		(entry) =>
+			`- ${entry.kind} ${entry.name}${entry.category ? ` [${entry.category}]` : ""}: ${entry.summary}`,
+	);
+	return lines.length > 0 ? lines.join("\n") : "(no matching capabilities)";
+}
+
+function findEntry(entries: CatalogEntry[], name: string): CatalogEntry | undefined {
+	const normalized = name.trim().toLowerCase();
+	return entries.find(
+		(entry) => entry.name.toLowerCase() === normalized || entry.aliases.some((alias) => alias.toLowerCase() === normalized),
+	);
+}
+
+function skillByFile(pi: ExtensionAPI, filePath: string): { name: string; body: string } | undefined {
+	const skill = pi.getResolvedSkills().find((s) => s.filePath === filePath);
+	if (!skill) return undefined;
+	try {
+		const body = stripFrontmatter(readFileSync(skill.filePath, "utf-8")).trim();
+		return { name: skill.name, body };
+	} catch {
+		return undefined;
+	}
+}
+
+function emitTelemetry(pi: ExtensionAPI, event: string, data: Record<string, unknown>): void {
+	try {
+		pi.events.emit("capability-gateway", { event, ...data });
+	} catch {
+		// Telemetry must never break the session.
+	}
+}
+
+export default function capabilityGatewayExtension(pi: ExtensionAPI): void {
+	if (!isEnabled()) return;
+
+	// ------------------------------------------------------------------
+	// Session start: snapshot baseline, make extension tools dormant, and
+	// install the compact skill index (action methods are stubs until bind).
+	// ------------------------------------------------------------------
+	pi.on("session_start", (_event, ctx) => {
+		const baseline = pi.getActiveTools();
+		const keep = baseline.filter(
+			(name) => !eligibleTools(pi).some((tool) => tool.name === name),
+		);
+		pi.setActiveTools(keep);
+		// Replace the eager skill index with a single compact capability
+		// instruction entry. Full skill instructions load only on show/invoke.
+		pi.setSkillsIndexFilter(() => [
+			{
+				name: "capability-gateway",
+				description: CAPABILITY_INSTRUCTION,
+				filePath: "<capability-gateway>",
+				baseDir: "<capability-gateway>",
+				sourceInfo: { path: "<capability-gateway>", source: "builtin", scope: "user", origin: "top-level" },
+				disableModelInvocation: false,
+			},
+		]);
+		emitTelemetry(pi, "session_start", { baselineCount: baseline.length, dormantCount: baseline.length - keep.length });
+		void ctx;
+	});
+
+	// ------------------------------------------------------------------
+	// Tools
+	// ------------------------------------------------------------------
+	pi.registerTool({
+		name: "capability_catalog",
+		label: "Capability Catalog",
+		description:
+			"Search the compact capability catalog for optional extension tools and skills. Returns name, kind (tool or skill), category, and a one-line purpose for each match. Use when no active tool fits or a specialized integration/workflow is requested.",
+		promptSnippet: "Search the compact catalog of optional tools and skills",
+		parameters: Type.Object({
+			query: Type.Optional(Type.String({ minLength: 1, description: "Natural-language query; omit to list all." })),
+			kind: Type.Optional(StringEnum(["tool", "skill"] as const, { description: "Filter by capability kind." })),
+		}),
+		async execute(_id, params) {
+			const entries = catalogEntries(pi);
+			const filtered = entries.filter(
+				(entry) => !params.kind || entry.kind === params.kind,
+			);
+			const matched = params.query ? route(params.query, filtered) : { action: "none" as const };
+			const shown =
+				params.query && matched.candidates
+					? matched.candidates
+					: params.query
+						? filtered.filter((entry) => {
+								const q = params.query!.toLowerCase();
+								return (
+									entry.name.toLowerCase().includes(q) ||
+									entry.summary.toLowerCase().includes(q) ||
+									entry.aliases.some((alias) => alias.toLowerCase().includes(q))
+								);
+							})
+						: filtered;
+			const text = formatCatalog(shown);
+			emitTelemetry(pi, "catalog", { query: params.query ?? "", kind: params.kind ?? "", results: shown.length });
+			return {
+				content: [{ type: "text", text }],
+				details: { count: shown.length, total: filtered.length },
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "capability_discover",
+		label: "Capability Discover",
+		description:
+			"Activate one catalogued extension tool for the current agent run. The tool's real schema and validation contract become available on the next model turn; it is removed again when the run ends. Use the exact name from capability_catalog.",
+		promptSnippet: "Activate a catalogued extension tool for the current run",
+		parameters: Type.Object({
+			name: Type.String({ minLength: 1, description: "Exact catalogued tool name." }),
+		}),
+		async execute(_id, params) {
+			const entries = catalogEntries(pi);
+			const entry = findEntry(entries, params.name);
+			if (!entry || entry.kind !== "tool") {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Unknown tool "${params.name}". Search capability_catalog for the exact name, or refine your query.`,
+						},
+					],
+					details: { activated: false },
+				};
+			}
+			const active = pi.getActiveTools();
+			if (!active.includes(entry.name)) {
+				pi.setActiveTools([...active, entry.name]);
+			}
+			emitTelemetry(pi, "discover", { tool: entry.name });
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Activated "${entry.name}" for this run. Call it normally on the next turn; it is removed when the run ends.`,
+					},
+				],
+				details: { activated: true, tool: entry.name },
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "capability_skill_show",
+		label: "Capability Skill Show",
+		description:
+			"Load the complete instructions for one skill from the resolved skill catalog. Use the exact skill name from capability_catalog. This is the explicit boundary that loads full SKILL.md content.",
+		promptSnippet: "Load a skill's full instructions by name",
+		parameters: Type.Object({
+			name: Type.String({ minLength: 1, description: "Exact skill name." }),
+		}),
+		async execute(_id, params) {
+			const skill = pi.getResolvedSkills().find((s) => s.name === params.name);
+			if (!skill) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Unknown skill "${params.name}". Search capability_catalog (kind: "skill") for the exact name.`,
+						},
+					],
+					details: { loaded: false },
+				};
+			}
+			const loaded = skillByFile(pi, skill.filePath);
+			if (!loaded) {
+				return {
+					content: [{ type: "text", text: `Skill "${params.name}" exists but its file could not be read.` }],
+					details: { loaded: false },
+				};
+			}
+			emitTelemetry(pi, "skill_show", { skill: loaded.name });
+			return {
+				content: [
+					{
+						type: "text",
+						text: `<skill name="${loaded.name}" location="${skill.filePath}">\nThe full instructions for this skill are embedded inline below; do not read its file again.\nReferences are relative to ${dirname(skill.filePath)}.\n\n${loaded.body}\n</skill>`,
+					},
+				],
+				details: { loaded: true, skill: loaded.name },
+			};
+		},
+	});
+
+	// ------------------------------------------------------------------
+	// Deterministic routing: high-confidence activation/recommendation,
+	// ambiguity hints, or nothing for unrelated prompts.
+	// ------------------------------------------------------------------
+	pi.on("before_agent_start", (event) => {
+		const result = route(event.prompt, catalogEntries(pi));
+		if (result.action === "none") return undefined;
+		if (result.action === "activate" && result.entry) {
+			const active = pi.getActiveTools();
+			if (!active.includes(result.entry.name)) {
+				pi.setActiveTools([...active, result.entry.name]);
+			}
+			emitTelemetry(pi, "route_activate", { tool: result.entry.name });
+			return undefined;
+		}
+		if (result.action === "recommend" && result.entry) {
+			emitTelemetry(pi, "route_recommend", { skill: result.entry.name });
+			return {
+				message: {
+					customType: "capability-gateway-hint",
+					content: `The request matches the optional skill "${result.entry.name}". Load it with capability_skill_show before applying it.`,
+					display: false,
+				},
+			};
+		}
+		if (result.action === "hint" && result.candidates) {
+			const names = result.candidates.map((c) => c.name).join(", ");
+			emitTelemetry(pi, "route_hint", { candidates: result.candidates.map((c) => c.name) });
+			return {
+				message: {
+					customType: "capability-gateway-hint",
+					content: `The request may match optional capabilities: ${names}. Search capability_catalog to confirm before selecting.`,
+					display: false,
+				},
+			};
+		}
+		return undefined;
+	});
+
+	// ------------------------------------------------------------------
+	// Reset: restore the baseline active-tool set after the run settles.
+	// ------------------------------------------------------------------
+	pi.on("agent_settled", () => {
+		const baseline = pi.getActiveTools().filter((name) => !eligibleTools(pi).some((tool) => tool.name === name));
+		pi.setActiveTools(baseline);
+		emitTelemetry(pi, "reset", { activeCount: baseline.length });
+	});
+
+	// ------------------------------------------------------------------
+	// Command: /capability-gateway status
+	// ------------------------------------------------------------------
+	pi.registerCommand("capability-gateway", {
+		description: "Show capability gateway status and catalog counts.",
+		async handler(_args, ctx) {
+			const tools = buildToolCatalog(eligibleTools(pi), GATEWAY_TOOLS);
+			const skills = buildSkillCatalog(pi.getResolvedSkills());
+			const active = pi.getActiveTools();
+			const dormant = tools.filter((t) => !active.includes(t.name)).length;
+			const text = [
+				`Capability gateway: enabled`,
+				`catalogued tools: ${tools.length} (${dormant} dormant)`,
+				`catalogued skills: ${skills.length}`,
+				`active tools: ${active.join(", ") || "(none)"}`,
+			].join("\n");
+			ctx.ui.notify(text);
+		},
+	});
+}

package/dist/extensions/capability-gateway/integration.test.ts

@@ -0,0 +1,215 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, it } from "vitest";
+import { fauxProvider } from "@earendil-works/pi-ai/providers/faux";
+import {
+	createAgentSession,
+	DefaultResourceLoader,
+	ModelRuntime,
+	SessionManager,
+	SettingsManager,
+	type AgentSession,
+} from "@selesai/code";
+
+const EXTENSIONS_DIR = fileURLToPath(new URL("../../", import.meta.url));
+const GATEWAY_DIR = fileURLToPath(new URL(".", import.meta.url));
+const GREP_APP_DIR = fileURLToPath(new URL("../grep-app", import.meta.url));
+
+interface Harness {
+	session: AgentSession;
+	dispose: () => Promise<void>;
+}
+
+async function createGatewaySession(options: {
+	enabled: boolean;
+	withSkill?: boolean;
+	extensions?: string[];
+}): Promise<Harness> {
+	const extensionPaths = options.extensions ?? [EXTENSIONS_DIR];
+	const cwd = mkdtempSync(join(tmpdir(), "gw-cwd-"));
+	const home = mkdtempSync(join(tmpdir(), "gw-home-"));
+	const previousCwd = process.cwd();
+	const previousHome = process.env.HOME;
+	const previousUserProfile = process.env.USERPROFILE;
+	const previousAgentDir = process.env.SELESAI_CODING_AGENT_DIR;
+	const previousGateway = process.env.SELESAI_CAPABILITY_GATEWAY;
+
+	process.chdir(cwd);
+	process.env.HOME = home;
+	process.env.USERPROFILE = home;
+	process.env.SELESAI_CODING_AGENT_DIR = home;
+	if (options.enabled) delete process.env.SELESAI_CAPABILITY_GATEWAY;
+	else process.env.SELESAI_CAPABILITY_GATEWAY = "0";
+
+	if (options.withSkill) {
+		mkdirSync(join(home, "skills", "research"), { recursive: true });
+		writeFileSync(
+			join(home, "skills", "research", "SKILL.md"),
+			"---\nname: research\ndescription: Investigate a question against high-trust primary sources.\n---\nResearch instructions body.\n",
+		);
+	}
+
+	const faux = fauxProvider({ provider: "faux-gw", models: [{ id: "gw", contextWindow: 200_000 }] });
+	const modelRuntime = await ModelRuntime.create({
+		authPath: join(home, "auth.json"),
+		modelsPath: null,
+		allowModelNetwork: false,
+	});
+	modelRuntime.registerProvider(faux.provider.id, {
+		name: faux.provider.name,
+		api: faux.api,
+		apiKey: "faux",
+		streamSimple: faux.provider.streamSimple,
+		models: [...faux.models],
+	});
+	await modelRuntime.refresh({ allowNetwork: false });
+	const model = modelRuntime.getModel(faux.provider.id, "gw");
+	if (!model) throw new Error("faux model not registered");
+
+	const settingsManager = SettingsManager.inMemory({ compaction: { enabled: false }, retry: { enabled: false } });
+	const loader = new DefaultResourceLoader({
+		cwd,
+		agentDir: home,
+		settingsManager,
+		additionalExtensionPaths: extensionPaths,
+		noPromptTemplates: true,
+		noThemes: true,
+		noContextFiles: true,
+	});
+	await loader.reload();
+
+	const created = await createAgentSession({
+		cwd,
+		agentDir: home,
+		model,
+		modelRuntime,
+		resourceLoader: loader,
+		sessionManager: SessionManager.create(cwd, join(home, "sessions")),
+		settingsManager,
+	});
+	const session = created.session;
+	await session.bindExtensions({});
+
+	const dispose = async () => {
+		try {
+			await session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" });
+		} catch {}
+		try {
+			session.dispose();
+		} catch {}
+		process.chdir(previousCwd);
+		if (previousHome === undefined) delete process.env.HOME;
+		else process.env.HOME = previousHome;
+		if (previousUserProfile === undefined) delete process.env.USERPROFILE;
+		else process.env.USERPROFILE = previousUserProfile;
+		if (previousAgentDir === undefined) delete process.env.SELESAI_CODING_AGENT_DIR;
+		else process.env.SELESAI_CODING_AGENT_DIR = previousAgentDir;
+		if (previousGateway === undefined) delete process.env.SELESAI_CAPABILITY_GATEWAY;
+		else process.env.SELESAI_CAPABILITY_GATEWAY = previousGateway;
+		rmSync(cwd, { recursive: true, force: true });
+		rmSync(home, { recursive: true, force: true });
+	};
+
+	return { session, dispose };
+}
+
+const harnesses: Harness[] = [];
+afterEach(async () => {
+	for (const h of harnesses.splice(0)) await h.dispose();
+});
+
+describe("capability gateway integration", () => {
+	it("keeps extension tools dormant and built-ins active when enabled", async () => {
+		const h = await createGatewaySession({ enabled: true });
+		harnesses.push(h);
+		const active = h.session.getActiveToolNames();
+		expect(active).toContain("read");
+		expect(active).toContain("bash");
+		expect(active).not.toContain("grep_app_search");
+		expect(active).not.toContain("subagent");
+		// Gateway's own tools stay active so the agent can discover.
+		expect(active).toContain("capability_catalog");
+	});
+
+	it("keeps all-visible behavior when disabled (compatibility mode)", async () => {
+		const h = await createGatewaySession({ enabled: false });
+		harnesses.push(h);
+		const active = h.session.getActiveToolNames();
+		expect(active).toContain("read");
+		expect(active).toContain("grep_app_search");
+		expect(active).toContain("subagent");
+	});
+
+	it("replaces the eager skill index with the compact capability instruction", async () => {
+		const h = await createGatewaySession({ enabled: true, withSkill: true });
+		harnesses.push(h);
+		const prompt = h.session.systemPrompt;
+		expect(prompt).toContain("capability_catalog");
+		expect(prompt).toContain("Never invent optional tool names");
+		// The full skill list is gone from the default prompt: the research
+		// skill name and body are absent, only the compact instruction remains.
+		expect(prompt).not.toContain("Research instructions body.");
+		const block = prompt.slice(prompt.indexOf("<available_skills>"), prompt.indexOf("</available_skills>"));
+		expect(block).not.toContain("research");
+		expect(block).toContain("capability-gateway");
+	});
+
+	it("activates a discovered tool for the run and resets after agent_settled", async () => {
+		const h = await createGatewaySession({ enabled: true });
+		harnesses.push(h);
+		const baseline = h.session.getActiveToolNames();
+		expect(baseline).not.toContain("grep_app_search");
+
+		// capability_discover activates the native tool.
+		const discover = h.session.getToolDefinition("capability_discover");
+		expect(discover).toBeDefined();
+		const result = await discover!.execute("call-1", { name: "grep_app_search" }, undefined, undefined, {} as never);
+		expect(result.content[0]!.type).toBe("text");
+		expect(String(result.content[0]!.text)).toContain("Activated");
+		expect(h.session.getActiveToolNames()).toContain("grep_app_search");
+
+		// agent_settled restores the baseline.
+		await h.session.extensionRunner.emit({ type: "agent_settled" });
+		expect(h.session.getActiveToolNames()).toEqual(baseline);
+	});
+
+	it("routes a high-confidence prompt to automatic activation", async () => {
+		// Minimal extension set (gateway + grep-app) so no other extension's
+		// before_agent_start handler interferes with the routing result.
+		const h = await createGatewaySession({ enabled: true, extensions: [GATEWAY_DIR, GREP_APP_DIR] });
+		harnesses.push(h);
+		expect(h.session.getActiveToolNames()).not.toContain("grep_app_search");
+
+		const runner = h.session.extensionRunner;
+		const result = await runner.emitBeforeAgentStart(
+			"search github code with grep_app_search",
+			undefined,
+			h.session.systemPrompt,
+			{ cwd: process.cwd() } as never,
+		);
+		expect(result).toBeUndefined();
+		expect(h.session.getActiveToolNames()).toContain("grep_app_search");
+	});
+
+	it("does not auto-load skills from fuzzy matching", async () => {
+		const h = await createGatewaySession({
+			enabled: true,
+			withSkill: true,
+			extensions: [GATEWAY_DIR, GREP_APP_DIR],
+		});
+		harnesses.push(h);
+		const runner = h.session.extensionRunner;
+		const result = await runner.emitBeforeAgentStart(
+			"do research on this topic",
+			undefined,
+			h.session.systemPrompt,
+			{ cwd: process.cwd() } as never,
+		);
+		// A recommendation message is injected, but the skill body is not loaded
+		// into the prompt and the skill is not auto-activated.
+		expect(result?.messages?.[0]?.content).toContain("research");
+		expect(h.session.systemPrompt).not.toContain("Research instructions body.");
+	});
+});

package/dist/extensions/capability-gateway/package.json

@@ -0,0 +1,15 @@
+{
+	"name": "@selesai/capability-gateway",
+	"version": "0.1.0",
+	"private": true,
+	"description": "Experimental progressive capability gateway: dormant extension tools and skills with compact catalog, deterministic routing, and native activation.",
+	"type": "module",
+	"pi": {
+		"extensions": ["./index.ts"]
+	},
+	"peerDependencies": {
+		"@selesai/code": "*",
+		"@earendil-works/pi-ai": "*",
+		"typebox": "*"
+	}
+}

package/dist/extensions/package.json

@@ -26,6 +26,7 @@
 			"./pi-hermes-memory",
 			"./web-agent-onboarding.ts",
 			"./tps.ts",
+			"./capability-gateway",
 			"./pi-zentui/extensions/zentui/index.ts"
 		]
 	}

package/dist/extensions/pi-zentui/extensions/zentui/working-line.ts

@@ -972,12 +972,17 @@ export function buildWorkingLinePreviewFrames(
 }
 
 function workingLineUi(ctx: WorkingLineContext): WorkingLineUi | undefined {
-	if (ctx.hasUI === false || (ctx.mode !== undefined && ctx.mode !== "tui")) return undefined;
-	const ui = ctx.ui as unknown as Partial<WorkingLineUi>;
-	if (typeof ui.setWorkingMessage !== "function" || typeof ui.setWorkingIndicator !== "function") {
+	try {
+		if (ctx.hasUI === false || (ctx.mode !== undefined && ctx.mode !== "tui")) return undefined;
+		const ui = ctx.ui as unknown as Partial<WorkingLineUi>;
+		if (typeof ui.setWorkingMessage !== "function" || typeof ui.setWorkingIndicator !== "function") {
+			return undefined;
+		}
+		return ui as WorkingLineUi;
+	} catch {
+		// A stale ctx (after session replacement or reload) must not crash timer-driven updates.
 		return undefined;
 	}
-	return ui as WorkingLineUi;
 }
 
 export type WorkingLineReconcileResult = { applied: boolean; reason?: string };

package/dist/extensions/pi-zentui/test/working-line.test.ts

@@ -1684,6 +1684,32 @@ describe("working-line runtime ownership", () => {
 		expect(phaseSignature(retried.frames[0] ?? "")[0]).toBe("⣏⠀⣹");
 	});
 
+	it("drops timer-driven updates when the captured ctx goes stale after session replacement", () => {
+		vi.useFakeTimers();
+		try {
+			const harness = runtime(true);
+			harness.controller.startSession(harness.ctx);
+			harness.clock.start();
+			harness.controller.startAgent(harness.ctx);
+			harness.controller.startTurn(harness.ctx);
+			harness.calls.length = 0;
+			// Simulate a session replacement invalidating the captured ctx: its getters throw.
+			const stale = harness.ctx as { hasUI: boolean };
+			Object.defineProperty(stale, "hasUI", {
+				get() {
+					throw new Error("stale ctx");
+				},
+				configurable: true,
+			});
+			expect(() => vi.advanceTimersByTime(1000)).not.toThrow();
+			expect(harness.calls).toEqual([]);
+			harness.controller.dispose(harness.ctx);
+			harness.clock.reset();
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
 	it("releases ownership when recovery also throws and waits for a clean reinstall", () => {
 		const current = config();
 		current.components.workingLine.enabled = true;

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { readStoredCredential } from "./core/auth-storage.ts";
 export { ensureTool, getToolPath, type ManagedTool } from "./utils/tools-manager.ts";
 export { type BranchPreparation, type BranchSummaryResult, type CollectEntriesResult, type CompactionResult, type CutPointResult, calculateContextTokens, collectEntriesForBranchSummary, compact, DEFAULT_COMPACTION_SETTINGS, estimateTokens, type FileOperations, findCutPoint, findTurnStartIndex, type GenerateBranchSummaryOptions, generateBranchSummary, generateSummary, generateSummaryWithUsage, getLastAssistantUsage, prepareBranchEntries, serializeConversation, shouldCompact, } from "./core/compaction/index.ts";
 export { createEventBus, type EventBus, type EventBusController } from "./core/event-bus.ts";
-export type { AgentEndEvent, AgentSettledEvent, AgentStartEvent, AgentToolResult, AgentToolUpdateCallback, AppKeybinding, AutocompleteProviderFactory, BashToolCallEvent, BeforeAgentStartEvent, BeforeAgentStartEventResult, BeforeProviderHeadersEvent, BeforeProviderRequestEvent, BeforeProviderRequestEventResult, BuildSystemPromptOptions, CompactOptions, ContextEvent, ContextUsage, CustomToolCallEvent, EditToolCallEvent, EntryRenderer, EntryRenderOptions, ExecOptions, ExecResult, Extension, ExtensionActions, ExtensionAPI, ExtensionCommandContext, ExtensionCommandContextActions, ExtensionContext, ExtensionContextActions, ExtensionError, ExtensionEvent, ExtensionFactory, ExtensionFlag, ExtensionHandler, ExtensionRuntime, ExtensionShortcut, ExtensionUIContext, ExtensionUIDialogOptions, ExtensionWidgetOptions, FindToolCallEvent, GrepToolCallEvent, InlineExtension, InputEvent, InputEventResult, InputSource, KeybindingsManager, LoadExtensionsResult, LsToolCallEvent, MessageEndEvent, MessageRenderer, MessageRenderOptions, MessageStartEvent, MessageUpdateEvent, ProjectTrustContext, ProjectTrustEvent, ProjectTrustEventDecision, ProjectTrustEventResult, ProjectTrustHandler, ProviderConfig, ProviderModelConfig, ReadToolCallEvent, RegisteredCommand, RegisteredTool, ResolvedCommand, SessionBeforeCompactEvent, SessionBeforeForkEvent, SessionBeforeSwitchEvent, SessionBeforeTreeEvent, SessionCompactEvent, SessionInfoChangedEvent, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent, SlashCommandInfo, SlashCommandSource, SourceInfo, TerminalInputHandler, ToolCallEvent, ToolCallEventResult, ToolDefinition, ToolExecutionEndEvent, ToolExecutionMode, ToolExecutionStartEvent, ToolExecutionUpdateEvent, ToolInfo, ToolRenderResultOptions, ToolResultEvent, TurnEndEvent, TurnStartEvent, UIPromptEndEvent, UIPromptKind, UIPromptStartEvent, UserBashEvent, UserBashEventResult, WidgetPlacement, WorkingIndicatorOptions, WriteToolCallEvent, } from "./core/extensions/index.ts";
+export type { AgentEndEvent, AgentSettledEvent, AgentStartEvent, AgentToolResult, AgentToolUpdateCallback, AppKeybinding, AutocompleteProviderFactory, BashToolCallEvent, BeforeAgentStartEvent, BeforeAgentStartEventResult, BeforeProviderHeadersEvent, BeforeProviderRequestEvent, BeforeProviderRequestEventResult, BuildSystemPromptOptions, CompactOptions, ContextEvent, ContextUsage, CustomToolCallEvent, EditToolCallEvent, EntryRenderer, EntryRenderOptions, ExecOptions, ExecResult, Extension, ExtensionActions, ExtensionAPI, ExtensionCommandContext, ExtensionCommandContextActions, ExtensionContext, ExtensionContextActions, ExtensionError, ExtensionEvent, ExtensionFactory, ExtensionFlag, ExtensionHandler, ExtensionRuntime, ExtensionShortcut, ExtensionUIContext, ExtensionUIDialogOptions, ExtensionWidgetOptions, FindToolCallEvent, GrepToolCallEvent, InlineExtension, InputEvent, InputEventResult, InputSource, KeybindingsManager, LoadExtensionsResult, LsToolCallEvent, MessageEndEvent, MessageRenderer, MessageRenderOptions, MessageStartEvent, MessageUpdateEvent, ProjectTrustContext, ProjectTrustEvent, ProjectTrustEventDecision, ProjectTrustEventResult, ProjectTrustHandler, ProviderConfig, ProviderModelConfig, ReadToolCallEvent, RegisteredCommand, RegisteredTool, ResolvedCommand, ResolvedSkillInfo, SessionBeforeCompactEvent, SessionBeforeForkEvent, SessionBeforeSwitchEvent, SessionBeforeTreeEvent, SessionCompactEvent, SessionInfoChangedEvent, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent, SlashCommandInfo, SlashCommandSource, SourceInfo, TerminalInputHandler, ToolCallEvent, ToolCallEventResult, ToolDefinition, ToolExecutionEndEvent, ToolExecutionMode, ToolExecutionStartEvent, ToolExecutionUpdateEvent, ToolInfo, ToolRenderResultOptions, ToolResultEvent, TurnEndEvent, TurnStartEvent, UIPromptEndEvent, UIPromptKind, UIPromptStartEvent, UserBashEvent, UserBashEventResult, WidgetPlacement, WorkingIndicatorOptions, WriteToolCallEvent, } from "./core/extensions/index.ts";
 export { createExtensionRuntime, defineTool, discoverAndLoadExtensions, ExtensionRunner, isBashToolResult, isEditToolResult, isFindToolResult, isGrepToolResult, isLsToolResult, isReadToolResult, isToolCallEventType, isWriteToolResult, wrapRegisteredTool, wrapRegisteredTools, } from "./core/extensions/index.ts";
 export type { ReadonlyFooterDataProvider } from "./core/footer-data-provider.ts";
 export { convertToLlm } from "./core/messages.ts";

package/dist/skills/to-prd/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: to-prd
+description: Turn the current conversation context into a PRD and save it under .selesai/docs/prds in the current project. Use when user wants to create a PRD from the current context.
+disable-model-invocation: true
+---
+
+This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know.
+
+## Process
+
+1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching.
+
+2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can.
+
+Check with the user that these seams match their expectations.
+
+3. Write the PRD using the template below, then save it as Markdown under `.selesai/docs/prds` relative to the current working directory. Create the directory if needed. Use a descriptive kebab-case filename ending in `.md`, and report the saved path to the user.
+
+<prd-template>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this PRD.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</prd-template>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selesai/code",
-  "version": "0.13.14",
+  "version": "0.13.15",
   "description": "Maintained, extension-first Pi coding agent with built-in workflows, subagents, web research, questions, skills, and an enhanced terminal UI.",
   "type": "module",
   "repository": {