humanish 0.104.3 → 0.106.0

package/dist/subject/serve.d.ts

@@ -0,0 +1,39 @@
+import type { LabSubjectServe, LabSubjectState } from "../lab/types.js";
+import type { RunSubjectStateStepRecord } from "../run/bundle.js";
+import { type DetachedTimers } from "../substrates/detached.js";
+import type { Shell } from "../substrates/shell.js";
+import { type SubjectPhaseEvent } from "./steps.js";
+/**
+ * The longest runSubjectServePipeline can take with these budgets: the Node bootstrap and install
+ * with their one retry, the package-manager step, every seed step, the build and the readiness
+ * wait. Detached-step polling adds seconds on top.
+ */
+export declare function serveProvisioningBudgetMs(serve: LabSubjectServe, state: LabSubjectState | undefined): number;
+/**
+ * The provisioning pipeline the clone and local-tree routes share once SUBJECT_DIR is populated
+ * (by git clone, or by upload and extract): install, state before-build, build, state
+ * before-start, detached start, readiness probe, state after-ready.
+ *
+ * State steps run through the same detached primitive as serve steps (both are author-trusted)
+ * under the reserved `subject-state-<name>` label prefix, so a step name can never collide with
+ * subject-clone, subject-extract, install, build or start. after-ready steps complete before the
+ * caller opens the browser: the participant never drives a half-seeded subject, and seeding never
+ * eats the session budget.
+ */
+export declare function runSubjectServePipeline(shell: Shell, args: {
+    serve: LabSubjectServe;
+    /** Declared subject state (seed steps; external declaration is provenance-only). */
+    state?: LabSubjectState;
+    requestTimeoutMs: number;
+    /** Literal scrubber for known provisioned values, applied to log tails PRE-truncation. */
+    scrub: (text: string) => string;
+    /** Called the moment each state step finishes, success or failure. */
+    onStateStep?: (record: RunSubjectStateStepRecord) => void;
+    /** Called at each phase boundary (started/completed): install, build, serve start, ready,
+     *  and each subject.state seed-step group (one pair per group, never per step). */
+    onPhase?: (event: SubjectPhaseEvent) => void;
+    /** Called after every phase completes. The clone route re-resolves HEAD here; the
+     *  local-tree route omits this entirely (identity is the host-side archive digest, never
+     *  an in-sandbox git refresh, because the archive excludes .git). */
+    onPhaseComplete?: () => Promise<void>;
+} & DetachedTimers): Promise<void>;

package/dist/subject/serve.js

