pi-pier 0.2.4 → 0.2.5

package/README.md

@@ -43,10 +43,9 @@ The installer also verifies node / pi / herdr versions, probes local paths, and
 | Tool | Purpose |
 |---|---|
 | `todo_write` | Full-replacement todo list. Session JSONL is the single source of truth; correct rollback on branch switches. Projected live onto the pane title (`▶i ○p ■b ✓c (N/M) · current task`). `/todos` command to view/edit/unblock |
-| `subagent` | Delegate self-contained subtasks to an isolated pi session in its own herdr pane (separate context window). Foreground / parallel / background modes |
-| `list_agents` | Live state of background subagents (running / idle + panes) |
-| `send_message` | Follow-up work for a subagent (queued if busy, wakes if idle) |
-| `interrupt_agent` | Stop a subagent's current turn; it stays alive for more messages |
+| `subagent` | Delegate self-contained subtasks to an isolated pi session in its own herdr pane. Actions: `spawn` (default; foreground / parallel / background), `list`, `send`, `interrupt`, `resume` |
+| `terminal` | Persistent interactive shells in dedicated herdr panes. Actions: `open`, `send`, `read`, `signal`, `close`, `list` |
+| `ask_user_question` | Human gate: pane shows blocked in herdr while waiting |
 
 ### Behaviors
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pier",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "pier: pi extension that fuses pi agent sessions with the herdr pane/tab orchestrator — todo_write loop closure + interactive subagents in isolated panes",
   "license": "MIT",
   "type": "module",

package/skills/pi-herdr-workflow/SKILL.md

@@ -2,8 +2,9 @@
 name: pi-herdr-workflow
 description: >-
   How to use the pi-herdr workbench fusion: todo_write discipline, subagent
-  delegation (foreground/parallel/background), list_agents/send_message/
-  interrupt_agent, and how the human watches everything in herdr panes.
+  delegation (foreground/parallel/background via action spawn/list/send/
+  interrupt/resume), terminal persistent shells, and how the human watches
+  everything in herdr panes.
   Load when the user asks about multi-step plans, delegating subtasks,
   background work, or checking on running subagents.
 license: MIT
@@ -35,34 +36,57 @@ rolls up to the sidebar.
 
 A subagent pane is an **interactive pi TUI** (independent session). A human can enter that pane and talk to it at any time. Your delegation prompt appears as a message in its conversation.
 
-### Mode
+The `subagent` tool has 5 operations controlled by the `action` parameter (default: `spawn`):
 
+### spawn (default action)
+
+Create a subagent in a new pane:
 - **Foreground** (default): the call waits for a result. Use when the next step depends on it.
 - **Background** (`run_in_background: true`): returns `agentId` immediately; the subagent keeps running in its own pane. Use for long / parallel work. It **persists** (own session). On settle you get a "Background subagent <id> finished..." notice.
-- Multiple `subagent` calls in one message run in parallel (cap 4).
-- Optional `role` (e.g. `advisor`) is a label only: v1 does not change tools or lifecycle; TTL is the same as `task`. Omit = `task`. Revive with `resume_subagent`; do not assume the pane comes back by itself.
-
-### Task-tab grouping (`tab`)
+- Multiple `subagent` calls (with `action: "spawn"`) in one message run in parallel (cap 4).
+- Optional `role` (e.g. `advisor`) matches a profile when found; unknown names are labels only.
 
+**Task-tab grouping** (`tab`):
 - Each delegation defaults to a **new tab named from `description`**.
 - Related subtasks share one `tab` name (e.g. web research + status probe both `tab: "research"`) so the human sees every related pane in one herdr tab.
 - Keep names short (≤20 chars) and obvious; the tab bar *is* the task board.
 - Do not cram unrelated work into one tab to "save tabs". One tab = one goal.
-- **Task tabs are temporary**: after every subagent in the tab has settled (default grace ~10 minutes) the tab closes. Do not assume those panes last. To review or continue, `resume_subagent(taskId)` from history — do not cite a closed pane.
-
-### Prompt discipline
+- **Task tabs are temporary**: after every subagent in the tab has settled (default grace ~10 minutes) the tab closes. Do not assume those panes last. To review or continue, use `action: "resume"` from history — do not cite a closed pane.
 
+**Prompt discipline**:
 - The prompt must be **self-contained**: the subagent cannot see your conversation, only this prompt.
 - State inputs (which files / facts), outputs (what to deliver), and bounds (what not to touch).
 - Share context via files / artifacts. Do not dump large blobs into the prompt.
 - Delegate only independent work; dependent steps go to the same subagent.
 
