humanish 0.95.0 → 0.96.1

package/dist/cua-actor-lab.js

@@ -1,3 +1,7 @@
+import { withTransientCommsSecrets } from "./run-narration-secrets.js";
+import { prepareReceivingRun, receivingPublication } from "./comms-receiving-runtime.js";
+import { deployReceivingInbox } from "./comms-receiving-inbox.js";
+import { receivingEmailValidationReason } from "./lab-config.js";
 // The computer-use lab backend: a subject (an app-url the caller provisioned, or a repo the
 // lab clones AND serves in-sandbox) driven by a REGISTRY-RESOLVED computer-use actor inside a
 // hosted E2B desktop. This is the path that makes `actors[].type` load-bearing — the
@@ -237,7 +241,7 @@ export function composeLaneInstructions(args) {
  *  runtime loopback/getHost address (not secret), so — mirroring the lobby-code runtime injection — this
  *  augments only the instructions the model receives; the authored prompt + its digest are unchanged.
  *  Returns a new spec (never mutates). Shared by the CUA + concurrent shared-world routes. */
-export function withInboxMission(spec, inboxUrl, address) {
+export function withInboxMission(spec, inboxUrl, address, receiving = false) {
     // No assigned identity means no participant inbox; never fall back to the shared operator view.
     if (!address?.trim())
         return spec;
@@ -248,6 +252,11 @@ export function withInboxMission(spec, inboxUrl, address) {
     // and ends its session — the exact give-up class a live run documented — unless told the wait
     // is expected and the inbox is the next step.
     const identity = ` Your email address is ${address} — when the app asks for an email address, enter exactly that.`;
+    if (receiving)
+        return {
+            ...spec,
+            instructions: `${spec.instructions}\n\nEmail inbox:${identity} This is a fresh test identity; it does not replace an existing account's email address. When the app says it sent email, open ${inboxUrl} to check your inbox. Read the original email and use its verification link or code. Delivery may take a little time; refresh if needed. If mail remains missing or unavailable, report what you observed rather than assuming the app failed to send. The inbox may block remote images or undeclared destinations; those are harness limitations.`
+        };
     return {
         ...spec,
         instructions: `${spec.instructions}\n\nEmail inbox:${identity} When the app tells you it has emailed you (a verification link, confirmation code, or magic link), open ${recipientInboxUrl(inboxUrl, address)} in the browser to read that email and follow its link or enter its code. All email the app sends you arrives there. Waiting for an email is normal, not a blocker — do not end your session while waiting; open the inbox and refresh it until the email appears.`
@@ -1155,36 +1164,48 @@ function isMeasuredViewport(value) {
 function isPositiveMeasurement(value) {
     return typeof value === "number" && Number.isFinite(value) && value > 0;
 }
-async function measureBrowserWindowWithXdotool(desktop, windowId, requestTimeoutMs) {
+async function measureBrowserWindowWithXwininfo(desktop, windowId, requestTimeoutMs) {
     const result = await desktop.commands.run([
         "set -euo pipefail",
         `win=${shellSingleQuote(windowId)}`,
-        "xdotool getwindowgeometry --shell \"$win\" 2>/dev/null || true"
+        // Older xdotool builds translate parent-relative offsets twice. With window
+        // decorations that falsely reports a visible client as clipped, triggering
+        // fullscreen and hiding the participant's address bar. Read root-relative
+        // client coordinates directly; never substitute emulated CDP outer bounds.
+        "LC_ALL=C xwininfo -id \"$win\" -stats 2>/dev/null"
     ].join("\n"), { requestTimeoutMs, timeoutMs: 5_000 });
-    const output = result.stdout ?? "";
-    const read = (name) => {
-        const raw = output.match(new RegExp(`^${name}=(-?\\d+)$`, "m"))?.[1];
-        if (raw === undefined)
+    if (result.exitCode !== undefined && result.exitCode !== 0)
+        return undefined;
+    return parseXwininfoGeometry(result.stdout ?? "");
+}
+/** Root-relative physical client bounds from xwininfo's C-locale stats. */
+export function parseXwininfoGeometry(output) {
+    const read = (label) => {
+        const matches = [...output.matchAll(new RegExp(`^\\s*${label}:\\s*(-?\\d+)\\s*$`, "gm"))];
+        if (matches.length !== 1)
             return undefined;
-        const value = Number(raw);
-        return Number.isFinite(value) ? value : undefined;
+        const value = Number(matches[0][1]);
+        return Number.isSafeInteger(value) ? value : undefined;
     };
-    const x = read("X");
-    const y = read("Y");
-    const width = read("WIDTH");
-    const height = read("HEIGHT");
+    const x = read("Absolute upper-left X");
+    const y = read("Absolute upper-left Y");
+    const width = read("Width");
+    const height = read("Height");
+    const mapStates = [...output.matchAll(/^\s*Map State:\s*(\S+)\s*$/gm)];
+    if (mapStates.length !== 1 || mapStates[0][1] !== "IsViewable")
+        return undefined;
     if (x === undefined || y === undefined || width === undefined || height === undefined || width <= 0 || height <= 0) {
         return undefined;
     }
-    return { x, y, width, height, source: "xdotool" };
+    return { x, y, width, height, source: "xwininfo" };
 }
 /** Physical X client bounds, never the page's emulated window.outerWidth/Height. */
 function isBrowserWindowContained(bounds, [width, height]) {
     return bounds.x >= 0 && bounds.y >= 0
         && bounds.x + bounds.width <= width && bounds.y + bounds.height <= height;
 }
-/** One bounded repair. Window-manager decorations may keep the client origin below (0, 0),
- * so a full-screen client height can clip the bottom even after windowmove succeeds. */
+/** Bounded repair. Resizing can clear a window-manager maximize state and move the
+ * client origin as decorations return, so remeasure before a second adjustment. */
 async function fitBrowserWindowWithinDesktop(desktop, windowId, resolution, requestTimeoutMs) {
     const run = (command) => desktop.commands.run([
         "set -euo pipefail",
@@ -1193,18 +1214,22 @@ async function fitBrowserWindowWithinDesktop(desktop, windowId, resolution, requ
     ].join("\n"), { requestTimeoutMs, timeoutMs: 5_000 }).catch(() => undefined);
     await run('xdotool windowmove "$win" 0 0');
     await desktop.wait(250).catch(() => undefined);
-    const moved = await measureBrowserWindowWithXdotool(desktop, windowId, requestTimeoutMs).catch(() => undefined);
+    const moved = await measureBrowserWindowWithXwininfo(desktop, windowId, requestTimeoutMs).catch(() => undefined);
     if (moved === undefined)
         return moved;
     let resized = moved;
-    const width = resolution[0] - moved.x;
-    const height = resolution[1] - moved.y;
     // Resizing alone cannot fix an offscreen client origin. The window manager
     // can also center a minimum-width client at a negative x on a narrow screen.
-    if (moved.x >= 0 && moved.y >= 0 && width > 0 && height > 0) {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        if (isBrowserWindowContained(resized, resolution))
+            return resized;
+        const width = resolution[0] - resized.x;
+        const height = resolution[1] - resized.y;
+        if (resized.x < 0 || resized.y < 0 || width <= 0 || height <= 0)
+            break;
         await run(`xdotool windowsize "$win" ${width} ${height}`);
         await desktop.wait(250).catch(() => undefined);
-        const measured = await measureBrowserWindowWithXdotool(desktop, windowId, requestTimeoutMs).catch(() => undefined);
+        const measured = await measureBrowserWindowWithXwininfo(desktop, windowId, requestTimeoutMs).catch(() => undefined);
         if (measured === undefined)
             return measured;
         resized = measured;
@@ -1227,7 +1252,7 @@ async function fitBrowserWindowWithinDesktop(desktop, windowId, resolution, requ
     // Give the window manager a bounded settling window, keeping missing reads unverified.
     for (let attempt = 0; attempt < 4; attempt += 1) {
         await desktop.wait(250).catch(() => undefined);
-        const measured = await measureBrowserWindowWithXdotool(desktop, windowId, requestTimeoutMs).catch(() => undefined);
+        const measured = await measureBrowserWindowWithXwininfo(desktop, windowId, requestTimeoutMs).catch(() => undefined);
         if (measured === undefined || isBrowserWindowContained(measured, resolution))
             return measured;
         resized = measured;
@@ -1244,40 +1269,40 @@ export async function captureDesktopBrowserGeometry(args) {
             return undefined;
         });
     }
-    let xdotoolWindow;
+    let physicalWindow;
     if (browserWindowId !== undefined) {
         if (args.resize !== false) {
             await fillDesktopBrowserWindow(args.desktop, browserWindowId, args.requestedScreen, args.requestTimeoutMs);
             // Let the window manager apply the resize before querying both X and page layout geometry.
             await args.desktop.wait(250).catch(() => undefined);
         }
-        xdotoolWindow = await measureBrowserWindowWithXdotool(args.desktop, browserWindowId, args.requestTimeoutMs)
+        physicalWindow = await measureBrowserWindowWithXwininfo(args.desktop, browserWindowId, args.requestTimeoutMs)
             .catch(() => undefined);
     }
     else {
         warnings.push(`Browser window bounds could not be measured for lane ${args.laneId}; the live stream will use the full desktop.`);
     }
     let unusable;
-    if (xdotoolWindow !== undefined && !isBrowserWindowContained(xdotoolWindow, args.requestedScreen)) {
-        const before = xdotoolWindow;
+    if (physicalWindow !== undefined && !isBrowserWindowContained(physicalWindow, args.requestedScreen)) {
+        const before = physicalWindow;
         if (args.resize !== false && browserWindowId !== undefined) {
-            xdotoolWindow = await fitBrowserWindowWithinDesktop(args.desktop, browserWindowId, args.requestedScreen, args.requestTimeoutMs);
-            if (xdotoolWindow === undefined) {
+            physicalWindow = await fitBrowserWindowWithinDesktop(args.desktop, browserWindowId, args.requestedScreen, args.requestTimeoutMs);
+            if (physicalWindow === undefined) {
                 // Keep the last measured bad state; a missing observation cannot prove a successful fix.
-                xdotoolWindow = before;
+                physicalWindow = before;
                 unusable = `Physical browser containment could not be verified after correction for lane ${args.laneId}; the last measured window was clipped.`;
             }
-            else if (isBrowserWindowContained(xdotoolWindow, args.requestedScreen)) {
-                warnings.push(`Browser window clipping corrected for lane ${args.laneId}; physical bounds are ${xdotoolWindow.width}x${xdotoolWindow.height} at (${xdotoolWindow.x}, ${xdotoolWindow.y}).`);
+            else if (isBrowserWindowContained(physicalWindow, args.requestedScreen)) {
+                warnings.push(`Browser window clipping corrected for lane ${args.laneId}; physical bounds are ${physicalWindow.width}x${physicalWindow.height} at (${physicalWindow.x}, ${physicalWindow.y}).`);
             }
         }
-        if (unusable === undefined && !isBrowserWindowContained(xdotoolWindow, args.requestedScreen)) {
-            unusable = `Browser window is outside the captured ${args.requestedScreen[0]}x${args.requestedScreen[1]} desktop for lane ${args.laneId}: physical bounds ${xdotoolWindow.width}x${xdotoolWindow.height} at (${xdotoolWindow.x}, ${xdotoolWindow.y}), right=${xdotoolWindow.x + xdotoolWindow.width}, bottom=${xdotoolWindow.y + xdotoolWindow.height}.`;
+        if (unusable === undefined && !isBrowserWindowContained(physicalWindow, args.requestedScreen)) {
+            unusable = `Browser window is outside the captured ${args.requestedScreen[0]}x${args.requestedScreen[1]} desktop for lane ${args.laneId}: physical bounds ${physicalWindow.width}x${physicalWindow.height} at (${physicalWindow.x}, ${physicalWindow.y}), right=${physicalWindow.x + physicalWindow.width}, bottom=${physicalWindow.y + physicalWindow.height}.`;
         }
         if (unusable !== undefined)
             warnings.push(unusable);
     }
-    if (xdotoolWindow === undefined) {
+    if (physicalWindow === undefined) {
         warnings.push(`Physical browser containment is unverified for lane ${args.laneId}; X window bounds could not be measured. Page-reported outer dimensions can be emulated and do not prove physical visibility.`);
     }
     let cdpUnavailable;
@@ -1293,11 +1318,11 @@ export async function captureDesktopBrowserGeometry(args) {
             return undefined;
         })
         : undefined;
-    const browserWindow = xdotoolWindow ?? chromeGeometry?.browserWindow;
+    const browserWindow = physicalWindow ?? chromeGeometry?.browserWindow;
     const viewport = chromeGeometry?.viewport;
     // The fill check reads the X window when it was measured: under mobile emulation (#221) the
     // page's window.outerWidth reports the EMULATED screen (414), which is not a fill failure.
-    const fillBounds = xdotoolWindow;
+    const fillBounds = physicalWindow;
     if (!browserWindow) {
         warnings.push(`Browser outer bounds could not be measured for lane ${args.laneId}.`);
     }
@@ -1653,12 +1678,13 @@ export async function runCuaLane(spec, deps) {
     // in-sandbox catch (loopback) so its verification mail is CAPTURED, not sent to the internet. Gated
     // ENTIRELY on config.comms — no comms declared → zero change. The base-URL env is injected at
     // sandbox-create (below, so the app reads it at boot); the catch is started right after create.
-    const commsEmail = (cloneRoute || localTreeRoute) ? config.comms?.email : undefined;
+    const commsEmail = (cloneRoute || localTreeRoute) && config.comms?.email?.kind === "fake" ? config.comms.email : undefined;
     const commsPort = commsEmail ? (commsEmail.port ?? DEFAULT_SANDBOX_CATCH_PORT) : undefined;
     // Hoisted so the finally can drain the catch before teardown; `commsArtifactPath` is the written
     // evidence path folded into the lane outcome.
     let deployedComms;
     let commsArtifactPath;
+    let receivingInboxUrl;
     // 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
@@ -1810,6 +1836,27 @@ export async function runCuaLane(spec, deps) {
         // Start the in-sandbox email catch BEFORE the subject serve, so the app's send-API base URL (injected
         // into its env at create) resolves the moment it boots. A comms-declared lab that can't stand the
         // catch up is a setup failure (fail closed) rather than silently sending real mail.
+        if (deps.receiving) {
+            const surface = await deployReceivingInbox(desktop, { leaseId: spec.streamId, requestTimeoutMs: Math.min(deps.requestTimeoutMs, 30_000) });
+            receivingInboxUrl = surface.url;
+            const email = config.comms?.email;
+            try {
+                await deps.receiving.attach(spec.laneId, {
+                    surface,
+                    allowedOrigins: [...new Set([new URL(targetUrl).origin, ...(email?.allowedOrigins ?? [])])],
+                    originMap: buildOriginMap({
+                        ...(config.subject.serve?.url === undefined ? {} : { internalServeUrl: config.subject.serve.url }),
+                        reachableBaseUrl: targetUrl,
+                        ...(email?.linkOrigin === undefined ? {} : { linkOrigin: email.linkOrigin })
+                    })
+                });
+                commsArtifactPath = "comms/receiving.json";
+            }
+            catch (error) {
+                await surface.stop().catch(() => { });
+                throw error;
+            }
+        }
         if (commsEmail && commsPort !== undefined) {
             deployedComms = await deployCommsCatch(desktop, {
                 port: commsPort,
@@ -2098,11 +2145,13 @@ export async function runCuaLane(spec, deps) {
                 // recipient it can actually receive mail into (else it would stall on an inbox that stays
                 // empty). Two comms planes, mutually exclusive by parse: the in-sandbox catch humanish
                 // deployed, or the adopter-hosted one (#380).
-                instructions: commsEmail && commsInboxUrl && deployedComms?.ready && laneHasInboxRecipient(commsEmail, spec.laneId)
-                    ? withInboxMission(spec, commsInboxUrl, inboxRecipientFor(commsEmail, spec.laneId)?.address).instructions
-                    : deps.externalComms && laneHasInboxRecipient(deps.externalComms.email, spec.laneId)
-                        ? withInboxMission(spec, deps.externalComms.inboxUrl, inboxRecipientFor(deps.externalComms.email, spec.laneId)?.address).instructions
-                        : spec.instructions,
+                instructions: deps.receiving && receivingInboxUrl
+                    ? withInboxMission(spec, receivingInboxUrl, deps.receiving.address(spec.laneId), true).instructions
+                    : commsEmail && commsInboxUrl && deployedComms?.ready && laneHasInboxRecipient(commsEmail, spec.laneId)
+                        ? withInboxMission(spec, commsInboxUrl, inboxRecipientFor(commsEmail, spec.laneId)?.address).instructions
+                        : deps.externalComms && laneHasInboxRecipient(deps.externalComms.email, spec.laneId)
+                            ? withInboxMission(spec, deps.externalComms.inboxUrl, inboxRecipientFor(deps.externalComms.email, spec.laneId)?.address).instructions
+                            : spec.instructions,
                 persona: spec.persona,
                 timeoutMs: deps.timeoutMs,
                 // The brain is either a keyed API client or a CLI the operator is already signed in to.
@@ -2257,6 +2306,14 @@ export async function runCuaLane(spec, deps) {
                         : { warnings: [...(desktopGeometry.warnings ?? []), ...geometryWarnings] })
                 };
             }
+            if (deps.receiving) {
+                try {
+                    await deps.receiving.finishParticipant(spec.laneId);
+                }
+                catch {
+                    warnings.push("Real email finalization is incomplete. Inspect communication cleanup with humanish comms recover.");
+                }
+            }
             // Off-app comms evidence (#297): before this lane's sandbox is torn down, drain everything the
             // in-sandbox catch captured, route it into a host fake inbox addressed to the declared
             // recipients, and write the digest-only thread artifact. Wrapped so a drain failure NEVER
@@ -2700,6 +2757,9 @@ function subjectProvenanceArg(subject, publicRepo, subjectEnvNames) {
  * ticking into a directory something else is deleting, which surfaces as an unrelated ENOTEMPTY.
  */
 export async function runCuaActorLab(options) {
+    return withTransientCommsSecrets(() => runCuaActorLabWithSecrets(options));
+}
+async function runCuaActorLabWithSecrets(options) {
     const analysisReason = resolveAutomaticAnalysis(options.config.review?.analysis);
     const tasksReason = analysisReason.ok ? taskProtocolValidationReason(options.config, true) : analysisReason.message;
     if (tasksReason)
@@ -2792,7 +2852,12 @@ async function runCuaActorLabInScope(options) {
     if (actor?.maxOutputTokens !== undefined && (hooks.runSession || hooks.buildProvider || hooks.buildExecutor)) {
         return fail("HUMANISH_CUA_LAB_SUBJECT_INVALID", "maxOutputTokens cannot be enforced by a custom runSession/provider/executor route.", descriptor.id);
     }
+    const receivingReason = receivingEmailValidationReason(config);
+    if (receivingReason)
+        return fail("HUMANISH_CUA_LAB_SUBJECT_INVALID", receivingReason, descriptor.id);
     const inProcessRoute = hooks.buildExecutor !== undefined;
+    if (inProcessRoute && config.comms?.email?.kind === "real")
+        return fail("HUMANISH_CUA_LAB_SUBJECT_INVALID", "Real email receiving requires hosted participant desktops.", descriptor.id);
     if (inProcessRoute && config.execution?.desktop?.media !== undefined) {
         return fail("HUMANISH_CUA_LAB_SUBJECT_INVALID", "execution.desktop.media is not provisioned by a caller-supplied executor. Remove the declaration or use a hosted computer-use browser lane.", descriptor.id);
     }
@@ -3267,20 +3332,47 @@ async function runCuaActorLabInScope(options) {
             await flushWriting;
         };
     }
+    const receivingWarnings = [];
+    let receiving;
+    if (!dryRun && config.comms?.email?.kind === "real") {
+        try {
+            receiving = await prepareReceivingRun({ cwd, runId, config, env, participants: laneSpecs.map(spec => spec.laneId), runPaths,
+                registerSecrets: values => { for (const value of values)
+                    if (value.length >= 4 && !knownSecretValues.includes(value))
+                        knownSecretValues.push(value); }
+            });
+            if (receiving)
+                deps.receiving = receiving;
+        }
+        catch {
+            await stopLiveFlush?.();
+            return fail("HUMANISH_CUA_LAB_SUBJECT_INVALID", "Real email setup failed before desktop allocation. Run humanish comms check --online and humanish comms recover to inspect authentication and pending cleanup.", descriptor.id);
+        }
+    }
     // Run lanes (dry-run runs none). In-process is always one lane.
     let outcomes;
     let failFastReason;
-    if (!dryRun) {
-        if (inProcessRoute) {
-            outcomes = [await runInProcessLane(laneSpecs[0], deps)];
+    try {
+        if (!dryRun) {
+            if (inProcessRoute) {
+                outcomes = [await runInProcessLane(laneSpecs[0], deps)];
+            }
+            else if (laneCount === 1) {
+                outcomes = [await runCuaLane(laneSpecs[0], deps)];
+            }
+            else {
+                const ran = await runCuaLanes(laneSpecs, deps, plan.concurrency);
+                outcomes = ran.outcomes;
+                failFastReason = ran.failFastReason;
+            }
         }
-        else if (laneCount === 1) {
-            outcomes = [await runCuaLane(laneSpecs[0], deps)];
+    }
+    finally {
+        try {
+            await receiving?.finish();
         }
-        else {
-            const ran = await runCuaLanes(laneSpecs, deps, plan.concurrency);
-            outcomes = ran.outcomes;
-            failFastReason = ran.failFastReason;
+        catch {
+            receivingWarnings.push("Email finalization could not complete. Inspect humanish comms recover; provider cleanup remains unresolved.");
         }
     }
     // Close the live flush BEFORE any final artifact work: no new flush may start, and an
@@ -3438,6 +3530,8 @@ async function runCuaActorLabInScope(options) {
         hookLabel: "cuaHooks",
         ...(options.scorerProvenance === undefined ? {} : { scorerProvenance: options.scorerProvenance })
     });
+    if (receiving)
+        bundle.commsReceiving = receiving.snapshot();
     await writeCuaRunArtifacts(bundle, createdAt, runPaths);
     // Finalize the status record from the bundle that was just written, so the index can never
     // claim an outcome the evidence does not carry. A run that throws before reaching here leaves
@@ -3467,7 +3561,7 @@ async function runCuaActorLabInScope(options) {
     const adapterFailure = adapterScoreFailureMessage(bundle);
     const ok = observer.ok && allLanesOk && adapterFailure === undefined && scorerResult.declaredVerdictFailure === undefined;
     const laneWarnings = (outcomes ?? []).flatMap((outcome) => outcome.warnings);
-    const warnings = [...laneWarnings, ...aggregateWarnings, ...adapterWarnings, ...observer.warnings];
+    const warnings = [...receivingWarnings, ...laneWarnings, ...aggregateWarnings, ...adapterWarnings, ...observer.warnings];
     const laneResults = laneSpecs.map((spec, index) => toLaneResult(spec, outcomes?.[index], laneSubjects[index], dryRun));
     const laneSummary = buildLaneSummary(outcomes, laneCount, plan, dryRun);
     const firstOutcome = outcomes?.[0];
@@ -3625,6 +3719,7 @@ function observerResultForCuaArtifacts(cwd, runId, artifactRoot, warnings = [])
 function buildSingleLaneBundle(args) {
     const { spec, outcome, config } = args;
     return buildCuaBundle({
+        realEmail: config.comms?.email?.kind === "real",
         ...(args.lab === undefined ? {} : { lab: args.lab }),
         actorId: args.descriptor.id,
         appUrl: args.appUrl,
@@ -4520,6 +4615,7 @@ export function buildCuaBundle(args) {
     }, [stream]);
     return {
         schema: RUN_BUNDLE_SCHEMA,
+        ...(args.realEmail && !args.dryRun ? { publication: { restrictions: ["real-communications"] } } : {}),
         runId: args.runId,
         mode: args.dryRun ? "dry-run" : "live",
         simCount: 1,
@@ -5008,6 +5104,7 @@ export function buildCuaFanoutBundle(args) {
     const cost = buildCuaCostSummary({ lanes: costLanes, desktops });
     return {
         schema: RUN_BUNDLE_SCHEMA,
+        ...receivingPublication(args.config, args.dryRun),
         runId: args.runId,
         mode: args.dryRun ? "dry-run" : "live",
         simCount: specs.length,