@@ -0,0 +1,249 @@
+// The serve pipeline the clone and local-tree subjects share once their source is in place.
+import { failureTail } from "../evidence/redaction.js";
+import { NODE_BOOTSTRAP_COMMAND, NODE_BOOTSTRAP_TIMEOUT_MS } from "./node-bootstrap.js";
+import { corepackCommandFor, needsNodeRuntime } from "./runtime.js";
+import { detachedTimersOf, probeUrl, readDetachedLog, runDetachedStep, startDetachedProcess, } from "../substrates/detached.js";
+import { DEFAULT_STATE_STEP_TIMEOUT_MS, runStateSteps } from "./state.js";
+import { emitPhaseCompleted, emitPhaseStarted, INSTALL_TIMEOUT_MS, isoNow, SUBJECT_DIR, } from "./steps.js";
+const BUILD_TIMEOUT_MS = 10 * 60_000;
+const DEFAULT_READY_TIMEOUT_MS = 180_000;
+/**
+ * Run a provisioning step and, when it fails with an exit code, run it once more (#602): a
+ * transient network error inside `npm install` is the common case. A timeout is not retried: its
+ * budget is already spent, and a second wait would double it. The retry runs under its own step
+ * name so both logs stay.
+ */
+async function runProvisioningStepWithOneRetry(shell, args) {
+    const first = await runDetachedStep(shell, {
+        name: args.name,
+        command: args.command,
+        cwd: args.cwd,
+        timeoutMs: args.timeoutMs,
+        requestTimeoutMs: args.requestTimeoutMs,
+        ...args.timers,
+    });
+    if (first.ok || first.timedOut)
+        return { ...first, attempts: 1 };
+    const retryStartedAt = args.now();
+    emitPhaseStarted(args.onPhase, args.now, args.retryPhase, `${args.retryMessage} (first attempt exited ${first.exitCode ?? "null"}; retrying once)`);
+    const second = await runDetachedStep(shell, {
+        name: `${args.name}-retry`,
+        command: args.command,
+        cwd: args.cwd,
+        timeoutMs: args.timeoutMs,
+        requestTimeoutMs: args.requestTimeoutMs,
+        ...args.timers,
+    });
+    emitPhaseCompleted(args.onPhase, args.now, retryStartedAt, args.retryPhase, second.ok, second.ok
+        ? `${args.retryMessage}: succeeded on the second attempt`
+        : `${args.retryMessage}: failed twice`);
+    return {
+        ...second,
+        attempts: 2,
+        ...(first.exitCode === undefined ? {} : { firstExitCode: first.exitCode }),
+    };
+}
+/**
+ * The longest runSubjectServePipeline can take with these budgets: the Node bootstrap and install
+ * with their one retry, the package-manager step, every seed step, the build and the readiness
+ * wait. Detached-step polling adds seconds on top.
+ */
+export function serveProvisioningBudgetMs(serve, state) {
+    const installMs = serve.installTimeoutMs ?? INSTALL_TIMEOUT_MS;
+    const commands = [serve.install, serve.build, serve.start];
+    const runtimeMs = needsNodeRuntime(commands)
+        ? 2 * NODE_BOOTSTRAP_TIMEOUT_MS + (corepackCommandFor(commands) === undefined ? 0 : installMs)
+        : 0;
+    const seedMs = (state?.seed ?? []).reduce((sum, step) => sum + (step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS), 0);
+    return (runtimeMs +
+        (serve.install === undefined ? 0 : 2 * installMs) +
+        seedMs +
+        (serve.build === undefined ? 0 : (serve.buildTimeoutMs ?? BUILD_TIMEOUT_MS)) +
+        (serve.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS));
+}
+/**
+ * The provisioning pipeline the clone and local-tree routes share once SUBJECT_DIR is populated
+ * (by git clone, or by upload and extract): install, state before-build, build, state
+ * before-start, detached start, readiness probe, state after-ready.
+ *
+ * State steps run through the same detached primitive as serve steps (both are author-trusted)
+ * under the reserved `subject-state-<name>` label prefix, so a step name can never collide with
+ * subject-clone, subject-extract, install, build or start. after-ready steps complete before the
+ * caller opens the browser: the participant never drives a half-seeded subject, and seeding never
+ * eats the session budget.
+ */
+export async function runSubjectServePipeline(shell, args) {
+    const timers = detachedTimersOf(args);
+    const now = args.now ?? Date.now;
+    const refresh = args.onPhaseComplete ?? (() => Promise.resolve());
+    const runState = (when) => runStateSteps(shell, when, {
+        ...(args.state === undefined ? {} : { state: args.state }),
+        requestTimeoutMs: args.requestTimeoutMs,
+        scrub: args.scrub,
+        ...(args.onStateStep === undefined ? {} : { onStateStep: args.onStateStep }),
+        ...(args.onPhase === undefined ? {} : { onPhase: args.onPhase }),
+        now,
+        timers,
+    });
+    const step = {
+        shell,
+        serve: args.serve,
+        requestTimeoutMs: args.requestTimeoutMs,
+        scrub: args.scrub,
+        onPhase: args.onPhase,
+        timers,
+        now,
+    };
+    await provideNodeRuntime(step);
+    if (args.serve.install) {
+        await installSubject(step, args.serve.install);
+        await refresh();
+    }
+    // before-build: after install, before build (builds that read seeded state, e.g. SSG).
+    // When no build is declared this simply precedes start: equivalent to before-start.
+    await runState("before-build");
+    await refresh();
+    if (args.serve.build) {
+        await buildSubject(step, args.serve.build);
+        await refresh();
+    }
+    // before-start (the default phase): migrations, SQL/file fixtures, an in-sandbox DB server
+    // (`sudo service postgresql start && pg_isready` is a bounded step; the daemon it forks is
+    // reclaimed by the sandbox lifecycle like everything else).
+    await runState("before-start");
+    await refresh();
+    await startSubject(step);
+    await waitForSubjectReady(step);
+    // after-ready: fixture loading through the RUNNING app (loopback curl from in-sandbox:
+    // steps are author-trusted provisioning, not actors, so no new URL policy surface). These
+    // complete before the caller opens the browser and the session timer starts.
+    await runState("after-ready");
+    await refresh();
+}
+/**
+ * Provide the runtime the pipeline needs before running it (#371). The stock desktop template
+ * ships python3 and curl but no Node. Probe first, so a template that ships its own Node pays
+ * nothing.
+ */
+async function provideNodeRuntime(step) {
+    const { shell, now } = step;
+    const serveCommands = [step.serve.install, step.serve.build, step.serve.start];
+    if (!needsNodeRuntime(serveCommands))
+        return;
+    const runtimeStartedAt = now();
+    emitPhaseStarted(step.onPhase, now, "runtime", "providing the Node runtime the serve pipeline needs");
+    const bootstrap = await runProvisioningStepWithOneRetry(shell, {
+        name: "subject-runtime-node",
+        command: NODE_BOOTSTRAP_COMMAND,
+        cwd: SUBJECT_DIR,
+        timeoutMs: NODE_BOOTSTRAP_TIMEOUT_MS,
+        requestTimeoutMs: step.requestTimeoutMs,
+        timers: step.timers,
+        retryPhase: "runtime-retry",
+        retryMessage: "Node runtime bootstrap",
+        onPhase: step.onPhase,
+        now,
+    });
+    let ok = bootstrap.ok;
+    const corepack = ok ? corepackCommandFor(serveCommands) : undefined;
+    if (corepack) {
+        const pm = await runDetachedStep(shell, {
+            name: "subject-runtime-pm",
+            command: corepack,
+            cwd: SUBJECT_DIR,
+            timeoutMs: step.serve.installTimeoutMs ?? INSTALL_TIMEOUT_MS,
+            requestTimeoutMs: step.requestTimeoutMs,
+            ...step.timers,
+        });
+        ok = pm.ok;
+    }
+    emitPhaseCompleted(step.onPhase, now, runtimeStartedAt, "runtime", ok, ok ? "Node runtime ready" : "could not provide a Node runtime");
+    if (!ok) {
+        throw new Error(`the subject's serve pipeline needs a Node runtime and this desktop template has none, and bootstrapping one failed${bootstrap.attempts === 2 ? " twice" : ""}: ${failureTail(step.scrub(bootstrap.logTail))}. Use execution.desktop.template with an image that ships Node, or change serve.install to a runtime the template provides.`);
+    }
+}
+/** serve.install, retried once on a non-zero exit. */
+async function installSubject(step, command) {
+    const { now } = step;
+    const installStartedAt = now();
+    emitPhaseStarted(step.onPhase, now, "install", "installing subject dependencies");
+    const install = await runProvisioningStepWithOneRetry(step.shell, {
+        name: "subject-install",
+        command,
+        cwd: SUBJECT_DIR,
+        timeoutMs: step.serve.installTimeoutMs ?? INSTALL_TIMEOUT_MS,
+        requestTimeoutMs: step.requestTimeoutMs,
+        timers: step.timers,
+        retryPhase: "install-retry",
+        retryMessage: "subject install",
+        onPhase: step.onPhase,
+        now,
+    });
+    emitPhaseCompleted(step.onPhase, now, installStartedAt, "install", install.ok, install.ok
+        ? install.attempts === 2
+            ? "subject dependencies installed (on the second attempt)"
+            : "subject dependencies installed"
+        : install.attempts === 2
+            ? "subject install failed twice"
+            : "subject install failed");
+    if (!install.ok) {
+        // Lead with the line a person can act on; npm's own trace follows it (#602).
+        const headline = install.timedOut
+            ? `subject install timed out after ${step.serve.installTimeoutMs ?? INSTALL_TIMEOUT_MS}ms`
+            : install.attempts === 2
+                ? `subject install failed twice (exit ${install.firstExitCode ?? "null"}, then exit ${install.exitCode ?? "null"}); the sandbox could not complete serve.install`
+                : `subject install failed (exit ${install.exitCode ?? "null"})`;
+        throw new Error(`${headline}: ${failureTail(step.scrub(install.logTail))}`);
+    }
+}
+/** serve.build, once. */
+async function buildSubject(step, command) {
+    const { now } = step;
+    const buildStartedAt = now();
+    emitPhaseStarted(step.onPhase, now, "build", "building subject");
+    const build = await runDetachedStep(step.shell, {
+        name: "subject-build",
+        command,
+        cwd: SUBJECT_DIR,
+        timeoutMs: step.serve.buildTimeoutMs ?? BUILD_TIMEOUT_MS,
+        requestTimeoutMs: step.requestTimeoutMs,
+        ...step.timers,
+    });
+    emitPhaseCompleted(step.onPhase, now, buildStartedAt, "build", build.ok, build.ok ? "subject build complete" : "subject build failed");
+    if (!build.ok) {
+        throw new Error(`subject build ${build.timedOut ? "timed out" : `failed (exit ${build.exitCode})`}: ${failureTail(step.scrub(build.logTail))}`);
+    }
+}
+/** serve.start as a detached process that keeps running. */
+async function startSubject(step) {
+    await startDetachedProcess(step.shell, {
+        name: "subject-start",
+        command: step.serve.start,
+        cwd: SUBJECT_DIR,
+        requestTimeoutMs: step.requestTimeoutMs,
+    });
+    // Fire-and-forget: startDetachedProcess never waits for the long-lived server to exit, so
+    // there is no matching completed event here (no ok/durationMs to report yet); readiness is
+    // the next boundary.
+    step.onPhase?.({
+        at: isoNow(step.now),
+        type: "cua-lab.subject.serve.started",
+        message: "subject server launched (detached)",
+    });
+}
+/** Probe serve.url until it answers; on timeout, report the start log's tail. */
+async function waitForSubjectReady(step) {
+    const { now } = step;
+    const readyStartedAt = now();
+    emitPhaseStarted(step.onPhase, now, "ready", "waiting for subject to become ready");
+    const ready = await probeUrl(step.shell, step.serve.url, {
+        timeoutMs: step.serve.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,
+        requestTimeoutMs: step.requestTimeoutMs,
+        ...step.timers,
+    });
+    emitPhaseCompleted(step.onPhase, now, readyStartedAt, "ready", ready, ready ? "subject is ready" : "subject did not become ready in time");
+    if (!ready) {
+        const startLog = await readDetachedLog(step.shell, "subject-start", step.requestTimeoutMs).catch(() => "");
+        throw new Error(`subject did not answer at ${step.serve.url} within ${step.serve.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS}ms; server log tail: ${failureTail(step.scrub(startLog))}`);
+    }
+}

