@ekairos/dataset 1.22.48-beta.development.0 → 1.22.50-beta.development.0

package/dist/sandbox/steps.js

@@ -2,12 +2,19 @@ import { execFile } from "node:child_process";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { promisify } from "node:util";
-import { getContextRuntime } from "@ekairos/events/runtime";
+import { SandboxService } from "@ekairos/sandbox";
 const execFileAsync = promisify(execFile);
 const localSandboxRoots = new Map();
 function isLocalDatasetSandboxMode() {
     return String(process.env.DATASET_TEST_LOCAL_SANDBOX ?? "").trim() === "1";
 }
+async function getRuntimeDb(runtime) {
+    if (!runtime) {
+        throw new Error("Dataset sandbox step requires runtime.");
+    }
+    const db = runtime.db;
+    return typeof db === "function" ? await db.call(runtime) : db;
+}
 function getLocalSandboxRoot(sandboxId) {
     return (localSandboxRoots.get(sandboxId) ||
         path.resolve(process.cwd(), "test-results", "dataset-sandboxes", sandboxId));
@@ -63,10 +70,11 @@ export async function createDatasetSandboxStep(params) {
         await ensureLocalSandboxRoot(sandboxId);
         return { sandboxId };
     }
-    const db = (await getContextRuntime(params.env)).db;
-    const { SandboxService } = (await import("@ekairos/sandbox"));
+    const db = await getRuntimeDb(params.runtime);
     const service = new SandboxService(db);
-    const created = await service.createSandbox(params);
+    const sandboxParams = { ...params, runtime: params.sandboxRuntime };
+    delete sandboxParams.sandboxRuntime;
+    const created = await service.createSandbox(sandboxParams);
     if (!created.ok)
         throw new Error(created.error);
     return { sandboxId: created.data.sandboxId };
@@ -80,8 +88,7 @@ export async function runDatasetSandboxCommandStep(params) {
             args: params.args,
         });
     }
-    const db = (await getContextRuntime(params.env)).db;
-    const { SandboxService } = (await import("@ekairos/sandbox"));
+    const db = await getRuntimeDb(params.runtime);
     const service = new SandboxService(db);
     const result = await service.runCommand(params.sandboxId, params.cmd, params.args ?? []);
     if (!result.ok)
@@ -101,8 +108,7 @@ export async function writeDatasetSandboxFilesStep(params) {
         }
         return;
     }
-    const db = (await getContextRuntime(params.env)).db;
-    const { SandboxService } = (await import("@ekairos/sandbox"));
+    const db = await getRuntimeDb(params.runtime);
     const service = new SandboxService(db);
     const result = await service.writeFiles(params.sandboxId, params.files);
     if (!result.ok)
@@ -114,8 +120,7 @@ export async function readDatasetSandboxFileStep(params) {
         const content = await fs.readFile(params.path);
         return { contentBase64: Buffer.from(content).toString("base64") };
     }
-    const db = (await getContextRuntime(params.env)).db;
-    const { SandboxService } = (await import("@ekairos/sandbox"));
+    const db = await getRuntimeDb(params.runtime);
     const service = new SandboxService(db);
     const result = await service.readFile(params.sandboxId, params.path);
     if (!result.ok)
@@ -130,8 +135,7 @@ export async function stopDatasetSandboxStep(params) {
         localSandboxRoots.delete(params.sandboxId);
         return;
     }
-    const db = (await getContextRuntime(params.env)).db;
-    const { SandboxService } = (await import("@ekairos/sandbox"));
+    const db = await getRuntimeDb(params.runtime);
     const service = new SandboxService(db);
     const result = await service.stopSandbox(params.sandboxId);
     if (!result.ok)

package/dist/transform/filepreview.d.ts

