@skrr-ai/cli 0.1.25 → 0.1.27

package/dist/lib/dedicated-terminal.d.ts

@@ -0,0 +1,89 @@
+import { io, type Socket } from 'socket.io-client';
+/**
+ * A real pseudo-terminal on a Dedicated Runtime, from a local terminal.
+ *
+ * This is the same lane the web lease card's "Open terminal" drives — the
+ * human terminal vocabulary (`HARNESS_TERMINAL_EVENTS`) relayed by `EngineTerminal/handlers.js` to the
+ * daemon's `TerminalSessionManager`, which runs an interactive login bash as
+ * `skrr-workload` through the PTY relay. Nothing here is a second way in: the
+ * relay admits a Dedicated Runtime terminal only when agent dispatch to that
+ * lease would be admitted (current generation, running, healthy volume).
+ *
+ * It is deliberately NOT a loop over `exec`. `exec` is one command with no TTY;
+ * a shell built from it would look like a shell and behave like none — no job
+ * control, no prompts, no state between lines. This is the honest version.
+ */
+/** Ctrl-] — telnet's escape. Ctrl-C and Ctrl-D belong to the remote shell. */
+export declare const TERMINAL_DETACH_BYTE = 29;
+/** How long the machine has to answer a start before the CLI gives up. */
+export declare const TERMINAL_START_TIMEOUT_MS = 30000;
+/**
+ * When to type an initial command: once the shell has printed something and
+ * then gone quiet, or after a fallback — the same heuristic the web terminal
+ * uses for its Sign in menu, because both are waiting on the same login bash.
+ */
+export declare const TERMINAL_READY_QUIET_MS = 300;
+export declare const TERMINAL_READY_FALLBACK_MS = 2500;
+export interface TerminalOutputFrame {
+    sessionId?: string;
+    daemonId?: string;
+    type?: 'stdout' | 'stderr' | 'exit' | 'error' | 'info';
+    data?: string;
+    dataBase64?: string;
+    encoding?: 'utf8' | 'base64';
+    exitCode?: number | null;
+    signal?: string | null;
+}
+export interface TerminalStartAck {
+    sessionId?: string;
+    daemonId?: string;
+    ok?: boolean;
+    error?: string;
+    code?: string;
+}
+/** Bytes of one output frame, without splitting a UTF-8 or ANSI sequence. */
+export declare function decodeTerminalFrame(frame: TerminalOutputFrame): Buffer;
+/**
+ * Types `command` once, when the shell looks ready.
+ *
+ * Returned as an object with injectable timers so the readiness rule is tested
+ * without a PTY. `onOutput` re-arms the quiet timer; the fallback fires
+ * regardless, because a shell with a silent prompt must not wait forever.
+ */
+export declare function createInitialCommandTyper(options: {
+    command: string;
+    send: (data: string) => void;
+    quietMs?: number;
+    fallbackMs?: number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}): {
+    start(): void;
+    onOutput(): void;
+    cancel(): void;
+    readonly typed: boolean;
+};
+export declare class DedicatedTerminalError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/** A start refusal in words that say what to do, keyed by the relay's codes. */
+export declare function describeTerminalStartRefusal(ack: TerminalStartAck): string;
+export interface DedicatedTerminalOptions {
+    baseURL: string;
+    token: string;
+    runtimeId: string;
+    daemonId: string;
+    cwd?: string;
+    initialCommand?: string;
+    input: NodeJS.ReadStream;
+    output: NodeJS.WriteStream;
+    errorOutput: NodeJS.WritableStream;
+    /** Injected for tests. */
+    connect?: (url: string, opts: Parameters<typeof io>[1]) => Socket;
+}
+/**
+ * Run one interactive session to completion. Resolves with the exit code the
+ * CLI should exit with: the shell's own, 0 for a detach, 1 for a lost session.
+ */
+export declare function runDedicatedTerminal(options: DedicatedTerminalOptions): Promise<number>;

package/dist/lib/dedicated-terminal.js

