Release 0.21.3 — concurrent per-agent tab groups

[ronaldeddings]

Summary

Prepares Interceptor 0.21.3 and closes #124: concurrent per-agent tab groups. Multiple AI agents can drive the same browser context at the same time, each penned into its own named, colored tab group — no cross-agent tab grabs, no shared-target clobbering, atomic per-job cleanup.

What Changed

Named per-agent groups (extension)

• Registry of label → groupId in chrome.storage.session, lifetime-matched to Chrome's session-scoped group ids; exact-title rediscovery (never pattern-matched query({title})).
• Group creation serialized per label — N concurrent opens for one label join a single group instead of minting N duplicates.
• Per-group auto-target keys (activeTabId:<label>). Grouped resolution never falls back to the browser-active tab; the ownership gate runs before the auto-target persists, and stored targets are membership-validated (self-healing).
• group_list / group_close actions — close is one atomic tabs.remove over exactly that group's ids; a tabGroups.onRemoved listener keeps the registry honest when a human closes a group by hand.
• Brand retitles (interceptor brand tab-group) propagate to named groups (<brand>-<label>).
• Monitor: child tabs inherit their opener's group; auto-attach accepts any managed group.
• Graceful degradation where tabGroups is unavailable (MV2 Electron bridge, Firefox).

CLI

• Global --group <label> / --group-color <color> flags with INTERCEPTOR_GROUP env fallback (flag wins), injected at the transport choke point so simple, compound, and looping paths are all scoped.
• New interceptor group list / interceptor group close <label>.

Docs

• ARCHITECTURE.md named-groups section; interceptor-browser agent skill updated with multi-agent scoping guidance.

Testing

• 19 new unit + source-assertion tests (626 total, 0 fail).
• Live: two-agent isolation, cross-group rejection, group-scoped --reuse, staggered teardown.
• Stress: 100 tabs / 10 groups / 3 browser contexts (two Chromium profiles + Firefox) opened, scrolled, and torn down fully concurrently — 100/100 opens, 100/100 scrolls, zero duplicate groups, zero cross-group bleed.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added named tab groups for isolating browser actions per session.
  • Introduced commands to list groups, close a group, and open tabs/windows into a specific group.
  • Added support for choosing a group color when creating a group.

• Bug Fixes

  • Improved tab targeting so actions stay within the correct group.
  • Made child tabs inherit their parent’s group more reliably.
  • Updated group handling to survive restarts more consistently.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 63b65974-9e73-4c0c-ae0e-5d1eeba2e75d

📥 Commits

Reviewing files that changed from the base of the PR and between c4f9542 and 86b86ea.

📒 Files selected for processing (22)

• .agents/skills/interceptor-browser/SKILL.md
• .agents/skills/interceptor-browser/references/command-catalog.md
• ARCHITECTURE.md
• cli/commands/group.ts
• cli/global-flags.ts
• cli/help.ts
• cli/index.ts
• cli/parse.ts
• cli/transport.ts
• extension/dist-mv2/background-electron.js
• extension/dist-mv2/manifest.json
• extension/manifest.json
• extension/src/background/brand-tab-group.ts
• extension/src/background/capabilities/monitor.ts
• extension/src/background/capabilities/tabs.ts
• extension/src/background/capabilities/windows.ts
• extension/src/background/message-dispatch.ts
• extension/src/background/no-tab-actions.ts
• extension/src/background/router.ts
• extension/src/background/tab-group.ts
• package.json
• test/tab-groups.test.ts

---

📝 Walkthrough

Walkthrough

This PR introduces concurrent, named per-agent tab groups within a single browser context. CLI adds --group/--group-color flags and a group list/group close command, propagated through transport. The extension maintains a persisted label→groupId registry, scoping tab creation/reuse, window creation, monitor attachment, focus-follow, and message-dispatch active-tab resolution to named groups instead of a single interceptor group. Documentation and tests are updated accordingly; versions bumped to 0.21.3.

Changes

Named per-agent tab groups

Layer / File(s)	Summary
CLI flag parsing and group commands cli/parse.ts, cli/global-flags.ts, cli/commands/group.ts, cli/index.ts, cli/help.ts	Adds GROUP_LABEL_RE/GROUP_COLORS validation, parseGroupFlag/parseGroupColorFlag, flag filtering, and parseGroupCommand for group list/group close, wired into CLI dispatch and help text.
Transport propagation cli/transport.ts	setGlobalGroup stores group/color state; withGroup injects it into sendCommand/sendCommandWs payloads.
Extension named group registry extension/src/background/tab-group.ts, extension/src/background/brand-tab-group.ts	Persisted namedGroups registry with hydration, label validation, color/title derivation, serialized creation, membership checks, brand retitling, and cleanup on removal.
Group-scoped tab/window handling extension/src/background/capabilities/tabs.ts, extension/src/background/capabilities/windows.ts, extension/src/background/router.ts, extension/src/background/no-tab-actions.ts	tab_create/tab_close/tab_list scoped to groups; group_list/group_close actions added; window_create assigns first tab to a named group.
Monitor and focus-follow group awareness extension/src/background/capabilities/monitor.ts	adoptChildTab inherits opener group; focus-follow and monitor resolution check any managed group or a specific named group.
Dispatch gating extension/src/background/message-dispatch.ts	Group-scoped active-tab storage keys, membership validation, and post-gate persistence replace single ungrouped active-tab logic.
Compiled bundle and versions extension/dist-mv2/background-electron.js, extension/dist-mv2/manifest.json, extension/manifest.json, package.json	Bundle mirrors source changes; versions bumped to 0.21.3.
Docs and tests .agents/skills/interceptor-browser/SKILL.md, .agents/skills/interceptor-browser/references/command-catalog.md, ARCHITECTURE.md, test/tab-groups.test.ts	Documents multi-agent group scoping; adds tests for label validation, serialization, CLI flag stripping, and dispatch/routing wiring.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Agent
  participant CLI as CLI (cli/index.ts)
  participant Transport as cli/transport.ts
  participant Dispatch as message-dispatch.ts
  participant TabGroup as tab-group.ts
  participant Tabs as chrome.tabs/tabGroups

  Agent->>CLI: interceptor open url --group ai134
  CLI->>Transport: setGlobalGroup, sendCommand(action)
  Transport->>Dispatch: action with group=ai134
  Dispatch->>TabGroup: ensureNamedGroup(ai134)
  TabGroup->>Tabs: create/query group, persist registry
  Tabs-->>TabGroup: groupId
  Dispatch->>Tabs: resolve/create tab within group
  Dispatch->>Dispatch: setActiveTabId(tabId, ai134)
  Dispatch-->>Agent: result with tabId, group

Loading

Possibly related PRs

• Hacker-Valley-Media/Interceptor#31: Overlaps in monitor focus-follow/attachment code that this PR further scopes to managed/named groups.
• Hacker-Valley-Media/Interceptor#65: Both modify persisted active-tab targeting logic in extension background dispatch, one via per-group keys and the other via session-persisted active tab state.
• Hacker-Valley-Media/Interceptor#118: Both change tab-group identity logic driven by brand/title/color in brand-tab-group.ts, extended here to named per-agent groups.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch release/0.21.3-tab-groups

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}