@springbrand/agent-runtime 0.3.0-alpha.7 → 0.3.0-alpha.9

package/src/tools/assistant/plan.ts

@@ -0,0 +1,98 @@
+import { StringEnum, Type, type Static } from "@earendil-works/pi-ai";
+import type { PiToolCandidate } from "../runtime/contracts";
+import { result } from "../runtime/result";
+import { candidate } from "./candidate";
+
+const updatePlanParameters = Type.Object({
+  steps: Type.Array(Type.Object({
+    text: Type.String({
+      description: "The step, phrased as a short imperative.",
+    }),
+    status: StringEnum(["pending", "in_progress", "done"] as const, {
+      description:
+        'Current status. Use "done" for a finished step; never use "completed".',
+    }),
+  }, { additionalProperties: false }), {
+    description:
+      "The complete, ordered plan. Overwrites any previously reported plan.",
+  }),
+}, { additionalProperties: false });
+
+type UpdatePlanArguments = Static<typeof updatePlanParameters>;
+
+function normalizeStepStatus(
+  status: unknown,
+): UpdatePlanArguments["steps"][number]["status"] {
+  switch (status) {
+    case "done":
+    case "completed": // Anthropic models sometimes output "completed"
+      return "done";
+    case "in_progress":
+    case "inProgress": // camelCase variant
+      return "in_progress";
+    default: // covers "pending", "todo" (Google), and any other unknown value
+      return "pending";
+  }
+}
+
+export function normalizeUpdatePlanArguments(
+  input: unknown,
+): UpdatePlanArguments {
+  if (input === null || typeof input !== "object") {
+    return input as UpdatePlanArguments;
+  }
+  const value = input as Record<string, unknown>;
+  let steps = value.steps;
+  if (typeof steps === "string") {
+    try {
+      steps = JSON.parse(steps);
+    } catch {
+      return input as UpdatePlanArguments;
+    }
+  }
+  if (!Array.isArray(steps)) return input as UpdatePlanArguments;
+  return {
+    ...value,
+    steps: steps.map((step) => {
+      if (step === null || typeof step !== "object") return step;
+      const s = step as Record<string, unknown>;
+      const { step: stepAlias, title: titleAlias, ...rest } = s;
+      const alias = typeof stepAlias === "string" ? stepAlias : titleAlias;
+      const text = typeof rest.text === "string"
+        ? rest.text
+        : typeof alias === "string"
+          ? alias
+          : undefined;
+      return {
+        ...rest,
+        ...(text === undefined ? {} : { text }),
+        status: normalizeStepStatus(s.status),
+      };
+    }),
+  } as UpdatePlanArguments;
+}
+
+export function updatePlanPiToolCandidate(): PiToolCandidate {
+  return {
+    ...candidate({
+      name: "update_plan",
+      label: "Update plan",
+      description:
+        "Maintain the user-visible plan for the current task. Required input: steps. Call this whenever a task involves 2 or more steps, and again every time the plan or a step's status changes. Always pass the FULL plan — it replaces the previous plan entirely (idempotent overwrite), so omitted steps disappear.",
+      parameters: updatePlanParameters,
+      prepareArguments: normalizeUpdatePlanArguments,
+      async execute(_toolCallId, input) {
+        return result({
+          ok: true,
+          total: input.steps.length,
+          done: input.steps.filter((step) => step.status === "done").length,
+        });
+      },
+    }),
+    unattendedExecution: {
+      capability: "runtime-ui",
+      operation: "update",
+    },
+    exposureMode: "direct",
+  };
+}

package/src/tools/{time.ts → assistant/time.ts}

@@ -1,6 +1,6 @@
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
-import type { PiToolCandidate } from "./compiler";
+import type { PiToolCandidate } from "../runtime/contracts";
 
 export const GET_TIME_TOOL_NAME = "get_time";
 

package/src/tools/{core-host.ts → codemode/adapter.ts}

@@ -1,38 +1,31 @@
+import { truncateResponse, truncateResult, type ProxyToolOutput } from "@cloudflare/codemode";
+import { generateTypes } from "@cloudflare/codemode/ai";
 import {
-  createWorkspaceStateBackend,
   STATE_TYPES,
+  createWorkspaceStateBackend,
   type StateBackend,
   type WorkspaceFsLike,
 } from "@cloudflare/shell";
