humanish 0.105.0 → 0.106.0

package/dist/substrates/e2b/desktop-recording.js

@@ -0,0 +1,238 @@
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { buildDesktopRecorderCommand, buildDesktopRecorderPulseSetupCommands, buildDesktopRecorderProbeCommand, parseDesktopRecorderDuration, } from "../../evidence/desktop-recorder.js";
+import { DESKTOP_RECORDING_MAX_BYTES, } from "../../evidence/desktop-recording-types.js";
+import { runOrThrow, shellQuote } from "../shell.js";
+import { e2bShell } from "./shell.js";
+const OUTPUT_PATH = "/tmp/humanish-desktop-recording.mp4";
+const PID_PATH = "/tmp/humanish-desktop-recording.pid";
+const PULSE_RUNTIME = "/tmp/humanish-recording-runtime";
+const FINALIZE_TIMEOUT_MS = 10_000;
+const FORCE_REAP_TIMEOUT_MS = 5_000;
+const baseEnv = Object.freeze({
+    PATH: "/usr/local/bin:/usr/bin:/bin",
+    HOME: "/home/user",
+    USER: "user",
+    LOGNAME: "user",
+    LANG: "C.UTF-8",
+    DISPLAY: ":0",
+});
+async function settlesWithin(promise, timeoutMs) {
+    let timer;
+    return Promise.race([
+        promise.then(() => true),
+        new Promise((resolve) => {
+            timer = setTimeout(() => resolve(false), timeoutMs);
+        }),
+    ]).finally(() => clearTimeout(timer));
+}
+const commandLine = (command) => `${shellQuote(command.binary)} ${command.args.map(shellQuote).join(" ")}`;
+async function stopPulse(shell, env, requestTimeoutMs) {
+    await shell.run("pulseaudio --kill", { env, timeoutMs: 5_000, requestTimeoutMs }).catch(() => { });
+}
+async function preparePulse(shell, requestTimeoutMs) {
+    const env = {
+        ...baseEnv,
+        XDG_RUNTIME_DIR: PULSE_RUNTIME,
+        PULSE_SERVER: `unix:${PULSE_RUNTIME}/pulse/native`,
+        PULSE_SOURCE: "humanish_input",
+        PULSE_SINK: "humanish_speaker",
+    };
+    try {
+        await runOrThrow(shell, "install -d -m 0700 /tmp/humanish-recording-runtime && " +
+            "pulseaudio --daemonize=yes --exit-idle-time=-1 --log-target=stderr && " +
+            "pactl load-module module-null-sink sink_name=humanish_mic sink_properties=device.description=HumanishSyntheticMicrophone >/dev/null && " +
+            "pactl load-module module-remap-source master=humanish_mic.monitor source_name=humanish_input source_properties=device.description=HumanishSyntheticMicrophone >/dev/null && " +
+            "pactl load-module module-null-sink sink_name=humanish_speaker sink_properties=device.description=HumanishSyntheticSpeaker >/dev/null && " +
+            "pactl set-default-source humanish_input && pactl set-default-sink humanish_speaker", {
+            env,
+            timeoutMs: 30_000,
+            requestTimeoutMs,
+        });
+        return env;
+    }
+    catch (error) {
+        await stopPulse(shell, env, requestTimeoutMs);
+        throw error;
+    }
+}
+async function runRecorderPulseSetup(shell, env, requestTimeoutMs) {
+    for (const setup of buildDesktopRecorderPulseSetupCommands()) {
+        await runOrThrow(shell, commandLine(setup), { env, timeoutMs: 5_000, requestTimeoutMs });
+    }
+}
+async function launchRecorder(options, env, audioSources) {
+    const startedAtMs = Date.now();
+    const command = buildDesktopRecorderCommand({
+        display: ":0",
+        width: options.width,
+        height: options.height,
+        outputPath: OUTPUT_PATH,
+        audioSources,
+    }, startedAtMs);
+    const launch = `set -eu; rm -f ${shellQuote(PID_PATH)}; /usr/bin/env --default-signal=INT,TERM ${commandLine(command)} & ` +
+        `child=$!; printf '%s\\n' "$child" > ${shellQuote(PID_PATH)}; wait "$child"`;
+    // The host launch boundary is the only clock shared with later run events. Capture it before
+    // the provider RPC so startup transport latency is not silently removed from the timeline.
+    const startedAt = new Date(startedAtMs).toISOString();
+    // A background run returns the process handle finish() needs, so it bypasses the Shell.
+    const handle = await options.desktop.commands.run(launch, {
+        background: true,
+        envs: { ...baseEnv, ...env },
+        timeoutMs: 0,
+        requestTimeoutMs: options.requestTimeoutMs,
+    });
+    return { handle, startedAt };
+}
+function watchRecorder(wait, kill) {
+    let stopping = false, exitedEarly = false;
+    const exited = wait().then((result) => {
+        if (!stopping)
+            exitedEarly = true;
+        return result;
+    }, (error) => {
+        if (!stopping)
+            exitedEarly = true;
+        return error;
+    });
+    void exited.catch(() => { });
+    return {
+        exited,
+        kill,
+        exitedEarly: () => exitedEarly,
+        markStopping: () => {
+            stopping = true;
+        },
+    };
+}
+async function readRecorderPid(shell, requestTimeoutMs) {
+    const pidResult = await runOrThrow(shell, `cat ${shellQuote(PID_PATH)}`, {
+        timeoutMs: 5_000,
+        requestTimeoutMs,
+    });
+    const recorderPid = Number(pidResult.stdout.trim());
+    if (!Number.isSafeInteger(recorderPid) || recorderPid < 1)
+        throw new Error("E2B desktop recorder did not report its owned process ID.");
+    return recorderPid;
+}
+/** Interrupt the recorder so FFmpeg finalizes the file; kill it if it does not exit in time. */
+async function stopRecorder(shell, recorder, recorderPid, requestTimeoutMs) {
+    recorder.markStopping();
+    if (!recorder.exitedEarly()) {
+        await runOrThrow(shell, `kill -INT -- ${recorderPid}`, {
+            timeoutMs: 5_000,
+            requestTimeoutMs,
+        });
+    }
+    let forced = false;
+    let timer;
+    await Promise.race([
+        recorder.exited,
+        new Promise((resolve) => {
+            timer = setTimeout(() => {
+                forced = true;
+                resolve();
+            }, FINALIZE_TIMEOUT_MS);
+        }),
+    ]).finally(() => clearTimeout(timer));
+    if (forced) {
+        await recorder.kill().catch(() => { });
+        if (!(await settlesWithin(recorder.exited, FORCE_REAP_TIMEOUT_MS)))
+            throw new Error("E2B recorder process did not stop.");
+    }
+    return { forced };
+}
+async function probeDuration(shell, requestTimeoutMs) {
+    const probe = await runOrThrow(shell, commandLine(buildDesktopRecorderProbeCommand(OUTPUT_PATH)), {
+        timeoutMs: 30_000,
+        requestTimeoutMs,
+    });
+    return parseDesktopRecorderDuration(probe.stdout);
+}
+/** Stream the finished file to the destination under the size limit; returns the byte count. */
+async function transferRecording(desktop, destination, requestTimeoutMs) {
+    const transferSignal = AbortSignal.timeout(requestTimeoutMs);
+    const web = await desktop.files.read(OUTPUT_PATH, {
+        format: "stream",
+        requestTimeoutMs,
+        streamIdleTimeoutMs: requestTimeoutMs,
+        signal: transferSignal,
+    });
+    let transferred = 0;
+    const count = new Transform({
+        transform(chunk, _encoding, callback) {
+            if (transferred + chunk.length > DESKTOP_RECORDING_MAX_BYTES) {
+                callback(new Error("E2B recording exceeds the size limit."));
+                return;
+            }
+            transferred += chunk.length;
+            callback(undefined, chunk);
+        },
+    });
+    await pipeline(Readable.fromWeb(web), count, destination, { signal: transferSignal });
+    if (transferred < 1)
+        throw new Error("E2B desktop recorder produced empty output.");
+    return transferred;
+}
+/** Starts the shared FFmpeg recipe through E2B's command transport; retrieval remains host-owned. */
+export async function startE2BDesktopRecording(options) {
+    if (!options.desktop.files.read)
+        throw new Error("Installed @e2b/desktop does not support streamed recording retrieval.");
+    const audioSources = options.audio
+        ? ["microphone-input", "speaker-output"]
+        : [];
+    const requestTimeoutMs = options.requestTimeoutMs;
+    // Recorder setup and finalization fail on any non-zero exit; runOrThrow says so with the tail.
+    const shell = e2bShell(options.desktop);
+    const ownsPulse = options.audio && options.pulseEnv === undefined;
+    const env = options.audio
+        ? (options.pulseEnv ?? (await preparePulse(shell, requestTimeoutMs)))
+        : baseEnv;
+    const stopOwnedPulse = async () => {
+        if (ownsPulse)
+            await stopPulse(shell, env, requestTimeoutMs);
+    };
+    const failStartup = async (error, recorder) => {
+        await recorder?.kill().catch(() => { });
+        await stopOwnedPulse();
+        throw error;
+    };
+    if (options.audio)
+        await runRecorderPulseSetup(shell, env, requestTimeoutMs).catch((error) => failStartup(error));
+    const { handle, startedAt } = await launchRecorder(options, env, audioSources).catch((error) => failStartup(error));
+    if (!handle.wait || !handle.kill || !Number.isSafeInteger(handle.pid) || handle.pid < 1) {
+        await handle.kill?.().catch(() => { });
+        await stopOwnedPulse();
+        throw new Error("Installed @e2b/desktop does not expose an owned recording process handle.");
+    }
+    const recorder = watchRecorder(handle.wait.bind(handle), handle.kill.bind(handle));
+    await options.desktop.wait(150);
+    if (recorder.exitedEarly())
+        await failStartup(new Error("E2B desktop recorder exited during startup."));
+    const recorderPid = await readRecorderPid(shell, requestTimeoutMs).catch((error) => failStartup(error, recorder));
+    let finishing;
+    return {
+        env,
+        finish: (destination) => (finishing ??= (async () => {
+            try {
+                const { forced } = await stopRecorder(shell, recorder, recorderPid, requestTimeoutMs);
+                const durationMs = await probeDuration(shell, requestTimeoutMs);
+                const bytes = await transferRecording(options.desktop, destination, requestTimeoutMs);
+                return {
+                    mimeType: "video/mp4",
+                    startedAt,
+                    durationMs,
+                    bytes,
+                    audioSources,
+                    complete: !recorder.exitedEarly() && !forced,
+                };
+            }
+            catch {
+                throw new Error("E2B desktop recording failed.");
+            }
+            finally {
+                await stopOwnedPulse();
+            }
+        })()),
+    };
+}

