humanish 0.74.0 → 0.75.0

package/dist/cua-actor-lab.js

@@ -46,6 +46,7 @@ import { appendSandboxReceipt } from "./sandbox-receipts.js";
 import { assertScreenshotEvidence } from "./image-evidence.js";
 import { buildObserverData } from "./observer-data.js";
 import { corepackCommandFor, needsNodeRuntime, nodeBootstrapCommand } from "./subject-runtime.js";
+import { chromeCdpProbeCommand, parseChromeCdpProbeOutput } from "./chrome-cdp-probe.js";
 import { personaToDirectives, renderPersonaPromptSection } from "./persona.js";
 import { labPersonaIds, resolveCommittedPersonas } from "./persona-resolve.js";
 import { renderTaskPrompt } from "./tasks.js";
@@ -505,6 +506,37 @@ function isoNow(now) {
     return new Date(now()).toISOString();
 }
 /** Emit a phase-started event (no ok/durationMs: those belong to the matching completed event). */
+/**
+ * Run a provisioning step and, when it fails with an EXIT CODE, run it once more (#602). A cold
+ * install of 0.74.0 lost its whole first live study to one transient TLS error inside the
+ * sandbox's `npm install`; the parallel install twenty seconds later passed, as had the ten
+ * before it. One retry clears that class. A TIMEOUT is not retried: its budget is already spent,
+ * and a second wait would double it. The retry runs under its own step name so both logs stay.
+ */
+async function runProvisioningStepWithOneRetry(desktop, args) {
+    const first = await runDetachedStep(desktop, {
+        name: args.name,
+        command: args.command,
+        cwd: args.cwd,
+        timeoutMs: args.timeoutMs,
+        requestTimeoutMs: args.requestTimeoutMs,
+        ...args.timers
+    });
+    if (first.ok || first.timedOut)
+        return { ...first, attempts: 1 };
+    const retryStartedAt = args.now();
+    emitPhaseStarted(args.onPhase, args.now, args.retryPhase, `${args.retryMessage} (first attempt exited ${first.exitCode ?? "null"}; retrying once)`);
+    const second = await runDetachedStep(desktop, {
+        name: `${args.name}-retry`,
+        command: args.command,
+        cwd: args.cwd,
+        timeoutMs: args.timeoutMs,
+        requestTimeoutMs: args.requestTimeoutMs,
+        ...args.timers
+    });
+    emitPhaseCompleted(args.onPhase, args.now, retryStartedAt, args.retryPhase, second.ok, second.ok ? `${args.retryMessage}: succeeded on the second attempt` : `${args.retryMessage}: failed twice`);
+    return { ...second, attempts: 2, ...(first.exitCode === undefined ? {} : { firstExitCode: first.exitCode }) };
+}
 function emitPhaseStarted(onPhase, now, phase, message) {
     onPhase?.({ at: isoNow(now), type: `cua-lab.subject.${phase}.started`, message });
 }
