@agent-native/core 0.88.0 → 0.90.2

package/dist/coding-tools/sandbox/executions-store.js

@@ -0,0 +1,380 @@
+/**
+ * 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.
+ */
+import crypto from "node:crypto";
+import { getDbExec, intType, isPostgres, retryOnDdlRace, } from "../../db/client.js";
+import { ensureColumnExists, ensureIndexExists, ensureTableExists, } from "../../db/ddl-guard.js";
+/** Default retry budget: the initial attempt plus one lease-expiry retry. */
+export 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 const SANDBOX_EXECUTION_MAX_STORED_OUTPUT_CHARS = 200_000;
+const TABLE = "sandbox_executions";
+let _initPromise;
+async function ensureTable() {
+    if (!_initPromise) {
+        _initPromise = _doEnsureTable().catch((err) => {
+            // Don't cache the rejection — let the next caller retry a fresh init.
+            _initPromise = undefined;
+            throw err;
+        });
+    }
+    return _initPromise;
+}
+/** Test-only: forget the memoized init so a fresh in-memory DB re-creates. */
+export function resetSandboxExecutionsStoreForTests() {
+    _initPromise = undefined;
+}
+async function _doEnsureTable() {
+    const client = getDbExec();
+    const createSql = `
+    CREATE TABLE IF NOT EXISTS ${TABLE} (
+      id TEXT PRIMARY KEY,
+      owner TEXT NOT NULL,
+      org_id TEXT,
+      thread_id TEXT,
+      runtime TEXT NOT NULL DEFAULT 'node',
+      code TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'queued',
+      timeout_ms ${intType()} NOT NULL,
+      max_output_chars ${intType()} NOT NULL,
+      attempt_count ${intType()} NOT NULL DEFAULT 0,
+      max_attempts ${intType()} NOT NULL DEFAULT ${SANDBOX_EXECUTION_DEFAULT_MAX_ATTEMPTS},
+      claim_token TEXT,
+      lease_expires_at ${intType()},
+      stdout TEXT NOT NULL DEFAULT '',
+      stderr TEXT NOT NULL DEFAULT '',
+      stdout_truncated ${intType()} NOT NULL DEFAULT 0,
+      stderr_truncated ${intType()} NOT NULL DEFAULT 0,
+      exit_code ${intType()},
+      timed_out ${intType()} NOT NULL DEFAULT 0,
+      error TEXT,
+      bridge_tools_used TEXT,
+      created_at ${intType()} NOT NULL,
+      started_at ${intType()},
+      finished_at ${intType()},
+      updated_at ${intType()} NOT NULL
+    )
+  `;
+    const ownerIdxSql = `CREATE INDEX IF NOT EXISTS sandbox_executions_owner_created_idx ON ${TABLE} (owner, created_at)`;
+    const dueIdxSql = `CREATE INDEX IF NOT EXISTS sandbox_executions_due_idx ON ${TABLE} (status, lease_expires_at)`;
+    if (isPostgres()) {
+        // Probe information_schema first (no lock) and DDL only what's missing —
+        // same guarded pattern as resources/store.ts so a fresh background worker
+        // never blocks on an ACCESS EXCLUSIVE lock for schema that already exists.
+        await ensureTableExists(TABLE, createSql);
+        // Additive-column guard: keeps older deployments (created before a column
+        // was added) self-healing without destructive migrations.
+        const pgColumns = [["bridge_tools_used", "TEXT"]];
+        for (const [col, def] of pgColumns) {
+            await ensureColumnExists(TABLE, col, `ALTER TABLE ${TABLE} ADD COLUMN IF NOT EXISTS ${col} ${def}`);
+        }
+        await ensureIndexExists("sandbox_executions_owner_created_idx", ownerIdxSql);
+        await ensureIndexExists("sandbox_executions_due_idx", dueIdxSql);
+    }
+    else {
+        await retryOnDdlRace(() => client.execute(createSql));
+        await retryOnDdlRace(() => client.execute(ownerIdxSql));
+        await retryOnDdlRace(() => client.execute(dueIdxSql));
+    }
+}
+function capOutput(value, maxChars) {
+    const raw = typeof value === "string" ? value : "";
+    const cap = Math.max(1, Math.min(maxChars, SANDBOX_EXECUTION_MAX_STORED_OUTPUT_CHARS));
+    if (raw.length <= cap)
+        return { text: raw, truncated: false };
+    return { text: raw.slice(0, cap), truncated: true };
+}
+function toBool(value) {
+    return value === true || value === 1 || value === "1" || value === "true";
+}
+function toNumberOrNull(value) {
+    if (value === null || value === undefined || value === "")
+        return null;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function rowFromDb(raw) {
+    let bridgeToolsUsed = [];
+    if (typeof raw.bridge_tools_used === "string" && raw.bridge_tools_used) {
+        try {
+            const parsed = JSON.parse(raw.bridge_tools_used);
+            if (Array.isArray(parsed)) {
+                bridgeToolsUsed = parsed.filter((item) => typeof item === "string");
+            }
+        }
+        catch {
+            bridgeToolsUsed = [];
+        }
+    }
+    return {
+        id: String(raw.id),
+        owner: String(raw.owner),
+        orgId: raw.org_id === null || raw.org_id === undefined
+            ? null
+            : String(raw.org_id),
+        threadId: raw.thread_id === null || raw.thread_id === undefined
+            ? null
+            : String(raw.thread_id),
+        runtime: String(raw.runtime ?? "node"),
+        code: String(raw.code ?? ""),
+        status: String(raw.status ?? "queued"),
+        timeoutMs: toNumberOrNull(raw.timeout_ms) ?? 0,
+        maxOutputChars: toNumberOrNull(raw.max_output_chars) ?? 0,
+        attemptCount: toNumberOrNull(raw.attempt_count) ?? 0,
+        maxAttempts: toNumberOrNull(raw.max_attempts) ??
+            SANDBOX_EXECUTION_DEFAULT_MAX_ATTEMPTS,
+        claimToken: raw.claim_token === null || raw.claim_token === undefined
+            ? null
+            : String(raw.claim_token),
+        leaseExpiresAt: toNumberOrNull(raw.lease_expires_at),
+        stdout: String(raw.stdout ?? ""),
+        stderr: String(raw.stderr ?? ""),
+        stdoutTruncated: toBool(raw.stdout_truncated),
+        stderrTruncated: toBool(raw.stderr_truncated),
+        exitCode: toNumberOrNull(raw.exit_code),
+        timedOut: toBool(raw.timed_out),
+        error: raw.error === null || raw.error === undefined ? null : String(raw.error),
+        bridgeToolsUsed,
+        createdAt: toNumberOrNull(raw.created_at) ?? 0,
+        startedAt: toNumberOrNull(raw.started_at),
+        finishedAt: toNumberOrNull(raw.finished_at),
+        updatedAt: toNumberOrNull(raw.updated_at) ?? 0,
+    };
+}
+/** Enqueue a new execution row in `queued` state. */
+export async function createSandboxExecution(input) {
+    await ensureTable();
+    const client = getDbExec();
+    const now = Date.now();
+    const id = `sbx_${crypto.randomUUID()}`;
+    const maxAttempts = Math.max(1, Math.min(input.maxAttempts ?? SANDBOX_EXECUTION_DEFAULT_MAX_ATTEMPTS, 5));
+    await client.execute({
+        sql: `INSERT INTO ${TABLE}
+      (id, owner, org_id, thread_id, runtime, code, status, timeout_ms, max_output_chars, attempt_count, max_attempts, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, 'queued', ?, ?, 0, ?, ?, ?)`,
+        args: [
+            id,
+            input.owner,
+            input.orgId ?? null,
+            input.threadId ?? null,
+            input.runtime ?? "node",
+            input.code,
+            input.timeoutMs,
+            input.maxOutputChars,
+            maxAttempts,
+            now,
+            now,
+        ],
+    });
+    const row = await getSandboxExecutionInternal(id);
+    if (!row)
+        throw new Error(`sandbox execution ${id} vanished after insert`);
+    return row;
+}
+/** Owner-scoped read for user-facing status/result surfaces. */
+export async function getSandboxExecutionForOwner(id, owner) {
+    if (!id || !owner)
+        return null;
+    await ensureTable();
+    const client = getDbExec();
+    const result = await client.execute({
+        sql: `SELECT * FROM ${TABLE} WHERE id = ? AND owner = ? LIMIT 1`,
+        args: [id, owner],
+    });
+    const raw = result.rows?.[0];
+    return raw ? rowFromDb(raw) : null;
+}
+/**
+ * Unscoped read for the trusted executor/sweep paths ONLY. Never expose this
+ * through a user-facing action — use `getSandboxExecutionForOwner`.
+ */
+export async function getSandboxExecutionInternal(id) {
+    if (!id)
+        return null;
+    await ensureTable();
+    const client = getDbExec();
+    const result = await client.execute({
+        sql: `SELECT * FROM ${TABLE} WHERE id = ? LIMIT 1`,
+        args: [id],
+    });
+    const raw = result.rows?.[0];
+    return raw ? rowFromDb(raw) : 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 async function claimSandboxExecution(id, claimToken, leaseMs, now = Date.now()) {
+    await ensureTable();
+    const client = getDbExec();
+    const result = await client.execute({
+        sql: `UPDATE ${TABLE}
+      SET status = 'running',
+          claim_token = ?,
+          lease_expires_at = ?,
+          attempt_count = attempt_count + 1,
+          started_at = COALESCE(started_at, ?),
+          updated_at = ?
+      WHERE id = ?
+        AND attempt_count < max_attempts
+        AND (
+          status = 'queued'
+          OR (status = 'running' AND lease_expires_at IS NOT NULL AND lease_expires_at < ?)
+        )`,
+        args: [claimToken, now + leaseMs, now, now, id, now],
+    });
+    if ((result.rowsAffected ?? 0) !== 1)
+        return null;
+    const row = await getSandboxExecutionInternal(id);
+    // Verify the claim token survived (paranoia against a same-ms racing UPDATE
+    // on drivers that report affected rows loosely).
+    if (!row || row.claimToken !== claimToken)
+        return null;
+    return row;
+}
+/** Heartbeat: extend the lease while the claimed execution is still running. */
+export async function renewSandboxExecutionLease(id, claimToken, leaseMs, now = Date.now()) {
+    await ensureTable();
+    const client = getDbExec();
+    const result = await client.execute({
+        sql: `UPDATE ${TABLE}
+      SET lease_expires_at = ?, updated_at = ?
+      WHERE id = ? AND claim_token = ? AND status = 'running'`,
+        args: [now + leaseMs, now, id, claimToken],
+    });
+    return (result.rowsAffected ?? 0) === 1;
+}
+/**
+ * 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 async function finalizeSandboxExecution(id, claimToken, input, now = Date.now()) {
+    await ensureTable();
+    const client = getDbExec();
+    const row = await getSandboxExecutionInternal(id);
+    if (!row)
+        return false;
+    const stdout = capOutput(input.stdout, row.maxOutputChars);
+    const stderr = capOutput(input.stderr, row.maxOutputChars);
+    const result = await client.execute({
+        sql: `UPDATE ${TABLE}
+      SET status = ?,
+          stdout = ?,
+          stderr = ?,
+          stdout_truncated = ?,
+          stderr_truncated = ?,
+          exit_code = ?,
+          timed_out = ?,
+          error = ?,
+          bridge_tools_used = ?,
+          finished_at = ?,
+          updated_at = ?,
+          lease_expires_at = NULL
+      WHERE id = ? AND claim_token = ? AND status = 'running'`,
+        args: [
+            input.status,
+            stdout.text,
+            stderr.text,
+            stdout.truncated ? 1 : 0,
+            stderr.truncated ? 1 : 0,
+            input.exitCode ?? null,
+            input.timedOut ? 1 : 0,
+            input.error ?? null,
+            JSON.stringify(input.bridgeToolsUsed ?? []),
+            now,
+            now,
+            id,
+            claimToken,
+        ],
+    });
+    return (result.rowsAffected ?? 0) === 1;
+}
+/**
+ * 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 async function failExpiredSandboxExecution(id, error, now = Date.now()) {
+    await ensureTable();
+    const client = getDbExec();
+    const result = await client.execute({
+        sql: `UPDATE ${TABLE}
+      SET status = 'failed',
+          error = ?,
+          finished_at = ?,
+          updated_at = ?,
+          lease_expires_at = NULL
+      WHERE id = ?
+        AND status = 'running'
+        AND lease_expires_at IS NOT NULL AND lease_expires_at < ?
+        AND attempt_count >= max_attempts`,
+        args: [error, now, now, id, now],
+    });
+    return (result.rowsAffected ?? 0) === 1;
+}
+/**
+ * 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 async function listDueSandboxExecutions(options) {
+    const client = getDbExec();
+    const now = options.now ?? Date.now();
+    const limit = Math.max(1, Math.min(options.limit ?? 5, 25));
+    const queuedCutoff = now - Math.max(0, options.queuedOlderThanMs ?? 30_000);
+    const result = await client.execute({
+        sql: `SELECT id, status, attempt_count, max_attempts, lease_expires_at
+      FROM ${TABLE}
+      WHERE (status = 'queued' AND updated_at < ?)
+         OR (status = 'running' AND lease_expires_at IS NOT NULL AND lease_expires_at < ?)
+      ORDER BY created_at ASC
+      LIMIT ?`,
+        args: [queuedCutoff, now, limit],
+    });
+    return (result.rows ?? []).map((raw) => ({
+        id: String(raw.id),
+        status: String(raw.status),
+        attemptCount: toNumberOrNull(raw.attempt_count) ?? 0,
+        maxAttempts: toNumberOrNull(raw.max_attempts) ??
+            SANDBOX_EXECUTION_DEFAULT_MAX_ATTEMPTS,
+        leaseExpiresAt: toNumberOrNull(raw.lease_expires_at),
+    }));
+}
+//# sourceMappingURL=executions-store.js.map

package/dist/coding-tools/sandbox/executions-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executions-store.js","sourceRoot":"","sources":["../../../src/coding-tools/sandbox/executions-store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Durable storage for queued `run-code` sandbox executions.\n *\n * A row in `sandbox_executions` is one background code-execution request: the\n * raw user code plus enough identity (owner email, org, thread) to rebuild the\n * action bridge context in a fresh process, and the full result once an\n * executor finishes. This is what lets a long compute job survive the hosted\n * serverless wall: the enqueueing request returns immediately, and any later\n * invocation (self-dispatch processor, status poll, warm-instance sweep) can\n * claim and run the row under its own budget.\n *\n * Concurrency model (single-writer via claim token + lease):\n *  - `claimSandboxExecution` atomically flips `queued → running` (or reclaims\n *    a `running` row whose lease expired) with `UPDATE … WHERE status = …`\n *    guards, so exactly one executor wins even when several invocations race.\n *  - The winning executor holds a random `claim_token` and heartbeats\n *    `lease_expires_at`; `finalizeSandboxExecution` only writes results when\n *    the token still matches, so a displaced executor can never clobber the\n *    reclaimer's result.\n *  - A row whose lease expired with attempts remaining is re-claimable; once\n *    attempts are exhausted `failExpiredSandboxExecution` marks it `failed`\n *    instead of leaving it \"running\" forever.\n *\n * Schema notes: additive-only, portable across Postgres (Neon) and SQLite —\n * same `ensureTableExists`/dialect-branched DDL pattern as\n * `resources/store.ts`. Timestamps are epoch-ms in `BIGINT`/`INTEGER` columns.\n * Reads for user-facing surfaces are always owner-scoped\n * (`getSandboxExecutionForOwner`); the unscoped internal reader exists only\n * for the trusted executor/sweep paths.\n */\n\nimport crypto from \"node:crypto\";\n\nimport {\n  getDbExec,\n  intType,\n  isPostgres,\n  retryOnDdlRace,\n} from \"../../db/client.js\";\nimport {\n  ensureColumnExists,\n  ensureIndexExists,\n  ensureTableExists,\n} from \"../../db/ddl-guard.js\";\n\nexport type SandboxExecutionStatus =\n  | \"queued\"\n  | \"running\"\n  | \"succeeded\"\n  | \"failed\"\n  | \"timed_out\";\n\nexport interface SandboxExecutionRow {\n  id: string;\n  owner: string;\n  orgId: string | null;\n  threadId: string | null;\n  runtime: string;\n  code: string;\n  status: SandboxExecutionStatus;\n  timeoutMs: number;\n  maxOutputChars: number;\n  attemptCount: number;\n  maxAttempts: number;\n  claimToken: string | null;\n  leaseExpiresAt: number | null;\n  stdout: string;\n  stderr: string;\n  stdoutTruncated: boolean;\n  stderrTruncated: boolean;\n  exitCode: number | null;\n  timedOut: boolean;\n  error: string | null;\n  bridgeToolsUsed: string[];\n  createdAt: number;\n  startedAt: number | null;\n  finishedAt: number | null;\n  updatedAt: number;\n}\n\nexport interface CreateSandboxExecutionInput {\n  owner: string;\n  orgId?: string | null;\n  threadId?: string | null;\n  code: string;\n  timeoutMs: number;\n  maxOutputChars: number;\n  maxAttempts?: number;\n  runtime?: string;\n}\n\nexport interface FinalizeSandboxExecutionInput {\n  status: Extract<SandboxExecutionStatus, \"succeeded\" | \"failed\" | \"timed_out\">;\n  stdout?: string;\n  stderr?: string;\n  exitCode?: number | null;\n  timedOut?: boolean;\n  error?: string | null;\n  bridgeToolsUsed?: string[];\n}\n\n/** Default retry budget: the initial attempt plus one lease-expiry retry. */\nexport const SANDBOX_EXECUTION_DEFAULT_MAX_ATTEMPTS = 2;\n/**\n * Hard per-stream storage cap. The per-row `max_output_chars` (derived from\n * the caller's `maxOutputChars`) is applied first; this bounds even that.\n */\nexport const SANDBOX_EXECUTION_MAX_STORED_OUTPUT_CHARS = 200_000;\n\nconst TABLE = \"sandbox_executions\";\n\nlet _initPromise: Promise<void> | undefined;\n\nasync function ensureTable(): Promise<void> {\n  if (!_initPromise) {\n    _initPromise = _doEnsureTable().catch((err) => {\n      // Don't cache the rejection — let the next caller retry a fresh init.\n      _initPromise = undefined;\n      throw err;\n    });\n  }\n  return _initPromise;\n}\n\n/** Test-only: forget the memoized init so a fresh in-memory DB re-creates. */\nexport function resetSandboxExecutionsStoreForTests(): void {\n  _initPromise = undefined;\n}\n\nasync function _doEnsureTable(): Promise<void> {\n  const client = getDbExec();\n  const createSql = `\n    CREATE TABLE IF NOT EXISTS ${TABLE} (\n      id TEXT PRIMARY KEY,\n      owner TEXT NOT NULL,\n      org_id TEXT,\n      thread_id TEXT,\n      runtime TEXT NOT NULL DEFAULT 'node',\n      code TEXT NOT NULL,\n      status TEXT NOT NULL DEFAULT 'queued',\n      timeout_ms ${intType()} NOT NULL,\n      max_output_chars ${intType()} NOT NULL,\n      attempt_count ${intType()} NOT NULL DEFAULT 0,\n      max_attempts ${intType()} NOT NULL DEFAULT ${SANDBOX_EXECUTION_DEFAULT_MAX_ATTEMPTS},\n      claim_token TEXT,\n      lease_expires_at ${intType()},\n      stdout TEXT NOT NULL DEFAULT '',\n      stderr TEXT NOT NULL DEFAULT '',\n      stdout_truncated ${intType()} NOT NULL DEFAULT 0,\n      stderr_truncated ${intType()} NOT NULL DEFAULT 0,\n      exit_code ${intType()},\n      timed_out ${intType()} NOT NULL DEFAULT 0,\n      error TEXT,\n      bridge_tools_used TEXT,\n      created_at ${intType()} NOT NULL,\n      started_at ${intType()},\n      finished_at ${intType()},\n      updated_at ${intType()} NOT NULL\n    )\n  `;\n  const ownerIdxSql = `CREATE INDEX IF NOT EXISTS sandbox_executions_owner_created_idx ON ${TABLE} (owner, created_at)`;\n  const dueIdxSql = `CREATE INDEX IF NOT EXISTS sandbox_executions_due_idx ON ${TABLE} (status, lease_expires_at)`;\n\n  if (isPostgres()) {\n    // Probe information_schema first (no lock) and DDL only what's missing —\n    // same guarded pattern as resources/store.ts so a fresh background worker\n    // never blocks on an ACCESS EXCLUSIVE lock for schema that already exists.\n    await ensureTableExists(TABLE, createSql);\n    // Additive-column guard: keeps older deployments (created before a column\n    // was added) self-healing without destructive migrations.\n    const pgColumns: Array<[string, string]> = [[\"bridge_tools_used\", \"TEXT\"]];\n    for (const [col, def] of pgColumns) {\n      await ensureColumnExists(\n        TABLE,\n        col,\n        `ALTER TABLE ${TABLE} ADD COLUMN IF NOT EXISTS ${col} ${def}`,\n      );\n    }\n    await ensureIndexExists(\n      \"sandbox_executions_owner_created_idx\",\n      ownerIdxSql,\n    );\n    await ensureIndexExists(\"sandbox_executions_due_idx\", dueIdxSql);\n  } else {\n    await retryOnDdlRace(() => client.execute(createSql));\n    await retryOnDdlRace(() => client.execute(ownerIdxSql));\n    await retryOnDdlRace(() => client.execute(dueIdxSql));\n  }\n}\n\nfunction capOutput(\n  value: string | undefined,\n  maxChars: number,\n): { text: string; truncated: boolean } {\n  const raw = typeof value === \"string\" ? value : \"\";\n  const cap = Math.max(\n    1,\n    Math.min(maxChars, SANDBOX_EXECUTION_MAX_STORED_OUTPUT_CHARS),\n  );\n  if (raw.length <= cap) return { text: raw, truncated: false };\n  return { text: raw.slice(0, cap), truncated: true };\n}\n\nfunction toBool(value: unknown): boolean {\n  return value === true || value === 1 || value === \"1\" || value === \"true\";\n}\n\nfunction toNumberOrNull(value: unknown): number | null {\n  if (value === null || value === undefined || value === \"\") return null;\n  const parsed = Number(value);\n  return Number.isFinite(parsed) ? parsed : null;\n}\n\nfunction rowFromDb(raw: Record<string, unknown>): SandboxExecutionRow {\n  let bridgeToolsUsed: string[] = [];\n  if (typeof raw.bridge_tools_used === \"string\" && raw.bridge_tools_used) {\n    try {\n      const parsed = JSON.parse(raw.bridge_tools_used);\n      if (Array.isArray(parsed)) {\n        bridgeToolsUsed = parsed.filter(\n          (item): item is string => typeof item === \"string\",\n        );\n      }\n    } catch {\n      bridgeToolsUsed = [];\n    }\n  }\n  return {\n    id: String(raw.id),\n    owner: String(raw.owner),\n    orgId:\n      raw.org_id === null || raw.org_id === undefined\n        ? null\n        : String(raw.org_id),\n    threadId:\n      raw.thread_id === null || raw.thread_id === undefined\n        ? null\n        : String(raw.thread_id),\n    runtime: String(raw.runtime ?? \"node\"),\n    code: String(raw.code ?? \"\"),\n    status: String(raw.status ?? \"queued\") as SandboxExecutionStatus,\n    timeoutMs: toNumberOrNull(raw.timeout_ms) ?? 0,\n    maxOutputChars: toNumberOrNull(raw.max_output_chars) ?? 0,\n    attemptCount: toNumberOrNull(raw.attempt_count) ?? 0,\n    maxAttempts:\n      toNumberOrNull(raw.max_attempts) ??\n      SANDBOX_EXECUTION_DEFAULT_MAX_ATTEMPTS,\n    claimToken:\n      raw.claim_token === null || raw.claim_token === undefined\n        ? null\n        : String(raw.claim_token),\n    leaseExpiresAt: toNumberOrNull(raw.lease_expires_at),\n    stdout: String(raw.stdout ?? \"\"),\n    stderr: String(raw.stderr ?? \"\"),\n    stdoutTruncated: toBool(raw.stdout_truncated),\n    stderrTruncated: toBool(raw.stderr_truncated),\n    exitCode: toNumberOrNull(raw.exit_code),\n    timedOut: toBool(raw.timed_out),\n    error:\n      raw.error === null || raw.error === undefined ? null : String(raw.error),\n    bridgeToolsUsed,\n    createdAt: toNumberOrNull(raw.created_at) ?? 0,\n    startedAt: toNumberOrNull(raw.started_at),\n    finishedAt: toNumberOrNull(raw.finished_at),\n    updatedAt: toNumberOrNull(raw.updated_at) ?? 0,\n  };\n}\n\n/** Enqueue a new execution row in `queued` state. */\nexport async function createSandboxExecution(\n  input: CreateSandboxExecutionInput,\n): Promise<SandboxExecutionRow> {\n  await ensureTable();\n  const client = getDbExec();\n  const now = Date.now();\n  const id = `sbx_${crypto.randomUUID()}`;\n  const maxAttempts = Math.max(\n    1,\n    Math.min(input.maxAttempts ?? SANDBOX_EXECUTION_DEFAULT_MAX_ATTEMPTS, 5),\n  );\n  await client.execute({\n    sql: `INSERT INTO ${TABLE}\n      (id, owner, org_id, thread_id, runtime, code, status, timeout_ms, max_output_chars, attempt_count, max_attempts, created_at, updated_at)\n      VALUES (?, ?, ?, ?, ?, ?, 'queued', ?, ?, 0, ?, ?, ?)`,\n    args: [\n      id,\n      input.owner,\n      input.orgId ?? null,\n      input.threadId ?? null,\n      input.runtime ?? \"node\",\n      input.code,\n      input.timeoutMs,\n      input.maxOutputChars,\n      maxAttempts,\n      now,\n      now,\n    ],\n  });\n  const row = await getSandboxExecutionInternal(id);\n  if (!row) throw new Error(`sandbox execution ${id} vanished after insert`);\n  return row;\n}\n\n/** Owner-scoped read for user-facing status/result surfaces. */\nexport async function getSandboxExecutionForOwner(\n  id: string,\n  owner: string,\n): Promise<SandboxExecutionRow | null> {\n  if (!id || !owner) return null;\n  await ensureTable();\n  const client = getDbExec();\n  const result = await client.execute({\n    sql: `SELECT * FROM ${TABLE} WHERE id = ? AND owner = ? LIMIT 1`,\n    args: [id, owner],\n  });\n  const raw = result.rows?.[0] as Record<string, unknown> | undefined;\n  return raw ? rowFromDb(raw) : null;\n}\n\n/**\n * Unscoped read for the trusted executor/sweep paths ONLY. Never expose this\n * through a user-facing action — use `getSandboxExecutionForOwner`.\n */\nexport async function getSandboxExecutionInternal(\n  id: string,\n): Promise<SandboxExecutionRow | null> {\n  if (!id) return null;\n  await ensureTable();\n  const client = getDbExec();\n  const result = await client.execute({\n    sql: `SELECT * FROM ${TABLE} WHERE id = ? LIMIT 1`,\n    args: [id],\n  });\n  const raw = result.rows?.[0] as Record<string, unknown> | undefined;\n  return raw ? rowFromDb(raw) : null;\n}\n\n/**\n * Atomically claim an execution for a single executor. Claims a `queued` row,\n * or reclaims a `running` row whose lease expired, as long as the attempt\n * budget is not exhausted. Returns the claimed row (with the new claim token)\n * or null when another executor holds it / it is terminal / attempts ran out.\n */\nexport async function claimSandboxExecution(\n  id: string,\n  claimToken: string,\n  leaseMs: number,\n  now = Date.now(),\n): Promise<SandboxExecutionRow | null> {\n  await ensureTable();\n  const client = getDbExec();\n  const result = await client.execute({\n    sql: `UPDATE ${TABLE}\n      SET status = 'running',\n          claim_token = ?,\n          lease_expires_at = ?,\n          attempt_count = attempt_count + 1,\n          started_at = COALESCE(started_at, ?),\n          updated_at = ?\n      WHERE id = ?\n        AND attempt_count < max_attempts\n        AND (\n          status = 'queued'\n          OR (status = 'running' AND lease_expires_at IS NOT NULL AND lease_expires_at < ?)\n        )`,\n    args: [claimToken, now + leaseMs, now, now, id, now],\n  });\n  if ((result.rowsAffected ?? 0) !== 1) return null;\n  const row = await getSandboxExecutionInternal(id);\n  // Verify the claim token survived (paranoia against a same-ms racing UPDATE\n  // on drivers that report affected rows loosely).\n  if (!row || row.claimToken !== claimToken) return null;\n  return row;\n}\n\n/** Heartbeat: extend the lease while the claimed execution is still running. */\nexport async function renewSandboxExecutionLease(\n  id: string,\n  claimToken: string,\n  leaseMs: number,\n  now = Date.now(),\n): Promise<boolean> {\n  await ensureTable();\n  const client = getDbExec();\n  const result = await client.execute({\n    sql: `UPDATE ${TABLE}\n      SET lease_expires_at = ?, updated_at = ?\n      WHERE id = ? AND claim_token = ? AND status = 'running'`,\n    args: [now + leaseMs, now, id, claimToken],\n  });\n  return (result.rowsAffected ?? 0) === 1;\n}\n\n/**\n * Write the terminal result. Single-writer safe: only the executor whose\n * claim token still matches the row (i.e. it was not reclaimed after a lease\n * expiry) can finalize. Returns false when the row was already finalized or\n * reclaimed — the caller must discard its result.\n */\nexport async function finalizeSandboxExecution(\n  id: string,\n  claimToken: string,\n  input: FinalizeSandboxExecutionInput,\n  now = Date.now(),\n): Promise<boolean> {\n  await ensureTable();\n  const client = getDbExec();\n  const row = await getSandboxExecutionInternal(id);\n  if (!row) return false;\n  const stdout = capOutput(input.stdout, row.maxOutputChars);\n  const stderr = capOutput(input.stderr, row.maxOutputChars);\n  const result = await client.execute({\n    sql: `UPDATE ${TABLE}\n      SET status = ?,\n          stdout = ?,\n          stderr = ?,\n          stdout_truncated = ?,\n          stderr_truncated = ?,\n          exit_code = ?,\n          timed_out = ?,\n          error = ?,\n          bridge_tools_used = ?,\n          finished_at = ?,\n          updated_at = ?,\n          lease_expires_at = NULL\n      WHERE id = ? AND claim_token = ? AND status = 'running'`,\n    args: [\n      input.status,\n      stdout.text,\n      stderr.text,\n      stdout.truncated ? 1 : 0,\n      stderr.truncated ? 1 : 0,\n      input.exitCode ?? null,\n      input.timedOut ? 1 : 0,\n      input.error ?? null,\n      JSON.stringify(input.bridgeToolsUsed ?? []),\n      now,\n      now,\n      id,\n      claimToken,\n    ],\n  });\n  return (result.rowsAffected ?? 0) === 1;\n}\n\n/**\n * Reap a `running` row whose lease expired after its attempt budget was\n * exhausted, so it never sits \"running\" forever. Atomic: guarded on the same\n * expiry + budget conditions, so a live executor (fresh lease) is untouched.\n */\nexport async function failExpiredSandboxExecution(\n  id: string,\n  error: string,\n  now = Date.now(),\n): Promise<boolean> {\n  await ensureTable();\n  const client = getDbExec();\n  const result = await client.execute({\n    sql: `UPDATE ${TABLE}\n      SET status = 'failed',\n          error = ?,\n          finished_at = ?,\n          updated_at = ?,\n          lease_expires_at = NULL\n      WHERE id = ?\n        AND status = 'running'\n        AND lease_expires_at IS NOT NULL AND lease_expires_at < ?\n        AND attempt_count >= max_attempts`,\n    args: [error, now, now, id, now],\n  });\n  return (result.rowsAffected ?? 0) === 1;\n}\n\nexport interface DueSandboxExecution {\n  id: string;\n  status: SandboxExecutionStatus;\n  attemptCount: number;\n  maxAttempts: number;\n  leaseExpiresAt: number | null;\n}\n\n/**\n * List rows that need driving: `queued` rows that have sat unclaimed longer\n * than `queuedOlderThanMs` (their enqueue-time dispatch was likely lost), and\n * `running` rows whose lease expired (executor died). Used by the sweep and\n * the poll-time drain. Deliberately does NOT call `ensureTable()` — the sweep\n * must stay a zero-footprint no-op on deployments that never enqueue; callers\n * treat a missing-table error as \"nothing due\".\n */\nexport async function listDueSandboxExecutions(options: {\n  limit?: number;\n  queuedOlderThanMs?: number;\n  now?: number;\n}): Promise<DueSandboxExecution[]> {\n  const client = getDbExec();\n  const now = options.now ?? Date.now();\n  const limit = Math.max(1, Math.min(options.limit ?? 5, 25));\n  const queuedCutoff = now - Math.max(0, options.queuedOlderThanMs ?? 30_000);\n  const result = await client.execute({\n    sql: `SELECT id, status, attempt_count, max_attempts, lease_expires_at\n      FROM ${TABLE}\n      WHERE (status = 'queued' AND updated_at < ?)\n         OR (status = 'running' AND lease_expires_at IS NOT NULL AND lease_expires_at < ?)\n      ORDER BY created_at ASC\n      LIMIT ?`,\n    args: [queuedCutoff, now, limit],\n  });\n  return (result.rows ?? []).map((raw: Record<string, unknown>) => ({\n    id: String(raw.id),\n    status: String(raw.status) as SandboxExecutionStatus,\n    attemptCount: toNumberOrNull(raw.attempt_count) ?? 0,\n    maxAttempts:\n      toNumberOrNull(raw.max_attempts) ??\n      SANDBOX_EXECUTION_DEFAULT_MAX_ATTEMPTS,\n    leaseExpiresAt: toNumberOrNull(raw.lease_expires_at),\n  }));\n}\n"]}

