@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/tools/registry.js

@@ -0,0 +1,481 @@
+import { createHash } from "node:crypto";
+import { readOrgSettings } from "../orgs/settings.service.js";
+import { estimateTokens } from "../runtime/context/tokens.js";
+import { SUBAGENT_LIMIT_DEFAULTS, subagentLimits } from "../runtime/subagents/limits.js";
+import { resolveRoster } from "../runtime/subagents/roster.js";
+import { AGENT_TOOL, agentToolSpec } from "./builtins/agent.js";
+import { SANDBOX_TOOL_NAMES } from "./builtins/sandbox/names.js";
+import { toolKey, toolKeyIssue } from "./naming.js";
+/**
+ * 内核内置工具的名字（Task 10 / Task 19 实现；M5 T8 加沙箱工具）。保存 agent 时内置工具引用按这份清单校验，
+ * 不依赖当前是否已注册，避免实现落地顺序影响已保存的定义；运行时未注册的照常报不可用。
+ * `skill_write`（M5 T15）由 agent 定义显式引用才可用（负责人决定 agent 能否改自己的技能）。
+ */
+export const BUILTIN_TOOL_NAMES = [
+    "ask_user",
+    "read_tool_output",
+    "tool_search",
+    "skill_load",
+    "skill_write",
+    ...SANDBOX_TOOL_NAMES,
+    // phase C: dispatches sub-agents; its description is built per agent from the roster
+    "agent",
+];
+/** 键排序、去掉 undefined 的 JSON（jsonb 不保留键顺序，指纹必须与顺序无关）。 */
+export function canonicalJson(v) {
+    if (Array.isArray(v))
+        return `[${v.map(canonicalJson).join(",")}]`;
+    if (v !== null && typeof v === "object") {
+        const entries = Object.entries(v)
+            .filter(([, x]) => x !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([k, x]) => `${JSON.stringify(k)}:${canonicalJson(x)}`).join(",")}}`;
+    }
+    return JSON.stringify(v);
+}
+/** The first 16 hex digits of sha256(canonicalJson(v)): a fingerprint independent of key order. */
+export function contentHash(v) {
+    return createHash("sha256").update(canonicalJson(v)).digest("hex").slice(0, 16);
+}
+/**
+ * `ToolSpec` fields that are display only (UI refresh B): never sent to the model and left out of
+ * the definition fingerprint, so adding or changing them never changes `model_call.request.tools`,
+ * never sends a connector tool to drift review and never invalidates a remembered grant.
+ */
+export const DISPLAY_ONLY_SPEC_FIELDS = ["title", "keyArgs"];
+/** A tool spec without its {@link DISPLAY_ONLY_SPEC_FIELDS} (non-objects unchanged). */
+export function withoutDisplayFields(spec) {
+    if (spec === null || typeof spec !== "object" || Array.isArray(spec))
+        return spec;
+    const out = { ...spec };
+    for (const f of DISPLAY_ONLY_SPEC_FIELDS)
+        delete out[f];
+    return out;
+}
+/**
+ * Tool definition fingerprint: {@link contentHash} of the spec without its display-only fields
+ * (`title`, `keyArgs`). Specs without them hash exactly as before.
+ */
+export function specHash(spec) {
+    return contentHash(withoutDisplayFields(spec));
+}
+/** 由注解推导默认策略：只读 → allow；其余（破坏性 / 无注解）→ ask。 */
+export function policyFromAnnotations(a) {
+    return a?.readOnlyHint === true ? "allow" : "ask";
+}
+/** 内置 `tool_search` 的名字（由注册表按组织设置与阈值自动加入，不进 agent 定义）。 */
+const TOOL_SEARCH = "tool_search";
+/** 内置 `skill_load` 的名字（对话日志里有技能目录快照时由注册表自动加入，不进 agent 定义）。 */
+const SKILL_LOAD = "skill_load";
+/** 工具定义（模型可见三项）的估算 token 数（与请求估算同一口径）。 */
+function estimateToolTokens(tools) {
+    return estimateTokens([], [], tools.map((t) => ({
+        name: t.key,
+        description: t.spec.description,
+        inputSchema: t.spec.inputSchema,
+    })));
+}
+const sourceId = (s) => s.kind === "builtin"
+    ? `builtin:${s.name}`
+    : s.kind === "plugin"
+        ? `plugin:${s.plugin}:${s.name}`
+        : `connector:${s.connectorId}:${s.name}`;
+/**
+ * Tool registry: resolves the references in an agent definition into the tools available for this
+ * run. Not cached (reads PG and the host live every time), so changes take effect right away across
+ * replicas.
+ *
+ * Availability:
+ * - builtin: in `builtins`;
+ * - extension tools: the extension is loaded and registered the tool, and this org enabled the
+ *   extension (`extension_org_configs.enabled`, spec 2.2 "installed at deployment level, enabled at
+ *   org level"; required bootstrap plugins are enabled in every org, `enabled.ts`);
+ * - connector tools: the connector belongs to this org, is not deleted or disabled, the connector is
+ *   installed, the tool status is `enabled` and the key is valid.
+ *   `tools: "all"` takes only enabled tools; disabled / pending-review ones count as deliberately
+ *   turned off by an admin and are not reported; named tools report their reason one by one.
+ * Only the first of a key is kept; the same source referenced twice is deduplicated silently,
+ * different sources with the same key report a duplicate.
+ */
+export class ToolRegistry {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** `host.list("connector")` 中 `kind` 匹配的第一个实现；未安装返回 undefined。 */
+    findConnector(kind) {
+        for (const e of this.deps.host.list("connector")) {
+            const impl = e.impl;
+            if (impl?.kind === kind)
+                return impl;
+        }
+        return undefined;
+    }
+    /** 同 {@link findConnector}，未安装时抛错。 */
+    connector(kind) {
+        const c = this.findConnector(kind);
+        if (!c)
+            throw new Error(`connector ${kind} is not installed`);
+        return c;
+    }
+    /**
+     * The handler of a builtin / extension tool (for the execution pipeline); connector tools run
+     * through the connector and return undefined. Also undefined when the extension was unloaded and so
+     * on. Extension tools resolve the current instance live and call through the instance's in-flight
+     * tracker (C17): on revocation it drains first and aborts at the limit, ending with
+     * `ExtensionUnloadedError` (the pipeline turns it into an English error result for the model).
+     */
+    handler(source) {
+        if (source.kind === "builtin") {
+            return this.deps.builtins.find((b) => b.spec.name === source.name)?.run;
+        }
+        if (source.kind === "plugin") {
+            const t = this.deps.host
+                .tools()
+                .find((x) => x.plugin === source.plugin && x.spec.name === source.name);
+            if (!t)
+                return undefined;
+            return (input, ctx) => t.inflight.run(ctx.signal, (signal) => t.handler(input, { ...ctx, signal }));
+        }
+        return undefined;
+    }
+    /** The registered builtin tools' specs (display metadata for `tools/info.ts`). */
+    builtinSpecs() {
+        return this.deps.builtins.map((b) => b.spec);
+    }
+    /** The loaded extensions' registered tool specs, with their extension's name. */
+    extensionToolSpecs() {
+        return this.deps.host.tools().map((t) => ({ plugin: t.plugin, spec: t.spec }));
+    }
+    /** 已安装连接器的 kind 列表（去重，按加载顺序）。 */
+    connectorKinds() {
+        return [...new Set(this.deps.host.list("connector").map((e) => e.impl.kind))];
+    }
+    /**
+     * 保存 agent 时校验工具引用（只看「存在」，停用 / 待复核 / 插件未启用等运行时状态不拒绝，由 `forAgent` 报不可用）：
+     * - 内置：名字在 {@link BUILTIN_TOOL_NAMES} 中；
+     * - 插件：插件已加载且注册了该工具，key 合法；
+     * - 连接器：连接器属于本组织且未删除；点名的工具必须在连接器的工具快照中。
+     * 不同来源拼出同一个 key 也报出来（不截断、不猜）。
+     * 返回 `keys`：这些引用可能产生的全部工具 key（`"all"` 含连接器当前所有工具，不论状态），供校验 `toolPolicies`。
+     */
+    async checkRefs(orgId, refs) {
+        const issues = [];
+        const owner = new Map();
+        const pluginTools = this.deps.host.tools();
+        const connectorIds = [
+            ...new Set(refs.flatMap((r) => (r.kind === "connector" ? [r.connectorId] : []))),
+        ];
+        const apps = await this.loadConnectors(orgId, connectorIds);
+        const claim = (path, key, source) => {
+            const prev = owner.get(key);
+            if (prev === undefined)
+                owner.set(key, source);
+            else if (prev !== source) {
+                issues.push({ path, message: `Tool key "${key}" is already used by another tool` });
+            }
+        };
+        refs.forEach((ref, i) => {
+            const path = `tools.${i}`;
+            if (ref.kind === "builtin") {
+                if (!BUILTIN_TOOL_NAMES.includes(ref.name)) {
+                    issues.push({ path, message: `Built-in tool "${ref.name}" does not exist` });
+                    return;
+                }
+                claim(path, ref.name, `builtin:${ref.name}`);
+            }
+            else if (ref.kind === "plugin") {
+                const key = toolKey(ref.plugin, ref.name);
+                if (!pluginTools.some((x) => x.plugin === ref.plugin && x.spec.name === ref.name)) {
+                    issues.push({ path, message: `Plugin tool "${key}" does not exist` });
+                    return;
+                }
+                const issue = toolKeyIssue(key);
+                if (issue) {
+                    issues.push({ path, message: issue });
+                    return;
+                }
+                claim(path, key, `plugin:${ref.plugin}:${ref.name}`);
+            }
+            else {
+                const app = apps.get(ref.connectorId);
+                if (!app || app.deleted) {
+                    issues.push({ path, message: `Connector "${ref.connectorId}" does not exist` });
+                    return;
+                }
+                const names = ref.tools === "all" ? app.tools.map((t) => t.name) : [...new Set(ref.tools)];
+                for (const name of names) {
+                    if (!app.tools.some((t) => t.name === name)) {
+                        issues.push({
+                            path,
+                            message: `Tool "${name}" does not exist in connector ${app.slug}`,
+                        });
+                        continue;
+                    }
+                    claim(path, toolKey(app.slug, name), `connector:${app.id}:${name}`);
+                }
+            }
+        });
+        return { keys: new Set(owner.keys()), issues };
+    }
+    /**
+     * 解析 agent 引用的工具（见类注释），再判定是否启用 `tool_search`：组织设置 `toolSearch === "on"`，且
+     * 可用工具数 > `tools.searchThresholdTools` 或其定义的估算 token > `tools.searchThresholdTokens`。
+     * 启用时把内置 `tool_search` 追加到末尾。定义里显式引用的 `tool_search` 忽略（由这里按设置管理）。
+     * `skillLoad`：对话日志里有技能目录快照（`skills_catalog`，Ruling M17）→ 加入内置 `skill_load`（始终完整加载）；
+     * 定义里显式引用的 `skill_load` 同样忽略。
+     */
+    async forAgent(orgId, def) {
+        const { tools, unavailable, hidden } = await this.resolve(orgId, def);
+        const sl = def.skillLoad === true && this.deps.builtins.find((x) => x.spec.name === SKILL_LOAD);
+        if (sl) {
+            tools.push({
+                key: SKILL_LOAD,
+                source: { kind: "builtin", name: SKILL_LOAD },
+                spec: sl.spec,
+                specHash: specHash(sl.spec),
+                defaultPolicy: sl.defaultPolicy,
+                ...(sl.timeoutMs !== undefined && { timeoutMs: sl.timeoutMs }),
+            });
+        }
+        const toolSearch = await this.searchActive(orgId, tools);
+        if (toolSearch) {
+            const b = this.deps.builtins.find((x) => x.spec.name === TOOL_SEARCH);
+            tools.push({
+                key: TOOL_SEARCH,
+                source: { kind: "builtin", name: TOOL_SEARCH },
+                spec: b.spec,
+                specHash: specHash(b.spec),
+                defaultPolicy: b.defaultPolicy,
+            });
+        }
+        return { tools, unavailable, hidden, toolSearch };
+    }
+    /** 是否启用 `tool_search`（见 {@link forAgent}）；先比阈值，超过才读组织设置。 */
+    async searchActive(orgId, tools) {
+        const cfg = this.deps.config?.().tools;
+        if (!cfg || !this.deps.builtins.some((b) => b.spec.name === TOOL_SEARCH))
+            return false;
+        const over = tools.length > cfg.searchThresholdTools ||
+            estimateToolTokens(tools) > cfg.searchThresholdTokens;
+        if (!over)
+            return false;
+        return (await readOrgSettings(this.deps.db, orgId)).toolSearch === "on";
+    }
+    async resolve(orgId, def) {
+        const tools = [];
+        const unavailable = [];
+        const hidden = [];
+        const seen = new Map();
+        const add = (t) => {
+            const id = sourceId(t.source);
+            const prev = seen.get(t.key);
+            if (prev === undefined) {
+                seen.set(t.key, id);
+                tools.push(t);
+            }
+            else if (prev !== id) {
+                unavailable.push({
+                    ref: t.key,
+                    reason: "Another tool with the same name is already loaded",
+                });
+            }
+        };
+        const enabledPlugins = def.tools.some((r) => r.kind === "plugin")
+            ? await this.enabledPlugins(orgId)
+            : new Set();
+        const connectorIds = [
+            ...new Set(def.tools.flatMap((r) => (r.kind === "connector" ? [r.connectorId] : []))),
+        ];
+        const apps = await this.loadConnectors(orgId, connectorIds);
+        const pluginTools = this.deps.host.tools();
+        for (const ref of def.tools) {
+            if (ref.kind === "builtin") {
+                if (ref.name === TOOL_SEARCH || ref.name === SKILL_LOAD)
+                    continue;
+                const b = this.deps.builtins.find((x) => x.spec.name === ref.name);
+                if (!b) {
+                    unavailable.push({ ref: ref.name, reason: "Built-in tool does not exist" });
+                    continue;
+                }
+                const why = b.unavailable?.() ?? null;
+                if (why !== null) {
+                    unavailable.push({ ref: ref.name, reason: why });
+                    continue;
+                }
+                // `agent`: the description lists this definition's roster (sub-agents spec §4.3); with an
+                // empty roster there is nothing to dispatch, so the tool is not offered at all
+                let spec = b.spec;
+                if (b.spec.name === AGENT_TOOL) {
+                    const roster = await resolveRoster(this.deps.db, orgId, { subagents: def.subagents });
+                    if (roster.length === 0)
+                        continue;
+                    spec = agentToolSpec(roster, await this.maxConcurrentSubagents(orgId));
+                }
+                add({
+                    key: b.spec.name,
+                    source: { kind: "builtin", name: b.spec.name },
+                    spec,
+                    specHash: specHash(spec),
+                    defaultPolicy: b.defaultPolicy,
+                    ...(b.timeoutMs !== undefined && { timeoutMs: b.timeoutMs }),
+                    ...(b.spillChars !== undefined && { spillChars: b.spillChars }),
+                });
+            }
+            else if (ref.kind === "plugin") {
+                const key = toolKey(ref.plugin, ref.name);
+                const t = pluginTools.find((x) => x.plugin === ref.plugin && x.spec.name === ref.name);
+                if (!t) {
+                    unavailable.push({ ref: key, reason: "Plugin tool does not exist" });
+                    continue;
+                }
+                if (!enabledPlugins.has(ref.plugin)) {
+                    unavailable.push({
+                        ref: key,
+                        reason: `Plugin ${ref.plugin} is not enabled in this organization`,
+                    });
+                    continue;
+                }
+                const issue = toolKeyIssue(key);
+                if (issue) {
+                    unavailable.push({ ref: key, reason: issue });
+                    continue;
+                }
+                add({
+                    key,
+                    source: { kind: "plugin", plugin: ref.plugin, name: ref.name },
+                    spec: t.spec,
+                    specHash: specHash(t.spec),
+                    defaultPolicy: t.spec.defaultPolicy ?? policyFromAnnotations(t.spec.annotations),
+                });
+            }
+            else {
+                const app = apps.get(ref.connectorId);
+                if (!app) {
+                    unavailable.push({ ref: `app:${ref.connectorId}`, reason: "App does not exist" });
+                    continue;
+                }
+                const all = toolKey(app.slug, "*");
+                if (app.deleted) {
+                    unavailable.push({ ref: all, reason: `App ${app.slug} was deleted` });
+                    continue;
+                }
+                if (app.status !== "active") {
+                    unavailable.push({ ref: all, reason: `App ${app.slug} is disabled` });
+                    continue;
+                }
+                if (!this.findConnector(app.connector)) {
+                    unavailable.push({
+                        ref: all,
+                        reason: `Connector ${app.connector} for app ${app.slug} is not installed`,
+                    });
+                    continue;
+                }
+                const wanted = ref.tools === "all"
+                    ? app.tools
+                    : ref.tools.map((name) => app.tools.find((t) => t.name === name) ?? { name, missing: true });
+                // 「all」里未启用的工具不算 agent 点名要的，不进 unavailable（不提醒），只记进 hidden 备查
+                const notEnabled = ref.tools === "all" ? hidden : unavailable;
+                for (const t of wanted) {
+                    const key = toolKey(app.slug, t.name);
+                    // 远端已不再提供（漂移检测置停用并标记，见 drift.ts）：与「没有这一行」同一个事实
+                    if ("missing" in t || t.gone) {
+                        notEnabled.push({ ref: key, reason: `Tool no longer exists in app ${app.slug}` });
+                        continue;
+                    }
+                    if (t.status === "disabled") {
+                        notEnabled.push({ ref: key, reason: "Tool is disabled" });
+                        continue;
+                    }
+                    if (t.status === "pending_review") {
+                        notEnabled.push({ ref: key, reason: "Tool is pending review" });
+                        continue;
+                    }
+                    const issue = toolKeyIssue(key);
+                    if (issue) {
+                        unavailable.push({ ref: key, reason: issue });
+                        continue;
+                    }
+                    add({
+                        key,
+                        source: {
+                            kind: "connector",
+                            connectorId: app.id,
+                            name: t.name,
+                            ...(t.source === "resources" && { resources: true }),
+                        },
+                        spec: t.spec,
+                        specHash: t.specHash,
+                        defaultPolicy: t.defaultPolicy,
+                    });
+                }
+            }
+        }
+        return { tools, unavailable, hidden };
+    }
+    /**
+     * `subagents.maxConcurrentPerRun` with the organization's override, for the `agent` tool's
+     * description (§4.3). A change of the limit changes the tool's spec hash; replays read the
+     * definition logged by hash, so no drift reason is involved. Without config (some tests): the
+     * schema default.
+     */
+    async maxConcurrentSubagents(orgId) {
+        const config = this.deps.config ?? (() => ({ subagents: SUBAGENT_LIMIT_DEFAULTS }));
+        return (await subagentLimits(this.deps.db, config, orgId)).maxConcurrentPerRun;
+    }
+    /** Plugins the organization enabled (built-in plugins always count as enabled, C14). */
+    async enabledPlugins(orgId) {
+        return this.deps.host.enabledPlugins(orgId);
+    }
+    async loadConnectors(orgId, ids) {
+        const out = new Map();
+        if (ids.length === 0)
+            return out;
+        // 软删除的连接器也读出来，只为给出「已删除」这个更准确的原因（slug 可能已被新连接器复用，按 id 区分）
+        const apps = await this.deps.db
+            .selectFrom("connectors")
+            .select(["id", "slug", "connector", "status", "deleted_at"])
+            .where("org_id", "=", orgId)
+            .where("id", "in", ids)
+            .execute();
+        const live = apps.filter((a) => a.deleted_at === null).map((a) => a.id);
+        const toolRows = live.length === 0
+            ? []
+            : await this.deps.db
+                .selectFrom("connector_tools")
+                .select([
+                "connector_id",
+                "name",
+                "spec",
+                "spec_hash",
+                "status",
+                "default_policy",
+                "source",
+                "missing_since",
+            ])
+                .where("connector_id", "in", live)
+                .orderBy("name")
+                .execute();
+        for (const a of apps) {
+            out.set(a.id, {
+                id: a.id,
+                slug: a.slug,
+                connector: a.connector,
+                status: a.status,
+                deleted: a.deleted_at !== null,
+                tools: toolRows
+                    .filter((t) => t.connector_id === a.id)
+                    .map((t) => ({
+                    name: t.name,
+                    spec: t.spec,
+                    specHash: t.spec_hash,
+                    status: t.status,
+                    defaultPolicy: t.default_policy,
+                    source: t.source,
+                    gone: t.missing_since !== null,
+                })),
+            });
+        }
+        return out;
+    }
+}

package/dist/tools/resources.d.ts

@@ -0,0 +1,16 @@
+import { type ConnectorSession, type ToolResult, type ToolSpec } from "@capybara-hq/plugin-sdk";
+/**
+ * 连接器 resources 的两个内核工具（brief：`<connectorSlug>__list_resources`、`<connectorSlug>__read_resource {uri}`）。
+ *
+ * 设计：安装 / 刷新连接器时，连接器会话带 `listResources` 方法即视为支持 resources（不额外调用，免得多一次外连
+ * 和多一种失败），内核把这两个工具作为 `source = 'resources'` 的行写进 `connector_tools`（迁移 0013）。这样它们和
+ * 连接器工具走同一套机制：管理员可启停、改默认策略，agent 可点名引用或随 `tools: "all"` 带上，策略 / 授权 /
+ * 审批按 key 与指纹生效；执行时管线按 `source` 路由到会话的 `listResources` / `readResource`。
+ * 只读注解 → 默认 `allow`。连接器自己有同名工具时连接器的优先，内核的那个不加并报原因。
+ */
+export declare const LIST_RESOURCES = "list_resources";
+export declare const READ_RESOURCE = "read_resource";
+/** 两个工具的定义（与 slug 无关，指纹稳定）。 */
+export declare function resourceToolSpecs(): ToolSpec[];
+/** 执行 resources 工具：路由到会话的 listResources / readResource。 */
+export declare function runResourceTool(session: ConnectorSession, name: string, input: unknown): Promise<ToolResult>;

package/dist/tools/resources.js

@@ -0,0 +1,76 @@
+import { ToolError, } from "@capybara-hq/plugin-sdk";
+/**
+ * 连接器 resources 的两个内核工具（brief：`<connectorSlug>__list_resources`、`<connectorSlug>__read_resource {uri}`）。
+ *
+ * 设计：安装 / 刷新连接器时，连接器会话带 `listResources` 方法即视为支持 resources（不额外调用，免得多一次外连
+ * 和多一种失败），内核把这两个工具作为 `source = 'resources'` 的行写进 `connector_tools`（迁移 0013）。这样它们和
+ * 连接器工具走同一套机制：管理员可启停、改默认策略，agent 可点名引用或随 `tools: "all"` 带上，策略 / 授权 /
+ * 审批按 key 与指纹生效；执行时管线按 `source` 路由到会话的 `listResources` / `readResource`。
+ * 只读注解 → 默认 `allow`。连接器自己有同名工具时连接器的优先，内核的那个不加并报原因。
+ */
+export const LIST_RESOURCES = "list_resources";
+export const READ_RESOURCE = "read_resource";
+/** 两个工具的定义（与 slug 无关，指纹稳定）。 */
+export function resourceToolSpecs() {
+    return [
+        {
+            name: LIST_RESOURCES,
+            description: "List the resources (documents, files, records) this app exposes. Returns a JSON array of { uri, name, description?, mimeType? }; read one with this app's read_resource tool.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            annotations: { readOnlyHint: true },
+        },
+        {
+            name: READ_RESOURCE,
+            description: "Read the content of one of this app's resources by its URI (get URIs from this app's list_resources tool).",
+            inputSchema: {
+                type: "object",
+                properties: { uri: { type: "string", description: "Resource URI from list_resources" } },
+                required: ["uri"],
+                additionalProperties: false,
+            },
+            annotations: { readOnlyHint: true },
+        },
+    ];
+}
+const NOT_SUPPORTED = "This app no longer supports resources; ask an administrator to refresh the app.";
+/** 显示摘要里的资源地址上限（码点）：摘要整体须 ≤ 200 码点。 */
+const DISPLAY_URI_MAX = 150;
+const shortUri = (uri) => {
+    const cps = [...uri.replace(/\s+/g, " ")];
+    return cps.length > DISPLAY_URI_MAX
+        ? `${cps.slice(0, DISPLAY_URI_MAX - 1).join("")}…`
+        : cps.join("");
+};
+/** 执行 resources 工具：路由到会话的 listResources / readResource。 */
+export async function runResourceTool(session, name, input) {
+    if (name === LIST_RESOURCES) {
+        if (!session.listResources)
+            throw new ToolError(NOT_SUPPORTED);
+        const items = await session.listResources();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: items.length === 0 ? "This app exposes no resources." : JSON.stringify(items),
+                },
+            ],
+            display: {
+                summary: { zh: `列出资源 · ${items.length} 个`, en: `Listed resources · ${items.length}` },
+            },
+        };
+    }
+    if (name === READ_RESOURCE) {
+        if (!session.readResource)
+            throw new ToolError(NOT_SUPPORTED);
+        const uri = input?.uri;
+        if (typeof uri !== "string" || uri === "")
+            throw new ToolError("uri must be a non-empty string.");
+        // 摘要由内核给（覆盖连接器结果里可能带的 display：那来自外部服务，不采信）
+        const u = shortUri(uri);
+        return {
+            ...(await session.readResource(uri)),
+            display: { summary: { zh: `读取资源 ${u}`, en: `Read resource ${u}` } },
+        };
+    }
+    throw new ToolError(`Unknown resource tool ${name}.`);
+}

package/dist/tools/specs.d.ts

@@ -0,0 +1,14 @@
+import type { ToolSpec } from "@capybara-hq/plugin-sdk";
+import type { Transaction } from "kysely";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+/**
+ * 把工具定义按指纹存进 `capybara.tool_specs`（内容寻址：同一指纹只存一次，已存在不改）。
+ * `model_call` 只记 `{key, specHash}`，定义本身存这里——连接器刷新 / 插件升级改了定义之后，早先请求用过的定义
+ * 仍可按指纹取回，模型请求可由日志还原。
+ */
+export declare function recordToolSpecs(db: KernelDb | Transaction<KernelDatabase>, specs: readonly {
+    specHash: string;
+    spec: ToolSpec;
+}[]): Promise<void>;
+/** 按指纹取回工具定义；没有记录 → null。 */
+export declare function loadToolSpec(db: KernelDb, specHash: string): Promise<ToolSpec | null>;

package/dist/tools/specs.js

@@ -0,0 +1,31 @@
+/**
+ * 把工具定义按指纹存进 `capybara.tool_specs`（内容寻址：同一指纹只存一次，已存在不改）。
+ * `model_call` 只记 `{key, specHash}`，定义本身存这里——连接器刷新 / 插件升级改了定义之后，早先请求用过的定义
+ * 仍可按指纹取回，模型请求可由日志还原。
+ */
+export async function recordToolSpecs(db, specs) {
+    const unique = new Map();
+    for (const s of specs)
+        if (!unique.has(s.specHash))
+            unique.set(s.specHash, s.spec);
+    if (unique.size === 0)
+        return;
+    // 按指纹排序插入：并发事务插入同一批指纹时加锁顺序一致，不会互相死锁
+    const rows = [...unique]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([hash, spec]) => ({ spec_hash: hash, spec: JSON.stringify(spec) }));
+    await db
+        .insertInto("tool_specs")
+        .values(rows)
+        .onConflict((oc) => oc.column("spec_hash").doNothing())
+        .execute();
+}
+/** 按指纹取回工具定义；没有记录 → null。 */
+export async function loadToolSpec(db, specHash) {
+    const row = await db
+        .selectFrom("tool_specs")
+        .select("spec")
+        .where("spec_hash", "=", specHash)
+        .executeTakeFirst();
+    return row ? row.spec : null;
+}

package/dist/tools/validate.d.ts

@@ -0,0 +1,20 @@
+import type { Logger, ToolSpec } from "@capybara-hq/plugin-sdk";
+/** 不受信任的 schema（连接器工具，来自连接器）JSON 序列化后的字节上限：超过不编译、不校验。 */
+export declare const UNTRUSTED_SCHEMA_MAX_BYTES: number;
+/** 不受信任的 schema 的嵌套层数上限（对象 / 数组层数）：超过不编译、不校验。 */
+export declare const UNTRUSTED_SCHEMA_MAX_DEPTH = 32;
+export interface ValidateOptions {
+    /**
+     * schema 来自不受信任的来源（连接器工具，由连接器提供）：编译前去掉 pattern / patternProperties / format，
+     * 并限制大小与嵌套层数（超限不校验）。
+     */
+    untrusted?: boolean;
+    /** 跳过校验（超限 / 无法编译）时记 warn（只含 toolKey 与原因）。 */
+    log?: Pick<Logger, "warn">;
+}
+/**
+ * 管线第 2 阶段：按工具的 inputSchema 校验参数（ajv，JSON Schema 2020-12，`strict: false`，`allErrors: true`）。
+ * 合法 → null；不合法 → 给模型的英文说明：全部错误路径 + 完整 inputSchema（spec 6.3「给事实，不猜」）。
+ * schema 自身无法编译或超限时不拦截（返回 null）。
+ */
+export declare function validateInput(key: string, spec: ToolSpec, input: unknown, opts?: ValidateOptions): string | null;