package/dist/substrates/e2b/desktop-resources.d.ts

@@ -0,0 +1,11 @@
+import type { E2BDesktopSandbox } from "./sdk.js";
+import { type DesktopResources } from "../../run/pricing.js";
+export type DesktopResourceObservation = {
+    resources: DesktopResources;
+    source: "e2b.getInfo";
+} | {
+    reason: "metadata_unavailable" | "metadata_invalid" | "metadata_timeout";
+};
+/** Called once after the caller owns and journals the handle. Never throws or delays cleanup
+ * beyond the bounded wait. Persist only resource quantities, never the raw info/connection. */
+export declare function observeDesktopResources(desktop: Pick<E2BDesktopSandbox, "getInfo">, timeoutMs?: number): Promise<DesktopResourceObservation>;

package/dist/substrates/e2b/desktop-resources.js

@@ -0,0 +1,35 @@
+import { isDesktopResources } from "../../run/pricing.js";
+/** Called once after the caller owns and journals the handle. Never throws or delays cleanup
+ * beyond the bounded wait. Persist only resource quantities, never the raw info/connection. */
+export async function observeDesktopResources(desktop, timeoutMs = 1_000) {
+    const controller = new AbortController();
+    let timer;
+    try {
+        if (typeof desktop.getInfo !== "function")
+            return { reason: "metadata_unavailable" };
+        const waitMs = Number.isFinite(timeoutMs) && timeoutMs > 0 ? Math.min(timeoutMs, 1_000) : 1_000;
+        return await Promise.race([
+            Promise.resolve().then(async () => {
+                const info = await desktop.getInfo({
+                    requestTimeoutMs: waitMs,
+                    signal: controller.signal,
+                });
+                const resources = { cpuCount: info?.cpuCount, memoryMiB: info?.memoryMB };
+                return isDesktopResources(resources)
+                    ? { resources, source: "e2b.getInfo" }
+                    : { reason: "metadata_invalid" };
+            }),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve({ reason: "metadata_timeout" }), waitMs);
+            }),
+        ]);
+    }
+    catch {
+        return { reason: "metadata_unavailable" };
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        controller.abort();
+    }
+}

