@watasu/sdk 0.1.6 → 0.1.25

package/dist/index.js

@@ -1,8 +1,13 @@
-export { ApiError, AuthenticationError, FileNotFoundError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, NotImplementedError, RateLimitError, SandboxError, TimeoutError, } from './errors.js';
+export { ApiError, AuthenticationError, ConflictError, FileNotFoundError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, NotImplementedError, RateLimitError, SandboxError, TimeoutError, } from './errors.js';
 export { ConnectionConfig, KEEPALIVE_PING_INTERVAL_SEC } from './connectionConfig.js';
-export { Sandbox, SnapshotPaginator } from './sandbox.js';
+export { Sandbox, SandboxPaginator, SnapshotPaginator } from './sandbox.js';
+export { Sandbox as CodeInterpreterSandbox } from './codeInterpreter.js';
+export { Context as CodeInterpreterContext, Execution as CodeInterpreterExecution, ExecutionError as CodeInterpreterExecutionError, OutputMessage as CodeInterpreterOutputMessage, Result as CodeInterpreterResult, } from './codeInterpreter.js';
 export { CommandExitError, CommandHandle, Commands } from './commands.js';
-export { FileType, Filesystem, WatchHandle } from './filesystem.js';
+export { Process, ProcessManager, ProcessMessage, ProcessOutput } from './process.js';
+export { FileType, Filesystem, FilesystemWatcher, WatchHandle } from './filesystem.js';
 export { Git } from './git.js';
 export { Pty } from './pty.js';
+export { Terminal, TerminalManager, TerminalOutput } from './terminal.js';
 export { ProcessSocket, base64DecodeBytes, base64DecodeText, base64Encode } from './processSocket.js';
+export { ReadyCmd, Template, TemplateBase, waitForFile, waitForPort, waitForProcess, waitForTimeout, waitForURL, waitForUrl, } from './template.js';

package/dist/process.d.ts

@@ -0,0 +1,56 @@
+import { CommandHandle, CommandResult, Commands, CommandStartOpts } from './commands.js';
+/** A message emitted by a sandbox process. */
+export declare class ProcessMessage {
+    readonly line: string;
+    /** Unix epoch in nanoseconds. */
+    readonly timestamp: number;
+    readonly error: boolean;
+    constructor(line: string, 
+    /** Unix epoch in nanoseconds. */
+    timestamp: number, error: boolean);
+    toString(): string;
+}
+/** Captured output from a sandbox process. */
+export declare class ProcessOutput {
+    private messages;
+    private _finished;
+    private _error;
+    private _exitCode;
+    get error(): boolean;
+    get exitCode(): number | undefined;
+    get stdout(): string;
+    get stderr(): string;
+    addStdout(message: ProcessMessage): void;
+    addStderr(message: ProcessMessage): void;
+    setExitCode(exitCode: number): void;
+    replace(result: CommandResult): void;
+}
+export interface ProcessOpts extends Omit<CommandStartOpts, 'cmd' | 'args' | 'onStdout' | 'onStderr' | 'onExit'> {
+    cmd: string;
+    onStdout?: (out: ProcessMessage) => Promise<void> | void;
+    onStderr?: (out: ProcessMessage) => Promise<void> | void;
+    onExit?: ((exitCode: number) => Promise<void> | void) | (() => Promise<void> | void);
+}
+/** A running sandbox process. */
+export declare class Process {
+    readonly processID: string;
+    private readonly handle;
+    readonly output: ProcessOutput;
+    private readonly onExit?;
+    readonly finished: Promise<ProcessOutput>;
+    private waitPromise?;
+    constructor(processID: string, handle: CommandHandle, output: ProcessOutput, onExit?: ((exitCode: number) => Promise<void> | void) | undefined);
+    kill(): Promise<void>;
+    wait(timeout?: number): Promise<ProcessOutput>;
+    private waitOnce;
+    sendStdin(data: string): Promise<void>;
+}
+/** Manager for starting and interacting with sandbox processes. */
+export declare class ProcessManager {
+    private readonly commands;
+    constructor(commands: Commands);
+    start(cmd: string): Promise<Process>;
+    start(opts: ProcessOpts): Promise<Process>;
+    startAndWait(cmd: string): Promise<ProcessOutput>;
+    startAndWait(opts: ProcessOpts): Promise<ProcessOutput>;
+}

