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

package/src/pi/tool/skill.ts

@@ -6,12 +6,15 @@ import {
   type SkillScriptRunner,
   type SkillSource,
 } from "agents/skills";
+import { truncateResponse, truncateResult } from "@cloudflare/codemode";
 import { tool } from "ai";
 import { z } from "zod";
 import type {
   RuntimeSkillScriptPolicy,
   WorkspacePort,
 } from "../../kernel/bindings";
+import { STORAGE_LEAF_MAX_CHARS } from "../../layers/context/budget/gate";
+import { serializeOutput } from "../../lib/artifacts";
 import { aiToolToPi } from "./ai-adapter";
 import type { PiToolCandidate } from "./compiler";
 import { piCandidatesToAiTools } from "./nested-tools";
@@ -46,6 +49,13 @@ 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. " +
+  "Inside execute, use tools.read_skill_resource for text instead of state.* on /skills.";
+const SKILL_RESOURCE_MATERIALIZE_GUIDANCE =
+  "Inside execute, use tools.materialize_skill_resource for Workspace assets when available.";
+const SKILL_SCRIPT_OUTPUT_ROOT = "/scratch/skill-output";
+
 /**
  * 按体积裁掉超预算的 Skill 资源，并把裁掉的事实写回 Skill 正文。
  *
@@ -93,7 +103,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 +131,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 +217,141 @@ 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 result(details: unknown) {
+  return {
+    content: [{ type: "text" as const, text: serializeOutput(details).text }],
+    details,
+  };
+}
+
+function resourceTarget(
+  bindings: readonly PiSkillBinding[],
+  input: unknown,
+): { binding: PiSkillBinding; path: string } | null {
+  if (input === null || typeof input !== "object") return null;
+  const target = input as { name?: unknown; path?: unknown };
+  if (typeof target.path !== "string") return null;
+  if (typeof target.name === "string") {
+    const binding = bindings.find(({ name }) => name === target.name);
+    return binding ? { binding, path: target.path } : null;
+  }
+  const [name, ...rest] = target.path.split("/");
+  const binding = bindings.find((candidate) => candidate.name === name);
+  return binding && rest.length > 0
+    ? { binding, path: rest.join("/") }
+    : null;
+}
+
+function materializationRequired(name: string, path: string, bytes?: number) {
+  return result({
+    status: "materialization_required",
+    name,
+    path,
+    ...(bytes === undefined ? {} : { bytes }),
+    next: "tools.materialize_skill_resource",
+  });
+}
+
+type ScriptOutputFile = {
+  path?: unknown;
+  content?: unknown;
+  encoding?: unknown;
+  mimeType?: unknown;
+};
+
+function scratchSegment(value: string): string {
+  const segment = value.replace(/[^a-zA-Z0-9._-]+/g, "_");
+  return !segment || segment === "." || segment === ".." ? "_" : segment;
+}
+
+function outputRelativePath(value: unknown): string {
+  const path = String(value ?? "output.txt").replace(/^\/?output\//, "");
+  const parts = path.split("/");
+  if (parts.some((part) => !part || part === "." || part === "..")) {
+    throw new Error(`Invalid Skill output path: ${path}`);
+  }
+  return parts.join("/");
+}
+
+async function projectSkillScriptResult(
+  details: unknown,
+  input: unknown,
+  toolCallId: string,
+  workspace: WorkspacePort | undefined,
+  signal: AbortSignal | undefined,
+): Promise<unknown> {
+  const record = details !== null && typeof details === "object"
+    ? details as Record<string, unknown>
+    : null;
+  const outputFiles = Array.isArray(record?.outputFiles)
+    ? record.outputFiles as ScriptOutputFile[]
+    : [];
+  const target = input as { name?: unknown };
+  const outputs: Array<{ path: string; bytes: number; mediaType?: string }> = [];
+  if (outputFiles.length > 0 && !workspace) {
+    throw new Error("Skill output files require Workspace access");
+  }
+  for (const file of outputFiles) {
+    signal?.throwIfAborted();
+    const relative = outputRelativePath(file.path);
+    const destination = `${SKILL_SCRIPT_OUTPUT_ROOT}/${scratchSegment(String(target.name ?? "skill"))}/${scratchSegment(toolCallId)}/${relative}`;
+    const content = String(file.content ?? "");
+    const binary = file.encoding === "base64";
+    const mediaType = typeof file.mimeType === "string"
+      ? file.mimeType
+      : binary ? "application/octet-stream" : "text/plain";
+    let bytes = new Blob([content]).size;
+    await serializeWorkspaceMutation(workspace!, destination, async () => {
+      const parent = destination.replace(/\/[^/]+$/, "");
+      await workspace!.mkdir(parent, { recursive: true });
+      if (!binary) {
+        await workspace!.writeFile(destination, content, mediaType);
+        return;
+      }
+      const decoded = resourceBytes({
+        path: relative,
+        kind: "file",
+        encoding: "base64",
+        content,
+      });
+      bytes = decoded.byteLength;
+      await workspace!.writeFileBytes(destination, decoded, mediaType);
+    });
+    outputs.push({ path: destination, bytes, mediaType });
+  }
+  const scriptResult = record && "result" in record
+    ? record.result
+    : record && ("outputFiles" in record || "logs" in record)
+    ? Object.fromEntries(Object.entries(record).filter(([key]) =>
+      key !== "outputFiles" && key !== "logs"
+    ))
+    : details;
+  const logs = Array.isArray(record?.logs)
+    ? record.logs.map(String)
+    : [];
+  return {
+    result: truncateResult(scriptResult),
+    ...(logs.length > 0
+      ? { logs: [truncateResponse(logs.join("\n"))] }
+      : {}),
+    ...(outputs.length > 0 ? { outputs } : {}),
+  };
+}
+
 function resourceBytes(resource: SkillResource): Uint8Array {
   if ((resource.encoding ?? "text") === "text") {
     return new TextEncoder().encode(resource.content);
@@ -211,95 +370,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 sequentially in one execute; 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 } : {}),
       };
     },
   });
@@ -349,7 +457,7 @@ export async function skillPiToolCandidates(
     }
     if (name === "read_skill_resource") {
       const execute = adapted.execute;
-      adapted.execute = (toolCallId, input, signal) => {
+      adapted.execute = async (toolCallId, input, signal) => {
         const target = input as { name?: unknown; path?: unknown };
         const parts = typeof target.path === "string"
           ? target.path.split("/")
@@ -360,26 +468,72 @@ export async function skillPiToolCandidates(
             parts.length === 2 &&
             parts[1] === "SKILL.md")
         ) {
-          return Promise.resolve({
+          return {
             content: [{ type: "text", text: SKILL_ENTRY_READ_GUIDANCE }],
             details: SKILL_ENTRY_READ_GUIDANCE,
-          });
+          };
+        }
+        const resolved = resourceTarget(bindings, input);
+        if (resolved) {
+          const skill = await resolved.binding.source
+            .load(resolved.binding.name)
+            .catch(() => null);
+          const descriptor = skill?.resources?.find(({ path }) =>
+            path === resolved.path
+          );
+          if (
+            typeof descriptor?.size === "number" &&
+            descriptor.size > STORAGE_LEAF_MAX_CHARS
+          ) {
+            return materializationRequired(
+              resolved.binding.name,
+              resolved.path,
+              descriptor.size,
+            );
+          }
+        }
+        const output = await execute(toolCallId, input, signal);
+        if (
+          resolved &&
+          typeof output.details === "string" &&
+          output.details.length > STORAGE_LEAF_MAX_CHARS
+        ) {
+          return materializationRequired(
+            resolved.binding.name,
+            resolved.path,
+          );
         }
-        return execute(toolCallId, input, signal);
+        return output;
+      };
+    }
+    if (name === "run_skill_script") {
+      adapted.description +=
+        " Large artifacts must be written directly to Workspace, not returned or logged; scratch outputs are materialized to Workspace and returned only as file references.";
+      adapted.prepareArguments = normalizeRunSkillScriptArguments;
+      const execute = adapted.execute;
+      adapted.execute = async (toolCallId, input, signal) => {
+        const output = await execute(toolCallId, input, signal);
+        return result(await projectSkillScriptResult(
+          output.details,
+          input,
+          toolCallId,
+          options.workspace,
+          signal,
+        ));
       };
     }
     return {
       owner: "runtime-skill",
-      requiredExecutionLevel:
-        name === "run_skill_script" || name === "materialize_skill_resource"
-          ? "high"
-          : "safe",
+      requiredExecutionLevel: "safe",
       // activate_skill 返回的是 Skill 指令本身,是模型接下来所有动作的依据。把它外置
       // 成文件,模型手里就只剩一个路径,必须再取一次才能知道该做什么 —— 而典型
       // SKILL.md 正好落在会触发外置的区间。指令必须当场到手。
       ...(name === "activate_skill"
         ? { outputBudget: { kind: "structure" as const } }
         : {}),
+      ...(name === "activate_skill"
+        ? { exposureMode: "direct" as const }
+        : { exposureMode: "codemode" as const }),
       tool: adapted,
     };
   });

package/src/pi/tool/subagent.ts

@@ -180,6 +180,7 @@ export function subagentPiToolCandidates(
     };
     return {
       owner: `subagent:${type.name}`,
+      exposureMode: "direct",
       requiredExecutionLevel: "safe",
       tool,
     };
@@ -262,6 +263,7 @@ export function subagentPiToolCandidates(
   };
   candidates.push({
     owner: "subagent:background",
+    exposureMode: "direct",
     requiredExecutionLevel: "low",
     summary: "Dispatch a background sub-agent",
     source: "action",

package/src/pi/tool/time.ts

@@ -4,7 +4,7 @@ import type { PiToolCandidate } from "./compiler";
 
 export const GET_TIME_TOOL_NAME = "get_time";
 
-const parameters = Type.Object({});
+const parameters = Type.Object({}, { additionalProperties: false });
 
 /** Product-neutral current-time Tool for Host registries. */
 export function getTimePiToolCandidate(owner = "utilities"): PiToolCandidate {

package/src/pi/tool/web-fetch.ts

@@ -51,7 +51,7 @@ export const webFetchParameters = Type.Object({
         "默认 false（保留位，当前实现总是返回原始内容）。",
     }),
   ),
