Bug 2062803 - Ship the __ffllm kit: agents develop, debug, hot-patch and verify a running Firefox — no rebuild

[Majdoddin]

Bug: https://bugzilla.mozilla.org/show_bug.cgi?id=2062803

Implements the kit proposed in the bug: eight privileged source files and one recipe document under kit/, served whole as kit:// resources and through a read_kit_file tool, plus an ensure_privileged_kit tool that installs them. The primitives — describe, tap, hook, hookScript, callChild, hookChild — are not MCP tools: the agent drives them through the existing evaluate_privileged_script channel. Motivation, design principle and the run evidence are in the bug; this description covers the mechanics the diff adds.

How the kit enters the browser: ensure_privileged_kit sends one BiDi script.callFunction whose functionDeclaration is kit/loader.js itself, with the other files' sources as its JSON argument. The loader evaluates them into a single invisibleToDebugger system-principal sandbox anchored on the shared system global, so the kit outlives the window that loaded it, and installs one global, __ffllm. A second install reuses the sandbox: each file is an IIFE, so re-evaluation replaces exports in place and leaves live hooks and capture buffers alone. The loader also retains the sources on the installed object, which is how content-process payloads (callChild, hookChild) are assembled in-process and stay byte-identical to the parent's — the sources cross the agent channel once, at install.

read_kit_file duplicates the kit:// resources deliberately. MCP resources are an optional client feature and do not reach every agent: in the harness our runs used, kit:// is unreachable from the background agents that do the actual work (anthropics/claude-code#85230, independently corroborated by #84125). The tool serves the same bytes everywhere, and a unit test pins the byte identity across the tool, the resource and the shipped file.

What the preset pays, measured (tokens estimated at chars/3.7): the standing delta in the mozilla preset is +594 tokens on a stock ~7.0k. The manuals are paid only when pulled: ~18.6k tokens for all nine files, a realistic working set ~8-10k.

Unit tests pin the serving: every file in kit/ is listed, exposed as a kit:// resource, and served byte-identically from the tool, the resource and the disk. Integration tests on the repo's existing headless-Firefox harness cover the install and its reuse — a hook armed between two ensure_privileged_kit calls keeps its buffer — a callChild round-trip (a value from every content process; a child throw rethrown parent-side with the child's message, not a timeout), and a hookChild capture streaming from the content processes to the parent drain. Full suite: 50 files, 665 tests, green.

Packaging and lint: the kit ships only in the -moz package — the public entry point hard-codes the privileged surface off, so neither the tools nor the kit:// resources exist there. kit/*.js is privileged chrome JavaScript outside the repo's eslint and prettier globs, the same treatment scripts/ gets; eslint, prettier, tsc and the tests typecheck all pass on the branch.

This work was done with AI assistance; I have reviewed and can explain every line.