humanish 0.104.3 → 0.106.0

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

@@ -0,0 +1,176 @@
+// Off-app comms for the concurrent shared-world route: which email catch a plane gets (in the
+// subject sandbox, or adopter-hosted), and the drains that match captured mail to the seats'
+// declared inboxes and write the digest-only thread.
+import { FakeInbox } from "../../comms/fake-inbox.js";
+import { prepareReceivingRun } from "../../comms/receiving-runtime.js";
+import { DEFAULT_SANDBOX_CATCH_PORT, collectCommsThread, collectExternalCommsThread, externalCatchHealthy, externalInboxUrl, } from "../../comms/sandbox-catch.js";
+import { redactText, toErrorMessage } from "../../evidence/redaction.js";
+import { writeContainedOutputFile } from "../../run/contained-output.js";
+import { addressedRecipients } from "../../lab/parse/comms.js";
+// Off-app comms (#297): on the provisioned-getHost plane the harness owns the ONE subject sandbox, so
+// it can redirect the app's email-API sends into an in-sandbox catch and evidence them. Gated ENTIRELY
+// on config.comms — no comms declared → zero change. The base-URL env is injected into the subject
+// sandbox at create (fixed port known up front); the catch is deployed before serve; the drain + digest
+// evidence run at subject teardown, then register run-level in the bundle. NOT available on the
+// external-public plane (the app is an operator-owned deployment the harness never provisions).
+export function subjectCommsOf(config, planeClass) {
+    const commsEmail = planeClass === "provisioned-getHost" && config.comms?.email?.kind === "fake"
+        ? config.comms.email
+        : undefined;
+    const commsPort = commsEmail ? (commsEmail.port ?? DEFAULT_SANDBOX_CATCH_PORT) : undefined;
+    // injectEnv is absent on an adopter-hosted plane (#328): there is no subject env to inject
+    // because the operator points their own app at their own catch.
+    const commsEnv = commsEmail?.injectEnv !== undefined && commsPort !== undefined
+        ? { [commsEmail.injectEnv]: `http://127.0.0.1:${commsPort}` }
+        : {};
+    return { email: commsEmail, port: commsPort, env: commsEnv };
+}
+/**
+ * ADOPTER-HOSTED ingress (#328): on the external-public plane the harness provisions nothing, so
+ * it cannot host a catch — but the OPERATOR can, and then humanish still does every other part of
+ * the funnel: it tells each persona its address and inbox URL, drains the declared catch over
+ * HTTP at teardown, and writes the same digest-only evidence. Declaring `external` is what turns
+ * the previously-inert block into a working one. Returns an error message when the declared catch
+ * does not answer as a humanish catch.
+ */
+export async function prepareExternalComms(config, planeClass, dryRun, warnings) {
+    const externalComms = planeClass === "external-public" ? config.comms?.email?.external : undefined;
+    const externalCommsEmail = externalComms ? config.comms?.email : undefined;
+    if (config.comms?.email?.kind === "fake" &&
+        planeClass === "external-public" &&
+        externalComms === undefined) {
+        warnings.push("comms.email is declared but this is the external-public plane (the shared plane is an operator-owned public deployment the harness does not provision) — the in-sandbox email catch cannot be deployed and no comms evidence is collected. Declare `comms.email.external` to host the catch yourself (#328).");
+    }
+    if (!externalComms || !externalCommsEmail)
+        return { ok: true, wiring: undefined };
+    const inboxUrl = externalInboxUrl(externalComms);
+    // Fail closed BEFORE any actor sandbox is created: a comms lab whose catch is unreachable
+    // collects nothing while every lane still spends. The probe asserts OUR service marker in
+    // /health, so an adopter's proxy answering 200 for everything cannot pass for a catch.
+    if (!dryRun && !(await externalCatchHealthy(externalComms))) {
+        return {
+            ok: false,
+            message: `The external comms catch or inbox is unreachable or incompatible (GET /health must identify humanish-comms-catch and advertise recipient-inbox-v1). Update humanish on the catch host and restart it with \`humanish comms catch\` on that host, or drop comms.email to run without the inbox funnel.`,
+        };
+    }
+    return { ok: true, wiring: { external: externalComms, email: externalCommsEmail, inboxUrl } };
+}
+/**
+ * Off-app comms evidence (#297): drain everything the in-sandbox catch captured, route it into a
+ * host fake inbox addressed to the declared recipients, and write the run-level digest-only thread
+ * artifact — while the subject is STILL alive, before it is killed. Wrapped so a drain error
+ * never blocks teardown (invariant: all sandboxes torn down by id in the plane's finally). Returns
+ * the thread's path when one was written.
+ */
+export async function drainSubjectComms(ctx, commsEmail, subjectShell, deployedComms) {
+    const { runPaths, warnings, requestTimeoutMs, scrubKnownValues } = ctx;
+    try {
+        const commsChannel = new FakeInbox();
+        const commsInboxes = [];
+        for (const recipient of addressedRecipients(commsEmail)) {
+            commsInboxes.push(await commsChannel.provisionAddress(recipient.participantId, recipient.address));
+        }
+        const collected = await collectCommsThread({
+            shell: subjectShell,
+            deployed: deployedComms,
+            channel: commsChannel,
+            inboxes: commsInboxes,
+            requestTimeoutMs,
+        });
+        if (collected.artifact) {
+            await writeContainedOutputFile(runPaths, "comms/thread.json", `${JSON.stringify(collected.artifact, null, 2)}\n`, "utf8");
+            return "comms/thread.json";
+        }
+        else if (collected.captured > 0) {
+            warnings.push(`Comms catch captured ${collected.captured} email send(s) but none matched a declared recipient inbox — no comms evidence written. Declare comms.email.recipients[].address to match the address the app sends to.`);
+        }
+        else {
+            // Zero captures is the silent-broken shape (#351): the app never posted to the catch.
+            warnings.push(`Comms catch captured ZERO email sends — the app never delivered mail through the catch. Verify the app reads ${commsEmail.injectEnv} for its email API base URL (an SDK that ignores it sends real mail or throws) and that the flow reached an email step.`);
+        }
+    }
+    catch (error) {
+        warnings.push(`Comms evidence collection failed (run continues; subject still torn down): ${redactText(scrubKnownValues(toErrorMessage(error)))}`);
+    }
+    return undefined;
+}
+/**
+ * Adopter-hosted drain (#328/#387): same routing and digest-only artifact as the in-sandbox
+ * catch — only the transport differs (HTTP GET /deliveries against the catch the operator
+ * runs). Called in the plane's finally so the evidence survives a failed run; a drain error never
+ * masks the run's own outcome. Returns the thread's path when one was written.
+ */
+export async function drainExternalComms(ctx, comms) {
+    const { env, runPaths, warnings } = ctx;
+    const externalComms = comms.external;
+    const externalCommsEmail = comms.email;
+    try {
+        const commsChannel = new FakeInbox();
+        const commsInboxes = [];
+        for (const recipient of addressedRecipients(externalCommsEmail)) {
+            commsInboxes.push(await commsChannel.provisionAddress(recipient.participantId, recipient.address));
+        }
+        const authToken = externalComms.authTokenEnv === undefined ? undefined : env[externalComms.authTokenEnv];
+        const collected = await collectExternalCommsThread({
+            external: { ...externalComms, ...(authToken === undefined ? {} : { authToken }) },
+            channel: commsChannel,
+            inboxes: commsInboxes,
+        });
+        if (collected.artifact) {
+            const path = "comms/thread.json";
+            await writeContainedOutputFile(runPaths, path, `${JSON.stringify(collected.artifact, null, 2)}\n`, "utf8");
+            return path;
+        }
+        else if (collected.captured > 0) {
+            warnings.push(`Comms catch captured ${collected.captured} email send(s) but none matched a declared recipient inbox — no comms evidence written. Declare comms.email.recipients[].address to match the address the app sends to.`);
+        }
+        else {
+            warnings.push(`Comms catch captured ZERO email sends — your app never delivered mail through the catch at ${externalComms.catchBaseUrl}. Verify the app's email-API base URL points at it and that the flow reached an email step.`);
+        }
+    }
+    catch (error) {
+        warnings.push(`Comms evidence collection failed against the adopter-hosted catch (run continues): ${redactText(toErrorMessage(error))}`);
+    }
+    return undefined;
+}
+/** What receiving guards: the lab's email declaration and the subject env names and values. */
+export function receivingSourceOf(residual, env) {
+    const { comms } = residual;
+    const { envValues } = residual.subject;
+    return {
+        ...(comms === undefined ? {} : { comms }),
+        subject: { env, ...(envValues === undefined ? {} : { envValues }) },
+    };
+}
+/**
+ * Real email receiving, when the lab declares it on a live run. It registers the connection's
+ * secrets with the run's scrub before any desktop starts. Returns the message the run fails with
+ * when setup fails.
+ */
+export async function prepareEmailReceiving(args) {
+    const { source, knownSecretValues } = args;
+    if (args.dryRun || source.comms?.email?.kind !== "real")
+        return { ok: true, receiving: undefined };
+    try {
+        const receiving = await prepareReceivingRun({
+            cwd: args.cwd,
+            runId: args.runId,
+            config: source,
+            env: args.env,
+            participants: args.participants,
+            runPaths: args.runPaths,
+            registerSecrets: (values) => {
+                for (const value of values)
+                    if (value.length >= 4 && !knownSecretValues.includes(value))
+                        knownSecretValues.push(value);
+            },
+        });
+        return { ok: true, receiving };
+    }
+    catch {
+        return {
+            ok: false,
+            message: "Real email setup failed before desktop allocation. Run humanish comms check --online and humanish comms recover to inspect authentication and pending cleanup.",
+        };
+    }
+}

