@larkup/sandbox 0.1.2 → 0.1.3

package/src/providers/browserbase.ts

@@ -0,0 +1,88 @@
+/**
+ * Browserbase adapter — https://docs.browserbase.com/welcome/introduction
+ *
+ * Browserbase provisions headless-Chrome sessions for Playwright/Puppeteer
+ * automation, not an arbitrary code-execution sandbox — see
+ * SANDBOX_PROVIDERS.browserbase.executionCaveat. `execute()` fails fast with
+ * that explanation instead of pretending to run Python/JS here.
+ * `verifyCredentials`/`healthCheck` are still fully real: they confirm the
+ * API key and project actually work.
+ */
+
+import type {
+  SandboxHealthCheck,
+  ExecutionRequest,
+  ExecutionResult,
+  SandboxProviderAdapter,
+} from '../types.js';
+import { failedResult } from '../remote-exec.js';
+import { SANDBOX_PROVIDERS } from '../registry.js';
+
+interface BrowserbaseProject {
+  id: string;
+}
+
+interface BrowserbaseClient {
+  projects: { list(): Promise<BrowserbaseProject[]> };
+}
+
+interface BrowserbaseModule {
+  default: new (opts: { apiKey: string }) => BrowserbaseClient;
+}
+
+async function loadSdk(): Promise<BrowserbaseModule> {
+  return (await import('@browserbasehq/sdk')) as unknown as BrowserbaseModule;
+}
+
+function requireFields(credentials: Record<string, string>): { apiKey: string; projectId: string } {
+  const apiKey = credentials.apiKey?.trim();
+  const projectId = credentials.projectId?.trim();
+  if (!apiKey || !projectId)
+    throw new Error('Browserbase API key and project ID are both required.');
+  return { apiKey, projectId };
+}
+
+async function verifyCredentials(credentials: Record<string, string>): Promise<void> {
+  const { apiKey, projectId } = requireFields(credentials);
+  const { default: Browserbase } = await loadSdk();
+  const client = new Browserbase({ apiKey });
+  const projects = await client.projects.list();
+  if (!projects.some((project) => project.id === projectId)) {
+    throw new Error('This API key cannot see the given Browserbase project ID.');
+  }
+}
+
+async function healthCheck(credentials: Record<string, string>): Promise<SandboxHealthCheck> {
+  const caveat = SANDBOX_PROVIDERS.browserbase.executionCaveat;
+  if (!credentials.apiKey?.trim() || !credentials.projectId?.trim()) {
+    return {
+      status: 'missing-credentials',
+      backend: 'browserbase',
+      error: 'Browserbase API key and project ID are required.',
+    };
+  }
+  try {
+    await verifyCredentials(credentials);
+    return { status: 'unsupported', backend: 'browserbase', error: caveat };
+  } catch (err) {
+    return {
+      status: 'error',
+      backend: 'browserbase',
+      error: err instanceof Error ? err.message : 'Browserbase health check failed.',
+    };
+  }
+}
+
+async function execute(
+  _request: ExecutionRequest,
+  _credentials: Record<string, string>,
+): Promise<ExecutionResult> {
+  return failedResult(SANDBOX_PROVIDERS.browserbase.executionCaveat!, Date.now());
+}
+
+export const browserbaseAdapter: SandboxProviderAdapter = {
+  id: 'browserbase',
+  verifyCredentials,
+  healthCheck,
+  execute,
+};