package/dist/coding-tools/sandbox/index.d.ts

@@ -9,27 +9,28 @@
  *
  *  1. Programmatically, via `registerSandboxAdapter(adapter)` — e.g. a host
  *     process that wants every `run-code` call to run in a remote container.
- *  2. By env var `AGENT_NATIVE_SANDBOX` for built-in adapters. Currently only
- *     `local` (the default) is wired; unknown values fall back to local.
+ *  2. By env var `AGENT_NATIVE_SANDBOX` for built-in adapters: `local` (the
+ *     default) and `background` (the durable queued backend — every `run-code`
+ *     call is enqueued to `sandbox_executions` and executed out-of-request;
+ *     see `./background.ts`). Unknown values fall back to local.
  *
  * Resolution order: an explicitly registered adapter wins; otherwise the env
  * var selects a built-in; otherwise the local adapter is used.
  *
- * // TODO: remote/durable adapter for long jobs. The local child-process
- * // adapter is bounded by the hosting process — on the hosted platform that
- * // means the agent loop's soft execution ceiling (~40s before timeout/
- * // continuation thrash). A remote or durable adapter (Docker, a
- * // Vercel-Sandbox-style runner, or a queued background worker) is the lever
- * // to exceed that ceiling: it would implement `SandboxAdapter.run` against an
- * // out-of-process runtime, tunnel the loopback bridge (or proxy bridge calls
- * // back to the parent), and let large data jobs run to completion
- * // independently of the request lifecycle. Register it here under a new
- * // `AGENT_NATIVE_SANDBOX` value (e.g. `remote`) and via
- * // `registerSandboxAdapter()`.
+ * The `background` adapter is a QUEUE MARKER, not an executor: `run-code`
+ * detects it via `isQueuedSandboxAdapter()` and enqueues the raw code instead
+ * of preparing a module (a prepared module embeds the enqueueing request's
+ * loopback bridge, which dies with that request). The queued work is later
+ * executed through `resolveExecutionSandboxAdapter()` — the active adapter
+ * unless that adapter is itself queued, in which case the local child process
+ * — so a host-registered Docker/remote adapter is still honored for the
+ * actual execution.
  */
 import type { SandboxAdapter } from "./adapter.js";
 export type { SandboxAdapter, SandboxRunRequest, SandboxRunResult, SandboxEnv, } from "./adapter.js";
 export { LocalChildProcessAdapter } from "./local-child-process-adapter.js";
