@springbrand/agent-runtime 0.2.0-alpha.62 → 0.2.0-alpha.64

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.2.0-alpha.62",
+  "version": "0.2.0-alpha.64",
   "type": "module",
   "files": [
     "src",
@@ -35,6 +35,6 @@
   },
   "devDependencies": {
     "agents": "0.22.0",
-    "ai": "7.0.37"
+    "ai": "7.0.56"
   }
 }

package/src/db/milestone.repo.ts

@@ -33,6 +33,14 @@ export class RecoveryMilestoneRepository {
   // 恢复事实必须与 Submission 位于同一 Agent 存储中，不能用另一个 sql 入口拼接。
   constructor(private readonly sql: SqlTaggedTemplate) {}
 
+  /** The existing unique index makes active Tool writes independent of Turn history size. */
+  findBody(submissionId: string, milestoneKey: string): string | null {
+    return this.sql<{ body: string }>`
+      SELECT body FROM pi_recovery_milestones
+      WHERE submission_id = ${submissionId} AND milestone_key = ${milestoneKey}
+    `[0]?.body ?? null;
+  }
+
   // 按写入顺序返回某次 Submission 的全部恢复内容。
   // Runtime 和 ApprovalLifecycle 在计算下一个恢复决策前调用，调用方直接把结果交给 Pi 恢复器。
   // ORDER BY seq 是重放契约，不能改成 milestoneKey 或无排序查询，否则决策顺序会变。

package/src/kernel/approval-lifecycle.ts

@@ -72,6 +72,7 @@ interface ApprovalLifecycleOptions<
   readonly db: RuntimeDatabase;
   readonly pi: PiRuntimeAdapter;
   readonly findSubmission: (submissionId: string) => TSubmission | null;
+  readonly isSubmissionActive: (submissionId: string) => boolean;
   readonly applyRecoveryMutations: (
     submission: TSubmission,
     mutations: readonly PiDurableMutation[],
@@ -227,11 +228,23 @@ export class ApprovalLifecycle<
       }
       return value;
     });
