@springbrand/agent-runtime 0.1.3-alpha.0 → 0.1.3-alpha.10

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

@@ -9,18 +9,27 @@ import {
 import type {
   Api,
   AssistantMessage,
+  Message,
   Model,
   Models,
   ToolResultMessage,
   UserMessage,
 } from "@earendil-works/pi-ai";
-import { requiresPiToolApproval, parkPiToolApproval } from "../turn";
+import { transformMessages } from "@earendil-works/pi-ai/api/transform-messages";
+import {
+  parkPiToolApproval,
+  parkPiToolInteraction,
+  requiresPiToolApproval,
+} from "../turn";
 import { PiChunkEncoder } from "../message";
 import type { UIMessageChunk } from "ai";
+import { ChatStreamStalledError } from "agents/chat";
 import {
   compilePiTools,
   createPiToolGovernance,
+  normalizeUpdatePlanArguments,
   type PiToolCandidate,
+  type PiToolInteractionSpec,
   type PiToolGovernance,
   type PiToolTelemetry,
   type SettledPiToolCall,
@@ -30,10 +39,29 @@ import {
   readPinnedPiRuntime,
   type PreparedPiRuntime,
 } from "./assembly";
-import { resolvePiApiKey, withProviderRetry } from "./models";
+import {
+  isRecoverableAssistantError,
+  isModelStreamStallMessage,
+  resolvePiApiKey,
+  withProviderRetry,
+} from "./models";
+import { EXECUTION_LEVELS } from "../../lib/execution-level";
 
 // #region Single-run Pi bridge
 
+const MAX_MODEL_TURNS = 30;
+
+export class RetryableModelError extends Error {}
+
+function normalizePlanToolCalls(message: AgentMessage): void {
+  if (message.role !== "assistant") return;
+  for (const part of message.content) {
+    if (part.type === "toolCall" && part.name === "update_plan") {
+      part.arguments = normalizeUpdatePlanArguments(part.arguments);
+    }
+  }
+}
+
 /**
  * 把 Pi 的终止原因翻译成本仓的回合结局。
  *
@@ -70,6 +98,16 @@ function classifyPiStopReason(stopReason: string | undefined): {
   }
 }
 
+function visibleAssistantContent(message: AssistantMessage) {
+  return message.content.filter((part) =>
+    part.type === "text"
+      ? part.text.trim()
+      : part.type === "thinking"
+        ? part.thinking.trim()
+        : false
+  );
+}
+
 interface PiTurnAdapterOptions {
   readonly pi: {
     readonly model: Model<Api>;
@@ -77,11 +115,11 @@ interface PiTurnAdapterOptions {
   };
   readonly models: Models;
   readonly apiKey: string;
+  readonly modelSessionId: string;
   // 读取这次执行真正要交给 Pi 的 canonical transcript。
   // PiTurnAdapter.run 在创建 PiCore 前调用它，宿主应返回当时最新的 transcript。
   // 这里保留为延迟读取，是为了避免适配器创建后新增的恢复消息被旧快照漏掉。
   readonly canonicalMessages: () => Promise<readonly AgentMessage[]>;
-  readonly denyTools?: readonly string[];
   // 把工具的最终结果交回宿主持久化。
   // 共享工具编译器在向 Pi 返回成功或规范化失败前调用它。
   // 这个先落库再发布结果的顺序是恢复边界，不能改成事后异步补写。
@@ -113,10 +151,9 @@ class PiTurnAdapter {
 
   // 把 Tool candidate 变成 Pi 可以执行的受治理 Tool。
   // 正常运行会编译 Pinned Runtime 的整份列表，恢复时只编译指定 Tool candidate。
-  // 拒绝规则、重名检查、输出限额和持久化结算统一走共享编译器，避免恢复另开旁路。
+  // 输出限额和持久化结算统一走共享编译器，避免恢复另开旁路。
   private compile(candidates: readonly PiToolCandidate[]) {
     return compilePiTools(candidates, {
-      deny: this.opts.denyTools,
       governance: this.governance,
       settle: this.opts.settle,
     });
@@ -129,10 +166,12 @@ class PiTurnAdapter {
     candidate: PiToolCandidate,
     toolCallId: string,
     input: unknown,
+    signal?: AbortSignal,
   ): Promise<boolean> {
     const [tool] = this.compile([candidate]);
     if (!tool) return false;
-    await tool.execute(toolCallId, input);
+    signal?.throwIfAborted();
+    await tool.execute(toolCallId, input, signal);
     return true;
   }
 
@@ -162,19 +201,33 @@ class PiTurnAdapter {
       readonly signal?: AbortSignal;
     },
     listener: (event: AgentEvent) => void | Promise<void>,
-  ): Promise<void> {
+  ): Promise<boolean> {
     const { systemPrompt, signal } = opts;
     signal?.throwIfAborted();
     const canonicalMessages = await this.opts.canonicalMessages();
     const tools = this.compile(opts.tools);
+    let modelTurns = 0;
+    let reachedModelTurnLimit = false;
     const pi = new PiCore({
       convertToLlm,
       streamFn: withProviderRetry(
         this.opts.models.streamSimple.bind(this.opts.models),
+        0,
+        this.opts.modelSessionId,
       ),
       getApiKey: () => this.opts.apiKey,
-      transformContext: this.opts.transformContext,
+      // transformMessages 在宿主上下文变换之后运行，确保跨 provider 的 tool call ID 格式兼容。
+      // OpenAI Responses API 生成含 `|` 的 450+ 字符 ID，Anthropic 只接受 ^[a-zA-Z0-9_-]+$(64 字符上限)；
+      // 切换 provider 或消息跨 provider 回放时若不规范化，provider 会静默拒绝。
+      transformContext: async (messages, signal) => {
+        const ctx = await this.opts.transformContext(messages, signal);
+        return transformMessages(ctx as Message[], this.opts.pi.model) as AgentMessage[];
+      },
       afterToolCall: this.governance.afterToolCall,
+      shouldStopAfterTurn: () => {
+        reachedModelTurnLimit = ++modelTurns >= MAX_MODEL_TURNS;
+        return signal?.aborted === true || reachedModelTurnLimit;
+      },
       initialState: {
         model: this.opts.pi.model,
         systemPrompt,
@@ -203,6 +256,7 @@ class PiTurnAdapter {
         pi.abort();
       }
       await running;
+      return reachedModelTurnLimit;
     } finally {
       signal?.removeEventListener("abort", abort);
       unsubscribe();
@@ -260,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>;
   /**
    * 记录工具输入，并返回它是否是第一次持久化尝试。
    *
@@ -288,7 +354,6 @@ export interface PiTurnDurability {
  */
 export interface CreatePreparedPiTurnOptions {
   readonly prepared: PreparedPiRuntime;
-  readonly baseRevision: string;
   readonly pinnedDescriptor: string;
   readonly submission: {
     readonly id: string;
@@ -391,6 +456,7 @@ export interface PiPreparedTurnRunOptions {
  */
 export class PreparedPiTurnAdapter {
   private readonly turn: PiTurnAdapter;
+  private readonly abortController = new AbortController();
   private readonly candidates: readonly PiToolCandidate[];
   private assistantOrdinal: number;
   private readonly encoder: PiChunkEncoder;
@@ -415,7 +481,6 @@ export class PreparedPiTurnAdapter {
       options.prepared,
       dependencies.owner,
       options.pinnedDescriptor,
-      options.baseRevision,
     );
     this.assistantOrdinal = options.submission.assistantOrdinal;
     this.encoder = new PiChunkEncoder({
@@ -428,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);
@@ -447,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,
@@ -462,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;
@@ -492,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,
@@ -523,9 +636,13 @@ export class PreparedPiTurnAdapter {
         state.snapshot.bindings.provider,
         state.snapshot.pi.model.id,
       ),
+      modelSessionId: options.submission.requestId,
       canonicalMessages: options.canonicalMessages,
-      denyTools: descriptor.deny,
-      settle: options.durability.settleTool,
+      // 被中断的 Turn 不写结算。它退场路上还会吐出「工具被中止」，而工具其实
+      // 没有产生任何结果 —— 结算是单调的，落了这条假结果，重建出来的续跑会
+      // 把一个从没跑过的工具当成跑过并失败。取消不走这里：取消要的就是终态。
+      settle: (call) =>
+        this.interrupted ? undefined : options.durability.settleTool(call),
       onToolTelemetry: options.onToolTelemetry,
       transformContext: options.transformContext,
     });
@@ -535,6 +652,7 @@ export class PreparedPiTurnAdapter {
 
   private readonly systemPrompt: string;
   private readonly options: CreatePreparedPiTurnOptions;
+  private interrupted = false;
 
   /**
    * 请求取消这个 Turn。
@@ -544,9 +662,24 @@ export class PreparedPiTurnAdapter {
    * 转交给 PiTurnAdapter 可保留启动前取消标记；run() 之前还没有可直接调用的 PiCore。
    */
   abort(): void {
+    this.abortController.abort();
     this.turn.abort();
   }
 
+  /**
+   * 中断这个 Turn，把它交给持久续跑接手。
+   *
+   * @remarks
+   * 宿主在 park 期间换掉装配后调用。与 `abort` 的差别只有一处、但很要命：
+   * 中断途中冒出来的工具结算一律丢弃。这条执行器的系统提示和工具表锁在它被
+   * 创建的那一刻，接下来跑的是另一条按新装配重建的执行器，两边共用同一批
+   * `toolCallId` —— 让退场路上的假结果先落盘，新那条就再也纠正不过来了。
+   */
+  interrupt(): void {
+    this.interrupted = true;
+    this.abort();
+  }
+
   /**
    * 把一条用户消息加入当前 Turn。
    *
@@ -582,10 +715,26 @@ export class PreparedPiTurnAdapter {
           candidate,
           request.toolCallId,
           request.input,
+          this.abortController.signal,
         )
       : 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 和所有等待中的事件回调结束。
    *
@@ -597,7 +746,7 @@ export class PreparedPiTurnAdapter {
     options: PiPreparedTurnRunOptions,
   ): Promise<void> {
     this.terminalIntent = undefined;
-    await this.turn.run(
+    const reachedModelTurnLimit = await this.turn.run(
       {
         systemPrompt: this.systemPrompt,
         tools: this.candidates,
@@ -605,6 +754,12 @@ export class PreparedPiTurnAdapter {
       },
       (event) => this.handleEvent(event),
     );
+    if (reachedModelTurnLimit && !this.terminalIntent) {
+      this.terminalIntent = {
+        outcome: "failed",
+        message: `Pi stopped after ${MAX_MODEL_TURNS} model turns`,
+      };
+    }
     if (this.terminalIntent) {
       await this.options.onTerminal(this.terminalIntent);
     }
@@ -614,9 +769,49 @@ export class PreparedPiTurnAdapter {
   // PiTurnAdapter 会对每个 AgentEvent 调用它，PiCore 会等待该 Promise 后再越过订阅事件屏障。
   // canonical message 先于流投影提交，恢复才不会依赖仅供浏览器消费的记录；调整顺序必须复核 recovery effect。
   private async handleEvent(event: AgentEvent): Promise<void> {
+    if (
+      event.type === "message_start" ||
+      event.type === "message_update" ||
+      event.type === "message_end"
+    ) {
+      normalizePlanToolCalls(event.message);
+    }
+    if (
+      event.type === "message_update" &&
+      event.assistantMessageEvent.type === "error" &&
+      (isModelStreamStallMessage(
+        event.assistantMessageEvent.error.errorMessage,
+      ) ||
+        isRecoverableAssistantError(event.assistantMessageEvent.error))
+    ) {
+      return;
+    }
     let projectedEvent = event;
     if (event.type === "message_end") {
       const message = event.message;
+      if (message.role === "assistant") {
+        const stalled = message.stopReason === "error" &&
+          isModelStreamStallMessage(message.errorMessage);
+        const retryable = isRecoverableAssistantError(message);
+        if (stalled || retryable) {
+          const content = visibleAssistantContent(message);
+          if (content.length > 0) {
+            this.assistantOrdinal += 1;
+            await this.options.onCanonicalMessage({
+              kind: "commit-turn",
+              ordinal: this.assistantOrdinal,
+              message: {
+                ...message,
+                content,
+              },
+            });
+          }
+          if (stalled) {
+            throw new ChatStreamStalledError(message.errorMessage!);
+          }
+          throw new RetryableModelError(message.errorMessage);
+        }
+      }
       if (message.role === "user") {
         await this.options.onCanonicalMessage({
           kind: "append-user",
@@ -634,7 +829,7 @@ export class PreparedPiTurnAdapter {
           abortReason
             ? {
                 ...message,
-                content: [],
+                content: visibleAssistantContent(message),
                 stopReason: "aborted" as const,
                 errorMessage: abortReason,
               }

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

@@ -2,13 +2,19 @@ import {
   PreparedPiTurnAdapter,
   type CreatePreparedPiTurnOptions,
 } from "./execution";
+export { RetryableModelError } from "./execution";
 import {
   uiUserMessageToPi,
 } from "../message";
 import type { UIMessage } from "ai";
 import { createModels, type MutableModels } from "@earendil-works/pi-ai";
-import { configurePiModels, resolvePiApiKey } from "./models";
-export { withProviderRetry } from "./models";
+import { configurePiModels, createPiModels, resolvePiApiKey } from "./models";
+export {
+  MODEL_STREAM_STALL_TIMEOUT_MS,
+  modelRequestUrl,
+  readModelStreamStallDetails,
+  withProviderRetry,
+} from "./models";
 import {
   pinPiRuntime,
   preparePiRuntime,
@@ -101,8 +107,11 @@ export class PiRuntimeAdapter {
    * 实现理由：转换只生成 Pi UserMessage 的 content 和 timestamp，原始浏览器视图由 transcript sidecar 另行保存。
    * 不要把 UI id、metadata 或原始 part 结构并入 canonical message。
    */
-  normalizeUserInput(input: UIMessage & { role: "user" }) {
-    return uiUserMessageToPi(input);
+  normalizeUserInput(
+    input: UIMessage & { role: "user" },
+    privateContext?: string,
+  ) {
+    return uiUserMessageToPi(input, privateContext);
   }
 
   resolveApiKey(
@@ -123,6 +132,9 @@ export class PiRuntimeAdapter {
   prepare(
     options: PreparePiRuntimeOptions,
   ): Promise<PreparedPiRuntime> {
+    if (this.managesModels) {
+      createPiModels(options.snapshot.bindings.provider);
+    }
     return preparePiRuntime(options, this.owner);
   }
 
@@ -132,8 +144,7 @@ export class PiRuntimeAdapter {
    * @remarks
    * 调用方：Runtime 的 `initConfig()` 在 Prepared Runtime 和 revision 检查成功后、发布新快照前调用。
    *
-   * 实现理由：激活会校验并注册所有 endpoint 中声明的模型，而不只校验当前选中的模型。
-   * 这解释了为什么一个未被选中的无效模型也会让配置启动失败；不要把激活误当成首次推理请求。
+   * 实现理由：`prepare()` 已校验所有 endpoint 模型，这里只把同一份部署目录切换到长期 Models 实例。
    * 注入模型目录时跳过此步骤，以保留调用方对目录的配置权。
    */
   activate(snapshot: PreparePiRuntimeOptions["snapshot"]): void {
@@ -148,7 +159,7 @@ export class PiRuntimeAdapter {
    * @remarks
    * 调用方：Runtime 的准入流程为每个新 Submission 调用，并把 descriptor 与其哈希一起持久化。
    *
-   * 实现理由：memory、workspace 和 Extension context 可能随时间变化，恢复必须使用准入时的描述符检查兼容性。
+   * 实现理由：memory、workspace 和 Extension context 可能随时间变化，所以把准入时的 Turn 字段保存在 descriptor 中。
    * 不要把 pin 推迟到 Turn 启动后，否则已持久化的 Submission 将失去可验证的执行基线。
    */
   pin(options: PinPiRuntimeOptions): Promise<PinnedPiRuntime> {
@@ -187,7 +198,7 @@ export class PiRuntimeAdapter {
    * @remarks
    * 调用方：Runtime 在首次执行和恢复继续时各创建一个新 Turn，并提供 canonical messages、durable Tool 回调和流事件回调。
    *
-   * 实现理由：构造时会校验 Prepared Runtime 的 owner、pinned descriptor 和 base revision，再建立本 Turn 独享的 Tool governance 与执行状态。
+   * 实现理由：构造时会校验 Prepared Runtime 的 owner 和 pinned descriptor 格式，再建立本 Turn 独享的 Tool governance 与执行状态。
    * 不要跨 Turn 复用返回对象；abort、steer、assistant ordinal 和 Tool governance 都是单次执行状态。
    */
   createTurn(
@@ -201,9 +212,14 @@ export class PiRuntimeAdapter {
 }
 
 export type {
+  RequestedCapability,
   UIChatRequestBody,
 } from "../message";
 export type { PiToolApproval } from "../turn";
+export type {
+  PiToolInteraction,
+  PiToolInteractionCancelReason,
+} from "../turn";
 export type {
   CreatePreparedPiTurnOptions,
   PiCanonicalUserInput,