@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

package/dist/tools/display-names.js

@@ -0,0 +1,24 @@
+/**
+ * The display names of plugins, for naming their extensions' tools (`<display name> [<tool>]`,
+ * tool naming spec §7): the live catalog item's `displayName`, else the plugin name in both
+ * languages (a bootstrap or uploaded plugin without a catalog item, or one without a display name).
+ * Display only.
+ */
+export async function pluginDisplayNames(db, names) {
+    const unique = [...new Set(names)];
+    const out = new Map(unique.map((n) => [n, { zh: n, en: n }]));
+    if (unique.length === 0)
+        return out;
+    const rows = await db
+        .selectFrom("catalog_items")
+        .select(["name", "display_name"])
+        .where("name", "in", unique)
+        .where("deleted_at", "is", null)
+        .execute();
+    for (const r of rows) {
+        const d = r.display_name;
+        if (d && typeof d.zh === "string" && typeof d.en === "string" && d.zh !== "" && d.en !== "")
+            out.set(r.name, { zh: d.zh, en: d.en });
+    }
+    return out;
+}

package/dist/tools/drift.js

@@ -7,7 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { TOOL_TITLE_MAX, ToolError, validateToolPresentation, } from "@capybara-hq/plugin-sdk";
+import { connectorToolKey, TOOL_TITLE_MAX, ToolError, validateToolPresentation, } from "@capybara-hq/plugin-sdk";
 import { getQueueToken } from "@nestjs/bullmq";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
@@ -21,7 +21,7 @@ import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
 import { HIDDEN_FORMAT_RE } from "../text.js";
 import { CredentialMissing, Credentials, isOAuth } from "./credentials.js";
-import { toolKey, toolKeyIssue } from "./naming.js";
+import { toolKeyIssue } from "./naming.js";
 import { redactDeep, redactorFor } from "./redact.js";
 import { canonicalJson, policyFromAnnotations, specHash, ToolRegistry } from "./registry.js";
 import { resourceToolSpecs } from "./resources.js";
@@ -105,7 +105,7 @@ export function snapshot(slug, specs, resources) {
             ...(isObj(s.connectorData) && { connectorData: s.connectorData }),
             ...displayFields(s),
         };
-        let issue = toolKeyIssue(toolKey(slug, name));
+        let issue = toolKeyIssue(connectorToolKey(slug, name));
         if (!issue && !isObj(s.inputSchema))
             issue = "Tool inputSchema must be an object";
         if (issue)
@@ -122,7 +122,7 @@ export function snapshot(slug, specs, resources) {
                 });
                 continue;
             }
-            const issue = toolKeyIssue(toolKey(slug, spec.name));
+            const issue = toolKeyIssue(connectorToolKey(slug, spec.name));
             if (issue)
                 issues.push({ name: spec.name, reason: issue });
             rows.push({ name: spec.name, spec, specHash: specHash(spec), issue, source: "resources" });
