@springbrand/agent-runtime 0.2.0-alpha.41 → 0.2.0-alpha.42

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

@@ -25,6 +25,7 @@ import { PiChunkEncoder } from "../message";
 import type { UIMessageChunk } from "ai";
 import { ChatStreamStalledError } from "agents/chat";
 import {
+  codeExecutionPiToolCandidate,
   compilePiTools,
   createPiToolGovernance,
   normalizeUpdatePlanArguments,
@@ -542,6 +543,25 @@ export interface CreatePreparedPiTurnOptions {
   readonly durability: PiTurnDurability;
   /** Reports paired model-generation lifecycle facts to the Runtime owner. */
   readonly onGeneration?: PiGenerationLifecycleObserver;
+  /** Reports Code Mode child Tool starts without adding Pi recovery state. */
+  readonly onNestedToolStarted?: (input: Readonly<{
+    parentToolCallId: string;
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    occurredAt: number;
+  }>) => void;
+  /** Reports Code Mode child Tool outcomes without adding Pi settlements. */
+  readonly onNestedToolFinished?: (input: Readonly<{
+    parentToolCallId: string;
+    toolCallId: string;
+    toolName: string;
+    outcome: "completed" | "failed" | "cancelled";
+    durationMs: number;
+    output?: import("@earendil-works/pi-agent-core").AgentToolResult<unknown>;
+    error?: unknown;
+    occurredAt: number;
+  }>) => void;
   /** Per-Submission executors for tools whose metadata is fixed at assembly time. */
   readonly toolExecutors?: Readonly<Record<
     string,
@@ -633,6 +653,7 @@ export class PreparedPiTurnAdapter {
   private readonly turn: PiTurnAdapter;
   private readonly abortController = new AbortController();
   private readonly candidates: readonly PiToolCandidate[];
+  private nestedToolOrdinal = 0;
   private assistantOrdinal: number;
   private readonly encoder: PiChunkEncoder;
   private readonly steerMessageIds: string[] = [];
@@ -665,6 +686,8 @@ export class PreparedPiTurnAdapter {
     });
     const bindCandidate = (
       candidate: PiToolCandidate,
+      toolCallIdPrefix?: string,
+      recordRecoveryAttempt = true,
     ): PiToolCandidate => ({
       ...candidate,
       tool: {
@@ -673,6 +696,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;
@@ -783,25 +809,93 @@ export class PreparedPiTurnAdapter {
             }
             return responded.result;
           }
-          const retry = piToolRetryPolicy(candidate);
-          const firstAttempt = options.durability.appendToolInput({
-            toolCallId,
+          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;
+          if (recordRecoveryAttempt || !toolCallIdPrefix) {
+            return execute(toolCallId, input, signal, onUpdate);
+          }
+          const startedAt = Date.now();
+          const telemetryToolCallId = `${toolCallId}:${++this.nestedToolOrdinal}`;
+          options.onNestedToolStarted?.({
+            parentToolCallId: toolCallIdPrefix,
+            toolCallId: telemetryToolCallId,
             toolName: candidate.tool.name,
             input,
-            retry,
+            occurredAt: startedAt,
           });
-          if (!firstAttempt && retry === "non-idempotent") {
-            throw new Error(
-              `Non-idempotent Tool outcome is uncertain after recovery: ${candidate.tool.name}`,
-            );
+          try {
+            const output = await execute(toolCallId, input, signal, onUpdate);
+            const occurredAt = Date.now();
+            options.onNestedToolFinished?.({
+              parentToolCallId: toolCallIdPrefix,
+              toolCallId: telemetryToolCallId,
+              toolName: candidate.tool.name,
+              outcome: "completed",
+              durationMs: occurredAt - startedAt,
+              output,
+              occurredAt,
+            });
+            return output;
+          } catch (error) {
+            const occurredAt = Date.now();
+            options.onNestedToolFinished?.({
+              parentToolCallId: toolCallIdPrefix,
+              toolCallId: telemetryToolCallId,
+              toolName: candidate.tool.name,
+              outcome: signal?.aborted ? "cancelled" : "failed",
+              durationMs: occurredAt - startedAt,
+              error,
+              occurredAt,
+            });
+            throw error;
           }
-          const execute = options.toolExecutors?.[candidate.tool.name] ??
-            candidate.tool.execute;
-          return execute(toolCallId, input, signal, onUpdate);
         },
       },
     });
-    this.candidates = state.candidates.map(bindCandidate);
+    this.candidates = state.candidates.map((candidate) => {
+      if (candidate.tool.name !== "execute") 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(state.codeExecutionCandidates.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,

package/src/pi/tool/base.ts

@@ -183,13 +183,31 @@ export function normalizeUpdatePlanArguments(
     return input as UpdatePlanArguments;
   }
   const value = input as Record<string, unknown>;
-  if (!Array.isArray(value.steps)) return input as UpdatePlanArguments;
+  let steps = value.steps;
+  if (typeof steps === "string") {
+    try {
+      steps = JSON.parse(steps);
+    } catch {
+      return input as UpdatePlanArguments;
+    }
+  }
+  if (!Array.isArray(steps)) return input as UpdatePlanArguments;
   return {
     ...value,
-    steps: value.steps.map((step) => {
+    steps: steps.map((step) => {
       if (step === null || typeof step !== "object") return step;
       const s = step as Record<string, unknown>;
-      return { ...s, status: normalizeStepStatus(s.status) };
+      const { step: alias, ...rest } = s;
+      const text = typeof rest.text === "string"
+        ? rest.text
+        : typeof alias === "string"
+        ? alias
+        : undefined;
+      return {
+        ...rest,
+        ...(text === undefined ? {} : { text }),
+        status: normalizeStepStatus(s.status),
+      };
     }),
   } as UpdatePlanArguments;
 }
@@ -278,7 +296,8 @@ export function basePiToolCandidates(
         },
       },
     },
-    candidate({
+    {
+      ...candidate({
         name: "suggest_followups",
         label: "Suggest follow-ups",
         description:
@@ -288,7 +307,10 @@ export function basePiToolCandidates(
           return result({ noted: true, count: input.items.length });
         },
       }),
-    candidate({
+      direct: true,
+    },
+    {
+      ...candidate({
         name: "update_plan",
         label: "Update plan",
         description:
@@ -303,6 +325,8 @@ export function basePiToolCandidates(
           });
         },
       }),
+      direct: true,
+    },
     ...(webSearch ? [webSearchPiToolCandidate(webSearch)] : []),
   ];
 }

package/src/pi/tool/compiler.ts

@@ -48,6 +48,10 @@ export interface PiToolCandidate {
   readonly tool: AgentTool<any, any>;
   /** @internal Send the complete schema but hide it until provider Tool Search finds it. */
   readonly deferLoading?: true;
+  /** Keep this Tool Direct-only instead of also offering it through Code Mode. */
+  readonly direct?: true;
+  /** Offer this Tool only through Code Mode, never as a top-level Tool. */
+  readonly codeExecutionOnly?: true;
   /** Conservative maximum used in the stable Runtime descriptor. */
   readonly requiredExecutionLevel: ExecutionLevel;
   /** Trusted parameter-level policy, evaluated before approval or dispatch. */

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

@@ -1,16 +1,61 @@
+import {
+  createWorkspaceStateBackend,
+  type WorkspaceFsLike,
+} from "@cloudflare/shell";
 import { createBrowserTools } from "@cloudflare/think/tools/browser";
+import { createExecuteRuntime } from "@cloudflare/think/tools/execute";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Usage } from "@earendil-works/pi-ai";
 import type { ToolSet } from "ai";
 import type {
   RuntimeBrowserPort,
   RuntimeCodeExecutionPort,
+  WorkspacePort,
 } from "../../kernel/bindings";
+import type { RuntimeCodeExecutionFactory } from "../../kernel/bindings";
 import { serializeOutput } from "../../lib/artifacts";
+import type { PiToolCandidate } from "./compiler";
+import { piCandidatesToAiTools } from "./nested-tools";
 
-// 本文件沿用 `../../index.ts` 入口定义的 Browser 和 Port 术语。
+// 本文件沿用 `../../index.ts` 入口定义的 Workspace、Port 和 Tool Candidate 术语。
 
 const CODEMODE_SANDBOX_TIMEOUT_MS = 55_000;
 
+function directoryEntry(name: string, label: string): string {
+  const singleLineLabel = label.replaceAll(/\s+/g, " ").trim().replaceAll("`", "'");
+  return `- \`${name}\` — ${singleLineLabel}`;
+}
+
+function codeExecutionDescription(
+  candidates: readonly PiToolCandidate[],
+): string {
+  const list = (
+    entries: readonly { readonly name: string; readonly label: string }[],
+  ) => entries.length > 0
+    ? entries.map(({ name, label }) => directoryEntry(name, label)).join("\n")
+    : "- None.";
+
+  return [
+    "Execute plain JavaScript in a sandbox using the exact Tool directory below.",
+    "",
+    "## `tools.*` Available",
+    list(candidates.map(({ tool }) => ({
+      name: tool.name,
+      label: tool.label ?? tool.name,
+    }))),
+    "",
+    "Call only the methods listed above through `tools.*`; never guess or construct a method name.",
+    "Use `codemode.describe(\"tools.method\")` when you need the exact input type for a listed method.",
+    "`codemode.search` cannot add methods to `tools.*` or load top-level Tools; it searches only connector methods and snippets already installed in this Code Mode Runtime.",
+    "Use `state.*` for the Workspace filesystem. Every method takes one object argument, for example `state.readFile({ path })` and `state.writeFile({ path, content })`.",
+    "Wrap raw fetch, random values, time, and other nondeterministic work in `codemode.step(name, fn)` so replay runs them once.",
+    "Some connector methods pause for approval and resume automatically. Do not re-issue paused code.",
+    "Keep all code outside connector calls and `codemode.step` deterministic.",
+    "Raw `fetch` is available inside `codemode.step(...)`; prefer connector SDKs when one owns the target.",
+    "There is no Node.js `require`, `process`, package manager, or Python runtime.",
+  ].join("\n");
+}
+
 /**
  * 宿主的 Browser Rendering 绑定，只取本仓真正用到的那一面。
  *
@@ -21,6 +66,13 @@ export interface RuntimeBrowserBinding {
   fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
 }
 
+/**
+ * 把宿主的 Worker Loader、出站网络和 Workspace 组装成代码执行 Port。
+ *
+ * Worker 宿主在具备 Durable Object state 和完整平台绑定时调用，然后把返回值交给 Runtime 工具组装。
+ *
+ * Think 的独立 execute factory 接受显式宿主参数，不要求 Agent 继承 Think；这里只借它组装 Codemode Runtime、Dynamic Worker executor 和已限定范围的 Workspace state connector。
+ */
 function result(details: unknown): AgentToolResult<unknown> {
   return {
     content: [{ type: "text", text: serializeOutput(details).text }],
@@ -28,6 +80,56 @@ function result(details: unknown): AgentToolResult<unknown> {
   };
 }
 
+function sumUsage(results: readonly AgentToolResult<unknown>[]): Usage | undefined {
+  const usages = results.flatMap(({ usage }) => usage ? [usage] : []);
+  if (usages.length === 0) return undefined;
+  return usages.reduce<Usage>((total, usage) => ({
+    input: total.input + usage.input,
+    output: total.output + usage.output,
+    cacheRead: total.cacheRead + usage.cacheRead,
+    cacheWrite: total.cacheWrite + usage.cacheWrite,
+    ...(total.cacheWrite1h === undefined && usage.cacheWrite1h === undefined
+      ? {}
+      : { cacheWrite1h: (total.cacheWrite1h ?? 0) + (usage.cacheWrite1h ?? 0) }),
+    ...(total.reasoning === undefined && usage.reasoning === undefined
+      ? {}
+      : { reasoning: (total.reasoning ?? 0) + (usage.reasoning ?? 0) }),
+    totalTokens: total.totalTokens + usage.totalTokens,
+    cost: {
+      input: total.cost.input + usage.cost.input,
+      output: total.cost.output + usage.cost.output,
+      cacheRead: total.cost.cacheRead + usage.cost.cacheRead,
+      cacheWrite: total.cost.cacheWrite + usage.cost.cacheWrite,
+      total: total.cost.total + usage.cost.total,
+    },
+  }), {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  });
+}
+
+function codeExecutionResult(
+  details: unknown,
+  innerResults: readonly AgentToolResult<unknown>[],
+): AgentToolResult<unknown> {
+  const addedToolNames = [...new Set(
+    innerResults.flatMap(({ addedToolNames }) => addedToolNames ?? []),
+  )].sort();
+  const usage = sumUsage(innerResults);
+  return {
+    ...result(details),
+    ...(addedToolNames.length > 0 ? { addedToolNames } : {}),
+    ...(usage ? { usage } : {}),
+    ...(innerResults.length > 0 && innerResults.every(({ terminate }) => terminate === true)
+      ? { terminate: true }
+      : {}),
+  };
+}
+
 // 上游把 Code Mode 类工具交付为 AI SDK tool；本仓只取 description 和 execute 两件，
 // 并在这里就地校验，使装配期缺件立刻失败，而不是等模型调用时才炸。
 function toCodeExecutionPort(
@@ -93,6 +195,7 @@ function browserToolDescription(): string {
  *
  * Worker 宿主在具备 DO state 与 Browser 绑定时调用，返回值经 Platform Port 交给 Runtime 工具组装。
  *
+ * 形状与 `createWorkspaceCodeExecutionFactory` 同构：宿主提供 DO state 与平台绑定，Runtime 只拿到一个可选装配输入。
  * `create()` 延迟到 Tool Surface 真的要注册时才调，被 deny 的装配不会白建连接器。
  */
 export function createBrowserExecutionFactory(options: {
@@ -137,3 +240,42 @@ export function createBrowserExecutionFactory(options: {
     },
   };
 }
+
+export function createWorkspaceCodeExecutionFactory(options: {
+  readonly ctx: DurableObjectState;
+  readonly loader: WorkerLoader;
+  readonly outbound: Fetcher;
+  readonly workspace: WorkspacePort;
+}): RuntimeCodeExecutionFactory {
+  return {
+    create(candidates) {
+      const description = codeExecutionDescription(candidates);
+      return {
+        description,
+        async execute(input) {
+          const innerResults: AgentToolResult<unknown>[] = [];
+          const { tool } = createExecuteRuntime({
+            ctx: options.ctx,
+            loader: options.loader,
+            globalOutbound: options.outbound,
+            tools: piCandidatesToAiTools(candidates, {
+              onResult: (value) => innerResults.push(value),
+            }),
+            description,
+            // 先于外层 60s 截止结束，给 Runtime RPC 结算和 Worker 释放留出时间。
+            timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
+            state: createWorkspaceStateBackend(
+              options.workspace as unknown as WorkspaceFsLike,
+            ),
+            name: "execute",
+          });
+          return toCodeExecutionPort(
+            tool,
+            "execute",
+            (details) => codeExecutionResult(details, innerResults),
+          ).execute(input);
+        },
+      };
+    },
+  };
+}

package/src/pi/tool/core.ts

@@ -202,7 +202,7 @@ export function listExtensionsPiToolCandidate(
 
 // #endregion
 
-// #region Browser Code Mode
+// #region Code Mode
 
 const executeParameters = Type.Object({
   code: Type.String({
@@ -213,8 +213,9 @@ const executeParameters = Type.Object({
 });
 const CODEMODE_EXECUTE_TIMEOUT_MS = 60_000;
 
-// 把模型提供的浏览器代码交给 Codemode Runtime 执行，并在外层再压一道截止。
-// `label` 只用于超时文案，因为模型看到的名字由候选项决定。
+// 把模型提供的代码交给 Codemode Runtime 执行，并在外层再压一道截止。
+// 两个 Code Mode 类工具（`execute` 与 `browser_execute`）共用同一段时序，
+// 避免两套心智模型；`label` 只用于超时文案，因为模型看到的名字由候选项决定。
 function runCodemode(
   runtime: RuntimeCodeExecutionPort,
   label: string,
@@ -253,6 +254,36 @@ function runCodemode(
   };
 }
 
+/**
+ * 把 Cloudflare Codemode Runtime handle 包装为 Pi 代码执行工具候选项。
+ *
+ * Tool Surface 收到 Host 已组装的 Code Execution Port 后调用，
+ * 模型再通过 `execute` 运行代码。
+ *
+ * Code Mode 作为一个完整的 safe 工具对外暴露，内部能力不再单独提权。
+ */
+export function codeExecutionPiToolCandidate(
+  runtime: RuntimeCodeExecutionPort,
+): PiToolCandidate {
+  const tool: AgentTool<typeof executeParameters> = {
+    name: "execute",
+    label: "Execute JavaScript",
+    description: runtime.description,
+    parameters: executeParameters,
+    // Pi 工具循环在模型选择 `execute` 时调用，调用前允许 Turn 取消。
+    // 必须通过 Runtime handle 而不是直接调用 executor，因为 Cloudflare Codemode 把重放、审批和执行日志放在持久化 Runtime 层。
+    execute: runCodemode(runtime, "Code Mode execute"),
+  };
+  return {
+    owner: "core:codemode",
+    requiredExecutionLevel: "safe",
+    outputBudget: { kind: "structure" },
+    source: "codemode",
+    summary: "Run JavaScript with network and configured connector access",
+    tool,
+  };
+}
+
 /** 模型可见的浏览器工具名；属外部契约，改名是破坏性变更。 */
 export const BROWSER_EXECUTE_TOOL_NAME = "browser_execute";
 

package/src/pi/tool/declared.ts

@@ -49,6 +49,7 @@ export interface PiDeclaredToolPolicy<Reply = unknown> {
   readonly modelName: string;
   readonly requiredExecutionLevel: PiToolCandidate["requiredExecutionLevel"];
   readonly requiredExecutionLevelForInput?: PiToolCandidate["requiredExecutionLevelForInput"];
+  readonly direct?: true;
   readonly retry?: PiToolCandidate["retry"];
   readonly source?: PiToolCandidate["source"];
   readonly summary?: string;
@@ -115,6 +116,7 @@ export function createPiDeclaredToolCandidate<Reply = unknown>(
     ...(policy.requiredExecutionLevelForInput
       ? { requiredExecutionLevelForInput: policy.requiredExecutionLevelForInput }
       : {}),
+    ...(policy.direct ? { direct: policy.direct } : {}),
     ...(policy.retry ? { retry: policy.retry } : {}),
     ...(policy.source ? { source: policy.source } : {}),
   };

package/src/pi/tool/schedule.ts

@@ -92,7 +92,7 @@ function candidate<T extends TSchema>(
   options: Partial<
     Pick<
       PiToolCandidate,
-      "alwaysRequiresApproval" | "owner" | "requiredExecutionLevel" | "summary"
+      "alwaysRequiresApproval" | "direct" | "owner" | "requiredExecutionLevel" | "summary"
     >
   > = {},
 ): PiToolCandidate {
@@ -104,6 +104,7 @@ function candidate<T extends TSchema>(
     ...(options.alwaysRequiresApproval
       ? { alwaysRequiresApproval: true }
       : {}),
+    ...(options.direct ? { direct: true } : {}),
     ...(options.summary ? { summary: options.summary } : {}),
   };
 }
@@ -133,6 +134,7 @@ export function schedulePiToolCandidates(
       },
       {
         alwaysRequiresApproval: true,
+        direct: true,
         summary: "Create a scheduled task",
       },
     ),