@ekairos/sandbox 1.22.15-beta.feature-thread-unify.0 → 1.22.16-beta.development.0

package/dist/service.js

@@ -1,7 +1,33 @@
-import { Sandbox as VercelSandbox } from "@vercel/sandbox";
+import { Sandbox as VercelSandbox, Snapshot as VercelSnapshot } from "@vercel/sandbox";
 import { Daytona, Image } from "@daytonaio/sdk";
 import { id } from "@instantdb/admin";
+import { resolveRuntime } from "@ekairos/domain/runtime";
 import { runCommandInSandbox } from "./commands.js";
+import { resolveVercelSandboxConfig, safeVercelConfigForRecord, } from "./vercel-options.js";
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+function isVercelSandbox(sandbox) {
+    return Boolean(sandbox &&
+        typeof sandbox === "object" &&
+        typeof sandbox.runCommand === "function" &&
+        typeof sandbox.currentSession === "function" &&
+        typeof sandbox.name === "string" &&
+        sandbox.__provider !== "sprites");
+}
+const EKAIROS_ROOT_DIR = "/vercel/sandbox/.ekairos";
+const EKAIROS_RUNTIME_MANIFEST_PATH = `${EKAIROS_ROOT_DIR}/runtime.json`;
+const EKAIROS_HTTP_HELPER_PATH = `${EKAIROS_ROOT_DIR}/instant-http.mjs`;
+const EKAIROS_QUERY_SCRIPT_PATH = `${EKAIROS_ROOT_DIR}/query.mjs`;
+const CODEX_HOME_DIR = "/vercel/sandbox/.codex";
+const CODEX_SKILLS_DIR = `${CODEX_HOME_DIR}/skills`;
+const INSTANT_API_BASE_URL = "https://api.instantdb.com";
+const SANDBOX_PROCESS_STREAM_VERSION = 1;
+const SANDBOX_PROCESS_TERMINAL_STATUSES = new Set(["exited", "failed", "killed", "lost"]);
 function formatInstantSchemaError(err) {
     const base = err instanceof Error ? err.message : String(err);
     const body = err?.body;
@@ -25,6 +51,174 @@ function formatInstantSchemaError(err) {
     // Keep it short + copy/paste friendly for debugging schema issues.
     return base + " | missing attributes: " + uniq.join(", ");
 }
+function formatSandboxError(err) {
+    const base = err instanceof Error ? err.message : String(err);
+    const text = typeof err?.text === "string" ? err.text.trim() : "";
+    const json = err?.json ? JSON.stringify(err.json) : "";
+    const detail = text || json;
+    if (!detail)
+        return base;
+    return `${base}: ${detail}`;
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function asOptionalString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function sanitizeInstantString(value) {
+    return value.includes("\0") ? value.replace(/\0/g, "") : value;
+}
+function sanitizeInstantValue(value) {
+    if (typeof value === "string") {
+        return sanitizeInstantString(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeInstantValue(item));
+    }
+    if (value && typeof value === "object" && !(value instanceof Date)) {
+        const sanitized = {};
+        for (const [key, entry] of Object.entries(value)) {
+            sanitized[key] = sanitizeInstantValue(entry);
+        }
+        return sanitized;
+    }
+    return value;
+}
+function createSandboxProcessStreamClientId(processId) {
+    const normalized = String(processId ?? "").trim();
+    if (!normalized)
+        throw new Error("sandbox_process_id_required");
+    return `sandbox-process:${normalized}`;
+}
+function encodeSandboxProcessStreamChunk(chunk) {
+    return `${JSON.stringify(chunk)}\n`;
+}
+function parseSandboxProcessStreamChunk(value) {
+    const parsed = typeof value === "string" ? JSON.parse(value) : value;
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error("invalid_sandbox_process_stream_chunk");
+    }
+    const record = parsed;
+    if (record.version !== SANDBOX_PROCESS_STREAM_VERSION) {
+        throw new Error(`invalid_sandbox_process_stream_version:${String(record.version)}`);
+    }
+    return record;
+}
+function sandboxProcessFinishedHookToken(processId) {
+    return `sandbox-process:${processId}:finished`;
+}
+async function resumeSandboxProcessHook(processId, payload) {
+    try {
+        const { resumeHook } = await import("workflow/api");
+        await resumeHook(sandboxProcessFinishedHookToken(processId), payload);
+    }
+    catch {
+        // No workflow may be listening; process metadata and streams remain the source of truth.
+    }
+}
+function commandResultFromProcessStream(params) {
+    const stdout = params.chunks
+        .filter((chunk) => chunk.type === "stdout")
+        .map((chunk) => String(chunk.data?.text ?? ""))
+        .join("");
+    const stderr = params.chunks
+        .filter((chunk) => chunk.type === "stderr" || chunk.type === "error")
+        .map((chunk) => String(chunk.data?.text ?? chunk.data?.message ?? ""))
+        .join("");
+    const exitChunk = [...params.chunks].reverse().find((chunk) => chunk.type === "exit");
+    const exitCode = Number(exitChunk?.data?.exitCode ?? params.processRow?.exitCode ?? 1);
+    const command = [
+        String(params.processRow?.command ?? ""),
+        ...(Array.isArray(params.processRow?.args) ? params.processRow.args : []),
+    ]
+        .filter(Boolean)
+        .join(" ");
+    return {
+        success: exitCode === 0,
+        exitCode,
+        output: stdout,
+        error: stderr,
+        command,
+    };
+}
+export class SandboxCommandRun {
+    constructor(data, service) {
+        this.service = null;
+        this.data = data;
+        this.service = service ?? null;
+    }
+    get sandboxId() {
+        return this.data.sandboxId;
+    }
+    get processId() {
+        return this.data.processId;
+    }
+    get streamId() {
+        return this.data.streamId;
+    }
+    get streamClientId() {
+        return this.data.streamClientId;
+    }
+    getService() {
+        if (!this.service) {
+            throw new Error("sandbox_command_run_service_required");
+        }
+        return this.service;
+    }
+    async readStream() {
+        const stream = await this.getService().readProcessStream(this.processId);
+        if (!stream.ok)
+            throw new Error(stream.error);
+        return stream.data;
+    }
+    async snapshot() {
+        const snapshot = await this.getService().getProcessSnapshot(this.processId);
+        if (!snapshot.ok)
+            throw new Error(snapshot.error);
+        return snapshot.data;
+    }
+    async wait(params) {
+        if (this.data.result)
+            return this.data.result;
+        const initial = await this.snapshot();
+        if (SANDBOX_PROCESS_TERMINAL_STATUSES.has(String(initial.status ?? ""))) {
+            const stream = await this.readStream();
+            const result = commandResultFromProcessStream({ processRow: initial, chunks: stream.chunks });
+            this.data.result = result;
+            return result;
+        }
+        try {
+            const { createHook } = await import("workflow");
+            const hook = createHook({
+                token: sandboxProcessFinishedHookToken(this.processId),
+            });
+            const result = await hook;
+            this.data.result = result;
+            return result;
+        }
+        catch {
+            // Outside workflow context, or if hooks are unavailable, poll the durable row.
+        }
+        const timeoutMs = Math.max(0, Number(params?.timeoutMs ?? 5 * 60 * 1000));
+        const pollMs = Math.max(50, Number(params?.pollMs ?? 500));
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() <= deadline) {
+            const row = await this.snapshot();
+            if (SANDBOX_PROCESS_TERMINAL_STATUSES.has(String(row.status ?? ""))) {
+                const stream = await this.readStream();
+                const result = commandResultFromProcessStream({ processRow: row, chunks: stream.chunks });
+                this.data.result = result;
+                return result;
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+        throw new Error(`sandbox_process_wait_timeout:${this.processId}`);
+    }
+    then(onfulfilled, onrejected) {
+        return this.wait().then(onfulfilled, onrejected);
+    }
+}
 export class SandboxService {
     constructor(db) {
         this.adminDb = db;
@@ -38,18 +232,423 @@ export class SandboxService {
         }
         return { teamId, projectId, token };
     }
-    static async provisionVercelSandbox(config) {
-        const creds = SandboxService.getVercelCredentials();
+    static getDomainName(domain) {
+        const metaName = typeof domain?.meta?.name === "string" ? domain.meta.name.trim() : "";
+        const contextName = typeof domain?.context === "function" ? String(domain.context()?.name ?? "").trim() : "";
+        return metaName || contextName || "domain";
+    }
+    static getDomainContextString(domain) {
+        if (typeof domain?.contextString !== "function")
+            return "";
+        try {
+            return String(domain.contextString() ?? "").trim();
+        }
+        catch {
+            return "";
+        }
+    }
+    static cloneJson(value) {
+        return JSON.parse(JSON.stringify(value));
+    }
+    static buildEkairosNetworkPolicy(params) {
+        const allow = {
+            "api.instantdb.com": [
+                {
+                    transform: [
+                        {
+                            headers: {
+                                "as-token": params.scopedToken,
+                            },
+                        },
+                    ],
+                },
+            ],
+        };
+        if (params.datasetEnabled) {
+            allow["pypi.org"] = [];
+            allow["files.pythonhosted.org"] = [];
+            allow["*.pythonhosted.org"] = [];
+        }
+        return {
+            allow,
+        };
+    }
+    static buildEkairosManifest(params) {
+        const contextString = SandboxService.getDomainContextString(params.domain);
+        const schemaJson = SandboxService.cloneJson(params.domain.toInstantSchema());
+        return {
+            version: 1,
+            instant: {
+                apiBaseUrl: INSTANT_API_BASE_URL,
+                appId: params.appId,
+            },
+            sandbox: {
+                sandboxUserId: params.sandboxUserId,
+            },
+            domain: {
+                name: SandboxService.getDomainName(params.domain),
+                ...(contextString ? { contextString } : {}),
+                schemaJson,
+            },
+            ...(params.datasetEnabled ? { dataset: { enabled: true } } : {}),
+        };
+    }
+    static buildEkairosRuntimeFiles(manifest) {
+        const httpHelper = [
+            "import { readFile } from 'node:fs/promises'",
+            "import { randomUUID } from 'node:crypto'",
+            "",
+            "export async function readRuntimeManifest(manifestPath) {",
+            `  const resolvedPath = manifestPath || ${JSON.stringify(EKAIROS_RUNTIME_MANIFEST_PATH)}`,
+            "  return JSON.parse(await readFile(resolvedPath, 'utf8'))",
+            "}",
+            "",
+            "export async function instantQuery(query, manifestPath) {",
+            "  const manifest = await readRuntimeManifest(manifestPath)",
+            "  const response = await fetch(`${manifest.instant.apiBaseUrl}/admin/query`, {",
+            "    method: 'POST',",
+            "    headers: {",
+            "      'content-type': 'application/json',",
+            "      'app-id': manifest.instant.appId,",
+            "    },",
+            "    body: JSON.stringify({ query }),",
+            "  })",
+            "  const text = await response.text()",
+            "  if (!response.ok) {",
+            "    throw new Error(JSON.stringify({ status: response.status, body: text }))",
+            "  }",
+            "  return text ? JSON.parse(text) : {}",
+            "}",
+            "",
+            "export async function instantTransact(steps, manifestPath) {",
+            "  const manifest = await readRuntimeManifest(manifestPath)",
+            "  const response = await fetch(`${manifest.instant.apiBaseUrl}/admin/transact`, {",
+            "    method: 'POST',",
+            "    headers: {",
+            "      'content-type': 'application/json',",
+            "      'app-id': manifest.instant.appId,",
+            "    },",
+            "    body: JSON.stringify({ steps, 'throw-on-missing-attrs?': true }),",
+            "  })",
+            "  const text = await response.text()",
+            "  if (!response.ok) {",
+            "    throw new Error(JSON.stringify({ status: response.status, body: text }))",
+            "  }",
+            "  return text ? JSON.parse(text) : {}",
+            "}",
+            "",
+            "export function newId() {",
+            "  return randomUUID()",
+            "}",
+            "",
+            "export function decodeArg(encodedJson) {",
+            "  return JSON.parse(Buffer.from(encodedJson, 'base64url').toString('utf8'))",
+            "}",
+            "",
+        ].join("\n");
+        const queryScript = [
+            `import { decodeArg, instantQuery } from ${JSON.stringify(EKAIROS_HTTP_HELPER_PATH)}`,
+            "",
+            "const encodedQuery = process.argv[2] ?? ''",
+            `const manifestPath = process.argv[3] ?? ${JSON.stringify(EKAIROS_RUNTIME_MANIFEST_PATH)}`,
+            "",
+            "if (!encodedQuery) {",
+            "  console.error('ekairos_query_required')",
+            "  process.exit(1)",
+            "}",
+            "",
+            "const query = decodeArg(encodedQuery)",
+            "try {",
+            "  const result = await instantQuery(query, manifestPath)",
+            "  process.stdout.write(JSON.stringify(result))",
+            "} catch (error) {",
+            "  console.error(error instanceof Error ? error.message : String(error))",
+            "  process.exit(1)",
+            "}",
+            "",
+        ].join("\n");
+        const files = [
+            {
+                path: EKAIROS_HTTP_HELPER_PATH,
+                content: Buffer.from(httpHelper, "utf8"),
+            },
+            {
+                path: EKAIROS_RUNTIME_MANIFEST_PATH,
+                content: Buffer.from(JSON.stringify(manifest, null, 2), "utf8"),
+            },
+            {
+                path: EKAIROS_QUERY_SCRIPT_PATH,
+                content: Buffer.from(queryScript, "utf8"),
+            },
+        ];
+        return files;
+    }
+    static async resolveInstantUserIdByRefreshToken(params) {
+        const response = await fetch(`${INSTANT_API_BASE_URL}/admin/users?refresh_token=${encodeURIComponent(params.refreshToken)}`, {
+            method: "GET",
+            headers: {
+                authorization: `Bearer ${params.adminToken}`,
+                "app-id": params.appId,
+            },
+        });
+        const text = await response.text();
+        let parsed = null;
+        try {
+            parsed = text ? JSON.parse(text) : null;
+        }
+        catch {
+            parsed = null;
+        }
+        if (!response.ok) {
+            throw new Error(parsed?.message || parsed?.error || text || "instant_refresh_token_lookup_failed");
+        }
+        const userId = String(parsed?.user?.id ?? "").trim();
+        if (!userId) {
+            throw new Error("instant_refresh_token_user_id_missing");
+        }
+        return userId;
+    }
+    static async resolveEkairosBootstrap(config) {
+        const hasRuntimeBinding = config.env !== undefined || config.domain !== undefined;
+        if (!hasRuntimeBinding)
+            return null;
+        if (!config.env || !config.domain) {
+            throw new Error("sandbox_runtime_requires_env_and_domain");
+        }
+        const provider = SandboxService.resolveProvider(config);
+        if (provider !== "vercel") {
+            throw new Error("ekairos_runtime_requires_vercel_provider");
+        }
+        const datasetEnabled = Boolean(config.dataset?.enabled);
+        const runtime = await resolveRuntime(config.domain, config.env);
+        const adminDb = runtime?.db;
+        const appId = String(adminDb?.config?.appId ?? "").trim();
+        const adminToken = String(adminDb?.config?.adminToken ?? "").trim();
+        if (!adminDb || !appId || !adminToken) {
+            throw new Error("ekairos_runtime_admin_db_required");
+        }
+        const provisionalSandboxUserId = randomUUID();
+        const scopedToken = await adminDb.auth.createToken({ id: provisionalSandboxUserId });
+        const sandboxUserId = await SandboxService.resolveInstantUserIdByRefreshToken({
+            appId,
+            adminToken,
+            refreshToken: scopedToken,
+        });
+        return {
+            appId,
+            sandboxUserId,
+            scopedToken,
+            manifest: SandboxService.buildEkairosManifest({
+                appId,
+                sandboxUserId,
+                domain: config.domain,
+                datasetEnabled,
+            }),
+            networkPolicy: SandboxService.buildEkairosNetworkPolicy({ scopedToken, datasetEnabled }),
+            env: {
+                EKAIROS_RUNTIME_MANIFEST_PATH: EKAIROS_RUNTIME_MANIFEST_PATH,
+                EKAIROS_SANDBOX_USER_ID: sandboxUserId,
+                EKAIROS_INSTANT_APP_ID: appId,
+                CODEX_HOME: CODEX_HOME_DIR,
+            },
+        };
+    }
+    static async bootstrapEkairosFiles(sandbox, manifest) {
+        await SandboxService.safeMkDir(sandbox, EKAIROS_ROOT_DIR);
+        await SandboxService.safeMkDir(sandbox, CODEX_HOME_DIR);
+        await SandboxService.safeMkDir(sandbox, CODEX_SKILLS_DIR);
+        await sandbox.writeFiles(SandboxService.buildEkairosRuntimeFiles(manifest));
+    }
+    static async safeMkDir(sandbox, dirPath) {
+        try {
+            await sandbox.mkDir(dirPath);
+        }
+        catch (error) {
+            const message = formatSandboxError(error);
+            if (message.includes("File exists")) {
+                return;
+            }
+            throw error;
+        }
+    }
+    static buildSkillInstallSet(skills) {
+        return skills.map((skill) => {
+            const skillName = String(skill.name ?? "").trim();
+            if (!skillName) {
+                throw new Error("sandbox_skill_name_required");
+            }
+            const rootDir = `${CODEX_SKILLS_DIR}/${skillName}`;
+            const files = (skill.files ?? []).map((file) => {
+                const relativePath = String(file.path ?? "").replace(/\\/g, "/").replace(/^\/+/, "").trim();
+                if (!relativePath) {
+                    throw new Error(`sandbox_skill_file_path_required:${skillName}`);
+                }
+                return {
+                    path: `${rootDir}/${relativePath}`,
+                    content: Buffer.from(String(file.contentBase64 ?? ""), "base64"),
+                };
+            });
+            return {
+                name: skillName,
+                rootDir,
+                files,
+            };
+        });
+    }
+    static async bootstrapSkills(sandbox, skills) {
+        const installSet = SandboxService.buildSkillInstallSet(skills);
+        if (installSet.length === 0)
+            return [];
+        await SandboxService.safeMkDir(sandbox, CODEX_HOME_DIR);
+        await SandboxService.safeMkDir(sandbox, CODEX_SKILLS_DIR);
+        for (const skill of installSet) {
+            await SandboxService.safeMkDir(sandbox, skill.rootDir);
+            const parentDirs = Array.from(new Set(skill.files
+                .map((file) => path.posix.dirname(file.path))
+                .filter((dirPath) => dirPath && dirPath !== "." && dirPath !== skill.rootDir))).sort((a, b) => a.length - b.length);
+            for (const dirPath of parentDirs) {
+                await SandboxService.safeMkDir(sandbox, dirPath);
+            }
+            await sandbox.writeFiles(skill.files);
+        }
+        return installSet.map((skill) => ({
+            name: skill.name,
+            rootDir: skill.rootDir,
+            fileCount: skill.files.length,
+        }));
+    }
+    static resolveVercelWorkingDirectory(config) {
+        const fromConfig = String(config.vercel?.cwd ?? "").trim();
+        if (fromConfig)
+            return path.resolve(fromConfig);
+        const fromEnv = String(process.env.SANDBOX_VERCEL_CWD ?? "").trim();
+        if (fromEnv)
+            return path.resolve(fromEnv);
+        return process.cwd();
+    }
+    static findLinkedVercelProjectFile(startDir) {
+        let current = path.resolve(startDir);
+        while (true) {
+            const candidate = path.join(current, ".vercel", "project.json");
+            if (existsSync(candidate))
+                return candidate;
+            const parent = path.dirname(current);
+            if (parent === current)
+                return null;
+            current = parent;
+        }
+    }
+    static async readLinkedVercelProject(config) {
+        const cwd = SandboxService.resolveVercelWorkingDirectory(config);
+        const file = SandboxService.findLinkedVercelProjectFile(cwd);
+        if (!file) {
+            return { cwd };
+        }
+        try {
+            const parsed = JSON.parse(await fs.readFile(file, "utf8"));
+            return {
+                cwd,
+                orgId: typeof parsed?.orgId === "string" ? parsed.orgId : undefined,
+                projectId: typeof parsed?.projectId === "string" ? parsed.projectId : undefined,
+                projectName: typeof parsed?.projectName === "string" ? parsed.projectName : undefined,
+            };
+        }
+        catch {
+            return { cwd };
+        }
+    }
+    static async pullVercelOidcToken(config) {
+        const cwd = SandboxService.resolveVercelWorkingDirectory(config);
+        const tmpPath = path.join(os.tmpdir(), `ekairos-vercel-env-${Date.now()}-${Math.random().toString(36).slice(2)}.env`);
+        const args = ["env", "pull", tmpPath, "--yes", "--environment", String(config.vercel?.environment ?? "development")];
+        const scope = String(config.vercel?.scope ?? process.env.SANDBOX_VERCEL_SCOPE ?? "").trim();
+        if (scope) {
+            args.push("--scope", scope);
+        }
+        const token = String(process.env.VERCEL_TOKEN ?? process.env.SANDBOX_VERCEL_TOKEN ?? "").trim();
+        if (token) {
+            args.push("--token", token);
+        }
+        const isWindows = process.platform === "win32";
+        const command = isWindows ? (process.env.COMSPEC || "cmd.exe") : "vercel";
+        const commandArgs = isWindows ? ["/c", "vercel", ...args] : args;
+        try {
+            await execFileAsync(command, commandArgs, {
+                cwd,
+                windowsHide: true,
+                timeout: 120000,
+                maxBuffer: 1024 * 1024 * 10,
+            });
+            const content = await fs.readFile(tmpPath, "utf8");
+            const match = content.match(/VERCEL_OIDC_TOKEN=\"?([^\r\n\"]+)\"?/);
+            const oidc = String(match?.[1] ?? "").trim();
+            if (!oidc) {
+                throw new Error("VERCEL_OIDC_TOKEN missing from vercel env pull output");
+            }
+            return oidc;
+        }
+        finally {
+            await fs.rm(tmpPath, { force: true }).catch(() => { });
+        }
+    }
+    static async resolveVercelCredentials(config) {
+        const explicitTeamId = String(config.vercel?.orgId ?? process.env.SANDBOX_VERCEL_TEAM_ID ?? "").trim();
+        const explicitProjectId = String(config.vercel?.projectId ?? process.env.SANDBOX_VERCEL_PROJECT_ID ?? "").trim();
+        const explicitToken = String(config.vercel?.token ?? process.env.SANDBOX_VERCEL_TOKEN ?? process.env.VERCEL_OIDC_TOKEN ?? "").trim();
+        if (explicitTeamId && explicitProjectId && explicitToken) {
+            return { teamId: explicitTeamId, projectId: explicitProjectId, token: explicitToken };
+        }
+        const linked = await SandboxService.readLinkedVercelProject(config);
+        const teamId = explicitTeamId || String(linked.orgId ?? "").trim();
+        const projectId = explicitProjectId || String(linked.projectId ?? "").trim();
+        let token = explicitToken;
+        if (!token) {
+            token = await SandboxService.pullVercelOidcToken(config);
+        }
+        if (!teamId || !projectId || !token) {
+            throw new Error("Missing Vercel sandbox credentials. Link the project (`vercel link`) and ensure `vercel env pull` can resolve VERCEL_OIDC_TOKEN, or provide explicit SANDBOX_VERCEL_* env vars.");
+        }
+        return { teamId, projectId, token };
+    }
+    static async provisionVercelSandbox(config, extra) {
+        const creds = await SandboxService.resolveVercelCredentials(config);
+        const resolved = extra?.resolved ?? resolveVercelSandboxConfig(config);
+        if (resolved.reuse && resolved.name) {
+            try {
+                return await VercelSandbox.get({
+                    name: resolved.name,
+                    teamId: creds.teamId,
+                    projectId: creds.projectId,
+                    token: creds.token,
+                    resume: true,
+                });
+            }
+            catch (error) {
+                const status = Number(error?.response?.status ?? 0);
+                const message = formatSandboxError(error).toLowerCase();
+                if (status !== 404 && !message.includes("not found")) {
+                    throw error;
+                }
+            }
+        }
         return await VercelSandbox.create({
             teamId: creds.teamId,
             projectId: creds.projectId,
             token: creds.token,
-            timeout: config.timeoutMs ?? 30 * 60 * 1000,
-            ports: Array.isArray(config.ports) ? config.ports : [],
+            ...(resolved.name ? { name: resolved.name } : {}),
+            timeout: resolved.timeoutMs,
+            ports: resolved.ports,
             // IMPORTANT: pass runtime as-is (e.g. "python3.13") to match provider expectations.
             // Don't normalize to "python3"/"node22" as that can cause provider-side 400s.
-            runtime: (config.runtime ?? "node22"),
-            resources: { vcpus: config.resources?.vcpus ?? 2 },
+            runtime: resolved.runtime,
+            resources: { vcpus: resolved.vcpus },
+            persistent: resolved.persistent,
+            ...(resolved.snapshotExpirationMs !== undefined
+                ? { snapshotExpiration: resolved.snapshotExpirationMs }
+                : {}),
+            ...(resolved.tags ? { tags: resolved.tags } : {}),
+            networkPolicy: extra?.networkPolicy,
+            env: extra?.env,
         });
     }
     static getDaytonaConfig() {
@@ -235,8 +834,8 @@ export class SandboxService {
                         : "";
         return {
             exitCode: Number.isFinite(exitCode) ? exitCode : 0,
-            stdout,
-            stderr,
+            stdout: sanitizeInstantString(stdout),
+            stderr: sanitizeInstantString(stderr),
         };
     }
     static async spritesExec(params) {
@@ -428,22 +1027,55 @@ export class SandboxService {
         const sandboxId = id();
         const now = Date.now();
         const provider = SandboxService.resolveProvider(config);
+        const resolvedVercel = provider === "vercel" ? resolveVercelSandboxConfig(config, { sandboxId }) : undefined;
         let daytonaEphemeral = undefined;
+        let installedSkills = [];
         try {
+            const ekairos = await SandboxService.resolveEkairosBootstrap(config);
             const baseParams = config.params && typeof config.params === "object" && !Array.isArray(config.params) ? config.params : {};
             await this.adminDb.transact(this.adminDb.tx.sandbox_sandboxes[sandboxId].update({
                 status: "creating",
+                ...(ekairos ? { sandboxUserId: ekairos.sandboxUserId } : {}),
                 provider,
-                timeout: config.timeoutMs,
-                runtime: config.runtime,
-                vcpus: config.resources?.vcpus,
-                ports: config.ports,
+                timeout: resolvedVercel?.timeoutMs ?? config.timeoutMs,
+                runtime: resolvedVercel?.runtime ?? config.runtime,
+                vcpus: resolvedVercel?.vcpus ?? config.resources?.vcpus,
+                ports: (resolvedVercel?.ports ?? config.ports),
                 purpose: config.purpose,
-                params: baseParams,
+                params: {
+                    ...baseParams,
+                    ...(resolvedVercel ? { vercel: safeVercelConfigForRecord(config, resolvedVercel) } : {}),
+                    ...(ekairos
+                        ? {
+                            ekairos: {
+                                enabled: true,
+                                sandboxUserId: ekairos.sandboxUserId,
+                                instant: {
+                                    appId: ekairos.appId,
+                                    apiBaseUrl: ekairos.manifest.instant.apiBaseUrl,
+                                },
+                                bootstrap: {
+                                    manifestPath: EKAIROS_RUNTIME_MANIFEST_PATH,
+                                    queryScriptPath: EKAIROS_QUERY_SCRIPT_PATH,
+                                },
+                                domain: ekairos.manifest.domain,
+                                ...(config.dataset?.enabled ? { dataset: { enabled: true } } : {}),
+                                ...(Array.isArray(config.skills) && config.skills.length > 0
+                                    ? {
+                                        skills: config.skills.map((skill) => ({
+                                            name: skill.name,
+                                            fileCount: Array.isArray(skill.files) ? skill.files.length : 0,
+                                        })),
+                                    }
+                                    : {}),
+                            },
+                        }
+                        : {}),
+                },
                 createdAt: now,
                 updatedAt: now,
             }));
-            let sandbox;
+            let sandbox = null;
             try {
                 if (provider === "daytona") {
                     const daytona = new Daytona(SandboxService.getDaytonaConfig());
@@ -505,11 +1137,36 @@ export class SandboxService {
                     });
                 }
                 else {
-                    sandbox = await SandboxService.provisionVercelSandbox(config);
+                    const vercelEnv = {
+                        ...(Array.isArray(config.skills) && config.skills.length > 0 ? { CODEX_HOME: CODEX_HOME_DIR } : {}),
+                        ...(ekairos?.env ?? {}),
+                    };
+                    sandbox = await SandboxService.provisionVercelSandbox(config, {
+                        networkPolicy: ekairos?.networkPolicy,
+                        env: Object.keys(vercelEnv).length > 0 ? vercelEnv : undefined,
+                        resolved: resolvedVercel,
+                    });
+                    if (ekairos) {
+                        await SandboxService.bootstrapEkairosFiles(sandbox, ekairos.manifest);
+                    }
+                    if (Array.isArray(config.skills) && config.skills.length > 0) {
+                        installedSkills = await SandboxService.bootstrapSkills(sandbox, config.skills);
+                    }
                 }
             }
             catch (e) {
-                const msg = e instanceof Error ? e.message : String(e);
+                const msg = formatSandboxError(e);
+                if (sandbox && provider === "vercel") {
+                    try {
+                        await sandbox.stop({ blocking: true });
+                        if (resolvedVercel?.deleteOnStop) {
+                            await sandbox.delete();
+                        }
+                    }
+                    catch {
+                        // ignore cleanup errors during failed bootstrap
+                    }
+                }
                 await this.adminDb.transact(this.adminDb.tx.sandbox_sandboxes[sandboxId].update({
                     status: "error",
                     updatedAt: Date.now(),
@@ -521,37 +1178,68 @@ export class SandboxService {
                 ? sandbox.id
                 : provider === "sprites"
                     ? String(sandbox.name)
-                    : sandbox.sandboxId;
+                    : sandbox.name;
             const sandboxUrl = provider === "sprites" ? sandbox.url : undefined;
-            await this.adminDb.transact(this.adminDb.tx.sandbox_sandboxes[sandboxId].update({
-                status: "active",
-                externalSandboxId,
-                ...(sandboxUrl ? { sandboxUrl } : {}),
-                updatedAt: Date.now(),
-                params: {
-                    ...baseParams,
-                    ...(provider === "daytona"
-                        ? {
-                            daytona: {
-                                ...baseParams?.daytona,
-                                ephemeral: daytonaEphemeral,
-                            },
-                        }
-                        : {}),
-                    ...(provider === "sprites"
-                        ? {
-                            sprites: {
-                                ...baseParams?.sprites,
-                                id: sandbox.id,
-                                name: sandbox.name,
-                                url: sandbox.url,
-                                urlSettings: config.sprites?.urlSettings ?? baseParams?.sprites?.urlSettings ?? undefined,
-                                deleteOnStop: config.sprites?.deleteOnStop ?? baseParams?.sprites?.deleteOnStop ?? true,
-                            },
-                        }
-                        : {}),
-                },
-            }));
+            const activateMutations = [
+                this.adminDb.tx.sandbox_sandboxes[sandboxId].update({
+                    status: "active",
+                    externalSandboxId,
+                    ...(ekairos ? { sandboxUserId: ekairos.sandboxUserId } : {}),
+                    ...(sandboxUrl ? { sandboxUrl } : {}),
+                    updatedAt: Date.now(),
+                    params: {
+                        ...baseParams,
+                        ...(ekairos
+                            ? {
+                                ekairos: {
+                                    enabled: true,
+                                    sandboxUserId: ekairos.sandboxUserId,
+                                    instant: {
+                                        appId: ekairos.appId,
+                                        apiBaseUrl: ekairos.manifest.instant.apiBaseUrl,
+                                    },
+                                    bootstrap: {
+                                        manifestPath: EKAIROS_RUNTIME_MANIFEST_PATH,
+                                        queryScriptPath: EKAIROS_QUERY_SCRIPT_PATH,
+                                    },
+                                    domain: ekairos.manifest.domain,
+                                    ...(config.dataset?.enabled ? { dataset: { enabled: true } } : {}),
+                                    ...(installedSkills.length > 0 ? { skills: installedSkills } : {}),
+                                },
+                            }
+                            : {}),
+                        ...(provider === "vercel"
+                            ? {
+                                vercel: resolvedVercel ? safeVercelConfigForRecord(config, resolvedVercel) : {},
+                            }
+                            : {}),
+                        ...(provider === "daytona"
+                            ? {
+                                daytona: {
+                                    ...baseParams?.daytona,
+                                    ephemeral: daytonaEphemeral,
+                                },
+                            }
+                            : {}),
+                        ...(provider === "sprites"
+                            ? {
+                                sprites: {
+                                    ...baseParams?.sprites,
+                                    id: sandbox.id,
+                                    name: sandbox.name,
+                                    url: sandbox.url,
+                                    urlSettings: config.sprites?.urlSettings ?? baseParams?.sprites?.urlSettings ?? undefined,
+                                    deleteOnStop: config.sprites?.deleteOnStop ?? baseParams?.sprites?.deleteOnStop ?? true,
+                                },
+                            }
+                            : {}),
+                    },
+                }),
+            ];
+            if (ekairos) {
+                activateMutations.push(this.adminDb.tx.sandbox_sandboxes[sandboxId].link({ user: ekairos.sandboxUserId }));
+            }
+            await this.adminDb.transact(activateMutations);
             return { ok: true, data: { sandboxId } };
         }
         catch (e) {
@@ -648,13 +1336,13 @@ export class SandboxService {
             if (record.provider !== "vercel") {
                 return { ok: false, error: "Valid sandbox record not found" };
             }
-            const creds = SandboxService.getVercelCredentials();
+            const creds = await SandboxService.resolveVercelCredentials(record?.params ?? {});
             try {
                 const maxAttempts = 20;
                 const delayMs = 500;
                 for (let attempt = 0; attempt < maxAttempts; attempt++) {
                     const sandbox = await VercelSandbox.get({
-                        sandboxId: String(record.externalSandboxId),
+                        name: String(record.externalSandboxId),
                         teamId: creds.teamId,
                         projectId: creds.projectId,
                         token: creds.token,
@@ -684,6 +1372,260 @@ export class SandboxService {
             return { ok: false, error: formatInstantSchemaError(e) };
         }
     }
+    async getSandboxRecord(sandboxId) {
+        const recordResult = await this.adminDb.query({
+            sandbox_sandboxes: { $: { where: { id: sandboxId }, limit: 1 }, user: {} },
+        });
+        return recordResult?.sandbox_sandboxes?.[0] ?? null;
+    }
+    async getProcessSnapshot(processId) {
+        try {
+            const processResult = await this.adminDb.query({
+                sandbox_processes: {
+                    $: { where: { id: processId }, limit: 1 },
+                    sandbox: {},
+                },
+            });
+            const processRow = processResult?.sandbox_processes?.[0];
+            if (!processRow)
+                return { ok: false, error: "sandbox_process_not_found" };
+            return { ok: true, data: processRow };
+        }
+        catch (e) {
+            return { ok: false, error: formatInstantSchemaError(e) };
+        }
+    }
+    async markOpenProcessesLost(sandboxId, reason) {
+        try {
+            const processResult = await this.adminDb.query({
+                sandbox_processes: {
+                    $: {
+                        where: { "sandbox.id": sandboxId },
+                        limit: 500,
+                    },
+                },
+            });
+            const rows = Array.isArray(processResult?.sandbox_processes)
+                ? processResult.sandbox_processes
+                : [];
+            const now = Date.now();
+            const txs = rows
+                .filter((row) => !SANDBOX_PROCESS_TERMINAL_STATUSES.has(String(row?.status ?? "")))
+                .map((row) => this.adminDb.tx.sandbox_processes[String(row.id)].update({
+                status: "lost",
+                streamFinishedAt: row.streamFinishedAt ?? now,
+                streamAbortReason: reason,
+                exitedAt: now,
+                updatedAt: now,
+                metadata: {
+                    ...(row.metadata ?? {}),
+                    lostReason: reason,
+                },
+            }));
+            if (txs.length > 0) {
+                await this.adminDb.transact(txs);
+            }
+        }
+        catch {
+            // Best-effort cleanup; stopping the sandbox should not fail because process metadata could not be marked.
+        }
+    }
+    async createProcessStream(params) {
+        const streams = this.adminDb?.streams;
+        if (!streams?.createWriteStream) {
+            throw new Error("sandbox_process_streams_unavailable");
+        }
+        const streamClientId = params.streamClientId || createSandboxProcessStreamClientId(params.processId);
+        const stream = streams.createWriteStream({ clientId: streamClientId });
+        const streamId = typeof stream.streamId === "function" ? await stream.streamId() : streamClientId;
+        return { stream, streamId, streamClientId };
+    }
+    async writeProcessChunk(params) {
+        await params.writer.write(encodeSandboxProcessStreamChunk({
+            version: SANDBOX_PROCESS_STREAM_VERSION,
+            at: nowIso(),
+            seq: params.seq,
+            type: params.type,
+            sandboxId: params.sandboxId,
+            processId: params.processId,
+            ...(params.data ? { data: sanitizeInstantValue(params.data) } : {}),
+        }));
+    }
+    async readProcessRow(processId) {
+        const result = await this.adminDb.query({
+            sandbox_processes: {
+                $: { where: { id: processId }, limit: 1 },
+                sandbox: {},
+            },
+        });
+        return result?.sandbox_processes?.[0] ?? null;
+    }
+    async writeProcessChunkByProcessId(processId, type, data, opts) {
+        const row = await this.readProcessRow(processId);
+        if (!row)
+            throw new Error("sandbox_process_not_found");
+        const linkedSandbox = Array.isArray(row?.sandbox) ? row.sandbox[0] : row?.sandbox;
+        const sandboxId = String(linkedSandbox?.id ?? row?.sandboxId ?? "").trim();
+        if (!sandboxId)
+            throw new Error("sandbox_process_sandbox_missing");
+        const streamClientId = String(row.streamClientId ?? "").trim() || createSandboxProcessStreamClientId(processId);
+        const streams = this.adminDb?.streams;
+        if (!streams?.createWriteStream)
+            throw new Error("sandbox_process_streams_unavailable");
+        const stream = streams.createWriteStream({ clientId: streamClientId });
+        const writer = stream.getWriter();
+        try {
+            const seq = Number(row.metadata?.lastSeq ?? row.metadata?.chunkCount ?? 0) + 1;
+            await this.writeProcessChunk({
+                writer,
+                sandboxId,
+                processId,
+                seq,
+                type,
+                data,
+            });
+            if (opts?.close) {
+                await writer.close();
+            }
+            await this.adminDb.transact([
+                this.adminDb.tx.sandbox_processes[processId].update({
+                    updatedAt: Date.now(),
+                    metadata: sanitizeInstantValue({
+                        ...(row.metadata ?? {}),
+                        lastSeq: seq,
+                        chunkCount: seq,
+                    }),
+                }),
+            ]);
+        }
+        finally {
+            try {
+                writer.releaseLock();
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    async startObservedProcess(sandboxId, opts) {
+        const processId = id();
+        const now = Date.now();
+        try {
+            const record = await this.getSandboxRecord(sandboxId);
+            if (!record)
+                return { ok: false, error: "Valid sandbox record not found" };
+            if (record.status !== "active")
+                return { ok: false, error: `sandbox_not_active:${record.status}` };
+            const streamSession = await this.createProcessStream({ sandboxId, processId });
+            const stream = streamSession.stream;
+            const writer = stream.getWriter();
+            try {
+                await this.adminDb.transact([
+                    this.adminDb.tx.sandbox_processes[processId]
+                        .update({
+                        kind: opts.kind ?? "command",
+                        mode: opts.mode ?? "foreground",
+                        status: "running",
+                        provider: String(record.provider ?? "unknown"),
+                        command: sanitizeInstantString(opts.command),
+                        args: sanitizeInstantValue(Array.isArray(opts.args) ? opts.args : []),
+                        cwd: asOptionalString(opts.cwd),
+                        env: sanitizeInstantValue(opts.env),
+                        externalProcessId: asOptionalString(opts.externalProcessId),
+                        streamId: streamSession.streamId,
+                        streamClientId: streamSession.streamClientId,
+                        streamStartedAt: now,
+                        startedAt: now,
+                        updatedAt: now,
+                        metadata: sanitizeInstantValue({
+                            ...(opts.metadata ?? {}),
+                            observed: true,
+                            lastSeq: 1,
+                            chunkCount: 1,
+                        }),
+                    })
+                        .link({ sandbox: sandboxId, stream: streamSession.streamId }),
+                ]);
+                await this.writeProcessChunk({
+                    writer,
+                    sandboxId,
+                    processId,
+                    seq: 1,
+                    type: "status",
+                    data: {
+                        status: "running",
+                        command: opts.command,
+                        args: Array.isArray(opts.args) ? opts.args : [],
+                        cwd: opts.cwd ?? null,
+                        externalProcessId: opts.externalProcessId ?? null,
+                    },
+                });
+                // Keep observed-process streams open across calls; finishObservedProcess closes them.
+            }
+            finally {
+                try {
+                    writer.releaseLock();
+                }
+                catch {
+                    // ignore
+                }
+            }
+            return {
+                ok: true,
+                data: {
+                    processId,
+                    streamId: streamSession.streamId,
+                    streamClientId: streamSession.streamClientId,
+                },
+            };
+        }
+        catch (e) {
+            return { ok: false, error: formatInstantSchemaError(e) };
+        }
+    }
+    async appendObservedProcessChunk(processId, type, data) {
+        try {
+            await this.writeProcessChunkByProcessId(processId, type, data);
+            return { ok: true, data: undefined };
+        }
+        catch (e) {
+            return { ok: false, error: formatInstantSchemaError(e) };
+        }
+    }
+    async finishObservedProcess(processId, opts) {
+        try {
+            const row = await this.readProcessRow(processId);
+            if (!row)
+                return { ok: false, error: "sandbox_process_not_found" };
+            const exitCode = Number.isFinite(Number(opts?.exitCode)) ? Number(opts?.exitCode) : undefined;
+            const status = opts?.status ?? (exitCode === undefined || exitCode === 0 ? "exited" : "failed");
+            await this.writeProcessChunkByProcessId(processId, status === "failed" ? "error" : "exit", {
+                exitCode: exitCode ?? null,
+                status,
+                ...(opts?.errorText ? { message: opts.errorText } : {}),
+            }, { close: true });
+            const finishedAt = Date.now();
+            await this.adminDb.transact([
+                this.adminDb.tx.sandbox_processes[processId].update({
+                    status,
+                    ...(exitCode !== undefined ? { exitCode } : {}),
+                    streamFinishedAt: finishedAt,
+                    streamAbortReason: opts?.errorText ?? null,
+                    exitedAt: finishedAt,
+                    updatedAt: finishedAt,
+                    metadata: sanitizeInstantValue({
+                        ...(row.metadata ?? {}),
+                        ...(opts?.metadata ?? {}),
+                        ...(opts?.errorText ? { error: opts.errorText } : {}),
+                    }),
+                }),
+            ]);
+            return { ok: true, data: undefined };
+        }
+        catch (e) {
+            return { ok: false, error: formatInstantSchemaError(e) };
+        }
+    }
     async stopSandbox(sandboxId) {
         try {
             const result = await this.reconnectToSandbox(sandboxId);
@@ -694,13 +1636,19 @@ export class SandboxService {
             const deleteOnStop = record?.provider === "sprites"
                 ? SandboxService.parseOptionalBoolean(process.env.SANDBOX_SPRITES_DELETE_ON_STOP) ??
                     Boolean(record?.params?.sprites?.deleteOnStop ?? true)
-                : SandboxService.parseOptionalBoolean(process.env.SANDBOX_DAYTONA_DELETE_ON_STOP) ??
-                    Boolean(record?.params?.daytona?.ephemeral);
+                : record?.provider === "vercel"
+                    ? SandboxService.parseOptionalBoolean(process.env.SANDBOX_VERCEL_DELETE_ON_STOP) ??
+                        Boolean(record?.params?.vercel?.deleteOnStop ?? !record?.params?.vercel?.persistent)
+                    : SandboxService.parseOptionalBoolean(process.env.SANDBOX_DAYTONA_DELETE_ON_STOP) ??
+                        Boolean(record?.params?.daytona?.ephemeral);
             if (result.ok) {
                 try {
                     const sandbox = result.data.sandbox;
-                    if (sandbox?.sandboxId) {
-                        await sandbox.stop();
+                    if (isVercelSandbox(sandbox)) {
+                        await sandbox.stop({ blocking: true });
+                        if (deleteOnStop) {
+                            await sandbox.delete();
+                        }
                     }
                     else if (sandbox?.__provider === "sprites") {
                         // Sprites does not have a reliable "stop" semantic; deleting is the durable cleanup primitive.
@@ -735,19 +1683,55 @@ export class SandboxService {
                 shutdownAt: Date.now(),
                 updatedAt: Date.now(),
             }));
+            await this.markOpenProcessesLost(sandboxId, "sandbox_stopped");
             return { ok: true, data: undefined };
         }
         catch (e) {
             return { ok: false, error: formatInstantSchemaError(e) };
         }
     }
+    async query(sandboxId, query) {
+        try {
+            const record = await this.getSandboxRecord(sandboxId);
+            if (!record) {
+                return { ok: false, error: "Valid sandbox record not found" };
+            }
+            if (record.provider !== "vercel") {
+                return { ok: false, error: "sandbox_query_requires_vercel_provider" };
+            }
+            const queryScriptPath = String(record?.params?.ekairos?.bootstrap?.queryScriptPath ?? "").trim();
+            if (!queryScriptPath) {
+                return { ok: false, error: "sandbox_query_not_configured" };
+            }
+            const manifestPath = String(record?.params?.ekairos?.bootstrap?.manifestPath ?? "").trim() || EKAIROS_RUNTIME_MANIFEST_PATH;
+            const encodedQuery = Buffer.from(JSON.stringify(query), "utf8").toString("base64url");
+            const result = await this.runCommand(sandboxId, "node", [queryScriptPath, encodedQuery, manifestPath]);
+            if (!result.ok) {
+                return result;
+            }
+            const stdout = String(result.data.output ?? "").trim();
+            if (!stdout) {
+                return { ok: false, error: "sandbox_query_empty_response" };
+            }
+            try {
+                return { ok: true, data: JSON.parse(stdout) };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return { ok: false, error: `sandbox_query_invalid_json: ${message}` };
+            }
+        }
+        catch (e) {
+            return { ok: false, error: formatInstantSchemaError(e) };
+        }
+    }
     async runCommand(sandboxId, command, args = []) {
         try {
             const sandboxResult = await this.reconnectToSandbox(sandboxId);
             if (!sandboxResult.ok)
                 return { ok: false, error: sandboxResult.error };
             const sandbox = sandboxResult.data.sandbox;
-            if (sandbox.sandboxId) {
+            if (isVercelSandbox(sandbox)) {
                 const result = await runCommandInSandbox(sandbox, command, args);
                 return { ok: true, data: result };
             }
@@ -788,13 +1772,279 @@ export class SandboxService {
             return { ok: false, error: formatInstantSchemaError(e) };
         }
     }
+    async runCommandProcess(sandboxId, command, args = [], opts) {
+        const processId = id();
+        const now = Date.now();
+        let writer = null;
+        let stream = null;
+        let seq = 0;
+        try {
+            const record = await this.getSandboxRecord(sandboxId);
+            if (!record)
+                return { ok: false, error: "Valid sandbox record not found" };
+            if (record.status !== "active")
+                return { ok: false, error: `sandbox_not_active:${record.status}` };
+            const streamSession = await this.createProcessStream({ sandboxId, processId });
+            stream = streamSession.stream;
+            writer = stream.getWriter();
+            await this.adminDb.transact([
+                this.adminDb.tx.sandbox_processes[processId]
+                    .update({
+                    kind: opts?.kind ?? "command",
+                    mode: opts?.mode ?? "foreground",
+                    status: "running",
+                    provider: String(record.provider ?? "unknown"),
+                    command: sanitizeInstantString(command),
+                    args: sanitizeInstantValue(Array.isArray(args) ? args : []),
+                    cwd: asOptionalString(opts?.cwd),
+                    env: sanitizeInstantValue(opts?.env),
+                    streamId: streamSession.streamId,
+                    streamClientId: streamSession.streamClientId,
+                    streamStartedAt: now,
+                    startedAt: now,
+                    updatedAt: now,
+                    metadata: sanitizeInstantValue(opts?.metadata),
+                })
+                    .link({ sandbox: sandboxId, stream: streamSession.streamId }),
+            ]);
+            seq += 1;
+            await this.writeProcessChunk({
+                writer,
+                sandboxId,
+                processId,
+                seq,
+                type: "status",
+                data: {
+                    status: "running",
+                    command,
+                    args: Array.isArray(args) ? args : [],
+                    cwd: opts?.cwd ?? null,
+                },
+            });
+            const result = await this.runCommand(sandboxId, command, args);
+            const finishedAt = Date.now();
+            let finalResult;
+            let status;
+            let exitCode;
+            let errorText;
+            if (result.ok) {
+                finalResult = result.data;
+                exitCode = Number(result.data.exitCode ?? (result.data.success === false ? 1 : 0));
+                status = exitCode === 0 ? "exited" : "failed";
+                const stdout = String(result.data.stdout ?? result.data.output ?? "");
+                const stderr = String(result.data.stderr ?? result.data.error ?? "");
+                if (stdout) {
+                    seq += 1;
+                    await this.writeProcessChunk({
+                        writer,
+                        sandboxId,
+                        processId,
+                        seq,
+                        type: "stdout",
+                        data: { text: stdout },
+                    });
+                }
+                if (stderr) {
+                    seq += 1;
+                    await this.writeProcessChunk({
+                        writer,
+                        sandboxId,
+                        processId,
+                        seq,
+                        type: "stderr",
+                        data: { text: stderr },
+                    });
+                }
+            }
+            else {
+                exitCode = 1;
+                status = "failed";
+                errorText = result.error;
+                finalResult = {
+                    success: false,
+                    exitCode,
+                    output: "",
+                    error: result.error,
+                    command: [command, ...(Array.isArray(args) ? args : [])].join(" "),
+                };
+                seq += 1;
+                await this.writeProcessChunk({
+                    writer,
+                    sandboxId,
+                    processId,
+                    seq,
+                    type: "error",
+                    data: { message: result.error },
+                });
+            }
+            seq += 1;
+            await this.writeProcessChunk({
+                writer,
+                sandboxId,
+                processId,
+                seq,
+                type: "exit",
+                data: { exitCode, status },
+            });
+            await writer.close();
+            writer = null;
+            await this.adminDb.transact([
+                this.adminDb.tx.sandbox_processes[processId].update({
+                    status,
+                    exitCode,
+                    streamFinishedAt: finishedAt,
+                    streamAbortReason: null,
+                    exitedAt: finishedAt,
+                    updatedAt: finishedAt,
+                    metadata: sanitizeInstantValue({
+                        ...(opts?.metadata ?? {}),
+                        ...(errorText ? { error: errorText } : {}),
+                        chunkCount: seq,
+                        result: finalResult,
+                    }),
+                }),
+            ]);
+            await resumeSandboxProcessHook(processId, finalResult);
+            return {
+                ok: true,
+                data: new SandboxCommandRun({
+                    sandboxId,
+                    processId,
+                    streamId: streamSession.streamId,
+                    streamClientId: streamSession.streamClientId,
+                    result: finalResult,
+                }, this),
+            };
+        }
+        catch (e) {
+            const message = formatInstantSchemaError(e);
+            const failedAt = Date.now();
+            try {
+                if (writer) {
+                    seq += 1;
+                    await this.writeProcessChunk({
+                        writer,
+                        sandboxId,
+                        processId,
+                        seq,
+                        type: "error",
+                        data: { message },
+                    });
+                    await writer.abort(message);
+                    writer = null;
+                }
+                else if (stream) {
+                    await stream.abort(message);
+                }
+            }
+            catch {
+                // ignore stream cleanup errors
+            }
+            try {
+                const finalResult = {
+                    success: false,
+                    exitCode: 1,
+                    output: "",
+                    error: message,
+                    command: [command, ...(Array.isArray(args) ? args : [])].join(" "),
+                };
+                await this.adminDb.transact([
+                    this.adminDb.tx.sandbox_processes[processId].update({
+                        status: "failed",
+                        streamFinishedAt: failedAt,
+                        streamAbortReason: message,
+                        exitedAt: failedAt,
+                        updatedAt: failedAt,
+                        metadata: sanitizeInstantValue({
+                            ...(opts?.metadata ?? {}),
+                            error: message,
+                            result: finalResult,
+                        }),
+                    }),
+                ]);
+                await resumeSandboxProcessHook(processId, finalResult);
+            }
+            catch {
+                // ignore partial metadata failures
+            }
+            return { ok: false, error: message };
+        }
+        finally {
+            try {
+                writer?.releaseLock();
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    async runCommandWithProcessStream(sandboxId, command, args = [], opts) {
+        const run = await this.runCommandProcess(sandboxId, command, args, opts);
+        if (!run.ok)
+            return run;
+        const result = await run.data;
+        return {
+            ok: true,
+            data: {
+                processId: run.data.processId,
+                streamId: run.data.streamId,
+                streamClientId: run.data.streamClientId,
+                result,
+            },
+        };
+    }
+    async readProcessStream(processId) {
+        try {
+            const processResult = await this.adminDb.query({
+                sandbox_processes: {
+                    $: { where: { id: processId }, limit: 1 },
+                },
+            });
+            const processRow = processResult?.sandbox_processes?.[0];
+            if (!processRow)
+                return { ok: false, error: "sandbox_process_not_found" };
+            const streams = this.adminDb?.streams;
+            if (!streams?.createReadStream)
+                return { ok: false, error: "sandbox_process_streams_unavailable" };
+            const clientId = String(processRow.streamClientId ?? "").trim() || undefined;
+            const streamId = String(processRow.streamId ?? "").trim() || undefined;
+            if (!clientId && !streamId)
+                return { ok: false, error: "sandbox_process_stream_missing" };
+            const stream = streams.createReadStream({ clientId, streamId });
+            const chunks = [];
+            let byteOffset = 0;
+            let buffer = "";
+            for await (const raw of stream) {
+                const encoded = typeof raw === "string" ? raw : String(raw ?? "");
+                if (!encoded)
+                    continue;
+                byteOffset += new TextEncoder().encode(encoded).length;
+                buffer += encoded;
+                const lines = buffer.split("\n");
+                buffer = lines.pop() ?? "";
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed)
+                        continue;
+                    chunks.push(parseSandboxProcessStreamChunk(trimmed));
+                }
+            }
+            const trailing = buffer.trim();
+            if (trailing)
+                chunks.push(parseSandboxProcessStreamChunk(trailing));
+            return { ok: true, data: { chunks, byteOffset } };
+        }
+        catch (e) {
+            return { ok: false, error: formatInstantSchemaError(e) };
+        }
+    }
     async writeFiles(sandboxId, files) {
         try {
             const sandboxResult = await this.reconnectToSandbox(sandboxId);
             if (!sandboxResult.ok)
                 return { ok: false, error: sandboxResult.error };
             const sandbox = sandboxResult.data.sandbox;
-            if (sandbox.sandboxId) {
+            if (isVercelSandbox(sandbox)) {
                 await sandbox.writeFiles(files.map((f) => ({
                     path: f.path,
                     content: Buffer.from(f.contentBase64, "base64"),
@@ -836,7 +2086,7 @@ export class SandboxService {
             if (!sandboxResult.ok)
                 return { ok: false, error: sandboxResult.error };
             const sandbox = sandboxResult.data.sandbox;
-            if (sandbox.sandboxId) {
+            if (isVercelSandbox(sandbox)) {
                 const stream = await sandbox.readFile({ path });
                 if (!stream) {
                     return { ok: true, data: { contentBase64: "" } };
@@ -878,6 +2128,38 @@ export class SandboxService {
             return { ok: false, error: formatInstantSchemaError(e) };
         }
     }
+    async getPortUrl(sandboxId, port) {
+        try {
+            const sandboxResult = await this.reconnectToSandbox(sandboxId);
+            if (!sandboxResult.ok)
+                return { ok: false, error: sandboxResult.error };
+            const sandbox = sandboxResult.data.sandbox;
+            const normalizedPort = Math.max(1, Math.floor(Number(port)));
+            if (isVercelSandbox(sandbox)) {
+                const url = sandbox.domain(normalizedPort);
+                return { ok: true, data: { url: String(url ?? "").replace(/\/+$/, "") } };
+            }
+            if (sandbox.__provider === "sprites") {
+                const base = String(sandbox.url ?? "").trim().replace(/\/+$/, "");
+                if (!base)
+                    return { ok: false, error: "sprites_url_missing" };
+                if (normalizedPort === 8080)
+                    return { ok: true, data: { url: base } };
+                try {
+                    const u = new URL(base);
+                    u.port = String(normalizedPort);
+                    return { ok: true, data: { url: u.toString().replace(/\/+$/, "") } };
+                }
+                catch {
+                    return { ok: true, data: { url: `${base}:${normalizedPort}` } };
+                }
+            }
+            return { ok: false, error: "sandbox_port_url_not_supported" };
+        }
+        catch (e) {
+            return { ok: false, error: formatInstantSchemaError(e) };
+        }
+    }
     static parseSpritesCheckpointIdFromNdjson(text) {
         const lines = String(text ?? "")
             .split("\n")
@@ -909,6 +2191,33 @@ export class SandboxService {
                 sandbox_sandboxes: { $: { where: { id: sandboxId }, limit: 1 } },
             });
             const record = recordResult?.sandbox_sandboxes?.[0];
+            if (record?.externalSandboxId && record.provider === "vercel") {
+                const sandboxResult = await this.reconnectToSandbox(sandboxId);
+                if (!sandboxResult.ok)
+                    return { ok: false, error: sandboxResult.error };
+                const sandbox = sandboxResult.data.sandbox;
+                if (!isVercelSandbox(sandbox))
+                    return { ok: false, error: "checkpoint_not_supported" };
+                const expiration = Number(record?.params?.vercel?.snapshotExpirationMs);
+                const snapshot = await sandbox.snapshot({
+                    ...(Number.isFinite(expiration) ? { expiration } : {}),
+                });
+                const checkpointId = String(snapshot?.snapshotId ?? "").trim();
+                if (!checkpointId)
+                    return { ok: false, error: "vercel_snapshot_id_missing" };
+                await this.adminDb.transact(this.adminDb.tx.sandbox_sandboxes[sandboxId].update({
+                    updatedAt: Date.now(),
+                    params: {
+                        ...(record.params ?? {}),
+                        vercel: {
+                            ...(record.params?.vercel ?? {}),
+                            lastCheckpointId: checkpointId,
+                            lastCheckpointComment: String(params?.comment ?? "").trim() || undefined,
+                        },
+                    },
+                }));
+                return { ok: true, data: { checkpointId } };
+            }
             if (!record?.externalSandboxId || record.provider !== "sprites") {
                 return { ok: false, error: "checkpoint_not_supported" };
             }
@@ -950,6 +2259,21 @@ export class SandboxService {
                 sandbox_sandboxes: { $: { where: { id: sandboxId }, limit: 1 } },
             });
             const record = recordResult?.sandbox_sandboxes?.[0];
+            if (record?.externalSandboxId && record.provider === "vercel") {
+                const creds = await SandboxService.resolveVercelCredentials(record?.params ?? {});
+                const listed = await VercelSnapshot.list({
+                    teamId: creds.teamId,
+                    projectId: creds.projectId,
+                    token: creds.token,
+                    name: String(record.externalSandboxId),
+                    limit: 50,
+                    sortOrder: "desc",
+                });
+                const checkpointIds = (listed.snapshots ?? [])
+                    .map((snapshot) => String(snapshot?.id ?? "").trim())
+                    .filter(Boolean);
+                return { ok: true, data: { checkpointIds } };
+            }
             if (!record?.externalSandboxId || record.provider !== "sprites") {
                 return { ok: false, error: "checkpoint_not_supported" };
             }