ollie/doc/design/proc-window.md

Proc Window Feature Design

Overview

A dedicated window for managing background processes (tools running in background mode). Accessible via context menu on sessions/agents in the tree view.

User Flow

1. Right-click session/agent → "Processes..."
2. Opens ProcWindow showing all background procs for that scope
3. Window tracks the active session (when main GUI switches session, proc window updates)
4. Can also be "pinned" to a specific session/agent

UI Components

ProcWindow.qml

┌─────────────────────────────────────────────────────────────┐
│ Processes - {session}/{agent}                      [📌] [×] │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ PID │ Tool      │ Status  │ Runtime  │ Actions         │ │
│ ├─────┼───────────┼─────────┼──────────┼─────────────────┤ │
│ │ 5   │ shell     │ running │ 2m 34s   │ [▶] [■] [×]    │ │
│ │ 3   │ web_fetch │ exited  │ 45s      │ [▶] [🗑]       │ │
│ │ 1   │ shell     │ exited  │ 12s      │ [▶] [🗑]       │ │
│ └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Output for PID 5                                    [Clear] │
├─────────────────────────────────────────────────────────────┤
│ $ npm install                                               │
│ npm WARN deprecated...                                      │
│ added 123 packages in 45s                                   │
│ █                                                           │
└─────────────────────────────────────────────────────────────┘

Actions

Icon	Action	Description
▶	Stream	Open output stream (updates in real-time)
■	Term	Send SIGTERM (graceful stop)
×	Kill	Send SIGKILL (force kill)
🗑	Dismiss	Remove from list (exited procs only)

Features

1. Live refresh: Subscribe to proc events or poll proc idx
2. Output streaming: Read proc output via proc out <pid>
3. Session tracking: Follow active session in main GUI (optional pin)
4. Multi-agent view: When opened on session, show all agents' procs
5. Auto-scroll: Output pane auto-scrolls unless user scrolls up

Backend Implementation Status

✅ Phase 1: Backend (DONE)

Proc Events

• session.{sid}.agent.{aid}.proc.start — emitted when background proc spawns
  • Payload: {pid}\t{tool}\t{cmd}
• session.{sid}.agent.{aid}.proc.exit — emitted when background proc exits
  • Payload: {pid}\t{exit_code}\t{tool}\t{cmd}

Machine-Readable Proc Index

• proc idx ctl command returns TSV format:
  • pid<TAB>status<TAB>exit_code<TAB>tool<TAB>cmd<TAB>start_unix<TAB>runtime_sec
• Status is running or exited
• Exit code is -1 for running processes

Event Publishing Endpoint

• event.pub file at root namespace accepts writes: topic<TAB>payload
• Used by toolsrv to publish proc.exit events back to olliesrv

🔲 Phase 2: GUI (TODO)

1. Create ProcModel (C++ model for proc list)
2. Create ProcWindow.qml
3. Add context menu action to SessionTree.qml
4. Wire up event subscription for live updates

🔲 Phase 3: Polish (TODO)

1. Session tracking / pin toggle
2. Output search/filter
3. Keyboard shortcuts
4. Copy output to clipboard

Files Modified (Phase 1)

• cmd/olliesrv/internal/agent/agent.go — added onProcStart callback
• cmd/olliesrv/internal/agent/state.go — added SetOnProcStart
• cmd/olliesrv/internal/agent/dispatch.go — call callback on proc start
• cmd/olliesrv/internal/fs/support.go — wire callback to publish event
• cmd/olliesrv/internal/fs/spec.go — added event.pub file, proc idx command
• cmd/olliesrv/internal/toolclient/toolsrv.go — added ListProcsIdx
• cmd/toolsrv/internal/server/proc.go — added ListProcsIdxForAgent
• cmd/toolsrv/internal/server/server.go — added proc/idx file
• cmd/toolsrv/main.go — publish proc.exit event via event.pub
• doc/event-topics.md — documented new proc events

API Reference

ctl Commands

# Human-readable proc list
echo "proc top" | ollie-9p rdwr session/$SID/agent/$AID/ctl

# Machine-readable proc index (TSV)
echo "proc idx" | ollie-9p rdwr session/$SID/agent/$AID/ctl

# Get proc output
echo "proc out 5" | ollie-9p rdwr session/$SID/agent/$AID/ctl

# Signal proc
echo "proc term 5" | ollie-9p rdwr session/$SID/agent/$AID/ctl
echo "proc kill 5" | ollie-9p rdwr session/$SID/agent/$AID/ctl

# Dismiss exited proc
echo "proc dismiss 5" | ollie-9p rdwr session/$SID/agent/$AID/ctl

Event Subscription

# All proc events for all sessions/agents
echo "session.*.agent.*.proc.>" | ollie-9p rdwrs event

# Proc events for specific session
echo "session.abc123.agent.*.proc.>" | ollie-9p rdwrs event

# Only proc.start events
echo "session.*.agent.*.proc.start" | ollie-9p rdwrs event

proc idx Output Format

pid	status	exit_code	tool	cmd	start_unix	runtime_sec
5	running	-1	shell	make test	1723456789	45.2
3	exited	0	web_fetch	fetch docs	1723456700	12.5