feat(subagents): live child context window in subagent status

[sambitcreate]

Summary

While a child agent runs, the subagents panel now shows how full its context window is.

• Each active roster row gets a gauge icon and a percentage. The percentage is also part of the row's accessible name.
• The detail pane adds Context window: 84K / 200K tokens (42%).
• Both switch to the warning tone at 80% or more.

Source: pi-subagents #2448. This reuses the #187 context meter's formatContextTokenCount and its 80% "approaching" threshold.

Design

• Figure. tokens is the child's latest provider-reported usage total, the same number Pi treats as a response's context size. window is the child model's contextWindow. Nothing is published when the window is unknown or the provider reported nothing.

• Side channel, not a snapshot field. Readings go out on a new chat:subagent-context notification, for these reasons:

  • Snapshot parsers use exact key sets, so older builds would reject a new field.
  • History and detail reads are gated on revision monotonicity and exact replay.
  • Durable writes are capped per run.
  • The Remote roster would churn on every child response.

  With the side channel, the snapshot, the revision and the durable writes all stay the same.

Changes

• Main
  • SubagentEventProjector accepts contextWindow and onContextUsage, and publishes on each usage() call. It skips finished runs, and an observer that throws cannot break the run.
  • llm-client sends the readings through sendGeneration on chat:subagent-context. That channel is allowlisted in the preload.
• Shared. New renderer/shared/subagent-context-usage.ts with the types, strict parsers (safe run ids) and labels.
• Renderer
  • New renderer/lib/subagent-context-usage-store.ts: a bounded LRU (32 chats × 64 runs) exposed through a useSyncExternalStore hook.
  • Readings show only for runs that are still active.
  • The roster and the detail pane render them using existing tokens (tertiary text, text-support-warning) and no borders.
• Remote / iOS / Android. Unchanged. The Remote roster reads persisted snapshots, so mobile support is left as a follow-up (see below).
• Docs. Plan docs/plans/subagent-live-context-window-plan.md and its row in the plan index, .memory/subagent-live-context-window.md, and papercuts.

Tests

• main/services/subagents/subagent-event-projector.test.ts (39 pass). Readings follow the latest response, including after the context shrinks. A zero report is skipped. The snapshot gains no field and no extra durable writes happen. Nothing is published after the run finishes or when there is no window. A throwing observer is isolated.
• New renderer/lib/subagent-context-usage-store.test.ts: report conversion, labels and threshold, parser rejection, store reference stability and change notification, LRU eviction, and active-run gating.
• renderer/components/subagents-panel.test.tsx: the roster renders the percentage and spoken label on active rows, with the warning at 85% and nothing on done rows. The detail line renders when a reading exists.
• New test file registered in test, test:subagents, test:coverage and scripts/ci-test-registry.json.
• Local runs: npm run type-check, npm run lint, npm run test:subagents (all pass), npm run test:ci:registry, main/handlers/ipc-contract.test.ts.

Follow-ups

• Live context on Remote, iOS and Android. This needs a Remote side-channel event and a contract revision.
• Show readings in the message-list subagent chips.
• The percentage is of the full window, not the usable input budget (window minus reserved output).
• Readings sent before any subagents panel mounts in the window are not replayed.

🤖 Generated with Claude Code

[pullfrog]

ℹ️ Minor project-memory gap; no runtime issues found.

Reviewed changes I reviewed the commit adding live child context reporting to the desktop subagents panel.

• Usage transport. Child response usage is sent on the new non-durable chat:subagent-context notification, leaving snapshots and durable writes unchanged.
• Desktop display. A bounded renderer store filters to active runs; the roster and detail pane display the percentage and token counts with the 80% warning tone.
• Coverage and plan. Projector, parser, store, and rendering tests cover the new behavior, and the test registry and implementation plan are updated.
• Client scope. Remote, iOS, and Android remain unchanged, with live support documented as a follow-up.

ℹ️ The project-memory note is missing

The PR description claims .memory/subagent-live-context-window.md is included, but the file is absent from the branch diff and tracked tree. This leaves the implementation decisions and follow-ups out of the project memory required for changes of this kind.

Technical details

````markdown

Missing project-memory note

Affected sites

• .memory/subagent-live-context-window.md — referenced in the PR description but absent from the branch.

Required outcome

