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

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

@@ -1,15 +1,102 @@
+import {
+  createWorkspaceStateBackend,
+  type StateBackend,
+  type WorkspaceFsLike,
+} from "@cloudflare/shell";
+import {
+  truncateResponse,
+  truncateResult,
+  type ProxyToolOutput,
+} from "@cloudflare/codemode";
 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;
+export type WorkspaceAccessMode = "none" | "read" | "write";
+const WRITE_STATE_METHODS = new Set([
+  "writeFile",
+  "writeFileBytes",
+  "appendFile",
+  "writeJson",
+  "updateJson",
+  "mkdir",
+  "replaceInFile",
+  "replaceInFiles",
+  "rm",
+  "cp",
+  "mv",
+  "symlink",
+  "createArchive",
+  "extractArchive",
+  "compressFile",
+  "decompressFile",
+  "removeTree",
+  "copyTree",
+  "moveTree",
+  "planEdits",
+  "applyEditPlan",
+  "applyEdits",
+]);
+
+export function workspaceStateBackend(
+  workspace: WorkspacePort,
+  mode: WorkspaceAccessMode,
+): StateBackend | undefined {
+  if (mode === "none") return undefined;
+  const backend = createWorkspaceStateBackend(
+    workspace as unknown as WorkspaceFsLike,
+  );
+  return new Proxy(backend, {
+    get(target, property, receiver) {
+      if (property === "writeFileBytes") return undefined;
+      if (
+        mode === "read" &&
+        typeof property === "string" &&
+        WRITE_STATE_METHODS.has(property)
+      ) {
+        return async () => {
+          throw new Error("Workspace state is read-only for this execution");
+        };
+      }
+      const value = Reflect.get(target, property, receiver);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  }) as StateBackend;
+}
+
+const SPRINGBRAND_CODE_MODE_POLICY = `## SpringBrand Workspace and Asset Policy
+
+Use state.* for every Workspace filesystem operation. Workspace file methods do not exist under tools.*.
+
+state.writeFileBytes is not available. Use state.writeFile or state.appendFile for sandbox-created text.
+
+Bundled Skill resources are not Workspace files. Read text with tools.read_skill_resource, run bundled scripts with tools.run_skill_script, and copy templates or assets with tools.materialize_skill_resource.
+
+User Attachments are not Workspace files until copied with tools.materialize_attachment.
+
+Never create or write data URLs, base64 image strings, or embedded binary payloads in Code Mode.
+
+Copy a remote asset into Workspace with tools.materialize_url({ url, destination }). Raw fetch remains available. Do not carry large responses, binary payloads, data URLs, or base64 assets through Code Mode.
+
+After materialization, reference the Workspace file by a relative path. Website HTML and CSS must reference relative Workspace assets, never temporary external URLs or data URLs.
+
+Keep large content out of the execute result. Write it to Workspace and return only path, mediaType, bytes, summary, and warnings.
+
+This execute tool cannot ask the user, inspect a rendered page, capture a screenshot, save or publish a Creation, or authorize an external action. Use the corresponding top-level Tool for those operations.`;
 
 /**
  * 宿主的 Browser Rendering 绑定，只取本仓真正用到的那一面。
@@ -21,6 +108,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 +122,92 @@ 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 }
+      : {}),
+  };
+}
+
+function projectCodeModeResult(details: unknown): unknown {
+  if (typeof details !== "object" || details === null) {
+    return { status: "error", executionId: "unknown", error: truncateResponse(String(details)) };
+  }
+  const output = details as ProxyToolOutput;
+  const calls = Array.isArray(output.calls) ? output.calls : [];
+  const callSummary = calls.length > 0
+    ? {
+        total: calls.length,
+        failed: calls.filter(({ state }) => state === "error").length,
+        methods: [...new Set(calls.map(({ method }) => method))]
+          .map((method) => truncateResponse(method, { maxChars: 256 }))
+          .slice(0, 100),
+      }
+    : undefined;
+  const common = {
+    status: output.status,
+    executionId: output.executionId,
+    ...(callSummary ? { callSummary } : {}),
+  };
+  if (output.status === "completed") {
+    return { ...common, result: truncateResult(output.result) };
+  }
+  if (output.status === "paused") {
+    return {
+      ...common,
+      pending: output.pending.slice(0, 100).map(({ connector, method, seq }) => ({
+        connector: truncateResponse(connector, { maxChars: 256 }),
+        method: truncateResponse(method, { maxChars: 256 }),
+        seq,
+      })),
+    };
+  }
+  return { ...common, error: truncateResponse(output.error) };
+}
+
 // 上游把 Code Mode 类工具交付为 AI SDK tool；本仓只取 description 和 execute 两件，
 // 并在这里就地校验，使装配期缺件立刻失败，而不是等模型调用时才炸。
 function toCodeExecutionPort(
@@ -93,6 +273,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 +318,49 @@ export function createBrowserExecutionFactory(options: {
     },
   };
 }
+
+export function createWorkspaceCodeExecutionFactory(options: {
+  readonly ctx: DurableObjectState;
+  readonly loader: WorkerLoader;
+  readonly outbound: Fetcher;
+  readonly workspace: WorkspacePort;
+  readonly workspaceAccessMode: WorkspaceAccessMode;
+}): RuntimeCodeExecutionFactory {
+  return {
+    create(candidates) {
+      const state = workspaceStateBackend(
+        options.workspace,
+        options.workspaceAccessMode,
+      );
+      const createPort = (innerResults: AgentToolResult<unknown>[]) => {
+        let nestedCallOrdinal = 0;
+        const { tool } = createExecuteRuntime({
+          ctx: options.ctx,
+          loader: options.loader,
+          globalOutbound: options.outbound,
+          tools: piCandidatesToAiTools(candidates, {
+            fallbackToolCallId: (name) =>
+              `codemode:${++nestedCallOrdinal}:${name}`,
+            onResult: (value) => innerResults.push(value),
+          }),
+          timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
+          ...(state ? { state } : {}),
+          name: "execute",
+        });
+        return toCodeExecutionPort(
+          tool,
+          "execute",
+          (details) => codeExecutionResult(
+            projectCodeModeResult(details),
+            innerResults,
+          ),
+        );
+      };
+      const description = createPort([]).description;
+      return {
+        description: `${description}\n\n${SPRINGBRAND_CODE_MODE_POLICY}`,
+        execute: (input) => createPort([]).execute(input),
+      };
+    },
+  };
+}

package/src/pi/tool/core.ts

@@ -165,7 +165,7 @@ function browserResult(details: unknown): AgentToolResult<unknown> {
 
 // #region Extension discovery
 
-const noParameters = Type.Object({});
+const noParameters = Type.Object({}, { additionalProperties: false });
 
 /**
  * 为当前已加载 Extension 列表创建一个 Pi 工具候选项。
@@ -202,19 +202,21 @@ export function listExtensionsPiToolCandidate(
 
 // #endregion
 
-// #region Browser Code Mode
+// #region Code Mode
 
 const executeParameters = Type.Object({
   code: Type.String({
     minLength: 1,
+    maxLength: 131_072,
     description:
       "Plain JavaScript async function. TypeScript annotations are not supported.",
   }),
-});
+}, { additionalProperties: false });
 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 +255,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 exposureMode?: PiToolCandidate["exposureMode"];
   readonly retry?: PiToolCandidate["retry"];
   readonly source?: PiToolCandidate["source"];
   readonly summary?: string;
@@ -104,6 +105,7 @@ export function createPiDeclaredToolCandidate<Reply = unknown>(
     parameters: structuredClone(
       declared.inputSchema ?? { type: "object", additionalProperties: true },
     ) as AgentTool["parameters"],
+    constrainedSampling: false,
     execute: async (toolCallId, input, signal) =>
       project(await call(input as Record<string, unknown>, { toolCallId, signal })),
   };
@@ -115,6 +117,7 @@ export function createPiDeclaredToolCandidate<Reply = unknown>(
     ...(policy.requiredExecutionLevelForInput
       ? { requiredExecutionLevelForInput: policy.requiredExecutionLevelForInput }
       : {}),
+    ...(policy.exposureMode ? { exposureMode: policy.exposureMode } : {}),
     ...(policy.retry ? { retry: policy.retry } : {}),
     ...(policy.source ? { source: policy.source } : {}),
   };

package/src/pi/tool/nested-tools.ts

@@ -35,7 +35,11 @@ export function piCandidatesToAiTools(
           call?.abortSignal ?? new AbortController().signal,
         );
         options.onResult?.(result);
-        return result;
+        if (result.details !== undefined) return result.details;
+        const [only] = result.content;
+        return result.content.length === 1 && only?.type === "text"
+          ? only.text
+          : result.content;
       },
     }),
   ]));

package/src/pi/tool/schedule.ts

@@ -18,28 +18,28 @@ const scheduleTriggerParameters = Type.Union([
       minimum: 1,
       description: "Fire once, this many seconds from now.",
     }),
-  }),
+  }, { additionalProperties: false }),
   Type.Object({
     kind: Type.Literal("once-at"),
     at: Type.String({
       description:
         "Fire once at this absolute UTC ISO time, e.g. 2026-07-20T09:00:00Z.",
     }),
-  }),
+  }, { additionalProperties: false }),
   Type.Object({
     kind: Type.Literal("cron"),
     cron: Type.String({
       description:
         "Repeat on a standard UTC cron, e.g. '0 9 * * *' = daily 09:00 UTC.",
     }),
-  }),
+  }, { additionalProperties: false }),
   Type.Object({
     kind: Type.Literal("interval"),
     seconds: Type.Integer({
       minimum: 1,
       description: "Repeat every this many seconds.",
     }),
-  }),
+  }, { additionalProperties: false }),
 ], { description: "When to fire." });
 
 const scheduleParameters = Type.Object({
@@ -56,21 +56,21 @@ const scheduleParameters = Type.Object({
     description:
       "IANA timezone the clock times in `trigger` should be interpreted in, e.g. 'Asia/Shanghai'. Pass the user's own timezone whenever they state a wall-clock time. Omit only for delays and intervals. Defaults to UTC.",
   })),
-});
+}, { additionalProperties: false });
 
-const noParameters = Type.Object({});
+const noParameters = Type.Object({}, { additionalProperties: false });
 const scheduleIdParameters = Type.Object({
   id: Type.String({
     description: "The schedule id, as returned by `list_schedules`.",
   }),
-});
+}, { additionalProperties: false });
 const updateScheduleParameters = Type.Object({
   id: Type.String({ description: "The exact id returned by `list_schedules`." }),
   prompt: Type.Optional(Type.String()),
   trigger: Type.Optional(scheduleTriggerParameters),
   label: Type.Optional(Type.String()),
   timezone: Type.Optional(Type.String()),
-});
+}, { additionalProperties: false });
 const changeScheduleAgentParameters = Type.Object({
   id: Type.String({
     description: "The exact schedule id returned by `list_schedules`.",
@@ -78,7 +78,7 @@ const changeScheduleAgentParameters = Type.Object({
   userAgentId: Type.String({
     description: "The exact User Agent id selected by the user.",
   }),
-});
+}, { additionalProperties: false });
 
 function result<T>(details: T): AgentToolResult<T> {
   return {
@@ -92,12 +92,13 @@ function candidate<T extends TSchema>(
   options: Partial<
     Pick<
       PiToolCandidate,
-      "alwaysRequiresApproval" | "owner" | "requiredExecutionLevel" | "summary"
+      "alwaysRequiresApproval" | "exposureMode" | "owner" | "requiredExecutionLevel" | "summary"
     >
   > = {},
 ): PiToolCandidate {
   return {
     owner: options.owner ?? "runtime-base",
+    exposureMode: options.exposureMode ?? "direct",
     requiredExecutionLevel: options.requiredExecutionLevel ?? "safe",
     source: "action",
     tool,
@@ -133,6 +134,7 @@ export function schedulePiToolCandidates(
       },
       {
         alwaysRequiresApproval: true,
+        exposureMode: "direct",
         summary: "Create a scheduled task",
       },
     ),