@springbrand/agent-runtime 0.2.0-alpha.66 → 0.2.0-alpha.68

package/package.json

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

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

@@ -197,6 +197,14 @@ export class ScopedWorkspace implements WorkspacePort, WorkspaceAdminPort {
     return this.parent.readFileBytes(await this.guardedPhysical(path));
   }
 
+  async readFilePage(
+    path: string,
+    offset?: number,
+  ) {
+    if (!this.parent.readFilePage) return null;
+    return this.parent.readFilePage(await this.guardedPhysical(path), offset);
+  }
+
   async writeFile(path: string, content: string, mimeType?: string) {
     return this.parent.writeFile(
       await this.guardedPhysical(path, true),
@@ -373,6 +381,9 @@ export function createWorkspacePortFacade(
   const facade: WorkspacePort = {
     readFile: (path) => workspace.readFile(path),
     readFileBytes: (path) => workspace.readFileBytes(path),
+    ...(workspace.readFilePage
+      ? { readFilePage: (path, offset) => workspace.readFilePage!(path, offset) }
+      : {}),
     writeFile: (path, content, mimeType) =>
       workspace.writeFile(path, content, mimeType),
     writeFileBytes: (path, data, mimeType) =>

package/src/kernel/bindings.ts

@@ -59,6 +59,19 @@ export type WorkspaceFileInspection = WorkspaceFileInfo & {
   evidence?: WorkspaceFileEvidence;
 };
 
+type WorkspaceFilePageBase = {
+  size: number;
+  nextOffset: number | null;
+};
+
+export type WorkspaceFilePage =
+  | (WorkspaceFilePageBase & { kind: "text"; content: string })
+  | (WorkspaceFilePageBase & {
+      kind: "csv";
+      columns: string[] | null;
+      rows: string[][];
+    });
+
 /**
  * 向 Runtime 提供已限定作用域的文件操作。
  *
@@ -86,6 +99,14 @@ export interface WorkspacePort {
    * 它与 `readFile` 分开，避免 Runtime 猜测字符编码。
    */
   readFileBytes(path: string): Promise<Uint8Array | null>;
+  /**
+   * Reads one bounded page without buffering the complete file.
+   * CSV pages preserve complete records and return parsed columns and rows.
+   */
+  readFilePage?(
+    path: string,
+    offset?: number,
+  ): Promise<WorkspaceFilePage | null>;
   /**
    * 覆盖写入一个文本文件。
    *

package/src/lib/prompt.ts

@@ -99,11 +99,13 @@ 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 " +
+  "Uploaded files live under /inputs/ in your workspace; convertible formats have a companion " +
   "'<file>.md' (structured markdown). Policy: to summarize, quote, or search files, use state.* inside execute. " +
+  "For every CSV analysis in Code Mode, start with state.readFilePage({ path }); CSV pages expose columns and rows, never data. Rows are arrays aligned to columns, not objects. Never call state.readFile for a CSV. " +
   "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; " +
+  "the ORIGINAL file — converted markdown tables are not for computation. " +
+  "For other large text files in Code Mode, use state.readFilePage({ path }) and continue until nextOffset is null. " +
+  "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.";
 
 // User-interaction actions are called only when their UI semantics are useful.

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

@@ -9,7 +9,10 @@ import {
   type ProxyToolOutput,
 } from "@cloudflare/codemode";
 import { createBrowserTools } from "@cloudflare/think/tools/browser";
-import { createExecuteRuntime } from "@cloudflare/think/tools/execute";
+import {
+  createExecuteRuntime,
+  type CreateExecuteToolOptions,
+} 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";
@@ -18,6 +21,10 @@ import type {
   RuntimeCodeExecutionPort,
   WorkspacePort,
 } from "../../kernel/bindings";
+import {
+  WorkspaceStateConnector,
+  WORKSPACE_PAGING_INSTRUCTIONS,
+} from "./workspace-state-connector";
 import type { RuntimeCodeExecutionFactory } from "../../kernel/bindings";
 import { serializeOutput } from "../../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
@@ -88,7 +95,7 @@ state.writeFileBytes is not available. Use state.writeFile or state.appendFile f
 
 Bundled Skill resources are not Workspace files. Read text with tools.read_skill_resource, run bundled scripts with tools.run_skill_script, and copy templates or assets with tools.materialize_skill_resource.
 
-User Attachments are already Workspace files below /inputs. Inspect their exact path and immutable cdnUrl before using them.
+User Attachments are already Workspace files below /inputs. Inspect their exact path before using them. Never raw-fetch an attachment already present below /inputs or materialize its cdnUrl; read it with state.*.
 
 When an asset already exists in Workspace, use state.cp to copy it into the current Website directory. Use actual task paths and reference the destination with a relative URL.
 
@@ -336,7 +343,19 @@ export function createWorkspaceCodeExecutionFactory(options: {
         options.workspace,
         options.workspaceAccessMode,
       );
-      const createPort = (innerResults: AgentToolResult<unknown>[]) => {
+      const workspaceState = state && options.workspace.readFilePage
+        ? new WorkspaceStateConnector(
+            options.ctx,
+            state,
+            options.workspace as WorkspacePort & {
+              readFilePage: NonNullable<WorkspacePort["readFilePage"]>;
+            },
+          )
+        : undefined;
+      const createPort = (
+        innerResults: AgentToolResult<unknown>[],
+        stateOptions: Pick<CreateExecuteToolOptions, "state" | "connectors">,
+      ) => {
         let nestedCallOrdinal = 0;
         const { tool } = createExecuteRuntime({
           ctx: options.ctx,
@@ -348,7 +367,7 @@ export function createWorkspaceCodeExecutionFactory(options: {
             onResult: (value) => innerResults.push(value),
           }),
           timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
-          ...(state ? { state } : {}),
+          ...stateOptions,
           name: "execute",
         });
         return toCodeExecutionPort(
@@ -360,10 +379,17 @@ export function createWorkspaceCodeExecutionFactory(options: {
           ),
         );
       };
-      const description = createPort([]).description;
+      // Inherit the complete official state description; custom connectors otherwise lose its hints.
+      const description = createPort([], state ? { state } : {}).description;
       return {
-        description: `${description}\n\n${SPRINGBRAND_CODE_MODE_POLICY}`,
-        execute: (input) => createPort([]).execute(input),
+        description: [
+          description,
+          ...(workspaceState ? [WORKSPACE_PAGING_INSTRUCTIONS] : []),
+          SPRINGBRAND_CODE_MODE_POLICY,
+        ].join("\n\n"),
+        execute: (input) => createPort(
+          [], workspaceState ? { connectors: [workspaceState] } : state ? { state } : {},
+        ).execute(input),
       };
     },
   };

package/src/pi/tool/workspace-state-connector.ts

@@ -0,0 +1,145 @@
+import type { StateBackend } from "@cloudflare/shell/workers";
+import { StateConnector } from "@cloudflare/shell/workers";
+import type { ConnectorTools } from "@cloudflare/codemode";
+import type { WorkspacePort } from "../../kernel/bindings";
+
+export const WORKSPACE_DIRECT_TEXT_READ_MAX_BYTES = 1024 * 1024;
+
+const READ_FILE_PAGE_TYPES = `
+type WorkspaceFilePage =
+  | { kind: "text"; size: number; nextOffset: number | null; content: string }
+  | { kind: "csv"; size: number; nextOffset: number | null; columns: string[] | null; rows: string[][] };
+`;
+
+export const WORKSPACE_PAGING_INSTRUCTIONS = `For CSV files, do not make a separate probe read or return page contents. Inspect columns and aggregate rows in the same execution with this loop shape:
+
+let page = await state.readFilePage({ path });
+if (!page || page.kind !== "csv") throw new Error("CSV not found");
+const columns = page.columns;
+for (;;) {
+  // Aggregate page.rows here. Do not return raw rows.
+  if (page.nextOffset === null) break;
+  page = await state.readFilePage({ path, offset: page.nextOffset });
+}
+return summary;
+
+CSV pages use page.columns and page.rows; never page.data or page.content. Only the first page has columns. Do not use console.log to inspect a page; explicitly return the final summary.`;
+
+type PagedWorkspacePort = WorkspacePort & {
+  readFilePage: NonNullable<WorkspacePort["readFilePage"]>;
+};
+
+export class WorkspaceStateConnector extends StateConnector {
+  constructor(
+    ctx: DurableObjectState | ExecutionContext,
+    backend: StateBackend,
+    private readonly workspace: PagedWorkspacePort,
+  ) {
+    super(ctx, backend);
+  }
+
+  protected override instructions(): string {
+    const base = super.instructions();
+    return `${base}
+
+${WORKSPACE_PAGING_INSTRUCTIONS}`;
+  }
+
+  protected override tools(): ConnectorTools {
+    const tools = super.tools();
+    const readFile = tools.readFile!;
+    return {
+      ...tools,
+      readFile: {
+        ...readFile,
+        description:
+          `${readFile.description} CSV and files over ${WORKSPACE_DIRECT_TEXT_READ_MAX_BYTES} bytes must use readFilePage.`,
+        execute: async (args, context) => {
+          const path = requiredPath(args, "readFile");
+          const file = await this.workspace.stat(path);
+          if (file?.type === "file" && (
+            file.mimeType === "text/csv" ||
+            file.size > WORKSPACE_DIRECT_TEXT_READ_MAX_BYTES
+          )) {
+            throw new Error(
+              `${path} requires state.readFilePage({ path: ${JSON.stringify(path)} }); continue with nextOffset until it is null`,
+            );
+          }
+          return readFile.execute(args, context);
+        },
+      },
+      readFilePage: {
+        description:
+          "Read up to 512 KiB or 2,000 CSV rows from a Workspace file. " +
+          "A CSV page returns columns and rows and has no data field; rows are string arrays aligned to columns. " +
+          "A text page returns content. Omit offset on the first call, then pass page.nextOffset until it is null. " +
+          "Prefer this over readFile for CSV and large files.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: { type: "string", minLength: 1, description: "Absolute Workspace file path." },
+            offset: {
+              type: "integer",
+              minimum: 0,
+              description: "Previous page.nextOffset. Omit on the first call.",
+            },
+          },
+          required: ["path"],
+          additionalProperties: false,
+        },
+        replay: "reexecute",
+        execute: (args) => {
+          const input = readFilePageInput(args);
+          return this.workspace.readFilePage(input.path, input.offset);
+        },
+      },
+    };
+  }
+
+  override async getTypeScriptTypes(): Promise<string> {
+    const types = await super.getTypeScriptTypes();
+    const addition = [
+      "  /** CSV pages have columns and rows; never data. Omit offset first, then pass nextOffset until null. */",
+      "  readFilePage(args: { path: string; offset?: number }): Promise<WorkspaceFilePage | null>;",
+    ].join("\n");
+    return `${READ_FILE_PAGE_TYPES}\n${types.replace(/\n\};$/u, `\n${addition}\n};`)}`;
+  }
+}
+
+function requiredPath(value: unknown, method: string): string {
+  if (!value || typeof value !== "object" || Array.isArray(value) ||
+      typeof (value as { path?: unknown }).path !== "string" ||
+      !(value as { path: string }).path) {
+    throw new Error(
+      `state.${method} takes one object argument: state.${method}({ path: "/path/to/file" })`,
+    );
+  }
+  return (value as { path: string }).path;
+}
+
+function readFilePageInput(value: unknown): {
+  path: string;
+  offset?: number;
+} {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("state.readFilePage requires an object argument");
+  }
+  const input = value as Record<string, unknown>;
+  const keys = Object.keys(input);
+  if (keys.some((key) => !["path", "offset"].includes(key))) {
+    throw new Error("state.readFilePage accepts only path and offset");
+  }
+  if (typeof input.path !== "string" || input.path.length === 0) {
+    throw new Error("state.readFilePage requires path");
+  }
+  const offset = input.offset;
+  if (offset !== undefined && (!Number.isInteger(offset) || (offset as number) < 0)) {
+    throw new Error(
+      "state.readFilePage offset must be a previous page.nextOffset; omit it on the first call",
+    );
+  }
+  return {
+    path: input.path,
+    ...(offset === undefined ? {} : { offset: offset as number }),
+  };
+}