package/dist/subject/state.d.ts

@@ -0,0 +1,23 @@
+import type { LabStateStepWhen, LabSubjectState } from "../lab/types.js";
+import type { RunSubjectStateStepRecord } from "../run/bundle.js";
+import { type DetachedTimers } from "../substrates/detached.js";
+import type { Shell } from "../substrates/shell.js";
+import { type SubjectPhaseEvent } from "./steps.js";
+export declare const DEFAULT_STATE_STEP_TIMEOUT_MS: number;
+/** sha256 hex of the exact command string, first 16 chars (the promptDigest convention). */
+export declare function commandDigestOf(command: string): string;
+/**
+ * Run the declared seed steps for one phase of the serve pipeline, as detached steps named
+ * `subject-state-<name>` so a step can never collide with a serve step. Each step's record goes
+ * to `onStateStep` as it finishes; the first failure throws with its scrubbed log tail.
+ */
+export declare function runStateSteps(shell: Shell, when: LabStateStepWhen, args: {
+    state?: LabSubjectState;
+    requestTimeoutMs: number;
+    /** Literal scrubber for known provisioned values, applied to log tails PRE-truncation. */
+    scrub: (text: string) => string;
+    onStateStep?: (record: RunSubjectStateStepRecord) => void;
+    onPhase?: (event: SubjectPhaseEvent) => void;
+    now: () => number;
+    timers: DetachedTimers;
+}): Promise<void>;

