@springbrand/agent-runtime 0.2.0-alpha.72 → 0.3.0-alpha.10

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

@@ -1,6 +1,6 @@
-import type { RuntimeMcpServer } from "../../kernel/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/runtime/approval/index.ts

@@ -0,0 +1 @@
+export * from "./repository";

package/src/{db/approval.repo.ts → tools/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;
 }
 
@@ -55,11 +57,6 @@ export interface ApprovalView {
   status: ApprovalStatus;
 }
 
-export interface DecidedApprovalRef {
-  executionId: string;
-  submissionId: string;
-}
-
 type ApprovalRow = {
   execution_id: string;
   submission_id: string;
@@ -71,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 和映射。
@@ -94,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,
@@ -101,22 +98,20 @@ function mapRow(row: ApprovalRow): StoredApproval {
   };
 }
 
-// #endregion
-// #region Repository
 export class ApprovalRepository {
   // 保存当前 Agent SQLite 的查询入口。
-  // RuntimeDatabase 构造时调用，ApprovalLifecycle 和 Transcript 随后共享这个 Repository。
+  // RuntimeDatabase 构造时调用，HarnessDecisionGate 和 Transcript 随后共享这个 Repository。
   // Approval 必须与所属 Submission 在同一 Agent 存储中查询，不能跨 Durable Object 拼接状态。
-  constructor(private readonly sql: SqlTaggedTemplate) {}
+  constructor(private readonly sql: SqlTaggedTemplate) { }
 
   // 按 executionId 读取一条完整 Approval，不存在时返回 null。
-  // ApprovalLifecycle 在请求去重、决策、继续和拒绝时调用，调用方必须处理 null。
+  // HarnessDecisionGate 在请求去重、决策、继续和拒绝时调用，调用方必须处理 null。
   // execution_id 是主键，LIMIT 1 明确只消费一行；不能改成按非唯一字段随意取首行。
   find(executionId: string): StoredApproval | null {
     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}
@@ -126,14 +121,14 @@ export class ApprovalRepository {
   }
 
   // 持久化一条新的 Approval。
-  // ApprovalLifecycle.ensurePending 在准入事务内确认没有同一记录后调用。
+  // HarnessDecisionGate 在 `before_tool` 事务内确认没有同一记录后调用。
   // 主键和 submission_id/tool_call_id 唯一约束是持久化去重防线，不能用覆盖式 INSERT 掩盖冲突审批。
   insert(approval: NewApproval): void {
     this.sql`
       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},
@@ -146,6 +141,7 @@ export class ApprovalRepository {
         ${approval.executionLevel},
         ${approval.requiredExecutionLevel},
         ${approval.inputJson},
+        ${approval.confirmationJson ?? null},
         ${approval.status},
         ${approval.createdAt}
       )
@@ -153,7 +149,7 @@ export class ApprovalRepository {
   }
 
   // 只把 pending Approval 写成指定决策，并记录时间和原因。
-  // applyPiRecoveryMutations 在处理用户决策或恢复命令时调用，迟到的重复决策不应覆盖首次结果。
+  // Runtime 处理用户决策时调用，迟到的重复决策不应覆盖首次结果。
   // WHERE status='pending' 实现首次决策胜出，不能去掉这个条件；调用方在事务后重读来确认是否真的生效。
   decide(
     executionId: string,
@@ -172,7 +168,7 @@ export class ApprovalRepository {
   }
 
   // 按创建顺序列出某次 Submission 仍待决策的 executionId。
-  // ApprovalLifecycle.rejectPending 在终止 Turn 时调用，随后为每条待决策记录追加拒绝恢复事实。
+  // Runtime 终止 Turn 时调用，保证没有待决策记录泊留在终态 Submission 上。
   // ORDER BY created_at 保留决策的原始顺序，不能依赖 SQLite 未声明的默认行顺序。
   listPendingForSubmission(submissionId: string): string[] {
     return this.sql<{ execution_id: string }>`
@@ -185,7 +181,7 @@ export class ApprovalRepository {
   }
 
   // 列出所属 Submission 仍活跃的全部待决策 Approval 摘要。
-  // ApprovalLifecycle.list 和广播流程在生成用户可见审批列表时调用。
+  // Runtime 广播流程在生成用户可见审批列表时调用。
   // JOIN Submission 是为了隐藏已终止 Turn 的孤立 pending 行，不能只按 Approval 自身状态暴露给用户。
   listPendingActive(): PendingApprovalSummary[] {
     return this.sql<{
@@ -197,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
@@ -217,28 +214,13 @@ 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,
     }));
   }
 
