@ekairos/structure 1.21.62-beta.0 → 1.21.69-beta.0

package/dist/clearDataset.tool.js

@@ -9,8 +9,6 @@ export function createClearDatasetTool({ datasetId, sandboxId, env }) {
             reason: z.string().describe("Reason for clearing"),
         }),
         execute: async ({ reason }) => {
-            console.log("[ekairos/structure] clearDataset.tool execute begin");
-            console.log("[ekairos/structure] clearDataset.tool execute datasetId", datasetId);
             const outputPath = getDatasetOutputPath(datasetId);
             try {
                 await runDatasetSandboxCommandStep({ env, sandboxId, cmd: "rm", args: ["-f", outputPath] });
@@ -18,7 +16,6 @@ export function createClearDatasetTool({ datasetId, sandboxId, env }) {
             catch {
                 // best-effort
             }
-            console.log("[ekairos/structure] clearDataset.tool execute ok");
             return { success: true, message: "Cleared", reason };
         },
     });

package/dist/completeObject.tool.js

@@ -24,8 +24,6 @@ export function createCompleteObjectTool({ datasetId, sandboxId, env }) {
             message: "Provide result, resultJson or resultPath",
         }),
         execute: async (input) => {
-            console.log("[ekairos/structure] completeObject.tool execute begin");
-            console.log("[ekairos/structure] completeObject.tool execute datasetId", datasetId);
             const contextKey = `structure:${datasetId}`;
             const ctxResult = await structureGetContextStep({ env, contextKey });
             if (!ctxResult.ok)
@@ -37,7 +35,6 @@ export function createCompleteObjectTool({ datasetId, sandboxId, env }) {
             else {
                 let jsonText = input.resultJson ?? "";
                 if (!jsonText && input.resultPath) {
-                    console.log("[ekairos/structure] completeObject.tool execute readingResultPath");
                     const fileRead = await readDatasetSandboxTextFileStep({ env, sandboxId, path: input.resultPath });
                     jsonText = fileRead.text ?? "";
                 }
@@ -46,7 +43,6 @@ export function createCompleteObjectTool({ datasetId, sandboxId, env }) {
                 }
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
-                    console.log("[ekairos/structure] completeObject.tool execute invalidJson");
                     return { success: false, error: `Invalid JSON: ${message}` };
                 }
             }
@@ -62,17 +58,14 @@ export function createCompleteObjectTool({ datasetId, sandboxId, env }) {
                         const errors = Array.isArray(validator.errors)
                             ? validator.errors.map((err) => err.message || "Unknown validation error")
                             : ["Unknown validation error"];
-                        console.log("[ekairos/structure] completeObject.tool execute schemaValidationFailed");
                         return { success: false, error: errors.slice(0, 5).join("; ") };
                     }
                 }
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
-                    console.log("[ekairos/structure] completeObject.tool execute schemaValidateThrew");
                     return { success: false, error: `Failed to validate schema: ${message}` };
                 }
             }
-            console.log("[ekairos/structure] completeObject.tool execute ok");
             return { success: true, summary: input.summary, result: obj };
         },
     });

package/dist/completeRows.tool.js

