Skip to content

fix(sdk): replace a service worker left over from a different extension build - #3502

Open
miguelg719 wants to merge 11 commits into
mainfrom
miguelgonzalez/ap-3226-never-run-a-stale-service-worker
Open

miguelg719 wants to merge 11 commits into
mainfrom
miguelgonzalez/ap-3226-never-run-a-stale-service-worker

Conversation

@miguelg719

@miguelg719 miguelg719 commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

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

  • The extension build stamps an identity into the service worker (__stagehand_build_id) and writes it to build-id.txt.
  • After attaching, the TypeScript and Python SDKs compare the two. If the SDK loaded the extension, or finds it installed from its own directory, it loads it again from that directory, which replaces the worker and keeps the extension's own storage. Otherwise it warns and continues. A missing file, an unstamped identity or a failed read is not compared.
  • If that load fails, or does not clear the mismatch, the SDK warns and continues with the running worker.
  • Builds on fix(extension): inject the content script into documents that were already open #3501 (merged), the content-script injection change, since a repair reloads the extension while pages are open.
  • The Go SDK is out of scope.

test plan

  • Unit tests in both SDKs, an extension build test, and a parity test pinning the file name, global name and placeholder. The Python repair is covered by unit tests only.
  • A real-browser test loads build A, then B with a bumped manifest version, at one path and profile: B's connect finds A's worker, loads the extension again and ends on B, with no uninstall.
  • Real Chrome, both changes: reconnect after the directory changed, then navigation, snapshots, typing and clicks on open pages, after reload and in new tabs, 10 runs each.

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.

  • The extension build stamps an identity into the worker and writes 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.
  • On worker start, the service worker injects the content script into every frame of open http(s) and file tabs. The readiness check now also requires chrome.runtime.id to detect a stale copy. The Go SDK is out of scope.

Written for commit 11184f6. Summary will update on new commits.

View guided diff Turn on auto-fix

…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-bot

changeset-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 11184f6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 19 packages
Name Type
@browserbasehq/stagehand-extension Patch
@browserbasehq/stagehand Patch
@browserbasehq/stagehand-python Patch
browse Patch
@browserbasehq/stagehand-examples Patch
@browserbasehq/stagehand-integrations-claude-cua-sdk Patch
@browserbasehq/stagehand-integrations Patch
@browserbasehq/eve Patch
@browserbasehq/stagehand-integrations-gemini-cua-sdk Patch
@browserbasehq/stagehand-integrations-example-pi-facade Patch
@browserbasehq/stagehand-integrations-claude-code Patch
@browserbasehq/stagehand-integrations-codex Patch
@browserbasehq/stagehand-integrations-cursor Patch
@browserbasehq/stagehand-integrations-deepagents-sdk Patch
@browserbasehq/stagehand-integrations-fx Patch
@browserbasehq/stagehand-integrations-mastra Patch
@browserbasehq/stagehand-integrations-pi-sdk Patch
@browserbasehq/stagehand-integrations-example-vercel-ai-facade Patch
@browserbasehq/stagehand-integrations-eve-harness Patch

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

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread packages/sdk-ts/src/cdpClient.ts Resolved

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 issue found across 12 files

Confidence score: 4/5

  • In cdpClient.test.ts, a setup or wait failure can leave the fake WebSocket installed and contaminate later tests. Restore the original global in a finally block 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
Loading

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

Comment thread packages/sdk-ts/tests/cdpClient.test.ts Resolved
Base automatically changed from miguelgonzalez/ap-3225-extension-inject-the-content-script to main November 19, 2026 23:57
Comment thread packages/sdk-ts/src/cdpClient.ts Outdated
loadedFrom = options.localExtensionDir;
}
if (isStaleServiceWorker(build) && loadedFrom !== undefined) {
await client.sendCommand("Extensions.uninstall", { id: extensionId }, undefined, signal);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

addressed in c162934

Comment thread packages/sdk-ts/src/cdpClient.ts Outdated
} catch (error) {
throwIfAborted(options.signal);
if (error instanceof CDPConnectionClosedError) throw error;
return { running: null, onDisk: null };

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

addressed in c162934

)
return worker, _required_string(attached, "sessionId", "Target.attachToTarget")

async def _read_service_worker_build(self, session_id: str) -> _ServiceWorkerBuild:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.)

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

addressed in c162934

Comment thread packages/sdk-ts/src/cdpClient.ts Outdated
loadedFrom = options.localExtensionDir;
}
if (isStaleServiceWorker(build) && loadedFrom !== undefined) {
await client.sendCommand("Extensions.uninstall", { id: extensionId }, undefined, signal);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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> {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good catch addressed in c162934

…in, and keep connecting when it cannot be read

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)
Loading

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread packages/sdk-ts/tests/cdpClient.test.ts Resolved
build = await readServiceWorkerBuild(client, attached.sessionId, { signal });
}
}
if (isStaleServiceWorker(build)) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants