@watasu/sdk 0.1.6 → 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,11 +26,49 @@ 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',
@@ -52,17 +90,26 @@ await sbx.git.push('/workspace/project', {
   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' })
 
-const watcher = await sbx.files.watchDir('/workspace/project', (event) => {
+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)
-}, { recursive: true })
+})
+await watcher.start({ recursive: true })
 
-const terminal = await sbx.pty.create({
-  cols: 100,
-  rows: 30,
+const terminal = await sbx.terminal.start({
+  size: { cols: 100, rows: 30 },
   onData: (data) => process.stdout.write(data),
 })
-await terminal.sendStdin('echo hello\n')
+await terminal.sendData('echo hello\n')
 
 const uploadUrl = await sbx.uploadUrl('/workspace/input.bin')
 const downloadUrl = await sbx.downloadUrl('/workspace/output.bin')
@@ -72,6 +119,54 @@ 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
@@ -81,6 +176,7 @@ 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,14 +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. */
@@ -48,28 +60,31 @@ export declare class CommandHandle implements Partial<CommandResult> {
     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, onPty?: ((data: Uint8Array) => 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. */
@@ -78,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;
@@ -90,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, base64DecodeBytes, base64DecodeText } from './processSocket.js';
-import { SandboxError } from './errors.js';
+import { SandboxError, TimeoutError } from './errors.js';
 /** Error thrown by `CommandHandle.wait()` when a process exits non-zero. */
 export class CommandExitError extends SandboxError {
     result;
@@ -22,11 +22,12 @@ export class CommandHandle {
     onStdout;
     onStderr;
     onPty;
+    onExit;
     _stdout = '';
     _stderr = '';
     result;
     pending;
-    constructor(pid, socket, handleKill, events, onStdout, onStderr, onPty) {
+    constructor(pid, socket, handleKill, events, onStdout, onStderr, onPty, onExit) {
         this.pid = pid;
         this.socket = socket;
         this.handleKill = handleKill;
@@ -34,6 +35,7 @@ export class CommandHandle {
         this.onStdout = onStdout;
         this.onStderr = onStderr;
         this.onPty = onPty;
+        this.onExit = onExit;
         this.pending = this.handleEvents();
     }
     get stdout() { return this._stdout; }
@@ -41,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)
@@ -57,12 +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() {
@@ -88,12 +94,14 @@ export class CommandHandle {
                     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') {
@@ -116,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);
@@ -137,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. */
@@ -145,7 +167,7 @@ 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 = {}) {
@@ -154,27 +176,44 @@ export class Commands {
         const actualPid = framePid(first) ?? pid;
         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, opts.onPty);
+        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

@@ -21,6 +21,11 @@ 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;
@@ -33,6 +38,17 @@ export interface WatchOpts {
     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;
@@ -46,22 +62,45 @@ export declare class WatchHandle {
     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;
@@ -88,5 +127,6 @@ export declare class Filesystem {
         requestTimeoutMs?: number;
     }): Promise<boolean>;
     /** Start watching a directory for filesystem events. */
-    watchDir(path: string, onEvent: (event: FilesystemEvent) => void | Promise<void>, opts?: WatchOpts): Promise<WatchHandle>;
+    watchDir(path: string): FilesystemWatcher;
+    watchDir(path: string, onEvent: (event: FilesystemEvent) => void | Promise<void>, opts?: WatchOpts): Promise<FilesystemWatcher>;
 }