@ekairos/sandbox 1.21.53-beta.0

package/README.md

@@ -0,0 +1,240 @@
+
+# @ekairos/sandbox
+
+Server-side utilities to provision and manage external sandboxes through a single, provider-agnostic interface.
+
+This package is **independent**. Other packages (e.g. `@ekairos/dataset`) may depend on it, but `@ekairos/sandbox` does not depend on any workflow framework.
+
+---
+
+## Installation (pnpm)
+
+```bash
+pnpm add @ekairos/sandbox
+```
+
+---
+
+## Environment variables (required)
+
+### InstantDB (admin)
+You must provide an InstantDB **admin** database client so sandbox actions can persist and query sandbox records.
+
+---
+
+## Data model (InstantDB)
+
+### `sandboxDomain`
+Defines a single entity:
+
+- `sandbox_sandboxes`
+
+Fields (high-level):
+- `externalSandboxId` (string, indexed): provider sandbox id (Vercel `sandbox.sandboxId`)
+- `provider` (string, indexed): e.g. `"vercel"`
+- `sandboxUrl` (string, optional): optional URL metadata
+- `status` (string, indexed): `"creating" | "active" | "shutdown" | "error" | ...`
+- `timeout` (number, optional): milliseconds
+- `runtime` (string, optional): `"node22" | "python3" | ...`
+- `vcpus` (number, optional)
+- `ports` (json, optional): array of ports
+- `purpose` (string, optional, indexed)
+- `params` (json, optional)
+- timestamps: `createdAt`, `updatedAt`, `shutdownAt`
+
+---
+
+## ID semantics (important)
+
+There are two ids involved:
+
+### 1) `sandboxId` (internal, durable handle)
+- The **InstantDB record id**: `sandbox_sandboxes[sandboxId]`
+- This is the id you store in durable state and pass around.
+- All sandbox actions and helpers take this `sandboxId`.
+
+### 2) `externalSandboxId` (provider id)
+- The id returned by the provider SDK (Vercel Sandbox `sandbox.sandboxId`)
+- Stored on the record as `externalSandboxId`
+- Used internally to call `Sandbox.get(...)` during reconnect.
+
+---
+
+## Schema integration
+
+In your app schema, include `sandboxDomain` along with other domains, then initialize Instant with the composed schema.
+
+Example:
+
+```ts
+import { domain } from "@ekairos/domain";
+import { sandboxDomain } from "@ekairos/sandbox";
+// import { storyDomain } from "@ekairos/story" (if you use stories)
+// import { datasetDomain } from "@ekairos/dataset" (if you use dataset)
+
+export const appDomain = domain("app")
+  .includes(sandboxDomain)
+  // .includes(storyDomain)
+  // .includes(datasetDomain)
+  .schema({
+    entities: {},
+    links: {},
+    rooms: {},
+  });
+
+export const schema = appDomain.toInstantSchema();
+```
+
+---
+
+## Exports
+
+This package exports:
+
+- `sandboxDomain` (schema domain + actions factory)
+- `runCommandInSandbox` (low-level helper)
+- Types (for TypeScript users): `SandboxConfig`, `SandboxRecord`, `ServiceResult<T>`, `CommandResult`
+
+---
+
+## Quickstart
+
+This package gives you a **persisted sandbox record** (`sandboxId`) and helpers to (re)connect and run commands.
+
+### 1) Instantiate the service (server-side)
+
+```ts
+import { init } from "@instantdb/admin";
+import { sandboxDomain } from "@ekairos/sandbox";
+
+const db = init({
+  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID,
+  adminToken: process.env.INSTANT_APP_ADMIN_TOKEN,
+  schema: {}, // your composed schema that includes sandboxDomain
+});
+
+const sandboxes = sandboxDomain(db);
+```
+
+### 2) Create a persisted sandbox
+
+```ts
+const created = await sandboxes.createSandbox({
+  runtime: "python3",
+  timeout: 10 * 60 * 1000,
+  resources: { vcpus: 2 },
+  purpose: "dataset-file-parse",
+  params: { datasetId: "..." },
+});
+
+if (!created.ok) throw new Error(created.error);
+
+const { sandboxId } = created.data;
+// Persist sandboxId in your app for continuity.
+```
+
+### 3) Run commands by `sandboxId` (recommended)
+
+```ts
+// Preferred DX: bind sandboxId once
+const sandbox = sandboxes.getSandbox(sandboxId);
+
+const res = await sandbox.runCommand("python", ["-c", "print('hello')"]);
+if (!res.ok) throw new Error(res.error);
+
+console.log(res.data.exitCode, res.data.output);
+```
+
+### 4) Reconnect (when you need the runtime object)
+
+```ts
+const sandbox = sandboxes.getSandbox(sandboxId);
+
+const rec = await sandbox.reconnect();
+if (!rec.ok) throw new Error(rec.error);
+
+const { sandbox } = rec.data;
+// Use sandbox.runCommand(...) / sandbox.writeFiles(...) / etc.
+```
+
+### 5) Stop (optional)
+
+```ts
+const sandbox = sandboxes.getSandbox(sandboxId);
+
+const stopped = await sandbox.stop();
+if (!stopped.ok) throw new Error(stopped.error);
+```
+
+---
+
+## Behavioral notes
+
+### `createSandbox(config)`
+- Creates an InstantDB record `sandbox_sandboxes[sandboxId]` with status `"creating"`.
+- Provisions a provider sandbox (provider-specific).
+- Updates the record to status `"active"` and stores `externalSandboxId` (provider sandbox id).
+
+### `reconnectToSandbox(sandboxId)`
+- Loads the record by internal `sandboxId`.
+- Validates:
+  - record exists
+  - `externalSandboxId` exists
+- Reconnects using the provider SDK/client (provider-specific).
+- Returns `ok: false` if sandbox is not found/not running.
+- If reconnection fails and the record was `"active"`, it may mark the record as `"shutdown"`.
+
+### `runCommand(sandboxId, command, args?)`
+- Durable-friendly command execution.
+- Attempts to reconnect; if unavailable it may recreate the sandbox from the stored record configuration and retry.
+- Returns a capped output payload suitable for storing in logs.
+
+### `stopSandbox(sandboxId)`
+- Attempts to reconnect and stop the provider sandbox.
+- Marks the record as `"shutdown"` regardless (the provider sandbox may already be gone).
+
+---
+
+## Usage
+The examples above cover the typical flows. When integrating in a real app, prefer `runCommand()` (provider-agnostic) and only call `reconnectToSandbox()` when you need direct access to the provider runtime object.
+
+```ts
+// Preferred: bind sandboxId once
+const sandbox = sandboxes.getSandbox(sandboxId);
+
+// Typical: run a command
+await sandbox.runCommand("python", ["-c", "print('hello')"]);
+
+// Advanced: reconnect for direct provider access
+const rec = await sandbox.reconnect();
+if (rec.ok) {
+  const { sandbox } = rec.data;
+  await sandbox.runCommand({ cmd: "echo", args: ["ok"] });
+}
+```
+
+---
+
+## Providers
+
+This package is designed to support multiple sandbox providers behind the same interface.
+
+### Vercel Sandbox (current provider)
+
+Environment variables:
+- `SANDBOX_VERCEL_TEAM_ID`
+- `SANDBOX_VERCEL_PROJECT_ID`
+- `SANDBOX_VERCEL_TOKEN`
+
+Provider behavior notes:
+- `externalSandboxId` maps to Vercel's sandbox id (e.g. `sandbox.sandboxId`).
+- Reconnect is done via `Sandbox.get(...)` using the stored `externalSandboxId`.
+
+### Ekairos Cloud (planned provider)
+
+Ekairos Cloud will provide sandboxes behind the same interface as the Vercel provider.
+It will be configured via an API key and act as a thin wrapper.
+
+Environment variables (planned):
+- `EKAIROS_CLOUD_API_KEY`
+

