feat(cockpit): tab activity registry + homepage feedback loop (PR 1/3)

[Dani Akash (DaniAkash)]

Summary

First of three PRs from the cockpit-homepage plan. Every successful browser-tool dispatch the cockpit observes is recorded against the calling agent and the targeted CDP target id; the homepage polls GET /cockpit/tabs/activity every 1500 ms and renders the live view. No takeover gate yet (PR 2), no UI redesign beyond rewiring the data hooks. Zero diffs in apps/server.

What changes

apps/agent-mcp-interface:

• lib/tab-activity/extract-page-id.ts is a pure helper that reads rawArgs.page for tools that accept it (act, diff, download, evaluate, grep, navigate, pdf, read, screenshot, snapshot, tabs, upload, wait) and rejects non-integer / non-positive values. Tools without a page (tab_groups, windows, run) yield null.
• lib/tab-activity/registry.ts is the in-memory map keyed by stable CDP targetId. recordTool writes; snapshot() reads. status is derived at read time (active within 5 s of the last tool, idle afterwards). Closed tabs are evicted lazily on the next snapshot read by checking PageManager.getInfo(pageId)?.targetId === storedTargetId (pageIds are reused, target ids are not). The registry takes an optional now clock for deterministic tests.
• lib/tab-activity/index.ts exports a process-wide singleton bound to the existing getBrowserSession accessor.
• mcp/register.ts wraps the existing executeTool call with recordSuccessfulDispatch(...). Failed dispatches and tools without a page arg are skipped. The new helper is extracted so the dispatcher function stays under biome's cognitive-complexity threshold.
• routes/tabs/index.ts exposes GET /tabs/activity returning { tabs: TabActivityRecord[] }. Mounted in server.ts so the chained AppType picks it up automatically.

apps/agent-mcp-ui:

• modules/api/tabs.hooks.ts defines useTabsActivity with react-query-kit, polling every 1500 ms via the existing hono-rpc client.
• screens/cockpit/cockpit.helpers.ts derives per-slug colours, parses the site from the URL, formats relative time, and maps TabActivityRecord[] to AgentRow[] (active records, status=running) and ActivityRow[] (idle records, status=done).
• screens/cockpit/cockpit.data.ts is the new aggregator hook. The homepage screen calls it and nothing else.
• Cockpit.tsx drops the mocked useAgents / useRecentActivity calls and consumes useCockpitData() instead. Approvals + handoffs stay on their mocks until later PRs supply them.

Server-side guarantees

$ git diff origin/feat/agent-mcp-interface-bootstrap...HEAD --name-only | grep '^packages/browseros-agent/apps/server' | wc -l
0

No edits to apps/server/src/tools/browser/framework.ts, no edits to executeTool, no edits to BROWSER_TOOLS. The cockpit reads PageManager via the shared BrowserSession singleton it already owns.

Test plan

• Unit tests for extractPageId (8 cases): every tool with a page, every tool without, missing / non-integer / non-object args.
• Unit tests for TabActivityRegistry (9 cases): record + snapshot, dedup-by-targetId, status timing with injectable clock, eviction on pageId reuse + outright deletion, no-session no-op, multi-tab independence, sort by lastToolAt desc, last-write-wins on shared target.
• Integration test for /tabs/activity route: empty-state shape + populated shape after recording.
• Unit tests for cockpit helpers (10 cases): site parsing, relative-time formatter (seconds / minutes / hours / days), colour determinism, AgentRow / ActivityRow mappers filtering by status.
• All 120 existing apps/agent-mcp-interface tests still pass.
• bunx tsc --noEmit clean in both packages.
• bunx biome ci clean.

Manual walk-through against a live BrowserOS (reviewer action):

1. Start apps/server against a running BrowserOS browser (CDP up).
2. Open the agent-mcp-ui at the cockpit homepage. Confirm RunningGrid is empty.
3. From a terminal, tools/call navigate { page: 1, url: 'https://example.com' } against /cockpit/mcp/<slug> for any agent profile.
4. curl http://127.0.0.1:9100/cockpit/tabs/activity should now show a record with agentId, slug, targetId, pageId: 1, url: 'https://example.com/', title: 'Example Domain', lastToolName: 'navigate', status: 'active'.
5. The homepage's RunningGrid should show one card within 2 seconds, labelled with the slug.
6. Wait 5 seconds without making another tool call. The card moves to RecentActivity with status done and a relative-time chip.
7. Close the corresponding browser tab. The record disappears from /tabs/activity on the next read (caught by the eviction-on-read pass).
8. Make a failed tool call (navigate { page: 999, url: '...' }). No new record appears, the previous record's lastToolAt does NOT advance.

