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

package/dist/tools/questions.service.js

@@ -0,0 +1,295 @@
+import { randomUUID } from "node:crypto";
+import { validateAnswer, } from "@capybara-hq/plugin-sdk";
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+const notFound = () => new ApiError("question.not_found", "Question not found");
+const notInitiator = () => new ApiError("forbidden", "Only the user who started the run can answer this question");
+const toView = ({ state: _state, ...rest }) => rest;
+const iso = (v) => new Date(v).toISOString();
+function toRecord(r) {
+    const spec = r.spec;
+    return {
+        id: r.id,
+        orgId: r.org_id,
+        conversationId: r.conversation_id,
+        runId: r.run_id,
+        callId: r.call_id,
+        attempt: r.attempt,
+        toolKey: spec.toolKey,
+        step: spec.step,
+        form: spec.form,
+        state: spec.state ?? null,
+        status: r.status,
+        answer: (r.answer ?? null),
+        answeredBy: r.answered_by,
+        answeredAt: r.answered_at === null ? null : iso(r.answered_at),
+        expiresAt: iso(r.expires_at),
+        createdAt: iso(r.created_at),
+    };
+}
+const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+ * 输入请求：新建（tools 节点）、回答（只有对话发起人）、超时与取消（等待机制）。
+ * 状态全部在 PG：回答 / 超时 / 取消都在事务里 `SELECT … FOR UPDATE` 该行，多副本并发时恰好一个生效，
+ * 只有生效的那次写 `question_answered`。HTTP 接口见 questions.controller.ts。
+ */
+export class QuestionsService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * 新建 pending 输入请求（`expires_at` = 现在 + `tools.approvalTimeoutHours`）并写 `question_asked`，同一事务。
+     * 按 (run_id, call_id, attempt) 幂等：已存在则返回已有记录，事件按 `question_asked:<id>` 幂等。
+     */
+    async ask(input) {
+        const { db, eventLog, config } = this.deps;
+        const hours = config().tools.approvalTimeoutHours;
+        const spec = {
+            form: input.form,
+            state: input.state ?? null,
+            toolKey: input.toolKey,
+            step: input.step,
+        };
+        const { record, toSeq } = await db.transaction().execute(async (t) => {
+            await t
+                .insertInto("questions")
+                .values({
+                id: randomUUID(),
+                org_id: input.orgId,
+                conversation_id: input.conversationId,
+                run_id: input.runId,
+                call_id: input.callId,
+                attempt: input.attempt,
+                spec: JSON.stringify(spec),
+                answer: null,
+                answered_by: null,
+                expires_at: sql `now() + ${hours}::integer * interval '1 hour'`,
+            })
+                .onConflict((oc) => oc.columns(["run_id", "call_id", "attempt"]).doNothing())
+                .execute();
+            const row = await t
+                .selectFrom("questions")
+                .selectAll()
+                .where("run_id", "=", input.runId)
+                .where("call_id", "=", input.callId)
+                .where("attempt", "=", input.attempt)
+                .executeTakeFirstOrThrow();
+            const rec = toRecord(row);
+            const written = await eventLog.append(rec.conversationId, [
+                {
+                    type: "question_asked",
+                    runId: rec.runId,
+                    idemKey: `question_asked:${rec.id}`,
+                    payload: {
+                        step: rec.step,
+                        callId: rec.callId,
+                        questionId: rec.id,
+                        form: rec.form,
+                        expiresAt: rec.expiresAt,
+                    },
+                },
+            ], t);
+            return { record: rec, toSeq: Math.max(...written.map((e) => e.seq)) };
+        });
+        await eventLog.notify(record.conversationId, toSeq);
+        return record;
+    }
+    /**
+     * 读一条输入请求（网页展示表单用）：只有该运行的发起人（其他人 → 403 `forbidden`）；
+     * 不属于该组织 / 不存在 → `question.not_found`。
+     */
+    async get(orgId, questionId, accountId) {
+        const row = await this.deps.db
+            .selectFrom("questions")
+            .innerJoin("runs", "runs.id", "questions.run_id")
+            .selectAll("questions")
+            .select("runs.trigger_account_id")
+            .where("questions.id", "=", questionId)
+            .where("questions.org_id", "=", orgId)
+            .executeTakeFirst();
+        if (!row)
+            throw notFound();
+        if (row.trigger_account_id !== accountId)
+            throw notInitiator();
+        return toView(toRecord(row));
+    }
+    /** 某个调用的全部输入请求（按轮次升序）。 */
+    async forCall(runId, callId) {
+        const rows = await this.deps.db
+            .selectFrom("questions")
+            .selectAll()
+            .where("run_id", "=", runId)
+            .where("call_id", "=", callId)
+            .orderBy("attempt")
+            .execute();
+        return rows.map(toRecord);
+    }
+    /**
+     * 回答：只有该运行的发起人（其他人 → 403 `forbidden`；传 `orgId` 时别的组织的输入请求 → `question.not_found`）；非 pending 或已到期 →
+     * `question.already_answered`；答案不符合表单（`validateAnswer`）→ `validation_failed`。
+     * 同一事务写状态与 `question_answered`（幂等键 `question_answered:<id>`）；提交后发布事件并调用 `onAnswered`（续跑）。
+     * 传 `orgId` 时还要求输入请求属于该组织（HTTP 接口用）。
+     */
+    async answer(questionId, accountId, answer, orgId) {
+        const { db, eventLog } = this.deps;
+        const { record, toSeq } = await db.transaction().execute(async (t) => {
+            let q = t
+                .selectFrom("questions")
+                .selectAll()
+                .select(sql `expires_at <= now()`.as("expired"))
+                .where("id", "=", questionId);
+            if (orgId !== undefined)
+                q = q.where("org_id", "=", orgId);
+            const locked = await q.forUpdate().executeTakeFirst();
+            if (!locked)
+                throw notFound();
+            const run = await t
+                .selectFrom("runs")
+                .select("trigger_account_id")
+                .where("id", "=", locked.run_id)
+                .executeTakeFirst();
+            if (run?.trigger_account_id !== accountId)
+                throw notInitiator();
+            const before = toRecord(locked);
+            if (before.status !== "pending") {
+                throw new ApiError("question.already_answered", "Question has already been answered");
+            }
+            if (locked.expired) {
+                throw new ApiError("question.already_answered", "Question has expired");
+            }
+            const problems = isPlainObject(answer)
+                ? validateAnswer(before.form, answer)
+                : ["answer must be an object"];
+            if (problems.length > 0) {
+                throw new ApiError("validation_failed", "Answer does not match the form", problems.map((message) => ({ path: "answer", message })));
+            }
+            const updated = await t
+                .updateTable("questions")
+                .set({
+                status: "answered",
+                answer: JSON.stringify(answer),
+                answered_by: accountId,
+                answered_at: sql `now()`,
+            })
+                .where("id", "=", questionId)
+                .returningAll()
+                .executeTakeFirstOrThrow();
+            const toSeq = await this.answeredEvent(t, before, answer, accountId, "answered");
+            return { record: toRecord(updated), toSeq };
+        });
+        await eventLog.notify(record.conversationId, toSeq);
+        if (this.deps.onAnswered) {
+            try {
+                await this.deps.onAnswered(record);
+            }
+            catch (err) {
+                this.deps.log.warn("question onAnswered hook failed", { questionId: record.id, err });
+            }
+        }
+        return record;
+    }
+    /**
+     * 超时（等待机制的超时任务调用）：仍 pending 且已到期 → 置 expired、写 `question_answered{expired}`。
+     * 返回 `expired`（本次生效）/ `not_due`（尚未到期）/ `settled`（已回答、已取消或不存在）。
+     */
+    async expire(questionId) {
+        const { db, eventLog } = this.deps;
+        const r = await db.transaction().execute(async (t) => {
+            const locked = await t
+                .selectFrom("questions")
+                .selectAll()
+                .select(sql `expires_at <= now()`.as("expired"))
+                .where("id", "=", questionId)
+                .forUpdate()
+                .executeTakeFirst();
+            if (!locked)
+                return { outcome: "settled" };
+            const before = toRecord(locked);
+            if (before.status !== "pending")
+                return { outcome: "settled", record: before };
+            if (!locked.expired)
+                return { outcome: "not_due", record: before };
+            const updated = await t
+                .updateTable("questions")
+                .set({ status: "expired", answered_at: sql `now()` })
+                .where("id", "=", questionId)
+                .returningAll()
+                .executeTakeFirstOrThrow();
+            const toSeq = await this.answeredEvent(t, before, null, null, "expired");
+            return { outcome: "expired", record: toRecord(updated), toSeq };
+        });
+        if ("toSeq" in r && r.toSeq !== undefined && r.record) {
+            await eventLog.notify(r.record.conversationId, r.toSeq);
+        }
+        return r.record ? { outcome: r.outcome, record: r.record } : { outcome: r.outcome };
+    }
+    /**
+     * 在事务 `t` 内取消运行的全部 pending 输入请求（运行在等待中被中止），各写 `question_answered{cancelled}`。
+     * 返回被取消的记录；调用方提交后发布事件。
+     */
+    async cancelPendingIn(t, runId) {
+        const rows = await t
+            .selectFrom("questions")
+            .selectAll()
+            .where("run_id", "=", runId)
+            .where("status", "=", "pending")
+            .orderBy("created_at")
+            .forUpdate()
+            .execute();
+        const out = [];
+        for (const row of rows) {
+            const updated = await t
+                .updateTable("questions")
+                .set({ status: "cancelled", answered_at: sql `now()` })
+                .where("id", "=", row.id)
+                .returningAll()
+                .executeTakeFirstOrThrow();
+            const rec = toRecord(row);
+            await this.answeredEvent(t, rec, null, null, "cancelled");
+            out.push(toRecord(updated));
+        }
+        return out;
+    }
+    /**
+     * 在事务 `t` 内取消某组织里由 `accountId` 发起的运行上的全部 pending 输入请求（只有运行发起人能回答，
+     * 即「其作为处理人」的提问；成员离职时调用），走与 {@link cancelPendingIn} 相同的取消路径：置 cancelled、
+     * 写 `question_answered{cancelled}`。返回被取消的记录与各会话写到的最大 seq；调用方提交后发布事件。
+     */
+    async cancelPendingFor(t, orgId, accountId) {
+        const rows = await t
+            .selectFrom("questions")
+            .selectAll()
+            .where("org_id", "=", orgId)
+            .where("status", "=", "pending")
+            .where("run_id", "in", (eb) => eb.selectFrom("runs").select("id").where("trigger_account_id", "=", accountId))
+            .orderBy("created_at")
+            .forUpdate()
+            .execute();
+        const records = [];
+        const seqs = new Map();
+        for (const row of rows) {
+            const updated = await t
+                .updateTable("questions")
+                .set({ status: "cancelled", answered_at: sql `now()` })
+                .where("id", "=", row.id)
+                .returningAll()
+                .executeTakeFirstOrThrow();
+            const seq = await this.answeredEvent(t, toRecord(row), null, null, "cancelled");
+            seqs.set(row.conversation_id, Math.max(seqs.get(row.conversation_id) ?? 0, seq));
+            records.push(toRecord(updated));
+        }
+        return { records, seqs };
+    }
+    async answeredEvent(t, q, answer, byAccountId, outcome) {
+        const written = await this.deps.eventLog.append(q.conversationId, [
+            {
+                type: "question_answered",
+                runId: q.runId,
+                idemKey: `question_answered:${q.id}`,
+                payload: { questionId: q.id, callId: q.callId, answer, byAccountId, outcome },
+            },
+        ], t);
+        return Math.max(...written.map((e) => e.seq));
+    }
+}