-    if (pending.created) {
-      await this.options.onApprovalsChanged();
-      await onApproval?.(pending.approval);
+    // Install the waiter before publishing pending state. Otherwise an early
+    // decision can schedule a second executor while this one is still alive.
+    const waiting = this.wait(pending.approval, signal);
+    try {
+      await Promise.all([
+        waiting,
+        (async () => {
+          if (pending.created) {
+            await this.options.onApprovalsChanged();
+            await onApproval?.(pending.approval);
+          }
+        })(),
+      ]);
+    } catch (error) {
+      this.waiters.get(pending.approval.executionId)?.release();
+      throw error;
     }
-    return this.wait(pending.approval, signal);
   }
 
   /**
@@ -362,7 +375,12 @@ export class ApprovalLifecycle<
       return { ok: false };
     }
     if (stored.status !== "pending") {
-      if (!this.waiters.has(stored.executionId)) {
+      // A released waiter does not mean its Tool has finished. Duplicate
+      // decisions must not start recovery alongside the live Submission.
+      if (
+        !this.waiters.has(stored.executionId) &&
+        !this.options.isSubmissionActive(submission.submissionId)
+      ) {
         await this.dispatchContinuation(
           submission,
           stored.executionId,

package/src/kernel/interaction-lifecycle.ts

@@ -144,9 +144,18 @@ export class InteractionLifecycle<
       }
       return value.interaction;
     });
-    // 必须在 wait 之前通知：wait 会一直挂到客户端投递，之后再通知就晚了一个回合。
-    await this.options.onInteractionsChanged?.();
-    return this.wait(pending, signal);
+    // Register synchronously, then publish while waiting for the person. An
+    // early response must release this execution instead of starting recovery.
+    const waiting = this.wait(pending, signal);
+    try {
+      await Promise.all([
+        waiting,
+        (async () => { await this.options.onInteractionsChanged?.(); })(),
+      ]);
+    } catch (error) {
+      this.waiters.get(pending.interactionId)?.();
+      throw error;
+    }
   }
 
   /**

package/src/layers/context/budget/gate.ts

@@ -186,10 +186,21 @@ export async function spillDurableToolOutput(
   }
 }
 
+// Native media is budgeted by the model/provider, not by a text JSON limit.
+// Counting base64 here would discard earlier images even though their bytes cannot be truncated.
+function modelTextSize(value: unknown): number {
+  if (typeof value === "string") return value.length;
+  return JSON.stringify(value, (_key, entry: unknown) =>
+    entry !== null && typeof entry === "object" && isBinaryContentLike(entry)
+      ? "[media]"
+      : entry
+  )?.length ?? 0;
+}
+
 // Bounds leaves first, then removes oldest array entries until the view fits.
 function structureView(output: unknown): unknown {
   const capped = truncateStringLeaves(output, MODEL_LEAF_MAX_CHARS);
-  if (serializeOutput(capped).text.length <= MODEL_REPLAY_THRESHOLD) {
+  if (modelTextSize(capped) <= MODEL_REPLAY_THRESHOLD) {
     return capped;
   }
   if (typeof capped !== "object" || capped === null) return capped;
@@ -204,10 +215,14 @@ function structureView(output: unknown): unknown {
   let dropped = 0;
   while (
     items.length > 1 &&
-    serializeOutput({ ...record, [arrayKey]: items }).text.length >
+    modelTextSize({ ...record, [arrayKey]: items }) >
       MODEL_REPLAY_THRESHOLD
   ) {
-    items.shift();
+    const removable = items.findIndex((item) =>
+      item === null || typeof item !== "object" || !isBinaryContentLike(item)
+    );
+    if (removable < 0) break;
+    items.splice(removable, 1);
     dropped += 1;
   }
   if (dropped === 0) return capped;
@@ -224,7 +239,7 @@ function structureView(output: unknown): unknown {
 /** Creates a non-destructive, smaller Tool-result projection for the model. */
 export function projectToolOutputForModel(output: unknown): unknown {
   try {
-    return serializeOutput(output).text.length <= MODEL_REPLAY_THRESHOLD
+    return modelTextSize(output) <= MODEL_REPLAY_THRESHOLD
       ? output
       : structureView(output);
   } catch {

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

@@ -867,8 +867,8 @@ export class PreparedPiTurnAdapter {
           execute: (toolCallId, input, signal, onUpdate) => {
             const runtimeCandidate = codeExecutionPiToolCandidate(
               factory.create(state.codeExecutionCandidates.map((inner) =>
-                // Code Mode owns replay of its connector calls. Pi persists
-                // only the parent execute attempt/result; recording an inner
+                // Code Mode records its own connector calls. Pi persists the
+                // non-idempotent parent execute attempt/result; recording an inner
                 // input without a Pi settlement creates an orphan recovery
                 // action that cannot be found on the direct Tool surface.
                 bindCandidate(inner, toolCallId, false)

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

@@ -30,6 +30,8 @@ import {
 } from "./assembly";
 import {
   decidePiRecovery,
+  recordPiToolMilestone,
+  type PiToolMilestoneInput,
   PiRuntimeRecoveryAdapter,
   type PiRecoveryHost,
   type PiRecoveryInput,
@@ -180,15 +182,20 @@ export class PiRuntimeAdapter {
    * 根据持久化 milestone 和一个命令算出恢复时要写什么、下一步做什么。
    *
    * @remarks
-   * 调用方：Runtime 和 approval 生命周期在检查状态、记录 Tool 输入结果、处理审批或提交终态时调用。
+   * 调用方：Runtime 和 approval 生命周期在检查恢复状态、处理审批或提交终态时调用。
    *
    * 实现理由：该方法只返回 durable mutations 和一个 effect，实际写库与调度仍由 Runtime 完成。
-   * replay、plan、stage、commit 和 encode 必须保持在同一决策入口，避免宿主与 Pi 各自推导出不同状态。
+   * 恢复规划保留在此入口；正常 Tool 写入复用同一命令 reducer，但不重复规划整个 Turn。
    */
   decideRecovery(options: PiRecoveryInput) {
     return decidePiRecovery(options);
   }
 
+  /** Active execution records only the indexed Tool fact; cold recovery still replays the full log. */
+  recordToolMilestone(options: PiToolMilestoneInput) {
+    return recordPiToolMilestone(options);
+  }
+
   /**
    * 把 Runtime 提供的持久化和重试回调包装成通用聊天恢复端口。
    *

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

@@ -369,15 +369,11 @@ function fromDispatch(
 // #region Recovery decision
 
 /**
- * 重放持久化里程碑，应用一条恢复命令，并算出下一批写入和后续动作。
- *
- * `PiRuntimeAdapter.decideRecovery` 在记录工具、审批、终态、续跑以及启动检查时调用它。
- *
- * 这里保持纯计算并只返回 mutations 和 effect；调用方必须先持久化 mutations，再执行 effect，不能把 I/O 搬进来破坏可重放性。
+ * Apply a durable command using the same validation during execution and recovery.
+ * Active Tool recording supplies only its indexed milestone; recovery supplies
+ * the full log and then plans the next effect. Neither path performs I/O.
  */
-export function decidePiRecovery(
-  input: PiRecoveryInput,
-): PiRecoveryDecision {
+function applyPiRecoveryCommand(input: PiRecoveryInput) {
   let bodies = [...input.milestoneBodies];
   let state = replayPiToolRecovery(bodies);
   const mutations: PiDurableMutation[] = [];
@@ -677,6 +673,22 @@ export function decidePiRecovery(
     applied = true;
   }
 
+  return { state, bodies, mutations, applied };
+}
+
+export interface PiToolMilestoneInput extends PiRecoveryInput {
+  readonly command: Extract<PiRecoveryCommand, {
+    kind: "record-tool-input" | "record-tool-result";
+  }>;
+}
+
+/** Record a single Tool fact without planning a recovery of the active Turn. */
+export function recordPiToolMilestone(input: PiToolMilestoneInput): readonly PiDurableMutation[] {
+  return applyPiRecoveryCommand(input).mutations;
+}
+
+export function decidePiRecovery(input: PiRecoveryInput): PiRecoveryDecision {
+  const { state, bodies, mutations, applied } = applyPiRecoveryCommand(input);
   const planned = fromPlan(
     state,
     planPiToolRecovery(state),

package/src/pi/tool/compiler.ts

@@ -108,6 +108,10 @@ export interface SettledPiToolCall {
 
 const MAX_TOOL_RETRIES = 3;
 const TURN_FAILURE_CEILING = 8;
+// 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;
 
 interface PiToolGovernanceState {
   readonly failures: Map<string, number>;
@@ -177,6 +181,15 @@ function artifactResult(
   result: AgentToolResult<unknown>,
   ref: ArtifactRef,
 ): AgentToolResult<unknown> {
+  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: [{
@@ -187,7 +200,7 @@ function artifactResult(
         `Bytes: ${ref.bytes}`,
         `Preview:\n${ref.preview}`,
       ].join("\n"),
-    }],
+    }, ...mediaContent],
     details: ref,
   };
 }
@@ -197,13 +210,24 @@ async function durableResult(
   candidate: PiToolCandidate,
   workspace: SpillWorkspace | undefined,
 ): Promise<AgentToolResult<unknown>> {
-  if ((candidate.outputBudget ?? { kind: "spill" }).kind === "spill") {
-    const ref = await spillDurableToolOutput(spillPayload(result), {
-      workspace,
-    });
-    if (ref) return artifactResult(result, ref);
-  }
-  return boundDurableToolOutput(result) as 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>(

package/src/pi/tool/core.ts

@@ -246,10 +246,17 @@ function runCodemode(
       }), CODEMODE_EXECUTE_TIMEOUT_MS);
     });
     try {
-      return project(await Promise.race([
+      const output = await Promise.race([
         runtime.execute(input),
         deadline.then(result),
-      ]));
+      ]);
+      const details = output.details as { status?: unknown; error?: unknown } | null;
+      if (details?.status === "error") {
+        throw new Error(typeof details.error === "string"
+          ? details.error
+          : `${label} failed`);
+      }
+      return project(output);
     } finally {
       if (timeout !== undefined) clearTimeout(timeout);
     }
@@ -257,12 +264,12 @@ function runCodemode(
 }
 
 /**
- * 把 Cloudflare Codemode Runtime handle 包装为 Pi 代码执行工具候选项。
+ * 把 Cloudflare Codemode execution port 包装为 Pi 代码执行工具候选项。
  *
  * Tool Surface 收到 Host 已组装的 Code Execution Port 后调用，
  * 模型再通过 `execute` 运行代码。
  *
- * Code Mode 作为一个完整的 safe 工具对外暴露，内部能力不再单独提权。
+ * Code Mode 的外层执行声明为 safe；内部候选仍经过各自的执行档位与审批门禁。
  */
 export function codeExecutionPiToolCandidate(
   runtime: RuntimeCodeExecutionPort,
@@ -273,13 +280,15 @@ export function codeExecutionPiToolCandidate(
     description: runtime.description,
     parameters: executeParameters,
     // Pi 工具循环在模型选择 `execute` 时调用，调用前允许 Turn 取消。
-    // 必须通过 Runtime handle 而不是直接调用 executor，因为 Cloudflare Codemode 把重放、审批和执行日志放在持久化 Runtime 层。
+    // 上游保留 connector 执行日志，但此调用会创建新 execution，不能把它当作旧执行的恢复。
     execute: runCodemode(runtime, "Code Mode execute"),
   };
   return {
     owner: "core:codemode",
     requiredExecutionLevel: "safe",
-    retry: "idempotent",
+    // Each upstream execute starts a new execution ID. A lost parent result
+    // cannot safely replay its already-applied connector or Workspace writes.
+    retry: "non-idempotent",
     outputBudget: { kind: "structure" },
     source: "codemode",
     summary: "Run JavaScript with network and configured connector access",

package/src/pi/tool/workspace-sandbox.ts

@@ -392,9 +392,10 @@ export function workspacePiToolCandidates(
       if (typeof path !== "string") {
         return removeTool.execute(toolCallId, params, signal, onUpdate);
       }
-      return serializeWorkspaceMutation(workspace, path, () =>
-        removeTool.execute(toolCallId, params, signal, onUpdate),
-      );
+      return serializeWorkspaceMutation(workspace, path, () => {
+        signal?.throwIfAborted();
+        return removeTool.execute(toolCallId, params, signal, onUpdate);
+      });
     },
   };
 

package/src/runtime.ts

@@ -248,7 +248,7 @@ type RecoveredTurnPreparation =
 // 原因：终态文本会直接呈现给用户，必须说明发生了什么以及能不能重试。
 function unresumableWaitMessage(reason: string | undefined): string {
   return reason === "uncertain-tool"
-    ? "SpringBrand stopped this turn: a non-idempotent Tool was interrupted and its result cannot be confirmed, so it was not retried. Re-send the request if you want to try again."
+    ? "SpringBrand stopped this turn: a non-idempotent Tool was interrupted and its result cannot be confirmed, so it was not retried. Check whether the external action already happened before sending another request."
     : "SpringBrand could not resume this turn after an interruption.";
 }
 
@@ -600,6 +600,7 @@ export abstract class AgentRuntimeKernel<
       pi: this.pi,
       findSubmission: (submissionId) =>
         this.readSubmission(submissionId),
+      isSubmissionActive: (submissionId) => this.submissions.isActive(submissionId),
       applyRecoveryMutations: (submission, mutations) =>
         this.applyPiRecoveryMutations(submission, mutations),
       materializeRecoveredToolResults: (submission) =>
@@ -2142,6 +2143,27 @@ export abstract class AgentRuntimeKernel<
     });
   }
 
+  private recordPiToolMilestone(
+    submission: StoredSubmission,
+    command: Extract<PiRecoveryCommand, {
+      kind: "record-tool-input" | "record-tool-result";
+    }>,
+  ): readonly PiDurableMutation[] {
+    const key = command.kind === "record-tool-input"
+      ? `tool-input:${command.record.toolCallId}`
+      : `tool-result:${command.toolCallId}`;
+    const body = this.db.milestones.findBody(submission.submissionId, key);
+    return this.pi.recordToolMilestone({
+      milestoneBodies: body === null ? [] : [body],
+      identity: {
+        turnId: submission.submissionId,
+        assemblyRevision: submission.assemblyRevision,
+      },
+      command,
+      now: Date.now(),
+    });
+  }
+
   // 作用：把 Pi 恢复决策产生的变更写入 Runtime 数据库。
   // 调用：记录 Tool、终态、审批或恢复步骤时，通常在事务内调用。
   // 原因：upsert 保证重放幂等，而 terminal intent 允许后来的更强结果更新早期意图。
@@ -2205,15 +2227,12 @@ export abstract class AgentRuntimeKernel<
     submission: StoredSubmission,
     input: PiToolInputRecord,
   ): boolean {
-    const decision = this.decidePiRecovery(submission, {
-      kind: "record-tool-input",
-      record: input,
-    });
     const appended = this.db.transaction(() => {
-      const inserted = this.applyPiRecoveryMutations(
-        submission,
-        decision.mutations,
-      );
+      const mutations = this.recordPiToolMilestone(submission, {
+        kind: "record-tool-input",
+        record: input,
+      });
+      const inserted = this.applyPiRecoveryMutations(submission, mutations);
       if (inserted) {
         this.telemetry.capture("toolStarted", {
           submissionId: submission.submissionId,
@@ -2359,15 +2378,18 @@ export abstract class AgentRuntimeKernel<
         occurredAt: createdAt,
       });
     }
-    const decision = this.decidePiRecovery(submission, {
+    const mutations = this.recordPiToolMilestone(submission, {
       kind: "record-tool-result",
       toolCallId: call.toolCallId,
       toolName: call.toolName,
       result: call.result,
       isError: call.isError,
       timestamp: createdAt,
+      // The current execution is already continuing. After a crash, recovery
+      // materializes this result before resuming; no per-Tool dispatch is needed.
+      needsContinuation: false,
     });
-    this.applyPiRecoveryMutations(submission, decision.mutations);
+    this.applyPiRecoveryMutations(submission, mutations);
     this.approvals.commitContinuation(submission, call.toolCallId);
   }
 
@@ -3464,13 +3486,7 @@ export abstract class AgentRuntimeKernel<
    * 使持久化历史和 resumable stream 只有一个生产者。
    */
   async onConnect(connection: Connection): Promise<void> {
-    sendIfOpen(
-      connection,
-      json({
-        type: MessageType.CF_AGENT_CHAT_MESSAGES,
-        messages: await this.hydrationMessages(),
-      }),
-    );
+    await this.sendHydrationSnapshot(connection);
     await super.onConnect(connection);
   }
 
@@ -3596,6 +3612,10 @@ export abstract class AgentRuntimeKernel<
     }
 
     if (event.type === "stream-resume-request") {
+      // The client sends this only after its listener mounts; onConnect's snapshot
+      // may have arrived while initial history suspended. Active replies still
+      // come exclusively from CF replay, never from this history snapshot.
+      await this.sendHydrationSnapshot(connection);
       await this.handleResumeRequest(
         connection,
         event.probeId,
@@ -3637,6 +3657,13 @@ export abstract class AgentRuntimeKernel<
     return this.transcript.browserMessages();
   }
 
+  private async sendHydrationSnapshot(connection: Connection): Promise<void> {
+    sendIfOpen(connection, json({
+      type: MessageType.CF_AGENT_CHAT_MESSAGES,
+      messages: await this.hydrationMessages(),
+    }));
+  }
+
   private async hydrationMessages(): Promise<UIMessage[]> {
     const messages = await this.getMessages();
     const running = this.db.submissions.findRunning();