@springbrand/agent-runtime 0.2.0-alpha.71 → 0.3.0-alpha.1

package/src/{pi/tool → tools}/base.ts

@@ -9,10 +9,10 @@ import {
   type TSchema,
 } from "@earendil-works/pi-ai";
 import { estimateStringTokens } from "agents/experimental/memory/utils";
-import type { RuntimeMemoryPort } from "../../kernel/bindings";
-import type { RuntimeMemoryProfile } from "../../kernel/profile";
-import { serializeOutput } from "../../lib/artifacts";
-import { modelAttachmentText } from "../message/conversion";
+import type { RuntimeMemoryPort } from "../config/ports";
+import type { RuntimeMemoryProfile } from "../config/profile";
+import { serializeOutput } from "../lib/artifacts";
+import { modelAttachmentText } from "../conversation/message/conversion";
 import type { PiToolCandidate } from "./compiler";
 import { webSearchPiToolCandidate } from "./web-search";
 import type { WebSearch } from "./web-search/api";
@@ -88,10 +88,7 @@ function recordOf(value: unknown): Record<string, unknown> | null {
     : null;
 }
 
-function questionsOf(
-  value: unknown,
-  allowLegacy = false,
-): AskUserInput["questions"] | null {
+function questionsOf(value: unknown): AskUserInput["questions"] | null {
   const questions = recordOf(value)?.questions;
   if (!Array.isArray(questions) || questions.length < 1 || questions.length > 10) {
     return null;
@@ -103,6 +100,10 @@ function questionsOf(
     if (!question || typeof question.question !== "string" || !question.question) {
       return null;
     }
+    if (Object.keys(question).some((key) =>
+      key !== "question" && key !== "responseType" && key !== "options" &&
+      key !== "allowCustom" && key !== "required"
+    )) return null;
     if (
       question.required !== undefined && typeof question.required !== "boolean"
     ) return null;
@@ -114,18 +115,7 @@ function questionsOf(
         responseType as typeof askUserResponseTypes[number],
       )
     ) {
-      if (!allowLegacy || question.responseType !== undefined) return null;
-      if (question.kind === "attachment") {
-        responseType = "attachment";
-      } else if (question.kind === undefined) {
-        responseType = Array.isArray(question.options)
-          ? question.multiSelect === true
-            ? "multi_select"
-            : "single_select"
-          : "text";
-      } else {
-        return null;
-      }
+      return null;
     }
     const normalizedQuestion = {
       question: question.question,
@@ -137,8 +127,7 @@ function questionsOf(
       if (
         attachmentQuestions > 1 ||
         question.options !== undefined ||
-        question.allowCustom !== undefined ||
-        (!allowLegacy && question.multiSelect !== undefined)
+        question.allowCustom !== undefined
       ) return null;
       normalized.push(normalizedQuestion);
       continue;
@@ -146,8 +135,7 @@ function questionsOf(
     if (responseType === "text") {
       if (
         question.options !== undefined ||
-        (!allowLegacy &&
-          (question.allowCustom !== undefined || question.multiSelect !== undefined))
+        question.allowCustom !== undefined
       ) {
         return null;
       }
@@ -165,10 +153,6 @@ function questionsOf(
       (question.allowCustom !== undefined &&
         typeof question.allowCustom !== "boolean")
     ) return null;
-    if (
-      !allowLegacy &&
-      (question.kind !== undefined || question.multiSelect !== undefined)
-    ) return null;
     normalized.push({
       ...normalizedQuestion,
       options: question.options,
@@ -199,7 +183,7 @@ function prepareAskUserArguments(input: unknown): AskUserInput {
 // 手写校验而不是拉 TypeBox compiler：这里只需要判真假，
 // 且校验位于 Worker 响应信任边界，不应为每次回答编译 schema。
 function isAskUserResponse(input: unknown, value: unknown): boolean {
-  const questions = questionsOf(input, true);
+  const questions = questionsOf(input);
   const answers = recordOf(value)?.answers;
   if (!questions || !Array.isArray(answers) || answers.length !== questions.length) {
     return false;
@@ -400,7 +384,7 @@ export function basePiToolCandidates(
       interaction: {
         validateResponse: isAskUserResponse,
         settle: (input, response) => {
-          const questions = questionsOf(input, true)!;
+          const questions = questionsOf(input)!;
           const responseAnswers = (response as AskUserResponse).answers;
           const answers = questions.map((question, index) => {
             const answer = responseAnswers[index]!;

package/src/tools/compiler.ts

@@ -0,0 +1,327 @@
+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"];
+}
+
+// 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
+
+// 把任意失败值收敛为可安全显示的简短消息。
+// 受治理工具在工具执行或结算抛错时调用它。
+// 读取错误自身也可能抛错，因此最外层必须保留固定回退文本。
+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 durableResult(
+  result: AgentToolResult<unknown>,
+  candidate: PiToolCandidate,
+  workspace: SpillWorkspace | undefined,
+): Promise<AgentToolResult<unknown>> {
+  const spill = (candidate.outputBudget ?? { kind: "spill" }).kind === "spill";
+  let ref = spill
+    ? await spillDurableToolOutput(spillPayload(result), { workspace })
+    : null;
+  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);
+  }
+}
+
+// #endregion
+
+// #region Governance and compilation
+
+/**
+ * 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;
+        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 {
+          result = await untilAborted(
+            signal,
+            async () => durableResult(
+              await 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,
+          });
+          throw cause instanceof Error && cause.message === message
+            ? cause
+            : new Error(message, { cause });
+        }
+        await options.onSettlement?.({
+          toolCallId,
+          toolName: source.name,
+          args,
+          result,
+          isError: false,
+          summary: candidate.summary,
+          source: candidate.source,
+        });
+        return result;
+      },
+    } satisfies AgentHarnessTool<object | undefined>;
+  });
+}
+
+// #endregion

package/src/{pi/tool → tools}/core-host.ts

@@ -21,14 +21,14 @@ import type {
   RuntimeBrowserPort,
   RuntimeCodeExecutionPort,
   WorkspacePort,
-} from "../../kernel/bindings";
+} from "../config/ports";
 import {
   WorkspaceStateConnector,
   WORKSPACE_PAGING_INSTRUCTIONS,
   WORKSPACE_STATE_TYPES,
 } from "./workspace-state-connector";
-import type { RuntimeCodeExecutionFactory } from "../../kernel/bindings";
-import { serializeOutput } from "../../lib/artifacts";
+import type { RuntimeCodeExecutionFactory } from "../config/ports";
+import { serializeOutput } from "../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
 import { piCandidatesToAiTools } from "./nested-tools";
 

package/src/{pi/tool → tools}/core.ts

@@ -5,9 +5,9 @@ import type {
 import { Type } from "@earendil-works/pi-ai";
 import type {
   RuntimeCodeExecutionPort,
-} from "../../kernel/bindings";
-import { serializeOutput } from "../../lib/artifacts";
-import type { PiLoadedExtension } from "../assembly/extensions";
+} from "../config/ports";
+import { serializeOutput } from "../lib/artifacts";
+import type { PiLoadedExtension } from "../context/extension/assembly";
 import type { PiToolCandidate } from "./compiler";
 
 // 本文件沿用 `../../index.ts` 入口定义的 Extension、Port 和 Tool Candidate 术语。

package/src/tools/decision-gate.ts

@@ -0,0 +1,227 @@
+import type {
+  AgentToolResult,
+  HookHandler,
+} from "@earendil-works/pi-agent-core";
+import type { ExecutionLevel } from "../lib/execution-level";
+import {
+  EXECUTION_LEVELS,
+  requiresExecutionApproval,
+} from "../lib/execution-level";
+import type { PiToolCandidate } from "./compiler";
+import type { ApprovalRepository } from "./approval";
+import type { ToolInteractionRepository } from "./interaction";
+import type { RuntimeTelemetryCoordinator } from "../telemetry/coordinator";
+
+export interface HarnessDecisionSubmission {
+  readonly submissionId: string;
+  readonly requestId: string;
+  readonly executionLevel: ExecutionLevel;
+}
+
+export interface HarnessDecisionGateOptions {
+  readonly submission: HarnessDecisionSubmission;
+  readonly candidates: readonly PiToolCandidate[];
+  readonly approvals: ApprovalRepository;
+  readonly interactions: ToolInteractionRepository;
+  readonly transaction: <T>(run: () => T) => T;
+  readonly release: (reason: "approval" | "interaction") => void;
+  readonly telemetry?: Pick<RuntimeTelemetryCoordinator, "capture">;
+  readonly onChanged?: (
+    kind: "approval" | "interaction",
+    id: string,
+  ) => void | Promise<void>;
+  readonly gateTool?: (input: {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly input: unknown;
+    readonly requiredExecutionLevel: ExecutionLevel;
+    readonly signal: AbortSignal;
+  }) => void | Promise<void>;
+}
+
+function waitForRelease(signal: AbortSignal): Promise<never> {
+  return new Promise((_resolve, reject) => {
+    const abort = () => {
+      signal.removeEventListener("abort", abort);
+      reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+    };
+    if (signal.aborted) return abort();
+    signal.addEventListener("abort", abort, { once: true });
+  });
+}
+
+function operationSignal(signal: AbortSignal | undefined): AbortSignal {
+  if (!signal) throw new Error("Harness Tool hook has no operation signal");
+  return signal;
+}
+
+function stableInput(input: unknown): string {
+  return JSON.stringify(input);
+}
+
+function interactionResult(
+  response: unknown,
+): AgentToolResult<unknown> {
+  return {
+    content: [{ type: "text", text: JSON.stringify(response) }],
+    details: response,
+  };
+}
+
+/** Durable policy facts around Pi's before_tool hook; Pi owns execution state. */
+export class HarnessDecisionGate {
+  private readonly candidates: ReadonlyMap<string, PiToolCandidate>;
+
+  constructor(private readonly options: HarnessDecisionGateOptions) {
+    this.candidates = new Map(
+      options.candidates.map((candidate) => [candidate.tool.name, candidate]),
+    );
+  }
+
+  readonly beforeTool: HookHandler<"before_tool"> = async (event, context) => {
+    const candidate = this.candidates.get(event.toolName);
+    if (!candidate) return undefined;
+    const requiredExecutionLevel = candidate.requiredExecutionLevelForInput
+      ? await candidate.requiredExecutionLevelForInput(event.args)
+      : candidate.requiredExecutionLevel;
+    if (!EXECUTION_LEVELS.includes(requiredExecutionLevel)) {
+      throw new Error(
+        `SpringBrand Tool "${event.toolName}" resolved an invalid execution level`,
+      );
+    }
+    const executionId = `${this.options.submission.submissionId}:${event.toolCallId}`;
+    const existing = this.options.approvals.find(executionId);
+    if (existing?.status === "rejected") {
+      return { block: { reason: existing.reason ?? "Tool execution denied by user" } };
+    }
+    const needsApproval = candidate.alwaysRequiresApproval ||
+      requiresExecutionApproval(
+        this.options.submission.executionLevel,
+        requiredExecutionLevel,
+      );
+    if (needsApproval && existing?.status !== "approved") {
+      if (existing && (
+        existing.requestId !== this.options.submission.requestId ||
+        existing.toolName !== event.toolName ||
+        existing.inputJson !== stableInput(event.args)
+      )) {
+        throw new Error(`Conflicting durable Tool approval: ${event.toolCallId}`);
+      }
+      if (!existing) {
+        const createdAt = Date.now();
+        this.options.transaction(() => this.options.approvals.insert({
+          executionId,
+          submissionId: this.options.submission.submissionId,
+          requestId: this.options.submission.requestId,
+          source: candidate.source ?? "action",
+          toolCallId: event.toolCallId,
+          toolName: event.toolName,
+          summary: candidate.summary ?? candidate.tool.label ?? event.toolName,
+          executionLevel: this.options.submission.executionLevel,
+          requiredExecutionLevel,
+          inputJson: stableInput(event.args),
+          status: "pending",
+          createdAt,
+        }));
+        this.options.telemetry?.capture("approvalRequested", {
+          submissionId: this.options.submission.submissionId,
+          toolCallId: event.toolCallId,
+          executionId,
+          toolName: event.toolName,
+          summary: candidate.summary ?? candidate.tool.label ?? event.toolName,
+          input: event.args,
+          occurredAt: createdAt,
+        });
+        await this.options.onChanged?.("approval", executionId);
+      }
+      this.options.release("approval");
+      return waitForRelease(operationSignal(context.abortSignal));
+    }
+
+    if (!candidate.interaction) return undefined;
+    const interaction = this.options.interactions.find(executionId);
+    if (interaction?.status === "responded" || interaction?.status === "cancelled") {
+      return undefined;
+    }
+    if (interaction && (
+      interaction.requestId !== this.options.submission.requestId ||
+      interaction.toolName !== event.toolName ||
+      interaction.inputJson !== stableInput(event.args)
+    )) {
+      throw new Error(`Conflicting durable Tool interaction: ${event.toolCallId}`);
+    }
+    if (!interaction) {
+      const createdAt = Date.now();
+      this.options.transaction(() => this.options.interactions.insert({
+        interactionId: executionId,
+        submissionId: this.options.submission.submissionId,
+        requestId: this.options.submission.requestId,
+        toolCallId: event.toolCallId,
+        toolName: event.toolName,
+        inputJson: stableInput(event.args),
+        status: "pending",
+        createdAt,
+      }));
+      this.options.telemetry?.capture("interactionRequested", {
+        submissionId: this.options.submission.submissionId,
+        toolCallId: event.toolCallId,
+        interactionId: executionId,
+        toolName: event.toolName,
+        input: event.args,
+        occurredAt: createdAt,
+      });
+      await this.options.onChanged?.("interaction", executionId);
+    }
+    this.options.release("interaction");
+    return waitForRelease(operationSignal(context.abortSignal));
+  };
+
+  async authorize(
+    candidate: PiToolCandidate,
+    args: unknown,
+    invocation: { readonly toolCallId: string; readonly signal: AbortSignal },
+  ): Promise<void> {
+    const requiredExecutionLevel = candidate.requiredExecutionLevelForInput
+      ? await candidate.requiredExecutionLevelForInput(args)
+      : candidate.requiredExecutionLevel;
+    await this.options.gateTool?.({
+      toolCallId: invocation.toolCallId,
+      toolName: candidate.tool.name,
+      input: args,
+      requiredExecutionLevel,
+      signal: invocation.signal,
+    });
+  }
+
+  resolveReplay(
+    candidate: PiToolCandidate,
+    toolCallId: string,
+    args: unknown,
+  ): AgentToolResult<unknown> | undefined {
+    if (!candidate.interaction) return undefined;
+    const interaction = this.options.interactions.find(
+      `${this.options.submission.submissionId}:${toolCallId}`,
+    );
+    if (!interaction || interaction.status === "pending") return undefined;
+    if (interaction.inputJson !== stableInput(args)) {
+      throw new Error(`Conflicting durable Tool interaction: ${toolCallId}`);
+    }
+    if (interaction.status === "cancelled") {
+      return {
+        content: [{
+          type: "text",
+          text: "The interaction was cancelled before the user answered.",
+        }],
+        details: { cancelled: true },
+      };
+    }
+    const response = JSON.parse(interaction.responseJson ?? "null");
+    if (!candidate.interaction.validateResponse(args, response)) {
+      throw new Error(`Stored Tool interaction response is invalid: ${toolCallId}`);
+    }
+    const settled = candidate.interaction.settle?.(args, response);
+    return settled
+      ? { ...settled, terminate: false }
+      : interactionResult(response);
+  }
+}