@mainbrella/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,191 @@
-# Temporary Holding Version
+# Mainbrella JavaScript SDK
 
-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.
+Local package, not published to npm yet. Requires Node 22+; no dependencies.
+
+```sh
+npm install /absolute/path/to/backend/sdk/javascript
+```
+
+```js
+import { Mainbrella } from '@mainbrella/sdk';
+
+const client = new Mainbrella({ apiKey: process.env.MAINBRELLA_API_KEY });
+console.log(await client.capabilities());
+const sandbox = await client.create({ catalogId: 'node' });
+try {
+  const result = await sandbox.commands.run('printf hello');
+  await sandbox.files.write('/tmp/probe.bin', new Uint8Array([0, 128, 255]));
+  const bytes = await sandbox.files.read('/tmp/probe.bin');
+  console.log(result.exitCode, bytes.length);
+} finally {
+  await sandbox.kill();
+}
+```
+
+Creation retries use the same key until the bounded wait expires. An ambiguous
+creation error contains `idempotencyKey`; preserve it and retry the same selection.
+Commands and file writes are never automatically retried. Inspect the file or
+application state after a lost response. `connect({id, createdAt})` attaches to
+an explicit existing generation without creating or stopping anything.
+
+The richer filesystem helpers require the corresponding `capabilities.files`
+flags. They operate on absolute UTF-8 guest paths:
+
+```js
+await sandbox.files.mkdir('/workspace/output', { recursive: true, mode: '0700' });
+const page = await sandbox.files.list('/workspace', { limit: 100 });
+// Pass page.nextOffset as offset for the next page, if it is not null.
+const metadata = await sandbox.files.stat('/workspace/output');
+await sandbox.files.move('/tmp/probe.bin', '/workspace/output/probe.bin');
+await sandbox.files.chmod('/workspace/output/probe.bin', '0640');
+await sandbox.files.remove('/workspace/output', { recursive: true });
+```
+
+Lists contain one level, sorted by UTF-8 filename bytes, with up to 1,000 entries
+per page. Pagination rescans; directory changes can duplicate or omit entries.
+Metadata includes type, size, mode, uid/gid, second-precision modification time
+and symlink target. `stat` inspects a symlink itself unless `followSymlinks: true`.
+Moves never overwrite an existing destination. Removal defaults to files or empty
+directories and removes a symlink itself. Mutation paths cannot be root. These
+operations share the four-operation pool and 30-second file deadline. Recursive
+deletion and moves across filesystems may partly complete before interruption;
+inspect state before retrying a mutation. Watchers remain unsupported.
+
+Versioned local archives can be built and checked with backend `npm run sdk:qualify`.
+Install its `.tgz` with `npm install /path/to/mainbrella-sdk-0.1.0.tgz`; this remains
+an archive installation, not an npm registry release. See the backend
+[SDK release runbook](https://github.com/mainbrella/backend/blob/main/docs/sdk-release.md)
+for artifact and deployed-workflow gates.
+
+Keep the API key in a secret store or environment, never in code or logs. The
+client rejects credential-bearing URLs, redirects, and HTTP except loopback.
+Nonzero command exit codes are returned normally. API failures raise
+`MainbrellaError` with a sanitized code and HTTP status.
+
+Managed execution separates process lifetime from a request:
+
+```js
+const job = await sandbox.commands.start('npm test', { timeoutMs: 300_000 });
+for await (const event of job.events()) {
+  if (event.type === 'stdout') process.stdout.write(event.data);
+}
+const result = await job.get();
+// await job.cancel(); // Explicit cancellation; closing events only detaches.
+```
+
+`events()` reconnects on normal stream rotation and tracks `job.cursor`; a transport
+failure exposes its cursor for explicit reconnect. `job.wait()` polls to terminal
+state. A wait timeout leaves the job running. `new Execution(sandbox, id)` reconnects
+to a known job. Preserve the idempotency key from a failed `commands.start()` call
+and retry the same options within the one-hour retention window. Runtime restart
+interrupts unfinished jobs and stops their matching container generation.
+
+For richer process control, check `execution.argv`, `stdin`, `signals`, `managedProcessListing`, `programmaticPty` and `ptyResize` in `client.capabilities()`:
+
+```js
+const job = await sandbox.commands.start(['cat'], { stdin: true, cwd: '/tmp', env: { TASK: 'probe' } });
+await job.stdin.write(new TextEncoder().encode('hello\n'));
+await job.stdin.close(); // Pipe EOF; no automatic input retry.
+const result = await job.wait();
+const attached = sandbox.commands.attach(job.id);
+const { executions } = await sandbox.commands.list(); // Retained managed jobs.
+const terminal = await sandbox.commands.start(['/bin/sh'], { stdin: true, pty: { cols: 80, rows: 24 } });
+await terminal.resize(132, 40);
+await terminal.stdin.write(new TextEncoder().encode('exit\n'));
+await terminal.wait();
+// await terminal.signal('SIGTERM'); // Delivery request; inspect state afterward.
+```
+
+An array starts the executable directly; a string uses `/bin/sh -lc`. Environment values go into the guest and are not protected secrets. Input caps are 64 KiB per write, 1 MiB accepted per job and 256 KiB pending. Ambiguous writes stay counted and are never retried. PTY output merges stderr into stdout with terminal line discipline; input closure may hang up the terminal. Cancellation targets the operation process group; deliberately detached processes remain bounded by the machine lease. These local helpers require corresponding deployed capabilities. Guest-wide process listing and filesystem watching remain unsupported.
+
+Protected application previews are available only when
+`(await client.capabilities()).previews.supported` is true. Start your application's
+HTTP server in the sandbox first, then create a link for its listening port:
+
+```js
+const preview = await sandbox.previews.create(3000, { ttlSeconds: 900 });
+// Give preview.url to the intended recipient through a private channel.
+const { previews } = await sandbox.previews.list(); // Metadata only, no URLs.
+await sandbox.previews.revoke(preview.id);
+```
+
+Ports are 1024–65535, TTL is 60–3600 seconds (default 900), and at most eight
+grants are active per generation. `expiresAt` is Unix milliseconds, clipped to
+the container deadline. The URL is a bearer credential returned once; keep it
+out of logs and analytics. Listing and revocation work when new issuance is disabled.
+Creation is never retried automatically. After a lost response, list and revoke
+the unwanted grant before creating another link. A `preview_reconciliation_required`
+error exposes `error.previewId`; retry `sandbox.previews.revoke(error.previewId)`.
+Revocation closes active connections. Stopping or replacing the generation
+invalidates its links. Application cookies are stripped; cookie sessions and
+absolute redirect rewriting are unsupported. Host and forwarded host/protocol
+reflect the validated HTTPS preview origin; the caller's Origin is preserved.
+Protected previews are enabled on `mainbrella.dev` after live qualification;
+check `previews.supported` in `/capabilities` before using them.
+
+## Command line
+
+The same local npm archive installs the dependency-free `mainbrella` command. Set `MAINBRELLA_API_KEY` in your environment; optional `MAINBRELLA_API_URL` selects a trusted API origin. Credentials are never CLI arguments. From the project where the archive is installed:
+
+```sh
+./node_modules/.bin/mainbrella --help
+./node_modules/.bin/mainbrella create --size small --idempotency-key stable-create-key
+# Preserve the returned id/createdAt before issuing another command.
+./node_modules/.bin/mainbrella run --id <id> --created-at <generation> --command 'printf hello'
+./node_modules/.bin/mainbrella kill --id <id> --created-at <generation>
+```
+
+`create` and `start` require an explicit stable idempotency key. Errors include it after an ambiguous response. Repeat the same options within retention; never issue a new key to resolve uncertainty. Every workload action requires both container ID and exact generation. There is no bulk-stop command. `job` controls inspect/cancel/stream/signal/resize/send input to known execution IDs; `jobs` lists retained managed jobs. Results are JSON and streamed events are newline-delimited JSON. `run` returns the guest exit code (124 on timeout, 125 on truncated output); API/CLI errors exit 1 and emit sanitized JSON on stderr.
+
+`file read --path /guest/file --output /local/new-file` creates a new local file without overwriting. `file write --path /guest/file --source /local/file` transfers binary bytes up to 1 MiB. `job input --source /local/chunk` accepts up to 64 KiB. CLI input writes never retry automatically. Registry publication and live qualification remain pending.
+
+## Workload observations and webhooks
+
+Check `observability.lifecycleEvents`, `metrics` and `webhooks` first. Lifecycle history belongs to one generation, survives stop, and is bounded to seven days/256 events per slot. Deduplicate stable IDs and order by sequence. Metrics are provider workload observations, separate from billing allocations and public service health; missing evidence remains unobserved/null. Metrics and webhook delivery remain disabled until operator configuration and live qualification.
+
+```js
+const page = await sandbox.events({ cursor: 0, limit: 100 });
+if (page.hasMore) await sandbox.events({ cursor: page.nextCursor });
+const capabilities = await client.capabilities();
+if (capabilities.observability.metrics) {
+  const observations = await sandbox.metrics();
+}
+if (capabilities.observability.webhooks) {
+  const configured = await sandbox.webhook.configure('https://trusted-relay.example/callback', { replayFromCursor: 0 });
+  // Store configured.signingSecret securely, outside guest files/env and logs.
+  const { deliveries } = await sandbox.webhook.deliveries();
+  // await sandbox.webhook.retry(exhaustedEventId);
+  await sandbox.webhook.remove();
+}
+```
+
+For a receiving server, import `verifyWebhookSignature` and call `await verifyWebhookSignature(rawBodyBytes, signatureHeader, signingSecret)` before parsing JSON. It authenticates the exact bytes and a five-minute timestamp window. Persist received event IDs to reject duplicates; delivery can be out of order. The CLI also exposes generation-bound `events` and `metrics` reads.
+
+Targets must be operator-controlled trusted HTTPS relay hosts; arbitrary customer domains, IPs, credentials, ports and redirects are unsupported. Configuration is per generation and expires after seven days. PUT rotates the secret and clears old attempts; it is never retried automatically. Reconcile lost responses, then rotate explicitly if the one-time secret is unavailable. Eight automatic attempts use bounded backoff; exhausted deliveries allow at most three manual retry cycles. Removing configuration cancels future attempts but cannot undo requests a receiver already accepted. See [API.md](https://mainbrella.com/API.md#lifecycle-webhooks) for retention and signature details. OTLP remains unsupported.
+
+## Outbound internet selection
+
+Internet defaults to enabled. Offline creation is immutable for that generation and requires the advertised `networking.internetControl` capability. The SDK checks discovery before admission, fails if a runtime cannot enforce the policy, and confirms the returned selection. It never coerces a string to a boolean. This flag does not configure domain/CIDR allowlists or mediated secrets. Keep the same creation key on ambiguous transport failure; live provider isolation remains a release gate.
+
+```js
+const offline = await client.create({ internet: false, idempotencyKey: "offline-workspace" });
+```
+
+The CLI accepts `create --idempotency-key offline-workspace --internet false`.
+
+The CLI also supports generation-bound `file list/stat/mkdir/remove/move/chmod`. Directory removal is nonrecursive unless `--recursive` is explicit; move refuses replacement. Permission modes use four octal digits (`0640`). Listing accepts `--limit` up to 1000 and `--offset` up to 1000000.
+
+## Saved workspaces
+
+Check `(await client.capabilities()).persistence.snapshots` before using save/restore. Save explicitly; ordinary stop discards changes.
+
+```js
+const saveKey = crypto.randomUUID(); // Persist this key and body before sending.
+const saved = await sandbox.saveWorkspace('Project files', { stop: true, idempotencyKey: saveKey });
+const restored = await client.workspaces.restore(saved.id, { idempotencyKey: crypto.randomUUID() });
+const archive = await restored.exportWorkspace(); // /workspace gzip tar, at most 16 MiB compressed.
+await restored.kill();
+await client.workspaces.delete(saved.id);
+```
+
+`client.workspaces.list()`, `.get(id)` and `.update(id, {name, archived})` manage saved metadata. Retry an ambiguous save with its original body and key (`error.idempotencyKey`). Restore consumes one start, requires the saved image digest, size and internet policy, and restores filesystem bytes with a fresh generation. RAM, processes and previews do not resume. Plan quotas and expiry apply; archive retains quota, while deletion revokes future restores without immediately erasing provider-held bytes.

package/cli.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import { open, realpath, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { Mainbrella, MainbrellaError } from './index.js';
+
+const help = `Mainbrella 0.1.0 — generation-bound container automation
+Set MAINBRELLA_API_KEY in your environment. Optional MAINBRELLA_API_URL.
+
+mainbrella capabilities | list
+mainbrella create --idempotency-key KEY [--size lite|small|medium|large|xl] [--internet true|false] [--catalog-id ID | --image-id ID]
+mainbrella kill --id ID --created-at ISO
+mainbrella run --id ID --created-at ISO --command COMMAND [--timeout-ms N]
+mainbrella start --id ID --created-at ISO --idempotency-key KEY (--command COMMAND | --argv-json JSON) [--stdin] [--cwd PATH] [--env-json JSON] [--pty-cols N --pty-rows N] [--timeout-ms N]
+mainbrella jobs --id ID --created-at ISO
+mainbrella events|metrics --id ID --created-at ISO [--cursor N --limit N | --from ISO --to ISO]
+mainbrella job get|cancel|events|signal|resize|input|close --id ID --created-at ISO --execution-id UUID [--cursor N] [--signal SIGTERM] [--cols N --rows N] [--source FILE]
+mainbrella file read|write --id ID --created-at ISO --path PATH (--output NEW_FILE | --source FILE)
+mainbrella file list|stat --id ID --created-at ISO --path PATH [--limit N --offset N | --follow-symlinks]
+mainbrella file mkdir --id ID --created-at ISO --path PATH [--recursive] [--mode 0700]
+mainbrella file remove --id ID --created-at ISO --path PATH [--recursive]
+mainbrella file move --id ID --created-at ISO --path PATH --destination PATH
+mainbrella file chmod --id ID --created-at ISO --path PATH --mode 0640
+
+Results are JSON; job events are newline-delimited JSON. Errors go to stderr.
+Creation and start require a stable key. Preserve it after an ambiguous response.
+kill affects only the supplied generation. Credentials are never command options.
+`;
+const specifications = {
+  capabilities: [], list: [], create: ['idempotency-key', 'internet', 'size', 'catalog-id', 'image-id'],
+  kill: [], run: ['command', 'timeout-ms'], start: ['idempotency-key', 'command', 'argv-json', 'timeout-ms', 'stdin', 'cwd', 'env-json', 'pty-cols', 'pty-rows'],
+  jobs: [], events: ['cursor', 'limit'], metrics: ['from', 'to'], 'job:get': ['execution-id'], 'job:cancel': ['execution-id'], 'job:events': ['execution-id', 'cursor'],
+  'job:signal': ['execution-id', 'signal'], 'job:resize': ['execution-id', 'cols', 'rows'], 'job:input': ['execution-id', 'source'], 'job:close': ['execution-id'],
+  'file:read': ['path', 'output'], 'file:write': ['path', 'source'],
+  'file:list': ['path', 'limit', 'offset'], 'file:stat': ['path', 'follow-symlinks'],
+  'file:mkdir': ['path', 'recursive', 'mode'], 'file:remove': ['path', 'recursive'], 'file:move': ['path', 'destination'], 'file:chmod': ['path', 'mode'],
+};
+const fail = () => { throw new MainbrellaError('invalid_cli_arguments'); };
+function parse(argv) {
+  const remaining = [...argv];
+  let command = remaining.shift();
+  if (['job', 'file'].includes(command)) command += ':' + remaining.shift();
+  if (!Object.hasOwn(specifications, command)) fail();
+  const hasIdentity = !['capabilities', 'list', 'create'].includes(command);
+  const allowed = new Set([...specifications[command], 'base-url', ...(hasIdentity ? ['id', 'created-at'] : [])]);
+  const options = {};
+  while (remaining.length) {
+    const flag = remaining.shift();
+    if (!flag?.startsWith('--') || !allowed.has(flag.slice(2)) || Object.hasOwn(options, flag.slice(2))) fail();
+    const name = flag.slice(2);
+    if (['stdin', 'recursive', 'follow-symlinks'].includes(name)) options[name] = true;
+    else { if (!remaining.length) fail(); options[name] = remaining.shift(); }
+  }
+  const required = name => { if (typeof options[name] !== 'string' || !options[name]) fail(); return options[name]; };
+  const integer = (name, maximum) => {
+    if (options[name] === undefined) return undefined;
+    if (!/^\d+$/.test(options[name]) || !Number.isSafeInteger(Number(options[name])) || Number(options[name]) > maximum) fail();
+    return Number(options[name]);
+  };
+  const json = name => { try { return JSON.parse(required(name)); } catch { fail(); } };
+  if (hasIdentity) { required('id'); required('created-at'); }
+  if (command === 'create' || command === 'start') { if (!/^[A-Za-z0-9_-]{1,128}$/.test(required('idempotency-key'))) fail(); }
+  if (options.internet !== undefined && !['true', 'false'].includes(options.internet)) fail();
+  if (command.startsWith('job:')) required('execution-id');
+  if (command === 'run') required('command');
+  if (command === 'start' && Boolean(options.command) === Boolean(options['argv-json'])) fail();
+  if (command === 'start' && Boolean(options['pty-cols']) !== Boolean(options['pty-rows'])) fail();
+  if (command.startsWith('file:')) required('path');
+  if (command === 'file:read') required('output');
+  if (command === 'file:write') required('source');
+  if (command === 'file:move') required('destination');
+  if (command === 'file:chmod') required('mode');
+  if (options.mode !== undefined && !/^0[0-7]{3}$/.test(options.mode)) fail();
+  if (command === 'job:input') required('source');
+  if (command === 'job:signal') required('signal');
+  if (command === 'job:resize') { required('cols'); required('rows'); }
+  const timeoutMs = integer('timeout-ms', command === 'run' ? 60_000 : 900_000);
+  if (timeoutMs === 0) fail();
+  const pty = options['pty-cols'] ? { cols: integer('pty-cols', 1000), rows: integer('pty-rows', 1000) } : undefined;
+  if (pty && (!pty.cols || !pty.rows || !options.stdin)) fail();
+  let argvValues, envValues;
+  if (options['argv-json']) { argvValues = json('argv-json'); if (!Array.isArray(argvValues) || !argvValues.length || !argvValues.every(value => typeof value === 'string')) fail(); }
+  if (options['env-json']) { envValues = json('env-json'); if (!envValues || typeof envValues !== 'object' || Array.isArray(envValues) || !Object.values(envValues).every(value => typeof value === 'string')) fail(); }
+  return { command, options, timeoutMs, pty, argvValues, envValues, cursor: integer('cursor', Number.MAX_SAFE_INTEGER), limit: integer('limit', command === 'file:list' ? 1000 : 100), offset: integer('offset', 1_000_000),
+    cols: integer('cols', 1000), rows: integer('rows', 1000) };
+}
+
+async function sourceBytes(path, limit) {
+  const file = await open(path, 'r');
+  try {
+    const stat = await file.stat();
+    if (!stat.isFile()) throw new MainbrellaError('invalid_local_file');
+    if (stat.size > limit) throw new MainbrellaError('input_too_large');
+    const bytes = new Uint8Array(limit + 1); let offset = 0;
+    while (offset < bytes.length) {
+      const { bytesRead } = await file.read(bytes, offset, bytes.length - offset, null);
+      if (!bytesRead) break;
+      offset += bytesRead;
+    }
+    if (offset > limit) throw new MainbrellaError('input_too_large');
+    return bytes.subarray(0, offset);
+  } finally { await file.close(); }
+}
+
+export async function main(argv = process.argv.slice(2), { env = process.env, stdout = process.stdout, stderr = process.stderr, fetch = globalThis.fetch } = {}) {
+  const print = value => stdout.write(JSON.stringify(value) + '\n');
+  try {
+    if (argv.length === 1 && ['--help', '-h'].includes(argv[0])) { stdout.write(help); return 0; }
+    if (argv.length === 1 && argv[0] === '--version') { stdout.write('0.1.0\n'); return 0; }
+    const { command, options, timeoutMs, pty, argvValues, envValues, cursor, limit, offset, cols, rows } = parse(argv);
+    const client = new Mainbrella({ apiKey: env.MAINBRELLA_API_KEY, baseUrl: options['base-url'] || env.MAINBRELLA_API_URL, fetch });
+    if (command === 'capabilities' || command === 'list') { print(await client[command]()); return 0; }
+    if (command === 'create') {
+      const sandbox = await client.create({ idempotencyKey: options['idempotency-key'], size: options.size, internet: options.internet === undefined ? undefined : options.internet === 'true', catalogId: options['catalog-id'], imageId: options['image-id'] });
+      print({ id: sandbox.id, createdAt: sandbox.createdAt, creationId: sandbox.creationId, internet: sandbox.internet, imageDigest: sandbox.imageDigest, instance: sandbox.instance }); return 0;
+    }
+    const sandbox = client.connect({ id: options.id, createdAt: options['created-at'] });
+    if (command === 'kill') print(await sandbox.kill());
+    else if (command === 'jobs') print(await sandbox.commands.list());
+    else if (command === 'events') print(await sandbox.events({ cursor, limit }));
+    else if (command === 'metrics') print(await sandbox.metrics({ from: options.from, to: options.to }));
+    else if (command === 'run') {
+      const result = await sandbox.commands.run(options.command, { timeoutMs }); print(result);
+      return result.timedOut ? 124 : result.outputTruncated ? 125 : Number.isInteger(result.exitCode) && result.exitCode >= 0 && result.exitCode <= 255 ? result.exitCode : 1;
+    } else if (command === 'start') {
+      const job = await sandbox.commands.start(argvValues || options.command, { timeoutMs, stdin: options.stdin, cwd: options.cwd, env: envValues, pty, idempotencyKey: options['idempotency-key'] });
+      print({ id: job.id, containerId: sandbox.id, createdAt: sandbox.createdAt, idempotencyKey: options['idempotency-key'] });
+    } else if (command === 'file:read') {
+      const bytes = await sandbox.files.read(options.path); await writeFile(options.output, bytes, { flag: 'wx', mode: 0o600 }); print({ path: options.path, bytes: bytes.byteLength, output: options.output });
+    } else if (command === 'file:write') print(await sandbox.files.write(options.path, await sourceBytes(options.source, 1024 * 1024)));
+    else if (command === 'file:list') print(await sandbox.files.list(options.path, { limit, offset }));
+    else if (command === 'file:stat') print(await sandbox.files.stat(options.path, { followSymlinks: options['follow-symlinks'] ?? false }));
+    else if (command === 'file:mkdir') print(await sandbox.files.mkdir(options.path, { recursive: options.recursive ?? false, mode: options.mode }));
+    else if (command === 'file:remove') print(await sandbox.files.remove(options.path, { recursive: options.recursive ?? false }));
+    else if (command === 'file:move') print(await sandbox.files.move(options.path, options.destination));
+    else if (command === 'file:chmod') print(await sandbox.files.chmod(options.path, options.mode));
+    else {
+      const job = sandbox.commands.attach(options['execution-id']);
+      const action = command.split(':')[1];
+      if (action === 'events') { for await (const event of job.events({ cursor })) print(event); }
+      else if (action === 'signal') print(await job.signal(options.signal));
+      else if (action === 'resize') print(await job.resize(cols, rows));
+      else if (action === 'input') print(await job.stdin.write(await sourceBytes(options.source, 64 * 1024)));
+      else if (action === 'close') print(await job.stdin.close());
+      else print(await job[action]());
+    }
+    return 0;
+  } catch (error) {
+    const code = error instanceof MainbrellaError ? error.code : error?.code === 'EEXIST' ? 'output_exists' : error?.code === 'ENOENT' ? 'local_file_not_found' : 'cli_failed';
+    stderr.write(JSON.stringify({ error: code, ...(error instanceof MainbrellaError && error.status ? { status: error.status } : {}),
+      ...(error?.idempotencyKey && /^[A-Za-z0-9_-]{1,128}$/.test(error.idempotencyKey) ? { idempotencyKey: error.idempotencyKey } : {}) }) + '\n');
+    return 1;
+  }
+}
+
+if (process.argv[1] && await realpath(process.argv[1]).catch(() => '') === fileURLToPath(import.meta.url)) process.exitCode = await main();

package/index.d.ts

@@ -0,0 +1,88 @@
+export type MachineSize = 'lite' | 'small' | 'medium' | 'large' | 'xl';
+export interface Size { id: MachineSize; name: string; instance: string; cpuVcpu: number; memoryMiB: number; diskGB: number; computeUnits: number }
+export interface ContainerIdentity { id: string; createdAt: string }
+export interface Workspace {id:string;name:string;createdAt:string;expiresAt:number;source:ContainerIdentity;size:MachineSize;internet:boolean;imageDigest:string;imageId?:string;imageName?:string;catalogId?:string;bytes:number|null;archived:boolean;status:'saving'|'ready'|'failed'|'expired'|'deleted';stopRequested:boolean;stopCompleted:boolean}
+export interface FileEntry { name: string; path: string; type: 'file' | 'directory' | 'symlink' | 'fifo' | 'socket' | 'character' | 'block' | 'other'; size: number; mode: string; uid: number; gid: number; modifiedAt: string; linkTarget?: string }
+export interface DirectoryPage { path: string; entries: FileEntry[]; nextOffset: number | null }
+export interface ExecutionOptions { timeoutMs?: number; idempotencyKey?: string; stdin?: boolean; cwd?: string; env?: Record<string, string>; pty?: { cols: number; rows: number } }
+export interface Preview { id: string; port: number; createdAt: string; expiresAt: number }
+export interface PreviewLink extends Preview { url: string }
+export interface CommandResult { stdout: string; stderr: string; exitCode: number | null; timedOut: boolean; outputTruncated: boolean }
+export interface Container extends ContainerIdentity { internet?: boolean; status: 'starting' | 'running'; expiresAt: string; imageName?: string; catalogId?: string; imageId?: string; imageDigest?: string; instance?: string; size?: MachineSize; computeUnits?: number }
+export interface AccountState { plan: 'builder' | 'pro' | 'scale' | null; active: boolean; containers: Container[];
+  sizes: Size[]; imageCatalog: { id: string; name: string }[]; limits: { maxComputeUnitHours: number; maxConcurrentComputeUnits: number; maxContainers: number; maxStartsPerMonth: number; maxSessionMs: number; idleTimeoutMs: number };
+  usage: { month: string; starts: number; computeUnitHours: number; reservedComputeUnitHours: number; availableComputeUnitHours: number; concurrentComputeUnits: number } }
+export interface Capabilities {
+  apiVersion: string;
+  execution: { foreground: boolean; streaming: boolean; background: boolean; cancellation: boolean; reconnect: boolean; pty: boolean;
+    programmaticPty: boolean; ptyResize: boolean; stdin: boolean; signals: boolean; argv: boolean; managedProcessListing: boolean; processListing: boolean;
+    maxStdinChunkBytes: number; maxStdinBytes: number; maxPendingStdinBytes: number;
+    maxCommandBytes: number; maxTimeoutMs: number; maxOutputBytes: number; maxConcurrentOperations: number;
+    maxManagedTimeoutMs: number; retentionMs: number; maxRetainedExecutions: number };
+  files: { read: boolean; write: boolean; binary: boolean; maxFileBytes: number; maxPathBytes: number; timeoutMs: number; [key: string]: boolean | number };
+  persistence: { filesystemAfterStop: boolean; snapshots: boolean; workspaces?:boolean; exports?:boolean; memory: boolean; volumes: boolean };
+  observability: { lifecycleEvents: boolean; metrics: boolean; webhooks: boolean; otlp: boolean; eventRetentionMs: number; maxLifecycleEvents: number; maxMetricRangeMs: number; metricBucketMs: number };
+  previews: { supported: boolean; signedUrls: boolean };
+  containers: { idempotentCreate: boolean; creationRetentionMs: number; generationRequired: boolean; accountLimitsPath: string; configurableDeadline: boolean };
+  resources: Size[];
+  images: { catalog: boolean; customBuilds: boolean; availableCatalogPath: string; limits: Record<string, number> };
+  authentication: Record<string, boolean>; networking: Record<string, boolean>; access: Record<string, number>;
+}
+export class MainbrellaError extends Error { code: string; status: number; idempotencyKey?: string; cursor?: number; previewId?: string; constructor(code: string, status?: number, details?: Record<string, unknown>) }
+export class Mainbrella {
+  constructor(options: { apiKey: string; baseUrl?: string; fetch?: typeof fetch; timeoutMs?: number });
+  baseUrl: string; timeoutMs: number;
+  workspaces:{list():Promise<{workspaces:Workspace[];limits:{maxSaved:number;maxReservedBytes:number;retentionMs:number;maxSavesPerMonth:number}|null;usage:{saved:number;reservedBytes:number}}>;
+    get(id:string):Promise<Workspace>;update(id:string,options:{name?:string;archived?:boolean}):Promise<Workspace>;delete(id:string):Promise<{deleted:true}>;
+    restore(id:string,options?:{idempotencyKey?:string;waitTimeoutMs?:number;pollIntervalMs?:number}):Promise<Sandbox>};
+  request<T = unknown>(path: string, options?: { method?: string; body?: unknown; headers?: Record<string, string>; binary?: boolean; stream?: boolean; signal?: AbortSignal }): Promise<T>;
+  capabilities(): Promise<Capabilities>; list(): Promise<AccountState>; connect(value: ContainerIdentity): Sandbox;
+  create(options?: { catalogId?: string; imageId?: string; workspaceId?:string; size?: MachineSize; internet?: boolean; idempotencyKey?: string; waitTimeoutMs?: number; pollIntervalMs?: number }): Promise<Sandbox>;
+}
+export class Sandbox implements ContainerIdentity {
+  internet?: boolean;
+  constructor(client: Mainbrella, value: ContainerIdentity);
+  client: Mainbrella; id: string; createdAt: string; creationId?: string; imageDigest?: string; instance?: string;
+  files: { read(path: string): Promise<Uint8Array>; write(path: string, bytes: Uint8Array): Promise<{ path: string; size: number }>;
+    list(path: string, options?: { limit?: number; offset?: number }): Promise<DirectoryPage>;
+    stat(path: string, options?: { followSymlinks?: boolean }): Promise<FileEntry>;
+    mkdir(path: string, options?: { recursive?: boolean; mode?: string }): Promise<{ path: string; ok: true }>;
+    remove(path: string, options?: { recursive?: boolean }): Promise<{ path: string; ok: true }>;
+    move(path: string, destination: string): Promise<{ path: string; destination: string; ok: true }>;
+    chmod(path: string, mode: string): Promise<{ path: string; mode: string; ok: true }> };
+  previews: { create(port: number, options?: { ttlSeconds?: number }): Promise<PreviewLink>;
+    list(): Promise<{ previews: Preview[] }>; revoke(previewId: string): Promise<{ revoked: true }> };
+  commands: { run(command: string, options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<CommandResult>;
+    start(command: string | string[], options?: ExecutionOptions): Promise<Execution>;
+    list(): Promise<{ executions: Omit<ExecutionRecord, 'stdout' | 'stderr'>[] }>; attach(id: string): Execution };
+  kill(): Promise<AccountState>;
+  workspaceId?:string;
+  saveWorkspace(name:string,options?:{stop?:boolean;idempotencyKey?:string}):Promise<Workspace>;
+  exportWorkspace():Promise<Uint8Array>;
+  webhook: { get(): Promise<{webhook: WebhookConfig | null}>; configure(url: string, options?: {replayFromCursor?: number}): Promise<{webhook: WebhookConfig; signingSecret: string}>;
+    remove(): Promise<{removed: true}>; deliveries(): Promise<{deliveries: WebhookDelivery[]}>; retry(eventId: string): Promise<WebhookDelivery> };
+  events(options?: {cursor?: number; limit?: number}): Promise<LifecyclePage>;
+  metrics(options?: {from?: string; to?: string}): Promise<WorkloadMetrics>;
+}
+export interface LifecycleEvent { id: string; sequence: number; createdAt: string; occurredAt: string; type: 'starting' | 'started' | 'failed' | 'stopped'; reason?: string; size: MachineSize; retainUntil: number }
+export interface LifecyclePage { events: LifecycleEvent[]; nextCursor: number; hasMore: boolean; historyTruncated: boolean; retainForMs: number }
+export interface WorkloadMetrics { id: string; createdAt: string; from: string; to: string; bucketMs: number; source: 'cloudflare-workload-analytics'; state: 'observed' | 'unobserved'; buckets: {at: string; samples: number; cpuSeconds: number | null; memoryPeakBytes: number | null; diskUsagePeak: number | null}[] }
+export const terminalExecutionStates: Set<string>;
+export function verifyWebhookSignature(bytes: Uint8Array, signature: string, signingSecret: string, options?: {nowMs?: number; toleranceSeconds?: number}): Promise<boolean>;
+export interface WebhookConfig { id: string; url: string; createdAt: string; configuredAt: string; retainUntil: number }
+export interface WebhookDelivery { id: string; sequence: number; status: 'pending' | 'sending' | 'delivered' | 'exhausted'; attempts: number; manualRetries: number; nextAt: number | null; retainUntil: number; lastAttemptAt?: number; httpStatus?: number | null }
+export interface ExecutionRecord extends CommandResult {
+  id: string; createdAt: string; startedAt: string; finishedAt?: string; retainUntil: number; cursor: number; outputBytes: number;
+  status: 'starting' | 'running' | 'succeeded' | 'failed' | 'canceled' | 'timed_out' | 'output_limit' | 'interrupted';
+  pty?: { cols: number; rows: number }; stdinEnabled?: boolean; stdinClosed?: boolean; stdinBytes?: number;
+}
+export type ExecutionEvent = { type: 'stdout' | 'stderr'; data: string; sequence: number } | { type: 'status'; execution: Omit<ExecutionRecord, 'stdout' | 'stderr'> };
+export class Execution {
+  constructor(sandbox: Sandbox, id: string); id: string; cursor: number;
+  get(): Promise<ExecutionRecord>; cancel(): Promise<Omit<ExecutionRecord, 'stdout' | 'stderr'>>;
+  resize(cols: number, rows: number): Promise<Omit<ExecutionRecord, 'stdout' | 'stderr'>>;
+  signal(signal: 'SIGINT' | 'SIGTERM' | 'SIGKILL'): Promise<Omit<ExecutionRecord, 'stdout' | 'stderr'>>;
+  stdin: { write(bytes: Uint8Array): Promise<{ bytes: number; stdinClosed: boolean }>; close(): Promise<{ bytes: number; stdinClosed: boolean }> };
+  wait(options?: { timeoutMs?: number; pollIntervalMs?: number }): Promise<ExecutionRecord>;
+  events(options?: { cursor?: number; signal?: AbortSignal }): AsyncGenerator<ExecutionEvent>;
+}