fix(extension): split debugger automation build

[steipete]

Summary

• move userScripts from required to optional permissions and request it only from the explicit Options action
• omit debugger from the standard summary/Web Store build and hide debugger-backed tools there
• add build:automation / dev:automation for the full agentic build, where Chrome requires debugger at install time
• document the permission purposes and add manifest, capability, fresh-install, Options, and direct-summary regression coverage

Security review notes

Chrome explicitly does not allow debugger to be declared optional. The standard build therefore has no debugger declaration or grant. The separate automation build declares it as required only for native click/type/key input and the explicit debugger tool; debugger-backed commands attach for the command and detach afterward.

userScripts remains optional in both builds. It is requested only after the user clicks Enable automation permissions, and is used for user-requested browserjs() / REPL execution in the page main world. Summarization, chat, and browser media do not need either capability.

Validation

• pnpm test — 2,944 passed, 43 skipped
• pnpm lint
• pnpm typecheck
• pnpm format:check
• Chrome summary, Chrome automation, and Firefox production builds
• Chromium fresh-install, manifest, Options, and direct-provider summary/chat tests
• structured autoreview: clean, no accepted/actionable findings

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 8, 2026, 2:14 AM ET / 06:14 UTC.

Summary
The branch moves Chrome userScripts access to optional permission requests, removes debugger from standard Chrome builds, adds debugger-enabled automation build scripts, gates debugger-backed tools by manifest capability, and updates extension docs/tests.

Reproducibility: not applicable. as a bug reproduction: this PR changes the extension permission and build model rather than reporting a current-main failure. The source diff and added tests give a high-confidence review path for the changed behavior.

Review metrics: 2 noteworthy metrics.

• Changed surface: 17 files, +190/-79. The diff spans manifest generation, package scripts, runtime tool gating, Options UI, docs, and tests, so release packaging is the key review concern.
• Build modes added: 2 scripts added. build:automation and dev:automation introduce a second Chrome artifact path that maintainers need to account for before release.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• none.

Risk before merge

• [P1] Merging intentionally removes debugger-backed automation from the standard Chrome build and moves it to a separate artifact, so existing automation users can lose that capability unless the release/distribution path makes the automation build explicit.

Maintainer options:

1. Confirm the artifact split before merge (recommended)
   Verify pnpm -C apps/chrome-extension build is the Web Store package path and build:automation is only the intended debugger-enabled automation artifact.
2. Accept the compatibility tradeoff
   Merge once maintainers agree that standard-build users should lose debugger-backed automation unless they install the automation build.
3. Pause the split
   Keep the PR open or close it if the project is not ready to maintain separate standard and automation Chrome builds.

Next step before merge

• [P2] This OWNER-authored draft has no narrow automated repair from this review; it needs maintainer release acceptance of the two Chrome build artifacts.

Maintainer decision needed

• Question: Should the next Chrome extension release ship the standard Web Store artifact without debugger while supporting debugger-backed automation only through the separate automation build?
• Rationale: The code and tests support the split, but accepting the changed install-time permission contract and maintaining two Chrome artifact paths is a release/product decision that tests cannot settle.
• Likely owner: steipete — steipete is both the PR author and the clearest recent owner for the affected extension automation and release-sensitive manifest paths.
• Options:
  • Accept the split (recommended): Ship the standard build without debugger and direct users who need native input or the debugger tool to the explicit automation build.
  • Verify packaging first: Keep the PR open until the exact Web Store and automation artifacts are produced and checked against the new build scripts.
  • Preserve one build: Do not merge this split and keep debugger-backed automation in the standard Chrome build despite the broader install-time permission.

Security
Cleared: No concrete security or supply-chain regression was found; the diff narrows standard-build permissions, isolates debugger access to an explicit automation build, and adds no dependency-source changes.

Review details

Best possible solution:

Ship the least-privilege standard Chrome/Web Store build only after maintainers confirm the debugger-enabled automation artifact is packaged, documented, and distributed through the intended non-Web-Store path.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction: this PR changes the extension permission and build model rather than reporting a current-main failure. The source diff and added tests give a high-confidence review path for the changed behavior.

Is this the best way to solve the issue?

Yes for the implementation shape, pending maintainer acceptance of the release tradeoff. A separate automation build is a maintainable way to remove debugger from the Web Store build while preserving a debugger-capable variant.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 206a6f844764.

Label changes

Label justifications:

• P2: This is a normal-priority extension permission and packaging improvement with bounded but real user-facing automation impact.
• merge-risk: 🚨 compatibility: The PR intentionally removes debugger-backed automation from the standard Chrome build and relies on a separate automation build for that capability.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply to this OWNER-authored draft PR; the PR body nevertheless lists Chrome summary, Chrome automation, Firefox production builds, browser regression checks, and test/lint/typecheck/format validation.

Evidence reviewed

What I checked:

• AGENTS.md policy read: Repository policy was read fully and applied: the checkout stayed read-only, Chrome extension release artifacts are release-sensitive, and extension build/test guidance was considered. (AGENTS.md:1, 206a6f844764)
• PR metadata and previous review: GitHub reports this PR is open, draft, mergeable, OWNER-authored, and the prior ClawSweeper review at the earlier head had no findings; the current head adds one test-only follow-up commit. (0eca56094279)
• Changed surface: The PR changes 17 files with 190 additions and 79 deletions across manifest generation, package scripts, Options UI, docs, and tests. (0eca56094279)
• Manifest split: The PR makes Chrome debugger conditional on SUMMARIZE_EXTENSION_DEBUGGER=1 and keeps Chrome userScripts in optional_permissions alongside nativeMessaging. (apps/chrome-extension/wxt.config.ts:102, 0eca56094279)
• Options permission request: The Options controller now derives automation permission requests from the current build manifest's optional permissions and only requests declared optional automation permissions. (apps/chrome-extension/src/entrypoints/options/support.ts:85, 0eca56094279)
• Debugger tool gating: Automation and direct-provider tool lists filter out debugger unless the built manifest actually includes the debugger permission. (apps/chrome-extension/src/automation/tools.ts:27, 0eca56094279)

Likely related people:

• steipete: The PR is OWNER-authored, and local blame/log history for the extension manifest, automation tool list, direct tool advertisement, and Options permission controller points to recent work by Peter Steinberger on the same extension automation surface. (role: feature owner and recent area contributor; confidence: high; commits: 288bec056698, 0fd135be7ed9, 0eca56094279; files: apps/chrome-extension/wxt.config.ts, apps/chrome-extension/src/automation/tools.ts, apps/chrome-extension/src/lib/direct-prompts.ts)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (1 earlier review cycle)

• reviewed 2026-07-08T04:04:45.116Z sha 0fd135b :: needs maintainer review before merge. :: none