@ekairos/structure 1.21.53-beta.0 → 1.21.56-beta.0

package/dist/rowsPagination.steps.d.ts

@@ -0,0 +1,59 @@
+import { type DatasetSandboxId } from "./sandbox/steps";
+/**
+ * Step 1: Download Structure rows output file (output.jsonl) into a sandbox.
+ *
+ * This enables pagination by reading chunks from the local sandbox filesystem.
+ */
+export declare function downloadStructureRowsOutputToSandboxStep(params: {
+    env: any;
+    sandboxId: DatasetSandboxId;
+    structureId: string;
+}): Promise<{
+    filePath: string;
+}>;
+/**
+ * @deprecated Prefer `downloadStructureRowsOutputToSandboxStep` (kept for symmetry with chunk naming).
+ *
+ * Note: The name includes `RowsOutputJsonl` to be explicit about the file format.
+ */
+export declare function structureDownloadRowsOutputJsonlToSandboxStep(params: {
+    env: any;
+    sandboxId: DatasetSandboxId;
+    structureId: string;
+}): Promise<{
+    filePath: string;
+}>;
+/**
+ * Step 2: Read a chunk/page of JSONL records from the downloaded sandbox file.
+ *
+ * Naming (consistent):
+ * - `structureReadRowsOutputJsonlStep` reads the whole file (base64)
+ * - `structureReadRowsOutputJsonlChunkStep` reads a paginated chunk from sandbox
+ *
+ * Offset/limit are line-based (0-indexed).
+ */
+export declare function structureReadRowsOutputJsonlChunkStep(params: {
+    env: any;
+    sandboxId: DatasetSandboxId;
+    structureId: string;
+    offset: number;
+    limit: number;
+}): Promise<{
+    records: any[];
+    nextOffset: number;
+    done: boolean;
+}>;
+/**
+ * @deprecated Use `structureReadRowsOutputJsonlChunkStep` instead (naming consistency).
+ */
+export declare function readStructureRowsChunkFromSandboxStep(params: {
+    env: any;
+    sandboxId: DatasetSandboxId;
+    structureId: string;
+    offset: number;
+    limit: number;
+}): Promise<{
+    records: any[];
+    nextOffset: number;
+    done: boolean;
+}>;

package/dist/rowsPagination.steps.js