package/dist/tools/redact.d.ts

@@ -0,0 +1,20 @@
+import type { AuthInjection } from "@capybara-hq/plugin-sdk";
+/**
+ * 工具结果打码（Review Focus 3）：远端服务可能把收到的凭据回显在结果或错误里，而工具结果会进事件日志、
+ * 工具输出存档并发给模型。管线在写入之前，用「本次调用实际注入的凭据」打码——值是精确已知的（不依赖进程内
+ * logger 的打码集合，多副本下同样成立），匹配器与 logger 共用（`createRedactor`）。
+ *
+ * 下限（Ruling A12）：按调用打码只用这一次调用自己的凭据，不存在「租户用短值遮蔽别人」的问题，所以下限取
+ * {@link RESULT_REDACT_MIN} = 6（短 API key 也遮住）；logger 的组织来源集合仍是 12（Ruling A2）。
+ */
+/** 按调用打码工具结果的最短值长度。 */
+export declare const RESULT_REDACT_MIN = 6;
+/**
+ * 一次注入里可能被回显的凭据值：头 / query 的值，`<scheme> <token>` 里的 token，Basic 解码后的串与密码，
+ * 以及它们的 `encodeURIComponent` 形式（query 参数、URL 里的回显是百分号编码的）。
+ */
+export declare function injectionSecrets(inj: AuthInjection): string[];
+/** 递归替换值里所有字符串（对象键不动）。 */
+export declare function redactDeep(value: unknown, redact: (s: string) => string): unknown;
+/** 由若干次注入构造打码函数。 */
+export declare function redactorFor(injections: readonly AuthInjection[]): (s: string) => string;

