@ferris1225/pi-subagents 0.31.0 → 1.0.0

package/src/fixloop.ts

@@ -87,7 +87,7 @@ export function chainKeyFragments(result: SingleResult): string[] {
 }
 
 /**
- * Compact one-line outcome for a finished chain run, shown in the widget so
+ * Compact one-line outcome for a finished chain run, retained so
  * each round reads as what it did: a reviewer reports its verdict plus the
  * key fragments of what it found ("fail · src/index.ts · render()"), a worker
  * the fragments of what it changed. Failed runs and runs with nothing

package/src/format.ts

@@ -90,7 +90,7 @@ export function formatCompletionBlock(result: SingleResult, maxResultLines: numb
 	const output = getResultOutput(result);
 	const { text, truncated } = truncateResultOutput(output, maxResultLines);
 	const fallbackNote = result.modelFallbackFrom
-		? ` (model fell back from ${result.modelFallbackFrom} to ${result.model ?? "main-window model"})`
+		? ` (model pool fallback: primary ${result.modelFallbackFrom} → final ${result.model ?? "dynamic default"})`
 		: "";
 	const startupRetryNote = result.startupRetries
 		? ` (recovered after ${result.startupRetries} startup retr${result.startupRetries === 1 ? "y" : "ies"} — concurrent pi startup race)`
@@ -98,7 +98,33 @@ export function formatCompletionBlock(result: SingleResult, maxResultLines: numb
 	const modelRetryNote = result.modelRetries
 		? ` (recovered after ${result.modelRetries} same-model retr${result.modelRetries === 1 ? "y" : "ies"} on a transient provider error)`
 		: "";
-	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}${startupRetryNote}${modelRetryNote}`, "", `Task: ${formatTaskSummary(result.task, 80, false)}`, "", text];
+	const relations = [
+		result.forkedFromRunId !== undefined ? `forked from #${result.forkedFromRunId}` : undefined,
+		(result.forkChildRunIds?.length ?? 0) > 0 ? `fork children ${result.forkChildRunIds!.map((id) => `#${id}`).join(", ")}` : undefined,
+	].filter((value): value is string => Boolean(value));
+	const relationNote = relations.length > 0 ? ` · ${relations.join(" · ")}` : "";
+	const runNote = result.runId !== undefined ? ` · run #${result.runId}` : "";
+	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}${startupRetryNote}${modelRetryNote}${runNote}`, "", `Task: ${formatTaskSummary(result.task, 80, false)}`, ""];
+	if (result.isolation === "worktree") {
+		const isolation =
+			result.integrationStatus === "integrated"
+				? "worktree · changes integrated into the original working tree"
+				: result.integrationStatus === "no_changes"
+					? "worktree · no changes; temporary worktree removed"
+					: result.integrationStatus === "retained"
+						? result.integrationApplied
+							? "worktree · changes applied, but cleanup failed; recovery artifacts retained"
+							: "worktree · integration failed; recovery artifacts retained"
+						: "worktree · isolated";
+		lines.push(`Isolation: ${isolation}${relationNote}`);
+		if (result.integrationWorktreePath) lines.push(`Retained worktree: ${result.integrationWorktreePath}`);
+		if (result.integrationPatchPath) lines.push(`Retained patch: ${result.integrationPatchPath}`);
+		if (result.integrationError) lines.push(`Integration error: ${result.integrationError}`);
+		lines.push("");
+	} else if (relations.length > 0) {
+		lines.push(`Relation: ${relations.join(" · ")}`, "");
+	}
+	lines.push(text);
 	// A run can exit cleanly while its last tools failed (e.g. a build that broke):
 	// the final text alone may claim more than the tools achieved, so surface the
 	// failures explicitly and tell the main agent to verify before relying on it.
@@ -130,10 +156,10 @@ export function modelLevelTakeoverNote(result: SingleResult, opts?: { runId?: nu
 	const sameModel = result.modelRetries
 		? `, after ${result.modelRetries} same-model retr${result.modelRetries === 1 ? "y" : "ies"} on transient errors`
 		: "";
-	const retry = result.modelFallbackFrom ? ", and the resume on the main-window model also failed" : "";
+	const retry = result.modelFallbackFrom ? ", and the configured backup chain also failed" : "";
 	const sessionPreserved = Boolean(result.sessionDir && result.sessionId) && opts?.runId !== undefined;
 	const recovery = sessionPreserved
-		? ` The sub-agent's earlier work in this run is preserved. Once a model is available again, call subagent with { resume: ${opts!.runId} } to CONTINUE it in-context (it picks up where it stopped — no re-scan), or execute the task in the main window with your own tools.`
+		? ` The sub-agent's earlier work in this run is preserved. Once a model is available again, call subagent_control with { action: "resume", id: ${opts!.runId} } to CONTINUE it in-context (it keeps the same run id and does not re-scan), or execute the task in the main window with your own tools.`
 		: ` Please execute this task in the main window with your own tools; do not re-dispatch it as a sub-agent.`;
 	return `The sub-agent could not complete this task: its model was unavailable or failed (or the run stalled)${sameModel}${retry}.${recovery}`;
 }

package/src/index.ts

@@ -4,9 +4,9 @@
  * Assembly point: builds the shared runtime and registers everything.
  * The heavy lifting lives in focused modules:
  *   - dispatch.ts  — the `subagent` tool (spawn, auto-fix chain, vision model)
- *   - tools.ts     — subagent_wait / subagent_status / subagent_stop
- *   - widget.ts    — session_start widget + one-time feature announcements
- *   - runtime.ts   — shared per-session state
+ *   - tools.ts     — subagent_control / subagent_wait / status / stop
+ *   - announcements.ts — session-start recovery and feature notices
+ *   - runtime.ts       — shared per-session state
  *
  * Also registers the `/subagents-setup` command and a `before_agent_start` hook
  * that injects a delegation directive into the parent system prompt so the main
@@ -19,6 +19,7 @@
 import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { discoverAgents } from "./agents.ts";
+import { registerAnnouncements } from "./announcements.ts";
 import { getConfigPath, loadConfig } from "./config.ts";
 import { registerSubagentTool } from "./dispatch.ts";
 import { matchRunIds } from "./format.ts";
@@ -27,7 +28,6 @@ import { createRuntime } from "./runtime.ts";
 import { runSetup } from "./setup.ts";
 import { currentSubagentDepth } from "./spawn.ts";
 import { registerLookupTools } from "./tools.ts";
-import { registerWidget } from "./widget.ts";
 
 export { matchRunIds };
 
@@ -57,23 +57,21 @@ export default function (pi: ExtensionAPI): void {
 		),
 	);
 
-	pi.on("session_shutdown", () => {
-		runtime.shutdown();
+	pi.on("session_shutdown", async () => {
+		await runtime.shutdown();
 	});
 
 	registerSubagentTool(pi, runtime);
 	registerLookupTools(pi, runtime);
 
 	pi.registerCommand("subagents-setup", {
-		description: "Configure pi-subagents: enable agents, pick per-agent models, toggle proactive injection",
+		description: "Configure pi-subagents: enabled agents, primary/backup model pools, and runtime settings",
 		handler: async (_args, ctx) => {
 			await runSetup(ctx, configPath);
 		},
 	});
 
-	// Persistent widget above the editor showing live sub-agent status, plus
-	// one-time feature announcements after updates.
-	registerWidget(pi, runtime);
+	registerAnnouncements(pi, runtime);
 
 	// Proactive dispatch: inject the delegation directive into the parent system prompt.
 	pi.on("before_agent_start", async (event, ctx) => {
@@ -82,6 +80,7 @@ export default function (pi: ExtensionAPI): void {
 		const { agents } = discoverAgents(ctx.cwd, {
 			scope: config.agentScope,
 			enabledNames: config.enabledAgents,
+			projectTrusted: ctx.isProjectTrusted?.() === true,
 		});
 		const directive = buildDelegationDirective(agents);
 		if (!directive) return undefined;

package/src/models.ts

@@ -1,82 +1,212 @@
-/**
- * Model availability helpers shared by setup and sub-agent execution.
+/*
+ * Model-pool resolution and setup-picker helpers.
  *
- * A configured override can outlive a provider login, a scoped-model change, or
- * a model rename. Keep the main session usable by replacing such overrides with
- * the model currently selected in the main window (or the first available model)
- * and let callers persist the repaired mapping.
+ * Runtime pools deliberately do not filter configured references by current
+ * availability: a stale primary/backup is attempted and normal provider/model
+ * failure handling advances to the next candidate. Setup uses the same catalog
+ * only for honest availability labels; it never rewrites persisted choices.
  */
 