Follow-ups (PR 2 and PR 3)

• PR 2 adds a TakeoverRegistry, POST /cockpit/tabs/:targetId/takeover + /release, and an MCP-error gate in the same wrapper.
• PR 3 surfaces "Take over" / "Resume agent" buttons in the UI and a "User driving" section in WaitingStrip.

[github-actions]

✅ Tests passed — 1393/1397

Suite	Passed	Failed	Skipped
✅ agent	271/271	0	0
✅ build	26/26	0	0
✅ eval	91/91	0	0
✅ server-agent	301/301	0	0
✅ server-api	138/138	0	0
✅ server-browser	10/10	0	0
✅ server-integration	10/10	0	0
✅ server-lib	251/252	0	1
✅ server-root	47/50	0	3
✅ server-tools	248/248	0	0

View workflow run

[greptile-apps]

Greptile Summary

This PR introduces a tab-activity registry for the BrowserOS cockpit: an in-memory map keyed by stable CDP targetId that records every successful browser-tool dispatch, a GET /tabs/activity route that publishes a live snapshot, and a polling hook + helper layer in the UI that drives RunningGrid (active tabs) and RecentActivity (idle tabs) from real data instead of mocks.

• lib/tab-activity/ — extractPageId validates tool args, registry.ts handles last-write-wins recording, lazy eviction via PageManager targetId comparison, and injectable clock for deterministic tests.
• mcp/register.ts — wraps executeTool results; only records on success and only when a valid pageId is present; failed dispatches are cleanly skipped.
• UI layer — useCockpitData() aggregates the tabs query with still-mocked approvals/handoffs; cockpit.helpers.ts maps records to AgentRow/ActivityRow using a slug-hashed colour palette and a simple relative-time formatter.

Confidence Score: 4/5

Safe to merge — zero changes to apps/server, no schema/migration impact, and all new behaviour is additive behind a polling endpoint the UI was already scaffolded for.

The registry logic, eviction strategy, and route wiring are all correct and well-tested. The main concerns are non-blocking: the route-test cleanup leaves the internal Map unpurged (the comment says "evict by detaching the session" but no eviction actually occurs), the CockpitData isPending flag only tracks the tabs query so it could mislead a future loading-gate, and the hardcoded harness value is a known PR-1 simplification that risks being forgotten across the three-PR arc.

routes.test.ts deserves a second look on the cleanup strategy; cockpit.data.ts and cockpit.helpers.ts have the minor gaps noted above.

Important Files Changed

