@capsulos/sdk 0.0.0-stage → 0.1.0

package/src/client.ts

@@ -0,0 +1,166 @@
+// Thin HTTP client for capsulod. Every request has a timeout: on a capsule
+// with egress blocked, a dead connection shows up as a hang, never as an error.
+import {
+  CapsuleError,
+  type Connection,
+  type ExecEvent,
+  type ExecOptions,
+  type ExecResult,
+  type FileEntry,
+  type Health,
+  type MountResult,
+  type MountSpec,
+} from './types.js';
+
+export interface ClientOptions {
+  fetch?: typeof fetch;
+  requestTimeoutMs?: number;
+}
+
+export class DaemonClient {
+  private readonly fetchImpl: typeof fetch;
+  private readonly requestTimeoutMs: number;
+
+  constructor(
+    readonly connection: Connection,
+    opts: ClientOptions = {},
+  ) {
+    this.fetchImpl = opts.fetch ?? ((...args) => fetch(...args));
+    this.requestTimeoutMs = opts.requestTimeoutMs ?? 30_000;
+  }
+
+  private async request(path: string, init: RequestInit & { timeoutMs?: number } = {}): Promise<Response> {
+    const headers = { ...(await this.connection.headers()), ...(init.headers as Record<string, string> | undefined) };
+    const res = await this.fetchImpl(`${this.connection.baseUrl}${path}`, {
+      ...init,
+      headers,
+      signal: AbortSignal.timeout(init.timeoutMs ?? this.requestTimeoutMs),
+    });
+    if (!res.ok) {
+      let detail = '';
+      try {
+        detail = ((await res.json()) as { error?: string }).error ?? '';
+      } catch {
+        /* non-JSON error body */
+      }
+      throw new CapsuleError(`${init.method ?? 'GET'} ${path} → HTTP ${res.status}${detail ? `: ${detail}` : ''}`, res.status);
+    }
+    return res;
+  }
+
+  async health(): Promise<Health> {
+    const res = await this.request('/health', { timeoutMs: 10_000 });
+    return (await res.json()) as Health;
+  }
+
+  /** Apply the mount table when the provider's boot hook did not deliver it. */
+  async configure(body: { mounts?: Record<string, MountSpec>; metadata?: Record<string, string> }): Promise<MountResult[]> {
+    const res = await this.request('/configure', {
+      method: 'POST',
+      body: JSON.stringify(body),
+      headers: { 'Content-Type': 'application/json' },
+      timeoutMs: 60_000,
+    });
+    return ((await res.json()) as { mounts: MountResult[] }).mounts ?? [];
+  }
+
+  /** Buffered or streamed depending on whether callbacks are given. */
+  async exec(cmd: string, opts: ExecOptions = {}): Promise<ExecResult> {
+    const body = JSON.stringify({
+      cmd,
+      args: opts.args,
+      cwd: opts.cwd,
+      env: opts.env,
+      stdin: opts.stdin,
+      timeoutMs: opts.timeoutMs,
+    });
+    // Request timeout = command timeout + slack; the daemon enforces the real one.
+    const timeoutMs = (opts.timeoutMs ?? 60_000) + 15_000;
+    const streaming = Boolean(opts.onStdout || opts.onStderr);
+
+    if (!streaming) {
+      const res = await this.request('/exec', { method: 'POST', body, headers: { 'Content-Type': 'application/json' }, timeoutMs });
+      return (await res.json()) as ExecResult;
+    }
+
+    const startedAt = Date.now();
+    const res = await this.request('/exec', {
+      method: 'POST',
+      body,
+      headers: { 'Content-Type': 'application/json', Accept: 'text/event-stream' },
+      timeoutMs,
+    });
+    const result: ExecResult = { exitCode: -1, stdout: '', stderr: '', timeout: false, durationMs: 0 };
+    for await (const ev of parseSse(res)) {
+      if (ev.type === 'stdout') {
+        result.stdout += ev.data;
+        opts.onStdout?.(ev.data);
+      } else if (ev.type === 'stderr') {
+        result.stderr += ev.data;
+        opts.onStderr?.(ev.data);
+      } else {
+        result.exitCode = ev.exitCode ?? 0;
+        result.timeout = ev.timeout ?? false;
+        if (ev.error) result.error = ev.error;
+      }
+    }
+    result.durationMs = Date.now() - startedAt;
+    return result;
+  }
+
+  async readFile(path: string): Promise<Uint8Array> {
+    const res = await this.request(`/files/read?path=${encodeURIComponent(path)}`);
+    return new Uint8Array(await res.arrayBuffer());
+  }
+
+  async readText(path: string): Promise<string> {
+    return new TextDecoder().decode(await this.readFile(path));
+  }
+
+  async writeFile(path: string, data: string | Uint8Array, opts: { mode?: string } = {}): Promise<void> {
+    const q = new URLSearchParams({ path, ...(opts.mode ? { mode: opts.mode } : {}) });
+    await this.request(`/files/write?${q}`, {
+      method: 'PUT',
+      body: typeof data === 'string' ? data : (data as BodyInit),
+      headers: { 'Content-Type': 'application/octet-stream' },
+    });
+  }
+
+  async list(path: string): Promise<FileEntry[]> {
+    const res = await this.request(`/files/list?path=${encodeURIComponent(path)}`);
+    return (await res.json()) as FileEntry[];
+  }
+
+  async stat(path: string): Promise<FileEntry> {
+    const res = await this.request(`/files/stat?path=${encodeURIComponent(path)}`);
+    return (await res.json()) as FileEntry;
+  }
+
+  async mkdir(path: string): Promise<void> {
+    await this.request(`/files/mkdir?path=${encodeURIComponent(path)}`, { method: 'POST' });
+  }
+
+  async remove(path: string): Promise<void> {
+    await this.request(`/files?path=${encodeURIComponent(path)}`, { method: 'DELETE' });
+  }
+}
+
+/** Minimal SSE parser over a fetch Response body. */
+export async function* parseSse(res: Response): AsyncGenerator<ExecEvent> {
+  const reader = res.body?.getReader();
+  if (!reader) throw new CapsuleError('exec stream has no body');
+  const decoder = new TextDecoder();
+  let buffer = '';
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    let idx: number;
+    while ((idx = buffer.indexOf('\n\n')) !== -1) {
+      const frame = buffer.slice(0, idx);
+      buffer = buffer.slice(idx + 2);
+      const dataLine = frame.split('\n').find((l) => l.startsWith('data: '));
+      if (dataLine) yield JSON.parse(dataLine.slice(6)) as ExecEvent;
+    }
+  }
+}

