@zhuxixi/pi-agent-board 0.3.0

package/README.md

@@ -0,0 +1,131 @@
+# Pi Agent Board
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/zhuxixi/pi-agent-board/main/assets/banner.png" alt="Pi Agent Board" width="100%" />
+</p>
+
+<p align="center">
+  <a href="https://github.com/zhuxixi/pi-agent-board/blob/main/assets/demo.mp4"><strong>30s demo</strong></a>
+  | <a href="https://pi.dev/packages?name=@zhuxixi/pi-agent-board">Pi package gallery</a>
+  | <a href="https://www.npmjs.com/package/@zhuxixi/pi-agent-board">npm</a>
+</p>
+
+Pi Agent Board is a full-screen TUI dashboard for [Pi](https://github.com/earendil-works/pi-mono). It lets you dispatch, monitor, peek/reply to, attach to, and clean up multiple background Pi sessions from one place.
+
+## Problems It Solves
+
+- Run several Pi tasks at once without losing track of which are queued, running, waiting for input, in progress, done, failed, or stopped.
+- Keep real Pi sessions durable and resumable after `/reload`, closing Pi, or restarting the terminal.
+- Check the latest output and answer follow-up questions without interrupting a running session.
+- Attach to the full interactive Pi session only when hands-on work is needed.
+- Manage work across multiple projects in one global board.
+
+## Install
+
+From npm:
+
+```bash
+pi install npm:@zhuxixi/pi-agent-board
+pi /agent-board
+```
+
+You can also start Pi normally and run `/agent-board`.
+
+Pi Agent Board requires Node 20+ and working Pi provider auth. If rows stay in `Running`, first confirm Pi can complete a one-shot model call:
+
+```bash
+pi --mode json -p --no-session "Reply with exactly: DONE"
+```
+
+That command should produce an assistant reply and finish with an `agent_end` event.
+
+From a local checkout:
+
+```bash
+npm install
+pi install "$(pwd)"
+pi /agent-board
+```
+
+For auto-discovery while developing:
+
+```bash
+ln -s "$(pwd)" ~/.pi/agent/extensions/agent-board
+pi
+```
+
+Remove that symlink when you no longer want Pi to auto-load the checkout. If you installed by path, remove it with `pi remove "$(pwd)"`.
+
+## Use
+
+Open the board with `pi /agent-board` or `/agent-board` inside Pi.
+
+- Type a task in the bottom input, then press `enter`.
+- Confirm **Start session**, or adjust `cwd`, model, and thinking level first.
+- Watch rows move through `Queued`, `Running`, `Needs input`, `In Progress`, `Done`, `Failed`, and `Stopped`.
+- Press `space` to peek at the selected row's summary, blocker, and latest output.
+- Press `r` to reply inline without attaching.
+- Press `enter`, `right`, or `>` to attach to the real Pi session.
+- Press `v` for a read-only live transcript.
+- Press `/` to filter by text or state, such as `s:running`.
+- Press `ctrl+r` rename, `ctrl+t` pin, `ctrl+s` stop, `d` mark done, `m` multi-select, `ctrl+x` delete/archive, `X` delete inactive rows in the selected state, and `?` for help.
+
+Rows are stored under `~/.pi/agent/agent-board/` by default. Deleting a row archives it from the board; it does not remove the underlying Pi session file.
+
+## Configuration
+
+Useful environment variables:
+
+| Variable | Use |
+| --- | --- |
+| `AGENT_BOARD_ROOT` | Store location. Defaults to `~/.pi/agent/agent-board/`. |
+| `AGENT_BOARD_AUTO_STATE=off` | Disable automatic terminal-state moves. |
+| `AGENT_BOARD_AUTO_STATE_MODEL=<model>` | Model for classifying finished turns. Defaults to `gpt-4o`; use `off` for heuristic-only. |
+| `AGENT_BOARD_SUMMARY_MODEL=<model>` | Model for short row summaries. Defaults to `gpt-4o`; use `off` to disable. |
+| `AGENT_BOARD_TITLE_MODEL=<model>` | Model for generated session titles. Defaults to `openai-codex/gpt-5.5`; use `off` to disable. |
+| `AGENT_BOARD_TITLE_THINKING_LEVEL=<level>` | Thinking level for title generation. Defaults to `low`; use `off` to omit it. |
+| `AGENT_BOARD_DISABLE_PTY=1` | Disable PTY attach mode. |
+| `AGENT_BOARD_FORCE_PTY=1` | Force PTY attach mode. |
+| `AGENT_BOARD_ATTACH_MOUSE=0` | Disable attach-view mouse handling and use terminal-native selection. |
+| `AGENT_BOARD_WHEEL_LINES=<1-50>` | Lines scrolled per mouse-wheel event in attach view. Defaults to `1`. |
+
+Legacy `AGENT_VIEW_*` variables are still honored for migration.
+
+If the board reports `node-pty unavailable`, press `!` in the dashboard for diagnosis and fix steps.
+
+## Develop
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run pack:dry
+```
+
+Run all checks with:
+
+```bash
+npm run verify
+```
+
+`npm run verify` runs typecheck, tests, and a dry npm pack.
+
+## Publish
+
+Before publishing a new release, bump the package version, run verification, then publish:
+
+```bash
+npm run verify
+npm version patch
+npm publish
+```
+
+If the version is already bumped, skip `npm version patch`.
+
+Use `npm version minor` or `npm version major` instead when the release warrants it. After publish, users install with:
+
+```bash
+pi install npm:@zhuxixi/pi-agent-board
+```
+
+The Pi package gallery uses the `pi.video` and `pi.image` URLs from `package.json`.

package/VERIFY.md

@@ -0,0 +1,113 @@
+# Manual Verification
+
+Steps you can run yourself to check the extension. Grouped from "no auth needed" to
+"needs pi provider auth". Commands assume you're in the repo root.
+
+---
+
+## 0. Static checks (no auth, fast)
+
+```bash
+npm install          # dev + runtime deps
+npm run typecheck    # expect: 0 errors
+npm test             # expect: 0 failures
+npm run pack:dry     # expect: pi-agent-board-<version>.tgz contents only include deploy files
+```
+
+`npm test` includes a hermetic integration test that runs the **real detached runner** against
+a fake pi worker (`test-support/fake-pi.mjs`) — it proves dispatch → events → status/state →
+finalize (completed / needs_input / failed / stopped) without any model/network.
+
+## 1. Does the extension load in pi? (no auth)
+
+```bash
+pi --list-models -e "$(pwd)/src/index.ts"
+```
+Expect a normal model table and **exit 0** (the extension factory ran without throwing). If you
+see an error mentioning `index.ts` / jiti / a missing import, that's a load problem.
+
+## 2. CRITICAL: can pi reach a model at all? (needs pi auth)
+
+This is the thing that was blocked in the dev sandbox. The background worker is just
+`pi --mode json -p --session <file> "<prompt>"`, so first confirm a plain one-shot works:
+
+```bash
+# Should print a JSON event stream that ENDS WITH a line of type "agent_end", then exit
+# within a few seconds. Watch for an "assistant" message_end before agent_end.
+pi --mode json -p --no-session "Reply with exactly: DONE" | tail -n 20
+```
+- ✅ **Healthy:** you see `...message_end (assistant)...`, then `agent_end`, and the command exits.
+- ❌ **Hang:** it prints up to a `message_end` for the **user** message then sits idle (no
+  assistant reply, never exits). That means pi has no working provider auth / network here.
+  Fix pi's auth first:
+  ```bash
+  pi            # then run /login inside pi, or set the provider key pi expects, e.g.
+  # export ANTHROPIC_API_KEY=...   (or OPENAI_API_KEY=... for gpt-4o summaries)
+  ```
+  Re-run the one-shot above until it ends in `agent_end`. The dashboard cannot show live results
+  until this works — it's a pi setup step, independent of this extension.
+
+## 3. Install the extension for normal use
+
+For a local checkout, install it as a Pi package:
+```bash
+pi install "$(pwd)"
+```
+Or symlink the repo into pi's global extensions dir (auto-discovered via the top-level `index.ts`):
+```bash
+ln -s "$(pwd)" ~/.pi/agent/extensions/agent-board
+```
+After publish, install with:
+```bash
+pi install npm:pi-agent-board
+```
+Then start pi normally:
+```bash
+pi
+```
+
+## 4. Drive the dashboard
+
+Inside pi:
+1. Type `/agent-board`, or start with `pi /agent-board` → the full-screen dashboard opens.
+   - With `pi /agent-board`, quitting the dashboard exits Pi instead of dropping you into a normal chat session.
+   - The startup path should feel cleaner than `/agent-board`: no normal Pi header/footer chrome and no dispatch notifications above the dashboard.
+2. Type a task in the bottom input (e.g. `list the files in this repo and summarize the README`), then press **Enter**.
+   - A **Start session** dialog opens with **Start session** focused by default.
+   - Press **Enter** again to launch immediately, or move with **↑/↓** to change **cwd**, **model**, or **thinking** first.
+   - A row appears and moves `Queued → Running → Done` (needs step 2 healthy).
+3. **space** = peek when the input is empty (summary, blocker, latest output); in peek **r** = reply, **a** = attach.
+   **→** / **>** = open a full-screen live session view without interrupting; **←** / **<** returns.
+4. **enter** on an empty input = attach to the selected full session (confirms first if it's still running).
+   You're now in the real Pi session; run `/agent-board` again to return.
+5. Other keys: **/** filter (`s:running`, or free text), **Ctrl+R** rename, **Ctrl+T** pin, **Ctrl+S** stop,
+   **Ctrl+X** delete (archives the row, keeps the session file), **?** help, **Esc** clears input / quits when empty.
+
+## 5. Inspect the durable store on disk
+
+```bash
+ls -R ~/.pi/agent/agent-board
+cat ~/.pi/agent/agent-board/roster.json
+cat ~/.pi/agent/agent-board/views/*/state.json
+cat ~/.pi/agent/agent-board/views/*/runs/*/status.json
+# raw worker event stream for a run:
+cat ~/.pi/agent/agent-board/views/*/runs/*/events.jsonl
+```
+
+## 6. Recovery / persistence
+
+- Start a dispatch, then quit pi (or `/reload`). Re-open pi and `/agent-board` — the row is still
+  there with its last state (rehydrated from disk). If a run's runner died without finishing,
+  the dashboard reconciles it to `failed (runner exited)` on open.
+
+## 7. Same-repo session launches
+
+- Dispatch one task in a git repo, then (while it's running) dispatch a second in the
+  **same repo**. Both launches should be allowed. The extension never creates a git worktree on
+  its own.
+
+## 8. Summary model
+
+Default summary model is **gpt-4o** (override `AGENT_BOARD_SUMMARY_MODEL=<model>`, disable with
+`AGENT_BOARD_SUMMARY_MODEL=off`; legacy `AGENT_VIEW_SUMMARY_MODEL` is also honored). It needs OpenAI auth; without it the row keeps its heuristic
+summary (e.g. the first sentence of the agent's last message or the active tool).

package/docs/BATCH_SELECTION_READ_FLOW.md

@@ -0,0 +1,277 @@
+# Batch Selection + Read/Unread Flow
+
+**Status:** Proposed  
+**Context:** Pi Agent Board dashboard  
+**Created:** 2026-06-02
+
+## Assumption
+
+"Move to done to delete that batch" is treated as a **safe 2-step cleanup flow**:
+
+1. bulk-select sessions,
+2. move them to **Done**,
+3. optionally delete that same batch from **Done** with a second explicit confirmation.
+
+This keeps "done" non-destructive and makes deletion intentional.
+
+---
+
+## 1. Goals
+
+### A. Multi-session selection
+- Let users select multiple rows from the board.
+- Let users batch-mark them as **Done**.
+- Let users immediately clean up that same batch from the **Done** group.
+
+### B. Read / Unread
+- Mark a session as **Read** once the user has actually visited it via attach / transcript-style deep view.
+- Show a **subtle unread hint** on rows with unseen activity.
+- If new activity happens after a visit, the row becomes **Unread** again.
+
+---
+
+## 2. UX overview
+
+### Normal mode
+- Board behaves exactly like today: single active row, peek, attach, done, delete.
+
+### Selection mode
+- User enters a temporary **multi-select mode**.
+- Selection count appears in header/footer: `3 selected`.
+- Rows show a subtle selected marker.
+- Actions become batch-oriented:
+  - **Mark selected done**
+  - **Delete selected** (only from Done, with confirm)
+  - **Clear selection**
+
+### Read state
+- Rows can be either:
+  - **Unread** = new activity since last visit
+  - **Read** = user has already visited the latest activity
+- Unread should not overpower semantic state; it is a secondary signal.
+
+---
+
+## 3. Multi-session selection flow
+
+## 3.1 Enter selection mode
+
+**Trigger**
+- User presses a dedicated shortcut from board list view.
+- Suggested shortcut: `m` for **multi-select**.
+
+**Result**
+- Footer changes to selection hints.
+- Selection starts empty; the current row stays focused but is **not** auto-selected.
+- Header shows selection count.
+
+---
+
+## 3.2 Build the selection
+
+While in selection mode:
+- `↑ / ↓` moves cursor
+- `space` toggles current row in selection
+- `a` selects all visible rows in current filter/group
+- `u` clears the current selection without leaving selection mode
+- `esc` clears selection and exits selection mode
+
+Optional later:
+- `A` = select all rows in current state group
+- `u` = unselect all
+
+---
+
+## 3.3 Move selected rows to Done
+
+**Trigger**
+- User presses `d` while in selection mode.
+
+**Confirmation copy**
+- `Mark 5 selected sessions as done? (y/N)`
+
+**Rules**
+- Running/live rows are skipped.
+- Needs-input / idle / failed / stopped rows may be moved to Done.
+- Confirmation should mention skipped rows if any.
+
+**Result**
+- Matching rows are moved to `Done`.
+- The same rows remain selected.
+- Board auto-scrolls/focuses to the `Done` section.
+- Toast example: `Moved 5 to Done · skipped 2 live`
+
+This preserves the batch as a temporary working set for cleanup.
+
+---
+
+## 3.4 Delete the same batch from Done
+
+**Trigger**
+- With the same batch still selected, user presses `ctrl+x` or a batch delete key.
+
+**Guardrail**
+- Deletion is only enabled when all selected rows are already in `Done`.
+- If selection includes non-Done rows, show: `Only Done sessions can be batch deleted`.
+
+**Confirmation copy**
+- `Delete 5 done sessions? Session files are preserved. (y/N)`
+
+**Result**
+- Selected rows are archived from dashboard.
+- Selection clears.
+- Toast example: `Deleted 5 done sessions`
+
+---
+
+## 4. Read / Unread flow
+
+## 4.1 What counts as Read
+
+A session becomes **Read** when the user intentionally opens that session in a deeper way:
+- attach via `enter` / `→`
+- transcript/full-session view
+
+**Not read by default:**
+- merely highlighting a row
+- passive polling updates
+- quick list navigation
+- optional: peek can remain non-read to preserve signal
+
+---
+
+## 4.2 When a row becomes Unread again
+
+A previously read row becomes **Unread** when a new assistant reply lands after the last visit, for example:
+- new assistant message
+- new blocker/question raised in that message
+- session re-enters `needs_input` because of that message
+
+User-authored actions alone should not create unread state, and intermediate tool churn alone should not flip unread.
+
+---
+
+## 4.3 Recommended subtle hint
+
+Use the **stage icon itself** as the unread signal:
+- **Unread:** stronger/heavier variant of that stage icon
+- **Read:** lighter/default variant of that stage icon
+
+Examples:
+- queued: `○` → `◎`
+- needs input: `◇` → `◆`
+- done: `✓` → `✔`
+
+Optional secondary treatment:
+- unread row title slightly brighter
+- read row title normal
+
+Avoid:
+- loud badges like `UNREAD`
+- full-row highlight
+- strong color conflict with semantic states like Failed / Needs input
+
+### Priority of signals
+1. semantic state (Running, Needs input, Done, Failed)
+2. selection state
+3. unread hint
+
+Unread should help scanning, not dominate the board.
+
+---
+
+## 5. State model
+
+## 5.1 Batch selection
+
+Selection can stay **ephemeral UI state** in the dashboard component:
+- `selectedIds: Set<string>`
+- `selectionMode: boolean`
+
+No persistence needed for V1.
+
+## 5.2 Read state
+
+Recommended durable fields:
+- `lastVisitedAt: number | null`
+- `lastAgentActivityAt: number | null`
+
+Derived flag:
+- `isUnread = lastAgentActivityAt > lastVisitedAt`
+
+This is simpler and more reliable than storing a raw boolean.
+
+---
+
+## 6. Edge cases
+
+### Live rows inside a batch
+- Cannot be batch-done or batch-deleted.
+- Skip and report counts.
+
+### Mixed-state selection
+- Batch done: allowed for inactive non-done rows.
+- Batch delete: only allowed if every selected row is already Done.
+
+### New activity during selection
+- Keep row selected.
+- If it receives new output, unread hint can appear even while selected.
+
+### Re-attaching to a row
+- Refresh `lastVisitedAt`.
+- Any prior unread marker clears.
+
+### Peek behavior
+- Recommend: peek does **not** mark read.
+- Reason: peek is triage, attach/transcript is actual visit.
+
+---
+
+## 7. Suggested implementation slices
+
+### Dashboard (`src/ui/dashboard.ts`)
+- add selection mode
+- add `selectedIds`
+- batch confirm flows
+- render selected marker + unread marker
+
+### Service (`src/runtime/service.mjs`)
+- add `markCompletedMany(viewIds)`
+- add `archiveMany(viewIds)`
+- add `markVisited(viewId)`
+
+### Store/types (`src/core/types.mjs`, `src/core/store.mjs`)
+- add read-tracking timestamps
+- expose unread derivation on rows
+
+### Attach / session view entry points
+- mark row visited when attach or transcript view opens
+
+---
+
+## 8. Recommended default interaction summary
+
+### Batch
+- `m` enter multi-select
+- `space` toggle row
+- `a` select all visible
+- `u` clear selection
+- `d` move selected to Done
+- `ctrl+x` delete selected Done batch
+- `esc` clear/exit
+
+### Read state
+- attach / transcript => mark read
+- new assistant reply => unread again
+- unread indicator => subtle left dot/bar
+
+---
+
+## 9. Acceptance criteria
+
+- User can select multiple sessions from the board.
+- User can mark that selection Done in one action.
+- User can immediately delete that same batch from Done with explicit confirmation.
+- A session becomes Read after attach/transcript visit.
+- New agent activity turns a previously read row back to Unread.
+- Unread is visible through a subtle row hint, not a loud badge.