Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

Merge origin/main (#628 Firefox target) into claude/issue-394-chromium-forks

Claudec3338de9d6ad
diff --cc .github/workflows/ci.yml
index 11ff2e50,64442c88..b8ae1a9b
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@@ -108,6 -98,16 +108,18 @@@ jobs
}
"
+ # Firefox has no Playwright extension loading, so its gate is the build
+ # itself plus Mozilla's own linter (the same addons-linter AMO runs at
+ # signing time) over the generated Gecko manifest and bundles. The unit
+ # tests above already cover the manifest generator and the API shim.
+ # Warnings fail the step: a warning today is usually an AMO rejection or
+ # an ignored manifest key on some Firefox version.
++ # Browser-independent, so it runs once, on the chromium leg.
+ - name: Build and lint the Firefox target
++ if: matrix.browser == 'chromium'
+ working-directory: browser-extension
+ run: npm run lint:firefox
+
# e2e/helpers/cert.ts shells out to openssl for the throwaway self-signed
# cert the replay server uses. Fail here with a clear message rather than
# inside a Playwright fixture.
diff --cc .github/workflows/release-extension.yml
index 1641ce0a,5856188b..0f156d58
--- a/.github/workflows/release-extension.yml
+++ b/.github/workflows/release-extension.yml
@@@ -2,13 -2,6 +2,13 @@@ name: Release Browser Extensio
# Publishes the unpacked Chrome MV3 build as a zip on a pushed `ext-v*` tag.
#
+# One zip serves every Chromium browser (Chrome, Edge, Brave, Opera, Vivaldi,
+# Arc). It keeps the `-chrome.zip` name on purpose: `chrome` is the name the
+# WebExtension tooling uses for the whole Chromium target family, it pairs with
- # any future per-engine targets, and renaming it would break every download
++# the `-firefox.xpi` target below, and renaming it would break every download
+# script and doc that already names the asset. The release notes state the
+# family claim instead (#394).
+#
# Independent of the CLI's `v*` release on purpose: the extension versions on its
# own cadence and shares no assets with the binary. GitHub tag patterns anchor at
# the start, so the `v*` filter in release.yml does not match `ext-v0.1.0` and the
diff --cc CLAUDE.md
index 5efe0cd5,0030a0e8..c31cd200
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@@ -55,7 -55,7 +55,7 @@@ Supported runtime surfaces today
- OpenClaw Gateway uses a Beacon-managed plugin directory plus OpenClaw's own diagnostics OTLP guidance (`beacon endpoint integrations openclaw`). The plugin's `before_tool_call` hook is fail-closed, so the handler dispatches synchronously and returns without awaiting. Conversation hooks, including `llm_output`, require `plugins.entries.beacon-endpoint.hooks.allowConversationAccess`; without it, token and agent-message coverage is partial. Beacon reads OpenClaw JSON/JSON5 config for advice but does not rewrite it.
- GitHub Copilot CLI uses MDM/customer-managed OTLP HTTP for live spans and approval-like activity, plus `beacon endpoint copilot sync` to backfill local session records from `~/.copilot/session-state`. Poll events carry assistant text, complete tool results, command/file details, and token usage with `harness.collection_method=poll`; approvals still come only from the live OTLP path and are not synthesized from persisted records.
- Runtimes that ride shared hook/OTLP paths without a special contract worth expanding here include Antigravity CLI, Devin CLI, Devin Desktop, Factory Droid, Gemini CLI, Grok Build, Hermes Agent, Qwen Code, and VS Code. Installed hook/endpoint support is governed by `cli/beacon/cmd/endpoint_targets.go` plus the install/status switches in `cli/beacon/cmd/endpoint_hooks.go`; discovery rows live in `cli/beacon/internal/endpoint/harness`.
- - Browser chat telemetry through an optional Chrome MV3 extension (`browser-extension/`) covering claude.ai and chatgpt.com. A main-world interceptor tees the streamed response, a per-site adapter parses it into a normalized turn, and the service worker POSTs OTLP GenAI logs to the local collector on `127.0.0.1:4318`; the extension never writes files and never contacts a remote endpoint. `harness.name` resolves to `claude_web` or `chatgpt_web` (already handled by `NormalizeHarnessName` in `pkg/asymptoteobserve/harness.go`, where the browser cases must stay above the generic `claude` rule) and `harness.collection_method` is `otlp`. The one build serves every Chromium browser; each event names the browser it came from in the typed `user_agent.name`/`user_agent.version` fields (OTel semconv, promoted by the exporter so Metadata-only forwarding keeps them), resolved in `browser-extension/src/shared/browser.ts` from UA Client Hints brands. Scope is deliberately narrow: only those origins' chat streams, never other tabs or general browsing. Retention defaults to `full`, so prompt and response text is retained by default; this is documented rather than defaulted down, because browser chat telemetry without content has no investigative value. Treat the adapters as experimental, since both sites' stream formats are private and undocumented.
-- Browser chat telemetry through an optional MV3 extension (`browser-extension/`; Chrome, with a beta Firefox build) covering claude.ai and chatgpt.com. A main-world interceptor tees the streamed response, a per-site adapter parses it into a normalized turn, and the service worker POSTs OTLP GenAI logs to the local collector on `127.0.0.1:4318`; the extension never writes files and never contacts a remote endpoint. `harness.name` resolves to `claude_web` or `chatgpt_web` (already handled by `NormalizeHarnessName` in `pkg/asymptoteobserve/harness.go`, where the browser cases must stay above the generic `claude` rule) and `harness.collection_method` is `otlp`. Scope is deliberately narrow: only those origins' chat streams, never other tabs or general browsing. Retention defaults to `full`, so prompt and response text is retained by default; this is documented rather than defaulted down, because browser chat telemetry without content has no investigative value. Treat the adapters as experimental, since both sites' stream formats are private and undocumented. Per-browser differences live only in `browser-extension/tools/targets.mjs` (one entry per target, deriving its manifest from `src/manifest.json`; Chrome ships that file verbatim to `dist/`, Firefox gets `dist-firefox/`), and every extension API call goes through the `src/shared/browser.ts` shim (a unit test fails on direct `chrome.*` use). The Firefox Gecko ID `[email protected]` is pinned and must never change.
++- Browser chat telemetry through an optional MV3 extension (`browser-extension/`; Chrome, with a beta Firefox build) covering claude.ai and chatgpt.com. A main-world interceptor tees the streamed response, a per-site adapter parses it into a normalized turn, and the service worker POSTs OTLP GenAI logs to the local collector on `127.0.0.1:4318`; the extension never writes files and never contacts a remote endpoint. `harness.name` resolves to `claude_web` or `chatgpt_web` (already handled by `NormalizeHarnessName` in `pkg/asymptoteobserve/harness.go`, where the browser cases must stay above the generic `claude` rule) and `harness.collection_method` is `otlp`. The one build serves every Chromium browser; each event names the browser it came from in the typed `user_agent.name`/`user_agent.version` fields (OTel semconv, promoted by the exporter so Metadata-only forwarding keeps them), resolved in `browser-extension/src/shared/browser-identity.ts` from UA Client Hints brands, with a UA-string fallback that also names Firefox. Scope is deliberately narrow: only those origins' chat streams, never other tabs or general browsing. Retention defaults to `full`, so prompt and response text is retained by default; this is documented rather than defaulted down, because browser chat telemetry without content has no investigative value. Treat the adapters as experimental, since both sites' stream formats are private and undocumented. Per-browser differences live only in `browser-extension/tools/targets.mjs` (one entry per target, deriving its manifest from `src/manifest.json`; Chrome ships that file verbatim to `dist/`, Firefox gets `dist-firefox/`), and every extension API call goes through the `src/shared/browser.ts` shim (a unit test fails on direct `chrome.*` use). The Firefox Gecko ID `[email protected]` is pinned and must never change.
- `beaconjson` OpenTelemetry Collector exporter that converts OTLP logs, traces, metrics, and resource attributes into Beacon endpoint JSONL.
- Endpoint inventory (`inventory.heartbeat` / `inventory.snapshot` in `inventory_state.jsonl`) is written by a scheduled job, `com.beacon.endpoint.inventory` (`service.InventoryManager`, user LaunchAgent or system LaunchDaemon, `beacon-inventory.timer` on systemd), every six hours and once at load, on by default and reconciled by `lifecycle.ReconcileInventoryJob` on every install, repair and package upgrade (`beacon endpoint inventory install-daemon`). Agent hooks do not trigger inventory any more; the hook binary's `--cli` flag and `inventory-heartbeat` subcommand survive only as no-ops for hook commands written by older versions, and `beacon endpoint inventory heartbeat --trigger hook` is likewise retired. A system-mode run inventories the active console user's home and still writes the liveness heartbeat when nobody is logged in; the scheduled scan has no working directory, so project-scoped config is only in `beacon endpoint inventory`.
- Beacon Managed forwarding, the one Beacon-hosted network channel for endpoint telemetry: user-mode `beacon endpoint connect` authorizes device enrollment with the signed-in CLI account; system mode uses browser PKCE at `/cli/enroll`. Both store only the per-device key in `<BaseDir>/asymptote/vector-secrets.json` (0600, 0700 dir), render the selected privacy mode into `vector.toml`, validate it, and run Vector as `com.beacon.endpoint.asymptote-forwarder` / `beacon-asymptote-forwarder.service` through `service.ForwarderManager` (refused in supervised mode). `enrollment.json` and `config.json`'s `managed_ingest` block carry only non-secret identity and privacy mode; `beacon endpoint status` reports forwarder state and a live credential check (`GET /v1/ingest/health`, 3 s timeout); `disconnect` and `uninstall` remove the forwarder and credentials but never revoke server-side.
@@@ -508,7 -513,7 +515,7 @@@ unpacked through Chrome's developer mod
- `go-test` (macOS): `bun run check && bun test` in all seven `plugins/*` directories, then `make build-hooks-current`, then `go test ./...` in `cli/beacon`, `go test -race ./internal/endpoint/...`, `go test ./...` in `cli/beacon-hooks`, `collector-builder/exporter/beaconjsonexporter`, and `pkg/asymptoteobserve` (includes threat-rules pack conformance), then CLI help smoke checks that also assert removed commands stay unexposed.
- `linux-test` (ubuntu) and `windows-test` (windows-2025) rerun the Go suites per platform. The Windows job tests a measured package list rather than `./...`; the excluded packages are tracked in #318, and the scope must not be widened back to `./...`.
- `typescript-sdk` (Node 20, 22, 24): `npm test`, `npm run check`, `npm run build`, `npm run pack:dry-run`, `npm run pack:smoke` in `packages/asymptote-sdk-js`.
- - `browser-extension` (Node 22, matrix over `chromium` and `msedge`): `npm run check`, `npm run test:unit`, `npm run build`, a check that the build is a loadable MV3 extension, and the Playwright replay e2e running the real extension headless in that browser (`BROWSER_CHANNEL`) against a local HTTPS replay server; the HTML report and traces upload on failure. Brave, Opera, Vivaldi and Arc have no Playwright channel; `BROWSER_EXECUTABLE` runs the same e2e against their binaries for the manual checklist in `docs/runtimes/browser-extension-chromium.mdx`.
-- `browser-extension` (Node 22): `npm run check`, `npm run test:unit`, `npm run build`, a check that the build is a loadable MV3 extension, `npm run lint:firefox` (the Firefox build plus `web-ext lint --warnings-as-errors`), and the Playwright replay e2e running the real extension in headless Chromium against a local HTTPS replay server; the HTML report and traces upload on failure.
++- `browser-extension` (Node 22, matrix over `chromium` and `msedge`): `npm run check`, `npm run test:unit`, `npm run build`, a check that the build is a loadable MV3 extension, `npm run lint:firefox` (the Firefox build plus `web-ext lint --warnings-as-errors`), and the Playwright replay e2e running the real extension headless in that leg's browser (`BROWSER_CHANNEL`) against a local HTTPS replay server; the HTML report and traces upload on failure. Brave, Opera, Vivaldi and Arc have no Playwright channel; `BROWSER_EXECUTABLE` runs the same e2e against their binaries for the manual checklist in `docs/runtimes/browser-extension-chromium.mdx`.
- `beacon-sandbox` (ubuntu): `go build`, `go vet`, and `go test` for the verification harness. Hermetic — no Modal account, no API key, no paid resources.
- `cross-build` (ubuntu): builds all five release targets and asserts the Linux binaries are statically linked (no `PT_INTERP`).
- `package-smoke` (macOS): `packaging/macos/test-endpoint-scripts.sh`, a `build-pkg.sh` payload check, and `packaging/macos/smoke-endpoint.sh`.
diff --cc browser-extension/README.md
index 71cc1897,9a692ff7..10f98ed5
--- a/browser-extension/README.md
+++ b/browser-extension/README.md
@@@ -91,13 -91,6 +93,13 @@@ npm run report # open the last H
## Loading the extension in your own browser
+One build serves every Chromium browser: Chrome, Edge, Brave, Opera, Vivaldi and Arc. The
+release archive is named `-chrome.zip` after the Chromium extension family, not after Google
+Chrome alone. CI runs the replay e2e in Chromium and Edge; the other forks are covered by the
+manual checklist in [docs/runtimes/browser-extension-chromium.mdx](../docs/runtimes/browser-extension-chromium.mdx).
+Every emitted event names the browser that produced it (`user_agent.name`, `user_agent.version`,
- `browser.brands`; see `src/shared/browser.ts`).
++`browser.brands`; see `src/shared/browser-identity.ts`).
+
**Beta, and not on the Chrome Web Store.** It installs unpacked, so Chrome will not
auto-update it: to move to a new version, rebuild or re-download and reload.
diff --cc browser-extension/src/background/delivery.ts
index ff31207b,7d33cd64..7eb95595
--- a/browser-extension/src/background/delivery.ts
+++ b/browser-extension/src/background/delivery.ts
@@@ -6,7 -7,6 +7,7 @@@ import { ext } from '../shared/browser.
import type { ChatTurn, Settings } from '../shared/types.js';
import { turnToEnvelope } from '../shared/normalize.js';
import type { LogsEnvelope } from '../shared/otlp.js';
- import type { BrowserIdentity } from '../shared/browser.js';
++import type { BrowserIdentity } from '../shared/browser-identity.js';
const QUEUE_KEY = 'delivery_queue';
const ALARM = 'beacon_flush';
@@@ -43,12 -43,8 +44,12 @@@ function withQueueLock<T>(fn: () => Pro
}
/** Normalize a turn and enqueue it for delivery, then kick a flush. */
-export async function enqueueTurn(turn: ChatTurn, settings: Settings): Promise<void> {
- const envelope = turnToEnvelope(turn, settings.retention);
+export async function enqueueTurn(
+ turn: ChatTurn,
+ settings: Settings,
- browser?: BrowserIdentity,
++ identity?: BrowserIdentity,
+): Promise<void> {
- const envelope = turnToEnvelope(turn, settings.retention, browser);
++ const envelope = turnToEnvelope(turn, settings.retention, identity);
const item: QueueItem = {
id: turn.turnId,
endpoint: settings.endpoint,
diff --cc browser-extension/src/background/sw.ts
index e005efad,badfd0ca..83692ded
--- a/browser-extension/src/background/sw.ts
+++ b/browser-extension/src/background/sw.ts
@@@ -7,15 -8,9 +8,15 @@@ import type { ChatTurn, RelayMessage, S
import { getSettings, saveSettings, siteEnabled } from './settings.js';
import { Assembler } from './assembler.js';
import { enqueueTurn, flush, installFlushAlarm } from './delivery.js';
- import { detectBrowser } from '../shared/browser.js';
++import { detectBrowser } from '../shared/browser-identity.js';
const assembler = new Assembler();
+// Which Chromium fork (or other browser) this is. Resolved once: the brand
+// list and UA string are fixed for the life of the worker. Stamped on every
+// emitted turn as user_agent.* / browser.brands.
- const browser = detectBrowser(globalThis.navigator);
++const browserIdentity = detectBrowser(globalThis.navigator);
+
// Keep the SW awake while any stream is active, so mid-stream suspension is
// rare. Correctness never depends on this — durable state covers the rest.
let keepAliveTimer: ReturnType<typeof setInterval> | undefined;
@@@ -57,7 -52,7 +58,7 @@@ async function finalizeTurn(turn: ChatT
const settings = await getSettings();
// siteEnabled covers both the global toggle and the per-site toggle.
if (!siteEnabled(settings, turn.site)) return;
- await enqueueTurn(turn, settings, browser);
- await enqueueTurn(turn, settings);
++ await enqueueTurn(turn, settings, browserIdentity);
}
// ---- Control messages from popup/options ----
diff --cc browser-extension/src/shared/browser-identity.ts
index 00000000,00000000..29550c74
new file mode 100644
--- /dev/null
+++ b/browser-extension/src/shared/browser-identity.ts
@@@ -1,0 -1,0 +1,118 @@@
++// PURE: which browser is this extension running in?
++//
++// Every Chromium fork runs the same MV3 build, so a captured turn says nothing
++// about the browser it came from unless we record it. On a managed fleet that
++// matters: a paste into ChatGPT from the managed Edge profile and one from a
++// personal Brave install are different investigations.
++//
++// Resolution order, from most to least reliable:
++// 1. navigator.userAgentData.brands (UA Client Hints). Edge, Opera and Brave
++// add their own brand here, which the UA string no longer carries reliably.
++// 2. A Brave-only `navigator.brave` object, for Brave builds whose brand list
++// reads like plain Chrome.
++// 3. The UA string's vendor tokens (Edg/, OPR/, Vivaldi/, Firefox/), for
++// engines without UA Client Hints.
++//
++// What this cannot do: Arc and Vivaldi do not add a brand of their own, and
++// copy Chrome's UA string, so from a service worker they are indistinguishable
++// from Google Chrome or plain Chromium. We report what the browser claims and
++// document that limit rather than guessing.
++//
++// No I/O, no chrome.*: sw.ts hands in `navigator`, tests hand in fixtures.
++
++/** One entry of NavigatorUAData.brands. */
++export interface UABrand {
++ brand: string;
++ version: string;
++}
++
++/** The subset of (Worker)Navigator this reads. Every field is optional. */
++export interface NavigatorLike {
++ userAgent?: string;
++ userAgentData?: { brands?: readonly UABrand[] } | null;
++ brave?: unknown;
++}
++
++export interface BrowserIdentity {
++ /** Browser name as the browser itself claims it, e.g. "Microsoft Edge". OTel `user_agent.name`. */
++ name: string;
++ /** Major version of that browser, when known. OTel `user_agent.version`. */
++ version?: string;
++ /** UA Client Hints brands as "<brand> <version>", in reported order. OTel `browser.brands`. */
++ brands: string[];
++ /** The raw UA string, when available. OTel `user_agent.original`. */
++ original?: string;
++}
++
++const CHROME = 'Google Chrome';
++const CHROMIUM = 'Chromium';
++
++// Chromium adds a deliberately malformed "GREASE" brand ("Not_A Brand",
++// "Not)A;Brand", " Not A;Brand", ...) with randomized punctuation so sites
++// cannot match the brand list exactly. It never names a browser.
++const GREASE = /^\s*not.?a.?brand\s*$/i;
++
++/** Resolve the browser identity, or undefined when nothing identifies it. */
++export function detectBrowser(nav: NavigatorLike | undefined): BrowserIdentity | undefined {
++ if (!nav) return undefined;
++ const rawBrands = Array.isArray(nav.userAgentData?.brands) ? nav.userAgentData!.brands! : [];
++ const valid = rawBrands.filter(
++ (b): b is UABrand => typeof b?.brand === 'string' && b.brand.trim() !== '',
++ );
++ const brands = valid.map((b) => `${b.brand} ${b.version ?? ''}`.trim());
++ const original = typeof nav.userAgent === 'string' && nav.userAgent !== '' ? nav.userAgent : undefined;
++ const isBrave = nav.brave != null && typeof nav.brave === 'object';
++
++ let found = fromBrands(valid) ?? (original ? fromUserAgent(original) : undefined);
++ if (!found) return undefined;
++ // Brave's own object is a stronger signal than a brand list that reads like Chrome.
++ if (isBrave && (found.name === CHROME || found.name === CHROMIUM)) found = { name: 'Brave', version: found.version };
++
++ const identity: BrowserIdentity = { name: found.name, brands };
++ if (found.version) identity.version = found.version;
++ if (original) identity.original = original;
++ return identity;
++}
++
++interface Found {
++ name: string;
++ version?: string;
++}
++
++function fromBrands(brands: readonly UABrand[]): Found | undefined {
++ const named = brands.filter((b) => !GREASE.test(b.brand));
++ if (named.length === 0) return undefined;
++ // Any brand other than the engine and Chrome is the vendor naming itself
++ // (Microsoft Edge, Opera, Brave, ...). Chromium shuffles brand order, so when
++ // there is more than one, pick deterministically: the most specific (longest)
++ // name, so "Opera GX" beats "Opera", then alphabetical.
++ const vendor = named
++ .filter((b) => b.brand !== CHROME && b.brand !== CHROMIUM)
++ .sort((a, b) => b.brand.length - a.brand.length || a.brand.localeCompare(b.brand))[0];
++ const pick =
++ vendor ?? named.find((b) => b.brand === CHROME) ?? named.find((b) => b.brand === CHROMIUM);
++ if (!pick) return undefined;
++ return { name: pick.brand.trim(), version: pick.version || undefined };
++}
++
++// Vendor tokens first: every Chromium fork also carries "Chrome/", and Chrome
++// and Edge also carry "Safari/".
++const UA_RULES: Array<[RegExp, string]> = [
++ [/\bEdg(?:e|A|iOS)?\/(\d+)/, 'Microsoft Edge'],
++ [/\bOPR\/(\d+)/, 'Opera'],
++ [/\bVivaldi\/(\d+)/, 'Vivaldi'],
++ [/\bBrave\/(\d+)/, 'Brave'],
++ [/\bFirefox\/(\d+)/, 'Firefox'],
++ // The UA string alone cannot tell Chrome from the forks that copy it, so
++ // claim only the engine.
++ [/\b(?:Headless)?Chrome\/(\d+)/, CHROMIUM],
++ [/\bVersion\/(\d+)[^ ]* (?:Mobile\/\S+ )?Safari\//, 'Safari'],
++];
++
++function fromUserAgent(ua: string): Found | undefined {
++ for (const [re, name] of UA_RULES) {
++ const m = re.exec(ua);
++ if (m) return { name, version: m[1] };
++ }
++ return undefined;
++}
diff --cc browser-extension/src/shared/normalize.ts
index c6eee15b,225b7032..dca9ce15
--- a/browser-extension/src/shared/normalize.ts
+++ b/browser-extension/src/shared/normalize.ts
@@@ -14,9 -14,7 +14,9 @@@ import
int,
msToUnixNano,
str,
+ strArray,
} from './otlp.js';
- import type { BrowserIdentity } from './browser.js';
++import type { BrowserIdentity } from './browser-identity.js';
import {
type EventAction,
MAX_FIELD_BYTES,
@@@ -75,22 -73,13 +75,22 @@@ function shapeText(text: string, retent
* Normalize a chat turn into 1..N OTLP log records:
* - one response record (agent.response.completed, or agent.response if partial)
* - one tool.invoked record per captured tool call
+ *
- * `browser` is the identity sw.ts resolved at startup (see browser.ts). It is
++ * `identity` is the browser identity sw.ts resolved at startup (see browser-identity.ts). It is
+ * a resource attribute, so every record of the turn carries it, and it is
+ * metadata rather than content, so it survives every retention mode.
*/
-export function normalizeTurn(turn: ChatTurn, retention: Retention): NormalizedTurn {
+export function normalizeTurn(
+ turn: ChatTurn,
+ retention: Retention,
- browser?: BrowserIdentity,
++ identity?: BrowserIdentity,
+): NormalizedTurn {
const resourceAttributes: KeyValue[] = [
str('beacon.origin', ORIGIN),
str('beacon.harness.name', turn.site),
str('service.name', SERVICE_NAME),
str('gen_ai.provider.name', providerFor(turn.site)),
- ...browserAttributes(browser),
++ ...browserAttributes(identity),
];
const tid = turn.turnId || turnId(turn.sessionId, 0);
@@@ -220,23 -209,12 +220,23 @@@ function toolRecord
};
}
+/** OTel semconv browser/user-agent attributes. The collector promotes
+ * user_agent.name/version into the event's typed `user_agent` field. */
- function browserAttributes(browser: BrowserIdentity | undefined): KeyValue[] {
- if (!browser) return [];
- const attrs: KeyValue[] = [str('user_agent.name', browser.name)];
- if (browser.version) attrs.push(str('user_agent.version', browser.version));
- if (browser.original) attrs.push(str('user_agent.original', browser.original));
- if (browser.brands.length > 0) attrs.push(strArray('browser.brands', browser.brands));
++function browserAttributes(identity: BrowserIdentity | undefined): KeyValue[] {
++ if (!identity) return [];
++ const attrs: KeyValue[] = [str('user_agent.name', identity.name)];
++ if (identity.version) attrs.push(str('user_agent.version', identity.version));
++ if (identity.original) attrs.push(str('user_agent.original', identity.original));
++ if (identity.brands.length > 0) attrs.push(strArray('browser.brands', identity.brands));
+ return attrs;
+}
+
function stringify(v: unknown): string {
return typeof v === 'string' ? v : JSON.stringify(v ?? null);
}
/** Convenience: normalize straight into a single OTLP logs envelope. */
- export function turnToEnvelope(turn: ChatTurn, retention: Retention, browser?: BrowserIdentity) {
- const { resourceAttributes, logRecords } = normalizeTurn(turn, retention, browser);
-export function turnToEnvelope(turn: ChatTurn, retention: Retention) {
- const { resourceAttributes, logRecords } = normalizeTurn(turn, retention);
++export function turnToEnvelope(turn: ChatTurn, retention: Retention, identity?: BrowserIdentity) {
++ const { resourceAttributes, logRecords } = normalizeTurn(turn, retention, identity);
return buildLogsEnvelope(resourceAttributes, logRecords, SERVICE_NAME);
}
diff --cc browser-extension/test/unit/browser-identity.test.ts
index 8f5de763,00000000..ec352d20
mode 100644,000000..100644
--- a/browser-extension/test/unit/browser-identity.test.ts
+++ b/browser-extension/test/unit/browser-identity.test.ts
@@@ -1,180 -1,0 +1,180 @@@
+import { describe, it, expect } from 'vitest';
- import { detectBrowser, type NavigatorLike, type UABrand } from '../../src/shared/browser.js';
++import { detectBrowser, type NavigatorLike, type UABrand } from '../../src/shared/browser-identity.js';
+
+// Brand lists as each browser reports them in navigator.userAgentData.brands.
+// Edge and Chromium were read from a live MV3 service worker (Edge 153, Chromium
+// 141); the others follow each vendor's documented UA Client Hints behavior.
+const b = (brand: string, version: string): UABrand => ({ brand, version });
+
+const CHROME_UA =
+ 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36';
+
+function nav(brands: UABrand[] | undefined, userAgent = CHROME_UA, extra: Partial<NavigatorLike> = {}) {
+ return { userAgent, userAgentData: brands ? { brands } : undefined, ...extra };
+}
+
+describe('detectBrowser — UA Client Hints brands', () => {
+ it('Microsoft Edge (live Edge 153 service worker)', () => {
+ const id = detectBrowser(
+ nav(
+ [b('Microsoft Edge', '153'), b('Not_A Brand', '8'), b('Chromium', '153')],
+ 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/153.0.0.0 Safari/537.36 Edg/153.0.0.0',
+ ),
+ );
+ expect(id).toEqual({
+ name: 'Microsoft Edge',
+ version: '153',
+ brands: ['Microsoft Edge 153', 'Not_A Brand 8', 'Chromium 153'],
+ original:
+ 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/153.0.0.0 Safari/537.36 Edg/153.0.0.0',
+ });
+ });
+
+ it('plain Chromium (live Chromium 141 service worker)', () => {
+ const id = detectBrowser(nav([b('Chromium', '141'), b('Not?A_Brand', '8')]));
+ expect(id?.name).toBe('Chromium');
+ expect(id?.version).toBe('141');
+ });
+
+ it('Google Chrome', () => {
+ const id = detectBrowser(nav([b('Google Chrome', '124'), b('Chromium', '124'), b('Not-A.Brand', '99')]));
+ expect(id?.name).toBe('Google Chrome');
+ expect(id?.version).toBe('124');
+ });
+
+ it('Brave, which adds its own brand', () => {
+ const id = detectBrowser(nav([b('Brave', '124'), b('Chromium', '124'), b('Not-A.Brand', '99')]));
+ expect(id?.name).toBe('Brave');
+ });
+
+ it("Opera, reporting Opera's own version rather than Chromium's", () => {
+ const id = detectBrowser(
+ nav(
+ [b('Chromium', '124'), b('Opera', '110'), b('Not-A.Brand', '99')],
+ CHROME_UA + ' OPR/110.0.0.0',
+ ),
+ );
+ expect(id?.name).toBe('Opera');
+ expect(id?.version).toBe('110');
+ });
+
+ it('Opera GX: the more specific vendor brand wins', () => {
+ const id = detectBrowser(nav([b('Opera', '110'), b('Chromium', '124'), b('Opera GX', '110')]));
+ expect(id?.name).toBe('Opera GX');
+ });
+
+ it('an unknown fork that brands itself is reported verbatim', () => {
+ const id = detectBrowser(nav([b('Chromium', '124'), b('YaBrowser', '24'), b('Not-A.Brand', '99')]));
+ expect(id?.name).toBe('YaBrowser');
+ expect(id?.version).toBe('24');
+ });
+
+ it('Vivaldi adds no brand, so it reports as Chromium (documented limit)', () => {
+ const id = detectBrowser(nav([b('Chromium', '124'), b('Not-A.Brand', '99')]));
+ expect(id?.name).toBe('Chromium');
+ });
+
+ it('Arc copies Chrome\'s brand list, so it reports as Google Chrome (documented limit)', () => {
+ const id = detectBrowser(nav([b('Chromium', '124'), b('Google Chrome', '124'), b('Not-A.Brand', '99')]));
+ expect(id?.name).toBe('Google Chrome');
+ });
+
+ it('is independent of brand order (Chromium shuffles it)', () => {
+ const brands = [b('Microsoft Edge', '153'), b('Not_A Brand', '8'), b('Chromium', '153')];
+ const names = new Set<string | undefined>();
+ for (const order of [[0, 1, 2], [2, 1, 0], [1, 2, 0], [2, 0, 1]]) {
+ names.add(detectBrowser(nav(order.map((i) => brands[i])))?.name);
+ }
+ expect([...names]).toEqual(['Microsoft Edge']);
+ });
+
+ it.each(['Not_A Brand', 'Not)A;Brand', ' Not A;Brand', 'Not-A.Brand', 'Not?A_Brand', 'Not/A)Brand', 'Not A(Brand'])(
+ 'never picks the GREASE brand %j',
+ (grease) => {
+ expect(detectBrowser(nav([b(grease, '99'), b('Chromium', '124')]))?.name).toBe('Chromium');
+ },
+ );
+
+ it('keeps GREASE in browser.brands, exactly as reported (semconv takes brands verbatim)', () => {
+ const id = detectBrowser(nav([b('Not)A;Brand', '99'), b('Chromium', '124')]));
+ expect(id?.brands).toEqual(['Not)A;Brand 99', 'Chromium 124']);
+ });
+});
+
+describe('detectBrowser — Brave without a Brave brand', () => {
+ it('navigator.brave overrides a Chrome-looking brand list', () => {
+ const id = detectBrowser(
+ nav([b('Google Chrome', '124'), b('Chromium', '124')], CHROME_UA, { brave: { isBrave: () => true } }),
+ );
+ expect(id?.name).toBe('Brave');
+ expect(id?.version).toBe('124');
+ });
+
+ it('navigator.brave does not override another vendor brand', () => {
+ const id = detectBrowser(nav([b('Microsoft Edge', '153'), b('Chromium', '153')], CHROME_UA, { brave: {} }));
+ expect(id?.name).toBe('Microsoft Edge');
+ });
+
+ it('a non-object navigator.brave is ignored', () => {
+ const id = detectBrowser(nav([b('Google Chrome', '124')], CHROME_UA, { brave: true }));
+ expect(id?.name).toBe('Google Chrome');
+ });
+});
+
+describe('detectBrowser — UA string fallback (no UA Client Hints)', () => {
+ it.each([
+ ['Edge', CHROME_UA + ' Edg/120.0.0.0', 'Microsoft Edge', '120'],
+ ['Opera', CHROME_UA + ' OPR/106.0.0.0', 'Opera', '106'],
+ ['Vivaldi (older builds that still say so)', CHROME_UA + ' Vivaldi/6.5.3206.48', 'Vivaldi', '6'],
+ ['Chrome-shaped UA: only the engine can be claimed', CHROME_UA, 'Chromium', '124'],
+ [
+ 'Firefox',
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 14.4; rv:125.0) Gecko/20100101 Firefox/125.0',
+ 'Firefox',
+ '125',
+ ],
+ [
+ 'Safari',
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15',
+ 'Safari',
+ '17',
+ ],
+ ])('%s', (_label, ua, name, version) => {
+ const id = detectBrowser(nav(undefined, ua));
+ expect(id?.name).toBe(name);
+ expect(id?.version).toBe(version);
+ expect(id?.brands).toEqual([]);
+ expect(id?.original).toBe(ua);
+ });
+
+ it('falls back to the UA string when the brand list is empty', () => {
+ expect(detectBrowser(nav([], CHROME_UA + ' Edg/120.0.0.0'))?.name).toBe('Microsoft Edge');
+ });
+
+ it('falls back to the UA string when the brand list is only GREASE', () => {
+ const id = detectBrowser(nav([b('Not_A Brand', '8')], CHROME_UA + ' OPR/106.0.0.0'));
+ expect(id?.name).toBe('Opera');
+ expect(id?.brands).toEqual(['Not_A Brand 8']);
+ });
+});
+
+describe('detectBrowser — nothing to go on', () => {
+ it('returns undefined without a navigator', () => {
+ expect(detectBrowser(undefined)).toBeUndefined();
+ });
+
+ it('returns undefined for an empty navigator', () => {
+ expect(detectBrowser({})).toBeUndefined();
+ });
+
+ it('returns undefined for an unrecognizable UA and no brands', () => {
+ expect(detectBrowser({ userAgent: 'curl/8.4.0', userAgentData: null })).toBeUndefined();
+ });
+
+ it('tolerates malformed brand entries', () => {
+ const brands = [null, { brand: 42 }, { brand: '' }, b('Chromium', '124')] as unknown as UABrand[];
+ const id = detectBrowser(nav(brands));
+ expect(id?.name).toBe('Chromium');
+ expect(id?.brands).toEqual(['Chromium 124']);
+ });
+});
diff --cc browser-extension/test/unit/normalize.test.ts
index 0f7de4f8,b729b7fe..ed4aea5f
--- a/browser-extension/test/unit/normalize.test.ts
+++ b/browser-extension/test/unit/normalize.test.ts
@@@ -1,12 -1,6 +1,12 @@@
import { describe, it, expect } from 'vitest';
-import { normalizeTurn } from '../../src/shared/normalize.js';
-import { attrValue, type KeyValue, type LogRecord } from '../../src/shared/otlp.js';
+import { normalizeTurn, turnToEnvelope } from '../../src/shared/normalize.js';
+import {
+ attrValue,
+ type AttrPrimitive,
+ type KeyValue,
+ type LogRecord,
+} from '../../src/shared/otlp.js';
- import type { BrowserIdentity } from '../../src/shared/browser.js';
++import type { BrowserIdentity } from '../../src/shared/browser-identity.js';
import type { ChatTurn, Retention } from '../../src/shared/types.js';
function baseTurn(over: Partial<ChatTurn> = {}): ChatTurn {
diff --cc docs/runtimes/browser-extension-chromium.mdx
index 45e8f902,00000000..34a37ddd
mode 100644,000000..100644
--- a/docs/runtimes/browser-extension-chromium.mdx
+++ b/docs/runtimes/browser-extension-chromium.mdx
@@@ -1,160 -1,0 +1,162 @@@
+---
+title: "Chromium Browsers"
+description: "Which Chromium browsers the Beacon browser extension is tested in, how events name the browser, and how to verify and deploy it in Edge, Brave, Opera, Vivaldi, and Arc"
+---
+
+## Overview
+
+Microsoft Edge, Brave, Opera, Vivaldi, and Arc are all built on Chromium and all run Manifest V3 extensions. The [browser extension](/runtimes/browser-extension) ships one build, and that same build loads in each of them. There is no per-browser port and no second artifact.
+
+A browser being Chromium-based does not mean Beacon has tested it there. This page keeps the two claims apart: which browsers run in automated tests on every change, and which rely on the manual checklist below.
+
+## Support levels
+
+| Browser | Status | How it is verified |
+|---------|--------|--------------------|
+| Chromium | Tested | Automated replay e2e in CI on every pull request (`BROWSER_CHANNEL=chromium`) |
+| Microsoft Edge | Tested | Automated replay e2e in CI on every pull request (`BROWSER_CHANNEL=msedge`) |
+| Google Chrome | Expected to work, not in CI | Branded Chrome (137 and later) no longer honors `--load-extension`, which the harness uses to load `dist/`, so it cannot run in the automated e2e. Use the [manual checklist](#manual-verification-checklist) |
+| Brave | Expected to work, not in CI | [Manual checklist](#manual-verification-checklist). There is no Playwright channel for Brave |
+| Opera, Opera GX | Expected to work, not in CI | [Manual checklist](#manual-verification-checklist). There is no Playwright channel for Opera |
+| Vivaldi | Expected to work, not in CI | [Manual checklist](#manual-verification-checklist). There is no Playwright channel for Vivaldi |
+| Arc | Expected to work, not in CI | [Manual checklist](#manual-verification-checklist). There is no Playwright channel for Arc, and Arc does not run on Linux CI runners |
- | Firefox, Safari | Not supported | Different extension platforms. Tracked separately |
++| Firefox | Beta, separate build | Not Chromium: a separate `dist-firefox` build, linted in CI and checked by hand. See [Load it in Firefox](/runtimes/browser-extension#load-it-in-firefox) |
++| Safari | Not supported | Different extension platform. Tracked separately |
+
+The extension needs a browser built on Chromium 111 or newer, because its interceptor is declared as a main-world content script in the manifest.
+
+## Which browser an event came from
+
+Every event the extension sends names the browser that produced it. On a managed fleet that matters: a paste into ChatGPT from the managed Edge profile and one from a personal Brave install are different investigations.
+
+The extension's service worker reads the browser's own UA Client Hints brand list (`navigator.userAgentData.brands`), falling back to the user-agent string, and sends OpenTelemetry semantic-convention attributes on every OTLP log:
+
+| OTLP attribute | Example | Where it lands in the event |
+|----------------|---------|-----------------------------|
+| `user_agent.name` | `Microsoft Edge` | `user_agent.name` |
+| `user_agent.version` | `153` (major version) | `user_agent.version` |
+| `browser.brands` | `["Microsoft Edge 153", "Not_A Brand 8", "Chromium 153"]` | `raw.attributes` |
+| `user_agent.original` | the browser's UA string | `raw.attributes` |
+
+`user_agent.name` and `user_agent.version` are typed event fields. They are metadata rather than content, so they survive every retention mode, including `metadata` retention in the extension and Metadata-only managed forwarding, which drops `raw`. Threat rules can match on `e.user_agent.name`.
+
+To see the browser on recent events:
+
+```bash
+grep '"claude_web"\|"chatgpt_web"' ~/.beacon/endpoint/logs/runtime.jsonl | tail -5 | jq '{harness: .harness.name, browser: .user_agent.name, version: .user_agent.version}'
+```
+
+`user_agent.name` is what the browser claims to be. Some browsers do not name themselves:
+
+| Browser | Reports as | Why |
+|---------|------------|-----|
+| Microsoft Edge | `Microsoft Edge` | Edge adds its own brand |
+| Brave | `Brave` | Brave adds its own brand. Builds that do not are still recognized by Brave's `navigator.brave` object |
+| Opera, Opera GX | `Opera`, `Opera GX` | Opera adds its own brand. `user_agent.version` is Opera's version, not Chromium's |
+| Google Chrome | `Google Chrome` | |
+| Chromium, and Playwright's test build | `Chromium` | No vendor brand |
+| Vivaldi | Usually `Chromium` | Vivaldi adds no brand of its own and copies Chrome's UA string for site compatibility. Older builds that still put `Vivaldi/` in the UA string without brand hints report `Vivaldi` |
+| Arc | Usually `Google Chrome` | Arc copies Chrome's brand list and UA string. An extension's service worker has no other signal, so Arc cannot be told apart from Chrome |
++| Firefox | `Firefox` | Firefox has no UA Client Hints, so the name and major version come from the `Firefox/` token in its UA string, and `browser.brands` is omitted |
+
+When a browser adds a brand Beacon does not know, that brand is reported as-is. When a browser gives neither brand hints nor a recognizable UA string, the attributes are omitted rather than guessed.
+
+## Install
+
- Every Chromium browser uses the same archive, `agent-beacon-browser-extension-<version>-chrome.zip`, or a local `dist/` build. The `-chrome` suffix names the Chromium extension family, not Google Chrome alone. See [Use a release archive](/runtimes/browser-extension#use-a-release-archive) for download and verification.
++Every Chromium browser uses the same archive, `agent-beacon-browser-extension-<version>-chrome.zip`, or a local `dist/` build. The `-chrome` suffix names the Chromium extension family, not Google Chrome alone; the Firefox build ships separately as `-firefox.xpi`. See [Use a release archive](/runtimes/browser-extension#use-a-release-archive) for download and verification.
+
+Load it unpacked from the browser's extensions page, with developer mode turned on:
+
+| Browser | Extensions page | Developer mode toggle |
+|---------|-----------------|-----------------------|
+| Google Chrome, Chromium | `chrome://extensions` | Top right |
+| Microsoft Edge | `edge://extensions` | Left sidebar |
+| Brave | `brave://extensions` | Top right |
+| Opera, Opera GX | `opera://extensions` | Top right |
+| Vivaldi | `vivaldi://extensions` | Top right |
+| Arc | `chrome://extensions` | Top right |
+
+Then choose **Load unpacked** and select the `dist` folder or the unzipped release folder, as described in [Load it in Chrome](/runtimes/browser-extension#load-it-in-chrome).
+
+The extension is not published in any extension store yet. When it is, Brave, Vivaldi, and Arc install from the Chrome Web Store, Opera needs its own add-ons listing (or the user allows Chrome Web Store installs in Opera), and Edge needs its own Microsoft Edge Add-ons listing through Partner Center. No Edge Add-ons submission exists today.
+
+## Manual verification checklist
+
+Use this for every browser the automated e2e does not cover, and record the result. Two passes: the replay e2e, which needs no login and no network, and a live check against the real sites.
+
+### 1. Replay e2e against the browser binary
+
+The Playwright harness accepts any Chromium-family binary through `BROWSER_EXECUTABLE`. It launches the browser with the built extension and replays recorded chat streams through it, which proves the extension loads, the interceptor fires, and delivery works in that browser.
+
+```bash
+cd browser-extension
+npm ci
+npm run build
+BROWSER_EXECUTABLE="/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" npx playwright test
+```
+
+Typical executable paths:
+
+| Browser | macOS | Linux |
+|---------|-------|-------|
+| Brave | `/Applications/Brave Browser.app/Contents/MacOS/Brave Browser` | `/usr/bin/brave-browser` |
+| Opera | `/Applications/Opera.app/Contents/MacOS/Opera` | `/usr/bin/opera` |
+| Vivaldi | `/Applications/Vivaldi.app/Contents/MacOS/Vivaldi` | `/usr/bin/vivaldi` |
+| Arc | `/Applications/Arc.app/Contents/MacOS/Arc` | Not available |
+
+On Windows, the path is the **Target** of the browser's shortcut (right-click the shortcut, then **Properties**).
+
+`BROWSER_CHANNEL` selects a Playwright channel instead (`chromium`, the default, or `msedge`; pre-release variants such as `msedge-beta` also work). `BROWSER_EXECUTABLE` wins when both are set. A browser that ignores `--load-extension`, as branded Chrome does, fails every test at the first step, which is itself a useful result: skip to the live check.
+
+### 2. Live check against the real sites
+
+With the Beacon endpoint running:
+
+- [ ] Load the extension unpacked from the browser's extensions page. It appears in the list, is enabled, and shows no errors.
+- [ ] The toolbar popup opens and shows capture on and a queue depth of 0.
+- [ ] Send one message on claude.ai. A `claude_web` event arrives in the runtime log.
+- [ ] Send one message on chatgpt.com. A `chatgpt_web` event arrives in the runtime log.
+- [ ] Both events carry `user_agent.name`. Note the value; see [Which browser an event came from](#which-browser-an-event-came-from) for what each browser should report.
+- [ ] No permission prompt about local network access appeared. The service worker console, from the extensions page, shows no delivery errors.
+- [ ] Quit and restart the browser. The extension is still enabled and the next message is still captured.
+- [ ] Browser-specific: in Brave, repeat one message with Shields up for the site; in Opera, confirm the extension is allowed on claude.ai and chatgpt.com; in Arc, check whether capture also works in a Space that uses a different profile, and record the answer.
+
+### 3. Record the result
+
+Add a row to the pull request or release notes that ran it:
+
+| Browser | Version | OS | Date | Replay e2e | Live check | `user_agent.name` seen |
+|---------|---------|----|------|------------|------------|------------------------|
+| _e.g. Brave_ | _1.x (Chromium N)_ | _macOS 15_ | _YYYY-MM-DD_ | _pass/fail_ | _pass/fail_ | _Brave_ |
+
+## Force-install through browser policy
+
+For IT-managed fleets, Chromium browsers can install an extension without user action through the `ExtensionInstallForcelist` policy, or its successor `ExtensionSettings` with `installation_mode: force_installed`. Each browser reads that policy from its own location:
+
+| Browser | Windows registry key | macOS preference domain | Linux policy directory |
+|---------|----------------------|-------------------------|------------------------|
+| Google Chrome | `HKLM\SOFTWARE\Policies\Google\Chrome` | `com.google.Chrome` | `/etc/opt/chrome/policies/managed/` |
+| Microsoft Edge | `HKLM\SOFTWARE\Policies\Microsoft\Edge` (Edge ADMX) | `com.microsoft.Edge` | `/etc/opt/edge/policies/managed/` |
+| Brave | `HKLM\SOFTWARE\Policies\BraveSoftware\Brave` (Brave ADMX) | `com.brave.Browser` | `/etc/brave/policies/managed/` |
+| Chromium | `HKLM\SOFTWARE\Policies\Chromium` | `org.chromium.Chromium` | `/etc/chromium/policies/managed/` |
+| Opera, Vivaldi, Arc | Not verified | Not verified | Not verified |
+
+Beacon has not verified an enterprise policy path for Opera, Vivaldi, or Arc. Check the vendor's current enterprise documentation, and test on one machine, before relying on policy there.
+
+Each `ExtensionInstallForcelist` entry is `<extension id>;<update URL>`. Two things block force-install today:
+
+- **There is no update URL to point at.** The extension is not in the Chrome Web Store or Microsoft Edge Add-ons, and Beacon does not publish a signed `.crx` with an update manifest. Force-install needs one of those.
+- **There is no stable extension ID.** An unpacked extension's ID is derived from the folder it was loaded from, because the manifest carries no `key`. A policy has nothing fixed to name until the extension is packaged with a key or listed in a store.
+
+Until then, distribution is load-unpacked. Managed profiles can also block developer mode, which blocks **Load unpacked**. If your fleet does, allow developer mode for the profiles that should run the extension, or wait for a store listing.
+
+## Related
+
+<Columns cols={2}>
+ <Card title="Browser extension" icon="puzzle-piece" href="/runtimes/browser-extension">
+ Install, configuration, and troubleshooting.
+ </Card>
+ <Card title="Schema fields" icon="table" href="/telemetry-schema/fields">
+ Where `user_agent` sits in the event schema.
+ </Card>
+</Columns>
diff --cc docs/runtimes/browser-extension.mdx
index 9c58d87a,de672182..e11beced
--- a/docs/runtimes/browser-extension.mdx
+++ b/docs/runtimes/browser-extension.mdx
@@@ -29,7 -29,7 +29,7 @@@ The extension is in beta. It is not pub
Before installing the extension, make sure:
- The Beacon endpoint is [installed](/cli/install) and running. The extension posts to the local collector on `http://127.0.0.1:4318/v1/logs`, which a default endpoint install already listens on, so no collector configuration is needed.
- - You have Chrome, Edge, or another Chromium browser that can load an unpacked MV3 extension. See [Chromium browsers](/runtimes/browser-extension-chromium) for which ones are tested. Firefox and Safari are not supported.
-- You have Chrome, or another Chromium browser that can load an unpacked MV3 extension, or Firefox 140 or newer for the Firefox build. Safari is not supported.
++- You have Chrome, Edge, or another Chromium browser that can load an unpacked MV3 extension (see [Chromium browsers](/runtimes/browser-extension-chromium) for which ones are tested), or Firefox 140 or newer for the Firefox build. Safari is not supported.
- You have Node 22 or newer, if you are building from source rather than using a release archive.
- You have reviewed what the extension retains. It captures full prompt and response text by default.
- The people whose browsers it runs in know it is there, since it reads their Claude.ai and ChatGPT conversations.
@@@ -98,8 -94,20 +98,22 @@@ The `-chrome` archive is the build for
4. Confirm the Agent Beacon browser collector now appears in the list and is enabled.
5. Click the extension's toolbar icon to check its status and, if you want, change the retention mode before capturing anything.
+Other Chromium browsers load it the same way from their own extensions page, such as `edge://extensions` or `brave://extensions`. See [Chromium browsers](/runtimes/browser-extension-chromium#install).
+
+ ### Load it in Firefox
+
+ The Firefox build is in beta. It is generated from the same sources as the Chrome build and passes Mozilla's linter in CI, but it has no automated end-to-end test, so capture on Firefox is checked by hand.
+
+ Build it with `npm run build:firefox`, which writes `browser-extension/dist-firefox`. Then:
+
+ 1. Open `about:debugging#/runtime/this-firefox`.
+ 2. Choose **Load Temporary Add-on**, then select `dist-firefox/manifest.json`. A temporary add-on is removed when Firefox restarts. For a permanent install, use a signed `.xpi` and the [enterprise policy](#firefox-enterprise-policy) below.
+ 3. Click the extension's toolbar icon. If it shows **Site access not granted**, choose **Grant site access** and accept Firefox's prompt.
+
+ <Warning>
+ Firefox lets the user withhold an MV3 extension's host permissions. If they are withheld, the extension captures nothing, and nothing on the chat site indicates it. The popup and options page show a **Site access not granted** banner listing the missing hosts, until access is granted. All five hosts are needed: `claude.ai`, `chatgpt.com`, and `chat.openai.com` for capture, and `127.0.0.1` and `localhost` for delivery to the collector. Access can also be changed per site in `about:addons`, under the extension's **Permissions** tab.
+ </Warning>
+
## Configuration
The extension is configured in its own UI, not by `beacon`. There is no CLI command and no config file on disk. Settings are split across two surfaces:
@@@ -171,8 -204,7 +210,8 @@@ Coverage that is the same for both site
| Approval telemetry | Not available. Neither site exposes approval decisions to a page script |
| Session lifecycle | Partial. Turns are correlated by conversation id; there is no session start or stop signal |
| Local JSONL and dashboard | Supported after events reach the collector |
- | MDM deployment | Not covered by Beacon's MDM assets. Browser force-install policy needs a store listing or signed package, which do not exist yet. See [Force-install through browser policy](/runtimes/browser-extension-chromium#force-install-through-browser-policy) |
-| MDM deployment | Not covered by Beacon's MDM assets. Distribute through browser policy instead, such as Firefox's [`ExtensionSettings`](#firefox-enterprise-policy) |
++| MDM deployment | Not covered by Beacon's MDM assets. Distribute through browser policy instead, such as Firefox's [`ExtensionSettings`](#firefox-enterprise-policy). Chromium force-install needs a store listing or signed package, which do not exist yet; see [Force-install through browser policy](/runtimes/browser-extension-chromium#force-install-through-browser-policy) |
+| Browser attribution | Supported. `user_agent.name` and `user_agent.version` name the browser on every event |
Tool telemetry and token usage differ by site. See [Claude.ai](/runtimes/claude-web) and [ChatGPT](/runtimes/chatgpt-web).