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

package/dist/tools/elicitation.js

@@ -0,0 +1,266 @@
+import { validateInputForm } from "@capybara-hq/plugin-sdk";
+import { contentHash } from "./registry.js";
+/**
+ * MCP elicitation（D4，仿 Claude Code：表单 + URL 两种模式）映射到通用输入请求（Task 9 的 `InputRequired`）。
+ *
+ * 设计（为什么不是「真正挂起」）：官方 SDK 的 elicitation 答复只能在原 `tools/call` 还挂着时送回同一个会话；
+ * 而内核等人回答时运行会暂停、worker 释放、连接器会话关闭（多副本下续跑可能在另一副本），原调用不可能保持。
+ * 所以采用「可续的连接器调用」：
+ *
+ * 1. 调用途中远端发起 elicitation → 连接器调用 `onElicit` → 本会话（{@link ElicitationSession}）把请求映射成
+ *    `InputForm`，记下待问的表单与 state，并**中止本次调用**（`onSuspend`，经 `callTool` 的 signal），`onElicit` 以
+ *    {@link ElicitationSuspended} 拒绝；管线据此
+ *    把这次执行当作 `input_required`（写 `question_asked`、运行进入等待）。
+ * 2. 用户回答（或超时 / 取消）后，管线照常用同一 input 再次调用该工具，带 `ctx.resume = { state, answer }`；
+ *    远端再次发起**同样的** elicitation（按指纹匹配：表单模式看 `requestedSchema` 与文案，URL 模式看地址的 origin + path 与文案）
+ *    时，本会话立即用用户的答案答复，远端继续执行。一次调用里有多个 elicitation 时，state 带上之前的全部答复，
+ *    每次续跑整条重放；最多 3 轮（管线的输入轮次上限）。
+ *
+ * 限制（写进报告与 .agents/skills/writing-tools）：远端第二次没有发起同样的 elicitation（换了 schema / 不再问）时，答案
+ * 不会被使用——前者会再问一次用户，后者远端按自己的逻辑继续；远端在 elicitation 之前做过的副作用会随重新发起
+ * 的调用再做一次（大多数服务在动手之前先问）；URL 模式的完成通知（`notifications/elicitation/complete`）收不到
+ * （会话已关闭），以用户在卡片上确认「已完成」为准。
+ *
+ * 超出 InputForm 子集的表单（嵌套对象、`minLength > 1`、`minItems > 1` 等）不展示：立即答复 `decline`，并在工具
+ * 结果末尾附一条给模型的英文说明。
+ */
+/** 本次调用为问用户而被中止（`onElicit` 以它拒绝；管线按 pending 的输入请求处理，不当作失败）。 */
+export class ElicitationSuspended extends Error {
+    constructor() {
+        super("The call was suspended to ask the user for input");
+        this.name = "ElicitationSuspended";
+    }
+}
+/** 不能展示的 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.]`;
+/** URL 模式表单里「已完成」开关的字段名。 */
+export const URL_COMPLETED_FIELD = "completed";
+/** 表单标题（远端给的 message）最多字符数。 */
+const MAX_TITLE = 2000;
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const str = (v) => typeof v === "string" && v.trim() !== "" ? v : undefined;
+/** 一个属性 → 表单字段；超出子集返回原因。 */
+function fieldFor(key, p, required) {
+    const at = `field "${key}"`;
+    if (!isObj(p))
+        return `${at} is not an object schema`;
+    const label = str(p.title) ?? key;
+    const notes = [];
+    const description = str(p.description);
+    if (description !== undefined)
+        notes.push(description);
+    let schema;
+    let multiSelect = false;
+    switch (p.type) {
+        case "string": {
+            if (typeof p.minLength === "number" && p.minLength > 1)
+                return `${at} uses minLength`;
+            if (Array.isArray(p.enum)) {
+                const values = p.enum.filter((x) => typeof x === "string");
+                if (values.length !== p.enum.length || values.length === 0)
+                    return `${at} has a non-string enum`;
+                const names = Array.isArray(p.enumNames) ? p.enumNames : undefined;
+                if (names && names.length === values.length && names.every((n) => typeof n === "string")) {
+                    notes.push(`Options: ${values.map((v, i) => `${v} = ${names[i]}`).join("; ")}.`);
+                }
+                schema = { type: "string", enum: values };
+            }
+            else if (Array.isArray(p.oneOf)) {
+                const opts = p.oneOf.filter((o) => isObj(o) && typeof o.const === "string");
+                if (opts.length !== p.oneOf.length || opts.length === 0)
+                    return `${at} has unsupported oneOf`;
+                notes.push(`Options: ${opts.map((o) => `${o.const} = ${str(o.title) ?? o.const}`).join("; ")}.`);
+                schema = { type: "string", enum: opts.map((o) => o.const) };
+            }
+            else {
+                if (typeof p.format === "string")
+                    notes.push(`Format: ${p.format}.`);
+                schema =
+                    typeof p.maxLength === "number" && Number.isInteger(p.maxLength) && p.maxLength >= 0
+                        ? { type: "string", maxLength: p.maxLength }
+                        : { type: "string" };
+            }
+            break;
+        }
+        case "boolean":
+            schema = { type: "boolean" };
+            break;
+        case "number":
+        case "integer": {
+            const s = {
+                type: p.type,
+            };
+            if (typeof p.minimum === "number" && Number.isFinite(p.minimum))
+                s.minimum = p.minimum;
+            if (typeof p.maximum === "number" && Number.isFinite(p.maximum))
+                s.maximum = p.maximum;
+            schema = s;
+            break;
+        }
+        case "array": {
+            const items = isObj(p.items) ? p.items : undefined;
+            let values;
+            if (items && Array.isArray(items.enum)) {
+                values = items.enum.filter((x) => typeof x === "string");
+                if (values.length !== items.enum.length)
+                    values = undefined;
+            }
+            else if (items && Array.isArray(items.anyOf)) {
+                const opts = items.anyOf.filter((o) => isObj(o) && typeof o.const === "string");
+                if (opts.length === items.anyOf.length) {
+                    values = opts.map((o) => o.const);
+                    notes.push(`Options: ${opts.map((o) => `${o.const} = ${str(o.title) ?? o.const}`).join("; ")}.`);
+                }
+            }
+            if (!values || values.length === 0)
+                return `${at} is an array without string options`;
+            if (typeof p.minItems === "number" && p.minItems > 1)
+                return `${at} uses minItems`;
+            if (typeof p.maxItems === "number" && p.maxItems < values.length)
+                return `${at} uses maxItems`;
+            schema = { type: "string", enum: values };
+            multiSelect = true;
+            break;
+        }
+        default:
+            return `${at} has unsupported type ${JSON.stringify(p.type)}`;
+    }
+    if (p.default !== undefined && !multiSelect && !("enum" in schema)) {
+        notes.push(`Default: ${JSON.stringify(p.default)}.`);
+    }
+    return {
+        key,
+        label,
+        ...(notes.length > 0 && { description: notes.join(" ") }),
+        schema,
+        ...(multiSelect && { multiSelect: true }),
+        ...(required && { required: true }),
+    };
+}
+/** elicitation → 交互表单；超出子集 → `{ unsupported: 原因 }`（英文）。 */
+export function elicitationForm(req) {
+    const title = req.message.trim().slice(0, MAX_TITLE) || "Input requested";
+    let form;
+    if (req.mode === "url") {
+        form = {
+            title,
+            url: req.url,
+            fields: [
+                {
+                    key: URL_COMPLETED_FIELD,
+                    label: { en: "I have completed this step", zh: "我已完成这一步" },
+                    schema: { type: "boolean" },
+                    required: true,
+                },
+            ],
+        };
+    }
+    else {
+        const s = req.requestedSchema;
+        if (s.type !== "object" || !isObj(s.properties)) {
+            return { unsupported: "requestedSchema is not an object schema with properties" };
+        }
+        const required = new Set(Array.isArray(s.required) ? s.required : []);
+        const fields = [];
+        for (const [key, p] of Object.entries(s.properties)) {
+            const f = fieldFor(key, p, required.has(key));
+            if (typeof f === "string")
+                return { unsupported: f };
+            fields.push(f);
+        }
+        if (fields.length === 0)
+            return { unsupported: "the form has no fields" };
+        form = { title, fields };
+    }
+    const problems = validateInputForm(form);
+    return problems.length > 0 ? { unsupported: problems.join("; ") } : { form };
+}
+/** 指纹：表单模式按 requestedSchema，URL 模式按地址的 origin + path（query 常带一次性 state）。 */
+function fingerprint(req) {
+    // 文案也计入：同一 schema 换了说明（问的是另一件事）要重新问用户
+    const message = contentHash(req.message);
+    if (req.mode === "form") {
+        return contentHash({ mode: "form", schema: req.requestedSchema, message });
+    }
+    let target = req.url;
+    try {
+        const u = new URL(req.url);
+        target = `${u.origin}${u.pathname}`;
+    }
+    catch {
+        // 原样
+    }
+    return contentHash({ mode: "url", target, message });
+}
+/** 用户答案 → 给远端的答复。 */
+function responseFor(mode, answer) {
+    if (answer === null)
+        return { action: "cancel" };
+    if (mode === "url") {
+        return answer[URL_COMPLETED_FIELD] === true ? { action: "accept" } : { action: "decline" };
+    }
+    return { action: "accept", content: answer };
+}
+function parseState(state) {
+    const e = isObj(state) ? state.elicitation : undefined;
+    if (!isObj(e) || !Array.isArray(e.answers) || !isObj(e.pending))
+        return undefined;
+    const p = e.pending;
+    if (typeof p.fp !== "string" || (p.mode !== "form" && p.mode !== "url"))
+        return undefined;
+    const answers = e.answers.filter((a) => isObj(a) && typeof a.fp === "string" && isObj(a.response));
+    return { answers, pending: { fp: p.fp, mode: p.mode } };
+}
+/**
+ * 一次连接器工具调用里的 elicitation 处理（见文件头）。`onSuspend` 中止本次调用；`declineAll` 用于不能续跑的场景
+ * （如 resources 工具），一律拒绝并附说明。
+ */
+export class ElicitationSession {
+    opts;
+    /** 需要问用户的表单与 state（有值即本次执行按 `input_required` 处理）。 */
+    pending;
+    /** 附在工具结果后给模型的说明。 */
+    notes = [];
+    answers;
+    used = new Set();
+    constructor(opts) {
+        this.opts = opts;
+        const prev = opts.resume ? parseState(opts.resume.state) : undefined;
+        this.answers = prev
+            ? [
+                ...prev.answers,
+                {
+                    fp: prev.pending.fp,
+                    response: responseFor(prev.pending.mode, opts.resume?.answer ?? null),
+                },
+            ]
+            : [];
+    }
+    handle = async (req) => {
+        if (this.opts.declineAll) {
+            this.notes.push(unsupportedNote("this tool cannot pause for user input"));
+            return { action: "decline" };
+        }
+        const fp = fingerprint(req);
+        const i = this.answers.findIndex((a, idx) => a.fp === fp && !this.used.has(idx));
+        if (i >= 0) {
+            this.used.add(i);
+            return this.answers[i].response;
+        }
+        const mapped = elicitationForm(req);
+        if ("unsupported" in mapped) {
+            this.notes.push(unsupportedNote(mapped.unsupported));
+            return { action: "decline" };
+        }
+        if (!this.pending) {
+            this.pending = {
+                form: mapped.form,
+                state: { elicitation: { answers: this.answers, pending: { fp, mode: req.mode } } },
+            };
+            this.opts.onSuspend();
+        }
+        // 调用已被中止：以错误结束（不让连接器等一个永不答复的 promise，如 -32042 路径里的 await），会话随后关闭
+        throw new ElicitationSuspended();
+    };
+}