package/dist/substrates/e2b/desktop-screenshot-cleanup.d.ts

@@ -0,0 +1,15 @@
+import type { E2BDesktopSandbox } from "./sdk.js";
+/** Runtime diagnostic only; no provider errors, file paths, or image contents are retained. */
+export declare function desktopScreenshotCleanupFailures(desktop: object): number;
+/**
+ * @e2b/desktop 2.3.3 screenshot() awaits capture and files.read(path), then discards the
+ * files.remove(path) promise. A removal that races sandbox teardown can therefore crash Node
+ * AFTER valid bytes were returned. Installed-SDK conformance tests pin that behavior (#662).
+ *
+ * Observe only removal of a file successfully read within THIS screenshot invocation. The
+ * exact path comes from the SDK, not a guessed filename pattern. AsyncLocalStorage isolates
+ * concurrent screenshots and unrelated file operations without changing SDK method receivers.
+ * The ORIGINAL removal promise is returned: an SDK version (or caller) that awaits it still
+ * receives the original rejection. No process-wide rejection handler or filesystem retry.
+ */
+export declare function protectDesktopScreenshotCleanup<T extends E2BDesktopSandbox>(desktop: T): T;

package/dist/substrates/e2b/desktop-screenshot-cleanup.js

@@ -0,0 +1,66 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const guarded = new WeakSet();
+const failureCounts = new WeakMap();
+// One long-lived context instance: creating one per desktop would require disable() on every
+// teardown for AsyncLocalStorage itself to be collected. Invocation stores follow async work.
+const screenshotScope = new AsyncLocalStorage();
+/** Runtime diagnostic only; no provider errors, file paths, or image contents are retained. */
+export function desktopScreenshotCleanupFailures(desktop) {
+    return failureCounts.get(desktop) ?? 0;
+}
+/**
+ * @e2b/desktop 2.3.3 screenshot() awaits capture and files.read(path), then discards the
+ * files.remove(path) promise. A removal that races sandbox teardown can therefore crash Node
+ * AFTER valid bytes were returned. Installed-SDK conformance tests pin that behavior (#662).
+ *
+ * Observe only removal of a file successfully read within THIS screenshot invocation. The
+ * exact path comes from the SDK, not a guessed filename pattern. AsyncLocalStorage isolates
+ * concurrent screenshots and unrelated file operations without changing SDK method receivers.
+ * The ORIGINAL removal promise is returned: an SDK version (or caller) that awaits it still
+ * receives the original rejection. No process-wide rejection handler or filesystem retry.
+ */
+export function protectDesktopScreenshotCleanup(desktop) {
+    if (guarded.has(desktop))
+        return desktop;
+    const files = desktop.files;
+    const read = files.read;
+    const remove = files.remove;
+    if (typeof read !== "function" || typeof remove !== "function")
+        return desktop;
+    const screenshot = desktop.screenshot;
+    files.read = function (path, ...args) {
+        const pending = read.call(this, path, ...args);
+        const scope = screenshotScope.getStore();
+        if (scope?.desktop !== desktop)
+            return pending;
+        return pending.then((value) => {
+            scope.paths.add(path);
+            return value;
+        });
+    };
+    files.remove = function (path, ...args) {
+        const pending = remove.call(this, path, ...args);
+        const scope = screenshotScope.getStore();
+        if (scope?.desktop === desktop && scope.paths.has(path)) {
+            // The secondary handler resolves independently. Returning pending (not catch's promise)
+            // preserves awaited removal failures while observing the SDK's detached rejection.
+            void pending.catch(() => {
+                const count = desktopScreenshotCleanupFailures(desktop) + 1;
+                failureCounts.set(desktop, count);
+                try {
+                    process.stderr.write(`humanish desktop: screenshot temporary-file cleanup failed (${count}); image read completed. Sandbox teardown reclaims temporary files.\n`);
+                }
+                catch {
+                    // A closed diagnostic stream must not turn this secondary rejection observer into a
+                    // new unhandled rejection. The per-instance counter remains available.
+                }
+            });
+        }
+        return pending;
+    };
+    desktop.screenshot = function (...args) {
+        return screenshotScope.run({ desktop, paths: new Set() }, () => screenshot.apply(this, args));
+    };
+    guarded.add(desktop);
+    return desktop;
+}

