@larkup/sandbox 0.1.1 → 0.1.3

package/src/registry.ts

@@ -0,0 +1,308 @@
+import type { SandboxBackend, SandboxProviderDescriptor } from './types.js';
+
+/**
+ * Declarative registry of the remote sandbox providers @larkup/sandbox can
+ * execute code on, besides the always-available local Docker backend.
+ *
+ * This single object powers two consumers:
+ *  1. The Settings UI — renders `fields` dynamically so each provider asks
+ *     for exactly the credentials it needs, the same way vector store and
+ *     embedding provider fields are rendered from their own registries.
+ *  2. `SandboxManager` / the provider adapters — read `id` to route
+ *     execution and `executionSupport` to fail fast with a clear message
+ *     instead of pretending every provider can run arbitrary code.
+ *
+ * Adding a new provider = one entry here + one adapter in `./providers`.
+ */
+export const SANDBOX_PROVIDERS: Record<
+  Exclude<SandboxBackend, 'local' | 'docker' | 'custom'>,
+  SandboxProviderDescriptor
+> = {
+  e2b: {
+    id: 'e2b',
+    label: 'E2B',
+    description:
+      'Firecracker-microVM sandboxes purpose-built for AI code execution, with fast cold starts.',
+    sdkPackage: 'e2b',
+    docsUrl: 'https://docs.e2b.dev/',
+    icon: '/icons/e2b.png',
+    executionSupport: 'full',
+    fields: [
+      {
+        key: 'apiKey',
+        label: 'API key',
+        type: 'password',
+        required: true,
+        secret: true,
+        placeholder: 'e2b_...',
+        help: 'From the E2B dashboard. Equivalent to the E2B_API_KEY environment variable.',
+      },
+      {
+        key: 'snapshotId',
+        label: 'Snapshot or template ID',
+        type: 'text',
+        required: false,
+        help: 'Optional prebuilt environment with your required packages. New executions start from it.',
+      },
+    ],
+  },
+
+  vercel: {
+    id: 'vercel',
+    label: 'Vercel Sandbox',
+    description:
+      'Isolated Firecracker microVMs for running arbitrary or untrusted code, billed through your Vercel account.',
+    sdkPackage: '@vercel/sandbox',
+    docsUrl: 'https://vercel.com/docs/sandbox',
+    icon: '/icons/vercel.svg',
+    executionSupport: 'full',
+    fields: [
+      {
+        key: 'token',
+        label: 'Access token',
+        type: 'password',
+        required: true,
+        secret: true,
+        help: 'Vercel access token with Sandbox permissions. Equivalent to VERCEL_TOKEN.',
+      },
+      {
+        key: 'teamId',
+        label: 'Team ID',
+        type: 'text',
+        required: true,
+        placeholder: 'team_...',
+        help: 'Found in Vercel Team Settings. Equivalent to VERCEL_TEAM_ID.',
+      },
+      {
+        key: 'projectId',
+        label: 'Project ID',
+        type: 'text',
+        required: true,
+        placeholder: 'prj_...',
+        help: 'The Vercel project sandboxes run under. Equivalent to VERCEL_PROJECT_ID.',
+      },
+      {
+        key: 'snapshotId',
+        label: 'Snapshot ID',
+        type: 'text',
+        required: false,
+        help: 'Optional Vercel snapshot to restore for each execution.',
+      },
+    ],
+  },
+
+  modal: {
+    id: 'modal',
+    label: 'Modal',
+    description:
+      'Sandboxes for executing untrusted user or agent code in secure containers on Modal’s compute platform.',
+    sdkPackage: 'modal',
+    docsUrl: 'https://modal.com/docs/guide/sandboxes',
+    icon: '/icons/modal.png',
+    executionSupport: 'full',
+    fields: [
+      {
+        key: 'tokenId',
+        label: 'Token ID',
+        type: 'text',
+        required: true,
+        placeholder: 'ak-...',
+        help: 'From `modal setup` or the Modal dashboard. Equivalent to MODAL_TOKEN_ID.',
+      },
+      {
+        key: 'tokenSecret',
+        label: 'Token secret',
+        type: 'password',
+        required: true,
+        secret: true,
+        placeholder: 'as-...',
+        help: 'Equivalent to MODAL_TOKEN_SECRET.',
+      },
+    ],
+  },
+
+  daytona: {
+    id: 'daytona',
+    label: 'Daytona',
+    description:
+      'Elastic infrastructure for running AI-generated code in fast, isolated sandboxes.',
+    sdkPackage: '@daytonaio/sdk',
+    docsUrl: 'https://www.daytona.io/docs/en/sandboxes/',
+    icon: '/icons/daytonaio.png',
+    executionSupport: 'full',
+    fields: [
+      {
+        key: 'apiKey',
+        label: 'API key',
+        type: 'password',
+        required: true,
+        secret: true,
+        help: 'From the Daytona dashboard. Equivalent to DAYTONA_API_KEY.',
+      },
+      {
+        key: 'apiUrl',
+        label: 'API URL',
+        type: 'text',
+        required: false,
+        placeholder: 'https://app.daytona.io/api',
+        help: 'Only needed for a self-hosted Daytona instance.',
+      },
+      {
+        key: 'snapshot',
+        label: 'Snapshot',
+        type: 'text',
+        required: false,
+        help: 'Optional Daytona snapshot containing the dependencies your agent needs.',
+      },
+    ],
+  },
+
+  browserbase: {
+    id: 'browserbase',
+    label: 'Browserbase',
+    description: 'Headless-Chrome browser sessions for Playwright/Puppeteer automation.',
+    sdkPackage: '@browserbasehq/sdk',
+    docsUrl: 'https://docs.browserbase.com/welcome/introduction',
+    icon: '/icons/browserbase.png',
+    executionSupport: 'unsupported',
+    executionCaveat:
+      'Browserbase provisions remote browser sessions reachable over CDP for Playwright/Puppeteer — it does not run arbitrary Python/JS and return stdout the way a code-execution sandbox does. Verify still checks your API key and project, but code-execution tools (data analysis, corpus analytics) need a different provider.',
+    fields: [
+      {
+        key: 'apiKey',
+        label: 'API key',
+        type: 'password',
+        required: true,
+        secret: true,
+        help: 'Equivalent to BROWSERBASE_API_KEY.',
+      },
+      {
+        key: 'projectId',
+        label: 'Project ID',
+        type: 'text',
+        required: true,
+        help: 'Equivalent to BROWSERBASE_PROJECT_ID.',
+      },
+    ],
+  },
+
+  flyio: {
+    id: 'flyio',
+    label: 'Fly.io Sprites',
+    description:
+      'Persistent, fast-suspending Linux VM sandboxes for AI agents, built on Fly Machines.',
+    sdkPackage: '@fly/sprites',
+    docsUrl: 'https://fly.io/sprites/',
+    icon: '/icons/flyio.jpeg',
+    executionSupport: 'full',
+    fields: [
+      {
+        key: 'token',
+        label: 'Sprite token',
+        type: 'password',
+        required: true,
+        secret: true,
+        help: 'From `sprite org auth` or the Fly dashboard. Equivalent to SPRITE_TOKEN.',
+      },
+    ],
+  },
+
+  northflank: {
+    id: 'northflank',
+    label: 'Northflank',
+    description: 'On-demand sandbox containers running as Northflank services in your own project.',
+    sdkPackage: '@northflank/js-client',
+    docsUrl: 'https://northflank.com/docs/v1/application/sandboxes/sandboxes-on-northflank',
+    icon: '/icons/Northflank.png',
+    executionSupport: 'full',
+    fields: [
+      {
+        key: 'token',
+        label: 'API token',
+        type: 'password',
+        required: true,
+        secret: true,
+        help: 'A personal or team API token from Northflank → Account → API Tokens.',
+      },
+      {
+        key: 'projectId',
+        label: 'Project ID',
+        type: 'text',
+        required: true,
+        help: 'The Northflank project sandbox services are created in.',
+      },
+    ],
+  },
+
+  cloudflare: {
+    id: 'cloudflare',
+    label: 'Cloudflare Sandbox',
+    description:
+      'Container sandboxes running inside a Cloudflare Worker via the Durable Object Sandbox SDK.',
+    sdkPackage: '@cloudflare/sandbox',
+    docsUrl: 'https://developers.cloudflare.com/sandbox/',
+    icon: '/icons/cloudflare.png',
+    executionSupport: 'unsupported',
+    executionCaveat:
+      '@cloudflare/sandbox only runs inside a Cloudflare Worker through a Durable Object binding declared in wrangler config. There is no external REST API to create or run commands in a sandbox from this server. Verify checks your account API token; actually running code here requires deploying a Worker with the Sandbox binding.',
+    fields: [
+      {
+        key: 'apiToken',
+        label: 'API token',
+        type: 'password',
+        required: true,
+        secret: true,
+        help: 'Used only to verify account access.',
+      },
+      {
+        key: 'accountId',
+        label: 'Account ID',
+        type: 'text',
+        required: true,
+      },
+    ],
+  },
+
+  webcontainers: {
+    id: 'webcontainers',
+    label: 'WebContainers',
+    description: 'In-browser WebAssembly Node.js runtime for running full-stack apps client-side.',
+    sdkPackage: '@webcontainer/api',
+    docsUrl: 'https://webcontainers.io/',
+    icon: '/icons/webcontainers.svg',
+    executionSupport: 'unsupported',
+    executionCaveat:
+      'WebContainers boots entirely inside a cross-origin-isolated browser tab (it needs SharedArrayBuffer). There is no Node.js/server-side way to run it, so this backend cannot execute code from here. Use @webcontainer/api directly in your frontend for in-browser execution instead.',
+    fields: [
+      {
+        key: 'apiKey',
+        label: 'License key (optional)',
+        type: 'password',
+        required: false,
+        secret: true,
+        help: 'StackBlitz-issued commercial key for production embeds. Leave blank for local/prototype use.',
+      },
+    ],
+  },
+};
+
+export const SANDBOX_PROVIDER_LIST: SandboxProviderDescriptor[] = Object.values(SANDBOX_PROVIDERS);
+
+export function getSandboxProvider(id: SandboxBackend): SandboxProviderDescriptor | undefined {
+  if (id === 'local' || id === 'docker' || id === 'custom') return undefined;
+  return SANDBOX_PROVIDERS[id];
+}
+
+/** Validates credentials against a provider's registered fields, mirroring validateStoreConfig. */
+export function validateSandboxCredentials(
+  provider: SandboxProviderDescriptor,
+  values: Record<string, string>,
+): Record<string, string> {
+  const errors: Record<string, string> = {};
+  for (const field of provider.fields) {
+    if (field.required && !values[field.key]?.trim()) {
+      errors[field.key] = `${field.label} is required`;
+    }
+  }
+  return errors;
+}

