@watasu/sdk 0.1.66 → 0.1.68

package/dist/codeInterpreter.d.ts

@@ -6,7 +6,7 @@ export { ControlClient as ApiClient } from './transport.js';
 export { ALL_TRAFFIC, SandboxPaginator, SnapshotPaginator, getSignature, } from './sandbox.js';
 export type { CreateSnapshotOpts, FileUrlInfo, McpServer, McpServerName, RestoreSnapshotOpts, SandboxApiOpts, SandboxConnectOpts, SandboxCreateOpts, SandboxInfo, SandboxInfoLifecycle, SandboxLifecycle, SandboxListOpts, SandboxMetrics, SandboxMetricsOpts, SandboxNetworkInfo, SandboxNetworkOpts, SandboxNetworkRule, SandboxNetworkRuleInfo, SandboxNetworkRules, SandboxNetworkSelector, SandboxNetworkSelectorContext, SandboxNetworkTransform, SandboxNetworkUpdate, SandboxNetworkUpdateOpts, SandboxOpts, SandboxState, SandboxUrlOpts, SignatureOpts, SnapshotInfo, SnapshotListOpts, } from './sandbox.js';
 export { CommandExitError, CommandHandle, Commands } from './commands.js';
-export type { CommandConnectOpts, CommandRequestOpts, CommandResult, CommandStartOpts, ProcessInfo, PtyOutput, Stderr, Stdout, } from './commands.js';
+export type { CommandConnectOpts, CommandRequestOpts, CommandResult, CommandStartOpts, ProcessInfo, ProcessOutputEvent, ProcessOutputSnapshot, ProcessStatus, PtyOutput, ReadProcessOutputOptions, Stderr, StopProcessOptions, Stdout, } from './commands.js';
 export { Process, ProcessManager, ProcessMessage, ProcessOutput } from './process.js';
 export type { ProcessOpts } from './process.js';
 export { FileType, Filesystem, FilesystemEventType, FilesystemWatcher, WatchHandle, } from './filesystem.js';

package/dist/commands.d.ts

@@ -26,6 +26,45 @@ export interface ProcessInfo {
     envs: Record<string, string>;
     cwd?: string;
 }
