@gotgenes/pi-subagents 16.3.0 → 16.3.1
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/CHANGELOG.md +7 -0
- package/README.md +3 -3
- package/docs/comparison-with-upstream.md +2 -2
- package/docs/retro/0377-split-widget-delegation-from-runtime.md +56 -0
- package/package.json +2 -2
- package/src/index.ts +1 -1
- package/src/observation/notification.ts +1 -1
- package/src/tools/agent-tool.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [16.3.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.3.0...pi-subagents-v16.3.1) (2026-06-16)
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
### Documentation
|
|
12
|
+
|
|
13
|
+
* reframe pi-subagents positioning away from "Claude Code-style" ([c8d380d](https://github.com/gotgenes/pi-packages/commit/c8d380d440a4ae29f9173673523337cf667fb3da))
|
|
14
|
+
|
|
8
15
|
## [16.3.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.2.2...pi-subagents-v16.3.0) (2026-06-16)
|
|
9
16
|
|
|
10
17
|
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@gotgenes/pi-subagents) [](https://github.com/gotgenes/pi-packages/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://pnpm.io/) [](https://pi.mariozechner.at/)
|
|
4
4
|
|
|
5
|
-
A [pi](https://pi.dev) extension that
|
|
5
|
+
A [pi](https://pi.dev) extension that gives pi **a focused, in-process sub-agent core** — autonomous agents that run inside the same pi runtime (no spawned subprocesses), plus a typed API and lifecycle events other extensions build on.
|
|
6
6
|
Spawn specialized agents that run in isolated sessions — each with its own tools, system prompt, model, and thinking level.
|
|
7
7
|
Run them in foreground or background, steer them mid-run, resume completed sessions, and define your own custom agent types.
|
|
8
8
|
|
|
@@ -15,7 +15,7 @@ Run them in foreground or background, steer them mid-run, resume completed sessi
|
|
|
15
15
|
|
|
16
16
|
## Features
|
|
17
17
|
|
|
18
|
-
- **
|
|
18
|
+
- **In-process & native** — agents run inside the same pi runtime (no spawned subprocesses), sharing tool names, calling conventions, and UI patterns (`subagent`, `get_subagent_result`, `steer_subagent`) — feels native
|
|
19
19
|
- **Parallel background agents** — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 4) and individual completion notifications
|
|
20
20
|
- **Live widget UI** — persistent above-editor widget with animated spinners, live tool activity, token counts, and colored status icons
|
|
21
21
|
- **Conversation viewer** — select any agent in `/agents` to open a live-scrolling overlay of its full conversation (auto-follows new content, scroll up to pause)
|
|
@@ -81,7 +81,7 @@ The token field is annotated with two optional signals inside parens:
|
|
|
81
81
|
- **`↻N`** — number of times the session has compacted, when > 0.
|
|
82
82
|
Stays dim; the percent's color carries urgency.
|
|
83
83
|
|
|
84
|
-
Individual agent results render
|
|
84
|
+
Individual agent results render inline in the conversation:
|
|
85
85
|
|
|
86
86
|
| State | Example |
|
|
87
87
|
| -------------- | ---------------------------------------------------------------------------------------- |
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Comparison with upstream
|
|
2
2
|
|
|
3
3
|
`@gotgenes/pi-subagents` began as a fork of [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents) by [@tintinweb](https://github.com/tintinweb).
|
|
4
|
-
The original design —
|
|
4
|
+
The original design — autonomous subagent dispatch, the live widget, the conversation viewer, custom agent types — is the foundation everything here builds on.
|
|
5
5
|
|
|
6
6
|
It has since become an independently maintained hard fork.
|
|
7
7
|
It follows its own architecture, does not track upstream as a merge target, and cherry-picks upstream fixes only when they fit its scope.
|
|
@@ -26,7 +26,7 @@ The peer-dep migration that prompted the original fork has since landed upstream
|
|
|
26
26
|
|
|
27
27
|
Both extensions provide the same core experience:
|
|
28
28
|
|
|
29
|
-
-
|
|
29
|
+
- Foreground/background subagents with a live above-editor widget and a conversation viewer.
|
|
30
30
|
- Custom agent types defined in `.pi/agents/<name>.md` with YAML frontmatter (system prompt, model, thinking, tools).
|
|
31
31
|
- Fuzzy model selection, context inheritance, mid-run steering, session resume, and graceful turn limits.
|
|
32
32
|
- A `pi.events` lifecycle bus (`subagents:created`, `started`, `completed`, `failed`, `steered`, `compacted`).
|
|
@@ -47,3 +47,59 @@ All deterministic checks green; pre-completion reviewer returned WARN (non-block
|
|
|
47
47
|
Sole finding: `index.ts` is 177 lines (Step 5's aspirational "<170" was already overshot at its own landing, 177); the comment trim kept Step 6 net-neutral.
|
|
48
48
|
Cosmetic, prose-pinned only, non-blocking.
|
|
49
49
|
- Cross-step invariants verified by grep: no `let widget` / `prefer-const` forward-ref (Step 1), no `runtime.widget` / `.widget =` / `WidgetLike` anywhere (the issue's core outcome).
|
|
50
|
+
|
|
51
|
+
## Stage: Final Retrospective (2026-06-16T00:30:08Z)
|
|
52
|
+
|
|
53
|
+
### Session summary
|
|
54
|
+
|
|
55
|
+
The issue shipped cleanly across plan → TDD → ship as `pi-subagents-v16.3.0`, closing #377 and resolving Phase 17 Step 6.
|
|
56
|
+
The design arc was the highlight: an operator-driven pivot from the issue's stated approach (relocate the late seam) to dissolving the construction cycle entirely, sequenced tidy-first so the hard cycle-break landed before the mechanical relay removal.
|
|
57
|
+
The friction was concentrated in mechanical `Edit`-tool execution, not in design or verification.
|
|
58
|
+
|
|
59
|
+
### Observations
|
|
60
|
+
|
|
61
|
+
#### What went well
|
|
62
|
+
|
|
63
|
+
- **Operator design steers compounded into the right architecture.**
|
|
64
|
+
The planning `ask_user` surfaced the construction cycle; the operator's "no setters, instantiate ready-to-work" steer eliminated two of three seam options, and the Kent Beck "make the change easy" prompt (turn 21) produced the tidy-first decomposition.
|
|
65
|
+
This is the pattern working as intended: the agent finds the constraint, the operator picks the principle, the agent verifies feasibility before committing.
|
|
66
|
+
- **Behavior-preservation was argued before it was coded.**
|
|
67
|
+
The ≤80ms-within-same-turn linger argument was established in planning and pinned by three new `agent-widget.test.ts` tests in TDD — no trial-and-error on the load-bearing claim.
|
|
68
|
+
- **Tidy-first sequencing kept the repo green at every commit.**
|
|
69
|
+
Step 2 broke the cycle while the relay methods still existed, making Step 3's export removal a clean atomic change.
|
|
70
|
+
- **Cheap model handled ship correctly.**
|
|
71
|
+
Ship ran on `opencode-go/deepseek-v4-flash` and executed the full mechanical sequence (push, CI watch, release-now `ask_user`, the `UNSTABLE` merge-state edge case via `gh pr merge`) with zero errors — an appropriate model-task match, not a mismatch.
|
|
72
|
+
|
|
73
|
+
#### What caused friction (agent side)
|
|
74
|
+
|
|
75
|
+
- `other` (tool friction) — `Edit` on `runtime.ts` failed twice (turns 45, 47) trying to delete the widget-delegation block bounded by a decorative `// ── Widget delegation methods ────` comment rule; the long run of `─` could not be reproduced exactly.
|
|
76
|
+
Fell back to `sed -i '' '75,104d'`, which over-deleted the class-closing brace and the next doc-comment opener (turn 51), needing a repair edit (turn 52).
|
|
77
|
+
Impact: ~5 extra tool calls and a near-miss structural breakage on a single block deletion.
|
|
78
|
+
- `instruction-violation` (user-caught) — the operator interjected "Use unicode literal characters, not escapes, per system prompt" (turn 49).
|
|
79
|
+
The system prompt already carries an "Edit Tool and Unicode Characters" section; the box-drawing match failures read to the operator as escape misuse.
|
|
80
|
+
Impact: one user correction; reinforced the same `Edit`-matching friction above.
|
|
81
|
+
- `other` (malformed payload) — the first `architecture.md` Step 6 edit was rejected for an invalid `oldText_unused` property I invented (turn 87), followed by empty assistant turns and two operator "Try again" nudges (turns 89, 94) before a clean single edit landed (turn 95).
|
|
82
|
+
Impact: ~4 turns + 2 user nudges on one prose edit.
|
|
83
|
+
- `other` (commit hygiene) — the `index.ts` comment-trim fixup was first amended into the `docs` commit (turn 108), then moved into the `refactor` commit via `reset --soft` (turn 109); separately, the stale-suppression fixup required the same maneuver during TDD.
|
|
84
|
+
Both self-identified and corrected.
|
|
85
|
+
Impact: two extra `reset --soft` + re-stage cycles; no rework to shipped code.
|
|
86
|
+
|
|
87
|
+
#### What caused friction (user side)
|
|
88
|
+
|
|
89
|
+
- The "no setters, instantiate ready-to-work" principle that drove the entire design only surfaced when the planning `ask_user` forced it.
|
|
90
|
+
Stated in the issue body or a standing design note, it would have let planning reach the dissolve approach without the round-trip — though the round-trip was cheap and the outcome correct.
|
|
91
|
+
|
|
92
|
+
### Diagnostic details
|
|
93
|
+
|
|
94
|
+
- **Model-performance correlation** — Planning and TDD ran on `anthropic/claude-opus-4-8` (judgment-heavy design + implementation; appropriate).
|
|
95
|
+
The pre-completion-reviewer subagent ran on `anthropic/claude-sonnet-4-6` per its frontmatter (appropriate for review).
|
|
96
|
+
Ship ran on `opencode-go/deepseek-v4-flash` — a cheap model on mechanical orchestration, completed without error.
|
|
97
|
+
No mismatch found.
|
|
98
|
+
- **Escalation-delay tracking** — no `rabbit-hole` exceeded the 5-consecutive-call threshold; the `Edit`/`sed` friction was 2–3 calls per location and self-resolved.
|
|
99
|
+
- **Unused-tool detection** — nothing notable; the friction points were mechanical edits, not missing context, so no Explore/`colgrep` dispatch would have helped.
|
|
100
|
+
- **Feedback-loop gap analysis** — verification was incremental and exemplary: `pnpm run check` after the shared-interface change in Step 2 (turn 43) and again mid-Step-3 (turns 69, 75, 78, 81); per-file `vitest run` after each Red and Green; `fallow dead-code` from repo root before ship.
|
|
101
|
+
No end-only verification anti-pattern.
|
|
102
|
+
|
|
103
|
+
### Changes made
|
|
104
|
+
|
|
105
|
+
1. `AGENTS.md` — appended two sentences to the "Edit tool batches" subsection: anchor edits on adjacent unique code lines rather than decorative `─`/`═` comment rules, and re-read after a `sed` line-number deletion to confirm an enclosing brace survived.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gotgenes/pi-subagents",
|
|
3
|
-
"version": "16.3.
|
|
3
|
+
"version": "16.3.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"exports": {
|
|
6
6
|
".": {
|
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
"#src/*": "./src/*",
|
|
22
22
|
"#test/*": "./test/*"
|
|
23
23
|
},
|
|
24
|
-
"description": "A
|
|
24
|
+
"description": "A focused, in-process sub-agent core for pi — autonomous agents plus a typed API and lifecycle events other extensions build on. Friendly fork of @tintinweb/pi-subagents.",
|
|
25
25
|
"author": {
|
|
26
26
|
"name": "Chris Lasher"
|
|
27
27
|
},
|
package/src/index.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/* eslint-disable @typescript-eslint/no-unsafe-argument -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
|
|
2
2
|
/**
|
|
3
|
-
* pi-agents — A pi extension providing
|
|
3
|
+
* pi-agents — A pi extension providing focused, in-process autonomous sub-agents.
|
|
4
4
|
*
|
|
5
5
|
* Tools:
|
|
6
6
|
* Agent — LLM-callable: spawn a sub-agent
|
|
@@ -41,7 +41,7 @@ export function getStatusLabel(status: string, error?: string): string {
|
|
|
41
41
|
}
|
|
42
42
|
}
|
|
43
43
|
|
|
44
|
-
/** Format a structured task
|
|
44
|
+
/** Format a structured <task-notification> XML block for the parent agent to parse. */
|
|
45
45
|
export function formatTaskNotification(record: Subagent, resultMaxLen: number): string {
|
|
46
46
|
const status = getStatusLabel(record.status, record.error);
|
|
47
47
|
const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
|
package/src/tools/agent-tool.ts
CHANGED