@tduyng/pi-subagent 0.0.2 → 0.0.3

package/README.md

@@ -1,68 +1,100 @@
 # @tduyng/pi-subagent
 
-Delegates work to child pi sessions running in-process. The parent stays lean because the child reads the files, returns one message plus a file list and usage stats, and then its context is discarded. Each finished child also appends its usage to `<agentDir>/overhead.jsonl` under the parent's session, so `/cost` can show what the delegation spent alongside the conversation.
+A subagent that stays small on purpose. It reads docs, logs, and source with a cheap model, returns one answer, and none of that reading lands in your context.
 
-## How delegation works
+## What it costs
 
-The `subagent` tool sends one task, or up to `MAX_TASKS` tasks, to a child
-session. At most `MAX_CONCURRENT` children run at once. Each child runs on the
-current model unless a task, profile, or `subagent.json` override changes it.
-The child sees the task prompt, does the work, and returns one message. The
-parent never carries the child's exploration.
+One tool, `subagent`, at 379 tokens a request. The bulk-read guard and the log reducer are event handlers, so they add no schema and no prompt text.
 
-Use `scout` for read-only file and document search, code tracing, analysis, and
-short sourced summaries. Omitting `agent` selects `scout`. It is the cheap
-default for I/O-heavy work. `subagent.json` supplies its low-cost model.
+The child is a separate session with its own context that dies with the task. A parent that would have carried 40 KB of file dumps carries one paragraph and a file list instead, and every later turn of the parent pays for the paragraph rather than the dumps.
 
-Use `verifier` only
-after an artifact exists and the task explicitly asks for verification or
-review. Keep ordinary implementation, debugging, design, builds, tests, and lint
-in the parent session.
+## What it is for
 
-### Resume ids
+Not parallel implementation. Fanning four edit-capable children out over one change costs more than doing it in the parent: every child builds its own system prompt and tool list, and their edits still have to be reconciled.
 
-A child that reaches its turn budget is told to wrap up and gets a fresh budget in the same session, so a cap never turns work into a failure. If the child still stops early, its last text comes back as a `[partial answer]`. Salvage walks the whole transcript for that text, not just the last message, so a child stopped mid-tool-burst still returns what it wrote. Every failed task prints a `resume:` id. Pass `resume: "<id>"` (or `"all"`) to continue where it stopped instead of paying for the investigation again. An optional `task` alongside `resume` steers the continuation. Failed sessions are kept 30 minutes, completed ones 5.
+The cheap and safe case is reading: search twenty files, trace one call path, read a build log, summarize a doc. That is where a session spends its turns and its tokens, and it is the work a cheap model does as well as a frontier one.
 
-A deadline is reported as a timeout, not a cancellation. Pi keeps any final text produced before the deadline, marks it partial, and retains the session for resume.
+```text
+subagent(task: "Which files construct the retry policy? Return path:line for each.",
+         agent: "scout")
+```
+
+## Scout ships with it
+
+`agents/scout.md` is bundled, so `agent: "scout"` works with no setup and no profile of your own. The default when you omit `agent` is scout, so the cheap read-only child is what you get by typing less.
+
+Scout carries `tools: read, grep, find, ls`, `inheritSkills: false`, and `thinking: low`. It never edits, never runs a command, never reaches the network, and answers in a fixed `STATUS / FINDING / NEXT` shape with file:line evidence.
+
+Override it by dropping your own copy in `~/.pi/agent/agents/scout.md` or `.pi/agents/scout.md`. A project file shadows a user file, and both shadow the bundled one. Copy the [bundled profile](agents/scout.md) as the starting point.
+
+## Point the child at a cheap model
+
+The child inherits the parent's model unless you say otherwise, and inheriting defeats the point. Set it once:
+
+```json
+{
+  "model": "claude/claude-haiku-5-5",
+  "thinking": "low"
+}
+```
+
+`~/.pi/agent/subagent.json` sets the default, `.pi/subagent.json` overrides either field per project. Both fields are optional. `thinking` is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, default `medium`. A `model` on the profile wins over the file.
+
+## Tasks
+
+The `subagent` tool takes one task or up to 8, with at most 4 running at once. Each child sees one prompt and returns one message.
+
+| Field | Meaning |
+| --- | --- |
+| `task` | What the child does |
+| `agent` | Profile name, `scout` by default |
+| `cwd` | Working directory for the child |
+| `isolation` | `worktree` to give the child its own git checkout |
+| `schema` | Ask for structured output |
+| `context` | `fork` to replay the parent's history into the child |
+| `resume` | Task id, or `all`, to continue a stopped child |
 