package/src/e2e.test.ts

@@ -0,0 +1,188 @@
+// End-to-end against a real capsulod running locally (no provider in between).
+// Needs the daemon built: `pnpm daemon:build`. Skipped otherwise.
+import { spawn, type ChildProcess } from 'node:child_process';
+import { existsSync, mkdtempSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { Capsule } from './capsule.js';
+import type { CapsuleHandle, Provider } from './types.js';
+
+const BIN = join(import.meta.dirname, '..', '..', '..', '.artifacts', 'capsulod');
+const PORT = 18080 + Math.floor(Math.random() * 1000);
+
+/** A provider whose "capsule" is a local capsulod process. */
+class LocalProvider implements Provider {
+  readonly name = 'local';
+  child: ChildProcess | undefined;
+  async create(): Promise<CapsuleHandle> {
+    this.child = spawn(BIN, [], {
+      env: { ...process.env, CAPSULOD_PORT: String(PORT), CAPSULOD_HOOK_PORT: String(PORT + 1) },
+      stdio: 'ignore',
+    });
+    return { id: 'local', provider: 'local', state: 'running', template: null, createdAt: new Date(), connection: await this.connect() };
+  }
+  async get() {
+    return null;
+  }
+  async list() {
+    return [];
+  }
+  async terminate() {
+    this.child?.kill();
+  }
+  async connect() {
+    return { baseUrl: `http://127.0.0.1:${PORT}`, headers: async () => ({}) };
+  }
+}
+
+describe.skipIf(!existsSync(BIN))('capsulod e2e', () => {
+  const provider = new LocalProvider();
+  let capsule: Capsule;
+  beforeAll(async () => {
+    capsule = await Capsule.create(provider, { template: 'local' });
+  });
+  afterAll(async () => {
+    await capsule?.kill();
+  });
+
+  it('runs commands with live output', async () => {
+    const chunks: string[] = [];
+    const res = await capsule.commands.run('for i in 1 2 3; do echo $i; sleep 0.1; done; exit 7', {
+      onStdout: (c) => chunks.push(c),
+    });
+    expect(res.exitCode).toBe(7);
+    expect(res.stdout).toBe('1\n2\n3\n');
+    expect(chunks.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('keeps exit code 0 in streaming mode', async () => {
+    const res = await capsule.commands.run('echo ok', { onStdout: () => {} });
+    expect(res.exitCode).toBe(0);
+    expect(res.stdout).toBe('ok\n');
+  });
+
+  it('kills on timeout', async () => {
+    const res = await capsule.commands.run('sleep 10', { timeoutMs: 300 });
+    expect(res.timeout).toBe(true);
+    expect(res.durationMs).toBeLessThan(5000);
+  });
+
+  it('opens an interactive terminal', async () => {
+    let out = '';
+    const seen = (text: string) =>
+      new Promise<void>((resolve) => {
+        const check = () => out.includes(text) && (off(), resolve());
+        const off = term.onData(check);
+        check();
+      });
+    const term = await capsule.pty.open({ cmd: '/bin/sh', cols: 100, rows: 30, onData: (c) => (out += new TextDecoder().decode(c)) });
+    term.write('echo hello-pty; stty size\n');
+    await seen('30 100'); // the first size must be read before we change it
+    term.resize(132, 43);
+    term.write('stty size; exit 5\n');
+    const code = await term.wait();
+    expect(code).toBe(5);
+    expect(out).toContain('hello-pty');
+    expect(out).toContain('30 100');
+    expect(out).toContain('43 132');
+  });
+
+  it('kills the process when the terminal is closed', async () => {
+    const term = await capsule.pty.open({ cmd: '/bin/sh' });
+    term.write('sleep 30\n');
+    term.close();
+    await expect(term.wait()).rejects.toThrow(/pty closed/);
+  });
+
+  it('reaches a server listening on a port inside the capsule', async () => {
+    // The capsule is this machine, so the "app inside" is a local http server.
+    const app = createServer((req, res) => res.end(`app saw ${req.method} ${req.url}`));
+    await new Promise<void>((r) => app.listen(0, '127.0.0.1', r));
+    const port = (app.address() as { port: number }).port;
+    try {
+      const res = await capsule.ports.fetch(port, '/hello?x=1');
+      expect(res.status).toBe(200);
+      expect(await res.text()).toBe('app saw GET /hello?x=1');
+      expect(capsule.ports.url(port, 'a/b')).toBe(`http://127.0.0.1:${PORT}/proxy/${port}/a/b`);
+      expect(capsule.ports.connection(port).baseUrl).toBe(`http://127.0.0.1:${PORT}/proxy/${port}`);
+    } finally {
+      app.close();
+    }
+  });
+
+  it('explains a port nobody listens on', async () => {
+    const res = await capsule.ports.fetch(1, '/');
+    expect(res.status).toBe(502);
+    expect((await res.json()).error).toMatch(/nothing is listening on port 1/);
+    expect(() => capsule.ports.url(0)).toThrow(RangeError);
+  });
+
+  it('reads and writes files', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'capsulos-'));
+    await capsule.files.write(`${dir}/a/hello.txt`, 'hola');
+    expect(await capsule.files.read(`${dir}/a/hello.txt`)).toBe('hola');
+    expect((await capsule.files.list(`${dir}/a`)).map((e) => e.name)).toEqual(['hello.txt']);
+    const out = await capsule.commands.run(`cat ${dir}/a/hello.txt`);
+    expect(out.stdout).toBe('hola');
+    await capsule.files.remove(dir);
+    await expect(capsule.files.stat(dir)).rejects.toThrow(/404/);
+  });
+});
+
+describe.skipIf(!existsSync(BIN))('capsulod e2e: mounts', () => {
+  it('applies a local mount table through /configure when the hook did not run', async () => {
+    const provider = new LocalProvider();
+    const dir = join(mkdtempSync(join(tmpdir(), 'capsulos-')), 'workspace');
+    const capsule = await Capsule.create(provider, { template: 'local', mounts: { [dir]: { driver: 'local' } } });
+    try {
+      const h = await capsule.health();
+      expect(h.configured).toBe(true);
+      expect(h.mounts?.[0]).toMatchObject({ path: dir, driver: 'local', ok: true });
+      expect((await capsule.files.stat(dir)).isDir).toBe(true);
+    } finally {
+      await capsule.kill();
+    }
+  });
+
+  // An s3 mount cannot work here (no mount-s3, not root), which is exactly
+  // what a broken capsule looks like: the failure must reach the caller.
+  const badMounts = { '/tmp/capsulos-e2e-s3': { driver: 's3' as const, bucket: 'nope' } };
+
+  it('throws when a mount applied through /configure failed', async () => {
+    const provider = new LocalProvider();
+    try {
+      await expect(Capsule.create(provider, { template: 'local', mounts: badMounts })).rejects.toThrow(/mounts failed: \/tmp\/capsulos-e2e-s3 \(s3\)/);
+    } finally {
+      await provider.terminate();
+    }
+  });
+
+  it('throws when a mount applied through the /run hook failed', async () => {
+    // Same as above, but the mount table arrives the way Lambda delivers it.
+    class HookedProvider extends LocalProvider {
+      override async create(): Promise<CapsuleHandle> {
+        const handle = await super.create();
+        const hook = `http://127.0.0.1:${PORT + 1}/aws/lambda-microvms/runtime/v1/run`;
+        const body = JSON.stringify({ microvmId: 'local', runHookPayload: JSON.stringify({ mounts: badMounts }) });
+        for (let i = 0; i < 50; i++) {
+          try {
+            const res = await fetch(hook, { method: 'POST', body, signal: AbortSignal.timeout(2000) });
+            if (res.ok) return handle;
+          } catch {
+            /* daemon still booting */
+          }
+          await new Promise((r) => setTimeout(r, 100));
+        }
+        throw new Error('hook port never answered');
+      }
+    }
+    const provider = new HookedProvider();
+    try {
+      await expect(Capsule.create(provider, { template: 'local', mounts: badMounts })).rejects.toThrow(/mounts failed: \/tmp\/capsulos-e2e-s3 \(s3\)/);
+    } finally {
+      await provider.terminate();
+    }
+  });
+});

package/src/index.ts

@@ -0,0 +1,7 @@
+export { Capsule, Commands, Files, Pty } from './capsule.js';
+export { Ports } from './ports.js';
+export { PtySession } from './pty.js';
+export type { CapsuleOptions } from './capsule.js';
+export { DaemonClient, parseSse } from './client.js';
+export type { ClientOptions } from './client.js';
+export * from './types.js';

package/src/ports.ts

@@ -0,0 +1,31 @@
+// Preview URLs: reach a server that listens on a port inside the capsule.
+// capsulod forwards /proxy/<port>/<path> to 127.0.0.1:<port>, so every
+// provider that exposes the daemon (one port, one token) exposes every port,
+// with nothing to declare at creation time.
+import type { Connection } from './types.js';
+
+export class Ports {
+  constructor(private readonly conn: Connection) {}
+
+  /** URL of `path` on the given port, as seen through the daemon (headers still apply, see `connection`). */
+  url(port: number, path = '/'): string {
+    checkPort(port);
+    return `${this.conn.baseUrl}/proxy/${port}${path.startsWith('/') ? path : `/${path}`}`;
+  }
+
+  /** A Connection whose baseUrl is the proxied port: build clients, WebSockets, fetches on it. */
+  connection(port: number): Connection {
+    checkPort(port);
+    return { baseUrl: `${this.conn.baseUrl}/proxy/${port}`, headers: () => this.conn.headers() };
+  }
+
+  /** `fetch()` against the server on `port` inside the capsule, with the capsule's auth headers attached. */
+  async fetch(port: number, path = '/', init: RequestInit = {}): Promise<Response> {
+    const headers = { ...(await this.conn.headers()), ...(init.headers as Record<string, string> | undefined) };
+    return fetch(this.url(port, path), { signal: AbortSignal.timeout(60_000), ...init, headers });
+  }
+}
+
+function checkPort(port: number): void {
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new RangeError(`bad port: ${port}`);
+}

package/src/pty.ts

@@ -0,0 +1,126 @@
+// 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, type Connection, type PtyOptions } from './types.js';
+
+type ControlMessage = { type: 'exit'; exitCode: number } | { type: 'resize'; cols: number; rows: number };
+
+// Node's global WebSocket (undici) accepts request headers through a
+// non-standard init object; the DOM typings do not know about it.
+type WebSocketCtor = new (url: string, init?: { headers?: Record<string, string> }) => WebSocket;
+
+/** Explain a failed upgrade: unreachable daemon, or one too old to have /pty. */
+async function diagnose(conn: Connection, headers: Record<string, string>): Promise<string> {
+  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 {
+  private readonly dataListeners = new Set<(chunk: Uint8Array) => void>();
+  private readonly exitPromise: Promise<number>;
+  private resolveExit!: (code: number) => void;
+  private rejectExit!: (err: Error) => void;
+  private settled = false;
+
+  private constructor(private readonly ws: WebSocket) {
+    this.exitPromise = new Promise<number>((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: MessageEvent) => {
+      if (typeof ev.data === 'string') {
+        const msg = JSON.parse(ev.data) as ControlMessage;
+        if (msg.type === 'exit') this.settle(msg.exitCode);
+        return;
+      }
+      const chunk = new Uint8Array(ev.data as ArrayBuffer);
+      for (const l of this.dataListeners) l(chunk);
+    });
+    ws.addEventListener('close', (ev: CloseEvent) => {
+      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: Connection, opts: PtyOptions = {}): Promise<PtySession> {
+    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 as unknown as WebSocketCtor;
+        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: string | Uint8Array): void {
+    this.ws.send(typeof data === 'string' ? new TextEncoder().encode(data) : data);
+  }
+
+  resize(cols: number, rows: number): void {
+    this.ws.send(JSON.stringify({ type: 'resize', cols, rows } satisfies ControlMessage));
+  }
+
+  /** Subscribe to terminal output; returns an unsubscribe function. */
+  onData(listener: (chunk: Uint8Array) => void): () => void {
+    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(): Promise<number> {
+    return this.exitPromise;
+  }
+
+  /** Hang up. The daemon kills the process when the socket goes away. */
+  close(): void {
+    this.ws.close(1000, 'client closed');
+  }
+
+  private settle(code: number) {
+    this.settled = true;
+    this.resolveExit(code);
+  }
+
+  private fail(err: Error) {
+    this.settled = true;
+    this.rejectExit(err);
+  }
+}

package/src/types.ts

@@ -0,0 +1,156 @@
+// 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)
+
+/** Where a capsule lives. Implemented by @capsulos/provider-* packages. */
+export interface Provider {
+  readonly name: string;
+  create(spec: CapsuleSpec): 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 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). Refreshed by the provider. */
+  headers(): 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;
+}
+
+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;
+}
+
+// ---- process primitive ----
+
+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 };
+
+// ---- pty primitive ----
+
+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;
+}
+
+// ---- fs primitive ----
+
+export interface FileEntry {
+  name: string;
+  path: string;
+  isDir: boolean;
+  size: number;
+  mode: string;
+  modTime: string;
+}
+
+export class CapsuleError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+  ) {
+    super(message);
+    this.name = 'CapsuleError';
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.