-  // 按决策时间列出所有已批准或已拒绝的 Approval 引用。
-  // ApprovalLifecycle.dispatchPendingContinuations 在 Runtime 启动时调用，用恢复决策判断哪些记录仍需要继续。
-  // 这里故意不预先猜测“已分派”，幂等性由 Recovery Milestone 决定；不能用内存队列替代跨重启扫描。
-  listDecided(): DecidedApprovalRef[] {
-    return this.sql<{ execution_id: string; submission_id: string }>`
-      SELECT execution_id, submission_id
-      FROM pi_approvals
-      WHERE status IN ('approved', 'rejected')
-      ORDER BY decided_at ASC
-    `.map((row) => ({
-      executionId: row.execution_id,
-      submissionId: row.submission_id,
-    }));
-  }
-
   // 计算所属 Submission 仍活跃的 pending Approval 数量。
-  // ApprovalLifecycle.countPending 在报告交互阻塞和 Runtime 稳定状态时调用。
+  // Runtime 在报告交互阻塞和稳定状态时调用。
   // 与 listPendingActive 使用同样的 JOIN 和状态条件才能保证计数和用户可见列表一致，修改其一时必须核对另一个。
   countPendingActive(): number {
     return (
@@ -254,7 +236,7 @@ export class ApprovalRepository {
   }
 
   // 只在某个 toolCallId 唯一匹配一条活跃 pending Approval 时返回 executionId。
-  // Runtime 处理工具审批决策时通过 ApprovalLifecycle 调用，返回 null 表示没有或存在歧义。
+  // Runtime 处理工具审批决策时通过 HarnessDecisionGate 调用，返回 null 表示没有或存在歧义。
   // toolCallId 只在单个 Submission 内唯一，LIMIT 2 用最小查询识别跨 Submission 重名；不能用 LIMIT 1 静默选中任意 Approval。
   findPendingByToolCallId(toolCallId: string): string | null {
     const matches = this.sql<{ execution_id: string }>`
@@ -274,7 +256,7 @@ export class ApprovalRepository {
 
   // 列出某次 Submission 的审批 ID、工具调用 ID 和状态。
   // Transcript 投影浏览器消息时调用，用这些精简字段补齐工具调用视图。
-  // 这里不返回风险、输入等内容，避免 Transcript 和 ApprovalLifecycle 共享过宽的数据契约。
+  // 这里不返回风险、输入等内容，避免 Transcript 和 HarnessDecisionGate 共享过宽的数据契约。
   listApprovalViews(submissionId: string): ApprovalView[] {
     return this.sql<{
       execution_id: string;
@@ -291,4 +273,3 @@ export class ApprovalRepository {
     }));
   }
 }
-// #endregion

package/src/tools/runtime/compiler.ts

@@ -0,0 +1,264 @@
+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;
+
+
+
+// 把任意失败值收敛为可安全显示的简短消息。
+// 受治理工具在工具执行或结算抛错时调用它。
+// 读取错误自身也可能抛错，因此最外层必须保留固定回退文本。
+function errorMessage(error: unknown): string {
+  try {
+    if (error instanceof Error) {
+      return error.message || error.name;
+    }
+    return String(error);
+  } catch {
+    return "Tool execution failed";
+  }
+}
+
+// Most Pi adapters keep the original Tool value in details and its serialized
+// model form in one text block. Spill that original once instead of duplicating
+// it inside an AgentToolResult JSON envelope.
+function spillPayload(result: AgentToolResult<unknown>): unknown {
+  const text = result.content.length === 1 && result.content[0]?.type === "text"
+    ? result.content[0].text
+    : undefined;
+  if (text !== undefined && serializeOutput(result.details).text === text) {
+    return result.details;
+  }
+  return result;
+}
+
+function artifactResult(
+  result: AgentToolResult<unknown>,
+  ref: ArtifactRef,
+): AgentToolResult<unknown> {
+  const presentation = result.details !== null && typeof result.details === "object"
+    ? (result.details as Record<string, unknown>).presentation
+    : undefined;
+  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 }] : [];
+    })
+    : [];
+  return {
+    ...result,
+    content: [{
+      type: "text",
+      text: [
+        ref.note,
+        `Path: ${ref.path}`,
+        `Bytes: ${ref.bytes}`,
+        `Preview:\n${ref.preview}`,
+      ].join("\n"),
+    }, ...mediaContent],
+    details: presentation === undefined ? ref : { ...ref, presentation },
+  };
+}
+
+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>;
+  const bytes = new TextEncoder().encode(JSON.stringify(bounded)).byteLength;
+  if (bytes <= DURABLE_TOOL_RESULT_MAX_BYTES) return bounded;
+
+  // Binary blocks cannot be truncated, and this boundary has no image resizer.
+  // Preserve the original where possible and fail before any SQLite write.
+  if (!spill) ref = await spillDurableToolOutput(spillPayload(result), { workspace });
+  throw new Error(
+    `Tool output exceeds the 1 MiB durable result limit (${bytes} bytes). ` +
+    "Return a smaller result, such as lower-resolution images or fewer media items; the original cannot be included inline. " +
+    (ref ? `Original output saved to Workspace: ${ref.path}` : "The original output could not be saved to Workspace."),
+  );
+}
+
+async function untilAborted<T>(
+  signal: AbortSignal | undefined,
+  run: () => T | Promise<T>,
+): Promise<T> {
+  // ponytail: 这会立即释放 Turn，但无法杀死不配合的进程内副作用；需要物理终止的 Tool 必须放进可销毁的隔离执行器。
+  signal?.throwIfAborted();
+  if (!signal) return run();
+  let onAbort!: () => void;
+  const aborted = new Promise<never>((_resolve, reject) => {
+    onAbort = () => reject(
+      signal.reason ?? new DOMException("Aborted", "AbortError"),
+    );
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    return await Promise.race([run(), aborted]);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+}
+
+
+
+/**
+ * Convert the configured candidate surface once at the AgentHarness boundary.
+ * Schema, argument preparation, progress, cancellation, replay classification,
+ * and output bounds stay attached to the original Tool declaration.
+ */
+export function compileHarnessTools(
+  candidates: readonly PiToolCandidate[],
+  options: CompileHarnessToolsOptions = {},
+): AgentHarnessTool<object | undefined>[] {
+  return candidates.map((candidate) => {
+    const source = candidate.tool;
+    const tool = source.constrainedSampling === false
+      ? source
+      : {
+        ...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
+        ? "safe" as const
+        : "never" as const,
+      ...(candidate.deferLoading ? { deferLoading: true as const } : {}),
+      async execute(
+        toolCallId,
+        args,
+        onUpdate,
+        _toolContext,
+        _invocation,
+        context,
+      ) {
+        const signal = context.abortSignal ?? new AbortController().signal;
+        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 (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,
+            ),
+          );
+        } catch (cause) {
+          const message = errorMessage(cause);
+          const failed = boundDurableToolOutput({
+            content: [{ type: "text", text: message }],
+            details: {},
+          }) as AgentToolResult<unknown>;
+          await options.onSettlement?.({
+            toolCallId,
+            toolName: source.name,
+            args,
+            result: failed,
+            isError: true,
+            cause,
+            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 });
+        }
+        await options.onSettlement?.({
+          toolCallId,
+          toolName: source.name,
+          args,
+          result,
+          isError: result.details !== null &&
+            typeof result.details === "object" &&
+            (result.details as { availability?: unknown }).availability ===
+              "unavailable",
+          summary: candidate.summary,
+          source: candidate.source,
+        });
+        return result;
+      },
+    } satisfies AgentHarnessTool<object | undefined>;
+  });
+}

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"];
+}