Skip to content

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.

docs: plan the declarative refactor across the extension and the harness

Shahriar8754ad405489
diff --git a/REFACTOR.md b/REFACTOR.md
new file mode 100644
index 0000000..1dae5ff
--- /dev/null
+++ b/REFACTOR.md
@@ -0,0 +1,357 @@
+# Declarative refactor plan
+
+Target: `lib/`, `components/`, `entrypoints/`, `mcp/src/` — 108 files, ~12.7k lines.
+
+## Verdict first
+
+The action layer (`lib/actions/`) and the intent funnel (`lib/intent/`) are already
+declarative — a registry of frozen descriptors, a rules table scored by a pure router.
+They are the model. Almost nothing else in the project follows them.
+
+The imperative weight is concentrated in six places, and it is mostly **duplication**,
+not style: the same pattern hand-written three or four times, each copy free to drift.
+That is the refactor's real payoff. "Fewer `for` loops" is not.
+
+Counted, in the current tree:
+
+| Pattern | Copies | Where |
+| --- | --- | --- |
+| Pending-request + timeout + promise map | 4 | [socket.ts:63-176](lib/bridge/socket.ts#L63-L176) |
+| Frame handler with `.then/.catch` envelope | 7 | [daemon.ts:197-246](mcp/src/daemon.ts#L197-L246) |
+| `storage.local` index + body store | 4 | `file-store`, `session-store`, `skill-store`, `recording-store` |
+| Byte-budgeted prompt section builder | 2 | [service.ts:356-419](mcp/src/agent/service.ts#L356-L419) |
+| Scrub-and-cap-every-leaf validator | 2 | `lib/skills/site-map.ts`, `lib/recordings/workflow.ts` |
+| `(input as { x?: unknown })` re-parse of a schema'd input | ~36 | 17 files |
+
+Module-level mutable state: 12 `let`s across three files (`socket.ts`, `run-port.ts`,
+`recorder.ts`). Those three *are* state machines; they are just written as globals.
+
+## What this plan will not touch
+
+Deciding this up front matters more than the rest of the plan, because a blanket
+"make it declarative" sweep would damage each of these.
+
+- **`renderInline` in [markdown.tsx:354-411](components/markdown.tsx#L354-L411).** A hand-tuned
+ single-pass scanner with shared sticky regexes, a `lastIndex`-before-recursion rule, and a
+ bounded look-ahead that exists because unbounded backtracking measured at 29s of blocked
+ main thread. It re-runs per streamed token. Split the *file*; do not restructure the loop.
+- **`send()` / `readCapped()` in [sitemap.ts:188-268](mcp/src/agent/sitemap.ts#L188-L268).**
+ The running byte counter and destroy-on-overflow *are* the control against a 4 MB gzip bomb.
+ A `.reduce()` over chunks would remove the early exit. Extract the pure parsers around it.
+- **Capture-phase listeners in [capture.ts:220-234](lib/recordings/capture.ts#L220-L234).**
+ They must be imperative registrations in the page, and the mutable `pendingFill` /
+ `lastClickAt` state is what makes the recorder semantic rather than a DOM replay.
+- **`spawnClaude` argv assembly in [runner.ts:31-190](mcp/src/agent/runner.ts#L31-L190).**
+ The `--tools ''` allowlist is a security boundary. It can become a typed builder; the
+ flag list must stay a literal that reads top-to-bottom in review.
+- **Action names, `.describe()` strings, and registry order.** `describeActions()` is hashed
+ (`hashManifest`) and compared at `hello`. Any incidental change to those forces a lockstep
+ rebuild of extension + daemon. Refactor *around* the registry, never through it.
+
+Three modules also have hard import constraints that survive the refactor:
+`lib/skills/format.ts` must stay import-free, `lib/intent/**` must stay free of `browser.*`
+and DOM (`yarn intent:check` runs it in bare Node), and `lib/actions/registry.ts` must gain
+no top-level DOM reference (`yarn mcp:manifest` is that check).
+
+## Library decision: no Ramda
+
+Recommend against it, on four grounds:
+
+1. Ramda's TypeScript types are weak and its curried signatures degrade inference — it works
+ directly against the "increase strict typing" goal.
+2. Its default build tree-shakes poorly; this bundles into an MV3 content script.
+3. The code already uses native `map`/`filter`/`flatMap`/`Object.entries` throughout. The
+ imperative residue is *state machines and I/O*, which Ramda does not address.
+4. Nothing in Ramda models `ActionResult`, which is the type actually threaded through
+ every call path in this project.
+
+Instead:
+
+- **`lib/fn.ts`, hand-rolled, ~60 lines, no dependency.** `pipe`, `flow`, `tap`,
+ `assertNever`, and — the important half — combinators over the existing `ActionResult`:
+ `mapOk`, `flatMapOk`, `mapErr`, `orElse`, `unwrapOr`, `allOk`. This is the single
+ highest-leverage change in the plan; see Phase 1.
+- **If a utility belt is still wanted later: `remeda`, not Ramda** — TS-first, tree-shakable,
+ `pipe` built in. Scope it to `mcp/` first, where bundle size is irrelevant. Do not import
+ it into `lib/skills/format.ts`, `lib/intent/`, or anything a content script pulls in.
+- **`zod` is already a dependency on both sides** and is the right tool for the wire types
+ (Phase 4). No new package needed.
+
+## Phase 0 — foundations (no behaviour change)
+
+1. `lib/fn.ts` — `pipe`, `flow`, `tap`, `assertNever`, and the `ActionResult` combinators.
+2. `lib/result.ts` or fold into `protocol.ts` — keep `success`/`failure` where they are so
+ both packages keep importing one module.
+3. `scripts/check-purity.mjs` — the project has no lint step and three bare-Node check
+ scripts; this follows that convention rather than introducing ESLint. It asserts that
+ modules under a declared pure set import nothing from `wxt/browser`, `node:*`, or touch
+ `document`/`window`/`browser.` at any scope. Wire into a new `yarn purity:check`.
+4. Add to `package.json`: `"check": "yarn compile && yarn compile:mcp && yarn intent:check && yarn security:check && yarn purity:check && yarn mcp:manifest"`. Every phase below is
+ gated on this staying green.
+
+No comments in any new module — the repo carries none by design; load-bearing rules go in
+`CLAUDE.md`.
+
+## Phase 1 — the Result spine (compose + pipe, for real)
+
+Today every caller unpacks `ActionResult` by hand: `if (!result.ok) return ...`, ~90 times.
+That is the imperative pattern the codebase repeats most.
+
+With combinators, the call sites collapse:
+
+- [invoke.ts:125-135](lib/bridge/invoke.ts#L125-L135) `navigateTab` — the in-page-then-tabs-API
+ fallback becomes `orElse(isNoContentScript, () => navigateViaTabsApi(...))`, which states
+ the documented rule (*only* a pre-delivery failure may retry) as a predicate instead of a
+ nested `if` on a substring.
+- [service.ts:73-121](mcp/src/agent/service.ts#L73-L121) `invokeForRun` — see Phase 2.
+- [fast-path.ts](lib/bridge/fast-path.ts), [run-port.ts](lib/bridge/run-port.ts),
+ [socket.ts](lib/bridge/socket.ts) — the `if (!post(frame)) return Promise.resolve(failure(...))`
+ preamble repeated five times becomes one `requireLink()` combinator.
+
+Sequence: land `lib/fn.ts`, convert `lib/bridge/invoke.ts` as the pilot (it is self-contained
+and has the trickiest control flow), then sweep.
+
+## Phase 2 — collapse duplication into declarative tables
+
+Ordered by payoff.
+
+### 2a. Pending calls over the socket — 4 copies → 1 table
+
+[socket.ts:63-176](lib/bridge/socket.ts#L63-L176) holds four independent `Map`s, four timeout
+constants, four `post()` guards, four promise bodies, plus four near-identical `case` arms in
+`handle()` at lines 331-353.
+
+Replace with one registry plus a declaration table:
+
+```
+const CALLS = {
+ analyzeFile: { reply: 'fileSummary', timeoutMs: 90_000, onTimeout: '…' },
+ analyzeRecording: { reply: 'recordingWorkflow', timeoutMs: 120_000, onTimeout: '…' },
+ nameSession: { reply: 'sessionName', timeoutMs: 20_000, onTimeout: '…' },
+ saveSkill: { reply: 'skillResult', timeoutMs: 15_000, onTimeout: '…' },
+ …
+} as const satisfies Record<string, CallSpec>
+```
+
+`handle()` loses four cases in favour of one lookup keyed on `frame.t`. Net: ~115 lines → ~45,
+and adding a request/reply pair becomes one table row.
+
+### 2b. Daemon frame dispatch — 7 branches → 1 record
+
+[daemon.ts:197-246](mcp/src/daemon.ts#L197-L246) is three `void X(...).then(send).catch(send-failure)`
+blocks and four synchronous `return source.send(...)`. Same envelope every time.
+
+Replace with `Record<ExtensionRequest['t'], (req, deps) => ActionResult | Promise<ActionResult>>`
+and one `respond()` that owns the `{ t: <replyFrame>, id, result }` shaping and the catch.
+Missing keys become a compile error, which closes the documented trap that a frame absent
+from `EXTENSION_REQUEST_FRAMES` is silently dropped.
+
+Do the same for the control-op if-chain at [daemon.ts:287-327](mcp/src/daemon.ts#L287-L327).
+
+### 2c. The index + body store — 4 copies → 1 factory
+
+`CLAUDE.md` counts these out loud ("the third store on the … pattern", "the fourth index+body
+store"). All four implement: read index, read `<prefix>:<id>` body, merge-on-write, eviction
+cascade that drops the body key with the record.
+
+`lib/bridge/store.ts`:
+
+```
+createIndexedStore<Meta, Body>({ indexKey, bodyKey, caps, merge })
+ → { list, put, read, remove, subscribe }
+```
+
+Each of the four becomes ~25 lines of types + config. This also fixes the divergence risk
+`CLAUDE.md` already flags — `putSession` merges (two writers), the others replace; making
+`merge` an explicit parameter states which semantics each store chose.
+
+### 2d. Byte-budgeted sections — 2 copies → 1 pure function
+
+`filesBlock` and `recordingsBlock` in [service.ts:356-419](mcp/src/agent/service.ts#L356-L419)
+are the same accumulate-until-full loop. Extract:
+
+```
+budgetedSections<T>(items, render: (t: T) => string, { maxBytes, overflowNote }): { text?: string; dropped: number }
+```
+
+Pure, testable, and the two 30-line loops become 5-line calls. `prompt.ts`'s own 64 KB
+overlay budget is the same shape and should use it too.
+
+### 2e. The two scrubbing validators — 2 copies → 1 field-spec interpreter
+
+`validateSiteMapReport` ([lib/skills/site-map.ts](lib/skills/site-map.ts)) and
+`validateRecordingWorkflow` ([lib/recordings/workflow.ts:66-212](lib/recordings/workflow.ts#L66-L212))
+run identical discipline over different shapes: scrub every leaf, cap every leaf, drop
+members outside an allowlist, re-parse URLs against a fixed origin, collect warnings, trim to
+a byte budget.
+
+This is the most security-relevant duplication in the tree — both consume text that came off
+an attacker-controlled page. Replace the two hand-written walkers with one declarative field
+spec both describe themselves in, interpreted by a shared `lib/skills/validate.ts`. One place
+to be right, which is the stated reason `lib/skills/scrub.ts` already exists.
+
+Constraint: the result must stay import-free enough to load in a worker and bare Node.
+
+### 2f. `invokeForRun` — a guard chain → an ordered interceptor list
+
+[service.ts:73-121](mcp/src/agent/service.ts#L73-L121) interleaves five concerns in one
+procedure: emit `tool`, intercept `voicelink.saveSiteMap`, apply the mapping gate, apply the
+approval gate, invoke, emit `toolResult`. The gate *order* is load-bearing and documented
+(mapping runs deliberately bypass approval) but currently only legible by reading the
+fall-through.
+
+Restructure as an ordered array of `(ctx, next) => Promise<ActionResult>`:
+
+```
+const PIPELINE = [withTimeline, interceptSaveSiteMap, mappingGate, approvalGate, dispatchToTab]
+```
+
+The order becomes a single readable line, and each stage is independently testable.
+
+### 2g. `effects.ts` — ifs → an effect table
+
+[effects.ts:3-9](mcp/src/agent/effects.ts#L3-L9) hardcodes `page.fillInput`/`page.pressKey`
+in an if-chain. Make it a table of `{ action, effect, when }` predicates so adding an action
+that submits a form is one row, not an edit to a function two files from the registry.
+
+## Phase 3 — split the large modules
+
+Splits only; no logic changes in this phase, so the diff stays reviewable.
+
+| File | Lines | Split into |
+| --- | --- | --- |
+| [entrypoints/sidepanel/App.tsx](entrypoints/sidepanel/App.tsx) | 478 | `App.tsx` (layout), `components/app-header.tsx`, `components/composer.tsx`, `components/composer-toolbar.tsx`, `components/attachments-list.tsx`, `lib/bridge/use-composer.ts`, `lib/bridge/use-panels.ts` |
+| [mcp/src/agent/service.ts](mcp/src/agent/service.ts) | 482 | `service.ts` (AgentSession), `agent/pipeline.ts` (2f), `agent/context-blocks.ts` (2d), `agent/summarize.ts` |
+| [mcp/src/daemon.ts](mcp/src/daemon.ts) | 463 | `daemon.ts` (lifecycle), `daemon/authorize.ts`, `daemon/handlers.ts` (2b), `daemon/control.ts`, `daemon/listen.ts` |
+| [components/markdown.tsx](components/markdown.tsx) | 433 | `markdown/blocks.ts` (pure), `markdown/inline.tsx` (pure, **algorithm untouched**), `markdown.tsx` (render) |
+| [mcp/src/agent/sitemap.ts](mcp/src/agent/sitemap.ts) | 408 | `sitemap/index.ts`, `sitemap/transport.ts` (pinned lookup + streaming, untouched), `sitemap/parse.ts` (pure), `net/private-address.ts` (pure — already covered by `yarn security:check`) |
+| [lib/bridge/socket.ts](lib/bridge/socket.ts) | 382 | `socket/connection.ts` (state machine), `socket/calls.ts` (2a), `socket/frames.ts` |
+| [lib/bridge/use-run.ts](lib/bridge/use-run.ts) | 350 | `use-run.ts`, `run-reducer.ts` (pure — `reduce`/`patchTool` already are), `use-run-port.ts`, `use-session-persistence.ts` |
+| [lib/recordings/capture.ts](lib/recordings/capture.ts) | 251 | `capture/targets.ts` (pure), `capture/handlers.ts` (listener table), `capture/session.ts` (buffer) |
+
+One correctness fix rides along in `App.tsx`: `skillsOpen` / `recordingsOpen` / `historyOpen`
+are three independent booleans representing one mutually-exclusive choice. Collapse to
+`activePanel: 'skills' | 'recordings' | 'history' | null` — making the impossible states
+unrepresentable is the most declarative change available in that file.
+
+## Phase 4 — strict typing
+
+### 4a. Branded ids
+
+`RunId`, `ToolId`, `StagingId`, `ClaudeSessionId`, `SessionId`, `TabId` in
+`lib/actions/protocol.ts`. Every one of these is a bare `string`/`number` today, and
+`CLAUDE.md` documents three separate bugs that came from crossing them: `EXTERNAL_RUN_ID`
+leaking into `activeRunId`, `sessionId` vs `claudeSessionId` ownership, a `done` frame ending
+the wrong run. Brands make those compile errors.
+
+### 4b. `ActionName` as a union
+
+Derive from the registry as a `const` tuple. Then:
+
+- `invokeForHarness(action: ActionName, …)` instead of `string`.
+- `ToolName` as a mapped/template-literal type over `ActionName`, which turns half of
+ `assertToolNamesRoundTrip` into a compile-time guarantee (a name with two underscores stops
+ type-checking rather than failing at daemon startup).
+- `REPLAYABLE_ACTIONS`, `requireApproval`, `CONSEQUENTIAL`, and the mapping allowlist all
+ narrow from `string[]` to `ActionName[]`, so a renamed action breaks every list that names it.
+
+### 4c. Typed action outputs
+
+Add an output type per action and an `OutputOf<N extends ActionName>` map. This removes the
+casts in [service.ts:459-476](mcp/src/agent/service.ts#L459-L476) `summarize()` and
+[daemon.ts:56-72](mcp/src/daemon.ts#L56-L72) `persistScreenshot()`, which currently reach into
+`result.data` with four separate `as` shapes.
+
+Note the invariant `CLAUDE.md` states: `mcp/src/server.ts` `JSON.stringify`s `result.data`
+straight to an ungated MCP client. Typed outputs make "what does this action hand back"
+reviewable at the type level, which is exactly where the `fill-input.ts` read-primitive bug
+lived.
+
+### 4d. Parse the wire instead of casting it
+
+[protocol.ts:162-169](lib/actions/protocol.ts#L162-L169) `parseFrame` casts after checking
+only that `t` is a string. [daemon.ts:290](mcp/src/daemon.ts#L290) casts `ControlRequest` with
+no check at all. Replace both with a zod discriminated union — zod is already a dependency on
+both sides and already ships in the content script, so this costs nothing new.
+
+### 4e. Stop re-hand-parsing schema'd inputs
+
+The ~36 `(input as { x?: unknown })` casts exist because worker-fulfilled actions
+([invoke.ts:43-121](lib/bridge/invoke.ts#L43-L121)) re-derive their own arguments from
+`unknown`, despite the action already owning a zod schema in the registry. Parse once at the
+boundary with `action.input.safeParse`, hand typed input downstream.
+
+### 4f. tsconfig
+
+Add to both `tsconfig.json` and `mcp/tsconfig.json`:
+
+```
+"noUncheckedIndexedAccess": true,
+"exactOptionalPropertyTypes": true,
+"noImplicitReturns": true,
+"noFallthroughCasesInSwitch": true,
+"noPropertyAccessFromIndexSignature": true
+```
+
+Two will hurt, and should be sequenced last:
+
+- `noUncheckedIndexedAccess` produces heavy churn in the two parsers (`markdown.tsx`,
+ `sitemap.ts`) where index access is provably in-range. Land it after Phase 3's splits so
+ the churn is contained to the pure files.
+- `exactOptionalPropertyTypes` breaks the `= x ?? undefined` idiom used for optional fields
+ ([use-run.ts:103](lib/bridge/use-run.ts#L103) is one). Fix by making those fields
+ `| undefined` explicitly rather than optional.
+
+## Phase 5 — the pure / side-effecting boundary
+
+Declare and enforce, rather than merely intend.
+
+**Pure** (no `browser.*`, no `node:*`, no DOM, no clock, no randomness — enforced by
+`scripts/check-purity.mjs`):
+
+`lib/intent/**`, `lib/skills/**`, `lib/recordings/{events,workflow}.ts`,
+`lib/actions/{core,dispatch,manifest,registry,tool-names}.ts`, `lib/fn.ts`,
+`mcp/src/agent/{effects,prompt}.ts`, `mcp/src/agent/sitemap/parse.ts`,
+`mcp/src/net/private-address.ts`, `components/markdown/**`, `lib/bridge/{redact,run-reducer}.ts`
+
+**Effectful, and named as such** — the modules that own I/O, timers, storage and process
+spawning: `lib/bridge/{socket,run-port,recorder,invoke}.ts`, `mcp/src/{daemon,server}.ts`,
+`mcp/src/agent/{runner,service}.ts`, `lib/actions/page/*` `execute()` bodies.
+
+Two rules that fall out and are worth stating in `CLAUDE.md`:
+
+1. `Date.now()` and `crypto.randomUUID()` are effects. Where a pure function needs them today
+ (`stateOf`, `freshSession`, the recording validators), take them as parameters. This is
+ what makes the validators testable without a clock.
+2. An action's `execute()` is the *only* sanctioned place for DOM in `lib/actions/`. That is
+ already the rule; the purity check makes it mechanical.
+
+## Sequencing
+
+Each step is independently landable and gated on `yarn check` staying green.
+
+1. Phase 0 — `lib/fn.ts`, `check-purity.mjs`, the `check` script. *(no behaviour change)*
+2. Phase 1 pilot — `lib/bridge/invoke.ts` on the Result combinators.
+3. Phase 2a + 2b — socket call table, daemon handler record. *(largest line reduction)*
+4. Phase 2c — the store factory.
+5. Phase 3 splits — mechanical, one file per commit.
+6. Phase 2d–2g — the extracted-and-shared pure helpers, now that files are small.
+7. Phase 4a–4e — branded ids, `ActionName`, typed outputs, wire parsing.
+8. Phase 4f — tsconfig flags, one at a time.
+9. Phase 5 — grow the pure set until `check-purity.mjs` covers the list above.
+10. Rewrite the affected `CLAUDE.md` sections *in the same commits*, not after — the file is
+ the project's only documentation and every section above cites it.
+
+Rough size: ~2,000 lines touched, of which ~600 are net deletions from the duplication
+collapse. Phases 1–3 carry most of the value; Phase 4 carries most of the risk.
+
+## Risks
+
+| Risk | Mitigation |
+| --- | --- |
+| Manifest hash drift forces lockstep rebuilds mid-refactor | Never touch action names, `.describe()` text, or registry order. `yarn mcp:manifest` after every commit. |
+| A security control is refactored into a no-op | `yarn security:check` covers SSRF ranges, approval effects and transcript redaction. Phases 2e/2f/2g touch exactly those — add fixtures *before* refactoring, not after. |
+| Intent routing shifts under the grammar refactor | `yarn intent:check` has both-direction fixtures per rule. `lib/intent/` needs almost no work; leave it alone. |
+| `exactOptionalPropertyTypes` cascades through the wire types | Land it last, after `parseFrame` is zod-parsed so the shapes are pinned. |
+| A pure module gains an import that breaks bare Node | `check-purity.mjs` plus the existing `yarn mcp:manifest` and `yarn intent:check` already run three of them in bare Node. |
+| Splitting `markdown.tsx` perturbs the inline scanner | Move the functions verbatim in one commit; any change to `renderInline` goes in a separate, separately reviewed commit. |