package/dist/routes/shared-world/external-public.d.ts

@@ -0,0 +1,21 @@
+import type { ActorRunResult, ExternalCommsWiring, LiveParticipants, PlaneContext } from "./types.js";
+/** What the external-public plane hands back to the orchestrator. */
+export interface ExternalPublicPlaneOutcome {
+    actorResults: ActorRunResult[];
+    runError: string | undefined;
+    publicOriginDigest: string | undefined;
+    lobbyConvergenceDigest: string | undefined;
+    handoffTimedOut: boolean;
+    hostHandoffFailure: string | undefined;
+    /** Set when the adopter-hosted drain wrote a thread. */
+    commsArtifactPath: string | undefined;
+}
+/**
+ * The operator-DECLARED origin (from subject.appUrl) — recorded for evidence/reference ONLY. The
+ * operator-OWNERSHIP claim rests on the subject.publicTarget.authorized attestation + this declared
+ * appUrl, NOT on digest equality (blocker 2): a normal cross-origin redirect (apex->www, http->https;
+ * lobby-trivia.example.test 307-redirects) makes the seats' OBSERVED origin differ from the declared one, which
+ * is expected and MUST NOT fail the run. Persisted digest-only (never the raw origin).
+ */
+export declare function declaredOriginDigestOf(publicAppUrl: string): string | undefined;
+export declare function runExternalPublicPlane(ctx: PlaneContext, live: LiveParticipants, inbox: ExternalCommsWiring | undefined): Promise<ExternalPublicPlaneOutcome>;

