@selesai/code 0.13.14 → 0.13.16

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to `@selesai/code` will be documented in this file.
 
+## [0.13.16] - 2026-09-06
+
+### Fixed
+- **Capability gateway inline-skill routing.** `$skill` references expanded by inline skills are no longer re-recommended through `capability_skill_show`; embedded `<skill>` blocks are excluded from prompt routing.
+- **TokenIn search backend URL.** A custom `baseUrl` ending in `/v1` no longer produces a doubled `/v1/v1/search/…` path, and accounts with a blank `apiKey` are now treated as unconfigured instead of triggering doomed requests.
+- **TokenIn search fallback typing.** Search fallback metadata can now reference any provider, matching actual failover behavior.
+
+## [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);
+	});
+});