V7 — Right Sidebar: Agents Panel + Agent Chat

[Luis85]

Parent epic: #326 · Depends on: F2, F3, F4 · Stories: US-043, US-044, US-040

Problem

Agent visibility and chat are the differentiator of the workspace. Without them, the user can't see what agents are doing, can't intervene mid-task, and can't open a direct conversation with a running agent.

Solution

AgentsList.vue — right-panel content when right === 'agents'

• Header: ← Tasks back button (returns right = 'tasks') + "Agents" label
• Two groups: Running (status dot green pulse) and Queued (amber)
• Row: gradient avatar (7px radius, square) + Name + Role + current task (truncated) + status dot
• Row click → right = 'agent', agentId = id (US-040)

AgentChat.vue — right-panel content when right === 'agent'

• Header: ← Agents back button + agent avatar + Name + Role + status (● Running / ● Queued)
• Message log with four types (per the design brief):
  • sys — purple-tinted background, monospace, for system instructions
  • agent — blue-tinted background, prose
  • tool — dark background, monospace, shows tool call + result
  • user — subtle border, right-aligned, user intent
• Typing indicator: three dots with staggered opacity animation, shown when agent.live === true
• Textarea at bottom: Enter sends (Shift+Enter newline); Send button activates when text is present
• New messages append to the log; container scrolls to bottom on send and on new arrivals
• Subscribed to AgentRuntimePort.subscribeToAgent(agentId, …) while right === 'agent'; unsubscribe on view leave (cleanup in onBeforeUnmount)
• Read agent chat log (US-043) and send messages (US-044)

Use cases

• GetAgentsUseCase — initial list via AgentRuntimePort.listAgents
• GetAgentDetailsUseCase — single agent + recent messages
• SendAgentMessageUseCase — send via AgentRuntimePort.sendMessage; optimistic append to chat log

Empty / disconnected states

• If AgentRuntimePort is mock-only (agent runtime endpoint not configured in F5): banner at top of AgentsList: "Agent runtime not configured. Showing demo agents. Configure in Settings."
• If a subscription drops mid-chat: persistent notice "Agent disconnected — reconnecting…"; auto-retry every 5s

Acceptance criteria

• AgentsList renders Running first, then Queued; row click switches to chat (US-040)
• AgentChat renders the four message types with correct styling
• Typing indicator only appears when agent.live === true
• Enter submits, Shift+Enter inserts newline, send button activates conditionally (US-044)
• User message appears optimistically; agent reply arrives via subscription and appends without re-render (US-043)
• Back button returns to AgentsList
• Subscription cleaned up on leave (verified by a test that unmounts the view and asserts no further callbacks fire)
• Empty state banner shown when agent runtime not configured
• Disconnect banner + retry loop on subscription drop
• PageObject tests cover: agent list click → chat, message type rendering, send + receive flow, back navigation, disconnect retry
• Storybook: empty agents list, mixed running/queued agents, agent chat with all message types, agent chat with typing indicator, disconnect state
• A11y: role="log" + aria-live="polite" on message container; messages added without focus jump; Tab moves between back button, message log, textarea, send button
• npm run typecheck, npm run lint, npm run test, npm run test:storybook pass

Out of scope

• The ContextualAIInput atom routing to a real model (Phase 2)
• Agent process management (spawn / kill) — Phase 2
• History scrolling / pagination for huge chat logs (Phase 2)

Affected files