package/dist/routes/shared-world/external-public.js

@@ -0,0 +1,130 @@
+// EXTERNAL-PUBLIC plane (#164 phase 2): NO subject sandbox, NO getHost, NO prober. The shared plane
+// is the operator-declared public deployment (publicAppUrl); each seat opens it directly and reaches
+// the shared session through the real UI. A host-first barrier extracts the /lobby/CODE from the host
+// seat's CDP-observed URL (onObservedUrl) and threads it into the follower missions; a follower fails
+// closed WITHOUT opening if the host never yields a code within the handoff deadline.
+import { liveObserverResult } from "../../observer/live.js";
+import { redactText, toErrorMessage } from "../../evidence/redaction.js";
+import { mapWithConcurrency } from "../../run/concurrency.js";
+import { buildConcurrentSharedWorldBundle, judgeSharedWorldRun } from "./bundle.js";
+import { drainExternalComms } from "./comms.js";
+import { LobbyHandoff, runFollower, runHost } from "./handoff.js";
+import { readLobbyCodeFromFrame } from "./lobby-code.js";
+import { hostOriginDigest } from "./provenance.js";
+import { participantRunDeps, startParticipantFlush } from "./seats.js";
+/**
+ * The operator-DECLARED origin (from subject.appUrl) — recorded for evidence/reference ONLY. The
+ * operator-OWNERSHIP claim rests on the subject.publicTarget.authorized attestation + this declared
+ * appUrl, NOT on digest equality (blocker 2): a normal cross-origin redirect (apex->www, http->https;
+ * lobby-trivia.example.test 307-redirects) makes the seats' OBSERVED origin differ from the declared one, which
+ * is expected and MUST NOT fail the run. Persisted digest-only (never the raw origin).
+ */
+export function declaredOriginDigestOf(publicAppUrl) {
+    return publicAppUrl ? hostOriginDigest(publicAppUrl) : undefined;
+}
+export async function runExternalPublicPlane(ctx, live, inbox) {
+    const { plan, hooks, actorSpecs, concurrency, warnings } = ctx;
+    const participants = plan.plane.participants;
+    // publicAppUrl is the operator-declared shared plane; its ORIGIN is persisted digest-only
+    // (publicOriginDigest), never raw (the raw URL + the runtime observed lobby CODE never land —
+    // TENSION 3). The latch code is scrubbed from all narration.
+    const publicAppUrl = plan.plane.kind === "external-public" ? plan.plane.appUrl : "";
+    const declaredOriginDigest = declaredOriginDigestOf(publicAppUrl);
+    const handoff = new LobbyHandoff({
+        participantCount: participants.length,
+        timeoutMs: ctx.timeoutMs,
+        deadlineMs: hooks.handoffDeadlineMs,
+        scrubKnownValues: ctx.scrubKnownValues,
+        // The per-seat vision lobby-code reader (default: the real single-frame OpenAI read). Injectable
+        // so the barrier's handoff + convergence proof are testable without a live vision call.
+        readLobbyCode: hooks.readLobbyCodeFromFrame ?? readLobbyCodeFromFrame,
+        openaiApiKey: ctx.openaiApiKey,
+    });
+    const deps = {
+        // Scrub the latched lobby CODE (known once the host resolves it) from ALL narration.
+        runDeps: participantRunDeps(ctx, live, handoff.scrub),
+        publicAppUrl,
+        inbox,
+        now: ctx.now,
+    };
+    // Publish the in-progress bundle and attach any live Observer before fan-out, as on the
+    // provisioned path.
+    const snapshotArgs = {
+        plan,
+        descriptor: ctx.descriptor,
+        createdAt: ctx.createdAt,
+        dryRun: false,
+        inProgress: true,
+        runId: ctx.runId,
+        source: ctx.source,
+        actorSpecs,
+        actorResults: [],
+        stateSnapshots: [],
+        subject: { source: "app-url", envNames: [], state: { provenance: "external-public" } },
+        seedDigest: ctx.seedDigest,
+        planeClass: "external-public",
+        // Pre-fan-out snapshot: no seat has observed an origin yet, so the OBSERVED publicOriginDigest
+        // is not available; surface the DECLARED origin for the live Observer's reference.
+        ...(declaredOriginDigest === undefined ? {} : { declaredOriginDigest }),
+    };
+    const inProgressBundle = buildConcurrentSharedWorldBundle({
+        ...snapshotArgs,
+        judgment: judgeSharedWorldRun(snapshotArgs),
+    });
+    await ctx.run.writeSnapshot(inProgressBundle);
+    if (ctx.input.onObserverReady) {
+        live.observer = liveObserverResult(ctx.cwd, ctx.runId, ctx.artifactRoot, [
+            "Live external-public concurrent shared-world Observer is attached before final verification; stream auth URLs are runtime-only and are not persisted.",
+        ]);
+        await ctx.input.onObserverReady(live.observer);
+    }
+    startParticipantFlush(ctx, live, inProgressBundle);
+    // The host-first handoff barrier.
+    handoff.startDeadline();
+    let actorResults = [];
+    let runError;
+    let commsArtifactPath;
+    // Split the roster into the designated host and the followers, preserving each follower's
+    // ORIGINAL plan index so results land back in plan order (validation guarantees EXACTLY ONE host).
+    const hostIndex = participants.findIndex((participant) => participant.host === true);
+    const followerEntries = actorSpecs
+        .map((spec, index) => ({ spec, index }))
+        .filter(({ index }) => index !== hostIndex);
+    const orderedResults = new Array(actorSpecs.length);
+    try {
+        const hostPromise = hostIndex >= 0 && actorSpecs[hostIndex] !== undefined
+            ? runHost(handoff, deps, actorSpecs[hostIndex], hostIndex)
+            : undefined;
+        const followerResultsPromise = mapWithConcurrency(followerEntries, Math.max(1, concurrency - 1), ({ spec, index }) => runFollower(handoff, deps, spec, index));
+        const [hostResult, followerResults] = await Promise.all([hostPromise, followerResultsPromise]);
+        if (hostResult !== undefined && hostIndex >= 0) {
+            orderedResults[hostIndex] = hostResult;
+        }
+        followerEntries.forEach((entry, i) => {
+            orderedResults[entry.index] = followerResults[i];
+        });
+        actorResults = orderedResults;
+    }
+    catch (error) {
+        runError = redactText(handoff.scrub(toErrorMessage(error)));
+        warnings.push(`External-public concurrent shared-world run failed before completion: ${runError}`);
+    }
+    finally {
+        handoff.stopDeadline();
+        if (inbox)
+            commsArtifactPath = await drainExternalComms(ctx, inbox);
+    }
+    const { publicOriginDigest, lobbyConvergenceDigest } = handoff.convergence(declaredOriginDigest);
+    if (handoff.timedOut && runError === undefined) {
+        runError = `The host participant never produced a /lobby/CODE URL within the ${handoff.deadlineMs}ms handoff deadline; follower participants failed closed without opening.`;
+    }
+    return {
+        actorResults,
+        runError,
+        publicOriginDigest,
+        lobbyConvergenceDigest,
+        handoffTimedOut: handoff.timedOut,
+        hostHandoffFailure: handoff.hostFailure,
+        commsArtifactPath,
+    };
+}

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