package/dist/subject/state.js

@@ -0,0 +1,58 @@
+import { digestText } from "../evidence/redaction.js";
+import { failureTail } from "../evidence/redaction.js";
+import { runDetachedStep } from "../substrates/detached.js";
+import { emitPhaseCompleted, emitPhaseStarted, SUBJECT_DIR, } from "./steps.js";
+// Per-step budget for subject.state seed steps; each step's declared (or default) budget is
+// also summed into the default sandbox deadline so seeding never eats the session's room.
+export const DEFAULT_STATE_STEP_TIMEOUT_MS = 5 * 60_000;
+/** sha256 hex of the exact command string, first 16 chars (the promptDigest convention). */
+export function commandDigestOf(command) {
+    return digestText(command, 16);
+}
+/**
+ * Run the declared seed steps for one phase of the serve pipeline, as detached steps named
+ * `subject-state-<name>` so a step can never collide with a serve step. Each step's record goes
+ * to `onStateStep` as it finishes; the first failure throws with its scrubbed log tail.
+ */
+export async function runStateSteps(shell, when, args) {
+    const { now, timers } = args;
+    const stateSteps = args.state?.seed ?? [];
+    const steps = stateSteps.filter((step) => (step.when ?? "before-start") === when);
+    if (steps.length === 0) {
+        // No declared steps for this group: no boundary to report (avoids empty-group noise on
+        // every run, since before-build/before-start/after-ready are always called).
+        return;
+    }
+    const groupStartedAt = now();
+    emitPhaseStarted(args.onPhase, now, `state.${when}`, `running subject state seed steps (${when})`);
+    for (const step of steps) {
+        const stepTimeoutMs = step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS;
+        const startedAt = now();
+        const result = await runDetachedStep(shell, {
+            name: `subject-state-${step.name}`,
+            command: step.command,
+            cwd: SUBJECT_DIR,
+            timeoutMs: stepTimeoutMs,
+            requestTimeoutMs: args.requestTimeoutMs,
+            ...timers,
+        });
+        args.onStateStep?.({
+            name: step.name,
+            when,
+            // Digest only (sha256-16): the command text never persists: the lab YAML in the
+            // consumer's repo is the plaintext source of truth.
+            commandDigest: commandDigestOf(step.command),
+            ok: result.ok,
+            ...(result.exitCode === undefined ? {} : { exitCode: result.exitCode }),
+            ...(result.timedOut ? { timedOut: true } : {}),
+            durationMs: Math.max(0, now() - startedAt),
+        });
+        if (!result.ok) {
+            emitPhaseCompleted(args.onPhase, now, groupStartedAt, `state.${when}`, false, `subject state seed steps failed (${when})`);
+            // Fail closed with the scrub-before-truncate tail chain: literal scrub of every provisioned
+            // value before truncation, then pattern redaction and the cap in failureTail.
+            throw new Error(`subject state step "${step.name}" ${result.timedOut ? `timed out after ${stepTimeoutMs}ms` : `failed (exit ${result.exitCode})`}: ${failureTail(args.scrub(result.logTail))}`);
+        }
+    }
+    emitPhaseCompleted(args.onPhase, now, groupStartedAt, `state.${when}`, true, `subject state seed steps complete (${when})`);
+}

