(WIP) feat: subagent & workflow observability — Agents panel

[t3dotgg]

Subagent & workflow observability: Agents panel

Live visibility into delegated work — Claude Code subagents and workflows, and Codex v2 collab agents — directly in the thread UI: who is running, what they're doing right now, token burn, elapsed time, and result summaries.

Plans (reviewed by Fable + gpt-5.6-sol, rev 3): docs/project/plans/subagent-observability-spec.html · docs/project/plans/subagent-observability-ui.html

Design in one paragraph

No new pipeline. Adapters normalize provider signals into the existing task.* runtime-event family (extended with typed usage and agent-linkage fields); an in-memory reducer in ProviderRuntimeIngestion folds them into one ThreadAgentSnapshot per agent and, on material transitions only, appends the full roster as a single agent.snapshot activity through the existing thread.activity.append command. The client derives panel state latest-wins from the newest such activity — the same pattern the context-window meter already uses. No new WS event types, subscriptions, projection tables, or capability flags; old clients decode the new activity kind as a benign info row.

What's included

• contracts: ThreadAgentSnapshot (identity + activations model: Codex agents are resumable, so idle ≠ completed; activationCount, firstStartedAt/lastActivityAt), agent.snapshot payload schema, task.updated runtime event, typed RuntimeTaskUsage, agent-linkage fields (incl. workflow phases, scriptPath, runId, outputFile) with a timelineBypass marker.
• ClaudeAdapter: carries previously-dropped fields (subagent_type, tool_use_id, workflow_name, prompt, output_file); handles task_updated (was: unknown-subtype warning); schema-guarded parse of the undeclared workflow_progress into per-workflow-agent child task events (label, phase, model, state, tokens, attempt); captures WorkflowOutput.scriptPath/runId from tool results.
• CodexSessionRuntime/CodexAdapter (probe-gated slice): learns v2 collab children from subAgentActivity items (a live wire probe on codex-cli 0.144.1 confirmed children emit no thread/started; nicknames come from agentPath), diverts their auto-subscribed notifications into synthetic collab/agentActivity events, and maps them to timeline-bypassing task.* events. turn/completed → idle (resumable), waitingOnApproval → waiting, per-child token breakdowns from thread/tokenUsage/updated.
• Ingestion reducer: material-transition filter (status/name/model/phase/activity changes, 25k-token usage steps — 1s ticks stay in memory), hydration from the latest persisted snapshot on restart, orphan sweep to stopped on session exit, 50-cap settled retention, dispatch counter.
• Web: new agents right-panel surface (tab, "+" menu, empty-state card) with grouped cards — workflow phase headers (✓ done / running counts / pending), status dots in the existing pill color language, self-ticking elapsed timers (no React commits), token counters (deliberately not bars — burn has no denominator), expandable recent-activity feed, "{} script" affordance; plus a collapsed live strip above the composer that opens the panel. Shared derivation helpers live in client-runtime for mobile reuse.

Verification

• Focused vitest: 152 tests across ClaudeAdapter, ProviderRuntimeIngestion (reducer: material filtering, latest-wins roster, orphan sweep, activation counts, retention), CodexAdapter (collab mapping), CodexSessionRuntime — all passing.
• tsgo --noEmit clean for contracts, client-runtime, server, web; vp lint clean on changed files.
• Integrated web verification: isolated vp run dev environment, paired browser, real Claude subagent spawn — panel, live strip, settled card, and empty state confirmed (screenshots in PR comments if useful).
• Codex v2 protocol behavior established by a live app-server wire probe (/tmp/codex-v2-probe/report.md) rather than source-reading alone.

Deliberately out of scope (per plan)

Per-agent stop/steer (needs provider command plumbing), full transcript drill-in RPC (phase 2; outputFile is already captured), ACP providers (no wire signal), cost USD attribution, mobile surfaces (derivation helpers are shared and ready).

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches core provider runtime ingestion and transcript projection (timeline bypass, revert cache invalidation); behavior is heavily tested but wrong roster or hydration logic could misrepresent agent state across restarts and session boundaries.

Overview
Adds live subagent and workflow observability by folding provider task.* signals into per-thread agent rosters and persisting them as agent.snapshot thread activities (latest-wins by revision), without new wire types or projections.

