humanish 0.104.3 → 0.106.0

package/dist/first-run-path.js

@@ -1,136 +0,0 @@
-// What a person — or the coding agent setting humanish up for them — should do NEXT.
-//
-// WHY: `humanish init` wrote twenty files and stopped. The only lab that could actually run was a
-// $0 dry run; the two live ones were templates with `your-org/your-app` in them, so the first live
-// run a newcomer tried could not succeed no matter what credentials they had. Three independent
-// sources reached the same place — a participant in our own TUI study walked to the Start row and
-// found a placeholder URL, an adoption review concluded "the funnel is broken at the first live
-// run", and the release-gate participant said, unprompted, "validate one paid live study before
-// committing" (#505).
-//
-// The fix is not more surface. Increasingly the thing running `init` is a coding agent acting for
-// someone, and an agent reads stdout and does what it says. So init ends by naming the next
-// command — and names the one that will actually work ON THIS MACHINE, because a next step that
-// fails is worse than none.
-/**
- * Which brain the starter live lab should be written for. A machine with a signed-in coding agent
- * and no provider key can still do a real live run; writing the lab for the credential the
- * operator DOESN'T have is how a starter file becomes homework.
- */
-export function starterActorFor(env) {
-    if (!env.hasProviderKey && env.localAgents.length > 0)
-        return "local-agent";
-    return "openai-computer-use";
-}
-/**
- * The next one or two commands, in order. Deliberately SHORT: a list of twelve options is the same
- * as no guidance, and the reader here has just been handed twenty files.
- */
-export function firstRunSteps(env) {
-    const steps = [
-        {
-            command: "humanish run first-run",
-            why: "an evidence preview: no browser or model runs, no keys, no spend"
-        }
-    ];
-    const localPlatform = env.platform === "linux" && env.arch === "x64"
-        || env.platform === "darwin" && env.arch === "arm64";
-    if (localPlatform) {
-        const prerequisites = env.platform === "darwin"
-            ? "M3-or-newer Mac, native ARM64 Node, Lima 2.2+, and a supported signed-in Codex CLI"
-            : "local rootful Docker, KVM, TUN, and a supported signed-in Codex CLI";
-        steps.push({
-            command: "humanish doctor --lab local-browser",
-            why: `check the local browser study (${prerequisites}); no resources or quota used. Run \`humanish runtime setup\` to prepare it, then start your app and run \`humanish run local-browser\`; no E2B or model API key`
-        });
-        return steps;
-    }
-    const localUnavailable = env.platform === undefined
-        ? ""
-        : " Local browsers are unavailable on this host; they support Linux x64 or M3-or-newer Apple Silicon Macs.";
-    if (!env.hasE2bKey) {
-        steps.push({
-            command: "humanish keys set e2b",
-            why: `the hosted starter needs an E2B desktop.${localUnavailable}`
-        });
-        return steps;
-    }
-    if (env.hasProviderKey || env.localAgents.length > 0) {
-        const brain = env.hasProviderKey
-            ? "your provider key"
-            : `${env.localAgents[0]} (already signed in — no API key needed)`;
-        // Everything the step needs, in one line. Splitting it across two commands means the second
-        // one fails, which is the same dead end this guidance exists to remove.
-        const command = env.hasDesktopSdk
-            ? "humanish run try-live"
-            : env.installedInProject
-                ? "npm i -D @e2b/desktop && humanish run try-live"
-                // Running from an npx cache: installing only the peer here would not be found, because
-                // Node resolves it relative to humanish. Both, or neither.
-                : "npm i -D humanish @e2b/desktop && npx humanish run try-live";
-        steps.push({
-            command,
-            why: `a REAL study: one participant drives a real app in a hosted desktop, using ${brain}`
-                + (env.hasDesktopSdk ? "" : " (the desktop SDK is an optional peer, so it installs first)")
-                + (!env.hasProviderKey ? "; automatic findings analysis is skipped without OPENAI_API_KEY" : "")
-                + localUnavailable
-        });
-        return steps;
-    }
-    steps.push({
-        command: "humanish keys set openai",
-        why: "openai-computer-use needs an API key; to use a Codex or Claude Code login instead, sign in and change the lab to actors[0].type: local-agent"
-            + localUnavailable
-    });
-    return steps;
-}
-/** The block init prints after its changes. */
-export function firstRunGuidance(env) {
-    const steps = firstRunSteps(env);
-    return [
-        "",
-        "next:",
-        ...steps.flatMap((step) => [`  ${step.command}`, `      ${step.why}`])
-    ];
-}
-/** Lets init recognise its own section without rewriting a file someone else wrote. */
-export const AGENTS_SECTION_MARKER = "<!-- humanish:agents-guide -->";
-/**
- * What the NEXT coding agent needs to know about humanish in this project.
- *
- * AGENTS.md is the cross-vendor convention (agents.md) that Codex, Claude Code, Cursor and others
- * read on arrival. Increasingly the thing that ran `humanish init` was itself an agent working for
- * someone, and the agent that shows up tomorrow finds a `humanish/` directory with no idea what it
- * is for. Deliberately SHORT and command-first: an agent acts on commands, not on prose.
- */
-export function agentsSection() {
-    return [
-        "",
-        `## humanish ${AGENTS_SECTION_MARKER}`,
-        "",
-        "This project uses humanish: synthetic participants use the product and leave evidence.",
-        "",
-        "```bash",
-        "humanish doctor --lab try-live  # requirements for the selected participant and analysis",
-        "humanish lab list --json   # the studies in this project",
-        "humanish run first-run     # evidence preview only: no browser, model, keys, or spend",
-        "humanish doctor --lab local-browser  # local Docker/Firecracker + Codex-account readiness",
-        "humanish run local-browser # your loopback app; no E2B or model API key",
-        "humanish run try-live      # demo app study: E2B plus the selected participant's authentication",
-        "humanish verify --run latest --json   # is the evidence share-safe",
-        "```",
-        "",
-        "- Studies are declared in `humanish/labs/*.yaml`. Edit `try-live.yaml`'s `subject` to point at",
-        "  this project's own app once you have seen a run work.",
-        "- Configure the local study without editing YAML: `humanish init --yes --local-browser",
-        "  http://127.0.0.1:3000 --local-mission \"Complete the primary flow\"` on first setup.",
-        "- Evidence lands in gitignored `.humanish/runs/`. Never commit it, and never paste raw run",
-        "  bundles into an issue — `humanish feedback issue` produces a redacted, share-safe draft.",
-        "- `humanish tui` is a HUMAN surface and refuses to run in an agent session. Use the `--json`",
-        "  commands above instead, and tell the person you are working for that `humanish tui` exists.",
-        "- A live run spends money. `execution.caps.maxUsd` in each lab is a fail-closed ceiling; do not",
-        "  raise it without asking the person you are working for.",
-        ""
-    ].join("\n");
-}
-//# sourceMappingURL=first-run-path.js.map

