@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/tools/info.js

@@ -1,21 +1,25 @@
+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 { 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";
-/** 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;
@@ -25,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.
  *
@@ -42,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
@@ -65,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);
@@ -82,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) {
@@ -91,23 +119,107 @@ 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. */
-export class ConversationToolInfo {
-    d;
-    constructor(d) {
-        this.d = d;
+let ConversationToolInfo = class ConversationToolInfo {
+    db;
+    registry;
+    access;
+    constructor(db, registry, 
+    /** Conversation visibility (the same rule as the events API). */
+    access) {
+        this.db = db;
+        this.registry = registry;
+        this.access = access;
     }
     async get(orgId, conversationId, viewerAccountId, keys) {
         if (!UUID_RE.test(conversationId) ||
-            !(await this.d.isAccessible(orgId, conversationId, viewerAccountId))) {
+            !(await this.access.isAccessible(orgId, conversationId, viewerAccountId))) {
             throw new ApiError("conversation.not_found", "Conversation not found");
         }
-        return toolInfo(this.d, orgId, keys);
+        return toolInfo({ db: this.db.db, registry: this.registry }, orgId, keys);
     }
-}
+};
+ConversationToolInfo = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(ToolRegistry)),
+    __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/job-ids.d.ts

@@ -0,0 +1,13 @@
+/** The periodic drift scan (`@LockedInterval`, tools/jobs.ts). */
+export declare const DRIFT_SCAN_JOB = "drift-scan";
+/** The BullMQ repeatable scheduler the scan had before it became `@LockedInterval` (retired). */
+export declare const DRIFT_SCHEDULER_ID = "drift-scan-interval";
+/**
+ * 单个连接器的漂移检查任务名（维护队列上的一次性任务：生产方是 `ToolDrift`，消费方是
+ * `MaintenanceProcessor`）。
+ */
+export declare const DRIFT_CONNECTOR_JOB = "drift-connector";
+/** The hourly cleanup of expired tool output archives (`@LockedCron`, tools/jobs.ts). */
+export declare const OUTPUT_CLEANUP_JOB = "output-cleanup";
+/** The BullMQ repeatable scheduler the cleanup had before it became `@LockedCron` (retired). */
+export declare const OUTPUT_CLEANUP_SCHEDULER_ID = "output-cleanup-hourly";

package/dist/tools/job-ids.js

@@ -0,0 +1,15 @@
+// The tools' job names and the retired scheduler ids: a leaf module (no service imports), read by
+// the maintenance queue's retirement list.
+/** The periodic drift scan (`@LockedInterval`, tools/jobs.ts). */
+export const DRIFT_SCAN_JOB = "drift-scan";
+/** The BullMQ repeatable scheduler the scan had before it became `@LockedInterval` (retired). */
+export const DRIFT_SCHEDULER_ID = "drift-scan-interval";
+/**
+ * 单个连接器的漂移检查任务名（维护队列上的一次性任务：生产方是 `ToolDrift`，消费方是
+ * `MaintenanceProcessor`）。
+ */
+export const DRIFT_CONNECTOR_JOB = "drift-connector";
+/** The hourly cleanup of expired tool output archives (`@LockedCron`, tools/jobs.ts). */
+export const OUTPUT_CLEANUP_JOB = "output-cleanup";
+/** The BullMQ repeatable scheduler the cleanup had before it became `@LockedCron` (retired). */
+export const OUTPUT_CLEANUP_SCHEDULER_ID = "output-cleanup-hourly";

package/dist/tools/jobs.d.ts

@@ -0,0 +1,24 @@
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { ToolDrift } from "./drift.js";
+/**
+ * The tools' periodic jobs, each run once per tick across replicas: the tool drift scan
+ * (`drift-scan`, every `tools.driftIntervalHours` and once right after the start, as the old
+ * repeatable scheduler's first run: `@LockedInterval` with `runOnStart`; a repeated scan in the
+ * same period enqueues nothing new, its job ids are per period) and the hourly cleanup of expired
+ * tool output archives (`output-cleanup`: `@LockedCron`).
+ */
+export declare class ToolJobs {
+    private readonly drift;
+    private readonly db;
+    readonly config: KernelConfigService;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(drift: Pick<ToolDrift, "scan">, db: KernelDb, config: KernelConfigService, lockService: LockService, log: KernelLogger);
+    /** Enqueues a drift check of every active connector not checked in this period. */
+    scanDrift(): Promise<void>;
+    /** Deletes expired tool output archives (in batches, no long transaction). */
+    cleanupOutputs(): Promise<void>;
+}

package/dist/tools/jobs.js

@@ -0,0 +1,69 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { LockedCron } from "../infra/schedule/locked-cron.decorator.js";
+import { LockedInterval } from "../infra/schedule/locked-interval.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { ToolDrift } from "./drift.js";
+import { DRIFT_SCAN_JOB, OUTPUT_CLEANUP_JOB } from "./job-ids.js";
+import { deleteExpiredOutputs } from "./outputs.js";
+/**
+ * The tools' periodic jobs, each run once per tick across replicas: the tool drift scan
+ * (`drift-scan`, every `tools.driftIntervalHours` and once right after the start, as the old
+ * repeatable scheduler's first run: `@LockedInterval` with `runOnStart`; a repeated scan in the
+ * same period enqueues nothing new, its job ids are per period) and the hourly cleanup of expired
+ * tool output archives (`output-cleanup`: `@LockedCron`).
+ */
+let ToolJobs = class ToolJobs {
+    drift;
+    db;
+    config;
+    lockService;
+    log;
+    constructor(drift, db, config, lockService, log) {
+        this.drift = drift;
+        this.db = db;
+        this.config = config;
+        this.lockService = lockService;
+        this.log = log;
+    }
+    /** Enqueues a drift check of every active connector not checked in this period. */
+    async scanDrift() {
+        const n = await this.drift.scan();
+        if (n > 0)
+            this.log.info("tool drift checks enqueued", { count: n });
+    }
+    /** Deletes expired tool output archives (in batches, no long transaction). */
+    async cleanupOutputs() {
+        const n = await deleteExpiredOutputs(this.db.db);
+        if (n > 0)
+            this.log.info("expired tool outputs deleted", { count: n });
+    }
+};
+__decorate([
+    LockedInterval(DRIFT_SCAN_JOB, (c) => c.tools.driftIntervalHours * 3_600_000, {
+        runOnStart: true,
+    })
+], ToolJobs.prototype, "scanDrift", null);
+__decorate([
+    LockedCron("0 * * * *", { name: OUTPUT_CLEANUP_JOB })
+], ToolJobs.prototype, "cleanupOutputs", null);
+ToolJobs = __decorate([
+    Injectable(),
+    __param(0, Inject(ToolDrift)),
+    __param(1, Inject(KernelDb)),
+    __param(2, Inject(KernelConfigService)),
+    __param(3, Inject(LockService)),
+    __param(4, Inject(KERNEL_LOGGER))
+], ToolJobs);
+export { ToolJobs };

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 ")}`;
+}