pi-neo-subagents 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-10-24
+
+First public release. Covers the v1 delegation core and the v2 governance work.
+
+### Added — delegation core
+
+- Named agent definitions as Markdown + frontmatter in `.pi/agents/` (project)
+  and `~/.pi/agent/agents/` (user), with project-over-user precedence.
+- `task` tool for the main agent: isolated nested sessions, self-contained task
+  text only, final reply returned as the tool result.
+- `/subagents` listing and detail views, and `/subagents run <name> [--to-context] <task>`
+  for user-invoked delegation whose result stays out of the model's context by
+  default.
+- Definition enforcement: tool whitelists, model overrides, `systemPrompt: replace`.
+- Result contract: 30,000-character truncation with the full result written to a
+  temp file, structured details, merged usage, coarse progress updates.
+- Non-interactive output routing: stdout in print mode, stderr in JSON mode,
+  notifications in TUI and RPC.
+- `create_subagent` tool and project-first placement, so a session with no
+  definitions is never a dead end.
+
+### Added — governance and scale (v2)
+
+- Execution controls: `maxTurns`, `timeoutMs`, `maxTokens`, and `thinking` in a
+  definition or per call; cut-short work is reported as a budget stop, never as
+  a failure.
+- Run ledger with `/subagents stats` and `stats reset`.
+- Fan-out dispatch (`tasks`) with a configurable concurrency cap, submission
+  order results, per-task status, and cancellation of everything in flight.
+- Chained dispatch (`chain`) with `{previous}` substitution and stop-at-first-
+  unfinished-step semantics.
+- Ad-hoc delegation with inline `instructions`, no definition file, accounted as
+  `ad-hoc`.
+- Live TUI widget listing in-flight delegations with turn and current tool.
+- Strict definition validation: non-`replace` `systemPrompt`, unknown tools,
+  unresolvable models, and invalid budgets are errors.
+- Discovery from nested working directories; listings show source file and
+  modification time.
+- Managed definitions: `/subagents new`, `edit`, `rm`.
+- Authorization: project-level agents require first-use consent, plus settings
+  `confirmProjectAgents`, `allowModelCreatedDefinitions`,
+  `allowUserScopeCreation`, and `maxDepth`.
+- Controlled recursion: opt-in `allowSubagents`, depth-bounded, with depth
+  reported in results and the ledger.
+- Hermetic test suite (112 tests) over a single session seam, plus an
+  environment-gated live-model smoke suite (`npm run test:live`).
+
+### Notes
+
+- Delegation is serial per call unless `tasks` is used; nesting requires an
+  explicit opt-in.
+- `@earendil-works/pi-ai` and `@earendil-works/pi-coding-agent` are host-provided
+  and declared as `peerDependencies` with a `*` range.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 灰木同学
+
+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.

package/README.md