+export interface ProcessStatus {
+    pid: number | string;
+    id?: number | string;
+    osPid?: number;
+    command?: string;
+    args: string[];
+    cwd?: string;
+    user?: string;
+    pty?: boolean;
+    status: string;
+    startedAt?: string;
+    finishedAt?: string;
+    exitCode?: number;
+}
+export interface ProcessOutputEvent {
+    cursor: number;
+    type: 'stdout' | 'stderr' | 'pty' | string;
+    data: Uint8Array;
+}
+export interface ProcessOutputSnapshot {
+    pid: number | string;
+    status: string;
+    exitCode?: number;
+    finishedAt?: string;
+    nextCursor: number;
+    truncatedBeforeCursor: boolean;
+    events: ProcessOutputEvent[];
+}
+export interface ReadProcessOutputOptions extends CommandRequestOpts {
+    since?: number;
+    limitBytes?: number;
+}
+export interface StopProcessOptions {
+    signal?: string;
+    killGroup?: boolean;
+    graceMs?: number;
+    requestTimeoutMs?: number;
+    abortSignal?: AbortSignal;
+}
 export interface CommandStartOpts {
     /** Return a `CommandHandle` immediately instead of waiting for exit. */
     background?: boolean;
@@ -55,21 +94,28 @@ export interface CommandConnectOpts extends CommandRequestOpts {
 export type Stdout = string;
 export type Stderr = string;
 export type PtyOutput = Uint8Array;
+type ProcessReconnect = (cursor: number) => Promise<{
+    socket: ProcessSocket;
+    events: AsyncIterable<ProcessFrame>;
+}>;
 /** Live handle for one sandbox process stream. */
 export declare class CommandHandle implements Partial<CommandResult> {
     readonly pid: number | string;
-    private readonly socket;
+    private socket;
     private readonly handleKill;
-    private readonly events;
+    private events;
     private readonly onStdout?;
     private readonly onStderr?;
     private readonly onPty?;
     private readonly onExit?;
+    private readonly reconnect?;
     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, onExit?: ((exitCode: number) => void | Promise<void>) | undefined);
+    private nextCursor;
+    private disconnected;
+    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, reconnect?: ProcessReconnect | undefined);
     get stdout(): string;
     get stderr(): string;
     get exitCode(): number | undefined;
@@ -90,6 +136,8 @@ export declare class CommandHandle implements Partial<CommandResult> {
     /** Detach the local stream without killing the process. */
     disconnect(): Promise<void>;
     private handleEvents;
+    private advanceCursor;
+    private reconnectStream;
 }
 /** Command runner for a sandbox data-plane session. */
 export declare class Commands {
@@ -125,6 +173,16 @@ export declare class Commands {
     run(cmd: string, opts?: CommandStartOpts): Promise<CommandResult>;
     /** Reconnect to a live process stream by pid. */
     connect(pid: number | string, opts?: CommandStartOpts): Promise<CommandHandle>;
+    /** Reconnect to a live process stream by pid starting at a cursor. */
+    connectSince(pid: number | string, cursor?: number, opts?: CommandStartOpts): Promise<CommandHandle>;
+    /** Look up process status without attaching a WebSocket. */
+    process(pid: number | string, opts?: CommandRequestOpts): Promise<ProcessStatus>;
+    /** Read available process output since a cursor without blocking. */
+    readProcessOutput(pid: number | string, opts?: ReadProcessOutputOptions): Promise<ProcessOutputSnapshot>;
+    /** Stop a process, optionally signalling the full process group. */
+    stopProcess(pid: number | string, opts?: StopProcessOptions): Promise<ProcessStatus>;
     /** Start a command and return a live handle immediately. */
     start(cmd: string, opts?: CommandStartOpts): Promise<CommandHandle>;
+    private openProcessStream;
 }
+export {};

package/dist/commands.js

@@ -1,3 +1,4 @@
+import { withQuery } from './transport.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. */
@@ -13,6 +14,9 @@ export class CommandExitError extends SandboxError {
     get stdout() { return this.result.stdout; }
     get stderr() { return this.result.stderr; }
 }
+const STREAM_RECONNECT_ATTEMPTS = 12;
+const STREAM_RECONNECT_BASE_DELAY_MS = 250;
+const STREAM_RECONNECT_MAX_DELAY_MS = 2_000;
 /** Live handle for one sandbox process stream. */
 export class CommandHandle {
     pid;
@@ -23,11 +27,14 @@ export class CommandHandle {
     onStderr;
     onPty;
     onExit;
+    reconnect;
     _stdout = '';
     _stderr = '';
     result;
     pending;
-    constructor(pid, socket, handleKill, events, onStdout, onStderr, onPty, onExit) {
+    nextCursor = 0;
+    disconnected = false;
+    constructor(pid, socket, handleKill, events, onStdout, onStderr, onPty, onExit, reconnect) {
         this.pid = pid;
         this.socket = socket;
         this.handleKill = handleKill;
@@ -36,6 +43,7 @@ export class CommandHandle {
         this.onStderr = onStderr;
         this.onPty = onPty;
         this.onExit = onExit;
+        this.reconnect = reconnect;
         this.pending = this.handleEvents();
     }
     get stdout() { return this._stdout; }
@@ -69,11 +77,14 @@ export class CommandHandle {
     }
     /** Detach the local stream without killing the process. */
     async disconnect() {
+        this.disconnected = true;
         this.socket.close();
     }
     async handleEvents() {
-        try {
+        while (!this.disconnected && !this.result) {
+            let streamError;
             for await (const frame of this.events) {
+                this.advanceCursor(frame);
                 const type = frame.type;
                 if (type === 'started' || type === 'ready' || type === 'pong')
                     continue;
@@ -102,16 +113,51 @@ export class CommandHandle {
                         stderr: this._stderr,
                     };
                     await this.onExit?.(exitCode);
+                    this.socket.close();
                     return;
                 }
                 else if (type === 'error') {
-                    throw new SandboxError(String(frame.message ?? frame.code ?? 'process error'));
+                    streamError = new SandboxError(String(frame.message ?? frame.code ?? 'process error'));
+                    if (!isReconnectableStreamError(streamError))
+                        throw streamError;
+                    break;
                 }
             }
+            if (this.result || this.disconnected)
+                return;
+            if (!this.reconnect) {
+                this.socket.close();
+                if (streamError)
+                    throw streamError;
+                return;
+            }
+            await this.reconnectStream();
         }
-        finally {
+    }
+    advanceCursor(frame) {
+        const cursor = numberValue(frame.cursor);
+        if (cursor !== undefined)
+            this.nextCursor = Math.max(this.nextCursor, cursor + 1);
+    }
+    async reconnectStream() {
+        let lastError;
+        for (let attempt = 0; attempt < STREAM_RECONNECT_ATTEMPTS && !this.disconnected; attempt += 1) {
             this.socket.close();
+            if (attempt > 0)
+                await sleep(reconnectDelayMs(attempt));
+            try {
+                const next = await this.reconnect(this.nextCursor);
+                this.socket = next.socket;
+                this.events = next.events;
+                return;
+            }
+            catch (error) {
+                lastError = error;
+            }
         }
+        if (lastError instanceof Error)
+            throw lastError;
+        throw new SandboxError('process websocket closed before exit and could not reconnect');
     }
 }
 /** Command runner for a sandbox data-plane session. */
@@ -136,9 +182,10 @@ export class Commands {
     }
     /** Send SIGKILL to a process by pid. */
     async kill(pid, opts = {}) {
-        await this.dataPlane.postJson(`/runtime/v1/process/${pid}/signal`, {
-            ...opts,
-            json: { signal: 'SIGKILL' },
+        await this.stopProcess(pid, {
+            signal: 'SIGKILL',
+            requestTimeoutMs: opts.requestTimeoutMs,
+            abortSignal: opts.signal,
         });
         return true;
     }
@@ -171,10 +218,38 @@ export class Commands {
     }
     /** 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, this.config.headers).connect();
-        const first = await nextStarted(socket);
-        const actualPid = framePid(first) ?? pid;
-        return new CommandHandle(actualPid, socket, () => this.kill(actualPid), socket, opts.onStdout, opts.onStderr, opts.onPty);
+        return this.connectSince(pid, 0, opts);
+    }
+    /** Reconnect to a live process stream by pid starting at a cursor. */
+    async connectSince(pid, cursor = 0, opts = {}) {
+        const stream = await this.openProcessStream(pid, cursor, opts);
+        const reconnect = async (nextCursor) => this.openProcessStream(stream.actualPid, nextCursor, opts);
+        return new CommandHandle(stream.actualPid, stream.socket, () => this.kill(stream.actualPid), stream.events, opts.onStdout, opts.onStderr, opts.onPty, undefined, reconnect);
+    }
+    /** Look up process status without attaching a WebSocket. */
+    async process(pid, opts = {}) {
+        const payload = await this.dataPlane.getJson(`/runtime/v1/process/${encodeURIComponent(String(pid))}`, opts);
+        return processStatus(payload);
+    }
+    /** Read available process output since a cursor without blocking. */
+    async readProcessOutput(pid, opts = {}) {
+        const payload = await this.dataPlane.getJson(withQuery(`/runtime/v1/process/${encodeURIComponent(String(pid))}/output`, {
+            since: opts.since,
+            limit_bytes: opts.limitBytes,
+        }), opts);
+        return processOutputSnapshot(payload);
+    }
+    /** Stop a process, optionally signalling the full process group. */
+    async stopProcess(pid, opts = {}) {
+        const payload = await this.dataPlane.deleteJson(withQuery(`/runtime/v1/process/${encodeURIComponent(String(pid))}`, {
+            signal: opts.signal,
+            kill_group: opts.killGroup ?? true,
+            grace_ms: opts.graceMs,
+        }), {
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.abortSignal,
+        });
+        return processStatus(payload);
     }
     /** Start a command and return a live handle immediately. */
     async start(cmd, opts = {}) {
@@ -197,7 +272,18 @@ export class Commands {
         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, opts.onExit);
+        const reconnect = async (nextCursor) => this.openProcessStream(pid, nextCursor, opts);
+        return new CommandHandle(pid, socket, () => this.kill(pid), withFirst(first, socket), opts.onStdout, opts.onStderr, opts.onPty, opts.onExit, reconnect);
+    }
+    async openProcessStream(pid, cursor, opts = {}) {
+        const encodedPid = encodeURIComponent(String(pid));
+        const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, withQuery(`/runtime/v1/process/${encodedPid}/connect`, { since: cursor }), opts.requestTimeoutMs ?? this.config.requestTimeoutMs, this.config.headers).connect();
+        const first = await nextStarted(socket);
+        return {
+            actualPid: framePid(first) ?? pid,
+            socket,
+            events: socket,
+        };
     }
 }
 function processStartConfig(cmd, opts) {
@@ -214,6 +300,15 @@ function waitFor(promise, timeoutMs) {
         promise.then(resolve, reject).finally(() => clearTimeout(timer));
     });
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function reconnectDelayMs(attempt) {
+    return Math.min(STREAM_RECONNECT_MAX_DELAY_MS, STREAM_RECONNECT_BASE_DELAY_MS * 2 ** Math.max(0, attempt - 1));
+}
+function isReconnectableStreamError(error) {
+    return error instanceof Error && /websocket|closed/i.test(error.message);
+}
 async function nextStarted(events) {
     for await (const frame of events) {
         if (frame.type === 'started')
@@ -243,8 +338,61 @@ function processInfo(value) {
         cwd: typeof process.cwd === 'string' ? process.cwd : undefined,
     };
 }
+function processStatus(value) {
+    const item = value && typeof value === 'object' ? value : {};
+    const process = item.process && typeof item.process === 'object' ? item.process : item;
+    const pid = scalar(process.pid ?? process.id) ?? '';
+    return {
+        pid,
+        id: scalar(process.id),
+        osPid: numberValue(process.os_pid ?? process.osPid),
+        command: stringValue(process.command ?? process.cmd),
+        args: arrayOfStrings(process.args ?? process.arguments),
+        cwd: stringValue(process.cwd ?? process.working_directory),
+        user: stringValue(process.user),
+        pty: typeof process.pty === 'boolean' ? process.pty : undefined,
+        status: stringValue(process.status) ?? '',
+        startedAt: stringValue(process.started_at ?? process.startedAt),
+        finishedAt: stringValue(process.finished_at ?? process.finishedAt),
+        exitCode: numberValue(process.exit_code ?? process.exitCode),
+    };
+}
+function processOutputSnapshot(value) {
+    const payload = value && typeof value === 'object' ? value : {};
+    return {
+        pid: scalar(payload.pid ?? payload.id) ?? '',
+        status: stringValue(payload.status) ?? '',
+        exitCode: numberValue(payload.exit_code ?? payload.exitCode),
+        finishedAt: stringValue(payload.finished_at ?? payload.finishedAt),
+        nextCursor: numberValue(payload.next_cursor ?? payload.nextCursor) ?? 0,
+        truncatedBeforeCursor: payload.truncated_before_cursor === true || payload.truncatedBeforeCursor === true,
+        events: Array.isArray(payload.events) ? payload.events.map(processOutputEvent) : [],
+    };
+}
+function processOutputEvent(value) {
+    const event = value && typeof value === 'object' ? value : {};
+    return {
+        cursor: numberValue(event.cursor) ?? 0,
+        type: stringValue(event.type) ?? '',
+        data: base64DecodeBytes(stringValue(event.data) ?? ''),
+    };
+}
 function recordOfStrings(value) {
     if (!value || typeof value !== 'object')
         return {};
     return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, String(item)]));
 }
+function scalar(value) {
+    return typeof value === 'number' || typeof value === 'string' ? value : undefined;
+}
+function stringValue(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function numberValue(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    return undefined;
+}
+function arrayOfStrings(value) {
+    return Array.isArray(value) ? value.map(String) : [];
+}

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export type { CreateSnapshotOpts, RestoreSnapshotOpts, SandboxApiOpts, SandboxCr
 export type { CreateCodeContextOpts, RunCodeLanguage, RunCodeOpts, } 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 type { CommandConnectOpts, CommandRequestOpts, CommandResult, CommandStartOpts, ProcessInfo, PtyOutput, Stderr, Stdout, } from './commands.js';
+export type { CommandConnectOpts, CommandRequestOpts, CommandResult, CommandStartOpts, ProcessInfo, ProcessOutputEvent, ProcessOutputSnapshot, ProcessStatus, PtyOutput, ReadProcessOutputOptions, Stderr, StopProcessOptions, Stdout, } from './commands.js';
 export { Process, ProcessManager, ProcessMessage, ProcessOutput } from './process.js';
 export type { ProcessOpts } from './process.js';
 export { FileType, Filesystem, FilesystemEventType, FilesystemWatcher, WatchHandle, } from './filesystem.js';

package/dist/pty.d.ts

@@ -39,4 +39,5 @@ export declare class Pty {
     resize(pid: number | string, size: PtySize, opts?: PtyConnectOpts): Promise<void>;
     /** Kill a running PTY. */
     kill(pid: number | string, opts?: Pick<ConnectionOpts, 'requestTimeoutMs' | 'signal'>): Promise<boolean>;
+    private openPtyStream;
 }

package/dist/pty.js

@@ -1,5 +1,6 @@
 import { CommandHandle } from './commands.js';
 import { ProcessSocket } from './processSocket.js';
+import { withQuery } from './transport.js';
 import { SandboxError } from './errors.js';
 /** PTY helper backed by the sandbox process WebSocket runtime. */
 export class Pty {
@@ -31,14 +32,14 @@ export class Pty {
         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);
+        const reconnect = async (cursor) => this.openPtyStream(pid, cursor, opts);
+        return new CommandHandle(pid, socket, () => this.kill(pid), withFirst(first, socket), undefined, undefined, opts.onData ?? opts.onPty, undefined, reconnect);
     }
     /** 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, this.config.headers).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);
+        const stream = await this.openPtyStream(pid, 0, opts);
+        const reconnect = async (cursor) => this.openPtyStream(stream.actualPid, cursor, opts);
+        return new CommandHandle(stream.actualPid, stream.socket, () => this.kill(stream.actualPid), stream.events, undefined, undefined, opts.onData, undefined, reconnect);
     }
     /** Send input bytes or text to a PTY. */
     async sendStdin(pid, data, opts = {}) {
@@ -66,13 +67,24 @@ export class Pty {
     }
     /** Kill a running PTY. */
     async kill(pid, opts = {}) {
-        await this.dataPlane.postJson(`/runtime/v1/process/${pid}/signal`, {
-            json: { signal: 'SIGKILL' },
+        await this.dataPlane.deleteJson(withQuery(`/runtime/v1/process/${encodeURIComponent(String(pid))}`, {
+            signal: 'SIGKILL',
+            kill_group: true,
+        }), {
             requestTimeoutMs: opts.requestTimeoutMs,
             signal: opts.signal,
         });
         return true;
     }
+    async openPtyStream(pid, cursor, opts = {}) {
+        const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, withQuery(`/runtime/v1/process/${encodeURIComponent(String(pid))}/connect`, { since: cursor }), opts.requestTimeoutMs ?? this.config.requestTimeoutMs, this.config.headers).connect();
+        const first = await nextStarted(socket);
+        return {
+            actualPid: framePid(first) ?? pid,
+            socket,
+            events: withFirst(first, socket),
+        };
+    }
 }
 async function nextStarted(events) {
     for await (const frame of events) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watasu/sdk",
-  "version": "0.1.66",
+  "version": "0.1.68",
   "type": "module",
   "license": "MIT OR Apache-2.0",
   "description": "TypeScript SDK for Watasu",