@ferris1225/pi-subagents 0.32.2 → 1.0.1

package/README.md

@@ -11,6 +11,30 @@ Focused background delegation for [pi](https://pi.dev): `explore` / `worker` /
 to the main agent automatically. Install it, and the main model starts using it
 on its own — no prompt engineering, no babysitting.
 
+## 1.0 — controllable agent threads
+
+Version 1.0 turns pi-subagents from a one-shot background runner into a small
+thread runtime. Every dispatch has a stable run id and retained Pi session, so
+work can be steered while it runs, parked without losing context, resumed after
+settlement, retargeted, or forked into another path. Generation ownership keeps
+retries and stale child processes from corrupting the logical thread without
+retaining a duplicate event history.
+
+The common quality loop now runs end to end without waking the main agent between
+steps:
+
+```text
+reviewer (find blockers) → worker (fix) → reviewer (verify) → final PASS/FAIL
+```
+
+Each chain is delivered as one concise completion group, while full per-run
+reports remain available through `subagent_status`. Its parent stays `running`
+until the whole chain settles; completed internal rounds leave active status
+immediately, so no `done` row keeps accumulating elapsed time. Ordered model
+pools keep the same retained context across provider fallback, and isolated parallel workers
+use detached Git worktrees whose changes are applied back without touching the
+parent index.
+
 ## Highlights
 
 - **Zero-setup proactive dispatch** — the extension injects a delegation directive
@@ -19,14 +43,17 @@ on its own — no prompt engineering, no babysitting.
   to `reviewer`. You just use pi; delegation happens by itself.
 - **Vision-capable image tasks** — flag screenshot/mockup/design work with
   `vision: true`. The configured vision primary is followed by that agent's
-  backup and the current main-window model. The setup picker offers only
-  image-capable models (while clearly marking an incompatible stale saved ref),
+  backup and the current main-window model. Setup lists only in-scope,
+  image-capable models from providers with a configured API key or OAuth session,
   and runtime failures never silently rewrite your configuration.
 - **Results come back on their own** — completions are delivered as messages that
   wake the main agent automatically, even mid-turn. No polling, no `sleep`, no
   "go check" step. `subagent_wait` is a **non-blocking** in-turn lookup by default
   (pass `timeoutMs` to block); `subagent_status` inspects runs; `subagent_stop`
   cancels one and delivers its partial output.
+- **Active-only live widget** — the TUI shows queued and running sub-agents above
+  the editor with live activity and elapsed time. Settled and parked rows disappear
+  immediately; an auto-fix parent remains `running` until its whole chain settles.
 - **Results are not re-narrated** — a sub-agent's completion is shown to you
   verbatim, and the main agent is told not to paraphrase it back. It replies with
   only its own conclusion or next step, so the same findings are never paid for
@@ -52,12 +79,6 @@ on its own — no prompt engineering, no babysitting.
   configurable limit (default 4). Parallel workers default to detached Git
   worktrees; tracked, deleted, untracked, and binary changes are applied back
   without touching the parent index. Failed integration keeps recovery artifacts.
-- **Live inspector** — `/subagents-inspect` opens a master/detail
-  overlay with thread state, model chain, usage, transcript, recent tools,
-  worktree/fork relations, and the append-only control trajectory.
-- **Live progress widget** — each run's status, current activity, model, token
-  usage, and elapsed time; auto-fix chain rounds hang under their triggering
-  review as a tree, each finished round keeping a one-line outcome.
 - **Recursion is structurally impossible** — children are leaf processes; the
   `subagent` tool is excluded from their toolset.
 - **Zero runtime dependencies** — agents are plain Markdown files; overriding or
@@ -134,7 +155,10 @@ once, then skipped as a permanent candidate error; it is not rewritten. A
 vision-flagged auto-fix chain keeps the flag for worker/re-review rounds because
 they may need to inspect the same images.
 
-### Controlling, inspecting, and stopping
+### Controlling and stopping
+
+Dispatch confirmations, tool result rows, and completion blocks all show the
+stable `#id`, so a thread remains directly controllable after its live UI is gone.
 
 - `subagent_control` — `steer`, `retarget`, `park`, `resume`, or `fork` a logical
   thread by stable run id. Resume accepts an optional replacement objective;
@@ -144,8 +168,6 @@ they may need to inspect the same images.
   run returns immediately; an active run tells the model to end its turn. Pass
   `timeoutMs` only when you must stay in the turn.
 - `subagent_status` — active/parked/finished runs and full result by run id.
-- `/subagents-inspect` — interactive live thread/transcript/tool/trajectory
-  overlay; press `p` to park or resume the selected thread.
 - `subagent_stop` — destructive cancellation. It retires that thread's retained
   session (independent forks survive) and delivers exactly one aborted partial
   result after the run and any worktree integration have quiesced.
@@ -187,8 +209,9 @@ Stored at `~/.pi/agent/pi-subagents.json` (follows `PI_CODING_AGENT_DIR` when
 set). The `/subagents-setup` wizard drives every field interactively — models, the
 default plus each enabled agent's thinking level, the vision model, concurrency,
 fix rounds, idle timeout, scope, and injection — with a per-agent "configure
-one" menu when the config already exists. `notifyOnReviewPass` and
-`maxResultLines` are edited directly in the file.
+one" menu when the config already exists. Model pickers show only models in the
+current session scope that are available through a configured API key or OAuth
+session. `notifyOnReviewPass` and `maxResultLines` are edited directly in the file.
 
 ```json
 {
@@ -268,11 +291,11 @@ sessions live until the parent Pi session shuts down.
 
 ### Configuration migration
 
-The config file migrates itself on load — no manual steps after an upgrade:
-schema upgrades are normalized and saved back, removed agents are stripped,
-legacy keys (`maxParallelTasks`, `maxSubagentDepth`) are folded in or dropped,
-and new fields are filled with defaults. New features are announced to you once
-after an update via a toast (marker persisted in `announcedFeatures`).
+The config file normalizes itself on load — no manual steps after an upgrade:
+configured non-empty agent names are preserved, invalid values and unsupported
+keys (including `maxParallelTasks` and `maxSubagentDepth`) are dropped, and
+missing current fields are filled with defaults. New features are announced to
+you once after an update via a toast (marker persisted in `announcedFeatures`).
 
 ## Agent discovery and overrides
 
@@ -298,6 +321,7 @@ after an update via a toast (marker persisted in `announcedFeatures`).
 - **Dispatch failures surface** — partial parallel startup reports every failed
   item and reason; if none start, the tool throws so Pi records a real tool error.
   Dispatch crashes likewise produce a failed result instead of a silent hang.
+- **Safe live status** — tool activity is credential-redacted and stripped of terminal control sequences before `subagent_status` can return it.
 - **Leaf children** — no nested delegation, no runaway trees.
 
 ## Development
@@ -310,10 +334,9 @@ npm test
 
 The source is modular: `dispatch.ts` (dispatch, controls, isolation, auto-fix),
 `rpc-run.ts` / `spawn.ts` (persistent child transport + model pools),
-`worktree.ts` / `session-fork.ts` (filesystem/session branching),
-`trajectory.ts` / `inspector*.ts` (safe live inspection), `tools.ts`
-(wait/status/control/stop), `widget.ts` (widget + recovery announcements), and
-`runtime.ts` (session-scoped ownership). No runtime dependencies beyond pi peer
+`worktree.ts` / `session-fork.ts` (filesystem/session branching), `tools.ts`
+(wait/status/control/stop), `widget.ts` (active-only TUI status), `announcements.ts`
+(recovery and feature notices), and `runtime.ts` (session-scoped ownership). No runtime dependencies beyond pi peer
 dependencies.
 
 ## License

package/agents/reviewer.md

@@ -60,5 +60,7 @@ Understand the context first, then verify: the fix addresses the root cause, cha
 One of: APPROVE / APPROVE_WITH_NITS / REQUEST_CHANGES, plus a 2-3 sentence rationale.
 End with exactly one machine-readable line: `VERDICT: REVIEW_PASS` for APPROVE or APPROVE_WITH_NITS; `VERDICT: REVIEW_FAIL` for REQUEST_CHANGES.
 
+REQUEST_CHANGES (or review-blocking concern) on this extension automatically starts an auto-fix loop: a worker is briefed with your findings, then you re-review, up to the configured round limit. Choose REVIEW_PASS when nothing objectively blocks the change (style preferences, optional refactors, or items the caller can knowingly accept are not blockers) — do not force a verdict that would trigger another loop just to hedge.
+
 ## Quality standards
 Specific file paths and line numbers. No vague feedback. A clean report means you looked hard, not that you found nothing to say.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.32.2",
-  "description": "Focused sub-agent delegation for pi: explore / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
+  "version": "1.0.1",
+  "description": "Controllable background sub-agent threads for pi: explore, worker, reviewer, auto-fix chains, model pools, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",
   "publishConfig": {

package/src/agents.ts

@@ -31,11 +31,6 @@ export interface AgentConfig {
 	filePath: string;
 }
 
-export interface AgentDiscoveryResult {
-	agents: AgentConfig[];
-	projectAgentsDir: string | null;
-}
-
 const here = dirname(fileURLToPath(import.meta.url));
 /** <package>/agents — the agents shipped with this extension. */
 export const BUILTIN_AGENTS_DIR = join(here, "..", "agents");
@@ -135,7 +130,7 @@ export interface DiscoverOptions {
  * Discover agents across scopes and apply the enabled-name filter.
  * Override priority for the same name: project > user > builtin.
  */
-export function discoverAgents(cwd: string, options: DiscoverOptions = {}): AgentDiscoveryResult {
+export function discoverAgents(cwd: string, options: DiscoverOptions = {}): { agents: AgentConfig[] } {
 	const scope = options.scope ?? "user";
 	const builtinDir = options.builtinDir ?? BUILTIN_AGENTS_DIR;
 	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
@@ -160,7 +155,7 @@ export function discoverAgents(cwd: string, options: DiscoverOptions = {}): Agen
 		agents = agents.filter((agent) => enabled.has(agent.name));
 	}
 
-	return { agents, projectAgentsDir };
+	return { agents };
 }
 
 /** One-line catalog entry for system-prompt injection and error messages. */

package/src/announcements.ts

@@ -0,0 +1,62 @@
+/** Session-start recovery and one-time feature announcements. */
+
+import { stat } from "node:fs/promises";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig, saveConfig } from "./config.ts";
+import { announceRecoveryRecords } from "./recovery.ts";
+import type { SubagentRuntime } from "./runtime.ts";
+import { installActiveRunsWidget } from "./widget.ts";
+
+const ANNOUNCEMENTS: Array<{
+	key: string;
+	condition: (config: Awaited<ReturnType<typeof loadConfig>>) => boolean;
+	message: string;
+}> = [
+	{
+		key: "visionModel",
+		condition: (config) => config.visionModel === undefined,
+		message:
+			"pi-subagents: new — a vision-capable model can now handle image tasks (screenshots, mockups, designs). Run /subagents-setup to configure it; until set, vision tasks use the main session's current model.",
+	},
+];
+
+async function announceNewFeatures(
+	ctx: { ui: { notify: (message: string, kind: "info" | "warning" | "error") => void } },
+	runtime: SubagentRuntime,
+): Promise<void> {
+	try {
+		let configExists = true;
+		try {
+			await stat(runtime.configPath);
+		} catch {
+			configExists = false;
+		}
+		if (!configExists) return;
+
+		const config = await loadConfig(runtime.configPath);
+		const pending = ANNOUNCEMENTS.filter(
+			(announcement) =>
+				announcement.condition(config) && !config.announcedFeatures.includes(announcement.key),
+		);
+		if (pending.length === 0) return;
+		await saveConfig(
+			{
+				...config,
+				announcedFeatures: [...config.announcedFeatures, ...pending.map((announcement) => announcement.key)],
+			},
+			runtime.configPath,
+		);
+		for (const announcement of pending) ctx.ui.notify(announcement.message, "info");
+	} catch {
+		/* announcement failures are non-fatal */
+	}
+}
+
+export function registerAnnouncements(pi: ExtensionAPI, runtime: SubagentRuntime): void {
+	pi.on("session_start", async (_event, ctx) => {
+		await announceRecoveryRecords(runtime.configPath, ctx);
+		if (ctx.mode !== "tui") return;
+		installActiveRunsWidget(ctx);
+		await announceNewFeatures(ctx, runtime);
+	});
+}

package/src/completion.ts

@@ -2,8 +2,7 @@
  * Smart batching for successful background completions.
  *
  * A short debounce coalesces sibling runs while a max-wait timer, measured from
- * the first item in the open group, bounds delivery latency. Runs that finish
- * shortly after an emitted group use a smaller straggler window. Failures are
+ * the first item in the open group, bounds delivery latency. Failures are
  * intentionally handled by the caller: flush held successes, then emit the
  * failure directly so it is never delayed.
  */
@@ -13,30 +12,14 @@ import { getResultOutput, isFailedResult, reviewVerdict, type SingleResult } fro
 export interface CompletionBatchTimings {
 	debounceMs: number;
 	maxWaitMs: number;
-	stragglerDebounceMs: number;
-	stragglerMaxWaitMs: number;
-	stragglerWindowMs: number;
 }
 
 export const DEFAULT_COMPLETION_BATCH_TIMINGS: CompletionBatchTimings = {
 	debounceMs: 150,
 	maxWaitMs: 1_000,
-	stragglerDebounceMs: 75,
-	stragglerMaxWaitMs: 400,
-	stragglerWindowMs: 2_000,
 };
 
-type TimerHandle = unknown;
-
-export interface TimerApi {
-	setTimeout(handler: () => void, delayMs: number): TimerHandle;
-	clearTimeout(handle: TimerHandle): void;
-}
-
-const defaultTimers: TimerApi = {
-	setTimeout: (handler, delayMs) => setTimeout(handler, delayMs),
-	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
-};
+type TimerHandle = ReturnType<typeof setTimeout>;
 
 function unrefHandle(handle: TimerHandle): void {
 	if (
@@ -52,8 +35,6 @@ function unrefHandle(handle: TimerHandle): void {
 export interface CompletionBatcherOptions<T> {
 	emit: (items: T[]) => void;
 	timings?: Partial<CompletionBatchTimings>;
-	timers?: TimerApi;
-	now?: () => number;
 }
 
 export interface CompletionBatcher<T> {
@@ -66,22 +47,18 @@ export interface CompletionBatcher<T> {
 }
 
 export function createCompletionBatcher<T>(options: CompletionBatcherOptions<T>): CompletionBatcher<T> {
-	const timers = options.timers ?? defaultTimers;
-	const now = options.now ?? Date.now;
 	const timings = { ...DEFAULT_COMPLETION_BATCH_TIMINGS, ...options.timings };
 	let pending: T[] = [];
 	let debounceTimer: TimerHandle | null = null;
 	let maxWaitTimer: TimerHandle | null = null;
-	let straggler = false;
-	let lastEmitAt: number | null = null;
 
 	const clearTimers = (): void => {
 		if (debounceTimer !== null) {
-			timers.clearTimeout(debounceTimer);
+			clearTimeout(debounceTimer);
 			debounceTimer = null;
 		}
 		if (maxWaitTimer !== null) {
-			timers.clearTimeout(maxWaitTimer);
+			clearTimeout(maxWaitTimer);
 			maxWaitTimer = null;
 		}
 	};
@@ -91,25 +68,19 @@ export function createCompletionBatcher<T>(options: CompletionBatcherOptions<T>)
 		if (pending.length === 0) return;
 		const items = pending;
 		pending = [];
-		lastEmitAt = now();
 		options.emit(items);
 	};
 
 	return {
 		push(item: T): void {
-			if (pending.length === 0) {
-				straggler = lastEmitAt !== null && now() - lastEmitAt < timings.stragglerWindowMs;
-			}
 			pending.push(item);
 
-			if (debounceTimer !== null) timers.clearTimeout(debounceTimer);
-			const debounceDelay = straggler ? timings.stragglerDebounceMs : timings.debounceMs;
-			debounceTimer = timers.setTimeout(emitGroup, debounceDelay);
+			if (debounceTimer !== null) clearTimeout(debounceTimer);
+			debounceTimer = setTimeout(emitGroup, timings.debounceMs);
 			unrefHandle(debounceTimer);
 
 			if (maxWaitTimer === null) {
-				const maxWaitDelay = straggler ? timings.stragglerMaxWaitMs : timings.maxWaitMs;
-				maxWaitTimer = timers.setTimeout(emitGroup, maxWaitDelay);
+				maxWaitTimer = setTimeout(emitGroup, timings.maxWaitMs);
 				unrefHandle(maxWaitTimer);
 			}
 		},