humanish 0.105.0 → 0.106.0

package/dist/routes/shared-world/handoff.js

@@ -0,0 +1,348 @@
+// The external-public plane's host-first handoff. The host seat opens a lobby; each follower waits
+// for the host's lobby code, read from the host's URL, narration or screen, and then joins with it.
+// A follower fails closed without opening if the host never yields a code within the deadline.
+//
+// TEMPORARY SHIM (tracked by #296): this CDP URL-relay handoff — reading the host's /lobby/CODE off
+// its own browser and threading it into the follower missions — is a temporary coordination shim.
+// It is to be augmented/replaced by the actor message bus (fake SMS/email invite) in #297: the
+// human-realistic version is the HOST SENDING the invite link and followers RECEIVING and tapping
+// it, rather than the orchestrator relaying the code out-of-band.
+import { commandDigestOf } from "../../subject/state.js";
+import { toErrorMessage } from "../../evidence/redaction.js";
+import { inboxRecipientFor, participantHasInboxRecipient, } from "../computer-use/participant-desktop.js";
+import { withInboxMission } from "../computer-use/participant-prompt.js";
+import { runCuaParticipant } from "../computer-use/lanes.js";
+import { extractLobbyCode, extractLobbyCodeFromNarration } from "./lobby-code.js";
+import { hostOriginDigest } from "./provenance.js";
+import { makeBlockedFollowerOutcome, withLobbyCodeMission, } from "./seats.js";
+// The FLOOR for the host-first handoff barrier deadline (ms). The host seat must surface a
+// shared-session (/lobby/CODE) URL within the deadline or the run fails closed and no follower
+// opens. The effective deadline SCALES with the per-seat run budget (execution.timeoutMs): a fixed
+// 2 min is too tight for a real create-a-lobby flow on a mobile-layout seat once you subtract the
+// seat's own desktop provisioning — the host reaches /lobby/CODE, but after the followers already
+// gave up. So use max(FLOOR, 40% of the budget), capped at the budget. The latch resolves the
+// instant the host actually reaches /lobby, so a generous ceiling only affects the fail-closed case.
+const DEFAULT_HANDOFF_DEADLINE_MS = 120_000;
+const HANDOFF_DEADLINE_BUDGET_FRACTION = 0.4;
+// Per-seat runaway backstop for the vision-off-frame lobby-code read (used by the host to LATCH the
+// handoff code, and by each follower to independently OBSERVE its own code for the convergence proof):
+// at most this many single-frame reads before the seat is assumed to be somewhere without a code. Each
+// reader stops the instant it has what it needs, so in practice only a handful fire (a seat reaches its
+// /lobby within a few turns). NOTE: these reads are out-of-band OpenAI calls (external-public route
+// only) and are NOT counted against execution.caps.maxUsd — this hard cap is what bounds their spend
+// instead (each read is one cheap single-frame OCR call). If this route ever runs under a strict
+// budget, fold the estimate in.
+const MAX_LOBBY_CODE_VISION_READS = 30;
+// Idle/no-progress backstop for the HOST lane specifically (default is 6/8). The host legitimately sits
+// on an unchanging waiting-room screen while followers provision and join; it must not give up first.
+const HOST_WAIT_IDLE_STEPS = 80;
+const FOLLOWER_WAIT_IDLE_STEPS = 40;
+/** A minimal resolve-once latch for the host-first handoff barrier. */
+function deferred() {
+    let resolve;
+    let reject;
+    let done = false;
+    const promise = new Promise((res, rej) => {
+        resolve = (value) => {
+            if (!done) {
+                done = true;
+                res(value);
+            }
+        };
+        reject = (reason) => {
+            if (!done) {
+                done = true;
+                rej(reason);
+            }
+        };
+    });
+    return { promise, resolve, reject, settled: () => done };
+}
+/** Marker error the host-first barrier rejects with when the deadline elapses (fail-closed). */
+class HandoffTimeoutError extends Error {
+    constructor(deadlineMs) {
+        super(`the host never produced a /lobby/CODE URL within the ${deadlineMs}ms handoff deadline`);
+        this.name = "HandoffTimeoutError";
+    }
+}
+/**
+ * The handoff latch, its deadline and what each seat observed. The latched code and observed URLs
+ * are runtime-only and land in persisted METADATA only as digests (origin + convergence). (The code
+ * is a shareable game code, not a secret, and it still renders in the host's screenshots, which are
+ * full-fidelity unless redactScreenshots is set — the digesting is about narration/URL metadata.)
+ */
+export class LobbyHandoff {
+    // Per-lane runtime-only observed state (never persisted raw): the last observed URL and the last
+    // observed /lobby/CODE per seat, fed by onObservedUrl. The URL is digested to ORIGIN for each seat's
+    // routeHostDigest (no code leaks); the codes drive the cross-seat lobby-convergence digest.
+    observedFinalUrls;
+    observedLobbyCodes;
+    latchedLobbyCode;
+    /** A follower gave up because the deadline passed. */
+    timedOut = false;
+    /** Why the host seat ended without producing a lobby code. */
+    hostFailure;
+    deadlineMs;
+    lobbyCodeLatch = deferred();
+    scrubKnownValues;
+    readLobbyCode;
+    openaiApiKey;
+    deadline;
+    deadlineTimer;
+    constructor(options) {
+        this.observedFinalUrls = new Array(options.participantCount);
+        this.observedLobbyCodes = new Array(options.participantCount);
+        this.deadlineMs =
+            options.deadlineMs ??
+                Math.min(options.timeoutMs, Math.max(DEFAULT_HANDOFF_DEADLINE_MS, Math.floor(options.timeoutMs * HANDOFF_DEADLINE_BUDGET_FRACTION)));
+        this.scrubKnownValues = options.scrubKnownValues;
+        this.readLobbyCode = options.readLobbyCode;
+        this.openaiApiKey = options.openaiApiKey;
+    }
+    /**
+     * Scrubs the latched lobby CODE from ANY persisted narration once the host resolves it (the
+     * 6-char code has no detectable secret shape, so shape-only redaction cannot catch it).
+     */
+    scrub = (text) => {
+        const base = this.scrubKnownValues(text);
+        return this.latchedLobbyCode && this.latchedLobbyCode.length > 0
+            ? base.split(this.latchedLobbyCode).join("[REDACTED_LOBBY_CODE]")
+            : base;
+    };
+    /** Starts the deadline the followers wait against. */
+    startDeadline() {
+        this.deadline = new Promise((_resolve, reject) => {
+            this.deadlineTimer = setTimeout(() => reject(new HandoffTimeoutError(this.deadlineMs)), this.deadlineMs);
+        });
+        this.deadline.catch(() => undefined); // never an unhandled rejection
+    }
+    stopDeadline() {
+        if (this.deadlineTimer) {
+            clearTimeout(this.deadlineTimer);
+            this.deadlineTimer = undefined;
+        }
+    }
+    // Resolve the host->follower handoff latch from WHICHEVER path sees the code first (CDP url-read,
+    // host narration, or vision-off-frame). Idempotent: only the first code wins, and it is also stashed
+    // as latchedLobbyCode so it gets scrubbed from any later narration.
+    latchLobbyCode(code, participantIndex) {
+        if (this.latchedLobbyCode !== undefined)
+            return;
+        this.observedLobbyCodes[participantIndex] = code;
+        this.latchedLobbyCode = code;
+        this.stopDeadline();
+        this.lobbyCodeLatch.resolve(code);
+    }
+    // Build an onScreenshot handler that vision-reads the lobby code off THIS seat's own frame (the
+    // CDP-independent observation). `done()` short-circuits once this seat has what it needs (the host
+    // once latched; a follower once it has recorded its own observed code), `onCode` records/latches the
+    // result. One read in flight at a time, bounded by MAX_LOBBY_CODE_VISION_READS so a seat that never
+    // reaches a lobby can't rack up unbounded calls (fire-and-forget; the loop never awaits it).
+    makeLobbyCodeVisionReader(done, onCode) {
+        let inFlight = false;
+        let reads = 0;
+        return (frame) => {
+            if (done() || inFlight || reads >= MAX_LOBBY_CODE_VISION_READS)
+                return;
+            inFlight = true;
+            reads += 1;
+            void this.readLobbyCode(frame, this.openaiApiKey)
+                .then((code) => {
+                if (code !== undefined && !done())
+                    onCode(code);
+            })
+                .catch(() => undefined)
+                .finally(() => {
+                inFlight = false;
+            });
+        };
+    }
+    makeObservedUrl(participantIndex, isHost) {
+        return (url) => {
+            if (typeof url !== "string" || url.length === 0)
+                return;
+            this.observedFinalUrls[participantIndex] = url; // runtime-only; digested to origin, never persisted raw
+            const code = extractLobbyCode(url);
+            if (code !== undefined) {
+                this.observedLobbyCodes[participantIndex] = code;
+                if (isHost)
+                    this.latchLobbyCode(code, participantIndex);
+            }
+        };
+    }
+    /** Resolves with the host's code, or rejects when the host ends without one or the deadline passes. */
+    waitForHostCode() {
+        return Promise.race([this.lobbyCodeLatch.promise, this.deadline]);
+    }
+    /** Releases waiting followers to fail closed when the host ended without a code. */
+    releaseFollowersIfUnlatched(outcome) {
+        if (!this.lobbyCodeLatch.settled()) {
+            const reason = outcome?.sessionError ??
+                outcome?.session?.reason ??
+                "no terminal host outcome was recorded";
+            this.hostFailure = this.scrub(`Host participant ended before producing a lobby URL: ${reason}`);
+            this.lobbyCodeLatch.reject(new Error(this.hostFailure));
+        }
+    }
+    /** The digest-only convergence proofs over what the seats observed. */
+    convergence(declaredOriginDigest) {
+        // Observed-origin convergence proof (blocker 2): the convergence claim is about what the seats
+        // OBSERVED, not what was DECLARED. Digest each observing seat's origin and require they AGREE on
+        // ONE — that agreement IS the convergence proof and becomes plane.publicOriginDigest. A normal
+        // cross-origin redirect (declared apex -> observed www) is therefore tolerated: the seats still
+        // converge on ONE observed origin. Leave it undefined (verify fails closed) only if the seats did
+        // not converge on a single observed origin (or none observed one).
+        const observedOriginDigests = this.observedFinalUrls
+            .filter((url) => typeof url === "string" && url.length > 0)
+            .map((url) => hostOriginDigest(url));
+        const distinctObservedOrigins = new Set(observedOriginDigests);
+        const publicOriginDigest = distinctObservedOrigins.size === 1
+            ? [...distinctObservedOrigins][0]
+            : // NOTHING observed (e.g. a handoff-timeout run where no seat ever navigated): fall back to the
+                // DECLARED origin so a FAILED run's bundle stays structurally valid (every seat's route then
+                // digests to the declared origin too). The run still fails closed for its own reason (HANDOFF_
+                // TIMEOUT / no lobby convergence / no overlap-on-pass). GENUINE divergence (≥2 distinct observed
+                // origins) leaves it undefined so verify fails closed on the non-convergence.
+                distinctObservedOrigins.size === 0
+                    ? declaredOriginDigest
+                    : undefined;
+        // Lobby-convergence proof: a digest of the shared /lobby/CODE path iff EVERY seat converged on the
+        // SAME code (a follower stuck on "/" yields no code → no false convergence). Digest-only. NOTE:
+        // observedLobbyCodes may be a SPARSE array (a seat that never observed a code leaves a hole), and
+        // Array.prototype.every SKIPS holes — so count the DEFINED codes explicitly, never rely on every().
+        const definedCodes = this.observedLobbyCodes.filter((code) => code !== undefined);
+        const distinctCodes = new Set(definedCodes);
+        const lobbyConvergenceDigest = distinctCodes.size === 1 && definedCodes.length === this.observedLobbyCodes.length
+            ? commandDigestOf(`/lobby/${[...distinctCodes][0]}`)
+            : undefined;
+        return { publicOriginDigest, lobbyConvergenceDigest };
+    }
+}
+// Adopter-hosted inbox (#387): the persona is told its address and inbox URL on THIS plane.
+function withParticipantInbox(spec, inbox) {
+    return inbox && participantHasInboxRecipient(inbox.email, spec.planned.id)
+        ? withInboxMission(spec, inbox.inboxUrl, inboxRecipientFor(inbox.email, spec.planned.id)?.address)
+        : spec;
+}
+// The HOST lane (which yields the /lobby/CODE the followers wait on) runs on its OWN dedicated
+// slot, and the FOLLOWERS run through a bounded pool of size concurrency-1 (blockers 1 & 4):
+// followers block on the host's code while holding a worker slot, so if the host lane were
+// scheduled INSIDE the same bounded pool it could be starved (never scheduled among the first
+// `concurrency` workers) and the run would die with a spurious HANDOFF_TIMEOUT (e.g. lanes
+// [p2,p3,host] with concurrency 2). Giving the host its own slot, started IMMEDIATELY and OUTSIDE
+// the follower pool, guarantees it is ALWAYS schedulable regardless of its roster position or of
+// concurrency vs lane count — while total in-flight paid desktops stay ≤ the declared concurrency
+// (host + up to concurrency-1 followers), preserving the spend cap.
+export async function runHost(handoff, deps, spec, participantIndex) {
+    const onObservedUrl = handoff.makeObservedUrl(participantIndex, true);
+    // CDP-INDEPENDENT handoff paths (the E2B-desktop CDP url-read the onObservedUrl path relies on is
+    // unreliable in practice). Two backups, both resolving the SAME latch; whichever sees the code first
+    // wins, all digest-only:
+    //   (1) onMessage — scan the host's own narration IF it happens to state the lobby URL; and
+    //   (2) onScreenshot — vision-read the code straight off the host's waiting-room frame. This is the
+    //       robust one: the code is rendered on screen even when CDP fails AND when the host never
+    //       narrates it, and — crucially — the host is NOT asked to announce anything, so it keeps
+    //       running (create -> wait for players -> Start -> play) instead of ending on a stray message.
+    const onMessage = (text) => {
+        if (handoff.latchedLobbyCode !== undefined)
+            return;
+        const code = extractLobbyCodeFromNarration(text);
+        if (code !== undefined)
+            handoff.latchLobbyCode(code, participantIndex);
+    };
+    // Vision-read the host's waiting-room frame and LATCH the code for the followers (stops once latched).
+    const onScreenshot = handoff.makeLobbyCodeVisionReader(() => handoff.latchedLobbyCode !== undefined, (code) => handoff.latchLobbyCode(code, participantIndex));
+    // The host's job includes a long LEGITIMATE idle wait — sitting in the waiting room while the
+    // followers provision their own desktops and walk the Join flow (easily 15-30 turns of an
+    // unchanging "waiting for players" screen). At the default idle backstop (6) the host would give up
+    // before anyone arrives, orphaning the lobby (exactly the earlier failure). Raise the host's idle /
+    // no-progress tolerance so it waits patiently; the per-seat timeout still bounds a truly stuck host.
+    const hostSpec = {
+        ...withParticipantInbox(spec, deps.inbox),
+        backstop: {
+            idleSteps: spec.backstop?.idleSteps ?? HOST_WAIT_IDLE_STEPS,
+            noProgressSteps: spec.backstop?.noProgressSteps ?? HOST_WAIT_IDLE_STEPS,
+        },
+    };
+    const startedAt = deps.now();
+    let outcome;
+    try {
+        outcome = await runCuaParticipant(hostSpec, {
+            ...deps.runDeps,
+            appUrl: deps.publicAppUrl,
+            onObservedUrl,
+            onMessage,
+            onScreenshot,
+        });
+    }
+    finally {
+        // If the host finished without ever surfacing a code, release followers to fail closed
+        // immediately rather than wait the full deadline (a no-op if it already resolved).
+        handoff.releaseFollowersIfUnlatched(outcome);
+    }
+    const endedAt = deps.now();
+    return {
+        spec,
+        outcome,
+        startedAt,
+        endedAt,
+        route: handoff.observedFinalUrls[participantIndex] ?? deps.publicAppUrl,
+    };
+}
+export async function runFollower(handoff, deps, spec, participantIndex) {
+    const onObservedUrl = handoff.makeObservedUrl(participantIndex, false);
+    // FOLLOWER: do NOT compose a mission or open the target until the host yields a lobby code.
+    let code;
+    try {
+        code = await handoff.waitForHostCode();
+    }
+    catch (error) {
+        // An ended host is not a deadline expiry. Preserve its actual failure.
+        const timedOut = error instanceof HandoffTimeoutError;
+        handoff.timedOut ||= timedOut;
+        const reason = handoff.scrub(toErrorMessage(error));
+        const at = deps.now();
+        return {
+            spec,
+            outcome: makeBlockedFollowerOutcome(spec, reason, timedOut),
+            startedAt: at,
+            endedAt: at,
+            route: deps.publicAppUrl,
+        };
+    }
+    // Followers also idle-wait — in the waiting room until the host starts, and between rounds. Raise
+    // their idle backstop too (less than the host's: they wait less), so a follower that joins ahead of
+    // the other does not give up before the game begins. Per-seat timeout still bounds a stuck follower.
+    const followerSpec = {
+        ...withLobbyCodeMission(withParticipantInbox(spec, deps.inbox), code),
+        backstop: {
+            idleSteps: spec.backstop?.idleSteps ?? FOLLOWER_WAIT_IDLE_STEPS,
+            noProgressSteps: spec.backstop?.noProgressSteps ?? FOLLOWER_WAIT_IDLE_STEPS,
+        },
+    };
+    // Independently OBSERVE this follower's own lobby code by vision-reading its waiting-room frame,
+    // and record it for the cross-seat convergence proof. This does NOT latch anything (followers gate
+    // on the HOST's code, not their own) — it just fills this seat's observedLobbyCodes slot from a
+    // reliable signal instead of the flaky CDP url-read, so lobbyConvergenceDigest can prove all seats
+    // reached the SAME /lobby/CODE. If a follower somehow joined a DIFFERENT lobby, it reads a different
+    // code and convergence correctly fails (no false proof); if it never reads one, the seat stays a
+    // hole and convergence is honestly "not observed" for that seat.
+    const onScreenshot = handoff.makeLobbyCodeVisionReader(() => handoff.observedLobbyCodes[participantIndex] !== undefined, (observed) => {
+        handoff.observedLobbyCodes[participantIndex] = observed;
+    });
+    const startedAt = deps.now();
+    const outcome = await runCuaParticipant(followerSpec, {
+        ...deps.runDeps,
+        appUrl: deps.publicAppUrl,
+        onObservedUrl,
+        onScreenshot,
+    });
+    const endedAt = deps.now();
+    return {
+        spec,
+        outcome,
+        startedAt,
+        endedAt,
+        route: handoff.observedFinalUrls[participantIndex] ?? deps.publicAppUrl,
+    };
+}

