@springbrand/agent-runtime 0.3.0-alpha.1 → 0.3.0-alpha.10

package/src/tools/{gateway.ts → mcp/gateway.ts}

@@ -1,6 +1,6 @@
-import type { RuntimeGatewaySession } from "../config/ports";
-import type { PiToolCandidate } from "./compiler";
-import { createPiMcpToolCandidate } from "./mcp";
+import type { RuntimeGatewaySession } from "../../config/ports";
+import type { PiToolCandidate } from "../runtime/contracts";
+import { createPiMcpToolCandidate } from "./index";
 
 const GATEWAY_TOOLS = [
   "search_capabilities",
@@ -31,22 +31,22 @@ export function createPiGatewayToolCandidates(
         requiredExecutionLevel: execute ? "high" : "safe",
         ...(execute
           ? {
-              requiredExecutionLevelForInput: async (input: unknown) => {
-                const reference = input && typeof input === "object" &&
-                    !Array.isArray(input)
-                  ? (input as Record<string, unknown>).name
-                  : undefined;
-                if (typeof reference !== "string" || !reference) {
-                  throw new Error(
-                    "Gateway Capability Reference is not verified",
-                  );
-                }
-                return (await session.resolveCapabilityRisk(reference)) ===
-                    "none"
-                  ? "safe" as const
-                  : "high" as const;
-              },
-            }
+            requiredExecutionLevelForInput: async (input: unknown) => {
+              const reference = input && typeof input === "object" &&
+                !Array.isArray(input)
+                ? (input as Record<string, unknown>).name
+                : undefined;
+              if (typeof reference !== "string" || !reference) {
+                throw new Error(
+                  "Gateway Capability Reference is not verified",
+                );
+              }
+              return (await session.resolveCapabilityRisk(reference)) ===
+                "none"
+                ? "safe" as const
+                : "high" as const;
+            },
+          }
           : {}),
       },
     );

package/src/tools/{mcp.ts → mcp/index.ts}