@@ -172,7 +172,7 @@ const displayOf = (spec) => {
 };
 /** 工具当前不能启用的原因（视图、启用与复核校验共用）。 */
 export function toolIssue(slug, spec) {
-    const keyIssue = toolKeyIssue(toolKey(slug, spec.name));
+    const keyIssue = toolKeyIssue(connectorToolKey(slug, spec.name));
     if (keyIssue)
         return keyIssue;
     if (!isObj(spec.inputSchema))

package/dist/tools/elicitation.js

@@ -33,7 +33,7 @@ export class ElicitationSuspended extends Error {
 }
 /** 不能展示的 elicitation 被拒绝时附在工具结果后的说明（模型可见，英文）。 */
 export const UNSUPPORTED_ELICITATION_NOTE = "The app asked the user for input that cannot be shown in this client, so the request was declined";
-const unsupportedNote = (why) => `[${UNSUPPORTED_ELICITATION_NOTE} (${why}). If the call needs that input, ask the user for it with ask_user and pass it as tool arguments, or try another approach.]`;
+const unsupportedNote = (why) => `[${UNSUPPORTED_ELICITATION_NOTE} (${why}). If the call needs that input, ask the user for it with AskUserQuestion and pass it as tool arguments, or try another approach.]`;
 /** URL 模式表单里「已完成」开关的字段名。 */
 export const URL_COMPLETED_FIELD = "completed";
 /** 表单标题（远端给的 message）最多字符数。 */

package/dist/tools/extension-tools.controller.d.ts

@@ -0,0 +1,14 @@
+import { type OrgContext } from "../orgs/org.guard.js";
+import { type ExtensionToolsOffer, OrgExtensionTools } from "./info.js";
+/**
+ * `GET /api/v1/orgs/:orgId/tools/extensions` (`agents.use`) → `{ extensions }`: the tools of the
+ * extensions enabled in the org, grouped by extension, for the agent form's Tools section (it adds
+ * or removes `{kind:"plugin",plugin,name}` references). Display only; nothing here is model-visible.
+ */
+export declare class ExtensionToolsController {
+    private readonly tools;
+    constructor(tools: OrgExtensionTools);
+    extensions(org: OrgContext): Promise<{
+        extensions: ExtensionToolsOffer[];
+    }>;
+}

package/dist/tools/extension-tools.controller.js

@@ -0,0 +1,37 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Controller, Get, Header, Inject } from "@nestjs/common";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { OrgExtensionTools } from "./info.js";
+/**
+ * `GET /api/v1/orgs/:orgId/tools/extensions` (`agents.use`) → `{ extensions }`: the tools of the
+ * extensions enabled in the org, grouped by extension, for the agent form's Tools section (it adds
+ * or removes `{kind:"plugin",plugin,name}` references). Display only; nothing here is model-visible.
+ */
+let ExtensionToolsController = class ExtensionToolsController {
+    tools;
+    constructor(tools) {
+        this.tools = tools;
+    }
+    async extensions(org) {
+        return { extensions: await this.tools.list(org.orgId) };
+    }
+};
+__decorate([
+    Get("extensions"),
+    Header("cache-control", "private, no-store"),
+    OrgAction("agents.use"),
+    __param(0, CurrentOrg())
+], ExtensionToolsController.prototype, "extensions", null);
+ExtensionToolsController = __decorate([
+    Controller("api/v1/orgs/:orgId/tools"),
+    __param(0, Inject(OrgExtensionTools))
+], ExtensionToolsController);
+export { ExtensionToolsController };

package/dist/tools/info.d.ts

@@ -1,6 +1,8 @@
+import { type LocalizedName, type ToolAnnotations } from "@capybara-hq/plugin-sdk";
 import { ConversationAccess } from "../conversations/access.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
+import { OrgToolSwitches } from "./org-tool-switches.js";
 import { ToolRegistry } from "./registry.js";
 /**
  * Tool presentation metadata for the conversation page (UI refresh B, design spec §6.16.9): the
@@ -11,16 +13,32 @@ export type ToolKind = "command" | "read" | "edit" | "search" | "connector" | "m
 export interface ToolInfo {
     /** The model-visible tool key, as asked for. */
     key: string;
+    /**
+     * Set only for a release-candidate builtin key (old history, tool naming spec §9): the current
+     * tool it stands for. Everything else describes that tool, with `keyArgs` in the old parameter
+     * names the logged input carries. Pages map a call's name through it (the `Agent` row, labels).
+     */
+    aliasOf?: string;
     /** The declared display title (`ToolSpec.title`), or null. */
     title: string | null;
     kind: ToolKind;
+    /** True exactly for the builtin tools that run in the conversation's sandbox. */
+    sandbox: boolean;
     /** The declared key arguments (`ToolSpec.keyArgs`), or []. */
     keyArgs: string[];
+    /**
+     * The local tool name parsed from a connector or extension key (`mcp__crm__delete` -> `delete`),
+     * shown in brackets after the source's display name; null for builtins and unparsable keys.
+     */
+    tool: string | null;
     source: {
         kind: "builtin";
-    } | {
+    }
+    /** `displayName`: the plugin's catalog display name, else its name. */
+     | {
         kind: "extension";
         name: string;
+        displayName: LocalizedName;
     } | {
         kind: "connector";
         id: string;
@@ -31,8 +49,7 @@ export interface ToolInfo {
         kind: "unknown";
     };
 }
-/** Kinds of the kernel builtin tools; a builtin missing here is a plain `tool`. */
-export declare const BUILTIN_TOOL_KINDS: Readonly<Record<string, ToolKind>>;
+export { BUILTIN_TOOL_KINDS } from "./builtin-names.js";
 /** At most this many keys per request, each at most {@link TOOL_INFO_KEY_MAX} characters. */
 export declare const TOOL_INFO_MAX_KEYS = 100;
 export declare const TOOL_INFO_KEY_MAX = 200;
