humanish 0.15.2 → 0.16.0

package/dist/cua-actor-lab.d.ts

@@ -11,7 +11,7 @@ import { renderObserver, type ObserverResult } from "./observer.js";
 import { type PreparedOutputDirectory } from "./selected-output-paths.js";
 import { type LocalTreeArchive } from "./source-archive.js";
 import type { StopWhen } from "./stop-conditions.js";
-import { type RunBundle, type RunRerunLineage, type RunProviderResource, type RunSubjectProvenance, type RunSubjectStateStepRecord } from "./run.js";
+import { type RunBundle, type RunDesktopGeometry, type RunRerunLineage, type RunProviderResource, type RunSubjectProvenance, type RunSubjectStateStepRecord } from "./run.js";
 export declare const CUA_ACTOR_LAB_SCHEMA = "humanish.cua-lab-result.v2";
 export declare const CUA_FANOUT_STRATEGY: "per-lane-worlds";
 export declare const CUA_ACTOR_LAB_PROVIDER_METADATA: {
@@ -22,6 +22,20 @@ export interface DesktopBrowserEvidence {
     requested: LabDesktopBrowser;
     resolved?: string;
 }
+export type DesktopBrowserFamily = "chromium" | "firefox" | "unknown";
+/** Runtime-only identity for the exact browser process started by this lane. */
+export interface DesktopBrowserLaunchIdentity {
+    processId: string;
+    profileDir: string;
+    targetUrl: string;
+    cdpPort?: number;
+}
+/** Runtime-only launch result. `evidence` preserves the existing public persistence policy. */
+export interface DesktopBrowserLaunchResult {
+    family: DesktopBrowserFamily;
+    identity?: DesktopBrowserLaunchIdentity;
+    evidence?: DesktopBrowserEvidence;
+}
 export declare const SUBJECT_DIR = "/home/user/subject";
 /**
  * One phase-boundary event from the shared subject provisioning pipeline (clone or local-tree
@@ -160,6 +174,7 @@ export interface CuaLanePlanEntry {
     index: number;
     persona: string;
     device: string;
+    /** Requested E2B/X screen resolution. This is not the measured browser CSS viewport. */
     resolution: [number, number];
     instructionDigest: string;
     /** Present only when a lane overrides subject.appUrl; digest avoids leaking preview hosts in plan logs. */
@@ -192,6 +207,7 @@ export interface CuaLaneResult {
     index: number;
     persona: string;
     device: string;
+    /** Requested E2B/X screen resolution. See the run stream's desktopGeometry for measurements. */
     resolution: [number, number];
     /** Terminal lane status; "blocked" = skipped (gate/fail-fast); "contract_proof_only" = dry-run. */
     status: ActorStatus | "blocked" | "contract_proof_only";
@@ -403,6 +419,14 @@ export interface CuaLaneDeps {
     hooks: CuaActorLabHooks;
     /** Lane-0 only: signal the pipeline gate after provisioning succeeds (true) or fails (false). */
     signalProvisioned?: (ok: boolean) => void;
+    /**
+     * How a PARSEABLE requested-vs-verified screen mismatch is treated. Default ("fail-closed"):
+     * the lane's device claim is falsified, so the lane fails with DEVICE_GEOMETRY (the
+     * single-lane/fan-out contract). "record-evidence" (the concurrent shared-world route):
+     * requested and verified stay recorded as separate facts plus an explicit warning, and the
+     * lane keeps running, so one seat's screen drift cannot abort a live multi-actor world.
+     */
+    screenMismatchPolicy?: "fail-closed" | "record-evidence";
 }
 /** One lane's end-to-end run outcome (internal; projected into CuaLaneResult + the bundle). */
 export interface LaneRunOutcome {
@@ -415,6 +439,8 @@ export interface LaneRunOutcome {
     screenshots: string[];
     subjectCommit?: string;
     desktopBrowser?: DesktopBrowserEvidence;
+    /** Requested + measured desktop/browser geometry. Viewport is absent when measurement failed. */
+    desktopGeometry?: RunDesktopGeometry;
     stateStepRecords: RunSubjectStateStepRecord[];
     /** Completed subject-phase records (clone/upload/extract/install/build/ready/state groups),
      *  folded into bundle.events at build time. Empty on the in-process route (no provisioning). */
@@ -434,6 +460,22 @@ export interface LaneRunOutcome {
 export declare function makeLaneWriteScreenshot(artifactRoot: PreparedOutputDirectory, spec: {
     screenshotDir: string;
 }, screenshots: string[]): (name: string, bytes: Buffer) => Promise<string>;
+/**
+ * Verify the desktop screen geometry IN-SANDBOX (the per-lane device claim is checked, never
+ * assumed). A parseable mismatch fails closed. Unavailable/unparseable evidence is returned as
+ * an explicit warning: the lane may still run, but its bundle records only the requested screen
+ * and never upgrades that request into a verified measurement.
+ */
+export declare function inspectDesktopScreenGeometry(args: {
+    desktop: E2BDesktopSandbox;
+    laneId: string;
+    requestedScreen: readonly [number, number];
+    requestTimeoutMs: number;
+}): Promise<{
+    verified?: RunDesktopGeometry["screen"]["verified"];
+    error?: string;
+    warning?: string;
+}>;
 /**
  * Build the xdotool command that makes a browser window fill the desktop.
  * Exported (pure) for contract tests. A window manager can ignore Chrome's
@@ -442,11 +484,62 @@ export declare function makeLaneWriteScreenshot(artifactRoot: PreparedOutputDire
  * dead margin around the browser.
  */
 export declare function buildFillDesktopWindowCommand(windowId: string, width: number, height: number): string;
-export declare function makeChromeBrowserStateObserver(desktop: E2BDesktopSandbox, requestTimeoutMs: number): () => Promise<{
+export declare function desktopBrowserFamily(value: string | undefined): DesktopBrowserFamily;
+/**
+ * Runtime-only CDP endpoint attribution for the exact chromium this lane launched. Port
+ * resolution at OBSERVE time: the cached launch-time `cdpPort` wins; absent that, the observer
+ * script re-reads `profileDir`'s DevToolsActivePort marker (a slow cold start can publish it
+ * AFTER the launch-time poll gave up); absent both it falls back to the legacy fixed 9222,
+ * where a dead endpoint degrades into an honest warning.
+ */
+export interface ChromeCdpEndpoint {
+    cdpPort?: number;
+    /** The launched profile dir; lets observers re-read DevToolsActivePort at observe time. */
+    profileDir?: string;
+    /** The URL this lane opened; attributes the CDP page when no target id is pinned yet. */
+    targetUrl: string;
+}
+/**
+ * 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 declare function chromeCdpPortResolutionScript(endpoint: ChromeCdpEndpoint): string[];
+export declare function makeChromeBrowserStateObserver(desktop: E2BDesktopSandbox, requestTimeoutMs: number, endpoint: ChromeCdpEndpoint, targetId?: string): () => Promise<{
     url?: string;
     title?: string;
     text?: string;
 }>;
+/**
+ * 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.
+ */
+export declare function makeChromeDesktopGeometryObserver(desktop: E2BDesktopSandbox, requestTimeoutMs: number, endpoint: ChromeCdpEndpoint, targetId?: string): () => Promise<(Pick<RunDesktopGeometry, "browserWindow" | "viewport"> & {
+    targetId?: string;
+}) | undefined>;
+/** Shared hosted-browser geometry capture used by per-lane and sequential shared-world routes. */
+export declare function captureDesktopBrowserGeometry(args: {
+    desktop: E2BDesktopSandbox;
+    browserFamily: DesktopBrowserFamily;
+    launchIdentity?: DesktopBrowserLaunchIdentity;
+    browserTargetId?: string;
+    browserWindowId?: string;
+    laneId: string;
+    /** Runtime-only lane target URL (attributes the CDP page); never persisted by this capture. */
+    targetUrl: string;
+    requestedScreen: readonly [number, number];
+    requestTimeoutMs: number;
+    resize?: boolean;
+}): Promise<{
+    browserWindowId?: string;
+    browserTargetId?: string;
+    browserWindow?: RunDesktopGeometry["browserWindow"];
+    viewport?: RunDesktopGeometry["viewport"];
+    warnings: string[];
+}>;
 /**
  * Run ONE E2B desktop lane end-to-end: create the sandbox (per-lane metadata + the lane's device
  * resolution), prepareDesktop, verify geometry, (clone+serve+seed the subject per lane), open the
@@ -556,8 +649,12 @@ export declare function buildCuaBundle(args: {
     mission: string;
     persona: ActorPersonaRef;
     resolution: [number, number];
-    /** Device metadata for the stream viewport (honest; isMobile/DSF are not rendered on this route). */
-    deviceScaleFactor?: number;
+    /** False only for the custom in-process route, which has no hosted screen/window to claim. */
+    desktopRoute?: boolean;
+    /** Runtime screen/window/viewport evidence. `viewport` inside this object must be measured. */
+    desktopGeometry?: RunDesktopGeometry;
+    /** Device-preset touch metadata echoed on the measured stream viewport (a prompt signal on
+     *  this route, never a rendered claim); the measured width/height/DPR stay authoritative. */
     isMobile?: boolean;
     runId: string;
     screenshots: string[];