-import {
-  truncateResponse,
-  truncateResult,
-  type ProxyToolOutput,
-} from "@cloudflare/codemode";
 import { createBrowserTools } from "@cloudflare/think/tools/browser";
-import {
-  createExecuteRuntime,
-  type CreateExecuteToolOptions,
-} from "@cloudflare/think/tools/execute";
+import { createExecuteRuntime } 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";
 import type {
   RuntimeBrowserPort,
+  RuntimeCodeExecutionFactory,
   RuntimeCodeExecutionPort,
   WorkspacePort,
-} from "../config/ports";
+} from "../../config/ports";
+import { serializeOutput } from "../../lib/artifacts";
+import { piCandidatesToAiTools } from "../adapters/pi-to-ai";
 import {
-  WorkspaceStateConnector,
   WORKSPACE_PAGING_INSTRUCTIONS,
   WORKSPACE_STATE_TYPES,
-} from "./workspace-state-connector";
-import type { RuntimeCodeExecutionFactory } from "../config/ports";
-import { serializeOutput } from "../lib/artifacts";
-import type { PiToolCandidate } from "./compiler";
-import { piCandidatesToAiTools } from "./nested-tools";
+  WorkspaceStateConnector,
+} from "./workspace-connector";
 
-// 本文件沿用 `../../index.ts` 入口定义的 Workspace、Port 和 Tool Candidate 术语。
+// 将 Cloudflare 的 Code Mode 与浏览器执行能力适配为 Runtime Port；Pi Tool 定义位于同目录 index.ts。
 
 const CODEMODE_SANDBOX_TIMEOUT_MS = 55_000;
 export type WorkspaceAccessMode = "none" | "read" | "write";
@@ -103,7 +96,7 @@ When an asset already exists in Workspace, use state.cp to copy it into the curr
 
 Never create or write data URLs, base64 image strings, or embedded binary payloads in Code Mode.
 
-Copy a remote asset into Workspace with tools.materialize_url({ url, destination }). Raw fetch remains available. Do not carry large responses, binary payloads, data URLs, or base64 assets through Code Mode.
+Copy a remote asset into Workspace with tools.materialize_url({ url, destination }). Do not carry large responses, binary payloads, data URLs, or base64 assets through Code Mode.
 
 After materialization, reference the Workspace file by a relative path. Website HTML and CSS must reference relative Workspace assets, never temporary external URLs or data URLs.
 
