@ferris1225/pi-subagents 4.0.1 → 4.1.2

package/src/models.ts

@@ -1,189 +1,189 @@
-/*
- * Model routing, capability-aware thinking, and setup-picker helpers.
- *
- * Runtime has one explicit fallback only: a configured agent model hands
- * off directly to the current main-window model. Setup lists only currently
- * available models and derives thinking choices from Pi's model metadata.
- */
-
-import {
-	clampThinkingLevel,
-	getSupportedThinkingLevels,
-	type Api,
-	type Model,
-} from "@earendil-works/pi-ai";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { DEFAULT_THINKING_LEVEL, type ThinkingLevel } from "./config.ts";
-
-export type ModelContext = Pick<ExtensionContext, "model" | "modelRegistry"> &
-	Partial<Pick<ExtensionContext, "scopedModels">>;
-
-export const CURRENT_MAIN_MODEL = "__current_main_model__";
-
-export interface ModelPickerItem {
-	value: string;
-	label: string;
-	description?: string;
-}
-
-export type ModelListEntry = Pick<
-	Model<Api>,
-	"provider" | "id" | "name" | "input" | "reasoning" | "thinkingLevelMap"
->;
-
-export interface ResolvedAgentModelRoute {
-	/** Effective first candidate. Undefined means let Pi use its normal default. */
-	primaryRef?: string;
-	/** Current main-window model when it differs from the selection. */
-	mainFallbackRef?: string;
-	/** Runtime order, useful for status/tests. */
-	candidateRefs: string[];
-	/** Configured ref skipped because Pi does not currently report it available. */
-	unavailableSelectedRef?: string;
-}
-
-export interface AgentModelRouteInput {
-	selectedRef?: string;
-	mainRef?: string;
-	declaredDefaultRef?: string;
-	/** When supplied, a configured selection outside this live set is skipped. */
-	availableRefs?: readonly 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;
-}
-
-/**
- * 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 original Pi 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)));
-}
-
-export function findModelByRef(
-	models: readonly Model<Api>[],
-	ref: string | undefined,
-): Model<Api> | undefined {
-	const normalized = cleanModelRef(ref);
-	return normalized ? models.find((model) => modelRef(model) === normalized) : undefined;
-}
-
-/**
- * Resolve one agent's runtime route:
- *
- * configured selection -> current main-window model
- *
- * Without an override, current main is primary; the agent-declared default is
- * used only when no main model exists. A configured selection that Pi no longer
- * reports as available is skipped immediately instead of spawning a doomed child.
- */
-export function resolveAgentModelRoute(input: AgentModelRouteInput): ResolvedAgentModelRoute {
-	const selectedRef = cleanModelRef(input.selectedRef);
-	const mainRef = cleanModelRef(input.mainRef);
-	const declaredDefaultRef = cleanModelRef(input.declaredDefaultRef);
-	const available = input.availableRefs
-		? new Set(input.availableRefs.map((ref) => ref.trim()).filter(Boolean))
-		: undefined;
-	const selectedAvailable = !selectedRef || !available || available.has(selectedRef);
-	const usableSelectedRef = selectedAvailable ? selectedRef : undefined;
-	const primaryRef = usableSelectedRef ?? mainRef ?? declaredDefaultRef;
-	const ordered = [primaryRef, usableSelectedRef && usableSelectedRef !== mainRef ? mainRef : undefined];
-	const candidateRefs = [...new Set(ordered.filter((ref): ref is string => Boolean(ref)))];
-	return {
-		primaryRef,
-		...(candidateRefs[1] ? { mainFallbackRef: candidateRefs[1] } : {}),
-		candidateRefs,
-		...(!selectedAvailable && selectedRef ? { unavailableSelectedRef: selectedRef } : {}),
-	};
-}
-
-/** The exact levels Pi exposes for this model, including `off` when supported. */
-export function supportedThinkingLevels(model: Model<Api> | undefined): ThinkingLevel[] {
-	return model ? (getSupportedThinkingLevels(model) as ThinkingLevel[]) : [];
-}
-
-/** Clamp an agent preference to the effective model's actual capability map. */
-export function resolveThinkingLevel(
-	model: Model<Api> | undefined,
-	preferred: ThinkingLevel = DEFAULT_THINKING_LEVEL,
-): ThinkingLevel {
-	return model ? (clampThinkingLevel(model, preferred) as ThinkingLevel) : preferred;
-}
-
-function modelCapabilities(model: ModelListEntry): string {
-	const input = model.input.includes("image") ? "vision" : "text-only";
-	const thinking = getSupportedThinkingLevels(model as Model<Api>).join("/");
-	return `${input} · thinking: ${thinking}`;
-}
-
-/** Build one searchable list for agent model selection. Only models Pi
- * currently reports as available are supplied by setup. */
-export function buildModelPickerItems(options: {
-	models: readonly ModelListEntry[];
-	configuredRef?: string;
-	mainRef?: string;
-}): ModelPickerItem[] {
-	const configuredRef = cleanModelRef(options.configuredRef);
-	const mainRef = cleanModelRef(options.mainRef);
-	const byRef = new Map<string, ModelListEntry>();
-	for (const model of options.models) {
-		const ref = modelRef(model);
-		if (!byRef.has(ref)) byRef.set(ref, model);
-	}
-
-	const refs = [...byRef.keys()]
-		.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);
-		});
-
-	const dynamic: ModelPickerItem = {
-		value: CURRENT_MAIN_MODEL,
-		label: "Current main model (dynamic)",
-		description: "Clear agent override; use the current main model dynamically",
-	};
-	const items: ModelPickerItem[] = [dynamic];
-	for (const ref of refs) {
-		const model = byRef.get(ref)!;
-		const tags = [ref === configuredRef ? "configured" : "", ref === mainRef ? "current main" : ""]
-			.filter(Boolean);
-		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;
-}
-
-/** The dynamic choice removes the persisted per-agent override. */
-export function applyAgentModelChoice(
-	current: Record<string, string>,
-	agentName: string,
-	choice: string,
-): Record<string, string> {
-	const next = { ...current };
-	if (choice === CURRENT_MAIN_MODEL) delete next[agentName];
-	else next[agentName] = choice.trim();
-	return next;
-}
+/*
+ * Model routing, capability-aware thinking, and setup-picker helpers.
+ *
+ * Runtime has one explicit fallback only: a configured agent model hands
+ * off directly to the current main-window model. Setup lists only currently
+ * available models and derives thinking choices from Pi's model metadata.
+ */
+
+import {
+	clampThinkingLevel,
+	getSupportedThinkingLevels,
+	type Api,
+	type Model,
+} from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_THINKING_LEVEL, type ThinkingLevel } from "./config.ts";
+
+export type ModelContext = Pick<ExtensionContext, "model" | "modelRegistry"> &
+	Partial<Pick<ExtensionContext, "scopedModels">>;
+
+export const CURRENT_MAIN_MODEL = "__current_main_model__";
+
+export interface ModelPickerItem {
+	value: string;
+	label: string;
+	description?: string;
+}
+
+export type ModelListEntry = Pick<
+	Model<Api>,
+	"provider" | "id" | "name" | "input" | "reasoning" | "thinkingLevelMap"
+>;
+
+export interface ResolvedAgentModelRoute {
+	/** Effective first candidate. Undefined means let Pi use its normal default. */
+	primaryRef?: string;
+	/** Current main-window model when it differs from the selection. */
+	mainFallbackRef?: string;
+	/** Runtime order, useful for status/tests. */
+	candidateRefs: string[];
+	/** Configured ref skipped because Pi does not currently report it available. */
+	unavailableSelectedRef?: string;
+}
+
+export interface AgentModelRouteInput {
+	selectedRef?: string;
+	mainRef?: string;
+	declaredDefaultRef?: string;
+	/** When supplied, a configured selection outside this live set is skipped. */
+	availableRefs?: readonly 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;
+}
+
+/**
+ * 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 original Pi 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)));
+}
+
+export function findModelByRef(
+	models: readonly Model<Api>[],
+	ref: string | undefined,
+): Model<Api> | undefined {
+	const normalized = cleanModelRef(ref);
+	return normalized ? models.find((model) => modelRef(model) === normalized) : undefined;
+}
+
+/**
+ * Resolve one agent's runtime route:
+ *
+ * configured selection -> current main-window model
+ *
+ * Without an override, current main is primary; the agent-declared default is
+ * used only when no main model exists. A configured selection that Pi no longer
+ * reports as available is skipped immediately instead of spawning a doomed child.
+ */
+export function resolveAgentModelRoute(input: AgentModelRouteInput): ResolvedAgentModelRoute {
+	const selectedRef = cleanModelRef(input.selectedRef);
+	const mainRef = cleanModelRef(input.mainRef);
+	const declaredDefaultRef = cleanModelRef(input.declaredDefaultRef);
+	const available = input.availableRefs
+		? new Set(input.availableRefs.map((ref) => ref.trim()).filter(Boolean))
+		: undefined;
+	const selectedAvailable = !selectedRef || !available || available.has(selectedRef);
+	const usableSelectedRef = selectedAvailable ? selectedRef : undefined;
+	const primaryRef = usableSelectedRef ?? mainRef ?? declaredDefaultRef;
+	const ordered = [primaryRef, usableSelectedRef && usableSelectedRef !== mainRef ? mainRef : undefined];
+	const candidateRefs = [...new Set(ordered.filter((ref): ref is string => Boolean(ref)))];
+	return {
+		primaryRef,
+		...(candidateRefs[1] ? { mainFallbackRef: candidateRefs[1] } : {}),
+		candidateRefs,
+		...(!selectedAvailable && selectedRef ? { unavailableSelectedRef: selectedRef } : {}),
+	};
+}
+
+/** The exact levels Pi exposes for this model, including `off` when supported. */
+export function supportedThinkingLevels(model: Model<Api> | undefined): ThinkingLevel[] {
+	return model ? (getSupportedThinkingLevels(model) as ThinkingLevel[]) : [];
+}
+
+/** Clamp an agent preference to the effective model's actual capability map. */
+export function resolveThinkingLevel(
+	model: Model<Api> | undefined,
+	preferred: ThinkingLevel = DEFAULT_THINKING_LEVEL,
+): ThinkingLevel {
+	return model ? (clampThinkingLevel(model, preferred) as ThinkingLevel) : preferred;
+}
+
+function modelCapabilities(model: ModelListEntry): string {
+	const input = model.input.includes("image") ? "vision" : "text-only";
+	const thinking = getSupportedThinkingLevels(model as Model<Api>).join("/");
+	return `${input} · thinking: ${thinking}`;
+}
+
+/** Build one searchable list for agent model selection. Only models Pi
+ * currently reports as available are supplied by setup. */
+export function buildModelPickerItems(options: {
+	models: readonly ModelListEntry[];
+	configuredRef?: string;
+	mainRef?: string;
+}): ModelPickerItem[] {
+	const configuredRef = cleanModelRef(options.configuredRef);
+	const mainRef = cleanModelRef(options.mainRef);
+	const byRef = new Map<string, ModelListEntry>();
+	for (const model of options.models) {
+		const ref = modelRef(model);
+		if (!byRef.has(ref)) byRef.set(ref, model);
+	}
+
+	const refs = [...byRef.keys()]
+		.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);
+		});
+
+	const dynamic: ModelPickerItem = {
+		value: CURRENT_MAIN_MODEL,
+		label: "Current main model (dynamic)",
+		description: "Clear agent override; use the current main model dynamically",
+	};
+	const items: ModelPickerItem[] = [dynamic];
+	for (const ref of refs) {
+		const model = byRef.get(ref)!;
+		const tags = [ref === configuredRef ? "configured" : "", ref === mainRef ? "current main" : ""]
+			.filter(Boolean);
+		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;
+}
+
+/** The dynamic choice removes the persisted per-agent override. */
+export function applyAgentModelChoice(
+	current: Record<string, string>,
+	agentName: string,
+	choice: string,
+): Record<string, string> {
+	const next = { ...current };
+	if (choice === CURRENT_MAIN_MODEL) delete next[agentName];
+	else next[agentName] = choice.trim();
+	return next;
+}

