@agent-native/core 0.88.0 → 0.90.2

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

@@ -0,0 +1,96 @@
+/**
+ * The data-program execution orchestrator.
+ *
+ * Loads a stored program (or dry-runs inline code), checks viewer-scoped
+ * access, resolves the run-result cache, and — on a cache miss — executes
+ * the program through the EXISTING `executeSandboxCode` (run-code) sandbox.
+ * No new sandboxing, credential, SSRF, or quota code lives here: all
+ * provider access flows through the sandbox's existing bridge globals
+ * (`providerFetch`, `providerFetchAll`, `providerSearchAll`, `appAction`,
+ * `workspace*`), which resolve auth through `provider-api-request` /
+ * `resolveAuth` using the CALLER's own request context — never the
+ * program's original author.
+ */
+import type { ActionEntry } from "../agent/production-agent.js";
+import { type DataProgramColumn } from "./contract.js";
+export type DataProgramErrorCode = "program_not_found" | "access_denied" | "archived" | "timeout" | "emit_missing" | "emit_shape_invalid" | "sandbox_error" | "run_code_unavailable" | "background_pending" | "result_too_large";
+export interface DataProgramSuccess {
+    ok: true;
+    rows: Record<string, unknown>[];
+    schema: DataProgramColumn[];
+    truncated: boolean;
+    stale: boolean;
+    cacheHit: boolean;
+    asOfMs: number;
+    runId: string;
+}
+export interface DataProgramFailure {
+    ok: false;
+    error: {
+        code: DataProgramErrorCode;
+        message: string;
+    };
+    lastGoodRun?: {
+        rows: Record<string, unknown>[];
+        schema: DataProgramColumn[];
+        truncated: boolean;
+        asOfMs: number;
+    };
+}
+export type DataProgramResult = DataProgramSuccess | DataProgramFailure;
+export type DataProgramTriggeredBy = "agent" | "panel_view" | "schedule" | "manual_refresh" | "preview";
+export interface RunDataProgramArgs {
+    /** Stored program id. Mutually exclusive with `code` (code = inline dry-run/preview path). */
+    programId?: string;
+    /**
+     * The calling app's id. When provided alongside `programId`, the lookup is
+     * scoped to programs owned by this app — a program created in one app is
+     * not runnable from another app's agent chat in a shared-database
+     * deployment, even for a user who otherwise has row-level access.
+     */
+    appId?: string;
+    /** Inline code for a dry-run/preview — no persisted program, no cache. */
+    code?: string;
+    params?: Record<string, unknown>;
+    ctx: {
+        userEmail?: string;
+        orgId?: string | null;
+    };
+    triggeredBy: DataProgramTriggeredBy;
+    forceRefresh?: boolean;
+    timeoutMs?: number;
+}
+export declare function initDataPrograms(opts: {
+    appId: string;
+    getActions: () => Record<string, ActionEntry>;
+}): void;
+/** The appId passed to the most recent `initDataPrograms()` call, if any. */
+export declare function getInitializedDataProgramsAppId(): string | undefined;
+/** Test-only: clear module-level supplier state. */
+export declare function _resetDataProgramsRuntimeForTests(): void;
+/** Canonical (key-sorted) JSON so equivalent params always hash the same. */
+export declare function canonicalDataProgramParamsJson(value: unknown): string;
+/**
+ * Hash params (and, critically, the viewer/org scope) into the cache key used for
+ * `data_program_runs` lookups.
+ *
+ * `providerFetch` inside a program resolves auth using the CALLING viewer's
+ * own request context (never the program author's), so two different viewers
+ * running the same program with the same params can legitimately get two
+ * different results — e.g. one has a configured HubSpot key and the other
+ * doesn't, or row-level provider permissions differ per user. Folding
+ * `viewerKey` and `orgKey` into the hash means the run cache (and the active-run /
+ * last-successful-run lookups keyed on it) is scoped per viewer, so a
+ * teammate missing a credential sees their own auth error, not a cached
+ * result produced under someone else's token or org grants. Pass stable
+ * identities for `viewerKey` (the calling user's email) and `orgKey`
+ * (the active org id); omitting them is only safe for inline preview/dry-run
+ * calls that never persist or read the shared cache.
+ */
+export declare function hashDataProgramParams(params: Record<string, unknown> | undefined, viewerKey?: string, orgKey?: string | null): string;
+/**
+ * Run a stored data program (or inline code for preview/dry-run). Never
+ * throws — always resolves to a discriminated success/failure result.
+ */
+export declare function runDataProgram(args: RunDataProgramArgs): Promise<DataProgramResult>;
+//# sourceMappingURL=execute.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/data-programs/execute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEhE,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AAmBvB,MAAM,MAAM,oBAAoB,GAC5B,mBAAmB,GACnB,eAAe,GACf,UAAU,GACV,SAAS,GACT,cAAc,GACd,oBAAoB,GACpB,eAAe,GACf,sBAAsB,GACtB,oBAAoB,GACpB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE;QAAE,IAAI,EAAE,oBAAoB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,WAAW,CAAC,EAAE;QACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;QAChC,MAAM,EAAE,iBAAiB,EAAE,CAAC;QAC5B,SAAS,EAAE,OAAO,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAExE,MAAM,MAAM,sBAAsB,GAC9B,OAAO,GACP,YAAY,GACZ,UAAU,GACV,gBAAgB,GAChB,SAAS,CAAC;AAEd,MAAM,WAAW,kBAAkB;IACjC,8FAA8F;IAC9F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,GAAG,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACnD,WAAW,EAAE,sBAAsB,CAAC;IACpC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAWD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CAC/C,GAAG,IAAI,CAGP;AAED,6EAA6E;AAC7E,wBAAgB,+BAA+B,IAAI,MAAM,GAAG,SAAS,CAEpE;AAED,oDAAoD;AACpD,wBAAgB,iCAAiC,IAAI,IAAI,CAGxD;AAQD,6EAA6E;AAC7E,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAerE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,SAAS,CAAC,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,MAAM,CAQR;AAmKD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAsF5B"}

package/dist/data-programs/execute.js