package/dist/tools/endpoint.d.ts

@@ -0,0 +1,18 @@
+/** The query parameter names of `u` that look like a credential (each once, in URL order). */
+export declare const credentialQueryParams: (u: URL) => string[];
+/** 端点里凭据样式的头 / query 参数 / URL 用户信息；path 相对 `endpoint`。 */
+export declare function endpointCredentialIssues(endpoint: unknown): {
+    path: string;
+    message: string;
+}[];
+/**
+ * 给没有 `connectors.manage` 的人看的端点：URL 字段（`url` / `*Url`）只留源（scheme + host + port），有路径时打码为
+ * `<origin>/…`（去掉路径、query、fragment 与用户信息）；`headers` 只留头名（`headerNames`）。
+ * 路径、固定头值与 query 可能含租户号等管理员不想公开的信息。
+ */
+export declare function publicEndpoint(endpoint: unknown): unknown;
+/**
+ * 连接器列表 / 详情里给所有人看的端点（Ruling A21）：`text` / `*Text` 字段（如最大 2 MB 的 OpenAPI 文档）不回显全文，
+ * 换成 `<field>Bytes`（UTF-8 字节数）与 `<field>Sha256`；要改文档时管理员重新上传。存储与连接器拿到的仍是全文。
+ */
+export declare function endpointView(endpoint: unknown): unknown;