Filename	Overview
packages/browseros-agent/apps/agent-mcp-interface/src/lib/tab-activity/registry.ts	New in-memory registry keyed by CDP targetId; lazy eviction on snapshot read; injectable clock for tests. Logic and eviction approach are sound.
packages/browseros-agent/apps/agent-mcp-interface/src/mcp/register.ts	Adds recordSuccessfulDispatch helper called after non-error executeTool results; failed dispatches and page-less tools are correctly skipped.
packages/browseros-agent/apps/agent-mcp-interface/tests/routes/tabs/routes.test.ts	Route integration test; cleanup via setBrowserSession(null) does NOT clear the internal records Map — the comment claiming eviction is inaccurate, leaving potential state leakage for future test cases.
packages/browseros-agent/apps/agent-mcp-ui/screens/cockpit/cockpit.data.ts	Aggregation hook; isPending only reflects the tabs query, ignoring approvals/handoffs loading state.
packages/browseros-agent/apps/agent-mcp-ui/screens/cockpit/cockpit.helpers.ts	Helper functions for color, site parsing, relative time, and row mapping; harness field is hardcoded to 'Claude Code'.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Agent as Agent (MCP Client)
    participant Register as mcp/register.ts
    participant Registry as TabActivityRegistry
    participant PageMgr as PageManager
    participant Route as GET /tabs/activity
    participant UI as Cockpit UI (1500ms poll)

    Agent->>Register: "tool call (e.g. navigate {page:1, url:...})"
    Register->>Register: executeTool(...)
    Register->>Register: extractPageId(toolName, rawArgs)
    alt "pageId is valid & result.isError === false"
        Register->>PageMgr: "getInfo(pageId) → live {targetId, url, title}"
        Register->>Registry: "recordTool({agentId, slug, pageId, targetId, toolName})"
        Registry->>Registry: records.set(targetId, RawRecord)
    end
    UI->>Route: GET /cockpit/tabs/activity
    Route->>Registry: snapshot()
    Registry->>PageMgr: getInfo(pageId) per record
    alt pageId still maps to same targetId
        Registry-->>Route: "TabActivityRecord (status = active|idle)"
    else tab closed / pageId reused
        Registry->>Registry: records.delete(targetId)
    end
    Route-->>UI: "{ tabs: TabActivityRecord[] }"
    UI->>UI: tabsToAgentRows (active → RunningGrid)
    UI->>UI: tabsToActivityRows (idle → RecentActivity)

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Agent as Agent (MCP Client)
    participant Register as mcp/register.ts
    participant Registry as TabActivityRegistry
    participant PageMgr as PageManager
    participant Route as GET /tabs/activity
    participant UI as Cockpit UI (1500ms poll)

    Agent->>Register: "tool call (e.g. navigate {page:1, url:...})"
    Register->>Register: executeTool(...)
    Register->>Register: extractPageId(toolName, rawArgs)
    alt "pageId is valid & result.isError === false"
        Register->>PageMgr: "getInfo(pageId) → live {targetId, url, title}"
        Register->>Registry: "recordTool({agentId, slug, pageId, targetId, toolName})"
        Registry->>Registry: records.set(targetId, RawRecord)
    end
    UI->>Route: GET /cockpit/tabs/activity
    Route->>Registry: snapshot()
    Registry->>PageMgr: getInfo(pageId) per record
    alt pageId still maps to same targetId
        Registry-->>Route: "TabActivityRecord (status = active|idle)"
    else tab closed / pageId reused
        Registry->>Registry: records.delete(targetId)
    end
    Route-->>UI: "{ tabs: TabActivityRecord[] }"
    UI->>UI: tabsToAgentRows (active → RunningGrid)
    UI->>UI: tabsToActivityRows (idle → RecentActivity)

Loading

Prompt To Fix All With AI

Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 3
packages/browseros-agent/apps/agent-mcp-interface/tests/routes/tabs/routes.test.ts:24-29
**Misleading cleanup comment + fragile registry isolation**

`setBrowserSession(null)` causes `snapshot()` to short-circuit with `return []`, but it does **not** clear the internal `records` Map. The comment "we evict by detaching the session" is inaccurate — no eviction happens; the entries simply stay in the Map unread. If a future test records a `targetId` that doesn't collide with an existing key AND that same `targetId`/`pageId` pair happens to be resolvable in a subsequent test's session stub, the stale record would surface in `snapshot()`. Adding a `clear(): void` method to `TabActivityRegistry` (next to the existing test-only `size()`) and calling it here would make the isolation explicit and safe.

### Issue 2 of 3
packages/browseros-agent/apps/agent-mcp-ui/screens/cockpit/cockpit.data.ts:42
**`isPending` only reflects the tabs query**

`isPending: tabs.isPending` ignores `approvals.isPending` and `handoffs.isPending`. Any caller that gates a loading spinner on `CockpitData.isPending` would treat the page as fully loaded while approvals/handoffs are still resolving, which could cause a brief flash of empty sections. Consider `isPending: tabs.isPending || approvals.isPending || handoffs.isPending` (or, since approvals/handoffs are currently mocked and resolve synchronously, at least document why the narrower scope is intentional).

### Issue 3 of 3
packages/browseros-agent/apps/agent-mcp-ui/screens/cockpit/cockpit.helpers.ts:58
**`harness` hardcoded to `'Claude Code'`**

Every `AgentRow` gets `harness: 'Claude Code'` regardless of the agent's actual harness, since `TabActivityRecord` doesn't carry that field. If the cockpit ever surfaces agents running under a different harness, the displayed value will silently be wrong. The PR description acknowledges this is a PR-1 simplification; it would be worth a `// TODO(PR-3): derive from agent profile` comment here so the debt stays visible and isn't forgotten across the three-PR arc.

_{Reviews (1): Last reviewed commit: "feat(agent-mcp-ui): drive cockpit homepa..." | Re-trigger Greptile}