jb/pi-interactive-subagents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Amos
2026-06-26 22:25:19 +03:00
commit c6c00f89a7
29 changed files with 14358 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+3
View File
@@ -0,0 +1,3 @@
node_modules/
config.json
.DS_Store
LICENSE
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 HazAT
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
README.md
+502
View File
@@ -0,0 +1,502 @@
# pi-interactive-subagents
Async subagents for [pi](https://github.com/badlogic/pi-mono) — spawn, orchestrate, and manage sub-agent sessions in multiplexer panes. **Fully non-blocking** — the main agent keeps working while subagents run in the background.
https://github.com/user-attachments/assets/30adb156-cfb4-4c47-84ca-dd4aa80cba9f
## How It Works
Call `subagent()` and it **returns immediately**. The sub-agent runs in its own terminal pane. A live widget above the input shows all running agents with their current state — `starting`, `active`, `waiting`, `stalled`, or `running`. When a sub-agent finishes, its result is **steered back** into the main session as an async notification — triggering a new turn so the agent can process it.
```
╭─ Subagents ──────────────────────────── 2 running ─╮
│ 00:23 Scout: Auth (scout) active · bash 7m │
│ 00:45 Scout: DB (scout) waiting 2m │
╰────────────────────────────────────────────────────╯
```
For parallel execution, just call `subagent` multiple times — they all run concurrently:
```typescript
subagent({ name: "Scout: Auth", agent: "scout", task: "Analyze auth module" });
subagent({ name: "Scout: DB", agent: "scout", task: "Map database schema" });
// Both return immediately, results steer back independently
```
## Install
```bash
pi install git:github.com/HazAT/pi-interactive-subagents
```
Supported multiplexers:
- [cmux](https://github.com/manaflow-ai/cmux)
- [tmux](https://github.com/tmux/tmux)
- [zellij](https://zellij.dev)
- [WezTerm](https://wezfurlong.org/wezterm/) (terminal emulator with built-in multiplexing)
Start pi inside one of them:
```bash
cmux pi
# or
tmux new -A -s pi 'pi'
# or
zellij --session pi # then run: pi
# or
# just run pi inside WezTerm — no wrapper needed
```
Optional: set `PI_SUBAGENT_MUX=cmux|tmux|zellij|wezterm` to force a specific backend.
If your shell startup is slow and subagent commands sometimes get dropped before the prompt is ready, set `PI_SUBAGENT_SHELL_READY_DELAY_MS` to a higher value (defaults to `500`):
```bash
export PI_SUBAGENT_SHELL_READY_DELAY_MS=2500
```
Subagent panes are created without stealing keyboard focus (cmux, tmux). Launch commands target child surfaces by explicit ID, so focus and command delivery are independent. Note: the `interactive` option controls parent status notifications, not terminal focus.
## What's Included
### Extensions
**Subagents** — 4 main-session tools + 3 commands, plus 1 subagent-only tool:
| Tool | Description |
| -------------------- | ------------------------------------------------------------------------------------------- |
| `subagent` | Spawn a sub-agent in a dedicated multiplexer pane (async — returns immediately) |
| `subagent_interrupt` | Interrupt a running Pi-backed subagent's current turn |
| `subagents_list` | List available agent definitions |
| `subagent_resume` | Resume a previous sub-agent session (async) |
| Command | Description |
| -------------------------- | ------------------------------------ |
| `/plan` | Start a full planning workflow |
| `/iterate` | Fork into a subagent for quick fixes |
| `/subagent <agent> <task>` | Spawn a named agent directly |
### Bundled Agents
| Agent | Model | Role |
| ----------------- | ---------------------- | ---------------------------------------------------------------------------------------- |
| **planner** | Opus (medium thinking) | Brainstorming — clarifies requirements, explores approaches, writes plans, creates todos |
| **scout** | Haiku | Fast codebase reconnaissance — maps files, patterns, conventions |
| **worker** | Sonnet | Implements tasks from todos — writes code, runs tests, makes polished commits |
| **reviewer** | Opus (medium thinking) | Reviews code for bugs, security issues, correctness |
| **visual-tester** | Sonnet | Visual QA via Chrome CDP — screenshots, responsive testing, interaction testing |
Agent discovery follows priority: **project-local** (`.pi/agents/`) > **global** (`~/.pi/agent/agents/`) > **package-bundled**. Override any bundled agent by placing your own version in the higher-priority location.
---
## Async Subagent Flow
```
1. Agent calls subagent() → returns immediately ("started")
2. Sub-agent runs in mux pane → widget shows live status
3. User keeps chatting → main session fully interactive
4. Sub-agent finishes → result steered back as a normal completion/failure
5. Main agent processes result → continues with new context
```
Multiple subagents run concurrently — each steers its result back independently as it finishes. The live widget above the input tracks all running agents:
```
╭─ Subagents ───────────────────────────────── 3 running ─╮
│ 01:23 Scout: Auth (scout) active · write 7m │
│ 00:45 Researcher (researcher) stalled 4m │
│ 00:12 Scout: DB (scout) starting… │
╰─────────────────────────────────────────────────────────╯
```
Completion messages render with a colored background and are expandable with `Ctrl+O` to show the full summary and session file path.
### In-progress status updates
The widget tracks each Pi-backed sub-agent from a child-written runtime snapshot and labels it with a coarse state:
- `starting` — launched, but no valid child snapshot has been observed yet
- `active` — the child is doing observed runtime work: agent turn, provider request, streaming, or tool execution
- `waiting` — the child finished a turn and is intentionally open for more input or another stage
- `stalled` — the parent has gone too long without a valid current child snapshot and can no longer trust the run is healthy
- `running` — fallback for backends without child snapshots (e.g. Claude)
These labels are no longer derived from session-file growth. Session JSONL is still used for transcript, resume, lineage, and result extraction, but Pi-backed liveness now comes from a small activity snapshot written by the child extension. A fixed internal watchdog marks a run as `stalled` when valid snapshots never appear, stop being readable, or stop matching the current child; valid long-running `active` or `waiting` states do not become `stalled` just because time passes. When a run enters `stalled` or recovers from it, the parent agent receives a steer message so it can react. All other status transitions stay in the widget only.
**Interactive subagents stay silent.** Long-running user-driven subagents (e.g. `planner`, or any `/iterate` fork) do not wake the parent session on `stalled`/`recovered` transitions — the user is working directly in the subagent's pane, and a steer message there would just burn an orchestrator turn on a no-op "still waiting" ping. The widget still updates normally, and child snapshots are still recorded/classified regardless of the `interactive` setting. By default, agents with `auto-exit: true` are treated as autonomous and get stall pings; agents without it are treated as interactive and stay quiet. Override per-agent with `interactive: true|false` in frontmatter, or per-spawn with `interactive: true|false` on the tool call.
#### Configuration
Status display is controlled by `config.json` in the extension directory. Copy `config.json.example` to get started:
```bash
cp config.json.example config.json
```
```json
{
"status": {
"enabled": true
}
}
```
`config.json` is gitignored so local overrides don't get committed.
---
## Spawning Subagents
```typescript
// Named agent with defaults from agent definition
subagent({ name: "Scout", agent: "scout", task: "Analyze the codebase..." });
// Force a full-context fork for this spawn
subagent({ name: "Iterate", fork: true, task: "Fix the bug where..." });
// Agent defaults can choose a different session-mode via frontmatter
subagent({ name: "Planner", agent: "planner", task: "Work through the design with me" });
// Custom working directory
subagent({ name: "Designer", agent: "game-designer", cwd: "agents/game-designer", task: "..." });
```
### Parameters
| Parameter | Type | Default | Description |
| ---------------------- | ------- | -------------- | ------------------------------------------------------------------------------------------------- |
| `name` | string | required | Display name (shown in widget and pane title) |
| `task` | string | required | Task prompt for the sub-agent |
| `agent` | string | — | Load defaults from agent definition |
| `fork` | boolean | `false` | Force the full-context fork mode for this spawn, overriding any agent `session-mode` frontmatter |
| `interactive` | boolean | derived | Mark this spawn as interactive (don't wake the parent on stall/recovery). Defaults to the agent's `interactive` frontmatter, otherwise the inverse of `auto-exit`. |
| `model` | string | — | Override agent's default model |
| `systemPrompt` | string | — | Append to system prompt |
| `skills` | string | — | Comma-separated skill names |
| `tools` | string | — | Comma-separated tool names |
| `cwd` | string | — | Working directory for the sub-agent (see [Role Folders](#role-folders)) |
---
## Interrupting a running subagent
Use `subagent_interrupt` to cancel the active turn of a running Pi-backed subagent:
```typescript
subagent_interrupt({ id: "abcd1234" });
// or
subagent_interrupt({ name: "Scout" });
```
This sends Escape to the child pane, cancelling the in-progress model turn. The subagent session stays alive — the pane, session file, and background polling all remain intact. After the interrupt, the widget immediately moves the child back to `waiting`, and stale pre-interrupt snapshots are ignored. If the child starts work later, newer snapshots return it to `active`; completion, failure, and `caller_ping` still flow through normally.
This is a turn-level interrupt, not a method for forcibly terminating a subagent session.
> **Note:** Only Pi-backed subagents are supported. Claude-backed runs will return an error.
---
## caller_ping — Child-to-Parent Help Request
The `caller_ping` tool lets a subagent request help from its parent agent. When called, the child session **exits** and the parent receives a notification with the help message. The parent can then **resume** the child session with a response using `subagent_resume`.
**`caller_ping` parameters:**
- `message` (required): What you need help with
**`subagent_resume` parameters:**
- `sessionPath` (required): Path to the child session `.jsonl` file
- `name` (optional): Display name for the resumed pane (defaults to `Resume`)
- `message` (optional): Follow-up prompt to send after resuming
- `autoExit` (optional): Whether the resumed session should auto-exit after its next response. Defaults to `true` for autonomous follow-up work; set `false` when resuming for an interactive handoff.
**Interaction flow:**
1. Child calls `caller_ping({ message: "Not sure which schema to use" })`
2. Child session exits (like `subagent_done`)
3. Parent receives a steer notification: *"Sub-agent Worker needs help: Not sure which schema to use"*
4. Parent resumes the child session via `subagent_resume` with the response
5. Child picks up where it left off with the parent's guidance
**Example:**
```typescript
// Inside a worker subagent
await caller_ping({
message: "Found two conflicting migration files — should I use v1 or v2?"
});
// Session exits here. Parent receives the ping, then resumes this session
// with guidance like "Use v2, v1 is deprecated"
```
> **Note:** `caller_ping` is only available inside subagent contexts. Calling it from a standalone pi session returns an error.
---
## The `/plan` Workflow
The `/plan` command orchestrates a full planning-to-implementation pipeline.
```
/plan Add a dark mode toggle to the settings page
```
```
Phase 1: Investigation → Quick codebase scan
Phase 2: Planning → Interactive planner subagent (user collaborates)
Phase 3: Review Plan → Confirm todos, adjust if needed
Phase 4: Execute → Scout + sequential workers implement todos
Phase 5: Review → Reviewer subagent checks all changes
```
Tab/window titles update to show current phase:
```
🔍 Investigating: dark mode → 💬 Planning: dark mode
→ 🔨 Executing: 1/3 → 🔎 Reviewing → ✅ Done
```
---
## The `/iterate` Workflow
For quick, focused work without polluting the main session's context.
```
/iterate Fix the off-by-one error in the pagination logic
```
This always forks the current session into a subagent with full conversation context. It does not inherit an agent default `session-mode`. Make the fix, verify it, and exit to return. The main session gets a summary of what was done.
---
## Custom Agents
Place a `.md` file in `.pi/agents/` (project) or `~/.pi/agent/agents/` (global):
```markdown
---
name: my-agent
description: Does something specific
model: anthropic/claude-sonnet-4-6
thinking: minimal
tools: read, bash, edit, write
session-mode: lineage-only
spawning: false
---
# My Agent
You are a specialized agent that does X...
```
### Frontmatter Reference
| Field | Type | Description |
| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | Agent name (used in `agent: "my-agent"`) |
| `description` | string | Shown in `subagents_list` output |
| `model` | string | Default model (e.g. `anthropic/claude-sonnet-4-6`) |
| `thinking` | string | Thinking level: `minimal`, `medium`, `high` |
| `tools` | string | Comma-separated **native pi tools only**: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls` |
| `skills` | string | Comma-separated skill names to auto-load |
| `session-mode` | string | Default child-session mode: `standalone`, `lineage-only`, or `fork` |
| `spawning` | boolean | Set `false` to deny all subagent-spawning tools |
| `deny-tools` | string | Comma-separated extension tool names to deny |
| `auto-exit` | boolean | Auto-shutdown when the agent finishes its turn — no `subagent_done` call needed. If the user sends any input, auto-exit is permanently disabled and the user takes over the session. Recommended for autonomous agents (scout, worker); not for interactive ones (planner). Also determines the default value of `interactive` (see below). |
| `interactive` | boolean | derived | Override whether stall/recovery transitions wake the parent session. Defaults to the inverse of `auto-exit`: autonomous agents (`auto-exit: true`) are non-interactive and get stall pings; agents without `auto-exit` are interactive and stay quiet. Explicit values take precedence. |
| `cwd` | string | Default working directory (absolute or relative to project root) |
| `disable-model-invocation` | boolean | Hide this agent from discovery surfaces like `subagents_list`. The agent still remains directly invokable by explicit name via `subagent({ agent: "name", ... })`. |
---
Discovery still resolves precedence before visibility filtering. If a project-local hidden agent has the same name as a visible global or bundled agent, the hidden project agent wins and the lower-precedence agent does not appear in `subagents_list`.
### `session-mode`
Choose how a subagent session starts:
- `standalone` — default fresh session with no lineage link to the caller
- `lineage-only` — fresh blank child session with `parentSession` linkage, but no copied turns from the caller
- `fork` — linked child session seeded with the caller's prior conversation context
`lineage-only` is useful when you want session discovery and fork lineage UX to show the relationship later, but you do **not** want the child to inherit the parent's turns.
`fork: true` on the tool call always forces the `fork` mode for that specific spawn. `/iterate` uses this explicit override on purpose.
```yaml
---
name: planner
session-mode: lineage-only
---
```
### `auto-exit`
When set to `true`, the agent session shuts down automatically as soon as the agent finishes its turn — no explicit `subagent_done` call is needed.
**Behavior:**
- The session closes after the agent's final message (on the `agent_end` event)
- If the user sends **any input** before the agent finishes, auto-exit is permanently disabled for that session — the user takes over interactively
- The modeHint injected into the agent's task is adjusted accordingly: autonomous agents see "Complete your task autonomously." rather than instructions to call `subagent_done`
**When to use:**
- ✅ Autonomous agents (scout, worker, reviewer) that run to completion
- ❌ Interactive agents (planner, iterate) where the user drives the session
```yaml
---
name: scout
auto-exit: true
---
```
### `interactive`
Controls whether status transitions (`stalled`, `recovered`) wake the parent session with a steer message.
**Default:** the inverse of `auto-exit`. Autonomous agents (`auto-exit: true`) are non-interactive and ping the parent on stall/recovery; agents without `auto-exit` are interactive and stay quiet. Bare spawns with no agent defs (e.g. `/iterate` with `fork: true`) are treated as interactive.
**Why it exists:** Interactive agents can run for minutes or hours while the user thinks, types, and reads in the subagent's pane. Child snapshots still update the widget, but stalled/recovered supervision messages rarely need to wake the parent for user-driven sessions. Skipping the steer keeps the parent quiet until the child actually finishes.
**When to override:**
- Set `interactive: false` on an agent that doesn't auto-exit but you still want stall pings for
- Set `interactive: true` on an autonomous agent you'd rather check on yourself
```yaml
---
name: planner
# interactive defaults to true because auto-exit is not set
---
```
Or per spawn:
```typescript
subagent({ name: "Scout", agent: "scout", interactive: true, task: "..." });
```
---
## Tool Access Control
By default, every sub-agent can spawn further sub-agents. Control this with frontmatter:
### `spawning: false`
Denies all subagent lifecycle tools (`subagent`, `subagent_interrupt`, `subagents_list`, `subagent_resume`):
```yaml
---
name: worker
spawning: false
---
```
### `deny-tools`
Fine-grained control over individual extension tools:
```yaml
---
name: focused-agent
deny-tools: subagent
---
```
### Recommended Configuration
| Agent | `spawning` | Rationale |
| ---------- | ----------- | -------------------------------------------- |
| planner | _(default)_ | Legitimately spawns scouts for investigation |
| worker | `false` | Should implement tasks, not delegate |
| researcher | `false` | Should research, not spawn |
| reviewer | `false` | Should review, not spawn |
| scout | `false` | Should gather context, not spawn |
---
## Role Folders
The `cwd` parameter lets sub-agents start in a specific directory with its own configuration:
```
project/
├── agents/
│ ├── game-designer/
│ │ └── CLAUDE.md ← "You are a game designer..."
│ ├── sre/
│ │ ├── CLAUDE.md ← "You are an SRE specialist..."
│ │ └── .pi/skills/ ← SRE-specific skills
│ └── narrative/
│ └── CLAUDE.md ← "You are a narrative designer..."
```
```typescript
subagent({ name: "Game Designer", cwd: "agents/game-designer", task: "Design the combat system" });
subagent({ name: "SRE", cwd: "agents/sre", task: "Review deployment pipeline" });
```
Set a default `cwd` in agent frontmatter:
```yaml
---
name: game-designer
cwd: ./agents/game-designer
spawning: false
---
```
---
## Tools Widget
Every sub-agent session displays a compact tools widget showing available and denied tools. Toggle with `Ctrl+J`:
```
[scout] — 12 tools · 4 denied (Ctrl+J) ← collapsed
[scout] — 12 available (Ctrl+J to collapse) ← expanded
read, bash, edit, write, todo, ...
denied: subagent, subagents_list, ...
```
---
## Requirements
- [pi](https://github.com/badlogic/pi-mono) — the coding agent
- One supported multiplexer:
- [cmux](https://github.com/manaflow-ai/cmux)
- [tmux](https://github.com/tmux/tmux)
- [zellij](https://zellij.dev)
- [WezTerm](https://wezfurlong.org/wezterm/)
```bash
cmux pi
# or
tmux new -A -s pi 'pi'
# or
zellij --session pi # then run: pi
# or
# just run pi inside WezTerm
```
Optional backend override:
```bash
export PI_SUBAGENT_MUX=cmux # or tmux, zellij, wezterm
```
---
## Acknowledgements
The sub-agent status supervision and turn-only interruption features were inspired by [RepoPrompt](https://repoprompt.com/)'s sub-agent snapshot polling and run cancellation features.
---
## License
MIT
agents/claude-code.md
+23
View File
@@ -0,0 +1,23 @@
---
name: claude-code
description: Self-driving Claude Code session for deep investigation, experimentation, and code exploration
cli: claude
model: sonnet
auto-exit: true
spawning: false
deny-tools: claude
---
# Claude Code
You are a self-driving Claude Code session spawned by pi for hands-on investigation and experimentation.
You have full autonomy: bash, file access, git clone, code editing, running tests, building projects — everything a developer can do in a terminal.
## Guidelines
- Focus on the task given to you
- Be thorough in your investigation
- Report concrete findings with evidence (file paths, command output, test results)
- If you get stuck, explain what you tried and what failed
- Your final message should summarize what you accomplished and what you found
agents/planner.md
+547
View File
@@ -0,0 +1,547 @@
---
name: planner
description: Interactive planning agent - clarifies WHAT to build and figures out HOW. Lightweight requirements engineering, approach exploration, design validation, premortem, plan + todos. Can spawn scouts/researchers mid-session when it needs facts.
model: anthropic/claude-opus-4-6
thinking: medium
system-prompt: append
---
# Planner Agent
You are a **specialist in an orchestration system**. You were spawned for one purpose — turn a user's request into a concrete plan and todos a worker can execute. You clarify **WHAT** we're building (lightly — just enough to eliminate ambiguity) and design **HOW** to build it. Then you exit.
**Your deliverable is a PLAN and TODOS. Not implementation.**
You may write throwaway code to validate an idea. You never implement the feature itself — that's for workers.
---
## 🚨 HARD RULES — VIOLATING THESE MEANS YOU FAILED
### Rule 1: You are INTERACTIVE — one phase per message
You operate in a **conversation loop** with the user. Each message you send covers ONE phase (or one sub-section of a phase), then you **end your message and wait for the user to reply**.
**Your turn structure:**
1. Do the work for the current step (investigate, analyze, draft, ask)
2. Present your output
3. Ask one clear question
4. **END YOUR MESSAGE. STOP GENERATING. WAIT.**
You must receive user input before advancing. No exceptions.
**If you catch yourself writing "I'll assume...", "Moving on to...", "Let me implement..." — STOP. Delete it. End the message at the question.**
### Rule 2: No skipping phases
**You MUST follow all phases.** Your judgment that something is "simple" or "obvious" is NOT sufficient to skip steps. Even a counter app gets the full treatment.
The ONLY exception: the user explicitly says *"skip the plan"*, *"just do it quickly"*, or *"I don't want a full planning session"*.
You will be tempted to skip. That's exactly when the process matters most.
### Rule 3: You NEVER implement the feature
You do not:
- Write production code
- Install packages (unless validating an approach in a throwaway script)
- Edit source files that are part of the deliverable
- Run builds/tests against the feature
You DO:
- Write the `plan.md` artifact
- Create todos
- Optionally run a throwaway script or read files to validate an approach
### Rule 4: Keep requirements engineering LIGHTWEIGHT
You are not a dedicated spec agent. You clarify intent and requirements **only enough to eliminate meaningful ambiguity** before planning. Don't drag the user through 10 rounds of multiple-choice when 2 rounds would do.
**Rule of thumb:** If you could explain the feature to a stranger and they'd build roughly the right thing, you have enough. Stop asking and start planning.
### Rule 5: Delegate when you hit a factual gap
You have two specialist agents available — use them when a fact (not a preference) is blocking a decision:
- **`scout`** — for codebase facts ("how does auth work today?", "what patterns exist for X?")
- **`researcher`** — for external knowledge ("current best practices for X", "tradeoffs between library A and B")
Don't delegate for user-preference questions — those you ask the user. Don't delegate when you can answer from existing context. See the **Delegation** section below.
---
## The Flow
```
Phase 1: Investigate Context → quick orientation, maybe pre-flight scout
⏸️ END — share what you see
↓
Phase 2: Understand Intent → reverse-engineer the request
⏸️ END — confirm or correct
↓
Phase 3: Clarify Requirements → only what's genuinely ambiguous
⏸️ END — wait for answers
(repeat until ambiguity is gone — usually 1-2 rounds)
↓
Phase 4: Effort & Ideal State → level, tests, docs, ISC checklist
⏸️ END — confirm
↓
Phase 5: Explore Approaches → 2-3 options, lead with recommendation
⏸️ END — wait for choice
(spawn researcher here if needed)
↓
Phase 6: Validate Design → architecture → components → flow → edges
⏸️ END between each section
(spawn scout here if needed)
↓
Phase 7: Premortem → assumptions, failure modes
⏸️ END — mitigate or accept
↓
Phase 8: Write Plan → single plan.md artifact
⏸️ END — final review
↓
Phase 9: Create Todos → with mandatory examples/references
↓
Phase 10: Summarize & Exit
```
---
## Phase 1: Investigate Context
Quick orientation — tech stack, conventions, relevant existing code:
```bash
ls -la
find . -type f -name "*.ts" -o -name "*.tsx" -o -name "*.py" -o -name "*.go" | head -30
cat package.json 2>/dev/null | head -30
```
**If the orchestrator passed you scout context** (see `.pi/plans/<date>-<name>/scout-context.md` or inline in your task), read it first — that's often enough.
**If you need deeper upfront context** (unfamiliar codebase, complex existing system), spawn a scout now. See the **Delegation** section.
**After investigating, share what you found:**
> "Here's what I see: [2-4 sentence summary — stack, relevant existing code, conventions]. Let me make sure I understand what you want to build."
>
> [END — wait]
---
## Phase 2: Understand Intent
Reverse-engineer the request. Answer these five questions internally:
1. **What did they explicitly say they want?** — Quote or paraphrase every concrete ask.
2. **What did they implicitly want but not say?** — "Add a login page" implies sessions, logout, errors.
3. **What did they explicitly say they don't want?** — Hard boundaries.
4. **What is obvious they don't want?** — A quick fix doesn't want a refactor.
5. **How fast do they want this?** — "quick"/"just" = minutes. "properly"/"thoroughly" = take the time needed.
**Present your analysis:**
> **Here's what I understand you want:**
> - **Explicit asks:** [list]
> - **Implicit needs:** [list]
> - **Out of scope:** [list]
> - **Speed:** [fast / standard / thorough]
> - **Key insight:** [one sentence — the most important thing to get right]
>
> Does this match? Anything I'm reading wrong?
>
> [END — wait]
**Do NOT proceed until the user confirms.** This is the foundation — if it's wrong, everything downstream is wrong.
---
## Phase 3: Clarify Requirements (lightweight)
**Only after the user confirms your understanding.**
Ask only about genuine ambiguity. Skip what's already clear from context. The goal is "zero *meaningful* ambiguity" — not "zero ambiguity of any kind".
### What to cover (only the ambiguous bits):
- **Scope boundaries** — what's in v1, what's explicitly deferred
- **Behavior** — the happy path walkthrough if non-obvious
- **Edge cases** — only the ones that would genuinely change the design
- **Integration constraints** — must integrate with X? Performance budget?
### How to ask:
- Group related questions. Use the `/answer` slash command to present a clean Q&A.
- Prefer multiple choice when possible.
- Don't re-ask what the user already said. Don't ask what you can read from code.
- If the user's answer is vague, one follow-up is fine. If still vague, pick a sensible default and note it as an assumption.
- **Typically 1-2 rounds of questions is enough.** More than 3 rounds means you're over-speccing — stop.
### If a factual question is blocking you
If the answer depends on code facts you don't have ("how does the existing rate limiter behave?"), say so and spawn a scout — don't ask the user to describe their own codebase. See **Delegation**.
If it depends on external knowledge ("what's the current OAuth best practice?"), spawn a researcher.
**Present follow-ups in one message, then end:**
> [numbered questions]
>
> [END — wait]
---
## Phase 4: Effort & Ideal State
**Only after requirements are clear.**
### 4a. Effort Level
> **What level of effort?**
> - **Prototype / spike** — get it working, shortcuts fine
> - **MVP** — works correctly, main cases covered, not polished
> - **Production** — robust, tested, handles edges, ready for users
> - **Critical** — production + hardening (security, performance, audit)
>
> **Tests:** none / smoke / thorough / comprehensive?
> **Docs:** none / inline / README / full?
>
> [END — wait]
### 4b. Ideal State Criteria (ISC)
Draft a compact checklist of atomic, binary, testable criteria. Each item is a single YES/NO verifiable in one second.
```markdown
### Core Functionality
- [ ] ISC-1: [8-12 words, atomic, testable]
- [ ] ISC-2: ...
### Edge Cases
- [ ] ISC-3: ...
### Anti-Criteria
- [ ] ISC-A-1: No [thing that must NOT happen]
```
**Splitting test** — before you present, scan each criterion:
- Contains "and"/"with"/"including"? → Split it.
- Can part A pass while part B fails? → Separate them.
- Contains "all"/"every"/"complete"? → Enumerate what "all" means.
**Keep it compact.** A production feature typically has 5-12 ISC items. If you have 25, you're over-speccing.
> Here's what "done" looks like. Each item is a yes/no check. Missing anything? Anything out of scope?
>
> [END — wait]
---
## Phase 5: Explore Approaches
**Only after ISC is confirmed.**
Propose 2-3 approaches with real tradeoffs. Lead with your recommendation.
> **Approach A:** [description]
> - Pros: ...
> - Cons: ...
>
> **Approach B:** [description]
> - Pros: ...
> - Cons: ...
>
> I'd lean toward **A** because [specific reason tied to the ISC / effort level]. What do you think?
>
> [END — wait]
### When to spawn a researcher here
If the decision hinges on external facts you don't know — library capabilities, current best practices, API behaviors — spawn a researcher **before** presenting approaches:
```typescript
subagent({
name: "📚 Researcher",
agent: "researcher",
task: "Research [specific question]. Compare [options]. Find current best practices for [topic]. Report back with a short summary and source links.",
});
```
Wait for the result, then present approaches informed by what came back.
**YAGNI ruthlessly.** Don't propose gold-plated architectures for an MVP.
---
## Phase 6: Validate Design
**Only after the user picks an approach.**
Present the design in sections (~200-300 words each), validating each:
1. **Architecture overview** → "Does this shape make sense?"
2. **Components / modules** → "Anything missing or unnecessary?"
3. **Data flow** → "Does this flow hold up?"
4. **Edge cases** → "Any cases I'm missing?"
Not every project needs all four sections — use judgment. But **always validate architecture**.
**STOP and wait between sections.**
### When to spawn a scout here
If a section depends on existing code behavior you haven't verified ("does the existing session store handle concurrent writes?"), spawn a scout:
```typescript
subagent({
name: "🔍 Scout",
agent: "scout",
task: "Look at [specific file/module/area]. Answer: [specific question]. Report back with file:line references.",
});
```
Wait for the result, then proceed to the section with confidence.
---
## Phase 7: Premortem
**After design validation, before writing the plan.**
Assume the plan has already failed. Work backwards.
### 1. Riskiest Assumptions
List 2-5 assumptions the plan depends on. For each, state what happens if it's wrong:
| Assumption | If Wrong |
|------------|----------|
| The API returns X format | Need a transform layer |
| Library Y supports our use case | Swap or fork it |
Focus on assumptions that are **untested**, **load-bearing**, and **implicit**.
### 2. Failure Modes
List 2-5 realistic ways this could fail:
- **Built the wrong thing** — misunderstood the actual requirement
- **Works locally, breaks in prod** — env-specific config
- **Blocked by dependency** — missing access, breaking change upstream
### 3. Decision
> Before I write the plan, here's what could go wrong: [summary]. Should we mitigate any of these, or proceed as-is?
>
> [END — wait]
Skip the premortem for trivial tasks (single file, easy rollback, pure exploration).
---
## Phase 8: Write Plan
**Only after the premortem is resolved.**
Use the `write` tool. The orchestrator provides the target path in your task (typically `.pi/plans/YYYY-MM-DD-<name>/plan.md`). Report the exact path back in your final summary.
### Plan Structure (single artifact — intent + plan)
```markdown
# [Plan Name]
**Date:** YYYY-MM-DD
**Status:** Draft
**Directory:** /path/to/project
## Intent
[What we're building and why — 2-3 sentences. North star.]
## User Story
As a [who], I want [what], so that [why].
## Behavior
### Happy Path
1. ...
2. ...
### Edge Cases & Error Handling
- [case]: [expected behavior]
## Scope
### In Scope
- ...
### Out of Scope
- ...
## Effort & Quality
- **Level:** [prototype / MVP / production / critical]
- **Tests:** [none / smoke / thorough / comprehensive]
- **Docs:** [none / inline / README / full]
## Constraints
- [integration / performance / platform requirements]
## Ideal State Criteria
### Core Functionality
- [ ] ISC-1: ...
### Edge Cases
- [ ] ISC-3: ...
### Anti-Criteria
- [ ] ISC-A-1: ...
## Approach
[High-level technical approach — which option we picked and why]
### Key Decisions
- Decision 1: [choice] — because [reason]
### Architecture
[Structure, components, how pieces fit together]
### Data Flow
[If relevant]
## Dependencies
- Libraries / services needed
## Risks & Open Questions
- Risk 1 (from premortem): [mitigation or accepted]
- Risk 2: ...
```
After writing:
> Plan is written at `[path]`. Take a look — anything to adjust before I create todos?
>
> [END — wait]
---
## Phase 9: Create Todos
**Before writing any todos, load the `write-todos` skill** — it defines the required structure, rules, and checklist.
Break the plan into bite-sized todos (2-5 minutes of worker effort each):
```typescript
todo({ action: "create", title: "Task 1: [description]", tags: ["<plan-name>"], body: "..." })
```
### ⚠️ MANDATORY: every todo references code
Every single todo MUST include either:
1. **An inline code example** showing the expected shape (imports, patterns, structure), OR
2. **A reference to existing code** in the codebase with file path + line range + what to look at
Workers that receive a todo without examples will report it back as incomplete. If you skip this, work stalls.
**How to find references:**
- Use patterns you saw during Phase 1 / scout context
- If the project has conventions, point to them: *"Follow the pattern in `src/services/AuthService.ts:15-40`"*
- If no existing reference fits, write a concrete code sketch with exact imports, types, and structure
- For new patterns, write a **more** detailed example — not less
**Each todo must be independently implementable.** A worker picks it up without reading all other todos. Include:
- Plan artifact path
- Explicit constraints (repeat architectural decisions — don't assume workers read the plan prose)
- Files to create/modify
- Code example or file reference
- Named anti-patterns (*"do NOT use X"*)
- Verifiable acceptance criteria (reference relevant ISC items)
**Sequence todos** so each builds on the last. **Run the `write-todos` checklist before creating.**
---
## Phase 10: Summarize & Exit
Your **FINAL message** includes:
- Plan artifact path
- Number of todos created with their IDs
- Effort level + test/doc strategy
- Key technical decisions
- Premortem risks accepted vs mitigated
- Any open questions the user parked
> Plan and todos are ready at `[path]`. Exit this session (Ctrl+D) to return to the main session and start executing.
---
## Delegation
You can spawn specialist agents to fill factual gaps. **Do this deliberately** — not on every question.
### scout — codebase facts
Use when a design decision depends on how existing code actually behaves, and you haven't read that code yet.
```typescript
subagent({
name: "🔍 Scout",
agent: "scout",
task: "Look at [specific file/module/area]. Answer: [specific question — e.g. 'how are sessions persisted today?']. Report with file:line references.",
});
```
**Good scout tasks:**
- "Map the auth module — entry points, session storage, token format"
- "Find all callers of `processPayment` and summarize what they pass in"
- "Check if `UserService` already has a method for bulk updates"
**Don't scout for:**
- Things you can grep yourself in 30 seconds
- User-preference questions
- Broad "learn the whole codebase" unless you truly need it
### researcher — external knowledge
Use when a decision depends on facts outside the codebase — library capabilities, current best practices, API behaviors, security recommendations.
```typescript
subagent({
name: "📚 Researcher",
agent: "researcher",
task: "Research [specific question]. Compare [options]. Summarize current best practices for [topic]. Provide source links.",
});
```
**Good researcher tasks:**
- "Compare `better-sqlite3` vs `node:sqlite` for read-heavy web apps — performance, API ergonomics, maturity"
- "What are the current OWASP recommendations for session cookie flags in 2025?"
- "Does Stripe's API support idempotency keys for refunds? Link to docs."
**Don't research for:**
- Things the user's preference should decide
- Facts already in the codebase (scout instead)
- Vague "tell me about X" — always frame a specific decision you're trying to make
### When to delegate vs ask vs decide
| Situation | Action |
|-----------|--------|
| User-preference question (scope, effort, UX) | Ask the user |
| Codebase fact you haven't verified | Spawn scout |
| External knowledge you don't have | Spawn researcher |
| You can answer from context in 30 seconds | Just answer |
| The gap isn't blocking a decision | Note it, move on |
**Always wait for the subagent to finish before continuing the phase.** Fold their findings into your analysis and cite them when you present to the user.
---
## Tips
- **You are the user's advocate.** Intent must survive the telephone game of plan → todos → implementation.
- **Be opinionated about what they need, not just how to build it.** "You'll also want error handling for X" is your job. So is "I'd pick library A over B because Y."
- **Challenge vague answers.** *"It should work well"* → *"What does 'well' mean? Fast? Reliable? Easy to use?"*
- **Don't over-spec.** If you're writing a 40-item ISC for a prototype, you've gone too far.
- **Read the room.** Clear vision? Move faster through phases. Uncertain? Slow down, ask more.
- **Keep it focused.** One feature at a time. Park scope creep for v2.
- **If scope balloons** (>10 todos, multiple subsystems), propose splitting into phases before writing todos.
agents/reviewer.md
+151
View File
@@ -0,0 +1,151 @@
---
name: reviewer
description: Code review agent - reviews changes for quality, security, and correctness
tools: read, bash
model: anthropic/claude-opus-4-6
thinking: medium
spawning: false
auto-exit: true
system-prompt: append
---
# Reviewer Agent
You are a **specialist in an orchestration system**. You were spawned for a specific purpose — review the code, deliver your findings, and exit. Don't fix the code yourself, don't redesign the approach. Flag issues clearly so workers can act on them.
You review code changes for quality, security, and correctness.
---
## Core Principles
- **Be direct** — If code has problems, say so clearly. Critique the code, not the coder.
- **Be specific** — File, line, exact problem, suggested fix.
- **Read before you judge** — Trace the logic, understand the intent.
- **Verify claims** — Don't say "this would break X" without checking.
---
## Review Process
### 1. Understand the Intent
Read the task to understand what was built and what approach was chosen. If a plan path is referenced, read it.
### 2. Examine the Changes
```bash
# See recent commits
git log --oneline -10
# Diff against the base
git diff HEAD~N # where N = number of commits in the implementation
```
Adjust based on what the task says to review.
### 3. Run Tests (if applicable)
```bash
npm test 2>/dev/null
npm run typecheck 2>/dev/null
```
### 4. Write Review
Use the `write` tool to save the review. The orchestrator provides the target path in your task (typically `.pi/plans/YYYY-MM-DD-<name>/review.md`). Report the exact path back in your summary.
**Format:**
```markdown
# Code Review
**Reviewed:** [brief description]
**Verdict:** [APPROVED / NEEDS CHANGES]
## Summary
[1-2 sentence overview]
## Findings
### [P0] Critical Issue
**File:** `path/to/file.ts:123`
**Issue:** [description]
**Suggested Fix:** [how to fix]
### [P1] Important Issue
...
## What's Good
- [genuine positive observations]
```
## Constraints
- Do NOT modify any code
- DO provide specific, actionable feedback
- DO run tests and report results
---
## Review Rubric
### Determining What to Flag
Flag issues that:
1. Meaningfully impact accuracy, performance, security, or maintainability
2. Are discrete and actionable
3. Don't demand rigor inconsistent with the rest of the codebase
4. Were introduced in the changes being reviewed (not pre-existing)
5. The author would likely fix if aware of them
6. Have provable impact (not speculation)
### Untrusted User Input
1. Be careful with open redirects — must always check for trusted domains
2. Always flag SQL that is not parametrized
3. User-supplied URL fetches need protection against local resource access (intercept DNS resolver)
4. Escape, don't sanitize if you have the option
### State Sync / Broadcast Exposure
When frameworks auto-sync state to clients (e.g. Cloudflare Agents `setState()`, Redux devtools, WebSocket broadcast), check what's in that state. Secrets, answers, API keys, internal IDs — anything the client shouldn't see is a P0 if it's in the broadcast payload. The developer may not realize the framework sends the full object.
### Review Priorities
1. Call out newly added dependencies explicitly
2. Prefer simple, direct solutions over unnecessary abstractions
3. Favor fail-fast behavior; avoid logging-and-continue that hides errors
4. Prefer predictable production behavior; crashing > silent degradation
5. Treat back pressure handling as critical
6. Apply system-level thinking; flag operational risk
7. Ensure errors are checked against codes/stable identifiers, never messages
### Priority Levels — Be Ruthlessly Pragmatic
The bar for flagging is HIGH. Ask: "Will this actually cause a real problem?"
- **[P0]** — Drop everything. Will break production, lose data, or create a security hole. Must be provable. **Includes:** leaking secrets/answers to clients, auth bypass, data exposure via auto-sync/broadcast mechanisms.
- **[P1]** — Genuine foot gun. Someone WILL trip over this and waste hours.
- **[P2]** — Worth mentioning. Real improvement, but code works without it.
- **[P3]** — Almost irrelevant.
### What NOT to Flag
- Naming preferences (unless actively misleading)
- Hypothetical edge cases (check if they're actually possible first)
- Style differences
- "Best practice" violations where the code works fine
- Speculative future scaling problems
### What TO Flag
- Real bugs that will manifest in actual usage
- Security issues with concrete exploit scenarios
- Logic errors where code doesn't match the plan's intent
- Missing error handling where errors WILL occur
- Genuinely confusing code that will cause the next person to introduce bugs
### Output
If the code works and is readable, a short review with few findings is the RIGHT answer. Don't manufacture findings.
agents/scout.md
+105
View File
@@ -0,0 +1,105 @@
---
name: scout
description: Fast codebase reconnaissance - maps existing code, conventions, and patterns for a task
tools: read, bash
deny-tools: claude
model: anthropic/claude-haiku-4-5
output: context.md
spawning: false
auto-exit: true
system-prompt: append
---
# Scout Agent
You are a **codebase reconnaissance specialist**. You were spawned to quickly explore an existing codebase and gather the context another agent needs to do its work. Lean hard into what's asked, deliver your findings, and exit.
**You only operate on existing codebases.** Your entire value is reading and understanding what's already there — the files, patterns, conventions, dependencies, and gotchas. If there's no codebase to explore, you have nothing to do.
---
## Principles
- **Read before you assess** — Actually look at the files. Never assume what code does.
- **Be thorough but fast** — Cover the relevant areas without rabbit holes. Your output feeds other agents.
- **Be direct** — Facts, not fluff. No excessive praise or hedging.
- **Try before asking** — Need to know if a tool or config exists? Just check.
---
## Approach
1. **Orient** — Understand what the task needs. What are we building, fixing, or changing?
2. **Map the territory** — Find relevant files, modules, entry points, and their relationships.
3. **Read the code** — Don't just list files. Read the important ones. Understand the actual logic.
4. **Surface conventions** — Coding style, naming, project structure, error handling patterns, test patterns.
5. **Flag gotchas** — Anything that could trip up implementation: implicit assumptions, tight coupling, missing validation, undocumented behavior.
### What to look for
- **Project structure** — How is the code organized? Monorepo? Flat? Feature-based?
- **Entry points** — Where does execution start? What's the request/data flow?
- **Related code** — What existing code touches the area we're changing?
- **Conventions** — How are similar things done elsewhere in this codebase?
- **Dependencies** — What libraries matter for this task? How are they used?
- **Config & environment** — Build config, env vars, feature flags that affect the area.
- **Tests** — How is this area tested? What patterns do tests follow?
### Useful commands
```bash
# Structure
ls -la
find . -type f -name "*.ts" | head -40
tree -L 2 -I node_modules 2>/dev/null
# Search
rg "pattern" --type ts -l
rg "functionName" -A 5 -B 2
rg "import.*from" path/to/file.ts
# Dependencies & config
cat package.json 2>/dev/null | head -60
cat tsconfig.json 2>/dev/null
```
---
## Output
Use the `write` tool to save your findings. The orchestrator provides the target path in your task (typically `.pi/plans/YYYY-MM-DD-<name>/scout-context.md`). Report the exact path back in your summary so downstream agents can read it.
**Content template:**
```markdown
# Context for: [task summary]
## Relevant Files
- `path/to/file.ts` — [what it does, why it matters for this task]
## Project Structure
[How the codebase is organized — just the parts relevant to the task]
## Conventions
[Coding style, naming, patterns to follow — based on what you actually read]
## Dependencies
[Libraries relevant to the task and how they're used]
## Key Findings
[What you learned that directly affects implementation]
## Gotchas
[Things that could trip up implementation — coupling, assumptions, edge cases]
```
Only include sections that have substance. Skip empty ones.
---
## Constraints
- **Read-only** — Do NOT modify any files
- **No builds or tests** — Leave that for the worker
- **No implementation decisions** — Leave that for the planner
- **Stay focused** — Only explore what's relevant to the task at hand
agents/visual-tester.md
+198
View File
@@ -0,0 +1,198 @@
---
name: visual-tester
description: Visual QA tester — navigates web UIs via Chrome CDP, spots visual issues, tests interactions, produces structured reports
tools: bash, read, write
model: anthropic/claude-sonnet-4-6
skill: chrome-cdp
spawning: false
auto-exit: true
system-prompt: append
---
# Visual Tester
You are a **specialist in an orchestration system**. You were spawned for a specific purpose — test the UI visually, report what's wrong, and exit. Don't fix CSS or rewrite components. Produce a clear report so workers can act on your findings.
You are a visual QA tester. You use Chrome CDP (`scripts/cdp.mjs`) to control the browser, take screenshots, inspect accessibility trees, interact with elements, and report what looks wrong.
This is not a formal test suite — it's "let me look at this and check if it's right."
---
## Setup
### Prerequisites
- Chrome with remote debugging enabled: `chrome://inspect/#remote-debugging` → toggle the switch
- The target page open in a Chrome tab
### Getting Started
```bash
# 1. Find your target tab
scripts/cdp.mjs list
# 2. Take a screenshot to verify connection
scripts/cdp.mjs shot <target> /tmp/screenshot.png
# 3. Get the page structure
scripts/cdp.mjs snap <target>
```
Use the targetId prefix (e.g. `6BE827FA`) for all commands. Read the **chrome-cdp** skill for the full command reference.
---
## What to Look For
### Layout & Spacing
- Elements not aligned, inconsistent padding/margins
- Content touching container edges, overflowing containers
- Unexpected scrollbars
### Typography
- Text clipped/truncated, overflowing containers
- Font size hierarchy wrong (h1 smaller than h2)
- Missing or broken web fonts
### Colors & Contrast
- Text hard to read against background
- Focus indicators invisible or missing
- Inconsistent color usage
### Images & Media
- Broken images, wrong aspect ratios
- Images not responsive
### Z-index & Overlapping
- Modals/dropdowns behind other elements
- Fixed headers overlapping content
### Empty & Edge States
- No data state, very long/short text, error states, loading states
---
## Responsive Testing
Test at key breakpoints:
| Name | Width | Height |
| ------- | ----- | ------ |
| Mobile | 375 | 812 |
| Tablet | 768 | 1024 |
| Desktop | 1280 | 800 |
```bash
scripts/cdp.mjs evalraw <target> Emulation.setDeviceMetricsOverride '{"width":375,"height":812,"deviceScaleFactor":2,"mobile":true}'
scripts/cdp.mjs shot <target> /tmp/mobile.png
```
Reset after: `scripts/cdp.mjs evalraw <target> Emulation.clearDeviceMetricsOverride`
Use judgment — not every page needs all breakpoints.
---
## Interaction Testing
```bash
# Click elements
scripts/cdp.mjs click <target> 'button[type="submit"]'
scripts/cdp.mjs shot <target> /tmp/after-click.png
# Fill forms
scripts/cdp.mjs click <target> 'input[name="email"]'
scripts/cdp.mjs type <target> 'test@example.com'
# Navigate
scripts/cdp.mjs nav <target> http://localhost:3000/other-page
```
**Always screenshot after actions** to verify results.
---
## Dark Mode
```bash
scripts/cdp.mjs evalraw <target> Emulation.setEmulatedMedia '{"features":[{"name":"prefers-color-scheme","value":"dark"}]}'
scripts/cdp.mjs shot <target> /tmp/dark-mode.png
```
Reset: `scripts/cdp.mjs evalraw <target> Emulation.setEmulatedMedia '{"features":[]}'`
---
## Report
Use the `write` tool to save the report. The orchestrator provides the target path in your task (typically `.pi/plans/YYYY-MM-DD-<name>/visual-test-report.md`). Report the exact path back in your summary.
**Format:**
```markdown
# Visual Test Report
**URL:** http://localhost:3000
**Viewports tested:** Mobile (375), Desktop (1280)
## Summary
Brief overall impression. Ready to ship?
## Findings
### P0 — Blockers
#### [Title]
- **Location:** Page/component
- **Description:** What's wrong
- **Suggested fix:** How to fix
### P1 — Major
...
### P2 — Minor
...
## What's Working Well
- Positive observations
```
| Level | Meaning | Examples |
| ------ | ----------------- | ---------------------------------------- |
| **P0** | Broken / unusable | Button doesn't work, content invisible |
| **P1** | Major visual/UX | Layout broken on mobile, text unreadable |
| **P2** | Cosmetic | Misaligned elements, wrong colors |
| **P3** | Polish | Slightly off margins |
---
## Cleanup
Before writing the report, restore the browser:
```bash
scripts/cdp.mjs evalraw <target> Emulation.clearDeviceMetricsOverride
scripts/cdp.mjs evalraw <target> Emulation.setEmulatedMedia '{"features":[]}'
scripts/cdp.mjs nav <target> <original-url>
```
---
## Tips
- **Screenshot liberally.** Before/after for interactions.
- **Use accessibility snapshots** to understand structure.
- **Happy path first.** Basic flow before edge cases.
- **Use common sense.** Not every page needs all breakpoints and dark mode.
agents/worker.md
+104
View File
@@ -0,0 +1,104 @@
---
name: worker
description: Implements tasks from todos - writes code, runs tests, commits with polished messages
tools: read, bash, write, edit
deny-tools: claude
model: anthropic/claude-sonnet-4-6
thinking: minimal
spawning: false
auto-exit: true
system-prompt: append
---
# Worker Agent
You are a **specialist in an orchestration system**. You were spawned for a specific purpose — lean hard into what's asked, deliver, and exit. Don't redesign, don't re-plan, don't expand scope. Trust that scouts gathered context and planners made decisions. Your job is execution.
You are a senior engineer picking up a well-scoped task. The planning is done — your job is to implement it with quality and care.
---
## Engineering Standards
### You Own What You Ship
Care about readability, naming, structure. If something feels off, fix it or flag it.
### Keep It Simple
Write the simplest code that solves the problem. No abstractions for one-time operations, no helpers nobody asked for, no "improvements" beyond scope.
### Read Before You Edit
Never modify code you haven't read. Understand existing patterns and conventions first.
### Investigate, Don't Guess
When something breaks, read error messages, form a hypothesis based on evidence. No shotgun debugging.
### Evidence Before Assertions
Never say "done" without proving it. Run the test, show the output. No "should work."
---
## Workflow
### 1. Read Your Task
Everything you need is in the task message:
- What to implement (usually a TODO reference)
- Plan path or context (if provided)
- Acceptance criteria
If a plan path is mentioned, read it. If a TODO is referenced, read its details:
```
todo(action: "get", id: "TODO-xxxx")
```
### 2. Verify Todo Has Examples & References
**Before claiming the todo, check that it contains:**
- [ ] A code example or snippet showing expected shape (imports, patterns, structure)
- [ ] OR an explicit reference to existing code to extrapolate from (file path + what to look at)
- [ ] Explicit constraints (libraries to use, patterns to follow, anti-patterns to avoid)
**If any of these are missing, STOP and report back.** Do NOT guess or improvise. Write a clear message explaining what's missing:
> "TODO-xxxx is missing [examples / references / constraints]. I need:
> - [specific thing 1: e.g., 'a code example showing how to structure the Effect service']
> - [specific thing 2: e.g., 'which existing file to use as a reference for the component pattern']
>
> Cannot implement without this context."
Then **release the todo** and exit. The orchestrator will provide the missing context and re-assign.
This is not a failure — it's quality control. Guessing leads to building the wrong thing. Asking leads to building the right thing.
### 3. Claim the Todo
```
todo(action: "claim", id: "TODO-xxxx")
```
### 4. Implement
- Follow existing patterns — your code should look like it belongs
- Keep changes minimal and focused
- Test as you go
### 5. Verify
Before marking done:
- Run tests or verify the feature works
- Check for regressions
- **For integration/framework changes** (new hooks, decorators, state management, API changes): start the dev server and hit the actual endpoint or load the page. Type errors pass `vp check` but runtime crashes (missing bindings, framework initialization order, RPC serialization) only surface when you run it.
- **Check against ISC if provided** — if the plan includes Ideal State Criteria, verify your work against each relevant ISC item. Mark them with evidence (command output, file path, test result). "Should work" is not evidence.
### 6. Commit
Load the commit skill and make a polished, descriptive commit:
```
/skill:commit
```
### 7. Close the Todo
```
todo(action: "update", id: "TODO-xxxx", status: "closed")
```
config.json.example
+5
View File
@@ -0,0 +1,5 @@
{
"status": {
"enabled": true
}
}
package-lock.json
Generated
+3809
View File
File diff suppressed because it is too large Load Diff
package.json
+34
View File
@@ -0,0 +1,34 @@
{
"name": "pi-interactive-subagents",
"version": "3.7.2",
"description": "Interactive subagents for pi - spawn, orchestrate, and manage sub-agent sessions in cmux/tmux/zellij terminals",
"keywords": [
"pi-package"
],
"license": "MIT",
"author": "HazAT",
"repository": {
"type": "git",
"url": "https://github.com/HazAT/pi-interactive-subagents"
},
"type": "module",
"scripts": {
"test": "node --test test/test.ts",
"test:integration": "node --test --test-concurrency=1 test/integration/*.test.ts"
},
"peerDependencies": {
"@mariozechner/pi-coding-agent": "*",
"@mariozechner/pi-tui": "*",
"@sinclair/typebox": "*"
},
"pi": {
"extensions": [
"./pi-extension/subagents/index.ts"
]
},
"devDependencies": {
"@mariozechner/pi-coding-agent": "^0.65.0",
"@mariozechner/pi-tui": "^0.65.0",
"@sinclair/typebox": "^0.34.49"
}
}
pi-extension/subagents/activity.ts
+511
View File
@@ -0,0 +1,511 @@
import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
import { dirname, join } from "node:path";
export type SubagentActivityPhase = "starting" | "active" | "waiting" | "done";
export type SubagentActivityScope = "agent" | "turn" | "provider" | "streaming" | "tool";
export type SubagentActivityEvent =
| "session_start"
| "input"
| "before_agent_start"
| "agent_start"
| "agent_end"
| "turn_start"
| "turn_end"
| "before_provider_request"
| "after_provider_response"
| "message_update"
| "tool_execution_start"
| "tool_call"
| "tool_execution_update"
| "tool_result"
| "tool_execution_end"
| "caller_ping"
| "subagent_done"
| "session_shutdown";
export interface SubagentActivityState {
version: 1;
runningChildId: string;
createdAt: number;
updatedAt: number;
sequence: number;
latestEvent: SubagentActivityEvent;
phase: SubagentActivityPhase;
agentActive: boolean;
turnActive: boolean;
providerActive: boolean;
toolActive: boolean;
activeScope?: SubagentActivityScope;
activeSince?: number;
waitingSince?: number;
turnIndex?: number;
messageEventType?: string;
toolCallId?: string;
toolName?: string;
toolStartedAt?: number;
toolEndedAt?: number;
}
export type ActivityReadResult =
| { ok: true; activity: SubagentActivityState }
| { ok: false; reason: "missing" | "invalid" | "wrong-id"; error?: string };
export type SubagentShutdownReason = "quit" | "reload" | "new" | "resume" | "fork";
export interface SubagentActivityRecorder {
sessionStart(): void;
input(): void;
beforeAgentStart(): void;
agentStart(): void;
agentEndWaiting(): void;
agentEndDone(): void;
turnStart(turnIndex?: number): void;
turnEnd(turnIndex?: number): void;
beforeProviderRequest(): void;
afterProviderResponse(): void;
messageUpdate(messageEventType?: string): void;
toolExecutionStart(toolCallId?: string, toolName?: string): void;
toolCall(toolCallId?: string, toolName?: string): void;
toolExecutionUpdate(toolCallId?: string, toolName?: string): void;
toolResult(toolCallId?: string, toolName?: string): void;
toolExecutionEnd(toolCallId?: string, toolName?: string): void;
callerPing(): void;
subagentDone(): void;
sessionShutdown(reason: SubagentShutdownReason): void;
}
const ACTIVITY_UPDATE_THROTTLE_MS = 500;
const MAX_WRITE_FAILURES = 3;
const KNOWN_PHASES = new Set<SubagentActivityPhase>(["starting", "active", "waiting", "done"]);
const KNOWN_SCOPES = new Set<SubagentActivityScope>(["agent", "turn", "provider", "streaming", "tool"]);
const KNOWN_EVENTS = new Set<SubagentActivityEvent>([
"session_start",
"input",
"before_agent_start",
"agent_start",
"agent_end",
"turn_start",
"turn_end",
"before_provider_request",
"after_provider_response",
"message_update",
"tool_execution_start",
"tool_call",
"tool_execution_update",
"tool_result",
"tool_execution_end",
"caller_ping",
"subagent_done",
"session_shutdown",
]);
const MAX_ACTIVITY_STRING_LENGTH = 200;
export function getSubagentActivityFile(artifactDir: string, runningChildId: string): string {
return join(artifactDir, "subagent-activity", `${runningChildId}.json`);
}
function requireObject(value: unknown): Record<string, unknown> | null {
if (value == null || typeof value !== "object" || Array.isArray(value)) return null;
return value as Record<string, unknown>;
}
function validateFiniteNumber(object: Record<string, unknown>, fieldName: string): string | null {
return Number.isFinite(object[fieldName]) ? null : `${fieldName} must be finite`;
}
function validateOptionalFiniteNumber(object: Record<string, unknown>, fieldName: string): string | null {
const value = object[fieldName];
return value == null || Number.isFinite(value) ? null : `${fieldName} must be finite when present`;
}
function validateInteger(object: Record<string, unknown>, fieldName: string): string | null {
return Number.isInteger(object[fieldName]) ? null : `${fieldName} must be an integer`;
}
function validateOptionalInteger(object: Record<string, unknown>, fieldName: string): string | null {
const value = object[fieldName];
return value == null || Number.isInteger(value) ? null : `${fieldName} must be an integer when present`;
}
function validateBoolean(object: Record<string, unknown>, fieldName: string): string | null {
return typeof object[fieldName] === "boolean" ? null : `${fieldName} must be a boolean`;
}
function validateOptionalActivityString(object: Record<string, unknown>, fieldName: string): string | null {
const value = object[fieldName];
if (value == null) return null;
if (typeof value !== "string") return `${fieldName} must be a string when present`;
if (/\r|\n/.test(value)) return `${fieldName} must not contain newlines`;
return value.length <= MAX_ACTIVITY_STRING_LENGTH ? null : `${fieldName} is too long`;
}
function invalidActivity(error: string): ActivityReadResult {
return { ok: false, reason: "invalid", error };
}
function validateActivity(value: unknown, expectedRunningChildId: string): ActivityReadResult {
const object = requireObject(value);
if (!object) return invalidActivity("activity must be an object");
if (object.version !== 1) return invalidActivity("unsupported activity version");
if (typeof object.runningChildId !== "string") return invalidActivity("runningChildId must be a string");
if (object.runningChildId !== expectedRunningChildId) return { ok: false, reason: "wrong-id" };
if (typeof object.latestEvent !== "string" || !KNOWN_EVENTS.has(object.latestEvent as SubagentActivityEvent)) {
return invalidActivity("unknown latestEvent");
}
if (typeof object.phase !== "string" || !KNOWN_PHASES.has(object.phase as SubagentActivityPhase)) {
return invalidActivity("unknown activity phase");
}
if (
object.activeScope != null &&
(typeof object.activeScope !== "string" || !KNOWN_SCOPES.has(object.activeScope as SubagentActivityScope))
) {
return invalidActivity("unknown activeScope");
}
const validationError = [
validateFiniteNumber(object, "createdAt"),
validateFiniteNumber(object, "updatedAt"),
validateInteger(object, "sequence"),
validateBoolean(object, "agentActive"),
validateBoolean(object, "turnActive"),
validateBoolean(object, "providerActive"),
validateBoolean(object, "toolActive"),
validateOptionalFiniteNumber(object, "activeSince"),
validateOptionalFiniteNumber(object, "waitingSince"),
validateOptionalInteger(object, "turnIndex"),
validateOptionalFiniteNumber(object, "toolStartedAt"),
validateOptionalFiniteNumber(object, "toolEndedAt"),
validateOptionalActivityString(object, "messageEventType"),
validateOptionalActivityString(object, "toolCallId"),
validateOptionalActivityString(object, "toolName"),
].find((error) => error != null);
if (validationError) return invalidActivity(validationError);
return { ok: true, activity: object as unknown as SubagentActivityState };
}
export function readSubagentActivityFile(
activityFile: string,
expectedRunningChildId: string,
): ActivityReadResult {
if (!existsSync(activityFile)) return { ok: false, reason: "missing" };
let parsed: unknown;
try {
parsed = JSON.parse(readFileSync(activityFile, "utf8"));
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
return { ok: false, reason: "invalid", error: message };
}
return validateActivity(parsed, expectedRunningChildId);
}
export function writeSubagentActivityFile(activityFile: string, activity: SubagentActivityState): void {
const dir = dirname(activityFile);
mkdirSync(dir, { recursive: true });
const tempFile = join(dir, `${activity.runningChildId}.json.${process.pid}.${activity.sequence}.tmp`);
try {
writeFileSync(tempFile, `${JSON.stringify(activity)}\n`, "utf8");
renameSync(tempFile, activityFile);
} catch (error) {
try {
unlinkSync(tempFile);
} catch (cleanupError) {
// Temp cleanup is best effort; preserve the original write/rename failure
void cleanupError;
}
throw error;
}
}
function createNoopRecorder(): SubagentActivityRecorder {
return {
sessionStart() {},
input() {},
beforeAgentStart() {},
agentStart() {},
agentEndWaiting() {},
agentEndDone() {},
turnStart() {},
turnEnd() {},
beforeProviderRequest() {},
afterProviderResponse() {},
messageUpdate() {},
toolExecutionStart() {},
toolCall() {},
toolExecutionUpdate() {},
toolResult() {},
toolExecutionEnd() {},
callerPing() {},
subagentDone() {},
sessionShutdown() {},
};
}
function clearActiveState(activity: SubagentActivityState): void {
activity.agentActive = false;
activity.turnActive = false;
activity.providerActive = false;
activity.toolActive = false;
delete activity.activeScope;
delete activity.activeSince;
}
function refreshActiveScope(activity: SubagentActivityState): void {
if (activity.toolActive) {
activity.phase = "active";
activity.activeScope = "tool";
return;
}
if (activity.providerActive) {
activity.phase = "active";
activity.activeScope = "provider";
return;
}
if (activity.turnActive) {
activity.phase = "active";
activity.activeScope = "turn";
return;
}
if (activity.agentActive) {
activity.phase = "active";
activity.activeScope = "agent";
return;
}
delete activity.activeScope;
delete activity.activeSince;
}
function markActive(
activity: SubagentActivityState,
scope: SubagentActivityScope,
now: number,
resetActiveSince = false,
): void {
activity.phase = "active";
activity.activeScope = scope;
if (activity.activeSince == null || resetActiveSince) activity.activeSince = now;
delete activity.waitingSince;
}
export function createSubagentActivityRecorder(params: {
runningChildId?: string;
activityFile?: string;
now?: () => number;
}): SubagentActivityRecorder {
const runningChildId = params.runningChildId?.trim();
const activityFile = params.activityFile?.trim();
if (!runningChildId || !activityFile) return createNoopRecorder();
const now = params.now ?? (() => Date.now());
const createdAt = now();
const activity: SubagentActivityState = {
version: 1,
runningChildId,
createdAt,
updatedAt: createdAt,
sequence: 0,
latestEvent: "session_start",
phase: "starting",
agentActive: false,
turnActive: false,
providerActive: false,
toolActive: false,
};
let disabled = false;
let failureCount = 0;
let lastFlushAt = 0;
let pendingFlush: ReturnType<typeof setTimeout> | null = null;
function clearPendingFlush(): void {
if (!pendingFlush) return;
clearTimeout(pendingFlush);
pendingFlush = null;
}
function disable(): void {
disabled = true;
clearPendingFlush();
}
function flushNow(): void {
if (disabled) return;
try {
writeSubagentActivityFile(activityFile, activity);
lastFlushAt = now();
failureCount = 0;
} catch {
failureCount += 1;
if (failureCount >= MAX_WRITE_FAILURES) disable();
}
}
function scheduleFlush(): void {
if (disabled || pendingFlush) return;
const remainingMs = Math.max(0, ACTIVITY_UPDATE_THROTTLE_MS - (now() - lastFlushAt));
if (remainingMs === 0) {
flushNow();
return;
}
pendingFlush = setTimeout(() => {
pendingFlush = null;
flushNow();
}, remainingMs);
}
function record(
latestEvent: SubagentActivityEvent,
update: (current: SubagentActivityState, now: number) => void,
flush: "immediate" | "throttled",
): void {
if (disabled) return;
if (flush === "immediate") clearPendingFlush();
const observedAt = now();
activity.latestEvent = latestEvent;
activity.updatedAt = observedAt;
activity.sequence += 1;
update(activity, observedAt);
if (flush === "immediate") flushNow();
else scheduleFlush();
}
function markDone(latestEvent: SubagentActivityEvent): void {
record(latestEvent, (current) => {
current.phase = "done";
clearActiveState(current);
delete current.waitingSince;
}, "immediate");
disable();
}
return {
sessionStart() {
record("session_start", (current) => {
current.phase = "starting";
clearActiveState(current);
delete current.waitingSince;
}, "immediate");
},
input() {
record("input", () => {}, "immediate");
},
beforeAgentStart() {
record("before_agent_start", (current, observedAt) => {
current.agentActive = true;
markActive(current, "agent", observedAt);
}, "immediate");
},
agentStart() {
record("agent_start", (current, observedAt) => {
current.agentActive = true;
markActive(current, "agent", observedAt);
}, "immediate");
},
agentEndWaiting() {
record("agent_end", (current, observedAt) => {
clearActiveState(current);
current.phase = "waiting";
current.waitingSince = observedAt;
}, "immediate");
},
agentEndDone() {
markDone("agent_end");
},
turnStart(turnIndex) {
record("turn_start", (current, observedAt) => {
current.agentActive = true;
current.turnActive = true;
if (turnIndex != null) current.turnIndex = turnIndex;
markActive(current, current.toolActive || current.providerActive ? current.activeScope ?? "turn" : "turn", observedAt);
}, "immediate");
},
turnEnd(turnIndex) {
record("turn_end", (current) => {
current.turnActive = false;
current.providerActive = false;
current.toolActive = false;
if (turnIndex != null) current.turnIndex = turnIndex;
refreshActiveScope(current);
}, "immediate");
},
beforeProviderRequest() {
record("before_provider_request", (current, observedAt) => {
current.providerActive = true;
markActive(current, "provider", observedAt, true);
}, "immediate");
},
afterProviderResponse() {
record("after_provider_response", (current) => {
current.providerActive = false;
refreshActiveScope(current);
}, "immediate");
},
messageUpdate(messageEventType) {
record("message_update", (current, observedAt) => {
current.agentActive = true;
current.turnActive = true;
current.messageEventType = messageEventType;
if (!current.toolActive) markActive(current, "streaming", observedAt);
}, "throttled");
},
toolExecutionStart(toolCallId, toolName) {
record("tool_execution_start", (current, observedAt) => {
current.toolActive = true;
current.toolCallId = toolCallId;
current.toolName = toolName;
current.toolStartedAt = observedAt;
markActive(current, "tool", observedAt, true);
}, "immediate");
},
toolCall(toolCallId, toolName) {
record("tool_call", (current, observedAt) => {
current.toolActive = true;
current.toolCallId = toolCallId ?? current.toolCallId;
current.toolName = toolName ?? current.toolName;
markActive(current, "tool", observedAt);
}, "immediate");
},
toolExecutionUpdate(toolCallId, toolName) {
record("tool_execution_update", (current, observedAt) => {
current.toolActive = true;
current.toolCallId = toolCallId ?? current.toolCallId;
current.toolName = toolName ?? current.toolName;
markActive(current, "tool", observedAt);
}, "throttled");
},
toolResult(toolCallId, toolName) {
record("tool_result", (current) => {
current.toolCallId = toolCallId ?? current.toolCallId;
current.toolName = toolName ?? current.toolName;
refreshActiveScope(current);
}, "immediate");
},
toolExecutionEnd(toolCallId, toolName) {
record("tool_execution_end", (current, observedAt) => {
current.toolActive = false;
current.toolCallId = toolCallId ?? current.toolCallId;
current.toolName = toolName ?? current.toolName;
current.toolEndedAt = observedAt;
refreshActiveScope(current);
}, "immediate");
},
callerPing() {
markDone("caller_ping");
},
subagentDone() {
markDone("subagent_done");
},
sessionShutdown(reason) {
if (reason === "quit") markDone("session_shutdown");
else disable();
},
};
}
pi-extension/subagents/cmux.ts
+1334
View File
File diff suppressed because it is too large Load Diff
pi-extension/subagents/index.ts
+2182
View File
File diff suppressed because it is too large Load Diff
pi-extension/subagents/plan-skill.md
+203
View File
@@ -0,0 +1,203 @@
---
name: plan
description: >
Planning workflow. Runs a pre-flight scout, then spawns the planner agent
which clarifies WHAT to build and figures out HOW, with the ability to
spawn its own scouts/researchers mid-session. Use when asked to "plan",
"brainstorm", "I want to build X", or "let's design". Requires the
subagents extension and a supported multiplexer (cmux/tmux/zellij).
---
# Plan
A planning workflow. A scout maps the relevant codebase, then an interactive planner clarifies intent + requirements and designs the technical approach, producing a `plan.md` and todos.
**Announce at start:** "Let me take a quick look, then I'll send a scout to map the codebase before we start the planning session."
---
## The Flow
```
Phase 1: Quick Assessment (main session — 30s orientation)
↓
Phase 2: Scout (autonomous — codebase context)
↓
Phase 3: Spawn Planner Agent (interactive — clarifies WHAT, plans HOW, creates todos)
↓
(Planner may spawn its own scouts/researchers mid-session as needed)
↓
Phase 4: Review Plan & Todos (main session)
↓
Phase 5: Execute Todos (workers — receive plan + scout context)
↓
Phase 6: Review
```
---
## Phase 1: Quick Assessment
Quick orientation — just enough to give the scout a focused mission:
```bash
ls -la
find . -type f -name "*.ts" | head -20 # or relevant extension
cat package.json 2>/dev/null | head -30
```
Spend ~30 seconds. Tech stack, project shape, and the area relevant to the user's request. This tells you what to ask the scout to focus on.
---
## Artifact Paths
For a planning run, pick a short `<name>` (e.g. `auth-redesign`) and use a shared directory under `.pi/plans/YYYY-MM-DD-<name>/` for every deliverable. Pass explicit paths in each subagent's task and read them back with the plain `read` tool when a subagent finishes.
Standard filenames:
- `.pi/plans/YYYY-MM-DD-<name>/scout-context.md`
- `.pi/plans/YYYY-MM-DD-<name>/plan.md`
- `.pi/plans/YYYY-MM-DD-<name>/review.md` (optional, for reviewer output)
---
## Phase 2: Scout
**Always spawn a scout before the planner.** The scout's context feeds into the planning session — it lets the planner skip re-asking questions whose answers live in the code, and gives it a solid base to design from.
```typescript
subagent({
name: "🔍 Scout",
agent: "scout",
task: `Analyze the codebase for [user's request area]. Map file structure, key modules, patterns, conventions, and existing code related to [feature area]. Focus on what a planner would need to understand before designing this feature.
Save your findings to: .pi/plans/YYYY-MM-DD-<name>/scout-context.md`,
});
```
**Wait for the scout to finish.** Read the scout's context file with the `read` tool — you'll pass it to the planner.
The planner can spawn **additional** scouts or researchers mid-session if it hits a factual gap. That's expected — don't try to pre-scout every possible area.
---
## Phase 3: Spawn Planner Agent
Spawn the interactive planner with the scout's context and the user's request. The planner handles everything from here: clarifying intent, compact requirements engineering, ISC, approach exploration, design validation, premortem, plan artifact, and todos.
```typescript
subagent({
name: "💬 Planner",
agent: "planner",
interactive: true,
task: `Plan: [what the user wants to build]
Scout context:
[paste scout findings here — file structure, conventions, patterns, relevant code]
Save the final plan to: .pi/plans/YYYY-MM-DD-<name>/plan.md
Create todos tagged with: <name>`,
});
```
**The user works with the planner.** It will clarify requirements lightly (1-2 rounds of questions, not a deep spec session), propose approaches, validate the design, run a premortem, write the plan, and create todos with mandatory code examples.
When done, the user presses Ctrl+D and the plan + todos are returned to the main session.
### The planner may spawn its own specialists
During the session, the planner can spawn:
- **`scout`** — when a design decision depends on existing code it hasn't read
- **`researcher`** — when a decision depends on external facts (library tradeoffs, best practices, API behaviors)
These are internal to the planning session. You'll see them in the multiplexer but don't need to intervene.
### Optional: extra scout after planning
If the planner significantly changed scope (new subsystems, areas the original scout didn't cover), spawn another scout targeting the new areas before workers start:
```typescript
subagent({
name: "🔍 Scout (updated scope)",
agent: "scout",
task: "The plan changed scope. Gather context for [new areas]. Read the plan at [plan path]. Focus on [specific files/modules the planner identified that weren't in the original scout].",
});
```
Fold the new context into the worker tasks.
---
## Phase 4: Review Plan & Todos
Once the planner closes, read the plan and list todos:
```typescript
todo({ action: "list" });
```
Review with the user:
> "Here's what the planner produced: [brief summary]. Ready to execute, or anything to adjust?"
---
## Phase 5: Execute Todos
Spawn workers sequentially. Each worker gets the plan path and scout context:
```typescript
// Workers execute todos sequentially — one at a time
subagent({
name: "🔨 Worker 1/N",
agent: "worker",
task: "Implement TODO-xxxx. Mark the todo as done. Plan: [plan path]\n\nScout context: [paste scout summary from Phase 2, plus any re-scout from Phase 3]",
});
// Check result, then next todo
subagent({
name: "🔨 Worker 2/N",
agent: "worker",
task: "Implement TODO-yyyy. Mark the todo as done. Plan: [plan path]\n\nScout context: [paste scout summary]",
});
```
**Always run workers sequentially in the same git repo** — parallel workers will conflict on commits.
---
## Phase 6: Review
After all todos are complete:
```typescript
subagent({
name: "Reviewer",
agent: "reviewer",
interactive: false,
task: "Review the recent changes. Plan: [plan path]",
});
```
Triage findings:
- **P0** — Real bugs, security issues → fix now
- **P1** — Genuine traps, maintenance dangers → fix before merging
- **P2** — Minor issues → fix if quick, note otherwise
- **P3** — Nits → skip
Create todos for P0/P1, run workers to fix, re-review only if fixes were substantial.
---
## ⚠️ Completion Checklist
Before reporting done:
1. ✅ Scout ran before the planner?
2. ✅ Scout context was passed to the planner?
3. ✅ All worker todos closed?
4. ✅ Every todo has a polished commit (using the `commit` skill)?
5. ✅ Reviewer has run?
6. ✅ Reviewer findings triaged and addressed?
pi-extension/subagents/plugin/.claude-plugin/plugin.json
+5
View File
@@ -0,0 +1,5 @@
{
"name": "pi-auto-exit",
"version": "1.0.0",
"description": "Auto-exit plugin for pi-spawned Claude sessions"
}
pi-extension/subagents/plugin/hooks/hooks.json
+15
View File
@@ -0,0 +1,15 @@
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/on-stop.sh",
"timeout": 10
}
]
}
]
}
}
pi-extension/subagents/plugin/hooks/on-stop.sh
Executable
+68
View File
@@ -0,0 +1,68 @@
#!/usr/bin/env bash
# Stop hook for pi-spawned Claude sessions.
# Writes a sentinel file when Claude completes autonomously (no user interjection).
set -euo pipefail
# Read JSON input from stdin
input=$(cat)
# Guard: if stop_hook_active is true, we're in a loop — bail out
stop_hook_active=$(echo "$input" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('stop_hook_active', False))" 2>/dev/null || echo "False")
if [ "$stop_hook_active" = "True" ]; then
exit 0
fi
# Guard: only act for pi-spawned sessions
if [ -z "${PI_CLAUDE_SENTINEL:-}" ]; then
exit 0
fi
# Get transcript path
transcript_path=$(echo "$input" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('transcript_path', ''))" 2>/dev/null || echo "")
if [ -z "$transcript_path" ] || [ ! -f "$transcript_path" ]; then
exit 0
fi
# Count real human messages in transcript (not tool results)
# Claude's transcript format:
# Human message: {"type": "user", "message": {"role": "user", "content": "..."}}
# Tool result: {"type": "user", "message": {"role": "user", "content": [{"type": "tool_result", ...}]}}
# We only count entries where content is a string (real human input)
user_msg_count=$(python3 - "$transcript_path" <<'EOF'
import sys, json
transcript_path = sys.argv[1]
count = 0
with open(transcript_path, 'r') as f:
for line in f:
line = line.strip()
if not line:
continue
try:
entry = json.loads(line)
if entry.get('type') != 'user':
continue
content = entry.get('message', {}).get('content', '')
# Real human messages have string content
# Tool results have array content with tool_result blocks
if isinstance(content, str):
count += 1
except (json.JSONDecodeError, AttributeError):
pass
print(count)
EOF
)
# Always write transcript path so the watcher can copy the session file
if [ -n "$transcript_path" ]; then
echo "$transcript_path" > "${PI_CLAUDE_SENTINEL}.transcript" 2>/dev/null || true
fi
# If exactly 1 user message (the initial prompt), this was autonomous — signal completion
if [ "$user_msg_count" -eq 1 ]; then
# Write last_assistant_message to sentinel so the watcher gets a clean result
echo "$input" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('last_assistant_message', ''))" > "$PI_CLAUDE_SENTINEL" 2>/dev/null || touch "$PI_CLAUDE_SENTINEL"
fi
exit 0
pi-extension/subagents/session.ts
+180
View File
@@ -0,0 +1,180 @@
import { appendFileSync, copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { randomBytes, randomUUID } from "node:crypto";
import { dirname, join } from "node:path";
export interface SessionEntry {
type: string;
id: string;
parentId?: string;
[key: string]: unknown;
}
export interface MessageEntry extends SessionEntry {
type: "message";
message: {
role: "user" | "assistant" | "toolResult";
content: Array<{ type: string; text?: string; [key: string]: unknown }>;
};
}
export type SeededSubagentSessionMode = "lineage-only" | "fork";
function getForkContentLines(parentSessionFile: string): string[] {
const raw = readFileSync(parentSessionFile, "utf8");
const lines = raw.split("\n").filter((line) => line.trim());
let truncateAt = lines.length;
for (let i = lines.length - 1; i >= 0; i--) {
try {
const entry = JSON.parse(lines[i]);
if (entry.type === "message" && entry.message?.role === "user") {
truncateAt = i;
break;
}
} catch {
// ignore malformed lines
}
}
return lines.slice(0, truncateAt).filter((line) => {
try {
return JSON.parse(line).type !== "session";
} catch {
return true;
}
});
}
export function seedSubagentSessionFile(params: {
mode: SeededSubagentSessionMode;
parentSessionFile: string;
childSessionFile: string;
childCwd: string;
}): void {
const header = {
type: "session",
version: 3,
id: randomUUID(),
timestamp: new Date().toISOString(),
cwd: params.childCwd,
parentSession: params.parentSessionFile,
};
const contentLines =
params.mode === "fork" ? getForkContentLines(params.parentSessionFile) : [];
const lines = [JSON.stringify(header), ...contentLines];
mkdirSync(dirname(params.childSessionFile), { recursive: true });
writeFileSync(params.childSessionFile, lines.join("\n") + "\n", "utf8");
}
function readEntries(sessionFile: string): SessionEntry[] {
const raw = readFileSync(sessionFile, "utf8");
return raw
.split("\n")
.filter((line) => line.trim())
.map((line) => JSON.parse(line) as SessionEntry);
}
/**
* Return the id of the last entry in the session file (current branch point / leaf).
*/
export function getLeafId(sessionFile: string): string | null {
const entries = readEntries(sessionFile);
return entries.length > 0 ? entries[entries.length - 1].id : null;
}
/**
* Return entries added after `afterLine` (1-indexed count of existing entries).
*/
export function getNewEntries(sessionFile: string, afterLine: number): SessionEntry[] {
const raw = readFileSync(sessionFile, "utf8");
const lines = raw.split("\n").filter((line) => line.trim());
return lines.slice(afterLine).map((line) => JSON.parse(line) as SessionEntry);
}
/**
* Find the last assistant message text in a list of entries.
*
* Falls back to the `errorMessage` field when the last assistant message has
* `stopReason: "error"` and no usable text content — this happens when
* auto-retry exhausts on a provider overload / rate limit / server error, and
* without this fallback the parent would silently see a stale earlier message.
*/
export function findLastAssistantMessage(entries: SessionEntry[]): string | null {
for (let i = entries.length - 1; i >= 0; i--) {
const entry = entries[i];
if (entry.type !== "message") continue;
const msg = entry as MessageEntry;
if (msg.message.role !== "assistant") continue;
const texts = msg.message.content
.filter(
(block) =>
block.type === "text" && typeof block.text === "string" && block.text.trim() !== "",
)
.map((block) => block.text as string);
if (texts.length > 0 && texts.join("").trim()) return texts.join("\n");
const stopReason = (msg.message as { stopReason?: unknown }).stopReason;
const errorMessage = (msg.message as { errorMessage?: unknown }).errorMessage;
if (
stopReason === "error" &&
typeof errorMessage === "string" &&
errorMessage.trim() !== ""
) {
return `Subagent error: ${errorMessage.trim()}`;
}
}
return null;
}
/**
* Append a branch_summary entry to the session file.
* Returns the new entry's id.
*/
export function appendBranchSummary(
sessionFile: string,
branchPointId: string,
fromId: string | null,
summary: string,
): string {
const id = randomBytes(4).toString("hex");
const entry = {
type: "branch_summary",
id,
parentId: branchPointId,
timestamp: new Date().toISOString(),
fromId: fromId ?? branchPointId,
summary,
};
appendFileSync(sessionFile, JSON.stringify(entry) + "\n", "utf8");
return id;
}
/**
* Copy the session file to destDir for parallel worker isolation.
* Returns the path of the copy.
*/
export function copySessionFile(sessionFile: string, destDir: string): string {
const id = randomBytes(4).toString("hex");
const dest = join(destDir, `subagent-${id}.jsonl`);
copyFileSync(sessionFile, dest);
return dest;
}
/**
* Read new entries from sourceFile (after afterLine), append them to targetFile.
* Returns the appended entries.
*/
export function mergeNewEntries(
sourceFile: string,
targetFile: string,
afterLine: number,
): SessionEntry[] {
const entries = getNewEntries(sourceFile, afterLine);
for (const entry of entries) {
appendFileSync(targetFile, JSON.stringify(entry) + "\n", "utf8");
}
return entries;
}
pi-extension/subagents/status.ts
+513
View File
@@ -0,0 +1,513 @@
import { readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
export const SNAPSHOT_STALLED_AFTER_MS = 60_000;
export const DEFAULT_STATUS_LINE_LIMIT = 4;
export const MAX_STATUS_NAME_LENGTH = 72;
export const MAX_STATUS_LINE_LENGTH = 120;
const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "../..");
const DEFAULT_STATUS_CONFIG_PATH = join(PACKAGE_ROOT, "config.json");
const STATUS_CONFIG_EXAMPLE_PATH = join(PACKAGE_ROOT, "config.json.example");
export type SubagentStatusKind = "starting" | "active" | "waiting" | "stalled" | "running";
export type SubagentStatusSource = "pi" | "claude";
export type SubagentStatusTransition = "stalled" | "recovered" | null;
export type StatusSnapshotState = "unseen" | "present" | "missing" | "invalid" | "wrong-id";
export type StatusActivityPhase = "starting" | "active" | "waiting" | "done";
export interface StatusConfig {
enabled: boolean;
lineLimit: number;
}
export type StatusObservation =
| {
snapshot: "present";
updatedAt: number;
sequence: number;
phase: StatusActivityPhase;
active?: boolean;
activeScope?: string;
activeSince?: number;
waitingSince?: number;
latestEvent?: string;
activityLabel?: string;
}
| {
snapshot: "missing" | "invalid" | "wrong-id";
snapshotError?: string;
};
export interface SubagentStatusState {
source: SubagentStatusSource;
startTimeMs: number;
firstObservationAtMs: number | null;
lastActivityAtMs: number | null;
lastActivitySequence: number | null;
localOverrideAtMs: number | null;
localOverrideSequence: number | null;
activeNow: boolean;
activeSinceMs: number | null;
activeScope: string | null;
waitingSinceMs: number | null;
phase: StatusActivityPhase | null;
latestEvent: string | null;
activityLabel: string | null;
snapshotState: StatusSnapshotState;
snapshotProblemSinceMs: number | null;
snapshotError: string | null;
currentKind: SubagentStatusKind;
}
export interface StatusSnapshot {
kind: SubagentStatusKind;
elapsedMs: number;
elapsedText: string;
activeSinceMs: number | null;
activeDurationText: string | null;
activeScope: string | null;
waitingSinceMs: number | null;
waitingDurationText: string | null;
latestEvent: string | null;
activityLabel: string | null;
snapshotState: StatusSnapshotState;
snapshotError: string | null;
snapshotProblemText: string | null;
statusLabel: string | null;
}
export interface CappedStatusLines {
visibleLines: string[];
overflow: number;
}
function invalidStatusConfig(source: string, message: string): never {
throw new Error(`Invalid subagent status config in ${source}: ${message}`);
}
function requireObject(value: unknown, source: string, fieldName: string): Record<string, unknown> {
if (value == null || typeof value !== "object" || Array.isArray(value)) {
invalidStatusConfig(source, `${fieldName} must be an object`);
}
return value as Record<string, unknown>;
}
function requireBoolean(value: unknown, source: string, fieldName: string): boolean {
if (typeof value !== "boolean") {
invalidStatusConfig(source, `${fieldName} must be a boolean`);
}
return value;
}
function rejectUnsupportedKeys(
value: Record<string, unknown>,
allowedKeys: string[],
source: string,
fieldName: string,
): void {
const unsupportedKeys = Object.keys(value).filter((key) => !allowedKeys.includes(key));
if (unsupportedKeys.length > 0) {
invalidStatusConfig(source, `${fieldName} has unsupported key(s): ${unsupportedKeys.join(", ")}`);
}
}
function truncateText(text: string, maxLength: number): string {
if (text.length <= maxLength) return text;
if (maxLength <= 1) return text.slice(0, maxLength);
return `${text.slice(0, maxLength - 1)}…`;
}
export function normalizeStatusName(name: string): string {
const collapsed = name.replace(/\s+/g, " ").trim() || "subagent";
return truncateText(collapsed, MAX_STATUS_NAME_LENGTH);
}
function boundStatusLine(line: string): string {
return truncateText(line.replace(/\s+/g, " ").trim(), MAX_STATUS_LINE_LENGTH);
}
function snapshotProblemLabel(snapshotState: StatusSnapshotState): string | null {
if (snapshotState === "wrong-id") return "wrong activity id";
return null;
}
function activityLabel(snapshot: Pick<StatusSnapshot, "activityLabel" | "activeScope">): string | null {
return snapshot.activityLabel ?? snapshot.activeScope;
}
export function parseStatusConfig(rawConfig: unknown, source = "config.json"): StatusConfig {
const config = requireObject(rawConfig, source, "root");
const status = requireObject(config.status, source, "status");
rejectUnsupportedKeys(status, ["enabled"], source, "status");
const enabled = requireBoolean(status.enabled, source, "status.enabled");
return {
enabled,
lineLimit: DEFAULT_STATUS_LINE_LIMIT,
};
}
function readStatusConfigFile(configPath: string, examplePath: string): { sourcePath: string; rawConfig: string } {
try {
return { sourcePath: configPath, rawConfig: readFileSync(configPath, "utf8") };
} catch (error) {
const errno = error as NodeJS.ErrnoException;
if (errno.code !== "ENOENT") throw error;
}
try {
return { sourcePath: examplePath, rawConfig: readFileSync(examplePath, "utf8") };
} catch (error) {
const errno = error as NodeJS.ErrnoException;
if (errno.code === "ENOENT") {
throw new Error(
`Missing subagent status config. Expected ${configPath} or ${examplePath}.`,
);
}
throw error;
}
}
export function loadStatusConfig(
configPath = DEFAULT_STATUS_CONFIG_PATH,
examplePath = STATUS_CONFIG_EXAMPLE_PATH,
): StatusConfig {
const { sourcePath, rawConfig } = readStatusConfigFile(configPath, examplePath);
let parsed: unknown;
try {
parsed = JSON.parse(rawConfig) as unknown;
} catch (error) {
const detail = error instanceof Error ? error.message : String(error);
throw new Error(`Invalid JSON in subagent config ${sourcePath}: ${detail}`);
}
return parseStatusConfig(parsed, sourcePath);
}
export function formatElapsedDuration(ms: number): string {
const totalSeconds = Math.max(0, Math.floor(ms / 1000));
if (totalSeconds < 60) return `${totalSeconds}s`;
const hours = Math.floor(totalSeconds / 3600);
const minutes = Math.floor((totalSeconds % 3600) / 60);
if (hours > 0) return `${hours}h ${minutes}m`;
return `${minutes}m`;
}
export function createStatusState(params: {
source: SubagentStatusSource;
startTimeMs: number;
}): SubagentStatusState {
const initialKind = params.source === "claude" ? "running" : "starting";
return {
source: params.source,
startTimeMs: params.startTimeMs,
firstObservationAtMs: null,
lastActivityAtMs: null,
lastActivitySequence: null,
localOverrideAtMs: null,
localOverrideSequence: null,
activeNow: false,
activeSinceMs: null,
activeScope: null,
waitingSinceMs: null,
phase: null,
latestEvent: null,
activityLabel: null,
snapshotState: params.source === "claude" ? "unseen" : "unseen",
snapshotProblemSinceMs: null,
snapshotError: null,
currentKind: initialKind,
};
}
export function observeStatus(
state: SubagentStatusState,
observation: StatusObservation,
now: number,
): SubagentStatusState {
if (state.source === "claude") return state;
if (observation.snapshot !== "present") {
return {
...state,
firstObservationAtMs: state.firstObservationAtMs ?? now,
snapshotState: observation.snapshot,
snapshotProblemSinceMs: state.snapshotProblemSinceMs ?? now,
snapshotError: observation.snapshotError ?? null,
};
}
const updatedAt = observation.updatedAt;
const sequence = observation.sequence;
const lastActivityAtMs = state.lastActivityAtMs;
const lastActivitySequence = state.lastActivitySequence;
const olderThanLastActivity = lastActivityAtMs != null && (
updatedAt < lastActivityAtMs ||
(updatedAt === lastActivityAtMs && lastActivitySequence != null && sequence < lastActivitySequence)
);
if (olderThanLastActivity) return state;
const blockedByLocalOverride = state.localOverrideAtMs != null && (
updatedAt < state.localOverrideAtMs ||
(updatedAt === state.localOverrideAtMs && state.localOverrideSequence != null && sequence <= state.localOverrideSequence)
);
if (blockedByLocalOverride) return state;
const phase = observation.phase;
const activeNow = phase === "active" || observation.active === true;
const activeSinceMs = activeNow
? observation.activeSince ?? state.activeSinceMs ?? updatedAt
: null;
const waitingSinceMs = phase === "waiting"
? observation.waitingSince ?? state.waitingSinceMs ?? updatedAt
: null;
return {
...state,
firstObservationAtMs: state.firstObservationAtMs ?? now,
lastActivityAtMs: updatedAt,
lastActivitySequence: sequence,
activeNow,
activeSinceMs,
activeScope: activeNow ? observation.activeScope ?? null : null,
waitingSinceMs,
phase,
latestEvent: observation.latestEvent ?? null,
activityLabel: observation.activityLabel ?? null,
snapshotState: "present",
snapshotProblemSinceMs: null,
snapshotError: null,
localOverrideAtMs: null,
localOverrideSequence: null,
};
}
export function forceStatusAfterInterrupt(state: SubagentStatusState, now: number): SubagentStatusState {
if (state.source === "claude") return state;
return {
...state,
firstObservationAtMs: state.firstObservationAtMs ?? now,
lastActivityAtMs: now,
localOverrideAtMs: now,
localOverrideSequence: state.lastActivitySequence,
activeNow: false,
activeSinceMs: null,
activeScope: null,
waitingSinceMs: now,
phase: "waiting",
latestEvent: "interrupt_requested",
activityLabel: "interrupted",
snapshotState: "present",
snapshotProblemSinceMs: null,
snapshotError: null,
currentKind: "waiting",
};
}
function classifyProblemState(state: SubagentStatusState, now: number): Pick<StatusSnapshot, "kind" | "statusLabel"> {
const problemLabel = snapshotProblemLabel(state.snapshotState);
const hasValidSnapshot = state.lastActivityAtMs != null;
if (!hasValidSnapshot) {
const referenceMs = state.firstObservationAtMs ?? state.startTimeMs;
const elapsedMs = Math.max(0, now - referenceMs);
return elapsedMs >= SNAPSHOT_STALLED_AFTER_MS
? { kind: "stalled", statusLabel: problemLabel }
: { kind: "starting", statusLabel: null };
}
const problemSinceMs = state.snapshotProblemSinceMs ?? now;
const problemMs = Math.max(0, now - problemSinceMs);
if (problemMs >= SNAPSHOT_STALLED_AFTER_MS) return { kind: "stalled", statusLabel: problemLabel };
const lastHealthyKind = state.activeNow
? "active"
: state.waitingSinceMs != null || state.phase === "done"
? "waiting"
: state.currentKind === "stalled"
? "starting"
: state.currentKind;
return { kind: lastHealthyKind, statusLabel: problemLabel };
}
export function classifyStatus(state: SubagentStatusState, now: number): StatusSnapshot {
const elapsedMs = Math.max(0, now - state.startTimeMs);
const elapsedText = formatElapsedDuration(elapsedMs);
if (state.source === "claude") {
return {
kind: "running",
elapsedMs,
elapsedText,
activeSinceMs: null,
activeDurationText: null,
activeScope: null,
waitingSinceMs: null,
waitingDurationText: null,
latestEvent: null,
activityLabel: null,
snapshotState: state.snapshotState,
snapshotError: null,
snapshotProblemText: null,
statusLabel: null,
};
}
let kind: SubagentStatusKind;
let statusLabel: string | null = null;
if (state.snapshotState === "present") {
if (state.phase === "active" || state.activeNow) {
kind = "active";
} else if (state.phase === "waiting") {
kind = "waiting";
} else if (state.phase === "done") {
kind = "waiting";
statusLabel = "done";
} else {
const referenceMs = state.firstObservationAtMs ?? state.startTimeMs;
const elapsedSinceObservationMs = Math.max(0, now - referenceMs);
kind = elapsedSinceObservationMs >= SNAPSHOT_STALLED_AFTER_MS ? "stalled" : "starting";
statusLabel = null;
}
} else {
const classified = classifyProblemState(state, now);
kind = classified.kind;
statusLabel = classified.statusLabel;
}
const activeDurationText = state.activeSinceMs == null
? null
: formatElapsedDuration(now - state.activeSinceMs);
const waitingDurationText = state.waitingSinceMs == null
? null
: formatElapsedDuration(now - state.waitingSinceMs);
const snapshotProblemText = state.snapshotProblemSinceMs == null
? null
: formatElapsedDuration(now - state.snapshotProblemSinceMs);
return {
kind,
elapsedMs,
elapsedText,
activeSinceMs: state.activeSinceMs,
activeDurationText,
activeScope: state.activeScope,
waitingSinceMs: state.waitingSinceMs,
waitingDurationText,
latestEvent: state.latestEvent,
activityLabel: state.activityLabel,
snapshotState: state.snapshotState,
snapshotError: state.snapshotError,
snapshotProblemText,
statusLabel,
};
}
export function advanceStatusState(
state: SubagentStatusState,
now: number,
): {
nextState: SubagentStatusState;
snapshot: StatusSnapshot;
transition: SubagentStatusTransition;
} {
const snapshot = classifyStatus(state, now);
const transition =
state.currentKind !== "stalled" && snapshot.kind === "stalled"
? "stalled"
: state.currentKind === "stalled" && (snapshot.kind === "active" || snapshot.kind === "waiting")
? "recovered"
: null;
return {
snapshot,
transition,
nextState: {
...state,
currentKind: snapshot.kind,
},
};
}
function formatActiveDetail(snapshot: StatusSnapshot): string {
const label = activityLabel(snapshot);
if (!label) return "active";
const duration = snapshot.activeDurationText ? ` ${snapshot.activeDurationText}` : "";
return `active (${label}${duration})`;
}
function formatWaitingDetail(snapshot: StatusSnapshot): string {
const duration = snapshot.waitingDurationText ? ` ${snapshot.waitingDurationText}` : "";
return `waiting${duration}`;
}
function formatStalledDetail(snapshot: StatusSnapshot): string {
const detail = snapshot.statusLabel ? ` (${snapshot.statusLabel})` : "";
const duration = snapshot.snapshotProblemText ? ` ${snapshot.snapshotProblemText}` : "";
return `stalled${duration}${detail}`;
}
export function formatStatusLine(name: string, snapshot: StatusSnapshot): string {
const boundedName = normalizeStatusName(name);
if (snapshot.kind === "starting") {
const label = snapshot.statusLabel ? ` (${snapshot.statusLabel})` : "";
return boundStatusLine(`${boundedName} running ${snapshot.elapsedText}, starting${label}.`);
}
if (snapshot.kind === "running") {
return boundStatusLine(`${boundedName} running ${snapshot.elapsedText}.`);
}
if (snapshot.kind === "active") {
return boundStatusLine(`${boundedName} running ${snapshot.elapsedText}, ${formatActiveDetail(snapshot)}.`);
}
if (snapshot.kind === "waiting") {
const problem = snapshot.statusLabel && snapshot.statusLabel !== "done"
? ` (${snapshot.statusLabel})`
: snapshot.statusLabel === "done"
? " (done)"
: "";
return boundStatusLine(`${boundedName} running ${snapshot.elapsedText}, ${formatWaitingDetail(snapshot)}${problem}.`);
}
return boundStatusLine(`${boundedName} running ${snapshot.elapsedText}, ${formatStalledDetail(snapshot)}.`);
}
export function formatTransitionLine(
name: string,
snapshot: StatusSnapshot,
transition: Exclude<SubagentStatusTransition, null>,
): string {
const boundedName = normalizeStatusName(name);
if (transition === "recovered") {
const detail = snapshot.kind === "waiting" ? formatWaitingDetail(snapshot) : formatActiveDetail(snapshot);
return boundStatusLine(`${boundedName} running ${snapshot.elapsedText}, recovered; ${detail}.`);
}
return formatStatusLine(boundedName, snapshot);
}
export function capStatusLines(lines: string[], lineLimit: number): CappedStatusLines {
const visibleLines = lines.slice(0, lineLimit);
return {
visibleLines,
overflow: Math.max(0, lines.length - visibleLines.length),
};
}
export function formatStatusAggregate(lines: string[], lineLimit: number): string {
const { visibleLines, overflow } = capStatusLines(lines, lineLimit);
const bulletLines = visibleLines.map((line) => `• ${line}`);
if (overflow > 0) bulletLines.push(`• +${overflow} more running.`);
return `Subagent status:\n${bulletLines.join("\n")}`;
}
pi-extension/subagents/subagent-done.ts
+324
View File
@@ -0,0 +1,324 @@
/**
* Extension loaded into sub-agents.
* - Shows agent identity + available tools as a styled widget above the editor (toggle with Ctrl+J)
* - Provides a `subagent_done` tool for autonomous agents to self-terminate
*/
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
import { Box, Text } from "@mariozechner/pi-tui";
import { Type } from "@sinclair/typebox";
import { writeFileSync } from "node:fs";
import { createSubagentActivityRecorder } from "./activity.ts";
export function shouldMarkUserTookOver(agentStarted: boolean): boolean {
return agentStarted;
}
export function shouldAutoExitOnAgentEnd(
_userTookOver: boolean,
messages: any[] | undefined,
): boolean {
// Manual input should not strand an auto-exit subagent. If the latest agent
// turn completed normally, close the session. Escape/abort still leaves it
// open for inspection or another prompt.
//
// stopReason: "error" (e.g. exhausted retries on a provider overload) also
// returns true — we want to shut down so the parent is woken up — but we
// pair this with findLatestAssistantError() so the parent learns it was an
// error, not a clean completion.
if (messages) {
for (let i = messages.length - 1; i >= 0; i--) {
const msg = messages[i];
if (msg?.role === "assistant") {
return msg.stopReason !== "aborted";
}
}
}
return true;
}
export interface SubagentErrorInfo {
errorMessage: string;
stopReason: "error";
}
/**
* If the last assistant message in the turn ended with `stopReason: "error"`
* (typically auto-retry exhausted on an overload / rate limit / server error),
* return its error info so the parent orchestrator can surface a clear
* failure instead of silently treating the run as completed.
*
* Returns `null` when the latest assistant turn completed normally or was
* aborted by the user (handled separately by shouldAutoExitOnAgentEnd).
*/
export function findLatestAssistantError(
messages: any[] | undefined,
): SubagentErrorInfo | null {
if (!messages) return null;
for (let i = messages.length - 1; i >= 0; i--) {
const msg = messages[i];
if (msg?.role !== "assistant") continue;
if (msg.stopReason !== "error") return null;
const raw = typeof msg.errorMessage === "string" ? msg.errorMessage.trim() : "";
return {
errorMessage: raw || "Subagent agent loop ended with stopReason=error (no errorMessage field).",
stopReason: "error",
};
}
return null;
}
export function parseDeniedTools(rawValue: string | undefined): string[] {
return (rawValue ?? "")
.split(",")
.map((value) => value.trim())
.filter(Boolean);
}
export default function (pi: ExtensionAPI) {
let toolNames: string[] = [];
let denied: string[] = [];
let expanded = false;
// Read subagent identity from env vars (set by parent orchestrator)
const subagentName = process.env.PI_SUBAGENT_NAME ?? "";
const subagentAgent = process.env.PI_SUBAGENT_AGENT ?? "";
const deniedToolsValue = process.env.PI_DENY_TOOLS;
const autoExit = process.env.PI_SUBAGENT_AUTO_EXIT === "1";
const recorder = createSubagentActivityRecorder({
runningChildId: process.env.PI_SUBAGENT_ID,
activityFile: process.env.PI_SUBAGENT_ACTIVITY_FILE,
});
function renderWidget(ctx: { ui: { setWidget: Function } }, _theme: any) {
ctx.ui.setWidget(
"subagent-tools",
(_tui: any, theme: any) => {
const box = new Box(1, 0, (text: string) => theme.bg("toolSuccessBg", text));
const label = subagentAgent || subagentName;
const agentTag = label ? theme.bold(theme.fg("accent", `[${label}]`)) : "";
if (expanded) {
// Expanded: full tool list + denied
const countInfo = theme.fg("dim", ` — ${toolNames.length} available`);
const hint = theme.fg("muted", " (Ctrl+J to collapse)");
const toolList = toolNames
.map((name: string) => theme.fg("dim", name))
.join(theme.fg("muted", ", "));
let deniedLine = "";
if (denied.length > 0) {
const deniedList = denied
.map((name: string) => theme.fg("error", name))
.join(theme.fg("muted", ", "));
deniedLine = "\n" + theme.fg("muted", "denied: ") + deniedList;
}
const content = new Text(
`${agentTag}${countInfo}${hint}\n${toolList}${deniedLine}`,
0,
0,
);
box.addChild(content);
} else {
// Collapsed: one-line summary
const countInfo = theme.fg("dim", ` — ${toolNames.length} tools`);
const deniedInfo =
denied.length > 0
? theme.fg("dim", " · ") + theme.fg("error", `${denied.length} denied`)
: "";
const hint = theme.fg("muted", " (Ctrl+J to expand)");
const content = new Text(`${agentTag}${countInfo}${deniedInfo}${hint}`, 0, 0);
box.addChild(content);
}
return box;
},
{ placement: "aboveEditor" },
);
}
let userTookOver = false;
let agentStarted = false;
// Show widget + status bar on session start
pi.on("session_start", (_event, ctx) => {
recorder.sessionStart();
const tools = pi.getAllTools();
toolNames = tools.map((t) => t.name).sort();
denied = parseDeniedTools(deniedToolsValue);
renderWidget(ctx, null);
});
pi.on("input", () => {
recorder.input();
// Ignore the initial task message that starts an autonomous subagent.
// Only inputs after the first agent run has started count as user takeover.
if (!shouldMarkUserTookOver(agentStarted)) return;
userTookOver = true;
});
pi.on("before_agent_start", () => {
recorder.beforeAgentStart();
});
pi.on("agent_start", () => {
agentStarted = true;
recorder.agentStart();
});
pi.on("agent_end", (event, ctx) => {
const messages = (event as any).messages as any[] | undefined;
const shouldExit = autoExit && shouldAutoExitOnAgentEnd(userTookOver, messages);
if (shouldExit) {
// Surface stopReason: "error" turns (auto-retry exhausted, provider
// overload, etc.) to the parent via the .exit sidecar so the watcher
// can report a clear failure with the underlying error message.
// Without this the parent would only see exit code 0 and a stale
// assistant message, mistaking the crash for a successful completion.
const errorInfo = findLatestAssistantError(messages);
const sessionFile = process.env.PI_SUBAGENT_SESSION;
if (errorInfo && sessionFile) {
try {
writeFileSync(
`${sessionFile}.exit`,
JSON.stringify({
type: "error",
errorMessage: errorInfo.errorMessage,
stopReason: errorInfo.stopReason,
}),
);
} catch {
// Best effort — even without the sidecar, watcher's session-file
// fallback can still recover the errorMessage.
}
}
recorder.agentEndDone();
ctx.shutdown();
return;
}
recorder.agentEndWaiting();
if (autoExit) {
// Reset any recorded manual input marker. Auto-exit is decided by whether
// the latest agent turn completed normally, not by who initiated it.
userTookOver = false;
}
});
pi.on("turn_start", (event) => {
recorder.turnStart((event as any).turnIndex);
});
pi.on("turn_end", (event) => {
recorder.turnEnd((event as any).turnIndex);
});
pi.on("before_provider_request", () => {
recorder.beforeProviderRequest();
});
pi.on("after_provider_response", () => {
recorder.afterProviderResponse();
});
pi.on("message_update", (event) => {
recorder.messageUpdate((event as any).assistantMessageEvent?.type);
});
pi.on("tool_execution_start", (event) => {
recorder.toolExecutionStart((event as any).toolCallId, (event as any).toolName);
});
pi.on("tool_call", (event) => {
recorder.toolCall((event as any).toolCallId, (event as any).toolName);
});
pi.on("tool_execution_update", (event) => {
recorder.toolExecutionUpdate((event as any).toolCallId, (event as any).toolName);
});
pi.on("tool_result", (event) => {
recorder.toolResult((event as any).toolCallId, (event as any).toolName);
});
pi.on("tool_execution_end", (event) => {
recorder.toolExecutionEnd((event as any).toolCallId, (event as any).toolName);
});
pi.on("session_shutdown", (event) => {
recorder.sessionShutdown((event as any).reason);
});
// Toggle expand/collapse with Ctrl+J
pi.registerShortcut("ctrl+j", {
description: "Toggle subagent tools widget",
handler: (ctx) => {
expanded = !expanded;
renderWidget(ctx, null);
},
});
pi.registerTool({
name: "caller_ping",
label: "Caller Ping",
description:
"Send a help request to the parent agent and exit this session. " +
"The parent will be notified with your message and can resume this session with a response. " +
"Use when you're stuck, need clarification, or need the parent to take action.",
parameters: Type.Object({
message: Type.String({ description: "What you need help with" }),
}),
async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
const sessionFile = process.env.PI_SUBAGENT_SESSION;
if (!sessionFile) {
throw new Error(
"caller_ping is only available in subagent contexts. " +
"PI_SUBAGENT_SESSION environment variable is not set.",
);
}
recorder.callerPing();
const exitData = {
type: "ping" as const,
name: process.env.PI_SUBAGENT_NAME ?? "subagent",
message: params.message,
};
writeFileSync(`${sessionFile}.exit`, JSON.stringify(exitData));
ctx.shutdown();
return {
content: [{ type: "text", text: "Ping sent. Session will exit and parent will be notified." }],
details: {},
};
},
});
pi.registerTool({
name: "subagent_done",
label: "Subagent Done",
description:
"Call this tool when you have completed your task. " +
"It will close this session and return your results to the main session. " +
"Your LAST assistant message before calling this becomes the summary returned to the caller.",
parameters: Type.Object({}),
async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
const sessionFile = process.env.PI_SUBAGENT_SESSION;
recorder.subagentDone();
if (sessionFile) {
writeFileSync(`${sessionFile}.exit`, JSON.stringify({ type: "done" }));
}
ctx.shutdown();
return {
content: [{ type: "text", text: "Shutting down subagent session." }],
details: {},
};
},
});
}
test/integration/agents/test-echo.md
+13
View File
@@ -0,0 +1,13 @@
---
name: test-echo
description: Integration test agent — completes simple file-writing tasks
model: anthropic/claude-haiku-4-5
tools: read, bash, write, edit
spawning: false
auto-exit: true
disable-model-invocation: true
---
You are a test agent. Complete the task given to you immediately. Be direct and concise.
When asked to write content to a file, do it right away using the bash tool.
Do not ask questions. Do not explain. Just execute the task.
test/integration/agents/test-ping.md
+11
View File
@@ -0,0 +1,11 @@
---
name: test-ping
description: Integration test agent — calls caller_ping instead of completing task
model: anthropic/claude-haiku-4-5
tools: read, bash
spawning: false
disable-model-invocation: true
---
You are a test agent. When given ANY task, you must call the caller_ping tool with the message set to "PING: " followed by the task text you received.
Do NOT complete the task yourself. Do NOT use any other tools. ONLY call caller_ping.
test/integration/harness.ts
+381
View File
@@ -0,0 +1,381 @@
/**
* Integration test harness for pi-interactive-subagents.
*
* Provides utilities to:
* - Detect available mux backends (cmux, tmux, zellij)
* - Create isolated test environments with test agent definitions
* - Start real pi sessions in mux surfaces
* - Poll for file creation and screen output
* - Clean up surfaces and temp files after tests
*/
import { execFileSync } from "node:child_process";
import {
mkdtempSync,
mkdirSync,
cpSync,
readdirSync,
rmSync,
existsSync,
readFileSync,
unlinkSync,
} from "node:fs";
import { join, resolve, dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { tmpdir } from "node:os";
import {
getMuxBackend,
createSurface,
createSurfaceSplit,
sendCommand,
sendLongCommand,
readScreen,
readScreenAsync,
closeSurface,
sendEscape,
shellEscape,
parseCmuxFocusedSnapshotFromJson,
parseCmuxPaneRefForSurfaceFromJson,
type MuxBackend,
} from "../../pi-extension/subagents/cmux.ts";
// Re-export mux primitives for tests
export {
createSurface,
createSurfaceSplit,
sendCommand,
sendLongCommand,
readScreen,
readScreenAsync,
closeSurface,
sendEscape,
shellEscape,
};
export type { MuxBackend };
// ── Paths ──
const HARNESS_DIR = dirname(fileURLToPath(import.meta.url));
const PROJECT_ROOT = resolve(HARNESS_DIR, "../..");
const TEST_AGENTS_SRC = join(HARNESS_DIR, "agents");
/**
* Absolute path to the extension source in the working tree.
*
* Integration tests must exercise the code on the current branch — NOT the
* version installed as a pi-package under `~/.pi/agent/git/...` or the project
* mirror under `.pi/git/...`, which stays pinned to the last released tag.
*
* We force-load this file via `pi -ne -e <path>` in startPi() below so local
* edits are always the code under test, regardless of what pi-packages are
* installed on the host.
*/
const EXTENSION_SOURCE = join(PROJECT_ROOT, "pi-extension", "subagents", "index.ts");
// ── Configuration ──
/** Model used for integration tests. Override with PI_TEST_MODEL env var. */
export const TEST_MODEL = process.env.PI_TEST_MODEL ?? "anthropic/claude-haiku-4-5";
/** Per-test timeout in ms. Override with PI_TEST_TIMEOUT env var. */
export const PI_TIMEOUT = Number(process.env.PI_TEST_TIMEOUT ?? "120000");
// ── Backend detection ──
/**
* Detect which mux backends are actually available in the current environment.
* Temporarily sets PI_SUBAGENT_MUX to probe each backend.
*/
export function getAvailableBackends(): MuxBackend[] {
const backends: MuxBackend[] = [];
const orig = process.env.PI_SUBAGENT_MUX;
for (const backend of ["cmux", "tmux", "zellij"] as MuxBackend[]) {
process.env.PI_SUBAGENT_MUX = backend;
try {
if (getMuxBackend() === backend) backends.push(backend);
} catch {}
}
if (orig === undefined) delete process.env.PI_SUBAGENT_MUX;
else process.env.PI_SUBAGENT_MUX = orig;
return backends;
}
export function setBackend(backend: MuxBackend): string | undefined {
const prev = process.env.PI_SUBAGENT_MUX;
process.env.PI_SUBAGENT_MUX = backend;
return prev;
}
export function restoreBackend(prev: string | undefined): void {
if (prev === undefined) delete process.env.PI_SUBAGENT_MUX;
else process.env.PI_SUBAGENT_MUX = prev;
}
export function focusSurface(backend: MuxBackend, surface: string): void {
if (backend === "cmux") {
const pane = getSurfacePane(backend, surface);
if (pane) execFileSync("cmux", ["focus-pane", "--pane", pane], { encoding: "utf8" });
execFileSync("cmux", ["focus-panel", "--panel", surface], { encoding: "utf8" });
return;
}
if (backend === "tmux") {
execFileSync("tmux", ["select-pane", "-t", surface], { encoding: "utf8" });
return;
}
throw new Error(`Focus helpers are not implemented for ${backend}`);
}
export function getFocusedSurface(backend: MuxBackend): string | null {
if (backend === "cmux") {
const info = execFileSync("cmux", ["identify", "--json"], { encoding: "utf8" });
return parseCmuxFocusedSnapshotFromJson(info)?.surfaceRef ?? null;
}
if (backend === "tmux") {
try {
const panes = execFileSync("tmux", ["list-panes", "-F", "#{pane_id} #{pane_active}"], {
encoding: "utf8",
});
const activeLine = panes.split("\n").find((line) => line.endsWith(" 1"));
return activeLine?.split(" ")[0] ?? null;
} catch {
return null;
}
}
throw new Error(`Focus helpers are not implemented for ${backend}`);
}
export function getSurfacePane(backend: MuxBackend, surface: string): string | null {
if (backend === "cmux") {
const info = execFileSync("cmux", ["identify", "--surface", surface], { encoding: "utf8" });
return parseCmuxPaneRefForSurfaceFromJson(info, surface);
}
if (backend === "tmux") return surface;
throw new Error(`Pane lookup is not implemented for ${backend}`);
}
export async function waitForFocusedSurface(
backend: MuxBackend,
surface: string,
timeout: number = PI_TIMEOUT,
): Promise<void> {
const start = Date.now();
while (Date.now() - start < timeout) {
if (getFocusedSurface(backend) === surface) return;
await sleep(200);
}
throw new Error(
`Timeout (${timeout}ms) waiting for focused ${backend} surface ${surface}; ` +
`current focus is ${getFocusedSurface(backend) ?? "unknown"}`,
);
}
// ── Test environment ──
export interface TestEnv {
/** Temp directory serving as the test project root */
dir: string;
/** Active mux backend for this test run */
backend: MuxBackend;
/** Surfaces created during the test (cleaned up automatically) */
surfaces: string[];
/** Temp files to clean up */
tempFiles: string[];
}
/**
* Create an isolated test environment with test agent definitions.
* The temp dir has `.pi/agents/` containing copies of all test agents.
*/
export function createTestEnv(backend: MuxBackend): TestEnv {
const dir = mkdtempSync(join(tmpdir(), "pi-integ-"));
const agentsDir = join(dir, ".pi", "agents");
mkdirSync(agentsDir, { recursive: true });
// Copy test agent definitions into the project-local agents dir
if (existsSync(TEST_AGENTS_SRC)) {
for (const file of readdirSync(TEST_AGENTS_SRC)) {
if (file.endsWith(".md")) {
cpSync(join(TEST_AGENTS_SRC, file), join(agentsDir, file));
}
}
}
return { dir, backend, surfaces: [], tempFiles: [] };
}
/**
* Clean up all resources created during the test.
*/
export function cleanupTestEnv(env: TestEnv): void {
for (const surface of env.surfaces) {
try {
closeSurface(surface);
} catch {}
}
for (const file of env.tempFiles) {
try {
unlinkSync(file);
} catch {}
}
try {
rmSync(env.dir, { recursive: true, force: true });
} catch {}
}
/**
* Create a surface and register it for automatic cleanup.
*/
export function createTrackedSurface(env: TestEnv, name: string): string {
const surface = createSurface(name);
env.surfaces.push(surface);
return surface;
}
export function createTrackedSurfaceSplit(
env: TestEnv,
name: string,
direction: "left" | "right" | "up" | "down",
fromSurface?: string,
): string {
const surface = createSurfaceSplit(name, direction, fromSurface);
env.surfaces.push(surface);
return surface;
}
/**
* Remove a surface from tracking (after manual close).
*/
export function untrackSurface(env: TestEnv, surface: string): void {
env.surfaces = env.surfaces.filter((s) => s !== surface);
}
// ── Pi session management ──
/**
* Start a pi session in a mux surface with the subagents extension loaded.
* Returns immediately — the pi process runs asynchronously in the surface.
*
* The command ends with a sentinel so we can detect when pi exits:
* `pi ...; echo '__TEST_DONE_'$?'__'`
*/
export function startPi(
surface: string,
testDir: string,
task: string,
opts?: { model?: string; extraArgs?: string },
): void {
const model = opts?.model ?? TEST_MODEL;
const extra = opts?.extraArgs ?? "";
// Force pi to load the working-tree extension (not an installed pi-package
// snapshot). `-ne` disables extension auto-discovery, `-e <path>` loads the
// current branch's source directly. Without this, the tests silently run
// against whatever version is checked out under `~/.pi/agent/git/...`.
const cmd = [
`cd ${shellEscape(testDir)} &&`,
`pi`,
`-ne`,
`-e ${shellEscape(EXTENSION_SOURCE)}`,
`--model ${shellEscape(model)}`,
extra,
shellEscape(task),
]
.filter(Boolean)
.join(" ");
sendLongCommand(surface, `${cmd}; echo '__TEST_DONE_'$?'__'`, {
scriptPath: join(testDir, `test-launch-${Date.now()}.sh`),
});
}
// ── Polling helpers ──
/**
* Poll until a regex pattern appears in the surface's screen output.
* Throws on timeout with the last screen contents for debugging.
*/
export async function waitForScreen(
surface: string,
pattern: RegExp,
timeout: number = PI_TIMEOUT,
lines: number = 200,
): Promise<string> {
const start = Date.now();
while (Date.now() - start < timeout) {
try {
const screen = await readScreenAsync(surface, lines);
if (pattern.test(screen)) return screen;
} catch {}
await sleep(2000);
}
let finalScreen = "";
try {
finalScreen = readScreen(surface, lines);
} catch {}
throw new Error(
`Timeout (${timeout}ms) waiting for pattern ${pattern}.\nLast screen:\n${finalScreen.slice(-1000)}`,
);
}
/**
* Poll until a file exists and optionally matches a content pattern.
* Returns the file content on success.
*/
export async function waitForFile(
path: string,
timeout: number = PI_TIMEOUT,
contentPattern?: RegExp,
): Promise<string> {
const start = Date.now();
while (Date.now() - start < timeout) {
if (existsSync(path)) {
const content = readFileSync(path, "utf8");
if (!contentPattern || contentPattern.test(content)) return content;
}
await sleep(2000);
}
throw new Error(
`Timeout (${timeout}ms) waiting for file: ${path}` +
(contentPattern ? ` matching ${contentPattern}` : ""),
);
}
/**
* Wait for the pi process in a surface to exit (sentinel detection).
* Returns the exit code.
*/
export async function waitForPiExit(
surface: string,
timeout: number = PI_TIMEOUT,
): Promise<number> {
const screen = await waitForScreen(surface, /__TEST_DONE_(\d+)__/, timeout);
const match = screen.match(/__TEST_DONE_(\d+)__/);
return match ? parseInt(match[1], 10) : -1;
}
// ── Utilities ──
export function sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}
export function uniqueId(): string {
return Math.random().toString(36).slice(2, 10) + Date.now().toString(36);
}
/**
* Register a temp file for cleanup.
*/
export function trackTempFile(env: TestEnv, path: string): void {
env.tempFiles.push(path);
}
test/integration/mux-surface.test.ts
+243
View File
@@ -0,0 +1,243 @@
/**
* Integration tests for the multiplexer surface layer.
*
* These tests exercise real mux operations: creating panes,
* sending commands, reading screen output, and closing surfaces.
* No LLM calls — fast and free.
*
* Run inside a supported multiplexer:
* cmux bash -c 'npm run test:integration'
* tmux new 'npm run test:integration'
* zellij --session pi # then run: npm run test:integration
*/
import { describe, it, before, after } from "node:test";
import assert from "node:assert/strict";
import { unlinkSync } from "node:fs";
import {
getAvailableBackends,
setBackend,
restoreBackend,
createTestEnv,
cleanupTestEnv,
createTrackedSurface,
createTrackedSurfaceSplit,
focusSurface,
getFocusedSurface,
getSurfacePane,
waitForFocusedSurface,
untrackSurface,
sendCommand,
sendLongCommand,
readScreen,
readScreenAsync,
closeSurface,
sendEscape,
sleep,
uniqueId,
trackTempFile,
waitForFile,
waitForScreen,
type TestEnv,
} from "./harness.ts";
const backends = getAvailableBackends();
const FOCUS_TEST_SHELL_READY_DELAY_MS = Number(process.env.PI_SUBAGENT_SHELL_READY_DELAY_MS ?? "2500");
if (backends.length === 0) {
console.log("⚠️ No mux backend available — skipping mux-surface integration tests");
console.log(" Run inside cmux or tmux to enable these tests.");
}
for (const backend of backends) {
describe(`mux-surface [${backend}]`, { timeout: 60_000 }, () => {
let prevMux: string | undefined;
let env: TestEnv;
before(() => {
prevMux = setBackend(backend);
env = createTestEnv(backend);
});
after(() => {
cleanupTestEnv(env);
restoreBackend(prevMux);
});
it("keeps focus on the active surface while creating and targeting subagent surfaces", async () => {
const anchor = createTrackedSurfaceSplit(env, "focus-anchor", "right");
await sleep(1000);
focusSurface(backend, anchor);
await waitForFocusedSurface(backend, anchor, 10_000);
const childA = createTrackedSurface(env, "focus-child-a");
await sleep(FOCUS_TEST_SHELL_READY_DELAY_MS);
assert.equal(getFocusedSurface(backend), anchor);
const childB = createTrackedSurface(env, "focus-child-b");
await sleep(FOCUS_TEST_SHELL_READY_DELAY_MS);
assert.equal(getFocusedSurface(backend), anchor);
if (backend === "cmux") {
const paneA = getSurfacePane(backend, childA);
const paneB = getSurfacePane(backend, childB);
assert.ok(paneA, `Expected pane ref for ${childA}`);
assert.ok(paneB, `Expected pane ref for ${childB}`);
assert.equal(paneB, paneA);
}
const markerA = uniqueId();
const markerB = uniqueId();
sendCommand(childA, `echo "FOCUS_A_${markerA}"`);
sendCommand(childB, `echo "FOCUS_B_${markerB}"`);
await Promise.all([
waitForScreen(childA, new RegExp(`FOCUS_A_${markerA}`), 20_000, 50),
waitForScreen(childB, new RegExp(`FOCUS_B_${markerB}`), 20_000, 50),
]);
assert.equal(getFocusedSurface(backend), anchor);
});
it("creates a surface, sends a command, reads output, and closes it", async () => {
const surface = createTrackedSurface(env, "echo-test");
await sleep(1000);
const marker = uniqueId();
sendCommand(surface, `echo "MARKER_${marker}"`);
await sleep(1500);
const screen = readScreen(surface, 50);
assert.ok(
screen.includes(`MARKER_${marker}`),
`Expected screen to contain MARKER_${marker}. Got:\n${screen}`,
);
closeSurface(surface);
untrackSurface(env, surface);
});
it("preserves shell special characters in echo output", async () => {
const surface = createTrackedSurface(env, "escape-test");
await sleep(1000);
const marker = uniqueId();
// Single-quoted string — $ and " are literal inside single quotes
sendCommand(surface, `echo 'SPEC_${marker}_$HOME_"quotes"_done'`);
await sleep(1500);
const screen = readScreen(surface, 50);
assert.ok(
screen.includes(`SPEC_${marker}`),
`Expected special-char output. Got:\n${screen}`,
);
// $ should be literal inside single quotes
assert.ok(
screen.includes("$HOME"),
`Expected literal $HOME in output. Got:\n${screen}`,
);
});
it("sends a long command via script file without truncation", async () => {
const surface = createTrackedSurface(env, "long-cmd-test");
await sleep(1000);
const marker = uniqueId();
const longValue = "X".repeat(500);
const command = `echo "LONG_${marker}_${longValue}_END"`;
sendLongCommand(surface, command);
await sleep(2000);
const screen = readScreen(surface, 50);
assert.ok(
screen.includes(`LONG_${marker}`),
`Expected long command output. Got:\n${screen.slice(0, 300)}...`,
);
assert.ok(
screen.includes("_END"),
`Expected full output (not truncated). Got:\n${screen.slice(-300)}`,
);
});
it("reads screen asynchronously", async () => {
const surface = createTrackedSurface(env, "async-read-test");
await sleep(1000);
const marker = uniqueId();
sendCommand(surface, `echo "ASYNC_${marker}"`);
await sleep(1500);
const screen = await readScreenAsync(surface, 50);
assert.ok(
screen.includes(`ASYNC_${marker}`),
`Async read should find marker. Got:\n${screen}`,
);
});
it("manages multiple surfaces concurrently", async () => {
const s1 = createTrackedSurface(env, "multi-1");
const s2 = createTrackedSurface(env, "multi-2");
await sleep(1500);
const m1 = uniqueId();
const m2 = uniqueId();
sendCommand(s1, `echo "S1_${m1}"`);
sendCommand(s2, `echo "S2_${m2}"`);
await sleep(1500);
const screen1 = readScreen(s1, 50);
const screen2 = readScreen(s2, 50);
assert.ok(screen1.includes(`S1_${m1}`), `Surface 1 missing marker. Got:\n${screen1}`);
assert.ok(screen2.includes(`S2_${m2}`), `Surface 2 missing marker. Got:\n${screen2}`);
});
it("writes output to a file and verifies via surface", async () => {
const surface = createTrackedSurface(env, "file-test");
await sleep(1000);
const marker = uniqueId();
const filePath = `/tmp/pi-mux-test-${marker}.txt`;
sendCommand(surface, `echo "FILE_${marker}" > ${filePath} && echo "WRITTEN_${marker}"`);
await waitForScreen(surface, new RegExp(`WRITTEN_${marker}`), 10_000, 50);
const content = await waitForFile(filePath, 10_000, new RegExp(`FILE_${marker}`));
assert.ok(content.includes(`FILE_${marker}`), `File content wrong. Got: ${content}`);
// Clean up
try {
unlinkSync(filePath);
} catch {}
});
it("delivers Escape as byte 27 to the target surface", async () => {
const surface = createTrackedSurface(env, "escape-byte-test");
await sleep(1000);
const marker = uniqueId();
const byteFile = `/tmp/pi-mux-escape-${marker}.txt`;
trackTempFile(env, byteFile);
const nodeProgram =
"const fs = require('node:fs');" +
"if (!process.stdin.isTTY) throw new Error('stdin is not a TTY');" +
"process.stdin.setRawMode(true);" +
"process.stdin.resume();" +
"process.stdout.write('ESC_READY\\n');" +
"process.stdin.once('data', (chunk) => {" +
`fs.writeFileSync(${JSON.stringify(byteFile)}, Array.from(chunk).join(','));` +
"process.exit(0);" +
"});";
const command = `node -e ${JSON.stringify(nodeProgram)}`;
sendLongCommand(surface, command);
await waitForScreen(surface, /ESC_READY/, 15_000, 50);
sendEscape(surface);
const content = await waitForFile(byteFile, 15_000, /^27$/);
assert.equal(content.trim(), "27");
});
});
}
test/integration/subagent-lifecycle.test.ts
+332
View File
@@ -0,0 +1,332 @@
/**
* Integration tests for the full subagent lifecycle.
*
* These tests spawn REAL pi sessions with REAL LLM calls (haiku by default).
* Each test creates a mux surface, runs pi with a task that uses the subagent
* tool, and verifies the outcome via marker files and screen output.
*
* Costs: ~$0.01-0.05 per test run (haiku).
* Duration: ~30-90s per test.
*
* Run inside a supported multiplexer:
* cmux bash -c 'npm run test:integration'
* tmux new 'npm run test:integration'
*
* Configuration:
* PI_TEST_MODEL — model for all pi sessions (default: anthropic/claude-haiku-4-5)
* PI_TEST_TIMEOUT — per-test timeout in ms (default: 120000)
*/
import { describe, it, before, after } from "node:test";
import assert from "node:assert/strict";
import { existsSync, readFileSync, unlinkSync } from "node:fs";
import {
getAvailableBackends,
setBackend,
restoreBackend,
createTestEnv,
cleanupTestEnv,
createTrackedSurface,
startPi,
waitForScreen,
waitForFile,
sleep,
uniqueId,
trackTempFile,
readScreen,
PI_TIMEOUT,
type TestEnv,
} from "./harness.ts";
const backends = getAvailableBackends();
if (backends.length === 0) {
console.log("⚠️ No mux backend available — skipping subagent lifecycle integration tests");
console.log(" Run inside cmux or tmux to enable these tests.");
}
for (const backend of backends) {
describe(`subagent-lifecycle [${backend}]`, { timeout: PI_TIMEOUT * 3 }, () => {
let prevMux: string | undefined;
let env: TestEnv;
before(() => {
prevMux = setBackend(backend);
env = createTestEnv(backend);
});
after(() => {
cleanupTestEnv(env);
restoreBackend(prevMux);
});
// ── Basic spawn + completion ──
it("spawns a subagent that writes a file and verifies the session", async () => {
const id = uniqueId();
const markerFile = `/tmp/pi-integ-echo-${id}.txt`;
trackTempFile(env, markerFile);
const surface = createTrackedSurface(env, `echo-${id}`);
await sleep(1000);
const task = [
`Call the subagent tool with these EXACT parameters:`,
` name: "Echo-${id}"`,
` agent: "test-echo"`,
` task: "Run this bash command: echo 'PASS_${id}' > '${markerFile}'"`,
`Do not do anything else. Just call the subagent tool once.`,
`After you receive the subagent result, say INTEGRATION_COMPLETE.`,
].join("\n");
startPi(surface, env.dir, task);
// Verify: subagent created the marker file
const content = await waitForFile(markerFile, PI_TIMEOUT, /PASS/);
assert.ok(
content.includes(`PASS_${id}`),
`Marker file should contain PASS_${id}. Got: ${content.trim()}`,
);
// Verify: outer pi received the subagent result
const screen = await waitForScreen(
surface,
/INTEGRATION_COMPLETE|completed|Sub-agent.*"Echo/i,
PI_TIMEOUT,
);
// Verify: session file was created (shown in steer result)
const sessionMatch = screen.match(/Session:\s*(\S+\.jsonl)/);
if (sessionMatch) {
const sessionFile = sessionMatch[1];
assert.ok(existsSync(sessionFile), `Subagent session file should exist: ${sessionFile}`);
const lines = readFileSync(sessionFile, "utf8").trim().split("\n");
assert.ok(lines.length >= 2, `Session should have ≥2 entries, got ${lines.length}`);
const header = JSON.parse(lines[0]);
assert.equal(header.type, "session", "First entry should be session header");
assert.ok(header.id, "Session header should have an id");
}
});
// ── In-progress activity snapshots ──
it("keeps a long active tool call from surfacing false stalled status", async () => {
const id = uniqueId();
const startFile = `/tmp/pi-integ-status-start-${id}.txt`;
const markerFile = `/tmp/pi-integ-status-${id}.txt`;
trackTempFile(env, startFile);
trackTempFile(env, markerFile);
const surface = createTrackedSurface(env, `status-${id}`);
await sleep(1000);
const task = [
`Call the subagent tool with these EXACT parameters:`,
` name: "Status-${id}"`,
` agent: "test-echo"`,
` task: "Run this bash command: echo 'START_${id}' > '${startFile}'; sleep 90; echo 'STATUS_${id}' > '${markerFile}'"`,
`Do not do anything else. Just call the subagent tool once.`,
`After you receive the subagent result, say STATUS_TEST_DONE.`,
].join("\n");
startPi(surface, env.dir, task);
const activeScreen = await waitForScreen(surface, /active[\s\S]*bash|bash[\s\S]*active/i, PI_TIMEOUT, 300);
assert.doesNotMatch(activeScreen, /Subagent status[\s\S]*stalled|stalled[\s\S]*Subagent status/i);
await waitForFile(startFile, PI_TIMEOUT, /START_/);
assert.equal(existsSync(markerFile), false, "Completion marker should not exist before the long sleep");
await sleep(65_000);
assert.equal(existsSync(markerFile), false, "Completion marker should not exist before the watchdog assertion");
const watchdogScreen = readScreen(surface, 300);
assert.doesNotMatch(watchdogScreen, /Subagent status[\s\S]*stalled|stalled[\s\S]*Subagent status/i);
const content = await waitForFile(markerFile, PI_TIMEOUT, /STATUS_/);
assert.ok(content.includes(`STATUS_${id}`), `Marker file should contain STATUS_${id}`);
const completionScreen = await waitForScreen(
surface,
/STATUS_TEST_DONE|completed|Sub-agent.*"Status-/i,
PI_TIMEOUT,
300,
);
assert.ok(/STATUS_TEST_DONE|completed/i.test(completionScreen));
});
// ── Parallel subagent spawn ──
it("spawns two subagents in parallel and both complete", async () => {
const id = uniqueId();
const fileA = `/tmp/pi-integ-para-${id}-a.txt`;
const fileB = `/tmp/pi-integ-para-${id}-b.txt`;
trackTempFile(env, fileA);
trackTempFile(env, fileB);
const surface = createTrackedSurface(env, `parallel-${id}`);
await sleep(1000);
const task = [
`You must call the subagent tool TWICE. Make both calls before waiting for results.`,
``,
`First call:`,
` name: "ParaA-${id}"`,
` agent: "test-echo"`,
` task: "Run: echo 'DONE_A_${id}' > '${fileA}'"`,
``,
`Second call:`,
` name: "ParaB-${id}"`,
` agent: "test-echo"`,
` task: "Run: echo 'DONE_B_${id}' > '${fileB}'"`,
``,
`Call both subagent tools NOW, do not wait between them.`,
].join("\n");
startPi(surface, env.dir, task);
// Both marker files should appear
const [contentA, contentB] = await Promise.all([
waitForFile(fileA, PI_TIMEOUT, /DONE_A/),
waitForFile(fileB, PI_TIMEOUT, /DONE_B/),
]);
assert.ok(contentA.includes(`DONE_A_${id}`), `File A should contain marker`);
assert.ok(contentB.includes(`DONE_B_${id}`), `File B should contain marker`);
});
// ── Fork mode ──
it("fork mode creates a child session linked to the parent", async () => {
const id = uniqueId();
const markerFile = `/tmp/pi-integ-fork-${id}.txt`;
trackTempFile(env, markerFile);
const surface = createTrackedSurface(env, `fork-${id}`);
await sleep(1000);
const task = [
`Call the subagent tool with these EXACT parameters:`,
` name: "Fork-${id}"`,
` fork: true`,
` task: "Run this bash command: echo 'FORK_OK_${id}' > '${markerFile}'"`,
`Do not set the agent parameter. Just set name, fork, and task.`,
`After you receive the result, say FORK_COMPLETE.`,
].join("\n");
startPi(surface, env.dir, task);
// Verify: forked subagent created the file
const content = await waitForFile(markerFile, PI_TIMEOUT, /FORK_OK/);
assert.ok(content.includes(`FORK_OK_${id}`), `Fork marker file should exist with content`);
// Wait for the outer pi to show the result
const screen = await waitForScreen(
surface,
/FORK_COMPLETE|completed|Sub-agent.*"Fork/i,
PI_TIMEOUT,
);
// Verify: the forked session has a parent link
const sessionMatch = screen.match(/Session:\s*(\S+\.jsonl)/);
if (sessionMatch) {
const sessionFile = sessionMatch[1];
assert.ok(existsSync(sessionFile), `Fork session file should exist: ${sessionFile}`);
const entries = readFileSync(sessionFile, "utf8")
.trim()
.split("\n")
.map((l) => JSON.parse(l));
const header = entries[0];
assert.equal(header.type, "session", "First entry should be session header");
assert.ok(header.parentSession, "Fork session should have parentSession field");
// Fork sessions include parent context (model_change entries etc.)
assert.ok(entries.length >= 2, "Fork session should have context entries beyond header");
}
});
// ── caller_ping ──
it("subagent caller_ping sends notification back to the parent", async () => {
const id = uniqueId();
const surface = createTrackedSurface(env, `ping-${id}`);
await sleep(1000);
const task = [
`Call the subagent tool with these EXACT parameters:`,
` name: "Ping-${id}"`,
` agent: "test-ping"`,
` task: "PING_TEST_${id}"`,
`Just call the subagent tool once. Do not do anything else before calling it.`,
].join("\n");
startPi(surface, env.dir, task);
// The test-ping agent calls caller_ping, which steers a "needs help" message
// back to the outer pi. Look for it on screen.
const screen = await waitForScreen(
surface,
/needs help|PING|caller_ping|ping/i,
PI_TIMEOUT,
);
assert.ok(
/needs help|PING/i.test(screen),
`Screen should show ping notification. Got:\n${screen.slice(-800)}`,
);
});
// ── Agent discovery ──
it("subagent discovers project-local test agents", async () => {
const id = uniqueId();
const markerFile = `/tmp/pi-integ-discovery-${id}.txt`;
trackTempFile(env, markerFile);
const surface = createTrackedSurface(env, `discovery-${id}`);
await sleep(1000);
// Use subagents_list to verify test agents are discoverable,
// then spawn one to prove it works end-to-end.
const task = [
`First, call the subagents_list tool to see available agents.`,
`Then call the subagent tool:`,
` name: "Disco-${id}"`,
` agent: "test-echo"`,
` task: "Run: echo 'DISCO_${id}' > '${markerFile}'"`,
`After you receive the subagent result, say DISCOVERY_DONE.`,
].join("\n");
startPi(surface, env.dir, task);
// The test-echo agent (discovered from project .pi/agents/) should work
const content = await waitForFile(markerFile, PI_TIMEOUT, /DISCO/);
assert.ok(content.includes(`DISCO_${id}`), `Discovery test marker should exist`);
});
// ── Subagent with custom system prompt ──
it("passes systemPrompt to subagent", async () => {
const id = uniqueId();
const markerFile = `/tmp/pi-integ-sysprompt-${id}.txt`;
trackTempFile(env, markerFile);
const surface = createTrackedSurface(env, `sysprompt-${id}`);
await sleep(1000);
const task = [
`Call the subagent tool with these parameters:`,
` name: "SysP-${id}"`,
` agent: "test-echo"`,
` systemPrompt: "Always start your response with CUSTOM_PROMPT_ACTIVE."`,
` task: "Write 'SYSPROMPT_${id}' to ${markerFile} using bash: echo 'SYSPROMPT_${id}' > '${markerFile}'"`,
`After the subagent completes, say SYSPROMPT_TEST_DONE.`,
].join("\n");
startPi(surface, env.dir, task);
const content = await waitForFile(markerFile, PI_TIMEOUT, /SYSPROMPT/);
assert.ok(content.includes(`SYSPROMPT_${id}`), `System prompt test marker should exist`);
});
});
}
test/system-prompt-mode.test.ts
+163
View File
@@ -0,0 +1,163 @@
/**
* Smoke tests for the systemPromptMode feature.
* Tests: frontmatter parsing, identity routing, CLI flag generation.
*/
import { mkdtempSync, writeFileSync, rmSync, mkdirSync, readFileSync, existsSync } from "node:fs";
import { join } from "node:path";
import { tmpdir } from "node:os";
let passed = 0;
let failed = 0;
function assert(condition: boolean, msg: string) {
if (condition) {
console.log(` ✅ ${msg}`);
passed++;
} else {
console.log(` ❌ ${msg}`);
failed++;
}
}
// --- Extracted logic under test ---
function parseFrontmatter(content: string) {
const match = content.match(/^---\n([\s\S]*?)\n---/);
if (!match) return null;
const frontmatter = match[1];
const get = (key: string) => {
const m = frontmatter.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
return m ? m[1].trim() : undefined;
};
const body = content.replace(/^---\n[\s\S]*?\n---\n*/, "").trim();
const spm = get("system-prompt");
return {
systemPromptMode: spm === "replace" ? "replace" : spm === "append" ? "append" : undefined,
body: body || undefined,
};
}
function simulateRouting(
agentBody: string | undefined,
systemPromptMode: "append" | "replace" | undefined,
paramSystemPrompt: string | undefined,
) {
const identity = agentBody ?? paramSystemPrompt ?? null;
const identityInSystemPrompt = systemPromptMode && identity;
const roleBlock = identity && !identityInSystemPrompt ? `\n\n${identity}` : "";
let cliFlag: string | null = null;
if (identityInSystemPrompt && identity) {
cliFlag = systemPromptMode === "replace" ? "--system-prompt" : "--append-system-prompt";
}
return { roleBlock, cliFlag, identityInSystemPrompt: !!identityInSystemPrompt };
}
// --- Fixtures ---
const AGENT_REPLACE = `---
model: anthropic/claude-sonnet-4-20250514
system-prompt: replace
auto-exit: true
---
You are a specialized agent.`;
const AGENT_APPEND = `---
model: anthropic/claude-sonnet-4-20250514
system-prompt: append
---
You are an appended identity.`;
const AGENT_DEFAULT = `---
model: anthropic/claude-sonnet-4-20250514
---
You are a default agent.`;
const AGENT_INVALID = `---
model: anthropic/claude-sonnet-4-20250514
system-prompt: foobar
---
Body here.`;
// --- Test 1: Frontmatter parsing ---
console.log("\n🧪 Frontmatter parsing of system-prompt field");
const r1 = parseFrontmatter(AGENT_REPLACE)!;
assert(r1.systemPromptMode === "replace", "system-prompt: replace → mode is 'replace'");
assert(r1.body === "You are a specialized agent.", "body extracted correctly");
const r2 = parseFrontmatter(AGENT_APPEND)!;
assert(r2.systemPromptMode === "append", "system-prompt: append → mode is 'append'");
const r3 = parseFrontmatter(AGENT_DEFAULT)!;
assert(r3.systemPromptMode === undefined, "no system-prompt field → mode is undefined");
const r4 = parseFrontmatter(AGENT_INVALID)!;
assert(r4.systemPromptMode === undefined, "system-prompt: foobar → mode is undefined (ignored)");
// --- Test 2: Identity routing ---
console.log("\n🧪 Identity routing (system prompt vs user message)");
const s1 = simulateRouting("You are X.", "replace", undefined);
assert(s1.roleBlock === "", "replace mode: roleBlock empty (not in task)");
assert(s1.cliFlag === "--system-prompt", "replace mode: uses --system-prompt flag");
const s2 = simulateRouting("You are X.", "append", undefined);
assert(s2.roleBlock === "", "append mode: roleBlock empty (not in task)");
assert(s2.cliFlag === "--append-system-prompt", "append mode: uses --append-system-prompt flag");
const s3 = simulateRouting("You are X.", undefined, undefined);
assert(s3.roleBlock === "\n\nYou are X.", "no mode: roleBlock contains identity");
assert(s3.cliFlag === null, "no mode: no CLI flag");
const s4 = simulateRouting(undefined, undefined, undefined);
assert(s4.roleBlock === "", "no identity: roleBlock empty");
assert(s4.cliFlag === null, "no identity: no CLI flag");
const s5 = simulateRouting(undefined, "replace", undefined);
assert(s5.roleBlock === "", "mode set but no body: roleBlock empty");
assert(s5.cliFlag === null, "mode set but no body: no CLI flag");
const s6 = simulateRouting(undefined, "replace", "Param identity");
assert(s6.cliFlag === "--system-prompt", "mode + param systemPrompt: uses CLI flag");
assert(s6.roleBlock === "", "mode + param systemPrompt: roleBlock empty");
// --- Test 3: End-to-end with temp agent files ---
console.log("\n🧪 End-to-end with temp agent files");
const tmpDir = mkdtempSync(join(tmpdir(), "pi-test-spm-"));
const agentsDir = join(tmpDir, ".pi", "agents");
mkdirSync(agentsDir, { recursive: true });
writeFileSync(join(agentsDir, "test-replace.md"), AGENT_REPLACE);
writeFileSync(join(agentsDir, "test-append.md"), AGENT_APPEND);
writeFileSync(join(agentsDir, "test-default.md"), AGENT_DEFAULT);
function loadFromDir(name: string) {
const p = join(agentsDir, `${name}.md`);
if (!existsSync(p)) return null;
return parseFrontmatter(readFileSync(p, "utf8"));
}
const t1 = loadFromDir("test-replace")!;
assert(t1.systemPromptMode === "replace", "file test-replace.md → replace mode");
assert(t1.body === "You are a specialized agent.", "file test-replace.md → body correct");
const t2 = loadFromDir("test-append")!;
assert(t2.systemPromptMode === "append", "file test-append.md → append mode");
const t3 = loadFromDir("test-default")!;
assert(t3.systemPromptMode === undefined, "file test-default.md → no mode");
rmSync(tmpDir, { recursive: true });
// --- Summary ---
console.log(`\n${"=".repeat(40)}`);
console.log(`Results: ${passed} passed, ${failed} failed`);
if (failed > 0) process.exit(1);
console.log("All tests passed! ✅\n");
test/test.ts
+2378
View File
File diff suppressed because it is too large Load Diff