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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.2.0-alpha.41",
+  "version": "0.2.0-alpha.43",
   "type": "module",
   "files": [
     "src",

package/src/adapter/cloudflare/resources/r2-skill-source.ts

@@ -0,0 +1,215 @@
+import {
+  parseSkillMarkdown,
+  type SkillContent,
+  type SkillDescriptor,
+  type SkillResource,
+  type SkillResourceDescriptor,
+  type SkillSource,
+} from "agents/skills";
+
+type ListedObject = Pick<R2Object, "key" | "size">;
+
+interface IndexedSkill {
+  readonly descriptor: SkillDescriptor;
+  readonly content: SkillContent;
+  readonly directory: string;
+  readonly resources: ReadonlyMap<string, SkillResourceDescriptor>;
+}
+
+const TEXT_EXTENSIONS = new Set([
+  ".bash",
+  ".css",
+  ".csv",
+  ".html",
+  ".js",
+  ".json",
+  ".jsx",
+  ".md",
+  ".mjs",
+  ".py",
+  ".sh",
+  ".svg",
+  ".ts",
+  ".tsx",
+  ".txt",
+  ".xml",
+  ".yaml",
+  ".yml",
+]);
+
+function trimSlashes(value: string): string {
+  return value.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+
+function resourceKind(path: string): SkillResourceDescriptor["kind"] {
+  if (path.startsWith("references/")) return "reference";
+  if (path.startsWith("scripts/")) return "script";
+  if (path.startsWith("assets/")) return "asset";
+  return "file";
+}
+
+function resourceEncoding(path: string): "text" | "base64" {
+  const file = path.split("/").at(-1) ?? path;
+  const dot = file.lastIndexOf(".");
+  return TEXT_EXTENSIONS.has(dot < 0 ? "" : file.slice(dot).toLowerCase())
+    ? "text"
+    : "base64";
+}
+
+function normalizedResourcePath(path: string): boolean {
+  return !path.startsWith("/") &&
+    !path.includes("\0") &&
+    path.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+}
+
+function base64Encode(buffer: ArrayBuffer): string {
+  let binary = "";
+  for (const byte of new Uint8Array(buffer)) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+
+async function readR2<T>(operation: () => Promise<T>): Promise<T> {
+  try {
+    return await operation();
+  } catch {
+    return operation();
+  }
+}
+
+async function listAllObjects(
+  bucket: R2Bucket,
+  prefix: string,
+): Promise<ListedObject[]> {
+  const objects: ListedObject[] = [];
+  let cursor: string | undefined;
+  do {
+    const page = await readR2(() => bucket.list({
+      prefix,
+      ...(cursor ? { cursor } : {}),
+    }));
+    objects.push(...page.objects);
+    cursor = page.truncated ? page.cursor : undefined;
+  } while (cursor);
+  return objects;
+}
+
+async function readText(bucket: R2Bucket, key: string): Promise<string> {
+  return readR2(async () => {
+    const object = await bucket.get(key);
+    if (!object) throw new Error(`Skill content not found: ${key}`);
+    return object.text();
+  });
+}
+
+async function readResource(
+  bucket: R2Bucket,
+  key: string,
+  descriptor: SkillResourceDescriptor,
+): Promise<SkillResource> {
+  return readR2(async () => {
+    const object = await bucket.get(key);
+    if (!object) throw new Error(`Skill resource not found: ${key}`);
+    const encoding = descriptor.encoding ?? resourceEncoding(descriptor.path);
+    return {
+      ...descriptor,
+      encoding,
+      ...(object.httpMetadata?.contentType
+        ? { mimeType: object.httpMetadata.contentType }
+        : {}),
+      content: encoding === "text"
+        ? await object.text()
+        : base64Encode(await object.arrayBuffer()),
+    };
+  });
+}
+
+/** Create the immutable, single-Skill R2 Source used by SpringBrand runtimes. */
+export function createR2SkillSource(
+  bucket: R2Bucket,
+  resourceId: string,
+  contentHash: string,
+  contentRef: string,
+): SkillSource {
+  const prefix = `${trimSlashes(contentRef)}/`;
+  const id = `resource-${resourceId}-${contentHash}`;
+  let indexPromise: Promise<IndexedSkill> | undefined;
+
+  const loadIndex = async (): Promise<IndexedSkill> => {
+    const objects = await listAllObjects(bucket, prefix);
+    const skillObjects = objects.filter(({ key }) => key.endsWith("/SKILL.md"));
+    if (skillObjects.length !== 1) {
+      throw new Error(`Skill content requires exactly one SKILL.md: ${contentRef}`);
+    }
+    const skillKey = skillObjects[0]!.key;
+    const directory = skillKey.slice(prefix.length, -"/SKILL.md".length);
+    if (!directory || directory.includes("/")) {
+      throw new Error(`Skill content has an invalid directory: ${contentRef}`);
+    }
+    const parsed = parseSkillMarkdown(await readText(bucket, skillKey));
+    if (!parsed) throw new Error(`Skill content has invalid frontmatter: ${contentRef}`);
+
+    const resourcePrefix = `${prefix}${directory}/`;
+    const resources = objects.flatMap(({ key, size }) => {
+      if (key === skillKey || !key.startsWith(resourcePrefix)) return [];
+      const path = key.slice(resourcePrefix.length);
+      return normalizedResourcePath(path)
+        ? [{ path, kind: resourceKind(path), encoding: resourceEncoding(path), size }]
+        : [];
+    });
+    const descriptor: SkillDescriptor = {
+      name: parsed.name,
+      description: parsed.description,
+      compatibility: parsed.compatibility,
+      license: parsed.license,
+      allowedTools: parsed.allowedTools,
+      metadata: parsed.metadata,
+      sourceId: id,
+    };
+    return {
+      descriptor,
+      directory,
+      resources: new Map(resources.map((resource) => [resource.path, resource])),
+      content: {
+        ...descriptor,
+        body: parsed.body,
+        resources,
+      },
+    };
+  };
+
+  const index = (): Promise<IndexedSkill> => {
+    if (!indexPromise) {
+      indexPromise = loadIndex().catch((error) => {
+        indexPromise = undefined;
+        throw error;
+      });
+    }
+    return indexPromise;
+  };
+
+  return {
+    id,
+    fingerprint: id,
+    async list() {
+      return [{ ...(await index()).descriptor }];
+    },
+    async load(name) {
+      const indexed = await index();
+      return indexed.descriptor.name === name ? { ...indexed.content } : null;
+    },
+    async readResource(name, path) {
+      if (!normalizedResourcePath(path)) return null;
+      const indexed = await index();
+      if (indexed.descriptor.name !== name) return null;
+      const descriptor = indexed.resources.get(path);
+      if (!descriptor) return null;
+      return readResource(
+        bucket,
+        `${prefix}${indexed.directory}/${path}`,
+        descriptor,
+      );
+    },
+  };
+}

package/src/adapter/cloudflare/resources/runtime-resources.ts

@@ -1,8 +1,8 @@
-import { r2, type SkillSource } from "agents/skills";
 import type { RuntimeDegradation } from "../../../kernel/degradation";
 import type { RuntimeExtensionConfig } from "../../../kernel/extensions";
 import { withRuntimeLoadTimeout } from "../../../kernel/runtime-load";
 import type { RuntimeExtensionContribution } from "../../../runtime-definition";
+export { createR2SkillSource } from "./r2-skill-source";
 
 export interface CloudflareRuntimeExtensionSource {
   readonly name: string;
@@ -11,29 +11,12 @@ export interface CloudflareRuntimeExtensionSource {
   readonly sourceHash: string;
 }
 
-function trimSlashes(value: string): string {
-  return value.replace(/^\/+/, "").replace(/\/+$/, "");
-}
-
 function hex(bytes: ArrayBuffer): string {
   return [...new Uint8Array(bytes)]
     .map((byte) => byte.toString(16).padStart(2, "0"))
     .join("");
 }
 
-export function createR2SkillSource(
-  bucket: R2Bucket,
-  resourceId: string,
-  contentHash: string,
-  contentRef: string,
-): SkillSource {
-  return r2(bucket, {
-    prefix: `${trimSlashes(contentRef)}/`,
-    id: `resource-${resourceId}-${contentHash}`,
-    fingerprint: "metadata",
-  });
-}
-
 export async function readVerifiedR2Text(
   bucket: R2Bucket,
   sourceRef: string,

package/src/adapter/cloudflare/subagent/tools.ts

@@ -29,9 +29,6 @@ const READONLY_WORKSPACE_TOOLS = new Set([
   "grep",
 ]);
 const DENIED_TOOLS = [
-  // SubAgents have no approval channel; keep the restored high-risk Workspace
-  // shell on the main Agent surface, matching the pre-Pi behavior.
-  "bash",
   "run_agent",
   "subagents",
   "fanout",
@@ -46,11 +43,11 @@ const executeParameters = Type.Object({
     description:
       "JavaScript to run. Return the final value. The sandbox provides fetch and state.*.",
   }),
-});
+}, { additionalProperties: false });
 
 const fetchParameters = Type.Object({
   url: Type.String({ minLength: 1, maxLength: 8_192 }),
-});
+}, { additionalProperties: false });
 
 function result(details: unknown): AgentToolResult<unknown> {
   let text: string;

package/src/adapter/cloudflare/universal-agent/preparation.ts

@@ -16,6 +16,7 @@ import { AGENT_TYPES } from "../../../layers/orchestration/subagents/agent-types
 import type { RuntimeAgentConfigContext } from "../../../runtime-agent-context";
 import {
   createBrowserExecutionFactory,
+  createWorkspaceCodeExecutionFactory,
   type RuntimeBrowserBinding,
 } from "../../../pi/tool/core-host";
 import {
@@ -54,14 +55,7 @@ const DEFAULT_MEMORY: RuntimeMemoryProfile = Object.freeze({
 });
 
 const WORKSPACE_TOOL_NAMES = [
-  "read",
-  "write",
-  "edit",
-  "list",
-  "find",
-  "grep",
-  "delete",
-  "bash",
+  "execute",
 ] as const;
 
 export function workspaceRequired(input: WorkspaceRequirement): boolean {
@@ -113,6 +107,11 @@ export function createPlatformLoader<
 ): PlatformLoader {
   let cached: ReturnType<PlatformLoader> | undefined;
   return () => cached ??= Promise.resolve().then(() => {
+    const exports = (context.ctx as unknown as {
+      exports: {
+        HttpGateway(options: Record<string, never>): Fetcher;
+      };
+    }).exports;
     return {
       loader: context.env.LOADER,
       // 绑定缺失时整条浏览器能力不进 Platform Port，Tool Surface 因此注册空集。
@@ -128,17 +127,30 @@ export function createPlatformLoader<
             }),
           }
         : {}),
+      outbound: () => exports.HttpGateway({}),
     };
   });
 }
 
 export async function prepareWorkspace<Env extends Cloudflare.Env>(
+  context: RuntimeAgentConfigContext<Env>,
   workspaceLoader: WorkspaceLoader,
+  platformLoader: PlatformLoader,
 ) {
-  const workspace = await workspaceLoader();
+  const [workspace, platform] = await Promise.all([
+    workspaceLoader(),
+    platformLoader(),
+  ]);
   if (!workspace.value) return { degradations: workspace.degradations };
   return {
     workspace: workspace.value,
+    codeExecution: createWorkspaceCodeExecutionFactory({
+      ctx: context.ctx,
+      loader: platform.loader,
+      outbound: platform.outbound(),
+      workspace: workspace.value,
+      workspaceAccessMode: "write",
+    }),
     degradations: workspace.degradations,
   };
 }

