@springbrand/agent-runtime 0.1.3-alpha.3 → 0.1.3-alpha.4

package/src/pi/runtime-adapter/assembly.ts

@@ -1,5 +1,6 @@
 import type {
   RuntimeBindings,
+  RuntimeGatewaySession,
   RuntimePlatformPort,
 } from "../../kernel/bindings";
 import type { RuntimeDegradation } from "../../kernel/degradation";
@@ -8,7 +9,7 @@ import type {
 } from "../../kernel/extensions";
 import type { RuntimeProfile } from "../../kernel/profile";
 import type { ExecutionLevel } from "../../lib/execution-level";
-import type { RuntimeSnapshot } from "../../plugins";
+import type { RuntimeSnapshot } from "../../runtime-assembler";
 import type { PiRuntimeAssembly } from "../assembly";
 import {
   assemblePiSystemContext,
@@ -19,6 +20,7 @@ import {
   type PiLoadedExtension,
 } from "../assembly";
 import {
+  createPiGatewayToolCandidates,
   createPiMcpToolCandidates,
   listExtensionsPiToolCandidate,
   type PiMcpHost,
@@ -58,6 +60,7 @@ interface PiAssemblySnapshot {
 interface PreparePiAssemblyOptions {
   readonly snapshot: PiAssemblySnapshot;
   readonly mcpHost: PiMcpHost;
+  readonly gatewaySession?: RuntimeGatewaySession;
   // 为一个扩展生成带权限参数的 Host Fetcher。
   // loadPiExtension 在扩展需要 Host 能力时调用它。
   // Worker 掌握真实绑定，装配层只保存这个窄函数，不能自行扩大权限。
@@ -90,6 +93,8 @@ interface PreparedPiAssembly {
 export interface PreparePiRuntimeOptions {
   readonly snapshot: RuntimeSnapshot;
   readonly mcpHost: PiMcpHost;
+  readonly gatewaySession?: RuntimeGatewaySession;
+  readonly additionalDegradations?: readonly RuntimeDegradation[];
   /**
    * 为一个扩展创建受限的 Host 绑定。
    *
@@ -115,6 +120,7 @@ export interface PreparePiRuntimeOptions {
 export interface PreparedPiRuntime {
   readonly revisionDescriptor: string;
   readonly degradations: readonly RuntimeDegradation[];
+  readonly extensions: readonly { readonly name: string; readonly version: string }[];
 }
 
 /**
@@ -301,6 +307,7 @@ class PreparedRuntime implements PreparedPiRuntime {
   constructor(
     readonly revisionDescriptor: string,
     readonly degradations: readonly RuntimeDegradation[],
+    readonly extensions: readonly { readonly name: string; readonly version: string }[],
     private readonly owner: object,
     private readonly state: PreparedPiRuntimeState,
   ) {}
@@ -414,6 +421,9 @@ async function preparePiAssembly(
     candidates: snapshot.pi.toolSurface.finalize([
       ...extensions.candidates,
       listExtensionsPiToolCandidate(extensions.loaded),
+      ...(options.gatewaySession
+        ? createPiGatewayToolCandidates(options.gatewaySession)
+        : []),
       ...createPiMcpToolCandidates(
         options.mcpHost,
         snapshot.profile.mcpServers,
@@ -444,8 +454,10 @@ export async function preparePiRuntime(
     describeRuntime(options.snapshot, candidates, assembly.loaded),
     Object.freeze([
       ...options.snapshot.degradations,
+      ...(options.additionalDegradations ?? []),
       ...assembly.degradations,
     ]),
+    Object.freeze(assembly.loaded.map(({ name, version }) => ({ name, version }))),
     owner,
     Object.freeze({
       snapshot: options.snapshot,

package/src/pi/runtime-adapter/execution.ts

@@ -16,7 +16,11 @@ import type {
   UserMessage,
 } from "@earendil-works/pi-ai";
 import { transformMessages } from "@earendil-works/pi-ai/api/transform-messages";
-import { requiresPiToolApproval, parkPiToolApproval } from "../turn";
+import {
+  parkPiToolApproval,
+  parkPiToolInteraction,
+  requiresPiToolApproval,
+} from "../turn";
 import { PiChunkEncoder } from "../message";
 import type { UIMessageChunk } from "ai";
 import { ChatStreamStalledError } from "agents/chat";
@@ -25,6 +29,7 @@ import {
   createPiToolGovernance,
   normalizeUpdatePlanArguments,
   type PiToolCandidate,
+  type PiToolInteractionSpec,
   type PiToolGovernance,
   type PiToolTelemetry,
   type SettledPiToolCall,
@@ -40,6 +45,7 @@ import {
   resolvePiApiKey,
   withProviderRetry,
 } from "./models";
+import { EXECUTION_LEVELS } from "../../lib/execution-level";
 
 // #region Single-run Pi bridge
 
@@ -308,6 +314,18 @@ export interface PiTurnDurability {
     signal?: AbortSignal,
     onCreated?: () => void | Promise<void>,
   ): Promise<void>;
+  /**
+   * 保存一次客户端结算请求并等待响应。
+   *
+   * @remarks
+   * Tool candidate 声明了 `interaction` 时，PreparedPiTurnAdapter 在执行前调用它，`execute` 不会被调用。
+   * 返回后必须再读一次 settlement —— 响应、取消和跨休眠恢复三条路径都只把结果留在 settlement 里。
+   */
+  requestToolInteraction(
+    interaction: import("../turn").PiToolInteraction,
+    settle: import("../tool").PiToolInteractionSpec,
+    signal?: AbortSignal,
+  ): Promise<void>;
   /**
    * 记录工具输入，并返回它是否是第一次持久化尝试。
    *
@@ -475,13 +493,21 @@ export class PreparedPiTurnAdapter {
         ...candidate.tool,
         // 只在 Runtime 的持久化和策略门禁都放行后执行一个 Tool candidate。
         // 实时运行由 PiCore 调用它，恢复或审批续跑则由 retryTool 进入同一路径。
-        // 顺序不能随便调整：已有结果优先，审批可能生成结果，不确定的非幂等工作不能重放。
+        // 顺序不能随便调整：门禁先于结果复用，审批可能生成结果，不确定的非幂等工作不能重放。
         execute: async (toolCallId, input, signal, onUpdate) => {
+          const requiredExecutionLevel = candidate.requiredExecutionLevelForInput
+            ? await candidate.requiredExecutionLevelForInput(input)
+            : candidate.requiredExecutionLevel;
+          if (!EXECUTION_LEVELS.includes(requiredExecutionLevel)) {
+            throw new Error(
+              `Pi Tool "${candidate.tool.name}" resolved an invalid execution level`,
+            );
+          }
           await state.snapshot.bindings.platform.gateTool?.({
             toolCallId,
             toolName: candidate.tool.name,
             input,
-            requiredExecutionLevel: candidate.requiredExecutionLevel,
+            requiredExecutionLevel,
             signal: signal ?? new AbortController().signal,
           });
           const settled = options.durability.findToolSettlement(toolCallId);
@@ -494,10 +520,13 @@ export class PreparedPiTurnAdapter {
             }
             return settled.result;
           }
-          if (requiresPiToolApproval({
-            executionLevel: descriptor.executionLevel,
-            requiredExecutionLevel: candidate.requiredExecutionLevel,
-          })) {
+          if (
+            candidate.alwaysRequiresApproval ||
+            requiresPiToolApproval({
+              executionLevel: descriptor.executionLevel,
+              requiredExecutionLevel,
+            })
+          ) {
             const approval = parkPiToolApproval({
               executionId: `${options.submission.id}:${toolCallId}`,
               requestId: options.submission.requestId,
@@ -509,7 +538,7 @@ export class PreparedPiTurnAdapter {
                 candidate.tool.label ??
                 candidate.tool.name,
               executionLevel: descriptor.executionLevel,
-              requiredExecutionLevel: candidate.requiredExecutionLevel,
+              requiredExecutionLevel,
               inputJson: JSON.stringify(input),
               createdAt: Date.now(),
             }).approval;
@@ -539,6 +568,43 @@ export class PreparedPiTurnAdapter {
           const afterApproval = options.durability
             .findToolSettlement(toolCallId);
           if (afterApproval) return afterApproval.result;
+          // 结果由客户端提供的 Tool 在这里 park，永远不走到下面的 execute。
+          // 放在审批之后：一个 Tool 既要审批又要客户端结算时，先过许可再问用户，
+          // 否则会先向用户要答案、再告诉他这事根本不许做。
+          if (candidate.interaction) {
+            // 必须先把 Tool 输入落成里程碑再 park。恢复出来的结算靠这条记录取回
+            // `args`;缺了它,Tool 醒来返回结果时 settleTool 会拿 undefined 的 args
+            // 去和真 args 比对,判成 "Conflicting durable Tool settlement" —— 整个
+            // Turn 就死在这。(审批那条路不受影响:批准后 Tool 真的执行,args 在
+            // 下面的 appendToolInput 里补上了。)
+            options.durability.appendToolInput({
+              toolCallId,
+              toolName: candidate.tool.name,
+              input,
+              retry: piToolRetryPolicy(candidate),
+            });
+            const parked = parkPiToolInteraction({
+              interactionId: `${options.submission.id}:${toolCallId}`,
+              requestId: options.submission.requestId,
+              toolCallId,
+              toolName: candidate.tool.name,
+              inputJson: JSON.stringify(input),
+              createdAt: Date.now(),
+            }).interaction;
+            await options.durability.requestToolInteraction(
+              parked,
+              candidate.interaction,
+              signal,
+            );
+            const responded = options.durability
+              .findToolSettlement(toolCallId);
+            if (!responded) {
+              throw new Error(
+                `Tool interaction produced no durable settlement: ${candidate.tool.name}`,
+              );
+            }
+            return responded.result;
+          }
           const retry = piToolRetryPolicy(candidate);
           const firstAttempt = options.durability.appendToolInput({
             toolCallId,
@@ -572,7 +638,11 @@ export class PreparedPiTurnAdapter {
       ),
       modelSessionId: options.submission.requestId,
       canonicalMessages: options.canonicalMessages,
-      settle: options.durability.settleTool,
+      // 被中断的 Turn 不写结算。它退场路上还会吐出「工具被中止」，而工具其实
+      // 没有产生任何结果 —— 结算是单调的，落了这条假结果，重建出来的续跑会
+      // 把一个从没跑过的工具当成跑过并失败。取消不走这里：取消要的就是终态。
+      settle: (call) =>
+        this.interrupted ? undefined : options.durability.settleTool(call),
       onToolTelemetry: options.onToolTelemetry,
       transformContext: options.transformContext,
     });
@@ -582,6 +652,7 @@ export class PreparedPiTurnAdapter {
 
   private readonly systemPrompt: string;
   private readonly options: CreatePreparedPiTurnOptions;
+  private interrupted = false;
 
   /**
    * 请求取消这个 Turn。
@@ -595,6 +666,20 @@ export class PreparedPiTurnAdapter {
     this.turn.abort();
   }
 
+  /**
+   * 中断这个 Turn，把它交给持久续跑接手。
+   *
+   * @remarks
+   * 宿主在 park 期间换掉装配后调用。与 `abort` 的差别只有一处、但很要命：
+   * 中断途中冒出来的工具结算一律丢弃。这条执行器的系统提示和工具表锁在它被
+   * 创建的那一刻，接下来跑的是另一条按新装配重建的执行器，两边共用同一批
+   * `toolCallId` —— 让退场路上的假结果先落盘，新那条就再也纠正不过来了。
+   */
+  interrupt(): void {
+    this.interrupted = true;
+    this.abort();
+  }
+
   /**
    * 把一条用户消息加入当前 Turn。
    *
@@ -635,6 +720,21 @@ export class PreparedPiTurnAdapter {
       : false;
   }
 
+  /**
+   * 取回某个 Tool 的客户端结算声明，没有声明时返回 null。
+   *
+   * @remarks
+   * `Runtime.respondToolInteraction` 在把客户端响应映射成 ToolResult 前调用它。
+   *
+   * 声明里含函数，无法持久化；从 Pinned Runtime 的 candidate 现取，
+   * 可让「DO 一直醒着」和「park 期间睡过一觉」走同一条解析路径，而不是一条真解析、一条退化成缺省。
+   */
+  interactionSpec(toolName: string): PiToolInteractionSpec | null {
+    return this.candidates.find(
+      (item) => item.tool.name === toolName,
+    )?.interaction ?? null;
+  }
+
   /**
    * 运行这个 Turn，直到 PiCore 和所有等待中的事件回调结束。
    *

package/src/pi/runtime-adapter/index.ts

@@ -8,7 +8,7 @@ import {
 } from "../message";
 import type { UIMessage } from "ai";
 import { createModels, type MutableModels } from "@earendil-works/pi-ai";
-import { configurePiModels, resolvePiApiKey } from "./models";
+import { configurePiModels, createPiModels, resolvePiApiKey } from "./models";
 export {
   MODEL_STREAM_STALL_TIMEOUT_MS,
   modelRequestUrl,
@@ -129,6 +129,9 @@ export class PiRuntimeAdapter {
   prepare(
     options: PreparePiRuntimeOptions,
   ): Promise<PreparedPiRuntime> {
+    if (this.managesModels) {
+      createPiModels(options.snapshot.bindings.provider);
+    }
     return preparePiRuntime(options, this.owner);
   }
 
@@ -138,8 +141,7 @@ export class PiRuntimeAdapter {
    * @remarks
    * 调用方：Runtime 的 `initConfig()` 在 Prepared Runtime 和 revision 检查成功后、发布新快照前调用。
    *
-   * 实现理由：激活会校验并注册所有 endpoint 中声明的模型，而不只校验当前选中的模型。
-   * 这解释了为什么一个未被选中的无效模型也会让配置启动失败；不要把激活误当成首次推理请求。
+   * 实现理由：`prepare()` 已校验所有 endpoint 模型，这里只把同一份部署目录切换到长期 Models 实例。
    * 注入模型目录时跳过此步骤，以保留调用方对目录的配置权。
    */
   activate(snapshot: PreparePiRuntimeOptions["snapshot"]): void {
@@ -210,6 +212,10 @@ export type {
   UIChatRequestBody,
 } from "../message";
 export type { PiToolApproval } from "../turn";
+export type {
+  PiToolInteraction,
+  PiToolInteractionCancelReason,
+} from "../turn";
 export type {
   CreatePreparedPiTurnOptions,
   PiCanonicalUserInput,

package/src/pi/runtime-adapter/recovery.ts

@@ -1,11 +1,15 @@
 import {
   applyRecoveredPiApprovalDecision,
+  applyRecoveredPiToolInteractionSettlement,
   commitPiRecoveryContinuation,
   encodePiToolRecoveryMilestone,
   planPiToolRecovery,
   replayPiToolRecovery,
+  stagePiAssemblyRepin,
   stagePiRecoveryContinuation,
   type PiToolApproval,
+  type PiToolInteraction,
+  type PiToolInteractionCancelReason,
   type PiToolRecoveryMilestone,
   type PiToolRecoveryPlan,
   type PiToolRecoveryState,
@@ -55,6 +59,32 @@ export type PiRecoveryCommand =
       readonly kind: "record-approval";
       readonly approval: PiToolApproval;
     }
+  | {
+      readonly kind: "record-interaction";
+      readonly interaction: PiToolInteraction;
+    }
+  /** 停在人机等待期间换了装配：记下这次被承认的身份迁移。 */
+  | {
+      readonly kind: "repin-assembly";
+      readonly nextAssemblyRevision: string;
+    }
+  | {
+      readonly kind: "interaction-settlement";
+      readonly interactionId: string;
+      readonly settlement:
+        | {
+            readonly kind: "respond";
+            readonly response: unknown;
+            readonly result: {
+              readonly content: ToolResultMessage["content"];
+              readonly details: unknown;
+            };
+          }
+        | {
+            readonly kind: "cancel";
+            readonly reason: PiToolInteractionCancelReason;
+          };
+    }
   | {
       readonly kind: "record-tool-result";
       readonly toolCallId: string;
@@ -109,6 +139,17 @@ export type PiDurableMutation =
       readonly status: "approved" | "rejected";
       readonly decidedAt: number;
       readonly reason?: string;
+    }
+  | {
+      readonly kind: "record-interaction";
+      readonly interaction: PiToolInteraction;
+    }
+  | {
+      readonly kind: "settle-interaction";
+      readonly interactionId: string;
+      readonly status: "responded" | "cancelled";
+      readonly settledAt: number;
+      readonly responseJson?: string;
     };
 
 export type PiRecoveryEffect =
@@ -131,7 +172,11 @@ export type PiRecoveryEffect =
     }
   | {
       readonly kind: "wait";
-      readonly reason?: "approval" | "uncertain-tool" | "complete";
+      readonly reason?:
+        | "approval"
+        | "interaction"
+        | "uncertain-tool"
+        | "complete";
     }
   | { readonly kind: "resume-turn" };
 
@@ -198,6 +243,31 @@ function approvalExecutionId(continuationKey: string): string | null {
   return match?.[1] ?? null;
 }
 
+// 把 Tool 自己的 settle 映射产出的内容包成一条权威 ToolResult。
+// interaction-settlement 命令处理 respond 分支时调用它。
+// 记录必须已经存在 —— 拿不到 toolCallId/toolName 就无法把结果绑回原调用，这时失败关闭而不是编一个 id。
+function interactionToolResult(
+  interaction: PiToolInteraction | undefined,
+  result: {
+    readonly content: ToolResultMessage["content"];
+    readonly details: unknown;
+  },
+  timestamp: number,
+): ToolResultMessage {
+  if (!interaction) {
+    throw new Error("Pi Tool interaction is missing for its response");
+  }
+  return {
+    role: "toolResult",
+    toolCallId: interaction.toolCallId,
+    toolName: interaction.toolName,
+    content: result.content,
+    details: result.details,
+    isError: false,
+    timestamp,
+  };
+}
+
 // 把纯恢复计划翻译成持久化操作和 Runtime 下一步动作。
 // decidePiRecovery 在命令应用并重放最新状态后调用它。
 // pending 续跑必须先形成里程碑并重放，再允许 dispatch，避免外部动作早于可恢复状态落盘。
@@ -223,6 +293,11 @@ function fromPlan(
         mutations: [],
         effect: { kind: "wait", reason: "approval" },
       };
+    case "parked-interaction":
+      return {
+        mutations: [],
+        effect: { kind: "wait", reason: "interaction" },
+      };
     case "park-uncertain-tool":
       return {
         mutations: [],
@@ -425,6 +500,112 @@ export function decidePiRecovery(
       applied = true;
     }
   }
+  if (input.command.kind === "repin-assembly") {
+    const milestone = stagePiAssemblyRepin(
+      state,
+      input.command.nextAssemblyRevision,
+      input.now,
+    );
+    if (milestone) {
+      const mutation = milestoneMutation(
+        `assembly-repin:${input.command.nextAssemblyRevision}`,
+        milestone,
+      );
+      mutations.push(mutation);
+      bodies = [...bodies, mutation.body];
+      state = replayPiToolRecovery(bodies);
+      applied = true;
+    }
+  }
+  if (input.command.kind === "record-interaction") {
+    const interaction = input.command.interaction;
+    const existing = state.interactions[interaction.interactionId];
+    if (existing) {
+      // 同一个 interactionId 必须描述同一次 Tool 调用，否则重放会把响应投给错的调用。
+      // 口径与 record-approval 的冲突检查一致。
+      if (
+        existing.requestId !== interaction.requestId ||
+        existing.toolCallId !== interaction.toolCallId ||
+        existing.toolName !== interaction.toolName ||
+        existing.inputJson !== interaction.inputJson
+      ) {
+        throw new Error(
+          `Conflicting Pi Tool interaction: ${interaction.interactionId}`,
+        );
+      }
+    } else {
+      const mutation = milestoneMutation(
+        `interaction:${interaction.interactionId}:${interaction.status}`,
+        {
+          ...recoveryIdentity(input),
+          type: "interaction",
+          interaction,
+        },
+      );
+      mutations.push(
+        { kind: "record-interaction", interaction },
+        mutation,
+      );
+      bodies = [...bodies, mutation.body];
+      state = replayPiToolRecovery(bodies);
+      applied = true;
+    }
+  }
+  if (input.command.kind === "interaction-settlement") {
+    const command = input.command;
+    const settlement = applyRecoveredPiToolInteractionSettlement(
+      state,
+      command.settlement.kind === "respond"
+        ? {
+            interactionId: command.interactionId,
+            kind: "respond",
+            response: command.settlement.response,
+            toolResult: interactionToolResult(
+              state.interactions[command.interactionId],
+              command.settlement.result,
+              input.now,
+            ),
+            settledAt: input.now,
+          }
+        : {
+            interactionId: command.interactionId,
+            kind: "cancel",
+            reason: command.settlement.reason,
+            settledAt: input.now,
+          },
+    );
+    applied = settlement.outcome.kind !== "noop";
+    if (applied) {
+      const record = settlement.milestones.find(
+        (milestone) => milestone.type === "interaction",
+      );
+      if (!record || record.type !== "interaction") {
+        throw new Error("Pi interaction settlement milestone is missing");
+      }
+      mutations.push({
+        kind: "settle-interaction",
+        interactionId: record.interaction.interactionId,
+        status: record.interaction.status as "responded" | "cancelled",
+        settledAt: record.interaction.respondedAt ?? input.now,
+        ...(record.interaction.responseJson === undefined
+          ? {}
+          : { responseJson: record.interaction.responseJson }),
+      });
+      settlement.milestones.forEach((milestone, index) => {
+        mutations.push(milestoneMutation(
+          milestone.type === "interaction"
+            ? `interaction:${command.interactionId}:${record.interaction.status}`
+            : `interaction-result:${command.interactionId}:${index}`,
+          milestone,
+        ));
+      });
+      bodies = [
+        ...bodies,
+        ...settlement.milestones.map(encodePiToolRecoveryMilestone),
+      ];
+      state = replayPiToolRecovery(bodies);
+    }
+  }
   if (input.command.kind === "record-tool-result") {
     const command = input.command;
     const toolResult: ToolResultMessage = {
@@ -649,6 +830,12 @@ export class PiRuntimeRecoveryAdapter
           reason: "Pi Turn is waiting for Tool approval",
         } as const;
       }
+      if (decision.effect.reason === "interaction") {
+        return {
+          kind: "park",
+          reason: "Pi Turn is waiting for a client Tool interaction response",
+        } as const;
+      }
       if (decision.effect.reason === "uncertain-tool") {
         return {
           kind: "park",

package/src/pi/tool/base.ts

@@ -26,6 +26,34 @@ const askUserParameters = Type.Object({
   })),
 });
 
+/**
+ * `ask_user` 的客户端响应体。
+ *
+ * `selections` 是选中的选项原文（多选时多于一项），`text` 是可选的补充说明。
+ * 刻意用结构化数组而不是拼好的字符串 —— 选项本身可能含分隔符，拼了再拆是有损的。
+ */
+const askUserResponse = Type.Object({
+  selections: Type.Array(Type.String()),
+  text: Type.Optional(Type.String()),
+});
+
+// 手写校验而不是拉 TypeBox 的 compiler：这里只需要判真假，
+// 且校验必须在 Worker 冷启动路径上零成本。
+function isAskUserResponse(value: unknown): boolean {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value as Record<string, unknown>;
+  if (!Array.isArray(record.selections)) return false;
+  if (!record.selections.every((item) => typeof item === "string")) {
+    return false;
+  }
+  if (record.text !== undefined && typeof record.text !== "string") {
+    return false;
+  }
+  // 什么都没选、也没写字，等于没回答 —— 不该被当成一次有效结算。
+  return record.selections.length > 0 ||
+    (typeof record.text === "string" && record.text.trim().length > 0);
+}
+
 const suggestFollowupsParameters = Type.Object({
   items: Type.Array(Type.String({
     description: "A follow-up the user could ask next, phrased as a request.",
@@ -124,16 +152,41 @@ export function basePiToolCandidates(
   webSearch?: WebSearch,
 ): PiToolCandidate[] {
   return [
-    candidate({
-      name: "ask_user",
-      label: "Ask user",
-      description:
-        "Ask the user to choose among a small set of options. Call this tool whenever you need the user to make a choice from limited options — do NOT write plain text like 'please pick A / B / C'. After calling this tool, end your turn and wait for the user's reply.",
-      parameters: askUserParameters,
-      async execute() {
-        return result({ asked: true });
+    // ask_user 是 client-settled tool：它没有 execute，结果由用户点选后经
+    // respondToolInteraction 投递回来。工具调用会一直 park 到那时候。
+    {
+      ...candidate({
+        name: "ask_user",
+        label: "Ask user",
+        description:
+          "Ask the user to choose among a small set of options. Call this tool whenever you need the user to make a choice from limited options — do NOT write plain text like 'please pick A / B / C'. The user's choice comes back to you as this tool's result, so just continue once you have it. Do NOT end your turn after calling this tool.",
+        parameters: askUserParameters,
+        // 永远不会被调用：执行链在 interaction 闸就 park 住了。留一个失败关闭的
+        // 实现，是为了万一哪次改动绕过了那道闸，能立刻炸出来而不是静默返回空答案。
+        async execute() {
+          throw new Error(
+            "ask_user is client-settled and must not execute on the server",
+          );
+        },
+      }),
+      interaction: {
+        validateResponse: isAskUserResponse,
+        settle: (_input, response) => {
+          const answer = response as Static<typeof askUserResponse>;
+          const parts = [
+            ...answer.selections,
+            ...(answer.text?.trim() ? [answer.text.trim()] : []),
+          ];
+          return {
+            content: [{
+              type: "text",
+              text: `The user answered: ${parts.join(" / ")}`,
+            }],
+            details: answer,
+          };
+        },
       },
-    }),
+    },
     candidate({
       name: "suggest_followups",
       label: "Suggest follow-ups",