@agent-native/core 0.88.0 → 0.90.1

package/dist/coding-tools/sandbox/background.js

@@ -0,0 +1,279 @@
+/**
+ * Durable background execution for the `run-code` tool.
+ *
+ * The hosted agent loop runs under a soft wall-clock ceiling (~40s on
+ * serverless): a foreground `run-code` call that outlives it is aborted and —
+ * because `run-code` is readOnly — its result is simply lost. This module is
+ * the queued, durable alternative wired through the existing sandbox-adapter
+ * seam: enqueue the raw code to SQL (`sandbox_executions`), return
+ * `{ executionId, status: "queued" }` immediately, and let an executor with
+ * its own budget claim the row, run it through the local sandbox machinery,
+ * and persist the result for later polling.
+ *
+ * Execution drivers, by deployment mode:
+ *  1. Serverless (Netlify/Vercel/Lambda/CF): `fireInternalDispatch` POSTs to
+ *     `/_agent-native/sandbox/_process-execution` on this same deployment, so
+ *     the code runs in a FRESH function invocation with its own full budget —
+ *     the same self-dispatch pattern A2A, integration webhooks, and Agent
+ *     Teams use. HMAC-verified via the shared internal-token scheme.
+ *  2. Long-lived Node (self-hosted, local dev): the execution starts in-process
+ *     immediately after enqueue, detached from the enqueueing tool call.
+ *  3. Opportunistic drain: every status poll re-drives a row that is still
+ *     `queued` (lost dispatch) or whose lease expired (dead executor), and a
+ *     periodic warm-instance sweep (`drainDueSandboxExecutions`, mounted by
+ *     the core routes plugin) does the same as a backstop.
+ *
+ * The executor itself never re-enters adapter selection (that could recurse
+ * into this queue when `AGENT_NATIVE_SANDBOX=background`): the runner
+ * registered by `createRunCodeEntry` executes through the non-queued adapter
+ * (the local child process by default), with the bridge/env-scrub/module
+ * building unchanged from the foreground path.
+ */
+import crypto from "node:crypto";
+import { isServerlessRuntime } from "../../db/client.js";
+import { runWithRequestContext } from "../../server/request-context.js";
+import { fireInternalDispatch } from "../../server/self-dispatch.js";
+import { claimSandboxExecution, createSandboxExecution, failExpiredSandboxExecution, finalizeSandboxExecution, getSandboxExecutionInternal, listDueSandboxExecutions, renewSandboxExecutionLease, } from "./executions-store.js";
+/** Framework route the enqueue self-dispatch targets (mounted by core-routes-plugin). */
+export const SANDBOX_PROCESS_EXECUTION_PATH = "/_agent-native/sandbox/_process-execution";
+/** Default background budget — generous compared to the foreground 120s default. */
+export const BACKGROUND_DEFAULT_TIMEOUT_MS = 10 * 60_000;
+/** Hard cap on a single background execution's own timeout. */
+export const BACKGROUND_MAX_TIMEOUT_MS = 30 * 60_000;
+/** Lease duration; an executor that misses ~3 heartbeats is considered dead. */
+export const SANDBOX_EXECUTION_LEASE_MS = 90_000;
+/** Heartbeat cadence while an execution is running. */
+const HEARTBEAT_INTERVAL_MS = 30_000;
+/** A queued row older than this with no claim is treated as a lost dispatch. */
+export const SANDBOX_EXECUTION_REDRIVE_AFTER_MS = 15_000;
+let registeredRunner;
+/**
+ * Register the runner the background executor uses to actually execute code.
+ * `createRunCodeEntry` registers one at plugin init, closing over its action
+ * registry + bridge allowlist so background executions get the same bridge
+ * surface (and the same owner-scoped request context) as foreground calls.
+ *
+ * First registration wins: agent-chat-plugin builds the full-surface prod
+ * entry before the lean/dev variants, so the executor runs against the fully
+ * assembled prod action registry.
+ */
+export function registerSandboxExecutionRunner(runner, options = {}) {
+    if (registeredRunner && !options.replace)
+        return;
+    registeredRunner = runner;
+}
+export function getSandboxExecutionRunner() {
+    return registeredRunner;
+}
+/** Test-only: clear registered runner state. */
+export function resetSandboxBackgroundForTests() {
+    registeredRunner = undefined;
+}
+// ---------------------------------------------------------------------------
+// Queued adapter marker
+// ---------------------------------------------------------------------------
+/**
+ * Marker adapter selectable via `AGENT_NATIVE_SANDBOX=background` (or
+ * `registerSandboxAdapter`). It never executes a prepared module itself —
+ * `run-code` detects it via `isQueuedSandboxAdapter` and takes the enqueue
+ * path with the RAW code instead (a prepared module embeds the enqueueing
+ * request's loopback bridge, which dies with that request, so deferring the
+ * prepared source would be wrong by construction).
+ */
+export class BackgroundQueueAdapter {
+    id = "background-queue";
+    /** Marks this adapter as deferred/queued for `isQueuedSandboxAdapter`. */
+    queued = true;
+    async run() {
+        throw new Error("BackgroundQueueAdapter does not execute prepared modules directly. " +
+            "Background executions are enqueued by run-code with the raw code and " +
+            "executed later by the registered sandbox execution runner.");
+    }
+}
+/** True when the active adapter defers execution to the background queue. */
+export function isQueuedSandboxAdapter(adapter) {
+    return Boolean(adapter && adapter.queued === true);
+}
+/**
+ * Create the queued row and kick off its first drive. Never throws on drive
+ * failure — the row stays queued and the poll-time / sweep drains re-drive it.
+ */
+export async function enqueueSandboxExecution(input) {
+    const execution = await createSandboxExecution({
+        owner: input.owner,
+        orgId: input.orgId ?? null,
+        threadId: input.threadId ?? null,
+        code: input.code,
+        timeoutMs: input.timeoutMs,
+        maxOutputChars: input.maxOutputChars,
+    });
+    let driveNote;
+    try {
+        await driveSandboxExecution(execution.id);
+    }
+    catch (err) {
+        driveNote =
+            "Initial dispatch could not be confirmed; the execution stays queued " +
+                "and will start on the next status poll or background sweep. " +
+                `(${err instanceof Error ? err.message : String(err)})`;
+        console.error(`[run-code] background execution ${execution.id} initial drive failed:`, err);
+    }
+    return { execution, driveNote };
+}
+/**
+ * Start (or restart) execution of a queued/lease-expired row.
+ *
+ * Serverless: fire an HMAC-signed self-dispatch so the work runs in a fresh
+ * invocation with its own budget. Long-lived Node: run in-process, detached
+ * from the caller. Both paths funnel into `processQueuedSandboxExecution`,
+ * whose atomic claim guarantees a single executor even when drives race.
+ */
+export async function driveSandboxExecution(executionId, options = {}) {
+    if (isServerlessRuntime()) {
+        await fireInternalDispatch({
+            path: SANDBOX_PROCESS_EXECUTION_PATH,
+            taskId: executionId,
+            event: options.event,
+            body: { executionId },
+        });
+        return;
+    }
+    // Long-lived process: execute here, detached. Errors are logged, never
+    // propagated into the caller (the poll/sweep drains recover).
+    void processQueuedSandboxExecution(executionId).catch((err) => {
+        console.error(`[run-code] in-process background execution ${executionId} failed:`, err);
+    });
+}
+/**
+ * Claim and execute one queued (or lease-expired) execution to completion,
+ * persisting the result. Safe to call from racing invocations: the SQL claim
+ * admits exactly one executor per attempt.
+ */
+export async function processQueuedSandboxExecution(executionId) {
+    const row = await getSandboxExecutionInternal(executionId);
+    if (!row)
+        return { status: "not_found" };
+    const now = Date.now();
+    const leaseExpired = row.status === "running" &&
+        row.leaseExpiresAt !== null &&
+        row.leaseExpiresAt < now;
+    if (row.status !== "queued" && !leaseExpired) {
+        return { status: "not_due", finalStatus: row.status };
+    }
+    const runner = getSandboxExecutionRunner();
+    if (!runner) {
+        // Leave the row queued — a later invocation (where the run-code entry has
+        // been built at plugin init) will pick it up via poll/sweep.
+        console.error(`[run-code] no sandbox execution runner registered; leaving ${executionId} queued.`);
+        return { status: "runner_unavailable" };
+    }
+    const claimToken = crypto.randomUUID();
+    const claimed = await claimSandboxExecution(executionId, claimToken, SANDBOX_EXECUTION_LEASE_MS, now);
+    if (!claimed) {
+        // Either another executor won the race, or attempts ran out. Reap the
+        // exhausted-expired case so the row cannot stay "running" forever.
+        if (leaseExpired && row.attemptCount >= row.maxAttempts) {
+            const reapedNow = await failExpiredSandboxExecution(executionId, `Executor lease expired after ${row.attemptCount} attempt(s); the execution environment was likely terminated before the code finished. Split the computation into smaller chunks or persist intermediate results (e.g. workspaceWrite) and run again.`, now);
+            if (reapedNow)
+                return { status: "completed", finalStatus: "failed" };
+            // Reap refused: a concurrent writer beat us (a zombie executor's
+            // finalize landed, or the state changed) — report what the row is now.
+            const current = await getSandboxExecutionInternal(executionId);
+            return current && current.status !== "running"
+                ? { status: "completed", finalStatus: current.status }
+                : { status: "already_claimed" };
+        }
+        return { status: "already_claimed" };
+    }
+    const heartbeat = setInterval(() => {
+        renewSandboxExecutionLease(executionId, claimToken, SANDBOX_EXECUTION_LEASE_MS).catch(() => {
+            // Best-effort — a failed heartbeat just means the lease may expire and
+            // another executor could reclaim; finalize is claim-token-guarded.
+        });
+    }, HEARTBEAT_INTERVAL_MS);
+    // Never keep a long-lived process alive solely for the heartbeat timer.
+    heartbeat.unref?.();
+    try {
+        const context = {
+            caller: "tool",
+            userEmail: claimed.owner,
+            orgId: claimed.orgId,
+            threadId: claimed.threadId ?? undefined,
+            actionName: "run-code",
+        };
+        const output = await runWithRequestContext({ userEmail: claimed.owner, orgId: claimed.orgId ?? undefined }, () => runner.execute({
+            code: claimed.code,
+            timeoutMs: claimed.timeoutMs,
+            context,
+        }));
+        const finalStatus = output.timedOut
+            ? "timed_out"
+            : output.exitCode === 0
+                ? "succeeded"
+                : "failed";
+        await finalizeSandboxExecution(executionId, claimToken, {
+            status: finalStatus,
+            stdout: output.stdout,
+            stderr: output.stderr,
+            exitCode: output.exitCode,
+            timedOut: output.timedOut,
+            bridgeToolsUsed: output.bridgeToolsUsed,
+            error: output.timedOut
+                ? `Execution exceeded its ${claimed.timeoutMs}ms background timeout and was terminated.`
+                : null,
+        });
+        return { status: "completed", finalStatus };
+    }
+    catch (err) {
+        await finalizeSandboxExecution(executionId, claimToken, {
+            status: "failed",
+            error: `Sandbox executor error: ${err instanceof Error ? err.message : String(err)}`,
+        });
+        return { status: "completed", finalStatus: "failed" };
+    }
+    finally {
+        clearInterval(heartbeat);
+    }
+}
+// ---------------------------------------------------------------------------
+// Drains
+// ---------------------------------------------------------------------------
+/**
+ * Re-drive lost/expired executions. Called opportunistically from the status
+ * poll (for the polled row) and periodically from the warm-instance sweep in
+ * core-routes-plugin. Missing-table errors are treated as "nothing due" so
+ * deployments that never use background run-code pay zero cost.
+ */
+export async function drainDueSandboxExecutions(options = {}) {
+    let due;
+    try {
+        due = await listDueSandboxExecutions({
+            limit: options.limit ?? 5,
+            queuedOlderThanMs: SANDBOX_EXECUTION_REDRIVE_AFTER_MS,
+        });
+    }
+    catch {
+        // Table may not exist yet (background run-code never used) — nothing due.
+        return 0;
+    }
+    let driven = 0;
+    for (const item of due) {
+        try {
+            const expired = item.status === "running" &&
+                item.leaseExpiresAt !== null &&
+                item.leaseExpiresAt < Date.now();
+            if (expired && item.attemptCount >= item.maxAttempts) {
+                await failExpiredSandboxExecution(item.id, `Executor lease expired after ${item.attemptCount} attempt(s); the execution environment was likely terminated before the code finished. Split the computation into smaller chunks or persist intermediate results (e.g. workspaceWrite) and run again.`);
+                driven += 1;
+                continue;
+            }
+            await driveSandboxExecution(item.id, { event: options.event });
+            driven += 1;
+        }
+        catch {
+            // Best-effort per row.
+        }
+    }
+    return driven;
+}
+//# sourceMappingURL=background.js.map