@@ -0,0 +1,275 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DedicatedTerminalError = exports.TERMINAL_READY_FALLBACK_MS = exports.TERMINAL_READY_QUIET_MS = exports.TERMINAL_START_TIMEOUT_MS = exports.TERMINAL_DETACH_BYTE = void 0;
+exports.decodeTerminalFrame = decodeTerminalFrame;
+exports.createInitialCommandTyper = createInitialCommandTyper;
+exports.describeTerminalStartRefusal = describeTerminalStartRefusal;
+exports.runDedicatedTerminal = runDedicatedTerminal;
+const node_crypto_1 = require("node:crypto");
+const socket_io_client_1 = require("socket.io-client");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const agentic_stream_1 = require("./agentic-stream");
+/**
+ * A real pseudo-terminal on a Dedicated Runtime, from a local terminal.
+ *
+ * This is the same lane the web lease card's "Open terminal" drives — the
+ * human terminal vocabulary (`HARNESS_TERMINAL_EVENTS`) relayed by `EngineTerminal/handlers.js` to the
+ * daemon's `TerminalSessionManager`, which runs an interactive login bash as
+ * `skrr-workload` through the PTY relay. Nothing here is a second way in: the
+ * relay admits a Dedicated Runtime terminal only when agent dispatch to that
+ * lease would be admitted (current generation, running, healthy volume).
+ *
+ * It is deliberately NOT a loop over `exec`. `exec` is one command with no TTY;
+ * a shell built from it would look like a shell and behave like none — no job
+ * control, no prompts, no state between lines. This is the honest version.
+ */
+/** Ctrl-] — telnet's escape. Ctrl-C and Ctrl-D belong to the remote shell. */
+exports.TERMINAL_DETACH_BYTE = 0x1d;
+/** How long the machine has to answer a start before the CLI gives up. */
+exports.TERMINAL_START_TIMEOUT_MS = 30_000;
+/**
+ * When to type an initial command: once the shell has printed something and
+ * then gone quiet, or after a fallback — the same heuristic the web terminal
+ * uses for its Sign in menu, because both are waiting on the same login bash.
+ */
+exports.TERMINAL_READY_QUIET_MS = 300;
+exports.TERMINAL_READY_FALLBACK_MS = 2_500;
+/** Bytes of one output frame, without splitting a UTF-8 or ANSI sequence. */
+function decodeTerminalFrame(frame) {
+    const encoded = frame.dataBase64 ?? (frame.encoding === 'base64' ? frame.data : undefined);
+    if (typeof encoded === 'string') {
+        return Buffer.from(encoded, 'base64');
+    }
+    return Buffer.from(typeof frame.data === 'string' ? frame.data : '', 'utf8');
+}
+/**
+ * Types `command` once, when the shell looks ready.
+ *
+ * Returned as an object with injectable timers so the readiness rule is tested
+ * without a PTY. `onOutput` re-arms the quiet timer; the fallback fires
+ * regardless, because a shell with a silent prompt must not wait forever.
+ */
+function createInitialCommandTyper(options) {
+    const setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+    const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+    const quietMs = options.quietMs ?? exports.TERMINAL_READY_QUIET_MS;
+    const fallbackMs = options.fallbackMs ?? exports.TERMINAL_READY_FALLBACK_MS;
+    let typed = false;
+    let quietTimer = null;
+    let fallbackTimer = null;
+    const type = () => {
+        if (typed)
+            return;
+        typed = true;
+        if (quietTimer)
+            clearTimer(quietTimer);
+        if (fallbackTimer)
+            clearTimer(fallbackTimer);
+        options.send(`${options.command}\r`);
+    };
+    return {
+        start() {
+            if (typed || fallbackTimer)
+                return;
+            fallbackTimer = setTimer(type, fallbackMs);
+        },
+        onOutput() {
+            if (typed)
+                return;
+            if (quietTimer)
+                clearTimer(quietTimer);
+            quietTimer = setTimer(type, quietMs);
+        },
+        cancel() {
+            typed = true;
+            if (quietTimer)
+                clearTimer(quietTimer);
+            if (fallbackTimer)
+                clearTimer(fallbackTimer);
+        },
+        get typed() {
+            return typed;
+        },
+    };
+}
+class DedicatedTerminalError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'DedicatedTerminalError';
+        this.code = code;
+    }
+}
+exports.DedicatedTerminalError = DedicatedTerminalError;
+/** A start refusal in words that say what to do, keyed by the relay's codes. */
+function describeTerminalStartRefusal(ack) {
+    const code = ack.code || '';
+    if (code === 'DEDICATED_RUNTIME_NOT_ASSIGNABLE') {
+        return ('The machine is not ready to take a terminal (it must be running with a healthy workspace). ' +
+            'Check it with `skrr machines dedicated show <lease-id>`.');
+    }
+    if (code === 'DEDICATED_RUNTIME_GENERATION_STALE') {
+        return 'The machine was replaced since its daemon registered. Wait a minute and try again.';
+    }
+    if (code === 'not_found' || code === 'offline') {
+        return 'The machine’s daemon is not connected. Wait for it to come online and try again.';
+    }
+    return ack.error ? `The terminal did not start: ${ack.error}` : 'The terminal did not start.';
+}
+/**
+ * Run one interactive session to completion. Resolves with the exit code the
+ * CLI should exit with: the shell's own, 0 for a detach, 1 for a lost session.
+ */
+function runDedicatedTerminal(options) {
+    const events = data_provider_1.HARNESS_TERMINAL_EVENTS;
+    const sessionId = (0, node_crypto_1.randomUUID)();
+    const connect = options.connect ?? socket_io_client_1.io;
+    const { input, output, errorOutput } = options;
+    return new Promise((resolve, reject) => {
+        let started = false;
+        let finished = false;
+        let rawMode = false;
+        const socket = connect((0, agentic_stream_1.toWebSocketOrigin)(options.baseURL), {
+            path: '/ws/agentic',
+            auth: {
+                token: options.token,
+                ...(0, data_provider_1.getClientIdentityAuth)(),
+                clientPlatform: 'cli',
+                clientOs: process.platform === 'darwin' ? 'macos' : process.platform,
+            },
+            transports: ['websocket'],
+            // A reconnect cannot resume a PTY: the relay forgets the session with the
+            // socket, and silently opening a NEW shell would drop the user into a
+            // different process tree mid-command. Say it ended instead.
+            reconnection: false,
+        });
+        const typer = options.initialCommand
+            ? createInitialCommandTyper({
+                command: options.initialCommand,
+                send: (data) => socket.emit(events.input, { sessionId, data }),
+            })
+            : null;
+        const size = () => ({
+            cols: Math.max(2, Math.min(1000, output.columns || 80)),
+            rows: Math.max(1, Math.min(1000, output.rows || 24)),
+        });
+        const onResize = () => {
+            if (started)
+                socket.emit(events.resize, { sessionId, ...size() });
+        };
+        const onInput = (chunk) => {
+            const buffer = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+            const detachAt = buffer.indexOf(exports.TERMINAL_DETACH_BYTE);
+            if (detachAt >= 0) {
+                if (detachAt > 0) {
+                    socket.emit(events.input, {
+                        sessionId,
+                        data: buffer.subarray(0, detachAt).toString('utf8'),
+                    });
+                }
+                errorOutput.write('\r\n[closed the terminal]\r\n');
+                finish(0, true);
+                return;
+            }
+            socket.emit(events.input, { sessionId, data: buffer.toString('utf8') });
+        };
+        const onSignal = () => finish(130, true);
+        const startTimer = setTimeout(() => {
+            fail(new DedicatedTerminalError('The machine did not answer the terminal start in time. Its daemon may be busy or offline.', 'TERMINAL_START_TIMEOUT'));
+        }, exports.TERMINAL_START_TIMEOUT_MS);
+        function restoreTty() {
+            input.off('data', onInput);
+            output.off('resize', onResize);
+            process.off('SIGTERM', onSignal);
+            process.off('SIGHUP', onSignal);
+            if (rawMode && typeof input.setRawMode === 'function') {
+                input.setRawMode(false);
+                rawMode = false;
+            }
+            input.pause();
+        }
+        function finish(code, stopRemote) {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(startTimer);
+            typer?.cancel();
+            restoreTty();
+            if (stopRemote && started)
+                socket.emit(events.stop, { sessionId });
+            socket.disconnect();
+            resolve(code);
+        }
+        function fail(error) {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(startTimer);
+            typer?.cancel();
+            restoreTty();
+            socket.disconnect();
+            reject(error);
+        }
+        socket.on('connect_error', (err) => {
+            fail(new DedicatedTerminalError(`Could not connect to skrr: ${err.message}`, err.data?.code || 'TERMINAL_CONNECT_FAILED'));
+        });
+        socket.on('connect', () => {
+            socket.emit(events.start, {
+                runtimeId: options.runtimeId,
+                sessionId,
+                ...(options.cwd ? { cwd: options.cwd } : {}),
+                ...size(),
+            });
+        });
+        socket.on(events.startAck, (ack) => {
+            if (!ack || ack.sessionId !== sessionId || started || finished)
+                return;
+            if (ack.daemonId && ack.daemonId !== options.daemonId)
+                return;
+            if (!ack.ok) {
+                fail(new DedicatedTerminalError(describeTerminalStartRefusal(ack), ack.code || 'TERMINAL_START_REFUSED'));
+                return;
+            }
+            started = true;
+            clearTimeout(startTimer);
+            if (typeof input.setRawMode === 'function') {
+                input.setRawMode(true);
+                rawMode = true;
+            }
+            input.resume();
+            input.on('data', onInput);
+            output.on('resize', onResize);
+            process.on('SIGTERM', onSignal);
+            process.on('SIGHUP', onSignal);
+            typer?.start();
+        });
+        socket.on(events.output, (frame) => {
+            if (!frame || frame.sessionId !== sessionId || finished)
+                return;
+            if (frame.daemonId && frame.daemonId !== options.daemonId)
+                return;
+            if (frame.type === 'exit') {
+                finish(typeof frame.exitCode === 'number' ? frame.exitCode : 0, false);
+                return;
+            }
+            if (frame.type === 'error' || frame.type === 'info') {
+                const text = decodeTerminalFrame(frame).toString('utf8');
+                if (text)
+                    errorOutput.write(`\r\n[${frame.type}] ${text}\r\n`);
+                return;
+            }
+            output.write(decodeTerminalFrame(frame));
+            typer?.onOutput();
+        });
+        socket.on('disconnect', () => {
+            if (finished)
+                return;
+            if (!started) {
+                fail(new DedicatedTerminalError('The connection to skrr closed before the terminal started.', 'TERMINAL_DISCONNECTED'));
+                return;
+            }
+            errorOutput.write('\r\n[lost the connection to skrr; the shell on the machine has ended]\r\n');
+            finish(1, false);
+        });
+    });
+}