@@ -839,162 +871,70 @@ export function desktopBrowserFamily(value) {
     return "unknown";
 }
 /**
- * Observe-time CDP port resolution lines (pure; exported for contract tests): cached
- * launch-time port first, then a re-read of the profile's DevToolsActivePort marker, then the
- * legacy fixed 9222. The re-read is a local best-effort file read inside the already
- * time-bounded observer command, so a missing/garbled marker degrades to the fallback,
- * never a hang.
- */
-export function chromeCdpPortResolutionScript(endpoint) {
-    return [
-        `let cdpPort = ${endpoint.cdpPort === undefined ? "undefined" : JSON.stringify(endpoint.cdpPort)};`,
-        `const cdpProfileDir = ${JSON.stringify(endpoint.profileDir ?? "")};`,
-        "if (cdpPort === undefined && cdpProfileDir) {",
-        "  try {",
-        "    const { readFileSync } = await import('node:fs');",
-        "    const marker = readFileSync(cdpProfileDir + '/DevToolsActivePort', 'utf8');",
-        "    const parsed = Number.parseInt(String(marker.split('\\n')[0] ?? ''), 10);",
-        "    if (Number.isInteger(parsed) && parsed > 0) cdpPort = parsed;",
-        "  } catch {}",
-        "}",
-        "if (cdpPort === undefined) cdpPort = 9222;"
-    ];
-}
-/** Shared CDP page-selection preamble: pinned target id first, then this lane's target URL,
- *  then a single-page fallback; never an arbitrary page from a multi-page endpoint. */
-function chromeCdpPageSelectionScript(endpoint, targetId, 
-/**
- * "pinned" (default): the launch-time target, for measurements about the ORIGINAL window
- * (geometry). "active": the tab the participant is driving NOW — Chrome's /json lists page
- * targets most-recently-focused first. The state observer must follow the participant: a
- * verification link that opens in a NEW tab left the pinned observer reading the old tab
- * forever, so the observed URL never changed again and stopWhen/task criteria went blind
- * (a live run's funnel read reach-dashboard 0/2 under a screenshot OF the dashboard).
+ * The URL / title / page-text / scroll observer behind stopWhen and task criteria. One probe per
+ * observation, run on the sandbox's python3 (see chrome-cdp-probe.ts for why not node: #514).
+ *
+ * "active": follow the participant to whatever tab they are driving now — never pin the state
+ * observer to the launch tab (a verification link that opened in a NEW tab left a pinned observer
+ * reading the old tab forever).
+ *
+ * `onUnavailable` fires ONCE, on the first probe that could not read the page, with the reason.
+ * The observer still degrades to `{}` for the loop; the callback is how a lane says out loud that
+ * url/text criteria are not being measured, instead of letting the funnel report 0/N (#514).
  */
-prefer = "pinned") {
-    return [
-        ...chromeCdpPortResolutionScript(endpoint),
-        "const pages = await fetch('http://127.0.0.1:' + cdpPort + '/json').then((r) => r.json()).catch(() => []);",
-        `const expectedTargetId = ${JSON.stringify(targetId ?? "")};`,
-        `const expectedTargetUrl = ${JSON.stringify(endpoint.targetUrl)};`,
-        "const normalizeUrl = (value) => String(value || '').replace(/\\/$/, '');",
-        "const httpPages = Array.isArray(pages) ? pages.filter((entry) => entry && entry.type === 'page' && /^https?:/.test(String(entry.url || ''))) : [];",
-        prefer === "active"
-            ? "const page = httpPages[0] || (expectedTargetId ? httpPages.find((entry) => entry.id === expectedTargetId) : undefined);"
-            : "const page = expectedTargetId ? httpPages.find((entry) => entry.id === expectedTargetId) : (httpPages.find((entry) => normalizeUrl(entry.url) === normalizeUrl(expectedTargetUrl)) || (httpPages.length === 1 ? httpPages[0] : undefined));"
-    ];
-}
-export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs, endpoint, targetId) {
+export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs, endpoint, targetId, onUnavailable) {
+    let reported = false;
+    const unavailable = (reason) => {
+        if (!reported) {
+            reported = true;
+            onUnavailable?.(reason);
+        }
+        return {};
+    };
     return async () => {
-        const script = [
-            // "active": follow the participant to whatever tab they are driving now — never pin the
-            // state observer to the launch tab (see chromeCdpPageSelectionScript).
-            ...chromeCdpPageSelectionScript(endpoint, targetId, "active"),
-            "if (!page) { console.log('{}'); process.exit(0); }",
-            "let text = '';",
-            "let scrollY = undefined;",
-            "let url = String(page.url || '');",
-            "let title = String(page.title || '');",
-            "if (typeof WebSocket === 'function' && page.webSocketDebuggerUrl) {",
-            "  const ws = new WebSocket(page.webSocketDebuggerUrl);",
-            "  const result = await new Promise((resolve) => {",
-            "    const timer = setTimeout(() => resolve(undefined), 1500);",
-            "    ws.onopen = () => ws.send(JSON.stringify({ id: 1, method: 'Runtime.evaluate', params: { returnByValue: true, expression: '({ url: location.href, title: document.title, text: (document.body && document.body.innerText || \"\").slice(0, 20000), scrollY: (window.scrollY || 0) })' } }));",
-            "    ws.onmessage = (event) => {",
-            "      try {",
-            "        const payload = JSON.parse(String(event.data));",
-            "        if (payload.id !== 1) return;",
-            "        clearTimeout(timer);",
-            "        resolve(payload.result && payload.result.result && payload.result.result.value);",
-            "      } catch { clearTimeout(timer); resolve(undefined); }",
-            "    };",
-            "    ws.onerror = () => { clearTimeout(timer); resolve(undefined); };",
-            "  }).finally(() => { try { ws.close(); } catch {} });",
-            "  if (result && typeof result === 'object') {",
-            "    url = typeof result.url === 'string' ? result.url : url;",
-            "    title = typeof result.title === 'string' ? result.title : title;",
-            "    text = typeof result.text === 'string' ? result.text : '';",
-            "    scrollY = typeof result.scrollY === 'number' ? result.scrollY : undefined;",
-            "  }",
-            "}",
-            "console.log(JSON.stringify({ url, title, text, scrollY }));"
-        ].join("\n");
-        const result = await desktop.commands.run(`node --input-type=module -e ${shellSingleQuote(script)}`, {
-            requestTimeoutMs,
-            timeoutMs: 5_000
-        });
+        const result = await desktop.commands.run(chromeCdpProbeCommand({ ...endpoint, ...(targetId === undefined ? {} : { targetId }), prefer: "active", mode: "state" }), { requestTimeoutMs, timeoutMs: 5_000 });
         if (result.exitCode !== undefined && result.exitCode !== 0) {
-            return {};
-        }
-        try {
-            const parsed = JSON.parse((result.stdout ?? "{}").trim() || "{}");
-            if (!parsed || typeof parsed !== "object") {
-                return {};
-            }
-            const record = parsed;
-            return {
-                ...(typeof record.url === "string" && record.url.length > 0 ? { url: record.url } : {}),
-                ...(typeof record.title === "string" && record.title.length > 0 ? { title: record.title } : {}),
-                ...(typeof record.text === "string" && record.text.length > 0 ? { text: record.text } : {}),
-                ...(typeof record.scrollY === "number" && Number.isFinite(record.scrollY) ? { scrollY: record.scrollY } : {})
-            };
-        }
-        catch {
-            return {};
+            return unavailable(`probe exited ${result.exitCode}: ${tailOf(result.stderr ?? result.stdout ?? "")}`);
         }
+        const parsed = parseChromeCdpProbeOutput(result.stdout);
+        if (parsed.unavailable !== undefined)
+            return unavailable(parsed.unavailable);
+        return {
+            ...(parsed.url === undefined ? {} : { url: parsed.url }),
+            ...(parsed.title === undefined ? {} : { title: parsed.title }),
+            ...(parsed.text === undefined ? {} : { text: parsed.text }),
+            ...(parsed.scrollY === undefined ? {} : { scrollY: parsed.scrollY })
+        };
     };
 }
 /**
  * Read the running browser's actual outer-window bounds and CSS layout viewport through the
  * already-enabled local Chrome DevTools endpoint. The returned values come from `window.*` in
  * the target page; requested E2B resolution is deliberately not an input to this function.
+ * `undefined` carries the reason the measurement is missing via `onUnavailable`, so the geometry
+ * warning can name the cause (a dead CDP endpoint, no python3) instead of only the symptom.
  */
