@agent-native/core 0.87.0 → 0.90.1

package/dist/data-programs/actions.js

@@ -0,0 +1,279 @@
+/**
+ * Actions exposed for the data-programs primitive: save/preview/run/list/get/
+ * delete. Mirrors the repo's `defineAction` conventions (see
+ * `../mcp/actions/create-org-service-token.ts`, `../sharing/actions/*`).
+ *
+ * Security: every action that EXECUTES code (save — which dry-runs before
+ * persisting — preview, run) or MUTATES stored code (delete) is
+ * `toolCallable: false`, so the sandboxed tools-iframe bridge can never
+ * invoke stored/arbitrary code under the opener's session — the same
+ * rationale as `provider-api-request`. `list`/`get` are read-only and
+ * access-scoped through the sharing helpers.
+ */
+import { z } from "zod";
+import { defineAction } from "../action.js";
+import { hashDataProgramParams, runDataProgram } from "./execute.js";
+import { archiveDataProgram, getDataProgram, getLatestRun, listDataPrograms, upsertDataProgram, MIN_REFRESH_TTL_MS, } from "./store.js";
+const SLUG_RE = /^[a-z0-9][a-z0-9_-]*$/;
+const paramsRecord = z.record(z.string(), z.unknown()).optional();
+function compactColumns(schema) {
+    return schema ?? [];
+}
+export function createDataProgramActions(options) {
+    const { appId } = options;
+    const saveDataProgram = defineAction({
+        description: "Save (create or update, by name) a data program: a stored JS script that fetches/joins/aggregates provider or app data server-side and emits rows for dashboard panels. " +
+            "Dry-runs the code with defaultParams before persisting and rejects the save if it fails, so a broken program is never stored.",
+        schema: z.object({
+            name: z
+                .string()
+                .min(1)
+                .max(64)
+                .regex(SLUG_RE, "name must be a slug: lowercase letters, numbers, - or _")
+                .describe("Stable slug identifying this program, unique per your account."),
+            title: z.string().min(1).max(200),
+            description: z.string().max(2000).optional(),
+            code: z
+                .string()
+                .min(1)
+                .describe("JS source. Must call emit(rows, schema?) exactly once. Has access to the same globals as run-code (providerFetch, providerFetchAll, providerSearchAll, appAction, workspace*) plus a frozen `params` global."),
+            paramsSchema: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Optional JSON Schema describing accepted params."),
+            defaultParams: paramsRecord,
+            refreshMode: z.enum(["manual", "ttl"]).optional(),
+            refreshTtlMs: z
+                .number()
+                .int()
+                .min(MIN_REFRESH_TTL_MS)
+                .optional()
+                .describe(`Minimum ${MIN_REFRESH_TTL_MS}ms.`),
+            background: z.boolean().optional(),
+        }),
+        toolCallable: false,
+        run: async (args, ctx) => {
+            const userEmail = ctx?.userEmail;
+            if (!userEmail)
+                throw new Error("No authenticated user for save-data-program.");
+            const dryRun = await runDataProgram({
+                code: args.code,
+                params: args.defaultParams ?? {},
+                ctx: { userEmail, orgId: ctx?.orgId ?? null },
+                triggeredBy: "preview",
+            });
+            if (!dryRun.ok) {
+                throw new Error(`Dry-run failed (${dryRun.error.code}): ${dryRun.error.message}`);
+            }
+            const program = await upsertDataProgram({
+                appId,
+                name: args.name,
+                title: args.title,
+                description: args.description ?? "",
+                code: args.code,
+                paramsSchema: args.paramsSchema
+                    ? JSON.stringify(args.paramsSchema)
+                    : null,
+                defaultParams: args.defaultParams
+                    ? JSON.stringify(args.defaultParams)
+                    : null,
+                outputColumns: JSON.stringify(dryRun.schema),
+                refreshMode: args.refreshMode,
+                refreshTtlMs: args.refreshTtlMs,
+                background: args.background,
+                ownerEmail: userEmail,
+                orgId: ctx?.orgId ?? null,
+            });
+            return {
+                programId: program.id,
+                rowCount: dryRun.rows.length,
+                columns: compactColumns(dryRun.schema),
+                sampleRows: dryRun.rows.slice(0, 5),
+            };
+        },
+    });
+    const previewDataProgram = defineAction({
+        description: "Dry-run a data-program script WITHOUT saving it. Use this to iterate on a program before calling save-data-program.",
+        schema: z.object({
+            code: z.string().min(1),
+            params: paramsRecord,
+        }),
+        toolCallable: false,
+        run: async (args, ctx) => {
+            const result = await runDataProgram({
+                code: args.code,
+                params: args.params ?? {},
+                ctx: { userEmail: ctx?.userEmail, orgId: ctx?.orgId ?? null },
+                triggeredBy: "preview",
+            });
+            if (!result.ok) {
+                return {
+                    ok: false,
+                    error: result.error,
+                };
+            }
+            return {
+                ok: true,
+                rowCount: result.rows.length,
+                columns: compactColumns(result.schema),
+                sampleRows: result.rows.slice(0, 5),
+            };
+        },
+    });
+    const runDataProgramAction = defineAction({
+        description: "Run a saved data program and return a compact proof of the result (row count, columns, sample rows). Set includeRows to get the full (capped) row set.",
+        schema: z.object({
+            programId: z.string().min(1),
+            params: paramsRecord,
+            forceRefresh: z.boolean().optional(),
+            includeRows: z.boolean().optional(),
+        }),
+        toolCallable: false,
+        run: async (args, ctx) => {
+            const result = await runDataProgram({
+                programId: args.programId,
+                appId,
+                params: args.params ?? {},
+                ctx: { userEmail: ctx?.userEmail, orgId: ctx?.orgId ?? null },
+                triggeredBy: "agent",
+                forceRefresh: args.forceRefresh,
+            });
+            if (!result.ok) {
+                return {
+                    ok: false,
+                    error: result.error,
+                    ...(result.lastGoodRun
+                        ? {
+                            lastGoodRun: {
+                                rowCount: result.lastGoodRun.rows.length,
+                                columns: compactColumns(result.lastGoodRun.schema),
+                                sampleRows: result.lastGoodRun.rows.slice(0, 5),
+                                truncated: result.lastGoodRun.truncated,
+                                asOfMs: result.lastGoodRun.asOfMs,
+                            },
+                        }
+                        : {}),
+                };
+            }
+            return {
+                ok: true,
+                rowCount: result.rows.length,
+                columns: compactColumns(result.schema),
+                sampleRows: result.rows.slice(0, 5),
+                ...(args.includeRows ? { rows: result.rows } : {}),
+                asOfMs: result.asOfMs,
+                cacheHit: result.cacheHit,
+                stale: result.stale,
+                truncated: result.truncated,
+            };
+        },
+    });
+    const listDataProgramsAction = defineAction({
+        description: "List data programs for this app, scoped to what the caller can access.",
+        schema: z.object({
+            includeArchived: z.boolean().optional(),
+        }),
+        http: { method: "GET" },
+        readOnly: true,
+        run: async (args, ctx) => {
+            const programs = await listDataPrograms(appId, { userEmail: ctx?.userEmail, orgId: ctx?.orgId ?? undefined }, { includeArchived: args.includeArchived });
+            return {
+                programs: programs.map((p) => ({
+                    id: p.id,
+                    name: p.name,
+                    title: p.title,
+                    description: p.description,
+                    refreshMode: p.refreshMode,
+                    refreshTtlMs: p.refreshTtlMs,
+                    background: p.background,
+                    archivedAt: p.archivedAt,
+                    updatedAt: p.updatedAt,
+                    columns: p.outputColumns ? JSON.parse(p.outputColumns) : [],
+                })),
+            };
+        },
+    });
+    const getDataProgramAction = defineAction({
+        description: "Get one data program's metadata, code, and last-run summary. Set includeRows to include the last run's cached rows.",
+        schema: z.object({
+            programId: z.string().min(1),
+            includeRows: z.boolean().optional(),
+        }),
+        http: { method: "GET" },
+        readOnly: true,
+        run: async (args, ctx) => {
+            const program = await getDataProgram(args.programId, appId);
+            if (!program)
+                throw new Error("Data program not found.");
+            const { resolveAccess } = await import("../sharing/access.js");
+            const access = await resolveAccess("data_program", args.programId, {
+                userEmail: ctx?.userEmail,
+                orgId: ctx?.orgId ?? undefined,
+            });
+            if (!access)
+                throw new Error("Access denied to this data program.");
+            const defaultParams = program.defaultParams
+                ? JSON.parse(program.defaultParams)
+                : {};
+            // Viewer/org-scoped hash: the cached run for these params was produced
+            // under SOME caller's credentials and org grants, so only show it back
+            // to that same scope (see hashDataProgramParams doc).
+            const hash = hashDataProgramParams(defaultParams, ctx?.userEmail, ctx?.orgId ?? null);
+            const lastRun = await getLatestRun(program.id, hash);
+            return {
+                id: program.id,
+                name: program.name,
+                title: program.title,
+                description: program.description,
+                code: program.code,
+                paramsSchema: program.paramsSchema
+                    ? JSON.parse(program.paramsSchema)
+                    : null,
+                defaultParams,
+                refreshMode: program.refreshMode,
+                refreshTtlMs: program.refreshTtlMs,
+                background: program.background,
+                archivedAt: program.archivedAt,
+                columns: program.outputColumns ? JSON.parse(program.outputColumns) : [],
+                lastRun: lastRun
+                    ? {
+                        status: lastRun.status,
+                        rowCount: lastRun.rowCount,
+                        truncated: lastRun.truncated,
+                        errorCode: lastRun.errorCode,
+                        errorMessage: lastRun.errorMessage,
+                        finishedAt: lastRun.finishedAt,
+                        ...(args.includeRows && lastRun.rowsJson
+                            ? { rows: JSON.parse(lastRun.rowsJson) }
+                            : {}),
+                    }
+                    : null,
+            };
+        },
+    });
+    const deleteDataProgramAction = defineAction({
+        description: "Archive (soft-delete) a data program. Existing dashboard panels referencing it will show an archived error until repointed.",
+        schema: z.object({
+            programId: z.string().min(1),
+        }),
+        toolCallable: false,
+        run: async (args, ctx) => {
+            const { assertAccess } = await import("../sharing/access.js");
+            await assertAccess("data_program", args.programId, "editor", {
+                userEmail: ctx?.userEmail,
+                orgId: ctx?.orgId ?? undefined,
+            });
+            const archived = await archiveDataProgram(args.programId, appId);
+            return { archived };
+        },
+    });
+    return {
+        "save-data-program": saveDataProgram,
+        "preview-data-program": previewDataProgram,
+        "run-data-program": runDataProgramAction,
+        "list-data-programs": listDataProgramsAction,
+        "get-data-program": getDataProgramAction,
+        "delete-data-program": deleteDataProgramAction,
+    };
+}
+//# sourceMappingURL=actions.js.map

