@capsulos/sdk 0.0.0-stage → 0.1.1

package/dist/pty.d.ts

@@ -0,0 +1,23 @@
+import { type Connection, type PtyOptions } from './types.js';
+export declare class PtySession {
+    private readonly ws;
+    private readonly dataListeners;
+    private readonly exitPromise;
+    private resolveExit;
+    private rejectExit;
+    private settled;
+    private constructor();
+    /** Open a terminal. Resolves once the socket is up; the process is already running. */
+    static open(conn: Connection, opts?: PtyOptions): Promise<PtySession>;
+    /** Send keystrokes (or any bytes) to the terminal. */
+    write(data: string | Uint8Array): void;
+    resize(cols: number, rows: number): void;
+    /** Subscribe to terminal output; returns an unsubscribe function. */
+    onData(listener: (chunk: Uint8Array) => void): () => void;
+    /** Resolves with the exit code when the process ends; rejects if the connection drops first. */
+    wait(): Promise<number>;
+    /** Hang up. The daemon kills the process when the socket goes away. */
+    close(): void;
+    private settle;
+    private fail;
+}

package/dist/pty.js

@@ -0,0 +1,122 @@
+// An interactive terminal inside the capsule, over a WebSocket to capsulod's
+// /pty: binary frames are terminal bytes in both directions, text frames are
+// JSON control messages (resize from us, exit from the daemon).
+import { CapsuleError } from './types.js';
+/** Explain a failed upgrade: unreachable daemon, or one too old to have /pty. */
+async function diagnose(conn, headers) {
+    try {
+        const res = await fetch(`${conn.baseUrl}/pty`, { headers, signal: AbortSignal.timeout(5_000) });
+        if (res.status === 404) {
+            return `this capsule's capsulod has no /pty endpoint: rebuild the template with the current daemon (pnpm docker:base, or capsulos template build) and create a new capsule`;
+        }
+        return `${conn.baseUrl}/pty answered HTTP ${res.status} instead of upgrading to a WebSocket`;
+    }
+    catch (err) {
+        return `cannot reach ${conn.baseUrl} (${err instanceof Error ? err.message : String(err)})`;
+    }
+}
+export class PtySession {
+    ws;
+    dataListeners = new Set();
+    exitPromise;
+    resolveExit;
+    rejectExit;
+    settled = false;
+    constructor(ws) {
+        this.ws = ws;
+        this.exitPromise = new Promise((resolve, reject) => {
+            this.resolveExit = resolve;
+            this.rejectExit = reject;
+        });
+        // A dropped connection rejects wait(); callers that never call it must
+        // not take the process down with an unhandled rejection.
+        this.exitPromise.catch(() => undefined);
+        ws.binaryType = 'arraybuffer';
+        ws.addEventListener('message', (ev) => {
+            if (typeof ev.data === 'string') {
+                const msg = JSON.parse(ev.data);
+                if (msg.type === 'exit')
+                    this.settle(msg.exitCode);
+                return;
+            }
+            const chunk = new Uint8Array(ev.data);
+            for (const l of this.dataListeners)
+                l(chunk);
+        });
+        ws.addEventListener('close', (ev) => {
+            if (!this.settled)
+                this.fail(new CapsuleError(`pty closed without exit (${ev.code}${ev.reason ? `: ${ev.reason}` : ''})`));
+        });
+        ws.addEventListener('error', () => {
+            if (!this.settled)
+                this.fail(new CapsuleError('pty connection error'));
+        });
+    }
+    /** Open a terminal. Resolves once the socket is up; the process is already running. */
+    static open(conn, opts = {}) {
+        return new Promise((resolve, reject) => {
+            void (async () => {
+                const q = new URLSearchParams();
+                if (opts.cmd)
+                    q.set('cmd', opts.cmd);
+                for (const a of opts.args ?? [])
+                    q.append('arg', a);
+                if (opts.cwd)
+                    q.set('cwd', opts.cwd);
+                for (const [k, v] of Object.entries(opts.env ?? {}))
+                    q.append('env', `${k}=${v}`);
+                q.set('cols', String(opts.cols ?? 80));
+                q.set('rows', String(opts.rows ?? 24));
+                const url = `${conn.baseUrl.replace(/^http/, 'ws')}/pty?${q}`;
+                const headers = await conn.headers();
+                const WS = globalThis.WebSocket;
+                const ws = new WS(url, Object.keys(headers).length ? { headers } : undefined);
+                const timer = setTimeout(() => {
+                    ws.close();
+                    reject(new CapsuleError('pty connect timeout'));
+                }, opts.connectTimeoutMs ?? 30_000);
+                const session = new PtySession(ws);
+                if (opts.onData)
+                    session.onData(opts.onData);
+                ws.addEventListener('open', () => {
+                    clearTimeout(timer);
+                    resolve(session);
+                });
+                ws.addEventListener('error', () => {
+                    clearTimeout(timer);
+                    // Node's WebSocket error carries no status; ask the daemon directly.
+                    void diagnose(conn, headers).then((why) => reject(new CapsuleError(`pty connection failed: ${why}`)));
+                });
+            })().catch(reject);
+        });
+    }
+    /** Send keystrokes (or any bytes) to the terminal. */
+    write(data) {
+        this.ws.send(typeof data === 'string' ? new TextEncoder().encode(data) : data);
+    }
+    resize(cols, rows) {
+        this.ws.send(JSON.stringify({ type: 'resize', cols, rows }));
+    }
+    /** Subscribe to terminal output; returns an unsubscribe function. */
+    onData(listener) {
+        this.dataListeners.add(listener);
+        return () => this.dataListeners.delete(listener);
+    }
+    /** Resolves with the exit code when the process ends; rejects if the connection drops first. */
+    wait() {
+        return this.exitPromise;
+    }
+    /** Hang up. The daemon kills the process when the socket goes away. */
+    close() {
+        this.ws.close(1000, 'client closed');
+    }
+    settle(code) {
+        this.settled = true;
+        this.resolveExit(code);
+    }
+    fail(err) {
+        this.settled = true;
+        this.rejectExit(err);
+    }
+}
+//# sourceMappingURL=pty.js.map

