@cad0p/pi-subagents-tintinweb 0.14.2 → 0.22.0

package/docs/verification-checklist.md

@@ -0,0 +1,132 @@
+# PR Verification Checklist
+
+Automated checks are necessary but not sufficient. This checklist is what a PR
+author runs before requesting review. Record the evidence in the PR body so a
+reviewer can see what was verified, on which setup. Skip a section only when it
+does not apply, and say so explicitly.
+
+## Workspace
+
+Keep the main checkout on `main`. Do the branch work in an isolated git worktree
+in a sibling folder (`git worktree add ../<repo>-<slug> <branch>`), install its
+dependencies there, and run every gate and live check from it. Remove the
+worktree after merge.
+
+## Automated gates
+
+Run all four from the repository root; all must pass (mirrors `CONTRIBUTING.md`'s
+"Before Submitting a PR"):
+
+```bash
+npm run lint        # biome
+npm run typecheck   # tsc --noEmit
+npm run test        # vitest, including the *-e2e.test.ts suites
+npm run build       # tsc
+```
+
+`npm run lint:fix` auto-fixes most style issues. If the change touches the
+end-to-end surface, also run the scripted suite directly:
+
+```bash
+npm run test:e2e
+```
+
+`PI_E2E_LIVE=1 npm run test:e2e` swaps the scripted faux suite for the live one
+and exercises a real model through your local `pi` login (`PI_PROVIDER` /
+`PI_MODEL` can pin the provider and model). Run it by hand before publishing.
+
+## Manual TUI checks
+
+Run these in a live pi session with the extension installed from the branch, and
+note the pi version in the PR body. Renderer behavior differs across pi
+versions; when the change targets a newer runtime, verify on that version too.
+
+Maintainer reference setup: `claude-bridge/claude-haiku-5-5` at thinking
+`xhigh`; fall back to `opencode-go/deepseek-v4.1-flash` at `max` when the bridge
+is unavailable. Load the branch build instead of the installed package so the two
+don't collide:
+
+```bash
+pi --no-extensions -e <pi-claude-bridge>/src/index.ts -e <repo>/src/index.ts \
+  --provider claude-bridge --model claude-haiku-5-5 --thinking xhigh
+```
+
+- Exercise the changed surface end to end in a real session — spawn, steer,
+  render, resume, or whatever the PR touches.
+- Toggle collapsed/expanded states with ctrl+o and, on pi 0.87.1+, per-row
+  click; confirm both paths reach the same state and the marker and hint update.
+- Check theme and color rendering in at least one dark theme; confirm wrapped or
+  clipped text stays within the intended box.
+- Feed long and edge inputs (empty, whitespace-only, multi-line, large) and
+  confirm the collapsed row stays bounded while the expanded view shows the full
+  content.
+- Confirm terminal control characters (ESC/OSC/CSI, newlines, tabs) in untrusted
+  text cannot forge rows or leak into the terminal: display copies are
+  sanitized, model-facing payloads are not.
+
+## Session-level checks
+
+Run these when the change touches session data, rendering, or persistence:
+
+- Load and replay an existing session containing the affected entry or tool
+  call; the old data must render without throwing.
+- Run `/export` and confirm the HTML renders without a crash and the affected
+  content appears where expected.
+- If the change touches cross-extension RPC or events, verify the RPC surface
+  still answers.
+
+## Independent agent review
+
+Every PR, docs included, needs a fresh read-only review agent on each pushed
+head before merge (plus any escalation). This section has no skip; the
+author's own checks don't count as review. Record every round in the PR body,
+under Evidence. A verdict counts only for the SHA it reviewed.
+
+- Spawn a new `general-purpose` agent with `max_turns: 20`. Don't
+  use `resume`, `inherit_context`, `isolation` (a worktree branches from the
+  caller's committed `HEAD`, not the PR head), or `steer_subagent`.
+- Brief it with the linked issue (the guarantees), the head SHA and the
+  worktree path holding it, the diff range `origin/main...<head-sha>`, and this
+  checklist. Leave out your own conclusions, test results, the PR body's
+  verification notes, and earlier verdicts. Frame it as a completeness
+  question: which inputs, callers, settings, or runtime versions would break
+  the guarantees while the gates stay green?
+- The brief forbids edits, commits, pushes, branch switches, and auto-fixers
+  (`npm run lint:fix`). It states the turn budget and the way out: reply
+  `NO VERDICT` with what was tested if the budget runs out, `HEAD` differs from
+  the head SHA, or the diff is empty.
+- The first line of the final message is `CLEAN`, `FINDINGS(n)`, or
+  `NO VERDICT`; then what it checked, and each finding tagged must-fix,
+  should-fix, or nit. A run that hit its turn limit, was aborted, or ends
+  without a first-line verdict counts as `NO VERDICT`.
+- After a `NO VERDICT`, retry `general-purpose` once with a narrower brief,
+  or a higher `max_turns` if the task needs it.
+- Escalate to the user-defined `smart` agent only when the review makes claims
+  that are easily shown wrong by facts (a misread API, code that doesn't exist,
+  behaviour the source contradicts). Don't escalate over opinionated findings
+  you disagree with. Confirm the result reports the escalated type: an unknown
+  `subagent_type` silently runs `general-purpose`, which is not an escalation.
+- A must-fix finding blocks its head until it is folded into a new head
+  (reviewed by a new `general-purpose` agent) or dismissed with the
+  maintainer's reason recorded in the PR body, citing the facts for a wrong
+  finding. A later verdict on the same head does not clear it by itself.
+  Should-fix and nit findings may stay open if recorded.
+- Merge only when the current head has a `CLEAN` or `FINDINGS(n)` verdict with
+  no undismissed must-fix findings.
+
+## Fork release rules
+
+- Do not edit `CHANGELOG.md` on non-release branches; the fork's
+  `validate-package-version` CI gate rejects it.
+- Release notes go in the PR body under `## Release notes`, with attribution
+  where one applies.
+
+## Evidence
+
+In the PR body, record:
+
+- the pi version and platform used for the live checks;
+- each command you ran and its result;
+- the manual observations (what you saw, not just "works");
+- every review round: the head it reviewed, the agent type, and the verdict;
+- any check that does not apply, and why.

package/examples/agent-tool-description.md

@@ -14,18 +14,12 @@ If the target is already known, use a direct tool — `read` for a known path, `
 ## Usage notes
 
 - Always include a short (3-5 word) description summarizing what the agent will do (shown in UI).
-- When you launch multiple agents for independent work, send them in a single message with multiple tool uses, with run_in_background: true on each, so they run concurrently. If the user specifies that they want agents run "in parallel", you MUST send a single message with multiple tool calls. Foreground calls run sequentially — only one executes at a time.
-- When the agent is done, it returns a single message back to you. The result is not visible to the user — to show the user, send a text message with a concise summary.
+- When an agent finishes or fails, you will be notified on subagent completion/failure — do NOT poll or sleep waiting for it.
 - Trust but verify: an agent's summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting work as done.
-- Use run_in_background for work you don't need immediately. You will be notified when it completes — do NOT poll or sleep waiting for it. Continue with other work or respond to the user instead.
-- Foreground vs background: use foreground (default) when you need the agent's results before you can proceed. Use background when you have genuinely independent work to do in parallel.
 - Use resume with an agent ID to continue a previous agent's work. A new (non-resume) Agent call starts a fresh agent with no memory of prior runs, so the prompt must be self-contained.
-- Use steer_subagent to send mid-run messages to a running background agent.
+- Use steer_subagent to send mid-run messages to a running subagent.
 - Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, etc.), since it is not aware of the user's intent.
-- If an agent's description says it should be used proactively, try to use it without the user having to ask for it first.
-- Use thinking to control extended thinking level.
-- Use inherit_context if the agent needs the parent conversation history.
-- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications). The worktree is automatically cleaned up if the agent makes no changes; otherwise the path and branch are returned in the result.{{scheduleGuideline}}
+- Use inherit_context if the agent needs the parent conversation history.{{isolationGuideline}}{{scheduleGuideline}}
 
 ## Writing the prompt
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cad0p/pi-subagents-tintinweb",
-  "version": "0.14.2",
+  "version": "0.22.0",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "publishConfig": {
@@ -25,18 +25,17 @@
     "autonomous"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.80.0",
-    "@earendil-works/pi-coding-agent": ">=0.80.0",
-    "@earendil-works/pi-tui": ">=0.80.0"
+    "@earendil-works/pi-ai": ">=1.0.4",
+    "@earendil-works/pi-coding-agent": ">=1.0.4",
+    "@earendil-works/pi-tui": ">=1.0.4",
+    "@sinclair/typebox": "*"
   },
   "dependencies": {
-    "@sinclair/typebox": "^0.34.49",
     "croner": "^10.0.1",
     "nanoid": "^5.0.0"
   },
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:e2e": "vitest run e2e --reporter=verbose",
@@ -46,16 +45,19 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
+    "@earendil-works/pi-ai": "1.0.4",
+    "@earendil-works/pi-coding-agent": "1.0.4",
+    "@earendil-works/pi-tui": "1.0.4",
     "@types/node": "^25.5.0",
     "typescript": "^6.0.0",
-    "vitest": "^4.0.18",
-    "@earendil-works/pi-ai": ">=0.80.0"
+    "vitest": "^4.0.18"
   },
   "pi": {
     "extensions": [
       "./src/index.ts"
-    ],
-    "video": "https://github.com/tintinweb/pi-subagents/raw/master/media/demo.mp4",
-    "image": "https://github.com/tintinweb/pi-subagents/raw/master/media/screenshot.png"
+    ]
+  },
+  "engines": {
+    "node": ">=22.19.0"
   }
 }

package/pnpm-workspace.yaml

@@ -10,3 +10,12 @@ allowBuilds:
   esbuild: true
   koffi: false
   protobufjs: true
+minimumReleaseAgeExclude:
+  - "@earendil-works/chord@1.0.4"
+  - "@earendil-works/pi-agent-core@1.0.4"
+  - "@earendil-works/pi-ai@1.0.4"
+  - "@earendil-works/pi-codemode@1.0.4"
+  - "@earendil-works/pi-coding-agent@1.0.4"
+  - "@earendil-works/pi-mcp@1.0.4"
+  - "@earendil-works/pi-telemetry@1.0.4"
+  - "@earendil-works/pi-tui@1.0.4"

package/src/abortable.ts

@@ -0,0 +1,43 @@
+/**
+ * abortable.ts — race a promise against an AbortSignal without cancelling the
+ * underlying work.
+ *
+ * Used by the nested `get_subagent_result` wait path: pressing Esc cancels only
+ * the caller's wait; the background child keeps running and its result stays
+ * unconsumed. The listener is removed on every settle path so the signal
+ * accumulates no handlers, and a late settlement of the wrapped promise after
+ * an abort is absorbed as a no-op (no unhandled rejection).
+ */
+
+/** Await a promise until it settles or the caller cancels, without aborting the underlying work. */
+export function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(signal.reason);
+
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(signal.reason);
+    };
+
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve(value);
+      },
+      (error: unknown) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(error);
+      },
+    );
+  });
+}