package/dist/commands.d.ts

@@ -0,0 +1,16 @@
+import { Sandbox } from "@vercel/sandbox";
+export interface CommandResult {
+    success: boolean;
+    exitCode?: number;
+    output?: string;
+    error?: string;
+    streamingLogs?: unknown[];
+    command?: string;
+}
+/**
+ * Ejecuta un comando en un sandbox.
+ *
+ * Nota: sin logs con interpolación para respetar reglas del repo.
+ */
+export declare function runCommandInSandbox(sandbox: Sandbox, command: string, args?: string[]): Promise<CommandResult>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAEzC,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,aAAa,CAAC,EAAE,OAAO,EAAE,CAAA;IACzB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,EAAO,GAClB,OAAO,CAAC,aAAa,CAAC,CAsBxB"}

package/dist/commands.js

@@ -0,0 +1,27 @@
+/**
+ * Ejecuta un comando en un sandbox.
+ *
+ * Nota: sin logs con interpolación para respetar reglas del repo.
+ */
+export async function runCommandInSandbox(sandbox, command, args = []) {
+    try {
+        // @vercel/sandbox soporta { cmd, args } en runCommand
+        const result = await sandbox.runCommand({ cmd: command, args });
+        const stdout = (await result.stdout()) ?? "";
+        const stderr = (await result.stderr()) ?? "";
+        const fullCommand = args.length > 0 ? [command, ...args].join(" ") : command;
+        return {
+            success: (result.exitCode ?? 0) === 0,
+            exitCode: result.exitCode ?? 0,
+            output: stdout,
+            error: stderr,
+            command: fullCommand,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const fullCommand = args.length > 0 ? [command, ...args].join(" ") : command;
+        return { success: false, error: message, command: fullCommand };
+    }
+}
+//# sourceMappingURL=commands.js.map

package/dist/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAgB,EAChB,OAAe,EACf,OAAiB,EAAE;IAEnB,IAAI,CAAC;QACH,sDAAsD;QACtD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAA;QAE/D,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAA;QAC5C,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAA;QAE5C,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAA;QAE5E,OAAO;YACL,OAAO,EAAE,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC,KAAK,CAAC;YACrC,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,CAAC;YAC9B,MAAM,EAAE,MAAM;YACd,KAAK,EAAE,MAAM;YACb,OAAO,EAAE,WAAW;SACrB,CAAA;IACH,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACtE,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAA;QAC5E,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,CAAA;IACjE,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { SandboxConfig, SandboxId, SandboxProvider, SandboxRunCommandResult, } from "./types.js";
+export { sandboxDomain } from "./schema.js";
+export { SandboxService } from "./service.js";
+export type { CommandResult } from "./commands.js";
+export { runCommandInSandbox } from "./commands.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,aAAa,EACb,SAAS,EACT,eAAe,EACf,uBAAuB,GACxB,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { sandboxDomain } from "./schema.js";
+export { SandboxService } from "./service.js";
+export { runCommandInSandbox } from "./commands.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAE7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA"}