package/dist/pty.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,168 @@
+/** Where a capsule lives. Implemented by @capsulos/provider-* packages. */
+export interface Provider {
+    readonly name: string;
+    /** Create a capsule and wait until it runs (see CreateOptions for the wait). */
+    create(spec: CapsuleSpec, opts?: CreateOptions): Promise<CapsuleHandle>;
+    get(id: string): Promise<CapsuleInfo | null>;
+    /** Capsules this provider knows about, optionally only those of one template. */
+    list(template?: string): Promise<CapsuleInfo[]>;
+    terminate(id: string): Promise<void>;
+    /** How to reach the daemon of an existing capsule (endpoint + auth headers). */
+    connect(id: string): Promise<Connection>;
+}
+export interface CreateOptions {
+    /**
+     * How long to wait for the capsule to run before giving up (provider
+     * default: 120 s). On timeout the provider terminates what it started, so
+     * nothing is left running without an owner, and throws a CapsuleError
+     * whose `capsuleId` names it.
+     */
+    timeoutMs?: number;
+    /** Abort the wait (same clean-up as a timeout). */
+    signal?: AbortSignal;
+}
+export interface HeadersOptions {
+    /** Discard any cached credential and mint a new one (after a 401/403). */
+    fresh?: boolean;
+}
+export interface Connection {
+    /** Base URL of capsulod, e.g. https://abc.microvm.lambda-url.us-east-1.on.aws */
+    baseUrl: string;
+    /** Headers every request must carry (e.g. X-aws-proxy-auth). Cached by the provider; `fresh` re-mints. */
+    headers(opts?: HeadersOptions): Promise<Record<string, string>>;
+}
+export type CapsuleState = 'pending' | 'running' | 'suspended' | 'terminated' | 'unknown';
+export interface CapsuleInfo {
+    id: string;
+    provider: string;
+    state: CapsuleState;
+    template: string | null;
+    createdAt: Date | null;
+    /** When the provider terminated it (provider clock); null while alive or unknown. */
+    terminatedAt?: Date | null;
+    /** The provider's reason for the current state (e.g. why it died), when it gives one. */
+    stateReason?: string | null;
+    /** Where capsulod answers (the Connection's baseUrl), when the provider knows it without another call. */
+    endpoint?: string | null;
+    /** Version of the template the capsule runs (a MicrovmImage version on Lambda). */
+    templateVersion?: string | null;
+    /** The hard wall-clock limit it was created with. */
+    maxDurationSeconds?: number | null;
+}
+export interface CapsuleHandle extends CapsuleInfo {
+    connection: Connection;
+}
+/** A mount declared at creation. `posix` drivers are mounted in the kernel and seen by processes. */
+export type MountSpec = {
+    driver: 'local';
+} | {
+    driver: 'tmpfs';
+    sizeMb?: number;
+} | {
+    driver: 'overlay';
+    lower: string;
+} | {
+    driver: 's3';
+    bucket: string;
+    prefix?: string;
+    readOnly?: boolean;
+    region?: string;
+};
+export interface MountResult {
+    path: string;
+    driver: string;
+    ok: boolean;
+    error?: string;
+}
+export interface Health {
+    ok: boolean;
+    version: string;
+    uptimeS: number;
+    /** True once the mount table was applied (by the boot hook or /configure). */
+    configured: boolean;
+    mounts?: MountResult[];
+    /** The template's long-running process (CAPSULOD_START), when the template declares one. */
+    service?: ServiceStatus;
+}
+export interface ServiceStatus {
+    cmd: string;
+    pid: number;
+    running: boolean;
+    restarts: number;
+    lastExitCode?: number;
+    startedAt?: string;
+}
+export interface IdlePolicy {
+    /** Suspend after this long without traffic (seconds). */
+    suspendAfterSeconds: number;
+    /** Destroy after this long suspended (seconds). */
+    destroyAfterSeconds: number;
+}
+export interface CapsuleSpec {
+    /** Template (image) name as registered with the provider. */
+    template: string;
+    /** Hard wall-clock limit for the capsule, in seconds. */
+    maxDurationSeconds?: number;
+    idle?: IdlePolicy;
+    mounts?: Record<string, MountSpec>;
+    /** Opaque per-capsule configuration delivered to the daemon at boot (never secrets). */
+    metadata?: Record<string, string>;
+    /** Idempotency key: creating twice with the same key returns the same capsule. */
+    clientToken?: string;
+}
+export interface ExecOptions {
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    stdin?: string;
+    timeoutMs?: number;
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+}
+export interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timeout: boolean;
+    error?: string;
+    durationMs: number;
+}
+export type ExecEvent = {
+    type: 'stdout';
+    data: string;
+} | {
+    type: 'stderr';
+    data: string;
+} | {
+    type: 'exit';
+    exitCode: number;
+    timeout?: boolean;
+    error?: string;
+};
+export interface PtyOptions {
+    /** Program to run; defaults to bash when the template has it, else sh. */
+    cmd?: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    cols?: number;
+    rows?: number;
+    onData?: (chunk: Uint8Array) => void;
+    connectTimeoutMs?: number;
+}
+export interface FileEntry {
+    name: string;
+    path: string;
+    isDir: boolean;
+    size: number;
+    mode: string;
+    modTime: string;
+}
+export declare class CapsuleError extends Error {
+    readonly status?: number | undefined;
+    /** The capsule the error is about, when there is one (e.g. the one a create() timeout terminated). */
+    readonly capsuleId?: string;
+    constructor(message: string, status?: number | undefined, opts?: {
+        capsuleId?: string;
+    });
+}