package/dist/data-programs/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../../src/data-programs/actions.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Actions exposed for the data-programs primitive: save/preview/run/list/get/\n * delete. Mirrors the repo's `defineAction` conventions (see\n * `../mcp/actions/create-org-service-token.ts`, `../sharing/actions/*`).\n *\n * Security: every action that EXECUTES code (save — which dry-runs before\n * persisting — preview, run) or MUTATES stored code (delete) is\n * `toolCallable: false`, so the sandboxed tools-iframe bridge can never\n * invoke stored/arbitrary code under the opener's session — the same\n * rationale as `provider-api-request`. `list`/`get` are read-only and\n * access-scoped through the sharing helpers.\n */\n\nimport { z } from \"zod\";\n\nimport { defineAction } from \"../action.js\";\nimport type { ActionEntry } from \"../agent/production-agent.js\";\nimport { hashDataProgramParams, runDataProgram } from \"./execute.js\";\nimport {\n  archiveDataProgram,\n  getDataProgram,\n  getLatestRun,\n  listDataPrograms,\n  upsertDataProgram,\n  MIN_REFRESH_TTL_MS,\n} from \"./store.js\";\n\nconst SLUG_RE = /^[a-z0-9][a-z0-9_-]*$/;\n\nconst paramsRecord = z.record(z.string(), z.unknown()).optional();\n\nfunction compactColumns(\n  schema: { name: string; type: string }[] | undefined,\n): { name: string; type: string }[] {\n  return schema ?? [];\n}\n\nexport interface CreateDataProgramActionsOptions {\n  appId: string;\n  getActions: () => Record<string, ActionEntry>;\n}\n\nexport function createDataProgramActions(\n  options: CreateDataProgramActionsOptions,\n): Record<string, ActionEntry> {\n  const { appId } = options;\n\n  const saveDataProgram = defineAction({\n    description:\n      \"Save (create or update, by name) a data program: a stored JS script that fetches/joins/aggregates provider or app data server-side and emits rows for dashboard panels. \" +\n      \"Dry-runs the code with defaultParams before persisting and rejects the save if it fails, so a broken program is never stored.\",\n    schema: z.object({\n      name: z\n        .string()\n        .min(1)\n        .max(64)\n        .regex(\n          SLUG_RE,\n          \"name must be a slug: lowercase letters, numbers, - or _\",\n        )\n        .describe(\n          \"Stable slug identifying this program, unique per your account.\",\n        ),\n      title: z.string().min(1).max(200),\n      description: z.string().max(2000).optional(),\n      code: z\n        .string()\n        .min(1)\n        .describe(\n          \"JS source. Must call emit(rows, schema?) exactly once. Has access to the same globals as run-code (providerFetch, providerFetchAll, providerSearchAll, appAction, workspace*) plus a frozen `params` global.\",\n        ),\n      paramsSchema: z\n        .record(z.string(), z.unknown())\n        .optional()\n        .describe(\"Optional JSON Schema describing accepted params.\"),\n      defaultParams: paramsRecord,\n      refreshMode: z.enum([\"manual\", \"ttl\"]).optional(),\n      refreshTtlMs: z\n        .number()\n        .int()\n        .min(MIN_REFRESH_TTL_MS)\n        .optional()\n        .describe(`Minimum ${MIN_REFRESH_TTL_MS}ms.`),\n      background: z.boolean().optional(),\n    }),\n    toolCallable: false,\n    run: async (args, ctx) => {\n      const userEmail = ctx?.userEmail;\n      if (!userEmail)\n        throw new Error(\"No authenticated user for save-data-program.\");\n\n      const dryRun = await runDataProgram({\n        code: args.code,\n        params: args.defaultParams ?? {},\n        ctx: { userEmail, orgId: ctx?.orgId ?? null },\n        triggeredBy: \"preview\",\n      });\n      if (!dryRun.ok) {\n        throw new Error(\n          `Dry-run failed (${dryRun.error.code}): ${dryRun.error.message}`,\n        );\n      }\n\n      const program = await upsertDataProgram({\n        appId,\n        name: args.name,\n        title: args.title,\n        description: args.description ?? \"\",\n        code: args.code,\n        paramsSchema: args.paramsSchema\n          ? JSON.stringify(args.paramsSchema)\n          : null,\n        defaultParams: args.defaultParams\n          ? JSON.stringify(args.defaultParams)\n          : null,\n        outputColumns: JSON.stringify(dryRun.schema),\n        refreshMode: args.refreshMode,\n        refreshTtlMs: args.refreshTtlMs,\n        background: args.background,\n        ownerEmail: userEmail,\n        orgId: ctx?.orgId ?? null,\n      });\n\n      return {\n        programId: program.id,\n        rowCount: dryRun.rows.length,\n        columns: compactColumns(dryRun.schema),\n        sampleRows: dryRun.rows.slice(0, 5),\n      };\n    },\n  });\n\n  const previewDataProgram = defineAction({\n    description:\n      \"Dry-run a data-program script WITHOUT saving it. Use this to iterate on a program before calling save-data-program.\",\n    schema: z.object({\n      code: z.string().min(1),\n      params: paramsRecord,\n    }),\n    toolCallable: false,\n    run: async (args, ctx) => {\n      const result = await runDataProgram({\n        code: args.code,\n        params: args.params ?? {},\n        ctx: { userEmail: ctx?.userEmail, orgId: ctx?.orgId ?? null },\n        triggeredBy: \"preview\",\n      });\n      if (!result.ok) {\n        return {\n          ok: false,\n          error: result.error,\n        };\n      }\n      return {\n        ok: true,\n        rowCount: result.rows.length,\n        columns: compactColumns(result.schema),\n        sampleRows: result.rows.slice(0, 5),\n      };\n    },\n  });\n\n  const runDataProgramAction = defineAction({\n    description:\n      \"Run a saved data program and return a compact proof of the result (row count, columns, sample rows). Set includeRows to get the full (capped) row set.\",\n    schema: z.object({\n      programId: z.string().min(1),\n      params: paramsRecord,\n      forceRefresh: z.boolean().optional(),\n      includeRows: z.boolean().optional(),\n    }),\n    toolCallable: false,\n    run: async (args, ctx) => {\n      const result = await runDataProgram({\n        programId: args.programId,\n        appId,\n        params: args.params ?? {},\n        ctx: { userEmail: ctx?.userEmail, orgId: ctx?.orgId ?? null },\n        triggeredBy: \"agent\",\n        forceRefresh: args.forceRefresh,\n      });\n      if (!result.ok) {\n        return {\n          ok: false,\n          error: result.error,\n          ...(result.lastGoodRun\n            ? {\n                lastGoodRun: {\n                  rowCount: result.lastGoodRun.rows.length,\n                  columns: compactColumns(result.lastGoodRun.schema),\n                  sampleRows: result.lastGoodRun.rows.slice(0, 5),\n                  truncated: result.lastGoodRun.truncated,\n                  asOfMs: result.lastGoodRun.asOfMs,\n                },\n              }\n            : {}),\n        };\n      }\n      return {\n        ok: true,\n        rowCount: result.rows.length,\n        columns: compactColumns(result.schema),\n        sampleRows: result.rows.slice(0, 5),\n        ...(args.includeRows ? { rows: result.rows } : {}),\n        asOfMs: result.asOfMs,\n        cacheHit: result.cacheHit,\n        stale: result.stale,\n        truncated: result.truncated,\n      };\n    },\n  });\n\n  const listDataProgramsAction = defineAction({\n    description:\n      \"List data programs for this app, scoped to what the caller can access.\",\n    schema: z.object({\n      includeArchived: z.boolean().optional(),\n    }),\n    http: { method: \"GET\" },\n    readOnly: true,\n    run: async (args, ctx) => {\n      const programs = await listDataPrograms(\n        appId,\n        { userEmail: ctx?.userEmail, orgId: ctx?.orgId ?? undefined },\n        { includeArchived: args.includeArchived },\n      );\n      return {\n        programs: programs.map((p) => ({\n          id: p.id,\n          name: p.name,\n          title: p.title,\n          description: p.description,\n          refreshMode: p.refreshMode,\n          refreshTtlMs: p.refreshTtlMs,\n          background: p.background,\n          archivedAt: p.archivedAt,\n          updatedAt: p.updatedAt,\n          columns: p.outputColumns ? JSON.parse(p.outputColumns) : [],\n        })),\n      };\n    },\n  });\n\n  const getDataProgramAction = defineAction({\n    description:\n      \"Get one data program's metadata, code, and last-run summary. Set includeRows to include the last run's cached rows.\",\n    schema: z.object({\n      programId: z.string().min(1),\n      includeRows: z.boolean().optional(),\n    }),\n    http: { method: \"GET\" },\n    readOnly: true,\n    run: async (args, ctx) => {\n      const program = await getDataProgram(args.programId, appId);\n      if (!program) throw new Error(\"Data program not found.\");\n\n      const { resolveAccess } = await import(\"../sharing/access.js\");\n      const access = await resolveAccess(\"data_program\", args.programId, {\n        userEmail: ctx?.userEmail,\n        orgId: ctx?.orgId ?? undefined,\n      });\n      if (!access) throw new Error(\"Access denied to this data program.\");\n\n      const defaultParams = program.defaultParams\n        ? (JSON.parse(program.defaultParams) as Record<string, unknown>)\n        : {};\n      // Viewer/org-scoped hash: the cached run for these params was produced\n      // under SOME caller's credentials and org grants, so only show it back\n      // to that same scope (see hashDataProgramParams doc).\n      const hash = hashDataProgramParams(\n        defaultParams,\n        ctx?.userEmail,\n        ctx?.orgId ?? null,\n      );\n      const lastRun = await getLatestRun(program.id, hash);\n\n      return {\n        id: program.id,\n        name: program.name,\n        title: program.title,\n        description: program.description,\n        code: program.code,\n        paramsSchema: program.paramsSchema\n          ? JSON.parse(program.paramsSchema)\n          : null,\n        defaultParams,\n        refreshMode: program.refreshMode,\n        refreshTtlMs: program.refreshTtlMs,\n        background: program.background,\n        archivedAt: program.archivedAt,\n        columns: program.outputColumns ? JSON.parse(program.outputColumns) : [],\n        lastRun: lastRun\n          ? {\n              status: lastRun.status,\n              rowCount: lastRun.rowCount,\n              truncated: lastRun.truncated,\n              errorCode: lastRun.errorCode,\n              errorMessage: lastRun.errorMessage,\n              finishedAt: lastRun.finishedAt,\n              ...(args.includeRows && lastRun.rowsJson\n                ? { rows: JSON.parse(lastRun.rowsJson) }\n                : {}),\n            }\n          : null,\n      };\n    },\n  });\n\n  const deleteDataProgramAction = defineAction({\n    description:\n      \"Archive (soft-delete) a data program. Existing dashboard panels referencing it will show an archived error until repointed.\",\n    schema: z.object({\n      programId: z.string().min(1),\n    }),\n    toolCallable: false,\n    run: async (args, ctx) => {\n      const { assertAccess } = await import(\"../sharing/access.js\");\n      await assertAccess(\"data_program\", args.programId, \"editor\", {\n        userEmail: ctx?.userEmail,\n        orgId: ctx?.orgId ?? undefined,\n      });\n      const archived = await archiveDataProgram(args.programId, appId);\n      return { archived };\n    },\n  });\n\n  return {\n    \"save-data-program\": saveDataProgram as unknown as ActionEntry,\n    \"preview-data-program\": previewDataProgram as unknown as ActionEntry,\n    \"run-data-program\": runDataProgramAction as unknown as ActionEntry,\n    \"list-data-programs\": listDataProgramsAction as unknown as ActionEntry,\n    \"get-data-program\": getDataProgramAction as unknown as ActionEntry,\n    \"delete-data-program\": deleteDataProgramAction as unknown as ActionEntry,\n  };\n}\n"]}

