pi-better-subagents 0.25.0 → 0.26.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/batch.mjs +12 -3
- package/catalog-runtime.ts +6 -2
- package/child-codemode.ts +17 -0
- package/cleanup.ts +118 -26
- package/config.json +1 -1
- package/config.ts +1 -1
- package/continuation.ts +43 -11
- package/docs/usage.md +83 -63
- package/extensions.mjs +2 -1
- package/index.ts +278 -188
- package/list.mjs +19 -3
- package/list.ts +1 -0
- package/package.json +1 -1
- package/registry.ts +133 -17
- package/session-selection.ts +35 -0
- package/session-store.ts +410 -0
- package/task-guard.ts +5 -2
- package/tools.ts +22 -23
- package/workspace-scope.ts +50 -0
package/docs/usage.md
CHANGED
|
@@ -96,74 +96,85 @@ thresholds continue to take precedence for subagent health.
|
|
|
96
96
|
|
|
97
97
|
| Tool | Blocks? | What it does |
|
|
98
98
|
|------|---------|--------------|
|
|
99
|
-
| `subagent_spawn` | never | Launch a task in a background subagent; returns a run id at once. Params: `prompt`, `name`, `model`, `tools` (allowlist), `exclude_tools`, `sandbox`, `sandbox_dir`, `callback`, `clean`, `cwd`, `git_clone_workspace`, `approve`, `allow_nested`, `
|
|
100
|
-
| `subagent_spawn_batch` | never | Launch several independent subagents at once. Each job becomes a normal run. Params: `batchName`, `shared` (options applied to every job), `jobs[]` (each needs `prompt`;
|
|
101
|
-
| `subagent_resume` | never | Continue a completed run in its own saved conversation. Params: `id` (the completed attempt), `prompt` (the next user turn — do not restate the task or role), optional `model`/`thinking` (explicit escalation only; otherwise the saved recipe wins), `callback`, and the timing overrides. Returns a NEW run id with the same native session id and `resumedFrom` lineage. See [continuing a completed subagent](#continuing-a-completed-subagent). |
|
|
102
|
-
| `subagent_release` | never | Release `retain_session` protection for a completed conversation and its workspace. Nothing is deleted now and no completed result is rewritten; ordinary cleanup may reclaim the artifacts afterwards. Only the owning foreground session may release. |
|
|
99
|
+
| `subagent_spawn` | never | Launch a task in a background subagent; returns a run id at once. Params: `prompt`, `name`, `model`, `tools` (allowlist), `exclude_tools`, `sandbox`, `sandbox_dir`, `callback`, `clean`, `cwd`, `git_clone_workspace`, `approve`, `allow_nested`, optional `session_id` or `session_name` (continue a saved conversation), and the [timing](#run-timing-deadline-ceiling-stuck) overrides `deadline_minutes`, `grace_minutes`, `max_minutes`, `stuck_minutes`. |
|
|
100
|
+
| `subagent_spawn_batch` | never | Launch several independent subagents at once. Each job becomes a normal run. Params: `batchName`, `shared` (options applied to every job), `jobs[]` (each needs `prompt`; optional per-job `session_id` or `session_name` continues a saved conversation), `onCapacity` (`reject` or `launch-available`). |
|
|
103
101
|
| `subagent_settings` | never | Read-only effective settings and capacity snapshot. No parameters. Returns `delegationMode`, `maxConcurrent`, per-setting `sources` (`session` or `config`), a stable settings `revision`, `runningCount`, `pendingCount`, `occupiedSlots`, and `availableSlots`. The limit is a ceiling, not a target; spawn admission rechecks live capacity. |
|
|
104
|
-
| `subagent_list` | never | Compact current
|
|
102
|
+
| `subagent_list` | never | Compact list for the current folder and descendants across foreground sessions (default 10 rows / 1 KiB page). Each row includes `session_id`. Params: `all` (machine-global search), `limit` (default 10, max 100), `cursor`, `max_bytes` (max 4 KiB), `status` (`running`, `completed`, `failed`, `killed`, `exited`, durable `orphaned`, `lost`). Incident counts are compact; no spend/tool histories. |
|
|
105
103
|
| `subagent_output` | never | Bounded current-session excerpt (default 1 KiB / 10 lines). Params: `id`, `lines` (`tail_lines` is a deprecated alias), `cursor` (a returned `nextCursor`, `statusCursor`, or `incidentCursor`), `max_bytes` (max 4 KiB; raw 16 KiB default, 64 KiB max), `mode` (`raw` pages retained log bytes), `include` (`["cost"]`, `["tools"]`, or both: opt-in spend and tool-count lines), `all` (foreign-session id). Missing/unreadable logs are gaps, not empty healthy output. |
|
|
106
104
|
| `subagent_result` | never | Finished-run answer for the current session (2048-byte page). Params: `id`, `cursor` (a returned `nextCursor` continues the answer; `statusCursor` / `incidentCursor` also accepted), `max_bytes` (maximum 8192 bytes), `lines` (optional line cap per answer page), `mode` (`raw`), `include` (`["cost"]`, `["tools"]`, or both), `all` (foreign-session id). Failures and exceptional lifecycle facts come before progress; no tool-name histories. TUI folding is display-only. |
|
|
107
105
|
| `subagent_stop` | never | SIGTERM a running run's process group. |
|
|
108
106
|
|
|
109
|
-
##
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
107
|
+
## Finding a saved conversation
|
|
108
|
+
|
|
109
|
+
`subagent_list()` searches the current folder and its descendants, including runs
|
|
110
|
+
from other foreground sessions. Use `subagent_list({ all: true })` for a global
|
|
111
|
+
search. Each row shows both the attempt id and `session_id`; use the session id
|
|
112
|
+
when continuing work. A continuation keeps that session id while receiving a new
|
|
113
|
+
attempt id.
|
|
114
|
+
|
|
115
|
+
```javascript
|
|
116
|
+
subagent_list()
|
|
117
|
+
subagent_list({ all: true })
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Local name lookup follows the same folder scope. A duplicate name is not resolved
|
|
121
|
+
by choosing the newest conversation; use one of the reported session ids instead.
|
|
122
|
+
|
|
123
|
+
## Continuing a saved conversation
|
|
124
|
+
|
|
125
|
+
Use the same spawn tool for new work and follow-up work:
|
|
126
|
+
|
|
127
|
+
```javascript
|
|
128
|
+
subagent_spawn({ name: "implementation", prompt: "Implement the change." })
|
|
129
|
+
subagent_spawn({ session_id: "<saved-session-id>", prompt: "Fix the review findings." })
|
|
130
|
+
subagent_spawn({ session_name: "implementation", prompt: "Fix the review findings." })
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
A launch without a session selector starts a new conversation. With a selector,
|
|
134
|
+
`prompt` is the next user turn; the original task and role are already saved.
|
|
135
|
+
Each attempt gets a new run id, log, timing record, and capacity slot while the
|
|
136
|
+
native session id and history stay the same. The launch recipe preserves the
|
|
137
|
+
worker's role, tools, model, and workspace, including uncommitted changes.
|
|
138
|
+
|
|
139
|
+
`session_name` is an exact display-name match within the current folder and its
|
|
140
|
+
descendants. Several attempts of the same conversation count once. If several
|
|
141
|
+
conversations share the name, spawn reports matching session ids and refuses to
|
|
142
|
+
guess. Use `subagent_list({ all: true })` to find conversations elsewhere and
|
|
143
|
+
pass `session_id`. `name` remains a new-launch label.
|
|
144
|
+
|
|
145
|
+
Single and batch launches save native Pi sessions and completed launch recipes
|
|
146
|
+
durably in the Pi agent directory. No retention flag or release tool is needed.
|
|
147
|
+
Temporary event logs can be cleaned up independently. Missing or manually deleted
|
|
148
|
+
history is never recreated by continuation. Older recipes pointing at temporary
|
|
149
|
+
session files remain usable only while those original files exist.
|
|
150
|
+
|
|
151
|
+
A different foreground session may continue a conversation. The new attempt's
|
|
152
|
+
callback goes to its caller; previous attempts keep their original evidence.
|
|
153
|
+
Only a completed conversation with an existing workspace and verified saved
|
|
154
|
+
history can continue. One conversation admits one writer: active or orphaned
|
|
155
|
+
attempts and live writer leases refuse competing launches. Continuation requires
|
|
156
|
+
a runtime with `node:sqlite` (Node 24 recommended).
|
|
157
|
+
|
|
158
|
+
Current mandatory human permissions apply on every attempt. A change that would
|
|
159
|
+
alter confinement or replace recorded tool implementations refuses continuation.
|
|
160
|
+
Only explicit model/effort escalation changes the saved model choice; a continued
|
|
161
|
+
worker does not silently inherit the caller's model or re-resolve its role.
|
|
162
|
+
|
|
163
|
+
Use per-job `session_id` or `session_name` in `subagent_spawn_batch`. A batch may
|
|
164
|
+
mix fresh and continued jobs. Keep one job per conversation; the writer lease
|
|
165
|
+
rejects competing jobs.
|
|
166
|
+
|
|
167
|
+
If new parameters are missing after an npm upgrade, run `/reload` in Pi.
|
|
168
|
+
Updating files on disk does not replace extension code already loaded in a live
|
|
169
|
+
session.
|
|
159
170
|
|
|
160
171
|
## Codemode batch launches
|
|
161
172
|
|
|
162
173
|
On Pi 0.99.1 or newer, enable native codemode alongside the existing direct
|
|
163
174
|
tools with `defaultTools: ["+codemode"]` and `codemode.mode: "on"`. SDK sessions
|
|
164
175
|
must also load Pi's `createCodemodeExtension()`. This support is for the
|
|
165
|
-
foreground coordinator
|
|
166
|
-
|
|
176
|
+
foreground coordinator. Child codemode is enabled separately by the default
|
|
177
|
+
tool set and preserves sandbox tool admission.
|
|
167
178
|
|
|
168
179
|
`subagent_spawn_batch` returns the same readable text to direct callers and a
|
|
169
180
|
structured launch receipt to codemode scripts. No text parsing is needed:
|
|
@@ -514,10 +525,17 @@ the task boundary.
|
|
|
514
525
|
## Tool scoping (allowlist)
|
|
515
526
|
|
|
516
527
|
Precedence, highest first: the per-call `tools` param → `config.json`
|
|
517
|
-
`defaultTools` → a built-in default (`read, bash, edit, write, web_search,
|
|
528
|
+
`defaultTools` → a built-in default (`read, bash, edit, write, codemode, web_search,
|
|
518
529
|
web_fetch`; just `read, bash` in a `clean` child). `exclude_tools` subtracts on
|
|
519
530
|
top.
|
|
520
531
|
|
|
532
|
+
On Pi 0.99.1 or newer, default children explicitly load native `codemode` even
|
|
533
|
+
with extension discovery disabled. Custom tool lists must include `codemode`;
|
|
534
|
+
`exclude_tools: "codemode"` removes it. Older SDKs keep their existing tools.
|
|
535
|
+
In confined children, nested tool calls pass through the task guard. Direct
|
|
536
|
+
classifier and image-model globals are disabled there because they bypass tool
|
|
537
|
+
hooks. Unconfined children retain native model globals.
|
|
538
|
+
|
|
521
539
|
User configuration lives in
|
|
522
540
|
`~/.pi/agent/settings.json` under `piBetterHarness.subagents` (under
|
|
523
541
|
`PI_CODING_AGENT_DIR` when set). The old user config migrates on first use.
|
|
@@ -741,10 +759,12 @@ state. Session shutdown disposes open navigator timers.
|
|
|
741
759
|
|
|
742
760
|
## Design notes
|
|
743
761
|
|
|
744
|
-
-
|
|
745
|
-
(`runs/<id>/` holds `output.log`, `prompt.md`, `meta.json
|
|
746
|
-
|
|
747
|
-
|
|
762
|
+
- Temporary run evidence lives outside any repo under `$TMPDIR/pi-better-subagents/`
|
|
763
|
+
(`runs/<id>/` holds `output.log`, `prompt.md`, and `meta.json`). Native child
|
|
764
|
+
sessions and compact completed-attempt recipes persist under the Pi agent
|
|
765
|
+
directory in `subagents/sessions` and `subagents/attempts`. Event-log cleanup
|
|
766
|
+
does not remove the saved conversation or recipe. Existing legacy recipes keep
|
|
767
|
+
their original session paths.
|
|
748
768
|
- The child runs `--mode json`; `subagent_result` / `subagent_output` **parse**
|
|
749
769
|
the event stream and return just the bounded final answer (no tool-name history).
|
|
750
770
|
Non-JSON banner/warning lines fail to parse and are dropped, so the result is
|
|
@@ -756,7 +776,7 @@ state. Session shutdown disposes open navigator timers.
|
|
|
756
776
|
|
|
757
777
|
## Parent-process scoping
|
|
758
778
|
|
|
759
|
-
The live widget,
|
|
779
|
+
The live widget, concurrency cap, and supervision ticker track this Pi process's runs. `subagent_list` searches the current folder and its descendants across foreground sessions; `all:true` searches globally. Rows show the attempt id and the native `session_id`, so a listed conversation can be continued explicitly. Results are newest first, with 10 rows / 1 KiB by default. Use `limit` (max 100), `max_bytes` (max 4 KiB), and `status` filters as needed. Cursors are bound to the local folder or global scope and cannot be replayed from a different folder. Id-based `subagent_result` and `subagent_output` keep their current-session scope; use `all:true` to read another session's run evidence. Unknown ownership remains an explicit gap for those evidence tools. Saved conversation discovery and continuation do not require the original foreground session to exist.
|
|
760
780
|
|
|
761
781
|
## Supervision health (`orphaned` / `lost`)
|
|
762
782
|
|
package/extensions.mjs
CHANGED
|
@@ -33,7 +33,8 @@
|
|
|
33
33
|
* pi -p --no-extensions "list your tools" -> read, bash, edit, write
|
|
34
34
|
* A builtin needs no extension, so it never counts as unmapped.
|
|
35
35
|
*/
|
|
36
|
-
|
|
36
|
+
// codemode is supplied by the harness child adapter, not a discovered package.
|
|
37
|
+
export const BUILTIN_TOOLS = ["read", "bash", "edit", "write", "codemode"];
|
|
37
38
|
|
|
38
39
|
/** Marker spec meaning "this extension's own package" (for allow_nested). */
|
|
39
40
|
export const SELF_SPEC = "self";
|