File	Action
src/ui/components/right/AgentsList.vue	New
src/ui/components/right/AgentChat.vue	New
src/ui/components/right/AgentMessage.vue	New (per-type message component)
src/application/agent/GetAgentsUseCase.ts	New
src/application/agent/GetAgentDetailsUseCase.ts	New
src/application/agent/SendAgentMessageUseCase.ts	New
tests/application/agent/*.test.ts	New
tests/ui/components/right/AgentsList.test.ts + .po.ts	New
tests/ui/components/right/AgentChat.test.ts + .po.ts	New
stories/right/AgentsList.stories.ts, AgentChat.stories.ts	New

References

• inputs/specorator-mvp-design-2026-05/Specorator_Design_Brief.html §"Agents Panel" + §"Agent Detail — Chat Log"
• inputs/specorator-mvp-design-2026-05/Specorator_Handoff.html §"AgentRuntimePort"
• User stories US-040, US-043, US-044

[Luis85]

Right-sidebar review (V7) — readiness: M — subscription lifecycle + reconnect banner need tightening before coding

V7 is the most stateful right-sidebar slice. The plan is broadly right but has three lifecycle hazards that will become flaky tests or memory leaks if not tightened now.

Review findings

1. subscribeToAgent cleanup must be tied to component lifecycle, not store ownership. The acceptance criterion mentions onBeforeUnmount but is silent on the right === 'agent' → right === 'agents' transition (no unmount; same parent). Pattern: bind subscription inside AgentChat.vue's setup() with onBeforeUnmount (unmount path) AND a watch(() => route.query.agentId, …) that re-subscribes when the agent changes and an explicit unsubscribe() on the old id. Without the watch, switching agents leaks one subscription per switch. Add an explicit test: mount → switch agent twice → unmount → assert exactly two cleanup callbacks fired and zero pending message callbacks.
2. Disconnect/reconnect banner is a separate component, not inline. Per SYNTHESIS §"empty/error/offline states" this pattern recurs (GitHub auth errors, agent disconnects). Suggest extracting <ConnectionBanner status="reconnecting" /> as a reusable atom now; V7 is the first consumer but V4 PR activity feed will need it too. Keep the 5-second retry as a prop (retryIntervalMs) so tests can override it.
3. Agent runtime mock-only fallback should be a port capability, not a try/catch. Detect via AgentRuntimePort.isConfigured(): boolean exposed by the port itself. The mock adapter returns false; the production adapter returns true once F5 PAT-equivalent agent endpoint is set. The "Agent runtime not configured" banner reads from this — do not infer from "list returned empty" because an empty Running/Queued list is a valid normal state.
4. Optimistic append + reconciliation. When SendAgentMessageUseCase succeeds, the local optimistic message must reconcile with the server-echoed message (same clientId). If the use case returns Result.err, the optimistic message must be marked failed (greyed + retry button). Acceptance is silent on this — add a criterion.
5. Scroll-to-bottom only when already at bottom. Auto-scrolling on every arrival when the user has scrolled up to read history is a known anti-pattern. Track isAtBottom (within 8px) and only scroll if true.

Use case test cases

SendAgentMessageUseCase.test.ts:

• sends a user message and returns the persisted Message with server id
• returns Result.err(AgentOffline) when AgentRuntimePort.sendMessage rejects
• returns Result.err(EmptyMessage) on whitespace-only input
• includes the optimistic clientId in the persisted message for reconciliation
• does not send when agent.status === 'queued' (returns Result.err(AgentNotReady))

GetAgentsUseCase.test.ts:

• returns Running agents before Queued
• returns empty array (not error) when port not configured
• propagates port errors as Result.err

Component test cases

AgentsList.test.ts:

• renders Running group above Queued group
• shows configured/unconfigured banner based on port capability
• row click sets right = 'agent' AND agentId = id
• empty Running + empty Queued → empty-state, no group headers

AgentChat.test.ts:

• renders sys/agent/tool/user messages with the four testids
• typing indicator visible only when agent.live === true
• Enter submits; Shift+Enter inserts a newline (textarea value contains \n)
• send button disabled when textarea empty
• subscription cleanup fires exactly once on unmount and on agent change
• on subscription drop, disconnect banner appears and setInterval retries every 5s
• optimistic user message appears, then reconciles with server echo (no duplicate)
• on SendAgentMessageUseCase Result.err, message marked failed with retry control
• auto-scroll only when user was at bottom

data-testid hooks

AgentsList: agents-list-root, agents-list-back-button, agents-list-running-group, agents-list-queued-group, agents-list-row (with data-agent-id), agents-list-row-avatar, agents-list-row-status-running, agents-list-row-status-queued, agents-list-banner-unconfigured, agents-list-empty.
AgentChat: agent-chat-root, agent-chat-back-button, agent-chat-header-name, agent-chat-header-status-running, agent-chat-header-status-queued, agent-chat-log, agent-chat-message-sys, agent-chat-message-agent, agent-chat-message-tool, agent-chat-message-user, agent-chat-message-failed, agent-chat-message-retry, agent-chat-typing-indicator, agent-chat-textarea, agent-chat-send-button, agent-chat-send-button-disabled, agent-chat-banner-disconnected.

EARS requirements

• REQ-MVP-045: When right === 'agents', the system shall render Running agents above Queued agents.
• REQ-MVP-046: When the user clicks an agent row, the system shall set right = 'agent' and agentId = row.id and subscribe via AgentRuntimePort.subscribeToAgent(agentId, …).
• REQ-MVP-047: While the agent chat is mounted, the system shall unsubscribe from the previous agent before subscribing to a new one when agentId changes.
• REQ-MVP-048: When the user presses Enter (without Shift) in the textarea with non-empty text, the system shall dispatch SendAgentMessageUseCase.
• REQ-MVP-049: If AgentRuntimePort.isConfigured() returns false, then AgentsList shall display the "Agent runtime not configured" banner.
• REQ-MVP-050: If a subscription drops, then the system shall display the disconnect banner and retry subscribeToAgent every 5000ms.
• REQ-MVP-051: When SendAgentMessageUseCase returns Result.err, the system shall mark the optimistic message failed and expose a retry control.

Storybook story matrix

AgentsList.stories.ts: EmptyConfigured, EmptyUnconfigured, RunningOnly, QueuedOnly, MixedRunningQueued, ManyAgents (perf).
AgentChat.stories.ts: EmptyLog, AllFourMessageTypes, WithTypingIndicator, Disconnected, LongMessageBacklog (200+), OptimisticPending, SendFailed, AgentOfflineMidChat.

A11y checklist

• agent-chat-log has role="log" and aria-live="polite" (per acceptance) but ALSO aria-relevant="additions" so only new messages are announced, not the entire backlog on mount.
• Tab order: back button → message log (focusable container) → textarea → send button.
• Typing indicator has aria-hidden="true" (decorative) and a visually hidden <span aria-live="polite">{{ agent.name }} is typing</span> for SR users.
• Disconnect banner uses role="status" with aria-live="polite" (not assertive — non-critical).
• Textarea has aria-label="Message {agent.name}" and aria-multiline="true".
• Failed message retry button has aria-label="Retry sending message".
• prefers-reduced-motion: disable the typing-dot staggered animation.

Edge cases

• Agent goes offline mid-chat — show disconnect banner; optimistic in-flight message marked failed after 10s timeout.
• Very long message backlog (200+) — virtualization deferred to X3 but agent-chat-log should set contain: strict to avoid layout thrash.
• Switching agents while a message is still optimistic — cancel the optimistic message; do not append the server echo to the new chat.
• Rapid Enter spamming — disable send button while in flight.
• Textarea grows up to 100px (per CSS) then scrolls internally; test the boundary.
• agent.live toggles false mid-chat → typing indicator removed without flicker.

---

Generated by Claude Code