package/dist/data-programs/contract.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The data-program output contract.
+ *
+ * This module deliberately does NOT touch `../coding-tools/run-code.ts` —
+ * `executeSandboxCode` already accepts arbitrary code, so a data program is
+ * just user code with a small prelude prepended. The prelude defines a
+ * frozen `params` global and a single-call `emit(rows, schema?)` that writes
+ * one sentinel-prefixed JSON line to stdout. `parseDataProgramResult` then
+ * extracts that line back out of the captured stdout (which may also contain
+ * arbitrary `console.log` debug noise before/after it).
+ */
+export declare const DATA_PROGRAM_SENTINEL = "__DATA_PROGRAM_RESULT__";
+export type DataProgramColumnType = "number" | "string" | "boolean" | "json";
+export interface DataProgramColumn {
+    name: string;
+    type: string;
+}
+export type DataProgramContractErrorCode = "emit_missing" | "emit_shape_invalid" | "result_too_large";
+export interface DataProgramContractError {
+    code: DataProgramContractErrorCode;
+    message: string;
+}
+export interface ParsedDataProgramResult {
+    rows: Record<string, unknown>[];
+    schema: DataProgramColumn[];
+    truncated: boolean;
+}
+/**
+ * Build the JS source prepended to user code before it is handed to
+ * `executeSandboxCode`. Defines:
+ *   - a frozen `params` global (deep-frozen best-effort; primitives and
+ *     plain JSON values are always frozen, so user code cannot mutate the
+ *     params object out from under itself).
+ *   - `emit(rows, schema?)` — single-call guard (a second call throws) that
+ *     writes `DATA_PROGRAM_SENTINEL + JSON.stringify({rows, schema})` as one
+ *     stdout line via `process.stdout.write`. Using `process.stdout.write`
+ *     directly (not `console.log`) keeps the sentinel line byte-exact with
+ *     no extra formatting, and on its own line so a naive `\n`-split still
+ *     finds it even if user code itself never calls `console.log`.
+ *
+ * `console.log` remains completely free for debugging — the runner captures
+ * combined stdout and only strips the sentinel line when parsing.
+ */
+export declare function buildDataProgramPrelude(params: Record<string, unknown> | undefined): string;
+/**
+ * Infer a column schema by surveying the first `sampleSize` rows. A column's
+ * type is "json" if any sampled row disagrees on primitive type (the safe,
+ * always-renderable fallback), otherwise the single agreed primitive type.
+ * Columns absent from a row are simply not counted for that row.
+ */
+export declare function inferDataProgramSchema(rows: Record<string, unknown>[], sampleSize?: number): DataProgramColumn[];
+export interface ParseDataProgramResultOptions {
+    maxRows: number;
+    maxBytes: number;
+}
+export type ParseDataProgramResultOutcome = {
+    ok: true;
+    result: ParsedDataProgramResult;
+} | {
+    ok: false;
+    error: DataProgramContractError;
+};
+/**
+ * Parse the sentinel-prefixed emit() payload out of captured sandbox stdout.
+ * Never throws — always returns a discriminated outcome with a structured
+ * error code so callers can surface something actionable instead of a bare
+ * "Error: ..." string.
+ */
+export declare function parseDataProgramResult(stdout: string, options: ParseDataProgramResultOptions): ParseDataProgramResultOutcome;
+//# sourceMappingURL=contract.d.ts.map

