pi-herdr-agents 3.0.2 → 3.1.0

package/pi-extension/subagents/index.ts

@@ -1,6 +1,7 @@
 import type {
 	AgentToolResult,
 	ExtensionAPI,
+	ExtensionCommandContext,
 	ExtensionContext,
 	SessionShutdownEvent,
 } from "@earendil-works/pi-coding-agent";
@@ -19,8 +20,9 @@ import { randomUUID } from "node:crypto";
 import type { RunCancellation, Task } from "../../maestro/core/types.ts";
 import {
 	createDefaultRunSession,
-	initializeTaskModels,
+	startTaskModelInit,
 	observePiActivity,
+	type TaskModelInitOutcome,
 	type PiRunSession,
 	type PiRunSessionInfrastructure,
 	type PiRunRecord,
@@ -60,9 +62,17 @@ import { wrapPiModelRegistry } from "./model-registry.ts";
 import {
 	loadModelConfig,
 	MISSING_CONFIG_REVISION,
+	parseRankingBasis,
+	readModelConfigSnapshot,
 	resolveModelDefault,
 	writeTaskModelConfig,
 } from "../../maestro/core/config/model-config.ts";
+import {
+	type OfferCallback,
+	type TaskModelBrief,
+	TASK_MODEL_INIT_APPROVAL_EVENT,
+	TASK_MODEL_INIT_START_EVENT,
+} from "../../maestro/core/config/task-model-init.ts";
 import {
 	TASK_CATEGORIES,
 	TASK_CATEGORY_DESCRIPTIONS,
@@ -98,6 +108,7 @@ import { isSubagentActivityScope } from "../../maestro/core/activity.ts";
 import type { SubagentActivityState } from "../../maestro/core/types.ts";
 import {
 	isFiniteNumber,
+	isFunction,
 	isPlainObject,
 	isString,
 } from "../../maestro/core/config/type-guards.ts";
@@ -344,6 +355,47 @@ function discoverAgentDefinitions(
 	return discoverAgentCatalog(pi).agents;
 }
 
+/**
+ * Payload of TASK_MODEL_INIT_APPROVAL_EVENT. `context` is the live context of
+ * the command that started init. It passes between trusted in-process
+ * extensions and is current only while the request is emitted.
+ */
+interface TaskModelApprovalRequest {
+	apiVersion: 1;
+	brief: TaskModelBrief;
+	context: ExtensionCommandContext;
+	offer: OfferCallback;
+}
+
+function hasMethods(value: any, names: readonly string[]): boolean {
+	return value != null && names.every((name) => isFunction(value[name]));
+}
+
+/**
+ * Read a TASK_MODEL_INIT_START_EVENT v1 payload. A v1 request whose context or
+ * preferences cannot run init still gets an offer, so its emitter reports why
+ * instead of concluding that no host is loaded.
+ */
+function parseInitStartRequest(raw: any):
+	| {
+			offer: OfferCallback;
+			input?: { context: ExtensionCommandContext; preferences: string };
+	  }
+	| undefined {
+	if (raw?.apiVersion !== 1 || !isFunction(raw.offer)) return undefined;
+	const { offer, context, preferences } = raw;
+	const usable =
+		isString(preferences) &&
+		hasMethods(context, ["isIdle", "hasPendingMessages"]) &&
+		hasMethods(context.modelRegistry, ["getAvailable"]);
+	return {
+		offer: (value) => offer.call(raw, value),
+		// The members init reads were checked above; the rest is the emitting
+		// command's own live context.
+		input: usable ? { context, preferences } : undefined,
+	};
+}
+
 function missingRoleMessage(agentName: string): string {
 	return `Agent "${agentName}" was not found. pi-herdr-agents ships no roles: define it in .pi/agents or the global agents directory, install a role pack that provides it, or omit agent for a bare launch.`;
 }
@@ -684,6 +736,16 @@ function formatWorktreeHandoff(worktree: WorktreeHandoff): string {
 	return lines.join("\n");
 }
 
+function launchDiagnosticsText(
+	diagnostics: readonly string[] | undefined,
+	prefix: string,
+	suffix: string,
+): string {
+	return diagnostics?.length
+		? `${prefix}Launch diagnostics: ${diagnostics.join("; ")}.${suffix}`
+		: "";
+}
+
 function resolveResultPresentation(
 	result: Pick<
 		SubagentResult,
@@ -2606,7 +2668,7 @@ export default function subagentsExtension(
 		pi.registerTool({
 			name: "subagents_write_task_models",
 			label: "Write task model preferences",
-			description: `Validate and atomically replace models.tasks and models.tasksMeta in the durable Pi agent config, preserving unrelated settings. Supported categories: ${TASK_CATEGORIES.join(", ")}. Partial nonempty categories are accepted; omitted categories are removed. Rejects duplicate exact refs within a category. Review the active authenticated registry and existing preferences first. Optional expectedConfigRevision makes the write conditional: it fails without replacing configuration when the config file no longer matches the revision the proposal was read from. Cooperating writes are serialized and fail on contention rather than waiting. Returns normalized saved preferences, missing categories, and the configRevision of the written file; reload required.`,
+			description: `Validate and atomically replace models.tasks and models.tasksMeta in the durable Pi agent config, preserving unrelated settings. Supported categories: ${TASK_CATEGORIES.join(", ")}. Partial nonempty categories are accepted; omitted categories are removed. Rejects duplicate exact refs within a category. Review the active authenticated registry and existing preferences first. Optional expectedConfigRevision makes the write conditional: it fails without replacing configuration when the config file no longer matches the revision the proposal was read from. Optional basis records what the ranking rests on; its kind must equal tasksMeta.method, and it is returned but not saved. Cooperating writes are serialized and fail on contention rather than waiting. Returns normalized saved preferences, missing categories, the configRevision of the written file, and any basis; reload required.`,
 			parameters: Type.Object({
 				tasks: Type.Object(
 					Object.fromEntries(
@@ -2640,6 +2702,37 @@ export default function subagentsExtension(
 						},
 					),
 				),
+				basis: Type.Optional(
+					Type.Union(
+						[
+							Type.Object(
+								{ kind: Type.Literal("registry-only") },
+								{ additionalProperties: false },
+							),
+							Type.Object(
+								{
+									kind: Type.Literal("research"),
+									sources: Type.Array(
+										Type.Object(
+											{
+												url: Type.String({ minLength: 1 }),
+												influence: Type.String({ minLength: 1 }),
+											},
+											{ additionalProperties: false },
+										),
+										{ minItems: 1 },
+									),
+									uncertainty: Type.String({ minLength: 1 }),
+								},
+								{ additionalProperties: false },
+							),
+						],
+						{
+							description:
+								'What the ranking rests on, as submitted by the proposer and not independently verified: {"kind":"registry-only"}, or {"kind":"research"} with the http(s) sources consulted in this run, how each informed the ranking, and the remaining uncertainty. kind must equal tasksMeta.method. Not saved. Omit for a legacy write.',
+						},
+					),
+				),
 			}),
 			execute: async (_id, params, _signal, _update, ctx) => {
 				const registry = wrapPiModelRegistry(ctx.modelRegistry);
@@ -2647,6 +2740,10 @@ export default function subagentsExtension(
 				const tasks = params.tasks as TaskPreferences;
 				// SAFETY: TypeBox validates the tool payload; the write seam performs stricter schema validation.
 				const tasksMeta = params.tasksMeta as TaskPreferencesMeta;
+				// Present-but-invalid values (including null) fail before anything is written.
+				const basis = Object.hasOwn(params, "basis")
+					? parseRankingBasis(params.basis, tasksMeta.method)
+					: undefined;
 				const saved = writeTaskModelConfig(
 					getSubagentsConfigPath(),
 					getSubagentsConfigExamplePath(),
@@ -2663,14 +2760,15 @@ export default function subagentsExtension(
 						? { expectedConfigRevision: params.expectedConfigRevision }
 						: {},
 				);
+				const details = basis ? { ...saved, basis } : saved;
 				return {
 					content: [
 						{
 							type: "text",
-							text: `Wrote task model preferences. Reload required.\n${JSON.stringify(saved, null, 2)}`,
+							text: `Wrote task model preferences. Reload required.\n${JSON.stringify(details, null, 2)}`,
 						},
 					],
-					details: saved,
+					details,
 				};
 			},
 		});
@@ -2833,6 +2931,7 @@ export default function subagentsExtension(
 								(running.worktree
 									? ` in worktree ${running.worktree.path} on branch ${running.worktree.branch}. `
 									: ". ") +
+								launchDiagnosticsText(running.worktree?.diagnostics, "", " ") +
 								`Do NOT generate or assume any results — you have no idea what the sub-agent will do or produce. ` +
 								`The results will be delivered to you automatically as a steer message when the sub-agent finishes. ` +
 								`Until then, move on to other work or tell the user you're waiting.`,
@@ -3316,21 +3415,73 @@ export default function subagentsExtension(
 			},
 		});
 
-	if (!process.env.PI_SUBAGENT_ID)
+	if (!process.env.PI_SUBAGENT_ID) {
+		const runTaskModelInit = (
+			ctx: ExtensionCommandContext,
+			preferences: string,
+		): TaskModelInitOutcome => {
+			if (!ctx.isIdle() || ctx.hasPendingMessages())
+				return {
+					kind: "not-started",
+					reason:
+						"a turn is in progress or messages are queued. Nothing was queued; retry when idle",
+				};
+			// Pi refuses a prompt without a model only after submission; refuse first.
+			if (!ctx.model)
+				return {
+					kind: "not-started",
+					reason:
+						"no model is selected, so Pi cannot run the init prompt. Select a model, then retry",
+				};
+			return startTaskModelInit({
+				preferences,
+				readConfig: () => readModelConfigSnapshot(getSubagentsConfigDir()),
+				projectActiveRegistry: (project) => project(ctx.modelRegistry),
+				emitApprovalRequest: (brief, offer) =>
+					pi.events.emit(
+						TASK_MODEL_INIT_APPROVAL_EVENT,
+						Object.freeze({
+							apiVersion: 1,
+							brief,
+							context: ctx,
+							offer,
+						} satisfies TaskModelApprovalRequest),
+					),
+				isToolActive: (name) => pi.getActiveTools().includes(name),
+				submit: (prompt) => pi.sendUserMessage(prompt),
+			});
+		};
 		pi.registerCommand("subagents-init", {
 			description:
 				"Draft task-category model preferences from the live registry; optional arguments set ranking preferences",
 			handler: async (args, ctx) => {
-				const registry = ctx.modelRegistry;
-				const current = loadModelConfig(getSubagentsConfigDir());
-				const prompt = initializeTaskModels({
-					projectActiveRegistry: (project) => project(registry),
-					current,
-					preferences: args,
-				});
-				pi.sendUserMessage(prompt);
+				const outcome = runTaskModelInit(ctx, args);
+				if (outcome.kind === "not-started")
+					ctx.ui.notify(
+						`Task-model init not started: ${outcome.reason}. Nothing was written.`,
+						"warning",
+					);
 			},
 		});
+		// Another extension's command may start the same init; it renders the outcome.
+		const stopInitStart = pi.events.on(TASK_MODEL_INIT_START_EVENT, (raw) => {
+			const request = parseInitStartRequest(raw);
+			if (!request) return;
+			const { input } = request;
+			request.offer({
+				owner: "pi-herdr-agents",
+				start: (): TaskModelInitOutcome =>
+					input
+						? runTaskModelInit(input.context, input.preferences)
+						: {
+								kind: "not-started",
+								reason:
+									"the start request lacks a usable command context or preferences text",
+							},
+			});
+		});
+		pi.on("session_shutdown", () => stopInitStart());
+	}
 
 	pi.registerCommand("worktree", {
 		description: parentSession
@@ -3462,10 +3613,13 @@ export default function subagentsExtension(
 					throw new Error("Worktree handoff did not return worktree metadata");
 				}
 				ctx.ui.notify(
-					result.focusError
+					(result.focusError
 						? `Worktree launched, but workspace focus failed: ${result.focusError}\nWorktree: ${worktree.path}`
-						: `Worktree launched in ${worktree.path} (workspace ${worktree.workspaceId}).`,
-					result.focusError ? "warning" : "info",
+						: `Worktree launched in ${worktree.path} (workspace ${worktree.workspaceId}).`) +
+						launchDiagnosticsText(worktree.diagnostics, "\n", ""),
+					result.focusError || worktree.diagnostics?.length
+						? "warning"
+						: "info",
 				);
 			} catch (error) {
 				ctx.ui.notify(

package/skills/pi-herdr-agents/SKILL.md

@@ -210,7 +210,12 @@ independent writer.
   blockers. Startup does not scan it.
 - `worktree_remove({ target, preserve? })` / `/worktree remove <target>
   [--preserve]` is explicit, parent-only, and needs separate authorization;
-  stopping or interrupting a child never authorizes cleanup. Dirty work is
+  stopping or interrupting a child never authorizes cleanup. Removal never
+  closes the source repository's primary workspace. If this process's create
+  appears to have opened that workspace and it still looks untouched, the
+  result suggests `herdr workspace close <id>` if you haven't used it. Another
+  session or a restarted process says nothing about it. Primary-workspace
+  snapshot failures at launch appear as launch diagnostics. Dirty work is
   blocked unless committed first or `preserve: true` makes a WIP commit (SHA
   reported). Eligibility is rechecked at removal and fails closed (unknown
   state, live holder, untracked files, conflicts, detached HEAD, locks,
@@ -240,12 +245,19 @@ changes. Without a real file, only non-model settings fall back to the example.
 | `roles.bundled` | Deprecated no-op; remove it |
 
 Model values must be exact authenticated IDs. `/subagents-init [preferences]`
-drafts task preferences from the live model registry and saves them through
-`subagents_write_task_models` (parent-only; validates, atomically replaces
-`models.tasks` and `tasksMeta`, preserves other settings). Payload: `tasks`
+drafts task preferences from the live model registry and the saved config's
+`configRevision`, then saves them through `subagents_write_task_models`
+(parent-only; validates, atomically replaces `models.tasks` and `tasksMeta`,
+preserves other settings). When one loaded extension offers to approve the
+write, the init prompt names that extension's tool instead; follow the prompt
+and do not call the writer around it. Payload: `tasks`
 (partial but nonempty categories; empty `tasks: {}` and duplicate refs within a
 category are rejected) and required `tasksMeta`. Warning: categories you omit
 are removed from the saved config, so send every category you want to keep.
+Optional `basis` states what the ranking rests on and is not saved: use
+`{"kind":"registry-only"}` unless sources consulted in this run informed it,
+then `{"kind":"research","sources":[{"url":"https://...","influence":"how it changed the ranking"}],"uncertainty":"what remains unknown"}`.
+Its kind must equal `tasksMeta.method`.
 Optional `expectedConfigRevision` (`sha256:` plus 64 lowercase hex digits of the exact file bytes,
 or `missing`) makes the write conditional; a stale revision fails with
 `Stale task model config revision`: re-read, re-propose, re-approve, do not