@watasu/sdk 0.1.71 → 0.1.72

package/dist/commands.d.ts

@@ -8,6 +8,11 @@ export interface CommandResult {
     error?: string;
     stdout: string;
     stderr: string;
+    /**
+     * True when the runtime dropped stream output that could not be replayed
+     * (retention evicted the events before the SDK could backfill them).
+     */
+    truncated?: boolean;
 }
 /** Error thrown by `CommandHandle.wait()` when a process exits non-zero. */
 export declare class CommandExitError extends SandboxError implements CommandResult {
@@ -17,6 +22,7 @@ export declare class CommandExitError extends SandboxError implements CommandRes
     get error(): string | undefined;
     get stdout(): string;
     get stderr(): string;
+    get truncated(): boolean | undefined;
 }
 export interface ProcessInfo {
     pid: number | string;
@@ -39,6 +45,11 @@ export interface ProcessStatus {
     startedAt?: string;
     finishedAt?: string;
     exitCode?: number;
+    /**
+     * Set when a kill has been requested but the process has not finished yet
+     * (the runtime reports a non-terminal `killing` status in that window).
+     */
+    killRequestedAt?: string;
 }
 export interface ProcessOutputEvent {
     cursor: number;
@@ -98,6 +109,8 @@ type ProcessReconnect = (cursor: number) => Promise<{
     socket: ProcessSocket;
     events: AsyncIterable<ProcessFrame>;
 }>;
+/** Client-side wait deadline for a command: its timeout plus grace. */
+export declare function commandWaitDeadlineMs(timeoutMs?: number): number;
 /** Live handle for one sandbox process stream. */
 export declare class CommandHandle implements Partial<CommandResult> {
     readonly pid: number | string;
@@ -115,6 +128,8 @@ export declare class CommandHandle implements Partial<CommandResult> {
     private readonly pending;
     private nextCursor;
     private disconnected;
+    private pendingLagged;
+    private outputDropped;
     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;

package/dist/commands.js

@@ -1,11 +1,12 @@
 import { withQuery } from './transport.js';
 import { ProcessSocket, base64DecodeBytes, base64DecodeText } from './processSocket.js';
-import { SandboxError, TimeoutError } from './errors.js';
+import { NotFoundError, SandboxError, TimeoutError } from './errors.js';
 /** Error thrown by `CommandHandle.wait()` when a process exits non-zero. */
 export class CommandExitError extends SandboxError {
     result;
     constructor(result) {
-        super(result.error ?? `Command exited with code ${result.exitCode}`);
+        super((result.error ?? `Command exited with code ${result.exitCode}`) +
+            (result.truncated ? '; some process output was dropped before delivery' : ''));
         this.result = result;
         this.name = 'CommandExitError';
     }
@@ -13,10 +14,26 @@ export class CommandExitError extends SandboxError {
     get error() { return this.result.error; }
     get stdout() { return this.result.stdout; }
     get stderr() { return this.result.stderr; }
+    get truncated() { return this.result.truncated; }
 }
 const STREAM_RECONNECT_ATTEMPTS = 12;
 const STREAM_RECONNECT_BASE_DELAY_MS = 250;
 const STREAM_RECONNECT_MAX_DELAY_MS = 2_000;
+/**
+ * Sentinel exit code reported when the runtime finishes a command without an
+ * explicit exit code (for example when it was killed or failed). Success is
+ * only ever an explicit exit code of 0.
+ */
+const MISSING_EXIT_CODE = -1;
+/** Server-side command ceiling used when the caller supplied no timeout. */
+const DEFAULT_WAIT_TIMEOUT_MS = 3_600_000;
+/** Extra client-side grace on top of the command timeout before giving up. */
+const WAIT_TIMEOUT_GRACE_MS = 60_000;
+/** Client-side wait deadline for a command: its timeout plus grace. */
+export function commandWaitDeadlineMs(timeoutMs) {
+    const base = timeoutMs !== undefined && timeoutMs > 0 ? timeoutMs : DEFAULT_WAIT_TIMEOUT_MS;
+    return base + WAIT_TIMEOUT_GRACE_MS;
+}
 /** Live handle for one sandbox process stream. */
 export class CommandHandle {
     pid;
@@ -34,6 +51,8 @@ export class CommandHandle {
     pending;
     nextCursor = 0;
     disconnected = false;
+    pendingLagged = false;
+    outputDropped = false;
     constructor(pid, socket, handleKill, events, onStdout, onStderr, onPty, onExit, reconnect) {
         this.pid = pid;
         this.socket = socket;
@@ -52,7 +71,7 @@ export class CommandHandle {
     get error() { return this.result?.error; }
     /** Wait until the process exits and return captured output. */
     async wait(timeoutMs) {
-        await waitFor(this.pending, timeoutMs);
+        await waitFor(this.pending, commandWaitDeadlineMs(timeoutMs), `timed out waiting for command ${this.pid} to exit; the command may still be running, check its status with commands.process(pid)`);
         if (!this.result)
             throw new SandboxError('Command ended without an exit event');
         if (this.result.exitCode !== 0)
@@ -84,8 +103,30 @@ export class CommandHandle {
         while (!this.disconnected && !this.result) {
             let streamError;
             for await (const frame of this.events) {
-                this.advanceCursor(frame);
                 const type = frame.type;
+                if (type === 'lagged') {
+                    // The runtime dropped frames from this stream. Replay them from the
+                    // next undelivered cursor when the stream supports reconnecting;
+                    // otherwise flag the dropped output. Do not advance the cursor from
+                    // a lagged frame, or the replay would skip the dropped events.
+                    if (!this.reconnect) {
+                        this.outputDropped = true;
+                        continue;
+                    }
+                    this.pendingLagged = true;
+                    break;
+                }
+                if (this.pendingLagged) {
+                    const cursor = numberValue(frame.cursor);
+                    if (cursor !== undefined) {
+                        // Backfill was impossible when the first replayed event sits past
+                        // the requested cursor: the runtime evicted the events between.
+                        if (cursor > this.nextCursor)
+                            this.outputDropped = true;
+                        this.pendingLagged = false;
+                    }
+                }
+                this.advanceCursor(frame);
                 if (type === 'started' || type === 'ready' || type === 'pong')
                     continue;
                 if (type === 'stdout') {
@@ -105,12 +146,25 @@ export class CommandHandle {
                     await this.onPty?.(bytes);
                 }
                 else if (type === 'exit') {
-                    const exitCode = Number(frame.exit_code ?? frame.exitCode ?? 0);
+                    const rawExitCode = numericExitCode(frame.exit_code ?? frame.exitCode);
+                    let error = typeof frame.error === 'string' ? frame.error : undefined;
+                    let exitCode;
+                    if (rawExitCode === undefined) {
+                        // Killed/failed commands may finish without an exit code. Keep
+                        // exitCode a plain number and take the failure path.
+                        const status = typeof frame.status === 'string' && frame.status ? frame.status : 'failed';
+                        exitCode = MISSING_EXIT_CODE;
+                        error ??= `command ${status} without an exit code${this._stderr ? `; stderr:\n${this._stderr}` : ''}`;
+                    }
+                    else {
+                        exitCode = rawExitCode;
+                    }
                     this.result = {
                         exitCode,
-                        error: typeof frame.error === 'string' ? frame.error : undefined,
+                        error,
                         stdout: this._stdout,
                         stderr: this._stderr,
+                        truncated: this.outputDropped,
                     };
                     await this.onExit?.(exitCode);
                     this.socket.close();
@@ -228,15 +282,19 @@ export class Commands {
     }
     /** 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);
+        const payload = await this.dataPlane
+            .getJson(`/runtime/v1/process/${encodeURIComponent(String(pid))}`, opts)
+            .catch((error) => { throw processPurgedNotFound(error, pid); });
         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`, {
+        const payload = await this.dataPlane
+            .getJson(withQuery(`/runtime/v1/process/${encodeURIComponent(String(pid))}/output`, {
             since: opts.since,
             limit_bytes: opts.limitBytes,
-        }), opts);
+        }), opts)
+            .catch((error) => { throw processPurgedNotFound(error, pid); });
         return processOutputSnapshot(payload);
     }
     /** Stop a process, optionally signalling the full process group. */
@@ -292,14 +350,22 @@ function processStartConfig(cmd, opts) {
     }
     return { cmd: '/bin/bash', args: ['-l', '-c', cmd] };
 }
-function waitFor(promise, timeoutMs) {
-    if (timeoutMs === undefined || timeoutMs <= 0)
-        return promise;
+function waitFor(promise, timeoutMs, message) {
     return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new TimeoutError()), timeoutMs);
+        const timer = setTimeout(() => reject(new TimeoutError(message)), timeoutMs);
         promise.then(resolve, reject).finally(() => clearTimeout(timer));
     });
 }
+function numericExitCode(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value !== '') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -355,8 +421,15 @@ function processStatus(value) {
         startedAt: stringValue(process.started_at ?? process.startedAt),
         finishedAt: stringValue(process.finished_at ?? process.finishedAt),
         exitCode: numberValue(process.exit_code ?? process.exitCode),
+        killRequestedAt: stringValue(process.kill_requested_at ?? process.killRequestedAt),
     };
 }
+function processPurgedNotFound(error, pid) {
+    if (error instanceof NotFoundError) {
+        return new NotFoundError(`process ${pid} not found: process records are purged when the sandbox is destroyed; terminal results were delivered via wait()/callbacks`);
+    }
+    return error;
+}
 function processOutputSnapshot(value) {
     const payload = value && typeof value === 'object' ? value : {};
     return {

package/dist/processSocket.js

@@ -1,7 +1,7 @@
 import { Buffer } from 'node:buffer';
 import WebSocket from 'ws';
 import { KEEPALIVE_PING_INTERVAL_SEC } from './connectionConfig.js';
-import { SandboxError, TimeoutError } from './errors.js';
+import { NotFoundError, SandboxError, TimeoutError } from './errors.js';
 /** Streaming WebSocket connection to the sandbox process runtime. */
 export class ProcessSocket {
     baseUrl;
@@ -36,6 +36,15 @@ export class ProcessSocket {
                 clearTimeout(timeout);
                 resolve();
             });
+            ws.once('unexpected-response', (_request, response) => {
+                clearTimeout(timeout);
+                if (response.statusCode === 404) {
+                    reject(new NotFoundError('process not found: process records are purged when the sandbox is destroyed; terminal results were delivered via wait()/callbacks'));
+                }
+                else {
+                    reject(new SandboxError(`process websocket failed to connect (status ${response.statusCode})`));
+                }
+            });
             ws.once('error', () => {
                 clearTimeout(timeout);
                 reject(new SandboxError('process websocket failed to connect'));

package/package.json

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