package/dist/data-programs/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/data-programs/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAE/D,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAE7E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,4BAA4B,GACpC,cAAc,GACd,oBAAoB,GACpB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,4BAA4B,CAAC;IACnC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC1C,MAAM,CAgBR;AAkBD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,UAAU,SAAK,GACd,iBAAiB,EAAE,CAwBrB;AAkCD,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,6BAA6B,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAC7C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,wBAAwB,CAAA;CAAE,CAAC;AAEnD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,6BAA6B,GACrC,6BAA6B,CA6G/B"}

package/dist/data-programs/contract.js

@@ -0,0 +1,225 @@
+/**
+ * The data-program output contract.
+ *
+ * This module deliberately does NOT touch `../coding-tools/run-code.ts` —
+ * `executeSandboxCode` already accepts arbitrary code, so a data program is
+ * just user code with a small prelude prepended. The prelude defines a
+ * frozen `params` global and a single-call `emit(rows, schema?)` that writes
+ * one sentinel-prefixed JSON line to stdout. `parseDataProgramResult` then
+ * extracts that line back out of the captured stdout (which may also contain
+ * arbitrary `console.log` debug noise before/after it).
+ */
+export const DATA_PROGRAM_SENTINEL = "__DATA_PROGRAM_RESULT__";
+/**
+ * Build the JS source prepended to user code before it is handed to
+ * `executeSandboxCode`. Defines:
+ *   - a frozen `params` global (deep-frozen best-effort; primitives and
+ *     plain JSON values are always frozen, so user code cannot mutate the
+ *     params object out from under itself).
+ *   - `emit(rows, schema?)` — single-call guard (a second call throws) that
+ *     writes `DATA_PROGRAM_SENTINEL + JSON.stringify({rows, schema})` as one
+ *     stdout line via `process.stdout.write`. Using `process.stdout.write`
+ *     directly (not `console.log`) keeps the sentinel line byte-exact with
+ *     no extra formatting, and on its own line so a naive `\n`-split still
+ *     finds it even if user code itself never calls `console.log`.
+ *
+ * `console.log` remains completely free for debugging — the runner captures
+ * combined stdout and only strips the sentinel line when parsing.
+ */
+export function buildDataProgramPrelude(params) {
+    const paramsJson = JSON.stringify(params ?? {});
+    return [
+        "// --- data-program prelude (framework-injected, do not edit) ---",
+        `const params = Object.freeze(${paramsJson});`,
+        "let __dataProgramEmitted = false;",
+        "function emit(rows, schema) {",
+        "  if (__dataProgramEmitted) {",
+        "    throw new Error('emit() called more than once — a data program must call emit() exactly once.');",
+        "  }",
+        "  __dataProgramEmitted = true;",
+        `  process.stdout.write(${JSON.stringify(DATA_PROGRAM_SENTINEL)} + JSON.stringify({ rows, schema }) + '\\n');`,
+        "}",
+        "// --- end prelude ---",
+        "",
+    ].join("\n");
+}
+function isPlainObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.getPrototypeOf(value) === Object.prototype);
+}
+function inferColumnType(value) {
+    if (typeof value === "number")
+        return "number";
+    if (typeof value === "boolean")
+        return "boolean";
+    if (typeof value === "string")
+        return "string";
+    return "json";
+}
+/**
+ * Infer a column schema by surveying the first `sampleSize` rows. A column's
+ * type is "json" if any sampled row disagrees on primitive type (the safe,
+ * always-renderable fallback), otherwise the single agreed primitive type.
+ * Columns absent from a row are simply not counted for that row.
+ */
+export function inferDataProgramSchema(rows, sampleSize = 50) {
+    const seen = new Map();
+    const order = [];
+    for (const row of rows.slice(0, sampleSize)) {
+        if (!isPlainObject(row))
+            continue;
+        for (const key of Object.keys(row)) {
+            if (!seen.has(key)) {
+                seen.set(key, new Set());
+                order.push(key);
+            }
+            const value = row[key];
+            if (value !== null && value !== undefined) {
+                seen.get(key).add(inferColumnType(value));
+            }
+        }
+    }
+    return order.map((name) => {
+        const types = seen.get(name);
+        const type = types.size === 1
+            ? Array.from(types)[0]
+            : "json";
+        return { name, type };
+    });
+}
+function validateSchema(schema) {
+    if (!Array.isArray(schema))
+        return false;
+    return schema.every((entry) => isPlainObject(entry) &&
+        typeof entry.name === "string" &&
+        typeof entry.type === "string");
+}
+function byteLength(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+/**
+ * Find the LAST sentinel-prefixed line in captured stdout. Using the last
+ * (not first) occurrence means accidental duplicate/partial sentinel text
+ * inside earlier `console.log` debug output can't be mistaken for the real
+ * result — the framework-injected `emit()` call is always what produced the
+ * final one (the single-call guard rules out a legitimate second `emit()`).
+ */
+function extractSentinelLine(stdout) {
+    const lines = stdout.split("\n");
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const line = lines[i];
+        if (line.startsWith(DATA_PROGRAM_SENTINEL)) {
+            return line.slice(DATA_PROGRAM_SENTINEL.length);
+        }
+    }
+    return null;
+}
+/**
+ * Parse the sentinel-prefixed emit() payload out of captured sandbox stdout.
+ * Never throws — always returns a discriminated outcome with a structured
+ * error code so callers can surface something actionable instead of a bare
+ * "Error: ..." string.
+ */
+export function parseDataProgramResult(stdout, options) {
+    const sentinelPayload = extractSentinelLine(stdout);
+    if (sentinelPayload === null) {
+        return {
+            ok: false,
+            error: {
+                code: "emit_missing",
+                message: "The program did not call emit(rows, schema) — a data program must call emit() exactly once with its result rows.",
+            },
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(sentinelPayload);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: {
+                code: "emit_shape_invalid",
+                message: `emit() payload was not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
+    }
+    if (!isPlainObject(parsed) || !Array.isArray(parsed.rows)) {
+        return {
+            ok: false,
+            error: {
+                code: "emit_shape_invalid",
+                message: "emit() must be called as emit(rows, schema?) where rows is an array of plain objects.",
+            },
+        };
+    }
+    const rawRows = parsed.rows;
+    if (!rawRows.every(isPlainObject)) {
+        return {
+            ok: false,
+            error: {
+                code: "emit_shape_invalid",
+                message: "Every element of the emitted rows array must be a plain object.",
+            },
+        };
+    }
+    const rows = rawRows;
+    const rawSchema = parsed.schema;
+    let schema;
+    if (rawSchema === undefined || rawSchema === null) {
+        schema = inferDataProgramSchema(rows);
+    }
+    else if (validateSchema(rawSchema)) {
+        schema = rawSchema;
+    }
+    else {
+        return {
+            ok: false,
+            error: {
+                code: "emit_shape_invalid",
+                message: "emit()'s schema argument, when provided, must be an array of { name: string, type: string }.",
+            },
+        };
+    }
+    // Enforce caps by truncating rows to fit — an honest partial result
+    // (`truncated: true`), never a silent drop. A single row that alone
+    // exceeds the byte cap is a hard failure (result_too_large) since there is
+    // nothing safe to truncate to.
+    if (rows.length === 0) {
+        return { ok: true, result: { rows, schema, truncated: false } };
+    }
+    const firstRowBytes = byteLength(JSON.stringify(rows[0]));
+    if (firstRowBytes > options.maxBytes) {
+        return {
+            ok: false,
+            error: {
+                code: "result_too_large",
+                message: `A single emitted row is ${firstRowBytes} bytes, exceeding the ${options.maxBytes}-byte cap. Reduce the row's field sizes (e.g. truncate long strings) before emitting.`,
+            },
+        };
+    }
+    let truncated = false;
+    let kept = rows;
+    if (rows.length > options.maxRows) {
+        kept = rows.slice(0, options.maxRows);
+        truncated = true;
+    }
+    let runningBytes = 0;
+    let byteCutIndex = kept.length;
+    for (let i = 0; i < kept.length; i += 1) {
+        const rowBytes = byteLength(JSON.stringify(kept[i]));
+        if (runningBytes + rowBytes > options.maxBytes) {
+            byteCutIndex = i;
+            break;
+        }
+        runningBytes += rowBytes;
+    }
+    if (byteCutIndex < kept.length) {
+        kept = kept.slice(0, byteCutIndex);
+        truncated = true;
+    }
+    return { ok: true, result: { rows: kept, schema, truncated } };
+}
+//# sourceMappingURL=contract.js.map