package/dist/process.js

@@ -0,0 +1,137 @@
+import { CommandExitError } from './commands.js';
+import { TimeoutError } from './errors.js';
+/** A message emitted by a sandbox process. */
+export class ProcessMessage {
+    line;
+    timestamp;
+    error;
+    constructor(line, 
+    /** Unix epoch in nanoseconds. */
+    timestamp, error) {
+        this.line = line;
+        this.timestamp = timestamp;
+        this.error = error;
+    }
+    toString() {
+        return this.line;
+    }
+}
+/** Captured output from a sandbox process. */
+export class ProcessOutput {
+    messages = [];
+    _finished = false;
+    _error = false;
+    _exitCode;
+    get error() { return this._error; }
+    get exitCode() { return this._exitCode; }
+    get stdout() { return this.messages.filter((message) => !message.error).map(String).join(''); }
+    get stderr() { return this.messages.filter((message) => message.error).map(String).join(''); }
+    addStdout(message) {
+        this.messages.push(message);
+    }
+    addStderr(message) {
+        this.messages.push(message);
+        this._error = true;
+    }
+    setExitCode(exitCode) {
+        this._exitCode = exitCode;
+        this._finished = true;
+        if (exitCode !== 0)
+            this._error = true;
+    }
+    replace(result) {
+        this.messages = [];
+        if (result.stdout)
+            this.addStdout(processMessage(result.stdout, false));
+        if (result.stderr)
+            this.addStderr(processMessage(result.stderr, true));
+        this.setExitCode(result.exitCode);
+    }
+}
+/** A running sandbox process. */
+export class Process {
+    processID;
+    handle;
+    output;
+    onExit;
+    finished;
+    waitPromise;
+    constructor(processID, handle, output, onExit) {
+        this.processID = processID;
+        this.handle = handle;
+        this.output = output;
+        this.onExit = onExit;
+        this.waitPromise = this.waitOnce();
+        this.finished = this.waitPromise;
+    }
+    async kill() {
+        await this.handle.kill();
+    }
+    async wait(timeout) {
+        if (!this.waitPromise)
+            this.waitPromise = this.waitOnce();
+        return waitFor(this.waitPromise, timeout);
+    }
+    async waitOnce() {
+        try {
+            this.output.replace(await this.handle.wait());
+        }
+        catch (error) {
+            if (error instanceof CommandExitError) {
+                this.output.replace(error);
+            }
+            else {
+                throw error;
+            }
+        }
+        await this.onExit?.(this.output.exitCode ?? 0);
+        return this.output;
+    }
+    async sendStdin(data) {
+        await this.handle.sendStdin(data);
+    }
+}
+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));
+    });
+}
+/** Manager for starting and interacting with sandbox processes. */
+export class ProcessManager {
+    commands;
+    constructor(commands) {
+        this.commands = commands;
+    }
+    async start(cmdOrOpts) {
+        const opts = processOpts(cmdOrOpts);
+        const { cmd, onStdout, onStderr, onExit, ...commandOpts } = opts;
+        const output = new ProcessOutput();
+        const handle = await this.commands.start(cmd, {
+            ...commandOpts,
+            onStdout: async (data) => {
+                const message = processMessage(data, false);
+                output.addStdout(message);
+                await onStdout?.(message);
+            },
+            onStderr: async (data) => {
+                const message = processMessage(data, true);
+                output.addStderr(message);
+                await onStderr?.(message);
+            },
+        });
+        return new Process(String(handle.pid), handle, output, onExit);
+    }
+    async startAndWait(cmdOrOpts) {
+        const process = await this.start(cmdOrOpts);
+        return process.wait(typeof cmdOrOpts === 'string' ? undefined : cmdOrOpts.timeout);
+    }
+}
+function processOpts(cmdOrOpts) {
+    return typeof cmdOrOpts === 'string' ? { cmd: cmdOrOpts } : cmdOrOpts;
+}
+function processMessage(line, error) {
+    return new ProcessMessage(line, Date.now() * 1_000_000, error);
+}

