@xynogen/pix-runtime 0.5.2 → 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.2",
+	"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,

package/src/pix-command.ts

@@ -44,8 +44,14 @@ function formatTokens(tokens: number): string {
 
 /** Parse a compact token label ("1M", "150k") back to an absolute count. */
 function parseTokens(label: string): number {
-	const n = Number.parseFloat(label);
-	return /m$/i.test(label) ? n * 1_000_000 : n * 1000;
+	const raw = label.trim();
+	const m = raw.match(/^([0-9]*\.?[0-9]+)\s*([km])?$/i);
+	if (!m) return Number.NaN;
+	const numStr = m[1] ?? "";
+	const n = Number.parseFloat(numStr);
+	if (!Number.isFinite(n)) return Number.NaN;
+	const suf = (m[2] ?? "").toLowerCase();
+	return suf === "m" ? Math.round(n * 1_000_000) : Math.round(n * 1000);
 }
 
 const SETTINGS: SettingRow<unknown>[] = [
@@ -93,7 +99,8 @@ const SETTINGS: SettingRow<unknown>[] = [
 		section: "Compaction",
 		label: "Trigger (% ctx)",
 		handle: compactionSection,
-		values: ["0", "5", "10", "15", "20", "25", "30", "40", "50", "60", "70", "80", "90"],
+		// 0–100 in 5% steps.
+		values: Array.from({ length: 21 }, (_, i) => String(i * 5)),
 		read: (v) => String(v.triggerPercent),
 		patch: (value) => ({ triggerPercent: Number(value) }),
 	}),
@@ -135,6 +142,8 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 	pi.registerCommand("pix", {
 		description: "pix: open shared settings (edit pix.json)",
 		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			// Re-parse pix.json so section parsers remain the single validation source.
+			await runtime.reload({ origin: "command", source: "pix" });
 			const ui = ctx.ui as unknown as {
 				custom?: (f: unknown, opts?: unknown) => Promise<unknown>;
 				notify(m: string, t?: "info" | "warning" | "error"): void;
@@ -169,11 +178,29 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 					const cycle = (direction: -1 | 1) => {
 						const row = SETTINGS[selected];
 						if (!row) return;
-						const cur = row.values.indexOf(row.read(runtime.get(row.handle)));
-						const next = (cur + direction + row.values.length) % row.values.length;
-						const val = row.values[next];
-						if (val === undefined) return;
-						void runtime.update(row.handle, row.patch(val), { origin: "command", source: "pix" });
+						// Functional updater: the runtime queue serializes writes, and the
+						// callback sees the latest committed value — so rapid presses each
+						// advance exactly one step instead of collapsing on a stale snapshot.
+						const step = (current: unknown): unknown => {
+							const curVal = row.read(current);
+							let cur = row.values.indexOf(curVal);
+							// ponytail: unsupported custom values snap to section default on first change.
+							if (cur === -1) {
+								const def = row.read(row.handle.defaults);
+								const defIdx = row.values.indexOf(def);
+								cur = defIdx !== -1 ? defIdx - direction : -1;
+							}
+							const next = (cur + direction + row.values.length) % row.values.length;
+							const val = row.values[next];
+							if (val === undefined) return current;
+							return { ...(current as object), ...(row.patch(val) as object) };
+						};
+						// Re-render AFTER the commit lands; the synchronous render in
+						// handleInput fires before the queued write and shows a stale value.
+						void runtime
+							.update(row.handle, step, { origin: "command", source: "pix" })
+							.then(() => tui.requestRender())
+							.catch(() => ui.notify(`pix: failed to update ${row.label}`, "error"));
 					};
 					const move = (direction: -1 | 1) => {
 						selected = (selected + direction + SETTINGS.length) % SETTINGS.length;
@@ -187,7 +214,8 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 							const settingBodyLines: number[] = [];
 							let lastSection = "";
 							for (let i = 0; i < SETTINGS.length; i++) {
-								const row = SETTINGS[i]!;
+								const row = SETTINGS[i];
+								if (!row) continue;
 								if (row.section !== lastSection) {
 									if (lastSection) body.push("");
 									body.push(theme.fg("dim", `  ${row.section}`));
@@ -241,20 +269,15 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 							// matchesKey handles both legacy bytes and Kitty CSI-u encodings
 							// for letters and special keys alike — raw string compares like
 							// `data === "k"` silently fail under the Kitty keyboard protocol.
-							if (matchesKey(data, "k") || matchesKey(data, "up")) move(-1);
-							else if (matchesKey(data, "j") || matchesKey(data, "down")) move(1);
-							else if (matchesKey(data, "h") || matchesKey(data, "left")) cycle(-1);
-							else if (
-								matchesKey(data, "l") ||
-								matchesKey(data, "right") ||
-								matchesKey(data, "space") ||
-								matchesKey(data, "enter")
-							)
-								cycle(1);
-							else if (matchesKey(data, "escape") || matchesKey(data, "q")) {
+							if (kb.matches(data, "tui.select.cancel")) {
 								done(null);
 								return;
-							} else return;
+							}
+							if (kb.matches(data, "tui.select.up")) move(-1);
+							else if (kb.matches(data, "tui.select.down")) move(1);
+							else if (matchesKey(data, Key.left)) cycle(-1);
+							else if (matchesKey(data, Key.right)) cycle(1);
+							else return;
 							tui.requestRender();
 						},
 					};
@@ -357,12 +380,13 @@ function frameRows(
 	const dashes = "─".repeat(width - 2);
 	const SENTINEL = "\x00";
 	const bgOpen = bg(SENTINEL).split(SENTINEL)[0] ?? "";
-	const reassert = (s: string): string =>
-		bgOpen
-			? s.replace(/\x1b\[([0-9;]*)m/g, (seq, p: string) =>
-					p === "0" || p.split(";").includes("49") ? `${seq}${bgOpen}` : seq,
-				)
-			: s;
+	const reassert = (s: string): string => {
+		if (!bgOpen) return s;
+		return s.replace(/\x1b\[([0-9;]*)m/g, (seq, p: string) => {
+			if (p === "0" || p.split(";").includes("49")) return `${seq}${bgOpen}`;
+			return seq;
+		});
+	};
 	const row = (content: string): string => {
 		const fitted = truncateToWidth(content, inner, "…");
 		const padded = fitted + " ".repeat(Math.max(0, inner - visibleWidth(fitted)));

package/src/runtime.ts

@@ -347,12 +347,24 @@ class RuntimeImpl implements PixRuntime {
 		const values = new Map<string, unknown>();
 		for (const s of this.registry.all()) values.set(s.key, s.parse(base[s.key], ctx));
 
-		const currentValue = values.get(section.key) as Readonly<T>;
-		const nextValue =
+		// Guard against a version-skewed second runtime copy whose registry
+		// lacks this section (e.g. an old npm copy handling a new handle). The
+		// functional updater would otherwise crash the whole process on
+		// `undefined`. Fall back to the handle's own parse of the raw doc.
+		const currentValue = (
+			values.has(section.key)
+				? values.get(section.key)
+				: section.__section.parse(base[section.key], ctx)
+		) as Readonly<T>;
+		const mergedValue =
 			typeof updater === "function"
 				? (updater as (c: Readonly<T>) => T)(currentValue)
 				: deepMerge(currentValue as T, updater);
 
+		// Re-validate through the section's own parse so a bad patch (NaN,
+		// Infinity, wrong type) can never enter the live snapshot.
+		const nextValue = section.__section.parse(mergedValue, ctx) as T;
+
 		if (JSON.stringify(currentValue) === JSON.stringify(nextValue)) return undefined;
 		values.set(section.key, nextValue);
 

package/src/sections/compaction.ts

@@ -31,17 +31,35 @@ function pctOr(v: unknown, fallback: number): number {
 /** Require a finite token floor of at least 25k. */
 function minimumTokensOr(v: unknown, fallback: number): number {
 	if (typeof v !== "number" || !Number.isFinite(v)) return fallback;
+	// Strings from older/hand-edited pix.json (e.g. "150k") → parse before clamping.
 	return Math.max(MINIMUM_TOKEN_FLOOR, Math.round(v));
 }
 
+function parseTokenString(label: string): number | undefined {
+	const raw = label.trim();
+	if (!raw) return undefined;
+	const m = raw.match(/^([0-9]*\.?[0-9]+)\s*([km])?$/i);
+	if (!m) return undefined;
+	const numStr = m[1] ?? "";
+	const n = Number.parseFloat(numStr);
+	if (!Number.isFinite(n)) return undefined;
+	const suf = (m[2] ?? "").toLowerCase();
+	if (suf === "m") return Math.round(n * 1_000_000);
+	if (suf === "k") return Math.round(n * 1000);
+	return Math.round(n);
+}
+
 export const compactionSection = defineSection<"compaction", CompactionConfig>({
 	key: "compaction",
 	defaults: DEFAULTS,
 	parse(raw) {
 		if (!isObj(raw)) return { ...DEFAULTS };
+		const rawMin = raw.minimumTokens;
+		const coercedMin =
+			typeof rawMin === "string" ? (parseTokenString(rawMin) ?? Number.NaN) : rawMin;
 		return {
 			triggerPercent: pctOr(raw.triggerPercent, DEFAULTS.triggerPercent),
-			minimumTokens: minimumTokensOr(raw.minimumTokens, DEFAULTS.minimumTokens),
+			minimumTokens: minimumTokensOr(coercedMin, DEFAULTS.minimumTokens),
 		};
 	},
 });