@@ -0,0 +1,190 @@
+import { getDatasetWorkstation } from "./datasetFiles";
+import { runDatasetSandboxCommandStep, writeDatasetSandboxTextFileStep, } from "./sandbox/steps";
+async function getRowsOutputUrl(params) {
+    const { resolveStoryRuntime } = await import("@ekairos/story/runtime");
+    const runtime = (await resolveStoryRuntime(params.env));
+    const db = runtime.db;
+    const contextKey = `structure:${params.structureId}`;
+    const query = (await db.query({
+        context_contexts: {
+            $: { where: { key: contextKey }, limit: 1 },
+            structure_output_file: {},
+        },
+    }));
+    const ctx = query.context_contexts?.[0];
+    const linked = Array.isArray(ctx?.structure_output_file) ? ctx.structure_output_file[0] : ctx?.structure_output_file;
+    const url = linked?.url;
+    if (!url) {
+        throw new Error("Rows output file not found");
+    }
+    return String(url);
+}
+/**
+ * Step 1: Download Structure rows output file (output.jsonl) into a sandbox.
+ *
+ * This enables pagination by reading chunks from the local sandbox filesystem.
+ */
+export async function downloadStructureRowsOutputToSandboxStep(params) {
+    "use step";
+    const workstation = getDatasetWorkstation(params.structureId);
+    const filePath = `${workstation}/rows_output.jsonl`;
+    const scriptPath = `${workstation}/download_rows_output.py`;
+    // Ensure directory exists
+    await runDatasetSandboxCommandStep({
+        env: params.env,
+        sandboxId: params.sandboxId,
+        cmd: "mkdir",
+        args: ["-p", workstation],
+    });
+    const url = await getRowsOutputUrl({ env: params.env, structureId: params.structureId });
+    // Write a deterministic script to the sandbox and run it (no external deps).
+    await writeDatasetSandboxTextFileStep({
+        env: params.env,
+        sandboxId: params.sandboxId,
+        path: scriptPath,
+        text: [
+            "import argparse",
+            "import urllib.request",
+            "",
+            "def main():",
+            "  p = argparse.ArgumentParser()",
+            "  p.add_argument('--url', required=True)",
+            "  p.add_argument('--out', required=True)",
+            "  args = p.parse_args()",
+            "",
+            "  # Download to local sandbox file",
+            "  with urllib.request.urlopen(args.url, timeout=60) as r:",
+            "    data = r.read()",
+            "  with open(args.out, 'wb') as f:",
+            "    f.write(data)",
+            "",
+            "  print('ok')",
+            "  print('bytes', len(data))",
+            "",
+            "if __name__ == '__main__':",
+            "  main()",
+            "",
+        ].join("\n"),
+    });
+    const res = await runDatasetSandboxCommandStep({
+        env: params.env,
+        sandboxId: params.sandboxId,
+        cmd: "python",
+        args: [scriptPath, "--url", url, "--out", filePath],
+    });
+    if (res.exitCode !== 0) {
+        throw new Error(res.stderr || "Failed to download rows output into sandbox");
+    }
+    return { filePath };
+}
+/**
+ * @deprecated Prefer `downloadStructureRowsOutputToSandboxStep` (kept for symmetry with chunk naming).
+ *
+ * Note: The name includes `RowsOutputJsonl` to be explicit about the file format.
+ */
+export async function structureDownloadRowsOutputJsonlToSandboxStep(params) {
+    "use step";
+    return await downloadStructureRowsOutputToSandboxStep(params);
+}
+/**
+ * Step 2: Read a chunk/page of JSONL records from the downloaded sandbox file.
+ *
+ * Naming (consistent):
+ * - `structureReadRowsOutputJsonlStep` reads the whole file (base64)
+ * - `structureReadRowsOutputJsonlChunkStep` reads a paginated chunk from sandbox
+ *
+ * Offset/limit are line-based (0-indexed).
+ */
+export async function structureReadRowsOutputJsonlChunkStep(params) {
+    "use step";
+    const workstation = getDatasetWorkstation(params.structureId);
+    const filePath = `${workstation}/rows_output.jsonl`;
+    const scriptPath = `${workstation}/read_rows_chunk.py`;
+    await writeDatasetSandboxTextFileStep({
+        env: params.env,
+        sandboxId: params.sandboxId,
+        path: scriptPath,
+        text: [
+            "import argparse",
+            "import json",
+            "",
+            "def main():",
+            "  p = argparse.ArgumentParser()",
+            "  p.add_argument('--path', required=True)",
+            "  p.add_argument('--offset', type=int, required=True)",
+            "  p.add_argument('--limit', type=int, required=True)",
+            "  args = p.parse_args()",
+            "",
+            "  records = []",
+            "  current = 0",
+            "  taken = 0",
+            "  done = True",
+            "",
+            "  with open(args.path, 'r', encoding='utf-8', errors='replace') as f:",
+            "    for line in f:",
+            "      if current < args.offset:",
+            "        current += 1",
+            "        continue",
+            "      if taken >= args.limit:",
+            "        done = False",
+            "        break",
+            "      line = line.strip()",
+            "      if not line:",
+            "        current += 1",
+            "        continue",
+            "      try:",
+            "        records.append(json.loads(line))",
+            "      except Exception:",
+            "        # Skip invalid JSON line",
+            "        pass",
+            "      taken += 1",
+            "      current += 1",
+            "",
+            "  out = {",
+            "    'records': records,",
+            "    'nextOffset': args.offset + taken,",
+            "    'done': done,",
+            "  }",
+            "  print(json.dumps(out, ensure_ascii=False))",
+            "",
+            "if __name__ == '__main__':",
+            "  main()",
+            "",
+        ].join("\n"),
+    });
+    const res = await runDatasetSandboxCommandStep({
+        env: params.env,
+        sandboxId: params.sandboxId,
+        cmd: "python",
+        args: [
+            scriptPath,
+            "--path",
+            filePath,
+            "--offset",
+            String(Math.max(0, params.offset ?? 0)),
+            "--limit",
+            String(Math.max(1, params.limit ?? 1)),
+        ],
+    });
+    if (res.exitCode !== 0) {
+        throw new Error(res.stderr || "Failed to read rows chunk from sandbox");
+    }
+    const text = (res.stdout ?? "").trim();
+    if (!text) {
+        return { records: [], nextOffset: params.offset, done: true };
+    }
+    // The script prints a single JSON object.
+    const parsed = JSON.parse(text);
+    return {
+        records: Array.isArray(parsed?.records) ? parsed.records : [],
+        nextOffset: Number(parsed?.nextOffset ?? params.offset),
+        done: Boolean(parsed?.done),
+    };
+}
+/**
+ * @deprecated Use `structureReadRowsOutputJsonlChunkStep` instead (naming consistency).
+ */
+export async function readStructureRowsChunkFromSandboxStep(params) {
+    "use step";
+    return await structureReadRowsOutputJsonlChunkStep(params);
+}

