aoaoe 0.95.0 → 0.114.0

package/README.md

@@ -1,19 +1,23 @@
 <p align="center">
   <h1 align="center">Agent of Agent of Empires (aoaoe)</h1>
   <p align="center">
+    <a href="https://github.com/Talador12/agent-of-agent-of-empires/actions/workflows/ci.yml"><img src="https://github.com/Talador12/agent-of-agent-of-empires/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
     <a href="https://www.npmjs.com/package/aoaoe"><img src="https://img.shields.io/npm/v/aoaoe" alt="npm version"></a>
     <a href="https://github.com/Talador12/agent-of-agent-of-empires/releases"><img src="https://img.shields.io/github/v/release/Talador12/agent-of-agent-of-empires" alt="GitHub release"></a>
+    <img src="https://img.shields.io/badge/tests-1739-brightgreen" alt="tests">
+    <img src="https://img.shields.io/badge/node-%3E%3D20-blue" alt="Node.js >= 20">
+    <img src="https://img.shields.io/badge/runtime%20deps-0-brightgreen" alt="zero runtime dependencies">
     <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
   </p>
 </p>
 
-An autonomous supervisor that manages [Agent of Empires](https://github.com/njbrake/agent-of-empires) sessions using [OpenCode](https://github.com/anomalyco/opencode) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code) as the reasoning engine.
+An autonomous supervisor for [Agent of Empires](https://github.com/njbrake/agent-of-empires) sessions. Uses [OpenCode](https://github.com/anomalyco/opencode) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code) as the reasoning engine.
 
-> Built on top of [Agent of Empires (AoE)](https://github.com/njbrake/agent-of-empires) by [Nate Brake](https://x.com/natebrake). AoE is the session manager -- aoaoe is the brain that drives it.
+**This project is a companion to [Agent of Empires (AoE)](https://github.com/njbrake/agent-of-empires) by [Nate Brake](https://x.com/natebrake).** AoE is the foundation -- it manages multiple AI coding agents in tmux sessions with git worktrees. aoaoe adds an autonomous supervisor layer on top. You need AoE running first; aoaoe plugs into it.
 
 ## What is this?
 
-[Agent of Empires (AoE)](https://github.com/njbrake/agent-of-empires) manages multiple AI coding agents (Claude Code, OpenCode, Gemini CLI, Codex, etc.) in tmux sessions with git worktrees. It is great at spawning and organizing agents, but someone still needs to watch the tmux panes and intervene when agents get stuck, ask questions, or finish their work.
+[AoE](https://github.com/njbrake/agent-of-empires) is great at spawning and organizing agents, but someone still needs to watch the tmux panes and intervene when agents get stuck, ask questions, or finish their work.
 
 **aoaoe** is that someone -- except it is an LLM. It polls your AoE sessions, reads agent output, decides when to act, and executes without you needing to be there.
 
@@ -171,19 +175,38 @@ aoaoe can automatically create and manage AoE sessions from a task list. Define
 
 ```json
 [
-  { "repo": "github/adventure", "tool": "opencode", "goal": "Continue the roadmap in claude.md" },
-  { "repo": "github/cloud-hypervisor", "goal": "Address PR review feedback" },
-  { "repo": "cc/cloudchamber" }
+  {
+    "repo": "github/adventure",
+    "sessionTitle": "adventure",
+    "sessionMode": "existing",
+    "goal": "Process queued TODOs in this existing AoE session"
+  },
+  {
+    "repo": "github/agent-of-agent-of-empires",
+    "sessionTitle": "aoaoe-roadmap",
+    "sessionMode": "new",
+    "tool": "opencode",
+    "goal": "Ship next roadmap item with tests"
+  },
+  {
+    "repo": "github/cloud-hypervisor",
+    "sessionMode": "auto",
+    "goal": "Address PR review feedback"
+  }
 ]
 ```
 
 | Field | Required | Description |
 |-------|:--------:|-------------|
 | `repo` | Yes | Path to the project directory (relative to cwd or absolute) |
+| `sessionTitle` | No | AoE session title to target. Default: derived from `repo` basename |
+| `sessionMode` | No | Session allocation strategy: `existing` (link only), `new` (create), `auto` (link or create). Default: `auto` |
 | `tool` | No | Agent tool to use (`opencode`, `claude-code`, etc.). Default: `opencode` |
 | `goal` | No | Goal text injected into the supervisor's context for this task |
 
-When the daemon starts, it reconciles sessions automatically: creates new AoE sessions for tasks that don't have one, links existing sessions to matching tasks. Progress is tracked persistently in `~/.aoaoe/task-state.json` and survives session cleanup.
+When the daemon starts, it now auto-imports any currently visible AoE sessions into the task list (mode=`existing`) so active and inactive sessions are immediately schedulable. Then it reconciles tasks: creates new AoE sessions when needed, links existing sessions by title, and starts linked sessions as needed. Progress is tracked persistently in `~/.aoaoe/task-state.json` and survives session cleanup.
+
+Interactive task updates (`aoaoe task new/edit/rm` or `/task ...`) also sync back to `aoaoe.tasks.json`, so your list evolves as you go.
 
 The supervisor can report progress milestones and mark tasks complete via two special actions:
 - `report_progress` — logs a milestone summary to persistent state
@@ -195,9 +218,117 @@ View task status:
 aoaoe tasks    # show task progress table
 ```
 
+## Daemon TUI Commands
+
+The daemon runs an interactive TUI with a rich command set. These commands are available when the daemon is running (started with `aoaoe`).
+
+### Talking to the AI
+
+| Command | What it does |
+|---------|-------------|
+| _(any text)_ | Send a message -- queued for the next reasoning cycle |
+| `!message` | Insist -- interrupt + deliver message immediately |
+| `/insist <msg>` | Same as `!message` |
+| `/explain` | Ask the AI to explain what's happening right now |
+
+### Controls
+
+| Command | What it does |
+|---------|-------------|
+| `/pause` | Pause the supervisor (stops reasoning) |
+| `/resume` | Resume after pause |
+| `/mode [name]` | Switch mode at runtime: `observe`, `dry-run`, `confirm`, `autopilot` (no arg = show current) |
+| `/interrupt` | Interrupt the AI mid-thought |
+| ESC ESC | Same as `/interrupt` (shortcut) |
+
+### Navigation
+
+| Command | What it does |
+|---------|-------------|
+| `1`-`9` | Quick-switch: jump to session N |
+| `/view [N\|name]` | Drill into a session's live output (default: 1) |
+| `/back` | Return to overview from drill-down |
+| `/sort [mode]` | Sort sessions: `status`, `name`, `activity`, `default` (no arg = cycle) |
+| `/compact` | Toggle compact mode (dense session panel) |
+| `/pin [N\|name]` | Pin/unpin a session to the top |
+| `/bell` | Toggle terminal bell on errors/completions |
+| `/focus` | Toggle focus mode (show only pinned sessions) |
+| `/mute [N\|name]` | Mute/unmute a session's activity entries |
+| `/unmute-all` | Unmute all sessions at once |
+| `/filter [tag]` | Filter activity by tag -- presets: `errors`, `actions`, `system` (no arg = clear) |
+| `/who` | Show fleet status: status, uptime, idle-since, context, errors, group, note |
+| `/uptime` | Show session uptimes |
+| `/top [mode]` | Rank sessions by `errors` (default), `burn`, or `idle` |
+| `/auto-pin` | Toggle auto-pin on error |
+| `/note N\|name text` | Attach a note to a session (no text = clear) |
+| `/notes` | List all session notes |
+| `/group N\|name tag` | Assign session to a group (lowercase, max 16 chars; no tag = clear) |
+| `/groups` | List all groups and their members |
+| `/group-filter [tag]` | Show only sessions in a group (no arg = clear) |
+| `/rename N\|name [display]` | Set custom TUI display name (no display = clear); persisted |
+| `/watchdog [N]` | Alert if session stalls N minutes (default 10); `/watchdog off` to disable |
+| `/broadcast <msg>` | Send message to all sessions; `/broadcast group:<tag> <msg>` for group |
+| `/clip [N]` | Copy last N activity entries to clipboard (default 20) |
+| `/diff N` | Show activity since bookmark N |
+| `/mark` | Bookmark current activity position |
+| `/jump N` | Jump to bookmark N |
+| `/marks` | List all bookmarks |
+| `/search <pattern>` | Filter activity entries by substring (no arg = clear) |
+| Click session | Click an agent card to drill down (click again to go back) |
+| Mouse wheel | Scroll activity (overview) or session output (drill-down) |
+| PgUp / PgDn | Scroll through activity or session output |
+| Home / End | Jump to oldest / return to live |
+
+### Info
+
+| Command | What it does |
+|---------|-------------|
+| `/status` | Show daemon state (mode, reasoner, poll counts, last cycle) |
+| `/dashboard` | Show full dashboard |
+| `/tasks` | Show task progress table |
+| `/t ...` `/todo ...` `/idea ...` | Aliases for `/task ...` |
+| `/task [sub] [args]` | Task management (list, start, stop, edit, new, rm) |
+| `/task <session> :: <goal>` | Fast path: update/create task for an existing session and set its goal |
+| `:<goal>` | Fastest path in drill-down: set goal for that session |
+| `just type` (in drill-down) | Default behavior: update goal for the focused session |
+| `/burn-rate` | Show context token burn rates (tokens/min) for all sessions |
+| `/ceiling` | Show context token usage vs limit for all sessions |
+| `/snapshot [md]` | Export session state snapshot to `~/.aoaoe/snapshot-<ts>.json` (or `.md`) |
+| `/alias /x /cmd` | Create command alias (`/x` expands to `/cmd`); no args = list |
+
+### Other
+
+| Command | What it does |
+|---------|-------------|
+| `/verbose` | Toggle detailed logging |
+| `/clear` | Clear the screen |
+| `/help` | Show all commands |
+
+### TUI Features
+
+- **Activity sparkline** -- 10-minute activity rate chart in the separator bar (Unicode blocks with color gradient)
+- **Session cards** -- per-session status with pin `▲`, mute `◌`, note `✎`, group `⊹tag`, and health score `⬡N` indicators
+- **Health score** -- composite 0–100 badge per session (errors, burn rate, context ceiling, stall time); LIME ≥80, AMBER ≥60, ROSE <60
+- **Error sparklines** -- ROSE 5-bucket mini-chart of recent error frequency in each card (last 5 min)
+- **Idle-since** -- time since last output change shown in idle/done card status and `/who` output
+- **Session grouping** -- `/group` assigns sessions to named groups; `/group-filter` narrows the panel view
+- **Session rename** -- `/rename` sets a custom TUI display name (bold with original dim alongside); persisted
+- **Watchdog** -- `/watchdog N` fires an alert if a session stalls for N minutes (rate-limited to once per 5 min)
+- **Burn-rate alerts** -- automatic "status" alert when context token usage exceeds 5k tokens/min; `/burn-rate` for on-demand view
+- **Context ceiling warning** -- automatic alert at 90% context usage when "X / Y tokens" format available; `/ceiling` for on-demand view
+- **Snapshot export** -- `/snapshot [md]` exports full session state (status, group, note, uptime, context, errors, burn rate) to `~/.aoaoe/`
+- **Broadcast** -- `/broadcast [group:<tag>] <message>` sends a message to all (or group-filtered) sessions via tmux
+- **Ranked view** -- `/top [errors|burn|idle]` ranks sessions by composite attention score or a single metric
+- **Sticky preferences** -- sort, compact, focus, bell, auto-pin, tag filter, aliases, groups, and renames persist across restarts
+- **Filter pipeline** -- mute, tag filter, and search compose: mute → tag → search
+- **Aliases** -- `/alias /x /cmd` creates command shortcuts; up to 50, persisted
+- **Activity heatmap** -- 24-hour colored block chart via `aoaoe stats`
+- **Bookmarks** -- mark positions in the activity stream, jump back to them, diff since a bookmark
+- **Clipboard export** -- `/clip` copies activity to system clipboard (macOS) or `~/.aoaoe/clip.txt`
+
 ## Chat UI Commands
 
-Once inside the chat UI (via `aoe` -> select "aoaoe"):
+The chat UI (`aoaoe-chat`) runs inside an AoE tmux pane. Register it with `aoaoe register`, then access via `aoe` -> select "aoaoe".
 
 | Command | What it does |
 |---------|-------------|
@@ -491,38 +622,43 @@ The daemon and chat UI communicate via files in `~/.aoaoe/`:
 
 ```
 src/
-  index.ts          # daemon entry point, main loop, subcommands
-  loop.ts           # extracted tick logic (poll->reason->execute), testable with mocks
-  chat.ts           # interactive chat UI (aoaoe-chat binary)
-  config.ts         # config loader and CLI arg parser
-  types.ts          # shared types (SessionSnapshot, Action, DaemonState, etc.)
-  poller.ts         # aoe CLI + tmux capture-pane wrapper
-  executor.ts       # maps action decisions to shell commands
-  console.ts        # conversation log + file-based IPC
-  dashboard.ts      # periodic CLI status table with task column
-  daemon-state.ts   # shared IPC state file + interrupt flag
-  tui.ts            # in-place terminal UI (alternate screen, scroll regions)
-  tui-history.ts    # persisted TUI history (JSONL file with rotation, replay on startup)
-  input.ts          # stdin readline listener with inject() for post-interrupt
-  init.ts           # `aoaoe init`: auto-discover tools, sessions, generate config
-  notify.ts         # webhook + Slack notification dispatcher for daemon events
-  health.ts         # HTTP health check endpoint (GET /health JSON status)
-  colors.ts         # shared ANSI color/style constants
-  context.ts        # discoverContextFiles, resolveProjectDir, loadSessionContext
-  activity.ts       # detect human keystrokes in tmux sessions
-  prompt-watcher.ts # reactive permission prompt clearing via tmux pipe-pane
-  task-manager.ts   # task orchestration: definitions, persistent state
-  task-cli.ts       # `aoaoe task` subcommand: list, start, stop, new, rm, edit
-  task-parser.ts    # parse OpenCode TODO patterns, model, tokens, cost from tmux
-  message.ts        # classifyMessages, formatUserMessages, shouldSkipSleep
-  wake.ts           # wakeableSleep with fs.watch for instant message delivery
-  shell.ts          # exec() wrappers with AbortSignal support
+  index.ts            # daemon entry point, main loop, subcommands
+  loop.ts             # extracted tick logic (poll->reason->execute), testable with mocks
+  chat.ts             # interactive chat UI (aoaoe-chat binary)
+  config.ts           # config loader and CLI arg parser
+  config-watcher.ts   # config hot-reload via fs.watch, safe field merge
+  types.ts            # shared types (SessionSnapshot, Action, DaemonState, etc.)
+  poller.ts           # aoe CLI + tmux capture-pane wrapper
+  executor.ts         # maps action decisions to shell commands
+  console.ts          # conversation log + file-based IPC
+  dashboard.ts        # periodic CLI status table with task column
+  daemon-state.ts     # shared IPC state file + interrupt flag
+  tui.ts              # in-place terminal UI (alternate screen, scroll, sparklines, cards)
+  tui-history.ts      # persisted TUI history (JSONL file with rotation, replay on startup)
+  input.ts            # stdin readline + keypress handlers (all /commands live here)
+  init.ts             # `aoaoe init`: auto-discover tools, sessions, generate config
+  notify.ts           # webhook + Slack notification dispatcher for daemon events
+  health.ts           # HTTP health check endpoint (GET /health JSON status)
+  colors.ts           # shared ANSI color/style constants
+  context.ts          # discoverContextFiles, resolveProjectDir, loadSessionContext
+  activity.ts         # detect human keystrokes in tmux sessions
+  prompt-watcher.ts   # reactive permission prompt clearing via tmux pipe-pane
+  task-manager.ts     # task orchestration: definitions, persistent state
+  task-cli.ts         # `aoaoe task` subcommand: list, start, stop, new, rm, edit
+  task-parser.ts      # parse OpenCode TODO patterns, model, tokens, cost from tmux
+  message.ts          # classifyMessages, formatUserMessages, shouldSkipSleep
+  wake.ts             # wakeableSleep with fs.watch for instant message delivery
+  shell.ts            # exec() wrappers with AbortSignal support
+  export.ts           # timeline export (JSON/Markdown) from actions + history
+  tail.ts             # `aoaoe tail`: live-stream daemon activity to another terminal
+  stats.ts            # `aoaoe stats`: aggregate statistics + activity heatmap
+  replay.ts           # `aoaoe replay`: play back tui-history.jsonl with timing
   reasoner/
-    index.ts        # common Reasoner interface + factory
-    prompt.ts       # system prompt + observation formatting
-    parse.ts        # response parsing, JSON extraction, action validation
-    opencode.ts     # OpenCode SDK backend
-    claude-code.ts  # Claude Code CLI backend
+    index.ts          # common Reasoner interface + factory
+    prompt.ts         # system prompt + observation formatting
+    parse.ts          # response parsing, JSON extraction, action validation
+    opencode.ts       # OpenCode SDK backend
+    claude-code.ts    # Claude Code CLI backend
 ```
 
 ## Related Projects

package/dist/daemon-state.js

@@ -5,7 +5,7 @@ import { writeFileSync, readFileSync, existsSync, unlinkSync, mkdirSync, renameS
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { toDaemonState } from "./types.js";
-import { parseTasks, formatTaskList } from "./task-parser.js";
+import { parseTasks, formatTaskList, parseContext } from "./task-parser.js";
 // default state directory — overridable via setStateDir() for test isolation
 let AOAOE_DIR = join(homedir(), ".aoaoe");
 let STATE_FILE = join(AOAOE_DIR, "daemon-state.json");
@@ -50,6 +50,8 @@ export function resetInternalState() {
 const sessionTasks = new Map();
 // cache parsed TODO summaries for unchanged sessions
 const todoCache = new Map();
+// cache parsed context token usage for unchanged sessions
+const contextCache = new Map();
 export function setSessionTask(sessionId, task) {
     // keep task text short for display
     sessionTasks.set(sessionId, task.length > 80 ? task.slice(0, 77) + "..." : task);
@@ -98,6 +100,14 @@ export function buildSessionStates(obs) {
         if (!currentIds.has(id))
             sessionTasks.delete(id);
     }
+    for (const id of todoCache.keys()) {
+        if (!currentIds.has(id))
+            todoCache.delete(id);
+    }
+    for (const id of contextCache.keys()) {
+        if (!currentIds.has(id))
+            contextCache.delete(id);
+    }
     // only re-parse TODO items for sessions that have new output
     const changedIds = new Set(obs.changes.map((c) => c.sessionId));
     return obs.sessions.map((snap) => {
@@ -115,6 +125,14 @@ export function buildSessionStates(obs) {
         else {
             todoSummary = todoCache.get(s.id);
         }
+        let contextTokens;
+        if (changedIds.has(s.id)) {
+            contextTokens = parseContext(snap.output);
+            contextCache.set(s.id, contextTokens);
+        }
+        else {
+            contextTokens = contextCache.get(s.id);
+        }
         return {
             id: s.id,
             title: s.title,
@@ -124,6 +142,7 @@ export function buildSessionStates(obs) {
             lastActivity: lastActivity && lastActivity.length > 100
                 ? lastActivity.slice(0, 97) + "..."
                 : lastActivity,
+            contextTokens,
             todoSummary,
             userActive: snap.userActive ?? false,
         };