@springbrand/agent-runtime 0.2.0-alpha.65 → 0.2.0-alpha.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.2.0-alpha.65",
+  "version": "0.2.0-alpha.67",
   "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/index.ts

@@ -68,6 +68,7 @@ export type {
   ResolvedResources,
   RuntimeAgentContext,
   RuntimeSettings,
+  RuntimeSkillBodyTransform,
   RuntimeToolBindings,
   ToolAssemblyResult,
 } from "./runtime-definition";

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

@@ -18,6 +18,7 @@ import type {
   RuntimeCodeExecutionPort,
   WorkspacePort,
 } from "../../kernel/bindings";
+import { WorkspaceStateConnector } from "./workspace-state-connector";
 import type { RuntimeCodeExecutionFactory } from "../../kernel/bindings";
 import { serializeOutput } from "../../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
@@ -88,7 +89,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,6 +337,15 @@ export function createWorkspaceCodeExecutionFactory(options: {
         options.workspace,
         options.workspaceAccessMode,
       );
+      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>[]) => {
         let nestedCallOrdinal = 0;
         const { tool } = createExecuteRuntime({
@@ -348,7 +358,7 @@ export function createWorkspaceCodeExecutionFactory(options: {
             onResult: (value) => innerResults.push(value),
           }),
           timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
-          ...(state ? { state } : {}),
+          ...(workspaceState ? { connectors: [workspaceState] } : state ? { state } : {}),
           name: "execute",
         });
         return toCodeExecutionPort(

package/src/pi/tool/skill.ts

@@ -13,6 +13,7 @@ import type {
   RuntimeSkillScriptPolicy,
   WorkspacePort,
 } from "../../kernel/bindings";
+import type { RuntimeSkillBodyTransform } from "../../runtime-definition";
 import { STORAGE_LEAF_MAX_CHARS } from "../../layers/context/budget/gate";
 import { serializeOutput } from "../../lib/artifacts";
 import { aiToolToPi } from "./ai-adapter";
@@ -33,6 +34,7 @@ export interface SkillPiToolOptions {
   readonly loader?: WorkerLoader;
   readonly workspace?: WorkspacePort;
   readonly tools?: readonly PiToolCandidate[];
+  readonly transformSkillBody?: RuntimeSkillBodyTransform;
 }
 
 /**
@@ -116,7 +118,11 @@ function budgetSkillResources(skill: LoadedSkill): LoadedSkill {
   return { ...skill, resources: kept, body: `${skill.body}\n\n${lines.join("\n")}` };
 }
 
-function catalogSkillSource(binding: PiSkillBinding): SkillSource {
+function catalogSkillSource(
+  binding: PiSkillBinding,
+  transformSkillBody: RuntimeSkillBodyTransform | undefined,
+  availableToolNames: readonly string[],
+): SkillSource {
   const source = binding.source;
   return {
     id: source.id,
@@ -132,7 +138,17 @@ function catalogSkillSource(binding: PiSkillBinding): SkillSource {
     load: async (name) => {
       const skill = await source.load(name);
       if (!skill) return null;
-      const loaded = budgetSkillResources(skill);
+      const prepared = transformSkillBody
+        ? {
+            ...skill,
+            body: transformSkillBody({
+              name: skill.name,
+              body: skill.body,
+              availableToolNames,
+            }),
+          }
+        : skill;
+      const loaded = budgetSkillResources(prepared);
       const hasOversizedResource = skill.resources?.some((resource) =>
         typeof resource.size === "number" &&
         resource.size > SKILL_RESOURCE_BUDGET_BYTES
@@ -420,8 +436,14 @@ export async function skillPiToolCandidates(
 ): Promise<PiToolCandidate[]> {
   if (bindings.length === 0) return [];
 
+  const availableToolNames = (options.tools ?? []).map(({ tool }) => tool.name);
+
   const registry = new SkillRegistry(
-    bindings.map(catalogSkillSource),
+    bindings.map((binding) => catalogSkillSource(
+      binding,
+      options.transformSkillBody,
+      availableToolNames,
+    )),
     scriptRunner(bindings, options),
   );
   await registry.load();

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

@@ -0,0 +1,143 @@
+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[][] };
+`;
+
+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}
+
+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.`;
+  }
+
+  protected override tools(): ConnectorTools {
+    const tools = super.tools();
+    const readFile = tools.readFile!;
+    return {
+      ...tools,
+      readFile: {
+        ...readFile,
+        description:
+          `Read a small non-CSV file as text. 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 }),
+  };
+}

package/src/runtime-assembler.ts

@@ -44,6 +44,7 @@ import type {
   RuntimeSettings,
   RuntimeExtensionContribution,
   RuntimeProfileContribution,
+  RuntimeSkillBodyTransform,
   RuntimeSkillContribution,
   RuntimeToolSurfacePolicy,
 } from "./runtime-definition";
@@ -90,6 +91,7 @@ export interface RuntimeAssemblyInput {
   readonly sandbox?: RuntimeSandboxPort;
   readonly memory?: RuntimeMemoryPort;
   readonly hostTools: readonly PiToolCandidate[];
+  readonly transformSkillBody?: RuntimeSkillBodyTransform;
   readonly skills: readonly RuntimeSkillContribution[];
   readonly connectors: readonly RuntimeMcpServer[];
   readonly gateway?: RuntimeGatewayPort;
@@ -168,6 +170,7 @@ interface ToolSurfaceInput {
     readonly profile: RuntimeMemoryProfile;
   };
   readonly hostTools: readonly PiToolCandidate[];
+  readonly transformSkillBody?: RuntimeSkillBodyTransform;
   readonly skills: readonly RuntimeSkillSourceBinding[];
   readonly enabledSubagents: readonly string[];
   readonly webSearch?: Parameters<typeof basePiToolCandidates>[0];
@@ -236,6 +239,9 @@ async function createToolSurface(
       loader: input.platform.loader,
       ...(input.workspace ? { workspace: input.workspace } : {}),
       tools: scriptCandidates,
+      ...(input.transformSkillBody
+        ? { transformSkillBody: input.transformSkillBody }
+        : {}),
     })),
     ...baseCandidates,
     ...memoryCandidates,
@@ -369,6 +375,7 @@ class RuntimeBuilder {
   private memoryProfile: RuntimeMemoryProfile = DISABLED_MEMORY;
   private memory?: RuntimeMemoryPort;
   private readonly hostTools: PiToolCandidate[] = [];
+  private transformSkillBody?: RuntimeSkillBodyTransform;
   private toolPolicy?: RuntimeToolSurfacePolicy;
   private readonly skillSources = new Map<
     string,
@@ -404,6 +411,7 @@ class RuntimeBuilder {
     this.memoryProfile = input.memoryProfile;
     this.memory = input.memory;
     this.hostTools.push(...input.hostTools);
+    this.transformSkillBody = input.transformSkillBody;
     this.toolPolicy = input.toolPolicy;
     for (const skill of input.skills) this.addSkill(skill);
     for (const connector of input.connectors) this.addConnector(connector);
@@ -619,6 +627,9 @@ class RuntimeBuilder {
           [...this.enabledSubagents],
         ),
       ],
+      ...(this.transformSkillBody
+        ? { transformSkillBody: this.transformSkillBody }
+        : {}),
       skills: skillSources,
       enabledSubagents: [...this.enabledSubagents],
       ...(webSearch ? { webSearch } : {}),
@@ -786,6 +797,9 @@ export async function assembleRuntimeSnapshot<
       ? { subagents: toolAssembly.bindings.subagents }
       : {}),
     hostTools,
+    ...(resources.transformSkillBody
+      ? { transformSkillBody: resources.transformSkillBody }
+      : {}),
     skills:
       input.ctx.role === "primary" && toolAssembly.bindings?.workspace
         ? [...BUILT_IN_RUNTIME_SKILLS, ...resources.skills]

package/src/runtime-definition.ts

@@ -82,12 +82,19 @@ export interface ResolvedConnectors {
   readonly degradations: readonly RuntimeDegradation[];
 }
 
+export type RuntimeSkillBodyTransform = (input: {
+  readonly name: string;
+  readonly body: string;
+  readonly availableToolNames: readonly string[];
+}) => string;
+
 export interface ResolvedResources {
   readonly settings: RuntimeSettings;
   readonly provider: RuntimeProviderPort;
   readonly platform: RuntimePlatformPort;
   readonly turnEvents?: RuntimeTurnEventsPort;
   readonly admission?: RuntimeSubmissionAdmissionHook;
+  readonly transformSkillBody?: RuntimeSkillBodyTransform;
   readonly skills: readonly RuntimeSkillContribution[];
   readonly extensions: readonly RuntimeExtensionContribution[];
   readonly connectors: ResolvedConnectors;