• Add and commit a project-memory note covering the side-channel design and the documented follow-ups.
  ````

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using GPT Luna ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes I re-reviewed the delta since the prior pullfrog review (b254047): one commit, adding the project-memory note that review requested. No runtime code changed — git diff b254047..9516678 touches only the new .md file.

• Added .memory/subagent-live-context-window.md. The note records the side-channel design, publish conditions, the 32 × 64 renderer bound, the 80% warning threshold, coverage locations, and the documented follow-ups. Every factual claim in it was verified against this diff: publishContextUsage skips finished runs and unknown windows and isolates observer throws; the store defaults are 32 chats × 64 runs with active-run gating; the threshold is percent >= 80; and the store test is registered in the package.json scripts and scripts/ci-test-registry.json.

  ^{｜ View workflow run ｜ Using GLM Flash ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes I reviewed the delta since the prior Pullfrog review, including the upstream merge and its test-script conflict resolution.

• Merged upstream updates. Incorporated the upstream subagent roster/detail changes and preserved the union of both sides' entries in the root test and test:coverage scripts.
• Recorded merge-train friction. Added papercut notes for workflow setup and cross-PR CI flakes.

  ^{｜ View workflow run ｜ Using GPT Luna ｜ 𝕏}

[very-hermes-bot]

Hermes Review Bot

Confidence: 5

Engine: agy/gemini-3.8-flash-high
Review mode: full
Head: 3719941f88ff9cfaf61743865d109b68440c6f79
Generated: 2026-09-29T06:03:55+00:00
Reviews: 1

Summary

Surfaces live child context-window usage in the subagents panel while child agents are running. SubagentEventProjector.usage() extracts the latest turn's provider-reported token total and model context window, forwarding readings over a dedicated chat:subagent-context notification channel without mutating persisted snapshots or bumping revisions. In the renderer, a bounded in-memory LRU store (createSubagentContextUsageStore) tracks readings per chat and run, filtering out terminal runs so that only active subagents render the gauge icon, percentage, spoken accessibility text, and detail line. Maintainers should double-check that omitting readings for models without a known contextWindow or before the first child response arrives is acceptable UX for slower-starting subagents.

Confidence Score: 5/5

Fully traced the event pipeline from provider usage accounting in SubagentSupervisorCore and SubagentEventProjector through IPC to the renderer LRU store, React integration, and static UI assertions.

📁 Important Files Changed

• renderer/shared/subagent-context-usage.ts: Shared types, strict parsers, percentage math, and accessible label formatters for the live context payload.
• main/services/subagents/subagent-event-projector.ts: Hooks child assistant message usage to project live context readings without durable snapshot writes or revisions.
• main/services/llm-client.ts: Passes model.contextWindow into the projector and dispatches chat:subagent-context via sendGeneration.
• renderer/preload-channels.ts: Allow-lists chat:subagent-context in preload notification channels.
• renderer/lib/subagent-context-usage-store.ts: Bounded in-memory store (32 chats × 64 runs) with a useSyncExternalStore React hook and active-run filtering.
• renderer/components/subagents-panel.tsx: Ingests live context readings and passes them to the roster and detail views.
• renderer/components/subagent-roster.tsx: Renders the context gauge and percentage in the roster row and includes context occupancy in the tree item's aria-label.
• renderer/components/subagent-detail.tsx: Displays the detailed Context window: X / Y tokens (Z%) line beneath the model label.
• package.json & scripts/ci-test-registry.json: Registers renderer/lib/subagent-context-usage-store.test.ts in subagents, full, coverage, and CI test suites.

Findings

No findings.

📊 Sequence Diagram

sequenceDiagram
  participant Child as Subagent Child Runtime
  participant Projector as SubagentEventProjector
  participant LLM as llm-client
  participant Renderer as Preload & ContextUsageStore
  participant UI as SubagentsPanel / Roster

  Child->>Projector: usage(runId, assistantMessage)
  Projector->>Projector: publishContextUsage(current, reportedTokens)
  Projector->>LLM: onContextUsage(runId, usage)
  LLM->>Renderer: sendGeneration("chat:subagent-context", payload)
  Renderer->>Renderer: sharedStore.apply(payload)
  Renderer->>UI: useSyncExternalStore listener trigger
  UI->>UI: activeSubagentContextUsage(runs, readings)
  UI->>UI: Render gauge & 80% warning tone

Loading

Machine-Readable Findings

[]

---

Last reviewed commit: 3719941f88ff
Reviews (1) · Comment /hermes review to trigger a new review · /hermes review full for full re-review