package/dist/subject/steps.d.ts

@@ -0,0 +1,37 @@
+export declare const SUBJECT_DIR = "/home/user/subject";
+/** Budget for putting the subject's source on the machine: a clone, or an archive extract. */
+export declare const SOURCE_TIMEOUT_MS: number;
+export declare const INSTALL_TIMEOUT_MS: number;
+/**
+ * One phase-boundary event from the shared subject provisioning pipeline (clone or local-tree
+ * route): started/completed pairs at each named boundary, never per poll tick (the detached
+ * primitive in src/substrates/detached.ts already polls every 1.5-3s internally; only the
+ * boundary itself is surfaced here). Message text is public-safe by construction: no URLs beyond
+ * the existing publicAppUrl convention, no paths, no command text. Completed events carry `ok`
+ * and `durationMs`; started events (and the fire-and-forget `subject.serve.started`) carry
+ * neither.
+ */
+export interface SubjectPhaseEvent {
+    at: string;
+    type: string;
+    ok?: boolean;
+    durationMs?: number;
+    message: string;
+}
+/** ISO timestamp from an injectable clock (tests freeze `now` for deterministic durationMs). */
+export declare function isoNow(now: () => number): string;
+/** Emit a phase-started event (no ok/durationMs: those belong to the matching completed event). */
+export declare function emitPhaseStarted(onPhase: ((event: SubjectPhaseEvent) => void) | undefined, now: () => number, phase: string, message: string): void;
+/** Emit the matching phase-completed event: always carries ok and durationMs (>= 0). */
+export declare function emitPhaseCompleted(onPhase: ((event: SubjectPhaseEvent) => void) | undefined, now: () => number, startedAt: number, phase: string, ok: boolean, message: string): void;
+/** Default phase-boundary sink (stderr): one line per event, prefixed with the lane id ONLY
+ *  when laneCount > 1. Single-lane emission is unconditional: total single-lane silence for the
+ *  whole clone/install/build/ready boot is the bug this event stream exists to close.
+ *  Overridable via CuaActorLabHooks.onPhase so deterministic tests capture instead of writing to
+ *  the real stderr. */
+export declare function defaultSubjectPhaseSink(event: SubjectPhaseEvent, ctx: {
+    laneId: string;
+    laneCount: number;
+}): void;
+/** The shared-world subject's phase line: one shared plane, so no lane prefix. */
+export declare function defaultSharedWorldPhaseSink(event: SubjectPhaseEvent): void;

