feat(extension): add resident browser proxy CDP resolver

[miguelg719]

Summary

Stack A/5 (resident Stagehand on main): feat/resident-main-a-transport (this PR) → -b-target-safety → -c-gateway-runtime → -d-artifacts → -e-browserbase-opt-in. Supersedes #2463 (archived v4-spike base).

Adds the resident browser proxy CDP resolver (packages/extension/service-worker-lifecycle/resident-browser-proxy.ts) used by the image-resident extension to find Chromium through pid2's loopback filtered proxy (127.0.0.1:9224, Go #3193–#3196): fetch /json/version from a loopback-only http(s) origin, validate that Chromium returned a loopback ws(s)://…/devtools/browser/<id> URL, and rewrite only scheme+authority to the proxy while preserving the exact target path/query.

Inert in this PR: nothing imports the module yet (wired in stack C). No ordinary-session behavior changes.

Changes vs the v4-spike version, from the 2026-08-20 review: accepts wss: when the proxy is https: (matches the Go side), emits path/query from the validated URL (not a raw slice), abort reason carries the proxy URL and budget, timeout raised 1 s → 5 s to match the Go upstream dial timeout, tests for identity rewrite / [::1] / trailing slash / fragment.

Validation

pnpm check, extension unit tests (incl. extension-source-compatibility), protocol tests — green. Verified end to end on a devbox k3d stack with the real image bytes (see stack E).

[changeset-bot]

⚠️ No Changeset found

Latest commit: d842e1b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

1 issue found across 2 files

Confidence score: 5/5

• packages/extension/service-worker-lifecycle/resident-browser-proxy.ts omits the proxy URL from timeout abort reasons, making it harder to identify which resident endpoint failed from logs; include the proxy origin alongside timeoutMs in the error.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/extension/service-worker-lifecycle/resident-browser-proxy.ts">

<violation number="1" location="packages/extension/service-worker-lifecycle/resident-browser-proxy.ts:24">
P2: When a timeout occurs, the abort reason omits the proxy URL, so logs cannot identify which resident endpoint timed out. Include the proxy origin alongside `timeoutMs` in this error.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Ext as Extension (Service Worker)
    participant Resolver as ResidentBrowserProxyResolver
    participant Proxy as Loopback Proxy (127.0.0.1:9224)
    participant Chromium as Chromium (Internal)

    Note over Ext,Chromium: NEW: Resident Browser Discovery Flow

    Ext->>Resolver: resolveResidentBrowserWebSocketUrl(proxyUrl)
    
    Resolver->>Resolver: NEW: parseBrowserProxyUrl()<br/>(Validate loopback + origin-only)
    
    rect rgb(240, 240, 240)
        Note right of Resolver: Start 5s Timeout Budget
        
        Resolver->>Proxy: NEW: GET /json/version
        Proxy->>Chromium: Forward version request
        Chromium-->>Proxy: 200 OK (JSON with webSocketDebuggerUrl)
        Proxy-->>Resolver: Return browser metadata
        
        alt Request timed out or HTTP error
            Resolver-->>Ext: Throw AbortError / HTTP Error
        end
    end

    Resolver->>Resolver: NEW: Zod parse BrowserVersionSchema
    
    Resolver->>Resolver: NEW: rewriteDebuggerUrl()<br/>(Validate loopback ws/wss target)
    
    Note over Resolver: NEW: Protocol Mapping<br/>http -> ws | https -> wss
    
    Resolver->>Resolver: NEW: Map internal Chromium path/query<br/>to Proxy authority

    alt Validation Failure (e.g. non-loopback or invalid path)
        Resolver-->>Ext: Throw Validation Error
    else Success
        Resolver-->>Ext: Return proxied WebSocket URL
    end

    Note over Ext,Proxy: Future: Connect to Browser via Proxy WS URL

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: When a timeout occurs, the abort reason omits the proxy URL, so logs cannot identify which resident endpoint timed out. Include the proxy origin alongside timeoutMs in this error.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/extension/service-worker-lifecycle/resident-browser-proxy.ts, line 24:

<comment>When a timeout occurs, the abort reason omits the proxy URL, so logs cannot identify which resident endpoint timed out. Include the proxy origin alongside `timeoutMs` in this error.</comment>

<file context>
@@ -0,0 +1,90 @@
+  const timeout = setTimeout(
+    () =>
+      abortController.abort(
+        new Error(`Resident browser proxy version request timed out after ${timeoutMs}ms`),
+      ),
+    timeoutMs,
</file context>