package/dist/routes/shared-world/lobby-code.d.ts

@@ -0,0 +1,25 @@
+/** Extract the shared-session CODE from a (runtime-only) observed URL, or undefined. Exported for the
+ *  handoff regex table test — pure, no side effects, never persists its input. */
+export declare function extractLobbyCode(url: string | undefined): string | undefined;
+export declare function extractLobbyCodeFromNarration(text: string | undefined): string | undefined;
+/** Pull the assistant's plain text out of an OpenAI Responses API body (`output_text` convenience
+ *  field, else the concatenated `output[].content[].text`). Tolerant of shape drift; pure. */
+export declare function extractResponsesOutputText(parsed: unknown): string | undefined;
+/** Parse a vision reply into a lobby CODE. PRECISION-FIRST: accept ONLY when the whole reply IS the
+ *  six-character code, or when it echoes an explicit /lobby/CODE — never a bare 6-letter token buried in
+ *  prose (e.g. "I see a home SCREEN"), because a wrong latch fails the entire run, whereas a miss just
+ *  retries on the next frame while the host keeps waiting. NONE (the instructed "no code" reply) is
+ *  rejected. Pure. */
+export declare function parseLobbyCodeReply(reply: string | undefined): string | undefined;
+export interface ReadLobbyCodeOptions {
+    model?: string;
+    endpoint?: string;
+    fetchFn?: typeof fetch;
+    signal?: AbortSignal;
+}
+/**
+ * Vision-read a lobby CODE straight off a host waiting-room FRAME (the robust, CDP-independent handoff
+ * relay). Fail-soft: any network/HTTP/parse problem returns undefined so the caller simply retries on
+ * the next frame. The frame is runtime-only; only the extracted code is used (as a digest downstream).
+ */
+export declare function readLobbyCodeFromFrame(frame: Buffer, apiKey: string, options?: ReadLobbyCodeOptions): Promise<string | undefined>;

