@xynogen/pix-runtime 0.5.3 → 0.6.0

package/README.md

@@ -68,6 +68,83 @@ Collapse policy helpers:
 import { shouldCollapse, collapseDelayMs } from "@xynogen/pix-runtime/collapse";
 ```
 
+## Agent state and herdr notifications
+
+### Agent-state coordinator
+
+`src/herdr-state.ts` (exported from the package index) is a process-wide
+coordinator that tracks whether the agent is `working`, `blocked`, or `idle`,
+keyed per Pi `EventBus`. On every transition it emits a `pix:agent-state` event:
+
+```ts
+{ state: "working" | "blocked" | "idle", message?: string, activities: number, blocks: number }
+```
+
+Two lease primitives drive it. Both return an idempotent release function:
+
+- `beginAgentActivity(events, source, message?)` marks asynchronous work in
+  progress (for example a running subagent). State reports `working` while any
+  activity lease is open.
+- `withAgentBlock(events, source, message, prompt)` holds `blocked` state for the
+  duration of an awaited `prompt()` and always releases it, even on throw. Blocks
+  take priority over activities, so state is `blocked` whenever any block lease is
+  open.
+
+`bindAgentStateEvents(events)` replays the current state and answers
+`pix:agent-state:request`. `resetAgentState(events)` clears all leases on session
+shutdown.
+
+Nested leases collapse to a single state: two open blocks still report `blocked`
+until both release.
+
+Consumers that open a block today: `pix-ask` (`ask_user`, "Waiting for user
+answer"), `pix-gate` (approval prompts), and `pix-sudo` (root approval).
+`pix-subagent` opens activity leases for running background agents.
+
+```ts
+import { withAgentBlock, beginAgentActivity } from "@xynogen/pix-runtime";
+
+// Hold blocked state while waiting on the user:
+await withAgentBlock(pi.events, "ask_user", "Waiting for user answer", () => promptUser());
+
+// Mark background work:
+const done = beginAgentActivity(pi.events, "subagent", "Agent running");
+// ... later ...
+done();
+```
+
+### herdr notification bridge
+
+`src/herdr-notify.ts` (exported as `bindHerdrNotify`) is a leaf subscriber on
+`pix:agent-state`. When the agent transitions INTO `blocked` it spawns:
+
+```bash
+herdr notification show <message> --sound request
+```
+
+so a user away from their terminal gets a popup and sound. `request` is herdr's
+built-in "needs attention" cue. The trigger is edge-triggered: it fires once per
+entry into `blocked`, not repeatedly, and nested blocks stay a single
+notification.
+
+The bridge is fire-and-forget. The child is `detached`, `unref`'d, and
+`stdio: "ignore"`, and a missing `herdr` binary is swallowed, so it never blocks
+the prompt path or throws. herdr owns the toast's color, position, and sound via
+its own server config (`[toast]` / `[notification]`); pix only reports the moment
+and the message. Compaction and other autonomous work never enter `blocked`, so
+they never notify.
+
+It is wired automatically by the runtime extension: bound at session start,
+unbound at shutdown. No manual setup beyond running inside a herdr pane.
+
+Two environment variables control it:
+
+- `HERDR_ENV` — herdr sets this to `1` inside its own pane. The bridge only runs
+  when `HERDR_ENV === "1"`; outside a herdr pane it is a no-op and spawns
+  nothing.
+- `PIX_HERDR_NOTIFY` — set to `0` to silence notifications even inside a herdr
+  pane.
+
 ## Testing
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-runtime",
-	"version": "0.5.3",
+	"version": "0.6.0",
 	"description": "Pix shared runtime — versioned pix.json config, atomic persistence, typed change events",
 	"type": "module",
 	"main": "src/index.ts",

package/src/extension.ts

@@ -1,4 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { bindHerdrNotify } from "./herdr-notify.ts";
+import { bindAgentStateEvents, resetAgentState } from "./herdr-state.ts";
 import { once } from "./once.ts";
 import { registerPixCommand } from "./pix-command.ts";
 import { pixRuntime } from "./runtime.ts";
@@ -16,6 +18,8 @@ export default function registerRuntime(pi: ExtensionAPI): void {
 		const runtime = pixRuntime();
 
 		registerPixCommand(pi, runtime);
+		const unbindAgentState = bindAgentStateEvents(pi.events);
+		const unbindHerdrNotify = bindHerdrNotify(pi.events);
 
 		let initialized = false;
 		pi.on("session_start", async () => {
@@ -29,6 +33,9 @@ export default function registerRuntime(pi: ExtensionAPI): void {
 		});
 
 		pi.on("session_shutdown", async () => {
+			resetAgentState(pi.events);
+			unbindHerdrNotify();
+			unbindAgentState();
 			await runtime.flush();
 		});
 	});

package/src/herdr-notify.ts

@@ -0,0 +1,39 @@
+import { spawn } from "node:child_process";
+import type { EventBus } from "@earendil-works/pi-coding-agent";
+import type { PixAgentState, PixAgentStateEvent } from "./herdr-state.ts";
+
+/**
+ * Leaf bridge: when the agent enters the `blocked` state (ask_user / gate /
+ * sudo waiting on the user), fire a herdr notification so an away-from-pane
+ * user gets a sound + popup. Fires only on the transition INTO blocked, never
+ * repeatedly. No-op outside a herdr pane; silence with `PIX_HERDR_NOTIFY=0`.
+ */
+export function bindHerdrNotify(events: EventBus, spawnFn = spawn): () => void {
+	// ponytail: gate on HERDR_ENV — herdr's own extension uses the same signal;
+	//           outside herdr the CLI would just no-op, so skip the spawn entirely.
+	if (process.env.HERDR_ENV !== "1" || process.env.PIX_HERDR_NOTIFY === "0") {
+		return () => {};
+	}
+	let last: PixAgentState | undefined;
+	const off = events.on("pix:agent-state", (raw) => {
+		const event = raw as PixAgentStateEvent;
+		if (event.state === "blocked" && last !== "blocked") {
+			notify(event.message ?? "Pi needs your attention", spawnFn);
+		}
+		last = event.state;
+	});
+	return off;
+}
+
+function notify(message: string, spawnFn: typeof spawn): void {
+	try {
+		const child = spawnFn("herdr", ["notification", "show", message, "--sound", "request"], {
+			stdio: "ignore",
+			detached: true,
+		});
+		child.on("error", () => {}); // herdr not on PATH — ignore
+		child.unref();
+	} catch {
+		// spawn threw synchronously; nothing actionable
+	}
+}

package/src/herdr-state.ts

@@ -0,0 +1,116 @@
+import type { EventBus } from "@earendil-works/pi-coding-agent";
+
+export type PixAgentState = "working" | "blocked" | "idle";
+export type PixAgentStateEvent = {
+	state: PixAgentState;
+	message?: string;
+	activities: number;
+	blocks: number;
+};
+
+type Entry = { source: string; message?: string };
+type Coordinator = {
+	activities: Map<symbol, Entry>;
+	blocks: Map<symbol, Entry>;
+};
+
+function coordinators(): WeakMap<EventBus, Coordinator> {
+	const global = globalThis as { __pixAgentState?: WeakMap<EventBus, Coordinator> };
+	global.__pixAgentState ??= new WeakMap<EventBus, Coordinator>();
+	return global.__pixAgentState;
+}
+
+function coordinator(events: EventBus): Coordinator {
+	const registry = coordinators();
+	let state = registry.get(events);
+	if (!state) {
+		state = { activities: new Map(), blocks: new Map() };
+		registry.set(events, state);
+	}
+	return state;
+}
+
+function snapshot(state: Coordinator): PixAgentStateEvent {
+	const blocked = [...state.blocks.values()].at(-1);
+	if (blocked) {
+		return {
+			state: "blocked",
+			...(blocked.message ? { message: blocked.message } : {}),
+			activities: state.activities.size,
+			blocks: state.blocks.size,
+		};
+	}
+	const active = [...state.activities.values()].at(-1);
+	if (active) {
+		return {
+			state: "working",
+			...(active.message ? { message: active.message } : {}),
+			activities: state.activities.size,
+			blocks: 0,
+		};
+	}
+	return { state: "idle", activities: 0, blocks: 0 };
+}
+
+function publish(events: EventBus): void {
+	events.emit("pix:agent-state", snapshot(coordinator(events)));
+}
+
+function begin(
+	events: EventBus,
+	kind: "activities" | "blocks",
+	source: string,
+	message?: string,
+): () => void {
+	const state = coordinator(events);
+	const token = Symbol(source);
+	state[kind].set(token, { source, message });
+	publish(events);
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		state[kind].delete(token);
+		publish(events);
+	};
+}
+
+/** Keep external status integrations working while asynchronous Pix work remains. */
+export function beginAgentActivity(events: EventBus, source: string, message?: string): () => void {
+	return begin(events, "activities", source, message);
+}
+
+/** Internal primitive behind {@link withAgentBlock}; exported only for same-package tests. Blocks take priority over activity. */
+export function beginAgentBlock(events: EventBus, source: string, message?: string): () => void {
+	return begin(events, "blocks", source, message);
+}
+
+/** Hold blocked state for one prompt and always release it. */
+export async function withAgentBlock<T>(
+	events: EventBus,
+	source: string,
+	message: string | undefined,
+	prompt: () => Promise<T>,
+): Promise<T> {
+	const release = beginAgentBlock(events, source, message);
+	try {
+		return await prompt();
+	} finally {
+		release();
+	}
+}
+
+/** Bind state replay/reset to one Pi session lifecycle. */
+export function bindAgentStateEvents(events: EventBus): () => void {
+	const off = events.on("pix:agent-state:request", () => publish(events));
+	publish(events);
+	return off;
+}
+
+/** Clear stale leases when a session shuts down or an extension reloads. */
+export function resetAgentState(events: EventBus): void {
+	const state = coordinator(events);
+	state.activities.clear();
+	state.blocks.clear();
+	publish(events);
+}

package/src/index.ts

@@ -7,6 +7,15 @@ export type {
 	SubscribeOptions,
 } from "./events.ts";
 export { default } from "./extension.ts";
+export { bindHerdrNotify } from "./herdr-notify.ts";
+export {
+	beginAgentActivity,
+	bindAgentStateEvents,
+	type PixAgentState,
+	type PixAgentStateEvent,
+	resetAgentState,
+	withAgentBlock,
+} from "./herdr-state.ts";
 export { ioTimeoutMs, ioTimeoutSignal } from "./io.ts";
 export {
 	config,