@springbrand/agent-runtime 0.2.0-alpha.34 → 0.2.0-alpha.36

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

@@ -4,24 +4,57 @@ import {
 } from "@cloudflare/shell";
 import { createBrowserTools } from "@cloudflare/think/tools/browser";
 import { createExecuteRuntime } from "@cloudflare/think/tools/execute";
-import { jsonSchema, tool as aiTool, type ToolSet } from "ai";
+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,
-  ToolRegistry,
-} from "../../tool-registry";
+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 术语。
 
 const CODEMODE_SANDBOX_TIMEOUT_MS = 55_000;
-const CODEMODE_TOOL_SURFACE_GUIDANCE =
-  "The `tools.*` Available list below is exhaustive, not examples. Inside execute, call only methods in that list; " +
-  "never guess or construct a `tools.*` method name. If a required Tool is absent, leave execute and call it at the top level, " +
-  "using top-level Tool Search first when it is deferred. `codemode.search` cannot add methods to `tools.*`.";
+
+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 绑定，只取本仓真正用到的那一面。
@@ -40,26 +73,61 @@ export interface RuntimeBrowserBinding {
  *
  * Think 的独立 execute factory 接受显式宿主参数，不要求 Agent 继承 Think；这里只借它组装 Codemode Runtime、Dynamic Worker executor 和已限定范围的 Workspace state connector。
  */
-function codeExecutionTools(tools: ToolRegistry): ToolSet {
-  return Object.fromEntries(Object.entries(tools).map(([name, spec]) => [
-    name,
-    aiTool({
-      description: spec.description,
-      inputSchema: jsonSchema(spec.parameters as never),
-      execute: async (input, options) => {
-        const result = await spec.execute(input, {
-          toolCallId: options?.toolCallId ?? name,
-          signal: options?.abortSignal ?? new AbortController().signal,
-        });
-        return result != null &&
-            typeof result === "object" &&
-            "content" in result &&
-            Array.isArray((result as { content?: unknown }).content)
-          ? (result as { details?: unknown }).details ?? result
-          : result;
-      },
-    }),
-  ]));
+function result(details: unknown): AgentToolResult<unknown> {
+  return {
+    content: [{ type: "text", text: serializeOutput(details).text }],
+    details,
+  };
+}
+
+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 两件，
@@ -67,6 +135,7 @@ function codeExecutionTools(tools: ToolRegistry): ToolSet {
 function toCodeExecutionPort(
   tool: ToolSet[string],
   name: string,
+  project: (details: unknown) => AgentToolResult<unknown> = result,
 ): RuntimeCodeExecutionPort {
   const { description, execute } = tool;
   if (typeof description !== "string" || description.length === 0) {
@@ -77,7 +146,7 @@ function toCodeExecutionPort(
   }
   return {
     description,
-    execute: (input) => Promise.resolve(execute(input, {
+    execute: async (input) => project(await execute(input, {
       toolCallId: name,
       messages: [],
       context: undefined,
@@ -179,26 +248,33 @@ export function createWorkspaceCodeExecutionFactory(options: {
   readonly workspace: WorkspacePort;
 }): RuntimeCodeExecutionFactory {
   return {
-    create(tools) {
-      const { tool } = createExecuteRuntime({
-        ctx: options.ctx,
-        loader: options.loader,
-        globalOutbound: options.outbound,
-        tools: codeExecutionTools(tools),
-        // 先于外层 60s 截止结束，给 Runtime RPC 结算和 Worker 释放留出时间。
-        timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
-        state: createWorkspaceStateBackend(
-          options.workspace as unknown as WorkspaceFsLike,
-        ),
-        name: "execute",
-      });
-      const port = toCodeExecutionPort(tool, "execute");
+    create(candidates) {
+      const description = codeExecutionDescription(candidates);
       return {
-        ...port,
-        description: `${CODEMODE_TOOL_SURFACE_GUIDANCE}\n\n${port.description.replace(
-          "- Do not use `fetch` — use connector SDKs.",
-          "- Raw `fetch` is available inside `codemode.step(...)`; prefer connector SDKs when one owns the target.",
-        )}`,
+        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

@@ -219,7 +219,8 @@ const CODEMODE_EXECUTE_TIMEOUT_MS = 60_000;
 function runCodemode(
   runtime: RuntimeCodeExecutionPort,
   label: string,
-  project: (details: unknown) => AgentToolResult<unknown> = result,
+  project: (result: AgentToolResult<unknown>) => AgentToolResult<unknown> =
+    (result) => result,
 ): AgentTool<typeof executeParameters>["execute"] {
   return async (_toolCallId, input, signal) => {
     signal?.throwIfAborted();
@@ -245,7 +246,7 @@ function runCodemode(
     try {
       return project(await Promise.race([
         runtime.execute(input),
-        deadline,
+        deadline.then(result),
       ]));
     } finally {
       if (timeout !== undefined) clearTimeout(timeout);
@@ -303,7 +304,11 @@ export function browserExecutionPiToolCandidate(
     label: "Drive a browser",
     description: runtime.description,
     parameters: executeParameters,
-    execute: runCodemode(runtime, "Browser Code Mode execute", browserResult),
+    execute: runCodemode(
+      runtime,
+      "Browser Code Mode execute",
+      ({ details }) => browserResult(details),
+    ),
   };
   return {
     owner: "core:browser",

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

@@ -0,0 +1,42 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { validateToolArguments } from "@earendil-works/pi-ai";
+import { jsonSchema, tool as aiTool, type ToolSet } from "ai";
+import type { PiToolCandidate } from "./compiler";
+
+interface NestedToolOptions {
+  readonly fallbackToolCallId?: (name: string) => string;
+  readonly onResult?: (result: AgentToolResult<unknown>) => void;
+}
+
+/** The one Pi candidate to AI SDK ToolSet adapter used by nested runtimes. */
+export function piCandidatesToAiTools(
+  candidates: readonly PiToolCandidate[],
+  options: NestedToolOptions,
+): ToolSet {
+  return Object.fromEntries(candidates.map((candidate) => [
+    candidate.tool.name,
+    aiTool({
+      description: candidate.tool.description,
+      inputSchema: jsonSchema(candidate.tool.parameters as never),
+      execute: async (input, call) => {
+        const toolCallId = call?.toolCallId ??
+          options.fallbackToolCallId?.(candidate.tool.name) ??
+          candidate.tool.name;
+        const prepared = candidate.tool.prepareArguments?.(input) ?? input;
+        const args = validateToolArguments(candidate.tool, {
+          type: "toolCall",
+          id: toolCallId,
+          name: candidate.tool.name,
+          arguments: prepared as Record<string, unknown>,
+        });
+        const result = await candidate.tool.execute(
+          toolCallId,
+          args,
+          call?.abortSignal ?? new AbortController().signal,
+        );
+        options.onResult?.(result);
+        return result;
+      },
+    }),
+  ]));
+}

package/src/pi/tool/schedule.ts

@@ -10,10 +10,6 @@ import type {
 import type { ScheduleSpec } from "../../kernel/receipts";
 import { serializeOutput } from "../../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
-import {
-  toolRegistryFromPiCandidates,
-  type ToolRegistry,
-} from "../../tool-registry";
 
 const scheduleTriggerParameters = Type.Union([
   Type.Object({
@@ -259,8 +255,3 @@ export function schedulePiToolCandidates(
 }
 
 /** 从 {@link RuntimeSchedulePort} 生成定时任务 Tool 集。 */
-export function createScheduleTools(
-  schedule: RuntimeSchedulePort,
-): ToolRegistry {
-  return toolRegistryFromPiCandidates(schedulePiToolCandidates(schedule));
-}

package/src/pi/tool/skill.ts

@@ -6,7 +6,7 @@ import {
   type SkillScriptRunner,
   type SkillSource,
 } from "agents/skills";
-import { jsonSchema, tool, type ToolSet } from "ai";
+import { tool } from "ai";
 import { z } from "zod";
 import type {
   RuntimeSkillScriptPolicy,
@@ -14,6 +14,7 @@ import type {
 } from "../../kernel/bindings";
 import { aiToolToPi } from "./ai-adapter";
 import type { PiToolCandidate } from "./compiler";
+import { piCandidatesToAiTools } from "./nested-tools";
 import { serializeWorkspaceMutation } from "./workspace-sandbox";
 
 /** A configured Skill source and its script capabilities. */
@@ -31,25 +32,6 @@ export interface SkillPiToolOptions {
   readonly tools?: readonly PiToolCandidate[];
 }
 
-function scriptTools(
-  candidates: readonly PiToolCandidate[],
-  names: readonly string[],
-): ToolSet {
-  const byName = new Map(
-    candidates.map((candidate) => [candidate.tool.name, candidate.tool]),
-  );
-  return Object.fromEntries(names.flatMap((name) => {
-    const candidate = byName.get(name);
-    if (!candidate) return [];
-    return [[name, {
-      description: candidate.description,
-      inputSchema: jsonSchema(candidate.parameters as never),
-      execute: async (input: unknown) =>
-        (await candidate.execute(`skill-script:${name}`, input)).details,
-    }]];
-  })) as ToolSet;
-}
-
 /**
  * `run_skill_script` 一次挂载的 Skill 资源总量上限。
  *
@@ -166,6 +148,10 @@ function scriptRunner(
       const workspace = policy.workspace !== "none" && options.workspace
         ? policy.workspace
         : "none";
+      let toolCallOrdinal = 0;
+      const selected = (options.tools ?? []).filter(({ tool }) =>
+        policy.tools.includes(tool.name)
+      );
       return createSkillScriptRunner({
         loader: options.loader!,
         network: policy.network === "full",
@@ -173,7 +159,10 @@ function scriptRunner(
         ...(workspace !== "none" && options.workspace
           ? { workspaceInstance: options.workspace }
           : {}),
-        tools: scriptTools(options.tools ?? [], policy.tools),
+        tools: piCandidatesToAiTools(selected, {
+          fallbackToolCallId: (name) =>
+            `skill-script:${++toolCallOrdinal}:${name}`,
+        }),
       }).run(request);
     },
   };

package/src/pi/tool/subagent.ts

@@ -13,10 +13,6 @@ import {
   subagentTerminalStatus,
 } from "../../kernel/subagent-runtime";
 import type { PiToolCandidate } from "./compiler";
-import {
-  toolRegistryFromPiCandidates,
-  type ToolRegistry,
-} from "../../tool-registry";
 
 const BACKGROUND_MAX_BUDGET_MS = 10 * 60 * 1_000;
 
@@ -275,12 +271,3 @@ export function subagentPiToolCandidates(
 }
 
 /** 从 {@link RuntimeSubagentPort} 生成已启用 SubAgent Tool 集。 */
-export function createSubagentTools(
-  subagents: RuntimeSubagentPort | undefined,
-  enabledSubagents: readonly string[],
-  lifecycle?: RuntimeSubagentLifecyclePort,
-): ToolRegistry {
-  return toolRegistryFromPiCandidates(
-    subagentPiToolCandidates(subagents, enabledSubagents, lifecycle),
-  );
-}

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

@@ -2,10 +2,6 @@ import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
 import type { WorkspaceRevisionRestorePort } from "../../workspace-versioning";
 import { serializeOutput } from "../../lib/artifacts";
-import {
-  toolRegistryFromPiCandidates,
-  type ToolRegistry,
-} from "../../tool-registry";
 import type { PiToolCandidate } from "./compiler";
 
 const parameters = Type.Object({
@@ -54,11 +50,3 @@ export function workspaceRevisionPiToolCandidate(
     summary: "Restore the Workspace tree",
   };
 }
-
-export function createWorkspaceRevisionTools(
-  versions: WorkspaceRevisionRestorePort,
-): ToolRegistry {
-  return toolRegistryFromPiCandidates([
-    workspaceRevisionPiToolCandidate(versions),
-  ]);
-}

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

@@ -21,10 +21,6 @@ import type {
 import { serializeOutput } from "../../lib/artifacts";
 import { aiToolToPi } from "./ai-adapter";
 import type { PiToolCandidate } from "./compiler";
-import {
-  toolRegistryFromPiCandidates,
-  type ToolRegistry,
-} from "../../tool-registry";
 
 // #region Shared Pi result helpers
 
@@ -428,9 +424,6 @@ export function workspacePiToolCandidates(
 }
 
 /** 从 {@link WorkspacePort} 生成标准 workspace 文件 Tool 集（read / write / edit …）。 */
-export function createWorkspaceTools(workspace: WorkspacePort): ToolRegistry {
-  return toolRegistryFromPiCandidates(workspacePiToolCandidates(workspace));
-}
 
 // #endregion
 
@@ -625,8 +618,5 @@ export function sandboxPiToolCandidates(
 }
 
 /** 从 {@link RuntimeSandboxPort} 生成 Sandbox Tool 集。 */
-export function createSandboxTools(sandbox: RuntimeSandboxPort): ToolRegistry {
-  return toolRegistryFromPiCandidates(sandboxPiToolCandidates(sandbox));
-}
 
 // #endregion

package/src/runtime-agent.ts

@@ -36,12 +36,8 @@ import {
 import type {
   ResolvedResources,
   RuntimeAgentHooks,
+  ToolAssemblyResult,
 } from "./runtime-definition";
-import {
-  normalizeToolAssembly,
-  type ToolAssemblyResult,
-  type ToolRegistry,
-} from "./tool-registry";
 import type { RuntimeAssemblyView } from "./kernel/runtime-assembly-view";
 import type { RuntimeConfigUpdateResult } from "./kernel/runtime-config";
 import {
@@ -108,7 +104,7 @@ interface RuntimeAgentDefinitionBase<
   readonly tools: (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
     config: Config,
-  ) => ToolRegistry | ToolAssemblyResult | Promise<ToolRegistry | ToolAssemblyResult>;
+  ) => ToolAssemblyResult | Promise<ToolAssemblyResult>;
 
   readonly hooks?:
     | RuntimeAgentHooks<Env, Config, Command, Change>
@@ -628,16 +624,16 @@ export function defineRuntimeAgent<
             const context = this.createDefinitionContext({
               value: loaded.config,
             });
-            let tools = normalizeToolAssembly(await withRuntimeLoadTimeout(
+            let tools = await withRuntimeLoadTimeout(
               "definition.tools",
               () => (
                 definition.tools as (
                   context: RuntimeAgentPlanningContext<Env, Command, Change>,
                   config: Config,
-                ) => ToolRegistry | ToolAssemblyResult | Promise<ToolRegistry | ToolAssemblyResult>
+                ) => ToolAssemblyResult | Promise<ToolAssemblyResult>
               )(context, loaded.config),
               { timeoutMs: RUNTIME_LOAD_TIMEOUT_MS },
-            ));
+            );
             let hooks = resolveDefinitionHooks(context);
             if (!this.telemetryResolved) {
               this.resolvedTelemetry = resolveDefinitionTelemetry(context);