An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
docs: document the harness, voice input, and local state
Shahriar06ec89bd477e
diff --git a/CLAUDE.md b/CLAUDE.mdnew file mode 100644index 0000000..8b874f0--- /dev/null+++ b/CLAUDE.md@@ -0,0 +1,113 @@+# CLAUDE.md++This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.++## Skills++Project skills live in `.claude/skills/<name>/SKILL.md` and are invoked with a leading slash (`/<name>`) or picked up automatically when the request matches their `description` triggers.++| Skill | Use it for |+| --- | --- |+| [`/voicelink`](.claude/skills/voicelink/SKILL.md) | Driving the user's real browser through the MCP harness — the preflight check, targeting strategy, the error-code → next-move table, navigation edge cases, and the safety rules that apply because these tools act on a live logged-in session. |++Read the skill before calling any `page_*` or `voicelink_*` tool; it encodes failure modes that are not obvious from the tool schemas.++## Project++VoiceLink is an AI voice assistant Chrome extension (Manifest V3) built with WXT (Vite-based extension framework), React 19, TypeScript, Tailwind CSS v4, and shadcn/ui. Its core is a declarative **action layer** (`lib/actions/`) of page-control capabilities designed to double as MCP tool definitions. The AI chat and voice features are still mocked; the scaffold marks where to wire them in.++## Commands++```sh+npm run dev # build + launch Chrome (throwaway profile) with the extension loaded, HMR+npm run dev:firefox # same, for Firefox+npm run build # production build → dist/chrome-mv3/+npm run compile # type-check only (tsc --noEmit) — the only check tooling; no lint or tests configured+npm run zip # store-ready zip+npm run icons # regenerate placeholder icons in public/icon/+npx shadcn@latest add <component> # add shadcn/ui components → components/ui/+```++The MCP harness lives in `mcp/` and is a **separate npm package** with its own `node_modules`, `tsconfig.json`, and dependency install:++```sh+npm run mcp:install # one-time; `npm install` at the root does NOT cover mcp/+npm run mcp:build # tsup → mcp/dist/ (bundles lib/actions via the @/* path alias)+npm run mcp:link # one-time; puts `voicelink-mcp` on PATH (npm run mcp:unlink undoes it)+npm run compile:mcp # type-check mcp/ (the root `npm run compile` excludes it)+npm run mcp:manifest # build + print the tool manifest from plain Node — no browser+```++Docs and daemon-printed hints all use the bare `voicelink-mcp` name, so `mcp:link` is effectively required for the documented workflow; without it, invoke `node mcp/dist/cli.js` instead.++`npm run mcp:manifest` is the standing check that no action gained a top-level DOM reference: it loads the shipped bundle in bare Node, where `document` at module scope throws on import.++`npm run compile` depends on generated types in `.wxt/` — run `npm install` (its postinstall runs `wxt prepare`) if they're missing.++## Architecture++### WXT conventions++- **The manifest is generated.** WXT builds `manifest.json` from `wxt.config.ts` (name, permissions: `storage`, `activeTab`, `sidePanel`, `alarms`, `scripting` + host access for content-script re-injection) plus filesystem conventions in `entrypoints/`: `background.ts` → service worker, `content.ts` → content script, `popup/index.html` → action popup, `sidepanel/index.html` → side panel. Never edit anything in `dist/` or `.wxt/` — both are generated.+- **Auto-imports.** In `entrypoints/`, `browser`, `defineBackground`, `defineContentScript`, etc. are globals injected by WXT (typed in `.wxt/types/`). Code in `lib/` imports explicitly from `wxt/browser` instead. The `@/` alias maps to the project root and comes from `.wxt/tsconfig.json`, which the root `tsconfig.json` extends.+- **Styling.** Tailwind v4 via the `@tailwindcss/vite` plugin in `wxt.config.ts` — no `tailwind.config` file; the theme lives in `assets/globals.css`. Dark mode: each entrypoint's `main.tsx` adds `.dark` to `<html>` based on `prefers-color-scheme`.++### The action layer (`lib/actions/`)++Each action is a frozen value from `defineAction()` (`core.ts`): a namespaced name (`page.clickElement`), a one-line description, a zod input schema, and an `execute()` that runs **in the page** (content-script context). The same declarative shape drives typed in-extension calls today and MCP tool definitions later. The pieces:++- `registry.ts` — the `Map` of all 17 actions, plus `describeActions()` → `[{ name, description, inputSchema }]` with JSON Schema (`io: 'input'`, so defaulted fields stay optional and the manifest matches what `dispatch` actually accepts).+- `dispatch.ts` — validates input against the schema and runs the action; always returns the `{ ok: true, data } | { ok: false, error: { code, message } }` envelope, never throws (`UNKNOWN_ACTION`, `INVALID_INPUT`, or the action's own `ActionError` code).+- `host.ts` — `exposeActions()`, called by the content script; listens on the `voicelink/action` channel and dispatches in the page.+- `client.ts` — `invokeInTab` / `invokeInActiveTab`: typed callers usable from any extension context. Passing the action object (not the string name) gives compile-time input typing — and the `input` argument is *required* when the schema has required fields. Transport failures come back as `TAB_UNREACHABLE` / `NO_ACTIVE_TAB` rather than throwing.+- `protocol.ts` — the two message channels: `voicelink/action` (extension → content script, one invocation) and `voicelink/bridge` (extension pages or external MCP harness → background worker; `op: 'describe'` returns the tool manifest, `op: 'invoke'` routes an action to the active tab). `background.ts` implements the bridge. `index.ts` re-exports the public API.+- `page/dom.ts` — shared targeting: most actions take `target: { selector?, text?, role?, nth? }`, resolved by `resolveTarget()` (visible elements only; text matches against accessible text, keeping the innermost match). `resolveTarget(target, { includeHidden: true })` opts out of the visibility filter — only `wait-for-element.ts` does, so its `attached`/`hidden`/`detached` states can observe hidden elements.+- `page/keyboard.ts` — `keyboardInit(key, modifiers)` builds a realistic `KeyboardEventInit`, including legacy `keyCode`/`which` so older handlers fire. Used by `press-key.ts` and `fill-input.ts`.++Call path: side panel / bridge → `invokeForHarness` → `browser.tabs.sendMessage` → content script `exposeActions` → `dispatch` → `action.execute` in the page.++### The MCP harness (`mcp/`, `lib/bridge/`)++`mcp/` is an installable package (`voicelink-mcp` on stdio, `voicelink-mcpd` as the daemon) that exposes the registry as MCP tools. The daemon owns a loopback WebSocket server; the extension connects **out** to it, because an MV3 service worker cannot listen.++- **Parity is structural, not conventional.** The daemon bundles `describeActions()` from `lib/actions/registry.ts` (tsup resolves `@/*` → repo root), so `tools/list` cannot drift from the registry within a build. Adding an action to `registry.ts` is the *only* step needed to expose a new MCP tool.+- **Names.** MCP tool names cannot contain dots, so `page.clickElement` ⇄ `page_clickElement` via `lib/actions/tool-names.ts`. The mapping is only reversible while no action name segment contains an underscore — `assertToolNamesRoundTrip()` enforces this at startup and in `voicelink-mcp tools`.+- **Wire types are shared, not copied.** `SocketFrame` and the `ActionResult` envelope both live in `lib/actions/protocol.ts` and are imported by both sides; `lib/actions/manifest.ts` hashes the manifest so a version-skewed extension is detected on connect.+- **Never import `@/lib/actions` (the index) from `mcp/`** — it re-exports `client.ts`/`host.ts`, which import `wxt/browser` and break in Node. Import the specific modules.+- **Auth is two independent gates.** At the HTTP upgrade the daemon classifies the peer by handshake `Origin` (extension scheme → extension path; `http(s)` → 403; absent → control client, lockfile token required). That only proves the peer is *an* extension; the `hello` frame must then carry a one-time `pairingToken` or a session key bound to that same origin. Credentials ride in the frame because the browser `WebSocket` API cannot set request headers, and a URL query would leak into logs.+- **The extension is off by default.** `connectDaemon()` returns without dialing unless `storage.local` holds a session key, so an unpaired browser never contacts the daemon. Pairing state lives in `~/.voicelink/auth.json` (`0600`) — deliberately *not* the lockfile, which is deleted on shutdown.+- Verified: Chrome does send `Origin: chrome-extension://<id>` from an MV3 worker.+- **The wire protocol is v2**: on top of the v1 request/reply frames, the extension may send `instruct`/`cancel`/`decision`/`reset` unprompted, and the daemon streams `run` frames back. `assertToolNamesRoundTrip` aside, protocol bumps require rebuilding both sides *and* reloading the extension — a v1 worker is refused at `hello`.+- **Navigation is special-cased** in `lib/bridge/invoke.ts`. It tries the in-page action first (pushes history) and falls back to `browser.tabs.update` only when `sendMessage` fails with "Receiving end does not exist" — a pre-delivery error proving the action never ran. Any other failure means the page already unloaded and is navigating, so re-issuing would navigate twice.+- **Service-worker lifetime.** Daemon pings every 20s reset Chrome's 30s idle timer; a 1-minute `alarms` tick is the only thing that can revive the worker once it is torn down.++### The agent harness (`mcp/src/agent/`, side panel)++The reverse direction of the MCP harness: a free-text instruction typed (or spoken) into the extension travels **out** over the same socket, and the daemon runs it as an agent that drives the browser back. There is deliberately no Anthropic API client anywhere — the daemon spawns the user's own **Claude Code** (`claude -p`), so the user's existing login, model choice and limits apply, and no API key ever exists in this codebase.++Call path: side panel/popup → `runtime.connect` port (`lib/bridge/run-port.ts`) → background → `instruct` frame (`lib/bridge/socket.ts`) → daemon → `AgentSession` (`mcp/src/agent/service.ts`) → `claude -p` (`mcp/src/agent/runner.ts`). The spawned Claude Code gets browser tools through our own stdio MCP server: `--mcp-config` points it back at `dist/cli.js` with `--strict-mcp-config`, so its tool calls loop through the daemon and out to the content script like any other MCP client's. Everything else it could touch is disabled via `--disallowedTools`.++- **Run identity is the safety boundary.** The spawn carries `VOICELINK_AGENT_RUN=<runId>`; `RemoteBridge` attaches it to every invoke, and the daemon routes tagged invokes through `AgentSession.invokeForRun` — which emits the timeline `tool`/`toolResult` events, applies the approval gate (`requireApproval` in `~/.voicelink/config.json`, default `page.submitForm`), and refuses invokes whose run is no longer active (a cancelled agent cannot keep driving).+- **Skills are markdown system prompts** in `mcp/skills/*.md` (bundled; `~/.voicelink/skills/` overrides by name, reloaded every run). Front-matter: `name`, `description`, `triggers: [...]`, `default: true`. Routing: `@name` prefix wins, else most trigger hits, else the default. The body is passed via `--append-system-prompt` on top of the frozen preamble in `mcp/src/agent/prompt.ts`.+- **Conversation continuity is Claude Code's own session store**: first run passes `--session-id`, follow-ups `--resume`; the side panel's clear button sends `reset`, which just forgets the id.+- **Run events** (`RunEvent` in `lib/actions/protocol.ts`) stream daemon → extension as `run` frames; the background worker fans them out to extension pages over a long-lived `runtime.connect` port (streamed text arrives token by token — `storage.session` would be wrong here). If no page is watching, the run is cancelled after a grace period.+- `voicelink-mcp logs` is the debugging surface: every run start/finish, routed skill, and tool call lands in `~/.voicelink/daemon.log`.++### Adding an action++One module per action: `lib/actions/page/<name>.ts` exporting `defineAction({ name: 'page.<name>', … })`, then add it to the array in `registry.ts`. That single edit also publishes it as an MCP tool. The conventions below are load-bearing — breaking them fails at runtime or silently corrupts the MCP manifest, not at compile time:++- **No top-level DOM access.** Touch `document`/`window` only inside `execute()`. `registry.ts` is imported by the background worker (for `describeActions()`), by the MCP daemon, and by plain Node, where a top-level DOM reference throws at import time. `npm run mcp:manifest` is the check.+- **No underscores in action names** — they break the round trip to MCP tool names.+- **`.describe()` every input field** — that text becomes the MCP tool's parameter documentation.+- **No zod `.refine()`/`.transform()`** — they don't survive `z.toJSONSchema()`. Validate inside `execute()` with `throw new ActionError(msg, 'CODE')`, using a stable code: `INVALID_INPUT`, `INVALID_TARGET`, `TARGET_NOT_FOUND`, `TIMEOUT`, `UNSUPPORTED`.+- **Return a small JSON-serializable result** (usually `describeElement(el)`). It crosses `sendMessage`, so never put a DOM node in it — read form attributes with `getAttribute('action')`, since a control named `action`/`method` shadows the IDL property with an element.+- **Write to inputs through the native prototype setter** (`Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')!.set!.call(el, next)`) then dispatch `input`/`change`. React/Vue ignore direct `.value` writes on controlled inputs. See `fill-input.ts`, `press-key.ts`, `select-option.ts`.+- **Synthetic events perform no default action.** Dispatched keys don't insert text or submit forms, so actions emulate that explicitly — and honor cancellation by checking `dispatchEvent()`'s return value before emulating.+- Keep comments to genuine DOM quirks only; the layer is deliberately low-noise.++## AI integration points++- **Chat responses:** real — the side panel's composer sends instructions through the agent harness (see above); replies and tool activity stream back into `RunTimeline`.+- **Voice input:** real, via the browser's Web Speech API (`webkitSpeechRecognition` — Chrome streams the audio to Google to transcribe; no bundled model). `lib/bridge/use-speech.ts` wraps recognition (mic-permission prompt, continuous mode, silence-driven auto-restart, feature detection); `lib/bridge/use-voice-composer.ts` layers hands-free dictation on top — finalized phrases append to an editable buffer and auto-send after a short silence, with any of {more speech, typing, cancel} calling off the pending send. The **side panel** listens by default (persisted `voicelink:voiceEnabled`, toggled by the mic button); the **popup** is press-to-talk, since a popup dies on blur and can't hold continuous listening. Both surfaces fall back to typing when recognition is unavailable or the mic is blocked. STT swap-out point is `use-speech.ts` alone.+- **Page context:** the side panel's paperclip button calls the `page.getPageInfo` action on the active tab and splices the result into the prompt.diff --git a/README.md b/README.mdnew file mode 100644index 0000000..552769d--- /dev/null+++ b/README.md@@ -0,0 +1,247 @@+# VoiceLink++**Talk to any web page.** VoiceLink is a Manifest V3 Chrome extension that turns a spoken or typed+instruction into real actions on the tab in front of you — clicking, filling, reading, navigating —+and narrates what it did as it goes.++Three pieces make that work:++- **An action layer** (`lib/actions/`) — 17 declarative, self-describing page capabilities that run+ in the content script.+- **An MCP harness** (`mcp/`) — the same registry exposed as an MCP server, so Claude Code or any+ other MCP client can drive your real, logged-in browser through a local daemon.+- **An agent harness** (`mcp/src/agent/`) — the reverse direction: an instruction typed into the+ side panel spawns **your own Claude Code**, which drives the browser back through that same+ server. There is no Anthropic API client in this repo and no API key anywhere in it.++Built with:++- **[WXT](https://wxt.dev)** — Vite-powered extension framework (auto-generated manifest, HMR, multi-browser builds)+- **React 19 + TypeScript** — UI entrypoints+- **Tailwind CSS v4** — styling via `@tailwindcss/vite`+- **[shadcn/ui](https://ui.shadcn.com)** — the component system used by most modern AI products (Radix primitives + CVA + `lucide-react` icons)+- **[zod](https://zod.dev)** — one schema per action, doubling as its MCP tool definition++## Getting started++```sh+npm install+npm run dev # builds, launches Chrome with the extension loaded, and hot-reloads+```++Other commands:++```sh+npm run build # production build → dist/chrome-mv3/+npm run build:firefox # firefox build+npm run zip # store-ready zip+npm run compile # type-check only (tsc --noEmit)+npm run icons # regenerate placeholder icons in public/icon/+```++To load the production build manually: `chrome://extensions` → enable **Developer mode** → **Load unpacked** → select `dist/chrome-mv3`.++## What's included++| Surface | File | Notes |+| --- | --- | --- |+| Popup | `entrypoints/popup/` | Press-to-talk mic, instruction box, pairing UI, "open side panel" |+| Side panel | `entrypoints/sidepanel/` | The agent chat: always-on dictation, streamed replies, live tool timeline, approval prompts |+| Background | `entrypoints/background.ts` | MV3 service worker + the action bridge (`describe`/`invoke`) + the MCP daemon link + the run port |+| Content script | `entrypoints/content.ts` | Exposes the action layer in every page (`exposeActions()`) |+| MCP harness | `mcp/` | Installable MCP server + daemon that drives the browser (see below) |+| Agent harness | `mcp/src/agent/`, `mcp/skills/` | Turns typed instructions into agent runs by spawning your own Claude Code (see below) |++```+assets/globals.css # Tailwind v4 + shadcn theme (violet, dark-mode aware)+components/ui/ # shadcn/ui components (button, badge, card, input, textarea, scroll-area)+lib/actions/ # the declarative page-control action layer (see below)+lib/bridge/ # extension side of the harness (daemon socket, invoke path, speech hooks)+mcp/ # the installable MCP server + daemon+mcp/skills/ # markdown system prompts the daemon routes instructions to+lib/utils.ts # cn() helper+public/icon/ # generated placeholder icons+wxt.config.ts # manifest + Vite/Tailwind config+components.json # shadcn CLI config+```++### Adding more shadcn/ui components++```sh+npx shadcn@latest add dialog dropdown-menu tooltip+```++Components land in `components/ui/` and import via the `@/` alias (provided by WXT).++## The agent harness — instructions in, actions out++Type an instruction into the side panel (or the popup) of a paired browser and the daemon runs it as an agent: it routes the text to a **skill** (a markdown system prompt from `mcp/skills/`, user-overridable in `~/.voicelink/skills/`), spawns **your own Claude Code** (`claude -p` — your login, your model, no API key anywhere in this repo), and hands it the browser through the same MCP server external clients use. Text streams back token by token; every `page_*` call shows up as a row on the side panel's timeline as it happens; gated actions (`page.submitForm` by default — edit `requireApproval` in `~/.voicelink/config.json`) pause for an Allow/Deny in the panel. Follow-ups resume the same Claude Code session, so "now click the second one" works.++Requires [Claude Code](https://claude.com/claude-code) on your PATH (or `{"claudeBin": "/path/to/claude"}` in `~/.voicelink/config.json`).++## Voice input++Dictation is live, on the browser's own **Web Speech API** (`webkitSpeechRecognition`) — Chrome+streams the audio to Google to transcribe, so there is no model bundled here and nothing to+download.++- [`use-speech.ts`](lib/bridge/use-speech.ts) wraps recognition itself: the mic-permission prompt,+ continuous mode, silence-driven auto-restart, and feature detection.+- [`use-voice-composer.ts`](lib/bridge/use-voice-composer.ts) layers hands-free dictation on top.+ Finalized phrases append to an *editable* buffer and auto-send after ~1.6 s of silence; more+ speech, typing, or an explicit cancel all call the pending send off, so you are never racing a+ timer.++The **side panel** listens by default (persisted under `voicelink:voiceEnabled`, toggled by the mic+button, and muted while a run is in flight or the browser is unpaired). The **popup** is+press-to-talk instead — a popup is destroyed the moment it loses focus and cannot hold continuous+listening. Both surfaces fall back to plain typing when recognition is unavailable or the mic is+blocked.++Swapping in a different speech-to-text engine is a one-file change: [`use-speech.ts`](lib/bridge/use-speech.ts)+is the only module that knows the Web Speech API exists.++## The action layer (`lib/actions/`)++A set of **declarative, first-class functions** that read and control the current web page. Each is a self-describing value — a semantic name, a one-line description, and a [zod](https://zod.dev) input schema — so the same registry drives in-extension calls today and an external **MCP harness** later.++```ts+// lib/actions/page/scroll-to.ts+export const scrollTo = defineAction({+ name: 'page.scrollTo',+ description: 'Scroll the page to an element, an absolute position, or by one viewport.',+ input: z.object({ target: targetSchema.optional(), /* … every field .describe()d */ }),+ execute({ target, position, direction, behavior }) { /* the side effect */ },+});+```++One action per module under `lib/actions/page/`:++| Action | Effect |+| --- | --- |+| `page.getPageInfo` | Snapshot: metadata, viewport/scroll, **semantic layout tree + text diagram**, heading outline, inventory of links/buttons/fields/forms with stable selectors |+| `page.scrollTo` | Scroll to an element, a position, or by a viewport (`up`/`down`/`top`/`bottom`) |+| `page.clickElement` | Realistic click (pointer/mouse sequence + native `.click()`) |+| `page.hoverElement` | Pointer/mouse hover sequence to trigger menus & tooltips |+| `page.focusInput` | Focus an element and place the caret (`start`/`end`/`all`) |+| `page.fillInput` | Type into an input/textarea/contenteditable (React/Vue-compatible), optional Enter |+| `page.selectOption` | Choose a `<select>` option by value, label, or index |+| `page.selectText` | Select an element's text, or the nth match of a phrase (spans inline markup) |+| `page.extractText` | Read rendered text or HTML of an element or the page |+| `page.pressKey` | Send a key with modifiers, with Enter-to-submit emulation |+| `page.submitForm` | Submit a form via `requestSubmit()` (runs validation) |+| `page.waitForElement` | Await `attached`/`visible`/`hidden`/`detached`, with timeout |+| `page.highlightElement` | Flash a temporary overlay on an element |+| `page.navigate` | Open a URL, or go `back`/`forward`/`reload` |+| `page.screenshot` | Capture the tab (full scroll view, viewport, or a targeted element) as a PNG/JPEG — stitched in the background worker; optionally saved under `~/voicelink/screenshot/` and returned as an image the agent can see |+| `page.listFiles` | List the user's files stored in VoiceLink, with their AI-generated summaries (resolved in the background from extension storage) |+| `page.attachFile` | Attach a stored file (by id) to a page's `<input type="file">` — the background reads the bytes, the page sets `input.files` via a `DataTransfer` |++**Targeting** is shared and declarative — most actions take a `target: { selector?, text?, role?, nth? }`, resolved by [`resolveTarget`](lib/actions/page/dom.ts) (visible elements only; text matches the innermost accessible element).++### Calling actions++```ts+import { invokeInActiveTab } from '@/lib/actions/client';+import { fillInput } from '@/lib/actions/page/fill-input';++// Fully typed from the action's schema; returns { ok: true, data } | { ok: false, error }+const res = await invokeInActiveTab(fillInput, { target: { text: 'Email' }, value: '[email protected]' });+```++- [`client.ts`](lib/actions/client.ts) — `invokeInTab` / `invokeInActiveTab`, typed end-to-end (input is compile-time required when the schema needs it).+- [`host.ts`](lib/actions/host.ts) — `exposeActions()`, run by the content script ([content.ts](entrypoints/content.ts)), dispatches actions in the page.+- [`dispatch.ts`](lib/actions/dispatch.ts) — validates input and returns the `{ ok }` envelope; unknown actions and bad input are structured failures, never throws.++### The MCP harness (`mcp/`)++[`@voicelink/mcp`](mcp/) turns the same registry into an MCP server, so Claude Code (or any MCP client) can drive the browser. It ships two binaries:++| Binary | Role |+| --- | --- |+| `voicelink-mcp` | MCP server on stdio — what an MCP client spawns. Starts the daemon if needed. |+| `voicelink-mcpd` | The daemon: a loopback WebSocket server on `127.0.0.1:8765` (falling back to 8766/8767) |++```sh+npm run mcp:install # one-time: install the package's own dependencies+npm run mcp:build # → mcp/dist/+npm run mcp:link # one-time: put `voicelink-mcp` on your PATH+npm run mcp:manifest # print the tool manifest (no browser needed)++claude mcp add voicelink -- voicelink-mcp+```++`mcp:link` runs `npm link`, symlinking both binaries into your npm prefix — rebuilds are picked up automatically, and `npm run mcp:unlink` removes them. Without it the CLI still works as `node mcp/dist/cli.js`, but every command below (and the hints the daemon prints) assumes the linked name.++```+Claude Code ──stdio──> voicelink-mcp ──ws(control)──┐+ ▼+ voicelink-mcpd (127.0.0.1:8765)+ ▲+ ws(extension, Origin-pinned)+ │+ background.ts ──> content script ──> execute()+```++The extension dials **out** to the daemon because an MV3 service worker cannot listen for connections. One daemon owns the browser link, so several MCP clients can share one browser.++**Tool parity is structural.** The daemon bundles [`describeActions()`](lib/actions/registry.ts) from this repo, so `tools/list` *is* the registry — 17 page tools plus `voicelink_status`. Dots are illegal in MCP tool names, so `page.clickElement` is exposed as `page_clickElement` ([tool-names.ts](lib/actions/tool-names.ts) round-trips the mapping and refuses collisions). On connect both sides exchange a hash of their manifest ([manifest.ts](lib/actions/manifest.ts)); if an installed extension was built from a different registry the daemon adopts the browser's list and emits `tools/list_changed`.++Three read-only resources avoid spending a tool call on page context: `voicelink://page/current` (full snapshot), `voicelink://page/diagram` (the layout diagram alone — the cheapest useful view), and `voicelink://page/text`.++### Pairing — agent control is off until you turn it on++A freshly installed extension connects to nothing. It dials the daemon only after you redeem a one-time code, so no agent can drive the browser without an explicit, deliberate act:++```sh+voicelink-mcp pair # prints e.g. PQC3-3RQ7 (single use, expires in 10 min)+```++Then open the VoiceLink popup, paste the code, and press **Connect**. The daemon consumes the code and issues a long-lived session key that the extension stores; it survives service-worker teardown, daemon restarts, and browser restarts, and dies only when you revoke it.++```sh+voicelink-mcp sessions # which browsers are paired, and which is live+voicelink-mcp revoke # unpair everything (or pass one origin)+voicelink-mcp status # daemon + extension state+voicelink-mcp tools # the bundled manifest+voicelink-mcp logs # ~/.voicelink/daemon.log+voicelink-mcp stop+```++**How the daemon decides who may connect.** Any web page can open a WebSocket to loopback, so there are two independent gates:++1. *At the HTTP upgrade*, by handshake `Origin`. Browsers set `Origin` themselves and pages can neither forge nor omit it, so the branches are mutually exclusive: an extension origin takes the extension path, `http(s)` origins get a flat 403, and a header-less local process (the CLI, the stdio server) must present the token from the `0600` lockfile. A web page can never reach the control path.+2. *In the `hello` frame*, by credential. Reaching the extension door proves only that you are **an** extension — a pairing token or a valid session key proves you are **the paired** one. Credentials travel in the frame rather than the URL (the browser `WebSocket` API cannot set headers), so they never land in a log or a process list.++Session keys are bound to the origin that paired them, pairing codes are consumed on first use, and revoking drops any live connection immediately. State lives in `~/.voicelink/auth.json` (`0600`), separate from the lockfile so shutting the daemon down never unpairs your browser.++> The token gates *which browser*, not *which local process*. Anything running as your user can read the lockfile and drive an already-paired browser — that is the real perimeter. And a paired agent reading a malicious page is still susceptible to prompt injection; pairing controls access, not intent.++Extension-page callers still use the in-process bridge on [background.ts](entrypoints/background.ts) (`{ channel: 'voicelink/bridge', op: 'describe' | 'invoke' }`); both routes share [`invokeForHarness`](lib/bridge/invoke.ts).++### Adding an action++Create `lib/actions/page/<name>.ts` exporting a `defineAction({ name: 'page.<name>', … })`, then add it to the array in [registry.ts](lib/actions/registry.ts). Keep every input field `.describe()`d and validate at runtime with `throw new ActionError(msg, 'CODE')` (no zod `.refine`/`.transform`, so schemas stay JSON-Schema-clean).++## Local state & what never reaches the repo++Everything the daemon persists lives under `~/.voicelink/`, outside the working tree:++| Path | Contents |+| --- | --- |+| `~/.voicelink/auth.json` (`0600`) | Pairing session keys, bound to the extension origin that redeemed them. Survives daemon restarts; cleared by `voicelink-mcp revoke`. |+| `~/.voicelink/daemon.json` | The lockfile — port and the control-client bearer token. Deleted on shutdown, so it is deliberately *not* where pairing state is kept. |+| `~/.voicelink/daemon.log` | Run starts/finishes, routed skill, every tool call — `voicelink-mcp logs`. |+| `~/.voicelink/config.json` | Optional: `claudeBin`, `requireApproval`. |+| `~/.voicelink/skills/` | Optional user skills that override the bundled ones by name. |++There are **no credentials in this repository and none to add** — the agent runs on your existing+Claude Code login, and speech goes through the browser's built-in recognition. `.gitignore` still+guards the paths above (plus `.env*`, key material, and the `mcp/bin/` + `mcp/lib/` symlinks that+`npm run mcp:link` creates) so a stray copy of any of them cannot be committed by accident.++## Notes++- The manifest is generated by WXT from `wxt.config.ts` — edit permissions/name there, not in `dist/`.+- Popup and side panel follow the system light/dark preference (`.dark` class toggled in each `main.tsx`).+- The dark-launch Chrome profile used by `npm run dev` is throwaway; see [WXT's browser startup docs](https://wxt.dev/guide/essentials/config/browser-startup.html) to customize it.