package/dist/types.js

@@ -0,0 +1,17 @@
+// The three axes of capsulos (docs/ARCHITECTURE.md):
+//   Provider   — where a capsule runs (lambda, docker, later firecracker)
+//   Primitives — what a capsule exposes (process, fs, pty, ports)
+//   Drivers    — how a primitive is implemented (fs: local, tmpfs, overlay, s3)
+export class CapsuleError extends Error {
+    status;
+    /** The capsule the error is about, when there is one (e.g. the one a create() timeout terminated). */
+    capsuleId;
+    constructor(message, status, opts = {}) {
+        super(message);
+        this.status = status;
+        this.name = 'CapsuleError';
+        if (opts.capsuleId)
+            this.capsuleId = opts.capsuleId;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,0EAA0E;AAC1E,kEAAkE;AAClE,gFAAgF;AAwKhF,MAAM,OAAO,YAAa,SAAQ,KAAK;IAM1B;IALX,sGAAsG;IAC7F,SAAS,CAAU;IAE5B,YACE,OAAe,EACN,MAAe,EACxB,OAA+B,EAAE;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,WAAM,GAAN,MAAM,CAAS;QAIxB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,IAAI,CAAC,SAAS;YAAE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IACtD,CAAC;CACF"}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@capsulos/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Throw a capsule, get a computer. Sandboxes for AI agents on your own AWS account (Lambda MicroVMs) or on Docker.",
+  "license": "Apache-2.0",
+  "keywords": [
+    "sandbox",
+    "ai-agents",
+    "aws",
+    "lambda",
+    "microvm",
+    "firecracker",
+    "e2b",
+    "daytona"
+  ],
+  "homepage": "https://github.com/tornoai/capsulos#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tornoai/capsulos.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/tornoai/capsulos/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run --passWithNoTests"
+  }
 }

package/src/capsule.ts