@@ -1,6 +1,6 @@
-import type { RuntimeMcpServer } from "../config/profile";
-import type { PiToolCandidate } from "./compiler";
-import { createPiDeclaredToolCandidate } from "./declared";
+import type { RuntimeMcpServer } from "../../config/profile";
+import { createPiDeclaredToolCandidate } from "../adapters/declared";
+import type { PiToolCandidate } from "../runtime/contracts";
 
 interface McpCallResult {
   content: unknown[];
@@ -34,7 +34,7 @@ interface PiMcpCandidatePolicy {
  * 单个 Server 的客户端，Server 是对外提供工具的服务。连接持久化、OAuth 和
  * 恢复仍由 Agents SDK 的 MCP Client 管理，本接口只读取和调用。
  *
- * `Host` 与 `Pi` 等项目核心术语见 `../../index.ts`。
+ * `Host` 与 `Pi` 等项目核心术语见 `src/index.ts`。
  */
 export interface PiMcpHost {
   /**
@@ -284,7 +284,7 @@ export function createPiMcpToolCandidate(
  * 远端 Server 提供的 annotations 只是提示，不是本地审批边界，所以所有动态
  * MCP 工具继续标为高风险，不能据此绕过审批。
  *
- * `Host`、`Pi`、`Runtime Snapshot` 与“候选工具”见 `../../index.ts`。
+ * `Host`、`Pi`、`Runtime Snapshot` 与“候选工具”见 `src/index.ts`。
  */
 export async function createPiMcpToolCandidates(
   host: PiMcpHost,

package/src/tools/{approval → runtime/approval}/repository.ts

@@ -1,8 +1,7 @@
 import type { SqlTaggedTemplate } from "agents/chat";
-import type { ExecutionLevel } from "../../lib/execution-level";
+import type { ExecutionLevel } from "../../../lib/execution-level";
 
 // Approval 的统一定义见 ./index.ts。
-// #region 状态与行类型
 export type ApprovalStatus = "pending" | "approved" | "rejected";
 
 export interface StoredApproval {
@@ -16,6 +15,7 @@ export interface StoredApproval {
   executionLevel: ExecutionLevel;
   requiredExecutionLevel: ExecutionLevel;
   inputJson: string;
+  confirmationJson?: string | null;
   status: ApprovalStatus;
   createdAt: number;
   decidedAt: number | null;
@@ -33,6 +33,7 @@ export interface NewApproval {
   executionLevel: ExecutionLevel;
   requiredExecutionLevel: ExecutionLevel;
   inputJson: string;
+  confirmationJson?: string | null;
   status: ApprovalStatus;
   createdAt: number;
 }
@@ -46,6 +47,7 @@ export interface PendingApprovalSummary {
   executionLevel: ExecutionLevel;
   requiredExecutionLevel: ExecutionLevel;
   inputJson: string;
+  confirmationJson?: string | null;
   requestId: string;
 }
 
@@ -66,14 +68,13 @@ type ApprovalRow = {
   execution_level: string;
   required_level: string;
   input_json: string;
+  confirmation_json: string | null;
   status: string;
   created_at: number;
   decided_at: number | null;
   reason: string | null;
 };
 
-// #endregion
-// #region 行映射
 // 把 SQLite 的 Approval 行转成 Runtime 对象。
 // find 查到记录后调用，上层因而不需要理解 snake_case 列名。
 // 状态由表内字符串转成联合类型；新增列或状态时必须同步核对类型、SELECT 和映射。
@@ -89,6 +90,7 @@ function mapRow(row: ApprovalRow): StoredApproval {
     executionLevel: row.execution_level as ExecutionLevel,
     requiredExecutionLevel: row.required_level as ExecutionLevel,
     inputJson: row.input_json,
+    confirmationJson: row.confirmation_json,
     status: row.status as ApprovalStatus,
     createdAt: row.created_at,
     decidedAt: row.decided_at,
@@ -96,13 +98,11 @@ function mapRow(row: ApprovalRow): StoredApproval {
   };
 }
 
-// #endregion
-// #region Repository
 export class ApprovalRepository {
   // 保存当前 Agent SQLite 的查询入口。
   // RuntimeDatabase 构造时调用，HarnessDecisionGate 和 Transcript 随后共享这个 Repository。
   // Approval 必须与所属 Submission 在同一 Agent 存储中查询，不能跨 Durable Object 拼接状态。
-  constructor(private readonly sql: SqlTaggedTemplate) {}
+  constructor(private readonly sql: SqlTaggedTemplate) { }
 
   // 按 executionId 读取一条完整 Approval，不存在时返回 null。
   // HarnessDecisionGate 在请求去重、决策、继续和拒绝时调用，调用方必须处理 null。
@@ -111,7 +111,7 @@ export class ApprovalRepository {
     const row = this.sql<ApprovalRow>`
       SELECT execution_id, submission_id, request_id, source,
              tool_call_id, tool_name, summary,
-             execution_level, required_level, input_json,
+             execution_level, required_level, input_json, confirmation_json,
              status, created_at, decided_at, reason
       FROM pi_approvals
       WHERE execution_id = ${executionId}
@@ -128,7 +128,7 @@ export class ApprovalRepository {
       INSERT INTO pi_approvals (
         execution_id, submission_id, request_id, source,
         tool_call_id, tool_name, summary,
-        execution_level, required_level, input_json,
+        execution_level, required_level, input_json, confirmation_json,
         status, created_at
       ) VALUES (
         ${approval.executionId},
@@ -141,6 +141,7 @@ export class ApprovalRepository {
         ${approval.executionLevel},
         ${approval.requiredExecutionLevel},
         ${approval.inputJson},
+        ${approval.confirmationJson ?? null},
         ${approval.status},
         ${approval.createdAt}
       )
@@ -192,12 +193,13 @@ export class ApprovalRepository {
       execution_level: string;
       required_level: string;
       input_json: string;
+      confirmation_json: string | null;
       request_id: string;
     }>`
       SELECT approval.execution_id, approval.tool_call_id, approval.source,
              approval.tool_name, approval.summary,
              approval.execution_level, approval.required_level,
-             approval.input_json, approval.request_id
+             approval.input_json, approval.confirmation_json, approval.request_id
       FROM pi_approvals approval
       JOIN pi_submissions submission
         ON submission.submission_id = approval.submission_id
@@ -212,7 +214,7 @@ export class ApprovalRepository {
       summary: row.summary,
       executionLevel: row.execution_level as ExecutionLevel,
       requiredExecutionLevel: row.required_level as ExecutionLevel,
-      inputJson: row.input_json,
+      inputJson: row.confirmation_json ?? row.input_json,
       requestId: row.request_id,
     }));
   }
@@ -271,4 +273,3 @@ export class ApprovalRepository {
     }));
   }
 }
-// #endregion

package/src/tools/{compiler.ts → runtime/compiler.ts}

@@ -1,121 +1,16 @@
-import type {
-  AgentHarnessTool,
-  AgentTool,
-  AgentToolResult,
-} from "@earendil-works/pi-agent-core";
-import type { ApprovalReceipt } from "../submission/contracts";
-import {
-  boundDurableToolOutput,
-  type BudgetPolicy,
-  spillDurableToolOutput,
-} from "../context/memory/budget/gate";
-import {
-  type ArtifactRef,
-  serializeOutput,
-  type SpillWorkspace,
-} from "../lib/artifacts";
-import {
-  type ExecutionLevel,
-} from "../lib/execution-level";
-
-// 本文件沿用 `../../index.ts` 入口定义的 Tool Candidate 和 Tool Settlement 术语。
-
-// #region Public contracts
-
-/**
- * 声明一个 Tool 的结果由客户端投递，而不是由 `execute()` 产出。
- *
- * 带这个字段的 Tool 会在执行链里 park 住，等宿主经 `respondToolInteraction` 把响应送进来，
- * 再用 `settle` 把响应映射成这次 `toolCallId` 的权威 ToolResult。它的 `execute` 不会被调用。
- *
- * 这是 AI SDK 里「没有 execute 的 user-interaction tool」的等价物；差别是我们 park 住整个 Turn，
- * 而不是让 tool part 悬空到下一次请求 —— 我们的 transcript 是服务端权威的，悬空的 tool_use
- * 会让下一次模型调用非法。
- */
-export interface PiToolInteractionSpec {
-  /** 结合 Tool 输入校验客户端响应体；不通过则拒绝投递，park 保持不变。 */
-  readonly validateResponse: (input: unknown, response: unknown) => boolean;
-  /** 把通过校验的响应映射成 ToolResult；缺省是原样回传。 */
-  readonly settle?: (
-    input: unknown,
-    response: unknown,
-  ) => Omit<AgentToolResult<unknown>, "terminate">;
-}
-
-/** 描述一个尚未进入最终 Tool Surface 和结算包装的 Pi 工具。 */
-export type ToolExposureMode = "direct" | "codemode" | "both";
-
-export interface PiToolCandidate {
-  readonly owner: string;
-  readonly tool: AgentTool<any, any>;
-  /** @internal Send the complete schema but hide it until provider Tool Search finds it. */
-  readonly deferLoading?: true;
-  /** Omitted means visible both directly and through Code Mode. */
-  readonly exposureMode?: ToolExposureMode;
-  /** Conservative maximum used in the stable Runtime descriptor. */
-  readonly requiredExecutionLevel: ExecutionLevel;
-  /** Trusted parameter-level policy, evaluated before approval or dispatch. */
-  readonly requiredExecutionLevelForInput?: (
-    input: unknown,
-  ) => ExecutionLevel | Promise<ExecutionLevel>;
-  /**
-   * 无条件需要人来决定：不看执行档位矩阵，每次调用都 park 出审批。
-   *
-   * 档位差是「够不够格自己跑」，不是「该不该问人」。花用户钱、改变账户
-   * 状态这类工具，一旦 Agent 档位被 `allow_level` 永久拉高就会静默执行，
-   * 那是失效不是降级。`deny` 仍然优先，被 deny 的工具根本不会注入。
-   */
-  readonly alwaysRequiresApproval?: boolean;
-  /** Recovery may replay this Tool Call only when the candidate guarantees convergence. Omitted means non-idempotent. */
-  readonly retry?: "idempotent" | "non-idempotent";
-  readonly summary?: string;
-  readonly source?: ApprovalReceipt["source"];
-  readonly interaction?: PiToolInteractionSpec;
-  /** Large payloads spill by default; protocol-shaped results opt into structure. */
-  readonly outputBudget?: BudgetPolicy;
-}
-
-export interface CompileHarnessToolsOptions {
-  readonly workspace?: SpillWorkspace;
-  /** Recheck live authorization at the effect boundary, including safe replay. */
-  readonly authorize?: (
-    candidate: PiToolCandidate,
-    args: unknown,
-    invocation: { readonly toolCallId: string; readonly signal: AbortSignal },
-  ) => void | Promise<void>;
-  /** Return an already decided interaction result without invoking the handler. */
-  readonly resolveReplay?: (
-    candidate: PiToolCandidate,
-    toolCallId: string,
-    args: unknown,
-  ) => AgentToolResult<unknown> | undefined | Promise<AgentToolResult<unknown> | undefined>;
-  /** Optional business projection; Pi remains the authoritative Tool result. */
-  readonly onSettlement?: (
-    call: SettledPiToolCall,
-  ) => void | Promise<void>;
-}
-
-/** 描述一次已进入持久化结算边界的 Pi 工具调用。 */
-export interface SettledPiToolCall {
-  readonly toolCallId: string;
-  readonly toolName: string;
-  readonly args: unknown;
-  readonly result: AgentToolResult<unknown>;
-  readonly isError: boolean;
-  /** Diagnostic-only original error; callers must not persist or expose it. */
-  readonly cause?: unknown;
-  readonly summary?: string;
-  readonly source?: ApprovalReceipt["source"];
-}
+import type { AgentHarnessTool, AgentToolResult } from "@earendil-works/pi-agent-core";
+import { boundDurableToolOutput, spillDurableToolOutput } from "../../context/memory/budget/gate";
+import { artifactId, serializeOutput, sha256Hex, type ArtifactRef, type SpillWorkspace } from "../../lib/artifacts";
+import type { CompileHarnessToolsOptions, PiToolCandidate } from "./contracts";
+import { UnattendedExecutionError } from "./unattended-error";
 
 // DO SQLite rows also contain arguments and transcript/recovery envelopes.
 // Keep each serialized result below half the 2 MiB row limit.
 const DURABLE_TOOL_RESULT_MAX_BYTES = 1024 * 1024;
+
 const MEDIA_CAPTION_MAX_CHARS = 4 * 1024;
 
-// #endregion
 
-// #region Governance helpers
 
 // 把任意失败值收敛为可安全显示的简短消息。
 // 受治理工具在工具执行或结算抛错时调用它。
@@ -154,11 +49,11 @@ function artifactResult(
   let captionRemaining = MEDIA_CAPTION_MAX_CHARS;
   const mediaContent = result.content.some((part) => part.type !== "text")
     ? result.content.flatMap((part): AgentToolResult<unknown>["content"] => {
-        if (part.type !== "text") return [part];
-        const text = part.text.slice(0, captionRemaining);
-        captionRemaining -= text.length;
-        return text ? [{ ...part, text }] : [];
-      })
+      if (part.type !== "text") return [part];
+      const text = part.text.slice(0, captionRemaining);
+      captionRemaining -= text.length;
+      return text ? [{ ...part, text }] : [];
+    })
     : [];
   return {
     ...result,
@@ -175,15 +70,54 @@ function artifactResult(
   };
 }
 
