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

package/dist/tools/pipeline.js

@@ -0,0 +1,1236 @@
+import { ToolError, validateInputForm, validateToolDisplay, } from "@capybara-hq/plugin-sdk";
+import { normalizeStoredDefinition } from "../agents/definition.js";
+import { ToolViewSchema } from "../conversations/events.js";
+import { clipText } from "../extensions/hooks.js";
+import { ExtensionUnloadedError, PLUGIN_UNLOADED_TOOL_ERROR } from "../extensions/inflight.js";
+import { audit } from "../identity/audit.js";
+import { UNKNOWN_RESULT_TEXT } from "../runtime/context/pairing.js";
+import { fireObserve, hookDeniedAudit, hookDeniedEvent, hookScope, } from "../runtime/hook-calls.js";
+import { subagentsWaitId, subagentWaitingIdemKey, } from "../runtime/loop.js";
+import { assistantIdemKey, MAX_MODEL_ATTEMPTS, modelCallIdemKey } from "../runtime/model-call.js";
+import { TERMINAL_STATUSES } from "../runtime/run-finish.js";
+import { childResult, dispatchOfCall, finishedEvent, } from "../runtime/subagents/child.js";
+import { forkSeqOfCall, pairStoppedForks } from "../runtime/subagents/skill-fork.js";
+import { skillLoadOfferedIn } from "../skills/catalog.js";
+import { breakerOpenMessage } from "./breaker.js";
+import { AGENT_STOPPED_WITH_RUN_TEXT, AGENT_TOOL, AgentToolInput, } from "./builtins/agent.js";
+import { isAlwaysLoaded, notLoadedText } from "./builtins/tool-search.js";
+import { CredentialMissing } from "./credentials.js";
+import { ElicitationSession } from "./elicitation.js";
+import { renderResult, resolveOutputRefs, spillIfLarge } from "./outputs.js";
+import { createDecidePolicy } from "./policy.js";
+import { redactDeep, redactorFor } from "./redact.js";
+import { runResourceTool } from "./resources.js";
+import { validateInput } from "./validate.js";
+// ---- 模型可见文案（英文） ----
+/** 审批被拒绝。 */
+export const APPROVAL_DENIED_TEXT = "The user denied this tool call.";
+/**
+ * The denied call's result when the approver gave a reason (model-visible, in the log). "An
+ * approver": under role escalation an admin, not the requester, decides. Older logs keep the text
+ * they recorded ("The user denied this tool call. Reason: …"); only new denials use this one.
+ */
+export const approvalDeniedText = (reason) => reason === null ? APPROVAL_DENIED_TEXT : `An approver denied this tool call. Reason: ${reason}`;
+/** 审批超时（按拒绝）。 */
+export const approvalExpiredText = (hours) => `Approval timed out after ${hours}h; treated as denied.`;
+/** 等待审批期间 run 被中止。 */
+export const APPROVAL_CANCELLED_TEXT = "The run was stopped while waiting for approval.";
+/** 等待用户输入期间 run 被中止。 */
+export const INPUT_CANCELLED_TEXT = "The run was stopped while waiting for user input.";
+/** 同一调用连续请求输入超过上限。 */
+export const TOO_MANY_INPUT_REQUESTS_TEXT = "Tool requested user input too many times.";
+/** run 已被中止 / 到达截止时间，调用尚未开始执行。 */
+export const RUN_STOPPED_TEXT = "The run was stopped before this tool call was executed.";
+/** 调用执行中 run 被中止 / 到达截止时间。 */
+export const RUN_STOPPED_DURING_TEXT = "The run was stopped while this tool call was running; its outcome is unknown. Verify before retrying.";
+const timeoutText = (key, ms) => `Tool ${key} timed out after ${ms / 1000}s. The operation may or may not have completed; verify before retrying.`;
+const failedText = (key, errName) => `Tool ${key} failed (${errName}). The operation may not have completed; check before retrying or try another approach.`;
+const unknownToolText = (name, keys, toolSearch) => `Unknown tool "${name}". Available tools: ${keys.length === 0 ? "(none)" : keys.join(", ")}.` +
+    (toolSearch ? " Use tool_search to load other tools." : "");
+const unavailableText = (name, reason) => `Tool "${name}" is unavailable: ${reason}.`;
+const deniedText = (key) => `Tool ${key} is denied by policy.`;
+/** Longest hook reason quoted in {@link hookDeniedText}. */
+const HOOK_REASON_MAX = 500;
+/**
+ * A plugin policy hook denied the call (model-visible). `reason` is the sanitized deny reason, or the
+ * generic sentence for a hook error / timeout; truncated to 500 characters.
+ */
+export const hookDeniedText = (plugin, reason) => `Tool call blocked by the "${plugin}" policy hook: ${clipText(reason, HOOK_REASON_MAX)}`;
+const invalidFormText = (key, problems) => `Tool ${key} returned an invalid input form: ${problems.join("; ")}.`;
+const stateTooLargeText = (key) => `Tool ${key} returned input state larger than ${MAX_INPUT_STATE_BYTES / 1024} KB.`;
+const personalMissingText = (connectorName) => `The user has not connected ${connectorName}. A connect card was shown; ask the user to connect, then retry.`;
+const orgMissingText = (connectorName) => `${connectorName} has no organization credential configured; ask an organization admin to set it up.`;
+/** `runCall` dispatched a sub-agent: the call stays open until the child run finishes. */
+const OPEN = "open";
+/**
+ * The wait of a step whose sub-agents still run (spec §7.2): id `sa-<runId>-<step>`, expiring after
+ * the approval timeout plus one run's duration plus 10 minutes (a child may itself wait for an
+ * approval); the timeout is a safety net.
+ */
+export function subagentsWait(runId, step, config, now = Date.now()) {
+    const ms = config.tools.approvalTimeoutHours * 3_600_000 + config.runtime.maxRunSeconds * 1000 + 600_000;
+    return {
+        kind: "subagents",
+        id: subagentsWaitId(runId, step),
+        expiresAt: new Date(now + ms).toISOString(),
+        step,
+    };
+}
+const approvalAuthorization = (a) => ({
+    approvalId: a.id,
+    approvedByAccountId: a.decidedBy,
+    scope: a.scope,
+});
+/**
+ * 幂等键（brief 约定）。同一调用因请求用户输入而被再次调用时，第 n（≥ 2）次调用的开始事件带轮次后缀。
+ */
+const idem = {
+    started: (runId, callId, attempt = 1) => attempt === 1
+        ? `tool_started:${runId}:${callId}`
+        : `tool_started:${runId}:${callId}:${attempt}`,
+    result: (runId, callId) => `tool_result:${runId}:${callId}`,
+    connection: (runId, callId) => `connection_required:${runId}:${callId}`,
+    hookDenied: (runId, callId) => `hook_denied:${runId}:${callId}`,
+};
+/** 同一调用最多连续请求用户输入的次数。 */
+const MAX_INPUT_ROUNDS = 3;
+/** 输入请求 state 的上限（JSON 序列化后的字节数）。 */
+const MAX_INPUT_STATE_BYTES = 16 * 1024;
+/** 关闭会话时最多等待的时间（连接器 close 卡住不拖住运行）。 */
+const CLOSE_WAIT_MS = 5_000;
+const errName = (e) => e instanceof Error && typeof e.name === "string" && e.name !== "" ? e.name : "Error";
+const isInputRequired = (v) => typeof v === "object" && v !== null && v.kind === "input_required";
+/**
+ * 内置工具结果里的 `loadedTools`（见 `BuiltinResult`）：只保留本步可用、非内置的工具 key，去重、保持顺序。
+ */
+function loadedFrom(result, tools) {
+    const raw = result?.loadedTools;
+    if (!Array.isArray(raw))
+        return [];
+    const known = new Set(tools.filter((t) => !isAlwaysLoaded(t.key)).map((t) => t.key));
+    return [...new Set(raw.filter((k) => typeof k === "string" && known.has(k)))];
+}
+class Stopped extends Error {
+}
+/** 在工具结果末尾附上说明（如被拒绝的 elicitation）；结果不是 `{ content: [] }` 形状时原样返回。 */
+function withNotes(result, notes) {
+    if (notes.length === 0)
+        return result;
+    const content = result?.content;
+    if (!Array.isArray(content))
+        return result;
+    return {
+        ...result,
+        content: [...content, ...notes.map((text) => ({ type: "text", text }))],
+    };
+}
+/** 审批的等待时长（小时，四舍五入，至少 1）。 */
+const approvalHours = (a) => Math.max(1, Math.round((new Date(a.expiresAt).getTime() - new Date(a.createdAt).getTime()) / 3_600_000));
+const approvalWait = (a) => ({
+    kind: "approval",
+    id: a.id,
+    expiresAt: a.expiresAt,
+});
+const inputWait = (q) => ({
+    kind: "input",
+    id: q.id,
+    expiresAt: q.expiresAt,
+});
+/**
+ * 工具执行管线（spec 5.4 / 6.2）：每个阶段是独立函数——
+ * `resolveOutputRefs` → `validateInput` → `decidePolicy` → `execute`（超时、熔断）→ `renderResult` / `spillIfLarge`
+ * → 写 `tool_result` 与审计。
+ *
+ * 有副作用不盲目重跑（spec 4.3）：执行前写 `tool_call_started`；续跑时「有开始无结果」的调用记为结果未知，不再执行。
+ */
+export class ToolPipeline {
+    deps;
+    decide;
+    constructor(deps) {
+        this.deps = deps;
+        this.decide = deps.decidePolicy ?? createDecidePolicy(deps.db);
+    }
+    /**
+     * tools 节点：按顺序处理本步 assistant 消息里的全部 `tool_call`，每个调用都以一条 `tool_result` 结束
+     * （之后才回到 prepare 构建下一次请求，保持「已记录调用、未记录结果之间不构建请求」的不变式）。
+     * 已有结果 → 跳过；有开始无结果 → 结果未知；run 已中止 → 不执行。
+     * 某个调用需要等人处理（审批 / 用户输入）→ 返回 `suspended`，之后的调用留到续跑时处理；
+     * 续跑时重新进入本函数，按 PG 里的审批 / 输入请求结果继续。
+     */
+    async runStep(ctx) {
+        const { eventLog } = this.deps;
+        const msg = await eventLog.findByIdem(ctx.conversationId, assistantIdemKey(ctx.runId, ctx.step));
+        if (msg?.type !== "assistant_message")
+            return { kind: "done" };
+        const calls = msg.payload.content.flatMap((b) => b.type === "tool_call" ? [{ id: b.id, name: b.name, input: b.input }] : []);
+        let resolved;
+        const resolve = async () => {
+            // 每步实时解析（连接器 / 插件状态可能在模型调用之后变化）
+            if (!resolved) {
+                // the request builder's rule: a skills catalog snapshot (even an empty one) or a person's
+                // skill invocation in the log → skill_load is offered (see skillLoadOffered)
+                const skillLoad = await skillLoadOfferedIn(this.deps.db, this.deps.eventLog, ctx.conversationId);
+                resolved = await this.deps.registry.forAgent(ctx.orgId, {
+                    tools: ctx.agent.tools ?? [],
+                    skillLoad,
+                    subagents: ctx.agent.subagents,
+                });
+            }
+            return resolved;
+        };
+        // `agent` calls whose sub-agent still runs (spec §7.1): a dispatch never blocks later calls;
+        // once every call was handled, the step waits for them
+        let open = 0;
+        for (const call of calls) {
+            if (await eventLog.findByIdem(ctx.conversationId, idem.result(ctx.runId, call.id)))
+                continue;
+            if (call.name === AGENT_TOOL) {
+                const row = await dispatchOfCall(this.deps.db, ctx.runId, call.id);
+                if (row) {
+                    if (!(await this.finishAgentCall(ctx, row, call, resolve)))
+                        open++;
+                    continue;
+                }
+            }
+            const waitingFor = await this.processCall(ctx, call, resolve);
+            if (waitingFor === OPEN)
+                open++;
+            else if (waitingFor)
+                return { kind: "suspended", waitingFor };
+        }
+        if (open > 0) {
+            // the run is being stopped (a person, its deadline): it does not wait for its sub-agents;
+            // their calls get their results now, and the children are stopped after the run's terminal
+            // commit (spec §12)
+            if (ctx.signal.aborted) {
+                const stopped = await this.deps.db
+                    .transaction()
+                    .execute((t) => this.stopOpenAgentCalls(t, ctx.runId, ctx.agent));
+                if (stopped.toSeq !== null) {
+                    await eventLog.notify(ctx.conversationId, stopped.toSeq);
+                }
+                stopped.fire();
+                return { kind: "done" };
+            }
+            return {
+                kind: "suspended",
+                waitingFor: subagentsWait(ctx.runId, ctx.step, this.deps.config()),
+            };
+        }
+        return { kind: "done" };
+    }
+    /**
+     * An `agent` call that was dispatched (spec §7.1 "already dispatched"): when its child run is
+     * terminal, writes the parent's `subagent_finished` (if the child's finisher did not) and the
+     * call's `tool_result` from the child's log, and returns true; else false (still open).
+     *
+     * The call ran like any tool, so the result is audited `tool.called` (duration = the child's;
+     * the authorization is known only when an approval let it run: a policy or remembered grant at
+     * dispatch time is not recorded, so nothing is guessed) and fires `tool.postExecute` with the
+     * result, from the replica that writes it (spec §11).
+     */
+    async finishAgentCall(ctx, row, call, resolve) {
+        const modelGiven = typeof call.input === "object" &&
+            call.input !== null &&
+            call.input.model !== undefined;
+        const r = await childResult(this.deps.eventLog, row, { modelGiven });
+        if (!r)
+            return false;
+        // No spec-hash check as in processCall: an `agent` call writes no tool_call_started holding
+        // the executed definition's hash, and its description changes with the roster and limits
+        // while the child runs. The call's approval (forCall: its latest) is by construction the one
+        // that let this dispatch start, since a dispatch happens only after an approved decision.
+        const approval = await this.deps.approvals.forCall(ctx.runId, call.id);
+        await this.writeResult(ctx, row.parentCallId, AGENT_TOOL, { content: r.content, isError: r.isError }, [finishedEvent(row, r.finished)], {
+            durationMs: r.finished.durationMs,
+            connectorId: null,
+            ...(approval?.status === "approved" && {
+                authorization: approvalAuthorization(approval),
+            }),
+        });
+        const hooks = this.deps.pluginHooks;
+        const scope = hookScope(hooks, ctx);
+        if (hooks && scope && hooks.has("tool.postExecute")) {
+            const tool = (await resolve()).tools.find((t) => t.key === AGENT_TOOL);
+            if (tool) {
+                fireObserve(hooks, "tool.postExecute", {
+                    ...scope,
+                    step: ctx.step,
+                    callId: call.id,
+                    toolKey: AGENT_TOOL,
+                    specHash: tool.specHash,
+                    input: call.input,
+                    isError: r.isError,
+                    content: r.content,
+                    durationMs: r.finished.durationMs,
+                }, ctx.signal, this.deps.log);
+            }
+        }
+        return true;
+    }
+    /**
+     * Writes, in `t`, the `tool_result` of every open `agent` call of a run that is being stopped
+     * (sub-agents spec §12: a person stopped it while it waited on sub-agents, or its deadline or a
+     * stop hit its tools node after a dispatch). A call whose child already ended gets the child's
+     * result (and the missing `subagent_finished`); one whose child is still active gets
+     * {@link AGENT_STOPPED_WITH_RUN_TEXT}. The caller stops those children after its commit.
+     *
+     * Like every `agent` result (see {@link finishAgentCall}), each is audited `tool.called` in `t`
+     * (duration: the child's, or the time since the dispatch) and fires `tool.postExecute`, through
+     * `fire()`, which the caller runs after its commit. Returns the steps and calls written (the
+     * caller must not write a "not executed" result for them) and the highest seq written.
+     */
+    async stopOpenAgentCalls(t, runId, agent) {
+        // phase D: the run's fork invocation without a report gets one (a fork has no tool call)
+        const forks = await pairStoppedForks(t, this.deps.eventLog, runId);
+        const none = {
+            steps: [],
+            callIds: new Set(forks.callIds),
+            toSeq: forks.toSeq,
+            fire: () => { },
+        };
+        const all = await t
+            .selectFrom("subagent_dispatches")
+            .select([
+            "parent_run_id",
+            "parent_call_id",
+            "parent_conversation_id",
+            "child_conversation_id",
+            "child_run_id",
+            "step",
+            "created_at",
+        ])
+            .where("parent_run_id", "=", runId)
+            .orderBy("step")
+            .orderBy("created_at")
+            .execute();
+        const dispatches = all.filter((d) => forkSeqOfCall(d.parent_call_id, d.step) === null);
+        if (dispatches.length === 0)
+            return none;
+        const run = await t
+            .selectFrom("runs as r")
+            .innerJoin("conversations as c", "c.id", "r.conversation_id")
+            .select([
+            "r.conversation_id",
+            "r.trigger_account_id",
+            "r.agent_version",
+            "c.org_id",
+            "c.agent_id",
+            "c.kind",
+        ])
+            .where("r.id", "=", runId)
+            .executeTakeFirst();
+        if (!run)
+            return none;
+        const conversationId = run.conversation_id;
+        const inputs = new Map();
+        const events = [];
+        const calls = [];
+        for (const d of dispatches) {
+            const written = await t
+                .selectFrom("conversation_events")
+                .select("seq")
+                .where("conversation_id", "=", conversationId)
+                .where("idem_key", "=", idem.result(runId, d.parent_call_id))
+                .executeTakeFirst();
+            if (written)
+                continue;
+            if (!inputs.has(`step:${d.step}`)) {
+                inputs.set(`step:${d.step}`, true);
+                const msg = await t
+                    .selectFrom("conversation_events")
+                    .select("payload")
+                    .where("conversation_id", "=", conversationId)
+                    .where("idem_key", "=", assistantIdemKey(runId, d.step))
+                    .executeTakeFirst();
+                const content = msg?.payload?.content ?? [];
+                for (const b of content) {
+                    if (b.type === "tool_call" && b.id !== undefined)
+                        inputs.set(b.id, b.input);
+                }
+            }
+            const input = inputs.get(d.parent_call_id);
+            const row = {
+                parentRunId: d.parent_run_id,
+                parentCallId: d.parent_call_id,
+                parentConversationId: d.parent_conversation_id,
+                childConversationId: d.child_conversation_id,
+                childRunId: d.child_run_id,
+            };
+            const child = await t
+                .selectFrom("runs")
+                .select("status")
+                .where("id", "=", d.child_run_id)
+                .executeTakeFirst();
+            // a child that already ended keeps its own result (its log is committed)
+            const ended = child !== undefined && TERMINAL_STATUSES.has(child.status)
+                ? await childResult(this.deps.eventLog, row, {
+                    modelGiven: typeof input === "object" &&
+                        input !== null &&
+                        input.model !== undefined,
+                })
+                : null;
+            if (ended)
+                events.push(finishedEvent(row, ended.finished));
+            const r = ended
+                ? { content: ended.content, isError: ended.isError, durationMs: ended.finished.durationMs }
+                : {
+                    content: AGENT_STOPPED_WITH_RUN_TEXT,
+                    isError: true,
+                    durationMs: Math.max(0, Date.now() - new Date(d.created_at).getTime()),
+                };
+            events.push({
+                type: "tool_result",
+                runId,
+                idemKey: idem.result(runId, d.parent_call_id),
+                payload: {
+                    step: d.step,
+                    callId: d.parent_call_id,
+                    toolKey: AGENT_TOOL,
+                    content: r.content,
+                    isError: r.isError,
+                },
+            });
+            calls.push({ step: d.step, callId: d.parent_call_id, input, r });
+        }
+        if (calls.length === 0)
+            return none;
+        const written = await this.deps.eventLog.append(conversationId, events, t);
+        for (const c of calls) {
+            const approval = await t
+                .selectFrom("approvals")
+                .select(["id", "status", "decided_by", "scope"])
+                .where("run_id", "=", runId)
+                .where("call_id", "=", c.callId)
+                .orderBy("attempt", "desc")
+                .limit(1)
+                .executeTakeFirst();
+            await audit(t, {
+                actorAccountId: run.trigger_account_id,
+                orgId: run.org_id,
+                action: "tool.called",
+                target: conversationId,
+                detail: {
+                    toolKey: AGENT_TOOL,
+                    isError: c.r.isError,
+                    durationMs: c.r.durationMs,
+                    agentId: run.agent_id,
+                    agentVersion: run.agent_version,
+                    conversationId,
+                    runId,
+                    callId: c.callId,
+                    ...(approval?.status === "approved" && {
+                        approvalId: approval.id,
+                        approvedByAccountId: approval.decided_by,
+                        scope: approval.scope,
+                    }),
+                },
+            });
+        }
+        const fire = () => {
+            const hooks = this.deps.pluginHooks;
+            const scope = hookScope(hooks, {
+                conversationKind: run.kind,
+                orgId: run.org_id,
+                accountId: run.trigger_account_id,
+                agentId: run.agent_id,
+                agentVersion: run.agent_version,
+                conversationId,
+                runId,
+            });
+            if (!hooks || !scope || !hooks.has("tool.postExecute"))
+                return;
+            void (async () => {
+                const def = agent ??
+                    normalizeStoredDefinition((await this.deps.db
+                        .selectFrom("agent_versions")
+                        .select("definition")
+                        .where("agent_id", "=", run.agent_id)
+                        .where("version", "=", run.agent_version)
+                        .executeTakeFirstOrThrow()).definition);
+                const skillLoad = await skillLoadOfferedIn(this.deps.db, this.deps.eventLog, conversationId);
+                const resolved = await this.deps.registry.forAgent(run.org_id, {
+                    tools: def.tools ?? [],
+                    skillLoad,
+                    subagents: def.subagents,
+                });
+                const tool = resolved.tools.find((x) => x.key === AGENT_TOOL);
+                if (!tool)
+                    return;
+                // the run is over: nothing aborts these observe hooks but their own timeouts
+                const signal = new AbortController().signal;
+                for (const c of calls) {
+                    fireObserve(hooks, "tool.postExecute", {
+                        ...scope,
+                        step: c.step,
+                        callId: c.callId,
+                        toolKey: AGENT_TOOL,
+                        specHash: tool.specHash,
+                        input: c.input,
+                        isError: c.r.isError,
+                        content: c.r.content,
+                        durationMs: c.r.durationMs,
+                    }, signal, this.deps.log);
+                }
+            })().catch((err) => this.deps.log.warn("cannot fire tool.postExecute for stopped agent calls", { runId, err }));
+        };
+        return {
+            steps: [...new Set(calls.map((c) => c.step))],
+            callIds: new Set([...forks.callIds, ...calls.map((c) => c.callId)]),
+            toSeq: Math.max(forks.toSeq ?? 0, ...written.map((e) => e.seq)),
+            fire,
+        };
+    }
+    /**
+     * 处理一个尚无结果的调用。先看输入请求的轮次：最近一轮仍 pending → 继续等；否则本次是第
+     * `已有轮数 + 1` 次调用，已有轮次时带 `ctx.resume`（answered → 答案，expired / cancelled → null）。
+     * 本次调用「有开始无结果」→ 结果未知（spec 4.3）。返回需要等待的对象，或 undefined（已写结果）。
+     */
+    async processCall(ctx, call, resolve) {
+        const rounds = await this.deps.questions.forCall(ctx.runId, call.id);
+        const last = rounds.at(-1);
+        if (last?.status === "pending")
+            return inputWait(last);
+        const attempt = rounds.length + 1;
+        const started = await this.deps.eventLog.findByIdem(ctx.conversationId, idem.started(ctx.runId, call.id, attempt));
+        if (started?.type === "tool_call_started") {
+            // 确实开始执行过：照样审计 tool.called（耗时未知）；放行依据只认批准了所执行定义的审批记录
+            const key = started.payload.toolKey;
+            const approval = await this.deps.approvals.forCall(ctx.runId, call.id);
+            const approved = approval?.status === "approved" && approval.specHash === started.payload.specHash
+                ? approval
+                : null;
+            const source = approved ? null : (await resolve()).tools.find((t) => t.key === key)?.source;
+            await this.writeResult(ctx, call.id, key, { content: UNKNOWN_RESULT_TEXT, isError: true }, [], {
+                durationMs: null,
+                connectorId: approved
+                    ? approved.connectorId
+                    : source?.kind === "connector"
+                        ? source.connectorId
+                        : null,
+                ...(approved && { authorization: approvalAuthorization(approved) }),
+            });
+            return undefined;
+        }
+        if (ctx.signal.aborted) {
+            await this.writeResult(ctx, call.id, call.name, {
+                content: RUN_STOPPED_TEXT,
+                isError: true,
+            });
+            return undefined;
+        }
+        const resume = last
+            ? { state: last.state, answer: last.status === "answered" ? last.answer : null }
+            : undefined;
+        return this.runCall(ctx, call, await resolve(), attempt, resume);
+    }
+    async runCall(ctx, call, resolved, attempt, resume) {
+        const fail = async (content, key = call.name) => {
+            await this.writeResult(ctx, call.id, key, { content, isError: true });
+            return undefined;
+        };
+        const tool = resolved.tools.find((t) => t.key === call.name);
+        if (!tool) {
+            const why = resolved.unavailable.find((u) => u.ref === call.name) ??
+                resolved.hidden?.find((u) => u.ref === call.name);
+            if (why)
+                return fail(unavailableText(call.name, why.reason));
+            let keys = resolved.tools.map((t) => t.key);
+            // tool_search 模式：目录可能很大，只列内置工具与发出本次调用的请求里带了定义的工具
+            if (resolved.toolSearch === true) {
+                const sent = await this.sentTools(ctx);
+                if (sent !== null)
+                    keys = keys.filter((k) => isAlwaysLoaded(k) || sent.has(k));
+            }
+            keys.sort();
+            return fail(unknownToolText(call.name, keys, keys.includes("tool_search")));
+        }
+        // tool_search 模式下，模型只能调用请求里带了完整定义的工具：目录里有、但发出本次调用的请求没加载 →
+        // 明确错误，不自动加载（spec 5.5 / 6.3）。同一步里先 tool_search 再调用刚加载的工具同样报错。
+        if (resolved.toolSearch === true && !isAlwaysLoaded(tool.key)) {
+            const sent = await this.sentTools(ctx);
+            if (sent !== null && !sent.has(tool.key))
+                return fail(notLoadedText(tool.key), tool.key);
+        }
+        let input;
+        try {
+            input = await resolveOutputRefs(call.input, (id) => this.deps.outputs.load({ orgId: ctx.orgId, conversationId: ctx.conversationId }, id));
+        }
+        catch (e) {
+            if (e instanceof ToolError)
+                return fail(e.message, tool.key);
+            throw e;
+        }
+        // 连接器工具的 schema 来自连接器（不受信任）：去掉有风险的关键字并限制大小 / 层数
+        const invalid = validateInput(tool.key, tool.spec, input, {
+            untrusted: tool.source.kind === "connector",
+            log: this.deps.log,
+        });
+        if (invalid !== null)
+            return fail(invalid, tool.key);
+        const decision = await this.decide(tool, ctx.agent, {
+            orgId: ctx.orgId,
+            accountId: ctx.accountId,
+            agentId: ctx.agentId,
+            conversationId: ctx.conversationId,
+            runId: ctx.runId,
+            ...(ctx.parent !== undefined && {
+                parentConversationId: ctx.parent.conversationId,
+                ...(ctx.parent.otherAgent !== undefined && { parentAgentDiffers: ctx.parent.otherAgent }),
+            }),
+        });
+        if (decision === "deny")
+            return fail(deniedText(tool.key), tool.key);
+        if (typeof decision === "object" && "unavailable" in decision) {
+            return fail(unavailableText(tool.key, decision.unavailable), tool.key);
+        }
+        // 该调用已有审批（续跑）→ 按审批结果；没有且策略为 ask → 建审批并等待
+        // （不写 tool_call_started：此时尚未开始执行）。
+        let approval = await this.deps.approvals.forCall(ctx.runId, call.id);
+        // 批准的是旧定义（等待期间工具定义变了）：原批准不适用于当前定义，策略仍需审批时按新定义重新审批。
+        const stale = approval?.status === "approved" && approval.specHash !== tool.specHash;
+        if ((!approval || stale) && typeof decision === "object" && "ask" in decision) {
+            approval = await this.deps.approvals.request({
+                attempt: (approval?.attempt ?? 0) + 1,
+                orgId: ctx.orgId,
+                conversationId: ctx.conversationId,
+                runId: ctx.runId,
+                step: ctx.step,
+                callId: call.id,
+                toolKey: tool.key,
+                specHash: decision.ask.specHash,
+                connectorId: decision.ask.connectorId,
+                input: call.input,
+                requestedFor: decision.ask.requestedFor,
+                approverRole: decision.ask.approverRole,
+                policy: decision.ask.policy,
+            });
+        }
+        if (approval && approval.status !== "approved") {
+            const refused = this.refusalText(approval);
+            return refused === null ? approvalWait(approval) : fail(refused, tool.key);
+        }
+        // 走到这里即放行：在（与当前定义一致的）审批下执行，否则是授权或策略放行
+        const authorization = approval?.status === "approved" && approval.specHash === tool.specHash
+            ? approvalAuthorization(approval)
+            : typeof decision === "object" && "grant" in decision
+                ? { grant: decision.grant }
+                : { policy: "allow" };
+        // tool.preExecute after policy and approval, before tool_call_started (F10)
+        const hooks = this.deps.pluginHooks;
+        const scope = hookScope(hooks, ctx);
+        if (scope && hooks?.has("tool.preExecute")) {
+            // sticky: a denial already logged for this call (e.g. an older log, or a crash right after it)
+            // is final: fail with the recorded reason, never re-run the hooks or execute the tool. Only
+            // looked up when a tool.preExecute hook could run (M-2: no query without hooks); a denial is
+            // written with the call's tool_result, so a call with a logged denial never runs again anyway.
+            const prior = await this.deps.eventLog.findByIdem(ctx.conversationId, idem.hookDenied(ctx.runId, call.id));
+            if (prior?.type === "hook_denied") {
+                return fail(hookDeniedText(prior.payload.plugin, prior.payload.reason), tool.key);
+            }
+        }
+        // payload only built when a tool hook is registered (zero overhead otherwise)
+        const hookBase = scope && hooks && (hooks.has("tool.preExecute") || hooks.has("tool.postExecute"))
+            ? {
+                ...scope,
+                step: ctx.step,
+                callId: call.id,
+                toolKey: tool.key,
+                specHash: tool.specHash,
+                input,
+            }
+            : null;
+        if (hooks && hookBase && hooks.has("tool.preExecute")) {
+            let verdict;
+            try {
+                verdict = await hooks.run("tool.preExecute", hookBase, ctx.signal);
+            }
+            catch (e) {
+                // run() rejects only when the run's signal aborted: an abort, never a deny
+                if (ctx.signal.aborted)
+                    return fail(RUN_STOPPED_TEXT, tool.key);
+                throw e;
+            }
+            if (!verdict.allowed) {
+                // hook_denied, its audit entry and the tool_result in one transaction (no window where the
+                // denial is logged but the call has no result)
+                const site = {
+                    orgId: ctx.orgId,
+                    conversationId: ctx.conversationId,
+                    runId: ctx.runId,
+                    accountId: ctx.accountId,
+                    agentId: ctx.agentId,
+                    idemKey: idem.hookDenied(ctx.runId, call.id),
+                };
+                const event = hookDeniedEvent(site, "tool.preExecute", verdict, {
+                    step: ctx.step,
+                    callId: call.id,
+                });
+                await this.writeResult(ctx, call.id, tool.key, { content: hookDeniedText(verdict.plugin, verdict.reason), isError: true }, [event], undefined, [hookDeniedAudit(site, event.payload, verdict)]);
+                return undefined;
+            }
+        }
+        // `agent` (sub-agents spec §7.1): no tool_call_started; the dispatch is made durable in one
+        // transaction (its marker is the subagent_dispatches row) and the call stays open
+        const dispatcher = this.deps.subagents;
+        if (tool.source.kind === "builtin" && tool.key === AGENT_TOOL && dispatcher) {
+            const parsed = AgentToolInput.safeParse(input);
+            if (!parsed.success) {
+                return fail("Invalid agent call: pass description and prompt, and optionally subagent_type, model or resume.", tool.key);
+            }
+            const r = await dispatcher.dispatch({ ctx, callId: call.id, input: parsed.data });
+            return r.kind === "refused" ? fail(r.content, tool.key) : OPEN;
+        }
+        await this.deps.eventLog.append(ctx.conversationId, [
+            {
+                type: "tool_call_started",
+                runId: ctx.runId,
+                idemKey: idem.started(ctx.runId, call.id, attempt),
+                payload: { step: ctx.step, callId: call.id, toolKey: tool.key, specHash: tool.specHash },
+            },
+        ]);
+        const t0 = Date.now();
+        let outcome = await this.execute(tool, input, ctx, call.id, resume, resolved.tools);
+        const durationMs = Date.now() - t0;
+        await this.deps.hooks?.afterExecute?.(ctx.runId, call.id);
+        if (outcome.kind === "input_required") {
+            const asked = await this.askInput(ctx, call.id, tool.key, attempt, outcome);
+            if (typeof asked !== "string")
+                return asked;
+            outcome = { kind: "error", message: asked };
+        }
+        const rendered = outcome.kind === "result"
+            ? renderResult(outcome.result)
+            : { text: outcome.message, contentTypes: [], isError: true };
+        // 内置工具（tool_search）报告的已加载工具：只认本步可用、非内置的 key，写进 tool_result（日志即事实源）
+        const loadedTools = outcome.kind === "result" && tool.source.kind === "builtin"
+            ? loadedFrom(outcome.result, resolved.tools)
+            : [];
+        // 显示摘要：只认插件 / 内置工具与内核的 resources 工具给的（连接器结果来自外部服务，不采信），
+        // 校验不过就丢弃并告警
+        const display = outcome.kind === "result" && (tool.source.kind !== "connector" || tool.source.resources)
+            ? this.displayOf(outcome.result, tool.key)
+            : undefined;
+        // structured view: builtins only (extension and connector results never carry one)
+        const view = outcome.kind === "result" && tool.source.kind === "builtin"
+            ? this.viewOf(outcome.result, tool.key)
+            : undefined;
+        // inline card: plugin tools only, naming an inline view of the same extension
+        const card = outcome.kind === "result" && tool.source.kind === "plugin"
+            ? this.cardOf(outcome.result, tool.source.plugin, tool.key)
+            : undefined;
+        const cfg = this.deps.config().tools;
+        const spilled = await spillIfLarge(rendered.text, {
+            // 内置工具可给更低的转存阈值（沙箱 bash 30000 字符）
+            spillChars: Math.min(cfg.outputSpillChars, tool.spillChars ?? Number.POSITIVE_INFINITY),
+            previewChars: cfg.outputPreviewChars,
+        }, (content) => this.deps.outputs.save({
+            orgId: ctx.orgId,
+            conversationId: ctx.conversationId,
+            callId: call.id,
+            content,
+        }));
+        const pre = outcome.kind === "connection_required"
+            ? [
+                {
+                    type: "connection_required",
+                    runId: ctx.runId,
+                    idemKey: idem.connection(ctx.runId, call.id),
+                    payload: {
+                        step: ctx.step,
+                        callId: call.id,
+                        // 事件 payload 字段名改名后不变（C27：日志确定性）
+                        appId: outcome.connectorId,
+                        appName: outcome.connectorName,
+                    },
+                },
+            ]
+            : [];
+        await this.writeResult(ctx, call.id, tool.key, {
+            content: spilled.content,
+            isError: rendered.isError,
+            ...(spilled.outputId !== undefined && { outputId: spilled.outputId }),
+            ...(rendered.contentTypes.length > 0 && { contentTypes: rendered.contentTypes }),
+            ...(loadedTools.length > 0 && { loadedTools }),
+            ...(display !== undefined && { display }),
+            ...(view !== undefined && { view }),
+            ...(card !== undefined && { card }),
+        }, pre, {
+            durationMs,
+            connectorId: tool.source.kind === "connector" ? tool.source.connectorId : null,
+            authorization,
+        });
+        // a sub-agent that needs a personal connection: mirrored in the parent for display (spec §9;
+        // not a wait, the child got the connect text as its result)
+        if (outcome.kind === "connection_required" && ctx.parent !== undefined) {
+            await this.deps.eventLog
+                .append(ctx.parent.conversationId, [
+                {
+                    type: "subagent_waiting",
+                    runId: ctx.parent.runId,
+                    idemKey: subagentWaitingIdemKey(ctx.runId, `connect-${call.id}`),
+                    payload: {
+                        subagentId: ctx.conversationId,
+                        childRunId: ctx.runId,
+                        kind: "connect",
+                        toolKey: tool.key,
+                    },
+                },
+            ])
+                .catch((err) => this.deps.log.warn("cannot surface a sub-agent's connect card in its parent", {
+                runId: ctx.runId,
+                err,
+            }));
+        }
+        if (hooks && hookBase) {
+            fireObserve(hooks, "tool.postExecute", { ...hookBase, isError: rendered.isError, content: spilled.content, durationMs }, ctx.signal, this.deps.log);
+        }
+        return undefined;
+    }
+    /**
+     * 发出本步调用的请求里带了完整定义的工具 key：本步最后一次尝试的 `model_call.request.tools`
+     * （`assistant_message` 来自最后一次尝试）。该请求不在 tool_search 模式（没有 `catalog`，工具全部发送）
+     * 或找不到 model_call 时返回 null（不做加载检查）。已加载集合由此从日志得出，不放进程内存。
+     */
+    async sentTools(ctx) {
+        for (let attempt = MAX_MODEL_ATTEMPTS; attempt >= 1; attempt--) {
+            const e = await this.deps.eventLog.findByIdem(ctx.conversationId, modelCallIdemKey(ctx.runId, ctx.step, attempt));
+            if (e?.type !== "model_call")
+                continue;
+            const { tools, catalog } = e.payload.request;
+            return catalog === undefined ? null : new Set((tools ?? []).map((t) => t.key));
+        }
+        return null;
+    }
+    /** 审批的非批准结果 → 给模型的说明；仍 pending → null（继续等待）。 */
+    refusalText(a) {
+        switch (a.status) {
+            case "denied":
+                return approvalDeniedText(a.denyReason);
+            case "expired":
+                // 按该审批实际的等待时长（创建到到期），不读当前配置（配置可热更新）
+                return approvalExpiredText(approvalHours(a));
+            case "cancelled":
+                return APPROVAL_CANCELLED_TEXT;
+            default:
+                return null;
+        }
+    }
+    /**
+     * 处理函数返回 `input_required`：超过轮次上限、表单不合规（`validateInputForm`）或 state 过大 → 返回给模型的错误说明；
+     * 否则建输入请求（写 `question_asked`）并返回等待对象。
+     */
+    async askInput(ctx, callId, toolKey, attempt, req) {
+        if (attempt > MAX_INPUT_ROUNDS)
+            return TOO_MANY_INPUT_REQUESTS_TEXT;
+        const problems = validateInputForm(req.form);
+        if (problems.length > 0)
+            return invalidFormText(toolKey, problems);
+        let stateJson;
+        try {
+            stateJson = JSON.stringify(req.state ?? null);
+        }
+        catch {
+            stateJson = undefined;
+        }
+        if (stateJson === undefined)
+            return `Tool ${toolKey} returned input state that is not JSON.`;
+        if (Buffer.byteLength(stateJson, "utf8") > MAX_INPUT_STATE_BYTES) {
+            return stateTooLargeText(toolKey);
+        }
+        const q = await this.deps.questions.ask({
+            orgId: ctx.orgId,
+            conversationId: ctx.conversationId,
+            runId: ctx.runId,
+            step: ctx.step,
+            callId,
+            attempt,
+            toolKey,
+            form: req.form,
+            state: JSON.parse(stateJson),
+        });
+        return inputWait(q);
+    }
+    /**
+     * 管线第 4 阶段：执行。内置 / 插件工具直接调用处理函数，连接器工具经连接器（每次调用打开并关闭会话）。
+     * 带 `tools.timeoutMs` 超时与 run 的中止信号（合并后传给处理函数 / 连接器，不响应信号的也按时结束）。
+     * 熔断只作用于连接器工具（键为组织 × 连接器）。
+     */
+    async execute(tool, input, ctx, callId, resume, stepTools) {
+        if (tool.source.kind === "connector") {
+            return this.executeConnector(tool, tool.source, input, ctx, resume);
+        }
+        const handler = this.deps.registry.handler(tool.source);
+        if (!handler)
+            return { kind: "error", message: `Tool ${tool.key} is no longer available.` };
+        // 插件处理函数只拿到 SDK 的 ToolCallContext；内置工具另外拿到本步解析出的工具（tool_search 用）
+        const base = {
+            orgId: ctx.orgId,
+            accountId: ctx.accountId,
+            agentId: ctx.agentId,
+            conversationId: ctx.conversationId,
+            callId,
+            ...(resume !== undefined && { resume }),
+            ...(tool.source.kind === "builtin" && stepTools !== undefined && { tools: stepTools }),
+            ...(tool.source.kind === "builtin" && { runId: ctx.runId }),
+            ...(tool.source.kind === "builtin" &&
+                ctx.deadline !== undefined && { runDeadline: ctx.deadline }),
+            // a sub-agent works in its parent conversation's sandbox (spec §10.1)
+            ...(tool.source.kind === "builtin" &&
+                ctx.parent !== undefined && { sandboxConversationId: ctx.parent.conversationId }),
+        };
+        // 内置工具可按输入给自己的时限（沙箱 bash 按命令超时加余量）；缺省 tools.timeoutMs
+        const timeoutMs = tool.timeoutMs?.(input) ?? this.deps.config().tools.timeoutMs;
+        try {
+            const r = await this.bounded(ctx.signal, (signal) => handler(input, { ...base, signal }), undefined, timeoutMs);
+            if (r === "timeout") {
+                return { kind: "error", message: timeoutText(tool.key, timeoutMs) };
+            }
+            if (r === "aborted")
+                return { kind: "error", message: RUN_STOPPED_DURING_TEXT };
+            if (isInputRequired(r.value)) {
+                return { kind: "input_required", form: r.value.form, state: r.value.state ?? null };
+            }
+            return { kind: "result", result: r.value };
+        }
+        catch (e) {
+            return this.thrown(tool.key, e);
+        }
+    }
+    async executeConnector(tool, source, input, ctx, resume) {
+        const { db, registry, breaker, credentials, config } = this.deps;
+        const { orgId } = ctx;
+        const connectorId = source.connectorId;
+        const app = await db
+            .selectFrom("connectors")
+            .select(["name", "connector", "endpoint", "auth", "status"])
+            .where("id", "=", connectorId)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (app?.status !== "active") {
+            return { kind: "error", message: `The app providing ${tool.key} is no longer available.` };
+        }
+        const connector = registry.findConnector(app.connector);
+        if (!connector) {
+            return {
+                kind: "error",
+                message: `The connector for ${tool.key} is not installed; ask an administrator.`,
+            };
+        }
+        const state = await breaker.check(orgId, connectorId);
+        if (state.open) {
+            return {
+                kind: "error",
+                message: breakerOpenMessage(app.name, state.failures, state.retryAfterSeconds),
+            };
+        }
+        const auth = app.auth;
+        let injection;
+        /** 本次调用实际注入过的凭据（含 401 后重新读取的），结果打码用。 */
+        const injected = [];
+        const getAuth = () => {
+            injection ??= credentials.injection(orgId, connectorId, auth, ctx.accountId).then((inj) => {
+                injected.push(inj);
+                return inj;
+            });
+            return injection;
+        };
+        // 远端在调用途中向用户要输入（MCP elicitation，见 elicitation.ts）：需要问用户时中止本次调用、按 input_required
+        // 处理；续跑时用 ctx.resume 的答案答复远端再次发起的同一请求。resources 工具不续跑，一律拒绝。
+        const suspend = new AbortController();
+        const elicit = new ElicitationSession({
+            resume,
+            onSuspend: () => suspend.abort(),
+            declineAll: source.resources === true,
+        });
+        // 远端可能把收到的凭据回显在结果 / 错误 / elicitation 表单里：写入事件之前按本次注入的值打码（见 redact.ts）
+        const clean = (o) => {
+            const redact = redactorFor(injected);
+            if (o.kind === "result") {
+                return { kind: "result", result: redactDeep(withNotes(o.result, elicit.notes), redact) };
+            }
+            if (o.kind === "error") {
+                return { kind: "error", message: redact([o.message, ...elicit.notes].join(" ")) };
+            }
+            if (o.kind === "input_required") {
+                return {
+                    kind: "input_required",
+                    form: redactDeep(o.form, redact),
+                    state: redactDeep(o.state, redact),
+                };
+            }
+            return o;
+        };
+        /** 本次执行要问用户（elicitation）：服务可达，算成功；返回打码后的输入请求。 */
+        const asked = async () => {
+            if (!elicit.pending)
+                return undefined;
+            await breaker.success(orgId, connectorId);
+            return clean({
+                kind: "input_required",
+                form: elicit.pending.form,
+                state: elicit.pending.state,
+            });
+        };
+        const missing = (e) => e.ownership === "personal"
+            ? {
+                kind: "connection_required",
+                connectorId,
+                connectorName: app.name,
+                message: personalMissingText(app.name),
+            }
+            : { kind: "error", message: orgMissingText(app.name) };
+        // 先取一次凭据：缺凭据在打开会话之前就确定，不依赖连接器把 CredentialMissing 原样抛出。
+        try {
+            await getAuth();
+        }
+        catch (e) {
+            if (e instanceof CredentialMissing)
+                return missing(e);
+            // 取 token 时授权服务器暂时不可用（OAuth）：给模型可执行的说明，不让整轮失败
+            if (e instanceof ToolError)
+                return { kind: "error", message: e.message };
+            throw e;
+        }
+        let opened;
+        try {
+            // suspend 也参与竞速：为问用户中止时立即结束，不等连接器自己收尾
+            const r = await this.bounded(ctx.signal, async (signal) => {
+                opened = connector.open({
+                    endpoint: app.endpoint,
+                    auth: getAuth,
+                    // OAuth：在刷新锁内强制刷新（别的副本已刷新则直接用新 token）；之后丢弃本次调用缓存的注入，
+                    // 连接器重试时重新读取。refresh 被拒 → CredentialMissing，经连接器原样抛出，下面转成「需要连接」。
+                    onUnauthorized: async () => {
+                        const stale = injected.at(-1);
+                        injection = undefined;
+                        await credentials.onUnauthorized(orgId, connectorId, auth, ctx.accountId, stale);
+                    },
+                    signal,
+                    onElicit: elicit.handle,
+                    onToolsChanged: () => {
+                        try {
+                            this.deps.onToolsChanged?.(orgId, connectorId);
+                        }
+                        catch (err) {
+                            this.deps.log.warn("tools changed notification failed", {
+                                orgId,
+                                connectorId,
+                                err,
+                            });
+                        }
+                    },
+                });
+                const session = await opened;
+                return source.resources
+                    ? runResourceTool(session, source.name, input)
+                    : // 交回已复核的定义（connector_tools.spec，含 connectorData）：连接器按它路由，远端变化须先经漂移复核
+                        session.callTool(source.name, input, AbortSignal.any([signal, suspend.signal]), {
+                            spec: tool.spec,
+                        });
+            }, suspend.signal);
+            if (r === "aborted")
+                return { kind: "error", message: RUN_STOPPED_DURING_TEXT };
+            const ask = await asked();
+            if (ask)
+                return ask;
+            if (r === "timeout") {
+                await breaker.failure(orgId, connectorId);
+                return { kind: "error", message: timeoutText(tool.key, config().tools.timeoutMs) };
+            }
+            // 工具自己报告的错误（isError）说明服务可用，也算成功。
+            await breaker.success(orgId, connectorId);
+            return clean({ kind: "result", result: r.value });
+        }
+        catch (e) {
+            // 为问用户而中止了调用：中止引起的错误不是失败
+            const ask = await asked();
+            if (ask)
+                return ask;
+            if (e instanceof CredentialMissing)
+                return missing(e);
+            // 熔断只计远端不可用（连接 / 传输错误、HTTP 5xx：连接器抛 kind = unavailable 的 ToolError 或原始错误）。
+            // 其余 ToolError（JSON-RPC 业务错误、鉴权失败、重定向等）说明服务可达，与 isError 结果一样算成功。
+            if (e instanceof ToolError && e.kind !== "unavailable")
+                await breaker.success(orgId, connectorId);
+            else
+                await breaker.failure(orgId, connectorId);
+            return clean(this.thrown(tool.key, e));
+        }
+        finally {
+            if (opened)
+                await this.closeSession(opened, tool.key);
+        }
+    }
+    /** 抛出的错误 → 给模型的结果：ToolError 的消息原样（插件约定为英文、可操作），其他只给错误类名。 */
+    thrown(key, e) {
+        if (e instanceof ToolError)
+            return { kind: "error", message: e.message };
+        // 提供工具的插件实例在调用进行中被撤销（停用 / 升级），排空时限到后中止（C17）
+        if (e instanceof ExtensionUnloadedError) {
+            this.deps.log.warn("tool call aborted: plugin unloaded", { toolKey: key, plugin: e.plugin });
+            return { kind: "error", message: PLUGIN_UNLOADED_TOOL_ERROR };
+        }
+        // 不记参数与结果；错误经日志打码
+        this.deps.log.warn("tool call failed", { toolKey: key, err: e });
+        return { kind: "error", message: failedText(key, errName(e)) };
+    }
+    /**
+     * 带超时与中止执行 work：合并 run 信号与超时信号传给 work，并与之竞速（work 不响应信号也按时返回）。
+     * 返回 `{ value }`，或 `"timeout"` / `"aborted"`；work 自己的错误照常抛出。
+     */
+    async bounded(runSignal, work, 
+    /** 额外参与竞速的信号（不传给 work）：中止时以 `Stopped` 抛出，由调用方判断原因。 */
+    interrupt, 
+    /** 时限（毫秒），缺省 `tools.timeoutMs`。 */
+    timeoutMs = this.deps.config().tools.timeoutMs) {
+        if (runSignal.aborted)
+            return "aborted";
+        const timeout = new AbortController();
+        // 本进程发起的调用自己的计时器，结束即清除
+        const timer = setTimeout(() => timeout.abort(), timeoutMs);
+        const signal = AbortSignal.any([runSignal, timeout.signal]);
+        let onAbort = () => { };
+        const race = interrupt ? AbortSignal.any([signal, interrupt]) : signal;
+        const stopped = new Promise((_, reject) => {
+            onAbort = () => reject(new Stopped());
+            race.addEventListener("abort", onAbort, { once: true });
+        });
+        stopped.catch(() => { });
+        try {
+            const p = (async () => work(signal))();
+            p.catch(() => { });
+            return { value: await Promise.race([p, stopped]) };
+        }
+        catch (e) {
+            if (signal.aborted)
+                return runSignal.aborted ? "aborted" : "timeout";
+            throw e;
+        }
+        finally {
+            clearTimeout(timer);
+            race.removeEventListener("abort", onAbort);
+        }
+    }
+    /** 关闭会话（打开仍在进行时等它完成后关闭），最多等 {@link CLOSE_WAIT_MS}；失败只记日志。 */
+    async closeSession(opened, key) {
+        const closing = opened
+            .then((s) => s.close())
+            .catch((err) => this.deps.log.warn("connector session close failed", { toolKey: key, err }));
+        let timer;
+        await Promise.race([
+            closing,
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, CLOSE_WAIT_MS);
+                timer.unref();
+            }),
+        ]);
+        clearTimeout(timer);
+    }
+    /**
+     * 工具结果里的显示摘要（`ToolResult.display`）：合法时只取 `{ summary: { zh, en } }`，没有给返回 undefined，
+     * 不合法时记告警并丢弃（结果照常写入）。摘要只进事件日志给界面看，不进模型请求。
+     */
+    displayOf(result, toolKey) {
+        const d = result?.display;
+        if (d === undefined)
+            return undefined;
+        const problems = validateToolDisplay(d);
+        if (problems.length > 0) {
+            this.deps.log.warn("tool returned an invalid display summary; dropped", {
+                toolKey,
+                problems,
+            });
+            return undefined;
+        }
+        const { zh, en } = d.summary;
+        return { summary: { zh, en } };
+    }
+    /**
+     * A plugin tool's inline card (`ToolResult.card` → `tool_result.card`, display only): `view` must
+     * be an `inline` ui contribution of the same extension and `key` at most 200 characters; anything
+     * else is dropped with a warning and the result is written as usual.
+     */
+    cardOf(result, plugin, toolKey) {
+        const c = result?.card;
+        if (c === undefined)
+            return undefined;
+        const x = (typeof c === "object" && c !== null ? c : {});
+        const views = this.deps.inlineViews?.(plugin);
+        const keyOk = x.key === undefined || (typeof x.key === "string" && x.key !== "" && x.key.length <= 200);
+        if (typeof x.view !== "string" || !views?.has(x.view) || !keyOk) {
+            this.deps.log.warn("tool returned an inline card that is not an inline view of its extension; dropped", {
+                toolKey,
+                view: typeof x.view === "string" ? x.view.slice(0, 100) : undefined,
+            });
+            return undefined;
+        }
+        return { plugin, view: x.view, ...(x.key !== undefined && { key: x.key }) };
+    }
+    /**
+     * A builtin's structured view (`tool_result.view`, display only): checked against
+     * {@link ToolViewSchema}; an invalid one is dropped with a warning and the result is written as usual.
+     */
+    viewOf(result, toolKey) {
+        const v = result?.view;
+        if (v === undefined)
+            return undefined;
+        const parsed = ToolViewSchema.safeParse(v);
+        if (!parsed.success) {
+            this.deps.log.warn("builtin tool returned an invalid view; dropped", { toolKey });
+            return undefined;
+        }
+        return parsed.data;
+    }
+    /**
+     * 管线第 6 阶段：写 `tool_result`（与 `connection_required` 同批）。传入 `callAudit`（即工具实际执行过；
+     * 耗时 null = 执行过但耗时未知，如续跑时「有开始无结果」的调用）时在同一事务里写审计 `tool.called`。
+     * 审计链（R6）：actor = 发起人 → agent（id + 版本）→ 会话 / 运行 / 调用 / 工具（连接器工具带 connectorId）→
+     * 放行依据（审批人 / 授权 / 策略）。不含参数、结果与凭据。
+     */
+    async writeResult(ctx, callId, toolKey, r, pre = [], callAudit, 
+    /** Extra audit entries written in the same transaction (e.g. `hook.denied`). */
+    audits = []) {
+        const events = [
+            ...pre,
+            {
+                type: "tool_result",
+                runId: ctx.runId,
+                idemKey: idem.result(ctx.runId, callId),
+                payload: { step: ctx.step, callId, toolKey, ...r },
+            },
+        ];
+        if (callAudit === undefined && audits.length === 0) {
+            await this.deps.eventLog.append(ctx.conversationId, events);
+            return;
+        }
+        const written = await this.deps.db.transaction().execute(async (t) => {
+            const out = await this.deps.eventLog.append(ctx.conversationId, events, t);
+            for (const a of audits)
+                await audit(t, a);
+            if (callAudit === undefined)
+                return out;
+            await audit(t, {
+                actorAccountId: ctx.accountId,
+                orgId: ctx.orgId,
+                action: "tool.called",
+                target: ctx.conversationId,
+                detail: {
+                    toolKey,
+                    isError: r.isError,
+                    durationMs: callAudit.durationMs,
+                    agentId: ctx.agentId,
+                    agentVersion: ctx.agentVersion,
+                    conversationId: ctx.conversationId,
+                    runId: ctx.runId,
+                    callId,
+                    ...(callAudit.connectorId !== null && { connectorId: callAudit.connectorId }),
+                    ...callAudit.authorization,
+                },
+            });
+            return out;
+        });
+        await this.deps.eventLog.notify(ctx.conversationId, Math.max(...written.map((e) => e.seq)));
+    }
+}