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

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

@@ -1,61 +1,16 @@
-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` 入口定义的 Workspace、Port 和 Tool Candidate 术语。
+// 本文件沿用 `../../index.ts` 入口定义的 Browser 和 Port 术语。
 
 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 绑定，只取本仓真正用到的那一面。
  *
@@ -66,13 +21,6 @@ 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 }],
@@ -80,56 +28,6 @@ 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(
@@ -195,7 +93,6 @@ function browserToolDescription(): string {
  *
  * Worker 宿主在具备 DO state 与 Browser 绑定时调用，返回值经 Platform Port 交给 Runtime 工具组装。
  *
- * 形状与 `createWorkspaceCodeExecutionFactory` 同构：宿主提供 DO state 与平台绑定，Runtime 只拿到一个可选装配输入。
  * `create()` 延迟到 Tool Surface 真的要注册时才调，被 deny 的装配不会白建连接器。
  */
 export function createBrowserExecutionFactory(options: {
@@ -240,42 +137,3 @@ 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 Code Mode
+// #region Browser Code Mode
 
 const executeParameters = Type.Object({
   code: Type.String({
@@ -213,9 +213,8 @@ const executeParameters = Type.Object({
 });
 const CODEMODE_EXECUTE_TIMEOUT_MS = 60_000;
 
-// 把模型提供的代码交给 Codemode Runtime 执行，并在外层再压一道截止。
-// 两个 Code Mode 类工具（`execute` 与 `browser_execute`）共用同一段时序，
-// 避免两套心智模型；`label` 只用于超时文案，因为模型看到的名字由候选项决定。
+// 把模型提供的浏览器代码交给 Codemode Runtime 执行，并在外层再压一道截止。
+// `label` 只用于超时文案，因为模型看到的名字由候选项决定。
 function runCodemode(
   runtime: RuntimeCodeExecutionPort,
   label: string,
@@ -254,36 +253,6 @@ 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,7 +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,7 +115,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" | "direct" | "owner" | "requiredExecutionLevel" | "summary"
+      "alwaysRequiresApproval" | "owner" | "requiredExecutionLevel" | "summary"
     >
   > = {},
 ): PiToolCandidate {
@@ -104,7 +104,6 @@ function candidate<T extends TSchema>(
     ...(options.alwaysRequiresApproval
       ? { alwaysRequiresApproval: true }
       : {}),
-    ...(options.direct ? { direct: true } : {}),
     ...(options.summary ? { summary: options.summary } : {}),
   };
 }
@@ -134,7 +133,6 @@ export function schedulePiToolCandidates(
       },
       {
         alwaysRequiresApproval: true,
-        direct: true,
         summary: "Create a scheduled task",
       },
     ),

package/src/pi/tool/skill.ts

@@ -93,7 +93,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 tools.materialize_skill_resource: ` +
+      `in one materialize_skill_resource call using its resources array: ` +
       `${portable.map((entry) => entry.path).join(", ")}.`,
     );
   }
@@ -175,6 +175,21 @@ const SKILL_TOOL_LABELS: Readonly<Record<string, string>> = {
   materialize_skill_resource: "Materialize Skill resource",
 };
 
+const SKILL_TOOL_PARAMETER_DESCRIPTIONS: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+  activate_skill: {
+    name: "Exact name of the available Skill to activate.",
+  },
+  read_skill_resource: {
+    name: "Name of the activated Skill. Omit only when path starts with the Skill name.",
+    path: "Bundled resource path listed by activate_skill.",
+  },
+  run_skill_script: {
+    name: "Name of the activated Skill that supplies the script.",
+    path: "Bundled script path listed by activate_skill.",
+    input: "JSON input expected by the Skill script. Defaults to an empty object.",
+  },
+};
+
 const SKILL_ENTRY_READ_GUIDANCE =
   "SKILL.md contains the Skill instructions; use activate_skill instead.";
 
