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

package/package.json

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

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,7 +21,10 @@ import type {
   RuntimeCodeExecutionPort,
   WorkspacePort,
 } from "../../kernel/bindings";
-import { WorkspaceStateConnector } from "./workspace-state-connector";
+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";
@@ -346,7 +352,10 @@ export function createWorkspaceCodeExecutionFactory(options: {
             },
           )
         : undefined;
-      const createPort = (innerResults: AgentToolResult<unknown>[]) => {
+      const createPort = (
+        innerResults: AgentToolResult<unknown>[],
+        stateOptions: Pick<CreateExecuteToolOptions, "state" | "connectors">,
+      ) => {
         let nestedCallOrdinal = 0;
         const { tool } = createExecuteRuntime({
           ctx: options.ctx,
@@ -358,7 +367,7 @@ export function createWorkspaceCodeExecutionFactory(options: {
             onResult: (value) => innerResults.push(value),
           }),
           timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
-          ...(workspaceState ? { connectors: [workspaceState] } : state ? { state } : {}),
+          ...stateOptions,
           name: "execute",
         });
         return toCodeExecutionPort(
@@ -370,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

@@ -11,6 +11,20 @@ type WorkspaceFilePage =
   | { 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"]>;
 };
@@ -28,19 +42,7 @@ export class WorkspaceStateConnector extends StateConnector {
     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.`;
+${WORKSPACE_PAGING_INSTRUCTIONS}`;
   }
 
   protected override tools(): ConnectorTools {
@@ -51,7 +53,7 @@ CSV pages use page.columns and page.rows; never page.data or page.content. Only
       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.`,
+          `${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);