package/dist/lib/dedicated-wait.d.ts

@@ -0,0 +1,72 @@
+import { type DedicatedLease, type DedicatedRuntimeScope } from './dedicated-machines';
+/**
+ * What a lifecycle command is waiting FOR, which is not always a state.
+ *
+ * `start`, `stop` and `destroy` settle into a state. `snapshot` and `grow` do
+ * not: a snapshot returns the lease to whatever state it left, and a grow never
+ * leaves it at all. For those the evidence is a field — a newer `lastBackupAt`,
+ * a larger `storageGb` — and waiting on the state alone would report success
+ * the instant a snapshot that failed returned the lease to `ready`.
+ */
+export type DedicatedWaitGoal = {
+    kind: 'running';
+} | {
+    kind: 'stopped';
+} | {
+    kind: 'destroyed';
+} | {
+    kind: 'snapshot';
+    previousBackupAt: string | null;
+} | {
+    kind: 'grown';
+    storageGb: number;
+};
+export type DedicatedWaitVerdict = {
+    status: 'done';
+} | {
+    status: 'failed';
+    reason: string;
+} | {
+    status: 'pending';
+    progress: string;
+};
+/**
+ * Has this lease reached the goal, failed to, or is it still on its way?
+ *
+ * Pure, so every branch is pinned without a server. "Failed" is reserved for a
+ * reading that cannot turn into the goal without someone acting again; anything
+ * that might still settle is `pending`, and the caller's timeout decides how long
+ * that is worth watching.
+ */
+export declare function evaluateDedicatedWait(goal: DedicatedWaitGoal, lease: DedicatedLease | undefined | null): DedicatedWaitVerdict;
+/**
+ * The CLI stopped watching. The MACHINE did not stop.
+ *
+ * Distinct from a failure on purpose: the operation is still running
+ * server-side, and the natural wrong move after "timed out" is to issue the
+ * action again — or create a second machine — while the first is still billing.
+ */
+export declare class DedicatedWaitTimeoutError extends Error {
+    readonly leaseId: string;
+    readonly lastProgress: string;
+    constructor(leaseId: string, lastProgress: string);
+}
+export declare class DedicatedWaitFailedError extends Error {
+    readonly leaseId: string;
+    readonly lease: DedicatedLease | undefined;
+    constructor(leaseId: string, reason: string, lease?: DedicatedLease);
+}
+/** Exit code for "stopped watching, still in progress" — `timeout(1)` uses 124. */
+export declare const DEDICATED_WAIT_TIMEOUT_EXIT = 124;
+export declare const DEDICATED_WAIT_DEFAULT_TIMEOUT_MS: number;
+export declare const DEDICATED_WAIT_DEFAULT_INTERVAL_MS: number;
+export declare const DEDICATED_WAIT_MAX_READ_FAILURES = 3;
+export declare function waitForDedicatedLease(leaseId: string, goal: DedicatedWaitGoal, options?: DedicatedRuntimeScope & {
+    initial?: DedicatedLease;
+    intervalMs?: number;
+    timeoutMs?: number;
+    onProgress?: (progress: string) => void;
+    fetchLease?: (id: string, scope: DedicatedRuntimeScope) => Promise<DedicatedLease | undefined>;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}): Promise<DedicatedLease>;

