@xynogen/pix-runtime 0.8.2 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-runtime",
-	"version": "0.8.2",
+	"version": "0.9.0",
 	"description": "Pix shared runtime — versioned pix.json config, atomic persistence, typed change events",
 	"type": "module",
 	"main": "src/index.ts",
@@ -25,7 +25,9 @@
 		"./config": "./src/runtime.ts",
 		"./sections": "./src/sections/index.ts",
 		"./collapse": "./src/collapse.ts",
+		"./icon-catalog": "./src/icon-catalog.ts",
 		"./io": "./src/io.ts",
+		"./lfid": "./src/lfid.ts",
 		"./once": "./src/once.ts",
 		"./testing": "./src/testing.ts"
 	},

package/src/icon-catalog.ts

@@ -0,0 +1,174 @@
+/**
+ * icon-catalog.ts — semantic icon catalog, treated like an l10n message table.
+ *
+ * Packages must NOT hardcode glyph codepoints. Instead they ask for an icon by
+ * its semantic role — `icon("cwd")`, `icon("paste.image")` — and this module
+ * resolves it against the single active icon mode, exactly like `t("key")`
+ * resolves a translation against the active locale.
+ *
+ *   catalog:  key -> { nerd, unicode, ascii }    (the "messages")
+ *   mode:     "nerd" | "unicode" | "ascii"       (the "locale")
+ *   icon(k):  catalog[k][mode]                    (the "t(key)")
+ *
+ * One global mode governs the whole stack. It is switched via the `/pix`
+ * settings command (in pix-data), persisted to `~/.pi/agent/pix.json`
+ * (`pretty.icons`), and seeded from the PRETTY_ICONS env var on first load.
+ *
+ * Why a catalog instead of per-package toggles: reskinning or fixing a
+ * missing-glyph ("tofu") problem becomes a one-file edit here, and there is
+ * exactly ONE knob (the mode) rather than one env var per package.
+ */
+
+/** Presentation modes, in /pix settings cycle order. nerd = Nerd Font PUA glyphs. */
+export type IconMode = "nerd" | "unicode" | "ascii";
+
+/** All modes in cycle order. */
+export const ICON_MODES: readonly IconMode[] = ["nerd", "unicode", "ascii"];
+
+/** Force text (non-emoji) presentation for symbols that default to emoji. */
+const VS = "\uFE0E";
+
+/**
+ * The catalog. Each semantic key maps to one glyph per mode.
+ *   - nerd:    Nerd Font Private Use Area codepoint (needs a patched font).
+ *   - unicode: standard BMP glyph that ships with virtually every monospace
+ *              font (no Nerd Font required); +VS to force text presentation.
+ *   - ascii:   pure ASCII, renders on literally any terminal.
+ *
+ * Keys are SEMANTIC ROLES, never glyph names — consumers reference meaning.
+ */
+const CATALOG = {
+	// ── footer / status segments ──────────────────────────────────────────
+	model: { nerd: "\u{F06A9}", unicode: `\u25C8${VS}`, ascii: "M" },
+	lsp: { nerd: "\u{F0626}", unicode: `\u25C9${VS}`, ascii: "LSP" },
+	mcp: { nerd: "\u{F048D}", unicode: `\u25D0${VS}`, ascii: "MCP" },
+	cwd: { nerd: "\u{F024B}", unicode: `\u2302${VS}`, ascii: "~" },
+	folder: { nerd: "\u{F024B}", unicode: `\u2302${VS}`, ascii: "/" },
+	afk: { nerd: "\u{F0310}", unicode: `\u2328${VS}`, ascii: "kbd" },
+
+	// ── footer indicators (git status, score) ─────────────────────────────
+	"git.unstaged": { nerd: "\u2717", unicode: "\u2717", ascii: "x" },
+	"git.ahead": { nerd: "\u21E1", unicode: "\u21E1", ascii: "^" },
+	"git.behind": { nerd: "\u21E3", unicode: "\u21E3", ascii: "v" },
+	"net.in": { nerd: "\u21E1", unicode: "\u21E1", ascii: "in" },
+	"net.out": { nerd: "\u21E3", unicode: "\u21E3", ascii: "out" },
+	score: { nerd: "\u26A1", unicode: "\u26A1", ascii: "S" },
+
+	// ── misc ──────────────────────────────────────────────────────────────
+	ok: { nerd: "\u2713", unicode: "\u2713", ascii: "ok" },
+	warn: { nerd: "\u26A0", unicode: "\u26A0", ascii: "!" },
+	error: { nerd: "\u2717", unicode: "\u2717", ascii: "x" },
+
+	// ── permission / security modal titles ────────────────────────────────
+	// Semantic keys for the danger prompts (🔐 root, 🔑 secret). nerd = Nerd
+	// Font glyph, unicode = a widely-shipped BMP symbol forced to text
+	// presentation, ascii = tofu-free token.
+	lock: { nerd: "\u{F0341}", unicode: `\u{1F512}${VS}`, ascii: "[!]" },
+	secret: { nerd: "\u{F0306}", unicode: `\u{1F511}${VS}`, ascii: "[key]" },
+	settings: { nerd: "\u{F0493}", unicode: `\u2699${VS}`, ascii: "[*]" },
+	update: { nerd: "\u{F01DA}", unicode: `\u2193${VS}`, ascii: "[v]" },
+
+	// ── shared status glyphs (checklists, panels, markers) ────────────────
+	// nerd/unicode keep the historical literal so mixed-glyph rows stay
+	// aligned; ascii mode swaps in tofu-free tokens. `⚡` (energetic
+	// warning/killed/denied) intentionally stays a local literal — it is not
+	// part of this set.
+	"status.ok": { nerd: "\u2713", unicode: `\u2713${VS}`, ascii: "ok" },
+	"status.error": { nerd: "\u2717", unicode: `\u2717${VS}`, ascii: "x" },
+	// `⚠` is East-Asian wide (2 cells); consumers that place it in an aligned
+	// marker column must normalize width via `padIcon` (pix-pretty/utils).
+	"status.warn": { nerd: "\u26A0", unicode: `\u26A0${VS}`, ascii: "!" },
+	"status.pending": { nerd: "\u25CB", unicode: `\u25CB${VS}`, ascii: "o" },
+	"status.running": { nerd: "\u25D0", unicode: `\u25D0${VS}`, ascii: "*" },
+	"status.active": { nerd: "\u25CF", unicode: `\u25CF${VS}`, ascii: "*" },
+	"status.done": { nerd: "\u25CF", unicode: `\u25CF${VS}`, ascii: "x" },
+	"status.blocked": { nerd: "\u2298", unicode: `\u2298${VS}`, ascii: "!" },
+
+	// ── welcome banner ────────────────────────────────────────────────────
+	ready: { nerd: "\u{F0633}", unicode: `\u2713${VS}`, ascii: "ok" },
+
+	// ── paste chips (pix-display) ─────────────────────────────────────────
+	"paste.image": { nerd: "\u{F02E9}", unicode: `\u25A3${VS}`, ascii: "img" },
+	"paste.text": { nerd: "\u{F027F}", unicode: `\u25A4${VS}`, ascii: "txt" },
+
+	// ── model picker (pix-models) ─────────────────────────────────────────
+	"picker.model": { nerd: "\u{F0229}", unicode: `\u25C8${VS}`, ascii: "M" },
+
+	// ── optimizer suite (pix-optimizer) ───────────────────────────────────
+	"opt.caveman": { nerd: "\u{F0710}", unicode: `\u2664${VS}`, ascii: "Cv" },
+	"opt.rtk": { nerd: "\u{F04E5}", unicode: `\u2661${VS}`, ascii: "Rk" },
+	"opt.toon": { nerd: "\u{F05C0}", unicode: `\u2662${VS}`, ascii: "Tn" },
+	"opt.ponytail": { nerd: "\u{F0190}", unicode: `\u2667${VS}`, ascii: "Pt" },
+	"opt.title": { nerd: "\u{F0DAB}", unicode: `\u25C8${VS}`, ascii: "*" },
+
+	// ── subagent widget (pix-subagent) ────────────────────────────────────
+	agent: { nerd: "\u{F0BA0}", unicode: `\u2699${VS}`, ascii: "@" },
+	turns: { nerd: "\u{F006A}", unicode: `\u21BB${VS}`, ascii: "~" },
+	tools: { nerd: "\u{F1064}", unicode: `\u2692${VS}`, ascii: "T" },
+	tokens: { nerd: "\u{F027F}", unicode: `\u25A4${VS}`, ascii: "tk" },
+} as const;
+
+/** Every valid semantic icon key. */
+export type IconKey = keyof typeof CATALOG;
+
+/** All catalog keys (useful for /pix previews and tests). */
+export const ICON_KEYS = Object.keys(CATALOG) as IconKey[];
+
+/**
+ * Active mode. Seeded from PRETTY_ICONS env (back-compat: none/off => ascii),
+ * then overridden by a persisted choice when the host loads pix.json.
+ */
+function envMode(): IconMode {
+	const raw = (process.env.PRETTY_ICONS ?? "").toLowerCase();
+	if (raw === "nerd" || raw === "unicode" || raw === "ascii") return raw;
+	if (raw === "none" || raw === "off") return "ascii";
+	return "nerd";
+}
+
+let activeMode: IconMode = envMode();
+
+/** Current global icon mode. */
+export function getIconMode(): IconMode {
+	return activeMode;
+}
+
+/**
+ * Mode-change subscribers. Most consumers resolve icon() at render time and
+ * need no notification, but PUSHED-status consumers (e.g. the optimizer cell,
+ * drawn once via setStatus) must repaint when the mode flips. They subscribe
+ * here; setIconMode fires every callback on an actual change.
+ */
+type ModeListener = (mode: IconMode) => void;
+const listeners = new Set<ModeListener>();
+
+/** Subscribe to global icon-mode changes. Returns an unsubscribe fn. */
+export function onIconModeChange(cb: ModeListener): () => void {
+	listeners.add(cb);
+	return () => listeners.delete(cb);
+}
+
+/**
+ * Set the global icon mode (does NOT persist — callers that want persistence
+ * use the /pix command, which writes pix.json then calls this). Fires
+ * subscribers only on an actual change (no-op re-sets are ignored).
+ */
+export function setIconMode(mode: IconMode): void {
+	if (!ICON_MODES.includes(mode) || mode === activeMode) return;
+	activeMode = mode;
+	for (const cb of listeners) cb(mode);
+}
+
+/**
+ * Resolve a semantic icon key to its glyph for the active mode — the `t(key)`
+ * of this module. Unknown keys return "" (fail soft: never throw mid-render).
+ */
+export function icon(key: IconKey): string {
+	const entry = CATALOG[key];
+	return entry ? entry[activeMode] : "";
+}
+
+/** Resolve a key for an explicit mode (used by /pix previews + tests). */
+export function iconFor(key: IconKey, mode: IconMode): string {
+	const entry = CATALOG[key];
+	return entry ? entry[mode] : "";
+}