+import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-export type ModelContext = Pick<ExtensionContext, "model" | "scopedModels" | "modelRegistry">;
+export type ModelContext = Pick<ExtensionContext, "model" | "modelRegistry"> &
+	Partial<Pick<ExtensionContext, "scopedModels">>;
+
+export const CURRENT_MAIN_MODEL = "__current_main_model__";
+
+export type ModelPoolSlot = "primary" | "backup";
+export type ModelPickerSlot = ModelPoolSlot | "vision";
+
+export interface ModelPickerItem {
+	value: string;
+	label: string;
+	description?: string;
+	/** Visible for diagnosis/search, but cannot be selected. */
+	disabled?: boolean;
+}
+
+export type ModelListEntry = Pick<
+	Model<Api>,
+	"provider" | "id" | "name" | "input" | "reasoning"
+>;
+
+export interface ResolvedAgentModelPool {
+	/** Effective first candidate. Undefined means let pi use its normal default. */
+	primaryRef?: string;
+	/** Ordered candidates after the primary, already deduplicated. */
+	fallbackModelRefs: string[];
+	/** All known references in runtime order, useful for tests/inspection. */
+	candidateRefs: string[];
+}
+
+export interface AgentModelPoolInput {
+	primaryRef?: string;
+	backupRef?: string;
+	mainRef?: string;
+	declaredDefaultRef?: string;
+}
 