+async function unavailableArtifactResult(
+  result: AgentToolResult<unknown>,
+): Promise<AgentToolResult<unknown>> {
+  const { text, ext } = serializeOutput(spillPayload(result));
+  const hash = await sha256Hex(text);
+  const ref: ArtifactRef = {
+    kind: "artifact_ref",
+    artifactId: artifactId(hash),
+    path: `/scratch/tool-output/${hash.slice(0, 24)}.${ext}`,
+    bytes: new TextEncoder().encode(text).byteLength,
+    hash,
+    workspaceRevision: "unavailable",
+    availability: "unavailable",
+    preview: text.slice(0, 600),
+    note:
+      "The Tool output was too large to keep inline, and the Workspace artifact " +
+      "could not be verified. The evidence is unavailable; do not treat the preview as complete.",
+  };
+  return {
+    ...result,
+    content: [{
+      type: "text",
+      text: [
+        ref.note,
+        `Artifact ID: ${ref.artifactId}`,
+        `Path: ${ref.path}`,
+        `Bytes: ${ref.bytes}`,
+        `Hash: ${ref.hash}`,
+        `Preview:\n${ref.preview}`,
+      ].join("\n"),
+    }],
+    details: ref,
+  };
+}
+
 async function durableResult(
   result: AgentToolResult<unknown>,
   candidate: PiToolCandidate,
   workspace: SpillWorkspace | undefined,
 ): Promise<AgentToolResult<unknown>> {
   const spill = (candidate.outputBudget ?? { kind: "spill" }).kind === "spill";
+  const serialized = serializeOutput(spillPayload(result));
   let ref = spill
     ? await spillDurableToolOutput(spillPayload(result), { workspace })
     : null;
+  if (spill && serialized.text.length > 32 * 1024 && !ref) {
+    return unavailableArtifactResult(result);
+  }
   const bounded = ref
     ? artifactResult(result, ref)
     : boundDurableToolOutput(result) as AgentToolResult<unknown>;
@@ -221,9 +155,7 @@ async function untilAborted<T>(
   }
 }
 