@@ -18,5 +18,5 @@ export type TransformSourcePreviewContext = {
 interface PreviewOptions {
     headLines?: number;
 }
-export declare function generateSourcePreview(env: any, sandboxId: string, sourcePath: string, datasetId: string, options?: PreviewOptions): Promise<TransformSourcePreviewContext>;
+export declare function generateSourcePreview(runtime: any, sandboxId: string, sourcePath: string, datasetId: string, options?: PreviewOptions): Promise<TransformSourcePreviewContext>;
 export {};

package/dist/transform/filepreview.js

@@ -1,11 +1,11 @@
 import { getDatasetWorkstation } from "../datasetFiles.js";
 import { runDatasetSandboxCommandStep, writeDatasetSandboxFilesStep } from "../sandbox/steps.js";
 const DEFAULT_HEAD_LINES = 50;
-async function runPythonSnippet(env, sandboxId, datasetId, scriptName, code, args, description) {
+async function runPythonSnippet(runtime, sandboxId, datasetId, scriptName, code, args, description) {
     const workstation = getDatasetWorkstation(datasetId);
     const scriptPath = `${workstation}/${scriptName}.py`;
     await writeDatasetSandboxFilesStep({
-        env,
+        runtime,
         sandboxId,
         files: [
             {
@@ -15,7 +15,7 @@ async function runPythonSnippet(env, sandboxId, datasetId, scriptName, code, arg
         ],
     });
     const result = await runDatasetSandboxCommandStep({
-        env,
+        runtime,
         sandboxId,
         cmd: "python",
         args: [scriptPath, ...args],
@@ -30,7 +30,7 @@ async function runPythonSnippet(env, sandboxId, datasetId, scriptName, code, arg
         stderr,
     };
 }
-export async function generateSourcePreview(env, sandboxId, sourcePath, datasetId, options = {}) {
+export async function generateSourcePreview(runtime, sandboxId, sourcePath, datasetId, options = {}) {
     const context = {
         totalRows: 0,
     };
@@ -54,7 +54,7 @@ try:
 except Exception as e:
     print(str(e))
 `;
-    const meta = await runPythonSnippet(env, sandboxId, datasetId, "jsonl_count", countScript, [sourcePath], "Counts number of JSONL records with type='row'");
+    const meta = await runPythonSnippet(runtime, sandboxId, datasetId, "jsonl_count", countScript, [sourcePath], "Counts number of JSONL records with type='row'");
     context.metadata = meta;
     try {
         if (meta.stdout) {
@@ -89,7 +89,7 @@ try:
 except Exception as e:
     print(str(e))
 `;
-    const head = await runPythonSnippet(env, sandboxId, datasetId, "jsonl_head", headScript, [sourcePath, String(headLines)], `Reads the first ${headLines} JSONL row records`);
+    const head = await runPythonSnippet(runtime, sandboxId, datasetId, "jsonl_head", headScript, [sourcePath, String(headLines)], `Reads the first ${headLines} JSONL row records`);
     context.head = head;
     return context;
 }

package/dist/transform/index.d.ts

@@ -1,2 +1,2 @@
-export { createTransformDatasetStory, type TransformDatasetAgentParams, type TransformDatasetContext, } from "./transform-dataset.agent.js";
+export { createTransformDatasetContext, type TransformDatasetAgentParams, type TransformDatasetContext, } from "./transform-dataset.agent.js";
 export { transformDataset, type TransformDatasetInput, type TransformDatasetResult, } from "./transformDataset.js";

package/dist/transform/index.js

@@ -1,2 +1,2 @@
-export { createTransformDatasetStory, } from "./transform-dataset.agent.js";
+export { createTransformDatasetContext, } from "./transform-dataset.agent.js";
 export { transformDataset, } from "./transformDataset.js";

package/dist/transform/prompts.js

@@ -97,19 +97,22 @@ function buildInstructions(context) {
         .up()
         .ele("Step", { number: "2", name: "Plan Mapping" })
         .ele("Action").txt("Plan a deterministic mapping from source data fields to the output schema fields (normalize names, types, and formats).").up()
-        .ele("Note").txt("If fields are missing, set defaults; if types differ, coerce consistently. When working with multiple sources, decide how to combine or relate them.").up()
+        .ele("Note").txt("If fields are missing, set defaults; if types differ, coerce consistently. When working with multiple sources, decide how to combine or relate them. Output field names must remain exactly as declared by the output schema.").up()
         .up()
         .ele("Step", { number: "3", name: "Transform" })
         .ele("Action").txt("Use executeCommand to run a Python script that reads source JSONL file(s) and writes transformed records to output.jsonl. Keep line-per-record JSON objects with { 'type': 'row', 'data': { ... } }.").up()
         .ele("Requirement").txt(`Write file to: ${outputPath}`).up()
+        .ele("Requirement").txt("Every data object MUST use the exact property names from OutputSchema required/properties keys. Do not translate, localize, rename, or infer alternative field names.").up()
         .ele("Requirement").txt("Do not print large data to stdout; only progress and summaries.").up()
         .up()
         .ele("Step", { number: "4", name: "Validate and Complete" })
         .ele("Action").txt("Call completeDataset to validate against the output schema and mark as completed.").up()
+        .ele("Behavior").txt("If completeDataset returns success:false, inspect validation details, rewrite output.jsonl, and call completeDataset again. Do not stop until completeDataset returns success:true.").up()
         .up()
         .up()
         .ele("Rules")
         .ele("Rule").txt("Output must strictly match the output schema for each record in data.").up()
+        .ele("Rule").txt("OutputSchema property names are authoritative. Field names are a technical contract; only field values may preserve source language.").up()
         .ele("Rule").txt("Each line in output.jsonl must be a standalone JSON object with {type:'row', data:{...}}.").up()
         .ele("Rule").txt("Do not include headers, summaries, or metadata as records.").up()
         .ele("Rule").txt("Be robust to malformed lines in source: skip or sanitize, but do not crash.").up()

package/dist/transform/transform-dataset.agent.d.ts

@@ -28,6 +28,10 @@ export type TransformDatasetAgentParams = {
     sandboxId?: string;
     reactor?: ContextReactor<any, any>;
 };
+export type TransformDatasetRunOptions = {
+    prompt?: string;
+    durable?: boolean;
+};
 export type TransformDatasetResult = {
     id: string;
     status?: string;
@@ -39,7 +43,7 @@ export type TransformDatasetResult = {
     createdAt?: number;
     updatedAt?: number;
 };
-export declare function createTransformDatasetStory<Env extends {
+export declare function createTransformDatasetContext<Env extends {
     orgId: string;
 }>(params: {
     sourceDatasetIds: string[];
@@ -51,8 +55,10 @@ export declare function createTransformDatasetStory<Env extends {
     reactor?: ContextReactor<any, any>;
 }): {
     datasetId: string;
-    transform(env: Env, prompt?: string): Promise<{
+    transform(runtime: {
+        env: Env;
+    }, options?: TransformDatasetRunOptions): Promise<{
         datasetId: string;
     }>;
-    story: any;
+    context: any;
 };

package/dist/transform/transform-dataset.agent.js

@@ -1,5 +1,5 @@
-import { createContext, didToolExecute, INPUT_TEXT_ITEM_TYPE, WEB_CHANNEL } from "@ekairos/events";
-import { createCompleteDatasetTool } from "../completeDataset.tool.js";
+import { createContext, INPUT_TEXT_ITEM_TYPE, WEB_CHANNEL } from "@ekairos/events";
+import { createCompleteDatasetTool, didCompleteDatasetSucceed } from "../completeDataset.tool.js";
 import { createExecuteCommandTool } from "../executeCommand.tool.js";
 import { createClearDatasetTool } from "../clearDataset.tool.js";
 import { buildTransformDatasetPrompt } from "./prompts.js";
@@ -8,19 +8,27 @@ import { id } from "@instantdb/admin";
 import { generateSourcePreview } from "./filepreview.js";
 import { datasetReadOutputJsonlStep, datasetUpdateSchemaStep } from "../dataset/steps.js";
 import { runDatasetSandboxCommandStep, writeDatasetSandboxFilesStep } from "../sandbox/steps.js";
-import { createEventsReactRuntime } from "../eventsReactRuntime.js";
-async function ensureSourcesInSandbox(env, sandboxId, datasetId, sourceDatasetIds, state) {
+async function awaitContextRun(run) {
+    if (!run)
+        return;
+    if (run.returnValue) {
+        await run.returnValue;
+        return;
+    }
+    await run;
+}
+async function ensureSourcesInSandbox(runtime, sandboxId, datasetId, sourceDatasetIds, state) {
     if (state.initialized) {
         return { sourcePaths: state.sourcePaths, outputPath: getDatasetOutputPath(datasetId) };
     }
     const workstation = getDatasetWorkstation(datasetId);
-    await runDatasetSandboxCommandStep({ env, sandboxId, cmd: "mkdir", args: ["-p", workstation] });
+    await runDatasetSandboxCommandStep({ runtime, sandboxId, cmd: "mkdir", args: ["-p", workstation] });
     const sourcePaths = [];
     for (const sourceDatasetId of sourceDatasetIds) {
         const sourcePath = `${workstation}/source_${sourceDatasetId}.jsonl`;
-        const source = await datasetReadOutputJsonlStep({ env, datasetId: sourceDatasetId });
+        const source = await datasetReadOutputJsonlStep({ runtime, datasetId: sourceDatasetId });
         await writeDatasetSandboxFilesStep({
-            env,
+            runtime,
             sandboxId,
             files: [{ path: sourcePath, contentBase64: source.contentBase64 }],
         });
@@ -30,22 +38,22 @@ async function ensureSourcesInSandbox(env, sandboxId, datasetId, sourceDatasetId
     state.initialized = true;
     return { sourcePaths, outputPath: getDatasetOutputPath(datasetId) };
 }
-function createTransformDatasetStoryDefinition(params) {
+function createTransformDatasetContextDefinition(params) {
     const datasetId = params.datasetId ?? id();
     const model = params.model ?? "openai/gpt-5";
-    let storyBuilder = createContext("dataset.transform")
-        .context(async (stored, env) => {
+    let contextBuilder = createContext("dataset.transform")
+        .context(async (stored, _env, runtime) => {
         const previous = stored?.content ?? {};
         const sandboxState = previous?.sandboxState ?? { initialized: false, sourcePaths: [] };
         const sandboxId = previous?.sandboxId ?? params.sandboxId ?? "";
         if (!sandboxId) {
             throw new Error("dataset_sandbox_required");
         }
-        const { sourcePaths, outputPath } = await ensureSourcesInSandbox(env, sandboxId, datasetId, params.sourceDatasetIds, sandboxState);
+        const { sourcePaths, outputPath } = await ensureSourcesInSandbox(runtime, sandboxId, datasetId, params.sourceDatasetIds, sandboxState);
         const sourcePreviews = [];
         for (const sp of sourcePaths) {
             try {
-                const preview = await generateSourcePreview(env, sandboxId, sp.path, datasetId);
+                const preview = await generateSourcePreview(runtime, sandboxId, sp.path, datasetId);
                 sourcePreviews.push({ datasetId: sp.datasetId, preview });
             }
             catch {
@@ -54,7 +62,7 @@ function createTransformDatasetStoryDefinition(params) {
         }
         // Persist output schema on the dataset record (so completeDataset validates against it)
         await datasetUpdateSchemaStep({
-            env,
+            runtime,
             datasetId,
             schema: params.outputSchema,
             status: "schema_complete",
@@ -91,40 +99,40 @@ function createTransformDatasetStoryDefinition(params) {
         .narrative(async (stored) => {
         return String(stored?.content?.system ?? "");
     })
-        .actions(async (stored, env) => {
+        .actions(async (stored, _env, runtime) => {
         const sandboxId = stored?.content?.sandboxId ?? params.sandboxId ?? "";
         return {
             executeCommand: createExecuteCommandTool({
                 datasetId,
                 sandboxId,
-                env,
+                runtime,
             }),
             completeDataset: createCompleteDatasetTool({
                 datasetId,
                 sandboxId,
-                env,
+                runtime,
             }),
             clearDataset: createClearDatasetTool({
                 datasetId,
                 sandboxId,
-                env,
+                runtime,
             }),
         };
     })
         .shouldContinue(({ reactionEvent }) => {
-        return !didToolExecute(reactionEvent, "completeDataset");
+        return !didCompleteDatasetSucceed(reactionEvent);
     });
     if (params.reactor) {
-        storyBuilder = storyBuilder.reactor(params.reactor);
+        contextBuilder = contextBuilder.reactor(params.reactor);
     }
     else {
-        storyBuilder = storyBuilder.model(model);
+        contextBuilder = contextBuilder.model(model);
     }
-    const story = storyBuilder.build();
-    return { datasetId, story };
+    const context = contextBuilder.build();
+    return { datasetId, context };
 }
-export function createTransformDatasetStory(params) {
-    const { datasetId, story } = createTransformDatasetStoryDefinition({
+export function createTransformDatasetContext(params) {
+    const { datasetId, context } = createTransformDatasetContextDefinition({
         sourceDatasetIds: params.sourceDatasetIds,
         outputSchema: params.outputSchema,
         instructions: params.instructions,
@@ -135,7 +143,7 @@ export function createTransformDatasetStory(params) {
     });
     return {
         datasetId,
-        async transform(env, prompt) {
+        async transform(runtime, options = {}) {
             const datasetCountText = params.sourceDatasetIds.length === 1
                 ? "the source dataset"
                 : `${params.sourceDatasetIds.length} source datasets`;
@@ -148,22 +156,21 @@ export function createTransformDatasetStory(params) {
                     parts: [
                         {
                             type: "text",
-                            text: prompt ??
+                            text: options.prompt ??
                                 `Transform ${datasetCountText} into a new dataset matching the provided output schema`,
                         },
                     ],
                 },
             };
-            const runtime = createEventsReactRuntime(env);
-            const shell = await story.react(triggerEvent, {
-                runtime,
+            const shell = await context.react(triggerEvent, {
+                runtime: runtime,
                 context: { key: `dataset:${datasetId}` },
-                durable: false,
+                durable: options.durable ?? false,
                 options: { silent: true, preventClose: true, sendFinish: false, maxIterations: 20, maxModelSteps: 5 },
             });
-            await shell.run;
+            await awaitContextRun(shell.run);
             return { datasetId };
         },
-        story,
+        context,
     };
 }

package/dist/transform/transformDataset.d.ts

@@ -1,3 +1,4 @@
+import type { AnyDatasetRuntime } from "../builder/types.js";
 export type TransformDatasetInput = {
     datasets: Array<{
         id: string;
@@ -14,6 +15,6 @@ export type TransformDatasetResult = {
 };
 /**
  * Workflow-compatible dataset transform.
- * Executes the transform story and returns datasetId + preview rows.
+ * Executes the transform context and returns datasetId + preview rows.
  */
-export declare function transformDataset(input: TransformDatasetInput): Promise<TransformDatasetResult>;
+export declare function transformDataset(runtime: AnyDatasetRuntime, input: TransformDatasetInput): Promise<TransformDatasetResult>;

package/dist/transform/transformDataset.js

@@ -1,6 +1,5 @@
-import { getContextEnv } from "@ekairos/events/runtime";
 import { datasetPreviewRowsStep } from "../dataset/steps.js";
-import { createTransformDatasetStory } from "./transform-dataset.agent.js";
+import { createTransformDatasetContext } from "./transform-dataset.agent.js";
 function buildInstructions(input) {
     const sources = input.datasets
         .map((d, idx) => {
@@ -22,18 +21,20 @@ function buildInstructions(input) {
 }
 /**
  * Workflow-compatible dataset transform.
- * Executes the transform story and returns datasetId + preview rows.
+ * Executes the transform context and returns datasetId + preview rows.
  */
-export async function transformDataset(input) {
-    const env = await getContextEnv();
-    const { datasetId, story } = createTransformDatasetStory({
+export async function transformDataset(runtime, input) {
+    const transformContext = createTransformDatasetContext({
         sourceDatasetIds: input.datasets.map((d) => d.id),
         outputSchema: input.outputSchema,
         instructions: buildInstructions(input),
         datasetId: input.datasetId,
         model: input.model,
     });
-    await story.transform(env);
-    const preview = await datasetPreviewRowsStep({ datasetId });
-    return { datasetId, previewRows: preview.rows };
+    await transformContext.transform(runtime);
+    const preview = await datasetPreviewRowsStep({
+        runtime,
+        datasetId: transformContext.datasetId,
+    });
+    return { datasetId: transformContext.datasetId, previewRows: preview.rows };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekairos/dataset",
-  "version": "1.22.48-beta.development.0",
+  "version": "1.22.50-beta.development.0",
   "description": "Pulzar Dataset Tools",
   "type": "module",
   "main": "dist/index.js",
@@ -35,6 +35,16 @@
       "import": "./dist/query/index.js",
       "default": "./dist/query/index.js"
     },
+    "./agents": {
+      "types": "./dist/agents.d.ts",
+      "import": "./dist/agents.js",
+      "default": "./dist/agents.js"
+    },
+    "./skill": {
+      "types": "./dist/skill.d.ts",
+      "import": "./dist/skill.js",
+      "default": "./dist/skill.js"
+    },
     "./file/scripts": {
       "default": "./dist/file/scripts"
     },
@@ -49,14 +59,15 @@
     "typecheck": "tsc --noEmit",
     "typecheck:tests": "tsc --noEmit -p tsconfig.typecheck.json",
     "test": "vitest run -c vitest.config.mts",
+    "test:workflow": "vitest run -c vitest.workflow.config.mts",
     "test:direct": "vitest run -c vitest.config.mts src/tests/dataset.builder.instant.test.ts",
     "test:tool": "vitest run -c vitest.config.mts src/tests/materializeDataset.tool.instant.test.ts",
     "test:ai-sdk:instant": "vitest run -c vitest.codex.config.mts src/tests/materializeDataset.ai-sdk.instant.test.ts"
   },
   "dependencies": {
-    "@ekairos/domain": "^1.22.48-beta.development.0",
-    "@ekairos/events": "^1.22.48-beta.development.0",
-    "@ekairos/sandbox": "^1.22.48-beta.development.0",
+    "@ekairos/domain": "^1.22.50-beta.development.0",
+    "@ekairos/events": "^1.22.50-beta.development.0",
+    "@ekairos/sandbox": "^1.22.50-beta.development.0",
     "@instantdb/admin": "0.22.158",
     "@instantdb/core": "0.22.142",
     "ai": "^5.0.44",
@@ -69,7 +80,10 @@
     "@ekairos/openai-reactor": "workspace:*",
     "@ekairos/tsconfig": "workspace:*",
     "@types/node": "^24.5.0",
+    "@workflow/serde": "5.0.0-beta.0",
+    "@workflow/vitest": "5.0.0-beta.1",
     "dotenv": "^17.2.3",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "workflow": "5.0.0-beta.1"
   }
 }

package/dist/eventsReactRuntime.d.ts

@@ -1,21 +0,0 @@
-import { eventsDomain } from "@ekairos/events";
-export type EventsReactRuntime<Env extends Record<string, unknown>> = {
-    env: Env;
-    db(): Promise<any>;
-    resolve(): Promise<{
-        db: any;
-        meta: () => {
-            domain: typeof eventsDomain;
-            schema: ReturnType<typeof eventsDomain.toInstantSchema>;
-            context?: unknown;
-            contextString?: string;
-        };
-    }>;
-    meta: () => {
-        domain: typeof eventsDomain;
-        schema: ReturnType<typeof eventsDomain.toInstantSchema>;
-        context?: unknown;
-        contextString?: string;
-    };
-};
-export declare function createEventsReactRuntime<Env extends Record<string, unknown>>(env: Env): EventsReactRuntime<Env>;

package/dist/eventsReactRuntime.js

@@ -1,25 +0,0 @@
-import { eventsDomain } from "@ekairos/events";
-import { getContextRuntime } from "@ekairos/events/runtime";
-export function createEventsReactRuntime(env) {
-    const meta = () => ({
-        domain: eventsDomain,
-        schema: eventsDomain.toInstantSchema(),
-        context: typeof eventsDomain.context === "function" ? eventsDomain.context() : undefined,
-        contextString: typeof eventsDomain.contextString === "function"
-            ? eventsDomain.contextString()
-            : undefined,
-    });
-    const runtime = {
-        env,
-        async db() {
-            const resolved = (await getContextRuntime(env));
-            return resolved.db;
-        },
-        async resolve() {
-            const db = await runtime.db();
-            return { db, meta };
-        },
-        meta,
-    };
-    return runtime;
-}