@springbrand/agent-runtime 0.2.0-alpha.15 → 0.2.0-alpha.17

package/src/kernel/interaction-lifecycle.ts

@@ -71,6 +71,8 @@ interface InteractionLifecycleOptions<
    * 没有这个回调，park 的那一刻不会有人去重算 —— 侧栏要等下一次广播才翻牌。
    */
   readonly onInteractionsChanged?: () => Promise<void>;
+  readonly onTelemetryRequested?: (interaction: InteractionRecord) => void;
+  readonly onTelemetrySettled?: (interaction: InteractionRecord) => void;
 }
 
 // #endregion
@@ -131,9 +133,17 @@ export class InteractionLifecycle<
     interaction: PiToolInteraction,
     signal?: AbortSignal,
   ): Promise<void> {
-    const pending = this.options.db.transaction(() =>
-      this.ensurePending(submission, interaction)
-    );
+    const pending = this.options.db.transaction(() => {
+      const value = this.ensurePending(submission, interaction);
+      if (value.created) {
+        try {
+          this.options.onTelemetryRequested?.(value.interaction);
+        } catch {
+          // Observability must not change interaction durability.
+        }
+      }
+      return value.interaction;
+    });
     // 必须在 wait 之前通知：wait 会一直挂到客户端投递，之后再通知就晚了一个回合。
     await this.options.onInteractionsChanged?.();
     return this.wait(pending, signal);
@@ -218,6 +228,14 @@ export class InteractionLifecycle<
         settlement: { kind: "cancel", reason },
       });
       this.options.applyRecoveryMutations(submission, decision.mutations);
+      const settled = this.read(interactionId);
+      if (settled) {
+        try {
+          this.options.onTelemetrySettled?.(settled);
+        } catch {
+          // Observability must not change terminal cleanup.
+        }
+      }
     }
     return true;
   }
@@ -267,6 +285,14 @@ export class InteractionLifecycle<
     if (!decision.applied) return { ok: false };
     this.options.db.transaction(() => {
       this.options.applyRecoveryMutations(submission, decision.mutations);
+      const settled = this.read(interactionId);
+      if (settled && settled.status !== "pending") {
+        try {
+          this.options.onTelemetrySettled?.(settled);
+        } catch {
+          // Observability must not change interaction settlement.
+        }
+      }
     });
     const persisted = this.read(interactionId);
     if (!persisted || persisted.status === "pending") {
@@ -320,7 +346,7 @@ export class InteractionLifecycle<
   private ensurePending(
     submission: TSubmission,
     interaction: PiToolInteraction,
-  ): InteractionRecord {
+  ): { interaction: InteractionRecord; created: boolean } {
     const existing = this.read(interaction.interactionId);
     if (existing) {
       if (
@@ -333,7 +359,7 @@ export class InteractionLifecycle<
           `Conflicting durable Tool interaction: ${interaction.toolCallId}`,
         );
       }
-      return existing;
+      return { interaction: existing, created: false };
     }
     // 表行和恢复里程碑都由 record-interaction 这一条命令产出，
     // 不在这里直接 insert —— 两份状态分叉正是恢复最难查的一类 bug。
@@ -342,7 +368,10 @@ export class InteractionLifecycle<
       interaction,
     });
     this.options.applyRecoveryMutations(submission, decision.mutations);
-    return { ...interaction, submissionId: submission.submissionId };
+    return {
+      interaction: { ...interaction, submissionId: submission.submissionId },
+      created: true,
+    };
   }
 
   // 作用：等待当前进程里的客户端响应。

package/src/layers/orchestration/temporary-agent/workspace.ts

@@ -3,7 +3,7 @@ import type {
   WorkspacePort,
 } from "../../../kernel/bindings";
 
-const MEMORY_ROOT = "/shared/memories";
+const MEMORY_ROOT = "/userspace/memories";
 
 // 作用：把 Workspace 路径统一成以 `/` 开头的正斜杠形式。
 // 调用：所有临时 Agent 路径在检查 Memory 边界前都经过这里。