package/dist/routes/shared-world/lobby-code.js

@@ -0,0 +1,152 @@
+// Reads a lobby code (the /lobby/CODE path segment) from a URL, from a seat's narration or, through
+// a vision model call, from a seat's screenshot. The external-public plane uses it to hand the
+// host's lobby to the followers.
+import { OPENAI_RESPONSES_URL } from "../../actors/openai-endpoint.js";
+/**
+ * The lobby-trivia (and general "/lobby/CODE") shared-session URL matcher. A code is exactly 6 chars of
+ * the [A-Z2-9] class; a locale prefix (/en/lobby/…) and a query/hash suffix are tolerated. RUNTIME-ONLY
+ * input (a live location.href); only the extracted CODE is used, and it lands only as a digest.
+ */
+const LOBBY_CODE_PATTERN = /\/lobby\/([A-Z2-9]{6})(?:$|[/?#])/;
+/** Extract the shared-session CODE from a (runtime-only) observed URL, or undefined. Exported for the
+ *  handoff regex table test — pure, no side effects, never persists its input. */
+export function extractLobbyCode(url) {
+    if (typeof url !== "string")
+        return undefined;
+    const match = url.match(LOBBY_CODE_PATTERN);
+    return match ? match[1] : undefined;
+}
+/**
+ * Extract a lobby CODE from free-form ACTOR NARRATION (the host's reasoning/message where it states
+ * the lobby URL it sees), where the /lobby/CODE is followed by arbitrary prose (a space, backtick,
+ * newline) rather than end-of-string or /?# — so the strict LOBBY_CODE_PATTERN would miss it. Uses a
+ * negative-lookahead boundary (exactly 6 code chars). This is the CDP-INDEPENDENT handoff path: the
+ * host reads the code on screen and states it, and this reads it from the model's own text. Pure;
+ * input is runtime-only; only the code is used (as a digest).
+ */
+const LOBBY_CODE_IN_TEXT = /\/lobby\/([A-Z2-9]{6})(?![A-Z2-9])/;
+export function extractLobbyCodeFromNarration(text) {
+    if (typeof text !== "string")
+        return undefined;
+    const inUrl = text.match(LOBBY_CODE_IN_TEXT);
+    if (inUrl)
+        return inUrl[1];
+    // Fallback: an explicitly-labeled bare code (e.g. "LOBBY_CODE=ABC123"), which the host may state
+    // if it copied the code rather than the URL. The label is matched case-insensitively, but the CODE
+    // itself must be UPPERCASE [A-Z2-9] — a real lobby code always renders uppercase, whereas an /i match
+    // on the code class would also grab an ordinary lowercase word after "lobby code " (e.g. "the lobby
+    // code screen") and latch a WRONG code. Precision-first, matching parseLobbyCodeReply's rationale.
+    const labeled = text.match(/lobby[ _-]?code[=:\s]+([A-Z2-9]{6})(?![A-Za-z2-9])/i);
+    return labeled && labeled[1] && /^[A-Z2-9]{6}$/.test(labeled[1]) ? labeled[1] : undefined;
+}
+/** Pull the assistant's plain text out of an OpenAI Responses API body (`output_text` convenience
+ *  field, else the concatenated `output[].content[].text`). Tolerant of shape drift; pure. */
+export function extractResponsesOutputText(parsed) {
+    if (typeof parsed !== "object" || parsed === null)
+        return undefined;
+    const obj = parsed;
+    if (typeof obj.output_text === "string" && obj.output_text.length > 0)
+        return obj.output_text;
+    const out = obj.output;
+    if (!Array.isArray(out))
+        return undefined;
+    const parts = [];
+    for (const item of out) {
+        if (typeof item !== "object" || item === null)
+            continue;
+        const content = item.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const chunk of content) {
+            if (typeof chunk === "object" &&
+                chunk !== null &&
+                typeof chunk.text === "string") {
+                parts.push(chunk.text);
+            }
+        }
+    }
+    return parts.length > 0 ? parts.join("\n") : undefined;
+}
+/** Parse a vision reply into a lobby CODE. PRECISION-FIRST: accept ONLY when the whole reply IS the
+ *  six-character code, or when it echoes an explicit /lobby/CODE — never a bare 6-letter token buried in
+ *  prose (e.g. "I see a home SCREEN"), because a wrong latch fails the entire run, whereas a miss just
+ *  retries on the next frame while the host keeps waiting. NONE (the instructed "no code" reply) is
+ *  rejected. Pure. */
+export function parseLobbyCodeReply(reply) {
+    if (typeof reply !== "string")
+        return undefined;
+    const up = reply.trim().toUpperCase();
+    if (up.length === 0 || /\bNONE\b/.test(up))
+        return undefined;
+    if (/^[A-Z2-9]{6}$/.test(up))
+        return up; // the well-behaved "code only" reply
+    const inUrl = up.match(/\/LOBBY\/([A-Z2-9]{6})(?![A-Z2-9])/); // model echoed the invite link
+    return inUrl ? inUrl[1] : undefined;
+}
+const LOBBY_CODE_VISION_PROMPT = "This is a screenshot of a the example multiplayer app multiplayer lobby. If a waiting-room / invite screen is " +
+    "shown, read the 6-character lobby code (characters A-Z and 2-9 only) — it appears near a 'lobby " +
+    "code'/'room code' label or inside an invite link of the form /lobby/CODE. Your entire reply MUST be " +
+    "exactly those 6 characters in uppercase and NOTHING else (no words, no punctuation). If no lobby " +
+    "code is visible on this screen (e.g. it is the home screen or a game round), reply exactly NONE.";
+// A single-frame OCR-style read. gpt-5.5 (the CU default) is used deliberately: it reliably reads the
+// 6-char code off a dense MOBILE-viewport waiting room — a smaller/cheaper model (gpt-4.1-mini) was
+// tried and could NOT read it. reasoning.effort stays "low" (minimal) and the output budget is small
+// but comfortably clear of the "incomplete on reasoning overflow" edge. Kept on the same account/key
+// as the actor; the same full-fidelity frame is already sent to this API by the CU provider, so this
+// adds no new data-exposure surface. See onScreenshot in runHost.
+const LOBBY_CODE_VISION_MODEL = "gpt-5.5";
+// Output-token budget for the read. The answer is 6 chars, but leave clear margin over any low-effort
+// reasoning tokens so the response never comes back status:"incomplete" with empty output.
+const LOBBY_CODE_VISION_MAX_OUTPUT_TOKENS = 64;
+// Per-read wall-clock cap. Without it a stalled fetch (Node fetch has no default timeout) would leave
+// visionInFlight pinned true and silently kill the relay for the rest of the host run.
+const LOBBY_CODE_VISION_TIMEOUT_MS = 15_000;
+/**
+ * Vision-read a lobby CODE straight off a host waiting-room FRAME (the robust, CDP-independent handoff
+ * relay). Fail-soft: any network/HTTP/parse problem returns undefined so the caller simply retries on
+ * the next frame. The frame is runtime-only; only the extracted code is used (as a digest downstream).
+ */
+export async function readLobbyCodeFromFrame(frame, apiKey, options = {}) {
+    if (typeof apiKey !== "string" || apiKey.length === 0 || frame.length === 0)
+        return undefined;
+    const fetchFn = options.fetchFn ?? fetch;
+    // Default a wall-clock timeout so a stalled request can't wedge the caller's in-flight guard. An
+    // explicit signal (e.g. run abort) takes precedence when provided.
+    const signal = options.signal ?? AbortSignal.timeout(LOBBY_CODE_VISION_TIMEOUT_MS);
+    const body = {
+        model: options.model ?? LOBBY_CODE_VISION_MODEL,
+        reasoning: { effort: "low" },
+        max_output_tokens: LOBBY_CODE_VISION_MAX_OUTPUT_TOKENS,
+        input: [
+            {
+                role: "user",
+                content: [
+                    { type: "input_text", text: LOBBY_CODE_VISION_PROMPT },
+                    { type: "input_image", image_url: `data:image/png;base64,${frame.toString("base64")}` },
+                ],
+            },
+        ],
+    };
+    let res;
+    try {
+        res = await fetchFn(options.endpoint ?? OPENAI_RESPONSES_URL, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal,
+        });
+    }
+    catch {
+        return undefined; // transient network error: skip this frame, next turn retries
+    }
+    if (!res.ok)
+        return undefined; // never read a non-ok body (it can echo the frame/input)
+    let parsed;
+    try {
+        parsed = await res.json();
+    }
+    catch {
+        return undefined;
+    }
+    return parseLobbyCodeReply(extractResponsesOutputText(parsed));
+}