package/dist/runtime.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Internal helper to resolve Story runtime from within workflow steps.
+ *
+ * Why dynamic import?
+ * - Some bundlers (notably Turbopack step bundles) can drop/hoist static imports in "use-step" modules,
+ *   causing `ReferenceError: resolveStoryRuntime is not defined`.
+ * - Using a dynamic import keeps the symbol resolution local to the step runtime.
+ */
+export declare function getStoryRuntime(env: any): Promise<import("@ekairos/story/runtime").StoryRuntime>;

package/dist/runtime.js

@@ -0,0 +1,12 @@
+/**
+ * Internal helper to resolve Story runtime from within workflow steps.
+ *
+ * Why dynamic import?
+ * - Some bundlers (notably Turbopack step bundles) can drop/hoist static imports in "use-step" modules,
+ *   causing `ReferenceError: resolveStoryRuntime is not defined`.
+ * - Using a dynamic import keeps the symbol resolution local to the step runtime.
+ */
+export async function getStoryRuntime(env) {
+    const { resolveStoryRuntime } = await import("@ekairos/story/runtime");
+    return await resolveStoryRuntime(env);
+}

package/dist/sandbox/steps.d.ts

@@ -71,4 +71,3 @@ export declare function stopDatasetSandboxStep(params: {
     env: any;
     sandboxId: DatasetSandboxId;
 }): Promise<void>;
-//# sourceMappingURL=steps.d.ts.map

package/dist/sandbox/steps.js