package/dist/first-run-path.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"first-run-path.js","sourceRoot":"","sources":["../src/first-run-path.ts"],"names":[],"mappings":"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"}

package/dist/frame-signature.d.ts

@@ -1,24 +0,0 @@
-/**
- * A perceptual hash of a PNG frame for no-progress detection. Decodes the PNG, area-averages it to
- * a SIGNATURE_GRID x SIGNATURE_GRID grayscale grid, CONTRAST-NORMALIZES that grid, quantizes each
- * cell to SIGNATURE_LEVELS, and packs the cells into a hex string. Deterministic (no Date, no
- * random). Returns SIGNATURE_FALLBACK on any decode failure so two unreadable frames compare equal.
- *
- * Why normalization, and why this grid (#383). The original was 16x16 at 2 bits per cell with no
- * normalization. On a 1440x950 desktop that is one cell per ~90x59 px, and on a light-themed web app
- * the area-average of nearly every cell lands at the top of the range: a measured run had 93% of the
- * 256 cells pinned to level 3 and levels 0 and 1 never used at all. The hash was effectively a
- * constant, so renaming a row in a sidebar, adding a list item, or opening a small panel could not
- * move it — 22 frames across one run produced 5 distinct values, and 9 visibly different consecutive
- * frames produced ONE. The no-progress backstop read that as a stuck agent and ended a lane that was
- * a foreign key away from finishing its mission.
- *
- * Stretching each frame's own min..max across the full range before quantizing is what makes a
- * mostly-white UI use the levels it actually has, and the finer grid shrinks a cell to ~45x30 px so
- * ordinary widget-sized changes survive the averaging.
- *
- * This is still a coarse whole-frame hash and it is still only ONE input to the backstop — see the
- * corroboration rule in computer-use.ts, which is what keeps a blind frame from ending a run on its
- * own.
- */
-export declare function perceptualSignature(pngBytes: Buffer | Uint8Array): string;

