@xynogen/pix-runtime 0.8.4 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-runtime",
-	"version": "0.8.4",
+	"version": "0.10.0",
 	"description": "Pix shared runtime — versioned pix.json config, atomic persistence, typed change events",
 	"type": "module",
 	"main": "src/index.ts",
@@ -27,8 +27,10 @@
 		"./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"
+		"./testing": "./src/testing.ts",
+		"./which": "./src/which.ts"
 	},
 	"keywords": [
 		"pi",

package/src/icon-catalog.ts

@@ -65,6 +65,10 @@ const CATALOG = {
 	// presentation, ascii = tofu-free token.
 	lock: { nerd: "\u{F0341}", unicode: `\u{1F512}${VS}`, ascii: "[!]" },
 	secret: { nerd: "\u{F0306}", unicode: `\u{1F511}${VS}`, ascii: "[key]" },
+	"data.boolean": { nerd: "\u25C6", unicode: `\u25C6${VS}`, ascii: "bool" },
+	"data.int": { nerd: "#", unicode: "#", ascii: "int" },
+	"data.float": { nerd: "\u2248", unicode: `\u2248${VS}`, ascii: "float" },
+	"data.string": { nerd: "\u201C", unicode: `\u201C${VS}`, ascii: "str" },
 	settings: { nerd: "\u{F0493}", unicode: `\u2699${VS}`, ascii: "[*]" },
 	update: { nerd: "\u{F01DA}", unicode: `\u2193${VS}`, ascii: "[v]" },
 

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,
@@ -60,3 +68,8 @@ export {
 	type PrettyConfig,
 	prettySection,
 } from "./sections/index.ts";
+export {
+	type FindExecutableOptions,
+	findExecutable,
+	findExecutableSync,
+} from "./which.ts";

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/which.ts

@@ -0,0 +1,103 @@
+/**
+ * Cross-platform executable lookup — the `which`/`where` a portable Node program
+ * lacks. Scans `PATH` (POSIX + Windows), honouring Windows `PATHEXT` so a bare
+ * name like `aria2c` resolves to `aria2c.exe`. Returns the first match, or
+ * `undefined` when nothing on `PATH` is runnable.
+ *
+ * A name that already contains a path separator is treated as a direct path and
+ * checked in place (still PATHEXT-expanded on Windows), matching `which` semantics.
+ *
+ * `ponytail:` POSIX runnability is an `X_OK` access check — it does not re-derive
+ * effective-uid permission bits. That matches how the shell picks a binary, which
+ * is the intent here. Windows treats "exists with an executable extension" as
+ * runnable (there is no X bit); this is the conventional `where` behaviour.
+ */
+
+import { accessSync, constants, statSync } from "node:fs";
+import { access, stat } from "node:fs/promises";
+import { delimiter, isAbsolute, join, sep } from "node:path";
+
+const isWindows = process.platform === "win32";
+
+/** Windows executable extensions, from `PATHEXT` with a sane fallback. */
+function pathExtensions(env: NodeJS.ProcessEnv): string[] {
+	if (!isWindows) return [""];
+	const raw = env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD";
+	// Leading "" lets an already-suffixed name (foo.exe) match as-is.
+	return ["", ...raw.split(";").filter(Boolean)];
+}
+
+/** Directories to scan, from `PATH`. Windows also probes the current directory first. */
+function pathDirs(env: NodeJS.ProcessEnv): string[] {
+	const raw = env.PATH ?? env.Path ?? "";
+	const dirs = raw.split(delimiter).filter(Boolean);
+	return isWindows ? [".", ...dirs] : dirs;
+}
+
+export interface FindExecutableOptions {
+	/** Environment to read PATH/PATHEXT from. Defaults to `process.env`. */
+	env?: NodeJS.ProcessEnv;
+}
+
+function candidatesFor(name: string, env: NodeJS.ProcessEnv): string[] {
+	const exts = pathExtensions(env);
+	const withExts = (base: string): string[] => exts.map((ext) => base + ext);
+	// A name with a separator (or absolute) is a direct path — do not scan PATH.
+	if (isAbsolute(name) || name.includes(sep) || (isWindows && name.includes("/"))) {
+		return withExts(name);
+	}
+	return pathDirs(env).flatMap((dir) => withExts(join(dir, name)));
+}
+
+function runnableSync(p: string): boolean {
+	try {
+		if (!statSync(p).isFile()) return false;
+		if (isWindows) return true;
+		accessSync(p, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function runnable(p: string): Promise<boolean> {
+	try {
+		const info = await stat(p);
+		if (!info.isFile()) return false;
+		if (isWindows) return true;
+		await access(p, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Find a runnable executable by name on PATH. Returns its path (as joined from
+ * PATH), or `undefined` when not found. Prefer {@link findExecutableSync} unless
+ * you specifically need to avoid blocking.
+ */
+export async function findExecutable(
+	name: string,
+	options: FindExecutableOptions = {},
+): Promise<string | undefined> {
+	if (!name) return undefined;
+	const env = options.env ?? process.env;
+	for (const candidate of candidatesFor(name, env)) {
+		if (await runnable(candidate)) return candidate;
+	}
+	return undefined;
+}
+
+/** Synchronous {@link findExecutable} — the common case (startup, gate checks). */
+export function findExecutableSync(
+	name: string,
+	options: FindExecutableOptions = {},
+): string | undefined {
+	if (!name) return undefined;
+	const env = options.env ?? process.env;
+	for (const candidate of candidatesFor(name, env)) {
+		if (runnableSync(candidate)) return candidate;
+	}
+	return undefined;
+}