@@ -0,0 +1,139 @@
+// The public face of a capsule. `Capsule.create()` asks the provider for a
+// machine and waits until capsulod answers; everything after that goes
+// straight to the daemon.
+import { DaemonClient, type ClientOptions } from './client.js';
+import { Ports } from './ports.js';
+import { PtySession } from './pty.js';
+import {
+  CapsuleError,
+  type CapsuleSpec,
+  type ExecOptions,
+  type ExecResult,
+  type FileEntry,
+  type Health,
+  type Provider,
+  type PtyOptions,
+} from './types.js';
+
+export interface CapsuleOptions extends ClientOptions {
+  /** How long to wait for the daemon to answer /health after creation. */
+  readyTimeoutMs?: number;
+  /** How long the provider may take to run the capsule (default 120 s); on timeout it is terminated. */
+  createTimeoutMs?: number;
+  /** Abort creation (the provider terminates what it started) or the wait for the daemon. */
+  signal?: AbortSignal;
+}
+
+export class Capsule {
+  readonly commands: Commands;
+  readonly files: Files;
+  readonly pty: Pty;
+  /** Servers listening inside the capsule, reachable through the daemon (preview URLs). */
+  readonly ports: Ports;
+
+  private constructor(
+    readonly id: string,
+    private readonly provider: Provider,
+    private readonly client: DaemonClient,
+  ) {
+    this.commands = new Commands(client);
+    this.files = new Files(client);
+    this.pty = new Pty(client);
+    this.ports = new Ports(client.connection);
+  }
+
+  /** Throw a capsule: create it with the provider and wait until it is ready. */
+  static async create(provider: Provider, spec: CapsuleSpec, opts: CapsuleOptions = {}): Promise<Capsule> {
+    const handle = await provider.create(spec, { timeoutMs: opts.createTimeoutMs, signal: opts.signal });
+    const client = new DaemonClient(handle.connection, opts);
+    const health = await waitReady(client, opts.readyTimeoutMs ?? 120_000, opts.signal);
+    // Providers deliver the mount table through their boot hook. When that did
+    // not happen (no hook, or the hook came without its payload), hand it over
+    // directly. Either way, a mount that failed is an error here, not a
+    // surprise later when a write lands in a plain directory.
+    let results = health.mounts ?? [];
+    const wanted = Object.keys(spec.mounts ?? {});
+    const applied = new Set(results.map((r) => r.path));
+    const hookMissed = !health.configured || wanted.some((p) => !applied.has(p));
+    if (hookMissed && (spec.mounts || spec.metadata)) {
+      results = await client.configure({ mounts: spec.mounts, metadata: spec.metadata });
+    }
+    const failed = results.filter((r) => !r.ok);
+    if (failed.length) {
+      throw new CapsuleError(`mounts failed: ${failed.map((r) => `${r.path} (${r.driver}): ${r.error}`).join('; ')}`);
+    }
+    return new Capsule(handle.id, provider, client);
+  }
+
+  /** Reconnect to a capsule that already exists (it may be suspended: the first request resumes it). */
+  static async connect(provider: Provider, id: string, opts: CapsuleOptions = {}): Promise<Capsule> {
+    const conn = await provider.connect(id);
+    return new Capsule(id, provider, new DaemonClient(conn, opts));
+  }
+
+  health() {
+    return this.client.health();
+  }
+
+  /** Put the capsule back in your pocket. */
+  async kill(): Promise<void> {
+    await this.provider.terminate(this.id);
+  }
+}
+
+export class Commands {
+  constructor(private readonly client: DaemonClient) {}
+  /** Run a command (through `sh -c` unless `args` is given). Pass onStdout/onStderr for live output. */
+  run(cmd: string, opts?: ExecOptions): Promise<ExecResult> {
+    return this.client.exec(cmd, opts);
+  }
+}
+
+export class Pty {
+  constructor(private readonly client: DaemonClient) {}
+  /** Open an interactive terminal (a shell by default). */
+  open(opts?: PtyOptions): Promise<PtySession> {
+    return PtySession.open(this.client.connection, opts);
+  }
+}
+
+export class Files {
+  constructor(private readonly client: DaemonClient) {}
+  read(path: string): Promise<string> {
+    return this.client.readText(path);
+  }
+  readBytes(path: string): Promise<Uint8Array> {
+    return this.client.readFile(path);
+  }
+  write(path: string, data: string | Uint8Array, opts?: { mode?: string }): Promise<void> {
+    return this.client.writeFile(path, data, opts);
+  }
+  list(path: string): Promise<FileEntry[]> {
+    return this.client.list(path);
+  }
+  stat(path: string): Promise<FileEntry> {
+    return this.client.stat(path);
+  }
+  mkdir(path: string): Promise<void> {
+    return this.client.mkdir(path);
+  }
+  remove(path: string): Promise<void> {
+    return this.client.remove(path);
+  }
+}
+
+async function waitReady(client: DaemonClient, timeoutMs: number, signal?: AbortSignal): Promise<Health> {
+  const t0 = Date.now();
+  let lastErr: unknown;
+  while (Date.now() - t0 < timeoutMs) {
+    if (signal?.aborted) throw new CapsuleError('wait for the capsule daemon aborted');
+    try {
+      const h = await client.health();
+      if (h.ok) return h;
+    } catch (err) {
+      lastErr = err;
+    }
+    await new Promise((r) => setTimeout(r, 400));
+  }
+  throw new CapsuleError(`capsule daemon did not become ready in ${timeoutMs}ms (${String(lastErr)})`);
+}

