@springbrand/agent-runtime 0.2.0-alpha.25 → 0.2.0-alpha.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.2.0-alpha.25",
+  "version": "0.2.0-alpha.28",
   "type": "module",
   "files": [
     "src",

package/src/kernel/public-contracts.ts

@@ -17,6 +17,7 @@ export * from "../pi/message";
 export * from "./receipts";
 export * from "./state";
 export * from "../lib/execution-level";
+export type { WorkspaceRevision, WorkspaceRevisionManifest } from "../workspace-versioning";
 export type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,

package/src/kernel/submission-lifecycle.ts

@@ -639,12 +639,13 @@ export class SubmissionLifecycle<
   }
 
   /**
-   * 为一条未结束提交记录取消，并尽快中断活动执行器。
+   * 为一条未结束提交记录取消终态，并中断活动执行器。
    *
    * @remarks
    * 客户端取消事件和 `cancelSubmissionById` RPC 按提交标识调用；不存在或已结束时返回 `ok: false`。
    *
-   * 先在事务中保存取消原因和恢复意图，再按活动、已排队或未执行三种情况处理，避免丢失启动窗口内的取消。
+   * 先在事务中保存取消原因和恢复意图，再中断活动执行器并在返回前写入终态，
+   * 使任何不配合取消的执行器都不能让调用方继续观察到 running。
    */
   async cancel(
     submissionId: string,
@@ -660,10 +661,8 @@ export class SubmissionLifecycle<
     });
     const active = this.activeBySubmission.get(submissionId);
     if (active) this.options.abortActive(active);
-    else {
-      await this.finish(submission, "aborted", reason);
-      this.pump();
-    }
+    await this.finish(submission, "aborted", reason);
+    if (!active) this.pump();
     return { ok: true };
   }
 

package/src/lib/prompt.ts

@@ -49,7 +49,6 @@ export const TOOLS =
   "inside execute. Any operation that needs the same Tool more than once, two or more related file, Skill, Extension, MCP, or Host Tool calls, " +
   "or branching or repetition MUST use one execute. Do not make repeated top-level calls for that work. Inside execute, use state.* for " +
   "workspace file operations, tools.* for other host capabilities, a loop for repeated calls, and Promise.all for independent calls. " +
-  "For materialize_skill_resource, materialize every known set of Skill resources in one execute; never start one execute per resource. " +
   "Tools available only at the top level must stay Direct. " +
   "For web tasks, use web_search for web discovery, current facts, cited research, " +
   "and public URL analysis. For web access specifically, use execute Code Mode only for raw or customized network requests, structured " +
@@ -106,7 +105,8 @@ export const FILES =
 export const INTERACTION =
   "Interaction: When progress requires user decisions, put all 1-4 necessary questions in one ask_user call " +
   "instead of asking each question separately or writing 'please choose A/B/C' as text. Use 2-6 options for " +
-  "a bounded choice, or no options when a required free-text answer is necessary; continue the same turn when its result arrives. " +
+  "a bounded choice; for required free text, omit the options field entirely — never pass an empty or single-item options array; " +
+  "continue the same turn when its result arrives. " +
   "Don't use it when a sensible default lets you proceed. " +
   "After completing a substantive task (report, analysis, multi-step job): write your full answer " +
   "FIRST, then call suggest_followups (2-4 directions) as the very last action and end the turn — " +

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

@@ -210,6 +210,41 @@ function projectToolResultsForModel(
   return changed ? projected : [...messages];
 }
 
