@watasu/sdk 0.1.5 → 0.1.24

package/dist/index.d.ts

@@ -1,9 +1,19 @@
-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 type { CreateSnapshotOpts, RestoreSnapshotOpts, SandboxCreateOpts, SandboxConnectOpts, SandboxInfo, SandboxMetrics, SnapshotInfo, } from './sandbox.js';
+export { Sandbox, SandboxPaginator, SnapshotPaginator } from './sandbox.js';
+export type { CreateSnapshotOpts, RestoreSnapshotOpts, SandboxCreateOpts, SandboxConnectOpts, SandboxInfo, SandboxListOpts, SandboxMetrics, McpServer, McpServerName, SandboxNetworkSelector, SandboxNetworkUpdate, SandboxNetworkUpdateOpts, SandboxUrlOpts, SnapshotInfo, FileUrlInfo, } from './sandbox.js';
 export { CommandExitError, CommandHandle, Commands } from './commands.js';
 export type { CommandResult, CommandStartOpts, ProcessInfo } from './commands.js';
-export { FileType, Filesystem } from './filesystem.js';
-export type { EntryInfo, WriteInfo } from './filesystem.js';
-export { ProcessSocket, base64DecodeText, base64Encode } from './processSocket.js';
+export { Process, ProcessManager, ProcessMessage, ProcessOutput } from './process.js';
+export type { ProcessOpts } from './process.js';
+export { FileType, Filesystem, FilesystemWatcher, WatchHandle } from './filesystem.js';
+export type { EntryInfo, FilesystemEvent, FilesystemReadOpts, FilesystemRequestOpts, FilesystemWriteOpts, WatchOpts, WriteData, WriteEntry, WriteInfo, } from './filesystem.js';
+export { Git } from './git.js';
+export type { GitAddOpts, GitAuthOpts, GitBranches, GitBranchOpts, GitCloneOpts, GitCommandResult, GitConfigOpts, GitConfigureUserOpts, GitCredentialOpts, GitCommitOpts, GitFileStatus, GitInitOpts, GitPullOpts, GitPushOpts, GitRemoteAddOpts, GitResetMode, GitResetOpts, GitRestoreOpts, GitRequestOpts, GitStatus, } from './git.js';
+export { Pty } from './pty.js';
+export type { PtyConnectOpts, PtyCreateOpts, PtySize } from './pty.js';
+export { Terminal, TerminalManager, TerminalOutput } from './terminal.js';
+export type { TerminalOpts } from './terminal.js';
+export { ProcessSocket, base64DecodeBytes, base64DecodeText, base64Encode } from './processSocket.js';
+export { ReadyCmd, Template, TemplateBase, waitForFile, waitForPort, waitForProcess, waitForTimeout, waitForURL, waitForUrl, } from './template.js';
+export type { BuildInfo, BuildOptions, BuildStatusReason, CopyItem, GetBuildStatusOptions, LogEntry, ReadyCommand, TemplateBuildStatus, TemplateBuildStatusResponse, TemplateBuilder, TemplateClass, TemplateFactory, TemplateFinal, TemplateFromImage, TemplateOptions, TemplateTag, TemplateTagInfo, } from './template.js';

package/dist/index.js

@@ -1,6 +1,11 @@
-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 { CommandExitError, CommandHandle, Commands } from './commands.js';
-export { FileType, Filesystem } from './filesystem.js';
-export { ProcessSocket, base64DecodeText, base64Encode } from './processSocket.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;
@@ -23,3 +24,4 @@ export declare class ProcessSocket implements AsyncIterable<ProcessFrame> {
 }
 export declare function base64Encode(bytes: Uint8Array): string;
 export declare function base64DecodeText(value: unknown): string;
+export declare function base64DecodeBytes(value: unknown): Uint8Array;

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)
@@ -122,12 +125,17 @@ export function base64DecodeText(value) {
     if (typeof value !== 'string')
         return String(value ?? '');
     try {
-        return Buffer.from(value, 'base64').toString('utf8');
+        return Buffer.from(base64DecodeBytes(value)).toString('utf8');
     }
     catch {
         return value;
     }
 }