-});
+}, { additionalProperties: false });
 
 /** webFetch 工具调用的结构化 details，随 AgentToolResult 一起持久化。 */
 export interface WebFetchDetails {

package/src/pi/tool/web-search/web-search.ts

@@ -18,7 +18,7 @@ export const webSearchParameters = Type.Object({
     description: "Additional URLs to analyze along with search (up to 20)",
     maxItems: 20,
   })),
-});
+}, { additionalProperties: false });
 
 export interface WebSearchDetails extends Omit<WebSearchResult, "text"> {
   resultCount: number;
@@ -119,6 +119,7 @@ export function webSearchPiToolCandidate(
   };
   return {
     owner: "runtime-base",
+    exposureMode: "direct",
     requiredExecutionLevel: "safe",
     source: "action",
     tool,

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

@@ -14,7 +14,7 @@ const parameters = Type.Object({
   ], {
     description: "Use previous for the revision immediately before the current one.",
   }),
-});
+}, { additionalProperties: false });
 
 function result<T>(details: T): AgentToolResult<T> {
   return {
@@ -43,6 +43,7 @@ export function workspaceRevisionPiToolCandidate(
   };
   return {
     owner: "workspace",
+    exposureMode: "direct",
     tool,
     requiredExecutionLevel: "safe",
     alwaysRequiresApproval: true,

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

@@ -1,5 +1,4 @@
 import {
-  createBashTool,
   createDeleteTool,
   createEditTool,
   createFindTool,
@@ -68,7 +67,7 @@ const workspaceReadParameters = Type.Object({
     minimum: 1,
     description: "Maximum lines to return; a page is capped by size regardless",
   })),
-});
+}, { additionalProperties: false });
 const workspaceEditParameters = Type.Object({
   path: Type.String({
     minLength: 1,
@@ -80,7 +79,7 @@ const workspaceEditParameters = Type.Object({
       "Exact existing text to replace. Include enough surrounding context to match one location.",
   }),
   new_string: Type.String({ description: "Replacement text." }),
-});
+}, { additionalProperties: false });
 
 /**
  * 单页 read 返回的字符上限。
@@ -176,7 +175,7 @@ function pageReadResult(
   const span = `lines ${fromLine}-${toLine} of ${totalLines ?? toLine}`;
   const lossyNote = lossy
     ? " Some lines were longer than 2000 chars and are cut short; " +
-      "paging cannot recover them — use grep or bash on this path instead."
+      "paging cannot recover them — use grep on this path instead."
     : "";
   const marker = fromLine === 1 && eof && !lossy
     ? ""
@@ -399,12 +398,6 @@ export function workspacePiToolCandidates(
     },
   };
 
-  const bash = aiToolToPi(
-    "bash",
-    createBashTool({ ops: workspace }),
-    { label: "Workspace Bash" },
-  );
-
   return [
     {
       owner: "workspace",
@@ -420,13 +413,6 @@ export function workspacePiToolCandidates(
       requiredExecutionLevel: "safe" as const,
       tool,
     })),
-    {
-      owner: "workspace",
-      requiredExecutionLevel: "high" as const,
-      summary: "Run a Bash script over Workspace files",
-      source: "action" as const,
-      tool: bash,
-    },
   ];
 }
 
@@ -460,15 +446,18 @@ const sandboxExecParameters = Type.Object({
       description: "Maximum command runtime in milliseconds, from 1 to 60000.",
     }),
   ),
-});
-const sandboxStartParameters = Type.Object(sandboxCommandParameters);
+}, { additionalProperties: false });
+const sandboxStartParameters = Type.Object(
+  sandboxCommandParameters,
+  { additionalProperties: false },
+);
 const sandboxProcessParameters = Type.Object({
   id: Type.String({
     minLength: 1,
     maxLength: 128,
     description: "Process ID returned by sandbox_start_process.",
   }),
-});
+}, { additionalProperties: false });
 const sandboxPublishParameters = Type.Object({
   paths: Type.Array(Type.String({
     minLength: 1,
@@ -479,7 +468,7 @@ const sandboxPublishParameters = Type.Object({
     maxItems: 100,
     description: "Files to copy from the temporary Sandbox into the persistent Workspace.",
   }),
-});
+}, { additionalProperties: false });
 
 /**
  * 为现有 RuntimeSandboxPort 创建 Pi 命令、进程和文件发布工具。

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,