-// #endregion
 
-// #region Governance and compilation
 
 /**
  * Convert the configured candidate surface once at the AgentHarness boundary.
@@ -239,19 +171,19 @@ export function compileHarnessTools(
     const tool = source.constrainedSampling === false
       ? source
       : {
-          ...source,
-          constrainedSampling: source.constrainedSampling ?? {
-            type: "json_schema" as const,
-            strict: "prefer" as const,
-          },
-        };
+        ...source,
+        constrainedSampling: source.constrainedSampling ?? {
+          type: "json_schema" as const,
+          strict: "prefer" as const,
+        },
+      };
     return {
       ...tool,
       replay: candidate.retry === "idempotent" &&
-          candidate.requiredExecutionLevel === "safe" &&
-          !candidate.alwaysRequiresApproval &&
-          !candidate.requiredExecutionLevelForInput &&
-          !candidate.interaction
+        candidate.requiredExecutionLevel === "safe" &&
+        !candidate.alwaysRequiresApproval &&
+        !candidate.requiredExecutionLevelForInput &&
+        !candidate.interaction
         ? "safe" as const
         : "never" as const,
       ...(candidate.deferLoading ? { deferLoading: true as const } : {}),
@@ -264,27 +196,28 @@ export function compileHarnessTools(
         context,
       ) {
         const signal = context.abortSignal ?? new AbortController().signal;
-        await options.authorize?.(candidate, args, {
-          toolCallId,
-          signal,
-        });
-        const replay = await options.resolveReplay?.(
-          candidate,
-          toolCallId,
-          args,
-        );
-        if (replay) return durableResult(replay, candidate, options.workspace);
         let result: AgentToolResult<unknown>;
         try {
+          await options.authorize?.(candidate, args, {
+            toolCallId,
+            signal,
+          });
+          const replay = await options.resolveReplay?.(
+            candidate,
+            toolCallId,
+            args,
+          );
+          if (replay) return durableResult(replay, candidate, options.workspace);
           result = await untilAborted(
             signal,
             async () => durableResult(
-              await source.execute(
-                toolCallId,
-                args,
-                signal,
-                (update) => onUpdate(update),
-              ),
+              await (candidate.confirmation
+                ? (() => {
+                  const confirmed = options.resolveConfirmation?.(candidate, toolCallId, args);
+                  if (!confirmed) throw new Error("User confirmation is required");
+                  return candidate.confirmation.execute(confirmed.prepared, { intentId: confirmed.intentId, signal });
+                })()
+                : source.execute(toolCallId, args, signal, (update) => onUpdate(update))),
               candidate,
               options.workspace,
             ),
@@ -305,6 +238,9 @@ export function compileHarnessTools(
             summary: candidate.summary,
             source: candidate.source,
           });
+          if (cause instanceof UnattendedExecutionError) {
+            return { ...failed, terminate: true };
+          }
           throw cause instanceof Error && cause.message === message
             ? cause
             : new Error(message, { cause });
@@ -314,7 +250,10 @@ export function compileHarnessTools(
           toolName: source.name,
           args,
           result,
-          isError: false,
+          isError: result.details !== null &&
+            typeof result.details === "object" &&
+            (result.details as { availability?: unknown }).availability ===
+              "unavailable",
           summary: candidate.summary,
           source: candidate.source,
         });
@@ -323,5 +262,3 @@ export function compileHarnessTools(
     } satisfies AgentHarnessTool<object | undefined>;
   });
 }
-
-// #endregion

package/src/tools/runtime/contracts.ts

@@ -0,0 +1,117 @@
+import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ApprovalReceipt } from "../../submission/contracts";
+import { type BudgetPolicy } from "../../context/memory/budget/gate";
+import { type SpillWorkspace } from "../../lib/artifacts";
+import { type ExecutionLevel } from "../../lib/execution-level";
+
+// 本文件沿用 `src/index.ts` 入口定义的 Tool Candidate 和 Tool Settlement 术语。
+
+
+/**
+ * 声明一个 Tool 的结果由客户端投递，而不是由 `execute()` 产出。
+ *
+ * 带这个字段的 Tool 会在执行链里 park 住，等宿主经 `respondToolInteraction` 把响应送进来，
+ * 再用 `settle` 把响应映射成这次 `toolCallId` 的权威 ToolResult。它的 `execute` 不会被调用。
+ *
+ * 这是 AI SDK 里「没有 execute 的 user-interaction tool」的等价物；差别是我们 park 住整个 Turn，
+ * 而不是让 tool part 悬空到下一次请求 —— 我们的 transcript 是服务端权威的，悬空的 tool_use
+ * 会让下一次模型调用非法。
+ */
+export interface PiToolInteractionSpec {
+  /** 结合 Tool 输入校验客户端响应体；不通过则拒绝投递，park 保持不变。 */
+  readonly validateResponse: (input: unknown, response: unknown) => boolean;
+  /** 把通过校验的响应映射成 ToolResult；缺省是原样回传。 */
+  readonly settle?: (
+    input: unknown,
+    response: unknown,
+  ) => Omit<AgentToolResult<unknown>, "terminate">;
+}
+
+/** Trusted Tool metadata used to evaluate a scheduled task grant. */
+export interface PiToolUnattendedExecutionSpec {
+  readonly capability: string;
+  readonly operation: string;
+  readonly objectForInput?: (
+    input: unknown,
+  ) => unknown | Promise<unknown>;
+}
+
+/** 描述一个尚未进入最终 Tool Surface 和结算包装的 Pi 工具。 */
+export type ToolExposureMode = "direct" | "codemode" | "both";
+
+/** Host-prepared confirmation travels through the existing durable approval. */
+export interface PiToolConfirmationSpec {
+  prepare(input: unknown, context: { intentId: string }): Promise<unknown>;
+  execute(prepared: unknown, context: { intentId: string; signal: AbortSignal }): Promise<AgentToolResult<unknown>>;
+}
+
+export interface PiToolCandidate {
+  /** Presentation only, resolved at the model boundary; never changes approved execution inputs. */
+  readonly modelGuidance?: () => Promise<{ description: string; systemPrompt?: string }>;
+  readonly confirmation?: PiToolConfirmationSpec;
+  readonly owner: string;
+  readonly tool: AgentTool<any, any>;
+  /** @internal Send the complete schema but hide it until provider Tool Search finds it. */
+  readonly deferLoading?: true;
+  /** Omitted means visible both directly and through Code Mode. */
+  readonly exposureMode?: ToolExposureMode;
+  /** Conservative maximum used in the stable Runtime descriptor. */
+  readonly requiredExecutionLevel: ExecutionLevel;
+  /** Trusted parameter-level policy, evaluated before approval or dispatch. */
+  readonly requiredExecutionLevelForInput?: (
+    input: unknown,
+  ) => ExecutionLevel | Promise<ExecutionLevel>;
+  /**
+   * 无条件需要人来决定：不看执行档位矩阵，每次调用都 park 出审批。
+   *
+   * 档位差是「够不够格自己跑」，不是「该不该问人」。花用户钱、改变账户
+   * 状态这类工具，一旦 Agent 档位被 `allow_level` 永久拉高就会静默执行，
+   * 那是失效不是降级。`deny` 仍然优先，被 deny 的工具根本不会注入。
+   */
+  readonly alwaysRequiresApproval?: boolean;
+  /** Declares the concrete grant identity derived from actual Tool input. */
+  readonly unattendedExecution?: PiToolUnattendedExecutionSpec;
+  /** Explicitly forbids this Tool from unattended Scheduled Runs. */
+  readonly unattendedMode?: "forbidden";
+  /** Recovery may replay this Tool Call only when the candidate guarantees convergence. Omitted means non-idempotent. */
+  readonly retry?: "idempotent" | "non-idempotent";
+  readonly summary?: string;
+  readonly source?: ApprovalReceipt["source"];
+  readonly interaction?: PiToolInteractionSpec;
+  /** Large payloads spill by default; protocol-shaped results opt into structure. */
+  readonly outputBudget?: BudgetPolicy;
+}
+
+export interface CompileHarnessToolsOptions {
+  readonly workspace?: SpillWorkspace;
+  readonly resolveConfirmation?: (candidate: PiToolCandidate, toolCallId: string, args: unknown) => { prepared: unknown; intentId: string };
+  /** Recheck live authorization at the effect boundary, including safe replay. */
+  readonly authorize?: (
+    candidate: PiToolCandidate,
+    args: unknown,
+    invocation: { readonly toolCallId: string; readonly signal: AbortSignal },
+  ) => void | Promise<void>;
+  /** Return an already decided interaction result without invoking the handler. */
+  readonly resolveReplay?: (
+    candidate: PiToolCandidate,
+    toolCallId: string,
+    args: unknown,
+  ) => AgentToolResult<unknown> | undefined | Promise<AgentToolResult<unknown> | undefined>;
+  /** Optional business projection; Pi remains the authoritative Tool result. */
+  readonly onSettlement?: (
+    call: SettledPiToolCall,
+  ) => void | Promise<void>;
+}
+
+/** 描述一次已进入持久化结算边界的 Pi 工具调用。 */
+export interface SettledPiToolCall {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly args: unknown;
+  readonly result: AgentToolResult<unknown>;
+  readonly isError: boolean;
+  /** Diagnostic-only original error; callers must not persist or expose it. */
+  readonly cause?: unknown;
+  readonly summary?: string;
+  readonly source?: ApprovalReceipt["source"];
+}