package/src/remote-exec.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, it, vi } from 'vitest';
+import { buildExecutionScript, failedResult, runScriptedExecution, withTimeout } from './remote-exec.js';
+import type { ExecutionRequest } from './types.js';
+
+describe('buildExecutionScript', () => {
+  it('writes the code to run.py and invokes python3 for python requests', () => {
+    const request: ExecutionRequest = { code: 'print(1)', language: 'python' };
+    const script = buildExecutionScript(request);
+    expect(script).toContain("mkdir -p '/tmp/larkup-sandbox/output'");
+    expect(script).toContain("base64 -d > 'run.py'");
+    expect(script).toContain("python3 'run.py'");
+    expect(script).not.toContain("node 'run.js'");
+  });
+
+  it('writes the code to run.js and invokes node for non-python requests', () => {
+    const request: ExecutionRequest = { code: 'console.log(1)', language: 'javascript' };
+    const script = buildExecutionScript(request);
+    expect(script).toContain("base64 -d > 'run.js'");
+    expect(script).toContain("node 'run.js'");
+  });
+
+  it('base64-encodes and stages every input file before running the code', () => {
+    const request: ExecutionRequest = {
+      code: 'x=1',
+      language: 'python',
+      files: [{ name: 'data.csv', content: 'a,b\n1,2' }],
+    };
+    const script = buildExecutionScript(request);
+    const expectedBase64 = Buffer.from('a,b\n1,2', 'utf8').toString('base64');
+    expect(script).toContain("base64 -d > 'data.csv'");
+    expect(script).toContain(expectedBase64);
+    // File staging must happen before the code executes.
+    expect(script.indexOf("'data.csv'")).toBeLessThan(script.indexOf("'run.py'"));
+  });
+
+  it('passes already-base64 file content through unmodified', () => {
+    const b64 = Buffer.from('binary-ish').toString('base64');
+    const request: ExecutionRequest = {
+      code: 'x=1',
+      language: 'python',
+      files: [{ name: 'blob.bin', content: b64, isBase64: true }],
+    };
+    const script = buildExecutionScript(request);
+    expect(script).toContain(b64);
+  });
+
+  it('single-quotes filenames so shell metacharacters cannot break out', () => {
+    const request: ExecutionRequest = {
+      code: 'x=1',
+      language: 'python',
+      files: [{ name: "weird'name.csv", content: 'a' }],
+    };
+    const script = buildExecutionScript(request);
+    expect(script).toContain(String.raw`'weird'\''name.csv'`);
+  });
+
+  it('rejects path-like input file names', () => {
+    expect(() =>
+      buildExecutionScript({
+        code: 'x=1',
+        language: 'python',
+        files: [{ name: '../escape.py', content: 'x' }],
+      }),
+    ).toThrow('Sandbox file names must be plain file names.');
+  });
+
+  it('emits an artifact marker line that lists the output directory', () => {
+    const script = buildExecutionScript({ code: 'x=1', language: 'python' });
+    expect(script).toContain('__LARKUP_ARTIFACTS__:');
+    expect(script).toContain("ls -1 '/tmp/larkup-sandbox/output'");
+  });
+});
+
+describe('runScriptedExecution', () => {
+  it('passes stdout/stderr/exitCode straight through when there are no artifacts', async () => {
+    const execFn = vi.fn().mockResolvedValue({ stdout: 'hello\n', stderr: '', exitCode: 0 });
+    const result = await runScriptedExecution(execFn, { code: 'print(1)', language: 'python' });
+
+    expect(execFn).toHaveBeenCalledTimes(1);
+    expect(result.stdout).toBe('hello\n');
+    expect(result.stderr).toBe('');
+    expect(result.exitCode).toBe(0);
+    expect(result.artifacts).toEqual([]);
+    expect(result.executionTimeMs).toBeGreaterThanOrEqual(0);
+  });
+
+  it('strips the artifact marker from stdout and fetches each named artifact', async () => {
+    const chartBase64 = Buffer.from('fake-png-bytes').toString('base64');
+    const execFn = vi
+      .fn()
+      .mockResolvedValueOnce({
+        stdout: 'analysis done\n__LARKUP_ARTIFACTS__:chart_0.png,chart_1.png\n',
+        stderr: '',
+        exitCode: 0,
+      })
+      .mockResolvedValueOnce({ stdout: chartBase64, stderr: '', exitCode: 0 })
+      .mockResolvedValueOnce({ stdout: chartBase64, stderr: '', exitCode: 0 });
+
+    const result = await runScriptedExecution(execFn, { code: 'x=1', language: 'python' });
+
+    expect(result.stdout).toBe('analysis done');
+    expect(execFn).toHaveBeenCalledTimes(3);
+    expect(result.artifacts).toHaveLength(2);
+    expect(result.artifacts[0]).toEqual({ name: 'chart_0.png', mimeType: 'image/png', data: chartBase64 });
+    expect(result.artifacts[1].name).toBe('chart_1.png');
+  });
+
+  it('drops an artifact whose follow-up fetch fails instead of failing the whole execution', async () => {
+    const execFn = vi
+      .fn()
+      .mockResolvedValueOnce({ stdout: '__LARKUP_ARTIFACTS__:missing.png\n', stderr: '', exitCode: 0 })
+      .mockRejectedValueOnce(new Error('file gone'));
+
+    const result = await runScriptedExecution(execFn, { code: 'x=1', language: 'python' });
+    expect(result.exitCode).toBe(0);
+    expect(result.artifacts).toEqual([]);
+  });
+
+  it('leaves a non-zero exit code and stderr message untouched', async () => {
+    const execFn = vi.fn().mockResolvedValue({ stdout: '', stderr: 'Traceback...', exitCode: 1 });
+    const result = await runScriptedExecution(execFn, { code: 'raise ValueError()', language: 'python' });
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toBe('Traceback...');
+  });
+});
+
+describe('withTimeout', () => {
+  it('resolves with the underlying value when it settles first', async () => {
+    await expect(withTimeout(Promise.resolve('ok'), 1000, 'test')).resolves.toBe('ok');
+  });
+
+  it('rejects with a labeled error once the timeout elapses', async () => {
+    vi.useFakeTimers();
+    try {
+      const never = new Promise(() => {});
+      const pending = withTimeout(never, 50, 'slow op');
+      const assertion = expect(pending).rejects.toThrow('slow op timed out after 50ms');
+      await vi.advanceTimersByTimeAsync(60);
+      await assertion;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe('failedResult', () => {
+  it('produces a normalized failure shape', () => {
+    const result = failedResult('boom', Date.now() - 5);
+    expect(result.exitCode).toBe(1);
+    expect(result.stdout).toBe('');
+    expect(result.stderr).toBe('boom');
+    expect(result.artifacts).toEqual([]);
+    expect(result.executionTimeMs).toBeGreaterThanOrEqual(0);
+  });
+});

package/src/remote-exec.ts

@@ -0,0 +1,190 @@
+/**
+ * Shared execution plumbing for every cloud sandbox adapter (E2B, Vercel
+ * Sandbox, Modal, Daytona, Fly Sprites, Northflank).
+ *
+ * Each of those providers exposes the same primitive — "run this shell
+ * command inside my sandbox and give me stdout/stderr/exitCode back" — but
+ * with a different SDK shape (commands.run, runCommand, exec, ...). Rather
+ * than re-implement file staging + artifact capture per provider, adapters
+ * plug their SDK's exec call in as a `RemoteExecFn` and hand it to
+ * `runScriptedExecution`, which builds one POSIX shell script that writes
+ * any input files, runs the code, and reports back any files written to an
+ * output directory (mirroring what the Docker adapter gets for free via a
+ * bind mount).
+ */
+
+import type { ExecutionArtifact, ExecutionRequest, ExecutionResult } from './types.js';
+import { getMimeType } from './mime.js';
+
+/** Default per-execution timeout for remote adapters when a request doesn't specify one. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+
+const WORKDIR = '/tmp/larkup-sandbox';
+const OUTPUT_DIR = `${WORKDIR}/output`;
+const ARTIFACT_MARKER = '__LARKUP_ARTIFACTS__:';
+/** Not part of the base64 alphabet, so it can never collide with an encoded file body. */
+const HEREDOC_DELIMITER = 'LARKUP__EOF__';
+
+export interface RemoteCommandResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/** Runs a single shell command/script inside a provider's sandbox instance. */
+export type RemoteExecFn = (script: string) => Promise<RemoteCommandResult>;
+
+function assertSafeFileName(name: string): void {
+  if (
+    !name ||
+    name === '.' ||
+    name === '..' ||
+    name.includes('/') ||
+    name.includes('\\') ||
+    name.includes('\0')
+  ) {
+    throw new Error('Sandbox file names must be plain file names.');
+  }
+}
+
+function shellSingleQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function writeBase64FileScript(name: string, base64: string): string {
+  return `base64 -d > ${shellSingleQuote(
+    name,
+  )} <<'${HEREDOC_DELIMITER}'\n${base64}\n${HEREDOC_DELIMITER}`;
+}
+
+/** Builds the POSIX shell script a remote adapter hands to its provider's exec call. */
+export function buildExecutionScript(request: ExecutionRequest): string {
+  const lines: string[] = [
+    'set -e',
+    `mkdir -p ${shellSingleQuote(OUTPUT_DIR)}`,
+    `cd ${shellSingleQuote(WORKDIR)}`,
+  ];
+
+  for (const file of request.files ?? []) {
+    assertSafeFileName(file.name);
+    const base64 = file.isBase64
+      ? file.content
+      : Buffer.from(file.content, 'utf8').toString('base64');
+    lines.push(writeBase64FileScript(file.name, base64));
+  }
+
+  const scriptName = request.language === 'python' ? 'run.py' : 'run.js';
+  const runner = request.language === 'python' ? 'python3' : 'node';
+  const codeBase64 = Buffer.from(request.code, 'utf8').toString('base64');
+  lines.push(writeBase64FileScript(scriptName, codeBase64));
+  lines.push(`${runner} ${shellSingleQuote(scriptName)}`);
+  lines.push(
+    `if [ -d ${shellSingleQuote(
+      OUTPUT_DIR,
+    )} ]; then echo "${ARTIFACT_MARKER}$(ls -1 ${shellSingleQuote(
+      OUTPUT_DIR,
+    )} 2>/dev/null | tr '\\n' ',')"; fi`,
+  );
+
+  return lines.join('\n');
+}
+
+function extractArtifactMarker(stdout: string): { stdout: string; artifactNames: string[] } {
+  const markerIndex = stdout.lastIndexOf(ARTIFACT_MARKER);
+  if (markerIndex === -1) return { stdout, artifactNames: [] };
+
+  const before = stdout.slice(0, markerIndex);
+  const after = stdout.slice(markerIndex + ARTIFACT_MARKER.length);
+  const newlineIndex = after.indexOf('\n');
+  const namesPart = newlineIndex === -1 ? after : after.slice(0, newlineIndex);
+  const rest = newlineIndex === -1 ? '' : after.slice(newlineIndex + 1);
+
+  const artifactNames = namesPart
+    .split(',')
+    .map((name) => name.trim())
+    .filter(Boolean);
+
+  return { stdout: (before + rest).replace(/\n$/, ''), artifactNames };
+}
+
+/**
+ * Runs `request` via `execFn` and reassembles an `ExecutionResult`,
+ * including a best-effort fetch of any files the code wrote to the output
+ * directory (one follow-up `base64 <file>` call per artifact).
+ */
+export async function runScriptedExecution(
+  execFn: RemoteExecFn,
+  request: ExecutionRequest,
+): Promise<ExecutionResult> {
+  const startTime = Date.now();
+  const script = buildExecutionScript(request);
+  const main = await execFn(script);
+
+  const { stdout, artifactNames } = extractArtifactMarker(main.stdout);
+  const artifacts: ExecutionArtifact[] = [];
+  for (const name of artifactNames) {
+    if (!name || name.includes('/') || name.includes('\\') || name === '.' || name === '..')
+      continue;
+    try {
+      const cat = await execFn(`base64 ${shellSingleQuote(`${OUTPUT_DIR}/${name}`)}`);
+      const data = cat.stdout.replace(/\s+/g, '');
+      if (cat.exitCode === 0 && data) {
+        artifacts.push({ name, mimeType: getMimeType(name), data });
+      }
+    } catch {
+      /* one missing/unreadable artifact shouldn't fail the whole execution */
+    }
+  }
+
+  return {
+    stdout,
+    stderr: main.stderr,
+    exitCode: main.exitCode,
+    artifacts,
+    executionTimeMs: Date.now() - startTime,
+  };
+}
+
+/** Uniform safety net for providers whose SDK doesn't take its own per-call timeout. */
+export async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  label: string,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () => reject(new Error(`${label} timed out after ${timeoutMs}ms`)),
+      timeoutMs,
+    );
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    clearTimeout(timer!);
+  }
+}
+
+/**
+ * Runs a teardown call (kill/delete/terminate/stop) and swallows whatever it
+ * throws or rejects with — cleanup failures shouldn't mask the actual
+ * execution result. Wrapping in try/catch (rather than `.catch()`) also
+ * tolerates a teardown method that doesn't return a real promise.
+ */
+export async function safeCleanup(fn: () => Promise<unknown>): Promise<void> {
+  try {
+    await fn();
+  } catch {
+    /* best effort */
+  }
+}
+
+export function failedResult(message: string, startTime: number): ExecutionResult {
+  return {
+    stdout: '',
+    stderr: message,
+    exitCode: 1,
+    artifacts: [],
+    executionTimeMs: Date.now() - startTime,
+  };
+}