package/src/adapter/cloudflare/universal-agent/tools.ts

@@ -12,8 +12,8 @@ import { schedulePiToolCandidates } from "../../../pi/tool/schedule";
 import { workspaceRevisionPiToolCandidate } from "../../../pi/tool/workspace-revision";
 import {
   sandboxPiToolCandidates,
-  workspacePiToolCandidates,
 } from "../../../pi/tool/workspace-sandbox";
+import type { RuntimeCodeExecutionFactory } from "../../../kernel/bindings";
 import type { ToolAssemblyResult } from "../../../runtime-definition";
 import type { PiToolCandidate } from "../../../pi/tool/compiler";
 
@@ -21,6 +21,7 @@ export function assembleUniversalAgentTools(options: {
   hostTools?: readonly PiToolCandidate[];
   workspace?: WorkspacePort;
   workspaceRevisions?: WorkspaceRevisionRestorePort;
+  codeExecution?: RuntimeCodeExecutionFactory;
   sandbox?: RuntimeSandboxPort;
   schedule?: RuntimeSchedulePort;
   subagents?: RuntimeSubagentPort;
@@ -32,7 +33,6 @@ export function assembleUniversalAgentTools(options: {
 }): ToolAssemblyResult {
   const tools = [
     ...(options.hostTools ?? []),
-    ...(options.workspace ? workspacePiToolCandidates(options.workspace) : []),
     ...(options.workspaceRevisions
       ? [workspaceRevisionPiToolCandidate(options.workspaceRevisions)]
       : []),
@@ -44,6 +44,7 @@ export function assembleUniversalAgentTools(options: {
     tools,
     bindings: {
       ...(options.workspace ? { workspace: options.workspace } : {}),
+      ...(options.codeExecution ? { codeExecution: options.codeExecution } : {}),
       ...(options.memory ? { memory: options.memory } : {}),
       ...(options.subagents ? { subagents: options.subagents } : {}),
     },

package/src/adapter/cloudflare/workspace/scoped-workspace.ts

@@ -2,6 +2,7 @@ import type {
   WorkspaceAdminPort,
   WorkspaceFileInfo,
   WorkspacePort,
+  WorkspaceStreamWriteOptions,
   WorkspaceQuota,
   WorkspaceUsage,
 } from "../../../kernel/bindings";
@@ -216,6 +217,18 @@ export class ScopedWorkspace implements WorkspacePort, WorkspaceAdminPort {
     );
   }
 
+  async writeFileStream(
+    path: string,
+    content: ReadableStream<Uint8Array>,
+    options?: WorkspaceStreamWriteOptions,
+  ) {
+    return this.parent.writeFileStream(
+      await this.guardedPhysical(path, true),
+      content,
+      options,
+    );
+  }
+
   async writeFileBytesIfUnchanged(
     path: string,
     data: Uint8Array,
@@ -363,6 +376,8 @@ export function createWorkspacePortFacade(
       workspace.writeFile(path, content, mimeType),
     writeFileBytes: (path, data, mimeType) =>
       workspace.writeFileBytes(path, data, mimeType),
+    writeFileStream: (path, content, options) =>
+      workspace.writeFileStream(path, content, options),
     appendFile: (path, content, mimeType) =>
       workspace.appendFile(path, content, mimeType),
     exists: (path) => workspace.exists(path),

package/src/index.ts

@@ -93,6 +93,7 @@ export type {
   CompilePiToolsOptions,
   PiToolCandidate,
   SettledPiToolCall,
+  ToolExposureMode,
 } from "./pi/tool";
 export { basePiToolCandidates } from "./pi/tool";
 export { createPiDeclaredToolCandidate } from "./pi/tool";
@@ -115,9 +116,11 @@ export type { PiSkillBinding } from "./pi/tool";
 export {
   BROWSER_EXECUTE_TOOL_NAME,
   browserExecutionPiToolCandidate,
+  codeExecutionPiToolCandidate,
 } from "./pi/tool";
 export {
   createBrowserExecutionFactory,
+  createWorkspaceCodeExecutionFactory,
 } from "./pi/tool";
 export {
   assemblePiExtensions,

package/src/kernel/bindings.ts

@@ -3,6 +3,7 @@ import type { ScheduleSpec } from "./receipts";
 import type { RuntimeActivityProjection } from "./state";
 import type { ExecutionLevel } from "../lib/execution-level";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { PiToolCandidate } from "../pi/tool/compiler";
 import type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
@@ -91,6 +92,11 @@ export interface WorkspacePort {
     data: Uint8Array | ArrayBuffer,
     mimeType?: string,
   ): Promise<void>;
+  writeFileStream(
+    path: string,
+    content: ReadableStream<Uint8Array>,
+    options?: WorkspaceStreamWriteOptions,
+  ): Promise<{ path: string; bytes: number }>;
   /**
    * 把文本追加到文件末尾。
    *
@@ -204,12 +210,17 @@ export interface WorkspacePort {
   glob(pattern: string): Promise<WorkspaceFileInfo[]>;
 }
 
+export interface WorkspaceStreamWriteOptions {
+  contentLength?: number;
+  mediaType?: string;
+}
+
 /**
- * 向 Runtime 提供已组装的浏览器 Code Mode 执行能力。
+ * 向 Runtime 提供已组装的 Workspace Code Mode 执行能力。
  *
  * @remarks
- * Browser Host Adapter 负责绑定 Durable Object、Worker Loader 和 Browser Run；
- * Tool Surface 只把这个已授权 Port 转成 `browser_execute` Tool。
+ * Host Adapter 负责绑定 Durable Object、Worker Loader、网络出口和
+ * Workspace；Tool Surface 只把这个已授权 Port 转成 `execute` Tool。
  */
 export interface RuntimeCodeExecutionPort {
   readonly description: string;
@@ -932,15 +943,24 @@ export interface RuntimeProviderPort {
  * 向 Runtime 提供 Cloudflare 执行平台上的可授权能力。
  *
  * @remarks
- * Platform Plugin 准备它，Browser 工具、遥测和工具门卫按需使用。
+ * Platform Plugin 准备它，Workspace Codemode、Browser 工具、遥测和工具门卫按需使用。
  *
- * Worker Loader 由 Host 选择，使 Dynamic Worker 只获得已授权绑定；术语见 `../index.ts`。
+ * Worker Loader 与网络出口由 Host 选择，使 Dynamic Worker 只获得已授权绑定；术语见 `../index.ts`。
  */
 export interface RuntimePlatformPort {
-  /** Browser Code Mode 在创建 Dynamic Worker 执行器时使用的 Worker Loader。 */
+  /** Workspace Codemode 在创建 Dynamic Worker 执行器时使用的 Worker Loader。 */
   loader: WorkerLoader;
   /** Platform Plugin 存在 Browser Run 绑定时用它生成 `browser_execute`；缺失即整条浏览器 Tool 面不注册。 */
   browser?: RuntimeBrowserPort;
+  /**
+   * 为一次 Dynamic Worker 组装取得已限定的网络出口。
+   *
+   * @remarks
+   * Workspace Plugin 创建 Codemode 工具时调用，并把返回的 `Fetcher` 交给 `DynamicWorkerExecutor`。
+   *
+   * 出口由 Host 通过 Service Binding 等平台边界控制，不使用无约束的 Runtime 全局网络能力。
+   */
+  outbound: () => Fetcher;
   /**
    * 在 Pi 工具真正执行前请 Host 审查本次调用。
    *
@@ -1009,9 +1029,21 @@ export interface RuntimeSkillSourceBinding {
  *
  * 它不携带业务 ID、Repository、数据库 Key、任意能力注册表或凭据配置；术语见 `../index.ts`。
  */
+/**
+ * 延迟到最终 Tool Surface 完成后再创建 Code Mode 执行能力。
+ *
+ * @remarks
+ * 工厂与返回 Port 同住 Host 绑定边界；输入直接使用最终 Pi Tool candidates，
+ * 不再经过 Registry 或另一份 Tool 元数据协议。
+ */
+export interface RuntimeCodeExecutionFactory {
+  create(candidates: readonly PiToolCandidate[]): RuntimeCodeExecutionPort;
+}
+
 export interface RuntimeBindings {
   provider: RuntimeProviderPort;
   platform: RuntimePlatformPort;
+  codeExecution?: RuntimeCodeExecutionFactory;
   /** Secret-capability binding; implementations must keep Runtime Grant in closure state. */
   gateway?: RuntimeGatewayPort;
   workspace?: WorkspacePort;

package/src/layers/context/budget/gate.ts

@@ -173,13 +173,13 @@ export async function spillDurableToolOutput(
       // 出口指令必须是可执行的，而且必须只承诺模型真的拿得到的东西：Provider 只把
       // Tool 结果的 content 发给模型，所以这里不能引用只存在于 details 的字段。
       // 溢出产物是 JSON，一个大字符串叶子会整块挤在一行上，而按行分页追不回被行宽
-      // 截断的内容 —— 那种情况要走 grep / bash，不能让模型以为 read 一定够用。
+      // 截断的内容 —— 那种情况要走 state.searchText，不能让模型以为分页读取一定够用。
       note:
         "Output was large and has been saved to the Workspace file above. " +
-        "Read it in pages with read(path, offset, limit) — do not read it whole; " +
+        "Read it in pages inside execute with state.readFile — do not read it whole; " +
         "each page ends with a footer telling you the line range and the next offset. " +
         "This file is JSON, so a single large value can sit on one very long line: " +
-        "if a page reports that lines were cut short, use grep or bash on the path instead.",
+        "if a page reports that lines were cut short, use state.searchText on the path instead.",
     };
   } catch {
     return null;

package/src/layers/orchestration/temporary-agent/workspace.ts

@@ -83,6 +83,8 @@ export function createTemporaryAgentWorkspace(
     // 原因：二进制写入必须与文本写入使用同一 Memory 禁止，不能留下第二条写入路径。
     writeFileBytes: async (path, data, mimeType) =>
       workspace.writeFileBytes(allowed(path), data, mimeType),
+    writeFileStream: async (path, content, options) =>
+      workspace.writeFileStream(allowed(path), content, options),
     // 作用：在一个允许的文件末尾追加文本。
     // 调用：临时 Agent 需要增量写入时通过 Workspace Tool 调用。
     // 原因：追加也是写操作，必须在委托前拦截 Memory 路径。

package/src/lib/prompt.ts

@@ -12,11 +12,18 @@
 export const PERSONA =
   "You are a personal assistant agent running on the universal-agent runtime. " +
   "You can recall user-managed cold memory across sessions and keep working memory within the current Session, " +
-  "manage files in your workspace, and call the declared Tools available to the current Runtime.";
+  "manage files in your workspace, and use execute Code Mode for network requests and tool composition.";
 
 // Names the stable runtime environment.
 export const RUNTIME =
-  "Runtime: this agent runs on Cloudflare Workers.";
+  "Runtime: this agent runs on Cloudflare Workers. When execute is present, its Code Mode Dynamic Worker is your " +
+  "instrument — code there runs with outbound network access (fetch), your " +
+  "workspace filesystem (state.*), and the tools.* methods listed in its own description. Use it for raw or customized HTTP " +
+  "requests, parsing a payload, hitting several known endpoints, or computing over a file. Write plain " +
+  "JavaScript — the sandbox evaluates " +
+  "it directly, so TypeScript type annotations (`: number`, `as Type`) are a syntax error, and there " +
+  "is no Python interpreter or package manager to invoke. Use the JS/Workers equivalent of what you " +
+  "would reach for in another ecosystem.";
 
 // Shared behavioral contract for the main Agent and bounded sub-agents.
 export const BEHAVIOR =
@@ -38,23 +45,31 @@ export const PLANNING =
   "step or a purely conversational reply — just do it.";
 
 const TOOL_ROUTING =
-  "Tools: Call only declared Tools. If a required Tool Schema is not visible, use Provider Tool Search with that exact name. Never invent a Tool name or input field. ";
+  "Tools: execute can call only the tools.* methods explicitly listed in its description; that list is exhaustive. Never guess a tools.* method. " +
+  "If a required top-level Tool is not visible, do not use execute. Call top-level Tool Search with that exact name, then call the discovered Tool directly. " +
+  "codemode.search searches only methods already installed inside execute; it cannot discover deferred top-level Tools. " +
+  "Never invent a Tool name or input field.";
 
 // Tool-selection guidance mirrors the actual approval and network boundaries.
 export const TOOLS =
   TOOL_ROUTING +
+  " Relatedness, repetition, or multiple calls never overrides this availability rule. " +
+  "When every required Tool is available inside execute, use one execute for repeated or related calls, branching, or repetition. Inside execute, " +
+  "use state.* for workspace file operations, tools.* for other host capabilities, and sequential calls for repeated or durable operations. " +
+  "Top-level-only Tools remain Direct even when called repeatedly. " +
   "For web tasks, use web_search for web discovery, current facts, cited research, " +
-  "and public URL analysis. When sandbox_* tools are present, use that isolated Linux environment for Python/Node, " +
+  "and public URL analysis. For web access specifically, use execute Code Mode only for raw or customized network requests, structured " +
+  "API calls, or when web_search cannot retrieve the required content; do not use execute for ordinary web " +
+  "searches. When execute is absent, use the actually exposed Direct Tools. When sandbox_* tools are present, use that isolated Linux environment for Python/Node, " +
   "package managers, system commands, builds, tests and background processes; its filesystem is temporary, " +
   "persistent inputs are copied in automatically on first use, /userspace is read-only, and only explicitly " +
-  "published /workspace outputs survive. Use run_skill_script only for scripts supplied by an activated Skill and allowed by its policy. " +
-  "bash is a shell over the workspace filesystem only " +
-  "(no network, no system utilities) and is approval-gated — don't reach for it to read files or fetch. " +
-  "Use read for one existing Workspace file, write to create or replace one file, and edit for one localized change. " +
-  "Use bash only when a single shell workflow must coordinate multiple Workspace files; do not use it for a single-file read, write, or edit. " +
+  "published /workspace outputs survive. Use Code Mode for computation, multi-step data work, and the " +
+  "raw or customized network cases described above; every response and failure it sees is visible to you. " +
+  "Every Workspace filesystem operation goes through execute and state.*; no Workspace file methods exist under tools.*. " +
   "Do not re-plan or explain between consecutive tool calls. When a run is within the last five model turns, stop expanding scope and " +
   "prioritize verification, saving durable results, and the final response. " +
-  "When Tool calls are independent, issue them together in one model step. When you reference " +
+  "When related Tool calls can run independently, all are available inside execute, and execute is present, run them inside that execute rather than as parallel top-level calls; " +
+  "only independent top-level-only Direct Tools should be issued together in one turn. When you reference " +
   "code, cite it as file_path:line_number.";
 
 // A real browser is the only way to observe what a page actually does, and the
@@ -67,9 +82,10 @@ export const TOOLS =
 // browser tool belongs to that tool's own description, which the model sees if
 // and only if the tool is registered.
 export const BROWSER =
-  "Browser: a real browser observes what a page actually does: " +
+  "Browser: a real browser is for the one thing execute cannot do — observe what a page actually does: " +
   "rendered result, console output, runtime exceptions, failed resource loads, CSP blocks, and state after an " +
-  "interaction. Use web_search for public discovery and Workspace or Sandbox Tools for files and computation. " +
+  "interaction. Everything else stays with execute: computation, files, and ordinary HTTP requests (fetching " +
+  "HTML is execute's job, not the browser's). " +
   "After you write or change a web page in the workspace, open it once with the browser tools you have before " +
   "you call the work done, and say in your reply what you checked and what you saw. " +
   "Drive each browser tool the way its own description tells you to; the failure mode they share is coming back " +
@@ -84,8 +100,8 @@ export const BROWSER =
 // Uploaded-file routing prevents lossy markdown conversions from becoming data sources.
 export const FILES =
   "Uploaded files live under /uploads/ in your workspace; convertible formats have a companion " +
-  "'<file>.md' (structured markdown). Policy: to summarize/quote/search one file, read or grep the .md. " +
-  "To compute/aggregate/transform (especially csv/xlsx), use the Linux Sandbox to read " +
+  "'<file>.md' (structured markdown). Policy: to summarize, quote, or search files, use state.* inside execute. " +
+  "To compute/aggregate/transform (especially csv/xlsx), write code in execute Code Mode or the Linux Sandbox that reads " +
   "the ORIGINAL file — converted markdown tables are not for computation, and large spreadsheets may " +
   "have no .md at all. For formats without a companion .md (e.g. pptx: unzip and read ppt/slides/*.xml; " +
   "zip archives; unknown types), parse the original in the sandbox with JS.";

package/src/pi/assembly/snapshot.ts

@@ -23,7 +23,13 @@ import type { PiToolCandidate } from "../tool/compiler";
 export interface PiToolSurface {
   finalize(
     candidates: readonly PiToolCandidate[],
-  ): readonly PiToolCandidate[];
+  ): FinalizedPiToolSurface;
+}
+
+/** Internal finalization output; not a second Tool protocol. */
+export interface FinalizedPiToolSurface {
+  readonly candidates: readonly PiToolCandidate[];
+  readonly codeExecutionCandidates: readonly PiToolCandidate[];
 }
 
 /** Immutable inputs consumed directly by Pi Agent Core. */