package/dist/data-programs/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/data-programs/contract.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The data-program output contract.\n *\n * This module deliberately does NOT touch `../coding-tools/run-code.ts` —\n * `executeSandboxCode` already accepts arbitrary code, so a data program is\n * just user code with a small prelude prepended. The prelude defines a\n * frozen `params` global and a single-call `emit(rows, schema?)` that writes\n * one sentinel-prefixed JSON line to stdout. `parseDataProgramResult` then\n * extracts that line back out of the captured stdout (which may also contain\n * arbitrary `console.log` debug noise before/after it).\n */\n\nexport const DATA_PROGRAM_SENTINEL = \"__DATA_PROGRAM_RESULT__\";\n\nexport type DataProgramColumnType = \"number\" | \"string\" | \"boolean\" | \"json\";\n\nexport interface DataProgramColumn {\n  name: string;\n  type: string;\n}\n\nexport type DataProgramContractErrorCode =\n  | \"emit_missing\"\n  | \"emit_shape_invalid\"\n  | \"result_too_large\";\n\nexport interface DataProgramContractError {\n  code: DataProgramContractErrorCode;\n  message: string;\n}\n\nexport interface ParsedDataProgramResult {\n  rows: Record<string, unknown>[];\n  schema: DataProgramColumn[];\n  truncated: boolean;\n}\n\n/**\n * Build the JS source prepended to user code before it is handed to\n * `executeSandboxCode`. Defines:\n *   - a frozen `params` global (deep-frozen best-effort; primitives and\n *     plain JSON values are always frozen, so user code cannot mutate the\n *     params object out from under itself).\n *   - `emit(rows, schema?)` — single-call guard (a second call throws) that\n *     writes `DATA_PROGRAM_SENTINEL + JSON.stringify({rows, schema})` as one\n *     stdout line via `process.stdout.write`. Using `process.stdout.write`\n *     directly (not `console.log`) keeps the sentinel line byte-exact with\n *     no extra formatting, and on its own line so a naive `\\n`-split still\n *     finds it even if user code itself never calls `console.log`.\n *\n * `console.log` remains completely free for debugging — the runner captures\n * combined stdout and only strips the sentinel line when parsing.\n */\nexport function buildDataProgramPrelude(\n  params: Record<string, unknown> | undefined,\n): string {\n  const paramsJson = JSON.stringify(params ?? {});\n  return [\n    \"// --- data-program prelude (framework-injected, do not edit) ---\",\n    `const params = Object.freeze(${paramsJson});`,\n    \"let __dataProgramEmitted = false;\",\n    \"function emit(rows, schema) {\",\n    \"  if (__dataProgramEmitted) {\",\n    \"    throw new Error('emit() called more than once — a data program must call emit() exactly once.');\",\n    \"  }\",\n    \"  __dataProgramEmitted = true;\",\n    `  process.stdout.write(${JSON.stringify(DATA_PROGRAM_SENTINEL)} + JSON.stringify({ rows, schema }) + '\\\\n');`,\n    \"}\",\n    \"// --- end prelude ---\",\n    \"\",\n  ].join(\"\\n\");\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    !Array.isArray(value) &&\n    Object.getPrototypeOf(value) === Object.prototype\n  );\n}\n\nfunction inferColumnType(value: unknown): DataProgramColumnType {\n  if (typeof value === \"number\") return \"number\";\n  if (typeof value === \"boolean\") return \"boolean\";\n  if (typeof value === \"string\") return \"string\";\n  return \"json\";\n}\n\n/**\n * Infer a column schema by surveying the first `sampleSize` rows. A column's\n * type is \"json\" if any sampled row disagrees on primitive type (the safe,\n * always-renderable fallback), otherwise the single agreed primitive type.\n * Columns absent from a row are simply not counted for that row.\n */\nexport function inferDataProgramSchema(\n  rows: Record<string, unknown>[],\n  sampleSize = 50,\n): DataProgramColumn[] {\n  const seen = new Map<string, Set<DataProgramColumnType>>();\n  const order: string[] = [];\n  for (const row of rows.slice(0, sampleSize)) {\n    if (!isPlainObject(row)) continue;\n    for (const key of Object.keys(row)) {\n      if (!seen.has(key)) {\n        seen.set(key, new Set());\n        order.push(key);\n      }\n      const value = row[key];\n      if (value !== null && value !== undefined) {\n        seen.get(key)!.add(inferColumnType(value));\n      }\n    }\n  }\n  return order.map((name) => {\n    const types = seen.get(name)!;\n    const type: DataProgramColumnType =\n      types.size === 1\n        ? (Array.from(types)[0] as DataProgramColumnType)\n        : \"json\";\n    return { name, type };\n  });\n}\n\nfunction validateSchema(schema: unknown): schema is DataProgramColumn[] {\n  if (!Array.isArray(schema)) return false;\n  return schema.every(\n    (entry) =>\n      isPlainObject(entry) &&\n      typeof entry.name === \"string\" &&\n      typeof entry.type === \"string\",\n  );\n}\n\nfunction byteLength(value: string): number {\n  return Buffer.byteLength(value, \"utf8\");\n}\n\n/**\n * Find the LAST sentinel-prefixed line in captured stdout. Using the last\n * (not first) occurrence means accidental duplicate/partial sentinel text\n * inside earlier `console.log` debug output can't be mistaken for the real\n * result — the framework-injected `emit()` call is always what produced the\n * final one (the single-call guard rules out a legitimate second `emit()`).\n */\nfunction extractSentinelLine(stdout: string): string | null {\n  const lines = stdout.split(\"\\n\");\n  for (let i = lines.length - 1; i >= 0; i -= 1) {\n    const line = lines[i];\n    if (line.startsWith(DATA_PROGRAM_SENTINEL)) {\n      return line.slice(DATA_PROGRAM_SENTINEL.length);\n    }\n  }\n  return null;\n}\n\nexport interface ParseDataProgramResultOptions {\n  maxRows: number;\n  maxBytes: number;\n}\n\nexport type ParseDataProgramResultOutcome =\n  | { ok: true; result: ParsedDataProgramResult }\n  | { ok: false; error: DataProgramContractError };\n\n/**\n * Parse the sentinel-prefixed emit() payload out of captured sandbox stdout.\n * Never throws — always returns a discriminated outcome with a structured\n * error code so callers can surface something actionable instead of a bare\n * \"Error: ...\" string.\n */\nexport function parseDataProgramResult(\n  stdout: string,\n  options: ParseDataProgramResultOptions,\n): ParseDataProgramResultOutcome {\n  const sentinelPayload = extractSentinelLine(stdout);\n  if (sentinelPayload === null) {\n    return {\n      ok: false,\n      error: {\n        code: \"emit_missing\",\n        message:\n          \"The program did not call emit(rows, schema) — a data program must call emit() exactly once with its result rows.\",\n      },\n    };\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(sentinelPayload);\n  } catch (err) {\n    return {\n      ok: false,\n      error: {\n        code: \"emit_shape_invalid\",\n        message: `emit() payload was not valid JSON: ${err instanceof Error ? err.message : String(err)}`,\n      },\n    };\n  }\n\n  if (!isPlainObject(parsed) || !Array.isArray((parsed as any).rows)) {\n    return {\n      ok: false,\n      error: {\n        code: \"emit_shape_invalid\",\n        message:\n          \"emit() must be called as emit(rows, schema?) where rows is an array of plain objects.\",\n      },\n    };\n  }\n\n  const rawRows = (parsed as any).rows as unknown[];\n  if (!rawRows.every(isPlainObject)) {\n    return {\n      ok: false,\n      error: {\n        code: \"emit_shape_invalid\",\n        message:\n          \"Every element of the emitted rows array must be a plain object.\",\n      },\n    };\n  }\n  const rows = rawRows as Record<string, unknown>[];\n\n  const rawSchema = (parsed as any).schema;\n  let schema: DataProgramColumn[];\n  if (rawSchema === undefined || rawSchema === null) {\n    schema = inferDataProgramSchema(rows);\n  } else if (validateSchema(rawSchema)) {\n    schema = rawSchema;\n  } else {\n    return {\n      ok: false,\n      error: {\n        code: \"emit_shape_invalid\",\n        message:\n          \"emit()'s schema argument, when provided, must be an array of { name: string, type: string }.\",\n      },\n    };\n  }\n\n  // Enforce caps by truncating rows to fit — an honest partial result\n  // (`truncated: true`), never a silent drop. A single row that alone\n  // exceeds the byte cap is a hard failure (result_too_large) since there is\n  // nothing safe to truncate to.\n  if (rows.length === 0) {\n    return { ok: true, result: { rows, schema, truncated: false } };\n  }\n\n  const firstRowBytes = byteLength(JSON.stringify(rows[0]));\n  if (firstRowBytes > options.maxBytes) {\n    return {\n      ok: false,\n      error: {\n        code: \"result_too_large\",\n        message: `A single emitted row is ${firstRowBytes} bytes, exceeding the ${options.maxBytes}-byte cap. Reduce the row's field sizes (e.g. truncate long strings) before emitting.`,\n      },\n    };\n  }\n\n  let truncated = false;\n  let kept = rows;\n  if (rows.length > options.maxRows) {\n    kept = rows.slice(0, options.maxRows);\n    truncated = true;\n  }\n\n  let runningBytes = 0;\n  let byteCutIndex = kept.length;\n  for (let i = 0; i < kept.length; i += 1) {\n    const rowBytes = byteLength(JSON.stringify(kept[i]));\n    if (runningBytes + rowBytes > options.maxBytes) {\n      byteCutIndex = i;\n      break;\n    }\n    runningBytes += rowBytes;\n  }\n  if (byteCutIndex < kept.length) {\n    kept = kept.slice(0, byteCutIndex);\n    truncated = true;\n  }\n\n  return { ok: true, result: { rows: kept, schema, truncated } };\n}\n"]}