+export function base64DecodeBytes(value) {
+    if (typeof value !== 'string')
+        return new TextEncoder().encode(String(value ?? ''));
+    return new Uint8Array(Buffer.from(value, 'base64'));
+}
 function rawDataToText(message) {
     if (typeof message === 'string')
         return message;

package/dist/pty.d.ts

@@ -0,0 +1,37 @@
+import { CommandHandle, CommandStartOpts } from './commands.js';
+import { ConnectionConfig } from './connectionConfig.js';
+import { DataPlaneClient } from './transport.js';
+export interface PtySize {
+    cols: number;
+    rows: number;
+}
+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 {
+    onData?: (data: Uint8Array) => void | Promise<void>;
+    timeoutMs?: number;
+    requestTimeoutMs?: number;
+}
+/** PTY helper backed by the sandbox process WebSocket runtime. */
+export declare class Pty {
+    private readonly dataPlane;
+    private readonly config;
+    constructor(dataPlane: DataPlaneClient, config: ConnectionConfig);
+    /** Create an interactive shell PTY and return its live command handle. */
+    create(opts: PtyCreateOpts): Promise<CommandHandle>;
+    /** Connect to a running PTY by pid. */
+    connect(pid: number | string, opts?: PtyConnectOpts): Promise<CommandHandle>;
+    /** Send input bytes or text to a PTY. */
+    sendStdin(pid: number | string, data: string | Uint8Array, opts?: PtyConnectOpts): Promise<void>;
+    /** Alias for `sendStdin`. */
+    sendInput(pid: number | string, data: string | Uint8Array, opts?: PtyConnectOpts): Promise<void>;
+    /** Resize a running PTY. */
+    resize(pid: number | string, size: PtySize, opts?: PtyConnectOpts): Promise<void>;
+    /** Kill a running PTY. */
+    kill(pid: number | string): Promise<boolean>;
+}

package/dist/pty.js

@@ -0,0 +1,90 @@
+import { CommandHandle } from './commands.js';
+import { ProcessSocket } from './processSocket.js';
+import { SandboxError } from './errors.js';
+/** PTY helper backed by the sandbox process WebSocket runtime. */
+export class Pty {
+    dataPlane;
+    config;
+    constructor(dataPlane, config) {
+        this.dataPlane = dataPlane;
+        this.config = config;
+    }
+    /** 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.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,
+            cwd: opts.cwd ?? opts.rootDir,
+            user: opts.user,
+            environment: envs,
+            envs,
+            stdin: true,
+            pty: { cols: size.cols, rows: size.rows },
+            timeout_ms: opts.timeoutMs ?? opts.timeout ?? 60_000,
+        });
+        const first = await nextStarted(socket);
+        const pid = framePid(first);
+        if (pid === undefined)
+            throw new SandboxError('PTY started frame did not include pid');
+        return new CommandHandle(pid, socket, () => this.kill(pid), withFirst(first, socket), undefined, undefined, opts.onData ?? opts.onPty);
+    }
+    /** Connect to a running PTY 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), withFirst(first, socket), undefined, undefined, opts.onData);
+    }
+    /** Send input bytes or text to a PTY. */
+    async sendStdin(pid, data, opts = {}) {
+        const handle = await this.connect(pid, opts);
+        try {
+            await handle.sendStdin(data);
+        }
+        finally {
+            await handle.disconnect();
+        }
+    }
+    /** Alias for `sendStdin`. */
+    async sendInput(pid, data, opts = {}) {
+        return this.sendStdin(pid, data, opts);
+    }
+    /** Resize a running PTY. */
+    async resize(pid, size, opts = {}) {
+        const handle = await this.connect(pid, opts);
+        try {
+            await handle.resize(size);
+        }
+        finally {
+            await handle.disconnect();
+        }
+    }
+    /** Kill a running PTY. */
+    async kill(pid) {
+        await this.dataPlane.postJson(`/runtime/v1/process/${pid}/signal`, {
+            json: { signal: 'SIGKILL' },
+        });
+        return true;
+    }
+}
+async function nextStarted(events) {
+    for await (const frame of events) {
+        if (frame.type === 'started')
+            return frame;
+    }
+    throw new SandboxError('PTY ended before started frame');
+}
+async function* withFirst(first, rest) {
+    yield first;
+    yield* rest;
+}
+function framePid(frame) {
+    const process = frame.process && typeof frame.process === 'object' ? frame.process : {};
+    const pid = frame.pid ?? process.pid ?? process.id;
+    return typeof pid === 'number' || typeof pid === 'string' ? pid : undefined;
+}

package/dist/sandbox.d.ts

@@ -2,6 +2,10 @@ import { Commands } from './commands.js';
 import { ConnectionConfig, ConnectionOpts } from './connectionConfig.js';
 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;
@@ -11,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;
@@ -47,39 +81,84 @@ export interface SnapshotInfo {
     expiresAt?: string;
     raw: Record<string, unknown>;
 }
+export interface FileUrlInfo {
+    method: string;
+    path: string;
+    url: string;
+    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;
+    expiresInSeconds?: number;
+}
 export interface CreateSnapshotOpts extends ConnectionOpts {
     name?: string;
     metadata?: Record<string, string>;
     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";
+    /** Default template slug used by MCP creation once Watasu supports it. */
+    static readonly defaultMcpTemplate = "mcp-gateway";
+    /** 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;
-    readonly pty: {
-        create: () => never;
-    };
-    readonly git: {
-        clone: () => never;
-    };
+    private readonly mcpPort;
+    private mcpToken;
     private readonly config;
     private readonly control;
     private readonly envs;
@@ -93,24 +172,40 @@ 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;
-    /** Snapshot deletion is not backed by a Watasu checkpoint delete API yet. */
-    static deleteSnapshot(..._args: unknown[]): never;
+    /** 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. */
     kill(): Promise<boolean>;
     /** Check if this sandbox is in a runtime-active lifecycle state. */
@@ -119,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. */
@@ -127,21 +224,44 @@ export declare class Sandbox {
     getMetrics(opts?: ConnectionOpts): Promise<SandboxMetrics[]>;
     /** Create a Watasu checkpoint using snapshot naming. */
     createSnapshot(opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
+    /** Delete a snapshot by id. */
+    deleteSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<boolean>;
     /** 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;
-    updateNetwork(..._args: unknown[]): never;
-    pause(): never;
-    betaPause(): never;
-    resume(): never;
+    /** 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>;
+    /** 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>;
+    /** Get signed download URL metadata for a sandbox file path. */
+    downloadUrlInfo(path: string, opts?: SandboxUrlOpts): Promise<FileUrlInfo>;
+    /** 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;
     private configOptions;
 }