+export { BackgroundQueueAdapter, isQueuedSandboxAdapter, registerSandboxExecutionRunner, resetSandboxBackgroundForTests, enqueueSandboxExecution, driveSandboxExecution, processQueuedSandboxExecution, drainDueSandboxExecutions, SANDBOX_PROCESS_EXECUTION_PATH, SANDBOX_EXECUTION_REDRIVE_AFTER_MS, BACKGROUND_DEFAULT_TIMEOUT_MS, BACKGROUND_MAX_TIMEOUT_MS, type SandboxExecutionRunner, type SandboxExecutionRunInput, type SandboxExecutionRunOutput, } from "./background.js";
+export { getSandboxExecutionForOwner, type SandboxExecutionRow, type SandboxExecutionStatus, } from "./executions-store.js";
 /**
  * Override the sandbox backend for all subsequent `run-code` invocations.
  * Intended for hosts that want to plug in a Docker/remote/durable adapter. Pass
@@ -43,6 +44,14 @@ export declare function registerSandboxAdapter(adapter: SandboxAdapter | null):
  * `AGENT_NATIVE_SANDBOX` → local child-process default.
  */
 export declare function getSandboxAdapter(): SandboxAdapter;
+/**
+ * Resolve the adapter to use for ACTUALLY EXECUTING a prepared sandbox module.
+ * Identical to `getSandboxAdapter()` except a queued (background) adapter is
+ * replaced by the local child-process default — the background executor and
+ * the foreground fallback both call this so they can never recurse back into
+ * the queue.
+ */
+export declare function resolveExecutionSandboxAdapter(): SandboxAdapter;
 /**
  * Reset selection state (registered override + cached default). Test-only helper
  * so specs can exercise selection without leaking adapters across cases.

package/dist/coding-tools/sandbox/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/coding-tools/sandbox/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAa5E;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAE3E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAelD;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAGlD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/coding-tools/sandbox/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAOnD,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,8BAA8B,EAC9B,8BAA8B,EAC9B,uBAAuB,EACvB,qBAAqB,EACrB,6BAA6B,EAC7B,yBAAyB,EACzB,8BAA8B,EAC9B,kCAAkC,EAClC,6BAA6B,EAC7B,yBAAyB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,2BAA2B,EAC3B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC;AAc/B;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAE3E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAelD;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,IAAI,cAAc,CAK/D;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAGlD"}

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

@@ -9,29 +9,32 @@
  *
  *  1. Programmatically, via `registerSandboxAdapter(adapter)` — e.g. a host
  *     process that wants every `run-code` call to run in a remote container.
- *  2. By env var `AGENT_NATIVE_SANDBOX` for built-in adapters. Currently only
- *     `local` (the default) is wired; unknown values fall back to local.
+ *  2. By env var `AGENT_NATIVE_SANDBOX` for built-in adapters: `local` (the
+ *     default) and `background` (the durable queued backend — every `run-code`
+ *     call is enqueued to `sandbox_executions` and executed out-of-request;
+ *     see `./background.ts`). Unknown values fall back to local.
  *
  * Resolution order: an explicitly registered adapter wins; otherwise the env
  * var selects a built-in; otherwise the local adapter is used.
  *
- * // TODO: remote/durable adapter for long jobs. The local child-process
- * // adapter is bounded by the hosting process — on the hosted platform that
- * // means the agent loop's soft execution ceiling (~40s before timeout/
- * // continuation thrash). A remote or durable adapter (Docker, a
- * // Vercel-Sandbox-style runner, or a queued background worker) is the lever
- * // to exceed that ceiling: it would implement `SandboxAdapter.run` against an
- * // out-of-process runtime, tunnel the loopback bridge (or proxy bridge calls
- * // back to the parent), and let large data jobs run to completion
- * // independently of the request lifecycle. Register it here under a new
- * // `AGENT_NATIVE_SANDBOX` value (e.g. `remote`) and via
- * // `registerSandboxAdapter()`.
+ * The `background` adapter is a QUEUE MARKER, not an executor: `run-code`
+ * detects it via `isQueuedSandboxAdapter()` and enqueues the raw code instead
+ * of preparing a module (a prepared module embeds the enqueueing request's
+ * loopback bridge, which dies with that request). The queued work is later
+ * executed through `resolveExecutionSandboxAdapter()` — the active adapter
+ * unless that adapter is itself queued, in which case the local child process
+ * — so a host-registered Docker/remote adapter is still honored for the
+ * actual execution.
  */