package/dist/processSocket.d.ts

@@ -14,6 +14,7 @@ export declare class ProcessSocket implements AsyncIterable<ProcessFrame> {
     connect(): Promise<this>;
     sendJson(payload: ProcessFrame): void;
     sendStdin(data: string | Uint8Array): void;
+    closeStdin(): void;
     close(): void;
     [Symbol.asyncIterator](): AsyncIterator<ProcessFrame>;
     private next;

package/dist/processSocket.js

@@ -55,6 +55,9 @@ export class ProcessSocket {
         const raw = typeof data === 'string' ? new TextEncoder().encode(data) : data;
         this.sendJson({ type: 'stdin', data: base64Encode(raw) });
     }
+    closeStdin() {
+        this.sendJson({ type: 'close_stdin' });
+    }
     close() {
         this.closed = true;
         if (this.keepalive)

package/dist/pty.d.ts

@@ -5,7 +5,11 @@ export interface PtySize {
     cols: number;
     rows: number;
 }
-export interface PtyCreateOpts extends Omit<CommandStartOpts, 'background' | 'onStdout' | 'onStderr'>, PtySize {
+export interface PtyCreateOpts extends Omit<CommandStartOpts, 'background' | 'onStdout' | 'onStderr'> {
+    cols?: number;
+    rows?: number;
+    size?: PtySize;
+    cmd?: string;
     onData?: (data: Uint8Array) => void | Promise<void>;
 }
 export interface PtyConnectOpts {

package/dist/pty.js

@@ -12,18 +12,20 @@ export class Pty {
     /** Create an interactive shell PTY and return its live command handle. */
     async create(opts) {
         const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, '/runtime/v1/process', opts.requestTimeoutMs ?? this.config.requestTimeoutMs).connect();
-        const envs = { TERM: 'xterm-256color', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8', ...(opts.envs ?? {}) };
+        const envs = { TERM: 'xterm-256color', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8', ...(opts.envVars ?? opts.envs ?? {}) };
+        const size = opts.size ?? { cols: opts.cols ?? 80, rows: opts.rows ?? 24 };
+        const args = opts.cmd === undefined ? ['-i', '-l'] : ['-l', '-c', opts.cmd];
         socket.sendJson({
             type: 'start',
             cmd: '/bin/bash',
-            args: ['-i', '-l'],
-            cwd: opts.cwd,
+            args,
+            cwd: opts.cwd ?? opts.rootDir,
             user: opts.user,
             environment: envs,
             envs,
             stdin: true,
-            pty: { cols: opts.cols, rows: opts.rows },
-            timeout_ms: opts.timeoutMs ?? 60_000,
+            pty: { cols: size.cols, rows: size.rows },
+            timeout_ms: opts.timeoutMs ?? opts.timeout ?? 60_000,
         });
         const first = await nextStarted(socket);
         const pid = framePid(first);
@@ -45,7 +47,7 @@ export class Pty {
             await handle.sendStdin(data);
         }
         finally {
-            handle.disconnect();
+            await handle.disconnect();
         }
     }
     /** Alias for `sendStdin`. */
@@ -59,7 +61,7 @@ export class Pty {
             await handle.resize(size);
         }
         finally {
-            handle.disconnect();
+            await handle.disconnect();
         }
     }
     /** Kill a running PTY. */

package/dist/sandbox.d.ts

@@ -4,6 +4,8 @@ import { ControlClient } from './transport.js';
 import { Filesystem } from './filesystem.js';
 import { Git } from './git.js';
 import { Pty } from './pty.js';
+import { ProcessManager } from './process.js';
+import { TerminalManager } from './terminal.js';
 export interface SandboxCreateOpts extends ConnectionOpts {
     /** Template slug to create. Defaults to "base". */
     template?: string;
@@ -13,14 +15,44 @@ export interface SandboxCreateOpts extends ConnectionOpts {
     envs?: Record<string, string>;
     secure?: boolean;
     allowInternetAccess?: boolean;
+    network?: SandboxNetworkUpdate;
     team?: string;
-    mcp?: unknown;
+    /** MCP gateway configuration to launch inside an `mcp-gateway` sandbox. */
+    mcp?: McpServer;
     volumeMounts?: unknown;
 }
+export type SandboxNetworkSelector = string | string[];
+export interface SandboxNetworkUpdate {
+    allowOut?: SandboxNetworkSelector;
+    denyOut?: SandboxNetworkSelector;
+    allowInternetAccess?: boolean;
+    allowPackageRegistryAccess?: boolean;
+    allowPublicTraffic?: boolean;
+    egressProfile?: string;
+    egressProfiles?: string[];
+    networkClass?: string;
+    rules?: unknown;
+    maskRequestHost?: string;
+}
+export interface SandboxNetworkUpdateOpts extends ConnectionOpts {
+}
 export interface SandboxConnectOpts extends ConnectionOpts {
     /** Optional new sandbox lifetime in milliseconds. */
     timeoutMs?: number;
 }
+export interface SandboxListOpts extends ConnectionOpts {
+    /** Filters applied by the Watasu API. */
+    query?: {
+        metadata?: Record<string, string>;
+        state?: Array<'running' | 'paused' | string>;
+    };
+    /** Maximum number of sandboxes to return per page. */
+    limit?: number;
+    /** Pagination cursor returned by a previous page. */
+    nextToken?: string;
+    /** Team slug to list within. */
+    team?: string;
+}
 export interface SandboxInfo {
     sandboxId: string;
     templateId?: string;
@@ -56,6 +88,10 @@ export interface FileUrlInfo {
     expiresAt?: string;
     raw: Record<string, unknown>;
 }
+/** MCP gateway configuration accepted by `Sandbox.create({ mcp })`. */
+export type McpServer = Record<string, unknown>;
+/** Name accepted by `Template.addMcpServer`. Watasu keeps this open-ended. */
+export type McpServerName = string;
 export interface SandboxUrlOpts extends ConnectionOpts {
     user?: string;
     useSignatureExpiration?: number;
@@ -67,29 +103,62 @@ export interface CreateSnapshotOpts extends ConnectionOpts {
     expiresAt?: string;
     quiesceMode?: string;
 }
+export interface SnapshotListOpts extends ConnectionOpts {
+    /** Filter snapshots by source sandbox id. */
+    sandboxId?: string;
+    /** Maximum number of snapshots to return per page. */
+    limit?: number;
+    /** Pagination cursor returned by a previous page. */
+    nextToken?: string;
+}
 export interface RestoreSnapshotOpts extends ConnectionOpts {
     checkpointId?: string | number;
     snapshotId?: string | number;
     timeout?: number;
     timeoutMs?: number;
 }
+/** Paginator for listing sandbox snapshots. */
 export declare class SnapshotPaginator {
-    private readonly loadItems;
-    private consumed;
+    private readonly opts;
+    hasNext: boolean;
+    nextToken: string | undefined;
+    constructor(opts?: SnapshotListOpts);
+    /** Fetch the next page of snapshot metadata. */
+    nextItems(opts?: ConnectionOpts): Promise<SnapshotInfo[]>;
+    /** Drain all remaining pages into one list. */
+    listItems(opts?: ConnectionOpts): Promise<SnapshotInfo[]>;
+}
+/** Paginator for listing sandboxes. */
+export declare class SandboxPaginator {
+    private readonly opts;
     hasNext: boolean;
     nextToken: string | undefined;
-    constructor(loadItems: () => Promise<SnapshotInfo[]>);
-    nextItems(): Promise<SnapshotInfo[]>;
+    constructor(opts?: SandboxListOpts);
+    /** Fetch the next page of sandbox metadata. */
+    nextItems(opts?: ConnectionOpts): Promise<SandboxInfo[]>;
+    /** Drain all remaining pages into one list. */
+    listItems(opts?: ConnectionOpts): Promise<SandboxInfo[]>;
 }
 /** Running Watasu sandbox with ready `files` and `commands` helpers. */
 export declare class Sandbox {
     /** Default template slug used when create is called without a template. */
-    static readonly defaultTemplate = "base";
+    static readonly defaultTemplate: string;
+    /** Default template slug used by MCP creation once Watasu supports it. */
+    static readonly defaultMcpTemplate: string;
+    /** Default sandbox lifetime in milliseconds. */
+    static readonly defaultSandboxTimeoutMs = 300000;
     files: Filesystem;
+    filesystem: Filesystem;
     commands: Commands;
+    process: ProcessManager;
     pty: Pty;
+    terminal: TerminalManager;
     git: Git;
+    cwd: string | undefined;
+    envVars: Record<string, string>;
     readonly sandboxId: string;
+    private readonly mcpPort;
+    private mcpToken;
     private readonly config;
     private readonly control;
     private readonly envs;
@@ -103,22 +172,38 @@ export declare class Sandbox {
         sandbox?: Record<string, unknown>;
         envs?: Record<string, string>;
     });
+    /** Sandbox id alias used by SDK-compatible code. */
+    get id(): string;
     static create(opts?: SandboxCreateOpts): Promise<Sandbox>;
     static create(template: string, opts?: SandboxCreateOpts): Promise<Sandbox>;
     /** Connect to an existing sandbox and return it with a fresh data-plane session. */
     static connect(sandboxId: string, opts?: SandboxConnectOpts): Promise<Sandbox>;
+    /** Alias for `connect`. */
+    static reconnect(sandboxId: string, opts?: SandboxConnectOpts): Promise<Sandbox>;
+    static reconnect(opts: SandboxConnectOpts & {
+        sandboxID: string;
+    }): Promise<Sandbox>;
     /** Refresh this sandbox's data-plane session in place. */
     connect(opts?: SandboxConnectOpts): Promise<this>;
+    /** Resume a paused sandbox by id. */
+    static resume(sandboxId: string, opts?: SandboxConnectOpts): Promise<boolean>;
+    /** Pause a sandbox by id. Returns false when it was already paused. */
+    static betaPause(sandboxId: string, opts?: ConnectionOpts): Promise<boolean>;
+    /** Alias for `betaPause`. */
+    static pause(sandboxId: string, opts?: ConnectionOpts): Promise<boolean>;
     /** Destroy a sandbox by id. */
-    static kill(sandboxId: string, opts?: ConnectionOpts): Promise<boolean>;
+    static kill(sandboxId: string, opts?: ConnectionOpts | string): Promise<boolean>;
     /** Fetch sandbox metrics by id. */
     static getMetrics(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxMetrics[]>;
+    /** Atomically replace a sandbox's network egress policy by id. */
+    static updateNetwork(sandboxId: string, network: SandboxNetworkUpdate, opts?: SandboxNetworkUpdateOpts): Promise<void>;
+    private static putNetwork;
     /** Deprecated alias for `getInfo`. */
     static getFullInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
     /** Create a Watasu checkpoint using snapshot naming. */
     static createSnapshot(sandboxId: string, opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
-    /** List checkpoints for one sandbox using snapshot naming. */
-    static listSnapshots(sandboxId: string, opts?: ConnectionOpts): SnapshotPaginator;
+    /** List snapshots visible to the configured API key. */
+    static listSnapshots(opts?: SnapshotListOpts): SnapshotPaginator;
     /** Delete a snapshot by id. Returns `false` when the snapshot does not exist. */
     static deleteSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<boolean>;
     /** Destroy this sandbox. */
@@ -129,6 +214,8 @@ export declare class Sandbox {
     static setTimeout(sandboxId: string, timeoutMs: number, opts?: ConnectionOpts): Promise<void>;
     /** Set this sandbox's lifetime. */
     setTimeout(timeoutMs: number): Promise<void>;
+    /** Keep the sandbox alive for `duration` milliseconds. */
+    keepAlive(duration: number): Promise<void>;
     /** Fetch control-plane metadata for a sandbox by id. */
     static getInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
     /** Fetch the latest control-plane metadata for this sandbox. */
@@ -142,27 +229,41 @@ export declare class Sandbox {
     /** Watasu-native alias for `createSnapshot`. */
     checkpoint(opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
     /** List checkpoints for this sandbox using snapshot naming. */
-    listSnapshots(opts?: ConnectionOpts): SnapshotPaginator;
+    listSnapshots(opts?: Omit<SnapshotListOpts, 'sandboxId'>): SnapshotPaginator;
     /** Restore a checkpoint into a new sandbox and return its control-plane info. */
     restore(opts?: RestoreSnapshotOpts | string | number): Promise<SandboxInfo>;
-    /** List sandboxes visible to the configured API key. */
-    static list(opts?: ConnectionOpts & {
-        team?: string;
-    }): Promise<SandboxInfo[]>;
+    /** Return a paginator for sandboxes visible to the configured API key. */
+    static list(opts?: SandboxListOpts | string): SandboxPaginator;
     /** Return the public hostname for an exposed sandbox port. */
     getHost(port: number): string;
+    /** Return the public hostname for the sandbox or an exposed sandbox port. */
+    getHostname(port?: number): string;
+    /** Return the conventional MCP URL for this sandbox. */
+    getMcpUrl(): string;
+    /** Return the MCP gateway token when the sandbox contains one. */
+    getMcpToken(): Promise<string | undefined>;
+    /** Return a protocol string for a secure or insecure sandbox URL. */
+    getProtocol(baseProtocol?: string, secure?: boolean): string;
+    /** Close the local SDK attachment. This does not destroy the sandbox. */
+    close(): Promise<void>;
     /** Get a signed URL that accepts a POST upload for a sandbox file path. */
-    uploadUrl(path: string, opts?: SandboxUrlOpts): Promise<string>;
+    uploadUrl(path?: string, opts?: SandboxUrlOpts): Promise<string>;
     /** Get a signed URL that accepts a GET download for a sandbox file path. */
     downloadUrl(path: string, opts?: SandboxUrlOpts): Promise<string>;
     /** Get signed upload URL metadata for a sandbox file path. */
-    uploadUrlInfo(path: string, opts?: SandboxUrlOpts): Promise<FileUrlInfo>;
+    uploadUrlInfo(path?: string, opts?: SandboxUrlOpts): Promise<FileUrlInfo>;
     /** Get signed download URL metadata for a sandbox file path. */
     downloadUrlInfo(path: string, opts?: SandboxUrlOpts): Promise<FileUrlInfo>;
-    updateNetwork(..._args: unknown[]): never;
-    pause(): never;
-    betaPause(): never;
-    resume(): never;
+    /** Atomically replace this sandbox's network egress policy. */
+    updateNetwork(network: SandboxNetworkUpdate, opts?: SandboxNetworkUpdateOpts): Promise<void>;
+    /** Pause this sandbox. Returns false when it was already paused. */
+    betaPause(opts?: ConnectionOpts): Promise<boolean>;
+    /** Alias for `betaPause`. */
+    pause(opts?: ConnectionOpts): Promise<boolean>;
+    /** Resume this sandbox and refresh its data-plane session. */
+    resume(opts?: SandboxConnectOpts): Promise<boolean>;
     private fileUrl;
+    /** POST JSON to the sandbox data-plane runtime API. */
+    protected runtimePostJson(path: string, json: Record<string, unknown>, opts?: ConnectionOpts): Promise<Record<string, unknown>>;
     private configOptions;
 }