package/dist/frame-signature.js

@@ -1,128 +0,0 @@
-import { PNG } from "pngjs";
-// ---------------------------------------------------------------------------
-// Perceptual signature.
-//
-// A coarse, deterministic hash of a frame for no-progress detection in the loop.
-// It is robust to small noise (a blinking cursor, a single changed clock digit)
-// because it area-averages the frame down to a 16x16 grayscale grid and then
-// quantizes each cell to 4 levels (2 bits). Two visually-identical frames produce
-// the same signature; a clearly different frame differs. It is NOT reversible to
-// the image, so exposing it (e.g. in a trace) is public-safe. On any decode
-// failure it returns a stable fallback so two unreadable frames compare equal.
-// ---------------------------------------------------------------------------
-const SIGNATURE_GRID = 32;
-const SIGNATURE_LEVELS = 16;
-const SIGNATURE_FALLBACK = "unreadable";
-/**
- * A perceptual hash of a PNG frame for no-progress detection. Decodes the PNG, area-averages it to
- * a SIGNATURE_GRID x SIGNATURE_GRID grayscale grid, CONTRAST-NORMALIZES that grid, quantizes each
- * cell to SIGNATURE_LEVELS, and packs the cells into a hex string. Deterministic (no Date, no
- * random). Returns SIGNATURE_FALLBACK on any decode failure so two unreadable frames compare equal.
- *
- * Why normalization, and why this grid (#383). The original was 16x16 at 2 bits per cell with no
- * normalization. On a 1440x950 desktop that is one cell per ~90x59 px, and on a light-themed web app
- * the area-average of nearly every cell lands at the top of the range: a measured run had 93% of the
- * 256 cells pinned to level 3 and levels 0 and 1 never used at all. The hash was effectively a
- * constant, so renaming a row in a sidebar, adding a list item, or opening a small panel could not
- * move it — 22 frames across one run produced 5 distinct values, and 9 visibly different consecutive
- * frames produced ONE. The no-progress backstop read that as a stuck agent and ended a lane that was
- * a foreign key away from finishing its mission.
- *
- * Stretching each frame's own min..max across the full range before quantizing is what makes a
- * mostly-white UI use the levels it actually has, and the finer grid shrinks a cell to ~45x30 px so
- * ordinary widget-sized changes survive the averaging.
- *
- * This is still a coarse whole-frame hash and it is still only ONE input to the backstop — see the
- * corroboration rule in computer-use.ts, which is what keeps a blind frame from ending a run on its
- * own.
- */
-export function perceptualSignature(pngBytes) {
-    let cells;
-    try {
-        const source = Buffer.isBuffer(pngBytes) ? pngBytes : Buffer.from(pngBytes);
-        if (source.length === 0)
-            return SIGNATURE_FALLBACK;
-        const decoded = PNG.sync.read(source);
-        const srcW = decoded.width;
-        const srcH = decoded.height;
-        if (!srcW || !srcH)
-            return SIGNATURE_FALLBACK;
-        cells = quantizedGrid(decoded.data, srcW, srcH);
-        return `${brightnessAnchor(decoded.data, srcW, srcH)}${packCells(cells)}`;
-    }
-    catch {
-        return SIGNATURE_FALLBACK;
-    }
-}
-/** Area-average an RGBA buffer to a grid of grayscale cells, contrast-normalized then quantized. */
-function quantizedGrid(data, srcW, srcH) {
-    const grays = [];
-    const xRatio = srcW / SIGNATURE_GRID;
-    const yRatio = srcH / SIGNATURE_GRID;
-    for (let gy = 0; gy < SIGNATURE_GRID; gy += 1) {
-        const sy0 = Math.floor(gy * yRatio);
-        const sy1 = Math.min(srcH, Math.max(sy0 + 1, Math.floor((gy + 1) * yRatio)));
-        for (let gx = 0; gx < SIGNATURE_GRID; gx += 1) {
-            const sx0 = Math.floor(gx * xRatio);
-            const sx1 = Math.min(srcW, Math.max(sx0 + 1, Math.floor((gx + 1) * xRatio)));
-            let sum = 0;
-            let n = 0;
-            for (let sy = sy0; sy < sy1; sy += 1) {
-                for (let sx = sx0; sx < sx1; sx += 1) {
-                    const si = (sy * srcW + sx) * 4;
-                    const r = data[si] ?? 0;
-                    const g = data[si + 1] ?? 0;
-                    const b = data[si + 2] ?? 0;
-                    sum += Math.round((r + g + b) / 3);
-                    n += 1;
-                }
-            }
-            grays.push(n ? Math.round(sum / n) : 0);
-        }
-    }
-    // Stretch this frame's own range across the full scale before quantizing. Without this a light UI
-    // occupies a sliver at the top of 0..255 and quantizes to a near-constant (#383).
-    //
-    // The endpoints are TRIMMED rather than the raw min/max: a handful of extreme cells must not be
-    // able to rescale the whole frame, or a blinking text cursor would rewrite every cell and read as
-    // progress forever. Trimming K cells from each end clamps that away while still preserving real
-    // structure, which occupies far more cells than K (a row of sidebar text covers dozens).
-    const sorted = [...grays].sort((a, b) => a - b);
-    const trim = Math.max(2, Math.floor(sorted.length / 256));
-    const lo = sorted[Math.min(trim, sorted.length - 1)] ?? 0;
-    const hi = sorted[Math.max(0, sorted.length - 1 - trim)] ?? 255;
-    const span = hi - lo;
-    const top = SIGNATURE_LEVELS - 1;
-    return grays.map((gray) => span <= 0 ? 0 : Math.min(top, Math.max(0, Math.round(((gray - lo) / span) * top))));
-}
-/**
- * The frame's overall brightness, coarsely quantized. Normalization deliberately discards absolute
- * level, so this is prefixed back on for the two cases where absolute level IS the change: a uniform
- * frame (an all-white blank vs an all-black screen normalize identically), and a whole-page dim such
- * as a modal overlay, which preserves relative structure while changing the whole frame. Quantized
- * coarsely so ordinary antialiasing noise cannot move it.
- */
-function brightnessAnchor(data, srcW, srcH) {
-    let sum = 0;
-    let n = 0;
-    const stride = Math.max(1, Math.floor((srcW * srcH) / 4096));
-    for (let p = 0; p < srcW * srcH; p += stride) {
-        const si = p * 4;
-        sum += ((data[si] ?? 0) + (data[si + 1] ?? 0) + (data[si + 2] ?? 0)) / 3;
-        n += 1;
-    }
-    const mean = n ? sum / n : 0;
-    return (Math.min(15, Math.floor(mean / 16))).toString(16);
-}
-/** Pack 4-bit cells (two per byte) into a compact hex string. */
-function packCells(cells) {
-    const bytes = Buffer.alloc(Math.ceil(cells.length / 2));
-    for (let i = 0; i < cells.length; i += 1) {
-        const byteIndex = i >> 1;
-        const shift = (i & 1) * 4;
-        const value = (cells[i] ?? 0) & 0xf;
-        bytes[byteIndex] = (bytes[byteIndex] ?? 0) | (value << shift);
-    }
-    return bytes.toString("hex");
-}
-//# sourceMappingURL=frame-signature.js.map

