@watasu/sdk 0.1.5 → 0.1.24

package/README.md

@@ -16,8 +16,8 @@ Set `WATASU_API_KEY` before using the SDK.
 import { Sandbox } from '@watasu/sdk'
 
 const sbx = await Sandbox.create()
-await sbx.files.write('/home/user/a.js', 'console.log(2 + 2)')
-const result = await sbx.commands.run('node /home/user/a.js')
+await sbx.filesystem.write('/home/user/a.js', 'console.log(2 + 2)')
+const result = await sbx.process.startAndWait('node /home/user/a.js')
 console.log(result.stdout)
 console.log(await sbx.isRunning())
 await sbx.kill()
@@ -26,6 +26,147 @@ await sbx.kill()
 `Sandbox.create` and `Sandbox.connect` return only after the Watasu API supplies
 a usable data-plane session. The SDK does not poll sandbox readiness.
 
+```ts
+await sbx.betaPause()
+await sbx.resume({ timeoutMs: 300_000 })
+```
+
+## MCP Gateway
+
+```ts
+const sbx = await Sandbox.create({
+  mcp: {
+    github: {
+      command: 'github-mcp-server',
+      args: ['stdio'],
+      env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
+    },
+  },
+})
+
+console.log(sbx.getMcpUrl())
+console.log(await sbx.getMcpToken())
+```
+
+## Listing Sandboxes
+
+```ts
+import { Sandbox } from '@watasu/sdk'
+
+const paginator = Sandbox.list({
+  query: { metadata: { purpose: 'ci' }, state: ['running'] },
+  limit: 20,
+})
+
+for (const sandbox of await paginator.listItems()) {
+  console.log(sandbox.sandboxId, sandbox.state)
+}
+```
+
+## Git, Watch, PTY, And Signed File URLs
+
+```ts
+const sbx = await Sandbox.create()
+
+await sbx.git.init('/workspace/new-project', { initialBranch: 'main' })
+await sbx.git.clone('https://github.com/acme/project.git', {
+  path: '/workspace/project',
+  branch: 'main',
+  depth: 1,
+})
+const status = await sbx.git.status('/workspace/project')
+await sbx.git.configureUser('Watasu Bot', 'bot@watasu.local', {
+  scope: 'local',
+  path: '/workspace/project',
+})
+await sbx.git.createBranch('/workspace/project', 'feature/docs')
+await sbx.git.add('/workspace/project', { files: ['README.md'] })
+await sbx.git.commit('/workspace/project', 'Update docs', {
+  authorName: 'Watasu Bot',
+  authorEmail: 'bot@watasu.local',
+})
+await sbx.git.push('/workspace/project', {
+  remote: 'origin',
+  branch: 'feature/docs',
+  setUpstream: true,
+})
+const remoteUrl = await sbx.git.remoteGet('/workspace/project', 'origin')
+await sbx.git.restore('/workspace/project', { paths: ['README.md'] })
+await sbx.git.reset('/workspace/project', { mode: 'hard', target: 'HEAD' })
+
+await sbx.filesystem.writeFiles([
+  { path: '/workspace/project/a.txt', data: 'alpha' },
+  { path: '/workspace/project/b.bin', data: new Uint8Array([0, 1, 2]) },
+])
+
+const watcher = sbx.filesystem.watchDir('/workspace/project')
+watcher.addEventListener((event) => {
+  console.log(event.type, event.path)
+})
+await watcher.start({ recursive: true })
+
+const terminal = await sbx.terminal.start({
+  size: { cols: 100, rows: 30 },
+  onData: (data) => process.stdout.write(data),
+})
+await terminal.sendData('echo hello\n')
+
+const uploadUrl = await sbx.uploadUrl('/workspace/input.bin')
+const downloadUrl = await sbx.downloadUrl('/workspace/output.bin')
+
+watcher.stop()
+await terminal.kill()
+await sbx.kill()
+```
+
+## Network Policy
+
+```ts
+const sbx = await Sandbox.create({
+  network: {
+    allowOut: ['pypi.org:443'],
+    denyOut: ['169.254.169.254'],
+  },
+})
+
+await sbx.updateNetwork({
+  allowInternetAccess: false,
+  allowPackageRegistryAccess: true,
+  allowOut: ['pypi.org:443', 'registry.npmjs.org:443'],
+})
+```
+
+## Template Builds
+
+```ts
+import { Template } from '@watasu/sdk'
+
+const template = Template()
+  .fromPythonImage('3.12')
+  .copy('requirements.txt', '/workspace/requirements.txt')
+  .aptInstall(['git'])
+  .pipInstall(['pytest'])
+  .setEnvs({ PIP_DISABLE_PIP_VERSION_CHECK: '1' })
+  .runCmd('echo ready')
+
+const build = await Template.buildInBackground(template, 'python-ci:stable', {
+  tags: ['stable'],
+  cpuCount: 2,
+  memoryMB: 2048,
+})
+const status = await Template.getBuildStatus(build)
+
+await Template.assignTags('python-ci:stable', ['prod'])
+console.log(await Template.exists('python-ci'))
+```
+
+Template names resolve server-side. `python-ci` starts the latest ready build;
+`python-ci:stable` starts the tagged build.
+
+`Template({ fileContextPath: process.cwd() }).fromDockerfile('Dockerfile')`
+parses common `FROM`, `WORKDIR`, `COPY`, `RUN`, `ENV`, `CMD`, and `ENTRYPOINT`
+instructions into Watasu's package-spec builder.
+
 ## Metrics And Snapshots
 
 ```ts
@@ -35,7 +176,9 @@ const sbx = await Sandbox.create()
 const metrics = await sbx.getMetrics()
 const snapshot = await sbx.createSnapshot({ name: 'ready' })
 const snapshots = await sbx.listSnapshots().nextItems()
+const allSnapshots = await Sandbox.listSnapshots({ limit: 100 }).nextItems()
 const restored = await sbx.restore({ snapshotId: snapshot.snapshotId })
+await sbx.deleteSnapshot(snapshot.snapshotId)
 await sbx.kill()
 ```
 

