fix(core): normalize URLs in ActCache key derivation (#2190)

[seanmcguire12]

thanks for the contribution @yawbtng !

Closes #2189.

why

ActCache.buildActCacheKey
(packages/core/lib/v3/cache/ActCache.ts:184) hashes the page URL verbatim from page.url() with no normalization. URLs that are semantically equivalent — same origin, path, and set of query parameters — produce different cache keys whenever the parameters appear in a different order. The cache silently misses, triggering an LLM call where one shouldn't be needed.

This is pervasive on real-world URLs: e-commerce links, ad funnels, anywhere utm_* / session params drift between visits.

| First run | Second run | Same page? | Cache hits today? | | --- | --- | --- | --- |
| ?id=42&utm_source=email | ?utm_source=email&id=42 | yes | no | | ?ref=home&page=2 | ?page=2&ref=home | yes | no |

what changed

• New normalizeUrlForCacheKey in cache/utils.ts: parses the URL, calls URLSearchParams.sort(), reserializes. Falls back to the raw input if the URL is unparseable ("", about:blank-like values).
• ActCache.prepareContext passes the normalized URL into buildActCacheKey while the stored entry.url still holds the raw URL (so on-disk cache files remain debuggable).
• New unit test packages/core/tests/unit/act-cache-url-normalize.test.ts covering: sort behavior, equivalent URLs producing identical output, fragment preservation, duplicate-key relative-order preservation, fallback paths.

design notes

The normalizer is intentionally conservative — only sorts parameters. Out of scope here, but candidates for follow-ups:

• Tracking-param stripping (utm_*, fbclid, gclid, etc.) — requires opinions on what counts as tracking; could break intentional differentiation, e.g. a customer that uses ?ref=X as a meaningful state.
• Fragment stripping — fragments often indicate distinct views in SPAs, so removing them could lose intent.
• Trailing-slash normalization — some servers treat them differently.

Each of those could land separately once the conservative pass is in.

compatibility

Strict superset of current cache hits — no URL that hits the cache today will miss after this change. URLs that miss today because of param reordering will now hit. The on-disk cache key for any URL containing query params changes; old entries become unreachable (don't break anything, just don't get used), and the next run rewrites them with the new key.

test plan

• pnpm run build:esm && pnpm exec vitest run --config vitest.esm.config.mjs dist/esm/tests/unit/act-cache-url-normalize.test.js — 9/9 pass.
• No public API changes; normalizeUrlForCacheKey is exported for testability but lives under cache/ and isn't re-exported from the SDK root.
• Changeset bundled (@browserbasehq/stagehand patch).

Found while reading ActCache.ts to understand the self-healing flow — happy to follow up with the tracking-param strip or fragment handling as a separate PR once this lands.

---

Summary by cubic

Normalize URLs in ActCache key derivation so query-parameter order no longer creates different cache keys, increasing hit rate and avoiding extra LLM calls. Closes #2189.

• Bug Fixes

• Added normalizeUrlForCacheKey in cache/utils.ts to sort query params via URLSearchParams.sort().

• prepareContext now hashes the normalized URL; stored entry.url stays raw for debugging.

• Preserves fragments and duplicate-key order; passes through empty/unparseable/about:blank URLs.

  • Added unit tests for sort behavior and equivalence cases.

• Migration

• Cache keys for URLs with query params change; existing on-disk entries won’t be used and will regenerate on next run.

^{Written for commit b98838e. Summary will update on new commits.}

why

what changed

test plan

[changeset-bot]

🦋 Changeset detected

Latest commit: cc07727

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

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v3	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]

No issues found across 4 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Page as Page
    participant ActCache as ActCache
    participant CacheStorage as CacheStorage
    participant Utils as cache/utils

    Note over Page,Utils: NEW: Cache key derivation with URL normalization

    Page->>ActCache: prepareContext(page, instruction, variableKeys)
    ActCache->>ActCache: sanitizeInstruction(instruction)
    ActCache->>Utils: safeGetPageUrl(page)
    Utils-->>ActCache: rawUrl (e.g. "https://example.com/?b=2&a=1")
    ActCache->>Utils: normalizeUrlForCacheKey(rawUrl)
    
    alt URL is parseable
        Utils->>Utils: new URL(rawUrl)
        Utils->>Utils: url.searchParams.sort()
        Utils-->>ActCache: normalizedUrl (e.g. "https://example.com/?a=1&b=2")
    else URL is empty/unparseable
        Utils-->>ActCache: rawUrl (unchanged)
    end

    ActCache->>ActCache: buildActCacheKey(sanitizedInstruction, normalizedUrl, variableKeys)
    ActCache->>CacheStorage: get(cacheKey)
    
    alt Cache hit
        CacheStorage-->>ActCache: cached entry (entry.url = rawUrl for debugging)
    else Cache miss
        CacheStorage-->>ActCache: null
        ActCache->>ActCache: Execute LLM call and store result
        ActCache->>CacheStorage: set(cacheKey, result, rawUrl)
    end
    
    ActCache-->>Page: return context with cached or fresh result

Loading

_{Re-trigger cubic}

[yawbtng]

of course! glad I could help!