package/dist/lib/dedicated-wait.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEDICATED_WAIT_MAX_READ_FAILURES = exports.DEDICATED_WAIT_DEFAULT_INTERVAL_MS = exports.DEDICATED_WAIT_DEFAULT_TIMEOUT_MS = exports.DEDICATED_WAIT_TIMEOUT_EXIT = exports.DedicatedWaitFailedError = exports.DedicatedWaitTimeoutError = void 0;
+exports.evaluateDedicatedWait = evaluateDedicatedWait;
+exports.waitForDedicatedLease = waitForDedicatedLease;
+const dedicated_machines_1 = require("./dedicated-machines");
+const RUNNING_STATES = new Set(['ready', 'active', 'idle']);
+/** Terminal for the lease itself, so no goal but `destroyed` can still be reached. */
+const DEAD_STATES = new Set(['failed', 'lost', 'terminated']);
+function backupIsNewer(current, previous) {
+    if (!current)
+        return false;
+    if (!previous)
+        return true;
+    const a = Date.parse(current);
+    const b = Date.parse(previous);
+    return Number.isFinite(a) && Number.isFinite(b) ? a > b : current !== previous;
+}
+function progressOf(lease) {
+    const state = (0, dedicated_machines_1.dedicatedLeaseState)(lease);
+    if (state === 'recovering') {
+        // `recovering` is where a failed provision or action lands, retried with
+        // backoff. It can settle — or never, which is why destroy is allowed from it.
+        return 'recovering (the platform is retrying; destroy is available if it never settles)';
+    }
+    return lease.stateReason ? `${state} (${lease.stateReason})` : state;
+}
+/**
+ * Has this lease reached the goal, failed to, or is it still on its way?
+ *
+ * Pure, so every branch is pinned without a server. "Failed" is reserved for a
+ * reading that cannot turn into the goal without someone acting again; anything
+ * that might still settle is `pending`, and the caller's timeout decides how long
+ * that is worth watching.
+ */
+function evaluateDedicatedWait(goal, lease) {
+    if (!lease) {
+        return { status: 'failed', reason: 'the lease is no longer visible' };
+    }
+    const state = (0, dedicated_machines_1.dedicatedLeaseState)(lease);
+    switch (goal.kind) {
+        case 'running': {
+            if (RUNNING_STATES.has(state))
+                return { status: 'done' };
+            if (DEAD_STATES.has(state) || state === 'archived' || state === 'terminating') {
+                return { status: 'failed', reason: `the machine is ${state}` };
+            }
+            // Every path to `running` leaves `stopped` before the 202 comes back, so
+            // reading it again means the start or restart rolled back.
+            if (state === 'stopped') {
+                return { status: 'failed', reason: 'the machine went back to stopped' };
+            }
+            return { status: 'pending', progress: progressOf(lease) };
+        }
+        case 'stopped': {
+            if (state === 'stopped')
+                return { status: 'done' };
+            if (DEAD_STATES.has(state) || state === 'archived') {
+                return { status: 'failed', reason: `the machine is ${state}` };
+            }
+            if (RUNNING_STATES.has(state)) {
+                return {
+                    status: 'failed',
+                    reason: `the machine is ${state} again; the stop did not complete`,
+                };
+            }
+            return { status: 'pending', progress: progressOf(lease) };
+        }
+        case 'destroyed': {
+            if (state === 'terminated' || state === 'archived')
+                return { status: 'done' };
+            if (state === 'failed' || state === 'lost') {
+                return { status: 'failed', reason: `the machine is ${state}` };
+            }
+            return { status: 'pending', progress: progressOf(lease) };
+        }
+        case 'snapshot': {
+            if (backupIsNewer(lease.storage?.lastBackupAt, goal.previousBackupAt)) {
+                return { status: 'done' };
+            }
+            if (DEAD_STATES.has(state) || state === 'archived') {
+                return { status: 'failed', reason: `the machine is ${state}` };
+            }
+            if (state === 'snapshotting' || state === 'recovering') {
+                return { status: 'pending', progress: progressOf(lease) };
+            }
+            return {
+                status: 'failed',
+                reason: `the snapshot ended (${state}) without recording a new recovery point`,
+            };
+        }
+        case 'grown': {
+            const size = lease.resources?.storageGb;
+            if (typeof size === 'number' && size >= goal.storageGb)
+                return { status: 'done' };
+            if (DEAD_STATES.has(state) || state === 'archived') {
+                return { status: 'failed', reason: `the machine is ${state}` };
+            }
+            return {
+                status: 'pending',
+                progress: `${progressOf(lease)} · workspace ${size ?? '?'} → ${goal.storageGb} GiB`,
+            };
+        }
+        default:
+            return { status: 'failed', reason: 'unknown wait goal' };
+    }
+}
+/**
+ * The CLI stopped watching. The MACHINE did not stop.
+ *
+ * Distinct from a failure on purpose: the operation is still running
+ * server-side, and the natural wrong move after "timed out" is to issue the
+ * action again — or create a second machine — while the first is still billing.
+ */
+class DedicatedWaitTimeoutError extends Error {
+    leaseId;
+    lastProgress;
+    constructor(leaseId, lastProgress) {
+        super(`Stopped waiting for ${leaseId}` +
+            (lastProgress ? ` — it is still ${lastProgress}.` : '.') +
+            ' Nothing was cancelled: the operation continues server-side. ' +
+            `Check it with \`skrr machines dedicated show ${leaseId}\`.`);
+        this.name = 'DedicatedWaitTimeoutError';
+        this.leaseId = leaseId;
+        this.lastProgress = lastProgress;
+    }
+}
+exports.DedicatedWaitTimeoutError = DedicatedWaitTimeoutError;
+class DedicatedWaitFailedError extends Error {
+    leaseId;
+    lease;
+    constructor(leaseId, reason, lease) {
+        super(`${leaseId}: ${reason}.`);
+        this.name = 'DedicatedWaitFailedError';
+        this.leaseId = leaseId;
+        this.lease = lease;
+    }
+}
+exports.DedicatedWaitFailedError = DedicatedWaitFailedError;
+/** Exit code for "stopped watching, still in progress" — `timeout(1)` uses 124. */
+exports.DEDICATED_WAIT_TIMEOUT_EXIT = 124;
+exports.DEDICATED_WAIT_DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
+exports.DEDICATED_WAIT_DEFAULT_INTERVAL_MS = 5 * 1000;
+exports.DEDICATED_WAIT_MAX_READ_FAILURES = 3;
+async function waitForDedicatedLease(leaseId, goal, options = {}) {
+    const intervalMs = options.intervalMs ?? exports.DEDICATED_WAIT_DEFAULT_INTERVAL_MS;
+    const timeoutMs = options.timeoutMs ?? exports.DEDICATED_WAIT_DEFAULT_TIMEOUT_MS;
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const fetchLease = options.fetchLease ??
+        (async (id, scope) => (await (0, dedicated_machines_1.getDedicatedRuntime)(id, scope)).lease);
+    const scope = { workspaceId: options.workspaceId };
+    const startedAt = now();
+    let lease = options.initial;
+    let lastProgress = '';
+    let consecutiveReadFailures = 0;
+    // One failed read is a blip, not an outcome: the operation is server-side and
+    // does not care that a poll 502'd. Three in a row is a real answer.
+    const read = async () => {
+        while (true) {
+            try {
+                const next = await fetchLease(leaseId, scope);
+                consecutiveReadFailures = 0;
+                return next;
+            }
+            catch (err) {
+                consecutiveReadFailures += 1;
+                if (consecutiveReadFailures >= exports.DEDICATED_WAIT_MAX_READ_FAILURES)
+                    throw err;
+                await sleep(intervalMs);
+            }
+        }
+    };
+    // The action's own response is already a reading; checking it first means a
+    // goal it has already reached (a re-run stop on a stopped machine) returns
+    // without one extra request and one interval.
+    if (!lease)
+        lease = await read();
+    while (true) {
+        const verdict = evaluateDedicatedWait(goal, lease);
+        if (verdict.status === 'done')
+            return lease;
+        if (verdict.status === 'failed')
+            throw new DedicatedWaitFailedError(leaseId, verdict.reason, lease);
+        if (verdict.progress !== lastProgress) {
+            lastProgress = verdict.progress;
+            options.onProgress?.(verdict.progress);
+        }
+        if (now() - startedAt >= timeoutMs) {
+            throw new DedicatedWaitTimeoutError(leaseId, lastProgress);
+        }
+        await sleep(intervalMs);
+        lease = await read();
+    }
+}