@@ -193,12 +186,12 @@ function projectCodeModeResult(details: unknown): unknown {
   const calls = Array.isArray(output.calls) ? output.calls : [];
   const callSummary = calls.length > 0
     ? {
-        total: calls.length,
-        failed: calls.filter(({ state }) => state === "error").length,
-        methods: [...new Set(calls.map(({ method }) => method))]
-          .map((method) => truncateResponse(method, { maxChars: 256 }))
-          .slice(0, 100),
-      }
+      total: calls.length,
+      failed: calls.filter(({ state }) => state === "error").length,
+      methods: [...new Set(calls.map(({ method }) => method))]
+        .map((method) => truncateResponse(method, { maxChars: 256 }))
+        .slice(0, 100),
+    }
     : undefined;
   const common = {
     status: output.status,
@@ -224,7 +217,7 @@ function projectCodeModeResult(details: unknown): unknown {
 // 上游把 Code Mode 类工具交付为 AI SDK tool；本仓只取 description 和 execute 两件，
 // 并在这里就地校验，使装配期缺件立刻失败，而不是等模型调用时才炸。
 function toCodeExecutionPort(
-  tool: ToolSet[string],
+  tool: Pick<ToolSet[string], "description" | "execute">,
   name: string,
   project: (details: unknown) => AgentToolResult<unknown> = result,
 ): RuntimeCodeExecutionPort {
@@ -345,35 +338,40 @@ export function createWorkspaceCodeExecutionFactory(options: {
         options.workspace,
         options.workspaceAccessMode,
       );
-      const workspaceState = state && options.workspace.readFilePage
+      const workspaceState = state
         ? new WorkspaceStateConnector(
-            options.ctx,
-            state,
-            options.workspace as WorkspacePort & {
-              readFilePage: NonNullable<WorkspacePort["readFilePage"]>;
-            },
-          )
+          options.ctx,
+          state,
+          options.workspace,
+        )
         : undefined;
       const createPort = (
         innerResults: AgentToolResult<unknown>[],
-        stateOptions: Pick<CreateExecuteToolOptions, "state" | "connectors">,
       ) => {
         let nestedCallOrdinal = 0;
-        const { tool } = createExecuteRuntime({
+        const tools = piCandidatesToAiTools(candidates, {
+          fallbackToolCallId: (name) =>
+            `codemode:${++nestedCallOrdinal}:${name}`,
+          onResult: (value) => innerResults.push(value),
+        });
+        const { tool, runtime } = createExecuteRuntime({
           ctx: options.ctx,
           loader: options.loader,
           globalOutbound: options.outbound,
-          tools: piCandidatesToAiTools(candidates, {
-            fallbackToolCallId: (name) =>
-              `codemode:${++nestedCallOrdinal}:${name}`,
-            onResult: (value) => innerResults.push(value),
-          }),
+          tools,
           timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
-          ...stateOptions,
+          connectors: workspaceState ? [workspaceState] : [],
           name: "execute",
         });
+        // Generate the official description from the same connectors used to execute.
+        const description = runtime.tool({
+          connectorHints: {
+            tools: "host tools as async functions; call tools.<method>({ ... }) inside execute. Discover additional methods with codemode.search and codemode.describe.",
+            state: "the workspace filesystem. Every method takes ONE object argument: state.readFile({ path }), state.writeFile({ path, content }), state.readdir({ path }).",
+          }
+        }).description;
         return toCodeExecutionPort(
-          tool,
+          { ...tool, description },
           "execute",
           (details) => codeExecutionResult(
             projectCodeModeResult(details),
@@ -381,21 +379,24 @@ export function createWorkspaceCodeExecutionFactory(options: {
           ),
         );
       };
-      // Inherit the complete official state description; custom connectors otherwise lose its hints.
-      const description = createPort([], state ? { state } : {}).description;
+      // External declarations opt out of constrained sampling and remain discoverable on demand.
+      const inlineCandidates = candidates.filter(({ tool }) => tool.constrainedSampling !== false);
+      const toolTypes = inlineCandidates.length > 0
+        ? generateTypes(piCandidatesToAiTools(inlineCandidates, {}), "tools")
+        : undefined;
+      const description = createPort([]).description;
       return {
         description: [
           description,
+          ...(toolTypes ? ["## Code Mode Tool types\nUse these signatures inside execute. The Tool routing list defines which methods also have a top-level entry.\n\n```ts\n" + toolTypes + "\n```"] : []),
           ...(state ? [
             "## Workspace type reference\nOnly methods exposed by connector discovery are callable.\n\n```ts\n" +
-              (workspaceState ? WORKSPACE_STATE_TYPES : STATE_TYPES) + "\n```",
+            (options.workspace.readFilePage ? WORKSPACE_STATE_TYPES : STATE_TYPES) + "\n```",
           ] : []),
-          ...(workspaceState ? [WORKSPACE_PAGING_INSTRUCTIONS] : []),
+          ...(state && options.workspace.readFilePage ? [WORKSPACE_PAGING_INSTRUCTIONS] : []),
           SPRINGBRAND_CODE_MODE_POLICY,
         ].join("\n\n"),
-        execute: (input) => createPort(
-          [], workspaceState ? { connectors: [workspaceState] } : state ? { state } : {},
-        ).execute(input),
+        execute: (input) => createPort([]).execute(input),
       };
     },
   };

package/src/tools/{core.ts → codemode/index.ts}

@@ -1,29 +1,14 @@
-import type {
-  AgentTool,
-  AgentToolResult,
-} from "@earendil-works/pi-agent-core";
+import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
-import type {
-  RuntimeCodeExecutionPort,
-} from "../config/ports";
-import { serializeOutput } from "../lib/artifacts";
-import type { PiLoadedExtension } from "../context/extension/assembly";
-import type { PiToolCandidate } from "./compiler";
-
-// 本文件沿用 `../../index.ts` 入口定义的 Extension、Port 和 Tool Candidate 术语。
-
-// 把核心工具的结构化值投影为 Pi 同时需要的文本和 details。
-// 本文件中所有核心工具 execute 方法在返回宿主结果时调用它。
-// 统一使用 `serializeOutput()` 可以保持模型可见文本和持久化 details 来自同一个值。
-function result(details: unknown): AgentToolResult<unknown> {
-  return {
-    content: [{ type: "text", text: serializeOutput(details).text }],
-    details,
-  };
-}
+import type { RuntimeCodeExecutionPort } from "../../config/ports";
+import { serializeOutput } from "../../lib/artifacts";
+import type { PiToolCandidate } from "../runtime/contracts";
+import { result } from "../runtime/result";
 
 const BROWSER_IMAGE_MAX_BYTES = 5 * 1024 * 1024;
+
 const BROWSER_IMAGE_MAX_BASE64_CHARS = Math.ceil(BROWSER_IMAGE_MAX_BYTES / 3) * 4;
+
 const BROWSER_IMAGE_MIME_TYPES = new Set([
   "image/jpeg",
   "image/png",
@@ -87,7 +72,7 @@ function browserResult(details: unknown): AgentToolResult<unknown> {
 
   const calls = Array.isArray(outer.calls) ? outer.calls : [];
   let screenshotCall: Record<string, unknown> | undefined;
-  for (let index = calls.length - 1; index >= 0; index -= 1) {
+  for (let index = calls.length - 1;index >= 0;index -= 1) {
     const call = record(calls[index]);
     const args = record(call?.args);
     if (
@@ -117,39 +102,39 @@ function browserResult(details: unknown): AgentToolResult<unknown> {
 
   const projectedCalls = Array.isArray(outer.calls)
     ? outer.calls.map((call) => {
-        const entry = record(call);
-        const args = record(entry?.args);
-        const callResult = record(entry?.result);
-        if (
-          entry?.connector !== "cdp" ||
-          entry.method !== "send" ||
-          args?.method !== "Page.captureScreenshot" ||
-          typeof callResult?.data !== "string"
-        ) return call;
-        const callFormat = record(args.params)?.format;
-        return {
-          ...entry,
-          result: {
-            ...callResult,
-            data: browserImageMetadata(
-              callResult.data,
-              screenshotMimeType(callFormat),
-            ),
-          },
-        };
-      })
+      const entry = record(call);
+      const args = record(entry?.args);
+      const callResult = record(entry?.result);
+      if (
+        entry?.connector !== "cdp" ||
+        entry.method !== "send" ||
+        args?.method !== "Page.captureScreenshot" ||
+        typeof callResult?.data !== "string"
+      ) return call;
+      const callFormat = record(args.params)?.format;
+      return {
+        ...entry,
+        result: {
+          ...callResult,
+          data: browserImageMetadata(
+            callResult.data,
+            screenshotMimeType(callFormat),
+          ),
+        },
+      };
+    })
     : outer.calls;
   const projectedDetails = {
     ...outer,
     result: inner
       ? {
-          ...inner,
-          image: projectedImage,
-        }
+        ...inner,
+        image: projectedImage,
+      }
       : {
-          image: projectedImage,
-          note: "Screenshot recovered from the Page.captureScreenshot result.",
-        },
+        image: projectedImage,
+        note: "Screenshot recovered from the Page.captureScreenshot result.",
+      },
     ...("calls" in outer ? { calls: projectedCalls } : {}),
   };
   return {
@@ -163,47 +148,7 @@ function browserResult(details: unknown): AgentToolResult<unknown> {
   };
 }
 
-// #region Extension discovery
-
-const noParameters = Type.Object({}, { additionalProperties: false });
-
-/**
- * 为当前已加载 Extension 列表创建一个 Pi 工具候选项。
- *
- * Runtime 组装层在 Extension 装载完成后调用，模型需要发现当前可用扩展时使用该工具。
- *
- * 候选项捕获准备阶段的只读列表，这与 pinned Runtime 组装保持一致，不能在执行时重新扫描出另一份 Extension 集合。
- */
-export function listExtensionsPiToolCandidate(
-  extensions: readonly PiLoadedExtension[],
-): PiToolCandidate {
-  const tool: AgentTool<typeof noParameters> = {
-    name: "list_extensions",
-    label: "List extensions",
-    description: "List all currently loaded extensions and their tools.",
-    parameters: noParameters,
-    // 返回这个 pinned Runtime 已加载的 Extension 快照。
-    // Pi 工具循环在模型选择 `list_extensions` 时调用，调用前允许 Turn 取消。
-    // 同时返回 count 和原列表，使模型既能快速判空又不丢失 Extension 细节。
-    async execute(_toolCallId, _input, signal) {
-      signal?.throwIfAborted();
-      return result({
-        count: extensions.length,
-        extensions,
-      });
-    },
-  };
-  return {
-    owner: "core:extensions",
-    requiredExecutionLevel: "low",
-    retry: "idempotent",
-    tool,
-  };
-}
-
-// #endregion
 
-// #region Code Mode
 
 const executeParameters = Type.Object({
   code: Type.String({
@@ -213,6 +158,7 @@ const executeParameters = Type.Object({
       "Plain JavaScript async function. TypeScript annotations are not supported.",
   }),
 }, { additionalProperties: false });
+
 const CODEMODE_EXECUTE_TIMEOUT_MS = 60_000;
 
 // 把模型提供的代码交给 Codemode Runtime 执行，并在外层再压一道截止。
@@ -331,5 +277,3 @@ export function browserExecutionPiToolCandidate(
     tool,
   };
 }
-
-// #endregion

package/src/tools/codemode/workspace-connector.ts

@@ -0,0 +1,198 @@
+import type { ConnectorTools } from "@cloudflare/codemode";
+import { STATE_TYPES } from "@cloudflare/shell";
+import type { StateBackend } from "@cloudflare/shell/workers";
+import { StateConnector } from "@cloudflare/shell/workers";
+import type { WorkspacePort } from "../../config/ports";
+
+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_STATE_TYPES = `${READ_FILE_PAGE_TYPES}\n${STATE_TYPES.replace(
+  /\n\};$/u,
+  '\n  /** CSV pages have columns and rows; never data. Omit offset first, then pass nextOffset until null. */\n  readFilePage(args: { path: string; offset?: number }): Promise<WorkspaceFilePage | null>;\n};',
+)}`;
+
+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.`;
+
+export class WorkspaceStateConnector extends StateConnector {
+  constructor(
+    ctx: DurableObjectState | ExecutionContext,
+    backend: StateBackend,
+    private readonly workspace: WorkspacePort,
+  ) {
+    super(ctx, backend);
+  }
+
+  protected override instructions(): string {
+    const base = super.instructions();
+    return this.workspace.readFilePage ? `${base}
+
+${WORKSPACE_PAGING_INSTRUCTIONS}` : base;
+  }
+
+  protected override tools(): ConnectorTools {
+    const tools = super.tools();
+    const readFile = tools.readFile!;
+    const mkdir = tools.mkdir!;
+    const readFilePage = this.workspace.readFilePage;
+    return {
+      ...tools,
+      mkdir: {
+        ...mkdir,
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: { type: "string", minLength: 1 },
+            options: {
+              type: "object",
+              properties: { recursive: { type: "boolean" } },
+              additionalProperties: false,
+            },
+          },
+          required: ["path"],
+          additionalProperties: false,
+        },
+        execute: (args, context) => mkdir.execute(mkdirInput(args), context),
+      },
+      ...(readFilePage
+        ? {
+            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: unknown) => {
+              const input = readFilePageInput(args);
+              return readFilePage.call(this.workspace, input.path, input.offset);
+            },
+          },
+        }
+        : {}),
+    };
+  }
+
+  override async getTypeScriptTypes(): Promise<string> {
+    return this.workspace.readFilePage ? WORKSPACE_STATE_TYPES : STATE_TYPES;
+  }
+}
+
+function mkdirInput(value: unknown): {
+  path: string;
+  options?: { recursive?: boolean };
+} {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("state.mkdir requires an object argument");
+  }
+  const input = value as Record<string, unknown>;
+  if (Object.keys(input).some((key) => !["path", "options"].includes(key))) {
+    throw new Error("state.mkdir accepts only path and options");
+  }
+  if (typeof input.path !== "string" || input.path.length === 0) {
+    throw new Error("state.mkdir requires path");
+  }
+  if (input.options === undefined) return { path: input.path };
+  if (!input.options || typeof input.options !== "object" || Array.isArray(input.options)) {
+    throw new Error("state.mkdir options must be an object");
+  }
+  const options = input.options as Record<string, unknown>;
+  if (Object.keys(options).some((key) => key !== "recursive")) {
+    throw new Error("state.mkdir options accepts only recursive");
+  }
+  if (options.recursive !== undefined && typeof options.recursive !== "boolean") {
+    throw new Error("state.mkdir options.recursive must be boolean");
+  }
+  return {
+    path: input.path,
+    options: options.recursive === undefined
+      ? {}
+      : { recursive: options.recursive },
+  };
+}
+
+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 }),
+  };
+}