145 lines
6.1 KiB
Markdown
145 lines
6.1 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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
|
||
```
|