package/dist/commands.d.ts

@@ -29,13 +29,26 @@ export interface ProcessInfo {
 export interface CommandStartOpts {
     /** Return a `CommandHandle` immediately instead of waiting for exit. */
     background?: boolean;
+    /** Executable to start directly. When omitted, `cmd` strings run through a login shell. */
+    cmd?: string;
+    /** Arguments for `cmd` when starting a direct executable. */
+    args?: string[];
     cwd?: string;
+    /** Deprecated alias for `cwd`. */
+    rootDir?: string;
     user?: string;
     envs?: Record<string, string>;
+    /** Alias for `envs`. */
+    envVars?: Record<string, string>;
     onStdout?: (data: string) => void | Promise<void>;
     onStderr?: (data: string) => void | Promise<void>;
+    onPty?: (data: Uint8Array) => void | Promise<void>;
+    onExit?: (exitCode: number) => void | Promise<void>;
     stdin?: boolean;
     timeoutMs?: number;
+    /** Alias for `timeoutMs`. */
+    timeout?: number;
+    processID?: string;
     requestTimeoutMs?: number;
 }
 /** Live handle for one sandbox process stream. */
@@ -46,23 +59,32 @@ export declare class CommandHandle implements Partial<CommandResult> {
     private readonly events;
     private readonly onStdout?;
     private readonly onStderr?;
+    private readonly onPty?;
+    private readonly onExit?;
     private _stdout;
     private _stderr;
     private result?;
     private readonly pending;
-    constructor(pid: number | string, socket: ProcessSocket, handleKill: () => Promise<boolean>, events: AsyncIterable<ProcessFrame>, onStdout?: ((data: string) => void | Promise<void>) | undefined, onStderr?: ((data: string) => void | Promise<void>) | undefined);
+    constructor(pid: number | string, socket: ProcessSocket, handleKill: () => Promise<boolean>, events: AsyncIterable<ProcessFrame>, onStdout?: ((data: string) => void | Promise<void>) | undefined, onStderr?: ((data: string) => void | Promise<void>) | undefined, onPty?: ((data: Uint8Array) => void | Promise<void>) | undefined, onExit?: ((exitCode: number) => void | Promise<void>) | undefined);
     get stdout(): string;
     get stderr(): string;
     get exitCode(): number | undefined;
     get error(): string | undefined;
     /** Wait until the process exits and return captured output. */
-    wait(): Promise<CommandResult>;
+    wait(timeoutMs?: number): Promise<CommandResult>;
     /** Kill the process. */
     kill(): Promise<boolean>;
     /** Send stdin bytes or text to the process. */
     sendStdin(data: string | Uint8Array): Promise<void>;
+    /** Close the stdin stream and signal EOF to the process. */
+    closeStdin(): Promise<void>;
+    /** Resize the attached PTY stream when this handle was created as a PTY. */
+    resize(size: {
+        cols: number;
+        rows: number;
+    }): Promise<void>;
     /** Detach the local stream without killing the process. */
-    disconnect(): void;
+    disconnect(): Promise<void>;
     private handleEvents;
 }
 /** Command runner for a sandbox data-plane session. */
@@ -71,6 +93,8 @@ export declare class Commands {
     private readonly config;
     private readonly sandboxEnvs;
     constructor(dataPlane: DataPlaneClient, config: ConnectionConfig, sandboxEnvs?: Record<string, string>);
+    /** Whether this runtime supports stdin EOF frames. */
+    get supportsStdinClose(): boolean;
     /** List processes currently known by the sandbox runtime. */
     list(opts?: {
         requestTimeoutMs?: number;
@@ -83,11 +107,16 @@ export declare class Commands {
     sendStdin(pid: number | string, data: string | Uint8Array, opts?: {
         requestTimeoutMs?: number;
     }): Promise<void>;
+    /** Attach to a process and close stdin, signalling EOF. */
+    closeStdin(pid: number | string, opts?: {
+        requestTimeoutMs?: number;
+    }): Promise<void>;
     run(cmd: string, opts: CommandStartOpts & {
         background: true;
     }): Promise<CommandHandle>;
     run(cmd: string, opts?: CommandStartOpts): Promise<CommandResult>;
     /** Reconnect to a live process stream by pid. */
     connect(pid: number | string, opts?: CommandStartOpts): Promise<CommandHandle>;
-    private start;
+    /** Start a command and return a live handle immediately. */
+    start(cmd: string, opts?: CommandStartOpts): Promise<CommandHandle>;
 }

package/dist/commands.js

@@ -1,5 +1,5 @@
-import { ProcessSocket, base64DecodeText } from './processSocket.js';
-import { SandboxError } from './errors.js';
+import { ProcessSocket, base64DecodeBytes, base64DecodeText } from './processSocket.js';
+import { SandboxError, TimeoutError } from './errors.js';
 /** Error thrown by `CommandHandle.wait()` when a process exits non-zero. */
 export class CommandExitError extends SandboxError {
     result;
@@ -21,17 +21,21 @@ export class CommandHandle {
     events;
     onStdout;
     onStderr;
+    onPty;
+    onExit;
     _stdout = '';
     _stderr = '';
     result;
     pending;
-    constructor(pid, socket, handleKill, events, onStdout, onStderr) {
+    constructor(pid, socket, handleKill, events, onStdout, onStderr, onPty, onExit) {
         this.pid = pid;
         this.socket = socket;
         this.handleKill = handleKill;
         this.events = events;
         this.onStdout = onStdout;
         this.onStderr = onStderr;
+        this.onPty = onPty;
+        this.onExit = onExit;
         this.pending = this.handleEvents();
     }
     get stdout() { return this._stdout; }
@@ -39,8 +43,8 @@ export class CommandHandle {
     get exitCode() { return this.result?.exitCode; }
     get error() { return this.result?.error; }
     /** Wait until the process exits and return captured output. */
-    async wait() {
-        await this.pending;
+    async wait(timeoutMs) {
+        await waitFor(this.pending, timeoutMs);
         if (!this.result)
             throw new SandboxError('Command ended without an exit event');
         if (this.result.exitCode !== 0)
@@ -55,8 +59,16 @@ export class CommandHandle {
     async sendStdin(data) {
         this.socket.sendStdin(data);
     }
+    /** Close the stdin stream and signal EOF to the process. */
+    async closeStdin() {
+        this.socket.closeStdin();
+    }
+    /** Resize the attached PTY stream when this handle was created as a PTY. */
+    async resize(size) {
+        this.socket.sendJson({ type: 'resize', cols: size.cols, rows: size.rows });
+    }
     /** Detach the local stream without killing the process. */
-    disconnect() {
+    async disconnect() {
         this.socket.close();
     }
     async handleEvents() {
@@ -75,13 +87,21 @@ export class CommandHandle {
                     this._stderr += out;
                     await this.onStderr?.(out);
                 }
+                else if (type === 'pty') {
+                    const bytes = base64DecodeBytes(frame.data);
+                    const out = new TextDecoder().decode(bytes);
+                    this._stdout += out;
+                    await this.onPty?.(bytes);
+                }
                 else if (type === 'exit') {
+                    const exitCode = Number(frame.exit_code ?? frame.exitCode ?? 0);
                     this.result = {
-                        exitCode: Number(frame.exit_code ?? frame.exitCode ?? 0),
+                        exitCode,
                         error: typeof frame.error === 'string' ? frame.error : undefined,
                         stdout: this._stdout,
                         stderr: this._stderr,
                     };
+                    await this.onExit?.(exitCode);
                     return;
                 }
                 else if (type === 'error') {
@@ -104,6 +124,10 @@ export class Commands {
         this.config = config;
         this.sandboxEnvs = sandboxEnvs;
     }
+    /** Whether this runtime supports stdin EOF frames. */
+    get supportsStdinClose() {
+        return true;
+    }
     /** List processes currently known by the sandbox runtime. */
     async list(opts = {}) {
         const payload = await this.dataPlane.getJson('/runtime/v1/process', opts);
@@ -125,7 +149,17 @@ export class Commands {
             await handle.sendStdin(data);
         }
         finally {
-            handle.disconnect();
+            await handle.disconnect();
+        }
+    }
+    /** Attach to a process and close stdin, signalling EOF. */
+    async closeStdin(pid, opts = {}) {
+        const handle = await this.connect(pid, opts);
+        try {
+            await handle.closeStdin();
+        }
+        finally {
+            await handle.disconnect();
         }
     }
     /** Run a shell command over the WebSocket process runtime. */
@@ -133,36 +167,53 @@ export class Commands {
         const handle = await this.start(cmd, opts);
         if (opts.background)
             return handle;
-        return handle.wait();
+        return handle.wait(opts.timeoutMs ?? opts.timeout);
     }
     /** Reconnect to a live process stream by pid. */
     async connect(pid, opts = {}) {
         const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, `/runtime/v1/process/${pid}/connect?since=0`, opts.requestTimeoutMs ?? this.config.requestTimeoutMs).connect();
         const first = await nextStarted(socket);
         const actualPid = framePid(first) ?? pid;
-        return new CommandHandle(actualPid, socket, () => this.kill(actualPid), socket, opts.onStdout, opts.onStderr);
+        return new CommandHandle(actualPid, socket, () => this.kill(actualPid), socket, opts.onStdout, opts.onStderr, opts.onPty);
     }
-    async start(cmd, opts) {
+    /** Start a command and return a live handle immediately. */
+    async start(cmd, opts = {}) {
         const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, '/runtime/v1/process', opts.requestTimeoutMs ?? this.config.requestTimeoutMs).connect();
-        const environment = { ...this.sandboxEnvs, ...(opts.envs ?? {}) };
+        const environment = { ...this.sandboxEnvs, ...(opts.envVars ?? opts.envs ?? {}) };
+        const processConfig = processStartConfig(cmd, opts);
         socket.sendJson({
             type: 'start',
-            cmd: '/bin/bash',
-            args: ['-l', '-c', cmd],
-            cwd: opts.cwd,
+            id: opts.processID,
+            cmd: processConfig.cmd,
+            args: processConfig.args,
+            cwd: opts.cwd ?? opts.rootDir,
             user: opts.user,
             environment,
             envs: environment,
             stdin: opts.stdin ?? false,
-            timeout_ms: opts.timeoutMs ?? 60_000,
+            timeout_ms: opts.timeoutMs ?? opts.timeout ?? 60_000,
         });
         const first = await nextStarted(socket);
         const pid = framePid(first);
         if (pid === undefined)
             throw new SandboxError('process started frame did not include pid');
-        return new CommandHandle(pid, socket, () => this.kill(pid), withFirst(first, socket), opts.onStdout, opts.onStderr);
+        return new CommandHandle(pid, socket, () => this.kill(pid), withFirst(first, socket), opts.onStdout, opts.onStderr, opts.onPty, opts.onExit);
     }
 }
+function processStartConfig(cmd, opts) {
+    if (opts.args !== undefined || opts.cmd !== undefined) {
+        return { cmd: opts.cmd ?? cmd, args: opts.args ?? [] };
+    }
+    return { cmd: '/bin/bash', args: ['-l', '-c', cmd] };
+}
+function waitFor(promise, timeoutMs) {
+    if (timeoutMs === undefined || timeoutMs <= 0)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new TimeoutError()), timeoutMs);
+        promise.then(resolve, reject).finally(() => clearTimeout(timer));
+    });
+}
 async function nextStarted(events) {
     for await (const frame of events) {
         if (frame.type === 'started')

package/dist/errors.d.ts

@@ -7,6 +7,9 @@ export declare class AuthenticationError extends SandboxError {
 export declare class NotFoundError extends SandboxError {
     constructor(message?: string);
 }
+export declare class ConflictError extends SandboxError {
+    constructor(message?: string);
+}
 export declare class TimeoutError extends SandboxError {
     constructor(message?: string);
 }

package/dist/errors.js

@@ -16,6 +16,12 @@ export class NotFoundError extends SandboxError {
         this.name = 'NotFoundError';
     }
 }
+export class ConflictError extends SandboxError {
+    constructor(message = 'Conflict') {
+        super(message);
+        this.name = 'ConflictError';
+    }
+}
 export class TimeoutError extends SandboxError {
     constructor(message = 'Request timed out') {
         super(message);
@@ -76,6 +82,8 @@ export function errorFromResponse(status, payload) {
         return new AuthenticationError(message);
     if (status === 404)
         return new NotFoundError(message);
+    if (status === 409)
+        return new ConflictError(message);
     if (status === 408 || status === 504)
         return new TimeoutError(message);
     if (status === 422 || status === 400)

package/dist/filesystem.d.ts

@@ -1,4 +1,5 @@
 import { DataPlaneClient } from './transport.js';
+import { ProcessFrame, ProcessSocket } from './processSocket.js';
 export declare enum FileType {
     /** Regular file. */
     FILE = "file",
@@ -20,22 +21,86 @@ export interface EntryInfo {
     metadata?: Record<string, string>;
 }
 export type WriteInfo = EntryInfo;
+export type WriteData = string | Uint8Array | ArrayBuffer | Blob | ReadableStream<Uint8Array>;
+export interface WriteEntry {
+    path: string;
+    data: WriteData;
+}
+export interface FilesystemEvent {
+    type: 'create' | 'write' | 'modify' | 'remove' | 'delete' | 'rename' | string;
+    path: string;
+    entry?: EntryInfo;
+    raw: Record<string, unknown>;
+}
+export interface WatchOpts {
+    recursive?: boolean;
+    includeEntry?: boolean;
+    requestTimeoutMs?: number;
+    onExit?: (error?: Error) => void | Promise<void>;
+}
+export interface FilesystemRequestOpts {
+    requestTimeoutMs?: number;
+    user?: string;
+}
+export interface FilesystemReadOpts extends FilesystemRequestOpts {
+    gzip?: boolean;
+}
+export interface FilesystemWriteOpts extends FilesystemRequestOpts {
+    gzip?: boolean;
+    metadata?: Record<string, string>;
+}
+/** Live filesystem watcher. Call `stop()` to close the local watch stream. */
+export declare class WatchHandle {
+    private readonly socket;
+    private readonly done;
+    constructor(socket: ProcessSocket, events: AsyncIterable<ProcessFrame>, onEvent: (event: FilesystemEvent) => void | Promise<void>, onExit?: (error?: Error) => void | Promise<void>);
+    /** Stop watching the directory. */
+    stop(): void;
+    /** Alias for `stop`. */
+    close(): void;
+    /** Resolves when the watcher stream exits. */
+    wait(): Promise<void>;
+    private pump;
+}
+/** Lazy filesystem watcher. Add listeners, then call `start()`. */
+export declare class FilesystemWatcher {
+    private readonly dataPlane;
+    private readonly path;
+    private readonly opts;
+    private handle?;
+    private listeners;
+    constructor(dataPlane: DataPlaneClient, path: string, opts?: WatchOpts);
+    start(opts?: WatchOpts): Promise<void>;
+    stop(): Promise<void>;
+    addEventListener(listener: (event: FilesystemEvent) => void | Promise<void>): () => boolean;
+    wait(): Promise<void>;
+}
 /** Filesystem helper for a sandbox data-plane session. */
 export declare class Filesystem {
     private readonly dataPlane;
     constructor(dataPlane: DataPlaneClient);
-    /** Read a file as UTF-8 text, bytes, or a one-chunk async byte stream. */
-    read(path: string, opts?: {
-        format?: 'text' | 'bytes' | 'stream';
-        requestTimeoutMs?: number;
-        gzip?: boolean;
-    }): Promise<string | Uint8Array | AsyncIterable<Uint8Array>>;
-    /** Write UTF-8 text or bytes to a file. */
-    write(path: string, data: string | Uint8Array, opts?: {
-        requestTimeoutMs?: number;
-        gzip?: boolean;
-        metadata?: Record<string, string>;
-    }): Promise<WriteInfo>;
+    /** Read file content as text, bytes, a `Blob`, or a `ReadableStream`. */
+    read(path: string, opts?: FilesystemReadOpts & {
+        format?: 'text';
+    }): Promise<string>;
+    read(path: string, opts: FilesystemReadOpts & {
+        format: 'bytes';
+    }): Promise<Uint8Array>;
+    read(path: string, opts: FilesystemReadOpts & {
+        format: 'blob';
+    }): Promise<Blob>;
+    read(path: string, opts: FilesystemReadOpts & {
+        format: 'stream';
+    }): Promise<ReadableStream<Uint8Array>>;
+    /** Read a file as raw bytes. */
+    readBytes(path: string, opts?: FilesystemReadOpts): Promise<Uint8Array>;
+    /** Write UTF-8 text, bytes, browser data objects, or a batch of file entries. */
+    write(path: string, data: WriteData, opts?: FilesystemWriteOpts): Promise<WriteInfo>;
+    write(files: WriteEntry[], opts?: FilesystemWriteOpts): Promise<WriteInfo[]>;
+    /** Write raw bytes to a file. */
+    writeBytes(path: string, data: Uint8Array | ArrayBuffer, opts?: FilesystemWriteOpts): Promise<WriteInfo>;
+    /** Write several files in one runtime API call. */
+    writeFiles(files: WriteEntry[], opts?: FilesystemWriteOpts): Promise<WriteInfo[]>;
     /** List directory entries below `path`. */
     list(path: string, opts?: {
         requestTimeoutMs?: number;
@@ -61,5 +126,7 @@ export declare class Filesystem {
     makeDir(path: string, opts?: {
         requestTimeoutMs?: number;
     }): Promise<boolean>;
-    watchDir(): never;
+    /** Start watching a directory for filesystem events. */
+    watchDir(path: string): FilesystemWatcher;
+    watchDir(path: string, onEvent: (event: FilesystemEvent) => void | Promise<void>, opts?: WatchOpts): Promise<FilesystemWatcher>;
 }