package/src/monitor.ts

@@ -49,15 +49,15 @@ export interface RunView {
 	startedAt?: number;
 	/** Epoch ms when the run finished (set on "done"/"failed"). */
 	endedAt?: number;
-	/** When set, this run belongs to an auto-fix chain (e.g. worker fixing a reviewer's findings). */
+	/** When set, this is an internal managed-workflow step. */
 	groupId?: string;
 	/** Human-readable role within a chain, e.g. "fix round 1" or "re-review round 1". */
 	relationLabel?: string;
-	/** Owning run for chain children: the triggering reviewer whose row represents the chain. */
+	/** Stable owning run whose row represents the whole managed workflow. */
 	parentRunId?: number;
 }
 
-/** Optional chain metadata for runs spawned by an auto-fix loop. */
+/** Optional metadata for documenter/reviewer/fix children of a stable parent run. */
 export interface RunChainMeta {
 	groupId?: string;
 	relationLabel?: string;
@@ -503,6 +503,15 @@ export class MonitorStore {
 		this.notify();
 	}
 
+	/** Reflect the currently owned internal stage when a managed parent is parked
+	 * or inspected between children; the stable id and original task stay intact. */
+	setAgent(id: number, agent: string): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.agent = agent;
+		this.notify();
+	}
+
 	/** Update the objective shown for a queued retarget or resumed generation. */
 	setTask(id: number, task: string): void {
 		const run = this.find(id);

package/src/prompt.ts

@@ -11,22 +11,42 @@ function bullets(lines: readonly string[]): string {
 	return lines.map((line) => `- ${line}`).join("\n");
 }
 
-export function buildDelegationDirective(agents: AgentConfig[]): string {
+export function buildDelegationDirective(
+	agents: AgentConfig[],
+	options: { maxFixRounds?: number } = {},
+): string {
 	if (agents.length === 0) return "";
 
 	const catalog = agents.map(formatCatalogEntry).join("\n");
 	const hasExplorer = agents.some((agent) => agent.name === "explorer");
 	const hasWorker = agents.some((agent) => agent.name === "worker");
 	const hasCleaner = agents.some((agent) => agent.name === "cleaner");
+	const hasDocumenter = agents.some((agent) => agent.name === "documenter");
 	const hasReviewer = agents.some((agent) => agent.name === "reviewer");
 	const hasMultiple = agents.length > 1;
-	const worktreeTargets = hasWorker && hasCleaner
-		? "worker, cleaner, or another"
-		: hasWorker
-			? "worker or another"
-			: hasCleaner
-				? "cleaner or another"
-				: "a";
+	const autoFixEnabled = hasWorker && (options.maxFixRounds ?? 1) > 0;
+	const codeWriterNames = [
+		...(hasWorker ? ["worker"] : []),
+		...(hasCleaner ? ["cleaner"] : []),
+	];
+	const reviewedWriterNames = [
+		...codeWriterNames,
+		...(hasDocumenter ? ["documenter"] : []),
+	];
+	const automaticWriterRoute = [
+		...(hasDocumenter ? ["documenter"] : []),
+		...(hasReviewer ? ["reviewer"] : []),
+	].join(" → ");
+	const namedWorktreeTargets = [
+		...(hasWorker ? ["worker"] : []),
+		...(hasCleaner ? ["cleaner"] : []),
+		...(hasDocumenter ? ["documenter"] : []),
+	];
+	const worktreeTargets = namedWorktreeTargets.length === 0
+		? "a"
+		: namedWorktreeTargets.length === 1
+			? `${namedWorktreeTargets[0]} or another`
+			: `${namedWorktreeTargets.slice(0, -1).join(", ")}, ${namedWorktreeTargets.at(-1)}, or another`;
 
 	const dispatchRules = [
 		"Handle simple work inline with direct tools: one-line lookups, known-target reads/edits, and quick questions do not justify a child process.",
@@ -40,12 +60,17 @@ export function buildDelegationDirective(agents: AgentConfig[]): string {
 			: []),
 		...(hasCleaner
 			? [
-				`Use \`cleaner\` only when the user explicitly authorizes cleanup/removal/simplification edits, including a requested maintenance pass. It gathers evidence, then applies every safe proven in-scope cut; zero edits is valid. Generic or read-only audit, inspect, report, review, code-health, plan, proposed-solution, or cleanup-candidate assessment goes to ${hasReviewer ? "`reviewer`" : "direct main-context inspection because `reviewer` is disabled"}. Never dispatch cleaner by PR count or as the pre-commit gate.`,
+				`Use \`cleaner\` only for user-authorized cleanup, removal, simplification, duplicate-code consolidation, or maintenance. Once dispatched, it applies every safe proven in-scope cut without item-by-item approval; zero edits is valid only if none is proved. Generic or read-only audit, review, code-health, plan, or cleanup-candidate assessment goes to ${hasReviewer ? "`reviewer`" : "direct main-context inspection because `reviewer` is disabled"}. Never dispatch cleaner by PR count or as the pre-commit gate.`,
+			]
+			: []),
+		...(hasDocumenter
+			? [
+				`Use \`documenter\` directly for explicit whole-codebase maintenance or standalone documentation work.${codeWriterNames.length > 0 ? ` Successful ${codeWriterNames.join("/")} runs already auto-sync the actual diff; never dispatch a duplicate.` : ""} Zero edits is valid and broad mode is never inferred. It changes docs/comments only and never runtime behavior, versions, release state, or ${hasReviewer ? "the final reviewer gate" : "direct final verification"}.`,
 			]
 			: []),
 		...(hasReviewer
 			? [
-				`Use \`reviewer\` for generic/read-only assessments and as the fresh independent pre-commit gate for non-trivial diffs${hasCleaner ? ", including cleaner edits" : ""}. Advisory findings do not authorize follow-up edits; only gate verdicts can enter auto-fix.`,
+				`Use \`reviewer\` for read-only assessments or an explicit gate.${reviewedWriterNames.length > 0 ? ` Successful ${reviewedWriterNames.join("/")} runs already get a fresh read-only reviewer gate.` : ""} Advisory output has no VERDICT: it stays read-only and does not authorize follow-up edits.`,
 			]
 			: []),
 		"Brief every child with the complete goal, exact paths, constraints, and expected output. It has no memory of this conversation.",
@@ -55,7 +80,7 @@ export function buildDelegationDirective(agents: AgentConfig[]): string {
 				"Dispatch independent work in one `tasks` array and let the resumed main agent start dependent work only after prerequisites finish.",
 			]
 			: []),
-		`Filesystem isolation: single tasks default to shared${hasWorker ? "; parallel worker tasks default to detached Git worktrees" : ""}${hasCleaner ? "; cleaner defaults to shared" : ""}. Request \`isolation: "worktree"\` only for ${worktreeTargets} write-capable agent in a Git repository with committed HEAD. Read-only agents reject it, and setup/integration failure never falls back silently to shared.`,
+		`Filesystem isolation: single tasks default to shared${hasWorker ? "; parallel worker tasks default to detached Git worktrees" : ""}${hasCleaner ? "; cleaner defaults to shared" : ""}${hasDocumenter ? "; documenter defaults to shared" : ""}. Request \`isolation: "worktree"\` only for ${worktreeTargets} write-capable agent in a Git repository with committed HEAD. Read-only agents reject it, and setup/integration failure never falls back silently to shared.`,
 		"A configured child model/provider failure automatically continues the same retained session on the current main model; do not redispatch. Ordinary tool/task failures stay on the selected model.",
 		"Trust but verify: inspect actual changes/results before reporting completion.",
 	];
@@ -69,9 +94,19 @@ export function buildDelegationDirective(agents: AgentConfig[]): string {
 
 	const verificationRules = [
 		"Never report an unrun check as passed; identify unavailable checks and pre-existing failures honestly.",
+		...(automaticWriterRoute && reviewedWriterNames.length > 0
+			? [
+				`Successful top-level write roles automatically continue through enabled downstream roles (${automaticWriterRoute}) to one final delivery; never duplicate stages.`,
+			]
+			: []),
 		...(hasReviewer
 			? [
-				"Send every non-trivial diff through one fresh read-only `reviewer` gate before reporting done. Resolve every finding; do not bypass the configured auto-fix/re-review cap.",
+				...(hasDocumenter
+					? [
+						`A direct REVIEW_PASS is preliminary: runtime runs documenter on the pending diff, then a fresh reviewer. A direct REVIEW_FAIL ${autoFixEnabled ? "keeps auto-fix; maxFixRounds limits worker fixes only, not initial docs/review." : "cannot start fixes while worker/fix rounds are disabled."}`,
+					]
+					: []),
+				"Resolve every gate finding; do not bypass the configured auto-fix/re-review cap. A reviewer report without a standalone VERDICT is advisory and cannot trigger writes.",
 				"Use multi-model cross-review only when explicitly requested or for genuinely high-risk security, unsafe/FFI, persistence-migration, or concurrency changes.",
 			]
 			: []),