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

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

@@ -19,7 +19,6 @@ import {
   type PiLoadedExtension,
 } from "../assembly";
 import {
-  compilePiTools,
   createPiMcpToolCandidates,
   listExtensionsPiToolCandidate,
   type PiMcpHost,
@@ -41,7 +40,7 @@ import {
 interface PiAssemblySnapshot {
   readonly pi: Pick<
     PiRuntimeAssembly,
-    "extensions" | "toolCandidates"
+    "extensions" | "toolSurface"
   >;
   readonly profile: Pick<
     RuntimeProfile,
@@ -75,10 +74,7 @@ interface PreparedPiAssembly {
   readonly loaded: readonly PiLoadedExtension[];
   readonly context: readonly PiExtensionContextContribution[];
   readonly degradations: PiExtensionAssembly["degradations"];
-  // 生成当前可供 Pi 编译的完整工具候选列表。
-  // preparePiAssembly 用它预检，preparePiRuntime 再读取并冻结最终列表。
-  // MCP 就绪状态由 Host 提供，因此这里不能只拼接初始化时的静态数组。
-  toolCandidates(): PiToolCandidate[];
+  readonly candidates: readonly PiToolCandidate[];
 }
 
 /**
@@ -164,7 +160,7 @@ export interface PinnedPiRuntime {
  * @remarks
  * `PreparedPiTurnAdapter` 在重建 Turn 前读取这个 JSON 结构。
  *
- * 版本号和基础版本校验用于阻止恢复落到不兼容的 Runtime 状态。
+ * 基础版本作为准入时元数据保留，创建 Turn 时不与当前 Runtime 比较。
  */
 export interface PinnedPiRuntimeDescriptor {
   readonly version: 1;
@@ -204,6 +200,8 @@ const IDEMPOTENT_TOOL_NAMES = new Set([
   "browser_markdown",
   "browser_scrape",
   "bind_resource",
+  "delete",
+  "edit",
   "find",
   "get_time",
   "grep",
@@ -215,6 +213,7 @@ const IDEMPOTENT_TOOL_NAMES = new Set([
   "read_skill_resource",
   "sandbox_process_logs",
   "web_search",
+  "write",
   "unbind_resource",
 ]);
 
@@ -255,7 +254,7 @@ function describeTools(candidates: readonly PiToolCandidate[]) {
 
 // 把本模块认定会影响版本的准备结果序列化出来。
 // preparePiRuntime 创建一次，Runtime 接受快照前再对结果求哈希。
-// 集合排序保证等价输入稳定；增删字段会改变版本哈希和恢复兼容性。
+// 集合排序保证等价输入稳定；增删字段会改变版本哈希。
 function describeRuntime(
   snapshot: RuntimeSnapshot,
   candidates: readonly PiToolCandidate[],
@@ -338,18 +337,17 @@ export function readPreparedPiRuntime(
 }
 
 /**
- * 校验已存的固定描述是否仍与当前准备好的 Runtime 兼容。
+ * 读取已存的固定描述。
  *
  * @remarks
  * `PreparedPiTurnAdapter` 在新建或恢复 Pi Turn 前调用它。
  *
- * 只有固定阶段写入的提示词允许不同，其余准备字段及基础版本必须匹配。
+ * Prepared Runtime 提供当前执行能力，descriptor 仅保留 Submission 固定的 Turn 字段。
  */
 export function readPinnedPiRuntime(
   prepared: PreparedPiRuntime,
   owner: object,
   descriptorBody: string,
-  baseRevision: string,
 ): {
   readonly state: PreparedPiRuntimeState;
   readonly descriptor: PinnedPiRuntimeDescriptor;
@@ -365,24 +363,11 @@ export function readPinnedPiRuntime(
     throw new Error("Pinned Runtime assembly descriptor is invalid");
   }
   const descriptor = value as PinnedPiRuntimeDescriptor;
-  const expected = JSON.parse(prepared.revisionDescriptor) as Record<
-    string,
-    unknown
-  >;
-  const actual = descriptor as unknown as Record<string, unknown>;
-  const incompatible = Object.keys(expected).some((key) =>
-    key !== "systemPrompt" &&
-    JSON.stringify(actual[key]) !== JSON.stringify(expected[key])
-  );
   if (
     descriptor.version !== 1 ||
-    descriptor.baseRevision !== baseRevision ||
-    typeof descriptor.systemPrompt !== "string" ||
-    incompatible
+    typeof descriptor.systemPrompt !== "string"
   ) {
-    throw new Error(
-      "Pinned Runtime revision is unavailable for Pi recovery",
-    );
+    throw new Error("Pinned Runtime assembly descriptor is invalid");
   }
   return { state, descriptor };
 }
@@ -391,54 +376,7 @@ export function readPinnedPiRuntime(
 
 // #region 扩展与工具装配
 
-class PreparedAssembly implements PreparedPiAssembly {
-  // 把准备快照、已加载扩展和 MCP Host 放在一个装配对象里。
-  // preparePiAssembly 在扩展加载完成后构造它。
-  // 这里保留源对象而不复制列表，让每个访问器都读取同一份结果。
-  constructor(
-    private readonly snapshot: PiAssemblySnapshot,
-    private readonly extensions: PiExtensionAssembly,
-    private readonly mcpHost: PiMcpHost,
-  ) {}
-
-  // 返回成功加载的扩展。
-  // preparePiRuntime 在生成版本描述时读取这个列表。
-  // 直接代理扩展装配，避免维护可能漂移的第二份列表。
-  get loaded(): readonly PiLoadedExtension[] {
-    return this.extensions.loaded;
-  }
-
-  // 返回已加载扩展声明的上下文贡献。
-  // pinPiRuntime 在提交准入时把它们交给系统上下文装配器。
-  // 上下文值在固定阶段才读取，所以不能提前写死在准备阶段的提示词中。
-  get context(): readonly PiExtensionContextContribution[] {
-    return this.extensions.context;
-  }
-
-  // 返回准备阶段被降级处理、而不是继续抛出的扩展失败。
-  // preparePiRuntime 把它们与快照降级合并，用于报告 Runtime 加载结果。
-  // 直接代理可保留扩展装配器生成的原始降级记录。
-  get degradations(): PiExtensionAssembly["degradations"] {
-    return this.extensions.degradations;
-  }
-
-  // 汇总内置、扩展列表、扩展和当前已就绪的 MCP 工具。
-  // 准备流程先调用它做校验，再冻结一份列表供后续 Turn 使用。
-  // 每次重新生成是因为 MCP 候选来自 Host 当前的连接状态。
-  toolCandidates(): PiToolCandidate[] {
-    return [
-      ...this.snapshot.pi.toolCandidates,
-      ...this.extensions.candidates,
-      listExtensionsPiToolCandidate(this.extensions.loaded),
-      ...createPiMcpToolCandidates(
-        this.mcpHost,
-        this.snapshot.profile.mcpServers,
-      ),
-    ];
-  }
-}
-
-// 加载已启用扩展，并确认汇总后的工具可以正常编译。
+// 加载已启用扩展，并把 Extension/MCP 候选交给唯一 Tool Surface 最终化。
 // preparePiRuntime 为每份待配置的 Runtime 快照调用它一次。
 // 工作区能力在共享加载边界校验，单个扩展加载失败则保留为降级结果。
 async function preparePiAssembly(
@@ -469,18 +407,19 @@ async function preparePiAssembly(
       });
     },
   });
-  const prepared = new PreparedAssembly(
-    snapshot,
-    extensions,
-    options.mcpHost,
-  );
-  // 待确认：MCP 就绪状态可能在下一次 toolCandidates() 前改变，
-  // 因而最终冻结的候选可能与这里校验的集合不同。
-  compilePiTools(prepared.toolCandidates(), {
-    deny: snapshot.profile.denyPolicy?.deny,
-    settle: () => undefined,
+  return Object.freeze({
+    loaded: extensions.loaded,
+    context: extensions.context,
+    degradations: extensions.degradations,
+    candidates: snapshot.pi.toolSurface.finalize([
+      ...extensions.candidates,
+      listExtensionsPiToolCandidate(extensions.loaded),
+      ...createPiMcpToolCandidates(
+        options.mcpHost,
+        snapshot.profile.mcpServers,
+      ),
+    ]),
   });
-  return prepared;
 }
 
 // #endregion
@@ -500,7 +439,7 @@ export async function preparePiRuntime(
   owner: object,
 ): Promise<PreparedPiRuntime> {
   const assembly = await preparePiAssembly(options);
-  const candidates = assembly.toolCandidates();
+  const candidates = assembly.candidates;
   return Object.freeze(new PreparedRuntime(
     describeRuntime(options.snapshot, candidates, assembly.loaded),
     Object.freeze([

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

@@ -9,17 +9,21 @@ import {
 import type {
   Api,
   AssistantMessage,
+  Message,
   Model,
   Models,
   ToolResultMessage,
   UserMessage,
 } from "@earendil-works/pi-ai";
+import { transformMessages } from "@earendil-works/pi-ai/api/transform-messages";
 import { requiresPiToolApproval, parkPiToolApproval } from "../turn";
 import { PiChunkEncoder } from "../message";
 import type { UIMessageChunk } from "ai";
+import { ChatStreamStalledError } from "agents/chat";
 import {
   compilePiTools,
   createPiToolGovernance,
+  normalizeUpdatePlanArguments,
   type PiToolCandidate,
   type PiToolGovernance,
   type PiToolTelemetry,
@@ -30,10 +34,28 @@ import {
   readPinnedPiRuntime,
   type PreparedPiRuntime,
 } from "./assembly";
-import { resolvePiApiKey, withProviderRetry } from "./models";
+import {
+  isRecoverableAssistantError,
+  isModelStreamStallMessage,
+  resolvePiApiKey,
+  withProviderRetry,
+} from "./models";
 
 // #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 +92,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 +109,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 +145,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 +160,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 +195,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 +250,7 @@ class PiTurnAdapter {
         pi.abort();
       }
       await running;
+      return reachedModelTurnLimit;
     } finally {
       signal?.removeEventListener("abort", abort);
       unsubscribe();
@@ -288,7 +336,6 @@ export interface PiTurnDurability {
  */
 export interface CreatePreparedPiTurnOptions {
   readonly prepared: PreparedPiRuntime;
-  readonly baseRevision: string;
   readonly pinnedDescriptor: string;
   readonly submission: {
     readonly id: string;
@@ -391,6 +438,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 +463,6 @@ export class PreparedPiTurnAdapter {
       options.prepared,
       dependencies.owner,
       options.pinnedDescriptor,
-      options.baseRevision,
     );
     this.assistantOrdinal = options.submission.assistantOrdinal;
     this.encoder = new PiChunkEncoder({
@@ -523,8 +570,8 @@ 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,
       onToolTelemetry: options.onToolTelemetry,
       transformContext: options.transformContext,
@@ -544,6 +591,7 @@ export class PreparedPiTurnAdapter {
    * 转交给 PiTurnAdapter 可保留启动前取消标记；run() 之前还没有可直接调用的 PiCore。
    */
   abort(): void {
+    this.abortController.abort();
     this.turn.abort();
   }
 
@@ -582,6 +630,7 @@ export class PreparedPiTurnAdapter {
           candidate,
           request.toolCallId,
           request.input,
+          this.abortController.signal,
         )
       : false;
   }
@@ -597,7 +646,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 +654,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 +669,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 +729,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,18 @@ 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";
+export {
+  MODEL_STREAM_STALL_TIMEOUT_MS,
+  readModelStreamStallDetails,
+  withProviderRetry,
+} from "./models";
 import {
   pinPiRuntime,
   preparePiRuntime,
@@ -148,7 +153,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 +192,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(