package/dist/substrates/e2b/lifetime.d.ts

@@ -0,0 +1,12 @@
+/**
+ * E2B refuses a sandbox lifetime over one hour ("400: Timeout cannot be greater than 1 hours").
+ * A derived deadline has to stay under it, and saying so at plan time beats discovering it from a
+ * raw provider 400 after a plan has already printed.
+ */
+export declare const MAX_SANDBOX_MS: number;
+/** Server-side reclamation buffer past a participant's own wall-clock stop. */
+export declare const SANDBOX_TIMEOUT_BUFFER_MS: number;
+/** Room a provisioned subject adds to the sandbox deadline for clone, install, build, start and probe. */
+export declare const SUBJECT_PROVISION_BUDGET_MS: number;
+/** The timeout of one E2B API request: HUMANISH_E2B_REQUEST_TIMEOUT_MS when set, else 60 s. */
+export declare function e2bRequestTimeoutMs(env: Record<string, string | undefined>): number;

package/dist/substrates/e2b/lifetime.js

@@ -0,0 +1,18 @@
+// How long an E2B sandbox may live, and the budgets the desktop routes add to a participant's own
+// deadline when they set a sandbox's server-side timeout. A dead host process can never orphan a
+// sandbox past that timeout, so every route derives it from these values.
+import { readPositiveInt } from "../../lab/parse/values.js";
+/**
+ * E2B refuses a sandbox lifetime over one hour ("400: Timeout cannot be greater than 1 hours").
+ * A derived deadline has to stay under it, and saying so at plan time beats discovering it from a
+ * raw provider 400 after a plan has already printed.
+ */
+export const MAX_SANDBOX_MS = 60 * 60_000;
+/** Server-side reclamation buffer past a participant's own wall-clock stop. */
+export const SANDBOX_TIMEOUT_BUFFER_MS = 10 * 60_000;
+/** Room a provisioned subject adds to the sandbox deadline for clone, install, build, start and probe. */
+export const SUBJECT_PROVISION_BUDGET_MS = 30 * 60_000;
+/** The timeout of one E2B API request: HUMANISH_E2B_REQUEST_TIMEOUT_MS when set, else 60 s. */
+export function e2bRequestTimeoutMs(env) {
+    return readPositiveInt(env.HUMANISH_E2B_REQUEST_TIMEOUT_MS, 60_000);
+}