package/dist/tools/endpoint.js

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+/**
+ * 连接器端点的通用处理（与连接器无关，按约定：顶层名为 `url` 或以 `Url` 结尾的字符串字段是 URL，如 MCP 的 `url`、
+ * OpenAPI 的 `specUrl` / `baseUrl`；`headers` 是固定头）：端点配置对 `connectors.use` 的成员可见，
+ * 不能放凭据——凭据走连接器的认证设置（加密存储、按调用注入、结果打码）。
+ */
+/** 端点里按「大段文本」处理的顶层字段名（如 OpenAPI 的 `specText`）：连接器视图只给字节数与 sha256。 */
+const isTextField = (key) => key === "text" || /^[a-z][A-Za-z0-9]*Text$/.test(key);
+/** 端点里按 URL 处理的顶层字段名。 */
+const isUrlField = (key) => key === "url" || /^[a-z][A-Za-z0-9]*Url$/.test(key);
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** 凭据样式的头名（小写比较）：authorization 各变体、api key、token、secret、cookie。 */
+const CREDENTIAL_HEADER = /^(?:(?:proxy-)?authorization|x-authorization|cookie|(?:x-)?api-?key|x-auth-token|.*-token|.*-secret)$/;
+/** 凭据样式的 query 参数名（小写比较）。 */
+const CREDENTIAL_QUERY = new Set([
+    "key",
+    "api_key",
+    "apikey",
+    "api-key",
+    "token",
+    "access_token",
+    "secret",
+]);
+/** The query parameter names of `u` that look like a credential (each once, in URL order). */
+export const credentialQueryParams = (u) => [...new Set([...u.searchParams.keys()])].filter((k) => CREDENTIAL_QUERY.has(k.toLowerCase()));
+const USE_CREDENTIALS = "configure it in the connector's credential settings instead";
+/** 端点里凭据样式的头 / query 参数 / URL 用户信息；path 相对 `endpoint`。 */
+export function endpointCredentialIssues(endpoint) {
+    if (!isObj(endpoint))
+        return [];
+    const out = [];
+    if (isObj(endpoint.headers)) {
+        for (const name of Object.keys(endpoint.headers)) {
+            if (CREDENTIAL_HEADER.test(name.toLowerCase())) {
+                out.push({
+                    path: `endpoint.headers.${name}`,
+                    message: `Header "${name}" looks like a credential; ${USE_CREDENTIALS}`,
+                });
+            }
+        }
+    }
+    for (const [field, value] of Object.entries(endpoint)) {
+        if (!isUrlField(field) || typeof value !== "string")
+            continue;
+        let u;
+        try {
+            u = new URL(value);
+        }
+        catch {
+            u = undefined; // 格式错误交给连接器的 schema
+        }
+        if (!u)
+            continue;
+        if (u.username !== "" || u.password !== "") {
+            out.push({
+                path: `endpoint.${field}`,
+                message: `The URL must not contain a user name or password; ${USE_CREDENTIALS}`,
+            });
+        }
+        const bad = credentialQueryParams(u);
+        if (bad.length > 0) {
+            out.push({
+                path: `endpoint.${field}`,
+                message: `Query parameter ${bad.map((k) => `"${k}"`).join(", ")} looks like a credential; ${USE_CREDENTIALS}`,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * 给没有 `connectors.manage` 的人看的端点：URL 字段（`url` / `*Url`）只留源（scheme + host + port），有路径时打码为
+ * `<origin>/…`（去掉路径、query、fragment 与用户信息）；`headers` 只留头名（`headerNames`）。
+ * 路径、固定头值与 query 可能含租户号等管理员不想公开的信息。
+ */
+export function publicEndpoint(endpoint) {
+    if (!isObj(endpoint))
+        return endpoint;
+    const { headers, ...rest } = endpoint;
+    const out = {};
+    for (const [field, value] of Object.entries(rest)) {
+        if (!isUrlField(field) || typeof value !== "string") {
+            out[field] = value;
+            continue;
+        }
+        try {
+            const u = new URL(value);
+            out[field] = u.pathname === "/" || u.pathname === "" ? u.origin : `${u.origin}/…`;
+        }
+        catch {
+            // 不是合法 URL：不展示
+        }
+    }
+    if (isObj(headers))
+        out.headerNames = Object.keys(headers);
+    return out;
+}
+/**
+ * 连接器列表 / 详情里给所有人看的端点（Ruling A21）：`text` / `*Text` 字段（如最大 2 MB 的 OpenAPI 文档）不回显全文，
+ * 换成 `<field>Bytes`（UTF-8 字节数）与 `<field>Sha256`；要改文档时管理员重新上传。存储与连接器拿到的仍是全文。
+ */
+export function endpointView(endpoint) {
+    if (!isObj(endpoint))
+        return endpoint;
+    const out = {};
+    for (const [field, value] of Object.entries(endpoint)) {
+        if (isTextField(field) && typeof value === "string") {
+            out[`${field}Bytes`] = Buffer.byteLength(value, "utf8");
+            out[`${field}Sha256`] = createHash("sha256").update(value).digest("hex");
+        }
+        else {
+            out[field] = value;
+        }
+    }
+    return out;
+}

package/dist/tools/info.d.ts

@@ -0,0 +1,67 @@
+import type { KernelDb } from "../db/kernel-schema.js";
+import type { ToolRegistry } from "./registry.js";
+/**
+ * Tool presentation metadata for the conversation page (UI refresh B, design spec §6.16.9): the
+ * kind picks the row verb and the group counts, the title and key arguments the row's wording.
+ * Display only: nothing here reaches the model.
+ */
+export type ToolKind = "command" | "read" | "edit" | "search" | "connector" | "meta" | "tool";
+export interface ToolInfo {
+    /** The model-visible tool key, as asked for. */
+    key: string;
+    /** The declared display title (`ToolSpec.title`), or null. */
+    title: string | null;
+    kind: ToolKind;
+    /** The declared key arguments (`ToolSpec.keyArgs`), or []. */
+    keyArgs: string[];
+    source: {
+        kind: "builtin";
+    } | {
+        kind: "extension";
+        name: string;
+    } | {
+        kind: "connector";
+        id: string;
+        name: string;
+    }
+    /** No tool with this key exists now (removed connector, unloaded extension, …). */
+     | {
+        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>>;
+/** 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;
+export interface ToolInfoDeps {
+    db: KernelDb;
+    registry: Pick<ToolRegistry, "builtinSpecs" | "extensionToolSpecs">;
+}
+/**
+ * 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
+ * connector's current stored tool (its reviewed definition, never a pending one). Anything else
+ * comes back as an unknown plain tool.
+ *
+ * - Titles and key arguments are never read from `tool_specs`: it is content-addressed by
+ *   `specHash`, which leaves the display fields out, so it keeps whichever title was stored first
+ *   under a hash. Eval and trajectory viewers must not show a title from it either.
+ * - Extension tools resolve deployment-wide (from the loaded host), not per org: a tool of an
+ *   extension that is not enabled in this org still answers `source: extension` with its title.
+ *   That is deliberate: old conversation logs keep their labels, and the data is not sensitive.
+ * - A key whose prefix is both a loaded extension's name and a connector slug resolves to the
+ *   extension. When an agent's tools are built, the registry's `claim()` reports that collision;
+ *   here it only changes the label.
+ */
+export declare function toolInfo(deps: ToolInfoDeps, orgId: string, keys: readonly string[]): Promise<ToolInfo[]>;
+export interface ConversationToolInfoDeps extends ToolInfoDeps {
+    /** Conversation visibility (the same rule as the events API: `ConversationsService.isAccessible`). */
+    isAccessible(orgId: string, conversationId: string, viewerAccountId: string): Promise<boolean>;
+}
+/** `GET /conversations/:id/tools`: {@link toolInfo} for a conversation the viewer can read. */
+export declare class ConversationToolInfo {
+    private readonly d;
+    constructor(d: ConversationToolInfoDeps);
+    get(orgId: string, conversationId: string, viewerAccountId: string, keys: readonly string[]): Promise<ToolInfo[]>;
+}

package/dist/tools/info.js

@@ -0,0 +1,113 @@
+import { ApiError } from "../errors.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",
+};
+/** 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;
+const display = (spec) => ({
+    title: typeof spec?.title === "string" ? spec.title : null,
+    keyArgs: Array.isArray(spec?.keyArgs) ? [...spec.keyArgs] : [],
+});
+/**
+ * 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
+ * connector's current stored tool (its reviewed definition, never a pending one). Anything else
+ * comes back as an unknown plain tool.
+ *
+ * - Titles and key arguments are never read from `tool_specs`: it is content-addressed by
+ *   `specHash`, which leaves the display fields out, so it keeps whichever title was stored first
+ *   under a hash. Eval and trajectory viewers must not show a title from it either.
+ * - Extension tools resolve deployment-wide (from the loaded host), not per org: a tool of an
+ *   extension that is not enabled in this org still answers `source: extension` with its title.
+ *   That is deliberate: old conversation logs keep their labels, and the data is not sensitive.
+ * - A key whose prefix is both a loaded extension's name and a connector slug resolves to the
+ *   extension. When an agent's tools are built, the registry's `claim()` reports that collision;
+ *   here it only changes the label.
+ */
+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 slugs = [
+        ...new Set(unique.flatMap((k) => {
+            if (builtins.has(k) || extensions.has(k))
+                return [];
+            const p = split(k);
+            return p ? [p[0]] : [];
+        })),
+    ];
+    const connectorRows = slugs.length === 0
+        ? []
+        : await deps.db
+            .selectFrom("connectors as c")
+            .innerJoin("connector_tools as t", "t.connector_id", "c.id")
+            .select(["c.id", "c.slug", "c.name", "t.name as tool", "t.spec"])
+            .where("c.org_id", "=", orgId)
+            .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]));
+    return unique.map((key) => {
+        const b = builtins.get(key);
+        if (b) {
+            return {
+                key,
+                ...display(b),
+                kind: BUILTIN_TOOL_KINDS[key] ?? "tool",
+                source: { kind: "builtin" },
+            };
+        }
+        const e = extensions.get(key);
+        if (e)
+            return {
+                key,
+                ...display(e.spec),
+                kind: "tool",
+                source: { kind: "extension", name: e.plugin },
+            };
+        const c = connectorTools.get(key);
+        if (c) {
+            // The reviewed definition: a pending (unreviewed) one never supplies display text.
+            return {
+                key,
+                ...display(c.spec),
+                kind: "connector",
+                source: { kind: "connector", id: c.id, name: c.name },
+            };
+        }
+        return { key, title: null, kind: "tool", keyArgs: [], 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;
+    }
+    async get(orgId, conversationId, viewerAccountId, keys) {
+        if (!UUID_RE.test(conversationId) ||
+            !(await this.d.isAccessible(orgId, conversationId, viewerAccountId))) {
+            throw new ApiError("conversation.not_found", "Conversation not found");
+        }
+        return toolInfo(this.d, orgId, keys);
+    }
+}

package/dist/tools/naming.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 工具命名（Global Constraints）：模型可见的工具 key 必须匹配 `^[a-zA-Z0-9_-]{1,64}$`；
+ * 插件工具为 `<plugin>__<tool>`，连接器工具为 `<connectorSlug>__<tool>`，内置工具就是其名字本身。
+ * 超长或含非法字符的 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。
+ */
+export declare function isValidSlug(slug: string): boolean;
+/** slug 不合法时的英文说明（给 validation_failed 用）。 */
+export declare const SLUG_RULE = "Slug must start with a lowercase letter, contain only lowercase letters, digits and single underscores, not end with an underscore, and be at most 24 characters";
+/**
+ * 由连接器名推导 slug：转小写，非 `[a-z0-9]` 的连续字符折成一个下划线，去掉首尾下划线与开头的数字 / 下划线，
+ * 截到 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;

package/dist/tools/naming.js

@@ -0,0 +1,47 @@
+/**
+ * 工具命名（Global Constraints）：模型可见的工具 key 必须匹配 `^[a-zA-Z0-9_-]{1,64}$`；
+ * 插件工具为 `<plugin>__<tool>`，连接器工具为 `<connectorSlug>__<tool>`，内置工具就是其名字本身。
+ * 超长或含非法字符的 key 一律报出来，不截断、不猜。
+ */
+export const TOOL_KEY_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+export const TOOL_KEY_MAX = 64;
+/** 连接器 slug：小写字母开头，小写字母 / 数字 / 下划线，最长 24。 */
+export const APP_SLUG_RE = /^[a-z][a-z0-9_]{0,23}$/;
+/** 前缀与工具名之间的分隔符。 */
+export const KEY_SEPARATOR = "__";
+/**
+ * slug 是否合法：除正则外，不得含连续下划线、不得以下划线结尾——否则 `a__b` + `c` 与 `a` + `b__c`
+ * 会拼出同一个 key。
+ */
+export function isValidSlug(slug) {
+    return APP_SLUG_RE.test(slug) && !slug.includes("__") && !slug.endsWith("_");
+}
+/** slug 不合法时的英文说明（给 validation_failed 用）。 */
+export const SLUG_RULE = "Slug must start with a lowercase letter, contain only lowercase letters, digits and single underscores, not end with an underscore, and be at most 24 characters";
+/**
+ * 由连接器名推导 slug：转小写，非 `[a-z0-9]` 的连续字符折成一个下划线，去掉首尾下划线与开头的数字 / 下划线，
+ * 截到 24 位（再去掉尾部下划线）。推导不出合法 slug（如名称全是中文）时返回 null，由调用方要求显式给出。
+ */
+export function deriveSlug(name) {
+    const s = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^[^a-z]+/, "")
+        .slice(0, 24)
+        .replace(/_+$/, "");
+    return isValidSlug(s) ? s : null;
+}
+/** 拼 `<prefix>__<name>`。 */
+export function toolKey(prefix, name) {
+    return `${prefix}${KEY_SEPARATOR}${name}`;
+}
+/** key 不合法时返回英文原因，合法时返回 null。 */
+export function toolKeyIssue(key) {
+    if (key.length > TOOL_KEY_MAX) {
+        return `Tool key "${key}" is ${key.length} characters; the limit is ${TOOL_KEY_MAX}`;
+    }
+    if (!TOOL_KEY_RE.test(key)) {
+        return `Tool key "${key}" contains characters outside [a-zA-Z0-9_-]`;
+    }
+    return null;
+}