-export interface ModelOverrideRepair {
+export interface AgentModelPoolMaps {
 	agentModels: Record<string, string>;
-	changed: boolean;
-	replaced: number;
-	removed: number;
-	fallbackRef?: string;
+	agentBackupModels: Record<string, string>;
+}
+
+export interface AgentModelPoolRow {
+	name: string;
+	primary: string;
+	backup: string;
+}
+
+function cleanModelRef(ref: string | undefined): string | undefined {
+	const trimmed = ref?.trim();
+	return trimmed || undefined;
 }
 
 export function modelRef(model: { provider: string; id: string }): string {
 	return `${model.provider}/${model.id}`;
 }
 
+export function currentModelRef(ctx: Pick<ModelContext, "model">): string | undefined {
+	return ctx.model ? modelRef(ctx.model) : undefined;
+}
+
 /**
- * Return model references usable by the current main window, with its current
- * model first so it is the deterministic fallback for stale configuration.
+ * Current authenticated registry models narrowed by the session scope. Scope
+ * entries are a session snapshot, so they act only as a whitelist; the live
+ * registry remains the source of truth for availability and model metadata.
  */
+export function availableModelsInScope(ctx: ModelContext): readonly Model<Api>[] {
+	const models = ctx.modelRegistry.getAvailable();
+	// scopedModels was added after the declared Pi 0.80.6 minimum. Treat a
+	// missing field exactly like an empty scope and use the full live registry.
+	const scopedModels = ctx.scopedModels ?? [];
+	if (scopedModels.length === 0) return models;
+	const scopedRefs = new Set(scopedModels.map((entry) => modelRef(entry.model)));
+	return models.filter((model) => scopedRefs.has(modelRef(model)));
+}
+
+/** Model refs usable by setup, with an available current main model first. */
 export function availableModelRefs(ctx: ModelContext): string[] {
-	const scoped = ctx.scopedModels.length > 0 ? ctx.scopedModels.map((entry) => entry.model) : undefined;
-	const models = scoped ?? ctx.modelRegistry.getAvailable();
-	const refs = [...new Set(models.map(modelRef))];
-	const currentRef = ctx.model ? modelRef(ctx.model) : undefined;
-	if (!currentRef) return refs;
+	const refs = [...new Set(availableModelsInScope(ctx).map(modelRef))];
+	const currentRef = currentModelRef(ctx);
+	if (!currentRef || !refs.includes(currentRef)) return refs;
 	return [currentRef, ...refs.filter((ref) => ref !== currentRef)];
 }
 
 /**
- * Resolve the model for a `vision: true` dispatch. The configured vision model
- * wins when it is usable by the current session; otherwise the task falls back
- * to the main window's current model (the documented behavior when the vision
- * model is unset). Returns undefined only when neither exists — callers then
- * keep the agent's own model as the last resort.
+ * Resolve one agent's ordered runtime pool:
+ *
+ * configured primary -> configured backup -> current main-window model
+ *
+ * Without a primary override, the current main model remains the primary; an
+ * agent-declared default is used only when no main model exists. Equal refs are
+ * removed without consulting availability, so stale refs stay in the chain and
+ * fail normally at runtime instead of being silently repaired.
  */
-export function resolveVisionModelRef(ctx: ModelContext, visionModel?: string): string | undefined {
-	const configured = visionModel?.trim();
-	if (configured && availableModelRefs(ctx).includes(configured)) return configured;
-	return ctx.model ? modelRef(ctx.model) : undefined;
+export function resolveAgentModelPool(input: AgentModelPoolInput): ResolvedAgentModelPool {
+	const mainRef = cleanModelRef(input.mainRef);
+	const primaryRef = cleanModelRef(input.primaryRef) ?? mainRef ?? cleanModelRef(input.declaredDefaultRef);
+	const ordered = [primaryRef, cleanModelRef(input.backupRef), mainRef];
+	const seen = new Set<string>();
+	const candidateRefs: string[] = [];
+	for (const ref of ordered) {
+		if (!ref || seen.has(ref)) continue;
+		seen.add(ref);
+		candidateRefs.push(ref);
+	}
+	const fallbackModelRefs = candidateRefs.filter((ref) => ref !== primaryRef);
+	return { primaryRef, fallbackModelRefs, candidateRefs };
 }
 
-/** Replace unavailable persisted overrides with a model usable by the main session. */
-export function repairUnavailableModelOverrides(
-	ctx: ModelContext,
-	agentModels: Record<string, string>,
-): ModelOverrideRepair {
-	const refs = availableModelRefs(ctx);
-	const available = new Set(refs);
-	const fallbackRef = refs[0];
-	const repaired: Record<string, string> = {};
-	let changed = false;
-	let replaced = 0;
-	let removed = 0;
-
-	for (const [name, configuredRef] of Object.entries(agentModels)) {
-		const ref = configuredRef.trim();
-		if (available.has(ref)) {
-			repaired[name] = ref;
-			continue;
-		}
+function modelCapabilities(model: ModelListEntry): string {
+	const capabilities = [model.input.includes("image") ? "vision" : "text-only"];
+	if (model.reasoning) capabilities.push("reasoning");
+	return capabilities.join(" + ");
+}
+
+/** Build the single searchable model list shared by primary/backup/vision picks.
+ * Only refs Pi currently reports as available are shown, which means providers
+ * without a configured API key/OAuth session never flood the setup picker. */
+export function buildModelPickerItems(options: {
+	models: readonly ModelListEntry[];
+	availableRefs: readonly string[];
+	slot: ModelPickerSlot;
+	configuredRef?: string;
+	mainRef?: string;
+}): ModelPickerItem[] {
+	const configuredRef = cleanModelRef(options.configuredRef);
+	const mainRef = cleanModelRef(options.mainRef);
+	const available = new Set(options.availableRefs.map((ref) => ref.trim()));
+	const byRef = new Map<string, ModelListEntry>();
+	for (const model of options.models) {
+		const ref = modelRef(model);
+		if (available.has(ref) && !byRef.has(ref)) byRef.set(ref, model);
+	}
+
+	const refs = [...byRef.keys()]
+		.filter((ref) => options.slot !== "vision" || byRef.get(ref)?.input.includes("image") === true)
+		.sort((left, right) => {
+			const leftRank = left === configuredRef ? 0 : left === mainRef ? 1 : 2;
+			const rightRank = right === configuredRef ? 0 : right === mainRef ? 1 : 2;
+			return leftRank - rightRank || left.localeCompare(right);
+		});
 
-		changed = true;
-		if (fallbackRef) {
-			repaired[name] = fallbackRef;
-			replaced++;
-		} else {
-			removed++;
+	const dynamic = options.slot === "backup"
+		? {
+			value: CURRENT_MAIN_MODEL,
+			label: "Current main model (default)",
+			description: "Clear configured backup; use the main-window model dynamically",
 		}
+		: {
+			value: CURRENT_MAIN_MODEL,
+			label: "Current main model (dynamic)",
+			description: options.slot === "vision"
+				? "Clear vision override; use the main-window model for vision tasks"
+				: "Clear primary override; use the main-window model dynamically",
+		};
+
+	const items: ModelPickerItem[] = [dynamic];
+	for (const ref of refs) {
+		const model = byRef.get(ref)!;
+		const tags = ["available"];
+		if (ref === configuredRef) tags.push("configured");
+		if (ref === mainRef) tags.push("current main");
+		const name = model.name.trim() && model.name !== model.id ? model.name.trim() : undefined;
+		items.push({
+			value: ref,
+			label: ref,
+			description: [name, modelCapabilities(model), ...tags].filter(Boolean).join(" · "),
+		});
 	}
+	return items;
+}
+
+/** Pure pool update: the dynamic/default choice removes the persisted override. */
+export function applyModelPoolChoice(
+	current: AgentModelPoolMaps,
+	agentName: string,
+	slot: ModelPoolSlot,
+	choice: string,
+): AgentModelPoolMaps {
+	const next: AgentModelPoolMaps = {
+		agentModels: { ...current.agentModels },
+		agentBackupModels: { ...current.agentBackupModels },
+	};
+	const target = slot === "primary" ? next.agentModels : next.agentBackupModels;
+	if (choice === CURRENT_MAIN_MODEL) delete target[agentName];
+	else target[agentName] = choice.trim();
+	return next;
+}
 
-	return { agentModels: repaired, changed, replaced, removed, fallbackRef };
+/** Pure rows used by the overview component and focused helper tests. */
+export function buildAgentModelPoolRows(
+	agentNames: readonly string[],
+	pools: AgentModelPoolMaps,
+): AgentModelPoolRow[] {
+	return agentNames.map((name) => ({
+		name,
+		primary: pools.agentModels[name] ?? "Main (dynamic)",
+		backup: pools.agentBackupModels[name] ?? "Main (default)",
+	}));
 }