@boatdev/sdk 1.2.0 → 1.3.0

package/.openapi-generator/FILES

@@ -25,6 +25,7 @@ docs/CommandRequest.md
 docs/CommandResponse.md
 docs/CommandStartedResponse.md
 docs/CommandStatusResponse.md
+docs/CommandStreamFrame.md
 docs/CompletionEvent.md
 docs/Conversation.md
 docs/ConversationsResponse.md
@@ -163,6 +164,7 @@ src/models/CommandRequest.ts
 src/models/CommandResponse.ts
 src/models/CommandStartedResponse.ts
 src/models/CommandStatusResponse.ts
+src/models/CommandStreamFrame.ts
 src/models/CompletionEvent.ts
 src/models/Conversation.ts
 src/models/ConversationsResponse.ts

package/dist/apis/BoatApi.d.ts

@@ -387,12 +387,12 @@ export declare class BoatApi extends runtime.BaseAPI {
      */
     commandRequestOpts(input: CommandOperationRequest | runtime.FlatBody<CommandOperationRequest, 'commandRequest'>): Promise<runtime.RequestOpts>;
     /**
-     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. Returns 409 boat_starting (retryable) while the sandbox is still provisioning -- wait until the sandbox state is ready before running commands. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
+     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. With `stream: true` the output arrives as the command writes it, as newline-delimited JSON (`application/x-ndjson`): `{\"type\":\"started\"}`, then `{\"type\":\"stdout\"|\"stderr\",\"data\":\"...\"}` per chunk, and last `{\"type\":\"exit\",...}` (the synchronous result without stdout/stderr) or `{\"type\":\"error\",\"error\":\"...\",\"message\":\"...\"}`. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. A command sent while the sandbox is still starting (right after a resume) waits up to 60s for it to be ready instead of failing; 409 boat_starting (retryable) is returned only if it is still not ready by then. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
      * Execute a command in a sandbox
      */
     commandRaw(requestParameters: CommandOperationRequest | runtime.FlatBody<CommandOperationRequest, 'commandRequest'>, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<Command200Response>>;
     /**
-     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. Returns 409 boat_starting (retryable) while the sandbox is still provisioning -- wait until the sandbox state is ready before running commands. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
+     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. With `stream: true` the output arrives as the command writes it, as newline-delimited JSON (`application/x-ndjson`): `{\"type\":\"started\"}`, then `{\"type\":\"stdout\"|\"stderr\",\"data\":\"...\"}` per chunk, and last `{\"type\":\"exit\",...}` (the synchronous result without stdout/stderr) or `{\"type\":\"error\",\"error\":\"...\",\"message\":\"...\"}`. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. A command sent while the sandbox is still starting (right after a resume) waits up to 60s for it to be ready instead of failing; 409 boat_starting (retryable) is returned only if it is still not ready by then. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
      * Execute a command in a sandbox
      */
     command(requestParameters: CommandOperationRequest | runtime.FlatBody<CommandOperationRequest, 'commandRequest'>, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<Command200Response>;

package/dist/apis/BoatApi.js

@@ -331,7 +331,7 @@ class BoatApi extends runtime.BaseAPI {
         };
     }
     /**
-     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. Returns 409 boat_starting (retryable) while the sandbox is still provisioning -- wait until the sandbox state is ready before running commands. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
+     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. With `stream: true` the output arrives as the command writes it, as newline-delimited JSON (`application/x-ndjson`): `{\"type\":\"started\"}`, then `{\"type\":\"stdout\"|\"stderr\",\"data\":\"...\"}` per chunk, and last `{\"type\":\"exit\",...}` (the synchronous result without stdout/stderr) or `{\"type\":\"error\",\"error\":\"...\",\"message\":\"...\"}`. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. A command sent while the sandbox is still starting (right after a resume) waits up to 60s for it to be ready instead of failing; 409 boat_starting (retryable) is returned only if it is still not ready by then. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
      * Execute a command in a sandbox
      */
     async commandRaw(requestParameters, initOverrides) {
@@ -340,7 +340,7 @@ class BoatApi extends runtime.BaseAPI {
         return new runtime.JSONApiResponse(response, (jsonValue) => (0, Command200Response_1.Command200ResponseFromJSON)(jsonValue));
     }
     /**
-     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. Returns 409 boat_starting (retryable) while the sandbox is still provisioning -- wait until the sandbox state is ready before running commands. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
+     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. With `stream: true` the output arrives as the command writes it, as newline-delimited JSON (`application/x-ndjson`): `{\"type\":\"started\"}`, then `{\"type\":\"stdout\"|\"stderr\",\"data\":\"...\"}` per chunk, and last `{\"type\":\"exit\",...}` (the synchronous result without stdout/stderr) or `{\"type\":\"error\",\"error\":\"...\",\"message\":\"...\"}`. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. A command sent while the sandbox is still starting (right after a resume) waits up to 60s for it to be ready instead of failing; 409 boat_starting (retryable) is returned only if it is still not ready by then. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
      * Execute a command in a sandbox
      */
     async command(requestParameters, initOverrides) {

package/dist/boat-helpers.d.ts

@@ -1,5 +1,5 @@
 import { BoatApi } from './apis/BoatApi';
-import type { Sandbox, SandboxEvent, DesktopResponse, PromptRequest, PromptRun } from './models';
+import type { Sandbox, SandboxEvent, DesktopResponse, PromptRequest, PromptRun, CommandStreamFrame } from './models';
 export type WaitOptions = {
     timeoutMs?: number;
     intervalMs?: number;
@@ -54,3 +54,19 @@ export declare function stopAndRemove(api: BoatApi, sandboxId: string, options?:
 export declare function readText(api: BoatApi, sandboxId: string, path: string): Promise<string>;
 export declare function writeText(api: BoatApi, sandboxId: string, path: string, content: string): Promise<import("./models").FileWriteResponse>;
 export declare function execCommand(api: BoatApi, sandboxId: string, command: string, cwd?: string, timeoutSeconds?: number): Promise<import("./models").Command200Response>;
+/** One line of a streamed command, as sent (an `exit` frame also carries e.g. `signal`, `oomKilled`). */
+export type CommandFrame = CommandStreamFrame & Record<string, unknown>;
+export type StreamCommandOptions = {
+    cwd?: string;
+    timeoutSeconds?: number;
+    signal?: AbortSignal;
+};
+/**
+ * Run a command and yield its output as the command writes it: `started`, then
+ * `stdout`/`stderr` chunks (`frame.data`), then exactly one `exit` (`exitCode`,
+ * `timedOut`, ...) or `error` (`error`, `message`).
+ *
+ * Safe to call right after `resume()`, without waiting: the API holds a command
+ * sent to a starting sandbox for up to 60 s instead of refusing it.
+ */
+export declare function streamCommand(api: BoatApi, sandboxId: string, command: string, options?: StreamCommandOptions): AsyncGenerator<CommandFrame>;

package/dist/boat-helpers.js

@@ -11,6 +11,7 @@ exports.stopAndRemove = stopAndRemove;
 exports.readText = readText;
 exports.writeText = writeText;
 exports.execCommand = execCommand;
+exports.streamCommand = streamCommand;
 const terminalPromptStatuses = new Set(['finished', 'failed']);
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -174,3 +175,63 @@ async function writeText(api, sandboxId, path, content) {
 async function execCommand(api, sandboxId, command, cwd, timeoutSeconds = 30) {
     return api.command({ sandboxId, commandRequest: { command, cwd, timeoutSeconds } });
 }
+// A refusal that provably never ran the command (the sandbox is still restoring
+// its disk, `retryable: true` before `started`) is retried for this long.
+const STREAM_RETRY_MS = 60000;
+async function* ndjsonFrames(response) {
+    if (!response.body)
+        throw new Error('The command stream has no body');
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffered = '';
+    let done = false;
+    try {
+        while (!done) {
+            const chunk = await reader.read();
+            done = chunk.done;
+            buffered += done ? decoder.decode() : decoder.decode(chunk.value, { stream: true });
+            let newline = buffered.indexOf('\n');
+            while (newline !== -1) {
+                const line = buffered.slice(0, newline).trim();
+                buffered = buffered.slice(newline + 1);
+                if (line)
+                    yield JSON.parse(line);
+                newline = buffered.indexOf('\n');
+            }
+        }
+        if (buffered.trim())
+            yield JSON.parse(buffered);
+    }
+    finally {
+        // The caller stopped early: drop the connection instead of reading the rest.
+        if (!done)
+            await reader.cancel().catch(() => undefined);
+    }
+}
+/**
+ * Run a command and yield its output as the command writes it: `started`, then
+ * `stdout`/`stderr` chunks (`frame.data`), then exactly one `exit` (`exitCode`,
+ * `timedOut`, ...) or `error` (`error`, `message`).
+ *
+ * Safe to call right after `resume()`, without waiting: the API holds a command
+ * sent to a starting sandbox for up to 60 s instead of refusing it.
+ */
+async function* streamCommand(api, sandboxId, command, options) {
+    const deadline = Date.now() + STREAM_RETRY_MS;
+    for (;;) {
+        const response = await api.commandRaw({ sandboxId, commandRequest: { command, cwd: options === null || options === void 0 ? void 0 : options.cwd, timeoutSeconds: options === null || options === void 0 ? void 0 : options.timeoutSeconds, stream: true } }, { signal: options === null || options === void 0 ? void 0 : options.signal });
+        let started = false;
+        let retry = false;
+        for await (const frame of ndjsonFrames(response.raw)) {
+            started = started || frame.type === 'started';
+            if (!started && frame.type === 'error' && frame.retryable === true && Date.now() < deadline) {
+                retry = true;
+                break;
+            }
+            yield frame;
+        }
+        if (!retry)
+            return;
+        await delay(1000);
+    }
+}

package/dist/esm/apis/BoatApi.d.ts

@@ -387,12 +387,12 @@ export declare class BoatApi extends runtime.BaseAPI {
      */
     commandRequestOpts(input: CommandOperationRequest | runtime.FlatBody<CommandOperationRequest, 'commandRequest'>): Promise<runtime.RequestOpts>;
     /**
-     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. Returns 409 boat_starting (retryable) while the sandbox is still provisioning -- wait until the sandbox state is ready before running commands. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
+     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. With `stream: true` the output arrives as the command writes it, as newline-delimited JSON (`application/x-ndjson`): `{\"type\":\"started\"}`, then `{\"type\":\"stdout\"|\"stderr\",\"data\":\"...\"}` per chunk, and last `{\"type\":\"exit\",...}` (the synchronous result without stdout/stderr) or `{\"type\":\"error\",\"error\":\"...\",\"message\":\"...\"}`. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. A command sent while the sandbox is still starting (right after a resume) waits up to 60s for it to be ready instead of failing; 409 boat_starting (retryable) is returned only if it is still not ready by then. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
      * Execute a command in a sandbox
      */
     commandRaw(requestParameters: CommandOperationRequest | runtime.FlatBody<CommandOperationRequest, 'commandRequest'>, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<Command200Response>>;
     /**
-     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. Returns 409 boat_starting (retryable) while the sandbox is still provisioning -- wait until the sandbox state is ready before running commands. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
+     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. With `stream: true` the output arrives as the command writes it, as newline-delimited JSON (`application/x-ndjson`): `{\"type\":\"started\"}`, then `{\"type\":\"stdout\"|\"stderr\",\"data\":\"...\"}` per chunk, and last `{\"type\":\"exit\",...}` (the synchronous result without stdout/stderr) or `{\"type\":\"error\",\"error\":\"...\",\"message\":\"...\"}`. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. A command sent while the sandbox is still starting (right after a resume) waits up to 60s for it to be ready instead of failing; 409 boat_starting (retryable) is returned only if it is still not ready by then. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
      * Execute a command in a sandbox
      */
     command(requestParameters: CommandOperationRequest | runtime.FlatBody<CommandOperationRequest, 'commandRequest'>, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<Command200Response>;

package/dist/esm/apis/BoatApi.js

@@ -295,7 +295,7 @@ export class BoatApi extends runtime.BaseAPI {
         };
     }
     /**
-     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. Returns 409 boat_starting (retryable) while the sandbox is still provisioning -- wait until the sandbox state is ready before running commands. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
+     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. With `stream: true` the output arrives as the command writes it, as newline-delimited JSON (`application/x-ndjson`): `{\"type\":\"started\"}`, then `{\"type\":\"stdout\"|\"stderr\",\"data\":\"...\"}` per chunk, and last `{\"type\":\"exit\",...}` (the synchronous result without stdout/stderr) or `{\"type\":\"error\",\"error\":\"...\",\"message\":\"...\"}`. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. A command sent while the sandbox is still starting (right after a resume) waits up to 60s for it to be ready instead of failing; 409 boat_starting (retryable) is returned only if it is still not ready by then. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
      * Execute a command in a sandbox
      */
     async commandRaw(requestParameters, initOverrides) {
@@ -304,7 +304,7 @@ export class BoatApi extends runtime.BaseAPI {
         return new runtime.JSONApiResponse(response, (jsonValue) => Command200ResponseFromJSON(jsonValue));
     }
     /**
-     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. Returns 409 boat_starting (retryable) while the sandbox is still provisioning -- wait until the sandbox state is ready before running commands. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
+     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. With `stream: true` the output arrives as the command writes it, as newline-delimited JSON (`application/x-ndjson`): `{\"type\":\"started\"}`, then `{\"type\":\"stdout\"|\"stderr\",\"data\":\"...\"}` per chunk, and last `{\"type\":\"exit\",...}` (the synchronous result without stdout/stderr) or `{\"type\":\"error\",\"error\":\"...\",\"message\":\"...\"}`. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. A command sent while the sandbox is still starting (right after a resume) waits up to 60s for it to be ready instead of failing; 409 boat_starting (retryable) is returned only if it is still not ready by then. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
      * Execute a command in a sandbox
      */
     async command(requestParameters, initOverrides) {

package/dist/esm/boat-helpers.d.ts

@@ -1,5 +1,5 @@
 import { BoatApi } from './apis/BoatApi';
-import type { Sandbox, SandboxEvent, DesktopResponse, PromptRequest, PromptRun } from './models';
+import type { Sandbox, SandboxEvent, DesktopResponse, PromptRequest, PromptRun, CommandStreamFrame } from './models';
 export type WaitOptions = {
     timeoutMs?: number;
     intervalMs?: number;
@@ -54,3 +54,19 @@ export declare function stopAndRemove(api: BoatApi, sandboxId: string, options?:
 export declare function readText(api: BoatApi, sandboxId: string, path: string): Promise<string>;
 export declare function writeText(api: BoatApi, sandboxId: string, path: string, content: string): Promise<import("./models").FileWriteResponse>;
 export declare function execCommand(api: BoatApi, sandboxId: string, command: string, cwd?: string, timeoutSeconds?: number): Promise<import("./models").Command200Response>;
+/** One line of a streamed command, as sent (an `exit` frame also carries e.g. `signal`, `oomKilled`). */
+export type CommandFrame = CommandStreamFrame & Record<string, unknown>;
+export type StreamCommandOptions = {
+    cwd?: string;
+    timeoutSeconds?: number;
+    signal?: AbortSignal;
+};
+/**
+ * Run a command and yield its output as the command writes it: `started`, then
+ * `stdout`/`stderr` chunks (`frame.data`), then exactly one `exit` (`exitCode`,
+ * `timedOut`, ...) or `error` (`error`, `message`).
+ *
+ * Safe to call right after `resume()`, without waiting: the API holds a command
+ * sent to a starting sandbox for up to 60 s instead of refusing it.
+ */
+export declare function streamCommand(api: BoatApi, sandboxId: string, command: string, options?: StreamCommandOptions): AsyncGenerator<CommandFrame>;

package/dist/esm/boat-helpers.js

@@ -161,3 +161,63 @@ export async function writeText(api, sandboxId, path, content) {
 export async function execCommand(api, sandboxId, command, cwd, timeoutSeconds = 30) {
     return api.command({ sandboxId, commandRequest: { command, cwd, timeoutSeconds } });
 }
+// A refusal that provably never ran the command (the sandbox is still restoring
+// its disk, `retryable: true` before `started`) is retried for this long.
+const STREAM_RETRY_MS = 60000;
+async function* ndjsonFrames(response) {
+    if (!response.body)
+        throw new Error('The command stream has no body');
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffered = '';
+    let done = false;
+    try {
+        while (!done) {
+            const chunk = await reader.read();
+            done = chunk.done;
+            buffered += done ? decoder.decode() : decoder.decode(chunk.value, { stream: true });
+            let newline = buffered.indexOf('\n');
+            while (newline !== -1) {
+                const line = buffered.slice(0, newline).trim();
+                buffered = buffered.slice(newline + 1);
+                if (line)
+                    yield JSON.parse(line);
+                newline = buffered.indexOf('\n');
+            }
+        }
+        if (buffered.trim())
+            yield JSON.parse(buffered);
+    }
+    finally {
+        // The caller stopped early: drop the connection instead of reading the rest.
+        if (!done)
+            await reader.cancel().catch(() => undefined);
+    }
+}
+/**
+ * Run a command and yield its output as the command writes it: `started`, then
+ * `stdout`/`stderr` chunks (`frame.data`), then exactly one `exit` (`exitCode`,
+ * `timedOut`, ...) or `error` (`error`, `message`).
+ *
+ * Safe to call right after `resume()`, without waiting: the API holds a command
+ * sent to a starting sandbox for up to 60 s instead of refusing it.
+ */
+export async function* streamCommand(api, sandboxId, command, options) {
+    const deadline = Date.now() + STREAM_RETRY_MS;
+    for (;;) {
+        const response = await api.commandRaw({ sandboxId, commandRequest: { command, cwd: options === null || options === void 0 ? void 0 : options.cwd, timeoutSeconds: options === null || options === void 0 ? void 0 : options.timeoutSeconds, stream: true } }, { signal: options === null || options === void 0 ? void 0 : options.signal });
+        let started = false;
+        let retry = false;
+        for await (const frame of ndjsonFrames(response.raw)) {
+            started = started || frame.type === 'started';
+            if (!started && frame.type === 'error' && frame.retryable === true && Date.now() < deadline) {
+                retry = true;
+                break;
+            }
+            yield frame;
+        }
+        if (!retry)
+            return;
+        await delay(1000);
+    }
+}

package/dist/esm/models/CommandRequest.d.ts

@@ -39,6 +39,12 @@ export interface CommandRequest {
      * @memberof CommandRequest
      */
     detached?: boolean;
+    /**
+     * Stream the output as the command writes it: the response is newline-delimited JSON (application/x-ndjson), one CommandStreamFrame per line. Ignored with detached.
+     * @type {boolean}
+     * @memberof CommandRequest
+     */
+    stream?: boolean;
 }
 /**
  * Check if a given object implements the CommandRequest interface.

package/dist/esm/models/CommandRequest.js

@@ -31,6 +31,7 @@ export function CommandRequestFromJSONTyped(json, ignoreDiscriminator) {
         'cwd': json['cwd'] == null ? undefined : json['cwd'],
         'timeoutSeconds': json['timeoutSeconds'] == null ? undefined : json['timeoutSeconds'],
         'detached': json['detached'] == null ? undefined : json['detached'],
+        'stream': json['stream'] == null ? undefined : json['stream'],
     };
 }
 export function CommandRequestToJSON(json) {
@@ -45,5 +46,6 @@ export function CommandRequestToJSONTyped(value, ignoreDiscriminator = false) {
         'cwd': value['cwd'],
         'timeoutSeconds': value['timeoutSeconds'],
         'detached': value['detached'],
+        'stream': value['stream'],
     };
 }

package/dist/esm/models/CommandStreamFrame.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Boat Public API v1
+ * Public JSON API for creating, operating, prompting, observing, and exposing sandboxes from backend services, CI jobs, hosted workers, and Boat automation products.  The v1 reference intentionally documents the developer integration surface only. Dashboard billing actions are not part of v1.
+ *
+ * The version of the OpenAPI document: 1.0.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+/**
+ * One line of a streamed command. `started` first, then `stdout`/`stderr` chunks, then exactly one `exit` (the synchronous result, without stdout/stderr) or `error`.
+ * @export
+ * @interface CommandStreamFrame
+ */
+export interface CommandStreamFrame {
+    /**
+     *
+     * @type {CommandStreamFrameTypeEnum}
+     * @memberof CommandStreamFrame
+     */
+    type: CommandStreamFrameTypeEnum;
+    /**
+     * stdout/stderr: the chunk of output, UTF-8.
+     * @type {string}
+     * @memberof CommandStreamFrame
+     */
+    data?: string;
+    /**
+     *
+     * @type {number}
+     * @memberof CommandStreamFrame
+     */
+    exitCode?: number | null;
+    /**
+     *
+     * @type {boolean}
+     * @memberof CommandStreamFrame
+     */
+    success?: boolean;
+    /**
+     *
+     * @type {boolean}
+     * @memberof CommandStreamFrame
+     */
+    timedOut?: boolean;
+    /**
+     *
+     * @type {string}
+     * @memberof CommandStreamFrame
+     */
+    error?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof CommandStreamFrame
+     */
+    message?: string;
+    /**
+     * error: true when the command provably never ran (the sandbox is still restoring its disk), so sending it again is safe.
+     * @type {boolean}
+     * @memberof CommandStreamFrame
+     */
+    retryable?: boolean;
+}
+/**
+ * @export
+ */
+export declare const CommandStreamFrameTypeEnum: {
+    readonly Started: 'started';
+    readonly Stdout: 'stdout';
+    readonly Stderr: 'stderr';
+    readonly Exit: 'exit';
+    readonly Error: 'error';
+};
+export type CommandStreamFrameTypeEnum = typeof CommandStreamFrameTypeEnum[keyof typeof CommandStreamFrameTypeEnum];
+/**
+ * Check if a given object implements the CommandStreamFrame interface.
+ */
+export declare function instanceOfCommandStreamFrame(value: object): value is CommandStreamFrame;
+export declare function CommandStreamFrameFromJSON(json: any): CommandStreamFrame;
+export declare function CommandStreamFrameFromJSONTyped(json: any, ignoreDiscriminator: boolean): CommandStreamFrame;
+export declare function CommandStreamFrameToJSON(json: any): CommandStreamFrame;
+export declare function CommandStreamFrameToJSONTyped(value?: CommandStreamFrame | null, ignoreDiscriminator?: boolean): any;

package/dist/esm/models/CommandStreamFrame.js

@@ -0,0 +1,67 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Boat Public API v1
+ * Public JSON API for creating, operating, prompting, observing, and exposing sandboxes from backend services, CI jobs, hosted workers, and Boat automation products.  The v1 reference intentionally documents the developer integration surface only. Dashboard billing actions are not part of v1.
+ *
+ * The version of the OpenAPI document: 1.0.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+/**
+ * @export
+ */
+export const CommandStreamFrameTypeEnum = {
+    Started: 'started',
+    Stdout: 'stdout',
+    Stderr: 'stderr',
+    Exit: 'exit',
+    Error: 'error'
+};
+/**
+ * Check if a given object implements the CommandStreamFrame interface.
+ */
+export function instanceOfCommandStreamFrame(value) {
+    if (!('type' in value) || value['type'] === undefined)
+        return false;
+    return true;
+}
+export function CommandStreamFrameFromJSON(json) {
+    return CommandStreamFrameFromJSONTyped(json, false);
+}
+export function CommandStreamFrameFromJSONTyped(json, ignoreDiscriminator) {
+    if (json == null) {
+        return json;
+    }
+    return {
+        'type': json['type'],
+        'data': json['data'] == null ? undefined : json['data'],
+        'exitCode': json['exitCode'] == null ? undefined : json['exitCode'],
+        'success': json['success'] == null ? undefined : json['success'],
+        'timedOut': json['timedOut'] == null ? undefined : json['timedOut'],
+        'error': json['error'] == null ? undefined : json['error'],
+        'message': json['message'] == null ? undefined : json['message'],
+        'retryable': json['retryable'] == null ? undefined : json['retryable'],
+    };
+}
+export function CommandStreamFrameToJSON(json) {
+    return CommandStreamFrameToJSONTyped(json, false);
+}
+export function CommandStreamFrameToJSONTyped(value, ignoreDiscriminator = false) {
+    if (value == null) {
+        return value;
+    }
+    return {
+        'type': value['type'],
+        'data': value['data'],
+        'exitCode': value['exitCode'],
+        'success': value['success'],
+        'timedOut': value['timedOut'],
+        'error': value['error'],
+        'message': value['message'],
+        'retryable': value['retryable'],
+    };
+}

package/dist/esm/models/CreateSandboxRequest.d.ts

@@ -53,6 +53,12 @@ export interface CreateSandboxRequest {
      * @memberof CreateSandboxRequest
      */
     snapshots?: boolean;
+    /**
+     * Pass `true` to get a sandbox only if a machine of this type is ready right now. The call answers within about 1.5 s: either the usual `202` with the sandbox, or `503` `no_ready_machine` with nothing created, billed, or counted against your start limits, so you can retry or fall back at once. Without it, a create waits for a machine to be built when none is ready. Not combinable with `from`.
+     * @type {boolean}
+     * @memberof CreateSandboxRequest
+     */
+    failFast?: boolean;
     /**
      * Shell script that runs on the sandbox after it is ready. Ready means "ready to accept the user", not "setup done": the script starts in the background once provisioning completes and never blocks the sandbox becoming usable. It runs as the sandbox user via `bash`, with the sandbox's environment applied, and its output goes to a log file on the sandbox. Observe the outcome as `setupStatus` (pending/running/done/failed) and `setupError` on the sandbox. Rejected with a 400 `invalid_setup_script` error when it is not a string or exceeds 64KB.
      * @type {string}

package/dist/esm/models/CreateSandboxRequest.js

@@ -39,6 +39,7 @@ export function CreateSandboxRequestFromJSONTyped(json, ignoreDiscriminator) {
         'environment': json['environment'] == null ? undefined : json['environment'],
         'noEnv': json['noEnv'] == null ? undefined : json['noEnv'],
         'snapshots': json['snapshots'] == null ? undefined : json['snapshots'],
+        'failFast': json['failFast'] == null ? undefined : json['failFast'],
         'setupScript': json['setupScript'] == null ? undefined : json['setupScript'],
         'org': json['org'] == null ? undefined : json['org'],
         'teamId': json['teamId'] == null ? undefined : json['teamId'],
@@ -59,6 +60,7 @@ export function CreateSandboxRequestToJSONTyped(value, ignoreDiscriminator = fal
         'environment': value['environment'],
         'noEnv': value['noEnv'],
         'snapshots': value['snapshots'],
+        'failFast': value['failFast'],
         'setupScript': value['setupScript'],
         'org': value['org'],
         'teamId': value['teamId'],

package/dist/esm/models/index.d.ts

@@ -20,6 +20,7 @@ export * from './CommandRequest';
 export * from './CommandResponse';
 export * from './CommandStartedResponse';
 export * from './CommandStatusResponse';
+export * from './CommandStreamFrame';
 export * from './CompletionEvent';
 export * from './Conversation';
 export * from './ConversationsResponse';

package/dist/esm/models/index.js

@@ -22,6 +22,7 @@ export * from './CommandRequest';
 export * from './CommandResponse';
 export * from './CommandStartedResponse';
 export * from './CommandStatusResponse';
+export * from './CommandStreamFrame';
 export * from './CompletionEvent';
 export * from './Conversation';
 export * from './ConversationsResponse';

package/dist/models/CommandRequest.d.ts

@@ -39,6 +39,12 @@ export interface CommandRequest {
      * @memberof CommandRequest
      */
     detached?: boolean;
+    /**
+     * Stream the output as the command writes it: the response is newline-delimited JSON (application/x-ndjson), one CommandStreamFrame per line. Ignored with detached.
+     * @type {boolean}
+     * @memberof CommandRequest
+     */
+    stream?: boolean;
 }
 /**
  * Check if a given object implements the CommandRequest interface.

package/dist/models/CommandRequest.js

@@ -38,6 +38,7 @@ function CommandRequestFromJSONTyped(json, ignoreDiscriminator) {
         'cwd': json['cwd'] == null ? undefined : json['cwd'],
         'timeoutSeconds': json['timeoutSeconds'] == null ? undefined : json['timeoutSeconds'],
         'detached': json['detached'] == null ? undefined : json['detached'],
+        'stream': json['stream'] == null ? undefined : json['stream'],
     };
 }
 function CommandRequestToJSON(json) {
@@ -52,5 +53,6 @@ function CommandRequestToJSONTyped(value, ignoreDiscriminator = false) {
         'cwd': value['cwd'],
         'timeoutSeconds': value['timeoutSeconds'],
         'detached': value['detached'],
+        'stream': value['stream'],
     };
 }

package/dist/models/CommandStreamFrame.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Boat Public API v1
+ * Public JSON API for creating, operating, prompting, observing, and exposing sandboxes from backend services, CI jobs, hosted workers, and Boat automation products.  The v1 reference intentionally documents the developer integration surface only. Dashboard billing actions are not part of v1.
+ *
+ * The version of the OpenAPI document: 1.0.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+/**
+ * One line of a streamed command. `started` first, then `stdout`/`stderr` chunks, then exactly one `exit` (the synchronous result, without stdout/stderr) or `error`.
+ * @export
+ * @interface CommandStreamFrame
+ */
+export interface CommandStreamFrame {
+    /**
+     *
+     * @type {CommandStreamFrameTypeEnum}
+     * @memberof CommandStreamFrame
+     */
+    type: CommandStreamFrameTypeEnum;
+    /**
+     * stdout/stderr: the chunk of output, UTF-8.
+     * @type {string}
+     * @memberof CommandStreamFrame
+     */
+    data?: string;
+    /**
+     *
+     * @type {number}
+     * @memberof CommandStreamFrame
+     */
+    exitCode?: number | null;
+    /**
+     *
+     * @type {boolean}
+     * @memberof CommandStreamFrame
+     */
+    success?: boolean;
+    /**
+     *
+     * @type {boolean}
+     * @memberof CommandStreamFrame
+     */
+    timedOut?: boolean;
+    /**
+     *
+     * @type {string}
+     * @memberof CommandStreamFrame
+     */
+    error?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof CommandStreamFrame
+     */
+    message?: string;
+    /**
+     * error: true when the command provably never ran (the sandbox is still restoring its disk), so sending it again is safe.
+     * @type {boolean}
+     * @memberof CommandStreamFrame
+     */
+    retryable?: boolean;
+}
+/**
+ * @export
+ */
+export declare const CommandStreamFrameTypeEnum: {
+    readonly Started: 'started';
+    readonly Stdout: 'stdout';
+    readonly Stderr: 'stderr';
+    readonly Exit: 'exit';
+    readonly Error: 'error';
+};
+export type CommandStreamFrameTypeEnum = typeof CommandStreamFrameTypeEnum[keyof typeof CommandStreamFrameTypeEnum];
+/**
+ * Check if a given object implements the CommandStreamFrame interface.
+ */
+export declare function instanceOfCommandStreamFrame(value: object): value is CommandStreamFrame;
+export declare function CommandStreamFrameFromJSON(json: any): CommandStreamFrame;
+export declare function CommandStreamFrameFromJSONTyped(json: any, ignoreDiscriminator: boolean): CommandStreamFrame;
+export declare function CommandStreamFrameToJSON(json: any): CommandStreamFrame;
+export declare function CommandStreamFrameToJSONTyped(value?: CommandStreamFrame | null, ignoreDiscriminator?: boolean): any;

package/dist/models/CommandStreamFrame.js

@@ -0,0 +1,75 @@
+"use strict";
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Boat Public API v1
+ * Public JSON API for creating, operating, prompting, observing, and exposing sandboxes from backend services, CI jobs, hosted workers, and Boat automation products.  The v1 reference intentionally documents the developer integration surface only. Dashboard billing actions are not part of v1.
+ *
+ * The version of the OpenAPI document: 1.0.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandStreamFrameTypeEnum = void 0;
+exports.instanceOfCommandStreamFrame = instanceOfCommandStreamFrame;
+exports.CommandStreamFrameFromJSON = CommandStreamFrameFromJSON;
+exports.CommandStreamFrameFromJSONTyped = CommandStreamFrameFromJSONTyped;
+exports.CommandStreamFrameToJSON = CommandStreamFrameToJSON;
+exports.CommandStreamFrameToJSONTyped = CommandStreamFrameToJSONTyped;
+/**
+ * @export
+ */
+exports.CommandStreamFrameTypeEnum = {
+    Started: 'started',
+    Stdout: 'stdout',
+    Stderr: 'stderr',
+    Exit: 'exit',
+    Error: 'error'
+};
+/**
+ * Check if a given object implements the CommandStreamFrame interface.
+ */
+function instanceOfCommandStreamFrame(value) {
+    if (!('type' in value) || value['type'] === undefined)
+        return false;
+    return true;
+}
+function CommandStreamFrameFromJSON(json) {
+    return CommandStreamFrameFromJSONTyped(json, false);
+}
+function CommandStreamFrameFromJSONTyped(json, ignoreDiscriminator) {
+    if (json == null) {
+        return json;
+    }
+    return {
+        'type': json['type'],
+        'data': json['data'] == null ? undefined : json['data'],
+        'exitCode': json['exitCode'] == null ? undefined : json['exitCode'],
+        'success': json['success'] == null ? undefined : json['success'],
+        'timedOut': json['timedOut'] == null ? undefined : json['timedOut'],
+        'error': json['error'] == null ? undefined : json['error'],
+        'message': json['message'] == null ? undefined : json['message'],
+        'retryable': json['retryable'] == null ? undefined : json['retryable'],
+    };
+}
+function CommandStreamFrameToJSON(json) {
+    return CommandStreamFrameToJSONTyped(json, false);
+}
+function CommandStreamFrameToJSONTyped(value, ignoreDiscriminator = false) {
+    if (value == null) {
+        return value;
+    }
+    return {
+        'type': value['type'],
+        'data': value['data'],
+        'exitCode': value['exitCode'],
+        'success': value['success'],
+        'timedOut': value['timedOut'],
+        'error': value['error'],
+        'message': value['message'],
+        'retryable': value['retryable'],
+    };
+}

package/dist/models/CreateSandboxRequest.d.ts

@@ -53,6 +53,12 @@ export interface CreateSandboxRequest {
      * @memberof CreateSandboxRequest
      */
     snapshots?: boolean;
+    /**
+     * Pass `true` to get a sandbox only if a machine of this type is ready right now. The call answers within about 1.5 s: either the usual `202` with the sandbox, or `503` `no_ready_machine` with nothing created, billed, or counted against your start limits, so you can retry or fall back at once. Without it, a create waits for a machine to be built when none is ready. Not combinable with `from`.
+     * @type {boolean}
+     * @memberof CreateSandboxRequest
+     */
+    failFast?: boolean;
     /**
      * Shell script that runs on the sandbox after it is ready. Ready means "ready to accept the user", not "setup done": the script starts in the background once provisioning completes and never blocks the sandbox becoming usable. It runs as the sandbox user via `bash`, with the sandbox's environment applied, and its output goes to a log file on the sandbox. Observe the outcome as `setupStatus` (pending/running/done/failed) and `setupError` on the sandbox. Rejected with a 400 `invalid_setup_script` error when it is not a string or exceeds 64KB.
      * @type {string}

package/dist/models/CreateSandboxRequest.js

@@ -47,6 +47,7 @@ function CreateSandboxRequestFromJSONTyped(json, ignoreDiscriminator) {
         'environment': json['environment'] == null ? undefined : json['environment'],
         'noEnv': json['noEnv'] == null ? undefined : json['noEnv'],
         'snapshots': json['snapshots'] == null ? undefined : json['snapshots'],
+        'failFast': json['failFast'] == null ? undefined : json['failFast'],
         'setupScript': json['setupScript'] == null ? undefined : json['setupScript'],
         'org': json['org'] == null ? undefined : json['org'],
         'teamId': json['teamId'] == null ? undefined : json['teamId'],
@@ -67,6 +68,7 @@ function CreateSandboxRequestToJSONTyped(value, ignoreDiscriminator = false) {
         'environment': value['environment'],
         'noEnv': value['noEnv'],
         'snapshots': value['snapshots'],
+        'failFast': value['failFast'],
         'setupScript': value['setupScript'],
         'org': value['org'],
         'teamId': value['teamId'],

package/dist/models/index.d.ts

@@ -20,6 +20,7 @@ export * from './CommandRequest';
 export * from './CommandResponse';
 export * from './CommandStartedResponse';
 export * from './CommandStatusResponse';
+export * from './CommandStreamFrame';
 export * from './CompletionEvent';
 export * from './Conversation';
 export * from './ConversationsResponse';

package/dist/models/index.js

@@ -38,6 +38,7 @@ __exportStar(require("./CommandRequest"), exports);
 __exportStar(require("./CommandResponse"), exports);
 __exportStar(require("./CommandStartedResponse"), exports);
 __exportStar(require("./CommandStatusResponse"), exports);
+__exportStar(require("./CommandStreamFrame"), exports);
 __exportStar(require("./CompletionEvent"), exports);
 __exportStar(require("./Conversation"), exports);
 __exportStar(require("./ConversationsResponse"), exports);

package/docs/BoatApi.md

@@ -368,7 +368,7 @@ example().catch(console.error);
 
 Execute a command in a sandbox
 
-Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. Returns 409 boat_starting (retryable) while the sandbox is still provisioning -- wait until the sandbox state is ready before running commands. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
+Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. With `stream: true` the output arrives as the command writes it, as newline-delimited JSON (`application/x-ndjson`): `{\"type\":\"started\"}`, then `{\"type\":\"stdout\"|\"stderr\",\"data\":\"...\"}` per chunk, and last `{\"type\":\"exit\",...}` (the synchronous result without stdout/stderr) or `{\"type\":\"error\",\"error\":\"...\",\"message\":\"...\"}`. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. A command sent while the sandbox is still starting (right after a resume) waits up to 60s for it to be ready instead of failing; 409 boat_starting (retryable) is returned only if it is still not ready by then. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
 
 ### Example
 
@@ -425,13 +425,13 @@ example().catch(console.error);
 ### HTTP request headers
 
 - **Content-Type**: `application/json`
-- **Accept**: `application/json`
+- **Accept**: `application/json`, `application/x-ndjson`
 
 
 ### HTTP response details
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
-| **200** | Command result (synchronous) or process start confirmation (detached). |  -  |
+| **200** | Command result (synchronous), process start confirmation (detached), or the output stream (`stream: true`). |  -  |
 | **400** | Invalid request body or parameters. |  -  |
 | **401** | Missing or invalid bearer token. |  -  |
 | **404** | Resource not found. |  -  |
@@ -672,6 +672,7 @@ example().catch(console.error);
 | **402** | Account cannot currently create or operate sandboxes. The error body may include a dashboard billing URL, but billing actions are not part of the v1 API. |  -  |
 | **409** | Request conflicts with current account or sandbox state. |  -  |
 | **429** | Machine start or concurrent-sandbox limit reached. Create, fork and resume each count as one machine start against your plan\'s start limits (see the Billing guide; `rate_limited`, naming the window you hit). A sandbox that would exceed your plan\'s concurrent-sandbox cap is refused with `limit_reached`, or `member_limit_reached` when an organization owner has capped you below the plan. |  -  |
+| **503** | No capacity. `no_ready_machine`: a `failFast` create found no ready machine of that type; nothing was created, billed, or counted. `out_of_capacity`: creates are paused until the provisioning queue drains. |  -  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 

package/docs/CommandRequest.md

@@ -10,6 +10,7 @@ Name | Type
 `cwd` | string
 `timeoutSeconds` | number
 `detached` | boolean
+`stream` | boolean
 
 ## Example
 
@@ -22,6 +23,7 @@ const example = {
   "cwd": null,
   "timeoutSeconds": null,
   "detached": null,
+  "stream": null,
 } satisfies CommandRequest
 
 console.log(example)

package/docs/CommandStreamFrame.md

@@ -0,0 +1,47 @@
+
+# CommandStreamFrame
+
+One line of a streamed command. `started` first, then `stdout`/`stderr` chunks, then exactly one `exit` (the synchronous result, without stdout/stderr) or `error`.
+
+## Properties
+
+Name | Type
+------------ | -------------
+`type` | string
+`data` | string
+`exitCode` | number
+`success` | boolean
+`timedOut` | boolean
+`error` | string
+`message` | string
+`retryable` | boolean
+
+## Example
+
+```typescript
+import type { CommandStreamFrame } from '@boatdev/sdk'
+
+// TODO: Update the object below with actual values
+const example = {
+  "type": null,
+  "data": null,
+  "exitCode": null,
+  "success": null,
+  "timedOut": null,
+  "error": null,
+  "message": null,
+  "retryable": null,
+} satisfies CommandStreamFrame
+
+console.log(example)
+
+// Convert the instance to a JSON string
+const exampleJSON: string = JSON.stringify(example)
+console.log(exampleJSON)
+
+// Parse the JSON string back to an object
+const exampleParsed = JSON.parse(exampleJSON) as CommandStreamFrame
+console.log(exampleParsed)
+```
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)

package/docs/CreateSandboxRequest.md

@@ -13,6 +13,7 @@ Name | Type
 `environment` | string
 `noEnv` | boolean
 `snapshots` | boolean
+`failFast` | boolean
 `setupScript` | string
 `org` | string
 `teamId` | string
@@ -31,6 +32,7 @@ const example = {
   "environment": null,
   "noEnv": null,
   "snapshots": null,
+  "failFast": null,
   "setupScript": null,
   "org": null,
   "teamId": null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boatdev/sdk",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "OpenAPI client for @boatdev/sdk",
   "author": "OpenAPI-Generator",
   "license": "MIT",

package/src/apis/BoatApi.ts

@@ -63,6 +63,11 @@ import {
     CommandStatusResponseFromJSON,
     CommandStatusResponseToJSON,
 } from '../models/CommandStatusResponse';
+import {
+    type CommandStreamFrame,
+    CommandStreamFrameFromJSON,
+    CommandStreamFrameToJSON,
+} from '../models/CommandStreamFrame';
 import {
     type ConversationsResponse,
     ConversationsResponseFromJSON,
@@ -979,7 +984,7 @@ export class BoatApi extends runtime.BaseAPI {
     }
 
     /**
-     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. Returns 409 boat_starting (retryable) while the sandbox is still provisioning -- wait until the sandbox state is ready before running commands. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
+     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. With `stream: true` the output arrives as the command writes it, as newline-delimited JSON (`application/x-ndjson`): `{\"type\":\"started\"}`, then `{\"type\":\"stdout\"|\"stderr\",\"data\":\"...\"}` per chunk, and last `{\"type\":\"exit\",...}` (the synchronous result without stdout/stderr) or `{\"type\":\"error\",\"error\":\"...\",\"message\":\"...\"}`. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. A command sent while the sandbox is still starting (right after a resume) waits up to 60s for it to be ready instead of failing; 409 boat_starting (retryable) is returned only if it is still not ready by then. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
      * Execute a command in a sandbox
      */
     async commandRaw(requestParameters: CommandOperationRequest | runtime.FlatBody<CommandOperationRequest, 'commandRequest'>, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<Command200Response>> {
@@ -990,7 +995,7 @@ export class BoatApi extends runtime.BaseAPI {
     }
 
     /**
-     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. Returns 409 boat_starting (retryable) while the sandbox is still provisioning -- wait until the sandbox state is ready before running commands. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
+     * Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. With `stream: true` the output arrives as the command writes it, as newline-delimited JSON (`application/x-ndjson`): `{\"type\":\"started\"}`, then `{\"type\":\"stdout\"|\"stderr\",\"data\":\"...\"}` per chunk, and last `{\"type\":\"exit\",...}` (the synchronous result without stdout/stderr) or `{\"type\":\"error\",\"error\":\"...\",\"message\":\"...\"}`. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. A command sent while the sandbox is still starting (right after a resume) waits up to 60s for it to be ready instead of failing; 409 boat_starting (retryable) is returned only if it is still not ready by then. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox.
      * Execute a command in a sandbox
      */
     async command(requestParameters: CommandOperationRequest | runtime.FlatBody<CommandOperationRequest, 'commandRequest'>, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<Command200Response> {

package/src/boat-helpers.ts

@@ -1,6 +1,6 @@
 
 import { BoatApi } from './apis/BoatApi';
-import type { Sandbox, SandboxEvent, DesktopResponse, PromptRequest, PromptRun } from './models';
+import type { Sandbox, SandboxEvent, DesktopResponse, PromptRequest, PromptRun, CommandStreamFrame } from './models';
 
 export type WaitOptions = {
   timeoutMs?: number;
@@ -185,3 +185,77 @@ export async function writeText(api: BoatApi, sandboxId: string, path: string, c
 export async function execCommand(api: BoatApi, sandboxId: string, command: string, cwd?: string, timeoutSeconds = 30) {
   return api.command({ sandboxId, commandRequest: { command, cwd, timeoutSeconds } });
 }
+
+/** One line of a streamed command, as sent (an `exit` frame also carries e.g. `signal`, `oomKilled`). */
+export type CommandFrame = CommandStreamFrame & Record<string, unknown>;
+
+export type StreamCommandOptions = {
+  cwd?: string;
+  timeoutSeconds?: number;
+  signal?: AbortSignal;
+};
+
+// A refusal that provably never ran the command (the sandbox is still restoring
+// its disk, `retryable: true` before `started`) is retried for this long.
+const STREAM_RETRY_MS = 60_000;
+
+async function* ndjsonFrames(response: Response): AsyncGenerator<CommandFrame> {
+  if (!response.body) throw new Error('The command stream has no body');
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffered = '';
+  let done = false;
+  try {
+    while (!done) {
+      const chunk = await reader.read();
+      done = chunk.done;
+      buffered += done ? decoder.decode() : decoder.decode(chunk.value, { stream: true });
+      let newline = buffered.indexOf('\n');
+      while (newline !== -1) {
+        const line = buffered.slice(0, newline).trim();
+        buffered = buffered.slice(newline + 1);
+        if (line) yield JSON.parse(line);
+        newline = buffered.indexOf('\n');
+      }
+    }
+    if (buffered.trim()) yield JSON.parse(buffered);
+  } finally {
+    // The caller stopped early: drop the connection instead of reading the rest.
+    if (!done) await reader.cancel().catch(() => undefined);
+  }
+}
+
+/**
+ * Run a command and yield its output as the command writes it: `started`, then
+ * `stdout`/`stderr` chunks (`frame.data`), then exactly one `exit` (`exitCode`,
+ * `timedOut`, ...) or `error` (`error`, `message`).
+ *
+ * Safe to call right after `resume()`, without waiting: the API holds a command
+ * sent to a starting sandbox for up to 60 s instead of refusing it.
+ */
+export async function* streamCommand(
+  api: BoatApi,
+  sandboxId: string,
+  command: string,
+  options?: StreamCommandOptions,
+): AsyncGenerator<CommandFrame> {
+  const deadline = Date.now() + STREAM_RETRY_MS;
+  for (;;) {
+    const response = await api.commandRaw(
+      { sandboxId, commandRequest: { command, cwd: options?.cwd, timeoutSeconds: options?.timeoutSeconds, stream: true } },
+      { signal: options?.signal },
+    );
+    let started = false;
+    let retry = false;
+    for await (const frame of ndjsonFrames(response.raw)) {
+      started = started || frame.type === 'started';
+      if (!started && frame.type === 'error' && frame.retryable === true && Date.now() < deadline) {
+        retry = true;
+        break;
+      }
+      yield frame;
+    }
+    if (!retry) return;
+    await delay(1_000);
+  }
+}

package/src/models/CommandRequest.ts

@@ -43,6 +43,12 @@ export interface CommandRequest {
      * @memberof CommandRequest
      */
     detached?: boolean;
+    /**
+     * Stream the output as the command writes it: the response is newline-delimited JSON (application/x-ndjson), one CommandStreamFrame per line. Ignored with detached.
+     * @type {boolean}
+     * @memberof CommandRequest
+     */
+    stream?: boolean;
 }
 
 /**
@@ -67,6 +73,7 @@ export function CommandRequestFromJSONTyped(json: any, ignoreDiscriminator: bool
         'cwd': json['cwd'] == null ? undefined : json['cwd'],
         'timeoutSeconds': json['timeoutSeconds'] == null ? undefined : json['timeoutSeconds'],
         'detached': json['detached'] == null ? undefined : json['detached'],
+        'stream': json['stream'] == null ? undefined : json['stream'],
     };
 }
 
@@ -85,6 +92,7 @@ export function CommandRequestToJSONTyped(value?: CommandRequest | null, ignoreD
         'cwd': value['cwd'],
         'timeoutSeconds': value['timeoutSeconds'],
         'detached': value['detached'],
+        'stream': value['stream'],
     };
 }
 

package/src/models/CommandStreamFrame.ts

@@ -0,0 +1,136 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Boat Public API v1
+ * Public JSON API for creating, operating, prompting, observing, and exposing sandboxes from backend services, CI jobs, hosted workers, and Boat automation products.  The v1 reference intentionally documents the developer integration surface only. Dashboard billing actions are not part of v1. 
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+import { mapValues } from '../runtime';
+/**
+ * One line of a streamed command. `started` first, then `stdout`/`stderr` chunks, then exactly one `exit` (the synchronous result, without stdout/stderr) or `error`.
+ * @export
+ * @interface CommandStreamFrame
+ */
+export interface CommandStreamFrame {
+    /**
+     * 
+     * @type {CommandStreamFrameTypeEnum}
+     * @memberof CommandStreamFrame
+     */
+    type: CommandStreamFrameTypeEnum;
+    /**
+     * stdout/stderr: the chunk of output, UTF-8.
+     * @type {string}
+     * @memberof CommandStreamFrame
+     */
+    data?: string;
+    /**
+     * 
+     * @type {number}
+     * @memberof CommandStreamFrame
+     */
+    exitCode?: number | null;
+    /**
+     * 
+     * @type {boolean}
+     * @memberof CommandStreamFrame
+     */
+    success?: boolean;
+    /**
+     * 
+     * @type {boolean}
+     * @memberof CommandStreamFrame
+     */
+    timedOut?: boolean;
+    /**
+     * 
+     * @type {string}
+     * @memberof CommandStreamFrame
+     */
+    error?: string;
+    /**
+     * 
+     * @type {string}
+     * @memberof CommandStreamFrame
+     */
+    message?: string;
+    /**
+     * error: true when the command provably never ran (the sandbox is still restoring its disk), so sending it again is safe.
+     * @type {boolean}
+     * @memberof CommandStreamFrame
+     */
+    retryable?: boolean;
+}
+
+
+/**
+ * @export
+ */
+export const CommandStreamFrameTypeEnum = {
+    Started: 'started',
+    Stdout: 'stdout',
+    Stderr: 'stderr',
+    Exit: 'exit',
+    Error: 'error'
+} as const;
+export type CommandStreamFrameTypeEnum = typeof CommandStreamFrameTypeEnum[keyof typeof CommandStreamFrameTypeEnum];
+
+
+/**
+ * Check if a given object implements the CommandStreamFrame interface.
+ */
+export function instanceOfCommandStreamFrame(value: object): value is CommandStreamFrame {
+    if (!('type' in value) || value['type'] === undefined) return false;
+    return true;
+}
+
+export function CommandStreamFrameFromJSON(json: any): CommandStreamFrame {
+    return CommandStreamFrameFromJSONTyped(json, false);
+}
+
+export function CommandStreamFrameFromJSONTyped(json: any, ignoreDiscriminator: boolean): CommandStreamFrame {
+    if (json == null) {
+        return json;
+    }
+    return {
+        
+        'type': json['type'],
+        'data': json['data'] == null ? undefined : json['data'],
+        'exitCode': json['exitCode'] == null ? undefined : json['exitCode'],
+        'success': json['success'] == null ? undefined : json['success'],
+        'timedOut': json['timedOut'] == null ? undefined : json['timedOut'],
+        'error': json['error'] == null ? undefined : json['error'],
+        'message': json['message'] == null ? undefined : json['message'],
+        'retryable': json['retryable'] == null ? undefined : json['retryable'],
+    };
+}
+
+export function CommandStreamFrameToJSON(json: any): CommandStreamFrame {
+    return CommandStreamFrameToJSONTyped(json, false);
+}
+
+export function CommandStreamFrameToJSONTyped(value?: CommandStreamFrame | null, ignoreDiscriminator: boolean = false): any {
+    if (value == null) {
+        return value;
+    }
+
+    return {
+        
+        'type': value['type'],
+        'data': value['data'],
+        'exitCode': value['exitCode'],
+        'success': value['success'],
+        'timedOut': value['timedOut'],
+        'error': value['error'],
+        'message': value['message'],
+        'retryable': value['retryable'],
+    };
+}
+

package/src/models/CreateSandboxRequest.ts

@@ -55,6 +55,12 @@ export interface CreateSandboxRequest {
      * @memberof CreateSandboxRequest
      */
     snapshots?: boolean;
+    /**
+     * Pass `true` to get a sandbox only if a machine of this type is ready right now. The call answers within about 1.5 s: either the usual `202` with the sandbox, or `503` `no_ready_machine` with nothing created, billed, or counted against your start limits, so you can retry or fall back at once. Without it, a create waits for a machine to be built when none is ready. Not combinable with `from`.
+     * @type {boolean}
+     * @memberof CreateSandboxRequest
+     */
+    failFast?: boolean;
     /**
      * Shell script that runs on the sandbox after it is ready. Ready means "ready to accept the user", not "setup done": the script starts in the background once provisioning completes and never blocks the sandbox becoming usable. It runs as the sandbox user via `bash`, with the sandbox's environment applied, and its output goes to a log file on the sandbox. Observe the outcome as `setupStatus` (pending/running/done/failed) and `setupError` on the sandbox. Rejected with a 400 `invalid_setup_script` error when it is not a string or exceeds 64KB.
      * @type {string}
@@ -116,6 +122,7 @@ export function CreateSandboxRequestFromJSONTyped(json: any, ignoreDiscriminator
         'environment': json['environment'] == null ? undefined : json['environment'],
         'noEnv': json['noEnv'] == null ? undefined : json['noEnv'],
         'snapshots': json['snapshots'] == null ? undefined : json['snapshots'],
+        'failFast': json['failFast'] == null ? undefined : json['failFast'],
         'setupScript': json['setupScript'] == null ? undefined : json['setupScript'],
         'org': json['org'] == null ? undefined : json['org'],
         'teamId': json['teamId'] == null ? undefined : json['teamId'],
@@ -140,6 +147,7 @@ export function CreateSandboxRequestToJSONTyped(value?: CreateSandboxRequest | n
         'environment': value['environment'],
         'noEnv': value['noEnv'],
         'snapshots': value['snapshots'],
+        'failFast': value['failFast'],
         'setupScript': value['setupScript'],
         'org': value['org'],
         'teamId': value['teamId'],

package/src/models/index.ts

@@ -22,6 +22,7 @@ export * from './CommandRequest';
 export * from './CommandResponse';
 export * from './CommandStartedResponse';
 export * from './CommandStatusResponse';
+export * from './CommandStreamFrame';
 export * from './CompletionEvent';
 export * from './Conversation';
 export * from './ConversationsResponse';