package/src/providers/cloudflare.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { cloudflareAdapter } from './cloudflare.js';
+
+beforeEach(() => {
+  vi.stubGlobal('fetch', vi.fn());
+});
+
+describe('cloudflareAdapter.execute', () => {
+  it('always fails fast — @cloudflare/sandbox only runs inside a deployed Worker', async () => {
+    const result = await cloudflareAdapter.execute({ code: 'print(1)', language: 'python' }, {
+      apiToken: 't',
+      accountId: 'a',
+    });
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain('Durable Object binding');
+    expect(fetch).not.toHaveBeenCalled();
+  });
+});
+
+describe('cloudflareAdapter.verifyCredentials', () => {
+  it('requires both apiToken and accountId', async () => {
+    await expect(cloudflareAdapter.verifyCredentials({ apiToken: 't' })).rejects.toThrow(
+      'Cloudflare API token and account ID are both required.',
+    );
+  });
+
+  it('verifies the token, then confirms account access', async () => {
+    (fetch as any).mockResolvedValue({ ok: true });
+    await cloudflareAdapter.verifyCredentials({ apiToken: 't', accountId: 'a' });
+
+    expect(fetch).toHaveBeenNthCalledWith(1, 'https://api.cloudflare.com/client/v4/user/tokens/verify', {
+      headers: { Authorization: 'Bearer t' },
+    });
+    expect(fetch).toHaveBeenNthCalledWith(2, 'https://api.cloudflare.com/client/v4/accounts/a', {
+      headers: { Authorization: 'Bearer t' },
+    });
+  });
+
+  it('fails when the token check fails, without checking the account', async () => {
+    (fetch as any).mockResolvedValue({ ok: false, status: 401 });
+    await expect(cloudflareAdapter.verifyCredentials({ apiToken: 'bad', accountId: 'a' })).rejects.toThrow(
+      'rejected the API token',
+    );
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('fails when the token works but cannot see the account', async () => {
+    (fetch as any)
+      .mockResolvedValueOnce({ ok: true })
+      .mockResolvedValueOnce({ ok: false, status: 403 });
+    await expect(cloudflareAdapter.verifyCredentials({ apiToken: 't', accountId: 'wrong' })).rejects.toThrow(
+      'cannot see the given Cloudflare account ID',
+    );
+  });
+});
+
+describe('cloudflareAdapter.healthCheck', () => {
+  it('reports status "unsupported" when credentials are valid', async () => {
+    (fetch as any).mockResolvedValue({ ok: true });
+    const result = await cloudflareAdapter.healthCheck({ apiToken: 't', accountId: 'a' });
+    expect(result.status).toBe('unsupported');
+  });
+});

package/src/providers/cloudflare.ts

@@ -0,0 +1,72 @@
+/**
+ * Cloudflare Sandbox adapter — https://developers.cloudflare.com/sandbox/
+ */
+
+import type {
+  SandboxHealthCheck,
+  ExecutionRequest,
+  ExecutionResult,
+  SandboxProviderAdapter,
+} from '../types.js';
+import { failedResult } from '../remote-exec.js';
+import { SANDBOX_PROVIDERS } from '../registry.js';
+
+function requireFields(credentials: Record<string, string>): {
+  apiToken: string;
+  accountId: string;
+} {
+  const apiToken = credentials.apiToken?.trim();
+  const accountId = credentials.accountId?.trim();
+  if (!apiToken || !accountId)
+    throw new Error('Cloudflare API token and account ID are both required.');
+  return { apiToken, accountId };
+}
+
+async function verifyCredentials(credentials: Record<string, string>): Promise<void> {
+  const { apiToken, accountId } = requireFields(credentials);
+
+  const tokenRes = await fetch('https://api.cloudflare.com/client/v4/user/tokens/verify', {
+    headers: { Authorization: `Bearer ${apiToken}` },
+  });
+  if (!tokenRes.ok) throw new Error(`Cloudflare rejected the API token (${tokenRes.status}).`);
+
+  const accountRes = await fetch(`https://api.cloudflare.com/client/v4/accounts/${accountId}`, {
+    headers: { Authorization: `Bearer ${apiToken}` },
+  });
+  if (!accountRes.ok) throw new Error('This API token cannot see the given Cloudflare account ID.');
+}
+
+async function healthCheck(credentials: Record<string, string>): Promise<SandboxHealthCheck> {
+  const caveat = SANDBOX_PROVIDERS.cloudflare.executionCaveat;
+  if (!credentials.apiToken?.trim() || !credentials.accountId?.trim()) {
+    return {
+      status: 'missing-credentials',
+      backend: 'cloudflare',
+      error: 'Cloudflare API token and account ID are required.',
+    };
+  }
+  try {
+    await verifyCredentials(credentials);
+    return { status: 'unsupported', backend: 'cloudflare', error: caveat };
+  } catch (err) {
+    return {
+      status: 'error',
+      backend: 'cloudflare',
+      error: err instanceof Error ? err.message : 'Cloudflare health check failed.',
+    };
+  }
+}
+
+async function execute(
+  _request: ExecutionRequest,
+  _credentials: Record<string, string>,
+): Promise<ExecutionResult> {
+  return failedResult(SANDBOX_PROVIDERS.cloudflare.executionCaveat!, Date.now());
+}
+
+export const cloudflareAdapter: SandboxProviderAdapter = {
+  id: 'cloudflare',
+  verifyCredentials,
+  healthCheck,
+  execute,
+};

package/src/providers/daytona.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+
+const executeCommandMock = vi.fn();
+const deleteMock = vi.fn();
+const createMock = vi.fn();
+const listMock = vi.fn();
+
+vi.mock('@daytonaio/sdk', () => ({
+  Daytona: vi.fn().mockImplementation(function () {
+    return { create: createMock, list: listMock };
+  }),
+}));
+
+const { daytonaAdapter } = await import('./daytona.js');
+
+beforeEach(() => {
+  executeCommandMock.mockReset();
+  deleteMock.mockReset();
+  createMock.mockReset();
+  listMock.mockReset();
+  createMock.mockResolvedValue({ process: { executeCommand: executeCommandMock }, delete: deleteMock });
+});
+
+describe('daytonaAdapter.verifyCredentials', () => {
+  it('requires an API key', async () => {
+    await expect(daytonaAdapter.verifyCredentials({})).rejects.toThrow('Daytona API key is required.');
+  });
+
+  it('uses list() as the cheap credential check', async () => {
+    const next = vi.fn().mockResolvedValue({ done: true, value: undefined });
+    listMock.mockReturnValue({ next });
+    await daytonaAdapter.verifyCredentials({ apiKey: 'dtn_1' });
+    expect(listMock).toHaveBeenCalledTimes(1);
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('daytonaAdapter.execute — merged stdout/stderr', () => {
+  it('puts successful output in stdout only', async () => {
+    executeCommandMock.mockResolvedValue({ exitCode: 0, result: 'all good\n' });
+    const result = await daytonaAdapter.execute({ code: 'print(1)', language: 'python' }, { apiKey: 'k' });
+    expect(result.stdout).toBe('all good\n');
+    expect(result.stderr).toBe('');
+    expect(result.exitCode).toBe(0);
+  });
+
+  it('mirrors the combined output into stderr when the command fails', async () => {
+    executeCommandMock.mockResolvedValue({ exitCode: 1, result: 'Traceback...\n' });
+    const result = await daytonaAdapter.execute({ code: 'raise ValueError()', language: 'python' }, { apiKey: 'k' });
+    expect(result.stdout).toBe('Traceback...\n');
+    expect(result.stderr).toBe('Traceback...\n');
+    expect(result.exitCode).toBe(1);
+  });
+
+  it('always deletes the sandbox afterward', async () => {
+    executeCommandMock.mockResolvedValue({ exitCode: 0, result: '' });
+    await daytonaAdapter.execute({ code: 'x=1', language: 'python' }, { apiKey: 'k' });
+    expect(deleteMock).toHaveBeenCalledTimes(1);
+  });
+});

package/src/providers/daytona.ts

@@ -0,0 +1,144 @@
+/**
+ * Daytona adapter — https://www.daytona.io/docs/en/sandboxes/
+ *
+ * Daytona's `process.executeCommand` result doesn't document a separate
+ * stderr field (output comes back merged into `result`), so unlike the
+ * other adapters we can't cleanly split stdout/stderr — everything lands in
+ * stdout, and the combined output is mirrored into stderr only when the
+ * command actually failed (exitCode !== 0), so error output still surfaces
+ * where callers expect it.
+ */
+
+import type {
+  SandboxHealthCheck,
+  ExecutionRequest,
+  ExecutionResult,
+  SandboxProviderAdapter,
+} from '../types.js';
+import {
+  DEFAULT_TIMEOUT_MS,
+  failedResult,
+  runScriptedExecution,
+  safeCleanup,
+  withTimeout,
+} from '../remote-exec.js';
+
+interface DaytonaSandbox {
+  process: {
+    executeCommand(
+      command: string,
+      cwd?: string,
+      env?: Record<string, string>,
+      timeout?: number,
+    ): Promise<{
+      exitCode?: number;
+      result?: string;
+    }>;
+  };
+  delete(): Promise<void>;
+}
+
+interface DaytonaClient {
+  create(opts?: Record<string, unknown>): Promise<DaytonaSandbox>;
+  list(): AsyncIterator<unknown>;
+}
+
+interface DaytonaModule {
+  Daytona: new (opts: { apiKey: string; apiUrl?: string }) => DaytonaClient;
+}
+
+async function loadSdk(): Promise<DaytonaModule> {
+  return (await import('@daytonaio/sdk')) as unknown as DaytonaModule;
+}
+
+function requireFields(credentials: Record<string, string>): { apiKey: string; apiUrl?: string } {
+  const apiKey = credentials.apiKey?.trim();
+  if (!apiKey) throw new Error('Daytona API key is required.');
+  return { apiKey, apiUrl: credentials.apiUrl?.trim() || undefined };
+}
+
+async function verifyCredentials(credentials: Record<string, string>): Promise<void> {
+  const fields = requireFields(credentials);
+  const { Daytona } = await loadSdk();
+  const daytona = new Daytona(fields);
+  await daytona.list().next();
+}
+
+async function healthCheck(credentials: Record<string, string>): Promise<SandboxHealthCheck> {
+  if (!credentials.apiKey?.trim()) {
+    return {
+      status: 'missing-credentials',
+      backend: 'daytona',
+      error: 'Daytona API key is required.',
+    };
+  }
+  try {
+    await verifyCredentials(credentials);
+    return { status: 'ready', backend: 'daytona' };
+  } catch (err) {
+    return {
+      status: 'error',
+      backend: 'daytona',
+      error: err instanceof Error ? err.message : 'Daytona health check failed.',
+    };
+  }
+}
+
+async function execute(
+  request: ExecutionRequest,
+  credentials: Record<string, string>,
+): Promise<ExecutionResult> {
+  const startTime = Date.now();
+  let fields: { apiKey: string; apiUrl?: string };
+  try {
+    fields = requireFields(credentials);
+  } catch (err) {
+    return failedResult(
+      err instanceof Error ? err.message : 'Missing Daytona credentials.',
+      startTime,
+    );
+  }
+
+  const timeoutMs = request.timeout ?? DEFAULT_TIMEOUT_MS;
+  let sandbox: DaytonaSandbox | undefined;
+  try {
+    const { Daytona } = await loadSdk();
+    const daytona = new Daytona(fields);
+    const snapshot = credentials.snapshot?.trim();
+    sandbox = await withTimeout(
+      daytona.create(snapshot ? { snapshot } : { language: 'python' }),
+      timeoutMs + 30_000,
+      'Daytona sandbox create',
+    );
+    const activeSandbox = sandbox;
+    return await withTimeout(
+      runScriptedExecution(async (script) => {
+        const result = await activeSandbox.process.executeCommand(
+          script,
+          undefined,
+          undefined,
+          timeoutMs / 1000,
+        );
+        const exitCode = result.exitCode ?? 0;
+        const output = result.result ?? '';
+        return { stdout: output, stderr: exitCode !== 0 ? output : '', exitCode };
+      }, request),
+      timeoutMs + 15_000,
+      'Daytona execution',
+    );
+  } catch (err) {
+    return failedResult(
+      err instanceof Error ? err.message : 'Daytona execution failed.',
+      startTime,
+    );
+  } finally {
+    if (sandbox) await safeCleanup(() => sandbox!.delete());
+  }
+}
+
+export const daytonaAdapter: SandboxProviderAdapter = {
+  id: 'daytona',
+  verifyCredentials,
+  healthCheck,
+  execute,
+};

package/src/providers/e2b.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+
+const listMock = vi.fn();
+const runMock = vi.fn();
+const killMock = vi.fn();
+const createMock = vi.fn();
+
+vi.mock('e2b', () => ({
+  Sandbox: {
+    list: listMock,
+    create: createMock,
+  },
+}));
+
+const { e2bAdapter } = await import('./e2b.js');
+
+beforeEach(() => {
+  listMock.mockReset();
+  runMock.mockReset();
+  killMock.mockReset();
+  createMock.mockReset();
+  createMock.mockResolvedValue({ commands: { run: runMock }, kill: killMock });
+});
+
+describe('e2bAdapter.verifyCredentials', () => {
+  it('rejects without calling the SDK when the API key is missing', async () => {
+    await expect(e2bAdapter.verifyCredentials({})).rejects.toThrow('E2B API key is required.');
+    expect(listMock).not.toHaveBeenCalled();
+  });
+
+  it('lists sandboxes as a cheap credential check', async () => {
+    const nextItems = vi.fn().mockResolvedValue([]);
+    listMock.mockReturnValue({ nextItems });
+    await e2bAdapter.verifyCredentials({ apiKey: 'e2b_test' });
+    expect(listMock).toHaveBeenCalledWith({ apiKey: 'e2b_test' });
+    expect(nextItems).toHaveBeenCalledTimes(1);
+  });
+
+  it('propagates the SDK error on an invalid key', async () => {
+    listMock.mockReturnValue({ nextItems: vi.fn().mockRejectedValue(new Error('401 unauthorized')) });
+    await expect(e2bAdapter.verifyCredentials({ apiKey: 'bad' })).rejects.toThrow('401 unauthorized');
+  });
+});
+
+describe('e2bAdapter.healthCheck', () => {
+  it('reports missing-credentials without touching the SDK', async () => {
+    const result = await e2bAdapter.healthCheck({});
+    expect(result).toEqual({ status: 'missing-credentials', backend: 'e2b', error: 'E2B API key is required.' });
+    expect(listMock).not.toHaveBeenCalled();
+  });
+
+  it('reports ready when verification succeeds', async () => {
+    listMock.mockReturnValue({ nextItems: vi.fn().mockResolvedValue([]) });
+    const result = await e2bAdapter.healthCheck({ apiKey: 'good' });
+    expect(result.status).toBe('ready');
+  });
+});
+
+describe('e2bAdapter.execute', () => {
+  it('fails fast without creating a sandbox when the API key is missing', async () => {
+    const result = await e2bAdapter.execute({ code: 'print(1)', language: 'python' }, {});
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain('E2B API key is required.');
+    expect(createMock).not.toHaveBeenCalled();
+  });
+
+  it('creates a sandbox, runs the script, and always kills it afterward', async () => {
+    runMock.mockResolvedValue({ stdout: 'hi\n', stderr: '', exitCode: 0 });
+    const result = await e2bAdapter.execute({ code: 'print("hi")', language: 'python' }, { apiKey: 'key' });
+
+    expect(createMock).toHaveBeenCalled();
+    expect(runMock).toHaveBeenCalledTimes(1);
+    expect(result.stdout).toBe('hi\n');
+    expect(result.exitCode).toBe(0);
+    expect(killMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('starts from a configured snapshot when one is supplied', async () => {
+    runMock.mockResolvedValue({ stdout: '', stderr: '', exitCode: 0 });
+
+    await e2bAdapter.execute(
+      { code: 'print(1)', language: 'python' },
+      { apiKey: 'key', snapshotId: 'larkup-python:latest' },
+    );
+
+    expect(createMock).toHaveBeenCalledWith(
+      'larkup-python:latest',
+      expect.objectContaining({ allowInternetAccess: false }),
+    );
+  });
+
+  it('still kills the sandbox and returns a failed result when the run call throws', async () => {
+    runMock.mockRejectedValue(new Error('command failed'));
+    const result = await e2bAdapter.execute({ code: 'x=1', language: 'python' }, { apiKey: 'key' });
+
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain('command failed');
+    expect(killMock).toHaveBeenCalledTimes(1);
+  });
+});

package/src/providers/e2b.ts

@@ -0,0 +1,115 @@
+/**
+ * E2B adapter — https://docs.e2b.dev/
+ *
+ * Uses the base `e2b` SDK (not `@e2b/code-interpreter`) so execution stays a
+ * plain "run this shell script, get stdout/stderr/exitCode" call, matching
+ * every other remote adapter and letting them share `runScriptedExecution`.
+ */
+
+import type {
+  SandboxHealthCheck,
+  ExecutionRequest,
+  ExecutionResult,
+  SandboxProviderAdapter,
+} from '../types.js';
+import {
+  DEFAULT_TIMEOUT_MS,
+  failedResult,
+  runScriptedExecution,
+  safeCleanup,
+  withTimeout,
+} from '../remote-exec.js';
+
+interface E2bSandbox {
+  commands: {
+    run(
+      script: string,
+      opts?: { timeoutMs?: number },
+    ): Promise<{ stdout?: string; stderr?: string; exitCode?: number }>;
+  };
+  kill(): Promise<void>;
+}
+
+interface E2bModule {
+  Sandbox: {
+    create(
+      template: string,
+      opts: { apiKey: string; timeoutMs?: number; allowInternetAccess?: boolean },
+    ): Promise<E2bSandbox>;
+    create(opts: {
+      apiKey: string;
+      timeoutMs?: number;
+      allowInternetAccess?: boolean;
+    }): Promise<E2bSandbox>;
+    list(opts: { apiKey: string }): { nextItems(): Promise<unknown[]> };
+  };
+}
+
+async function loadSdk(): Promise<E2bModule> {
+  return (await import('e2b')) as unknown as E2bModule;
+}
+
+async function verifyCredentials(credentials: Record<string, string>): Promise<void> {
+  const apiKey = credentials.apiKey?.trim();
+  if (!apiKey) throw new Error('E2B API key is required.');
+  const { Sandbox } = await loadSdk();
+  await Sandbox.list({ apiKey }).nextItems();
+}
+
+async function healthCheck(credentials: Record<string, string>): Promise<SandboxHealthCheck> {
+  if (!credentials.apiKey?.trim()) {
+    return { status: 'missing-credentials', backend: 'e2b', error: 'E2B API key is required.' };
+  }
+  try {
+    await verifyCredentials(credentials);
+    return { status: 'ready', backend: 'e2b' };
+  } catch (err) {
+    return {
+      status: 'error',
+      backend: 'e2b',
+      error: err instanceof Error ? err.message : 'E2B health check failed.',
+    };
+  }
+}
+
+async function execute(
+  request: ExecutionRequest,
+  credentials: Record<string, string>,
+): Promise<ExecutionResult> {
+  const startTime = Date.now();
+  const apiKey = credentials.apiKey?.trim();
+  if (!apiKey) return failedResult('E2B API key is required.', startTime);
+
+  const timeoutMs = request.timeout ?? DEFAULT_TIMEOUT_MS;
+  let sandbox: E2bSandbox | undefined;
+  try {
+    const { Sandbox } = await loadSdk();
+    const options = { apiKey, timeoutMs: timeoutMs + 60_000, allowInternetAccess: false };
+    const snapshotId = credentials.snapshotId?.trim();
+    sandbox = await withTimeout(
+      snapshotId ? Sandbox.create(snapshotId, options) : Sandbox.create(options),
+      timeoutMs + 30_000,
+      'E2B sandbox create',
+    );
+    const activeSandbox = sandbox;
+    return await runScriptedExecution(async (script) => {
+      const result = await activeSandbox.commands.run(script, { timeoutMs });
+      return {
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+        exitCode: result.exitCode ?? 0,
+      };
+    }, request);
+  } catch (err) {
+    return failedResult(err instanceof Error ? err.message : 'E2B execution failed.', startTime);
+  } finally {
+    if (sandbox) await safeCleanup(() => sandbox!.kill());
+  }
+}
+
+export const e2bAdapter: SandboxProviderAdapter = {
+  id: 'e2b',
+  verifyCredentials,
+  healthCheck,
+  execute,
+};