-### After a background spawn
+### list
+
+Show all background subagents with status (`running` / `idle` / `blocked`), `agentId`, and last activity.
+
+Call: `subagent(action: "list")`
+
+### send
+
+Append follow-up message to background subagent:
+- If working: delivered at next tool-gap (steering, seconds).
+- If idle: wakes for new turn.
+- After settle, `send` to wake it; do not spawn duplicate.
+
+Call: `subagent(action: "send", agentId: "<id>", message: "...")`
+
+### interrupt
+
+Abort subagent's current turn (fire-and-return). Pane stays; can `send` again.
+
+Call: `subagent(action: "interrupt", agentId: "<id>")`
 
-- `list_agents`: all background subagents and status (`running` / `idle`).
-- `send_message(agentId, message)`: append work (FIFO; a settled subagent is woken).
-- `interrupt_agent(agentId)`: abort the current turn (the pane stays; you can `send_message` again).
-- After settle, if you have more work for that same `agentId`, `send_message` to wake it; do not spawn a duplicate.
+### resume
+
+Revive finished subagent from ledger by `taskId`. Opens saved conversation in new pane; then `send` work.
+
+The ledger is an append-only JSONL file at `~/.pi/agent/herdr-pi/history/<flattened-cwd>/history.jsonl`, one row per status change. Use `list` for live panes from this session; for tasks from earlier sessions or closed panes, read/grep the ledger for the `taskId`.
+
+Call: `subagent(action: "resume", taskId: "<uuid>")`
 
 ## 3. Human gate
 
@@ -75,3 +99,60 @@ A subagent pane is an **interactive pi TUI** (independent session). A human can
 - Independent review for critical conclusions (a different subagent as reviewer). Do not trust a single worker blindly.
 - Homogeneous parallel workers make the same mistakes: give them different bounds and output shapes.
 - After delegating, keep doing your own work. Do not idle-wait (except a foreground call).
+
+## 5. Terminal management (master only)
+
+The `terminal` tool has 6 operations for persistent shell sessions (dev servers, REPLs, stateful work):
+
+### open
+
+Create a persistent interactive terminal (resident shell in its own herdr pane) and return its `terminal_id`.
+
+The shell keeps its cwd, environment variables, and background processes across `terminal` calls — use it for dev servers, REPLs, or multi-step shell work instead of one-shot bash calls.
+
+Call: `terminal(action: "open", cwd: "<path>")`
+Returns: `terminal_id` and readiness status (prompt detected or busy).
+
+### send
+
+Send a text command (plain text only, no ANSI escapes) to a persistent terminal; Enter is appended automatically.
+
+Returns after the keystrokes are delivered — poll with `action: "read"` for output (long-running commands keep producing output across reads).
+
+Call: `terminal(action: "send", terminal_id: "<id>", text: "npm run dev")`
+
+### read
+
+Read new output from a persistent terminal since your last read (cursor-based increment; the first read returns the recent buffer).
+
+Parameters:
+- `terminal_id`: your terminal from `open`. Alternatively `pane_id`: a pane in this session's own tab (narrow scope by design).
+- `max_chars`: output cap for this read.
+
+Output is ANSI-stripped and bounded; if the buffer scrolled past your last read you get a reset marker plus the current tail. Detecting a fullscreen TUI program (vim/less/top) returns an error with suggestions instead of garbage.
+
+Call: `terminal(action: "read", terminal_id: "<id>")`
+
+### signal
+
+Send a control key to a persistent terminal: ctrl+c (interrupt), ctrl+d (EOF), ctrl+z (suspend), esc, enter.
+
+Use ctrl+c to stop a running command; anything beyond this whitelist is outside the terminal seam.
+
+Call: `terminal(action: "signal", terminal_id: "<id>", key: "ctrl+c")`
+
+### close
+
+Close a persistent terminal (kills its shell process tree and removes the pane).
+
+Terminal state does not survive close — persist anything you need to files first.
+
+Call: `terminal(action: "close", terminal_id: "<id>")`
+
+### list
+
+List this session's persistent terminals with open/closed and pane-liveness status.
+
+Entries whose pane is gone (human closed it, restart) are marked closed — terminal sessions do not survive pane closure or restarts; persist state to files instead of relying on terminal reuse.
+
+Call: `terminal(action: "list")`