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

package/dist/tools/pipeline.d.ts

@@ -1,20 +1,24 @@
 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 { EventLog } from "../conversations/event-log.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { ExtensionHost } from "../extensions/host.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 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 { SubagentsService } from "../runtime/subagents/subagents.service.js";
+import { ApprovalsService } from "./approvals.service.js";
+import { 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";
+import { Credentials } from "./credentials.js";
+import { ToolDrift } from "./drift.js";
+import { ToolOutputs } from "./outputs.js";
+import { QuestionsService } from "./questions.service.js";
+import { type ResolvedTool, ToolRegistry } from "./registry.js";
 /** 审批被拒绝。 */
 export declare const APPROVAL_DENIED_TEXT = "The user denied this tool call.";
 /**
@@ -94,55 +98,63 @@ export interface PolicyContext {
 }
 /** 管线第 3 阶段：策略判定。 */
 export type DecidePolicy = (tool: ResolvedTool, agentDef: AgentDefinition, ctx: PolicyContext) => Promise<PolicyDecision>;
-/** 测试钩子。 */
+/** The pipeline's test seams (`TOOL_PIPELINE_HOOKS`; the kernel never provides them). */
 export interface ToolPipelineHooks {
-    /** 工具执行返回之后、结果写入日志之前调用：抛错即模拟「工具已执行、结果未记录」时进程崩溃。 */
+    /**
+     * Called after a tool returned and before its result is logged: throwing simulates a crash
+     * between the execution and the record ("executed, result not recorded").
+     */
     afterExecute?(runId: string, callId: string): Promise<void>;
+    /** The policy decision; default {@link createDecidePolicy} (reads policies and grants live). */
+    decidePolicy?: DecidePolicy;
 }
-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">;
+/** Optional provider: the pipeline's {@link ToolPipelineHooks} (tests). */
+export declare const TOOL_PIPELINE_HOOKS: unique symbol;
+/** What the pipeline calls through (the sub-agent dispatch is read at call time). */
+interface PipelineDeps {
+    /** The kernel-schema handle of the current context (its transaction, else the pool). */
+    readonly db: KernelSchemaDb;
+    readonly eventLog: EventLog;
+    readonly registry: Pick<ToolRegistry, "forAgent" | "findConnector" | "handler">;
+    readonly credentials: Pick<Credentials, "injection" | "onUnauthorized">;
+    readonly breaker: Pick<Breaker, "check" | "failure" | "success">;
+    readonly outputs: Pick<ToolOutputs, "save" | "load">;
     /** 策略为 `ask` 时建审批；续跑时读该调用的审批结果。 */
-    approvals: Pick<ApprovalsService, "request" | "forCall">;
+    readonly approvals: Pick<ApprovalsService, "request" | "forCall">;
     /** 处理函数返回 `input_required` 时建输入请求；续跑时读该调用的各轮输入请求。 */
-    questions: Pick<QuestionsService, "ask" | "forCall">;
-    config: () => KernelConfig;
-    log: Logger;
-    /** 默认 {@link createDecidePolicy}（执行时实时读取策略与授权）。 */
-    decidePolicy?: DecidePolicy;
-    hooks?: ToolPipelineHooks;
+    readonly questions: Pick<QuestionsService, "ask" | "forCall">;
+    readonly log: Logger;
+    readonly hooks: ToolPipelineHooks | undefined;
     /**
      * 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
+     * observe after the result). Only the chat pipeline has them; the eval replay uses
      * `RecordedToolPipeline`, which never runs hooks. Also needs `conversationKind: "chat"` (P-18).
      */
-    pluginHooks?: HookRunner;
+    readonly pluginHooks: HookRunner | undefined;
     /**
-     * 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.
+     * Ids of an extension's `inline` ui contributions (read live, no alias): a plugin tool's
+     * `ToolResult.card` must name one of them, otherwise it is dropped with a warning.
      */
-    inlineViews?: (plugin: string) => ReadonlySet<string>;
+    inlineViews(plugin: string): ReadonlySet<string>;
     /**
      * 连接器在调用途中报告工具清单变了（MCP `notifications/tools/list_changed`）：内核安排一次该连接器的漂移检查。
      * 不等待、不抛错（实现自己吞掉错误）。
      */
-    onToolsChanged?: (orgId: string, connectorId: string) => void;
+    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.
+     * 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?: {
+    readonly subagents: {
         dispatch(a: {
             ctx: ToolStepContext;
             callId: string;
             input: AgentToolInputT;
         }): Promise<DispatchOutcome>;
-    };
+    } | undefined;
 }
+/** The sub-agent dispatch the pipeline calls (`SubagentsService.dispatch`). */
+export type SubagentDispatch = NonNullable<PipelineDeps["subagents"]>["dispatch"];
 /** tools 节点处理一步工具调用所需的上下文。 */
 export interface ToolStepContext {
     orgId: string;
@@ -204,13 +216,6 @@ export type ExecOutcome =
     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`
@@ -219,9 +224,15 @@ export declare function subagentsWait(runId: string, step: number, config: Pick<
  * 有副作用不盲目重跑（spec 4.3）：执行前写 `tool_call_started`；续跑时「有开始无结果」的调用记为结果未知，不再执行。
  */
 export declare class ToolPipeline {
-    private readonly deps;
+    private readonly config;
+    readonly txHost: TransactionHost;
     private readonly decide;
-    constructor(deps: ToolPipelineDeps);
+    private readonly deps;
+    constructor(kdb: KernelDb, eventLog: EventLog, 
+    /** The `Agent` tool's sub-agent dispatch; absent (tests): `Agent` calls are refused. */
+    subagents: Pick<SubagentsService, "dispatch"> | undefined, registry: Pick<ToolRegistry, "forAgent" | "findConnector" | "handler">, credentials: Pick<Credentials, "injection" | "onUnauthorized">, breaker: Pick<Breaker, "check" | "failure" | "success">, outputs: Pick<ToolOutputs, "save" | "load">, approvals: Pick<ApprovalsService, "request" | "forCall">, questions: Pick<QuestionsService, "ask" | "forCall">, config: Pick<KernelConfigService, "get">, log: Logger, 
+    /** Plugin hooks and inline ui contributions; absent (tests): no hooks, cards dropped. */
+    host: Pick<ExtensionHost, "hooks" | "current"> | undefined, drift: Pick<ToolDrift, "onToolsChanged"> | undefined, txHost: TransactionHost, hooks?: ToolPipelineHooks);
     /**
      * tools 节点：按顺序处理本步 assistant 消息里的全部 `tool_call`，每个调用都以一条 `tool_result` 结束
      * （之后才回到 prepare 构建下一次请求，保持「已记录调用、未记录结果之间不构建请求」的不变式）。
@@ -231,7 +242,7 @@ export declare class ToolPipeline {
      */
     runStep(ctx: ToolStepContext): Promise<ToolStepOutcome>;
     /**
-     * An `agent` call that was dispatched (spec §7.1 "already dispatched"): when its child run is
+     * 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).
      *
@@ -241,19 +252,22 @@ export declare class ToolPipeline {
      * result, from the replica that writes it (spec §11).
      */
     private finishAgentCall;
+    /** {@link stopOpenAgentCalls} in a transaction of its own (a stop seen by the tools node). */
+    private stopOpenAgentCallsNow;
     /**
-     * Writes, in `t`, the `tool_result` of every open `agent` call of a run that is being stopped
+     * Writes, in the caller's transaction (`mandatory`), 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`
+     * Like every `Agent` result (see {@link finishAgentCall}), each is audited `tool.called` in it
      * (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<{
+    stopOpenAgentCalls(runId: string, agent?: AgentDefinition): Promise<{
         steps: number[];
         callIds: Set<string>;
         toSeq: number | null;
@@ -266,9 +280,15 @@ export declare class ToolPipeline {
      */
     private processCall;
     private runCall;
+    /**
+     * Every tool key the request that issued this step's calls offered (`request.tools` plus the
+     * `catalog` keys), in any mode; null when its model_call is not found. Used to tell a call to an
+     * old key that was offered (in flight across the rename) from one that never was.
+     */
+    private requestToolKeys;
     /**
      * 发出本步调用的请求里带了完整定义的工具 key：本步最后一次尝试的 `model_call.request.tools`
-     * （`assistant_message` 来自最后一次尝试）。该请求不在 tool_search 模式（没有 `catalog`，工具全部发送）
+     * （`assistant_message` 来自最后一次尝试）。该请求不在 ToolSearch 模式（没有 `catalog`，工具全部发送）
      * 或找不到 model_call 时返回 null（不做加载检查）。已加载集合由此从日志得出，不放进程内存。
      */
     private sentTools;
@@ -318,5 +338,7 @@ export declare class ToolPipeline {
      * 放行依据（审批人 / 授权 / 策略）。不含参数、结果与凭据。
      */
     private writeResult;
+    /** The result's events and audit rows in one transaction (see {@link writeResult}). */
+    private writeResultIn;
 }
 export {};