+import { BackgroundQueueAdapter, isQueuedSandboxAdapter, } from "./background.js";
 import { LocalChildProcessAdapter } from "./local-child-process-adapter.js";
 export { LocalChildProcessAdapter } from "./local-child-process-adapter.js";
+export { BackgroundQueueAdapter, isQueuedSandboxAdapter, registerSandboxExecutionRunner, resetSandboxBackgroundForTests, enqueueSandboxExecution, driveSandboxExecution, processQueuedSandboxExecution, drainDueSandboxExecutions, SANDBOX_PROCESS_EXECUTION_PATH, SANDBOX_EXECUTION_REDRIVE_AFTER_MS, BACKGROUND_DEFAULT_TIMEOUT_MS, BACKGROUND_MAX_TIMEOUT_MS, } from "./background.js";
+export { getSandboxExecutionForOwner, } from "./executions-store.js";
 /** Built-in adapter ids selectable via the `AGENT_NATIVE_SANDBOX` env var. */
 const BUILT_IN_ADAPTERS = {
     local: () => new LocalChildProcessAdapter(),
+    background: () => new BackgroundQueueAdapter(),
 };
 /** Lazily-constructed default (local) adapter, shared across calls. */
 let defaultAdapter;
@@ -68,6 +71,21 @@ export function getSandboxAdapter() {
         defaultAdapter = new LocalChildProcessAdapter();
     return defaultAdapter;
 }
