@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.5

package/dist/tools/pipeline.d.ts

@@ -1,7 +1,8 @@
 import { type FormAnswer, type InputForm, type Logger } from "@capybara-hq/plugin-sdk";
-import { type AgentDefinition } from "../agents/definition.js";
+import type { AgentDefinition } from "../agents/definition.js";
 import { EventLog } from "../conversations/event-log.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { EffectiveConfigs } from "../extensions/effective-config.js";
 import { ExtensionHost } from "../extensions/host.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
@@ -9,16 +10,17 @@ 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 { DispatchArgs, DispatchOutcome } from "../runtime/subagents/dispatch.js";
+import { SubagentMessages } from "../runtime/subagents/messages.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 { Credentials } from "./credentials.js";
 import { ToolDrift } from "./drift.js";
+import { OrgToolSwitches } from "./org-tool-switches.js";
 import { ToolOutputs } from "./outputs.js";
 import { QuestionsService } from "./questions.service.js";
-import { type ResolvedTool, ToolRegistry } from "./registry.js";
+import { type CallPolicy, type ResolvedTool, ToolRegistry } from "./registry.js";
 /** 审批被拒绝。 */
 export declare const APPROVAL_DENIED_TEXT = "The user denied this tool call.";
 /**
@@ -85,16 +87,26 @@ export interface PolicyContext {
     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).
+     * A sub-agent's call: its parent conversation, whose agent's current policies apply on top
+     * (sub-agents spec §5.5).
      */
     parentConversationId?: string;
+    /**
+     * A sub-agent's call: the root conversation of its tree, where "approve for this conversation"
+     * grants are stored and looked up (agent map spec §7), so every agent of the tree uses them.
+     */
+    rootConversationId?: 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;
+    /**
+     * The call's per-call policy ({@link ResolvedTool.callPolicy} of the validated input), or
+     * null / unset: policies, grants and approvals use the tool key.
+     */
+    callPolicy?: CallPolicy | null;
 }
 /** 管线第 3 阶段：策略判定。 */
 export type DecidePolicy = (tool: ResolvedTool, agentDef: AgentDefinition, ctx: PolicyContext) => Promise<PolicyDecision>;
@@ -131,6 +143,13 @@ interface PipelineDeps {
      * `RecordedToolPipeline`, which never runs hooks. Also needs `conversationKind: "chat"` (P-18).
      */
     readonly pluginHooks: HookRunner | undefined;
+    /**
+     * The effective deployment config of an extension for an org (layering spec A §6): a plugin
+     * tool's handler gets it as `ToolCallContext.config`, and is not called when it is not valid.
+     */
+    readonly effective: Pick<EffectiveConfigs, "get">;
+    /** The org's switches of single extension tools: a turned-off one is not called (spec A §7). */
+    readonly switches: Pick<OrgToolSwitches, "isToolOff">;
     /**
      * 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.
@@ -146,12 +165,13 @@ interface PipelineDeps {
      * it, `Agent` calls reach the builtin's guard, which refuses them.
      */
     readonly subagents: {
-        dispatch(a: {
-            ctx: ToolStepContext;
-            callId: string;
-            input: AgentToolInputT;
-        }): Promise<DispatchOutcome>;
+        dispatch(a: DispatchArgs): Promise<DispatchOutcome>;
     } | undefined;
+    /**
+     * `SendMessage` and `SubagentHandback` (agent map spec §4.2, §4.3; `SubagentMessages`). Without
+     * it, their calls reach the builtins' guards, which refuse them.
+     */
+    readonly messages: Pick<SubagentMessages, "toChild" | "toParent"> | undefined;
 }
 /** The sub-agent dispatch the pipeline calls (`SubagentsService.dispatch`). */
 export type SubagentDispatch = NonNullable<PipelineDeps["subagents"]>["dispatch"];
@@ -174,8 +194,8 @@ export interface ToolStepContext {
     /** 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.
+     * Set when the run is a sub-agent's: its builtin tools use the root conversation's sandbox
+     * (spec §10.1, agent map spec §6), and it dispatches sub-agents only below `subagents.maxDepth`.
      */
     parent?: SubagentParent;
 }
@@ -230,9 +250,11 @@ export declare class ToolPipeline {
     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, 
+    subagents: Pick<SubagentsService, "dispatch"> | undefined, 
+    /** The message tools between agents; absent (tests): their calls are refused. */
+    messages: Pick<SubagentMessages, "toChild" | "toParent"> | 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);
+    host: Pick<ExtensionHost, "hooks" | "current"> | undefined, drift: Pick<ToolDrift, "onToolsChanged"> | undefined, effective: Pick<EffectiveConfigs, "get">, switches: Pick<OrgToolSwitches, "isToolOff">, txHost: TransactionHost, hooks?: ToolPipelineHooks);
     /**
      * tools 节点：按顺序处理本步 assistant 消息里的全部 `tool_call`，每个调用都以一条 `tool_result` 结束
      * （之后才回到 prepare 构建下一次请求，保持「已记录调用、未记录结果之间不构建请求」的不变式）。
@@ -242,32 +264,14 @@ 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
-     * 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;
-    /** {@link stopOpenAgentCalls} in a transaction of its own (a stop seen by the tools node). */
-    private stopOpenAgentCallsNow;
-    /**
-     * 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 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.
+     * Writes, in the caller's transaction (`mandatory`), what a run that is being stopped (a person,
+     * its deadline, a failure, the wait sweep) still owes its log: the report of its fork invocation
+     * (phase D, `pairStoppedForks`; a still active fork child is stopped by the caller after its
+     * commit). An `Agent` call has its result from its dispatch (agent map spec §4.1), so there is
+     * nothing to write for it. Returns the fork's call id (the caller must not write a "not executed"
+     * result for it), the highest seq written, and `fire`, a no-op kept for the callers' hook phase.
      */
-    stopOpenAgentCalls(runId: string, agent?: AgentDefinition): Promise<{
+    stopOpenAgentCalls(runId: string): Promise<{
         steps: number[];
         callIds: Set<string>;
         toSeq: number | null;
@@ -280,6 +284,8 @@ export declare class ToolPipeline {
      */
     private processCall;
     private runCall;
+    /** Appends a sub-agent's connect card to its root conversation ({@link rootSurfaceOf}). */
+    private surfaceConnectInRoot;
     /**
      * 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