@@ -42,7 +59,7 @@ export interface ToolInfoDeps {
 }
 /**
  * Presentation metadata for `keys` in this org, in request order with repeats dropped. Builtins
- * by name; `<prefix>__<tool>` keys first as a loaded extension's registration, then as a live
+ * by name (a release-candidate builtin key as its current tool, with `aliasOf`); `plugin__<plugin>__<tool>` keys as a loaded extension's registration, and `mcp__<slug>__<tool>` keys as a live
  * connector's current stored tool (its reviewed definition, never a pending one). Anything else
  * comes back as an unknown plain tool.
  *
@@ -68,3 +85,43 @@ export declare class ConversationToolInfo {
     access: Pick<ConversationAccess, "isAccessible">);
     get(orgId: string, conversationId: string, viewerAccountId: string, keys: readonly string[]): Promise<ToolInfo[]>;
 }
+/** One tool of {@link OrgExtensionTools}. Display only, for the agent form. */
+export interface ExtensionToolOffer {
+    /** The tool's registered name (the `name` of a `{kind:"plugin"}` reference). */
+    name: string;
+    /** The model-visible key, `plugin__<plugin>__<name>` (the `toolPolicies` key). */
+    key: string;
+    /** The declared display title (`ToolSpec.title`), or null. */
+    title: string | null;
+    /** The first non-empty line of the tool's description (English, model-facing text). */
+    description: string;
+    annotations: ToolAnnotations;
+    /** The tool's default policy: its `defaultPolicy`, else derived from the annotations. */
+    defaultPolicy: "allow" | "ask";
+    /**
+     * The org turned this tool off (layering spec A §7): still listed, so the form shows it as
+     * unavailable in the agents that selected it.
+     */
+    switchedOff: boolean;
+}
+/** One extension of {@link OrgExtensionTools} with its tools, in registration order. */
+export interface ExtensionToolsOffer {
+    plugin: string;
+    /** The plugin's catalog display name, else its name. */
+    displayName: LocalizedName;
+    tools: ExtensionToolOffer[];
+}
+/**
+ * `GET /orgs/:orgId/tools/extensions`: the tools an agent of this org can reference by
+ * `{kind:"plugin"}` and get at run time, grouped by extension: the extensions loaded on this
+ * replica and enabled in the org (`enabled.ts`, through the host), each with the tools it
+ * registered whose key is valid (`ToolRegistry.forAgent` reports the others unavailable); a tool
+ * the org turned off is listed with `switchedOff`.
+ */
+export declare class OrgExtensionTools {
+    private readonly db;
+    private readonly registry;
+    private readonly switches;
+    constructor(db: KernelDb, registry: Pick<ToolRegistry, "extensionToolSpecs" | "enabledExtensions">, switches: Pick<OrgToolSwitches, "offKeys">);
+    list(orgId: string): Promise<ExtensionToolsOffer[]>;
+}

package/dist/tools/info.js

