pi-herdr-agents 3.0.3 → 3.2.0

package/maestro/runtime/pi-run-session.ts

@@ -66,6 +66,12 @@ import {
 	type ModelRegistryAdapter,
 } from "../core/routing.ts";
 import { loadPaneConfig, type PaneConfig } from "../core/config/pane-config.ts";
+import {
+	DelegatedMarkers,
+	herdrMarkerWriter,
+	type DelegatedMarker,
+	type MarkerWriter,
+} from "./delegated-marker.ts";
 import {
 	createRunSession,
 	type RunSession,
@@ -327,6 +333,8 @@ export interface PiRunSessionInfrastructure {
 	supervision: SupervisionCoordinator;
 	/** Kernel process-identity probe for worktree cancel; tests inject it. */
 	processProbe?: ProcessIdentityProbe;
+	/** Sidebar marker transport; defaults to this pane's Herdr socket. */
+	markerWriter?: MarkerWriter;
 }
 // pi-herdr-agents extension
 export interface DefaultRunSessionOptions {
@@ -340,6 +348,8 @@ export interface DefaultRunSessionOptions {
 	hooks: PiRunSessionHooks;
 	persistent: PiPersistentHostOperations;
 	forcePolling: boolean;
+	/** Mark delegated children's panes for the Herdr sidebar plugin. */
+	sidebarMarkers?: boolean;
 }
 // pi-herdr-agents extension
 export interface PiWorktreeHandoffInput {
@@ -395,6 +405,7 @@ interface PiEntry {
 	started: PiStartedMetadata;
 	completed?: PiCompletedMetadata;
 	readResumeResult?: PiSettlementIO["readResumeResult"];
+	marker?: DelegatedMarker;
 }
 // The previous facade carries its live composition explicitly across module replacement.
 // No module-local lookup can accidentally rediscover an owner.
@@ -413,6 +424,8 @@ interface PiSessionOwner {
 		"surfaceProvider" | "supervision" | "processProbe"
 	>;
 	worktreeOperations: WorktreeOperations;
+	/** Absent outside Herdr: without a socket nothing can be marked. */
+	markers?: DelegatedMarkers;
 }
 
 // A detached close can outlive settlement without capturing a child, metadata,
@@ -426,6 +439,21 @@ function temporarySurfaceRelease(
 	};
 }
 
+function createDelegatedMarkers(
+	infrastructure: PiRunSessionInfrastructure | undefined,
+	probe: ProcessIdentityProbe | undefined,
+): DelegatedMarkers | undefined {
+	// Injected infrastructure never falls back to the ambient Herdr socket.
+	if (infrastructure) {
+		const write = infrastructure.markerWriter;
+		return write ? new DelegatedMarkers({ write, probe }) : undefined;
+	}
+	const socketPath = process.env.HERDR_SOCKET_PATH;
+	return socketPath
+		? new DelegatedMarkers({ write: herdrMarkerWriter(socketPath), probe })
+		: undefined;
+}
+
 // Capture only resume presentation scalars, not the child or its owning registry.
 function resumeResultReader(
 	sessionFile: string,
@@ -682,6 +710,20 @@ export function createDefaultRunSession(
 	// Replacements must invoke the original kernel's invocation closure, which
 	// reads this shared current binding, not the old facade's options.
 	if (adopted) resumePi = state.resumePi;
+	// Live markers and their sequence survive a reload with their runs.
+	state.markers ??= createDelegatedMarkers(
+		options.infrastructure,
+		state.infrastructure.processProbe,
+	);
+	// Turning the setting off retires every marker now, pending ones included;
+	// a retired marker never writes live again, even if the setting returns.
+	if (!options.sidebarMarkers)
+		for (const entry of state.entries.values()) entry.marker?.retire();
+
+	/** Markers for new launches, only while the sidebar setting is on. */
+	function enabledMarkers(): DelegatedMarkers | undefined {
+		return state.options.sidebarMarkers ? state.markers : undefined;
+	}
 
 	function prune(id: string) {
 		if (!state.kernel.getTask(id)) state.entries.delete(id);
@@ -712,11 +754,11 @@ export function createDefaultRunSession(
 		};
 	}
 	function observed(child: PiRunRecord, observation: RunObservation) {
-		if (
-			child.lifecycle.delivery === "suppressed" ||
-			![...state.entries.values()].some((entry) => entry.record === child)
-		)
-			return;
+		const entry = [...state.entries.values()].find(
+			(candidate) => candidate.record === child,
+		);
+		if (child.lifecycle.delivery === "suppressed" || !entry) return;
+		entry.marker?.renew();
 		if (observation.kind === "local-evidence" && child.persistent) {
 			try {
 				state.options.persistent.drain(child, io);
@@ -745,6 +787,7 @@ export function createDefaultRunSession(
 			parentRuntime: snapshot.parentRuntime,
 			supervision: state.infrastructure.supervision,
 			processProbe: state.infrastructure.processProbe,
+			recordProcessIdentity: enabledMarkers() !== undefined,
 			operations: launchOperations(snapshot),
 			onObservation(child, kind) {
 				const at = Date.now();
@@ -794,7 +837,10 @@ export function createDefaultRunSession(
 		};
 		if (suppressed)
 			child.lifecycle = markDelivery(child.lifecycle, "suppressed");
-		else state.entries.set(task.id, entry);
+		else {
+			entry.marker = enabledMarkers()?.attach(child);
+			state.entries.set(task.id, entry);
+		}
 		return {
 			handle,
 			adapter: owner,
@@ -805,6 +851,8 @@ export function createDefaultRunSession(
 			),
 			observe: (at) => hydrate(child, at, "refresh"),
 			finalize: async (result) => {
+				// Clear before delivery; a retained worktree root keeps its pane.
+				entry.marker?.retire();
 				const at = Date.now();
 				let evidence = result.evidence;
 				if (evidence)
@@ -1153,8 +1201,11 @@ export function createDefaultRunSession(
 		suppress(id) {
 			for (const acquisition of state.pending)
 				if (acquisition.taskId === id) acquisition.suppressed = true;
-			const r = live(id)?.record;
+			const suppressed = live(id);
+			const r = suppressed?.record;
 			if (r) r.lifecycle = markDelivery(r.lifecycle, "suppressed");
+			// Nothing renews an unsupervised run's marker; clear it now.
+			suppressed?.marker?.retire();
 			state.kernel.suppress(id);
 			state.entries.delete(id);
 		},

package/maestro/runtime/task-model-init.ts

@@ -1,22 +1,119 @@
 import {
 	buildTaskModelBrief,
 	buildTaskModelInitPrompt,
+	collectApprovalOffers,
+	DIRECT_WRITER_DESTINATION,
+	type NonEmpty,
+	type OfferCallback,
+	openApprovalOffer,
+	selectApprovalRoute,
+	type TaskModelBrief,
+	type TaskModelFacts,
+	type TaskModelInitDestination,
 	type TaskModelRegistryProjector,
 	type TaskModelRegistrySnapshot,
 } from "../core/config/task-model-init.ts";
-import type { ModelConfig } from "../core/config/model-config.ts";
+import type { ModelConfigSnapshot } from "../core/config/model-config.ts";
 import { projectTaskModelRegistry } from "../adapters/pi/task-model-init.ts";
 
-/** Compose the active Pi projection with current saved choices and the complete init prompt. */
-export function initializeTaskModels(input: {
+/** What one init request did. Only `started` submitted a prompt. */
+export type TaskModelInitOutcome =
+	| { kind: "started"; destination: string }
+	| { kind: "not-started"; reason: string };
+
+export interface TaskModelInitInput {
+	preferences: string;
+	/** Saved settings and the revision of the same bytes; throws when invalid. */
+	readConfig(): ModelConfigSnapshot;
 	/** The host supplies its actual active registry to this projector exactly once. */
 	projectActiveRegistry(
 		project: TaskModelRegistryProjector,
 	): TaskModelRegistrySnapshot;
-	current: ModelConfig;
-	preferences: string;
-}): string {
-	const snapshot = input.projectActiveRegistry(projectTaskModelRegistry);
-	const brief = buildTaskModelBrief(snapshot, input.current, input.preferences);
-	return buildTaskModelInitPrompt(brief);
+	/** Emits the approval request for this brief and returns when listeners did. */
+	emitApprovalRequest(brief: TaskModelBrief, offer: OfferCallback): void;
+	isToolActive(name: string): boolean;
+	/** Hands the prompt to Pi; a throw means Pi did not take it. */
+	submit(prompt: string): void;
+}
+
+/** Listeners share the brief; freezing it keeps the prompt equal to what they saw. */
+function deepFreeze<T>(value: T): T {
+	if (value == null || Object(value) !== value) return value;
+	// SAFETY: Object(value) === value holds only for objects and functions.
+	for (const item of Object.values(value as object)) deepFreeze(item);
+	return Object.freeze(value);
+}
+
+function isNonEmpty<T>(values: T[]): values is NonEmpty<T> {
+	return values.length > 0;
+}
+
+/**
+ * Capture one brief, pick where its proposal goes, and submit the prompt. It
+ * runs synchronously, so nothing can change between selection and submission.
+ * An opened offer that is not submitted is cancelled before this returns.
+ */
+export function startTaskModelInit(
+	input: TaskModelInitInput,
+): TaskModelInitOutcome {
+	const notStarted = (reason: string): TaskModelInitOutcome => ({
+		kind: "not-started",
+		reason,
+	});
+	let snapshot: ModelConfigSnapshot;
+	try {
+		snapshot = input.readConfig();
+	} catch (error) {
+		return notStarted(error instanceof Error ? error.message : String(error));
+	}
+	const { models } = input.projectActiveRegistry(projectTaskModelRegistry);
+	if (!isNonEmpty<TaskModelFacts>(models))
+		return notStarted(
+			"the active registry has no authenticated models, so there is nothing to rank. Configure a provider, then run /subagents-init again",
+		);
+	const brief = deepFreeze(
+		buildTaskModelBrief({
+			models,
+			current: snapshot.config,
+			configRevision: snapshot.revision,
+			preferences: input.preferences,
+		}),
+	);
+	const route = selectApprovalRoute(
+		collectApprovalOffers((offer) => input.emitApprovalRequest(brief, offer)),
+	);
+	let destination: TaskModelInitDestination;
+	let cancel: () => string | undefined = () => undefined;
+	switch (route.kind) {
+		case "direct":
+			destination = DIRECT_WRITER_DESTINATION;
+			break;
+		case "refused":
+			return notStarted(route.reason);
+		case "offer": {
+			const opened = openApprovalOffer(route.offer);
+			if (opened.kind === "blocked") return notStarted(opened.reason);
+			destination = opened.destination;
+			cancel = opened.cancel;
+			break;
+		}
+		default: {
+			const _exhaustive: never = route;
+			return _exhaustive;
+		}
+	}
+	const cancelled = (reason: string): TaskModelInitOutcome => {
+		const problem = cancel();
+		return notStarted(problem ? `${reason}; ${problem}` : reason);
+	};
+	if (!input.isToolActive(destination.toolName))
+		return cancelled(`${destination.toolName} is not an active tool`);
+	try {
+		input.submit(buildTaskModelInitPrompt(brief, destination));
+	} catch (error) {
+		return cancelled(
+			`Pi did not accept the init prompt (${error instanceof Error ? error.message : String(error)})`,
+		);
+	}
+	return { kind: "started", destination: destination.toolName };
 }

package/maestro/surfaces/herdr/herdr-socket.ts

@@ -0,0 +1,165 @@
+import { connect } from "node:net";
+import {
+	isNonEmptyString,
+	isRecord,
+	isString,
+	type JsonObject,
+} from "../../core/config/type-guards.ts";
+
+export const HERDR_SOCKET_TIMEOUT_MS = 2_000;
+export const HERDR_SOCKET_MAX_REPLY_BYTES = 64 * 1024;
+const MAX_REPORTED_CHARS = 200;
+
+export type HerdrSocketReply =
+	| { kind: "result"; result: JsonObject }
+	/** Herdr answered with an error object. */
+	| { kind: "error"; code: string; message: string }
+	/** No usable answer: refused, closed, timed out, oversized, malformed, or another id. */
+	| { kind: "failed"; reason: string };
+
+function bounded(text: string): string {
+	return text.replace(/\p{Cc}+/gu, " ").slice(0, MAX_REPORTED_CHARS);
+}
+
+let requestCount = 0;
+
+/**
+ * One request on one connection: Herdr closes ordinary connections after a
+ * reply. Settles once with the first newline-terminated reply, or fails on a
+ * timeout, an oversized reply, or a connection that ends first. The socket
+ * and timer are unreferenced, so a pending request never keeps Pi running.
+ */
+export function requestHerdrSocket(
+	socketPath: string,
+	method: string,
+	params: JsonObject,
+	options: { timeoutMs?: number; maxReplyBytes?: number } = {},
+): Promise<HerdrSocketReply> {
+	const timeoutMs = options.timeoutMs ?? HERDR_SOCKET_TIMEOUT_MS;
+	const maxReplyBytes = options.maxReplyBytes ?? HERDR_SOCKET_MAX_REPLY_BYTES;
+	const id = `pi-herdr-agents:${process.pid}:${++requestCount}`;
+	return new Promise((resolve) => {
+		let settled = false;
+		let received = Buffer.alloc(0);
+		const socket = connect(socketPath);
+		socket.unref();
+		const finish = (reply: HerdrSocketReply) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			socket.destroy();
+			resolve(reply);
+		};
+		const timer = setTimeout(
+			() =>
+				finish({
+					kind: "failed",
+					reason: `${method} got no reply in ${timeoutMs}ms`,
+				}),
+			timeoutMs,
+		);
+		timer.unref();
+		socket.on("connect", () => {
+			socket.write(`${JSON.stringify({ id, method, params })}\n`);
+		});
+		socket.on("error", (error) =>
+			finish({ kind: "failed", reason: bounded(error.message) }),
+		);
+		socket.on("close", () =>
+			finish({
+				kind: "failed",
+				reason: `${method}: connection closed before a reply`,
+			}),
+		);
+		socket.on("data", (chunk: Buffer) => {
+			received = Buffer.concat([received, chunk]);
+			const end = received.indexOf(10);
+			if ((end < 0 ? received.length : end) > maxReplyBytes) {
+				finish({
+					kind: "failed",
+					reason: `${method} reply exceeds ${maxReplyBytes} bytes`,
+				});
+				return;
+			}
+			if (end >= 0)
+				finish(
+					parseHerdrSocketReply(received.subarray(0, end).toString("utf8"), id),
+				);
+		});
+	});
+}
+
+/**
+ * Herdr answers `ok` even when it ignores a write whose `seq` is not newer
+ * than the last one it applied from this source, so `answered` is not proof
+ * that the token changed.
+ */
+export type PaneTokenOutcome = "answered" | "pane-missing" | "failed";
+
+export interface PaneTokenWrite {
+	paneId: string;
+	source: string;
+	seq: number;
+	token: string;
+	/** `null` clears the token. */
+	value: string | null;
+	ttlMs?: number;
+}
+
+/** One sequenced `pane.report_metadata` token patch. */
+export async function reportPaneToken(
+	socketPath: string,
+	write: PaneTokenWrite,
+	options?: { timeoutMs?: number },
+): Promise<PaneTokenOutcome> {
+	const params: JsonObject = {
+		pane_id: write.paneId,
+		source: write.source,
+		seq: write.seq,
+		tokens: { [write.token]: write.value },
+	};
+	if (write.ttlMs !== undefined) params.ttl_ms = write.ttlMs;
+	const reply = await requestHerdrSocket(
+		socketPath,
+		"pane.report_metadata",
+		params,
+		options,
+	);
+	if (reply.kind === "result") return "answered";
+	if (reply.kind === "error" && reply.code === "pane_not_found")
+		return "pane-missing";
+	return "failed";
+}
+
+/** Parses one reply line; a reply for another request id is never accepted. */
+export function parseHerdrSocketReply(
+	line: string,
+	id: string,
+): HerdrSocketReply {
+	let reply: JsonObject | undefined;
+	try {
+		const parsed: unknown = JSON.parse(line);
+		if (isRecord(parsed)) reply = parsed;
+	} catch {
+		// Malformed JSON is the same failure as a non-object reply below.
+	}
+	if (!reply) return { kind: "failed", reason: "reply is not a JSON object" };
+	if (reply.id !== id)
+		return {
+			kind: "failed",
+			reason: `reply id ${bounded(JSON.stringify(reply.id) ?? "missing")} is not ${id}`,
+		};
+	if (isRecord(reply.error))
+		return {
+			kind: "error",
+			code: isNonEmptyString(reply.error.code)
+				? bounded(reply.error.code)
+				: "herdr_error",
+			message: isString(reply.error.message)
+				? bounded(reply.error.message)
+				: "",
+		};
+	if (!isRecord(reply.result))
+		return { kind: "failed", reason: "reply has no result" };
+	return { kind: "result", result: reply.result };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-agents",
-  "version": "3.0.3",
+  "version": "3.2.0",
   "description": "Asynchronous Pi subagents in Herdr, with optional isolated Git worktrees",
   "keywords": [
     "pi-package",
@@ -30,10 +30,10 @@
   "type": "module",
   "scripts": {
     "changelog": "auto-changelog",
-    "format": "biome format --write pi-extension test maestro",
-    "format:check": "biome format pi-extension test maestro",
-    "lint": "oxlint pi-extension test maestro",
-    "test": "node --experimental-strip-types --test test/test.ts test/worktree-cleanup.test.ts test/launch.test.ts test/runtime-routing.test.ts test/release-workflow.test.ts test/package-manifest.test.js test/maestro/*.test.ts",
+    "format": "biome format --write pi-extension test maestro plugins",
+    "format:check": "biome format pi-extension test maestro plugins",
+    "lint": "oxlint pi-extension test maestro plugins",
+    "test": "node --experimental-strip-types --test test/test.ts test/worktree-cleanup.test.ts test/launch.test.ts test/runtime-routing.test.ts test/release-workflow.test.ts test/package-manifest.test.js test/sidebar-plugin.test.js test/maestro/*.test.ts",
     "test:integration": "node --experimental-strip-types --test --test-concurrency=1 test/integration/*.test.ts",
     "test:integration:live": "PI_TEST_LIVE=1 node --experimental-strip-types --test --test-concurrency=1 test/integration/*.test.ts",
     "version": "auto-changelog --package && git add CHANGELOG.md"
@@ -61,7 +61,7 @@
   "devDependencies": {
     "@biomejs/biome": "2.5.11",
     "@earendil-works/pi-ai": "^1.0.0",
-    "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@earendil-works/pi-coding-agent": "^1.1.0",
     "@earendil-works/pi-tui": "^1.0.0",
     "@oxlint/plugins": "^1.80.0",
     "@sinclair/typebox": "^0.34.52",