@xynogen/pix-runtime 0.5.3 → 0.7.0

package/README.md

@@ -44,6 +44,12 @@ const timeoutMs = ioTimeoutMs();                    // shared network timeout
 const signal = ioTimeoutSignal(toolSignal);         // timeout + cancellation
 ```
 
+Set `pretty.maxRenderWidth` and `pretty.maxRenderHeight` in `~/.pi/agent/pix.json`,
+or change **Pretty → max modal width/height** with `/pix`. Values accept terminal
+percentages such as `"65%"`/`"80%"` or fixed columns/rows such as `96`/`20`.
+Percentage choices in `/pix` move in 5% steps. Width is the rendered frame width;
+height is the threshold where modal content starts paging.
+
 Set `io.timeoutSec` in `~/.pi/agent/pix.json`, or change **Network → timeout (sec)**
 with `/pix`. The default is 30 seconds. It applies to Pix network operations,
 including remote skills, web fetch/search/transcription, MCP requests and
@@ -68,6 +74,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.7.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

@@ -21,7 +21,7 @@ import { collapseSection } from "./sections/collapse.ts";
 import { compactionSection } from "./sections/compaction.ts";
 import { gateSection } from "./sections/gate.ts";
 import { ioSection } from "./sections/io.ts";
-import { prettySection } from "./sections/pretty.ts";
+import { prettySection, type RenderSize } from "./sections/pretty.ts";
 
 interface SettingRow<T> {
 	section: string;
@@ -42,6 +42,15 @@ function formatTokens(tokens: number): string {
 	return tokens % 1_000_000 === 0 ? `${tokens / 1_000_000}M` : `${tokens / 1000}k`;
 }
 
+function parseRenderSize(value: string): RenderSize {
+	return value.endsWith("%") ? (value as `${number}%`) : Number.parseFloat(value);
+}
+
+function resolveRenderSize(limit: RenderSize, available: number): number {
+	if (typeof limit === "number") return Math.floor(limit);
+	return Math.floor((available * Number.parseFloat(limit)) / 100);
+}
+
 /** Parse a compact token label ("1M", "150k") back to an absolute count. */
 function parseTokens(label: string): number {
 	const raw = label.trim();
@@ -71,6 +80,58 @@ const SETTINGS: SettingRow<unknown>[] = [
 		read: (v) => v.lsStyle,
 		patch: (value) => ({ lsStyle: value as "grid" | "tree" }),
 	}),
+	row({
+		section: "Pretty",
+		label: "max modal width",
+		handle: prettySection,
+		values: [
+			"50%",
+			"55%",
+			"60%",
+			"65%",
+			"70%",
+			"75%",
+			"80%",
+			"85%",
+			"90%",
+			"95%",
+			"100%",
+			"72 cols",
+			"80 cols",
+			"88 cols",
+			"96 cols",
+			"104 cols",
+			"120 cols",
+		],
+		read: (v) =>
+			typeof v.maxRenderWidth === "number" ? `${v.maxRenderWidth} cols` : v.maxRenderWidth,
+		patch: (value) => ({ maxRenderWidth: parseRenderSize(value) }),
+	}),
+	row({
+		section: "Pretty",
+		label: "max modal height",
+		handle: prettySection,
+		values: [
+			"50%",
+			"55%",
+			"60%",
+			"65%",
+			"70%",
+			"75%",
+			"80%",
+			"85%",
+			"90%",
+			"95%",
+			"100%",
+			"12 rows",
+			"16 rows",
+			"20 rows",
+			"24 rows",
+		],
+		read: (v) =>
+			typeof v.maxRenderHeight === "number" ? `${v.maxRenderHeight} rows` : v.maxRenderHeight,
+		patch: (value) => ({ maxRenderHeight: parseRenderSize(value) }),
+	}),
 	row({
 		section: "Collapse",
 		label: "enabled",
@@ -154,7 +215,6 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 				return;
 			}
 
-			const boxW = 52;
 			await ui.custom(
 				(
 					tui: { requestRender(): void; terminal?: { rows?: number } },
@@ -208,7 +268,7 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 					};
 
 					return {
-						render: () => {
+						render: (width: number) => {
 							const labelW = Math.max(...SETTINGS.map((r) => r.label.length));
 							const body: string[] = [];
 							const settingBodyLines: number[] = [];
@@ -230,8 +290,11 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 								body.push(`${cursor} ${label}  ${theme.fg(isDefault ? "dim" : "success", value)}`);
 							}
 							const result = frameModal({
-								width: boxW,
-								maxHeight: modalHeight(tui.terminal?.rows),
+								width,
+								maxHeight: modalHeight(
+									tui.terminal?.rows,
+									runtime.get(prettySection).maxRenderHeight,
+								),
 								header: [theme.fg("accent", theme.bold("  pix settings")), ""],
 								body,
 								footer: [
@@ -282,7 +345,18 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 						},
 					};
 				},
-				{ overlay: true, overlayOptions: { anchor: "center", width: boxW, maxHeight: "80%" } },
+				{
+					overlay: true,
+					overlayOptions: () => {
+						const pretty = runtime.get(prettySection);
+						return {
+							anchor: "center",
+							width: pretty.maxRenderWidth,
+							maxHeight: pretty.maxRenderHeight,
+							margin: 2,
+						};
+					},
+				},
 			);
 		},
 	});
@@ -309,9 +383,9 @@ interface RuntimeModalResult {
 	maxBodyOffset: number;
 }
 
-function modalHeight(rows = 24): number {
+function modalHeight(rows = 24, limit: RenderSize = "80%"): number {
 	const safe = Number.isFinite(rows) ? Math.max(1, Math.floor(rows)) : 24;
-	return Math.max(1, Math.min(safe, Math.floor(safe * 0.8)));
+	return Math.max(1, Math.min(safe, resolveRenderSize(limit, safe)));
 }
 
 function pageBodyOffset(offset: number, size: number, max: number, direction: -1 | 1): number {

package/src/sections/index.ts

@@ -20,6 +20,7 @@ export {
 	type LsStyle,
 	type PrettyConfig,
 	prettySection,
+	type RenderSize,
 } from "./pretty.ts";
 
 import { collapseSection } from "./collapse.ts";

package/src/sections/pretty.ts

@@ -2,6 +2,7 @@ import { defineSection, enumOr, isObj, posNumOr } from "../schema.ts";
 
 export type IconMode = "nerd" | "unicode" | "ascii";
 export type LsStyle = "grid" | "tree";
+export type RenderSize = number | `${number}%`;
 
 export interface DiffConfig {
 	splitMinWidth: number;
@@ -11,6 +12,8 @@ export interface DiffConfig {
 export interface PrettyConfig {
 	icons: IconMode;
 	lsStyle: LsStyle;
+	maxRenderWidth: RenderSize;
+	maxRenderHeight: RenderSize;
 	maxPreviewLines: number;
 	maxRenderLines: number;
 	maxHighlightChars: number;
@@ -21,9 +24,20 @@ export interface PrettyConfig {
 const ICON_MODES: readonly IconMode[] = ["nerd", "unicode", "ascii"];
 const LS_STYLES: readonly LsStyle[] = ["grid", "tree"];
 
+function renderSizeOr(value: unknown, fallback: RenderSize): RenderSize {
+	if (typeof value === "number") return Number.isFinite(value) && value > 0 ? value : fallback;
+	if (typeof value !== "string") return fallback;
+	const match = value.match(/^(\d+(?:\.\d+)?)%$/);
+	if (!match) return fallback;
+	const percent = Number(match[1]);
+	return percent > 0 && percent <= 100 ? (value as `${number}%`) : fallback;
+}
+
 const DEFAULTS: Readonly<PrettyConfig> = {
 	icons: "nerd",
 	lsStyle: "grid",
+	maxRenderWidth: "65%",
+	maxRenderHeight: "80%",
 	maxPreviewLines: 80,
 	maxRenderLines: 150,
 	maxHighlightChars: 80_000,
@@ -40,6 +54,8 @@ export const prettySection = defineSection<"pretty", PrettyConfig>({
 		return {
 			icons: enumOr(raw.icons, ICON_MODES, DEFAULTS.icons),
 			lsStyle: enumOr(raw.lsStyle, LS_STYLES, DEFAULTS.lsStyle),
+			maxRenderWidth: renderSizeOr(raw.maxRenderWidth, DEFAULTS.maxRenderWidth),
+			maxRenderHeight: renderSizeOr(raw.maxRenderHeight, DEFAULTS.maxRenderHeight),
 			maxPreviewLines: posNumOr(raw.maxPreviewLines, DEFAULTS.maxPreviewLines),
 			maxRenderLines: posNumOr(raw.maxRenderLines, DEFAULTS.maxRenderLines),
 			maxHighlightChars: posNumOr(raw.maxHighlightChars, DEFAULTS.maxHighlightChars),