@@ -7,28 +7,19 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
+import { connectorToolKey, extensionToolKey, parseToolKey, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { ConversationAccess } from "../conversations/access.js";
 import { ApiError } from "../errors.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { UUID_RE } from "../ui/registry.js";
-import { KEY_SEPARATOR, toolKey } from "./naming.js";
-import { ToolRegistry } from "./registry.js";
-/** Kinds of the kernel builtin tools; a builtin missing here is a plain `tool`. */
-export const BUILTIN_TOOL_KINDS = {
-    sandbox_bash: "command",
-    sandbox_read: "read",
-    sandbox_write: "edit",
-    sandbox_edit: "edit",
-    sandbox_glob: "search",
-    sandbox_grep: "search",
-    sandbox_deliver: "tool",
-    tool_search: "meta",
-    skill_load: "meta",
-    skill_write: "meta",
-    read_tool_output: "meta",
-    ask_user: "meta",
-};
+import { BUILTIN_TOOL_KINDS, SANDBOX_TOOL_NAMES } from "./builtin-names.js";
+import { pluginDisplayNames } from "./display-names.js";
+import { isLegacyBuiltinKey, LEGACY_BUILTINS } from "./legacy-keys.js";
+import { toolKeyIssue } from "./naming.js";
+import { OrgToolSwitches } from "./org-tool-switches.js";
+import { policyFromAnnotations, ToolRegistry } from "./registry.js";
+export { BUILTIN_TOOL_KINDS } from "./builtin-names.js";
 /** At most this many keys per request, each at most {@link TOOL_INFO_KEY_MAX} characters. */
 export const TOOL_INFO_MAX_KEYS = 100;
 export const TOOL_INFO_KEY_MAX = 200;
@@ -38,7 +29,7 @@ const display = (spec) => ({
 });
 /**
  * Presentation metadata for `keys` in this org, in request order with repeats dropped. Builtins
- * by name; `<prefix>__<tool>` keys first as a loaded extension's registration, then as a live
+ * by name (a release-candidate builtin key as its current tool, with `aliasOf`); `plugin__<plugin>__<tool>` keys as a loaded extension's registration, and `mcp__<slug>__<tool>` keys as a live
  * connector's current stored tool (its reviewed definition, never a pending one). Anything else
  * comes back as an unknown plain tool.
  *
@@ -55,17 +46,13 @@ const display = (spec) => ({
 export async function toolInfo(deps, orgId, keys) {
     const unique = [...new Set(keys)];
     const builtins = new Map(deps.registry.builtinSpecs().map((s) => [s.name, s]));
-    const extensions = new Map(deps.registry.extensionToolSpecs().map((t) => [toolKey(t.plugin, t.spec.name), t]));
-    const split = (key) => {
-        const i = key.indexOf(KEY_SEPARATOR);
-        return i > 0 ? [key.slice(0, i), key.slice(i + KEY_SEPARATOR.length)] : null;
-    };
+    const extensions = new Map(deps.registry.extensionToolSpecs().map((t) => [extensionToolKey(t.plugin, t.spec.name), t]));
     const slugs = [
         ...new Set(unique.flatMap((k) => {
             if (builtins.has(k) || extensions.has(k))
                 return [];
-            const p = split(k);
-            return p ? [p[0]] : [];
+            const p = parseToolKey(k);
+            return p?.kind === "connector" ? [p.slug] : [];
         })),
     ];
     const connectorRows = slugs.length === 0
@@ -78,15 +65,37 @@ export async function toolInfo(deps, orgId, keys) {
             .where("c.deleted_at", "is", null)
             .where("c.slug", "in", slugs)
             .execute();
-    const connectorTools = new Map(connectorRows.map((r) => [toolKey(r.slug, r.tool), r]));
+    const connectorTools = new Map(connectorRows.map((r) => [connectorToolKey(r.slug, r.tool), r]));
+    const displayNames = await pluginDisplayNames(deps.db, unique.flatMap((k) => {
+        const e = extensions.get(k);
+        return e ? [e.plugin] : [];
+    }));
+    const localTool = (key) => {
+        const p = parseToolKey(key);
+        return p && p.kind !== "builtin" ? p.tool : null;
+    };
+    const builtinInfo = (key, name, spec) => ({
+        key,
+        ...display(spec),
+        kind: BUILTIN_TOOL_KINDS[name] ?? "tool",
+        sandbox: SANDBOX_TOOL_NAMES.includes(name),
+        tool: null,
+        source: { kind: "builtin" },
+    });
     return unique.map((key) => {
         const b = builtins.get(key);
-        if (b) {
+        if (b)
+            return builtinInfo(key, key, b);
+        const legacy = isLegacyBuiltinKey(key) ? LEGACY_BUILTINS[key] : undefined;
+        const current = legacy && builtins.get(legacy.name);
+        if (legacy && current) {
+            // the logged input of an rc call names the old parameters: key arguments in those names
+            const oldName = new Map(Object.entries(legacy.params).map(([o, n]) => [n, o]));
+            const info = builtinInfo(key, legacy.name, current);
             return {
-                key,
-                ...display(b),
-                kind: BUILTIN_TOOL_KINDS[key] ?? "tool",
-                source: { kind: "builtin" },
+                ...info,
+                aliasOf: legacy.name,
+                keyArgs: info.keyArgs.map((a) => oldName.get(a) ?? a),
             };
         }
         const e = extensions.get(key);
@@ -95,7 +104,13 @@ export async function toolInfo(deps, orgId, keys) {
                 key,
                 ...display(e.spec),
                 kind: "tool",
-                source: { kind: "extension", name: e.plugin },
+                sandbox: false,
+                tool: e.spec.name,
+                source: {
+                    kind: "extension",
+                    name: e.plugin,
+                    displayName: displayNames.get(e.plugin) ?? { zh: e.plugin, en: e.plugin },
+                },
             };
         const c = connectorTools.get(key);
         if (c) {
@@ -104,10 +119,20 @@ export async function toolInfo(deps, orgId, keys) {
                 key,
                 ...display(c.spec),
                 kind: "connector",
+                sandbox: false,
+                tool: c.tool,
                 source: { kind: "connector", id: c.id, name: c.name },
             };
         }
-        return { key, title: null, kind: "tool", keyArgs: [], source: { kind: "unknown" } };
+        return {
+            key,
+            title: null,
+            kind: "tool",
+            sandbox: false,
+            keyArgs: [],
+            tool: localTool(key),
+            source: { kind: "unknown" },
+        };
     });
 }
 /** `GET /conversations/:id/tools`: {@link toolInfo} for a conversation the viewer can read. */
@@ -137,3 +162,64 @@ ConversationToolInfo = __decorate([
     __param(2, Inject(ConversationAccess))
 ], ConversationToolInfo);
 export { ConversationToolInfo };
+/**
+ * `GET /orgs/:orgId/tools/extensions`: the tools an agent of this org can reference by
+ * `{kind:"plugin"}` and get at run time, grouped by extension: the extensions loaded on this
+ * replica and enabled in the org (`enabled.ts`, through the host), each with the tools it
+ * registered whose key is valid (`ToolRegistry.forAgent` reports the others unavailable); a tool
+ * the org turned off is listed with `switchedOff`.
+ */
+let OrgExtensionTools = class OrgExtensionTools {
+    db;
+    registry;
+    switches;
+    constructor(db, registry, switches) {
+        this.db = db;
+        this.registry = registry;
+        this.switches = switches;
+    }
+    async list(orgId) {
+        const [enabled, off] = await Promise.all([
+            this.registry.enabledExtensions(orgId),
+            this.switches.offKeys(orgId),
+        ]);
+        const groups = new Map();
+        for (const t of this.registry.extensionToolSpecs()) {
+            if (!enabled.has(t.plugin))
+                continue;
+            const key = extensionToolKey(t.plugin, t.spec.name);
+            if (toolKeyIssue(key) !== null)
+                continue;
+            const tools = groups.get(t.plugin) ?? [];
+            if (tools.some((x) => x.name === t.spec.name))
+                continue;
+            tools.push({
+                name: t.spec.name,
+                key,
+                title: display(t.spec).title,
+                description: firstLine(t.spec.description),
+                annotations: { ...(t.spec.annotations ?? {}) },
+                defaultPolicy: t.spec.defaultPolicy ?? policyFromAnnotations(t.spec.annotations),
+                switchedOff: off.has(key),
+            });
+            groups.set(t.plugin, tools);
+        }
+        const names = await pluginDisplayNames(this.db.db, [...groups.keys()]);
+        return [...groups].map(([plugin, tools]) => ({
+            plugin,
+            displayName: names.get(plugin) ?? { zh: plugin, en: plugin },
+            tools,
+        }));
+    }
+};
+OrgExtensionTools = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(ToolRegistry)),
+    __param(2, Inject(OrgToolSwitches))
+], OrgExtensionTools);
+export { OrgExtensionTools };
+const firstLine = (s) => (typeof s === "string" ? s : "")
+    .split("\n")
+    .map((l) => l.trim())
+    .find((l) => l !== "") ?? "";