package/dist/subject/steps.js

@@ -0,0 +1,39 @@
+// What every subject provisioner shares: where the subject lives on the machine, the step
+// budgets, and the started/completed phase events each step reports.
+export const SUBJECT_DIR = "/home/user/subject";
+/** Budget for putting the subject's source on the machine: a clone, or an archive extract. */
+export const SOURCE_TIMEOUT_MS = 5 * 60_000;
+export const INSTALL_TIMEOUT_MS = 10 * 60_000;
+/** ISO timestamp from an injectable clock (tests freeze `now` for deterministic durationMs). */
+export function isoNow(now) {
+    return new Date(now()).toISOString();
+}
+/** Emit a phase-started event (no ok/durationMs: those belong to the matching completed event). */
+export function emitPhaseStarted(onPhase, now, phase, message) {
+    onPhase?.({ at: isoNow(now), type: `cua-lab.subject.${phase}.started`, message });
+}
+/** Emit the matching phase-completed event: always carries ok and durationMs (>= 0). */
+export function emitPhaseCompleted(onPhase, now, startedAt, phase, ok, message) {
+    onPhase?.({
+        at: isoNow(now),
+        type: `cua-lab.subject.${phase}.completed`,
+        ok,
+        durationMs: Math.max(0, now() - startedAt),
+        message,
+    });
+}
+/** Default phase-boundary sink (stderr): one line per event, prefixed with the lane id ONLY
+ *  when laneCount > 1. Single-lane emission is unconditional: total single-lane silence for the
+ *  whole clone/install/build/ready boot is the bug this event stream exists to close.
+ *  Overridable via CuaActorLabHooks.onPhase so deterministic tests capture instead of writing to
+ *  the real stderr. */
+export function defaultSubjectPhaseSink(event, ctx) {
+    const durationSuffix = event.durationMs === undefined ? "" : ` (${event.durationMs}ms)`;
+    const prefix = ctx.laneCount > 1 ? `humanish cua [${ctx.laneId}]` : "humanish cua";
+    process.stderr.write(`${prefix}: ${event.message}${durationSuffix}\n`);
+}
+/** The shared-world subject's phase line: one shared plane, so no lane prefix. */
+export function defaultSharedWorldPhaseSink(event) {
+    const durationSuffix = event.durationMs === undefined ? "" : ` (${event.durationMs}ms)`;
+    process.stderr.write(`humanish shared-world (concurrent): ${event.message}${durationSuffix}\n`);
+}