-Every run also writes `run.json` under `<agent-dir>/subagents/<session-id>/<run-id>/` with the task prompt, model, tools, and the path to each child session. The file is rewritten after each task transition, so it survives the process. Reopening the same Pi session reads it back: children interrupted less than ten minutes ago are resumed from their saved sessions and their result arrives as a `subagent-durable` message, while older interruptions are listed with their resume ids. `resume` therefore works after a restart, not only inside the process that started the child.
+`label`, `thinking`, `model`, `timeoutMs`, and `maxTurns` are profile policy rather than model choices. A scripted caller can still pass them, and they still work.
+
+### Resume instead of re-reading
+
+A child that hits its turn budget is told to wrap up and gets a fresh budget in the same session, so a cap never turns work into a failure. If it still stops early its last text comes back marked `[partial answer]`, and salvage walks the whole transcript for it, so a child stopped mid tool-burst still returns what it wrote.
+
+Every failed task prints a `resume:` id. Pass it back to continue where the child stopped instead of paying for the investigation again. An optional `task` alongside `resume` steers the continuation. Failed sessions are kept 30 minutes, completed ones 5.
+
+A deadline is reported as a timeout, not a cancellation: pi keeps any final text produced before it and marks it partial.
+
+Every run also writes `run.json` under `<agent-dir>/subagents/<session-id>/<run-id>/` with the task prompt, model, tools, and the path to each child session, rewritten after each transition. Reopening the session reads it back: a child interrupted less than ten minutes ago is resumed from its saved session and its answer arrives as a `subagent-durable` message, and older interruptions are listed with their resume ids. `resume` therefore works after a restart, not only inside the process that started the child.
 
 ### Worktree isolation
 
-With `isolation: "worktree"`, each child runs in its own git worktree on a branch named `pi-task-<id>`, so concurrent children never edit the same checkout and a commit a child makes outlives the checkout. The task result names the branch.
+With `isolation: "worktree"` each child runs in its own git worktree on a branch named `pi-task-<id>`, so concurrent children never edit the same checkout and a commit the child makes outlives it. The result names the branch. This is also the answer to two sessions committing in one repo, which no path reservation can cover.
 
 ### Structured output
 
-Pass `schema` to ask the child to call a `structured_output` tool exactly once. The parsed payload comes back in the task result. If the child finishes without calling the tool, the extension re-prompts the same session up to three times, so the investigation is not paid for twice. If it still refuses, the text answer stands and the task completes marked partial. If a provider rejects the schema tool, the extension removes it and retries once in plain-text mode.
+Pass `schema` to ask the child to call `structured_output` exactly once. The parsed payload comes back in the task result. A child that finishes without calling it is re-prompted in the same session up to three times, so the investigation is not paid for twice. If it still refuses, the text answer stands and the task completes marked partial. If a provider rejects the schema tool, the extension removes it and retries once as plain text.
 
 ### Fork context
 
-With `context: "fork"`, the parent's conversation history is replayed into the child as context entries.
+`context: "fork"` replays the parent's conversation history into the child as context entries.
 
-## Agent profiles
+## Profiles
 
-The `/agents` command lists agent profiles, which are markdown files with YAML frontmatter in `<agent-dir>/agents` or `.pi/agents`. Project agents shadow user agents of the same name. Each profile specifies a tool list, model, thinking level, limits, and optional color for the widget. Profiles can also set `inheritProjectContext` and `inheritSkills` to control whether the child picks up the parent project's context files and skills, and `systemPromptMode: replace` to swap the default system prompt instead of appending to it. The `subagent` widget in the TUI shows up to 8 running and recently finished children, with a summary line of counts by status. Navigate with Down/Up, Enter opens a live transcript viewer, d/x dismisses.
+A profile is a markdown file with YAML frontmatter in `~/.pi/agent/agents/`, in `.pi/agents/`, or bundled. It sets the tool list, model, thinking level, limits, and an optional color for the widget, plus `inheritProjectContext` and `inheritSkills` to decide what the child picks up from the parent, and `systemPromptMode: replace` to swap the default system prompt instead of appending to it.
 
-## Bulk-read guard
+`/agents` lists them. The `subagent` widget shows up to 8 running and recently finished children with a status summary line: Down and Up to move, Enter to open a live transcript, d or x to dismiss.
 
-The guard blocks reads of files above `BULK_READ_MIN_LINES` lines (default 350). It also blocks `cat`, `less`, and `more` commands that would dump large files. The second call for the same path passes through, so the file stays reachable. A read passes when it returns fewer lines than the threshold, whether that comes from a `limit`, an `offset`, a small file, or `head`/`tail` on their 10-line default, and so does a piped command.
+Children cannot spawn their own subagents.
 