package/dist/lib/edge-error-page.d.ts

@@ -0,0 +1,49 @@
+/**
+ * edge-error-page.ts — say what an HTML error page from the EDGE means, instead
+ * of printing it.
+ *
+ * Every API route answers in JSON. An HTML page in an error response therefore
+ * did not come from the API: it is CloudFront, its web application firewall, or
+ * a load balancer answering in the API's place. Printed as-is it is a screen of
+ * markup whose one useful line ("Request blocked", a request id) is buried, and
+ * treated as an API answer it is misleading in a specific way — a 403 reads as
+ * "you lack permission", and CloudFront's 504 page tells the reader to "try again
+ * later", which for a write that is still running repeats it.
+ *
+ * Both happened to `skrr machines dedicated exec` (OSK-8700, OSK-8705): a shell
+ * command containing `http://10.0.0.10/` came back as CloudFront's raw
+ * "403 ERROR / Request blocked" page, and a command running past 60 seconds as
+ * its raw 504 page while it kept running on the machine.
+ *
+ * General on purpose: nothing here knows which command asked.
+ */
+export type EdgeErrorCode = 'EDGE_REQUEST_BLOCKED' | 'EDGE_GATEWAY_TIMEOUT' | 'EDGE_ORIGIN_UNAVAILABLE' | 'EDGE_ERROR_PAGE';
+export interface EdgeErrorPage {
+    status: number;
+    code: EdgeErrorCode;
+    /** The edge's own id for the request (CloudFront prints one), when the page carries it. */
+    requestId?: string;
+    message: string;
+    /** Whether sending the identical request again can help. */
+    retryable: boolean;
+}
+/**
+ * True when an error response body is an HTML page rather than an API answer.
+ *
+ * A JSON body is never a page, whatever its text says: an API refusal that
+ * quotes "The request could not be satisfied" or an HTML fragment in its message
+ * must keep its own words (the base command's handler already gates on "no JSON
+ * body"; this makes every caller agree). The CloudFront wording counts only
+ * inside markup, never on its own.
+ */
+export declare function isHtmlErrorPage(body: string | null | undefined): boolean;
+/**
+ * Describe an HTML error page, or return null when the body is not one (a JSON
+ * refusal from the API must keep its own words).
+ */
+export declare function describeEdgeErrorPage(input: {
+    status: number | undefined;
+    body: string | null | undefined;
+    method?: string | null;
+    host?: string | null;
+}): EdgeErrorPage | null;