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

package/dist/tools/questions.service.js

@@ -1,7 +1,23 @@
+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 { randomUUID } from "node:crypto";
-import { validateAnswer, } from "@capybara-hq/plugin-sdk";
+import { validateAnswer } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
+import { EventLog } from "../conversations/event-log.js";
 import { ApiError } from "../errors.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { KernelEvents } from "../infra/events/kernel-events.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;
@@ -32,75 +48,88 @@ const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArr
  * 输入请求：新建（tools 节点）、回答（只有对话发起人）、超时与取消（等待机制）。
  * 状态全部在 PG：回答 / 超时 / 取消都在事务里 `SELECT … FOR UPDATE` 该行，多副本并发时恰好一个生效，
  * 只有生效的那次写 `question_answered`。HTTP 接口见 questions.controller.ts。
+ *
+ * An answer is announced after the commit as the domain event `question.answered` (exactly once),
+ * which the run's waits follow to resume it (spec §3b; the wait sweep resumes a run whose resume was
+ * lost). Events are appended in the context's transaction (`EventLog.appendIn`).
  */
-export class QuestionsService {
-    deps;
-    constructor(deps) {
-        this.deps = deps;
+let QuestionsService = class QuestionsService {
+    db;
+    config;
+    eventLog;
+    events;
+    txHost;
+    constructor(db, config, eventLog, events, txHost) {
+        this.db = db;
+        this.config = config;
+        this.eventLog = eventLog;
+        this.events = events;
+        this.txHost = txHost;
     }
     /**
      * 新建 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 { record, toSeq } = await this.askIn(input);
+        await this.eventLog.notify(record.conversationId, toSeq);
+        return record;
+    }
+    async askIn(input) {
+        const hours = this.config.get().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,
-                    },
+        const t = this.db.db;
+        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 this.eventLog.appendIn(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;
+            },
+        ]);
+        return { record: rec, toSeq: Math.max(...written.map((e) => e.seq)) };
     }
     /**
      * 读一条输入请求（网页展示表单用）：只有该运行的发起人（其他人 → 403 `forbidden`）；
      * 不属于该组织 / 不存在 → `question.not_found`。
      */
     async get(orgId, questionId, accountId) {
-        const row = await this.deps.db
+        const row = await this.db
             .selectFrom("questions")
             .innerJoin("runs", "runs.id", "questions.run_id")
             .selectAll("questions")
@@ -116,7 +145,7 @@ export class QuestionsService {
     }
     /** 某个调用的全部输入请求（按轮次升序）。 */
     async forCall(runId, callId) {
-        const rows = await this.deps.db
+        const rows = await this.db
             .selectFrom("questions")
             .selectAll()
             .where("run_id", "=", runId)
@@ -132,103 +161,107 @@ export class QuestionsService {
      * 传 `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 };
+        const { record, toSeq } = await this.answerIn(questionId, accountId, answer, orgId);
+        await this.eventLog.notify(record.conversationId, toSeq);
+        // waits resume the run and its IM delivery is enqueued (handler failures are logged)
+        await this.events.emit("question.answered", {
+            id: record.id,
+            orgId: record.orgId,
+            conversationId: record.conversationId,
+            runId: record.runId,
         });
-        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;
     }
+    // its own transaction (as the legacy one was): `question.answered` is emitted only after the
+    // answer committed, even when a caller has a transaction open
+    async answerIn(questionId, accountId, answer, orgId) {
+        const t = this.db.db;
+        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(before, answer, accountId, "answered");
+        return { record: toRecord(updated), toSeq };
+    }
     /**
      * 超时（等待机制的超时任务调用）：仍 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 };
-        });
+        const r = await this.expireIn(questionId);
         if ("toSeq" in r && r.toSeq !== undefined && r.record) {
-            await eventLog.notify(r.record.conversationId, r.toSeq);
+            await this.eventLog.notify(r.record.conversationId, r.toSeq);
         }
         return r.record ? { outcome: r.outcome, record: r.record } : { outcome: r.outcome };
     }
+    async expireIn(questionId) {
+        const t = this.db.db;
+        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(before, null, null, "expired");
+        return { outcome: "expired", record: toRecord(updated), toSeq };
+    }
     /**
-     * 在事务 `t` 内取消运行的全部 pending 输入请求（运行在等待中被中止），各写 `question_answered{cancelled}`。
-     * 返回被取消的记录；调用方提交后发布事件。
+     * 在调用方的事务内（`mandatory`）取消运行的全部 pending 输入请求（运行在等待中被中止），各写
+     * `question_answered{cancelled}`。返回被取消的记录；调用方提交后发布事件。
      */
-    async cancelPendingIn(t, runId) {
+    async cancelPendingIn(runId) {
+        const t = this.db.db;
         const rows = await t
             .selectFrom("questions")
             .selectAll()
@@ -246,17 +279,18 @@ export class QuestionsService {
                 .returningAll()
                 .executeTakeFirstOrThrow();
             const rec = toRecord(row);
-            await this.answeredEvent(t, rec, null, null, "cancelled");
+            await this.answeredEvent(rec, null, null, "cancelled");
             out.push(toRecord(updated));
         }
         return out;
     }
     /**
-     * 在事务 `t` 内取消某组织里由 `accountId` 发起的运行上的全部 pending 输入请求（只有运行发起人能回答，
+     * 在调用方的事务内（`mandatory`）取消某组织里由 `accountId` 发起的运行上的全部 pending 输入请求（只有运行发起人能回答，
      * 即「其作为处理人」的提问；成员离职时调用），走与 {@link cancelPendingIn} 相同的取消路径：置 cancelled、
      * 写 `question_answered{cancelled}`。返回被取消的记录与各会话写到的最大 seq；调用方提交后发布事件。
      */
-    async cancelPendingFor(t, orgId, accountId) {
+    async cancelPendingFor(orgId, accountId) {
+        const t = this.db.db;
         const rows = await t
             .selectFrom("questions")
             .selectAll()
@@ -275,21 +309,46 @@ export class QuestionsService {
                 .where("id", "=", row.id)
                 .returningAll()
                 .executeTakeFirstOrThrow();
-            const seq = await this.answeredEvent(t, toRecord(row), null, null, "cancelled");
+            const seq = await this.answeredEvent(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, [
+    /** `question_answered` in the current transaction; returns its seq. */
+    async answeredEvent(q, answer, byAccountId, outcome) {
+        const written = await this.eventLog.appendIn(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));
     }
-}
+};
+__decorate([
+    Transactional()
+], QuestionsService.prototype, "askIn", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], QuestionsService.prototype, "answerIn", null);
+__decorate([
+    Transactional()
+], QuestionsService.prototype, "expireIn", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], QuestionsService.prototype, "cancelPendingIn", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], QuestionsService.prototype, "cancelPendingFor", null);
+QuestionsService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(KernelConfigService)),
+    __param(2, Inject(EventLog)),
+    __param(3, Inject(KernelEvents)),
+    __param(4, Inject(TransactionHost))
+], QuestionsService);
+export { QuestionsService };

package/dist/tools/registry.d.ts

@@ -1,17 +1,14 @@
-import type { Connector, InputRequired, Logger, ToolAnnotations, ToolCallContext, ToolResult, ToolSpec } from "@capybara-hq/plugin-sdk";
+import type { Connector, InputRequired, 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 { ExtensionHost } from "../extensions/host.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.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"];
+import { BuiltinTools } from "./builtins/builtin-tools.js";
+export { BUILTIN_TOOL_NAMES } from "./builtin-names.js";
+export { canonicalJson } from "./canonical-json.js";
 /** 保存 agent 时引用校验的问题（`path` 为 `tools.<i>`）。 */
 export interface ToolRefIssue {
     path: string;
@@ -19,7 +16,7 @@ export interface ToolRefIssue {
 }
 /**
  * 内置工具处理函数的上下文：在 SDK 的 `ToolCallContext` 之上，管线额外传入本步解析出的工具
- * （`tool_search` 据此搜索）。插件处理函数收到的仍是 `ToolCallContext`。
+ * （`ToolSearch` 据此搜索）。插件处理函数收到的仍是 `ToolCallContext`。
  */
 export interface BuiltinCallContext extends ToolCallContext {
     tools?: readonly ResolvedTool[];
@@ -37,7 +34,7 @@ export interface BuiltinCallContext extends ToolCallContext {
     sandboxConversationId?: string;
 }
 /**
- * 内置工具的结果：`ToolResult` 之外可带 `loadedTools`（`tool_search` 加载的工具 key，
+ * 内置工具的结果：`ToolResult` 之外可带 `loadedTools`（`ToolSearch` 加载的工具 key，
  * 管线写进 `tool_result.loadedTools`）。
  */
 export type BuiltinResult = (ToolResult & {
@@ -50,7 +47,7 @@ export type BuiltinResult = (ToolResult & {
 }) | InputRequired;
 /** 内置工具的处理函数（插件的 `ToolHandler` 可直接赋给它）。 */
 export type BuiltinHandler = (input: unknown, ctx: BuiltinCallContext) => Promise<BuiltinResult>;
-/** 内核内置工具（`ask_user` 等，Task 10 实现具体工具）；key 就是 `spec.name`。 */
+/** 内核内置工具（`AskUserQuestion` 等，Task 10 实现具体工具）；key 就是 `spec.name`。 */
 export interface BuiltinTool {
     spec: ToolSpec;
     defaultPolicy: "allow" | "ask";
@@ -114,13 +111,11 @@ export interface ResolvedTool {
      */
     requiredRole?: OrgRole;
 }
-/** 不可用的引用：`ref` 尽量写成模型认识的工具 key（`docs__search`、`docs__*`），否则 `app:<id>`。 */
+/** 不可用的引用：`ref` 尽量写成模型认识的工具 key（`mcp__docs__search`、`mcp__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;
 /**
@@ -138,17 +133,6 @@ export declare function withoutDisplayFields<T>(spec: T): T;
 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[];
@@ -159,7 +143,7 @@ export interface AgentTools {
      */
     hidden?: UnavailableTool[];
     /**
-     * 本步是否启用 `tool_search`（spec 5.5）：启用时 `tools` 末尾含 `tool_search`，构建请求时只放内置工具
+     * 本步是否启用 `ToolSearch`（spec 5.5）：启用时 `tools` 末尾含 `ToolSearch`，构建请求时只放内置工具
      * 与已加载工具的完整定义，其余进目录。缺省视为未启用。
      */
     toolSearch?: boolean;
@@ -182,8 +166,29 @@ export interface AgentTools {
  * different sources with the same key report a duplicate.
  */
 export declare class ToolRegistry {
-    private readonly deps;
-    constructor(deps: ToolRegistryDeps);
+    private readonly db;
+    /** Extension tools and the organization's enabled extensions. */
+    private readonly host;
+    /** The installed connectors (`connector@1`, from the extension registry). */
+    private readonly extensions;
+    private readonly builtinTools;
+    /**
+     * `tools.searchThreshold*` and the sub-agent limits. Absent (some tests): `ToolSearch` is never
+     * offered and the sub-agent limits are the schema defaults.
+     */
+    private readonly config?;
+    constructor(db: KernelDb, 
+    /** Extension tools and the organization's enabled extensions. */
+    host: Pick<ExtensionHost, "tools" | "enabledPlugins">, 
+    /** The installed connectors (`connector@1`, from the extension registry). */
+    extensions: Pick<ExtensionRegistry, "list">, builtinTools: Pick<BuiltinTools, "list">, 
+    /**
+     * `tools.searchThreshold*` and the sub-agent limits. Absent (some tests): `ToolSearch` is never
+     * offered and the sub-agent limits are the schema defaults.
+     */
+    config?: Pick<KernelConfigService, "get"> | undefined);
+    /** The kernel's builtin tools (`ToolSearch` is added by {@link forAgent}, not by definitions). */
+    private get builtins();
     /** `host.list("connector")` 中 `kind` 匹配的第一个实现；未安装返回 undefined。 */
     findConnector(kind: string): Connector | undefined;
     /** 同 {@link findConnector}，未安装时抛错。 */
@@ -218,23 +223,23 @@ export declare class ToolRegistry {
         issues: ToolRefIssue[];
     }>;
     /**
-     * 解析 agent 引用的工具（见类注释），再判定是否启用 `tool_search`：组织设置 `toolSearch === "on"`，且
+     * 解析 agent 引用的工具（见类注释），再判定是否启用 `ToolSearch`：组织设置 `toolSearch === "on"`，且
      * 可用工具数 > `tools.searchThresholdTools` 或其定义的估算 token > `tools.searchThresholdTokens`。
-     * 启用时把内置 `tool_search` 追加到末尾。定义里显式引用的 `tool_search` 忽略（由这里按设置管理）。
-     * `skillLoad`：对话日志里有技能目录快照（`skills_catalog`，Ruling M17）→ 加入内置 `skill_load`（始终完整加载）；
-     * 定义里显式引用的 `skill_load` 同样忽略。
+     * 启用时把内置 `ToolSearch` 追加到末尾。定义里显式引用的 `ToolSearch` 忽略（由这里按设置管理）。
+     * `skillLoad`：对话日志里有技能目录快照（`skills_catalog`，Ruling M17）→ 加入内置 `Skill`（始终完整加载）；
+     * 定义里显式引用的 `Skill` 同样忽略。
      */
     forAgent(orgId: string, def: {
         tools: readonly AgentToolRef[];
         skillLoad?: boolean;
-        /** The definition's sub-agent roster source: the `agent` tool's description lists it. */
+        /** The definition's sub-agent roster source: the `Agent` tool's description lists it. */
         subagents?: AgentDefinition["subagents"];
     }): Promise<AgentTools>;
-    /** 是否启用 `tool_search`（见 {@link forAgent}）；先比阈值，超过才读组织设置。 */
+    /** 是否启用 `ToolSearch`（见 {@link forAgent}）；先比阈值，超过才读组织设置。 */
     private searchActive;
     private resolve;
     /**
-     * `subagents.maxConcurrentPerRun` with the organization's override, for the `agent` tool's
+     * `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.