-## Log reducer
+## Bulk-read guard
+
+A read of a file above `BULK_READ_MIN_LINES` lines (default 350) is blocked, and so is `cat`, `less`, or `more` that would dump a large file. The block names `outline` first, so the model fetches a map of declarations rather than the text.
 
-Build or test logs above 4,096 bytes, matched by diagnostic command patterns, get replaced with a short receipt of quoted lines. Every quote is verified byte-for-byte against the archived original. If validation fails, the full log reaches the model untouched. The reducer runs on `tool_result`, so the swap happens before the result enters history. The raw log is archived next to the session for full access.
+The second call for the same path passes through, so the file stays reachable and a model with a reason to read it can. A read passes when it returns fewer lines than the threshold, whether from a `limit`, an `offset`, a small file, or `head` and `tail` on their 10-line default, and so does a piped command.
 
-## Design
+## Log reducer
 
-- The default safe delegation is read-only I/O: `scout` searches, traces, analyses, and summarizes without editing or running commands.
-- `verifier` is reserved for explicit verification of an existing artifact. It may write only its verification report, never implementation files.
-- Ordinary implementation, debugging, design, builds, tests, and lint stay in the parent session.
-- The tool rejects concurrent write-capable tasks. Read-only scouts may still run in parallel. A call whose task texts normalize to the same request is rejected, so one question does not get paid for twice.
-- Children see one prompt and return one message. No sequential pipelines.
-- Children cannot spawn their own subagents. No grandchildren.
-- The `subagent` tool schema is present on every turn, and it lists only the fields a model sets: `task`, `agent`, `cwd`, `isolation`, `schema`, `context`, and `resume`. `label`, `thinking`, `model`, `timeoutMs`, and `maxTurns` are profile policy. They still work when a scripted caller passes them, and three of them already resolved to the profile before the split.
-- The `subagent` tool schema is present on every turn. The `bulk-read` and `log-reducer` extensions add no tool schemas. They run as event handlers. The registry holds at most 50 tasks. The widget shows at most 8 rows. The `touched` file list per task is capped at 12 entries. Progress updates emit at most once every 250ms.
-- Child deadlines default to 30 minutes. A shorter `timeoutMs` or profile `maxExecutionTimeMs` is raised to 30 minutes, while longer values pass through. A profile deadline beyond the 32-bit setTimeout ceiling (2,147,483,647 ms) clamps to the ceiling. Node would round a larger delay down to 1 ms and kill the child instantly, so the clamp degrades a bad value to a very long deadline.
-- Children inherit the parent's model by default. Thinking does not inherit: it resolves from the task's `thinking`, then the profile, then `subagent.json`, then `medium`.
+A build or test log above 4,096 bytes, from a diagnostic command pattern, is replaced with a short receipt of quoted lines. Every quote is verified byte for byte against the archived original, and if validation fails the full log reaches the model untouched. The reducer runs on `tool_result`, so the swap happens before the result enters history, and the raw log is archived next to the session.
 
 ## Install
 