Server: New contracts (ThreadAgentSnapshot, task.updated, typed RuntimeTaskUsage, timelineBypass). ClaudeAdapter maps task_updated, workflow progress, and normalized usage; Codex diverts v2 collab child notifications to collab/agentActivity → bypassing task.* events. ProviderRuntimeIngestion runs foldTaskAgentEvent / pruneSettledAgents, appends snapshots on material changes, hydrates from persisted activities on restart, orphans agents on session exit, and clears roster cache on checkpoint revert. task.updated and bypass events no longer create timeline rows; work logs skip agent.snapshot.

Client: Shared deriveLatestAgentSnapshot / panel grouping in client-runtime. Web adds an Agents right-panel tab, AgentsPanel (phases, timers, tokens, activity feed), and AgentsLiveStrip above the composer when agents are live.

^{Reviewed by Cursor Bugbot for commit a40376b. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add Agents panel with live subagent and workflow observability to the chat right panel

• Introduces an agent.snapshot activity kind that carries a roster of ThreadAgentSnapshot records, persisted by the ingestion layer and decoded client-side via deriveLatestAgentSnapshot in threadAgents.ts.
• Adds AgentsPanel.tsx with grouped workflow/phase/agent cards, live elapsed timers, usage counters, expandable activity feeds, and a footer summary; accessible as a new agents right panel surface.
• Adds AgentsLiveStrip.tsx, a one-line strip shown above the composer when agents are pending/running/waiting, with a button to open the Agents panel.
• The Claude adapter (ClaudeAdapter.ts) and Codex adapter (CodexAdapter.ts) now emit structured task.* events with agent linkage, normalized usage, and workflow phase data; child collab threads are synthesized as collab/agentActivity notifications and kept off the parent timeline.
• ProviderRuntimeIngestion.ts folds task events into per-thread agent rosters via foldTaskAgentEvent, appends agent.snapshot activities on material changes or activity pressure, marks non-terminal agents stopped on session exit, and rehydrates from the latest persisted snapshot across restarts.
• Behavioral Change: agent.snapshot activities and task.updated events are suppressed from the normal thread timeline; RIGHT_PANEL_STORAGE_VERSION is bumped from 7 to 8, clearing any persisted panel layout.

^{Macroscope summarized a40376b.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: cfd75ce4-617a-4fba-8d04-2b30ff0fb5e5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/subagent-workflow-sidebar

---

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

[t3dotgg]

Integrated verification note: in the browser run (isolated dev env, real Claude subagent), the settled card briefly showed Σ 0 tok — usage for very short agents arrives only on the terminal task_notification, and the final roster snapshot (verified in SQLite: totalTokens 22798) updates the panel when it lands. Screenshots live at /tmp/codex-computer-use.lvQ4hP/ locally; FILE_HOST_TOKEN was unset in this session so they aren't embedded here.

[macroscopeapp]

Approvability

Verdict: Needs human review

This WIP PR introduces a substantial new feature (Agents panel for subagent/workflow observability) with significant new server-side logic, client state management, and UI components. Additionally, there's an unresolved high-severity bug identified in the activity change detection logic.

^{You can customize Macroscope's approvability policy. Learn more.}

[t3dotgg]

Addressed the review handoff (all four P1s + six P2s) in 0dd586c:

P1

• Workflow agent identity: keyed on stable row index (<workflowTaskId>:wf:<index>) instead of per-attempt agentId — queued/blocked/pre-spawn-error rows now surface, retries update one card.
• Snapshot ordering: agent.snapshot payloads carry a monotonic per-thread revision (seeded from the hydrated snapshot); the client selects the highest revision instead of trusting list position.
• Codex turn status: turn/completed now decodes turn.status — failed→failed (with error message), interrupted→stopped, completed→idle.
• Hydration cost: roster hydration is lazy — only agent-touching events (task.* / session.exited) trigger it, so message deltas never cause a full thread-detail load.

P2: reducer re-derives kind from event data (order-independent), reactivation counts any settled→active transition, workflow containers excluded from worker counts / usage not double-counted, settled cards lead with error/result over stale activity, newest agents array is authoritative on decode failure (no stale-roster resurrection), idle agents exempt from the terminal retention pool, Codex usage consistently uses the cumulative total breakdown.

160 focused tests passing (new regression coverage for the identity, revision, decode-authority, and retention behaviors); typecheck clean across contracts/client-runtime/server/web.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a40376b. Configure here.}

[cursor]

Truncation breaks activity change detection

High Severity

The activityChanged check incorrectly compares the raw summary with the previously truncated currentActivity. This leads to false positives for activity changes when summaries are long, resulting in duplicate recentActivity entries and excessive agent.snapshot appends.

 

^{Reviewed by Cursor Bugbot for commit a40376b. Configure here.}