package/src/index.ts

@@ -24,6 +24,14 @@ export {
 	withAgentBlock,
 } from "./herdr-state.ts";
 export { ioTimeoutMs, ioTimeoutSignal } from "./io.ts";
+export {
+	generateLfid,
+	isLfid,
+	LFID_RE,
+	type LfidOptions,
+	parseLfid,
+	uniqueLfid,
+} from "./lfid.ts";
 export {
 	config,
 	createRuntime,

package/src/lfid.ts

@@ -0,0 +1,86 @@
+/**
+ * LFID — LLM-friendly IDs (`agent-happy-walrus-42`).
+ *
+ * Raw UUID fragments (`3f2a1b9c-4d5e`, `abc123`) waste parent-model tokens and
+ * invite typos when the model must type them back (steer/stop/resume). An LFID
+ * is `[prefix]-[adjective]-[noun]-[NN]`: pronounceable, copyable, and
+ * self-evidently an ID in a transcript. Two random words + two digits give
+ * 100×100×100 = 1M combinations per prefix — plenty for a live agent set, and
+ * the owning registry (e.g. pix-subagent's AgentManager) maps LFID → record.
+ *
+ * `ponytail:` 2-digit suffix caps the namespace at 1M per prefix. If live sets
+ * ever approach that, widen the suffix or add a third word here.
+ */
+
+import { randomInt } from "node:crypto";
+
+/** `agent-<adj>-<noun>-<NN>` shape. Prefix is caller-owned (`agent`, `job`, …). */
+export const LFID_RE = /^[a-z][a-z0-9]*-[a-z]+-[a-z]+-\d{2}$/;
+
+// Small curated lists: common words, no ambiguous pairs, no profanity.
+// Sized at 100 × 100 so two digits complete a 1M namespace per prefix.
+const ADJECTIVES = (
+	"agate amber azure birch bold brave bright brisk calm cedar cinder clever cloudy coral crisp dawn drift dusk eager elm" +
+	"ember fair fern fleet flint fresh frost garnet glad golden grand green grove happy hazy heath iris ivory jade juniper" +
+	"keen kind lagoon larch light linden lively lotus lucid lunar maple meadow merry misty moss nectar nimble nimbus noble north" +
+	"ocean olive opal pearl pine plain plum proud quartz quick quiet rapid reef ridge river rocky round royal rusty sable" +
+	"sage sandy sedge sharp shiny silent silver sleek small smart smooth solid sorrel spring steady stone sunny swift tango teal"
+).split(" ");
+
+const NOUNS = (
+	"adder albatross anchovy badger beagle bear beaver boar bobcat cobra condor cougar coyote crane cricket deer dove drake duck eagle" +
+	"falcon ferret finch fisher fox frog gannet gazelle gecko goose gopher grouse gull hamster hare hawk heron hyena ibis impala" +
+	"indigo jackal jaguar jay kelp kestrel koala kudu lark lemur llama lynx magpie manatee marmot marten meerkat mink mole mongoose" +
+	"moose narwhal newt numbats ocelot okapi oriole osprey otter owl ox oyster panda pangolin parrot pelican penguin pigeon pika platypus" +
+	"porpoise possum puffin python quail quokka rabbit raven rhea robin sable salmon saola seal shark shrew skunk sloth snail sparrow"
+).split(" ");
+
+export interface LfidOptions {
+	/** Namespace prefix, e.g. `"agent"`. Defaults to `"agent"`. */
+	prefix?: string;
+	/** RNG override for tests/determinism. Must return an int in [0, max). */
+	rand?: (max: number) => number;
+}
+
+/** Generate one LFID, e.g. `agent-happy-walrus-42`. */
+export function generateLfid(opts: LfidOptions = {}): string {
+	const prefix = opts.prefix ?? "agent";
+	const rand = opts.rand ?? randomInt;
+	const pick = (xs: string[]): string => xs[rand(xs.length)] as string;
+	const n = String(rand(100)).padStart(2, "0");
+	return `${prefix}-${pick(ADJECTIVES)}-${pick(NOUNS)}-${n}`;
+}
+
+/** Loose check: is this string LFID-shaped (any prefix)? */
+export function isLfid(s: string): boolean {
+	return LFID_RE.test(s);
+}
+
+/** Parse an LFID into its parts; undefined when the shape doesn't match. */
+export function parseLfid(
+	s: string,
+): { prefix: string; adjective: string; noun: string; num: string } | undefined {
+	const m = LFID_RE.exec(s);
+	if (!m) return undefined;
+	const [prefix, adjective, noun, num] = s.split("-");
+	return {
+		prefix: prefix as string,
+		adjective: adjective as string,
+		noun: noun as string,
+		num: num as string,
+	};
+}
+
+/**
+ * Generate an LFID not already present in `taken`. Retries a bounded number of
+ * times, then throws — a full or near-full namespace is a caller bug, not a
+ * loop-candidate. Collisions across live sets are essentially impossible long
+ * before this bound (1M combinations), so 64 tries is generous.
+ */
+export function uniqueLfid(taken: (id: string) => boolean, opts: LfidOptions = {}): string {
+	for (let i = 0; i < 64; i++) {
+		const id = generateLfid(opts);
+		if (!taken(id)) return id;
+	}
+	throw new Error("lfid: namespace exhausted (too many live IDs for prefix)");
+}

package/src/pix-command.ts

@@ -15,6 +15,7 @@ import {
 	visibleWidth,
 	wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
+import { icon } from "./icon-catalog.ts";
 import type { PixRuntime } from "./runtime.ts";
 import type { DeepPartial, SectionHandle } from "./schema.ts";
 import { collapseSection } from "./sections/collapse.ts";
@@ -184,7 +185,7 @@ const SETTINGS: SettingRow<unknown>[] = [
 ];
 
 function buildSummary(runtime: PixRuntime): string {
-	const lines = [`pix settings (${runtime.path})`, ""];
+	const lines = [`Pix Settings (${runtime.path})`, ""];
 	let lastSection = "";
 	for (const row of SETTINGS) {
 		if (row.section !== lastSection) {
@@ -299,7 +300,9 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 									tui.terminal?.rows,
 									runtime.get(prettySection).maxRenderHeight,
 								),
-								header: [theme.fg("accent", theme.bold("  pix settings")), ""],
+								title: `${icon("settings")} Pix Settings`,
+								titleColor: (s: string) => theme.fg("accent", theme.bold(s)),
+								header: [""],
 								body,
 								footer: [
 									"",
@@ -378,6 +381,10 @@ interface RuntimeModalOptions {
 	selectedBodyLine?: number;
 	color: (s: string) => string;
 	bg?: (s: string) => string;
+	/** Plain title embedded in the top border (`╭─ title ──╮`). */
+	title?: string;
+	/** Color for the embedded title. Defaults to `color`. */
+	titleColor?: (s: string) => string;
 }
 
 interface RuntimeModalResult {
@@ -451,11 +458,22 @@ function frameModal(opts: RuntimeModalOptions): RuntimeModalResult {
 function frameRows(
 	width: number,
 	lines: string[],
-	opts: Pick<RuntimeModalOptions, "color" | "bg">,
+	opts: Pick<RuntimeModalOptions, "color" | "bg" | "title" | "titleColor">,
 ): string[] {
 	const bg = opts.bg ?? ((s: string) => s);
 	const inner = Math.max(1, width - 4);
 	const dashes = "─".repeat(width - 2);
+	// Top border: bare, or `╭─ title ──╮` when a title is given. Chrome around
+	// the label is 5 cols (2 corners, 1 lead dash, 2 pad spaces); tail fills the
+	// rest so the row stays exactly `width` visible cells.
+	const topBorder = ((): string => {
+		const span = width - 5;
+		if (!opts.title || span < 3) return opts.color(`╭${dashes}╮`);
+		const paint = opts.titleColor ?? opts.color;
+		const label = truncateToWidth(opts.title, span - 1, "…");
+		const tail = "─".repeat(Math.max(1, span - visibleWidth(label)));
+		return `${opts.color("╭─ ")}${paint(label)}${opts.color(` ${tail}╮`)}`;
+	})();
 	const SENTINEL = "\x00";
 	const bgOpen = bg(SENTINEL).split(SENTINEL)[0] ?? "";
 	const reassert = (s: string): string => {
@@ -470,5 +488,5 @@ function frameRows(
 		const padded = fitted + " ".repeat(Math.max(0, inner - visibleWidth(fitted)));
 		return bg(`${opts.color("│")} ${reassert(padded)} ${opts.color("│")}`);
 	};
-	return [bg(opts.color(`╭${dashes}╮`)), ...lines.map(row), bg(opts.color(`╰${dashes}╯`))];
+	return [bg(topBorder), ...lines.map(row), bg(opts.color(`╰${dashes}╯`))];
 }