package/dist/substrates/e2b/sandbox.d.ts

@@ -0,0 +1,102 @@
+import type { PreparedOutputRoot } from "../../run/contained-output.js";
+import { type DesktopReleaseResult, type OwnedDesktopAllocation } from "../desktop-session.js";
+import type { LabConfig } from "../../lab/types.js";
+import { type E2BDesktopCreateOptions, type E2BDesktopModule, type E2BDesktopSandbox } from "./sdk.js";
+/** Where an allocation's receipt goes: the run's prepared root, under a public-safe participant
+ *  label. The receipt line saves it as `laneId`. */
+interface E2BSandboxReceiptTarget {
+    root: PreparedOutputRoot;
+    participantId: string;
+    /** Clock for the receipt's `at`; defaults to Date.now. */
+    now?: () => number;
+}
+export interface E2BSandboxRequest {
+    module: E2BDesktopModule;
+    options: E2BDesktopCreateOptions;
+    retry?: TransientRetryHooks;
+    /**
+     * Required so every caller decides. `null` is only for a caller that could not open a journal;
+     * that sandbox is reclaimable by its create-time `timeoutMs` alone.
+     */
+    receipt: E2BSandboxReceiptTarget | null;
+}
+export interface E2BSandbox {
+    /** The mutable SDK handle. Provisioning hooks receive it and may change it. */
+    sandbox: E2BDesktopSandbox;
+    /** The exact id and release authority, captured before any hook sees the handle. */
+    allocation: OwnedDesktopAllocation;
+}
+/** A desktop sandbox, on the stock `desktop` template or a named one. */
+export declare function acquireE2BDesktopSandbox(request: E2BSandboxRequest & {
+    template?: string | undefined;
+}): Promise<E2BSandbox>;
+/** The terminal route's shell sandbox. It always runs on the stock template. */
+export declare function acquireE2BShellSandbox(request: E2BSandboxRequest): Promise<E2BSandbox>;
+/** A route's reading of one sandbox release: whether it is gone, and the warning to record. */
+export interface E2BReleaseReading {
+    released: boolean;
+    warning?: string;
+}
+/**
+ * Read a release result the same way on every route. `label` names the sandbox in the warning
+ * ("Sandbox", "Subject sandbox"). `costSpan` adds that desktop cost uses the observed span when
+ * the sandbox was already gone, for routes that price its minutes. A retained sandbox is the
+ * caller's to describe.
+ */
+export declare function readE2BRelease(result: DesktopReleaseResult, options: {
+    label: string;
+    scrub: (text: string) => string;
+    costSpan?: boolean;
+}): E2BReleaseReading;
+/** Reclaim's persisted outcome; run/reclaim.ts writes these strings. */
+export type E2BSandboxDestroyOutcome = {
+    state: "killed" | "already-gone";
+} | {
+    state: "kill-failed";
+    detail: string;
+};
+/**
+ * Kill one sandbox by its exact recorded id, for reclaim, and map the shared release result onto
+ * reclaim's persisted outcome. It never lists the account.
+ */
+export declare function destroyE2BSandbox(module: E2BDesktopModule, sandboxId: string, options: {
+    requestTimeoutMs: number;
+}): Promise<E2BSandboxDestroyOutcome>;
+/** Versioned public template built by runtime/browser-media/e2b-template.mjs. */
+export declare const E2B_SPEECH_TEMPLATE = "7409n13kr83f7g7abx5g";
+/** The desktop template a lab asks for; undefined selects the SDK default. */
+export declare function e2bDesktopTemplate(config: {
+    readonly execution?: Pick<NonNullable<LabConfig["execution"]>, "target" | "desktop">;
+}): string | undefined;
+/** How a caller hears about the one retry; `sleep` is injectable so tests never wait. */
+export interface TransientRetryHooks {
+    onRetry?: (reason: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Wall-clock pause before the single retry; envd routing settles within a few seconds. */
+export declare const TRANSIENT_RETRY_DELAY_MS = 3000;
+/**
+ * The provider errors worth one retry, by the message the SDK throws. Each is a gap that clears
+ * within seconds of sandbox creation:
+ *
+ * - `12: [unimplemented] HTTP 404` and `[unavailable]`: the sandbox exists but its envd is not
+ *   routable yet, so the first request (the desktop SDK's Xvfb start) hits the proxy instead.
+ * - `Cannot read properties of undefined (reading 'envdVersion')` / `Response data is missing`:
+ *   the create API answered without a body.
+ * - `Expected to receive information about written file`: a file write the envd accepted without
+ *   describing, the same routing gap seen from the upload side.
+ * - transport resets (`fetch failed`, `ECONNRESET`, `socket hang up`, 502/503/504).
+ *
+ * NOT retried: timeouts (the budget is spent), auth (401/403), quota and rate limits (429: a burst
+ * that hit the limit should be spaced, not repeated), and anything that names the request as wrong.
+ */
+export declare function isTransientE2BError(error: unknown): boolean;
+/**
+ * Run `attempt`; on a transient provider error, say so through `onRetry`, wait, and run it once
+ * more. A second failure, or a non-transient first one, propagates as is. The first attempt may
+ * have allocated a sandbox this process never learned the id of (the SDK throws after the API
+ * call); the provider's own `timeoutMs` on that sandbox is what reclaims it, which the caller's
+ * warning should say.
+ */
+export declare function withOneRetryOnTransientE2BError<T>(attempt: () => Promise<T>, hooks?: TransientRetryHooks): Promise<T>;
+export {};