+function orderLateToolResultsBeforeTurnAbortMarker(
+  messages: readonly AgentMessage[],
+): AgentMessage[] {
+  const ordered: AgentMessage[] = [];
+  for (let index = 0; index < messages.length; index += 1) {
+    const message = messages[index]!;
+    const previous = ordered.at(-1);
+    if (
+      message.role !== "custom" ||
+      message.customType !== "turn-aborted" ||
+      previous?.role !== "assistant"
+    ) {
+      ordered.push(message);
+      continue;
+    }
+    const pending = new Set(
+      previous.content.flatMap((part) =>
+        part.type === "toolCall" ? [part.id] : []
+      ),
+    );
+    let cursor = index + 1;
+    while (true) {
+      const result = messages[cursor];
+      if (result?.role !== "toolResult" || !pending.has(result.toolCallId)) {
+        break;
+      }
+      ordered.push(result);
+      cursor += 1;
+    }
+    ordered.push(message);
+    index = cursor - 1;
+  }
+  return ordered;
+}
+
 class PiTurnAdapter {
   private piInstance?: PiCore;
   private abortRequested = false;
@@ -304,7 +339,9 @@ class PiTurnAdapter {
       transformContext: async (messages, signal) => {
         const ctx = await this.opts.transformContext(messages, signal);
         return transformMessages(
-          projectToolResultsForModel(ctx, selfBounded) as Message[],
+          orderLateToolResultsBeforeTurnAbortMarker(
+            projectToolResultsForModel(ctx, selfBounded),
+          ) as Message[],
           this.opts.pi.model,
         ) as AgentMessage[];
       },

package/src/pi/tool/base.ts

@@ -24,7 +24,8 @@ const askUserQuestion = Type.Object({
     minItems: 2,
     maxItems: 6,
     uniqueItems: true,
-    description: "2-6 mutually distinct options for the user to choose from.",
+    description:
+      "For a bounded choice, provide 2-6 mutually distinct options. For required free text, omit this field entirely; never pass an empty or single-item array.",
   })),
   multiSelect: Type.Optional(Type.Boolean({
     description:
@@ -237,7 +238,7 @@ export function basePiToolCandidates(
         name: "ask_user",
         label: "Ask user",
         description:
-          "Ask all 1-4 user questions needed to continue in one call. Each question may offer 2-6 options, allow multiple selections, and/or allow a custom answer. Do not make one call per question or write plain text like 'please pick A / B / C'. The answers return as this tool's result, so continue the same turn after calling it.",
+          "Ask all 1-4 user questions needed to continue in one call. For a bounded choice, provide 2-6 distinct options. For required free text, omit the options field entirely; never pass an empty, single-item, or more-than-6-item options array. Do not make one call per question or write plain text like 'please pick A / B / C'. The answers return as this tool's result, so continue the same turn after calling it.",
         parameters: askUserParameters,
         // 永远不会被调用：执行链在 interaction 闸就 park 住了。留一个失败关闭的
         // 实现，是为了万一哪次改动绕过了那道闸，能立刻炸出来而不是静默返回空答案。

package/src/pi/tool/compiler.ts

@@ -204,6 +204,27 @@ async function durableResult(
   return boundDurableToolOutput(result) as AgentToolResult<unknown>;
 }
 
+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);
+  }
+}
+
 // 记录一次工具失败并在 Turn 达到上限时打开断路器。
 // 受治理 execute 方法在工具或结算失败后调用。
 // 同时记录单输入次数和 Turn 总数，是为了既阻止原样重试又防止换参数无限失败。
@@ -327,11 +348,19 @@ function governedTool(
       }
 
       let result: AgentToolResult<unknown>;
+      const guardedUpdate: typeof onUpdate = onUpdate
+        ? (update) => {
+            if (!signal?.aborted) onUpdate(update);
+          }
+        : undefined;
       try {
-        result = await durableResult(
-          await execute(toolCallId, args, signal, onUpdate),
-          candidate,
-          options.workspace,
+        result = await untilAborted(
+          signal,
+          async () => durableResult(
+            await execute(toolCallId, args, signal, guardedUpdate),
+            candidate,
+            options.workspace,
+          ),
         );
       } catch (cause) {
         const message = errorMessage(cause);

package/src/pi/tool/core-host.ts

@@ -85,6 +85,8 @@ function previewNote(base: string): string {
 
 function browserToolDescription(): string {
   return "Run JavaScript against a live browser over the Chrome DevTools Protocol through the `cdp` connector. " +
+    "Use the bare lexical identifiers `cdp` and `codemode`. They are not properties of `globalThis` and are not importable modules. " +
+    "Never use `globalThis.cdp`, `globalThis.codemode`, or `import(\"cdp\")`; never import `cdp`. " +
     "Each top-level `browser_execute` call is one-shot: it starts a fresh browser and closes it when the call returns. " +
     "Never reuse a `targetId` or `sessionId` from an earlier browser_execute call. " +
     "Create targets, attach, navigate, interact, inspect diagnostics, and capture screenshots within the same call. " +
@@ -131,16 +133,14 @@ export function createBrowserExecutionFactory(options: {
       if (!tool) {
         throw new Error("Upstream createBrowserTools did not return browser_execute");
       }
-      const port = {
-        ...toCodeExecutionPort(tool, "browser_execute"),
-        description: browserToolDescription(),
-      };
-      if (!options.previewBaseUrl) return port;
+      const port = toCodeExecutionPort(tool, "browser_execute");
+      const description = `${port.description}\n\n${browserToolDescription()}`;
+      if (!options.previewBaseUrl) return { ...port, description };
       // 前置而不是追加：上游的 codemode 描述很长，缀在末尾的一句会被读丢 ——
       // 2026-08-13 手动冒烟里模型就没看见它，转而去猜 `file://` 和 `https://workspace.local/`。
       return {
         ...port,
-        description: `${previewNote(options.previewBaseUrl)}\n\n${port.description}`,
+        description: `${previewNote(options.previewBaseUrl)}\n\n${description}`,
       };
     },
   };

package/src/pi/tool/skill.ts

@@ -111,7 +111,7 @@ function budgetSkillResources(skill: LoadedSkill): LoadedSkill {
   if (portable.length > 0) {
     lines.push(
       `> If any of these resources are needed, copy all required ones into the Workspace ` +
-      `in one execute with materialize_skill_resource: ` +
+      `in one execute with tools.materialize_skill_resource: ` +
       `${portable.map((entry) => entry.path).join(", ")}.`,
     );
   }

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

@@ -399,13 +399,7 @@ export function workspacePiToolCandidates(
   const bash = aiToolToPi(
     "bash",
     createBashTool({ ops: workspace }),
-    {
-      label: "Workspace Bash",
-      description:
-        "Run a Bash script over Workspace files for shell-style workflows that combine multiple file operations. " +
-        "The Workspace is mounted at / and changes are written back. This is a virtual filesystem, not a machine: " +
-        "there is no network or system utilities; use execute for fetch and sandbox_exec for system commands.",
-    },
+    { label: "Workspace Bash" },
   );
 
   return [

package/src/runtime-assembler.ts

@@ -268,12 +268,24 @@ async function createToolSurface(
             typeof candidate.tool.execute === "function",
         );
         const codeExecutionTools = Object.freeze([...mergeable]);
+        const codeExecution = input.codeExecution.create(
+          toolRegistryFromPiCandidates(codeExecutionTools),
+        );
+        const materializeGuidance = codeExecutionTools.some(
+            ({ tool }) => tool.name === "materialize_skill_resource",
+          )
+          ? "Skill resource copying is available only inside execute through " +
+            "`tools.materialize_skill_resource({ name, path, destination })`; " +
+            "no Direct Tool is registered for it. " +
+            "Use a loop or Promise.all when copying multiple resources.\n\n"
+          : "";
         return Object.freeze([
           Object.freeze({
             ...codeExecutionPiToolCandidate(
-              input.codeExecution.create(
-                toolRegistryFromPiCandidates(codeExecutionTools),
-              ),
+              {
+                ...codeExecution,
+                description: materializeGuidance + codeExecution.description,
+              },
             ),
             codeExecutionTools,
           }),

package/src/runtime.ts

@@ -613,7 +613,13 @@ export abstract class AgentRuntimeKernel<
       resumeSubmission: async (submissionId) => {
         await this.submissions.recover(submissionId);
       },
-      onInteractionsChanged: () => this.broadcastApprovals(),
+      onInteractionsChanged: async () => {
+        this.broadcast(json({
+          type: MessageType.CF_AGENT_CHAT_MESSAGES,
+          messages: await this.getMessages(),
+        }));
+        await this.broadcastApprovals();
+      },
       onTelemetryRequested: (interaction) => {
         this.telemetry.capture("interactionRequested", {
           submissionId: interaction.submissionId,
@@ -2554,6 +2560,36 @@ export abstract class AgentRuntimeKernel<
           return { kind: "settled" };
         case "resume-turn": {
           const last = (await this.transcript.canonicalMessages()).at(-1);
+          if (last?.role === "assistant" && last.stopReason === "toolUse") {
+            // Tool input 会在真正执行前持久化。恢复状态仍为 idle 证明这些
+            // canonical Tool Call 还没越过 attempt 边界，包括非幂等 Tool 也可以安全首次执行。
+            const unstartedCalls = last.content.filter((part) =>
+              part.type === "toolCall"
+            );
+            if (unstartedCalls.length > 0) {
+              for (const call of unstartedCalls) {
+                try {
+                  if (
+                    !await adapter.retryTool({
+                      toolName: call.name,
+                      toolCallId: call.id,
+                      input: call.arguments,
+                    })
+                  ) {
+                    return {
+                      kind: "unresumable",
+                      reason:
+                        `SpringBrand could not resume this turn: Tool "${call.name}" is no longer available.`,
+                    };
+                  }
+                } catch {
+                  // The governed Tool persisted its bounded error ToolResult.
+                }
+              }
+              decision = await this.materializeRecoveredToolResults(submission);
+              continue;
+            }
+          }
           // Pi 的 agentLoopContinue 拒绝从 assistant 消息继续。悬空的尾部 assistant
           // 意味着这条 transcript 续不下去了 —— 判断出来就必须收尾,不能默默退场。
           return last?.role === "user" || last?.role === "toolResult"
@@ -3060,9 +3096,18 @@ export abstract class AgentRuntimeKernel<
               });
             },
           );
+          const stoppedAfterScheduling = this.readSubmission(submissionId)
+            ?.abortReason;
+          if (recoveryOutcome !== "disabled" && stoppedAfterScheduling) {
+            await this.settleChatRecovery(
+              submission.requestId,
+              "skipped",
+              stoppedAfterScheduling,
+            );
+          }
           if (
             recoveryOutcome !== "disabled" &&
-            !this.readSubmission(submissionId)?.abortReason
+            !stoppedAfterScheduling
           ) {
             // 只有恢复通道的调用方(`_chatRecoveryRetry`)靠这次重抛判定 "scheduled"。
             // 让步续跑由 alarm 驱动，重抛只会把那次 alarm 变成一次失败。