package/dist/substrates/command-failure.d.ts

@@ -0,0 +1,23 @@
+/**
+ * True when `error` is (structurally) the @e2b/desktop CommandExitError: a
+ * non-zero substrate command exit that the real Sandbox surfaces as a THROW.
+ * Matches either the SDK class name (`name === "CommandExitError"`) or any object
+ * carrying a numeric `exitCode` (the same field `commandFailureInfo` reads, so a
+ * structural fake is covered without importing the SDK class).
+ *
+ * Deliberately conservative — it is the RECOVERABILITY predicate the CUA loop uses
+ * to skip a single failed desktop action instead of ending the whole run: it must
+ * NOT match a deadline/abort control-flow signal (those subclass Error without a
+ * name override or an exitCode) or a generic Error with no exit signal, so only a
+ * genuine substrate-command failure is treated as recoverable.
+ */
+export declare function isCommandExitError(error: unknown): boolean;
+/**
+ * Recover the exit code + a sanitized stderr/stdout tail from a command failure.
+ * The real @e2b/desktop CommandExitError exposes exitCode/stderr/stdout/error;
+ * these are read structurally so the caller does not depend on the SDK class.
+ */
+export declare function commandFailureInfo(error: unknown): {
+    exitCode?: number;
+    stderrTail: string;
+};

package/dist/substrates/command-failure.js

@@ -0,0 +1,45 @@
+// Shared handling for @e2b/desktop command failures.
+//
+// The SDK's `commands.run` throws a CommandExitError on any non-zero exit (e2b 2.49.0:
+// CommandHandle.wait), so a caller that reads `result.exitCode` after a raw call never sees a
+// failure. Desktop code runs commands through e2bShell (src/substrates/e2b/shell.ts), which turns
+// that throw into a result. These helpers recover the exit code and a sanitized output tail from
+// the throw for the callers that still meet it directly, such as the desktop executor.
+//
+// Public-safety: only the substrate's own output (stderr/stdout/error/message) is
+// read here; caller-supplied text (e.g. typed input) must never be passed to the
+// failing command as an argument, so it cannot appear in these fields.
+import { tailOf } from "./shell.js";
+/**
+ * True when `error` is (structurally) the @e2b/desktop CommandExitError: a
+ * non-zero substrate command exit that the real Sandbox surfaces as a THROW.
+ * Matches either the SDK class name (`name === "CommandExitError"`) or any object
+ * carrying a numeric `exitCode` (the same field `commandFailureInfo` reads, so a
+ * structural fake is covered without importing the SDK class).
+ *
+ * Deliberately conservative — it is the RECOVERABILITY predicate the CUA loop uses
+ * to skip a single failed desktop action instead of ending the whole run: it must
+ * NOT match a deadline/abort control-flow signal (those subclass Error without a
+ * name override or an exitCode) or a generic Error with no exit signal, so only a
+ * genuine substrate-command failure is treated as recoverable.
+ */
+export function isCommandExitError(error) {
+    if (error === null || typeof error !== "object")
+        return false;
+    const e = error;
+    return e.name === "CommandExitError" || typeof e.exitCode === "number";
+}
+/**
+ * Recover the exit code + a sanitized stderr/stdout tail from a command failure.
+ * The real @e2b/desktop CommandExitError exposes exitCode/stderr/stdout/error;
+ * these are read structurally so the caller does not depend on the SDK class.
+ */
+export function commandFailureInfo(error) {
+    const e = (error ?? {});
+    const exitCode = typeof e.exitCode === "number" ? e.exitCode : undefined;
+    const str = (value) => typeof value === "string" && value.length > 0 ? value : undefined;
+    const source = str(e.stderr) ?? str(e.stdout) ?? str(e.error) ?? str(e.message);
+    return exitCode === undefined
+        ? { stderrTail: tailOf(source) }
+        : { exitCode, stderrTail: tailOf(source) };
+}

