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

package/dist/tools/connectors.service.js

@@ -8,7 +8,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { randomUUID } from "node:crypto";
-import { ToolError, } from "@capybara-hq/plugin-sdk";
+import { connectorToolKey, ToolError, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { z } from "zod";
@@ -25,7 +25,7 @@ import { OrgLock } from "../orgs/org-lock.js";
 import { CredentialMissing, Credentials, isOAuth, } from "./credentials.js";
 import { snapshot, ToolDrift, toolIssue, } from "./drift.js";
 import { endpointCredentialIssues, endpointView } from "./endpoint.js";
-import { deriveSlug, isValidSlug, SLUG_RULE, toolKey } from "./naming.js";
+import { deriveSlug, isValidSlug, SLUG_RULE } from "./naming.js";
 import { checkOAuthUrl, discoverMcp, OAuthSetupError, oauthHttpOptions, pickAuthMethod, registerClient, } from "./oauth/discovery.js";
 import { callbackUrl, publicUrlRequired } from "./oauth/flow-paths.js";
 import { OAuthGrantError, OAuthUnavailable, tokenRequest, } from "./oauth/tokens.js";
@@ -619,7 +619,7 @@ let ConnectorsService = class ConnectorsService {
             issues = snap.issues;
             tools = snap.rows.map((r) => ({
                 name: r.name,
-                key: toolKey(slug, r.name),
+                key: connectorToolKey(slug, r.name),
                 description: r.spec.description,
                 inputSchema: r.spec.inputSchema,
                 annotations: r.spec.annotations ?? null,
@@ -720,7 +720,7 @@ let ConnectorsService = class ConnectorsService {
                 const next = t.pending_spec;
                 return {
                     name: t.name,
-                    key: toolKey(r.slug, t.name),
+                    key: connectorToolKey(r.slug, t.name),
                     description: spec.description,
                     inputSchema: spec.inputSchema,
                     annotations: spec.annotations ?? null,

package/dist/tools/display-names.d.ts

@@ -0,0 +1,9 @@
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+/**
+ * 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 declare function pluginDisplayNames(db: KernelSchemaDb, names: readonly string[]): Promise<Map<string, LocalizedName>>;

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/info.d.ts

@@ -1,3 +1,4 @@
+import { type LocalizedName } 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";
@@ -11,16 +12,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 +48,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 +58,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.
  *

package/dist/tools/info.js

@@ -7,28 +7,17 @@ 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 { 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 { 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",
-};
+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 +27,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 +44,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 +63,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 +102,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 +117,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. */

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;

package/dist/tools/legacy-keys.js

@@ -0,0 +1,115 @@
+import { BUILTIN } from "./builtin-names.js";
+export const LEGACY_BUILTINS = Object.freeze({
+    sandbox_bash: {
+        name: BUILTIN.Bash,
+        params: { timeoutSeconds: "timeout" },
+        msParams: ["timeout"],
+    },
+    sandbox_read: { name: BUILTIN.Read, params: { path: "file_path" } },
+    sandbox_write: { name: BUILTIN.Write, params: { path: "file_path" } },
+    sandbox_edit: {
+        name: BUILTIN.Edit,
+        params: {
+            path: "file_path",
+            oldText: "old_string",
+            newText: "new_string",
+            replaceAll: "replace_all",
+        },
+    },
+    sandbox_glob: { name: BUILTIN.Glob, params: {} },
+    sandbox_grep: { name: BUILTIN.Grep, params: { ignoreCase: "-i" } },
+    sandbox_deliver: { name: BUILTIN.Deliver, params: { path: "file_path" } },
+    skill_load: { name: BUILTIN.Skill, params: { name: "skill" } },
+    skill_write: { name: BUILTIN.SkillWrite, params: {} },
+    ask_user: { name: BUILTIN.AskUserQuestion, params: {} },
+    read_tool_output: { name: BUILTIN.ReadToolOutput, params: {} },
+    tool_search: { name: BUILTIN.ToolSearch, params: { limit: "max_results" } },
+    agent: { name: BUILTIN.Agent, params: {} },
+});
+/** Is `key` a release-candidate builtin name? */
+export const isLegacyBuiltinKey = (key) => Object.hasOwn(LEGACY_BUILTINS, key);
+/** A key in the current format for connector and extension tools (`mcp__…`, `plugin__…`). */
+const CURRENT_PREFIXED_RE = /^(mcp|plugin)__/;
+/** An rc connector or extension key `<x>__<tool>` (the SQL of migration 0063 uses the same test). */
+const LEGACY_PREFIXED_RE = /^[a-z0-9][a-z0-9_-]*__./;
+/**
+ * Is `key` an rc `<x>__<tool>` key, which only a {@link LegacyScope} can map? Keys in the current
+ * format (`mcp__…`, `plugin__…`) never are.
+ */
+export const isLegacyPrefixedKey = (key) => LEGACY_PREFIXED_RE.test(key) && !CURRENT_PREFIXED_RE.test(key);
+/**
+ * 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 function legacyToolKey(key, scope) {
+    if (isLegacyBuiltinKey(key))
+        return LEGACY_BUILTINS[key].name;
+    if (scope === undefined || !isLegacyPrefixedKey(key))
+        return null;
+    const i = key.indexOf("__");
+    if (i <= 0 || i + 2 >= key.length)
+        return null;
+    const head = key.slice(0, i);
+    const tool = key.slice(i + 2);
+    const connector = scope.connectorSlugs.has(head);
+    const extension = scope.extensionNames.has(head);
+    if (connector === extension)
+        return null;
+    return connector ? `mcp__${head}__${tool}` : `plugin__${head}__${tool}`;
+}
+/** The input of an old builtin call in the current parameter names (seconds -> milliseconds). */
+export function legacyToolInput(oldKey, input) {
+    if (!isLegacyBuiltinKey(oldKey))
+        return input;
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return input;
+    const { params, msParams } = LEGACY_BUILTINS[oldKey];
+    const out = {};
+    for (const [k, v] of Object.entries(input)) {
+        const next = Object.hasOwn(params, k) ? params[k] : k;
+        out[next] = msParams?.includes(next) === true && typeof v === "number" ? v * 1000 : v;
+    }
+    return out;
+}
+/** The new parameters of the builtins whose parameters were renamed (model-visible hint text). */
+const HINT_PARAMS = {
+    Bash: "command, description, timeout in milliseconds",
+    Read: "file_path, offset, limit",
+    Write: "file_path, content",
+    Edit: "file_path, old_string, new_string, replace_all",
+    Grep: "pattern, path, glob, -i, output_mode, -n, -A, -B, -C, head_limit, offset",
+    Deliver: "file_path, name",
+    Skill: "skill, args",
+    ToolSearch: "query, max_results",
+};
+/** The model-visible hint for a call to an old builtin key; null for any other key. */
+export function legacyHint(key) {
+    if (!isLegacyBuiltinKey(key))
+        return null;
+    const { name } = LEGACY_BUILTINS[key];
+    const params = HINT_PARAMS[name];
+    return `Tool "${key}" no longer exists; it is now "${name}"${params === undefined ? "" : ` (parameters: ${params})`}.`;
+}
+/**
+ * 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 function legacyKeyCandidates(key, known) {
+    if (isLegacyBuiltinKey(key))
+        return [LEGACY_BUILTINS[key].name];
+    if (!isLegacyPrefixedKey(key))
+        return [];
+    const all = [`mcp__${key}`, `plugin__${key}`];
+    const hit = all.filter((k) => known?.has(k) === true);
+    return hit.length > 0 ? hit : all;
+}
+/** The refusal text for saving rc key `key` (null when it is none): names the new key(s). */
+export function legacyKeySaveText(key, known) {
+    const c = legacyKeyCandidates(key, known);
+    if (c.length === 0)
+        return null;
+    return `"${key}" is a release-candidate tool key; use ${c.map((x) => `"${x}"`).join(" or ")}`;
+}

package/dist/tools/naming.d.ts

@@ -1,14 +1,12 @@
 /**
  * 工具命名（Global Constraints）：模型可见的工具 key 必须匹配 `^[a-zA-Z0-9_-]{1,64}$`；
- * 插件工具为 `<plugin>__<tool>`，连接器工具为 `<connectorSlug>__<tool>`，内置工具就是其名字本身。
+ * 插件工具为 `plugin__<plugin>__<tool>`，连接器工具为 `mcp__<connectorSlug>__<tool>`（拼与拆见 SDK 的 tool-key.ts），内置工具就是其名字本身。
  * 超长或含非法字符的 key 一律报出来，不截断、不猜。
  */
 export declare const TOOL_KEY_RE: RegExp;
 export declare const TOOL_KEY_MAX = 64;
 /** 连接器 slug：小写字母开头，小写字母 / 数字 / 下划线，最长 24。 */
 export declare const APP_SLUG_RE: RegExp;
-/** 前缀与工具名之间的分隔符。 */
-export declare const KEY_SEPARATOR = "__";
 /**
  * slug 是否合法：除正则外，不得含连续下划线、不得以下划线结尾——否则 `a__b` + `c` 与 `a` + `b__c`
  * 会拼出同一个 key。
@@ -21,7 +19,5 @@ export declare const SLUG_RULE = "Slug must start with a lowercase letter, conta
  * 截到 24 位（再去掉尾部下划线）。推导不出合法 slug（如名称全是中文）时返回 null，由调用方要求显式给出。
  */
 export declare function deriveSlug(name: string): string | null;
-/** 拼 `<prefix>__<name>`。 */
-export declare function toolKey(prefix: string, name: string): string;
 /** key 不合法时返回英文原因，合法时返回 null。 */
 export declare function toolKeyIssue(key: string): string | null;