@@ -21,7 +21,7 @@ function normalize(path: string): string {
 
 // 作用：判断一条路径是否指向共享 Memory 根目录或其子项。
 // 调用：`allowed` 拦截直接访问，`visible` 过滤目录和 glob 结果。
-// 原因：同时比较根路径和带 `/` 的子路径前缀，避免误伤 `/shared/memories-old`。
+// 原因：同时比较根路径和带 `/` 的子路径前缀，避免误伤 `/userspace/memories-old`。
 function isMemoryPath(path: string): boolean {
   const normalized = normalize(path);
   return (
@@ -32,12 +32,12 @@ function isMemoryPath(path: string): boolean {
 
 // 作用：返回可交给底层 Workspace 的归一化路径。
 // 调用：临时 Agent Workspace 外观的每个路径参数都必须先经过它。
-// 原因：在一个共享边界拒绝 `/shared/memories`，比在每个上层 Tool 里分别检查更不容易漏掉新调用方。
+// 原因：在一个共享边界拒绝 `/userspace/memories`，比在每个上层 Tool 里分别检查更不容易漏掉新调用方。
 function allowed(path: string): string {
   const normalized = normalize(path);
   if (isMemoryPath(normalized)) {
     throw new Error(
-      "/shared/memories is not accessible to temporary agents",
+      "/userspace/memories is not accessible to temporary agents",
     );
   }
   return normalized;

package/src/lib/prompt.ts

@@ -24,9 +24,10 @@ export const SYSTEM_PROMPT =
 
 // Explains how to reach capabilities instead of listing unsupported substitutes.
 export const RUNTIME =
-  "Runtime: this agent runs on Cloudflare Workers. The execute Code Mode Dynamic Worker is your " +
-  "instrument — you write code there and it runs with outbound network access (fetch), your " +
-  "workspace filesystem (state.*), and your other tools (tools.*). Use it for raw or customized HTTP " +
+  "Runtime: this agent runs on Cloudflare Workers. When execute is present, its Code Mode Dynamic Worker is your " +
+  "instrument — code there runs with outbound network access (fetch), your " +
+  "workspace filesystem (state.*), and your other tools (tools.* when that connector is available). Put repeated or multi-step work " +
+  "in one execute instead of making consecutive top-level Tool calls. Use it for raw or customized HTTP " +
   "requests, parsing a payload, hitting several known endpoints, or computing over a file. Write plain " +
   "JavaScript — the sandbox evaluates " +
   "it directly, so TypeScript type annotations (`: number`, `as Type`) are a syntax error, and there " +
@@ -52,28 +53,34 @@ export const PLANNING =
 
 // Tool-selection guidance mirrors the actual approval and network boundaries.
 export const TOOLS =
-  "Tools: Prefer the dedicated workspace file tools (read/write/edit/list/find/grep) for file work — " +
-  "they run without approval. For web tasks, use web_search for web discovery, current facts, cited research, " +
-  "and public URL analysis. Use execute Code Mode only for raw or customized network requests, structured " +
+  "Tools: When execute is present, call a top-level Tool directly only for a single standalone Tool call or when that Tool is unavailable " +
+  "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 non-CDP calls. " +
+  "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 " +
   "API calls, or when web_search cannot retrieve the required content; do not use execute for ordinary web " +
-  "searches. When sandbox_* tools are present, use that isolated Linux environment for Python/Node, " +
+  "searches. When execute is absent, use the actually exposed Direct Tools. When sandbox_* tools are present, use that isolated Linux environment for Python/Node, " +
   "package managers, system commands, builds, tests and background processes; its filesystem is temporary, " +
-  "persistent inputs are copied in automatically on first use, /shared is read-only, and only explicitly " +
+  "persistent inputs are copied in automatically on first use, /userspace is read-only, and only explicitly " +
   "published /workspace outputs survive. Use Code Mode for computation, multi-step data work, and the " +
   "raw or customized network cases described above; every response and failure it sees is visible to you. " +
   "bash is a shell over the workspace filesystem only " +
   "(no network, no system utilities) and is approval-gated — don't reach for it to read files or fetch. " +
-  "For more than three related changes in one file, use one write or bash operation instead of serial edits; " +
-  "do not re-plan or explain between consecutive tool calls. When a run is within the last five model turns, stop expanding scope and " +
+  "When execute is present, make related file changes in one execute with state.*; when execute is absent, use one write or bash operation instead of serial edits. " +
+  "Do not re-plan or explain between consecutive tool calls. When a run is within the last five model turns, stop expanding scope and " +
   "prioritize verification, saving durable results, and the final response. " +
-  "When tool calls are independent, issue them in one turn so they run in parallel. When you reference " +
+  "When related Tool calls can run independently and execute is present, run them inside that execute rather than as parallel top-level calls; " +
+  "only independent top-level-only Direct Tools should be issued together in one turn. When you reference " +
   "code, cite it as file_path:line_number.";
 
 // Uploaded-file routing prevents lossy markdown conversions from becoming data sources.
 export const FILES =
   "Uploaded files live under /uploads/ in your workspace; convertible formats have a companion " +
-  "'<file>.md' (structured markdown). Policy: to summarize/quote/search, read or grep the .md; " +
-  "to compute/aggregate/transform (especially csv/xlsx), write code in execute Code Mode or the Linux Sandbox that reads " +
+  "'<file>.md' (structured markdown). Policy: to summarize/quote/search one file, read or grep the .md; when execute is present, " +
+  "read or search multiple files through state.* in one execute instead of repeated top-level file Tool calls. " +
+  "To compute/aggregate/transform (especially csv/xlsx), write code in execute Code Mode or the Linux Sandbox that reads " +
   "the ORIGINAL file — converted markdown tables are not for computation, and large spreadsheets may " +
   "have no .md at all. For formats without a companion .md (e.g. pptx: unzip and read ppt/slides/*.xml; " +
   "zip archives; unknown types), parse the original in the sandbox with JS.";
@@ -93,9 +100,9 @@ export const INTERACTION =
 export const MEMORY =
   "Memory conventions: memory/preferences context blocks are writable working memory " +
   "for this Session only. Cold memory is managed explicitly by the user and is shared " +
-  "across Sessions under /shared/memories/. Runtime access to that directory is read-only: " +
+  "across Sessions under /userspace/memories/. Runtime access to that directory is read-only: " +
   "never create, edit, move, or delete its files. To recall long-tail information, check " +
-  "the memory_index block first, then read the listed entry under /shared/memories/ when relevant.";
+  "the memory_index block first, then read the listed entry under /userspace/memories/ when relevant.";
 
 /**
  * 把 Agent 个性和 Runtime 的固定行为说明组成主 Agent 系统提示词。

package/src/pi/assembly/context.ts

@@ -41,7 +41,7 @@ const COMPACTION_RETRY: RetryPolicy = {
   baseDelayMs: 500,
 };
 
-const COLD_MEMORY_INDEX = "/shared/memories/MEMORY.md";
+const COLD_MEMORY_INDEX = "/userspace/memories/MEMORY.md";
 const TRUNCATION_MARKER = "\n[truncated to memory budget]";
 
 function sumUsage(responses: readonly AssistantMessage[]): Usage | undefined {
@@ -350,7 +350,7 @@ async function readMemory(
         blocks.push(
           renderBlock(
             "MEMORY_INDEX",
-            "Index of user-managed cold memory under /shared/memories; entries are read on demand",
+            "Index of user-managed cold memory under /userspace/memories; entries are read on demand",
             index,
           ),
         );

package/src/pi/message/conversion.ts

@@ -21,7 +21,19 @@ function attachmentText(
   part: Extract<UIMessage["parts"][number], { type: "file" }>,
 ): string {
   const name = part.filename?.trim() || "attachment";
-  return `[Attachment: ${name} (${part.mediaType}) ${part.url}]`;
+  let ref: string | null = null;
+  try {
+    const path = part.url.startsWith("/")
+      ? new URL(part.url, "https://attachment.invalid").pathname
+      : new URL(part.url).pathname;
+    const leaf = path.split("/").filter(Boolean).at(-1);
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(leaf ?? "")) {
+      ref = leaf!;
+    }
+  } catch {
+    // Preserve the existing canonical form for non-platform file URLs.
+  }
+  return `[Attachment: ${name} (${part.mediaType}) ${ref ? `ref=${ref}` : part.url}]`;
 }
 
 function userContent(

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

@@ -208,6 +208,7 @@ const IDEMPOTENT_TOOL_NAMES = new Set([
   "bind_resource",
   "delete",
   "edit",
+  "execute",
   "find",
   "get_time",
   "grep",

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

@@ -25,13 +25,13 @@ import { PiChunkEncoder } from "../message";
 import type { UIMessageChunk } from "ai";
 import { ChatStreamStalledError } from "agents/chat";
 import {
+  codeExecutionPiToolCandidate,
   compilePiTools,
   createPiToolGovernance,
   normalizeUpdatePlanArguments,
   type PiToolCandidate,
   type PiToolInteractionSpec,
   type PiToolGovernance,
-  type PiToolTelemetry,
   type SettledPiToolCall,
 } from "../tool";
 import {
@@ -44,10 +44,12 @@ import {
   isModelStreamStallMessage,
   resolvePiApiKey,
   withProviderRetry,
+  type PiGenerationLifecycleObserver,
 } from "./models";
 import { EXECUTION_LEVELS } from "../../lib/execution-level";
 import { projectToolOutputForModel } from "../../layers/context/budget/gate";
 import type { SpillWorkspace } from "../../lib/artifacts";
+import { toolRegistryFromPiCandidates } from "../../tool-registry";
 
 // #region Single-run Pi bridge
 
@@ -128,10 +130,7 @@ interface PiTurnAdapterOptions {
   readonly settle: (
     call: SettledPiToolCall,
   ) => void | Promise<void>;
-  // 上报工具执行耗时、结果大小和成败。
-  // 工具治理层在每次执行结束时调用它，宿主可选择不提供。
-  // 该回调只负责观测，工具治理层会吞掉它的异常以免改变执行结果。
-  readonly onToolTelemetry?: (event: PiToolTelemetry) => void;
+  readonly onGeneration?: PiGenerationLifecycleObserver;
   // 在模型调用前调整 Pi 的消息上下文。
   // PiCore 通过 AgentOptions.transformContext 调用它，Runtime 用它接入现有上下文处理。
   // 直接复用 Pi 的回调类型可避免这里维护另一套上下文转换约定。
@@ -171,7 +170,7 @@ class PiTurnAdapter {
   // PreparedPiTurnAdapter 只构造一次，并把运行、重试、转向和中止都交给它。
   // 工具治理对象必须在这些路径间复用，因为它保存本 Turn 的重试次数和熔断状态。
   constructor(private readonly opts: PiTurnAdapterOptions) {
-    this.governance = createPiToolGovernance(opts.onToolTelemetry);
+    this.governance = createPiToolGovernance();
   }
 
   // 把 Tool candidate 变成 Pi 可以执行的受治理 Tool。
@@ -240,6 +239,7 @@ class PiTurnAdapter {
         this.opts.models.streamSimple.bind(this.opts.models),
         0,
         this.opts.modelSessionId,
+        this.opts.onGeneration,
       ),
       getApiKey: () => this.opts.apiKey,
       // transformMessages 在宿主上下文变换之后运行，确保跨 provider 的 tool call ID 格式兼容。
@@ -402,18 +402,13 @@ export interface CreatePreparedPiTurnOptions {
    */
   readonly canonicalMessages: () => Promise<readonly AgentMessage[]>;
   readonly durability: PiTurnDurability;
+  /** Reports paired model-generation lifecycle facts to the Runtime owner. */
+  readonly onGeneration?: PiGenerationLifecycleObserver;
   /** Per-Submission executors for tools whose metadata is fixed at assembly time. */
   readonly toolExecutors?: Readonly<Record<
     string,
     NonNullable<PiToolCandidate["tool"]["execute"]>
   >>;
-  /**
-   * 上报受治理工具的耗时、结果大小和成败。
-   *
-   * 工具治理层在执行结束时调用它，Runtime 可用它发出工具遥测事件。
-   * 该回调只负责观测，工具治理层会隔离它的异常，避免遥测改变工具结果。
-   */
-  readonly onToolTelemetry?: (event: PiToolTelemetry) => void;
   /**
    * 调整 Pi 即将发送给模型的消息上下文。
    *
@@ -527,7 +522,11 @@ export class PreparedPiTurnAdapter {
       messageId: options.submission.messageId,
       startedAt: options.submission.startedAt,
     });
-    this.candidates = state.candidates.map((candidate) => ({
+    const bindCandidate = (
+      candidate: PiToolCandidate,
+      toolCallIdPrefix?: string,
+      recordRecoveryAttempt = true,
+    ): PiToolCandidate => ({
       ...candidate,
       tool: {
         ...candidate.tool,
@@ -535,6 +534,9 @@ export class PreparedPiTurnAdapter {
         // 实时运行由 PiCore 调用它，恢复或审批续跑则由 retryTool 进入同一路径。
         // 顺序不能随便调整：门禁先于结果复用，审批可能生成结果，不确定的非幂等工作不能重放。
         execute: async (toolCallId, input, signal, onUpdate) => {
+          if (toolCallIdPrefix) {
+            toolCallId = `${toolCallIdPrefix}:${toolCallId}`;
+          }
           const requiredExecutionLevel = candidate.requiredExecutionLevelForInput
             ? await candidate.requiredExecutionLevelForInput(input)
             : candidate.requiredExecutionLevel;
@@ -645,17 +647,19 @@ export class PreparedPiTurnAdapter {
             }
             return responded.result;
           }
-          const retry = piToolRetryPolicy(candidate);
-          const firstAttempt = options.durability.appendToolInput({
-            toolCallId,
-            toolName: candidate.tool.name,
-            input,
-            retry,
-          });
-          if (!firstAttempt && retry === "non-idempotent") {
-            throw new Error(
-              `Non-idempotent Tool outcome is uncertain after recovery: ${candidate.tool.name}`,
-            );
+          if (recordRecoveryAttempt) {
+            const retry = piToolRetryPolicy(candidate);
+            const firstAttempt = options.durability.appendToolInput({
+              toolCallId,
+              toolName: candidate.tool.name,
+              input,
+              retry,
+            });
+            if (!firstAttempt && retry === "non-idempotent") {
+              throw new Error(
+                `Non-idempotent Tool outcome is uncertain after recovery: ${candidate.tool.name}`,
+              );
+            }
           }
           const execute = options.toolExecutors?.[candidate.tool.name] ??
             candidate.tool.execute;
@@ -667,7 +671,39 @@ export class PreparedPiTurnAdapter {
           );
         },
       },
-    }));
+    });
+    this.candidates = state.candidates.map((candidate) => {
+      if (!candidate.codeExecutionTools) return bindCandidate(candidate);
+      const factory = state.snapshot.bindings.codeExecution;
+      if (!factory) {
+        throw new Error("Prepared Code Mode Tool requires a Runtime factory");
+      }
+      return bindCandidate({
+        ...candidate,
+        tool: {
+          ...candidate.tool,
+          execute: (toolCallId, input, signal, onUpdate) => {
+            const runtimeCandidate = codeExecutionPiToolCandidate(
+              factory.create(toolRegistryFromPiCandidates(
+                candidate.codeExecutionTools!.map((inner) =>
+                  // Code Mode owns replay of its connector calls. Pi persists
+                  // only the 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)
+                ),
+              )),
+            );
+            return runtimeCandidate.tool.execute(
+              toolCallId,
+              input,
+              signal,
+              onUpdate,
+            );
+          },
+        },
+      });
+    });
     this.turn = new PiTurnAdapter({
       pi: {
         model: state.snapshot.pi.model,
@@ -679,13 +715,13 @@ export class PreparedPiTurnAdapter {
         state.snapshot.pi.model.id,
       ),
       modelSessionId: options.submission.requestId,
+      ...(options.onGeneration ? { onGeneration: options.onGeneration } : {}),
       canonicalMessages: options.canonicalMessages,
       // 被中断的 Turn 不写结算。它退场路上还会吐出「工具被中止」，而工具其实
       // 没有产生任何结果 —— 结算是单调的，落了这条假结果，重建出来的续跑会
       // 把一个从没跑过的工具当成跑过并失败。取消不走这里：取消要的就是终态。
       settle: (call) =>
         this.interrupted ? undefined : options.durability.settleTool(call),
-      onToolTelemetry: options.onToolTelemetry,
       transformContext: options.transformContext,
       workspace: state.snapshot.bindings.workspace,
     });