package/dist/substrates/desktop-session.d.ts

@@ -0,0 +1,41 @@
+import type { CuaExecutor } from "../actors/computer-use/loop.js";
+/** Internal lifecycle contract. Provider IDs are evidence, not permission to acquire a handle. */
+export type DesktopReleaseResult = {
+    status: "released";
+    reason: "terminated" | "already_gone";
+} | {
+    status: "retained";
+    reason: "debug";
+} | {
+    status: "unconfirmed";
+    reason: "release_unavailable" | "invalid_result" | "release_failed";
+    error?: unknown;
+};
+export interface DesktopSession {
+    readonly resourceId: string;
+    readonly executor: CuaExecutor;
+    close(options?: {
+        retainForDebug?: boolean;
+    }): Promise<DesktopReleaseResult>;
+}
+export interface OwnedDesktopAllocation {
+    readonly resourceId: string;
+    /** Bind after adapter-specific provisioning, once per allocation. */
+    open(executor: CuaExecutor): DesktopSession;
+    /** Also available before open, so a provisioning failure cannot lose its cleanup handle. */
+    close(options?: {
+        retainForDebug?: boolean;
+    }): Promise<DesktopReleaseResult>;
+}
+/**
+ * Wrap an already-acquired resource. The adapter supplies release authority as a closure;
+ * this layer never reconstructs it from a saved ID or enumerates provider resources.
+ * Closing immediately rejects new actions, including when release is unconfirmed. An
+ * in-flight backend operation may reject as the resource stops; close does not wait for it.
+ */
+export declare function ownDesktopAllocation(options: {
+    resourceId: string;
+    release: () => Promise<Exclude<DesktopReleaseResult, {
+        status: "retained";
+    }>>;
+}): OwnedDesktopAllocation;

package/dist/substrates/desktop-session.js

@@ -0,0 +1,59 @@
+import { CuaExecutorError } from "../actors/computer-use/executor-error.js";
+/**
+ * Wrap an already-acquired resource. The adapter supplies release authority as a closure;
+ * this layer never reconstructs it from a saved ID or enumerates provider resources.
+ * Closing immediately rejects new actions, including when release is unconfirmed. An
+ * in-flight backend operation may reject as the resource stops; close does not wait for it.
+ */
+export function ownDesktopAllocation(options) {
+    const resourceId = options.resourceId;
+    const release = options.release;
+    let opened = false;
+    let closing;
+    const assertOpen = () => {
+        if (closing !== undefined)
+            throw new CuaExecutorError("executor_closed", "not_dispatched");
+    };
+    const close = (policy = {}) => {
+        // Install the promise before invoking release: concurrent/reentrant callers share it.
+        closing ??=
+            policy.retainForDebug === true
+                ? Promise.resolve({ status: "retained", reason: "debug" })
+                : Promise.resolve()
+                    .then(release)
+                    .catch((error) => ({
+                    status: "unconfirmed",
+                    reason: "release_failed",
+                    error,
+                }));
+        return closing;
+    };
+    return Object.freeze({
+        resourceId,
+        close,
+        open(executor) {
+            assertOpen();
+            if (opened)
+                throw new Error("Desktop allocation already has a participant session.");
+            opened = true;
+            return Object.freeze({
+                resourceId,
+                close,
+                executor: {
+                    ...(executor.stallRecovery === "fail_closed"
+                        ? { stallRecovery: "fail_closed" }
+                        : {}),
+                    ...(executor.speechEnabled === true ? { speechEnabled: true } : {}),
+                    observe: async () => {
+                        assertOpen();
+                        return executor.observe();
+                    },
+                    execute: async (action, signal) => {
+                        assertOpen();
+                        return executor.execute(action, signal);
+                    },
+                },
+            });
+        },
+    });
+}