Bug 2065545 - [firefox-devtools-mcp] Add a tool to disable the network cache

[shoemoney]

Adds a set_network_cache tool so an agent can send every request to the network instead of the cache:

{ "behavior": "bypass" }                    // selected tab
{ "behavior": "bypass", "scope": "global" } // browser-wide
{ "behavior": "default" }                   // restore

Per your note on the bug, this is a tool rather than a config, and it is scoped to the selected tab by default with scope: "global" as the opt-in. It joins the existing network module, so it arrives with the developer preset alongside the profiler tools it is meant to be used with.

One correction to the bug, with evidence

The bug says:

WebDriver BiDi supports the emulation.setNetworkConditions command, which allows to bypass the cache.

That command does exist in Firefox, but it has no cache parameter — it is offline emulation. Probed against Firefox 154 through this repo's own BiDi transport:

ERR   emulation.setNetworkConditions {contexts, cacheDisabled:true}  -> invalid argument
ERR   emulation.setNetworkConditions {contexts, offline:false}       -> invalid argument
ERR   emulation.setNetworkConditions {contexts, latency:0}           -> invalid argument
ERR   emulation.setNetworkConditions networkConditions:"offline"     -> invalid argument
OK    emulation.setNetworkConditions networkConditions:{type:"offline"}
OK    emulation.setNetworkConditions networkConditions:null

The only accepted values are {type: "offline"} and null.

I checked that invalid argument really meant "exists, wrong params" rather than "no such command", because reading it the other way would have sent me down the wrong path:

ERR   bogus.noSuchCommand                    -> unknown command
ERR   emulation.noSuchThing                  -> unknown command
ERR   emulation.setLocaleOverride {}         -> invalid argument   (real command, bad params)

The command that actually bypasses the cache is network.setCacheBehavior, with cacheBehavior: "bypass" | "default" and an optional contexts — omit it for global, pass one for per-tab. That is what this PR wraps.

Measured, not assumed

A local server serving asset.js with Cache-Control: public, max-age=86400, counting real server hits across 3 page loads:

state	3 loads → server hits
baseline (default)	1 — cached
setCacheBehavior('bypass'), tab-scoped	3 — every load hit the network
setCacheBehavior('default') restore	0 — served from cache again
setCacheBehavior('bypass', {global:true})	3

Both scopes work, and the effect is reversible.

Rejecting rather than defaulting

An unrecognised behavior or scope returns an error instead of falling back:

behavior must be one of default, bypass (got "disabled")
scope must be 'tab' or 'global' (got "everything")

Defaulting to default when someone asked for disabled would silently leave the cache on and quietly invalidate whatever they were measuring — the exact failure this tool exists to prevent. bypass also echoes back how to undo it, since the setting persists until reset:

cache bypass (selected tab) — set behavior='default' to restore caching

Tests

Six new unit tests in tests/tools/network.test.ts, all failing on unmodified main:

× exposes a behavior enum and an optional scope
× scopes to the selected tab by default
× applies browser-wide when scope is global
× tells the caller how to restore caching after a bypass
× rejects an unknown behavior instead of defaulting to cached
× rejects an unknown scope instead of silently using the tab

No integration test: the cache-bypass assertion needs a local HTTP server with a cacheable asset and a hit counter, which is a new pattern for tests/integration/ (every file there uses file:// fixtures, and file:// cannot exercise the HTTP cache). Happy to add one if you would like that pattern introduced — the measurements above came from exactly that harness, so it is written.

npm run lint            clean
npm run format:check    clean
npm run typecheck       clean
npm run typecheck:tests clean
npm run build           clean
npm run test:unit       43 files, 601 tests passed

Left alone deliberately

emulation.setNetworkConditions with {type: "offline"} is a genuinely useful thing to expose — offline-mode testing — but it is a different feature from this bug and would want its own tool and its own name. Happy to follow up if you want it.

[juliandescottes]

Thanks for the patch, works nicely. Just one small comment to address.

[juliandescottes]

Feels a bit odd in index.ts. Could we move this to another module, eg create a src/firefox/cache.ts ?