package/dist/tools/legacy-data.d.ts

@@ -0,0 +1,34 @@
+import { type AgentDefinition } from "../agents/definition.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import type { KernelLogger } from "../log.js";
+import { type LegacyScope } from "./legacy-keys.js";
+/**
+ * Stored release-candidate tool keys (tool naming spec §8): the scope that reads an rc
+ * `<x>__<tool>` key in an org, the stored-definition readers that use it, and the startup notice
+ * for the rows migration 0063 could not map. No in-process state: each call reads PostgreSQL.
+ */
+/**
+ * What an rc `<x>__<tool>` key can name in `orgId`: the org's live connector slugs and the
+ * deployment's extension names (installed ones and config-declared ones, which claim their name
+ * in `extension_name_owners`). Migration 0063 reads the same two sources.
+ */
+export declare function loadLegacyScope(db: KernelSchemaDb, orgId: string): Promise<LegacyScope>;
+/**
+ * A stored agent definition of `orgId` with every rc key it can map read as the current key
+ * ({@link normalizeStoredDefinition}); the scope is read only when the definition holds an rc
+ * `<x>__<tool>` key.
+ */
+export declare function normalizeStoredDefinitionIn(db: KernelSchemaDb, orgId: string, def: unknown): Promise<AgentDefinition>;
+/** A stored agent template (or any template-shaped value) of `orgId` in current keys. */
+export declare function normalizeTemplateIn<T>(db: KernelSchemaDb, orgId: string, t: T): Promise<T>;
+/**
+ * Rows still holding an rc tool key after migration 0063: grants and pending approvals and
+ * questions it could not map (an ambiguous or unknown `<x>__<tool>`). Read-only.
+ */
+export declare function countLegacyToolKeys(db: KernelSchemaDb): Promise<number>;
+/**
+ * The startup notice (spec §8.2): one WARN `tools.legacy_key_unmapped` with the count of rows
+ * still holding an rc key, only when there are any. A grant that no longer matches stops applying
+ * (the person is asked again), so this is a notice, not a failure.
+ */
+export declare function warnLegacyToolKeys(db: KernelSchemaDb, log: Pick<KernelLogger, "warn">): Promise<void>;