package/dist/runtime.d.ts

@@ -0,0 +1,11 @@
+export type SandboxRuntime = {
+    /**
+     * Instant Admin DB (or compatible) that contains `sandbox_sandboxes`.
+     */
+    db: any;
+};
+export type SandboxRuntimeResolver = () => Promise<SandboxRuntime> | SandboxRuntime;
+export declare function configureSandboxRuntime(resolver: SandboxRuntimeResolver): void;
+export declare function isSandboxRuntimeConfigured(): boolean;
+export declare function resolveSandboxRuntime(): Promise<SandboxRuntime>;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,EAAE,EAAE,GAAG,CAAA;CACR,CAAA;AAED,MAAM,MAAM,sBAAsB,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAAA;AAInF,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,sBAAsB,QAEvE;AAED,wBAAgB,0BAA0B,YAEzC;AAED,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,cAAc,CAAC,CAMrE"}

package/dist/runtime.js

@@ -0,0 +1,14 @@
+let runtimeResolver = null;
+export function configureSandboxRuntime(resolver) {
+    runtimeResolver = resolver;
+}
+export function isSandboxRuntimeConfigured() {
+    return Boolean(runtimeResolver);
+}
+export async function resolveSandboxRuntime() {
+    if (!runtimeResolver) {
+        throw new Error("Sandbox runtime is not configured.");
+    }
+    return await runtimeResolver();
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AASA,IAAI,eAAe,GAAkC,IAAI,CAAA;AAEzD,MAAM,UAAU,uBAAuB,CAAC,QAAgC;IACtE,eAAe,GAAG,QAAQ,CAAA;AAC5B,CAAC;AAED,MAAM,UAAU,0BAA0B;IACxC,OAAO,OAAO,CAAC,eAAe,CAAC,CAAA;AACjC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB;IACzC,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAA;IACvD,CAAC;IAED,OAAO,MAAM,eAAe,EAAE,CAAA;AAChC,CAAC"}

package/dist/schema.d.ts

@@ -0,0 +1,18 @@
+export declare const sandboxDomain: import("@ekairos/domain").DomainSchemaResult<{
+    sandbox_sandboxes: import("@instantdb/core").EntityDef<{
+        externalSandboxId: import("@instantdb/core").DataAttrDef<string, false, true>;
+        provider: import("@instantdb/core").DataAttrDef<string, true, true>;
+        sandboxUrl: import("@instantdb/core").DataAttrDef<string, false, false>;
+        status: import("@instantdb/core").DataAttrDef<string, true, true>;
+        timeout: import("@instantdb/core").DataAttrDef<number, false, false>;
+        runtime: import("@instantdb/core").DataAttrDef<string, false, false>;
+        vcpus: import("@instantdb/core").DataAttrDef<number, false, false>;
+        ports: import("@instantdb/core").DataAttrDef<any, false, false>;
+        purpose: import("@instantdb/core").DataAttrDef<string, false, true>;
+        params: import("@instantdb/core").DataAttrDef<any, false, false>;
+        createdAt: import("@instantdb/core").DataAttrDef<number, true, true>;
+        updatedAt: import("@instantdb/core").DataAttrDef<number, false, true>;
+        shutdownAt: import("@instantdb/core").DataAttrDef<number, false, true>;
+    }, {}, void>;
+}, {}, import("@instantdb/core").RoomsDef>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;0CAoBxB,CAAA"}

package/dist/schema.js

@@ -0,0 +1,25 @@
+import { i } from "@instantdb/core";
+import { domain } from "@ekairos/domain";
+// Port de `ekairos-core/src/lib/domain/sandbox/schema.ts`
+export const sandboxDomain = domain("sandbox").schema({
+    entities: {
+        sandbox_sandboxes: i.entity({
+            externalSandboxId: i.string().optional().indexed(),
+            provider: i.string().indexed(),
+            sandboxUrl: i.string().optional(),
+            status: i.string().indexed(),
+            timeout: i.number().optional(),
+            runtime: i.string().optional(),
+            vcpus: i.number().optional(),
+            ports: i.json().optional(),
+            purpose: i.string().optional().indexed(),
+            params: i.json().optional(),
+            createdAt: i.number().indexed(),
+            updatedAt: i.number().optional().indexed(),
+            shutdownAt: i.number().optional().indexed(),
+        }),
+    },
+    links: {},
+    rooms: {},
+});
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAA;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAExC,0DAA0D;AAC1D,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC;IACpD,QAAQ,EAAE;QACR,iBAAiB,EAAE,CAAC,CAAC,MAAM,CAAC;YAC1B,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE;YAClD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE;YAC9B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YACjC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE;YAC5B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAC9B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAC9B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAC5B,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE;YAC1B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE;YACxC,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE;YAC3B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE;YAC/B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE;YAC1C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE;SAC5C,CAAC;KACH;IACD,KAAK,EAAE,EAAE;IACT,KAAK,EAAE,EAAE;CACV,CAAC,CAAA"}

package/dist/service.d.ts

@@ -0,0 +1,53 @@
+import { Sandbox } from "@vercel/sandbox";
+import { type InstantAdminDatabase } from "@instantdb/admin";
+import { SchemaOf } from "@ekairos/domain";
+import { type CommandResult } from "./commands.js";
+import { sandboxDomain } from "./schema.js";
+import type { SandboxConfig } from "./types.js";
+type SandboxSchemaType = SchemaOf<typeof sandboxDomain>;
+export interface SandboxRecord {
+    id: string;
+    externalSandboxId?: string;
+    provider: string;
+    sandboxUrl?: string;
+    status: "creating" | "active" | "shutdown" | "error" | "recreating";
+    timeout?: number;
+    runtime?: string;
+    vcpus?: number;
+    ports?: number[];
+    purpose?: string;
+    params?: Record<string, any>;
+    createdAt: number;
+    updatedAt?: number;
+    shutdownAt?: number;
+}
+export type ServiceResult<T = any> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+};
+export declare class SandboxService {
+    private adminDb;
+    constructor(db: InstantAdminDatabase<SandboxSchemaType>);
+    private static getVercelCredentials;
+    private static provisionVercelSandbox;
+    createSandbox(config: SandboxConfig): Promise<ServiceResult<{
+        sandboxId: string;
+    }>>;
+    reconnectToSandbox(sandboxId: string): Promise<ServiceResult<{
+        sandbox: Sandbox;
+    }>>;
+    stopSandbox(sandboxId: string): Promise<ServiceResult<void>>;
+    runCommand(sandboxId: string, command: string, args?: string[]): Promise<ServiceResult<CommandResult>>;
+    writeFiles(sandboxId: string, files: Array<{
+        path: string;
+        contentBase64: string;
+    }>): Promise<ServiceResult<void>>;
+    readFile(sandboxId: string, path: string): Promise<ServiceResult<{
+        contentBase64: string;
+    }>>;
+}
+export {};
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AACzC,OAAO,EAAM,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC1C,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAA;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,KAAK,iBAAiB,GAAG,QAAQ,CAAC,OAAO,aAAa,CAAC,CAAA;AAEvD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,GAAG,YAAY,CAAA;IACnE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,GAAG,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AA4BzF,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAyC;gBAE5C,EAAE,EAAE,oBAAoB,CAAC,iBAAiB,CAAC;IAIvD,OAAO,CAAC,MAAM,CAAC,oBAAoB;mBAYd,sBAAsB;IAgBrC,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAiDnF,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAoDnF,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAyB5D,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC;IAY1G,UAAU,CACd,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,GACpD,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAkBzB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CA4BnG"}