package/dist/coding-tools/sandbox/background.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"background.js","sourceRoot":"","sources":["../../../src/coding-tools/sandbox/background.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AAGjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAErE,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,2BAA2B,EAC3B,wBAAwB,EACxB,2BAA2B,EAC3B,wBAAwB,EACxB,0BAA0B,GAE3B,MAAM,uBAAuB,CAAC;AAE/B,yFAAyF;AACzF,MAAM,CAAC,MAAM,8BAA8B,GACzC,2CAA2C,CAAC;AAE9C,oFAAoF;AACpF,MAAM,CAAC,MAAM,6BAA6B,GAAG,EAAE,GAAG,MAAM,CAAC;AACzD,+DAA+D;AAC/D,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,MAAM,CAAC;AACrD,gFAAgF;AAChF,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC;AACjD,uDAAuD;AACvD,MAAM,qBAAqB,GAAG,MAAM,CAAC;AACrC,gFAAgF;AAChF,MAAM,CAAC,MAAM,kCAAkC,GAAG,MAAM,CAAC;AAwBzD,IAAI,gBAAoD,CAAC;AAEzD;;;;;;;;;GASG;AACH,MAAM,UAAU,8BAA8B,CAC5C,MAA8B,EAC9B,OAAO,GAA0B,EAAE;IAEnC,IAAI,gBAAgB,IAAI,CAAC,OAAO,CAAC,OAAO;QAAE,OAAO;IACjD,gBAAgB,GAAG,MAAM,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,yBAAyB;IAGvC,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,8BAA8B;IAC5C,gBAAgB,GAAG,SAAS,CAAC;AAC/B,CAAC;AAED,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,OAAO,sBAAsB;IACxB,EAAE,GAAG,kBAAkB,CAAC;IACjC,0EAA0E;IACjE,MAAM,GAAG,IAAa,CAAC;IAEhC,KAAK,CAAC,GAAG;QACP,MAAM,IAAI,KAAK,CACb,qEAAqE;YACnE,uEAAuE;YACvE,4DAA4D,CAC/D,CAAC;IACJ,CAAC;CACF;AAED,6EAA6E;AAC7E,MAAM,UAAU,sBAAsB,CACpC,OAA0C;IAE1C,OAAO,OAAO,CAAC,OAAO,IAAK,OAAgC,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC;AAC/E,CAAC;AAqBD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,KAAmC;IAEnC,MAAM,SAAS,GAAG,MAAM,sBAAsB,CAAC;QAC7C,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,IAAI;QAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,IAAI;QAChC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,cAAc,EAAE,KAAK,CAAC,cAAc;KACrC,CAAC,CAAC;IACH,IAAI,SAA6B,CAAC;IAClC,IAAI,CAAC;QACH,MAAM,qBAAqB,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,SAAS;YACP,sEAAsE;gBACtE,8DAA8D;gBAC9D,IAAI,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;QAC1D,OAAO,CAAC,KAAK,CACX,mCAAmC,SAAS,CAAC,EAAE,wBAAwB,EACvE,GAAG,CACJ,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;AAClC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,WAAmB,EACnB,OAAO,GAAwB,EAAE;IAEjC,IAAI,mBAAmB,EAAE,EAAE,CAAC;QAC1B,MAAM,oBAAoB,CAAC;YACzB,IAAI,EAAE,8BAA8B;YACpC,MAAM,EAAE,WAAW;YACnB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,IAAI,EAAE,EAAE,WAAW,EAAE;SACtB,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IACD,uEAAuE;IACvE,8DAA8D;IAC9D,KAAK,6BAA6B,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QAC5D,OAAO,CAAC,KAAK,CACX,8CAA8C,WAAW,UAAU,EACnE,GAAG,CACJ,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAgBD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,WAAmB;IAEnB,MAAM,GAAG,GAAG,MAAM,2BAA2B,CAAC,WAAW,CAAC,CAAC;IAC3D,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IACzC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,YAAY,GAChB,GAAG,CAAC,MAAM,KAAK,SAAS;QACxB,GAAG,CAAC,cAAc,KAAK,IAAI;QAC3B,GAAG,CAAC,cAAc,GAAG,GAAG,CAAC;IAC3B,IAAI,GAAG,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,YAAY,EAAE,CAAC;QAC7C,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;IACxD,CAAC;IAED,MAAM,MAAM,GAAG,yBAAyB,EAAE,CAAC;IAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,0EAA0E;QAC1E,6DAA6D;QAC7D,OAAO,CAAC,KAAK,CACX,8DAA8D,WAAW,UAAU,CACpF,CAAC;QACF,OAAO,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC1C,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;IACvC,MAAM,OAAO,GAAG,MAAM,qBAAqB,CACzC,WAAW,EACX,UAAU,EACV,0BAA0B,EAC1B,GAAG,CACJ,CAAC;IACF,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,sEAAsE;QACtE,mEAAmE;QACnE,IAAI,YAAY,IAAI,GAAG,CAAC,YAAY,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;YACxD,MAAM,SAAS,GAAG,MAAM,2BAA2B,CACjD,WAAW,EACX,gCAAgC,GAAG,CAAC,YAAY,uMAAuM,EACvP,GAAG,CACJ,CAAC;YACF,IAAI,SAAS;gBAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;YACrE,iEAAiE;YACjE,uEAAuE;YACvE,MAAM,OAAO,GAAG,MAAM,2BAA2B,CAAC,WAAW,CAAC,CAAC;YAC/D,OAAO,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;gBAC5C,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,MAAM,EAAE;gBACtD,CAAC,CAAC,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;QACpC,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IACvC,CAAC;IAED,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;QACjC,0BAA0B,CACxB,WAAW,EACX,UAAU,EACV,0BAA0B,CAC3B,CAAC,KAAK,CAAC,GAAG,EAAE;YACX,uEAAuE;YACvE,mEAAmE;QACrE,CAAC,CAAC,CAAC;IACL,CAAC,EAAE,qBAAqB,CAAC,CAAC;IAC1B,wEAAwE;IACvE,SAAoC,CAAC,KAAK,EAAE,EAAE,CAAC;IAEhD,IAAI,CAAC;QACH,MAAM,OAAO,GAAqB;YAChC,MAAM,EAAE,MAAM;YACd,SAAS,EAAE,OAAO,CAAC,KAAK;YACxB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,SAAS;YACvC,UAAU,EAAE,UAAU;SACvB,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,qBAAqB,CACxC,EAAE,SAAS,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,SAAS,EAAE,EAC/D,GAAG,EAAE,CACH,MAAM,CAAC,OAAO,CAAC;YACb,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,OAAO;SACR,CAAC,CACL,CAAC;QACF,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ;YACjC,CAAC,CAAC,WAAW;YACb,CAAC,CAAC,MAAM,CAAC,QAAQ,KAAK,CAAC;gBACrB,CAAC,CAAC,WAAW;gBACb,CAAC,CAAC,QAAQ,CAAC;QACf,MAAM,wBAAwB,CAAC,WAAW,EAAE,UAAU,EAAE;YACtD,MAAM,EAAE,WAAW;YACnB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,KAAK,EAAE,MAAM,CAAC,QAAQ;gBACpB,CAAC,CAAC,0BAA0B,OAAO,CAAC,SAAS,2CAA2C;gBACxF,CAAC,CAAC,IAAI;SACT,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;IAC9C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,wBAAwB,CAAC,WAAW,EAAE,UAAU,EAAE;YACtD,MAAM,EAAE,QAAQ;YAChB,KAAK,EAAE,2BAA2B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;SACrF,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;IACxD,CAAC;YAAS,CAAC;QACT,aAAa,CAAC,SAAS,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,OAAO,GAAwC,EAAE;IAEjD,IAAI,GAAyD,CAAC;IAC9D,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,wBAAwB,CAAC;YACnC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;YACzB,iBAAiB,EAAE,kCAAkC;SACtD,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;QAC1E,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;QACvB,IAAI,CAAC;YACH,MAAM,OAAO,GACX,IAAI,CAAC,MAAM,KAAK,SAAS;gBACzB,IAAI,CAAC,cAAc,KAAK,IAAI;gBAC5B,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACnC,IAAI,OAAO,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;gBACrD,MAAM,2BAA2B,CAC/B,IAAI,CAAC,EAAE,EACP,gCAAgC,IAAI,CAAC,YAAY,uMAAuM,CACzP,CAAC;gBACF,MAAM,IAAI,CAAC,CAAC;gBACZ,SAAS;YACX,CAAC;YACD,MAAM,qBAAqB,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;YAC/D,MAAM,IAAI,CAAC,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,uBAAuB;QACzB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["/**\n * Durable background execution for the `run-code` tool.\n *\n * The hosted agent loop runs under a soft wall-clock ceiling (~40s on\n * serverless): a foreground `run-code` call that outlives it is aborted and —\n * because `run-code` is readOnly — its result is simply lost. This module is\n * the queued, durable alternative wired through the existing sandbox-adapter\n * seam: enqueue the raw code to SQL (`sandbox_executions`), return\n * `{ executionId, status: \"queued\" }` immediately, and let an executor with\n * its own budget claim the row, run it through the local sandbox machinery,\n * and persist the result for later polling.\n *\n * Execution drivers, by deployment mode:\n *  1. Serverless (Netlify/Vercel/Lambda/CF): `fireInternalDispatch` POSTs to\n *     `/_agent-native/sandbox/_process-execution` on this same deployment, so\n *     the code runs in a FRESH function invocation with its own full budget —\n *     the same self-dispatch pattern A2A, integration webhooks, and Agent\n *     Teams use. HMAC-verified via the shared internal-token scheme.\n *  2. Long-lived Node (self-hosted, local dev): the execution starts in-process\n *     immediately after enqueue, detached from the enqueueing tool call.\n *  3. Opportunistic drain: every status poll re-drives a row that is still\n *     `queued` (lost dispatch) or whose lease expired (dead executor), and a\n *     periodic warm-instance sweep (`drainDueSandboxExecutions`, mounted by\n *     the core routes plugin) does the same as a backstop.\n *\n * The executor itself never re-enters adapter selection (that could recurse\n * into this queue when `AGENT_NATIVE_SANDBOX=background`): the runner\n * registered by `createRunCodeEntry` executes through the non-queued adapter\n * (the local child process by default), with the bridge/env-scrub/module\n * building unchanged from the foreground path.\n */\n\nimport crypto from \"node:crypto\";\n\nimport type { ActionRunContext } from \"../../action.js\";\nimport { isServerlessRuntime } from \"../../db/client.js\";\nimport { runWithRequestContext } from \"../../server/request-context.js\";\nimport { fireInternalDispatch } from \"../../server/self-dispatch.js\";\nimport type { SandboxAdapter, SandboxRunResult } from \"./adapter.js\";\nimport {\n  claimSandboxExecution,\n  createSandboxExecution,\n  failExpiredSandboxExecution,\n  finalizeSandboxExecution,\n  getSandboxExecutionInternal,\n  listDueSandboxExecutions,\n  renewSandboxExecutionLease,\n  type SandboxExecutionRow,\n} from \"./executions-store.js\";\n\n/** Framework route the enqueue self-dispatch targets (mounted by core-routes-plugin). */\nexport const SANDBOX_PROCESS_EXECUTION_PATH =\n  \"/_agent-native/sandbox/_process-execution\";\n\n/** Default background budget — generous compared to the foreground 120s default. */\nexport const BACKGROUND_DEFAULT_TIMEOUT_MS = 10 * 60_000;\n/** Hard cap on a single background execution's own timeout. */\nexport const BACKGROUND_MAX_TIMEOUT_MS = 30 * 60_000;\n/** Lease duration; an executor that misses ~3 heartbeats is considered dead. */\nexport const SANDBOX_EXECUTION_LEASE_MS = 90_000;\n/** Heartbeat cadence while an execution is running. */\nconst HEARTBEAT_INTERVAL_MS = 30_000;\n/** A queued row older than this with no claim is treated as a lost dispatch. */\nexport const SANDBOX_EXECUTION_REDRIVE_AFTER_MS = 15_000;\n\n// ---------------------------------------------------------------------------\n// Runner registration\n// ---------------------------------------------------------------------------\n\nexport interface SandboxExecutionRunInput {\n  code: string;\n  timeoutMs: number;\n  context?: ActionRunContext;\n}\n\nexport interface SandboxExecutionRunOutput {\n  stdout: string;\n  stderr: string;\n  exitCode: number | null;\n  timedOut: boolean;\n  bridgeToolsUsed: string[];\n}\n\nexport interface SandboxExecutionRunner {\n  execute(input: SandboxExecutionRunInput): Promise<SandboxExecutionRunOutput>;\n}\n\nlet registeredRunner: SandboxExecutionRunner | undefined;\n\n/**\n * Register the runner the background executor uses to actually execute code.\n * `createRunCodeEntry` registers one at plugin init, closing over its action\n * registry + bridge allowlist so background executions get the same bridge\n * surface (and the same owner-scoped request context) as foreground calls.\n *\n * First registration wins: agent-chat-plugin builds the full-surface prod\n * entry before the lean/dev variants, so the executor runs against the fully\n * assembled prod action registry.\n */\nexport function registerSandboxExecutionRunner(\n  runner: SandboxExecutionRunner,\n  options: { replace?: boolean } = {},\n): void {\n  if (registeredRunner && !options.replace) return;\n  registeredRunner = runner;\n}\n\nexport function getSandboxExecutionRunner():\n  | SandboxExecutionRunner\n  | undefined {\n  return registeredRunner;\n}\n\n/** Test-only: clear registered runner state. */\nexport function resetSandboxBackgroundForTests(): void {\n  registeredRunner = undefined;\n}\n\n// ---------------------------------------------------------------------------\n// Queued adapter marker\n// ---------------------------------------------------------------------------\n\n/**\n * Marker adapter selectable via `AGENT_NATIVE_SANDBOX=background` (or\n * `registerSandboxAdapter`). It never executes a prepared module itself —\n * `run-code` detects it via `isQueuedSandboxAdapter` and takes the enqueue\n * path with the RAW code instead (a prepared module embeds the enqueueing\n * request's loopback bridge, which dies with that request, so deferring the\n * prepared source would be wrong by construction).\n */\nexport class BackgroundQueueAdapter implements SandboxAdapter {\n  readonly id = \"background-queue\";\n  /** Marks this adapter as deferred/queued for `isQueuedSandboxAdapter`. */\n  readonly queued = true as const;\n\n  async run(): Promise<SandboxRunResult> {\n    throw new Error(\n      \"BackgroundQueueAdapter does not execute prepared modules directly. \" +\n        \"Background executions are enqueued by run-code with the raw code and \" +\n        \"executed later by the registered sandbox execution runner.\",\n    );\n  }\n}\n\n/** True when the active adapter defers execution to the background queue. */\nexport function isQueuedSandboxAdapter(\n  adapter: SandboxAdapter | null | undefined,\n): boolean {\n  return Boolean(adapter && (adapter as { queued?: boolean }).queued === true);\n}\n\n// ---------------------------------------------------------------------------\n// Enqueue + drive\n// ---------------------------------------------------------------------------\n\nexport interface EnqueueSandboxExecutionInput {\n  code: string;\n  timeoutMs: number;\n  maxOutputChars: number;\n  owner: string;\n  orgId?: string | null;\n  threadId?: string | null;\n}\n\nexport interface EnqueueSandboxExecutionResult {\n  execution: SandboxExecutionRow;\n  /** Human-readable note when the initial drive could not be confirmed. */\n  driveNote?: string;\n}\n\n/**\n * Create the queued row and kick off its first drive. Never throws on drive\n * failure — the row stays queued and the poll-time / sweep drains re-drive it.\n */\nexport async function enqueueSandboxExecution(\n  input: EnqueueSandboxExecutionInput,\n): Promise<EnqueueSandboxExecutionResult> {\n  const execution = await createSandboxExecution({\n    owner: input.owner,\n    orgId: input.orgId ?? null,\n    threadId: input.threadId ?? null,\n    code: input.code,\n    timeoutMs: input.timeoutMs,\n    maxOutputChars: input.maxOutputChars,\n  });\n  let driveNote: string | undefined;\n  try {\n    await driveSandboxExecution(execution.id);\n  } catch (err) {\n    driveNote =\n      \"Initial dispatch could not be confirmed; the execution stays queued \" +\n      \"and will start on the next status poll or background sweep. \" +\n      `(${err instanceof Error ? err.message : String(err)})`;\n    console.error(\n      `[run-code] background execution ${execution.id} initial drive failed:`,\n      err,\n    );\n  }\n  return { execution, driveNote };\n}\n\n/**\n * Start (or restart) execution of a queued/lease-expired row.\n *\n * Serverless: fire an HMAC-signed self-dispatch so the work runs in a fresh\n * invocation with its own budget. Long-lived Node: run in-process, detached\n * from the caller. Both paths funnel into `processQueuedSandboxExecution`,\n * whose atomic claim guarantees a single executor even when drives race.\n */\nexport async function driveSandboxExecution(\n  executionId: string,\n  options: { event?: unknown } = {},\n): Promise<void> {\n  if (isServerlessRuntime()) {\n    await fireInternalDispatch({\n      path: SANDBOX_PROCESS_EXECUTION_PATH,\n      taskId: executionId,\n      event: options.event,\n      body: { executionId },\n    });\n    return;\n  }\n  // Long-lived process: execute here, detached. Errors are logged, never\n  // propagated into the caller (the poll/sweep drains recover).\n  void processQueuedSandboxExecution(executionId).catch((err) => {\n    console.error(\n      `[run-code] in-process background execution ${executionId} failed:`,\n      err,\n    );\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Executor\n// ---------------------------------------------------------------------------\n\nexport interface ProcessSandboxExecutionResult {\n  status:\n    | \"completed\"\n    | \"already_claimed\"\n    | \"not_found\"\n    | \"not_due\"\n    | \"runner_unavailable\";\n  finalStatus?: SandboxExecutionRow[\"status\"];\n}\n\n/**\n * Claim and execute one queued (or lease-expired) execution to completion,\n * persisting the result. Safe to call from racing invocations: the SQL claim\n * admits exactly one executor per attempt.\n */\nexport async function processQueuedSandboxExecution(\n  executionId: string,\n): Promise<ProcessSandboxExecutionResult> {\n  const row = await getSandboxExecutionInternal(executionId);\n  if (!row) return { status: \"not_found\" };\n  const now = Date.now();\n  const leaseExpired =\n    row.status === \"running\" &&\n    row.leaseExpiresAt !== null &&\n    row.leaseExpiresAt < now;\n  if (row.status !== \"queued\" && !leaseExpired) {\n    return { status: \"not_due\", finalStatus: row.status };\n  }\n\n  const runner = getSandboxExecutionRunner();\n  if (!runner) {\n    // Leave the row queued — a later invocation (where the run-code entry has\n    // been built at plugin init) will pick it up via poll/sweep.\n    console.error(\n      `[run-code] no sandbox execution runner registered; leaving ${executionId} queued.`,\n    );\n    return { status: \"runner_unavailable\" };\n  }\n\n  const claimToken = crypto.randomUUID();\n  const claimed = await claimSandboxExecution(\n    executionId,\n    claimToken,\n    SANDBOX_EXECUTION_LEASE_MS,\n    now,\n  );\n  if (!claimed) {\n    // Either another executor won the race, or attempts ran out. Reap the\n    // exhausted-expired case so the row cannot stay \"running\" forever.\n    if (leaseExpired && row.attemptCount >= row.maxAttempts) {\n      const reapedNow = await failExpiredSandboxExecution(\n        executionId,\n        `Executor lease expired after ${row.attemptCount} attempt(s); the execution environment was likely terminated before the code finished. Split the computation into smaller chunks or persist intermediate results (e.g. workspaceWrite) and run again.`,\n        now,\n      );\n      if (reapedNow) return { status: \"completed\", finalStatus: \"failed\" };\n      // Reap refused: a concurrent writer beat us (a zombie executor's\n      // finalize landed, or the state changed) — report what the row is now.\n      const current = await getSandboxExecutionInternal(executionId);\n      return current && current.status !== \"running\"\n        ? { status: \"completed\", finalStatus: current.status }\n        : { status: \"already_claimed\" };\n    }\n    return { status: \"already_claimed\" };\n  }\n\n  const heartbeat = setInterval(() => {\n    renewSandboxExecutionLease(\n      executionId,\n      claimToken,\n      SANDBOX_EXECUTION_LEASE_MS,\n    ).catch(() => {\n      // Best-effort — a failed heartbeat just means the lease may expire and\n      // another executor could reclaim; finalize is claim-token-guarded.\n    });\n  }, HEARTBEAT_INTERVAL_MS);\n  // Never keep a long-lived process alive solely for the heartbeat timer.\n  (heartbeat as { unref?: () => void }).unref?.();\n\n  try {\n    const context: ActionRunContext = {\n      caller: \"tool\",\n      userEmail: claimed.owner,\n      orgId: claimed.orgId,\n      threadId: claimed.threadId ?? undefined,\n      actionName: \"run-code\",\n    };\n    const output = await runWithRequestContext(\n      { userEmail: claimed.owner, orgId: claimed.orgId ?? undefined },\n      () =>\n        runner.execute({\n          code: claimed.code,\n          timeoutMs: claimed.timeoutMs,\n          context,\n        }),\n    );\n    const finalStatus = output.timedOut\n      ? \"timed_out\"\n      : output.exitCode === 0\n        ? \"succeeded\"\n        : \"failed\";\n    await finalizeSandboxExecution(executionId, claimToken, {\n      status: finalStatus,\n      stdout: output.stdout,\n      stderr: output.stderr,\n      exitCode: output.exitCode,\n      timedOut: output.timedOut,\n      bridgeToolsUsed: output.bridgeToolsUsed,\n      error: output.timedOut\n        ? `Execution exceeded its ${claimed.timeoutMs}ms background timeout and was terminated.`\n        : null,\n    });\n    return { status: \"completed\", finalStatus };\n  } catch (err) {\n    await finalizeSandboxExecution(executionId, claimToken, {\n      status: \"failed\",\n      error: `Sandbox executor error: ${err instanceof Error ? err.message : String(err)}`,\n    });\n    return { status: \"completed\", finalStatus: \"failed\" };\n  } finally {\n    clearInterval(heartbeat);\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Drains\n// ---------------------------------------------------------------------------\n\n/**\n * Re-drive lost/expired executions. Called opportunistically from the status\n * poll (for the polled row) and periodically from the warm-instance sweep in\n * core-routes-plugin. Missing-table errors are treated as \"nothing due\" so\n * deployments that never use background run-code pay zero cost.\n */\nexport async function drainDueSandboxExecutions(\n  options: { limit?: number; event?: unknown } = {},\n): Promise<number> {\n  let due: Awaited<ReturnType<typeof listDueSandboxExecutions>>;\n  try {\n    due = await listDueSandboxExecutions({\n      limit: options.limit ?? 5,\n      queuedOlderThanMs: SANDBOX_EXECUTION_REDRIVE_AFTER_MS,\n    });\n  } catch {\n    // Table may not exist yet (background run-code never used) — nothing due.\n    return 0;\n  }\n  let driven = 0;\n  for (const item of due) {\n    try {\n      const expired =\n        item.status === \"running\" &&\n        item.leaseExpiresAt !== null &&\n        item.leaseExpiresAt < Date.now();\n      if (expired && item.attemptCount >= item.maxAttempts) {\n        await failExpiredSandboxExecution(\n          item.id,\n          `Executor lease expired after ${item.attemptCount} attempt(s); the execution environment was likely terminated before the code finished. Split the computation into smaller chunks or persist intermediate results (e.g. workspaceWrite) and run again.`,\n        );\n        driven += 1;\n        continue;\n      }\n      await driveSandboxExecution(item.id, { event: options.event });\n      driven += 1;\n    } catch {\n      // Best-effort per row.\n    }\n  }\n  return driven;\n}\n"]}