@@ -18,8 +18,6 @@ export function createCompleteRowsTool({ datasetId, sandboxId, env }) {
             summary: z.string().describe("Summary of the completed dataset"),
         }),
         execute: async ({ summary }) => {
-            console.log("[ekairos/structure] completeRows.tool execute begin");
-            console.log("[ekairos/structure] completeRows.tool execute datasetId", datasetId);
             const contextKey = `structure:${datasetId}`;
             const outputPath = getDatasetOutputPath(datasetId);
             try {
@@ -27,7 +25,6 @@ export function createCompleteRowsTool({ datasetId, sandboxId, env }) {
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
-                console.log("[ekairos/structure] completeRows.tool execute missingOutputFile");
                 return { success: false, error: message };
             }
             const ctxResult = await structureGetContextStep({ env, contextKey });
@@ -36,7 +33,6 @@ export function createCompleteRowsTool({ datasetId, sandboxId, env }) {
             const content = (ctxResult.data?.content ?? {});
             const outputSchema = content?.structure?.outputSchema;
             if (!outputSchema?.schema) {
-                console.log("[ekairos/structure] completeRows.tool execute schemaMissing");
                 return { success: false, error: "Schema not found in database. Please generate schema first." };
             }
             const schemaJson = outputSchema.schema;
@@ -48,11 +44,9 @@ export function createCompleteRowsTool({ datasetId, sandboxId, env }) {
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 if (mode === "auto") {
-                    console.log("[ekairos/structure] completeRows.tool execute schemaCompileSkippedAuto");
                     validator = null;
                 }
                 else {
-                    console.log("[ekairos/structure] completeRows.tool execute schemaCompileFailed");
                     return { success: false, error: `Failed to compile schema: ${message}` };
                 }
             }
@@ -63,7 +57,6 @@ export function createCompleteRowsTool({ datasetId, sandboxId, env }) {
                     return validationResult;
                 totalValidRows = validationResult.validRowCount ?? 0;
             }
-            console.log("[ekairos/structure] completeRows.tool execute validRowCount", totalValidRows);
             const fileRead = await readDatasetSandboxFileStep({ env, sandboxId, path: outputPath });
             if (!fileRead.contentBase64)
                 return { success: false, error: "Empty file content" };
@@ -74,8 +67,6 @@ export function createCompleteRowsTool({ datasetId, sandboxId, env }) {
             });
             if (!uploadResult.ok)
                 return { success: false, error: uploadResult.error };
-            console.log("[ekairos/structure] completeRows.tool execute uploadedFileId", uploadResult.data.fileId);
-            console.log("[ekairos/structure] completeRows.tool execute ok");
             return {
                 success: true,
                 summary,

package/dist/executeCommand.tool.js

@@ -30,20 +30,15 @@ export function createExecuteCommandTool({ datasetId, sandboxId, env }) {
                 .describe("Name for the script file in snake_case (e.g., 'inspect_file', 'parse_csv', 'generate_output'). The file will be saved as <scriptName>.py in the workstation."),
         }),
         execute: async ({ pythonCode, scriptName }) => {
-            console.log("[ekairos/structure] executeCommand.tool execute begin");
-            console.log("[ekairos/structure] executeCommand.tool execute datasetId", datasetId);
-            console.log("[ekairos/structure] executeCommand.tool execute scriptName", scriptName);
             const workstation = getDatasetWorkstation(datasetId);
             const scriptNameWithExt = `${normalizeScriptName(scriptName)}.py`;
             const scriptFile = `${workstation}/${scriptNameWithExt}`;
-            console.log("[ekairos/structure] executeCommand.tool execute writingScript");
             await writeDatasetSandboxTextFileStep({
                 env,
                 sandboxId,
                 path: scriptFile,
                 text: pythonCode,
             });
-            console.log("[ekairos/structure] executeCommand.tool execute runningPython");
             const result = await runDatasetSandboxCommandStep({
                 env,
                 sandboxId,
@@ -58,7 +53,6 @@ export function createExecuteCommandTool({ datasetId, sandboxId, env }) {
             const stdoutCapped = isStdoutTruncated ? stdout.slice(0, MAX_STDOUT_CHARS) : stdout;
             const stderrCapped = isStderrTruncated ? stderr.slice(0, MAX_STDERR_CHARS) : stderr;
             if (exitCode !== 0) {
-                console.log("[ekairos/structure] executeCommand.tool execute failedExitCode");
                 return {
                     success: false,
                     exitCode,
@@ -73,7 +67,6 @@ export function createExecuteCommandTool({ datasetId, sandboxId, env }) {
                 };
             }
             if (stderr && (stderr.includes("Traceback") || stderr.toLowerCase().includes("error"))) {
-                console.log("[ekairos/structure] executeCommand.tool execute pythonErrorDetected");
                 return {
                     success: false,
                     exitCode,
@@ -87,7 +80,6 @@ export function createExecuteCommandTool({ datasetId, sandboxId, env }) {
                     stderrOriginalLength: stderr.length,
                 };
             }
-            console.log("[ekairos/structure] executeCommand.tool execute ok");
             return {
                 success: true,
                 exitCode,

package/dist/generateSchema.tool.js

@@ -11,11 +11,6 @@ export function createGenerateSchemaTool({ datasetId, sandboxId, env }) {
             schemaJson: z.string().describe("A JSON Schema string"),
         }),
         execute: async ({ schemaTitle, schemaDescription, schemaJson }) => {
-            console.log("[ekairos/structure] generateSchema.tool execute begin");
-            console.log("[ekairos/structure] generateSchema.tool execute datasetId", datasetId);
-            console.log("[ekairos/structure] generateSchema.tool execute sandboxId", sandboxId);
-            console.log("[ekairos/structure] generateSchema.tool execute schemaTitle", schemaTitle);
-            console.log("[ekairos/structure] generateSchema.tool execute schemaJsonLength", String(schemaJson ?? "").length);
             const schemaData = {
                 title: schemaTitle,
                 description: schemaDescription,
@@ -24,17 +19,12 @@ export function createGenerateSchemaTool({ datasetId, sandboxId, env }) {
                         return JSON.parse(schemaJson);
                     }
                     catch (e) {
-                        const message = e instanceof Error ? e.message : String(e);
-                        console.log("[ekairos/structure] generateSchema.tool execute invalidSchemaJson");
-                        console.log("[ekairos/structure] generateSchema.tool execute invalidSchemaJsonMessage", message);
-                        console.log("[ekairos/structure] generateSchema.tool execute invalidSchemaJsonPreview", String(schemaJson ?? "").slice(0, 300));
                         throw e;
                     }
                 })(),
             };
             const schemaPath = getDatasetOutputSchemaPath(datasetId);
             try {
-                console.log("[ekairos/structure] generateSchema.tool execute writingSchemaPath", schemaPath);
                 await writeDatasetSandboxTextFileStep({
                     env,
                     sandboxId,
@@ -43,17 +33,9 @@ export function createGenerateSchemaTool({ datasetId, sandboxId, env }) {
                 });
             }
             catch (e) {
-                console.log("[ekairos/structure] generateSchema.tool execute failed");
                 const message = e instanceof Error ? e.message : String(e);
-                console.log("[ekairos/structure] generateSchema.tool execute failedMessage", message);
-                if (e instanceof Error && e.stack) {
-                    console.log("[ekairos/structure] generateSchema.tool execute failedStack", e.stack);
-                }
-                console.log("[ekairos/structure] generateSchema.tool execute failedSchemaPath", schemaPath);
-                console.log("[ekairos/structure] generateSchema.tool execute failedHasEnv", Boolean(env));
                 return { success: false, error: message };
             }
-            console.log("[ekairos/structure] generateSchema.tool execute ok");
             return { success: true, message: "Schema written", schemaPath };
         },
     });

package/dist/rowsOutputSplit.d.ts

@@ -0,0 +1,25 @@
+import type { StructureRowsOutputPagingCursor } from "./rowsOutputPaging";
+export type StructureSplitRowsOutputToDatasetResult = {
+    datasetId?: string;
+    rowsWritten: number;
+    nextCursor: StructureRowsOutputPagingCursor;
+    done: boolean;
+};
+/**
+ * Step:
+ * Split a sandbox-local `output.jsonl` into a child dataset (also `output.jsonl`) of up to `limit` ROW entries.
+ *
+ * Key property:
+ * - Does NOT return rows; it persists a child dataset and returns only `{ datasetId, nextCursor, done }`.
+ *
+ * This is useful for workflows where you want to batch work (e.g. 300 rows) without moving large payloads
+ * through workflow/step params.
+ */
+export declare function structureSplitRowsOutputToDatasetStep(params: {
+    env: any;
+    sandboxId: string;
+    localPath: string;
+    cursor?: Partial<StructureRowsOutputPagingCursor>;
+    limit: number;
+    childDatasetId: string;
+}): Promise<StructureSplitRowsOutputToDatasetResult>;

package/dist/rowsOutputSplit.js

@@ -0,0 +1,131 @@
+import { getDatasetOutputPath, getDatasetWorkstation } from "./datasetFiles";
+import { readDatasetSandboxFileStep, runDatasetSandboxCommandStep } from "./sandbox/steps";
+import { getStoryRuntime } from "./runtime";
+/**
+ * Step:
+ * Split a sandbox-local `output.jsonl` into a child dataset (also `output.jsonl`) of up to `limit` ROW entries.
+ *
+ * Key property:
+ * - Does NOT return rows; it persists a child dataset and returns only `{ datasetId, nextCursor, done }`.
+ *
+ * This is useful for workflows where you want to batch work (e.g. 300 rows) without moving large payloads
+ * through workflow/step params.
+ */
+export async function structureSplitRowsOutputToDatasetStep(params) {
+    "use step";
+    const byteOffset = params.cursor?.byteOffset ?? 0;
+    const rowOffset = params.cursor?.rowOffset ?? 0;
+    const workstation = getDatasetWorkstation(params.childDatasetId);
+    const outPath = getDatasetOutputPath(params.childDatasetId);
+    await runDatasetSandboxCommandStep({
+        env: params.env,
+        sandboxId: params.sandboxId,
+        cmd: "mkdir",
+        args: ["-p", workstation],
+    });
+    // Read from parent jsonl and write a child jsonl containing only ROW records, preserving `{ type, data }` lines.
+    const py = [
+        "import sys, json",
+        "in_path = sys.argv[1]",
+        "out_path = sys.argv[2]",
+        "byte_offset = int(sys.argv[3])",
+        "row_offset = int(sys.argv[4])",
+        "limit = int(sys.argv[5])",
+        "rows_written = 0",
+        "next_byte = byte_offset",
+        "next_row = row_offset",
+        "with open(in_path, 'rb') as f_in:",
+        "  f_in.seek(byte_offset)",
+        "  with open(out_path, 'wb') as f_out:",
+        "    while rows_written < limit:",
+        "      line = f_in.readline()",
+        "      if not line:",
+        "        break",
+        "      next_byte = f_in.tell()",
+        "      try:",
+        "        obj = json.loads(line.decode('utf-8'))",
+        "      except Exception:",
+        "        continue",
+        "      if obj.get('type') != 'row':",
+        "        continue",
+        "      f_out.write(line if line.endswith(b'\\n') else (line + b'\\n'))",
+        "      rows_written += 1",
+        "      next_row += 1",
+        "done = rows_written < limit",
+        "print(json.dumps({",
+        "  'rowsWritten': rows_written,",
+        "  'nextByteOffset': next_byte,",
+        "  'nextRowOffset': next_row,",
+        "  'done': done,",
+        "}))",
+    ].join("\n");
+    const res = await runDatasetSandboxCommandStep({
+        env: params.env,
+        sandboxId: params.sandboxId,
+        cmd: "python",
+        args: ["-c", py, params.localPath, outPath, String(byteOffset), String(rowOffset), String(params.limit)],
+    });
+    if (res.exitCode !== 0) {
+        throw new Error(res.stderr || "Failed to split rows output to dataset");
+    }
+    const parsed = JSON.parse(String(res.stdout ?? "").trim());
+    const rowsWritten = Number(parsed?.rowsWritten ?? 0);
+    const nextCursor = {
+        byteOffset: Number(parsed?.nextByteOffset ?? byteOffset),
+        rowOffset: Number(parsed?.nextRowOffset ?? rowOffset),
+    };
+    const done = Boolean(parsed?.done);
+    // No work to persist: return only paging state.
+    if (rowsWritten <= 0) {
+        return { datasetId: undefined, rowsWritten: 0, nextCursor, done: true };
+    }
+    const fileRes = await readDatasetSandboxFileStep({
+        env: params.env,
+        sandboxId: params.sandboxId,
+        path: outPath,
+    });
+    const storyRuntime = await getStoryRuntime(params.env);
+    const db = storyRuntime.db;
+    const store = storyRuntime.store;
+    const storagePath = `/structure/${params.childDatasetId}/output.jsonl`;
+    const fileBuffer = Buffer.from(fileRes.contentBase64 ?? "", "base64");
+    const uploadResult = await db.storage.uploadFile(storagePath, fileBuffer, {
+        contentType: "application/x-ndjson",
+        contentDisposition: "output.jsonl",
+    });
+    const fileId = uploadResult?.data?.id;
+    if (!fileId)
+        throw new Error("Failed to upload child dataset output file to storage");
+    const contextKey = `structure:${params.childDatasetId}`;
+    const ctx = await store.getOrCreateContext({ key: contextKey });
+    const ctxId = ctx?.id;
+    if (!ctxId)
+        throw new Error("Failed to create child dataset context");
+    // Link the output file to the context (used by DatasetService.readRecordsFromFile).
+    await db.transact([db.tx.context_contexts[ctxId].link({ structure_output_file: fileId })]);
+    // Patch metadata under `structure` namespace (never clobber Story runtime keys).
+    const existingContent = (ctx?.content ?? {});
+    const existingStructure = (existingContent?.structure ?? {});
+    const updatedAt = Date.now();
+    await store.updateContextContent({ key: contextKey }, {
+        ...existingContent,
+        structure: {
+            ...existingStructure,
+            kind: "ekairos.structure",
+            version: Number(existingStructure?.version ?? 1),
+            structureId: params.childDatasetId,
+            output: "rows",
+            updatedAt,
+            outputs: {
+                ...(existingStructure?.outputs ?? {}),
+                rows: {
+                    format: "jsonl",
+                    fileId,
+                    storagePath,
+                    rowCount: rowsWritten,
+                },
+            },
+        },
+    });
+    return { datasetId: params.childDatasetId, rowsWritten, nextCursor, done };
+}

package/dist/sandbox/steps.js

@@ -1,7 +1,5 @@
 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"));
@@ -9,15 +7,10 @@ export async function createDatasetSandboxStep(params) {
     const created = await service.createSandbox(params);
     if (!created.ok)
         throw new Error(created.error);
-    console.log("[ekairos/structure] sandbox.step createSandbox ok");
-    console.log("[ekairos/structure] sandbox.step createSandbox sandboxId", created.data.sandboxId);
     return { sandboxId: created.data.sandboxId };
 }
 export async function runDatasetSandboxCommandStep(params) {
     "use step";
-    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"));
@@ -30,15 +23,10 @@ export async function runDatasetSandboxCommandStep(params) {
         stdout: result.data.output ?? "",
         stderr: result.data.error ?? "",
     };
-    console.log("[ekairos/structure] sandbox.step runCommand ok");
-    console.log("[ekairos/structure] sandbox.step runCommand exitCode", normalized.exitCode);
     return normalized;
 }
 export async function writeDatasetSandboxFilesStep(params) {
     "use step";
-    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"));
@@ -46,7 +34,6 @@ export async function writeDatasetSandboxFilesStep(params) {
     const result = await service.writeFiles(params.sandboxId, params.files);
     if (!result.ok)
         throw new Error(result.error);
-    console.log("[ekairos/structure] sandbox.step writeFiles ok");
 }
 /**
  * Workflow-safe helper:
@@ -66,9 +53,6 @@ export async function writeDatasetSandboxTextFileStep(params) {
 }
 export async function readDatasetSandboxFileStep(params) {
     "use step";
-    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"));
@@ -76,7 +60,6 @@ export async function readDatasetSandboxFileStep(params) {
     const result = await service.readFile(params.sandboxId, params.path);
     if (!result.ok)
         throw new Error(result.error);
-    console.log("[ekairos/structure] sandbox.step readFile ok");
     return result.data;
 }
 /**
@@ -94,8 +77,6 @@ export async function readDatasetSandboxTextFileStep(params) {
 }
 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"));
@@ -103,5 +84,4 @@ export async function stopDatasetSandboxStep(params) {
     const result = await service.stopSandbox(params.sandboxId);
     if (!result.ok)
         throw new Error(result.error);
-    console.log("[ekairos/structure] sandbox.step stopSandbox ok");
 }

package/dist/steps/persistObjectFromStory.step.js

@@ -39,11 +39,8 @@ export async function persistObjectResultFromStoryStep(params) {
     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");
-    console.log("[ekairos/structure] persistObjectFromStory.step execute datasetId", params.datasetId);
     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 ?? {}) : {};
@@ -58,7 +55,6 @@ export async function persistObjectResultFromStoryStep(params) {
             .trim();
         const obj = extractJsonObject(text);
         if (obj) {
-            console.log("[ekairos/structure] persistObjectFromStory.step execute parsedJsonOk");
             const patchResult = await structurePatchContextContentStep({
                 env: params.env,
                 contextKey,
@@ -80,10 +76,8 @@ export async function persistObjectResultFromStoryStep(params) {
                 const err = patchResult?.error ?? "Failed to persist object result";
                 throw new Error(err);
             }
-            console.log("[ekairos/structure] persistObjectFromStory.step execute savedOk");
             return { ok: true };
         }
     }
-    console.log("[ekairos/structure] persistObjectFromStory.step execute noJsonFound");
     return { ok: false };
 }

package/dist/structure.d.ts

@@ -18,6 +18,16 @@ export type StructureRowsReadResult = {
     cursor: StructureRowsOutputPagingCursor;
     done: boolean;
 };
+export type StructureRowsSplitResult = {
+    /**
+     * Child datasetId containing a JSONL `output.jsonl` with up to `limit` ROW entries.
+     * Omitted when there are no more rows to split.
+     */
+    datasetId?: string;
+    rowsWritten: number;
+    cursor: StructureRowsOutputPagingCursor;
+    done: boolean;
+};
 export type StructureRowsReader = {
     /**
      * Workflow-friendly rows reader.
@@ -33,6 +43,18 @@ export type StructureRowsReader = {
         cursor?: Partial<StructureRowsOutputPagingCursor>;
         limit?: number;
     }): Promise<StructureRowsReadResult>;
+    /**
+     * Split the rows output into a child dataset (jsonl) and return paging state.
+     *
+     * Unlike `read()`, this does not return `rows[]` (avoids moving payloads through params/results).
+     */
+    split(): Promise<StructureRowsSplitResult>;
+    split(cursor?: Partial<StructureRowsOutputPagingCursor>, limit?: number): Promise<StructureRowsSplitResult>;
+    split(params?: {
+        cursor?: Partial<StructureRowsOutputPagingCursor>;
+        limit?: number;
+        datasetId?: string;
+    }): Promise<StructureRowsSplitResult>;
 };
 export type StructureBuildResult = {
     datasetId: string;

package/dist/structure.js

@@ -1,9 +1,11 @@
 import { createStory, didToolExecute, USER_MESSAGE_TYPE, WEB_CHANNEL } from "@ekairos/story";
 import { getDatasetOutputPath, getDatasetOutputSchemaPath, getDatasetWorkstation } from "./datasetFiles";
 import { structureDownloadRowsOutputToSandboxStep, structureReadRowsOutputPageFromSandboxStep, } from "./rowsOutputPaging";
+import { structureSplitRowsOutputToDatasetStep } from "./rowsOutputSplit";
 import { createDatasetSandboxStep, readDatasetSandboxFileStep, readDatasetSandboxTextFileStep, runDatasetSandboxCommandStep, writeDatasetSandboxFilesStep, writeDatasetSandboxTextFileStep, } from "./sandbox/steps";
 import { readInstantFileStep } from "./file/steps";
 import { structureGetContextStep, structureGetContextWithRowsOutputFileStep, structureReadRowsOutputJsonlStep, } from "./dataset/steps";
+import { getWorkflowMetadata } from "workflow";
 import { buildStructurePrompt } from "./prompts";
 import { createExecuteCommandTool } from "./executeCommand.tool";
 import { createGenerateSchemaTool } from "./generateSchema.tool";
@@ -20,6 +22,21 @@ function createUuidV4() {
         return v.toString(16);
     });
 }
+function assertRunningInsideWorkflow(params) {
+    try {
+        const meta = getWorkflowMetadata();
+        const runId = meta?.workflowRunId;
+        if (!runId) {
+            throw new Error("Missing workflowRunId");
+        }
+        return meta;
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`@ekairos/structure: structure().build() must be called from a "use workflow" function. ` +
+            `datasetId=${params.datasetId}. getWorkflowMetadata failed: ${msg}`);
+    }
+}
 function guessTextFileExtension(mimeType, name) {
     const n = String(name ?? "").toLowerCase();
     if (n.includes("."))
@@ -38,18 +55,11 @@ async function ensureSandboxPrepared(params) {
     const workstation = getDatasetWorkstation(datasetId);
     const outputPath = getDatasetOutputPath(datasetId);
     if (state.initialized) {
-        console.log("[ekairos/structure] structure.ts ensureSandboxPrepared alreadyInitialized");
         return { preparedSources: state.sources, workstation, outputPath };
     }
-    console.log("[ekairos/structure] structure.ts ensureSandboxPrepared begin");
-    console.log("[ekairos/structure] structure.ts ensureSandboxPrepared datasetId", datasetId);
-    console.log("[ekairos/structure] structure.ts ensureSandboxPrepared sourcesCount", sources.length);
-    console.log("[ekairos/structure] structure.ts ensureSandboxPrepared sandbox.mkdir", workstation);
     const mkdirRes = await runDatasetSandboxCommandStep({ env, sandboxId, cmd: "mkdir", args: ["-p", workstation] });
-    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+openpyxl");
     const pipInstall = await runDatasetSandboxCommandStep({
         env,
         sandboxId,
@@ -65,8 +75,6 @@ async function ensureSandboxPrepared(params) {
     for (let i = 0; i < sources.length; i++) {
         const src = sources[i];
         if (src.kind === "file") {
-            console.log("[ekairos/structure] structure.ts ensureSandboxPrepared preparingFileSource");
-            console.log("[ekairos/structure] structure.ts ensureSandboxPrepared fileId", src.fileId);
             const file = await readInstantFileStep({ env, fileId: src.fileId });
             const fileName = String(file.contentDisposition ?? "");
             const ext = fileName.includes(".") ? fileName.substring(fileName.lastIndexOf(".")) : "";
@@ -76,13 +84,10 @@ async function ensureSandboxPrepared(params) {
                 sandboxId,
                 files: [{ path, contentBase64: file.contentBase64 }],
             });
-            console.log("[ekairos/structure] structure.ts ensureSandboxPrepared wroteFile path", path);
             prepared.push({ kind: "file", id: src.fileId, path });
             continue;
         }
         if (src.kind === "dataset") {
-            console.log("[ekairos/structure] structure.ts ensureSandboxPrepared preparingDatasetSource");
-            console.log("[ekairos/structure] structure.ts ensureSandboxPrepared sourceDatasetId", src.datasetId);
             const content = await structureReadRowsOutputJsonlStep({ env, structureId: src.datasetId });
             if (!content.ok) {
                 throw new Error(content.error);
@@ -93,38 +98,30 @@ async function ensureSandboxPrepared(params) {
                 sandboxId,
                 files: [{ path, contentBase64: content.data.contentBase64 }],
             });
-            console.log("[ekairos/structure] structure.ts ensureSandboxPrepared wroteDatasetJsonl path", path);
             prepared.push({ kind: "dataset", id: src.datasetId, path });
             continue;
         }
         if (src.kind === "text") {
-            console.log("[ekairos/structure] structure.ts ensureSandboxPrepared preparingTextSource");
             const ext = guessTextFileExtension(src.mimeType, src.name);
             const textId = `text_${i}`;
             const path = `${workstation}/${textId}${ext}`;
             await writeDatasetSandboxTextFileStep({ env, sandboxId, path, text: String(src.text ?? "") });
-            console.log("[ekairos/structure] structure.ts ensureSandboxPrepared wroteText path", path);
             prepared.push({ kind: "text", id: textId, path, name: src.name, mimeType: src.mimeType });
             continue;
         }
     }
     state.initialized = true;
     state.sources = prepared;
-    console.log("[ekairos/structure] structure.ts ensureSandboxPrepared ok");
     return { preparedSources: prepared, workstation, outputPath };
 }
 async function readSchemaFromSandboxIfPresent(params) {
     const schemaPath = getDatasetOutputSchemaPath(params.datasetId);
-    console.log("[ekairos/structure] structure.ts readSchemaFromSandboxIfPresent begin");
-    console.log("[ekairos/structure] structure.ts readSchemaFromSandboxIfPresent datasetId", params.datasetId);
-    console.log("[ekairos/structure] structure.ts readSchemaFromSandboxIfPresent schemaPath", schemaPath);
     const exists = await runDatasetSandboxCommandStep({
         env: params.env,
         sandboxId: params.sandboxId,
         cmd: "test",
         args: ["-f", schemaPath],
     });
-    console.log("[ekairos/structure] structure.ts readSchemaFromSandboxIfPresent existsExitCode", exists.exitCode);
     if (exists.exitCode !== 0)
         return null;
     const fileRead = await readDatasetSandboxFileStep({
@@ -143,11 +140,9 @@ async function readSchemaFromSandboxIfPresent(params) {
         return null;
     try {
         const parsed = JSON.parse(jsonText);
-        console.log("[ekairos/structure] structure.ts readSchemaFromSandboxIfPresent parsedOk");
         return parsed;
     }
     catch {
-        console.log("[ekairos/structure] structure.ts readSchemaFromSandboxIfPresent parsedFailed");
         return null;
     }
 }
@@ -156,13 +151,11 @@ function createStructureStoryDefinition(config) {
     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");
         const prev = stored?.content ?? {};
         const sandboxState = prev.sandboxState ?? { initialized: false, sources: [] };
         const existingSandboxId = prev.sandboxId ?? config.sandboxId ?? "";
         let sandboxId = existingSandboxId;
         if (!sandboxId) {
-            console.log("[ekairos/structure] structure.ts story.context creatingSandbox");
             const created = await createDatasetSandboxStep({ env, runtime: "python3.13", timeoutMs: 10 * 60 * 1000 });
             sandboxId = created.sandboxId;
         }
@@ -174,7 +167,6 @@ function createStructureStoryDefinition(config) {
             state: sandboxState,
         });
         if (config.mode === "schema" && config.outputSchema) {
-            console.log("[ekairos/structure] structure.ts story.context schemaMode outputSchemaProvided");
         }
         const promptContext = {
             datasetId,
@@ -231,15 +223,12 @@ function createStructureStoryDefinition(config) {
         };
     })
         .narrative(async (stored) => {
-        console.log("[ekairos/structure] structure.ts story.narrative begin");
         const promptContext = stored?.content?.promptContext;
         const base = buildStructurePrompt(promptContext);
         const userInstructions = String(config.instructions ?? "").trim();
         if (!userInstructions) {
-            console.log("[ekairos/structure] structure.ts story.narrative okNoUserInstructions");
             return base;
         }
-        console.log("[ekairos/structure] structure.ts story.narrative okWithUserInstructions");
         return [
             "## USER INSTRUCTIONS",
             "The following instructions were provided by the user. Apply them in addition to (and with higher priority than) the default instructions.",
@@ -250,14 +239,10 @@ function createStructureStoryDefinition(config) {
         ].join("\n");
     })
         .actions(async (stored, env) => {
-        console.log("[ekairos/structure] structure.ts story.actions begin");
         const sandboxId = stored?.content?.sandboxId;
         const output = config.output;
         const content = (stored?.content ?? {});
         const hasOutputSchema = Boolean(content?.structure?.outputSchema?.schema);
-        console.log("[ekairos/structure] structure.ts story.actions datasetId", datasetId);
-        console.log("[ekairos/structure] structure.ts story.actions mode", config.mode);
-        console.log("[ekairos/structure] structure.ts story.actions hasOutputSchema", hasOutputSchema);
         const actions = {
             executeCommand: createExecuteCommandTool({ datasetId, sandboxId, env }),
             clear: createClearDatasetTool({ datasetId, sandboxId, env }),
@@ -274,7 +259,6 @@ function createStructureStoryDefinition(config) {
                     ? createCompleteRowsTool({ datasetId, sandboxId, env })
                     : createCompleteObjectTool({ datasetId, sandboxId, env });
         }
-        console.log("[ekairos/structure] structure.ts story.actions ok");
         return actions;
     })
         .shouldContinue(({ reactionEvent }) => {
@@ -319,11 +303,9 @@ export function structure(env, opts) {
             return api;
         },
         async build(userPrompt) {
-            console.log("[ekairos/structure] structure.ts build begin");
-            console.log("[ekairos/structure] structure.ts build datasetId", datasetId);
-            console.log("[ekairos/structure] structure.ts build mode", mode);
-            console.log("[ekairos/structure] structure.ts build output", output);
-            console.log("[ekairos/structure] structure.ts build sourcesCount", sources.length);
+            // Guardrail: structure build MUST run inside workflow runtime ("use workflow").
+            const workflowMeta = assertRunningInsideWorkflow({ datasetId });
+            void workflowMeta?.workflowRunId;
             const contextKey = `structure:${datasetId}`;
             const storyConfig = {
                 datasetId,
@@ -344,22 +326,14 @@ export function structure(env, opts) {
                 };
             }
             async function runStory(evt) {
-                console.log("[ekairos/structure] structure.ts build storyReact begin");
-                console.log("[ekairos/structure] structure.ts build storyReact contextKey", contextKey);
-                console.log("[ekairos/structure] structure.ts build storyReact silent", true);
-                console.log("[ekairos/structure] structure.ts build storyReact eventId", evt?.id);
-                console.log("[ekairos/structure] structure.ts build storyReact eventType", evt?.type);
                 await story.react(evt, {
                     env,
                     context: { key: contextKey },
                     options: { silent: true, preventClose: true, sendFinish: false, maxIterations: 40, maxModelSteps: 10 },
                 });
-                console.log("[ekairos/structure] structure.ts build storyReact end");
                 // Tools are intentionally pure: persist completion outputs post-react by reading tool results from events.
                 const commit = await structureCommitFromEventsStep({ env, structureId: datasetId });
                 if (!commit.ok) {
-                    console.log("[ekairos/structure] structure.ts build commitFromEvents failed");
-                    console.log("[ekairos/structure] structure.ts build commitFromEvents error", commit.error);
                 }
             }
             async function getContextOrThrow() {
@@ -388,7 +362,6 @@ export function structure(env, opts) {
                 const content = (ctx?.content ?? {});
                 const hasSchema = Boolean(content?.structure?.outputSchema?.schema);
                 if (!hasSchema) {
-                    console.log("[ekairos/structure] structure.ts build autoSchemaMissing followUp");
                     await runStory(makeUserMessageEvent([
                         "CRITICAL: You did not generate a schema yet.",
                         "1) Investigate Sources using executeCommand (inspect paths, read files, infer structure).",
@@ -399,38 +372,30 @@ export function structure(env, opts) {
                 }
             }
             const needsSecondPass = output === "rows" ? !(await isRowsCompleted()) : !isObjectCompleted(ctx);
-            console.log("[ekairos/structure] structure.ts build needsSecondPass", needsSecondPass);
             if (needsSecondPass) {
-                console.log("[ekairos/structure] structure.ts build secondPass begin");
                 const followUpText = output === "rows"
                     ? "Finalize now: write output.jsonl to OutputPath and call complete."
                     : "Finalize now: call complete with summary and resultJson (inline JSON).";
                 await runStory(makeUserMessageEvent(followUpText));
                 ctx = await getContextOrThrow();
-                console.log("[ekairos/structure] structure.ts build secondPass end");
             }
             const stillIncompleteAfterSecondPass = output === "rows" ? !(await isRowsCompleted()) : !isObjectCompleted(ctx);
             if (stillIncompleteAfterSecondPass) {
-                console.log("[ekairos/structure] structure.ts build thirdPass begin");
                 const finalText = output === "rows"
                     ? "CRITICAL: Do not do anything else. Ensure output.jsonl exists at OutputPath and immediately call complete."
                     : "CRITICAL: Do not do anything else. Immediately call complete with summary and resultJson (inline JSON).";
                 await runStory(makeUserMessageEvent(finalText));
                 ctx = await getContextOrThrow();
-                console.log("[ekairos/structure] structure.ts build thirdPass end");
             }
             if (output === "rows" && !(await isRowsCompleted())) {
                 throw new Error("Rows output not completed");
             }
             if (output === "object" && !isObjectCompleted(ctx)) {
-                console.log("[ekairos/structure] structure.ts build objectNotCompleted tryingPersistFallback");
                 const persisted = await persistObjectResultFromStoryStep({ env, datasetId });
                 if (persisted.ok) {
-                    console.log("[ekairos/structure] structure.ts build persistFallback ok");
                     ctx = await getContextOrThrow();
                 }
                 else {
-                    console.log("[ekairos/structure] structure.ts build persistFallback failed");
                 }
             }
             if (output === "object" && !isObjectCompleted(ctx)) {
@@ -464,8 +429,40 @@ export function structure(env, opts) {
                         done: page.done,
                     };
                 },
+                split: async (cursorOrParams, limit) => {
+                    if (output !== "rows") {
+                        throw new Error("reader.split() 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,
+                            datasetId: undefined,
+                        };
+                    const childDatasetId = params?.datasetId ?? createUuidV4();
+                    const res = await structureSplitRowsOutputToDatasetStep({
+                        env,
+                        sandboxId: rowsSandboxRef.sandboxId,
+                        localPath: rowsSandboxRef.localPath,
+                        cursor: params?.cursor,
+                        limit: params?.limit ?? 300,
+                        childDatasetId,
+                    });
+                    return {
+                        datasetId: res.datasetId,
+                        rowsWritten: res.rowsWritten,
+                        cursor: res.nextCursor,
+                        done: res.done,
+                    };
+                },
             };
-            console.log("[ekairos/structure] structure.ts build ok");
             return output === "object" ? { datasetId, reader, dataset: ctx } : { datasetId, reader };
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekairos/structure",
-  "version": "1.21.62-beta.0",
+  "version": "1.21.69-beta.0",
   "description": "Ekairos Structure - Unified structured extraction (rows or object) from file/text/dataset inputs",
   "type": "module",
   "main": "dist/index.js",
@@ -36,12 +36,13 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@ekairos/domain": "^1.21.62-beta.0",
+    "@ekairos/domain": "^1.21.69-beta.0",
     "@ekairos/sandbox": "^1.21.60-beta.0",
     "@instantdb/admin": "^0.22.13",
     "@instantdb/core": "^0.22.13",
     "ai": "^5.0.95",
     "ajv": "^8.17.1",
+    "workflow": "4.0.1-beta.41",
     "zod": "^4.1.8"
   },
   "peerDependencies": {