package/dist/service.js

@@ -0,0 +1,219 @@
+import { Sandbox } from "@vercel/sandbox";
+import { id } from "@instantdb/admin";
+import { runCommandInSandbox } from "./commands.js";
+function formatInstantSchemaError(err) {
+    const base = err instanceof Error ? err.message : String(err);
+    const body = err?.body;
+    const hintErrors = body?.hint?.errors;
+    if (!Array.isArray(hintErrors) || hintErrors.length === 0) {
+        return base;
+    }
+    const missingAttrs = [];
+    for (const he of hintErrors) {
+        const attrs = he?.hint?.attributes;
+        if (Array.isArray(attrs)) {
+            for (const a of attrs) {
+                if (typeof a === "string")
+                    missingAttrs.push(a);
+            }
+        }
+    }
+    const uniq = Array.from(new Set(missingAttrs));
+    if (uniq.length === 0)
+        return base;
+    // Keep it short + copy/paste friendly for debugging schema issues.
+    return base + " | missing attributes: " + uniq.join(", ");
+}
+export class SandboxService {
+    constructor(db) {
+        this.adminDb = db;
+    }
+    static getVercelCredentials() {
+        const teamId = String(process.env.SANDBOX_VERCEL_TEAM_ID ?? "").trim();
+        const projectId = String(process.env.SANDBOX_VERCEL_PROJECT_ID ?? "").trim();
+        const token = String(process.env.SANDBOX_VERCEL_TOKEN ?? "").trim();
+        if (!teamId || !projectId || !token) {
+            throw new Error("Missing required Vercel sandbox environment variables");
+        }
+        return { teamId, projectId, token };
+    }
+    static async provisionVercelSandbox(config) {
+        const creds = SandboxService.getVercelCredentials();
+        return await Sandbox.create({
+            teamId: creds.teamId,
+            projectId: creds.projectId,
+            token: creds.token,
+            timeout: config.timeoutMs ?? 5 * 60 * 1000,
+            ports: Array.isArray(config.ports) ? config.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 },
+        });
+    }
+    async createSandbox(config) {
+        const sandboxId = id();
+        const now = Date.now();
+        try {
+            await this.adminDb.transact(this.adminDb.tx.sandbox_sandboxes[sandboxId].update({
+                status: "creating",
+                provider: "vercel",
+                timeout: config.timeoutMs,
+                runtime: config.runtime,
+                vcpus: config.resources?.vcpus,
+                ports: config.ports,
+                purpose: config.purpose,
+                params: config.params,
+                createdAt: now,
+                updatedAt: now,
+            }));
+            let sandbox;
+            try {
+                sandbox = await SandboxService.provisionVercelSandbox(config);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                await this.adminDb.transact(this.adminDb.tx.sandbox_sandboxes[sandboxId].update({
+                    status: "error",
+                    updatedAt: Date.now(),
+                    params: { ...(config.params ?? {}), error: msg },
+                }));
+                return { ok: false, error: msg };
+            }
+            await this.adminDb.transact(this.adminDb.tx.sandbox_sandboxes[sandboxId].update({
+                status: "active",
+                externalSandboxId: sandbox.sandboxId,
+                updatedAt: Date.now(),
+            }));
+            return { ok: true, data: { sandboxId } };
+        }
+        catch (e) {
+            return { ok: false, error: formatInstantSchemaError(e) };
+        }
+    }
+    async reconnectToSandbox(sandboxId) {
+        try {
+            const recordResult = await this.adminDb.query({
+                sandbox_sandboxes: { $: { where: { id: sandboxId }, limit: 1 } },
+            });
+            const record = recordResult?.sandbox_sandboxes?.[0];
+            if (!record || !record.externalSandboxId || record.provider !== "vercel") {
+                return { ok: false, error: "Valid sandbox record not found" };
+            }
+            const creds = SandboxService.getVercelCredentials();
+            try {
+                const maxAttempts = 20;
+                const delayMs = 500;
+                for (let attempt = 0; attempt < maxAttempts; attempt++) {
+                    const sandbox = await Sandbox.get({
+                        sandboxId: String(record.externalSandboxId),
+                        teamId: creds.teamId,
+                        projectId: creds.projectId,
+                        token: creds.token,
+                    });
+                    if (!sandbox)
+                        return { ok: false, error: "Sandbox not found" };
+                    if (sandbox.status === "running") {
+                        return { ok: true, data: { sandbox } };
+                    }
+                    await new Promise((r) => setTimeout(r, delayMs));
+                }
+                return { ok: false, error: "Sandbox not active" };
+            }
+            catch (e) {
+                if (record.status === "active") {
+                    await this.adminDb.transact(this.adminDb.tx.sandbox_sandboxes[sandboxId].update({
+                        status: "shutdown",
+                        shutdownAt: Date.now(),
+                        updatedAt: Date.now(),
+                    }));
+                }
+                const msg = e instanceof Error ? e.message : String(e);
+                return { ok: false, error: msg };
+            }
+        }
+        catch (e) {
+            return { ok: false, error: formatInstantSchemaError(e) };
+        }
+    }
+    async stopSandbox(sandboxId) {
+        try {
+            const result = await this.reconnectToSandbox(sandboxId);
+            if (result.ok) {
+                try {
+                    await result.data.sandbox.stop();
+                }
+                catch {
+                    // ignore
+                }
+            }
+            await this.adminDb.transact(this.adminDb.tx.sandbox_sandboxes[sandboxId].update({
+                status: "shutdown",
+                shutdownAt: Date.now(),
+                updatedAt: Date.now(),
+            }));
+            return { ok: true, data: undefined };
+        }
+        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 result = await runCommandInSandbox(sandboxResult.data.sandbox, command, args);
+            return { ok: true, data: result };
+        }
+        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 };
+            await sandboxResult.data.sandbox.writeFiles(files.map((f) => ({
+                path: f.path,
+                content: Buffer.from(f.contentBase64, "base64"),
+            })));
+            return { ok: true, data: undefined };
+        }
+        catch (e) {
+            return { ok: false, error: formatInstantSchemaError(e) };
+        }
+    }
+    async readFile(sandboxId, path) {
+        try {
+            const sandboxResult = await this.reconnectToSandbox(sandboxId);
+            if (!sandboxResult.ok)
+                return { ok: false, error: sandboxResult.error };
+            const stream = await sandboxResult.data.sandbox.readFile({ path });
+            if (!stream) {
+                return { ok: true, data: { contentBase64: "" } };
+            }
+            const chunks = [];
+            for await (const chunk of stream) {
+                if (typeof chunk === "string") {
+                    chunks.push(Buffer.from(chunk, "utf-8"));
+                }
+                else if (chunk instanceof Uint8Array) {
+                    chunks.push(Buffer.from(chunk));
+                }
+                else if (chunk instanceof ArrayBuffer) {
+                    chunks.push(Buffer.from(chunk));
+                }
+                else if (chunk) {
+                    chunks.push(Buffer.from(chunk));
+                }
+            }
+            return { ok: true, data: { contentBase64: Buffer.concat(chunks).toString("base64") } };
+        }
+        catch (e) {
+            return { ok: false, error: formatInstantSchemaError(e) };
+        }
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/dist/steps.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=steps.d.ts.map

package/dist/steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../src/steps.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAA"}

package/dist/steps.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=steps.js.map

package/dist/steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../src/steps.ts"],"names":[],"mappings":""}

package/dist/types.d.ts

@@ -0,0 +1,24 @@
+export type SandboxId = string;
+export type SandboxConfig = {
+    /**
+     * Provider runtime, e.g. "python3.13", "node22"
+     */
+    runtime?: string;
+    /**
+     * Max lifetime in ms.
+     */
+    timeoutMs?: number;
+    ports?: number[];
+    resources?: {
+        vcpus?: number;
+    };
+    purpose?: string;
+    params?: Record<string, any>;
+};
+export type SandboxRunCommandResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+export type SandboxProvider = "vercel";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAE9B,MAAM,MAAM,aAAa,GAAG;IAC1B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,SAAS,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAA"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@ekairos/sandbox",
+  "version": "1.21.53-beta.0",
+  "description": "Pulzar Sandbox - Provider-agnostic sandbox helpers",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pulz-ar/pulzar-lib-core.git",
+    "directory": "packages/sandbox"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "clean": "node -e \"require('fs').rmSync('dist', {recursive:true, force:true})\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ekairos/domain": "^1.21.53-beta.0",
+    "@instantdb/admin": "^0.22.13",
+    "@instantdb/core": "^0.22.13",
+    "@vercel/sandbox": "^0.0.23",
+    "zod": "^4.1.8"
+  },
+  "devDependencies": {
+    "@ekairos/tsconfig": "workspace:*",
+    "@types/node": "^24.5.0",
+    "typescript": "^5.9.2"
+  }
+}