-export function makeChromeDesktopGeometryObserver(desktop, requestTimeoutMs, endpoint, targetId) {
+export function makeChromeDesktopGeometryObserver(desktop, requestTimeoutMs, endpoint, targetId, onUnavailable) {
     return async () => {
-        const script = [
-            ...chromeCdpPageSelectionScript(endpoint, targetId),
-            "if (!page || typeof WebSocket !== 'function' || !page.webSocketDebuggerUrl) { console.log('{}'); process.exit(0); }",
-            "const ws = new WebSocket(page.webSocketDebuggerUrl);",
-            "const result = await new Promise((resolve) => {",
-            "  const timer = setTimeout(() => resolve(undefined), 1500);",
-            "  ws.onopen = () => ws.send(JSON.stringify({ id: 1, method: 'Runtime.evaluate', params: { returnByValue: true, expression: '({ browserWindow: { x: window.screenX, y: window.screenY, width: window.outerWidth, height: window.outerHeight }, viewport: { width: window.innerWidth, height: window.innerHeight, deviceScaleFactor: window.devicePixelRatio } })' } }));",
-            "  ws.onmessage = (event) => {",
-            "    try {",
-            "      const payload = JSON.parse(String(event.data));",
-            "      if (payload.id !== 1) return;",
-            "      clearTimeout(timer);",
-            "      resolve(payload.result && payload.result.result && payload.result.result.value);",
-            "    } catch { clearTimeout(timer); resolve(undefined); }",
-            "  };",
-            "  ws.onerror = () => { clearTimeout(timer); resolve(undefined); };",
-            "}).finally(() => { try { ws.close(); } catch {} });",
-            "console.log(JSON.stringify(result ? { ...result, targetId: String(page.id || '') } : {}));"
-        ].join("\n");
-        const result = await desktop.commands.run(`node --input-type=module -e ${shellSingleQuote(script)}`, {
-            requestTimeoutMs,
-            timeoutMs: 5_000
-        });
+        const result = await desktop.commands.run(chromeCdpProbeCommand({ ...endpoint, ...(targetId === undefined ? {} : { targetId }), prefer: "pinned", mode: "geometry" }), { requestTimeoutMs, timeoutMs: 5_000 });
         if (result.exitCode !== undefined && result.exitCode !== 0) {
+            onUnavailable?.(`probe exited ${result.exitCode}: ${tailOf(result.stderr ?? result.stdout ?? "")}`);
             return undefined;
         }
-        try {
-            const parsed = JSON.parse((result.stdout ?? "{}").trim() || "{}");
-            if (!parsed || typeof parsed !== "object")
-                return undefined;
-            const record = parsed;
-            const rawWindow = record.browserWindow;
-            const rawViewport = record.viewport;
-            if (!isMeasuredRect(rawWindow) || !isMeasuredViewport(rawViewport))
-                return undefined;
-            return {
-                browserWindow: { ...rawWindow, source: "cdp" },
-                viewport: { ...rawViewport, source: "cdp" },
-                ...(typeof record.targetId === "string" && record.targetId.length > 0 ? { targetId: record.targetId } : {})
-            };
+        const parsed = parseChromeCdpProbeOutput(result.stdout);
+        if (parsed.unavailable !== undefined) {
+            onUnavailable?.(parsed.unavailable);
+            return undefined;
         }
-        catch {
+        if (!isMeasuredRect(parsed.browserWindow) || !isMeasuredViewport(parsed.viewport)) {
+            onUnavailable?.("the page reported no usable window or viewport dimensions");
             return undefined;
         }
+        return {
+            browserWindow: { ...parsed.browserWindow, source: "cdp" },
+            viewport: { ...parsed.viewport, source: "cdp" },
+            ...(parsed.targetId === undefined ? {} : { targetId: parsed.targetId })
+        };
     };
 }
 function isMeasuredRect(value) {
@@ -1063,12 +1003,18 @@ export async function captureDesktopBrowserGeometry(args) {
     else {
         warnings.push(`Browser window bounds could not be measured for lane ${args.laneId}; the live stream will use the full desktop.`);
     }
+    let cdpUnavailable;
     const chromeGeometry = args.browserFamily === "chromium"
         ? await makeChromeDesktopGeometryObserver(args.desktop, args.requestTimeoutMs, {
             ...(args.launchIdentity?.cdpPort === undefined ? {} : { cdpPort: args.launchIdentity.cdpPort }),
             ...(args.launchIdentity?.profileDir === undefined ? {} : { profileDir: args.launchIdentity.profileDir }),
             targetUrl: args.targetUrl
-        }, args.browserTargetId)().catch(() => undefined)
+        }, args.browserTargetId, (reason) => {
+            cdpUnavailable = reason;
+        })().catch((error) => {
+            cdpUnavailable = toErrorMessage(error);
+            return undefined;
+        })
         : undefined;
     const browserWindow = chromeGeometry?.browserWindow ?? xdotoolWindow;
     const viewport = chromeGeometry?.viewport;
@@ -1079,9 +1025,12 @@ export async function captureDesktopBrowserGeometry(args) {
         warnings.push(`Browser window fill did not reach the requested ${args.requestedScreen[0]}x${args.requestedScreen[1]} screen for lane ${args.laneId}; measured outer bounds are ${browserWindow.width}x${browserWindow.height}.`);
     }
     if (!viewport) {
+        // Name the cause, not only the symptom: the same dead DevTools channel that loses the viewport
+        // loses every url/text observation, and a reader of the bundle should learn that here (#514).
+        const cause = cdpUnavailable === undefined ? "" : ` DevTools probe: ${redactText(cdpUnavailable)}.`;
         warnings.push(args.browserFamily === "firefox"
             ? `Browser CSS viewport measurement is unavailable for Firefox on lane ${args.laneId}; stream.viewport is omitted instead of reading a different browser's CDP endpoint.`
-            : `Browser CSS viewport could not be measured for lane ${args.laneId}; stream.viewport is omitted instead of copying the requested screen resolution.`);
+            : `Browser CSS viewport could not be measured for lane ${args.laneId}; stream.viewport is omitted instead of copying the requested screen resolution.${cause}`);
     }
     return {
         ...(browserWindowId === undefined ? {} : { browserWindowId }),
@@ -1752,7 +1701,13 @@ export async function runCuaLane(spec, deps) {
                                 ...(browserLaunchIdentity?.cdpPort === undefined ? {} : { cdpPort: browserLaunchIdentity.cdpPort }),
                                 ...(browserLaunchIdentity?.profileDir === undefined ? {} : { profileDir: browserLaunchIdentity.profileDir }),
                                 targetUrl
-                            }, browserTargetId)
+                            }, browserTargetId, 
+                            // Once per lane: a dark observation channel is a gap in the instrument, and the
+                            // funnel's NEVER MEASURED count needs this line to explain itself (#514).
+                            (reason) => {
+                                warnings.push(`Browser-state observer unavailable for lane ${spec.laneId} (${redactText(deps.scrubKnownValues(reason))}); ` +
+                                    "urlIncludes/urlPathEquals/textIncludes stop conditions and task criteria are NOT being measured this session.");
+                            })
                         }
                     }
                     : {}),
