Repository navigation
fix(sdk): replace a service worker left over from a different extension build - #3502
miguelg719 wants to merge 11 commits into
Conversation
…ready open Chrome adds manifest content scripts only to documents created after the extension loads, so locator operations timed out on pages that were open before the extension was loaded into a running browser. Whenever the service worker starts, it now injects the content script into every frame of each open http(s) or file tab and logs any failure to the worker console. Worker start covers install, reload, update and re-enable, which onInstalled misses; the content script ignores a second run in the same world. A copy of the extension that was unloaded or disabled leaves its worlds in open tabs. The readiness check now also requires chrome.runtime.id, which Chrome removes from those worlds, and the readiness timeout error reports it.
…on build Chrome keeps an extension's service-worker registration and script in the profile under the extension ID, which an unpacked extension derives from its path. When a profile that ran one build loads another build from the same path, the old worker keeps running next to the new content script, even across a manifest version bump. The extension build now stamps an identity into the service worker (globalThis.__stagehand_build_id) and writes it to build-id.txt. The identity is the fingerprint of the build before stamping, so the shipped fingerprint, which covers the stamped files, stays separate. The runtime marker is unchanged. After attaching to the worker, both SDKs compare the running identity with the directory's build-id.txt. If the SDK loaded the extension, or finds it installed from the SDK's own extension directory, it uninstalls and loads it again. If that load fails, the error says the extension was uninstalled and not loaded again. For an extension it does not own, or when the repair does not clear the mismatch, it logs a warning and continues. A read that fails or times out, and an unstamped identity, are not compared.
🦋 Changeset detectedLatest commit: 11184f6 The changes in this PR will be included in the next version bump. This PR includes changesets to release 19 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
There was a problem hiding this comment.
Review completed against the latest diff
Reply with feedback, questions, or to request a fix.
View guided diff | Turn on auto-fix | Re-trigger cubic
There was a problem hiding this comment.
1 issue found across 12 files
Confidence score: 4/5
- In
cdpClient.test.ts, a setup or wait failure can leave the fakeWebSocketinstalled and contaminate later tests. Restore the original global in afinallyblock around the full helper flow.
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="packages/sdk-ts/tests/cdpClient.test.ts">
<violation number="1" location="packages/sdk-ts/tests/cdpClient.test.ts:753">
P2: `connectWith` leaves the fake `WebSocket` installed if setup or `vi.waitFor` throws, which can contaminate later tests. Restore the original global in a `finally` block around the helper’s full setup and connection flow.</violation>
</file>
Architecture diagram
sequenceDiagram
participant SDK as TypeScript/Python SDK
participant CDP as CDP Client
participant Chrome as Chrome Browser
participant SW as Service Worker (Extension)
participant File as build-id.txt (extension dir)
Note over SDK,File: Extension identity comparison and repair flow
SDK->>CDP: connect() with extension source
CDP->>Chrome: Discover or load extension
alt Extension not loaded
Chrome-->>CDP: Extension ID + path
CDP->>Chrome: Extensions.loadUnpacked(path)
Chrome-->>CDP: Extension ID
else Extension already installed
Chrome-->>CDP: Extension ID + install path
end
CDP->>Chrome: Target.getTargets (service worker)
Chrome-->>CDP: Worker target ID
CDP->>Chrome: Target.attachToTarget(workerId)
Chrome-->>CDP: sessionId
CDP->>SW: Runtime.evaluate (read build identities)
SW->>SW: Read globalThis.__stagehand_build_id
SW->>File: fetch(chrome.runtime.getURL("build-id.txt"))
File-->>SW: On-disk build ID (or null)
SW-->>CDP: { running, onDisk }
alt Build IDs match or missing/unstamped
CDP->>Chrome: Continue with current worker
else Stale worker detected AND SDK owns extension
CDP->>Chrome: Extensions.uninstall(extensionId)
Chrome-->>CDP: Uninstalled
CDP->>Chrome: Extensions.loadUnpacked(loadedFrom)
Chrome-->>CDP: New extension ID
CDP->>Chrome: Target.getTargets (exclude old worker)
Chrome-->>CDP: New worker target ID
CDP->>Chrome: Target.attachToTarget(newWorkerId)
Chrome-->>CDP: New sessionId
CDP->>SW: Runtime.evaluate (verify build)
SW-->>CDP: { running, onDisk }
alt Reload succeeded and build matches
CDP->>Chrome: Continue with new worker
else Reload failed
CDP-->>SDK: Error: extension uninstalled, could not reload
else Still stale after reload
CDP->>SDK: Warning: continues with running worker
end
else Stale worker detected AND SDK does NOT own extension
CDP->>SDK: Warning: continues with running worker
end
Requires human review: Auto-approval blocked because this review re-detected 1 unresolved issue already reported by Cubic.
View guided diff | Turn on auto-fix | Re-trigger cubic
| loadedFrom = options.localExtensionDir; | ||
| } | ||
| if (isStaleServiceWorker(build) && loadedFrom !== undefined) { | ||
| await client.sendCommand("Extensions.uninstall", { id: extensionId }, undefined, signal); |
There was a problem hiding this comment.
If Extensions.uninstall is rejected (unsupported by a proxy, policy-installed extension, etc.), connect now throws a raw CDP error. before this PR it would have connected and run. should we catch here and fall through to the stale-worker warning instead of failing the connect? Same at cdp_client.py:370
| } catch (error) { | ||
| throwIfAborted(options.signal); | ||
| if (error instanceof CDPConnectionClosedError) throw error; | ||
| return { running: null, onDisk: null }; |
There was a problem hiding this comment.
A thrown Runtime.evaluate returns "unidentified" immediately, but a null result keeps polling. Right after attachToTarget the worker context may not be ready yet, so a transient error here would silently skip the check — a genuinely stale worker would be kept with no warning. Should transient errors retry like the null case (bounded), and only give up after that? Same at cdp_client.py:719.
| ) | ||
| return worker, _required_string(attached, "sessionId", "Target.attachToTarget") | ||
|
|
||
| async def _read_service_worker_build(self, session_id: str) -> _ServiceWorkerBuild: |
There was a problem hiding this comment.
This loop has no timeout of its own — it only stops via the 60s init deadline, and then the error is a generic "initialization timed out." Direct CDPClient.connect callers get no bound at all. Could we wrap it in a short asyncio.timeout and either treat it as unidentified or raise an error that says the worker never published its runtime marker? (TS is bounded by signal, so this is Python-only.)
| loadedFrom = options.localExtensionDir; | ||
| } | ||
| if (isStaleServiceWorker(build) && loadedFrom !== undefined) { | ||
| await client.sendCommand("Extensions.uninstall", { id: extensionId }, undefined, signal); |
There was a problem hiding this comment.
Two consequences of uninstall vs. reload worth confirming are intended:
- On a shared long-lived browser, another client still attached to the old worker loses its session mid-run.
- Uninstall wipes the extension's chrome.storage / IndexedDB / dynamic DNR rules in a persistent profile.
Did you try re-running Extensions.loadUnpacked on the same path (or chrome.runtime.reload() via the attached session) instead? If either reliably replaces the stale worker, it'd avoid both of the above issues
There was a problem hiding this comment.
Tried both. Re-running loadUnpacked on the same path replaces the worker and keeps the extension's storage, so I switched to that and dropped the uninstall
| } | ||
|
|
||
| async function getInstalledStagehandExtensionId( | ||
| async function sameDirectory(first: string, second: string): Promise<boolean> { |
There was a problem hiding this comment.
On macOS/Windows, could Chrome report the extension path with different casing than STAGEHAND_EXTENSION_DIRECTORY_PATH? If so, the SDK-upgrade case only warns instead of replacing. Have you seen this match in practice on macOS? Same for os.path.realpath at cdp_client.py:367.
…in, and keep connecting when it cannot be read
There was a problem hiding this comment.
1 issue found across 12 files
Confidence score: 4/5
- In
packages/sdk-ts/src/cdpClient.ts, repeated comparison failures or a missing build ID are treated as non-stale, so the SDK can continue without the promised diagnostic. Emit a distinct unavailable-build diagnostic.
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="packages/sdk-ts/src/cdpClient.ts">
<violation number="1" location="packages/sdk-ts/src/cdpClient.ts:446">
P2: This gate suppresses the promised diagnostic when comparison is unavailable: repeated evaluation failures or a missing build ID are treated as non-stale, so the SDK continues silently. Emit a distinct unavailable-build warning before continuing.</violation>
</file>
Architecture diagram
sequenceDiagram
participant SDK as TypeScript/Python SDK
participant CDP as CDP Connection
participant Browser as Chrome Browser
participant SW as Service Worker
participant Build as Extension Build System
Note over Build: Build-time identity stamping
Build->>Build: Compute fingerprint of build files
Build->>SW: Inject build ID into worker (globalThis.__stagehand_build_id)
Build->>Build: Write build-id.txt to extension directory
Note over SDK,SW: Connection and stale worker detection
SDK->>CDP: Connect to browser
alt Local extension directory provided
SDK->>Browser: Extensions.getExtensions
Browser-->>SDK: Installed extension info
alt Extension not found
SDK->>Browser: Extensions.loadUnpacked
Browser-->>SDK: Extension ID
end
else Extension directory provided
SDK->>Browser: Extensions.loadUnpacked
Browser-->>SDK: Extension ID
end
SDK->>Browser: Target.getTargets
Browser-->>SDK: Service worker target
SDK->>Browser: Target.attachToTarget
Browser-->>SDK: Session ID
SDK->>SW: Runtime.evaluate - read build IDs
SW->>SW: Read globalThis.__stagehand_build_id
SW->>SW: Fetch chrome.runtime.getURL("build-id.txt")
SW-->>SDK: { running: buildId, onDisk: buildId }
alt Stale worker detected (running != onDisk)
alt SDK owns the extension (loaded it or installed from its own directory)
SDK->>Browser: Extensions.loadUnpacked (reload)
Browser-->>SDK: Extension ID
SDK->>Browser: Target.getTargets (exclude old worker)
Browser-->>SDK: New worker target
SDK->>Browser: Target.attachToTarget
Browser-->>SDK: New session ID
SDK->>SW: Runtime.evaluate - verify new build
SW-->>SDK: { running: newBuildId, onDisk: newBuildId }
alt Build mismatch persists
SDK-->>SDK: Warn and continue with running worker
end
else External extension (not owned)
SDK-->>SDK: Warn and continue with running worker
end
end
Note over SDK,SW: Stamped worker with content script injection
SW->>SW: On worker start, inject content script into open tabs
SDK->>SW: Runtime.evaluate - readiness check
SW-->>SDK: Ready (with runtime marker)
Reply with feedback, questions, or to request a fix.
View guided diff | Turn on auto-fix | Re-trigger cubic
| build = await readServiceWorkerBuild(client, attached.sessionId, { signal }); | ||
| } | ||
| } | ||
| if (isStaleServiceWorker(build)) { |
There was a problem hiding this comment.
P2: This gate suppresses the promised diagnostic when comparison is unavailable: repeated evaluation failures or a missing build ID are treated as non-stale, so the SDK continues silently. Emit a distinct unavailable-build warning before continuing.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/sdk-ts/src/cdpClient.ts, line 446:
<comment>This gate suppresses the promised diagnostic when comparison is unavailable: repeated evaluation failures or a missing build ID are treated as non-stale, so the SDK continues silently. Emit a distinct unavailable-build warning before continuing.</comment>
<file context>
@@ -395,20 +399,55 @@ export class CDPClient {
+ build = await readServiceWorkerBuild(client, attached.sessionId, { signal });
+ }
+ }
+ if (isStaleServiceWorker(build)) {
+ process.emitWarning(staleServiceWorkerMessage(extensionId, build, replacement), {
+ code: "STAGEHAND_STALE_SERVICE_WORKER",
</file context>
why
Chrome keeps an extension's service worker in the profile under its ID, which an unpacked extension derives from its path. When a profile that ran one build loads another from the same path, the old worker keeps running next to the new content script, even across a manifest version bump. The runtime marker cannot tell them apart.
what changed
__stagehand_build_id) and writes it tobuild-id.txt.test plan
Summary by cubic
Replaces a service worker a browser profile kept from a different extension build, and injects the content script into pages already open when the extension loads.
build-id.txt. The TypeScript and Python SDKs compare the running worker with the file after attaching. If the SDK loaded the extension, or finds it installed from its own directory, it loads it again from that directory, which swaps in the new worker and keeps the extension's own storage; otherwise it warns and continues. The installed directory is matched by filesystem identity, falling back to normalized-path comparison when it cannot be read on the machine the SDK runs on, such as a browser on another host. A missing, empty, or unstamped identity is not compared, and a failed or timed-out read keeps the connection going.http(s)and file tabs. The readiness check now also requireschrome.runtime.idto detect a stale copy. The Go SDK is out of scope.Written for commit 11184f6. Summary will update on new commits.