@@ -1,8 +1,8 @@
-import { resolveStoryRuntime } from "@ekairos/story/runtime";
 export async function createDatasetSandboxStep(params) {
     "use step";
     console.log("[ekairos/structure] sandbox.step createSandbox begin");
     console.log("[ekairos/structure] sandbox.step createSandbox runtime", params.runtime);
+    const { resolveStoryRuntime } = await import("@ekairos/story/runtime");
     const db = (await resolveStoryRuntime(params.env)).db;
     const { SandboxService } = (await import("@ekairos/sandbox"));
     const service = new SandboxService(db);
@@ -18,6 +18,7 @@ export async function runDatasetSandboxCommandStep(params) {
     console.log("[ekairos/structure] sandbox.step runCommand begin");
     console.log("[ekairos/structure] sandbox.step runCommand sandboxId", params.sandboxId);
     console.log("[ekairos/structure] sandbox.step runCommand cmd", params.cmd);
+    const { resolveStoryRuntime } = await import("@ekairos/story/runtime");
     const db = (await resolveStoryRuntime(params.env)).db;
     const { SandboxService } = (await import("@ekairos/sandbox"));
     const service = new SandboxService(db);
@@ -38,6 +39,7 @@ export async function writeDatasetSandboxFilesStep(params) {
     console.log("[ekairos/structure] sandbox.step writeFiles begin");
     console.log("[ekairos/structure] sandbox.step writeFiles sandboxId", params.sandboxId);
     console.log("[ekairos/structure] sandbox.step writeFiles paths", params.files.map((f) => f.path));
+    const { resolveStoryRuntime } = await import("@ekairos/story/runtime");
     const db = (await resolveStoryRuntime(params.env)).db;
     const { SandboxService } = (await import("@ekairos/sandbox"));
     const service = new SandboxService(db);
@@ -67,6 +69,7 @@ export async function readDatasetSandboxFileStep(params) {
     console.log("[ekairos/structure] sandbox.step readFile begin");
     console.log("[ekairos/structure] sandbox.step readFile sandboxId", params.sandboxId);
     console.log("[ekairos/structure] sandbox.step readFile path", params.path);
+    const { resolveStoryRuntime } = await import("@ekairos/story/runtime");
     const db = (await resolveStoryRuntime(params.env)).db;
     const { SandboxService } = (await import("@ekairos/sandbox"));
     const service = new SandboxService(db);
@@ -93,6 +96,7 @@ export async function stopDatasetSandboxStep(params) {
     "use step";
     console.log("[ekairos/structure] sandbox.step stopSandbox begin");
     console.log("[ekairos/structure] sandbox.step stopSandbox sandboxId", params.sandboxId);
+    const { resolveStoryRuntime } = await import("@ekairos/story/runtime");
     const db = (await resolveStoryRuntime(params.env)).db;
     const { SandboxService } = (await import("@ekairos/sandbox"));
     const service = new SandboxService(db);
@@ -101,4 +105,3 @@ export async function stopDatasetSandboxStep(params) {
         throw new Error(result.error);
     console.log("[ekairos/structure] sandbox.step stopSandbox ok");
 }
-//# sourceMappingURL=steps.js.map

package/dist/schema.d.ts

@@ -1,2 +1 @@
 export declare const structureDomain: any;
-//# sourceMappingURL=schema.d.ts.map

package/dist/schema.js

@@ -1,6 +1,7 @@
 import { i } from "@instantdb/core";
 import { domain } from "@ekairos/domain";
-import { storyDomain } from "@ekairos/story";
+import { storyDomain } from "@ekairos/story/schema";
+import { sandboxDomain } from "@ekairos/sandbox/schema";
 const entities = {
     // Keep $files compatible with Instant's base file fields used by structure flows.
     $files: i.entity({
@@ -29,5 +30,5 @@ const links = {
 const rooms = {};
 export const structureDomain = domain("structure")
     .includes(storyDomain)
+    .includes(sandboxDomain)
     .schema({ entities, links, rooms });
-//# sourceMappingURL=schema.js.map

package/dist/service.d.ts

@@ -38,4 +38,3 @@ export declare class DatasetService {
         fileId: string;
     }): Promise<ServiceResult<void>>;
 }
-//# sourceMappingURL=service.d.ts.map

package/dist/service.js

@@ -55,42 +55,22 @@ export class DatasetService {
             if (!url)
                 return { ok: false, error: "Rows output file not found" };
             async function* createGenerator(fileUrl) {
-                const response = await fetch(fileUrl);
-                if (!response.ok || !response.body) {
-                    throw new Error("Failed to download rows output file");
-                }
-                const reader = response.body.getReader();
-                const decoder = new TextDecoder("utf-8");
-                let buffer = "";
-                while (true) {
-                    const { value, done } = await reader.read();
-                    if (done)
-                        break;
-                    buffer += decoder.decode(value, { stream: true });
-                    let newlineIndex = buffer.indexOf("\n");
-                    while (newlineIndex !== -1) {
-                        const line = buffer.slice(0, newlineIndex);
-                        buffer = buffer.slice(newlineIndex + 1);
-                        const trimmed = line.trim();
-                        if (trimmed) {
-                            try {
-                                const record = JSON.parse(trimmed);
-                                yield record;
-                            }
-                            catch {
-                                // skip invalid
-                            }
-                        }
-                        newlineIndex = buffer.indexOf("\n");
-                    }
-                }
-                const remaining = buffer.trim();
-                if (remaining) {
+                // NOTE:
+                // We intentionally download the file fully (with retry/timeout) before yielding.
+                // This avoids partial processing + duplicates when network streams abort mid-way
+                // (e.g. undici `TypeError: terminated`).
+                const text = await fetchTextWithRetry(fileUrl, { attempts: 4, timeoutMs: 90000 });
+                // Parse JSONL (one JSON object per line)
+                const lines = text.split("\n");
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed)
+                        continue;
                     try {
-                        yield JSON.parse(remaining);
+                        yield JSON.parse(trimmed);
                     }
                     catch {
-                        // skip invalid
+                        // skip invalid line
                     }
                 }
             }
@@ -176,4 +156,33 @@ function createUuidV4() {
         return v.toString(16);
     });
 }
-//# sourceMappingURL=service.js.map
+async function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+async function fetchTextWithRetry(url, opts) {
+    let lastError = null;
+    for (let attempt = 1; attempt <= opts.attempts; attempt++) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), opts.timeoutMs);
+        try {
+            const res = await fetch(url, { signal: controller.signal });
+            if (!res.ok) {
+                throw new Error(`Failed to download rows output file (HTTP ${res.status})`);
+            }
+            return await res.text();
+        }
+        catch (e) {
+            lastError = e;
+            // Backoff: 250ms, 500ms, 1000ms...
+            if (attempt < opts.attempts) {
+                await sleep(250 * Math.pow(2, attempt - 1));
+                continue;
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    const message = lastError instanceof Error ? lastError.message : String(lastError);
+    throw new Error(message || "Failed to download rows output file");
+}

package/dist/steps/commitFromEvents.step.d.ts

@@ -10,4 +10,3 @@ export declare function structureCommitFromEventsStep(params: {
     ok: false;
     error: string;
 }>;
-//# sourceMappingURL=commitFromEvents.step.d.ts.map

package/dist/steps/commitFromEvents.step.js

@@ -1,4 +1,3 @@
-import { resolveStoryRuntime } from "@ekairos/story/runtime";
 function isToolCompletePart(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -23,6 +22,7 @@ export async function structureCommitFromEventsStep(params) {
     "use step";
     const contextKey = `structure:${params.structureId}`;
     try {
+        const { resolveStoryRuntime } = await import("@ekairos/story/runtime");
         const runtime = (await resolveStoryRuntime(params.env));
         const store = runtime.store;
         const db = runtime.db;
@@ -79,4 +79,3 @@ export async function structureCommitFromEventsStep(params) {
         return { ok: false, error: message };
     }
 }
-//# sourceMappingURL=commitFromEvents.step.js.map

package/dist/steps/persistObjectFromStory.step.d.ts

@@ -4,4 +4,3 @@ export declare function persistObjectResultFromStoryStep(params: {
 }): Promise<{
     ok: boolean;
 }>;
-//# sourceMappingURL=persistObjectFromStory.step.d.ts.map

package/dist/steps/persistObjectFromStory.step.js

@@ -1,5 +1,3 @@
-import { resolveStoryRuntime } from "@ekairos/story/runtime";
-import { structurePatchContextContentStep, structureGetContextStep } from "../dataset/steps";
 function extractJsonObject(text) {
     const trimmed = text.trim();
     if (!trimmed)
@@ -38,6 +36,7 @@ function extractJsonObject(text) {
 }
 export async function persistObjectResultFromStoryStep(params) {
     "use step";
+    const { resolveStoryRuntime } = await import("@ekairos/story/runtime");
     const runtime = (await resolveStoryRuntime(params.env));
     const store = runtime.store;
     console.log("[ekairos/structure] persistObjectFromStory.step execute begin");
@@ -45,6 +44,7 @@ export async function persistObjectResultFromStoryStep(params) {
     const contextKey = `structure:${params.datasetId}`;
     const events = await store.getEvents({ key: contextKey });
     console.log("[ekairos/structure] persistObjectFromStory.step execute eventsCount", Array.isArray(events) ? events.length : -1);
+    const { structurePatchContextContentStep, structureGetContextStep } = await import("../dataset/steps");
     const ctxResult = await structureGetContextStep({ env: params.env, contextKey });
     const existingContent = ctxResult.ok ? (ctxResult.data?.content ?? {}) : {};
     for (let i = events.length - 1; i >= 0; i--) {
@@ -87,4 +87,3 @@ export async function persistObjectResultFromStoryStep(params) {
     console.log("[ekairos/structure] persistObjectFromStory.step execute noJsonFound");
     return { ok: false };
 }
-//# sourceMappingURL=persistObjectFromStory.step.js.map

package/dist/structure.d.ts

@@ -1,3 +1,4 @@
+import { type StructureRowsOutputPagingCursor } from "./rowsOutputPaging";
 export type StructureSource = {
     kind: "file";
     fileId: string;
@@ -12,8 +13,35 @@ export type StructureSource = {
 };
 export type StructureMode = "auto" | "schema";
 export type StructureOutput = "rows" | "object";
+export type StructureRowsReadResult = {
+    rows: any[];
+    cursor: StructureRowsOutputPagingCursor;
+    done: boolean;
+};
+export type StructureRowsReader = {
+    /**
+     * Workflow-friendly rows reader.
+     *
+     * It lazily:
+     * - ensures a sandbox
+     * - downloads `/structure/<datasetId>/output.jsonl` into the sandbox (absolute dataset path)
+     * - reads the file in pages using an explicit cursor
+     */
+    read(): Promise<StructureRowsReadResult>;
+    read(cursor?: Partial<StructureRowsOutputPagingCursor>, limit?: number): Promise<StructureRowsReadResult>;
+    read(params?: {
+        cursor?: Partial<StructureRowsOutputPagingCursor>;
+        limit?: number;
+    }): Promise<StructureRowsReadResult>;
+};
 export type StructureBuildResult = {
     datasetId: string;
+    reader: StructureRowsReader;
+    /**
+     * Back-compat: in object output mode we still return the full context snapshot.
+     * Rows mode intentionally does not return the context, to keep the API light.
+     */
+    dataset?: any;
 };
 export declare function structure<Env extends {
     orgId: string;
@@ -27,8 +55,5 @@ export declare function structure<Env extends {
     schema(schema: any): /*elided*/ any;
     asRows(): /*elided*/ any;
     asObject(): /*elided*/ any;
-    build(userPrompt?: string): Promise<StructureBuildResult & {
-        dataset?: any;
-    }>;
+    build(userPrompt?: string): Promise<StructureBuildResult>;
 };
-//# sourceMappingURL=structure.d.ts.map

package/dist/structure.js

@@ -1,5 +1,6 @@
 import { createStory, didToolExecute, USER_MESSAGE_TYPE, WEB_CHANNEL } from "@ekairos/story";
 import { getDatasetOutputPath, getDatasetOutputSchemaPath, getDatasetWorkstation } from "./datasetFiles";
+import { structureDownloadRowsOutputToSandboxStep, structureReadRowsOutputPageFromSandboxStep, } from "./rowsOutputPaging";
 import { createDatasetSandboxStep, readDatasetSandboxFileStep, readDatasetSandboxTextFileStep, runDatasetSandboxCommandStep, writeDatasetSandboxFilesStep, writeDatasetSandboxTextFileStep, } from "./sandbox/steps";
 import { readInstantFileStep } from "./file/steps";
 import { structureGetContextStep, structureGetContextWithRowsOutputFileStep, structureReadRowsOutputJsonlStep, } from "./dataset/steps";
@@ -48,12 +49,13 @@ async function ensureSandboxPrepared(params) {
     console.log("[ekairos/structure] structure.ts ensureSandboxPrepared sandbox.mkdir exitCode", mkdirRes.exitCode);
     // Align with dataset sandbox behavior: install python deps up-front (once per dataset sandbox).
     // This avoids tool-level "install if used" heuristics and ensures scripts can import pandas.
-    console.log("[ekairos/structure] structure.ts ensureSandboxPrepared installingPythonDeps pandas");
+    console.log("[ekairos/structure] structure.ts ensureSandboxPrepared installingPythonDeps pandas+openpyxl");
     const pipInstall = await runDatasetSandboxCommandStep({
         env,
         sandboxId,
         cmd: "python",
-        args: ["-m", "pip", "install", "pandas", "--quiet", "--upgrade"],
+        // NOTE: pandas needs openpyxl to read .xlsx files.
+        args: ["-m", "pip", "install", "pandas", "openpyxl", "--quiet", "--upgrade"],
     });
     const installStderr = pipInstall.stderr ?? "";
     if (installStderr && (installStderr.includes("ERROR") || installStderr.includes("FAILED"))) {
@@ -151,7 +153,7 @@ async function readSchemaFromSandboxIfPresent(params) {
 }
 function createStructureStoryDefinition(config) {
     const datasetId = config.datasetId;
-    const model = config.model ?? "openai/gpt-5";
+    const model = config.model ?? "openai/gpt-5.2";
     const story = createStory("ekairos.structure")
         .context(async (stored, env) => {
         console.log("[ekairos/structure] structure.ts story.context begin");
@@ -434,10 +436,38 @@ export function structure(env, opts) {
             if (output === "object" && !isObjectCompleted(ctx)) {
                 throw new Error("Object output not completed");
             }
+            let rowsSandboxRef = null;
+            const reader = {
+                read: async (cursorOrParams, limit) => {
+                    if (output !== "rows") {
+                        throw new Error("reader.read() is only supported for output=rows");
+                    }
+                    if (!rowsSandboxRef) {
+                        rowsSandboxRef = await structureDownloadRowsOutputToSandboxStep({
+                            env,
+                            structureId: datasetId,
+                        });
+                    }
+                    const params = cursorOrParams && typeof cursorOrParams === "object" && ("cursor" in cursorOrParams || "limit" in cursorOrParams)
+                        ? cursorOrParams
+                        : { cursor: cursorOrParams, limit };
+                    const page = await structureReadRowsOutputPageFromSandboxStep({
+                        env,
+                        sandboxId: rowsSandboxRef.sandboxId,
+                        localPath: rowsSandboxRef.localPath,
+                        cursor: params?.cursor,
+                        limit: params?.limit ?? 200,
+                    });
+                    return {
+                        rows: page.rows,
+                        cursor: page.nextCursor,
+                        done: page.done,
+                    };
+                },
+            };
             console.log("[ekairos/structure] structure.ts build ok");
-            return { datasetId, dataset: ctx };
+            return output === "object" ? { datasetId, reader, dataset: ctx } : { datasetId, reader };
         },
     };
     return api;
 }
-//# sourceMappingURL=structure.js.map