@@ -1,3 +1,332 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# pi-neo-subagents
+
+Subagents for [Pi](https://github.com/earendil-works/pi): define named specialist
+agents as Markdown files, then let the main agent delegate self-contained tasks
+to them — or run them yourself. Each delegation runs in an isolated nested
+session with its own conversation, so your main context stays small and focused.
+
+```bash
+pi install npm:pi-neo-subagents
+```
+
+- **Delegate**: a `task` tool the main agent calls, single / fan-out / chained,
+  with per-run budgets and a run ledger.
+- **Define**: Markdown definitions with tool whitelists, model overrides, and an
+  opt-in for controlled recursion — project-first, reviewable in your repo.
+- **Run**: `/subagents list|run|new|edit|rm|stats` for doing it yourself.
+
+## Install
+
+From npm:
+
+```bash
+pi install npm:pi-neo-subagents          # user-level
+pi install npm:pi-neo-subagents -l       # project-level (needs project trust)
+```
+
+From a directory or a single file (TypeScript, no build step):
+
+```bash
+pi install /path/to/pi-neo-subagents
+pi --extension /path/to/pi-neo-subagents/index.ts
+```
+
+Project-level installs land in `.pi/settings.json`, which Pi only honours after
+project trust is granted — start Pi with `--approve` (or trust the project
+interactively) or the package will appear to be ignored. It can also live under
+`~/.pi/agent/extensions/` or `<project>/.pi/extensions/` for discovery.
+
+To publish to npm, remove `"private": true` from `package.json` and add the
+`pi-package` keyword; the `pi.extensions` manifest is already declared.
+
+## Agent definitions
+
+Definitions are Markdown files with YAML-style frontmatter in two resource
+directories:
+
+- project-level: `.pi/agents/*.md` (wins on a name collision, labelled in listings).
+  Discovery walks up from the working directory to the nearest `.pi/agents`, so
+  running Pi inside a subdirectory still finds the repository's agents.
+- user-level: `~/.pi/agent/agents/*.md`
+
+```markdown
+---
+description: Reviews code changes
+tools: read, grep
+model: anthropic/claude-sonnet-4-5
+systemPrompt: replace
+---
+
+You are a careful code reviewer. Always cite the file you reviewed.
+```
+
+| Field | Meaning | Default |
+|---|---|---|
+| `name` | Canonical agent name | the file's stem |
+| `description` | One-line description used for delegation discovery | required |
+| `tools` | Whitelist of tool names for the subagent | all default tools |
+| `model` | Model to run on (`provider/id` or bare id) | inherit the host session's model |
+| `systemPrompt` | `replace` makes the body the entire system prompt | append to Pi's default prompt |
+| `maxTurns` | Cap on assistant turns for one delegation | unbounded |
+| `timeoutMs` | Wall-clock cap in milliseconds | unbounded |
+| `maxTokens` | Cap on total tokens for one delegation | unbounded |
+| `thinking` | Thinking level (`minimal`, `low`, `medium`, `high`, `xhigh`, `max`) | inherit |
+| `allowSubagents` | `true` lets this agent delegate further with the `task` tool | `false` |
+
+Frontmatter accepts both `tools: read, grep` and YAML block lists:
+
+```markdown
+tools:
+  - read
+  - grep
+```
+
+Quoted values and trailing `# comments` are handled. Definition mistakes fail
+loudly instead of silently changing behaviour:
+
+- `tools:` present but empty → error (it used to mean "all default tools")
+- an unterminated quoted value → error
+- a `systemPrompt` value other than `replace` → error (omitting it still means append)
+- at creation time: an unregistered tool name, an unresolvable model, an
+  invalid budget, or the `task` tool (subagents never delegate further) → error
+- two definitions with the same `name` in one directory → the later file is
+  rejected with a duplicate-name error
+
+The Markdown body is the agent's specialization instructions.
+
+## Creating definitions
+
+You can write definition files by hand, or let the agent do it. The
+`create_subagent` tool takes `{ name, description, instructions, tools?, model?,
+scope?, overwrite? }` and owns the file format and location:
+
+- **`scope: "project"` (default)** → `<cwd>/.pi/agents/<name>.md`, so the
+  definition travels with the repository and can be reviewed and committed.
+- `scope: "user"` → `~/.pi/agent/agents/<name>.md`, only when explicitly asked.
+- Existing definitions are never replaced unless `overwrite: true`; names that
+  would escape the agents directory are rejected; the generated file is
+  validated before it is written.
+- A newly created definition is delegable immediately in the same session.
+
+Asking for "one subagent reviews the pending diff, one scans the repo for TODOs"
+in a project with no definitions therefore produces `reviewer.md` and
+`scout.md` **inside the project**, not in your global config.
+
+## Budgets
+
+A delegation can be capped by turns, wall-clock time, and tokens — in the
+definition, or per call (a per-call value wins):
+
+```jsonc
+// task tool call
+{ "agent": "scout", "task": "…", "maxTurns": 3, "timeoutMs": 60000, "thinking": "low" }
+```
+
+Hitting a cap is a first-class outcome, not a failure: the subagent's reply so
+far comes back with a note naming the budget that tripped, for example
+`[Budget stop: turns limit 1 reached (observed 1). Partial reply above.]`.
+Cut-short work stays distinguishable from a failed delegation, and the usage
+footer still reports what it cost.
+
+## Delegate from the main agent
+
+The `task` tool lists every available agent in its description, names both
+definition directories, and says project definitions are preferred. The main
+agent delegates with a **self-contained** task description — the subagent sees the task
+text only, never the host conversation. Its final reply comes back as the tool
+result (oversized replies are truncated at 30,000 characters with the full
+result written to a temp file).
+
+### Fan-out
+
+One call can dispatch several tasks concurrently:
+
+```jsonc
+{ "tasks": [
+  { "agent": "reviewer", "task": "Review the diff of src/ for bugs" },
+  { "agent": "scout",    "task": "Find every TODO under src/", "maxTurns": 4 }
+] }
+```
+
+- Results come back **in submission order**, each as its own block with its
+  status (`ok`, `budget stop (…)`, `failed`) and details.
+- One failing task does not cancel its siblings; the call is an error only when
+  every task failed.
+- Concurrency is capped at 4 by default; set
+  `PI_NEO_SUBAGENTS_MAX_CONCURRENCY=<n>` to change it.
+- Cancelling the call cancels every in-flight task.
+- A single `{ agent, task }` call behaves exactly as before.
+- In the TUI, a widget lists every in-flight delegation with its current turn
+  and tool, and clears when the dispatch settles. Other modes never show it.
+
+### One-off work, without a definition
+
+For work you will not reuse, an entry can carry inline instructions instead of an
+agent name:
+
+```jsonc
+{ "instructions": "You read one file and summarize it in three bullets.",
+  "tools": ["read"],
+  "task": "Summarize docs/specs/subagents.md" }
+```
+
+- Nothing is written to disk and nothing appears in `/subagents`; the run is
+  still counted in `/subagents stats` under the fixed label `ad-hoc`.
+- Inline entries accept the same `model`, budget, and `tools` options as a
+  definition, work in single, fan-out, and chain dispatch, and can never spawn
+  further subagents.
+
+### Controlled recursion
+
+By default a subagent cannot delegate further. A definition can opt in:
+
+```markdown
+---
+description: Plans work and delegates the parts
+allowSubagents: true
+tools: read, task
+---
+```
+
+Opted-in agents receive the `task` tool in their nested session, and a depth
+limit bounds the tree (`subagents.maxDepth`, default 2 — a top-level delegation
+is depth 1). Exceeding it fails that call with the limit and the attempted
+depth. Every result carries `details.depth`, and the ledger shows the deepest
+level each agent ran at.
+
+### Chains
+
+Steps can run in order, each able to consume the previous reply — a
+review-then-fix pipeline, for example:
+
+```jsonc
+{ "chain": [
+  { "agent": "reviewer", "task": "Review src/runner.ts and list the problems" },
+  { "agent": "fixer",    "task": "Fix exactly these problems, nothing else: {previous}" }
+] }
+```
+
+- `{previous}` is replaced with the previous step's reply; using it in the first
+  step is rejected before anything runs.
+- A chain stops at the first step that fails **or is cut short by a budget**;
+  remaining steps are reported as `skipped`, and the result names every step's
+  status.
+- A chain is strictly sequential, so the fan-out cap does not apply.
+
+Delegation is one level deep by default: the `task` tool is never available to
+subagents themselves. Nested sessions also load no extensions, skills, prompt
+templates, or themes, so a subagent's prompt is its definition plus the task —
+never the host's skill index.
+
+## Run directly
+
+```
+/subagents                                          # list all definitions
+/subagents <name>                                   # show one definition
+/subagents run <name> <task>                        # run one; result shown to you only
+/subagents run --to-context <name> <task>           # also send the result into the model's context
+/subagents run "code review" <task>                 # quote names that contain spaces
+/subagents run -- <name> <task>                     # anything after -- is taken literally
+/subagents new <name> [description] [--force]       # scaffold a definition in the resolved project dir
+/subagents edit <name>                              # open the resolved file; invalid edits are not saved
+/subagents rm <name> [--yes]                        # delete after confirmation (--yes for scripts)
+/subagents stats                                    # per-agent runs, turns, tokens, cost, average time
+/subagents stats reset                              # clear this session's ledger
+```
+
+The ledger is per session and accounts for every delegation — single, fan-out,
+and chain steps — counting successes, failures, and budget stops separately:
+
+```
+Delegation ledger (this session):
+- reviewer: 1 run (1 ok, 0 failed, 0 budget stops) · 3 turns · tokens 647 in / 410 out · $0.000718 · avg 4616ms
+- scout: 1 run (1 ok, 0 failed, 0 budget stops) · 2 turns · tokens 421 in / 221 out · $0.000411 · avg 2475ms
+Total: 2 runs · $0.001130
+```
+
+Options are parsed only before the name, so `--to-context` inside a task stays
+part of the task text. Unknown options are rejected with the usage line.
+
+Direct runs report a one-line usage summary (model, turns, tokens, cost). Long
+results are shortened for display and the full text is written to a temp file
+named in the notice.
+
+### Output channels
+
+| Mode | Where command output goes |
+|---|---|
+| TUI | notification |
+| RPC | `extension_ui_request` notification |
+| `--print` | stdout |
+| `--mode json` | stderr (stdout is the JSON event stream) |
+
+Progress for a long direct run appears as a status line (`<agent> · turn N`) and
+is cleared when the run finishes.
+
+## Windows / Git Bash
+
+MSYS rewrites arguments that start with `/`, so passing a slash command on the
+command line (`pi -p "/subagents"`) reaches Pi as
+`D:/Program Files/Git/subagents`. Quote it differently or disable the rewrite for
+that argument:
+
+```bash
+MSYS2_ARG_CONV_EXCL='/subagents' pi -p "/subagents"
+pi -p "//subagents"          # MSYS strips one slash
+```
+
+This does not affect typing commands inside the Pi TUI, RPC clients, cmd.exe, or
+PowerShell.
+
+## Settings
+
+Optional settings live under the `subagents` key of Pi's settings (global
+`~/.pi/agent/settings.json` or project `.pi/settings.json`):
+
+```json
+{
+  "subagents": {
+    "confirmProjectAgents": "ask",
+    "allowModelCreatedDefinitions": true,
+    "allowUserScopeCreation": false,
+    "maxDepth": 2
+  }
+}
+```
+
+| Setting | Meaning | Default |
+|---|---|---|
+| `confirmProjectAgents` | `"ask"`, `"allow"`, or `"deny"`: whether a project-level agent needs consent before its first use in a session | `"ask"` |
+| `allowModelCreatedDefinitions` | whether the model may author definitions with `create_subagent` | `true` |
+| `allowUserScopeCreation` | whether definitions may be written to the user-level directory | `false` |
+| `maxDepth` | delegation depth limit (reserved for controlled recursion) | `2` |
+
+Consent is remembered per agent for the session, and a denial runs nothing.
+User-level agents and ad-hoc entries never prompt. In a session without a
+dialog UI, `"ask"` proceeds (automation never hangs) while `"deny"` refuses.
+
+## Development
+
+```bash
+npm install
+npm test        # vitest, hermetic: scripted fake model, no network
+npm run typecheck
+npm run test:live   # live-model smoke suite (real provider, real cost)
+```
+
+`npm test` is offline and never needs credentials. The live suite is excluded
+from it and runs only through `npm run test:live`, which enables it with
+`PI_NEO_SUBAGENTS_LIVE=1`:
+
+- It uses the credentials Pi already has, so run `pi auth` first if needed.
+- `PI_NEO_SUBAGENTS_LIVE_MODEL=provider/model` picks the model (default
+  `deepseek/deepseek-flash`).
+- A missing model or provider fails loudly with instructions instead of
+  skipping, so a green run always means the real path worked.
+- A full run costs roughly 25 seconds and a few thousand tokens: it creates two
+  definitions in a temp project, fans out to them, checks the files and the
+  ledger, and delegates one ad-hoc task to prove no definition is created.
+
+Tests drive full in-memory agent sessions through the Pi SDK with pi-ai's
+`fauxProvider` as the scripted model; behaviour is asserted only at the
+session boundary (tool results, visible messages, recorded UI output).