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

package/src/pi/tool/skill.ts

@@ -46,6 +46,12 @@ const SKILL_RESOURCE_BUDGET_BYTES = 8 * 1024 * 1024;
 
 type LoadedSkill = NonNullable<Awaited<ReturnType<SkillSource["load"]>>>;
 
+const SKILL_RESOURCE_READ_GUIDANCE =
+  "Bundled Skill resources are not Workspace files. " +
+  "Use read_skill_resource for text instead of read, bash, or find on /skills.";
+const SKILL_RESOURCE_MATERIALIZE_GUIDANCE =
+  "Use materialize_skill_resource for Workspace assets when that Tool is available.";
+
 /**
  * 按体积裁掉超预算的 Skill 资源，并把裁掉的事实写回 Skill 正文。
  *
@@ -93,7 +99,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 materialize_skill_resource call using its resources array: ` +
+      `in one execute with tools.materialize_skill_resource: ` +
       `${portable.map((entry) => entry.path).join(", ")}.`,
     );
   }
@@ -121,7 +127,21 @@ function catalogSkillSource(binding: PiSkillBinding): SkillSource {
     }],
     load: async (name) => {
       const skill = await source.load(name);
-      return skill && budgetSkillResources(skill);
+      if (!skill) return null;
+      const loaded = budgetSkillResources(skill);
+      const hasOversizedResource = skill.resources?.some((resource) =>
+        typeof resource.size === "number" &&
+        resource.size > SKILL_RESOURCE_BUDGET_BYTES
+      );
+      const guidance = hasOversizedResource
+        ? SKILL_RESOURCE_READ_GUIDANCE
+        : `${SKILL_RESOURCE_READ_GUIDANCE} ${SKILL_RESOURCE_MATERIALIZE_GUIDANCE}`;
+      return loaded.resources?.length
+        ? {
+            ...loaded,
+            body: `${loaded.body}\n\n${guidance}`,
+          }
+        : loaded;
     },
     ...(source.readResource
       ? { readResource: (name: string, path: string) =>
@@ -193,6 +213,20 @@ const SKILL_TOOL_PARAMETER_DESCRIPTIONS: Readonly<Record<string, Readonly<Record
 const SKILL_ENTRY_READ_GUIDANCE =
   "SKILL.md contains the Skill instructions; use activate_skill instead.";
 
+function normalizeRunSkillScriptArguments(input: unknown): unknown {
+  if (input === null || typeof input !== "object") return input;
+  const value = input as Record<string, unknown>;
+  if (typeof value.input !== "string") return input;
+  try {
+    const decoded = JSON.parse(value.input);
+    return decoded !== null && typeof decoded === "object"
+      ? { ...value, input: decoded }
+      : input;
+  } catch {
+    return input;
+  }
+}
+
 function resourceBytes(resource: SkillResource): Uint8Array {
   if ((resource.encoding ?? "text") === "text") {
     return new TextEncoder().encode(resource.content);
@@ -211,95 +245,44 @@ 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 complete bundled Skill resources directly into the Workspace without returning their contents to the model. " +
+      "Copy a complete bundled Skill resource directly into the Workspace without returning its 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. " +
-      "Pass every required item in the resources array; items are copied in order and failures are reported per item. " +
+      "When multiple resources are needed, copy them in one execute with a loop or Promise.all; never start one execute per resource. " +
       "The destination is created or overwritten, including parent directories.",
     inputSchema: z.object({
-      resources: z.array(resourceInput).min(1).max(100),
+      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"),
     }),
-    execute: async ({ resources }, { abortSignal }) => {
+    execute: async ({ name, path, destination }, { abortSignal }) => {
       abortSignal?.throwIfAborted();
-      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 source = byName.get(name)?.source;
+      if (!source?.readResource) {
+        throw new Error(`Skill \"${name}\" has no readable resources.`);
       }
+      const resource = await source.readResource(name, path);
+      if (!resource) throw new Error(`Resource not found: ${name}/${path}`);
+      abortSignal?.throwIfAborted();
+      const bytes = resourceBytes(resource);
 
-      const results: Array<Record<string, unknown>> = [];
-      for (const { name, path, destination } of resources) {
+      await serializeWorkspaceMutation(workspace, destination, async () => {
         abortSignal?.throwIfAborted();
-        const source = byName.get(name)?.source;
-        if (!source?.readResource) {
-          results.push({
-            status: "error",
-            name,
-            path,
-            destination,
-            error: `Skill \"${name}\" has no readable resources.`,
-          });
-          continue;
+        const parent = destination.replace(/\/[^/]+$/, "");
+        if (parent && parent !== "/") {
+          await workspace.mkdir(parent, { recursive: true });
         }
-        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 {
-        written: results.filter(({ status }) => status === "written").length,
-        failed: results.filter(({ status }) => status === "error").length,
-        results,
+        name,
+        path: resource.path,
+        destination,
+        bytesWritten: bytes.byteLength,
+        encoding: resource.encoding ?? "text",
+        ...(resource.mimeType ? { mimeType: resource.mimeType } : {}),
       };
     },
   });
@@ -368,6 +351,9 @@ export async function skillPiToolCandidates(
         return execute(toolCallId, input, signal);
       };
     }
+    if (name === "run_skill_script") {
+      adapted.prepareArguments = normalizeRunSkillScriptArguments;
+    }
     return {
       owner: "runtime-skill",
       requiredExecutionLevel:
@@ -380,6 +366,9 @@ export async function skillPiToolCandidates(
       ...(name === "activate_skill"
         ? { outputBudget: { kind: "structure" as const } }
         : {}),
+      ...(name === "materialize_skill_resource"
+        ? { codeExecutionOnly: true as const }
+        : {}),
       tool: adapted,
     };
   });

package/src/runtime-agent.ts

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

package/src/runtime-assembler.ts

@@ -30,6 +30,7 @@ import {
 } from "./lib/execution-level";
 import {
   createPiRuntimeAssembly,
+  type FinalizedPiToolSurface,
   type PiToolSurface,
   type PiRuntimeAssembly,
 } from "./pi/assembly/snapshot";
@@ -43,6 +44,7 @@ import type {
   RuntimeSkillContribution,
   RuntimeToolSurfacePolicy,
 } from "./runtime-definition";
+import type { RuntimeCodeExecutionFactory } from "./kernel/bindings";
 import {
   basePiToolCandidates,
   memoryPiToolCandidate,
@@ -50,6 +52,7 @@ import {
 import {
   BROWSER_EXECUTE_TOOL_NAME,
   browserExecutionPiToolCandidate,
+  codeExecutionPiToolCandidate,
 } from "./pi/tool/core";
 import { skillPiToolCandidates } from "./pi/tool/skill";
 import { createWebSearch } from "./pi/tool/web-search";
@@ -80,6 +83,7 @@ export interface RuntimeAssemblyInput {
   readonly provider: RuntimeProviderPort;
   readonly platform: RuntimePlatformPort;
   readonly workspace?: WorkspacePort;
+  readonly codeExecution?: RuntimeCodeExecutionFactory;
   readonly sandbox?: RuntimeSandboxPort;
   readonly memory?: RuntimeMemoryPort;
   readonly hostTools: readonly PiToolCandidate[];
@@ -153,6 +157,7 @@ function assertMemoryProfile(profile: RuntimeMemoryProfile): void {
 }
 
 interface ToolSurfaceInput {
+  readonly codeExecution?: RuntimeCodeExecutionFactory;
   readonly platform: RuntimePlatformPort;
   readonly workspace?: WorkspacePort;
   readonly memory?: {
@@ -198,10 +203,15 @@ async function createToolSurface(
     });
   // 平台没有浏览器能力时注册空集：宁可没有这个 Tool，也不注册一个必然失败的 Tool 误导模型。
   // `create()` 推迟到确认这个名字真的可见之后，被 deny 的装配不白建一个浏览器连接器。
+  // `direct` 使它只走 Direct 调用，不再被并进 `execute` 的工具集——两个 Code Mode 类工具互相嵌套
+  // 会让「哪次执行被记录、被重放」变得无法解释，而它们的分工本就由 System Prompt 划清。
   const browserVisible = !deny.has(BROWSER_EXECUTE_TOOL_NAME) &&
     allowsTool?.(BROWSER_EXECUTE_TOOL_NAME) !== false;
   const browserCandidates = input.platform.browser && browserVisible
-    ? [browserExecutionPiToolCandidate(input.platform.browser.create())]
+    ? [{
+        ...browserExecutionPiToolCandidate(input.platform.browser.create()),
+        direct: true as const,
+      }]
     : [];
   const baseCandidates = basePiToolCandidates(input.webSearch);
   const memoryCandidates = input.memory
@@ -238,16 +248,87 @@ async function createToolSurface(
           if (!EXECUTION_LEVELS.includes(candidate.requiredExecutionLevel)) {
             throw new Error(`SpringBrand Tool ${name} execution level is invalid`);
           }
-          if (name === "execute") {
-            throw new Error("SpringBrand reserved Runtime Tool name: execute");
-          }
           if (tools.has(name)) {
             throw new Error(`Duplicate Runtime SpringBrand Tool: ${name}`);
           }
-          tools.set(name, classify(candidate));
+          tools.set(name, Object.freeze({ ...candidate }));
         }
 
-        return Object.freeze([...tools.values()]);
+        const finalized = [...tools.values()];
+        const directVisible = finalized.filter(
+          (candidate) => !candidate.codeExecutionOnly,
+        );
+        if (tools.has("execute")) {
+          throw new Error("SpringBrand reserved Runtime Tool name: execute");
+        }
+        if (
+          !input.codeExecution ||
+          deny.has("execute") ||
+          allowsTool?.("execute") === false
+        ) {
+          return Object.freeze({
+            candidates: Object.freeze(directVisible.map(classify)),
+            codeExecutionCandidates: Object.freeze([]),
+          }) satisfies FinalizedPiToolSurface;
+        }
+        const mergeable = finalized.filter(
+          (candidate) =>
+            !candidate.direct &&
+            !candidate.interaction &&
+            typeof candidate.tool.execute === "function",
+        );
+        const codeExecutionCandidates = Object.freeze([...mergeable]);
+        const codeExecutionToolNames = new Set(
+          codeExecutionCandidates.map(({ tool }) => tool.name),
+        );
+        const codeExecution = input.codeExecution.create(
+          codeExecutionCandidates,
+        );
+        const topLevelOnly = directVisible.filter(
+          ({ tool }) => !codeExecutionToolNames.has(tool.name),
+        );
+        const routeList = (deferred: boolean) => {
+          const matches = topLevelOnly.filter((candidate) =>
+            (defersTool?.(candidate.tool.name) === true) === deferred
+          );
+          return matches.length > 0
+            ? matches.map(({ tool }) =>
+                `- \`${tool.name}\` — ${(tool.label ?? tool.name)
+                  .replaceAll(/\s+/g, " ").trim().replaceAll("`", "'")}`
+              ).join("\n")
+            : "- None.";
+        };
+        const routeGuidance = [
+          "## Tool routing",
+          "Top-level deferred Tools are not callable through `tools.*`. Use Provider Tool Search with their exact name, then call them directly.",
+          "Top-level immediate Tools are already available outside execute; call them directly.",
+          "",
+          "## Top-level deferred Tools",
+          routeList(true),
+          "",
+          "## Top-level immediate Tools",
+          routeList(false),
+          "",
+        ].join("\n");
+        const materializeGuidance = codeExecutionCandidates.some(
+            ({ tool }) => tool.name === "materialize_skill_resource",
+          )
+          ? "Skill resource copying is available only inside execute through " +
+            "`tools.materialize_skill_resource({ name, path, destination })`; " +
+            "no Direct Tool is registered for it. " +
+            "Use a loop or Promise.all when copying multiple resources.\n\n"
+          : "";
+        return Object.freeze({
+          candidates: Object.freeze([
+            classify(codeExecutionPiToolCandidate({
+              ...codeExecution,
+              description:
+                routeGuidance + "\n" + materializeGuidance + codeExecution.description,
+            })),
+            ...directVisible.map(classify),
+          ]),
+          codeExecutionCandidates,
+        }) satisfies FinalizedPiToolSurface;
       },
     }),
     extensions: input.extensions.filter(
@@ -275,6 +356,7 @@ class RuntimeBuilder {
   private platform?: RuntimePlatformPort;
   private gateway?: RuntimeGatewayPort;
   private workspace?: WorkspacePort;
+  private codeExecution?: RuntimeCodeExecutionFactory;
   private sandbox?: RuntimeSandboxPort;
   private schedule?: RuntimeSchedulePort;
   private memoryProfile: RuntimeMemoryProfile = DISABLED_MEMORY;
@@ -310,6 +392,7 @@ class RuntimeBuilder {
     this.provider = input.provider;
     this.platform = input.platform;
     this.workspace = input.workspace;
+    this.codeExecution = input.codeExecution;
     this.sandbox = input.sandbox;
     this.memoryProfile = input.memoryProfile;
     this.memory = input.memory;
@@ -449,6 +532,9 @@ class RuntimeBuilder {
     if (!this.platform.loader) {
       throw new Error("Runtime platform loader is required");
     }
+    if (typeof this.platform.outbound !== "function") {
+      throw new Error("Runtime platform outbound port is required");
+    }
 
     assertMemoryProfile(this.memoryProfile);
     if (this.memoryProfile.enabled && (!this.workspace || !this.memory)) {
@@ -498,6 +584,7 @@ class RuntimeBuilder {
     });
     const skillSources = [...this.skillSources.values()];
     const toolSurface = await createToolSurface({
+      ...(this.codeExecution ? { codeExecution: this.codeExecution } : {}),
       platform: this.platform,
       ...(this.workspace ? { workspace: this.workspace } : {}),
       ...(this.memoryProfile.enabled && this.memory
@@ -522,6 +609,7 @@ class RuntimeBuilder {
     const bindings: RuntimeBindings = Object.freeze({
       provider,
       platform: Object.freeze({ ...this.platform }),
+      ...(this.codeExecution ? { codeExecution: this.codeExecution } : {}),
       ...(this.gateway ? { gateway: this.gateway } : {}),
       ...(this.workspace ? { workspace: this.workspace } : {}),
       ...(this.memoryProfile.enabled && this.memory
@@ -666,6 +754,9 @@ export async function assembleRuntimeSnapshot<
     ...(toolAssembly.bindings?.workspace
       ? { workspace: toolAssembly.bindings.workspace }
       : {}),
+    ...(toolAssembly.bindings?.codeExecution
+      ? { codeExecution: toolAssembly.bindings.codeExecution }
+      : {}),
     ...(memoryProfile.enabled && toolAssembly.bindings?.memory
       ? { memory: toolAssembly.bindings.memory }
       : {}),

package/src/runtime-definition.ts

@@ -33,6 +33,7 @@ export interface ToolSurfaceSelectionPolicy {
 /** Kernel 绑定仍需要的执行后端；不出现在 Definition 公开类型里。 */
 export interface RuntimeToolBindings {
   readonly workspace?: import("./kernel/bindings").WorkspacePort;
+  readonly codeExecution?: import("./kernel/bindings").RuntimeCodeExecutionFactory;
   readonly memory?: import("./kernel/bindings").RuntimeMemoryPort;
   readonly subagents?: import("./kernel/bindings").RuntimeSubagentPort;
 }

package/src/runtime.ts

@@ -975,6 +975,28 @@ export abstract class AgentRuntimeKernel<
           occurredAt: event.timestamp,
         });
       },
+      onNestedToolStarted: (event) => {
+        this.telemetry.capture("toolStarted", {
+          submissionId: submission.submissionId,
+          ...event,
+        });
+      },
+      onNestedToolFinished: (event) => {
+        this.telemetry.capture("toolFinished", {
+          submissionId: submission.submissionId,
+          parentToolCallId: event.parentToolCallId,
+          toolCallId: event.toolCallId,
+          toolName: event.toolName,
+          outcome: event.outcome,
+          durationMs: event.durationMs,
+          ...(event.output ? {
+            output: event.output,
+            outputBytes: json(event.output).length,
+          } : {}),
+          ...(event.error ? { error: errorText(event.error) } : {}),
+          occurredAt: event.occurredAt,
+        });
+      },
       ...(toolExecutors && Object.keys(toolExecutors).length > 0
         ? { toolExecutors }
         : {}),