@@ -0,0 +1,62 @@
+import type { DesktopParticipantRun, ParticipantRunOutcome } from "../computer-use/types.js";
+import { type ParticipantRunDeps } from "./seats.js";
+import type { ActorRunResult, ExternalCommsWiring } from "./types.js";
+/** What the host and follower lanes need besides the handoff. */
+export interface HandoffParticipantDeps {
+    runDeps: ParticipantRunDeps;
+    publicAppUrl: string;
+    inbox: ExternalCommsWiring | undefined;
+    now: () => number;
+}
+/**
+ * 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 declare class LobbyHandoff {
+    readonly observedFinalUrls: (string | undefined)[];
+    readonly observedLobbyCodes: (string | undefined)[];
+    latchedLobbyCode: string | undefined;
+    /** A follower gave up because the deadline passed. */
+    timedOut: boolean;
+    /** Why the host seat ended without producing a lobby code. */
+    hostFailure: string | undefined;
+    readonly deadlineMs: number;
+    private readonly lobbyCodeLatch;
+    private readonly scrubKnownValues;
+    private readonly readLobbyCode;
+    private readonly openaiApiKey;
+    private deadline;
+    private deadlineTimer;
+    constructor(options: {
+        participantCount: number;
+        timeoutMs: number;
+        deadlineMs: number | undefined;
+        scrubKnownValues: (text: string) => string;
+        readLobbyCode: (frame: Buffer, apiKey: string) => Promise<string | undefined>;
+        openaiApiKey: string;
+    });
+    /**
+     * 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).
+     */
+    readonly scrub: (text: string) => string;
+    /** Starts the deadline the followers wait against. */
+    startDeadline(): void;
+    stopDeadline(): void;
+    latchLobbyCode(code: string, participantIndex: number): void;
+    makeLobbyCodeVisionReader(done: () => boolean, onCode: (code: string) => void): (frame: Buffer) => void;
+    makeObservedUrl(participantIndex: number, isHost: boolean): (url: string | undefined) => void;
+    /** Resolves with the host's code, or rejects when the host ends without one or the deadline passes. */
+    waitForHostCode(): Promise<string>;
+    /** Releases waiting followers to fail closed when the host ended without a code. */
+    releaseFollowersIfUnlatched(outcome: ParticipantRunOutcome | undefined): void;
+    /** The digest-only convergence proofs over what the seats observed. */
+    convergence(declaredOriginDigest: string | undefined): {
+        publicOriginDigest: string | undefined;
+        lobbyConvergenceDigest: string | undefined;
+    };
+}
+export declare function runHost(handoff: LobbyHandoff, deps: HandoffParticipantDeps, spec: DesktopParticipantRun, participantIndex: number): Promise<ActorRunResult>;
+export declare function runFollower(handoff: LobbyHandoff, deps: HandoffParticipantDeps, spec: DesktopParticipantRun, participantIndex: number): Promise<ActorRunResult>;