package/dist/frame-signature.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"frame-signature.js","sourceRoot":"","sources":["../src/frame-signature.ts"],"names":[],"mappings":"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"}

package/dist/guest-bootstrap.d.ts

@@ -1,55 +0,0 @@
-import { type DesktopRecordingConfig } from "./desktop-recording-types.js";
-import type { Duplex } from "node:stream";
-import { type BrowserControlIdentity } from "./browser-control-protocol.js";
-import { createBrowserControlClient } from "./browser-control-client.js";
-import { type GuestMediaConfig } from "./guest-media-config.js";
-export declare const GUEST_BOOTSTRAP_VERSION = 1;
-export declare const GUEST_BOOTSTRAP_LIMITS: Readonly<{
-    bytes: number;
-    readyBytes: 1024;
-    initialUrlBytes: 65536;
-    admissionMs: 5000;
-    readyMs: 35000;
-    navigationMs: 30000;
-    paintMs: 5000;
-    connectMs: 3000;
-    port: 5251;
-}>;
-/** Same entry authority as the local desktop's opaque app-port forward. */
-export declare function validateGuestInitialUrl(value: string): string;
-export declare function guestReadyTimeoutMs(initialUrl?: string): number;
-export declare function encodeGuestBootstrap(identity: BrowserControlIdentity, ready?: boolean, initialUrl?: string, media?: GuestMediaConfig, recording?: DesktopRecordingConfig): Buffer;
-export declare function parseGuestBootstrap(bytes: Buffer, revision: string, ready?: boolean): BrowserControlIdentity;
-/** Own the first frame and continue refusing early bytes until synchronous handoff. */
-export declare class GuestBootstrapReader {
-    private readonly stream;
-    private readonly revision;
-    private readonly signal;
-    private readonly ready;
-    private readonly onFailure;
-    readonly identity: Promise<BrowserControlIdentity>;
-    initialUrl: string | undefined;
-    media: GuestMediaConfig | undefined;
-    recording: DesktopRecordingConfig | undefined;
-    private resolve;
-    private reject;
-    private readonly header;
-    private headerUsed;
-    private body;
-    private used;
-    private admitted;
-    private terminal;
-    private timer;
-    constructor(stream: Duplex, revision: string, signal: AbortSignal, ready?: boolean, onFailure?: () => void, readyTimeoutMs?: number);
-    private data;
-    private error;
-    private end;
-    private abort;
-    private release;
-    private fail;
-    /** Must be followed synchronously by installing the sole next stream owner. */
-    handoff(): void;
-    close(): void;
-}
-/** Fixed preface on an already acquired Firecracker stream; no path discovery/retry. */
-export declare function connectGuestBootstrap(stream: Duplex, identity: BrowserControlIdentity, signal: AbortSignal, initialUrl?: string, media?: GuestMediaConfig, recording?: DesktopRecordingConfig): Promise<ReturnType<typeof createBrowserControlClient>>;