package/src/client.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import { DaemonClient, parseSse } from './client.js';
+import type { Connection } from './types.js';
+
+const conn: Connection = { baseUrl: 'http://capsule', headers: async () => ({ 'X-Test': '1' }) };
+
+function sseResponse(frames: string[]): Response {
+  return new Response(frames.join(''), { status: 200, headers: { 'Content-Type': 'text/event-stream' } });
+}
+
+describe('parseSse', () => {
+  it('yields one event per frame, across chunk boundaries', async () => {
+    const res = sseResponse([
+      'event: stdout\ndata: {"type":"stdout","data":"he"}\n\n',
+      'event: stdout\ndata: {"type":"stdout","data":"llo"}\n\n',
+      'event: exit\ndata: {"type":"exit","exitCode":0}\n\n',
+    ]);
+    const events = [];
+    for await (const ev of parseSse(res)) events.push(ev);
+    expect(events).toEqual([
+      { type: 'stdout', data: 'he' },
+      { type: 'stdout', data: 'llo' },
+      { type: 'exit', exitCode: 0 },
+    ]);
+  });
+});
+
+describe('DaemonClient.exec', () => {
+  it('streams when callbacks are given and sends auth headers', async () => {
+    let seen: Request | undefined;
+    const fetchImpl: typeof fetch = async (input, init) => {
+      seen = new Request(input, init);
+      return sseResponse(['data: {"type":"stdout","data":"x"}\n\n', 'data: {"type":"exit","exitCode":2}\n\n']);
+    };
+    const client = new DaemonClient(conn, { fetch: fetchImpl });
+    const chunks: string[] = [];
+    const res = await client.exec('echo x', { onStdout: (c) => chunks.push(c) });
+    expect(chunks).toEqual(['x']);
+    expect(res.exitCode).toBe(2);
+    expect(seen?.headers.get('X-Test')).toBe('1');
+    expect(seen?.headers.get('Accept')).toBe('text/event-stream');
+  });
+
+  it('turns non-2xx into CapsuleError with the daemon message', async () => {
+    const fetchImpl: typeof fetch = async () => new Response('{"error":"nope"}', { status: 404 });
+    const client = new DaemonClient(conn, { fetch: fetchImpl });
+    await expect(client.readText('/x')).rejects.toThrow(/HTTP 404: nope/);
+  });
+});
+
+describe('DaemonClient credentials', () => {
+  it('retries once with fresh headers when the endpoint rejects the token', async () => {
+    const minted: boolean[] = [];
+    const conn: Connection = {
+      baseUrl: 'http://capsule',
+      headers: async (opts) => {
+        minted.push(Boolean(opts?.fresh));
+        return { 'X-Token': opts?.fresh ? 'new' : 'stale' };
+      },
+    };
+    const client = new DaemonClient(conn, {
+      fetch: async (_url, init) => {
+        const token = new Headers(init?.headers).get('X-Token');
+        return token === 'new'
+          ? new Response(JSON.stringify({ ok: true, version: 't', uptimeS: 1, configured: true }), { status: 200 })
+          : new Response(JSON.stringify({ error: 'forbidden' }), { status: 403 });
+      },
+    });
+    const health = await client.health();
+    expect(health.ok).toBe(true);
+    expect(minted).toEqual([false, true]);
+  });
+
+  it('gives up after one fresh attempt', async () => {
+    const conn: Connection = { baseUrl: 'http://capsule', headers: async () => ({}) };
+    const client = new DaemonClient(conn, { fetch: async () => new Response('{"error":"no"}', { status: 403 }) });
+    await expect(client.health()).rejects.toThrow(/HTTP 403/);
+  });
+});