package/dist/routes/shared-world/plan.d.ts

@@ -0,0 +1,27 @@
+import { type CuaActorDescriptor } from "../../actors/registry.js";
+import type { RoutePlanResult, RouteRefusal, SharedWorldPlan } from "../../lab/plan-types.js";
+import type { LabConfig, LabSubjectState } from "../../lab/types.js";
+import type { RunLabProvenance } from "../../run/status.js";
+import type { ConcurrentSharedWorldLabErrorCode } from "./types.js";
+/** The error a shared-world lab returns before a run starts. */
+export interface SharedWorldRefusal extends RouteRefusal<"shared-world", ConcurrentSharedWorldLabErrorCode> {
+    /** The registered actor id, once the registry check has passed. */
+    readonly actor?: string;
+}
+export type SharedWorldPlanResult = RoutePlanResult<SharedWorldPlan, SharedWorldRefusal>;
+/** The registered descriptor for a planned actor; planSharedWorldLab checked the registry. */
+export declare function sharedWorldDescriptorOf(actorType: string): CuaActorDescriptor;
+/**
+ * Plan a shared-world lab. It is called for any config handed to the shared-world runner, not only
+ * one routeOf sends here, so a config for another route gets this route's refusal.
+ */
+export declare function planSharedWorldLab(config: LabConfig, input: {
+    readonly dryRun: boolean;
+    readonly lab?: RunLabProvenance;
+    /** A caller's session runner cannot enforce maxOutputTokens. */
+    readonly hooks?: {
+        readonly runSession?: unknown;
+    };
+}): SharedWorldPlanResult;
+/** The provisioned plane's declared subject state. The external-public plane declares none. */
+export declare function planeStateOf(plan: SharedWorldPlan): LabSubjectState | undefined;