package/dist/guest-bootstrap.js

@@ -1,285 +0,0 @@
-import { desktopRecordingConfigSchema } from "./desktop-recording-types.js";
-import { validateBrowserControlIdentity, sameBrowserControlIdentity } from "./browser-control-protocol.js";
-import { CuaExecutorError } from "./cua-executor-error.js";
-import { createBrowserControlClient } from "./browser-control-client.js";
-import { guestMediaConfigSchema } from "./guest-media-config.js";
-export const GUEST_BOOTSTRAP_VERSION = 1;
-export const GUEST_BOOTSTRAP_LIMITS = Object.freeze({ bytes: 65_536 + 1024, readyBytes: 1024, initialUrlBytes: 65_536,
-    admissionMs: 5000, readyMs: 35_000, navigationMs: 30_000, paintMs: 5000, connectMs: 3000, port: 5251 });
-const refused = () => new CuaExecutorError("protocol_mismatch", "not_dispatched");
-/** Same entry authority as the local desktop's opaque app-port forward. */
-export function validateGuestInitialUrl(value) {
-    try {
-        if (typeof value !== "string")
-            throw refused();
-        const url = new URL(value);
-        if (!["http:", "https:"].includes(url.protocol) || !["localhost", "127.0.0.1"].includes(url.hostname)
-            || url.username || url.password || !/^\d+$/.test(url.port) || Number(url.port) < 1024
-            || Buffer.byteLength(url.href) > GUEST_BOOTSTRAP_LIMITS.initialUrlBytes)
-            throw refused();
-        return url.href;
-    }
-    catch {
-        throw refused();
-    }
-}
-export function guestReadyTimeoutMs(initialUrl) {
-    return GUEST_BOOTSTRAP_LIMITS.readyMs + (initialUrl === undefined ? 0 : GUEST_BOOTSTRAP_LIMITS.navigationMs + GUEST_BOOTSTRAP_LIMITS.paintMs);
-}
-function canonical(identity, ready, initialUrl, media, recording) {
-    const { generation, challenge, runtimeRevision } = validateBrowserControlIdentity(identity);
-    const fixed = { generation, challenge, runtimeRevision };
-    if (initialUrl !== undefined && (ready || validateGuestInitialUrl(initialUrl) !== initialUrl))
-        throw refused();
-    if (media !== undefined && (ready || !guestMediaConfigSchema.safeParse(media).success))
-        throw refused();
-    if (recording !== undefined && (ready || !desktopRecordingConfigSchema.safeParse(recording).success))
-        throw refused();
-    return JSON.stringify(ready ? { version: 1, ready: true, identity: fixed }
-        : { version: 1, identity: fixed, ...(initialUrl === undefined ? {} : { initialUrl }), ...(media === undefined ? {} : { media: guestMediaConfigSchema.parse(media) }), ...(recording === undefined ? {} : { recording: desktopRecordingConfigSchema.parse(recording) }) });
-}
-export function encodeGuestBootstrap(identity, ready = false, initialUrl, media, recording) {
-    const bytes = Buffer.from(canonical(identity, ready, initialUrl, media, recording));
-    if (bytes.length > (ready ? GUEST_BOOTSTRAP_LIMITS.readyBytes : GUEST_BOOTSTRAP_LIMITS.bytes))
-        throw refused();
-    const frame = Buffer.alloc(4 + bytes.length);
-    frame.writeUInt32BE(bytes.length);
-    bytes.copy(frame, 4);
-    return frame;
-}
-export function parseGuestBootstrap(bytes, revision, ready = false) {
-    return parseBootstrap(bytes, revision, ready).identity;
-}
-function parseBootstrap(bytes, revision, ready) {
-    if (!bytes.length || bytes.length > (ready ? GUEST_BOOTSTRAP_LIMITS.readyBytes : GUEST_BOOTSTRAP_LIMITS.bytes) || bytes.some(byte => byte > 127))
-        throw refused();
-    try {
-        const value = JSON.parse(bytes.toString("ascii"));
-        if (typeof value !== "object" || value === null || !("identity" in value))
-            throw refused();
-        const identity = validateBrowserControlIdentity(value.identity);
-        const initialUrl = "initialUrl" in value ? value.initialUrl : undefined;
-        const media = "media" in value ? guestMediaConfigSchema.parse(value.media) : undefined;
-        const recording = "recording" in value ? desktopRecordingConfigSchema.parse(value.recording) : undefined;
-        if (initialUrl !== undefined && typeof initialUrl !== "string")
-            throw refused();
-        if (identity.runtimeRevision !== revision || canonical(identity, ready, initialUrl, media, recording) !== bytes.toString("ascii"))
-            throw refused();
-        return { identity, ...(initialUrl === undefined ? {} : { initialUrl }), ...(media === undefined ? {} : { media }), ...(recording === undefined ? {} : { recording }) };
-    }
-    catch {
-        throw refused();
-    }
-}
-/** Own the first frame and continue refusing early bytes until synchronous handoff. */
-export class GuestBootstrapReader {
-    stream;
-    revision;
-    signal;
-    ready;
-    onFailure;
-    identity;
-    initialUrl;
-    media;
-    recording;
-    resolve;
-    reject;
-    header = Buffer.alloc(4);
-    headerUsed = 0;
-    body;
-    used = 0;
-    admitted = false;
-    terminal = false;
-    timer;
-    constructor(stream, revision, signal, ready = false, onFailure = () => { }, readyTimeoutMs = GUEST_BOOTSTRAP_LIMITS.readyMs) {
-        this.stream = stream;
-        this.revision = revision;
-        this.signal = signal;
-        this.ready = ready;
-        this.onFailure = onFailure;
-        this.identity = new Promise((resolve, reject) => { this.resolve = resolve; this.reject = reject; });
-        // A later factory rejection must not leave the admission rejection unconsumed.
-        void this.identity.catch(() => { });
-        this.timer = setTimeout(() => this.fail("deadline_exceeded"), ready ? readyTimeoutMs : GUEST_BOOTSTRAP_LIMITS.admissionMs);
-        stream.on("error", this.error);
-        stream.on("close", this.end);
-        stream.on("end", this.end);
-        stream.on("data", this.data);
-        signal.addEventListener("abort", this.abort, { once: true });
-        if (signal.aborted || stream.destroyed || stream.readableEnded || stream.writableEnded || stream.readableObjectMode || stream.writableObjectMode)
-            this.abort();
-        else
-            stream.resume();
-    }
-    data = (value) => {
-        if (this.terminal)
-            return;
-        if (!Buffer.isBuffer(value) || this.admitted) {
-            this.fail();
-            return;
-        }
-        let offset = 0;
-        if (!this.body) {
-            const count = Math.min(4 - this.headerUsed, value.length);
-            value.copy(this.header, this.headerUsed, 0, count);
-            this.headerUsed += count;
-            offset += count;
-            if (this.headerUsed < 4)
-                return;
-            const length = this.header.readUInt32BE(0);
-            if (!length || length > (this.ready ? GUEST_BOOTSTRAP_LIMITS.readyBytes : GUEST_BOOTSTRAP_LIMITS.bytes)) {
-                this.fail();
-                return;
-            }
-            this.body = Buffer.alloc(length);
-        }
-        const count = Math.min(value.length - offset, this.body.length - this.used);
-        value.copy(this.body, this.used, offset, offset + count);
-        this.used += count;
-        offset += count;
-        if (offset !== value.length) {
-            this.fail();
-            return;
-        }
-        if (this.used === this.body.length) {
-            try {
-                const parsed = parseBootstrap(this.body, this.revision, this.ready);
-                this.initialUrl = parsed.initialUrl;
-                this.media = parsed.media;
-                this.recording = parsed.recording;
-                this.admitted = true;
-                clearTimeout(this.timer);
-                this.resolve(parsed.identity);
-            }
-            catch {
-                this.fail();
-            }
-        }
-    };
-    error = () => this.fail("transport_failed");
-    end = () => this.fail("transport_failed");
-    abort = () => this.fail("session_revoked");
-    release() {
-        clearTimeout(this.timer);
-        this.stream.off("data", this.data);
-        this.stream.off("end", this.end);
-        this.stream.off("close", this.end);
-        this.signal.removeEventListener("abort", this.abort);
-        // Retain a safe listener until queued native error/close events have drained.
-        const stream = this.stream, error = this.error;
-        const off = () => { stream.off("error", error); stream.off("close", off); };
-        stream.once("close", off);
-        if (stream.closed)
-            setImmediate(off);
-    }
-    fail(code = "protocol_mismatch") {
-        if (this.terminal)
-            return;
-        this.terminal = true;
-        this.release();
-        this.reject(new CuaExecutorError(code, "not_dispatched"));
-        this.stream.destroy();
-        this.onFailure();
-    }
-    /** Must be followed synchronously by installing the sole next stream owner. */
-    handoff() {
-        if (this.terminal || !this.admitted || this.signal.aborted || this.stream.destroyed || this.stream.readableLength !== 0)
-            throw refused();
-        this.stream.pause();
-        this.terminal = true;
-        this.release();
-    }
-    close() { this.fail("session_revoked"); }
-}
-/** Fixed preface on an already acquired Firecracker stream; no path discovery/retry. */
-export async function connectGuestBootstrap(stream, identity, signal, initialUrl, media, recording) {
-    validateBrowserControlIdentity(identity);
-    const request = encodeGuestBootstrap(identity, false, initialUrl, media, recording);
-    await new Promise((resolve, reject) => {
-        let bytes = Buffer.alloc(0), done = false;
-        const timer = setTimeout(() => finish(new CuaExecutorError("deadline_exceeded", "not_dispatched")), GUEST_BOOTSTRAP_LIMITS.connectMs);
-        const finish = (error) => {
-            if (done)
-                return;
-            done = true;
-            clearTimeout(timer);
-            stream.pause();
-            stream.off("data", data);
-            stream.off("end", end);
-            stream.off("close", end);
-            signal.removeEventListener("abort", abort);
-            const release = () => { stream.off("error", end); stream.off("close", release); };
-            stream.once("close", release);
-            if (stream.closed)
-                setImmediate(release);
-            if (error) {
-                stream.destroy();
-                reject(error);
-            }
-            else
-                resolve();
-        };
-        const end = () => {
-            if (done)
-                stream.destroy();
-            finish(new CuaExecutorError("transport_failed", "not_dispatched"));
-        };
-        const abort = () => finish(new CuaExecutorError("session_revoked", "not_dispatched"));
-        const data = (chunk) => {
-            if (!Buffer.isBuffer(chunk) || bytes.length + chunk.length > 64 + 1028) {
-                finish(refused());
-                return;
-            }
-            bytes = Buffer.concat([bytes, chunk]);
-            const newline = bytes.indexOf(10);
-            if (newline < 0) {
-                if (bytes.length > 64)
-                    finish(refused());
-                return;
-            }
-            const line = bytes.subarray(0, newline + 1).toString("ascii");
-            if (newline >= 64 || bytes.subarray(0, newline + 1).some(byte => byte > 127)
-                || !/^OK [1-9][0-9]{0,9}\n$/.test(line) || Number(line.slice(3)) > 0xffffffff) {
-                finish(refused());
-                return;
-            }
-            const tail = bytes.subarray(newline + 1);
-            if (tail.length) {
-                stream.pause();
-                stream.unshift(tail);
-            }
-            finish();
-        };
-        stream.on("error", end);
-        stream.on("end", end);
-        stream.on("close", end);
-        stream.on("data", data);
-        signal.addEventListener("abort", abort, { once: true });
-        if (signal.aborted || stream.destroyed)
-            abort();
-        else {
-            stream.resume();
-            stream.write("CONNECT 5251\n", error => { if (error)
-                end(); });
-        }
-    });
-    const reader = new GuestBootstrapReader(stream, identity.runtimeRevision, signal, true, undefined, guestReadyTimeoutMs(initialUrl));
-    try {
-        stream.write(request, error => { if (error)
-            reader.close(); });
-        const actual = await reader.identity;
-        if (!sameBrowserControlIdentity(actual, identity))
-            throw refused();
-        reader.handoff();
-    }
-    catch (error) {
-        reader.close();
-        stream.destroy();
-        throw error;
-    }
-    const client = createBrowserControlClient({ transport: stream, identity,
-        ...(media?.microphone?.source === "speech" ? { speechEnabled: true } : {}) });
-    stream.resume();
-    return client;
-}
-//# sourceMappingURL=guest-bootstrap.js.map