package/dist/tools/legacy-data.js

@@ -0,0 +1,76 @@
+import { sql } from "kysely";
+import { needsLegacyScope, normalizeStoredDefinition, normalizeToolKeys, } from "../agents/definition.js";
+import { LEGACY_BUILTINS } from "./legacy-keys.js";
+/**
+ * Stored release-candidate tool keys (tool naming spec §8): the scope that reads an rc
+ * `<x>__<tool>` key in an org, the stored-definition readers that use it, and the startup notice
+ * for the rows migration 0063 could not map. No in-process state: each call reads PostgreSQL.
+ */
+/**
+ * What an rc `<x>__<tool>` key can name in `orgId`: the org's live connector slugs and the
+ * deployment's extension names (installed ones and config-declared ones, which claim their name
+ * in `extension_name_owners`). Migration 0063 reads the same two sources.
+ */
+export async function loadLegacyScope(db, orgId) {
+    const [connectors, installs, owners] = await Promise.all([
+        db
+            .selectFrom("connectors")
+            .select(["id", "slug"])
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .execute(),
+        db.selectFrom("extension_installs").select("name").execute(),
+        db.selectFrom("extension_name_owners").select("name").execute(),
+    ]);
+    return {
+        connectorSlugs: new Set(connectors.map((r) => r.slug)),
+        connectorSlugById: new Map(connectors.map((r) => [r.id, r.slug])),
+        extensionNames: new Set([...installs, ...owners].map((r) => r.name)),
+    };
+}
+/**
+ * A stored agent definition of `orgId` with every rc key it can map read as the current key
+ * ({@link normalizeStoredDefinition}); the scope is read only when the definition holds an rc
+ * `<x>__<tool>` key.
+ */
+export async function normalizeStoredDefinitionIn(db, orgId, def) {
+    return normalizeStoredDefinition(def, needsLegacyScope(def) ? await loadLegacyScope(db, orgId) : undefined);
+}
+/** A stored agent template (or any template-shaped value) of `orgId` in current keys. */
+export async function normalizeTemplateIn(db, orgId, t) {
+    return normalizeToolKeys(t, needsLegacyScope(t) ? await loadLegacyScope(db, orgId) : undefined);
+}
+/**
+ * The SQL test for an rc key, the predicate of migration 0063's partial indexes (so the count
+ * below reads only those, nearly empty, indexes): an old builtin name, or `<x>__<tool>` not in the
+ * current `mcp__` / `plugin__` format.
+ */
+const legacyKeySql = (col) => sql `(${col} = ANY (ARRAY[${sql.join(Object.keys(LEGACY_BUILTINS).map((k) => sql.lit(k)))}]::text[]) OR (${col} ~ '^[a-z0-9][a-z0-9_-]*__.' AND ${col} !~ '^(mcp|plugin)__'))`;
+/**
+ * Rows still holding an rc tool key after migration 0063: grants and pending approvals and
+ * questions it could not map (an ambiguous or unknown `<x>__<tool>`). Read-only.
+ */
+export async function countLegacyToolKeys(db) {
+    const r = await sql `
+    SELECT
+      (SELECT count(*) FROM capybara.tool_grants WHERE ${legacyKeySql(sql.ref("tool_key"))})
+      + (SELECT count(*) FROM capybara.conversation_tool_grants
+         WHERE ${legacyKeySql(sql.ref("tool_key"))})
+      + (SELECT count(*) FROM capybara.approvals
+         WHERE status = 'pending' AND ${legacyKeySql(sql.ref("tool_key"))})
+      + (SELECT count(*) FROM capybara.questions
+         WHERE status = 'pending' AND ${legacyKeySql(sql.raw("(spec->>'toolKey')"))})
+      AS n
+  `.execute(db);
+    return Number(r.rows[0]?.n ?? 0);
+}
+/**
+ * The startup notice (spec §8.2): one WARN `tools.legacy_key_unmapped` with the count of rows
+ * still holding an rc key, only when there are any. A grant that no longer matches stops applying
+ * (the person is asked again), so this is a notice, not a failure.
+ */
+export async function warnLegacyToolKeys(db, log) {
+    const count = await countLegacyToolKeys(db);
+    if (count > 0)
+        log.warn("tools.legacy_key_unmapped", { count });
+}