@@ -196,44 +211,95 @@ function materializeSkillResourceTool(
 ) {
   const names = bindings.map(({ name }) => name) as [string, ...string[]];
   const byName = new Map(bindings.map((binding) => [binding.name, binding]));
+  const resourceInput = z.object({
+    name: z.enum(names).describe("Activated Skill name"),
+    path: z.string().min(1).describe("Bundled resource path listed by activate_skill"),
+    destination: z.string().min(1).startsWith("/").describe(
+      "Absolute destination path in the Workspace",
+    ),
+  });
   return tool({
     description:
-      "Copy a complete bundled Skill resource directly into the Workspace without returning its contents to the model. " +
+      "Copy complete bundled Skill resources directly into the Workspace without returning their contents to the model. " +
       "Use this instead of read_skill_resource when a template, script, image, font, or other asset must become a Workspace file. " +
-      "When multiple resources are needed, copy them in one execute with a loop or Promise.all; never start one execute per resource. " +
+      "Pass every required item in the resources array; items are copied in order and failures are reported per item. " +
       "The destination is created or overwritten, including parent directories.",
     inputSchema: z.object({
-      name: z.enum(names).describe("Activated Skill name"),
-      path: z.string().min(1).describe("Bundled resource path listed by activate_skill"),
-      destination: z.string().min(1).describe("Absolute destination path in the Workspace"),
+      resources: z.array(resourceInput).min(1).max(100),
     }),
-    execute: async ({ name, path, destination }, { abortSignal }) => {
+    execute: async ({ resources }, { abortSignal }) => {
       abortSignal?.throwIfAborted();
-      const source = byName.get(name)?.source;
-      if (!source?.readResource) {
-        throw new Error(`Skill \"${name}\" has no readable resources.`);
+      const destinations = new Set<string>();
+      for (const { destination } of resources) {
+        if (destinations.has(destination)) {
+          throw new Error(`Duplicate materialize destination: ${destination}`);
+        }
+        destinations.add(destination);
       }
-      const resource = await source.readResource(name, path);
-      if (!resource) throw new Error(`Resource not found: ${name}/${path}`);
-      abortSignal?.throwIfAborted();
-      const bytes = resourceBytes(resource);
 
-      await serializeWorkspaceMutation(workspace, destination, async () => {
+      const results: Array<Record<string, unknown>> = [];
+      for (const { name, path, destination } of resources) {
         abortSignal?.throwIfAborted();
-        const parent = destination.replace(/\/[^/]+$/, "");
-        if (parent && parent !== "/") {
-          await workspace.mkdir(parent, { recursive: true });
+        const source = byName.get(name)?.source;
+        if (!source?.readResource) {
+          results.push({
+            status: "error",
+            name,
+            path,
+            destination,
+            error: `Skill \"${name}\" has no readable resources.`,
+          });
+          continue;
+        }
+        try {
+          const resource = await source.readResource(name, path);
+          if (!resource) {
+            results.push({
+              status: "error",
+              name,
+              path,
+              destination,
+              error: `Resource not found: ${name}/${path}`,
+            });
+            continue;
+          }
+          abortSignal?.throwIfAborted();
+          const bytes = resourceBytes(resource);
+
+          await serializeWorkspaceMutation(workspace, destination, async () => {
+            abortSignal?.throwIfAborted();
+            const parent = destination.replace(/\/[^/]+$/, "");
+            if (parent && parent !== "/") {
+              await workspace.mkdir(parent, { recursive: true });
+            }
+            await workspace.writeFileBytes(destination, bytes, resource.mimeType);
+          });
+
+          results.push({
+            status: "written",
+            name,
+            path: resource.path,
+            destination,
+            bytesWritten: bytes.byteLength,
+            encoding: resource.encoding ?? "text",
+            ...(resource.mimeType ? { mimeType: resource.mimeType } : {}),
+          });
+        } catch (error) {
+          abortSignal?.throwIfAborted();
+          results.push({
+            status: "error",
+            name,
+            path,
+            destination,
+            error: "Resource materialization failed",
+          });
         }
-        await workspace.writeFileBytes(destination, bytes, resource.mimeType);
-      });
+      }
 
       return {
-        name,
-        path: resource.path,
-        destination,
-        bytesWritten: bytes.byteLength,
-        encoding: resource.encoding ?? "text",
-        ...(resource.mimeType ? { mimeType: resource.mimeType } : {}),
+        written: results.filter(({ status }) => status === "written").length,
+        failed: results.filter(({ status }) => status === "error").length,
+        results,
       };
     },
   });
@@ -270,6 +336,17 @@ export async function skillPiToolCandidates(
           }
         : {}),
     });
+    const properties = (adapted.parameters as { properties?: unknown }).properties;
+    if (properties && typeof properties === "object" && !Array.isArray(properties)) {
+      for (const [parameter, description] of Object.entries(
+        SKILL_TOOL_PARAMETER_DESCRIPTIONS[name] ?? {},
+      )) {
+        const schema = (properties as Record<string, unknown>)[parameter];
+        if (schema && typeof schema === "object" && !Array.isArray(schema)) {
+          (schema as Record<string, unknown>).description ??= description;
+        }
+      }
+    }
     if (name === "read_skill_resource") {
       const execute = adapted.execute;
       adapted.execute = (toolCallId, input, signal) => {
@@ -303,9 +380,6 @@ export async function skillPiToolCandidates(
       ...(name === "activate_skill"
         ? { outputBudget: { kind: "structure" as const } }
         : {}),
-      ...(name === "materialize_skill_resource"
-        ? { codeExecutionOnly: true as const }
-        : {}),
       tool: adapted,
     };
   });

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

@@ -70,9 +70,16 @@ const workspaceReadParameters = Type.Object({
   })),
 });
 const workspaceEditParameters = Type.Object({
-  path: Type.String({ minLength: 1, maxLength: 4_096 }),
-  old_string: Type.String(),
-  new_string: Type.String(),
+  path: Type.String({
+    minLength: 1,
+    maxLength: 4_096,
+    description: "Absolute Workspace path of the file to edit.",
+  }),
+  old_string: Type.String({
+    description:
+      "Exact existing text to replace. Include enough surrounding context to match one location.",
+  }),
+  new_string: Type.String({ description: "Replacement text." }),
 });
 
 /**
@@ -430,24 +437,47 @@ export function workspacePiToolCandidates(
 // #region Sandbox tools
 
 const sandboxCommandParameters = {
-  command: Type.String({ minLength: 1, maxLength: 32_768 }),
-  cwd: Type.Optional(Type.String({ maxLength: 4_096 })),
-  stdin: Type.Optional(Type.String({ maxLength: 65_536 })),
+  command: Type.String({
+    minLength: 1,
+    maxLength: 32_768,
+    description: "Shell command to run in the isolated Linux Sandbox.",
+  }),
+  cwd: Type.Optional(Type.String({
+    maxLength: 4_096,
+    description: "Sandbox working directory. Omit to use the Sandbox default.",
+  })),
+  stdin: Type.Optional(Type.String({
+    maxLength: 65_536,
+    description: "Optional text to pass to the command on standard input.",
+  })),
 };
 const sandboxExecParameters = Type.Object({
   ...sandboxCommandParameters,
   timeoutMs: Type.Optional(
-    Type.Integer({ minimum: 1, maximum: 60_000 }),
+    Type.Integer({
+      minimum: 1,
+      maximum: 60_000,
+      description: "Maximum command runtime in milliseconds, from 1 to 60000.",
+    }),
   ),
 });
 const sandboxStartParameters = Type.Object(sandboxCommandParameters);
 const sandboxProcessParameters = Type.Object({
-  id: Type.String({ minLength: 1, maxLength: 128 }),
+  id: Type.String({
+    minLength: 1,
+    maxLength: 128,
+    description: "Process ID returned by sandbox_start_process.",
+  }),
 });
 const sandboxPublishParameters = Type.Object({
-  paths: Type.Array(Type.String({ minLength: 1, maxLength: 4_096 }), {
+  paths: Type.Array(Type.String({
+    minLength: 1,
+    maxLength: 4_096,
+    description: "Sandbox file path to publish.",
+  }), {
     minItems: 1,
     maxItems: 100,
+    description: "Files to copy from the temporary Sandbox into the persistent Workspace.",
   }),
 });
 

package/src/runtime-agent.ts

@@ -672,9 +672,6 @@ export function defineRuntimeAgent<
             ...(assembly.bindings?.workspace
               ? { workspace: assembly.bindings.workspace }
               : {}),
-            ...(assembly.bindings?.codeExecution
-              ? { codeExecution: assembly.bindings.codeExecution }
-              : {}),
           },
           memoryProfile: {
             enabled: false,