package/dist/tools/redact.js

@@ -0,0 +1,60 @@
+import { createRedactor } from "../log.js";
+/**
+ * 工具结果打码（Review Focus 3）：远端服务可能把收到的凭据回显在结果或错误里，而工具结果会进事件日志、
+ * 工具输出存档并发给模型。管线在写入之前，用「本次调用实际注入的凭据」打码——值是精确已知的（不依赖进程内
+ * logger 的打码集合，多副本下同样成立），匹配器与 logger 共用（`createRedactor`）。
+ *
+ * 下限（Ruling A12）：按调用打码只用这一次调用自己的凭据，不存在「租户用短值遮蔽别人」的问题，所以下限取
+ * {@link RESULT_REDACT_MIN} = 6（短 API key 也遮住）；logger 的组织来源集合仍是 12（Ruling A2）。
+ */
+/** 按调用打码工具结果的最短值长度。 */
+export const RESULT_REDACT_MIN = 6;
+const SCHEME = /^(?:Bearer|Basic|Token)\s+(.+)$/i;
+/**
+ * 一次注入里可能被回显的凭据值：头 / query 的值，`<scheme> <token>` 里的 token，Basic 解码后的串与密码，
+ * 以及它们的 `encodeURIComponent` 形式（query 参数、URL 里的回显是百分号编码的）。
+ */
+export function injectionSecrets(inj) {
+    const raw = rawSecrets(inj);
+    const out = new Set(raw);
+    for (const v of raw)
+        out.add(encodeURIComponent(v));
+    return [...out];
+}
+function rawSecrets(inj) {
+    const out = [];
+    for (const v of [...Object.values(inj.headers), ...Object.values(inj.query ?? {})]) {
+        out.push(v);
+        const m = SCHEME.exec(v);
+        if (!m)
+            continue;
+        const token = m[1];
+        out.push(token);
+        if (/^basic\s/i.test(v)) {
+            const decoded = Buffer.from(token, "base64").toString("utf8");
+            out.push(decoded);
+            const i = decoded.indexOf(":");
+            if (i >= 0)
+                out.push(decoded.slice(i + 1));
+        }
+    }
+    return out;
+}
+/** 递归替换值里所有字符串（对象键不动）。 */
+export function redactDeep(value, redact) {
+    if (typeof value === "string")
+        return redact(value);
+    if (Array.isArray(value))
+        return value.map((v) => redactDeep(v, redact));
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = redactDeep(v, redact);
+        return out;
+    }
+    return value;
+}
+/** 由若干次注入构造打码函数。 */
+export function redactorFor(injections) {
+    return createRedactor(injections.flatMap(injectionSecrets), RESULT_REDACT_MIN);
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,246 @@
+import type { Connector, InputRequired, Logger, ToolAnnotations, ToolCallContext, ToolResult, ToolSpec } from "@capybara-hq/plugin-sdk";
+import type { AgentDefinition } from "../agents/definition.js";
+import type { KernelConfig } from "../config/schema.js";
+import type { ToolView } from "../conversations/events.js";
+import type { KernelDb } from "../db/kernel-schema.js";
+import type { ExtensionHost } from "../extensions/host.js";
+import type { OrgRole } from "../orgs/roles.js";
+import type { Credentials } from "./credentials.js";
+/**
+ * 内核内置工具的名字（Task 10 / Task 19 实现；M5 T8 加沙箱工具）。保存 agent 时内置工具引用按这份清单校验，
+ * 不依赖当前是否已注册，避免实现落地顺序影响已保存的定义；运行时未注册的照常报不可用。
+ * `skill_write`（M5 T15）由 agent 定义显式引用才可用（负责人决定 agent 能否改自己的技能）。
+ */
+export declare const BUILTIN_TOOL_NAMES: readonly ["ask_user", "read_tool_output", "tool_search", "skill_load", "skill_write", "sandbox_bash", "sandbox_read", "sandbox_write", "sandbox_edit", "sandbox_glob", "sandbox_grep", "sandbox_deliver", "agent"];
+/** 保存 agent 时引用校验的问题（`path` 为 `tools.<i>`）。 */
+export interface ToolRefIssue {
+    path: string;
+    message: string;
+}
+/**
+ * 内置工具处理函数的上下文：在 SDK 的 `ToolCallContext` 之上，管线额外传入本步解析出的工具
+ * （`tool_search` 据此搜索）。插件处理函数收到的仍是 `ToolCallContext`。
+ */
+export interface BuiltinCallContext extends ToolCallContext {
+    tools?: readonly ResolvedTool[];
+    /** 本次运行 id（内置工具写自己的事件时用，如沙箱 deliver 的 `artifact_created`）。 */
+    runId?: string;
+    /**
+     * 本次运行的截止时间（epoch 毫秒，`runtime.maxRunSeconds` 起算，Ruling M20）。到点运行被中止；
+     * 沙箱命令按它收紧超时，赶在截止前自己超时、给模型可执行的说明。
+     */
+    runDeadline?: number;
+    /**
+     * The conversation whose sandbox this call uses (sub-agents spec §10.1): the parent conversation
+     * for a sub-agent's call, the conversation itself otherwise (the default when absent).
+     */
+    sandboxConversationId?: string;
+}
+/**
+ * 内置工具的结果：`ToolResult` 之外可带 `loadedTools`（`tool_search` 加载的工具 key，
+ * 管线写进 `tool_result.loadedTools`）。
+ */
+export type BuiltinResult = (ToolResult & {
+    loadedTools?: string[];
+    /**
+     * Structured display view (UI refresh B; the pipeline writes it to `tool_result.view` after
+     * checking it against `ToolViewSchema`). Builtins only: extension tools cannot set it.
+     */
+    view?: ToolView;
+}) | InputRequired;
+/** 内置工具的处理函数（插件的 `ToolHandler` 可直接赋给它）。 */
+export type BuiltinHandler = (input: unknown, ctx: BuiltinCallContext) => Promise<BuiltinResult>;
+/** 内核内置工具（`ask_user` 等，Task 10 实现具体工具）；key 就是 `spec.name`。 */
+export interface BuiltinTool {
+    spec: ToolSpec;
+    defaultPolicy: "allow" | "ask";
+    run: BuiltinHandler;
+    /**
+     * 本次调用的执行时限（毫秒，按已校验的输入算）；缺省为 `tools.timeoutMs`。沙箱 `bash` 按命令自己的超时加余量。
+     */
+    timeoutMs?: (input: unknown) => number;
+    /** 结果转存阈值（字符）：与 `tools.outputSpillChars` 取小者。缺省只用配置。 */
+    spillChars?: number;
+    /** 本部署当前不可用时返回事实原因（英文、可执行，进「工具不可用」提醒）；可用返回 null。 */
+    unavailable?: () => string | null;
+}
+/**
+ * agent 定义里对工具的引用（Task 6 在 `AgentDefinitionSchema` 中落地同形的 zod schema）。
+ * 连接器工具按连接器 id 引用，`tools: "all"` = 该连接器当前所有启用的工具。
+ */
+export type AgentToolRef = {
+    kind: "builtin";
+    name: string;
+} | {
+    kind: "plugin";
+    plugin: string;
+    name: string;
+} | {
+    kind: "connector";
+    connectorId: string;
+    tools: "all" | readonly string[];
+};
+export type ToolPolicy = "allow" | "ask" | "deny";
+export interface ResolvedTool {
+    /** 模型可见名。 */
+    key: string;
+    source: {
+        kind: "builtin";
+        name: string;
+    } | {
+        kind: "plugin";
+        plugin: string;
+        name: string;
+    }
+    /** `resources`：内核补上的 list_resources / read_resource（见 resources.ts），执行时路由到会话的 resources 方法。 */
+     | {
+        kind: "connector";
+        connectorId: string;
+        name: string;
+        resources?: true;
+    };
+    /** 存储 / 注册时的定义（`name` 为来源内的原名，description 与 inputSchema 原样）；模型可见名用 `key`。 */
+    spec: ToolSpec;
+    /** sha256(canonical spec) 前 16 位。 */
+    specHash: string;
+    defaultPolicy: ToolPolicy;
+    /** 内置工具的执行时限（见 {@link BuiltinTool.timeoutMs}）；缺省为 `tools.timeoutMs`。 */
+    timeoutMs?: (input: unknown) => number;
+    /** 内置工具的结果转存阈值（见 {@link BuiltinTool.spillChars}）。 */
+    spillChars?: number;
+    /**
+     * 执行所需的最低组织角色（spec 3.6 R1）。发起人当前角色不足时转为按角色升级的审批
+     * （推给持有该角色的人）。M3 的内置与连接器工具都不设。
+     */
+    requiredRole?: OrgRole;
+}
+/** 不可用的引用：`ref` 尽量写成模型认识的工具 key（`docs__search`、`docs__*`），否则 `app:<id>`。 */
+export interface UnavailableTool {
+    ref: string;
+    reason: string;
+}
+/** 键排序、去掉 undefined 的 JSON（jsonb 不保留键顺序，指纹必须与顺序无关）。 */
+export declare function canonicalJson(v: unknown): string;
+/** The first 16 hex digits of sha256(canonicalJson(v)): a fingerprint independent of key order. */
+export declare function contentHash(v: unknown): string;
+/**
+ * `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 declare const DISPLAY_ONLY_SPEC_FIELDS: readonly ["title", "keyArgs"];
+/** A tool spec without its {@link DISPLAY_ONLY_SPEC_FIELDS} (non-objects unchanged). */
+export declare function withoutDisplayFields<T>(spec: T): T;
+/**
+ * Tool definition fingerprint: {@link contentHash} of the spec without its display-only fields
+ * (`title`, `keyArgs`). Specs without them hash exactly as before.
+ */
+export declare function specHash(spec: unknown): string;
+/** 由注解推导默认策略：只读 → allow；其余（破坏性 / 无注解）→ ask。 */
+export declare function policyFromAnnotations(a: ToolAnnotations | undefined): "allow" | "ask";
+export interface ToolRegistryDeps {
+    db: KernelDb;
+    host: ExtensionHost;
+    credentials: Credentials;
+    log: Logger;
+    builtins: BuiltinTool[];
+    /**
+     * 当前配置（`tools.searchThreshold*`）。不提供时从不启用 `tool_search`（只用于不关心它的测试 / 调用方）。
+     */
+    config?: () => KernelConfig;
+}
+/** `forAgent` 的结果。 */
+export interface AgentTools {
+    tools: ResolvedTool[];
+    unavailable: UnavailableTool[];
+    /**
+     * `tools: "all"` 引用的连接器里未启用的工具（待复核 / 停用 / 已消失）及事实原因。不进 `unavailable`
+     * （那会让每步都写「工具不可用」提醒），只在模型点名调用时用来给事实说明（spec 6.3）。缺省视为空。
+     */
+    hidden?: UnavailableTool[];
+    /**
+     * 本步是否启用 `tool_search`（spec 5.5）：启用时 `tools` 末尾含 `tool_search`，构建请求时只放内置工具
+     * 与已加载工具的完整定义，其余进目录。缺省视为未启用。
+     */
+    toolSearch?: boolean;
+}
+/**
+ * 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 declare class ToolRegistry {
+    private readonly deps;
+    constructor(deps: ToolRegistryDeps);
+    /** `host.list("connector")` 中 `kind` 匹配的第一个实现；未安装返回 undefined。 */
+    findConnector(kind: string): Connector | undefined;
+    /** 同 {@link findConnector}，未安装时抛错。 */
+    connector(kind: string): Connector;
+    /**
+     * 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: ResolvedTool["source"]): BuiltinHandler | undefined;
+    /** The registered builtin tools' specs (display metadata for `tools/info.ts`). */
+    builtinSpecs(): ToolSpec[];
+    /** The loaded extensions' registered tool specs, with their extension's name. */
+    extensionToolSpecs(): {
+        plugin: string;
+        spec: ToolSpec;
+    }[];
+    /** 已安装连接器的 kind 列表（去重，按加载顺序）。 */
+    connectorKinds(): string[];
+    /**
+     * 保存 agent 时校验工具引用（只看「存在」，停用 / 待复核 / 插件未启用等运行时状态不拒绝，由 `forAgent` 报不可用）：
+     * - 内置：名字在 {@link BUILTIN_TOOL_NAMES} 中；
+     * - 插件：插件已加载且注册了该工具，key 合法；
+     * - 连接器：连接器属于本组织且未删除；点名的工具必须在连接器的工具快照中。
+     * 不同来源拼出同一个 key 也报出来（不截断、不猜）。
+     * 返回 `keys`：这些引用可能产生的全部工具 key（`"all"` 含连接器当前所有工具，不论状态），供校验 `toolPolicies`。
+     */
+    checkRefs(orgId: string, refs: readonly AgentToolRef[]): Promise<{
+        keys: Set<string>;
+        issues: ToolRefIssue[];
+    }>;
+    /**
+     * 解析 agent 引用的工具（见类注释），再判定是否启用 `tool_search`：组织设置 `toolSearch === "on"`，且
+     * 可用工具数 > `tools.searchThresholdTools` 或其定义的估算 token > `tools.searchThresholdTokens`。
+     * 启用时把内置 `tool_search` 追加到末尾。定义里显式引用的 `tool_search` 忽略（由这里按设置管理）。
+     * `skillLoad`：对话日志里有技能目录快照（`skills_catalog`，Ruling M17）→ 加入内置 `skill_load`（始终完整加载）；
+     * 定义里显式引用的 `skill_load` 同样忽略。
+     */
+    forAgent(orgId: string, def: {
+        tools: readonly AgentToolRef[];
+        skillLoad?: boolean;
+        /** The definition's sub-agent roster source: the `agent` tool's description lists it. */
+        subagents?: AgentDefinition["subagents"];
+    }): Promise<AgentTools>;
+    /** 是否启用 `tool_search`（见 {@link forAgent}）；先比阈值，超过才读组织设置。 */
+    private searchActive;
+    private resolve;
+    /**
+     * `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.
+     */
+    private maxConcurrentSubagents;
+    /** Plugins the organization enabled (built-in plugins always count as enabled, C14). */
+    private enabledPlugins;
+    private loadConnectors;
+}