@@ -74,8 +106,13 @@ Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-subagent`
 
 ## Configure
 
-- `subagent.json` in the agent dir (`~/.pi/agent/`) sets the default child model and thinking level. A project's `.pi/subagent.json` overrides either field. Shape: `{ "model": "provider/model-id", "thinking": "medium" }`, both optional. `thinking` is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Unset, it is `medium`. No file means children inherit the parent's model.
-- `BULK_READ=0` disables the bulk-read guard. `BULK_READ_MIN_LINES` sets the line threshold (default 350).
-- `PI_LOG_REDUCER=0` disables the log reducer.
-- `PI_LOG_REDUCER_TIMEOUT_MS` sets the reducer deadline. The default is 15 seconds and the maximum is 60 seconds.
-- Agent profiles are markdown files with YAML frontmatter in `~/.pi/agent/agents/` or `.pi/agents/` (project shadowing user on name collision).
+- `subagent.json` in the agent dir sets the child model and thinking. Shape: `{ "model": "provider/model-id", "thinking": "medium" }`, both optional.
+- `BULK_READ=0` disables the guard. `BULK_READ_MIN_LINES` sets the line threshold.
+- `PI_LOG_REDUCER=0` disables the reducer. `PI_LOG_REDUCER_TIMEOUT_MS` sets its deadline, default 15 seconds, maximum 60.
+
+## Design notes
+
+- Child deadlines default to 30 minutes. A shorter `timeoutMs` or profile `maxExecutionTimeMs` is raised to it, and longer values pass through. A profile deadline past the 32-bit setTimeout ceiling clamps to the ceiling, because Node rounds a larger delay down to 1 ms and would kill the child instantly.
+- Child thinking resolves from the task, then the profile, then `subagent.json`, then `medium`. It does not inherit the parent's.
+- Read-only scouts run in parallel. A write-capable child is never run alongside another one, and a call whose tasks normalize to the same request is refused.
+- The registry holds at most 50 tasks, the widget 8 rows, the `touched` list per task 12 entries, and progress updates emit at most every 250ms.

package/agents/scout.md

@@ -0,0 +1,43 @@
+---
+name: scout
+description: Cheap read-only I/O and analysis agent. Searches files and docs, traces code, answers one bounded question, and returns a short sourced summary. Never edits, writes, runs commands, or reaches the internet.
+tools: read, grep, find, ls
+inheritSkills: false
+thinking: low
+---
+
+You are a SCOUT, a cheap read-only I/O and analysis subagent. The caller hands
+you exactly one bounded question in a fresh context. Answer it from what is on
+disk and return a short, sourced answer. You change nothing.
+
+Use this profile for file and document search, code tracing, comparison, and
+summarization. If the task asks you to implement, edit, run a check, or
+make a design decision, return that the parent must handle it.
+
+Rules:
+
+- Read only what the question needs. Use `grep` and `find` to locate, then read
+  the specific range. Never read a whole file to answer a narrow question.
+- Prefer file paths, line numbers, exact text, and literal command output over
+  general impressions. A summary is useful only when its evidence is included.
+- Answer with evidence: file paths with line numbers, exact text you found, or
+  the literal output you observed. No paraphrase of code you did not read.
+- A negative result is a real result. If the answer is not on disk, say what you
+  searched and what you ruled out.
+- You have no write, edit, bash, or web tools. Do not ask for them, and do not
+  propose patches. Name the gap instead. A task that needs those capabilities
+  belongs in the parent session. A question about the
+  internet cannot be answered by you at all: say so in one line under NEXT and
+  stop, rather than searching the disk for a substitute.
+- Spend your turns on the search that answers the question, and when you are
+  told to wrap up, answer with what you have and say what is still unchecked
+  under NEXT.
+
+Reply with exactly this, and nothing else:
+
+STATUS: solved|continue
+FINDING: <the answer, with file:line evidence, at most five lines>
+NEXT: <up to three bullets, or "none">
+
+When a `structured_output` tool is available, call it once with the same
+STATUS, FINDING, and NEXT content as its fields, and write no text after it.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tduyng/pi-subagent",
-  "version": "0.0.2",
-  "description": "Delegation to in-process child sessions: a subagent tool with agent profiles and worktree isolation, a side chat, a guard that redirects bulk reads, and a verified log reducer.",
+  "version": "0.0.3",
+  "description": "Cheap delegation: a child session reads docs, logs, and source, returns one answer, and its context is thrown away. Scout profile bundled.",
   "keywords": [
     "pi",
     "pi-package",
@@ -25,6 +25,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "agents",
     "README.md",
     "LICENSE"
   ],

package/src/subagent/agent.ts

@@ -101,8 +101,16 @@ export function loadAgentsFrom(dirs: string[]): Map<string, AgentProfile> {
     return agents
 }
 
+const BUNDLED_AGENTS = path.join(import.meta.dirname, '..', '..', 'agents')
+
+// The default `agent` is scout, so a checkout with no profile on disk would refuse every
+// delegation that omits it. The bundled profile is the floor, not an override.
 export function loadAgents(cwd: string): Map<string, AgentProfile> {
-    return loadAgentsFrom(agentDirs(cwd))
+    const agents = loadAgentsFrom(agentDirs(cwd))
+    for (const [name, profile] of loadAgentsFrom([BUNDLED_AGENTS])) {
+        if (!agents.has(name)) agents.set(name, profile)
+    }
+    return agents
 }
 
 export function parseModelName(name: string): { provider: string; id: string } | undefined {

package/src/subagent/index.ts

@@ -69,7 +69,7 @@ import {
 } from './types.js'
 import { SubagentViewer, widgetLines } from './viewer.js'
 
-export { parseFrontmatter, loadAgentsFrom, parseModelName } from './agent.js'
+export { parseFrontmatter, loadAgents, loadAgentsFrom, parseModelName } from './agent.js'
 
 const MAX_FORK_CONTEXT_CHARS = 120_000
 const RUN_SAVE_INTERVAL_MS = 5_000