@@ -0,0 +1,454 @@
+/**
+ * The data-program execution orchestrator.
+ *
+ * Loads a stored program (or dry-runs inline code), checks viewer-scoped
+ * access, resolves the run-result cache, and — on a cache miss — executes
+ * the program through the EXISTING `executeSandboxCode` (run-code) sandbox.
+ * No new sandboxing, credential, SSRF, or quota code lives here: all
+ * provider access flows through the sandbox's existing bridge globals
+ * (`providerFetch`, `providerFetchAll`, `providerSearchAll`, `appAction`,
+ * `workspace*`), which resolve auth through `provider-api-request` /
+ * `resolveAuth` using the CALLER's own request context — never the
+ * program's original author.
+ */
+import { createHash } from "node:crypto";
+import { resolveAccess } from "../sharing/access.js";
+import { buildDataProgramPrelude, parseDataProgramResult, } from "./contract.js";
+import { getActiveRun, getDataProgram, getLatestSuccessfulRun, recordDataProgramRun, updateDataProgramRun, MAX_PROGRAM_ROWS, MAX_PROGRAM_RESULT_BYTES, } from "./store.js";
+const PANEL_VIEW_TIMEOUT_MS = 25_000;
+const DEFAULT_TIMEOUT_MS = 120_000;
+/** Background executions get a generous budget — they run out-of-band. */
+const BACKGROUND_TIMEOUT_MS = 10 * 60 * 1000;
+/** Max chars of combined stdout/stderr retained per run row for debugging. */
+const LOGS_TAIL_MAX_CHARS = 4096;
+// ---------------------------------------------------------------------------
+// Module-level action supplier — mirrors the `getActions` supplier pattern
+// `createRunCodeEntry` closes over, so the sandbox bridge exposes the same
+// app-scoped action registry data programs (and run-code) already use.
+// ---------------------------------------------------------------------------
+let _actionsSupplier;
+let _initializedAppId;
+export function initDataPrograms(opts) {
+    _actionsSupplier = opts.getActions;
+    _initializedAppId = opts.appId;
+}
+/** The appId passed to the most recent `initDataPrograms()` call, if any. */
+export function getInitializedDataProgramsAppId() {
+    return _initializedAppId;
+}
+/** Test-only: clear module-level supplier state. */
+export function _resetDataProgramsRuntimeForTests() {
+    _actionsSupplier = undefined;
+    _initializedAppId = undefined;
+}
+function defaultTimeoutFor(triggeredBy) {
+    return triggeredBy === "panel_view"
+        ? PANEL_VIEW_TIMEOUT_MS
+        : DEFAULT_TIMEOUT_MS;
+}
+/** Canonical (key-sorted) JSON so equivalent params always hash the same. */
+export function canonicalDataProgramParamsJson(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalDataProgramParamsJson).join(",")}]`;
+    }
+    const keys = Object.keys(value).sort();
+    const entries = keys.map((k) => `${JSON.stringify(k)}:${canonicalDataProgramParamsJson(value[k])}`);
+    return `{${entries.join(",")}}`;
+}
+/**
+ * Hash params (and, critically, the viewer/org scope) into the cache key used for
+ * `data_program_runs` lookups.
+ *
+ * `providerFetch` inside a program resolves auth using the CALLING viewer's
+ * own request context (never the program author's), so two different viewers
+ * running the same program with the same params can legitimately get two
+ * different results — e.g. one has a configured HubSpot key and the other
+ * doesn't, or row-level provider permissions differ per user. Folding
+ * `viewerKey` and `orgKey` into the hash means the run cache (and the active-run /
+ * last-successful-run lookups keyed on it) is scoped per viewer, so a
+ * teammate missing a credential sees their own auth error, not a cached
+ * result produced under someone else's token or org grants. Pass stable
+ * identities for `viewerKey` (the calling user's email) and `orgKey`
+ * (the active org id); omitting them is only safe for inline preview/dry-run
+ * calls that never persist or read the shared cache.
+ */
+export function hashDataProgramParams(params, viewerKey, orgKey) {
+    return createHash("sha256")
+        .update(canonicalDataProgramParamsJson(params ?? {}))
+        .update(":viewer:")
+        .update(viewerKey ?? "")
+        .update(":org:")
+        .update(orgKey ?? "")
+        .digest("hex");
+}
+function truncateLogs(stdout, stderr) {
+    const combined = [stdout, stderr].filter(Boolean).join("\n---stderr---\n");
+    if (combined.length <= LOGS_TAIL_MAX_CHARS)
+        return combined;
+    return combined.slice(-LOGS_TAIL_MAX_CHARS);
+}
+function lastGoodFromRun(run) {
+    if (!run.rowsJson)
+        return undefined;
+    try {
+        return {
+            rows: JSON.parse(run.rowsJson),
+            schema: run.schemaJson
+                ? JSON.parse(run.schemaJson)
+                : [],
+            truncated: run.truncated ?? false,
+            asOfMs: run.finishedAt ?? run.startedAt,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function failure(code, message, lastGoodRun) {
+    return {
+        ok: false,
+        error: { code, message },
+        ...(lastGoodRun ? { lastGoodRun } : {}),
+    };
+}
+/**
+ * Attach the last successful run (if any) to a failure result, so panels can
+ * stale-serve instead of showing a blank error card.
+ */
+async function failureWithLastGood(programId, paramsHash, code, message) {
+    if (!programId || !paramsHash)
+        return failure(code, message);
+    const lastGood = await getLatestSuccessfulRun(programId, paramsHash);
+    return failure(code, message, lastGood ? lastGoodFromRun(lastGood) : undefined);
+}
+function buildActionRunContext(ctx) {
+    return {
+        caller: "tool",
+        userEmail: ctx.userEmail,
+        orgId: ctx.orgId ?? null,
+    };
+}
+/**
+ * Execute one prepared (prelude + code) module through the existing run-code
+ * sandbox. Never throws — resolves to either a parsed contract result or a
+ * structured failure (timeout, sandbox_error, or a contract error code).
+ */
+async function executeProgramCode(fullCode, timeoutMs, ctx) {
+    let executeSandboxCode;
+    try {
+        ({ executeSandboxCode } = await import("../coding-tools/run-code.js"));
+    }
+    catch {
+        return {
+            ok: false,
+            code: "run_code_unavailable",
+            message: "The run-code sandbox module is unavailable in this build, so data programs cannot execute.",
+            logsTail: "",
+        };
+    }
+    const getActions = _actionsSupplier ?? (() => ({}));
+    try {
+        const result = await executeSandboxCode({
+            code: fullCode,
+            timeoutMs,
+            getActions,
+            extraBridgeTools: new Set(),
+            context: buildActionRunContext(ctx),
+        });
+        const logsTail = truncateLogs(result.stdout, result.stderr);
+        if (result.timedOut) {
+            return {
+                ok: false,
+                code: "timeout",
+                message: `The program did not finish within ${timeoutMs}ms.`,
+                logsTail,
+            };
+        }
+        const parsed = parseDataProgramResult(result.stdout, {
+            maxRows: MAX_PROGRAM_ROWS,
+            maxBytes: MAX_PROGRAM_RESULT_BYTES,
+        });
+        if (!parsed.ok) {
+            return {
+                ok: false,
+                code: parsed.error.code,
+                message: parsed.error.message,
+                logsTail,
+            };
+        }
+        return {
+            ok: true,
+            rows: parsed.result.rows,
+            schema: parsed.result.schema,
+            truncated: parsed.result.truncated,
+            logsTail,
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            code: "sandbox_error",
+            message: err instanceof Error ? err.message : String(err),
+            logsTail: "",
+        };
+    }
+}
+function accessContextFrom(ctx) {
+    return {
+        userEmail: ctx.userEmail,
+        orgId: ctx.orgId ?? undefined,
+    };
+}
+/**
+ * Run a stored data program (or inline code for preview/dry-run). Never
+ * throws — always resolves to a discriminated success/failure result.
+ */
+export async function runDataProgram(args) {
+    const triggeredBy = args.triggeredBy;
+    const timeoutMs = args.timeoutMs ??
+        (triggeredBy === "schedule" || (args.code && !args.programId)
+            ? DEFAULT_TIMEOUT_MS
+            : defaultTimeoutFor(triggeredBy));
+    // Inline preview/dry-run path: no persisted program, no cache, no access
+    // check beyond "the caller can execute code at all" (governed by the
+    // caller's own action-level toolCallable gate).
+    if (!args.programId) {
+        if (!args.code) {
+            return failure("program_not_found", "Either programId or code must be provided.");
+        }
+        const prelude = buildDataProgramPrelude(args.params);
+        const outcome = await executeProgramCode(`${prelude}\n${args.code}`, timeoutMs, args.ctx);
+        if (!outcome.ok) {
+            return failure(outcome.code, outcome.message);
+        }
+        return {
+            ok: true,
+            rows: outcome.rows,
+            schema: outcome.schema,
+            truncated: outcome.truncated,
+            stale: false,
+            cacheHit: false,
+            asOfMs: Date.now(),
+            runId: "preview",
+        };
+    }
+    const program = await getDataProgram(args.programId, args.appId);
+    if (!program) {
+        return failure("program_not_found", `No data program exists with id "${args.programId}".`);
+    }
+    const access = await resolveAccess("data_program", args.programId, accessContextFrom(args.ctx));
+    if (!access) {
+        return failure("access_denied", "You do not have access to this data program.");
+    }
+    const paramsHash = hashDataProgramParams(args.params, args.ctx.userEmail, args.ctx.orgId ?? null);
+    if (program.archivedAt) {
+        return failureWithLastGood(program.id, paramsHash, "archived", "This data program was archived and can no longer be run.");
+    }
+    if (!args.forceRefresh) {
+        const cached = await resolveCacheHit(program, paramsHash);
+        if (cached)
+            return cached;
+    }
+    // Background programs: serve the last good run as `stale: true` while
+    // (re)enqueuing a durable execution, deduped against any active run.
+    if (program.background) {
+        return runBackgroundProgram(program, args, paramsHash, timeoutMs);
+    }
+    return runForegroundProgram(program, args, paramsHash, timeoutMs);
+}
+async function resolveCacheHit(program, paramsHash) {
+    const latestSuccess = await getLatestSuccessfulRun(program.id, paramsHash);
+    if (!latestSuccess || !latestSuccess.rowsJson)
+        return null;
+    const now = Date.now();
+    const asOf = latestSuccess.finishedAt ?? latestSuccess.startedAt;
+    const fresh = program.refreshMode === "manual" ? true : now - asOf < program.refreshTtlMs;
+    if (!fresh)
+        return null;
+    try {
+        return {
+            ok: true,
+            rows: JSON.parse(latestSuccess.rowsJson),
+            schema: latestSuccess.schemaJson
+                ? JSON.parse(latestSuccess.schemaJson)
+                : [],
+            truncated: latestSuccess.truncated,
+            stale: false,
+            cacheHit: true,
+            asOfMs: asOf,
+            runId: latestSuccess.id,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function runForegroundProgram(program, args, paramsHash, timeoutMs) {
+    // Best-effort double-run guard: skip re-execution if another `running` row
+    // for this (programId, paramsHash) is still within its own timeout window.
+    // Programs are read-only, so a duplicate concurrent run is wasted work, not
+    // a correctness hazard — this is advisory, not a hard lock.
+    const active = await getActiveRun(program.id, paramsHash);
+    if (active && Date.now() - active.startedAt < timeoutMs) {
+        const latestSuccess = await getLatestSuccessfulRun(program.id, paramsHash);
+        if (latestSuccess?.rowsJson) {
+            const cached = await resolveCacheHit(program, paramsHash);
+            if (cached)
+                return { ...cached, stale: true };
+        }
+        return failureWithLastGood(program.id, paramsHash, "background_pending", "This data program is already running; try again shortly.");
+    }
+    const paramsJson = JSON.stringify(args.params ?? {});
+    const running = await recordDataProgramRun({
+        programId: program.id,
+        paramsHash,
+        paramsJson,
+        status: "running",
+        triggeredBy: args.triggeredBy,
+    });
+    const prelude = buildDataProgramPrelude(args.params);
+    const startedAt = Date.now();
+    const outcome = await executeProgramCode(`${prelude}\n${program.code}`, timeoutMs, args.ctx);
+    const finishedAt = Date.now();
+    if (!outcome.ok) {
+        await updateDataProgramRun(running.id, {
+            status: outcome.code === "timeout" ? "timed_out" : "failed",
+            errorCode: outcome.code,
+            errorMessage: outcome.message,
+            logsTail: outcome.logsTail,
+            finishedAt,
+            durationMs: finishedAt - startedAt,
+        });
+        return failureWithLastGood(program.id, paramsHash, outcome.code, outcome.message);
+    }
+    const rowsJson = JSON.stringify(outcome.rows);
+    await updateDataProgramRun(running.id, {
+        status: "succeeded",
+        rowsJson,
+        schemaJson: JSON.stringify(outcome.schema),
+        truncated: outcome.truncated,
+        rowCount: outcome.rows.length,
+        byteSize: Buffer.byteLength(rowsJson, "utf8"),
+        logsTail: outcome.logsTail,
+        finishedAt,
+        durationMs: finishedAt - startedAt,
+    });
+    return {
+        ok: true,
+        rows: outcome.rows,
+        schema: outcome.schema,
+        truncated: outcome.truncated,
+        stale: false,
+        cacheHit: false,
+        asOfMs: finishedAt,
+        runId: running.id,
+    };
+}
+async function runBackgroundProgram(program, args, paramsHash, timeoutMs) {
+    const { enqueueSandboxExecution, getSandboxExecutionForOwner } = await import("../coding-tools/sandbox/index.js");
+    const backgroundTimeout = Math.max(timeoutMs, BACKGROUND_TIMEOUT_MS);
+    // Poll-driven completion: if there's already a queued/running row, check
+    // whether its execution has gone terminal and finalize it before deciding
+    // whether to enqueue another.
+    const active = await getActiveRun(program.id, paramsHash);
+    if (active?.executionId && args.ctx.userEmail) {
+        const execution = await getSandboxExecutionForOwner(active.executionId, args.ctx.userEmail);
+        if (execution &&
+            execution.status !== "queued" &&
+            execution.status !== "running") {
+            await finalizeBackgroundRun(active.id, execution);
+        }
+    }
+    const stillActive = await getActiveRun(program.id, paramsHash);
+    const staleWindowMs = backgroundTimeout;
+    const shouldEnqueue = !stillActive || Date.now() - stillActive.startedAt >= staleWindowMs;
+    if (shouldEnqueue && args.ctx.userEmail) {
+        const prelude = buildDataProgramPrelude(args.params);
+        const paramsJson = JSON.stringify(args.params ?? {});
+        try {
+            const { execution } = await enqueueSandboxExecution({
+                code: `${prelude}\n${program.code}`,
+                timeoutMs: backgroundTimeout,
+                maxOutputChars: 200_000,
+                owner: args.ctx.userEmail,
+                orgId: args.ctx.orgId ?? null,
+            });
+            await recordDataProgramRun({
+                programId: program.id,
+                paramsHash,
+                paramsJson,
+                status: "queued",
+                executionId: execution.id,
+                triggeredBy: args.triggeredBy,
+            });
+        }
+        catch (err) {
+            // Enqueue failed — fall through to serving lastGoodRun / background_pending.
+            console.error(`[data-programs] failed to enqueue background run for ${program.id}:`, err);
+        }
+    }
+    const cached = await resolveCacheHit(program, paramsHash);
+    if (cached)
+        return { ...cached, stale: true };
+    const latestSuccess = await getLatestSuccessfulRun(program.id, paramsHash);
+    if (latestSuccess?.rowsJson) {
+        const stale = lastGoodFromRun(latestSuccess);
+        if (stale) {
+            return {
+                ok: true,
+                rows: stale.rows,
+                schema: stale.schema,
+                truncated: stale.truncated,
+                stale: true,
+                cacheHit: true,
+                asOfMs: stale.asOfMs,
+                runId: latestSuccess.id,
+            };
+        }
+    }
+    return failureWithLastGood(program.id, paramsHash, "background_pending", "This data program is running in the background and has not produced a result yet.");
+}
+async function finalizeBackgroundRun(runId, execution) {
+    const finishedAt = Date.now();
+    if (execution.status === "succeeded") {
+        const parsed = parseDataProgramResult(execution.stdout, {
+            maxRows: MAX_PROGRAM_ROWS,
+            maxBytes: MAX_PROGRAM_RESULT_BYTES,
+        });
+        if (parsed.ok) {
+            const rowsJson = JSON.stringify(parsed.result.rows);
+            await updateDataProgramRun(runId, {
+                status: "succeeded",
+                rowsJson,
+                schemaJson: JSON.stringify(parsed.result.schema),
+                truncated: parsed.result.truncated,
+                rowCount: parsed.result.rows.length,
+                byteSize: Buffer.byteLength(rowsJson, "utf8"),
+                logsTail: truncateLogs(execution.stdout, execution.stderr),
+                finishedAt,
+            });
+            return;
+        }
+        await updateDataProgramRun(runId, {
+            status: "failed",
+            errorCode: parsed.error.code,
+            errorMessage: parsed.error.message,
+            logsTail: truncateLogs(execution.stdout, execution.stderr),
+            finishedAt,
+        });
+        return;
+    }
+    await updateDataProgramRun(runId, {
+        status: execution.status === "timed_out" ? "timed_out" : "failed",
+        errorCode: execution.status === "timed_out" ? "timeout" : "sandbox_error",
+        errorMessage: execution.status === "timed_out"
+            ? "Background execution timed out."
+            : "Background execution failed.",
+        logsTail: truncateLogs(execution.stdout, execution.stderr),
+        finishedAt,
+    });
+}
+//# sourceMappingURL=execute.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"execute.js","sourceRoot":"","sources":["../../src/data-programs/execute.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The data-program execution orchestrator.\n *\n * Loads a stored program (or dry-runs inline code), checks viewer-scoped\n * access, resolves the run-result cache, and — on a cache miss — executes\n * the program through the EXISTING `executeSandboxCode` (run-code) sandbox.\n * No new sandboxing, credential, SSRF, or quota code lives here: all\n * provider access flows through the sandbox's existing bridge globals\n * (`providerFetch`, `providerFetchAll`, `providerSearchAll`, `appAction`,\n * `workspace*`), which resolve auth through `provider-api-request` /\n * `resolveAuth` using the CALLER's own request context — never the\n * program's original author.\n */\n\nimport { createHash } from \"node:crypto\";\n\nimport type { ActionRunContext } from \"../action.js\";\nimport type { ActionEntry } from \"../agent/production-agent.js\";\nimport { resolveAccess, type AccessContext } from \"../sharing/access.js\";\nimport {\n  buildDataProgramPrelude,\n  parseDataProgramResult,\n  type DataProgramColumn,\n} from \"./contract.js\";\nimport {\n  getActiveRun,\n  getDataProgram,\n  getLatestSuccessfulRun,\n  recordDataProgramRun,\n  updateDataProgramRun,\n  MAX_PROGRAM_ROWS,\n  MAX_PROGRAM_RESULT_BYTES,\n  type DataProgramRow,\n} from \"./store.js\";\n\nconst PANEL_VIEW_TIMEOUT_MS = 25_000;\nconst DEFAULT_TIMEOUT_MS = 120_000;\n/** Background executions get a generous budget — they run out-of-band. */\nconst BACKGROUND_TIMEOUT_MS = 10 * 60 * 1000;\n/** Max chars of combined stdout/stderr retained per run row for debugging. */\nconst LOGS_TAIL_MAX_CHARS = 4096;\n\nexport type DataProgramErrorCode =\n  | \"program_not_found\"\n  | \"access_denied\"\n  | \"archived\"\n  | \"timeout\"\n  | \"emit_missing\"\n  | \"emit_shape_invalid\"\n  | \"sandbox_error\"\n  | \"run_code_unavailable\"\n  | \"background_pending\"\n  | \"result_too_large\";\n\nexport interface DataProgramSuccess {\n  ok: true;\n  rows: Record<string, unknown>[];\n  schema: DataProgramColumn[];\n  truncated: boolean;\n  stale: boolean;\n  cacheHit: boolean;\n  asOfMs: number;\n  runId: string;\n}\n\nexport interface DataProgramFailure {\n  ok: false;\n  error: { code: DataProgramErrorCode; message: string };\n  lastGoodRun?: {\n    rows: Record<string, unknown>[];\n    schema: DataProgramColumn[];\n    truncated: boolean;\n    asOfMs: number;\n  };\n}\n\nexport type DataProgramResult = DataProgramSuccess | DataProgramFailure;\n\nexport type DataProgramTriggeredBy =\n  | \"agent\"\n  | \"panel_view\"\n  | \"schedule\"\n  | \"manual_refresh\"\n  | \"preview\";\n\nexport interface RunDataProgramArgs {\n  /** Stored program id. Mutually exclusive with `code` (code = inline dry-run/preview path). */\n  programId?: string;\n  /**\n   * The calling app's id. When provided alongside `programId`, the lookup is\n   * scoped to programs owned by this app — a program created in one app is\n   * not runnable from another app's agent chat in a shared-database\n   * deployment, even for a user who otherwise has row-level access.\n   */\n  appId?: string;\n  /** Inline code for a dry-run/preview — no persisted program, no cache. */\n  code?: string;\n  params?: Record<string, unknown>;\n  ctx: { userEmail?: string; orgId?: string | null };\n  triggeredBy: DataProgramTriggeredBy;\n  forceRefresh?: boolean;\n  timeoutMs?: number;\n}\n\n// ---------------------------------------------------------------------------\n// Module-level action supplier — mirrors the `getActions` supplier pattern\n// `createRunCodeEntry` closes over, so the sandbox bridge exposes the same\n// app-scoped action registry data programs (and run-code) already use.\n// ---------------------------------------------------------------------------\n\nlet _actionsSupplier: (() => Record<string, ActionEntry>) | undefined;\nlet _initializedAppId: string | undefined;\n\nexport function initDataPrograms(opts: {\n  appId: string;\n  getActions: () => Record<string, ActionEntry>;\n}): void {\n  _actionsSupplier = opts.getActions;\n  _initializedAppId = opts.appId;\n}\n\n/** The appId passed to the most recent `initDataPrograms()` call, if any. */\nexport function getInitializedDataProgramsAppId(): string | undefined {\n  return _initializedAppId;\n}\n\n/** Test-only: clear module-level supplier state. */\nexport function _resetDataProgramsRuntimeForTests(): void {\n  _actionsSupplier = undefined;\n  _initializedAppId = undefined;\n}\n\nfunction defaultTimeoutFor(triggeredBy: DataProgramTriggeredBy): number {\n  return triggeredBy === \"panel_view\"\n    ? PANEL_VIEW_TIMEOUT_MS\n    : DEFAULT_TIMEOUT_MS;\n}\n\n/** Canonical (key-sorted) JSON so equivalent params always hash the same. */\nexport function canonicalDataProgramParamsJson(value: unknown): string {\n  if (value === null || typeof value !== \"object\") {\n    return JSON.stringify(value);\n  }\n  if (Array.isArray(value)) {\n    return `[${value.map(canonicalDataProgramParamsJson).join(\",\")}]`;\n  }\n  const keys = Object.keys(value as Record<string, unknown>).sort();\n  const entries = keys.map(\n    (k) =>\n      `${JSON.stringify(k)}:${canonicalDataProgramParamsJson(\n        (value as any)[k],\n      )}`,\n  );\n  return `{${entries.join(\",\")}}`;\n}\n\n/**\n * Hash params (and, critically, the viewer/org scope) into the cache key used for\n * `data_program_runs` lookups.\n *\n * `providerFetch` inside a program resolves auth using the CALLING viewer's\n * own request context (never the program author's), so two different viewers\n * running the same program with the same params can legitimately get two\n * different results — e.g. one has a configured HubSpot key and the other\n * doesn't, or row-level provider permissions differ per user. Folding\n * `viewerKey` and `orgKey` into the hash means the run cache (and the active-run /\n * last-successful-run lookups keyed on it) is scoped per viewer, so a\n * teammate missing a credential sees their own auth error, not a cached\n * result produced under someone else's token or org grants. Pass stable\n * identities for `viewerKey` (the calling user's email) and `orgKey`\n * (the active org id); omitting them is only safe for inline preview/dry-run\n * calls that never persist or read the shared cache.\n */\nexport function hashDataProgramParams(\n  params: Record<string, unknown> | undefined,\n  viewerKey?: string,\n  orgKey?: string | null,\n): string {\n  return createHash(\"sha256\")\n    .update(canonicalDataProgramParamsJson(params ?? {}))\n    .update(\":viewer:\")\n    .update(viewerKey ?? \"\")\n    .update(\":org:\")\n    .update(orgKey ?? \"\")\n    .digest(\"hex\");\n}\n\nfunction truncateLogs(stdout: string, stderr: string): string {\n  const combined = [stdout, stderr].filter(Boolean).join(\"\\n---stderr---\\n\");\n  if (combined.length <= LOGS_TAIL_MAX_CHARS) return combined;\n  return combined.slice(-LOGS_TAIL_MAX_CHARS);\n}\n\nfunction lastGoodFromRun(run: {\n  rowsJson: string | null;\n  schemaJson: string | null;\n  finishedAt: number | null;\n  startedAt: number;\n  truncated?: boolean;\n}): DataProgramFailure[\"lastGoodRun\"] {\n  if (!run.rowsJson) return undefined;\n  try {\n    return {\n      rows: JSON.parse(run.rowsJson) as Record<string, unknown>[],\n      schema: run.schemaJson\n        ? (JSON.parse(run.schemaJson) as DataProgramColumn[])\n        : [],\n      truncated: run.truncated ?? false,\n      asOfMs: run.finishedAt ?? run.startedAt,\n    };\n  } catch {\n    return undefined;\n  }\n}\n\nfunction failure(\n  code: DataProgramErrorCode,\n  message: string,\n  lastGoodRun?: DataProgramFailure[\"lastGoodRun\"],\n): DataProgramFailure {\n  return {\n    ok: false,\n    error: { code, message },\n    ...(lastGoodRun ? { lastGoodRun } : {}),\n  };\n}\n\n/**\n * Attach the last successful run (if any) to a failure result, so panels can\n * stale-serve instead of showing a blank error card.\n */\nasync function failureWithLastGood(\n  programId: string | undefined,\n  paramsHash: string | undefined,\n  code: DataProgramErrorCode,\n  message: string,\n): Promise<DataProgramFailure> {\n  if (!programId || !paramsHash) return failure(code, message);\n  const lastGood = await getLatestSuccessfulRun(programId, paramsHash);\n  return failure(\n    code,\n    message,\n    lastGood ? lastGoodFromRun(lastGood) : undefined,\n  );\n}\n\nfunction buildActionRunContext(\n  ctx: RunDataProgramArgs[\"ctx\"],\n): ActionRunContext {\n  return {\n    caller: \"tool\",\n    userEmail: ctx.userEmail,\n    orgId: ctx.orgId ?? null,\n  };\n}\n\n/**\n * Execute one prepared (prelude + code) module through the existing run-code\n * sandbox. Never throws — resolves to either a parsed contract result or a\n * structured failure (timeout, sandbox_error, or a contract error code).\n */\nasync function executeProgramCode(\n  fullCode: string,\n  timeoutMs: number,\n  ctx: RunDataProgramArgs[\"ctx\"],\n): Promise<\n  | {\n      ok: true;\n      rows: Record<string, unknown>[];\n      schema: DataProgramColumn[];\n      truncated: boolean;\n      logsTail: string;\n    }\n  | { ok: false; code: DataProgramErrorCode; message: string; logsTail: string }\n> {\n  let executeSandboxCode: typeof import(\"../coding-tools/run-code.js\").executeSandboxCode;\n  try {\n    ({ executeSandboxCode } = await import(\"../coding-tools/run-code.js\"));\n  } catch {\n    return {\n      ok: false,\n      code: \"run_code_unavailable\",\n      message:\n        \"The run-code sandbox module is unavailable in this build, so data programs cannot execute.\",\n      logsTail: \"\",\n    };\n  }\n\n  const getActions =\n    _actionsSupplier ?? (() => ({}) as Record<string, ActionEntry>);\n\n  try {\n    const result = await executeSandboxCode({\n      code: fullCode,\n      timeoutMs,\n      getActions,\n      extraBridgeTools: new Set(),\n      context: buildActionRunContext(ctx),\n    });\n\n    const logsTail = truncateLogs(result.stdout, result.stderr);\n\n    if (result.timedOut) {\n      return {\n        ok: false,\n        code: \"timeout\",\n        message: `The program did not finish within ${timeoutMs}ms.`,\n        logsTail,\n      };\n    }\n\n    const parsed = parseDataProgramResult(result.stdout, {\n      maxRows: MAX_PROGRAM_ROWS,\n      maxBytes: MAX_PROGRAM_RESULT_BYTES,\n    });\n    if (!parsed.ok) {\n      return {\n        ok: false,\n        code: parsed.error.code,\n        message: parsed.error.message,\n        logsTail,\n      };\n    }\n\n    return {\n      ok: true,\n      rows: parsed.result.rows,\n      schema: parsed.result.schema,\n      truncated: parsed.result.truncated,\n      logsTail,\n    };\n  } catch (err) {\n    return {\n      ok: false,\n      code: \"sandbox_error\",\n      message: err instanceof Error ? err.message : String(err),\n      logsTail: \"\",\n    };\n  }\n}\n\nfunction accessContextFrom(ctx: RunDataProgramArgs[\"ctx\"]): AccessContext {\n  return {\n    userEmail: ctx.userEmail,\n    orgId: ctx.orgId ?? undefined,\n  };\n}\n\n/**\n * Run a stored data program (or inline code for preview/dry-run). Never\n * throws — always resolves to a discriminated success/failure result.\n */\nexport async function runDataProgram(\n  args: RunDataProgramArgs,\n): Promise<DataProgramResult> {\n  const triggeredBy = args.triggeredBy;\n  const timeoutMs =\n    args.timeoutMs ??\n    (triggeredBy === \"schedule\" || (args.code && !args.programId)\n      ? DEFAULT_TIMEOUT_MS\n      : defaultTimeoutFor(triggeredBy));\n\n  // Inline preview/dry-run path: no persisted program, no cache, no access\n  // check beyond \"the caller can execute code at all\" (governed by the\n  // caller's own action-level toolCallable gate).\n  if (!args.programId) {\n    if (!args.code) {\n      return failure(\n        \"program_not_found\",\n        \"Either programId or code must be provided.\",\n      );\n    }\n    const prelude = buildDataProgramPrelude(args.params);\n    const outcome = await executeProgramCode(\n      `${prelude}\\n${args.code}`,\n      timeoutMs,\n      args.ctx,\n    );\n    if (!outcome.ok) {\n      return failure(outcome.code, outcome.message);\n    }\n    return {\n      ok: true,\n      rows: outcome.rows,\n      schema: outcome.schema,\n      truncated: outcome.truncated,\n      stale: false,\n      cacheHit: false,\n      asOfMs: Date.now(),\n      runId: \"preview\",\n    };\n  }\n\n  const program = await getDataProgram(args.programId, args.appId);\n  if (!program) {\n    return failure(\n      \"program_not_found\",\n      `No data program exists with id \"${args.programId}\".`,\n    );\n  }\n\n  const access = await resolveAccess(\n    \"data_program\",\n    args.programId,\n    accessContextFrom(args.ctx),\n  );\n  if (!access) {\n    return failure(\n      \"access_denied\",\n      \"You do not have access to this data program.\",\n    );\n  }\n\n  const paramsHash = hashDataProgramParams(\n    args.params,\n    args.ctx.userEmail,\n    args.ctx.orgId ?? null,\n  );\n\n  if (program.archivedAt) {\n    return failureWithLastGood(\n      program.id,\n      paramsHash,\n      \"archived\",\n      \"This data program was archived and can no longer be run.\",\n    );\n  }\n\n  if (!args.forceRefresh) {\n    const cached = await resolveCacheHit(program, paramsHash);\n    if (cached) return cached;\n  }\n\n  // Background programs: serve the last good run as `stale: true` while\n  // (re)enqueuing a durable execution, deduped against any active run.\n  if (program.background) {\n    return runBackgroundProgram(program, args, paramsHash, timeoutMs);\n  }\n\n  return runForegroundProgram(program, args, paramsHash, timeoutMs);\n}\n\nasync function resolveCacheHit(\n  program: DataProgramRow,\n  paramsHash: string,\n): Promise<DataProgramSuccess | null> {\n  const latestSuccess = await getLatestSuccessfulRun(program.id, paramsHash);\n  if (!latestSuccess || !latestSuccess.rowsJson) return null;\n\n  const now = Date.now();\n  const asOf = latestSuccess.finishedAt ?? latestSuccess.startedAt;\n  const fresh =\n    program.refreshMode === \"manual\" ? true : now - asOf < program.refreshTtlMs;\n  if (!fresh) return null;\n\n  try {\n    return {\n      ok: true,\n      rows: JSON.parse(latestSuccess.rowsJson) as Record<string, unknown>[],\n      schema: latestSuccess.schemaJson\n        ? (JSON.parse(latestSuccess.schemaJson) as DataProgramColumn[])\n        : [],\n      truncated: latestSuccess.truncated,\n      stale: false,\n      cacheHit: true,\n      asOfMs: asOf,\n      runId: latestSuccess.id,\n    };\n  } catch {\n    return null;\n  }\n}\n\nasync function runForegroundProgram(\n  program: DataProgramRow,\n  args: RunDataProgramArgs,\n  paramsHash: string,\n  timeoutMs: number,\n): Promise<DataProgramResult> {\n  // Best-effort double-run guard: skip re-execution if another `running` row\n  // for this (programId, paramsHash) is still within its own timeout window.\n  // Programs are read-only, so a duplicate concurrent run is wasted work, not\n  // a correctness hazard — this is advisory, not a hard lock.\n  const active = await getActiveRun(program.id, paramsHash);\n  if (active && Date.now() - active.startedAt < timeoutMs) {\n    const latestSuccess = await getLatestSuccessfulRun(program.id, paramsHash);\n    if (latestSuccess?.rowsJson) {\n      const cached = await resolveCacheHit(program, paramsHash);\n      if (cached) return { ...cached, stale: true };\n    }\n    return failureWithLastGood(\n      program.id,\n      paramsHash,\n      \"background_pending\",\n      \"This data program is already running; try again shortly.\",\n    );\n  }\n\n  const paramsJson = JSON.stringify(args.params ?? {});\n  const running = await recordDataProgramRun({\n    programId: program.id,\n    paramsHash,\n    paramsJson,\n    status: \"running\",\n    triggeredBy: args.triggeredBy,\n  });\n\n  const prelude = buildDataProgramPrelude(args.params);\n  const startedAt = Date.now();\n  const outcome = await executeProgramCode(\n    `${prelude}\\n${program.code}`,\n    timeoutMs,\n    args.ctx,\n  );\n  const finishedAt = Date.now();\n\n  if (!outcome.ok) {\n    await updateDataProgramRun(running.id, {\n      status: outcome.code === \"timeout\" ? \"timed_out\" : \"failed\",\n      errorCode: outcome.code,\n      errorMessage: outcome.message,\n      logsTail: outcome.logsTail,\n      finishedAt,\n      durationMs: finishedAt - startedAt,\n    });\n    return failureWithLastGood(\n      program.id,\n      paramsHash,\n      outcome.code,\n      outcome.message,\n    );\n  }\n\n  const rowsJson = JSON.stringify(outcome.rows);\n  await updateDataProgramRun(running.id, {\n    status: \"succeeded\",\n    rowsJson,\n    schemaJson: JSON.stringify(outcome.schema),\n    truncated: outcome.truncated,\n    rowCount: outcome.rows.length,\n    byteSize: Buffer.byteLength(rowsJson, \"utf8\"),\n    logsTail: outcome.logsTail,\n    finishedAt,\n    durationMs: finishedAt - startedAt,\n  });\n\n  return {\n    ok: true,\n    rows: outcome.rows,\n    schema: outcome.schema,\n    truncated: outcome.truncated,\n    stale: false,\n    cacheHit: false,\n    asOfMs: finishedAt,\n    runId: running.id,\n  };\n}\n\nasync function runBackgroundProgram(\n  program: DataProgramRow,\n  args: RunDataProgramArgs,\n  paramsHash: string,\n  timeoutMs: number,\n): Promise<DataProgramResult> {\n  const { enqueueSandboxExecution, getSandboxExecutionForOwner } =\n    await import(\"../coding-tools/sandbox/index.js\");\n\n  const backgroundTimeout = Math.max(timeoutMs, BACKGROUND_TIMEOUT_MS);\n\n  // Poll-driven completion: if there's already a queued/running row, check\n  // whether its execution has gone terminal and finalize it before deciding\n  // whether to enqueue another.\n  const active = await getActiveRun(program.id, paramsHash);\n  if (active?.executionId && args.ctx.userEmail) {\n    const execution = await getSandboxExecutionForOwner(\n      active.executionId,\n      args.ctx.userEmail,\n    );\n    if (\n      execution &&\n      execution.status !== \"queued\" &&\n      execution.status !== \"running\"\n    ) {\n      await finalizeBackgroundRun(active.id, execution);\n    }\n  }\n\n  const stillActive = await getActiveRun(program.id, paramsHash);\n  const staleWindowMs = backgroundTimeout;\n  const shouldEnqueue =\n    !stillActive || Date.now() - stillActive.startedAt >= staleWindowMs;\n\n  if (shouldEnqueue && args.ctx.userEmail) {\n    const prelude = buildDataProgramPrelude(args.params);\n    const paramsJson = JSON.stringify(args.params ?? {});\n    try {\n      const { execution } = await enqueueSandboxExecution({\n        code: `${prelude}\\n${program.code}`,\n        timeoutMs: backgroundTimeout,\n        maxOutputChars: 200_000,\n        owner: args.ctx.userEmail,\n        orgId: args.ctx.orgId ?? null,\n      });\n      await recordDataProgramRun({\n        programId: program.id,\n        paramsHash,\n        paramsJson,\n        status: \"queued\",\n        executionId: execution.id,\n        triggeredBy: args.triggeredBy,\n      });\n    } catch (err) {\n      // Enqueue failed — fall through to serving lastGoodRun / background_pending.\n      console.error(\n        `[data-programs] failed to enqueue background run for ${program.id}:`,\n        err,\n      );\n    }\n  }\n\n  const cached = await resolveCacheHit(program, paramsHash);\n  if (cached) return { ...cached, stale: true };\n\n  const latestSuccess = await getLatestSuccessfulRun(program.id, paramsHash);\n  if (latestSuccess?.rowsJson) {\n    const stale = lastGoodFromRun(latestSuccess);\n    if (stale) {\n      return {\n        ok: true,\n        rows: stale.rows,\n        schema: stale.schema,\n        truncated: stale.truncated,\n        stale: true,\n        cacheHit: true,\n        asOfMs: stale.asOfMs,\n        runId: latestSuccess.id,\n      };\n    }\n  }\n\n  return failureWithLastGood(\n    program.id,\n    paramsHash,\n    \"background_pending\",\n    \"This data program is running in the background and has not produced a result yet.\",\n  );\n}\n\nasync function finalizeBackgroundRun(\n  runId: string,\n  execution: { status: string; stdout: string; stderr: string },\n): Promise<void> {\n  const finishedAt = Date.now();\n  if (execution.status === \"succeeded\") {\n    const parsed = parseDataProgramResult(execution.stdout, {\n      maxRows: MAX_PROGRAM_ROWS,\n      maxBytes: MAX_PROGRAM_RESULT_BYTES,\n    });\n    if (parsed.ok) {\n      const rowsJson = JSON.stringify(parsed.result.rows);\n      await updateDataProgramRun(runId, {\n        status: \"succeeded\",\n        rowsJson,\n        schemaJson: JSON.stringify(parsed.result.schema),\n        truncated: parsed.result.truncated,\n        rowCount: parsed.result.rows.length,\n        byteSize: Buffer.byteLength(rowsJson, \"utf8\"),\n        logsTail: truncateLogs(execution.stdout, execution.stderr),\n        finishedAt,\n      });\n      return;\n    }\n    await updateDataProgramRun(runId, {\n      status: \"failed\",\n      errorCode: parsed.error.code,\n      errorMessage: parsed.error.message,\n      logsTail: truncateLogs(execution.stdout, execution.stderr),\n      finishedAt,\n    });\n    return;\n  }\n\n  await updateDataProgramRun(runId, {\n    status: execution.status === \"timed_out\" ? \"timed_out\" : \"failed\",\n    errorCode: execution.status === \"timed_out\" ? \"timeout\" : \"sandbox_error\",\n    errorMessage:\n      execution.status === \"timed_out\"\n        ? \"Background execution timed out.\"\n        : \"Background execution failed.\",\n    logsTail: truncateLogs(execution.stdout, execution.stderr),\n    finishedAt,\n  });\n}\n"]}

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

@@ -0,0 +1,11 @@
+/**
+ * Data programs: a named, stored, agent-authored JS script executed
+ * server-side through the existing run-code sandbox, cached in SQL, and
+ * rendered by dashboard panels via a `"program"` source.
+ */
+export { dataPrograms, dataProgramShares, dataProgramRunsCreateSql, } from "./schema.js";
+export { ensureDataProgramTables, registerDataProgramsShareable, upsertDataProgram, getDataProgram, getDataProgramByName, listDataPrograms, archiveDataProgram, recordDataProgramRun, updateDataProgramRun, getLatestSuccessfulRun, getLatestRun, getActiveRun, pruneDataProgramRuns, MAX_PROGRAM_ROWS, MAX_PROGRAM_RESULT_BYTES, MAX_ACTIVE_PROGRAMS_PER_APP, MIN_REFRESH_TTL_MS, type DataProgramRow, type DataProgramRefreshMode, type DataProgramRunRow, type DataProgramRunStatus, type UpsertDataProgramInput, type ListDataProgramsOptions, type RecordDataProgramRunInput, type UpdateDataProgramRunInput, } from "./store.js";
+export { DATA_PROGRAM_SENTINEL, buildDataProgramPrelude, parseDataProgramResult, inferDataProgramSchema, type DataProgramColumn, type DataProgramColumnType, type DataProgramContractError, type DataProgramContractErrorCode, type ParsedDataProgramResult, type ParseDataProgramResultOptions, type ParseDataProgramResultOutcome, } from "./contract.js";
+export { initDataPrograms, getInitializedDataProgramsAppId, canonicalDataProgramParamsJson, hashDataProgramParams, runDataProgram, type DataProgramErrorCode, type DataProgramSuccess, type DataProgramFailure, type DataProgramResult, type DataProgramTriggeredBy, type RunDataProgramArgs, } from "./execute.js";
+export { createDataProgramActions, type CreateDataProgramActionsOptions, } from "./actions.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/data-programs/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,gBAAgB,EAChB,wBAAwB,EACxB,2BAA2B,EAC3B,kBAAkB,EAClB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,GAC/B,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,4BAA4B,EACjC,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,GACnC,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,EAChB,+BAA+B,EAC/B,8BAA8B,EAC9B,qBAAqB,EACrB,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,wBAAwB,EACxB,KAAK,+BAA+B,GACrC,MAAM,cAAc,CAAC"}