@springbrand/agent-runtime 0.3.0-alpha.2 → 0.3.0-alpha.21

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/runtime/activation.ts

@@ -0,0 +1,40 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { PiToolCandidate } from "./contracts";
+
+/**
+ * 把 Candidate 上的按需激活声明收成 SessionHarness 可直接消费的选项。
+ *
+ * `inactiveUntilActivated` 的工具仍编译进 Harness，只是一开始不在活动集里。
+ * 其他工具成功返回后通过 `toolsToActivate` 点名，Harness 在 `after_tool`
+ * 里 `setActiveTools`，由 Pi Agent Loop 写成 transcript 的 `toolsAdded`。
+ */
+export function harnessToolActivation(candidates: readonly PiToolCandidate[]): {
+  readonly activeToolNames: string[];
+  readonly onDemandToolNames: readonly string[];
+  readonly toolsToActivate: (
+    toolName: string,
+    result: AgentToolResult<unknown>,
+    isError: boolean,
+  ) => readonly string[];
+} {
+  const compiled = candidates.map(({ tool }) => tool.name);
+  const onDemand = candidates
+    .filter((candidate) => candidate.inactiveUntilActivated === true)
+    .map(({ tool }) => tool.name);
+  const onDemandSet = new Set(onDemand);
+  const activators = new Map(
+    candidates.flatMap((candidate) =>
+      candidate.toolsToActivate
+        ? [[candidate.tool.name, candidate.toolsToActivate] as const]
+        : [],
+    ),
+  );
+  return {
+    activeToolNames: compiled.filter((name) => !onDemandSet.has(name)),
+    onDemandToolNames: onDemand,
+    toolsToActivate: (toolName, result, isError) => {
+      if (isError) return [];
+      return activators.get(toolName)?.(result) ?? [];
+    },
+  };
+}

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/runtime/compiler.ts

@@ -0,0 +1,246 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ToolRegistration } from "@earendil-works/pi-durable";
+import { awaitWithContext } from "@earendil-works/chord/context";
+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."),
+  );
+}
+
+/**
+ * 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 = {},
+): ToolRegistration<any, any>[] {
+  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
+        : "unsafe" as const,
+      ...(candidate.deferLoading ? { deferLoading: true as const } : {}),
+      async execute(args, api, context) {
+        const toolCallId = api.callId;
+        // AgentTool progress is a replacing snapshot (web_search sends its accumulated text), but Pi output only
+        // appends and has no replace operation: append a grown snapshot's suffix, and start a new line otherwise.
+        let shown = "";
+        const onUpdate = (update: AgentToolResult<unknown>) => {
+          const text = update.content.flatMap((part) => part.type === "text" ? [part.text] : []).join("");
+          if (text && text !== shown) {
+            api.output(text.startsWith(shown) ? text.slice(shown.length) : shown ? `\n${text}` : text);
+            shown = text;
+          }
+          if (update.details !== undefined) void api.details(update.details, context).catch(() => {});
+        };
+        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);
+          signal.throwIfAborted();
+          const execution = 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));
+          result = await awaitWithContext(
+            Promise.resolve(execution).then((result) => durableResult(result, candidate, options.workspace)),
+            context,
+          );
+        } 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, isError: true, control: { terminate: true as const } };
+          }
+          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, ...(result.terminate ? { control: { terminate: true as const } } : {}) };
+      },
+    } satisfies ToolRegistration<any, any>;
+  });
+}

package/src/tools/runtime/contracts.ts

@@ -0,0 +1,140 @@
+import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { TSchema } from "@earendil-works/pi-ai";
+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>>;
+}
+
+/**
+ * 一份尚未进入最终 Tool Surface 的 Pi 工具及其治理字段。
+ *
+ * 单个工厂可以写成 `PiToolCandidate<typeof parameters, Details>`，把 Schema 和
+ * details 留在类型里。混进同一个 `PiToolCandidate[]` 时走默认擦除形式：
+ * `AgentTool` 在两个类型参数上都是不变的，只有默认 `any` 能收进异构列表。
+ */
+export interface PiToolCandidate<
+  TParameters extends TSchema = any,
+  TDetails = any,
+> {
+  /** 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<TParameters, TDetails>;
+  /** @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;
+  /**
+   * 编进 Harness 工具表，但不进入初始 `setActiveTools`。
+   * 之后由其他 Tool 的 `toolsToActivate` 经 `setActiveTools` 写入 transcript `toolsAdded`。
+   */
+  readonly inactiveUntilActivated?: true;
+  /**
+   * 本次成功结果要把哪些已编译工具加入活动集。未知名字会被忽略。
+   * 替代已删除的 `AgentToolResult.addedToolNames`。
+   */
+  readonly toolsToActivate?: (
+    result: AgentToolResult<unknown>,
+  ) => readonly string[];
+}
+
+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"];
+}