Agent Visibility System: Live terminal streaming, session

Home Epics Agent Visibility System: Live terminal streaming, session logs, and debug dashboardEdit

Agent Visibility System: Live terminal streaming, session logs, and debug dashboard

Cancel

Title *

Project *

Description

## Overview

Build a comprehensive agent visibility system for debugging and monitoring autonomous agents. Currently agents run in opaque Docker containers with no visibility into their actual work - we only see high-level action logs, not what they're actually doing.

## Problem

When agents get stuck or behave unexpectedly, we have **zero visibility** into:
- What the agent is currently doing/thinking
- What commands it's running
- What errors it's encountering
- What led to a failure

## Solution: Three-Part System

### Part 1: Live Terminal Streaming
Capture Claude PTY output from agent-bridge and stream to Rails WebSocket for real-time viewing.

**Changes needed:**
- `agent-bridge.go`: Capture PTY output, send to WebSocket
- Rails: New WebSocket channel for terminal streaming
- Frontend: Terminal-like UI component (xterm.js or similar)

### Part 2: Agent Session Logs
Store terminal output persistently for replay and debugging.

**Changes needed:**
- New `AgentSession` model (agent_id, started_at, ended_at, log_file_path)
- New `AgentTerminalLog` model (session_id, timestamp, output_line)
- Log rotation/cleanup policy
- MCP tool to query historical logs

### Part 3: Debug Dashboard
Web UI showing real-time agent activity.

**Features:**
- Live terminal view for each active agent
- Agent status cards (busy/idle, current ticket, last activity)
- Recent activity feed
- Session history browser
- Search/filter by agent, ticket, time range

## Technical Approach

### agent-bridge.go changes
```go
// Capture PTY output line by line
scanner := bufio.NewScanner(ptmx)
for scanner.Scan() {
    line := scanner.Text()
    
    // Send to WebSocket for live streaming
    sendTerminalMessage(ctx, conn, TerminalMessage{
        Type: "output",
        Line: line,
        Timestamp: time.Now(),
    })
    
    // Also write to log file for persistence
    logFile.WriteString(line + "\n")
}
```

### New Rails models
```ruby
# AgentSession - Represents a single agent run
class AgentSession < ApplicationRecord
  belongs_to :agent
  has_many :terminal_logs, dependent: :destroy
  
  def self.current_for_agent(agent)
    where(agent: agent, ended_at: nil).last
  end
end

# AgentTerminalLog - Individual lines of terminal output
class AgentTerminalLog < ApplicationRecord
  belongs_to :agent_session
end
```

### New WebSocket channel
```ruby
# TerminalChannel - Streams agent terminal output
class TerminalChannel < ApplicationCable::Channel
  def subscribed
    stream_from "terminal_agent_#{params[:agent_id]}"
  end
end
```

## Acceptance Criteria

1. **Live Streaming**: See agent terminal output in browser in real-time (< 1s latency)
2. **Session Logs**: All terminal output stored and queryable via API
3. **Dashboard**: Single page showing all agents with live terminal views
4. **Performance**: No impact on agent performance (< 5% overhead)
5. **Retention**: Logs kept for 7 days, auto-purged after

## Files to Modify

- `agent-bridge.go` - Add terminal capture and WebSocket streaming
- `app/models/agent_session.rb` (new)
- `app/models/agent_terminal_log.rb` (new)
- `app/channels/terminal_channel.rb` (new)
- `app/controllers/dashboard_controller.rb` (new)
- `app/views/dashboard/index.html.erb` (new)
- `db/migrate/*_create_agent_sessions.rb` (new)
- `db/migrate/*_create_agent_terminal_logs.rb` (new)
- Frontend assets for terminal UI (xterm.js integration)

## Dependencies

- xterm.js for browser terminal emulation
- WebSocket bandwidth monitoring (don't saturate connection)
- Log storage consideration (could be large)