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

package/dist/tools/outputs.js

@@ -0,0 +1,156 @@
+import { randomUUID } from "node:crypto";
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { sql } from "kysely";
+/** 文本行数（按 `\n` 切分；空串算 1 行，与按行分页读取一致）。 */
+export function countLines(s) {
+    let n = 1;
+    for (let i = s.indexOf("\n"); i !== -1; i = s.indexOf("\n", i + 1))
+        n++;
+    return n;
+}
+/**
+ * 输出存档（spec 5.4）：超大工具结果的全文存进 `capybara.tool_outputs`，保留 `tools.outputRetentionDays` 天。
+ * 只能在产生它的会话里读取（同组织别的会话也不行：会话之间可见范围不同），过期即视为不存在（清理由维护任务负责）。
+ */
+export class ToolOutputs {
+    db;
+    config;
+    constructor(db, config) {
+        this.db = db;
+        this.config = config;
+    }
+    async save(a) {
+        const id = randomUUID();
+        const sizeChars = a.content.length;
+        const lineCount = countLines(a.content);
+        const days = this.config().tools.outputRetentionDays;
+        await this.db
+            .insertInto("tool_outputs")
+            .values({
+            id,
+            org_id: a.orgId,
+            conversation_id: a.conversationId,
+            call_id: a.callId,
+            size_chars: sizeChars,
+            line_count: lineCount,
+            content: a.content,
+            expires_at: sql `now() + make_interval(days => ${days})`,
+        })
+            .execute();
+        return { id, sizeChars, lineCount };
+    }
+    /** 读本会话未过期的存档全文；不存在 / 过期 / 属于别的会话或组织 → null。 */
+    async load(scope, id) {
+        const row = await this.db
+            .selectFrom("tool_outputs")
+            .select("content")
+            .where("id", "=", id)
+            .where("org_id", "=", scope.orgId)
+            .where("conversation_id", "=", scope.conversationId)
+            .where("expires_at", ">", sql `now()`)
+            .executeTakeFirst();
+        return row?.content ?? null;
+    }
+}
+/** 存档不存在 / 过期 / 不属于本会话（模型可见，英文；不区分几种情况，不泄露别处的存档是否存在）。 */
+export const outputNotFoundText = (id) => `Output ${id} not found or expired. Run the tool that produced it again to get a new output id.`;
+const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+ * 管线第 1 阶段：把参数中任意位置的 `{"$output": "<id>"}`（对象恰好只有这一个键）替换为该存档全文。
+ * 不存在 / 过期 / 不属于本会话 → `ToolError`（给模型看的英文）。不修改传入的对象。
+ */
+export async function resolveOutputRefs(input, load) {
+    const cache = new Map();
+    const walk = async (v) => {
+        if (Array.isArray(v)) {
+            const out = [];
+            for (const x of v)
+                out.push(await walk(x));
+            return out;
+        }
+        if (!isPlainObject(v))
+            return v;
+        const keys = Object.keys(v);
+        if (keys.length === 1 && keys[0] === "$output") {
+            const id = v.$output;
+            if (typeof id !== "string") {
+                throw new ToolError('Invalid {"$output": ...} reference: the output id must be a string.');
+            }
+            let text = cache.get(id);
+            if (text === undefined) {
+                const loaded = await load(id);
+                if (loaded === null)
+                    throw new ToolError(outputNotFoundText(id));
+                text = loaded;
+                cache.set(id, text);
+            }
+            return text;
+        }
+        const out = {};
+        for (const k of keys)
+            out[k] = await walk(v[k]);
+        return out;
+    };
+    return walk(input);
+}
+/** base64 数据解码后的字节数。 */
+function base64Bytes(data) {
+    const s = data.replace(/\s/g, "");
+    const pad = s.endsWith("==") ? 2 : s.endsWith("=") ? 1 : 0;
+    return Math.max(0, Math.floor((s.length * 3) / 4) - pad);
+}
+/** 空结果的文本（模型可见，英文；部分供应商不接受空的 tool_result）。 */
+const NO_OUTPUT = "(no output)";
+/**
+ * 管线第 5 阶段（渲染）：文本块按行拼接；图片 → `[image <mimeType>, <n> bytes]`（M3 不把图片回传模型）；
+ * `resource_link` → `[resource <uri>]`；未知块 → `[unsupported content <type>]`。
+ * 畸形结果（不是对象、content 不是数组）给出说明并标为错误，不抛错（Review Focus 5）。
+ */
+export function renderResult(result) {
+    if (!isPlainObject(result) || !Array.isArray(result.content)) {
+        return {
+            text: "The tool returned a malformed result (expected an object with a content array).",
+            contentTypes: [],
+            isError: true,
+        };
+    }
+    const parts = [];
+    const types = [];
+    for (const block of result.content) {
+        const b = isPlainObject(block) ? block : {};
+        const type = typeof b.type === "string" ? b.type : "unknown";
+        if (!types.includes(type))
+            types.push(type);
+        if (type === "text" && typeof b.text === "string")
+            parts.push(b.text);
+        else if (type === "image" && typeof b.data === "string") {
+            const mime = typeof b.mimeType === "string" ? b.mimeType : "unknown";
+            parts.push(`[image ${mime}, ${base64Bytes(b.data)} bytes]`);
+        }
+        else if (type === "resource_link" && typeof b.uri === "string") {
+            parts.push(`[resource ${b.uri}]`);
+        }
+        else
+            parts.push(`[unsupported content ${type}]`);
+    }
+    return {
+        text: parts.length === 0 ? NO_OUTPUT : parts.join("\n"),
+        contentTypes: types,
+        isError: result.isError === true,
+    };
+}
+/**
+ * 管线第 5 阶段（转存）：超过 `spillChars` 的文本存为输出存档，模型只见前 `previewChars` 个字符与截断说明。
+ */
+export async function spillIfLarge(text, opts, save) {
+    if (text.length <= opts.spillChars)
+        return { content: text };
+    const saved = await save(text);
+    const id = saved.id;
+    return {
+        content: `${text.slice(0, opts.previewChars)}\n…\n` +
+            `[Output truncated: ${saved.sizeChars} chars, ${saved.lineCount} lines. Full output id: ${id}. ` +
+            `Use read_tool_output to page through it, or pass {"$output":"${id}"} as a tool argument.]`,
+        outputId: id,
+    };
+}