+/**
+ * Resolve the adapter to use for ACTUALLY EXECUTING a prepared sandbox module.
+ * Identical to `getSandboxAdapter()` except a queued (background) adapter is
+ * replaced by the local child-process default — the background executor and
+ * the foreground fallback both call this so they can never recurse back into
+ * the queue.
+ */
+export function resolveExecutionSandboxAdapter() {
+    const adapter = getSandboxAdapter();
+    if (!isQueuedSandboxAdapter(adapter))
+        return adapter;
+    if (!defaultAdapter)
+        defaultAdapter = new LocalChildProcessAdapter();
+    return defaultAdapter;
+}
 /**
  * Reset selection state (registered override + cached default). Test-only helper
  * so specs can exercise selection without leaking adapters across cases.

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/coding-tools/sandbox/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAQ5E,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAE5E,8EAA8E;AAC9E,MAAM,iBAAiB,GAAyC;IAC9D,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,wBAAwB,EAAE;CAC5C,CAAC;AAEF,uEAAuE;AACvE,IAAI,cAA0C,CAAC;AAE/C,gFAAgF;AAChF,IAAI,iBAA6C,CAAC;AAElD;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAA8B;IACnE,iBAAiB,GAAG,OAAO,IAAI,SAAS,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,iBAAiB;QAAE,OAAO,iBAAiB,CAAC;IAEhD,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,EAAE,CAAC;SACtD,IAAI,EAAE;SACN,WAAW,EAAE,CAAC;IACjB,IAAI,QAAQ,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACrC,MAAM,OAAO,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,OAAO;YAAE,OAAO,OAAO,EAAE,CAAC;QAC9B,2EAA2E;QAC3E,8EAA8E;IAChF,CAAC;IAED,IAAI,CAAC,cAAc;QAAE,cAAc,GAAG,IAAI,wBAAwB,EAAE,CAAC;IACrE,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,2BAA2B;IACzC,iBAAiB,GAAG,SAAS,CAAC;IAC9B,cAAc,GAAG,SAAS,CAAC;AAC7B,CAAC","sourcesContent":["/**\n * Sandbox-adapter selection seam.\n *\n * `getSandboxAdapter()` resolves which backend the `run-code` tool executes in.\n * By default it returns the local child-process adapter (preserving today's\n * behavior). The active adapter can be overridden in two ways, both designed so\n * a remote/durable backend can be plugged in later WITHOUT touching the agent\n * loop or `run-code.ts`:\n *\n *  1. Programmatically, via `registerSandboxAdapter(adapter)` — e.g. a host\n *     process that wants every `run-code` call to run in a remote container.\n *  2. By env var `AGENT_NATIVE_SANDBOX` for built-in adapters. Currently only\n *     `local` (the default) is wired; unknown values fall back to local.\n *\n * Resolution order: an explicitly registered adapter wins; otherwise the env\n * var selects a built-in; otherwise the local adapter is used.\n *\n * // TODO: remote/durable adapter for long jobs. The local child-process\n * // adapter is bounded by the hosting process — on the hosted platform that\n * // means the agent loop's soft execution ceiling (~40s before timeout/\n * // continuation thrash). A remote or durable adapter (Docker, a\n * // Vercel-Sandbox-style runner, or a queued background worker) is the lever\n * // to exceed that ceiling: it would implement `SandboxAdapter.run` against an\n * // out-of-process runtime, tunnel the loopback bridge (or proxy bridge calls\n * // back to the parent), and let large data jobs run to completion\n * // independently of the request lifecycle. Register it here under a new\n * // `AGENT_NATIVE_SANDBOX` value (e.g. `remote`) and via\n * // `registerSandboxAdapter()`.\n */\n\nimport type { SandboxAdapter } from \"./adapter.js\";\nimport { LocalChildProcessAdapter } from \"./local-child-process-adapter.js\";\n\nexport type {\n  SandboxAdapter,\n  SandboxRunRequest,\n  SandboxRunResult,\n  SandboxEnv,\n} from \"./adapter.js\";\nexport { LocalChildProcessAdapter } from \"./local-child-process-adapter.js\";\n\n/** Built-in adapter ids selectable via the `AGENT_NATIVE_SANDBOX` env var. */\nconst BUILT_IN_ADAPTERS: Record<string, () => SandboxAdapter> = {\n  local: () => new LocalChildProcessAdapter(),\n};\n\n/** Lazily-constructed default (local) adapter, shared across calls. */\nlet defaultAdapter: SandboxAdapter | undefined;\n\n/** Explicitly registered adapter, if any. Takes precedence over the env var. */\nlet registeredAdapter: SandboxAdapter | undefined;\n\n/**\n * Override the sandbox backend for all subsequent `run-code` invocations.\n * Intended for hosts that want to plug in a Docker/remote/durable adapter. Pass\n * `null` to clear the override and fall back to env-var / default resolution.\n */\nexport function registerSandboxAdapter(adapter: SandboxAdapter | null): void {\n  registeredAdapter = adapter ?? undefined;\n}\n\n/**\n * Resolve the active sandbox adapter.\n *\n * Order: explicitly registered adapter → built-in selected by\n * `AGENT_NATIVE_SANDBOX` → local child-process default.\n */\nexport function getSandboxAdapter(): SandboxAdapter {\n  if (registeredAdapter) return registeredAdapter;\n\n  const selected = (process.env.AGENT_NATIVE_SANDBOX ?? \"\")\n    .trim()\n    .toLowerCase();\n  if (selected && selected !== \"local\") {\n    const factory = BUILT_IN_ADAPTERS[selected];\n    if (factory) return factory();\n    // Unknown value: fall through to the local default rather than failing the\n    // run. (A remote adapter is registered programmatically; see the TODO above.)\n  }\n\n  if (!defaultAdapter) defaultAdapter = new LocalChildProcessAdapter();\n  return defaultAdapter;\n}\n\n/**\n * Reset selection state (registered override + cached default). Test-only helper\n * so specs can exercise selection without leaking adapters across cases.\n */\nexport function resetSandboxAdapterForTests(): void {\n  registeredAdapter = undefined;\n  defaultAdapter = undefined;\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/coding-tools/sandbox/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EACL,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAQ5E,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,8BAA8B,EAC9B,8BAA8B,EAC9B,uBAAuB,EACvB,qBAAqB,EACrB,6BAA6B,EAC7B,yBAAyB,EACzB,8BAA8B,EAC9B,kCAAkC,EAClC,6BAA6B,EAC7B,yBAAyB,GAI1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,2BAA2B,GAG5B,MAAM,uBAAuB,CAAC;AAE/B,8EAA8E;AAC9E,MAAM,iBAAiB,GAAyC;IAC9D,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,wBAAwB,EAAE;IAC3C,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI,sBAAsB,EAAE;CAC/C,CAAC;AAEF,uEAAuE;AACvE,IAAI,cAA0C,CAAC;AAE/C,gFAAgF;AAChF,IAAI,iBAA6C,CAAC;AAElD;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAA8B;IACnE,iBAAiB,GAAG,OAAO,IAAI,SAAS,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,iBAAiB;QAAE,OAAO,iBAAiB,CAAC;IAEhD,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,EAAE,CAAC;SACtD,IAAI,EAAE;SACN,WAAW,EAAE,CAAC;IACjB,IAAI,QAAQ,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACrC,MAAM,OAAO,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,OAAO;YAAE,OAAO,OAAO,EAAE,CAAC;QAC9B,2EAA2E;QAC3E,8EAA8E;IAChF,CAAC;IAED,IAAI,CAAC,cAAc;QAAE,cAAc,GAAG,IAAI,wBAAwB,EAAE,CAAC;IACrE,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,8BAA8B;IAC5C,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;IACpC,IAAI,CAAC,sBAAsB,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IACrD,IAAI,CAAC,cAAc;QAAE,cAAc,GAAG,IAAI,wBAAwB,EAAE,CAAC;IACrE,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,2BAA2B;IACzC,iBAAiB,GAAG,SAAS,CAAC;IAC9B,cAAc,GAAG,SAAS,CAAC;AAC7B,CAAC","sourcesContent":["/**\n * Sandbox-adapter selection seam.\n *\n * `getSandboxAdapter()` resolves which backend the `run-code` tool executes in.\n * By default it returns the local child-process adapter (preserving today's\n * behavior). The active adapter can be overridden in two ways, both designed so\n * a remote/durable backend can be plugged in later WITHOUT touching the agent\n * loop or `run-code.ts`:\n *\n *  1. Programmatically, via `registerSandboxAdapter(adapter)` — e.g. a host\n *     process that wants every `run-code` call to run in a remote container.\n *  2. By env var `AGENT_NATIVE_SANDBOX` for built-in adapters: `local` (the\n *     default) and `background` (the durable queued backend — every `run-code`\n *     call is enqueued to `sandbox_executions` and executed out-of-request;\n *     see `./background.ts`). Unknown values fall back to local.\n *\n * Resolution order: an explicitly registered adapter wins; otherwise the env\n * var selects a built-in; otherwise the local adapter is used.\n *\n * The `background` adapter is a QUEUE MARKER, not an executor: `run-code`\n * detects it via `isQueuedSandboxAdapter()` and enqueues the raw code instead\n * of preparing a module (a prepared module embeds the enqueueing request's\n * loopback bridge, which dies with that request). The queued work is later\n * executed through `resolveExecutionSandboxAdapter()` — the active adapter\n * unless that adapter is itself queued, in which case the local child process\n * — so a host-registered Docker/remote adapter is still honored for the\n * actual execution.\n */\n\nimport type { SandboxAdapter } from \"./adapter.js\";\nimport {\n  BackgroundQueueAdapter,\n  isQueuedSandboxAdapter,\n} from \"./background.js\";\nimport { LocalChildProcessAdapter } from \"./local-child-process-adapter.js\";\n\nexport type {\n  SandboxAdapter,\n  SandboxRunRequest,\n  SandboxRunResult,\n  SandboxEnv,\n} from \"./adapter.js\";\nexport { LocalChildProcessAdapter } from \"./local-child-process-adapter.js\";\nexport {\n  BackgroundQueueAdapter,\n  isQueuedSandboxAdapter,\n  registerSandboxExecutionRunner,\n  resetSandboxBackgroundForTests,\n  enqueueSandboxExecution,\n  driveSandboxExecution,\n  processQueuedSandboxExecution,\n  drainDueSandboxExecutions,\n  SANDBOX_PROCESS_EXECUTION_PATH,\n  SANDBOX_EXECUTION_REDRIVE_AFTER_MS,\n  BACKGROUND_DEFAULT_TIMEOUT_MS,\n  BACKGROUND_MAX_TIMEOUT_MS,\n  type SandboxExecutionRunner,\n  type SandboxExecutionRunInput,\n  type SandboxExecutionRunOutput,\n} from \"./background.js\";\nexport {\n  getSandboxExecutionForOwner,\n  type SandboxExecutionRow,\n  type SandboxExecutionStatus,\n} from \"./executions-store.js\";\n\n/** Built-in adapter ids selectable via the `AGENT_NATIVE_SANDBOX` env var. */\nconst BUILT_IN_ADAPTERS: Record<string, () => SandboxAdapter> = {\n  local: () => new LocalChildProcessAdapter(),\n  background: () => new BackgroundQueueAdapter(),\n};\n\n/** Lazily-constructed default (local) adapter, shared across calls. */\nlet defaultAdapter: SandboxAdapter | undefined;\n\n/** Explicitly registered adapter, if any. Takes precedence over the env var. */\nlet registeredAdapter: SandboxAdapter | undefined;\n\n/**\n * Override the sandbox backend for all subsequent `run-code` invocations.\n * Intended for hosts that want to plug in a Docker/remote/durable adapter. Pass\n * `null` to clear the override and fall back to env-var / default resolution.\n */\nexport function registerSandboxAdapter(adapter: SandboxAdapter | null): void {\n  registeredAdapter = adapter ?? undefined;\n}\n\n/**\n * Resolve the active sandbox adapter.\n *\n * Order: explicitly registered adapter → built-in selected by\n * `AGENT_NATIVE_SANDBOX` → local child-process default.\n */\nexport function getSandboxAdapter(): SandboxAdapter {\n  if (registeredAdapter) return registeredAdapter;\n\n  const selected = (process.env.AGENT_NATIVE_SANDBOX ?? \"\")\n    .trim()\n    .toLowerCase();\n  if (selected && selected !== \"local\") {\n    const factory = BUILT_IN_ADAPTERS[selected];\n    if (factory) return factory();\n    // Unknown value: fall through to the local default rather than failing the\n    // run. (A remote adapter is registered programmatically; see the TODO above.)\n  }\n\n  if (!defaultAdapter) defaultAdapter = new LocalChildProcessAdapter();\n  return defaultAdapter;\n}\n\n/**\n * Resolve the adapter to use for ACTUALLY EXECUTING a prepared sandbox module.\n * Identical to `getSandboxAdapter()` except a queued (background) adapter is\n * replaced by the local child-process default — the background executor and\n * the foreground fallback both call this so they can never recurse back into\n * the queue.\n */\nexport function resolveExecutionSandboxAdapter(): SandboxAdapter {\n  const adapter = getSandboxAdapter();\n  if (!isQueuedSandboxAdapter(adapter)) return adapter;\n  if (!defaultAdapter) defaultAdapter = new LocalChildProcessAdapter();\n  return defaultAdapter;\n}\n\n/**\n * Reset selection state (registered override + cached default). Test-only helper\n * so specs can exercise selection without leaking adapters across cases.\n */\nexport function resetSandboxAdapterForTests(): void {\n  registeredAdapter = undefined;\n  defaultAdapter = undefined;\n}\n"]}

package/dist/coding-tools/sandbox/local-child-process-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-child-process-adapter.d.ts","sourceRoot":"","sources":["../../../src/coding-tools/sandbox/local-child-process-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,cAAc,CAAC;AAmDtB,gFAAgF;AAChF,qBAAa,wBAAyB,YAAW,cAAc;IAC7D,QAAQ,CAAC,EAAE,yBAAyB;IAE9B,GAAG,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA4E/D;CACF"}
+{"version":3,"file":"local-child-process-adapter.d.ts","sourceRoot":"","sources":["../../../src/coding-tools/sandbox/local-child-process-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,cAAc,CAAC;AAkEtB,gFAAgF;AAChF,qBAAa,wBAAyB,YAAW,cAAc;IAC7D,QAAQ,CAAC,EAAE,yBAAyB;IAE9B,GAAG,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAsH/D;CACF"}