@ferris1225/pi-subagents 0.32.2 → 1.0.0

package/README.md

@@ -11,6 +11,28 @@ 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. An internal append-only
+lifecycle trajectory keeps retries and stale generations from corrupting the
+logical thread.
+
+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`. 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,8 +41,8 @@ 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
@@ -52,12 +74,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 +150,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 +163,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 +204,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
 {
@@ -298,6 +316,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
@@ -311,9 +330,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
+`trajectory.ts` (internal lifecycle history), `tools.ts`
+(wait/status/control/stop), `announcements.ts` (recovery and feature notices),
+and `runtime.ts` (session-scoped ownership). No runtime dependencies beyond pi peer
 dependencies.
 
 ## License

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.0",
+  "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/announcements.ts

@@ -0,0 +1,59 @@
+/** 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";
+
+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") await announceNewFeatures(ctx, runtime);
+	});
+}