package/dist/tools/pipeline.d.ts

@@ -0,0 +1,322 @@
+import { type FormAnswer, type InputForm, type Logger } from "@capybara-hq/plugin-sdk";
+import type { Transaction } from "kysely";
+import { type AgentDefinition } from "../agents/definition.js";
+import type { KernelConfig } from "../config/schema.js";
+import type { EventLog } from "../conversations/event-log.js";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import type { OrgRole } from "../orgs/roles.js";
+import { type ConversationKindForHooks, type HookRunner } from "../runtime/hook-calls.js";
+import { type SubagentParent, type WaitingFor } from "../runtime/loop.js";
+import type { DispatchOutcome } from "../runtime/subagents/dispatch.js";
+import type { ApprovalsService } from "./approvals.service.js";
+import { type Breaker } from "./breaker.js";
+import { type AgentToolInputT } from "./builtins/agent.js";
+import { type Credentials } from "./credentials.js";
+import { type ToolOutputs } from "./outputs.js";
+import type { QuestionsService } from "./questions.service.js";
+import type { ResolvedTool, ToolRegistry } from "./registry.js";
+/** 审批被拒绝。 */
+export declare 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 declare const approvalDeniedText: (reason: string | null) => string;
+/** 审批超时（按拒绝）。 */
+export declare const approvalExpiredText: (hours: number) => string;
+/** 等待审批期间 run 被中止。 */
+export declare const APPROVAL_CANCELLED_TEXT = "The run was stopped while waiting for approval.";
+/** 等待用户输入期间 run 被中止。 */
+export declare const INPUT_CANCELLED_TEXT = "The run was stopped while waiting for user input.";
+/** 同一调用连续请求输入超过上限。 */
+export declare const TOO_MANY_INPUT_REQUESTS_TEXT = "Tool requested user input too many times.";
+/** run 已被中止 / 到达截止时间，调用尚未开始执行。 */
+export declare const RUN_STOPPED_TEXT = "The run was stopped before this tool call was executed.";
+/** 调用执行中 run 被中止 / 到达截止时间。 */
+export declare const RUN_STOPPED_DURING_TEXT = "The run was stopped while this tool call was running; its outcome is unknown. Verify before retrying.";
+/**
+ * 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 declare const hookDeniedText: (plugin: string, reason: string) => string;
+/** 需要人审批的请求（`ApprovalsService.request` 据此建审批记录）。 */
+export interface AskRequest {
+    toolKey: string;
+    /** 所批准的工具定义指纹（「本会话 / 以后都允许」授权按它匹配）。 */
+    specHash: string;
+    /** 连接器工具的来源连接器；插件 / 内置工具为 null。 */
+    connectorId: string | null;
+    /** 指定处理人（发起人本人）；按角色升级时为 null。 */
+    requestedFor: string | null;
+    /** 按角色升级（R1）时所需的角色；否则为 null。 */
+    approverRole: OrgRole | null;
+    /** Which rule asked (display only, written to `approval_requested.policy`). */
+    policy: ApprovalPolicySource;
+}
+/**
+ * Which rule made a call need approval: role escalation, the agent's tool policy, the connector's
+ * policy, a fixed ask (R3, `requiresUserInteraction`), the org's `sandboxToolPolicy`, or the tool's
+ * own default. `org` and `fixed` were added after the first B events (older logs say `default`).
+ */
+export type ApprovalPolicySource = "agent" | "connector" | "default" | "role" | "org" | "fixed";
+/**
+ * `unavailable`：调用那一刻工具已不可用（连接器 / 工具不存在、停用、删除、待审核），值为事实原因；
+ * 管线写「工具不可用」说明，而不是「策略拒绝」。
+ */
+export type PolicyDecision = "allow" | "deny" | {
+    ask: AskRequest;
+} | {
+    unavailable: string;
+}
+/** 记住的授权把 `ask` 放行（按 allow 执行，审计记授权种类）。 */
+ | {
+    grant: "session" | "always";
+};
+export interface PolicyContext {
+    orgId: string;
+    /** 对话发起人。 */
+    accountId: string;
+    agentId: string;
+    conversationId: string;
+    runId: string;
+    /**
+     * A sub-agent's call: its parent conversation, where "approve for this conversation" grants are
+     * looked up (sub-agents spec §9).
+     */
+    parentConversationId?: string;
+    /**
+     * False when the sub-agent runs its parent conversation's agent (a template or general-purpose
+     * child): the parent agent's policies were already read as its own, so no second read. Unset:
+     * read and compare.
+     */
+    parentAgentDiffers?: boolean;
+}
+/** 管线第 3 阶段：策略判定。 */
+export type DecidePolicy = (tool: ResolvedTool, agentDef: AgentDefinition, ctx: PolicyContext) => Promise<PolicyDecision>;
+/** 测试钩子。 */
+export interface ToolPipelineHooks {
+    /** 工具执行返回之后、结果写入日志之前调用：抛错即模拟「工具已执行、结果未记录」时进程崩溃。 */
+    afterExecute?(runId: string, callId: string): Promise<void>;
+}
+export interface ToolPipelineDeps {
+    db: KernelDb;
+    eventLog: EventLog;
+    registry: Pick<ToolRegistry, "forAgent" | "findConnector" | "handler">;
+    credentials: Pick<Credentials, "injection" | "onUnauthorized">;
+    breaker: Pick<Breaker, "check" | "failure" | "success">;
+    outputs: Pick<ToolOutputs, "save" | "load">;
+    /** 策略为 `ask` 时建审批；续跑时读该调用的审批结果。 */
+    approvals: Pick<ApprovalsService, "request" | "forCall">;
+    /** 处理函数返回 `input_required` 时建输入请求；续跑时读该调用的各轮输入请求。 */
+    questions: Pick<QuestionsService, "ask" | "forCall">;
+    config: () => KernelConfig;
+    log: Logger;
+    /** 默认 {@link createDecidePolicy}（执行时实时读取策略与授权）。 */
+    decidePolicy?: DecidePolicy;
+    hooks?: ToolPipelineHooks;
+    /**
+     * Plugin hooks (`tool.preExecute` policy / observe after policy and approval, `tool.postExecute`
+     * observe after the result). Only the chat pipeline gets it; the eval replay uses
+     * `RecordedToolPipeline`, which never runs hooks. Also needs `conversationKind: "chat"` (P-18).
+     */
+    pluginHooks?: HookRunner;
+    /**
+     * Ids of an extension's `inline` ui contributions (read live): a plugin tool's `ToolResult.card`
+     * must name one of them, otherwise it is dropped with a warning. Absent: cards are dropped.
+     */
+    inlineViews?: (plugin: string) => ReadonlySet<string>;
+    /**
+     * 连接器在调用途中报告工具清单变了（MCP `notifications/tools/list_changed`）：内核安排一次该连接器的漂移检查。
+     * 不等待、不抛错（实现自己吞掉错误）。
+     */
+    onToolsChanged?: (orgId: string, connectorId: string) => void;
+    /**
+     * Dispatches the sub-agent of an `agent` call (sub-agents spec §7.1; `dispatchSubagent`). Without
+     * it, `agent` calls reach the builtin's guard, which refuses them.
+     */
+    subagents?: {
+        dispatch(a: {
+            ctx: ToolStepContext;
+            callId: string;
+            input: AgentToolInputT;
+        }): Promise<DispatchOutcome>;
+    };
+}
+/** tools 节点处理一步工具调用所需的上下文。 */
+export interface ToolStepContext {
+    orgId: string;
+    conversationId: string;
+    runId: string;
+    step: number;
+    agentId: string;
+    /** 运行所用的 agent 版本（审计链记录）。 */
+    agentVersion: number;
+    agent: AgentDefinition;
+    /** 对话发起人（取个人凭据、审计 actor）。 */
+    accountId: string;
+    /** run 的中止信号（用户中止 / 截止时间）。 */
+    signal: AbortSignal;
+    /** run 的截止时间（epoch 毫秒）；传给内置工具（沙箱命令据此收紧超时，Ruling M20）。 */
+    deadline?: number;
+    /** Hooks fire only for `chat` conversations. */
+    conversationKind?: ConversationKindForHooks;
+    /**
+     * Set when the run is a sub-agent's: its builtin tools use the parent conversation's sandbox
+     * (spec §10.1) and it cannot dispatch sub-agents.
+     */
+    parent?: SubagentParent;
+}
+/** tools 节点一步的结果：全部调用都有了结果，或某个调用需要等人处理（之后的调用留到续跑）。 */
+export type ToolStepOutcome = {
+    kind: "done";
+} | {
+    kind: "suspended";
+    waitingFor: WaitingFor;
+};
+/** 续跑时带给处理函数的上一轮输入请求结果（`ctx.resume`）。 */
+export type ToolResume = {
+    state: unknown;
+    answer: FormAnswer | null;
+};
+/** 执行阶段的结果。 */
+export type ExecOutcome = 
+/** 工具返回了结果（可能是工具自己报告的错误，或畸形结果，由渲染阶段处理）。 */
+{
+    kind: "result";
+    result: unknown;
+}
+/** 处理函数需要用户输入（表单尚未校验）。 */
+ | {
+    kind: "input_required";
+    form: InputForm;
+    state: unknown;
+}
+/** 执行失败（超时、抛错、熔断、中止等），message 给模型看。 */
+ | {
+    kind: "error";
+    message: string;
+}
+/** 发起人未连接个人凭据：除错误结果外再写 `connection_required`。 */
+ | {
+    kind: "connection_required";
+    connectorId: string;
+    connectorName: string;
+    message: string;
+};
+type KernelTrx = Transaction<KernelDatabase>;
+/**
+ * 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 declare function subagentsWait(runId: string, step: number, config: Pick<KernelConfig, "tools" | "runtime">, now?: number): WaitingFor;
+/**
+ * 工具执行管线（spec 5.4 / 6.2）：每个阶段是独立函数——
+ * `resolveOutputRefs` → `validateInput` → `decidePolicy` → `execute`（超时、熔断）→ `renderResult` / `spillIfLarge`
+ * → 写 `tool_result` 与审计。
+ *
+ * 有副作用不盲目重跑（spec 4.3）：执行前写 `tool_call_started`；续跑时「有开始无结果」的调用记为结果未知，不再执行。
+ */
+export declare class ToolPipeline {
+    private readonly deps;
+    private readonly decide;
+    constructor(deps: ToolPipelineDeps);
+    /**
+     * tools 节点：按顺序处理本步 assistant 消息里的全部 `tool_call`，每个调用都以一条 `tool_result` 结束
+     * （之后才回到 prepare 构建下一次请求，保持「已记录调用、未记录结果之间不构建请求」的不变式）。
+     * 已有结果 → 跳过；有开始无结果 → 结果未知；run 已中止 → 不执行。
+     * 某个调用需要等人处理（审批 / 用户输入）→ 返回 `suspended`，之后的调用留到续跑时处理；
+     * 续跑时重新进入本函数，按 PG 里的审批 / 输入请求结果继续。
+     */
+    runStep(ctx: ToolStepContext): Promise<ToolStepOutcome>;
+    /**
+     * 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).
+     */
+    private finishAgentCall;
+    /**
+     * 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.
+     */
+    stopOpenAgentCalls(t: KernelTrx, runId: string, agent?: AgentDefinition): Promise<{
+        steps: number[];
+        callIds: Set<string>;
+        toSeq: number | null;
+        fire: () => void;
+    }>;
+    /**
+     * 处理一个尚无结果的调用。先看输入请求的轮次：最近一轮仍 pending → 继续等；否则本次是第
+     * `已有轮数 + 1` 次调用，已有轮次时带 `ctx.resume`（answered → 答案，expired / cancelled → null）。
+     * 本次调用「有开始无结果」→ 结果未知（spec 4.3）。返回需要等待的对象，或 undefined（已写结果）。
+     */
+    private processCall;
+    private runCall;
+    /**
+     * 发出本步调用的请求里带了完整定义的工具 key：本步最后一次尝试的 `model_call.request.tools`
+     * （`assistant_message` 来自最后一次尝试）。该请求不在 tool_search 模式（没有 `catalog`，工具全部发送）
+     * 或找不到 model_call 时返回 null（不做加载检查）。已加载集合由此从日志得出，不放进程内存。
+     */
+    private sentTools;
+    /** 审批的非批准结果 → 给模型的说明；仍 pending → null（继续等待）。 */
+    private refusalText;
+    /**
+     * 处理函数返回 `input_required`：超过轮次上限、表单不合规（`validateInputForm`）或 state 过大 → 返回给模型的错误说明；
+     * 否则建输入请求（写 `question_asked`）并返回等待对象。
+     */
+    private askInput;
+    /**
+     * 管线第 4 阶段：执行。内置 / 插件工具直接调用处理函数，连接器工具经连接器（每次调用打开并关闭会话）。
+     * 带 `tools.timeoutMs` 超时与 run 的中止信号（合并后传给处理函数 / 连接器，不响应信号的也按时结束）。
+     * 熔断只作用于连接器工具（键为组织 × 连接器）。
+     */
+    execute(tool: ResolvedTool, input: unknown, ctx: ToolStepContext, callId: string, resume?: ToolResume, stepTools?: readonly ResolvedTool[]): Promise<ExecOutcome>;
+    private executeConnector;
+    /** 抛出的错误 → 给模型的结果：ToolError 的消息原样（插件约定为英文、可操作），其他只给错误类名。 */
+    private thrown;
+    /**
+     * 带超时与中止执行 work：合并 run 信号与超时信号传给 work，并与之竞速（work 不响应信号也按时返回）。
+     * 返回 `{ value }`，或 `"timeout"` / `"aborted"`；work 自己的错误照常抛出。
+     */
+    private bounded;
+    /** 关闭会话（打开仍在进行时等它完成后关闭），最多等 {@link CLOSE_WAIT_MS}；失败只记日志。 */
+    private closeSession;
+    /**
+     * 工具结果里的显示摘要（`ToolResult.display`）：合法时只取 `{ summary: { zh, en } }`，没有给返回 undefined，
+     * 不合法时记告警并丢弃（结果照常写入）。摘要只进事件日志给界面看，不进模型请求。
+     */
+    private displayOf;
+    /**
+     * 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.
+     */
+    private cardOf;
+    /**
+     * 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.
+     */
+    private viewOf;
+    /**
+     * 管线第 6 阶段：写 `tool_result`（与 `connection_required` 同批）。传入 `callAudit`（即工具实际执行过；
+     * 耗时 null = 执行过但耗时未知，如续跑时「有开始无结果」的调用）时在同一事务里写审计 `tool.called`。
+     * 审计链（R6）：actor = 发起人 → agent（id + 版本）→ 会话 / 运行 / 调用 / 工具（连接器工具带 connectorId）→
+     * 放行依据（审批人 / 授权 / 策略）。不含参数、结果与凭据。
+     */
+    private writeResult;
+}
+export {};