package/dist/coding-tools/sandbox/executions-store.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Durable storage for queued `run-code` sandbox executions.
+ *
+ * A row in `sandbox_executions` is one background code-execution request: the
+ * raw user code plus enough identity (owner email, org, thread) to rebuild the
+ * action bridge context in a fresh process, and the full result once an
+ * executor finishes. This is what lets a long compute job survive the hosted
+ * serverless wall: the enqueueing request returns immediately, and any later
+ * invocation (self-dispatch processor, status poll, warm-instance sweep) can
+ * claim and run the row under its own budget.
+ *
+ * Concurrency model (single-writer via claim token + lease):
+ *  - `claimSandboxExecution` atomically flips `queued → running` (or reclaims
+ *    a `running` row whose lease expired) with `UPDATE … WHERE status = …`
+ *    guards, so exactly one executor wins even when several invocations race.
+ *  - The winning executor holds a random `claim_token` and heartbeats
+ *    `lease_expires_at`; `finalizeSandboxExecution` only writes results when
+ *    the token still matches, so a displaced executor can never clobber the
+ *    reclaimer's result.
+ *  - A row whose lease expired with attempts remaining is re-claimable; once
+ *    attempts are exhausted `failExpiredSandboxExecution` marks it `failed`
+ *    instead of leaving it "running" forever.
+ *
+ * Schema notes: additive-only, portable across Postgres (Neon) and SQLite —
+ * same `ensureTableExists`/dialect-branched DDL pattern as
+ * `resources/store.ts`. Timestamps are epoch-ms in `BIGINT`/`INTEGER` columns.
+ * Reads for user-facing surfaces are always owner-scoped
+ * (`getSandboxExecutionForOwner`); the unscoped internal reader exists only
+ * for the trusted executor/sweep paths.
+ */
+export type SandboxExecutionStatus = "queued" | "running" | "succeeded" | "failed" | "timed_out";
+export interface SandboxExecutionRow {
+    id: string;
+    owner: string;
+    orgId: string | null;
+    threadId: string | null;
+    runtime: string;
+    code: string;
+    status: SandboxExecutionStatus;
+    timeoutMs: number;
+    maxOutputChars: number;
+    attemptCount: number;
+    maxAttempts: number;
+    claimToken: string | null;
+    leaseExpiresAt: number | null;
+    stdout: string;
+    stderr: string;
+    stdoutTruncated: boolean;
+    stderrTruncated: boolean;
+    exitCode: number | null;
+    timedOut: boolean;
+    error: string | null;
+    bridgeToolsUsed: string[];
+    createdAt: number;
+    startedAt: number | null;
+    finishedAt: number | null;
+    updatedAt: number;
+}
+export interface CreateSandboxExecutionInput {
+    owner: string;
+    orgId?: string | null;
+    threadId?: string | null;
+    code: string;
+    timeoutMs: number;
+    maxOutputChars: number;
+    maxAttempts?: number;
+    runtime?: string;
+}
+export interface FinalizeSandboxExecutionInput {
+    status: Extract<SandboxExecutionStatus, "succeeded" | "failed" | "timed_out">;
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number | null;
+    timedOut?: boolean;
+    error?: string | null;
+    bridgeToolsUsed?: string[];
+}
+/** Default retry budget: the initial attempt plus one lease-expiry retry. */
+export declare const SANDBOX_EXECUTION_DEFAULT_MAX_ATTEMPTS = 2;
+/**
+ * Hard per-stream storage cap. The per-row `max_output_chars` (derived from
+ * the caller's `maxOutputChars`) is applied first; this bounds even that.
+ */
+export declare const SANDBOX_EXECUTION_MAX_STORED_OUTPUT_CHARS = 200000;
+/** Test-only: forget the memoized init so a fresh in-memory DB re-creates. */
+export declare function resetSandboxExecutionsStoreForTests(): void;
+/** Enqueue a new execution row in `queued` state. */
+export declare function createSandboxExecution(input: CreateSandboxExecutionInput): Promise<SandboxExecutionRow>;
+/** Owner-scoped read for user-facing status/result surfaces. */
+export declare function getSandboxExecutionForOwner(id: string, owner: string): Promise<SandboxExecutionRow | null>;
+/**
+ * Unscoped read for the trusted executor/sweep paths ONLY. Never expose this
+ * through a user-facing action — use `getSandboxExecutionForOwner`.
+ */
+export declare function getSandboxExecutionInternal(id: string): Promise<SandboxExecutionRow | null>;
+/**
+ * Atomically claim an execution for a single executor. Claims a `queued` row,
+ * or reclaims a `running` row whose lease expired, as long as the attempt
+ * budget is not exhausted. Returns the claimed row (with the new claim token)
+ * or null when another executor holds it / it is terminal / attempts ran out.
+ */
+export declare function claimSandboxExecution(id: string, claimToken: string, leaseMs: number, now?: number): Promise<SandboxExecutionRow | null>;
+/** Heartbeat: extend the lease while the claimed execution is still running. */
+export declare function renewSandboxExecutionLease(id: string, claimToken: string, leaseMs: number, now?: number): Promise<boolean>;
+/**
+ * Write the terminal result. Single-writer safe: only the executor whose
+ * claim token still matches the row (i.e. it was not reclaimed after a lease
+ * expiry) can finalize. Returns false when the row was already finalized or
+ * reclaimed — the caller must discard its result.
+ */
+export declare function finalizeSandboxExecution(id: string, claimToken: string, input: FinalizeSandboxExecutionInput, now?: number): Promise<boolean>;
+/**
+ * Reap a `running` row whose lease expired after its attempt budget was
+ * exhausted, so it never sits "running" forever. Atomic: guarded on the same
+ * expiry + budget conditions, so a live executor (fresh lease) is untouched.
+ */
+export declare function failExpiredSandboxExecution(id: string, error: string, now?: number): Promise<boolean>;
+export interface DueSandboxExecution {
+    id: string;
+    status: SandboxExecutionStatus;
+    attemptCount: number;
+    maxAttempts: number;
+    leaseExpiresAt: number | null;
+}
+/**
+ * List rows that need driving: `queued` rows that have sat unclaimed longer
+ * than `queuedOlderThanMs` (their enqueue-time dispatch was likely lost), and
+ * `running` rows whose lease expired (executor died). Used by the sweep and
+ * the poll-time drain. Deliberately does NOT call `ensureTable()` — the sweep
+ * must stay a zero-footprint no-op on deployments that never enqueue; callers
+ * treat a missing-table error as "nothing due".
+ */
+export declare function listDueSandboxExecutions(options: {
+    limit?: number;
+    queuedOlderThanMs?: number;
+    now?: number;
+}): Promise<DueSandboxExecution[]>;
+//# sourceMappingURL=executions-store.d.ts.map

package/dist/coding-tools/sandbox/executions-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executions-store.d.ts","sourceRoot":"","sources":["../../../src/coding-tools/sandbox/executions-store.ts"],"names":[],"mappings":"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"}