@@ -3288,13 +3243,17 @@ async function runSubjectServePipeline(desktop, args) {
     if (needsNodeRuntime(serveCommands)) {
         const runtimeStartedAt = now();
         emitPhaseStarted(args.onPhase, now, "runtime", "providing the Node runtime the serve pipeline needs");
-        const bootstrap = await runDetachedStep(desktop, {
+        const bootstrap = await runProvisioningStepWithOneRetry(desktop, {
             name: "subject-runtime-node",
             command: nodeBootstrapCommand(),
             cwd: SUBJECT_DIR,
             timeoutMs: args.serve.installTimeoutMs ?? INSTALL_TIMEOUT_MS,
             requestTimeoutMs: args.requestTimeoutMs,
-            ...timers
+            timers,
+            retryPhase: "runtime-retry",
+            retryMessage: "Node runtime bootstrap",
+            onPhase: args.onPhase,
+            now
         });
         let ok = bootstrap.ok;
         const corepack = ok ? corepackCommandFor(serveCommands) : undefined;
@@ -3311,23 +3270,39 @@ async function runSubjectServePipeline(desktop, args) {
         }
         emitPhaseCompleted(args.onPhase, now, runtimeStartedAt, "runtime", ok, ok ? "Node runtime ready" : "could not provide a Node runtime");
         if (!ok) {
-            throw new Error(`the subject's serve pipeline needs a Node runtime and this desktop template has none, and bootstrapping one failed: ${tailOf(args.scrub(bootstrap.logTail))}. Use execution.desktop.template with an image that ships Node, or change serve.install to a runtime the template provides.`);
+            throw new Error(`the subject's serve pipeline needs a Node runtime and this desktop template has none, and bootstrapping one failed${bootstrap.attempts === 2 ? " twice" : ""}: ${tailOf(args.scrub(bootstrap.logTail))}. Use execution.desktop.template with an image that ships Node, or change serve.install to a runtime the template provides.`);
         }
     }
     if (args.serve.install) {
         const installStartedAt = now();
         emitPhaseStarted(args.onPhase, now, "install", "installing subject dependencies");
-        const install = await runDetachedStep(desktop, {
+        const install = await runProvisioningStepWithOneRetry(desktop, {
             name: "subject-install",
             command: args.serve.install,
             cwd: SUBJECT_DIR,
             timeoutMs: args.serve.installTimeoutMs ?? INSTALL_TIMEOUT_MS,
             requestTimeoutMs: args.requestTimeoutMs,
-            ...timers
+            timers,
+            retryPhase: "install-retry",
+            retryMessage: "subject install",
+            onPhase: args.onPhase,
+            now
         });
-        emitPhaseCompleted(args.onPhase, now, installStartedAt, "install", install.ok, install.ok ? "subject dependencies installed" : "subject install failed");
+        emitPhaseCompleted(args.onPhase, now, installStartedAt, "install", install.ok, install.ok
+            ? install.attempts === 2
+                ? "subject dependencies installed (on the second attempt)"
+                : "subject dependencies installed"
+            : install.attempts === 2
+                ? "subject install failed twice"
+                : "subject install failed");
         if (!install.ok) {
-            throw new Error(`subject install ${install.timedOut ? "timed out" : `failed (exit ${install.exitCode})`}: ${tailOf(args.scrub(install.logTail))}`);
+            // Lead with the line a person can act on; npm's own trace follows it (#602).
+            const headline = install.timedOut
+                ? `subject install timed out after ${args.serve.installTimeoutMs ?? INSTALL_TIMEOUT_MS}ms`
+                : install.attempts === 2
+                    ? `subject install failed twice (exit ${install.firstExitCode ?? "null"}, then exit ${install.exitCode ?? "null"}); the sandbox could not complete serve.install`
+                    : `subject install failed (exit ${install.exitCode ?? "null"})`;
+            throw new Error(`${headline}: ${tailOf(args.scrub(install.logTail))}`);
         }
         await refresh();
     }