package/dist/tools/legacy-keys.d.ts

@@ -0,0 +1,51 @@
+import { type BuiltinName } from "./builtin-names.js";
+/**
+ * The release-candidate builtin tool names (tool naming spec §8.1). FROZEN: it describes the names
+ * of the 0.1.0 release candidates and never grows. Old keys stay in logs, recordings and stored
+ * configuration; this map is how the kernel reads them. `check:terms` exempts this file.
+ */
+export interface LegacyBuiltin {
+    /** The new name. */
+    name: BuiltinName;
+    /** Old parameter name -> new parameter name (only the renamed ones). */
+    params: Readonly<Record<string, string>>;
+    /** New parameters whose value is in milliseconds where the old one was in seconds (× 1000). */
+    msParams?: readonly string[];
+}
+export declare const LEGACY_BUILTINS: Readonly<Record<string, LegacyBuiltin>>;
+/** Is `key` a release-candidate builtin name? */
+export declare const isLegacyBuiltinKey: (key: string) => boolean;
+/** What a connector slug / extension name can be, to read an old `<x>__<tool>` key. */
+export interface LegacyScope {
+    connectorSlugs: ReadonlySet<string>;
+    extensionNames: ReadonlySet<string>;
+    /**
+     * Connector id -> slug, for reading a stored definition's connector refs when a key is
+     * ambiguous (a slug that is also an extension name); optional.
+     */
+    connectorSlugById?: ReadonlyMap<string, string>;
+}
+/**
+ * Is `key` an rc `<x>__<tool>` key, which only a {@link LegacyScope} can map? Keys in the current
+ * format (`mcp__…`, `plugin__…`) never are.
+ */
+export declare const isLegacyPrefixedKey: (key: string) => boolean;
+/**
+ * The current key of a release-candidate key: a builtin by the frozen map; `<x>__<tool>` becomes
+ * `mcp__x__tool` when `x` is only a connector slug in `scope`, `plugin__x__tool` when only an
+ * extension name, else null (ambiguous, unknown, or not an old key; a key in the current format
+ * is never mapped again).
+ */
+export declare function legacyToolKey(key: string, scope?: LegacyScope): string | null;
+/** The input of an old builtin call in the current parameter names (seconds -> milliseconds). */
+export declare function legacyToolInput(oldKey: string, input: unknown): unknown;
+/** The model-visible hint for a call to an old builtin key; null for any other key. */
+export declare function legacyHint(key: string): string | null;
+/**
+ * The current key(s) an rc key stands for, to name in a refusal when a definition is saved with
+ * it: a builtin's new name; for `<x>__<tool>`, the candidates among `known` (the agent's tool
+ * keys), else both `mcp__<x>__<tool>` and `plugin__<x>__<tool>`. Empty when `key` is no rc key.
+ */
+export declare function legacyKeyCandidates(key: string, known?: ReadonlySet<string>): string[];
+/** The refusal text for saving rc key `key` (null when it is none): names the new key(s). */
+export declare function legacyKeySaveText(key: string, known?: ReadonlySet<string>): string | null;