Skip to content

feat(tui): interactive subagent management — sidebar selection and transcript viewer #2376

@bug-ops

Description

@bug-ops

Problem

Subagents run as async Tokio tasks and are orchestrated through SubAgentManager in zeph-core. The TUI currently shows a minimal non-interactive subagent list (name, state, turns, elapsed). There is no way to:

  • Select a subagent to inspect its chat/tool output
  • Switch between the main agent conversation and a subagent's transcript
  • See detailed per-agent progress without leaving the chat view

When multiple subagents run in parallel (during DAG-orchestrated plans), the user has zero visibility into individual agent behavior.

Goal

Add interactive subagent management to the TUI:

  • Navigable sidebar listing all active/completed subagents
  • Per-agent transcript viewer in the main chat area (reusing existing chat renderer)
  • Tab/Shift+Tab keyboard switching between main agent and any subagent

Spec

.local/specs/026-tui-subagent-management/spec.md + plan.md

Key Design

  • AgentViewTarget { Main, SubAgent { id, name } } enum on TuiApp controls what the chat area displays
  • Transcripts read from JSONL files via TranscriptReader (no new channels, no modifications to SubAgentManager)
  • Reuse existing widgets::chat::render — markdown/diff/tool output rendering for free
  • Selection preserved by agent ID (not index) — survives agent completion/spawn events
  • 200-message limit per agent to prevent memory bloat; large files loaded via spawn_blocking

Open Question (implement-time decision)

How TUI discovers the transcript path for a subagent:

  • Option A (recommended): add transcript_dir: Option<String> to SubAgentMetrics in zeph-core
  • Option B: derive from convention (data_dir/transcripts/<id>.jsonl) passed into App at construction

Acceptance Criteria

  • Subagent sidebar shows name, state (color-coded), turns, elapsed, spinner for active agents
  • Tab/Shift+Tab cycles focus: Main → Agent1 → Agent2 → … → Main (wraps)
  • Focused subagent's transcript renders in the main chat area
  • Esc / selecting "Main" returns to main agent conversation
  • Status bar shows Viewing subagent: <name> when a subagent is focused
  • Transcript reloads on each focus switch (poll-based, no stale display)
  • TUI resize does not crash while viewing a subagent
  • Empty subagent list shows placeholder text, no panic
  • All existing 011-tui invariants remain unviolated (spinner rule, no blocking render thread)

Out of Scope

  • Sending input to subagents from the TUI
  • Canceling/spawning from sidebar
  • Multi-pane split view
  • Real-time streaming via watch channels (MVP: poll-based)
  • CLI/Telegram

Metadata

Metadata

Assignees

Labels

P2High value, medium complexityenhancementNew feature or request

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions