@xynogen/pix-core 0.2.4 → 0.3.1

package/src/nudge/capability.ts

@@ -1,189 +0,0 @@
-/**
- * capability-nudge.ts — orient the model to its full toolbelt
- *
- * Models drift toward improvising mid-session, forgetting they can ask the
- * user, search the web, pull library docs (context7), use LSP, or invoke an
- * Agent Skill instead of guessing. Fires on EVERY user prompt via
- * `before_agent_start`, injected into the system prompt for the turn.
- *
- * Two modes:
- *   1. FIRST prompt of the session — an orientation block: a high-level
- *      description of WHAT is available (counts of tools / MCP tools / skills)
- *      and HOW to explore it. We deliberately do NOT dump the whole inventory
- *      every turn — the model should call read_skills() for skills and use /toolbox
- *      (slash command, user-facing) to discover/enable gated tools.
- *   2. EVERY subsequent prompt — the terse one-line CAPABILITY_REMINDER, a
- *      cheap (~40 tok) reinforcement that steers toward read_skills() and /toolbox.
- *
- * NOTE: `toolbox` is a slash command only (/toolbox) — NOT a model-callable
- * function tool. The model cannot call toolbox() in function definitions.
- * The `read_skills` tool IS model-callable: read_skills() lists/loads bundled skills.
- */
-
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import type {
-	BuildSystemPromptOptions,
-	ExtensionAPI,
-	ToolInfo,
-} from "@earendil-works/pi-coding-agent";
-
-type LoadedSkill = NonNullable<BuildSystemPromptOptions["skills"]>[number];
-
-/** The standing per-turn reminder. Kept terse — it ships on every turn. */
-/** How often (in turns after the first) to re-send the capability reminder. */
-const REMINDER_INTERVAL = 10;
-
-export const CAPABILITY_REMINDER =
-	"Reminder — check knowledge resources " +
-	"(skills/tools/MCP/web/user) before improvising. " +
-	"Matching skill? Call read_skills() first.";
-
-/**
- * Build the optional graphify hint line.
- * Returns a string if graphify-out/graph.json exists in cwd, else undefined.
- */
-export function graphifyHint(cwd: string): string | undefined {
-	if (existsSync(join(cwd, "graphify-out", "graph.json"))) {
-		return (
-			"graphify-out/graph.json exists — for codebase questions (how does X work, " +
-			'where is Y, trace Z) run `graphify query "<question>"` before reading files.'
-		);
-	}
-	return undefined;
-}
-
-/** Count model-invocable skills (excludes user-only /skill:name entries). */
-export function countInvocableSkills(
-	skills: LoadedSkill[] | undefined,
-): number {
-	return (skills ?? []).filter((s) => !s.disableModelInvocation).length;
-}
-
-/**
- * Split tools by source (MCP vs other) and, when an `active` set is supplied,
- * by gate status (active = schema in the prompt now; gated = registered but
- * gated out, reachable only via toolbox). Without `active`, everything counts
- * as active (gated = 0) so callers that don't track the gate are unaffected.
- */
-export function partitionTools(
-	tools: ToolInfo[] | undefined,
-	active?: Iterable<string>,
-): {
-	mcp: number;
-	other: number;
-	active: number;
-	gated: number;
-} {
-	const activeSet = active ? new Set(active) : undefined;
-	let mcp = 0;
-	let other = 0;
-	let activeCount = 0;
-	let gated = 0;
-	for (const t of tools ?? []) {
-		if (/mcp/i.test(t.sourceInfo?.source ?? "")) mcp++;
-		else other++;
-		// A tool is "gated" only when we have an active set and it's absent from it.
-		if (activeSet && !activeSet.has(t.name)) gated++;
-		else activeCount++;
-	}
-	return { mcp, other, active: activeCount, gated };
-}
-
-/**
- * Build the one-time orientation block shown on the FIRST prompt. Describes the
- * shape of the toolbelt (counts) and how to explore it via `toolbox`, plus the
- * sorted skill names so the model knows what exists by name without a dump of
- * descriptions (those live in the system prompt / are searchable via tools).
- */
-export function buildOrientation(
-	tools: ToolInfo[] | undefined,
-	skills: LoadedSkill[] | undefined,
-	/** Currently-active tool names; absent ⇒ gate not tracked (all treated active). */
-	activeToolNames?: Iterable<string>,
-): string {
-	const { mcp, other, gated } = partitionTools(tools, activeToolNames);
-	const skillNames = (skills ?? [])
-		.filter((s) => !s.disableModelInvocation)
-		.map((s) => s.name)
-		.sort();
-
-	const inventory: string[] = [];
-	if (other) inventory.push(`${other} tool${other === 1 ? "" : "s"}`);
-	if (mcp) inventory.push(`${mcp} MCP tool${mcp === 1 ? "" : "s"}`);
-	if (skillNames.length)
-		inventory.push(
-			`${skillNames.length} skill${skillNames.length === 1 ? "" : "s"}`,
-		);
-	const summary = inventory.length ? inventory.join(", ") : "your toolbelt";
-
-	// Lead with the gate — tools not described in the prompt are still callable
-	// via function definitions, but the model doesn't know about them.
-	const gateLine = gated
-		? `${gated} ${gated === 1 ? "is" : "are"} gated (kept out of the prompt to save context). All tools are always callable via function definitions.`
-		: undefined;
-
-	const lines = [
-		`Toolbelt: ${summary}, plus LSP, MCP (context7 docs), web search/fetch, and the user.`,
-	];
-	if (gateLine) lines.push(gateLine);
-	lines.push(
-		"Don't improvise what a capability covers — ask the user, search the web, or pull docs first.",
-		"`read_skills()` lists/loads bundled skills — call it when a skill matches your task.",
-	);
-	if (skillNames.length) {
-		lines.push(`Skills: ${skillNames.join(", ")}.`);
-	}
-	// Graphify hint — only when a graph is already built for this project
-	const gHint = graphifyHint(process.cwd());
-	if (gHint) lines.push(gHint);
-	// Framing — this block is orientation context, not a task. Without it the
-	// model can mistake the first-turn orientation for the prompt and reply
-	// "Ready, waiting for task" instead of acting on the user's request.
-	lines.push(
-		"(Orientation only — not a task. Act on the user's request now; do not reply to this notice.)",
-	);
-	return lines.join("\n");
-}
-
-export default function registerCapabilityNudge(pi: ExtensionAPI): void {
-	let turnCount = 0;
-
-	pi.on("before_agent_start", async (event) => {
-		const skills = event.systemPromptOptions?.skills;
-		turnCount++;
-
-		let content: string;
-		if (turnCount === 1) {
-			let tools: ToolInfo[] | undefined;
-			try {
-				tools = pi.getAllTools();
-			} catch {
-				tools = undefined;
-			}
-			// Active set lets the orientation distinguish callable-now from gated.
-			// getActiveTools() returns string[] (tool NAMES) — not ToolInfo[]. Use as-is.
-			let activeToolNames: string[] | undefined;
-			try {
-				activeToolNames = pi.getActiveTools();
-			} catch {
-				activeToolNames = undefined;
-			}
-			content = buildOrientation(tools, skills, activeToolNames);
-		} else if (turnCount % REMINDER_INTERVAL === 1) {
-			// Fire reminder every REMINDER_INTERVAL turns (turn 11, 21, ...)
-			const cwd = process.cwd();
-			const gHint = graphifyHint(cwd);
-			content = gHint
-				? `${CAPABILITY_REMINDER}\n${gHint}`
-				: CAPABILITY_REMINDER;
-		} else {
-			return; // no nudge this turn
-		}
-
-		const existing = event.systemPrompt ?? "";
-		const systemPrompt = existing ? `${existing}\n\n${content}` : content;
-
-		return { systemPrompt };
-	});
-}

package/src/nudge/index.ts

@@ -1,17 +0,0 @@
-/**
- * nudge/ — model-steering reminders, wired by one registerNudges(pi).
- *
- *   - tools      — block raw bash that stands in for a native tool (reactive,
- *                  per tool_call, once per category). See tools.ts.
- *   - capability — full-toolbelt one-liner + dynamic skill-name list on every
- *                  prompt (one hidden message). See capability.ts.
- */
-
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import registerCapabilityNudge from "./capability.ts";
-import registerToolsNudge from "./tools.ts";
-
-export default function registerNudges(pi: ExtensionAPI): void {
-	registerToolsNudge(pi);
-	registerCapabilityNudge(pi);
-}

package/src/nudge/tools.test.ts

@@ -1,157 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import {
-	classify,
-	classifyCompound,
-	nudgeReason,
-	splitSegments,
-} from "./tools.ts";
-
-describe("classify", () => {
-	test("maps cat/head/tail/less to read", () => {
-		for (const c of ["cat foo.ts", "head -5 a", "tail -f log", "less x"]) {
-			expect(classify(c)?.category).toBe("read");
-		}
-	});
-
-	test("maps ls/tree to ls", () => {
-		expect(classify("ls -la")?.category).toBe("ls");
-		expect(classify("tree src")?.category).toBe("ls");
-	});
-
-	test("maps grep/rg to grep", () => {
-		expect(classify("grep foo bar.ts")?.category).toBe("grep");
-		expect(classify("rg pattern")?.category).toBe("grep");
-	});
-
-	test("maps find/fd to find", () => {
-		expect(classify("find . -name x")?.category).toBe("find");
-		expect(classify("fd '*.ts'")?.category).toBe("find");
-	});
-
-	test("maps sed -i to edit, but plain sed is allowed", () => {
-		expect(classify("sed -i 's/a/b/' f")?.category).toBe("edit");
-		expect(classify("sed 's/a/b/' f")).toBeUndefined();
-	});
-
-	test("strips env-var prefix before matching", () => {
-		expect(classify("FOO=bar grep x y")?.category).toBe("grep");
-	});
-
-	test("unaliases leading backslash", () => {
-		expect(classify("\\grep x y")?.category).toBe("grep");
-	});
-
-	test("ignores compound / piped / redirected commands", () => {
-		expect(classify("cat a | grep b")).toBeUndefined();
-		expect(classify("grep x y > out")).toBeUndefined();
-		expect(classify("ls && echo done")).toBeUndefined();
-		expect(classify("cat $(ls)")).toBeUndefined();
-		expect(classify("ls; pwd")).toBeUndefined();
-	});
-
-	test("ignores non-tool commands and empty input", () => {
-		expect(classify("git status")).toBeUndefined();
-		expect(classify("npm test")).toBeUndefined();
-		expect(classify("")).toBeUndefined();
-		expect(classify("   ")).toBeUndefined();
-	});
-});
-
-describe("splitSegments", () => {
-	test("records the operator following each segment", () => {
-		expect(splitSegments("cat x | jq .")).toEqual([
-			{ text: "cat x ", followedBy: "|" },
-			{ text: " jq .", followedBy: "" },
-		]);
-		expect(splitSegments("cat x || ls y")).toEqual([
-			{ text: "cat x ", followedBy: "||" },
-			{ text: " ls y", followedBy: "" },
-		]);
-	});
-
-	test("drops empty segments", () => {
-		expect(splitSegments("ls;")).toEqual([{ text: "ls", followedBy: ";" }]);
-	});
-});
-
-describe("classifyCompound", () => {
-	test("still classifies simple commands", () => {
-		expect(classifyCompound("cat foo")?.category).toBe("read");
-		expect(classifyCompound("git status")).toBeUndefined();
-	});
-
-	test("catches the chaining-dodge (|| && ;)", () => {
-		// seg1 `cat x 2>/dev/null` has a redirect (opaque per-segment); seg2
-		// `ls -la` is a clean stand-in — still nudged, as `ls`.
-		expect(classifyCompound("cat x 2>/dev/null || ls -la")?.category).toBe(
-			"ls",
-		);
-		// Pure clean read stand-in chained with another clean cmd.
-		expect(classifyCompound("cat x || ls -la")?.category).toBe("read");
-		expect(classifyCompound("ls -la && echo done")?.category).toBe("ls");
-		expect(classifyCompound("ls; pwd")?.category).toBe("ls");
-		expect(classifyCompound("true && grep foo bar.ts")?.category).toBe("grep");
-	});
-
-	test("exempts a segment that feeds a pipe (legit producer)", () => {
-		expect(classifyCompound("cat x | jq .")).toBeUndefined();
-		expect(classifyCompound("grep foo a | head")).toBeUndefined();
-	});
-
-	test("exempts redirects per-segment", () => {
-		expect(classifyCompound("grep x y > out")).toBeUndefined();
-	});
-
-	test("exempts when no segment is a leading stand-in", () => {
-		expect(classifyCompound("git log | cat")).toBeUndefined();
-		expect(classifyCompound("npm test && npm run build")).toBeUndefined();
-	});
-
-	test("empty / whitespace", () => {
-		expect(classifyCompound("")).toBeUndefined();
-		expect(classifyCompound("   ")).toBeUndefined();
-	});
-});
-
-describe("nudgeReason", () => {
-	test("active tool: point straight at it, no toolbox", () => {
-		const msg = nudgeReason(
-			"Searching file contents via bash grep/rg.",
-			"grep",
-			true,
-		);
-		expect(msg).toContain("Use `grep` instead");
-		expect(msg).toContain("function definitions");
-		expect(msg).not.toContain("toolbox");
-	});
-
-	test("gated tool: route through toolbox enable, not a direct call", () => {
-		const msg = nudgeReason(
-			"Listing a directory via bash ls/tree.",
-			"ls",
-			false,
-		);
-		expect(msg).toContain('toolbox(action:"enable", name:"ls")');
-		expect(msg).toContain("prompt-hidden");
-		expect(msg).toContain("function definitions");
-		// Must NOT imply the tool is directly callable by name (it's prompt-hidden).
-		expect(msg).not.toContain("Use `ls` instead");
-	});
-
-	test("gated find tool names itself in the enable hint", () => {
-		expect(
-			nudgeReason("Locating files via bash find/fd.", "find", false),
-		).toContain('toolbox(action:"enable", name:"find")');
-	});
-
-	test("is a single short line — no inventory dump, no newlines", () => {
-		const msg = nudgeReason(
-			"Listing a directory via bash ls/tree.",
-			"ls",
-			false,
-		);
-		expect(msg).not.toContain("\n");
-		expect(msg).not.toContain("Available tools");
-		expect(msg.length).toBeLessThan(400);
-	});
-});

package/src/nudge/tools.ts

@@ -1,212 +0,0 @@
-/**
- * tools-nudge.ts — nudge the model toward dedicated tools over raw bash
- *
- * Hooks `tool_call` for the built-in `bash` tool. When a bash command merely
- * reimplements a first-class tool (read/ls/grep/find/edit/write), it blocks the
- * call ONCE per command-category per session with a guidance reason. The model
- * retries using the proper tool — improving token usage and enforcing stricter,
- * more predictable behavior. After the first nudge for a category, subsequent
- * bash calls in that category are allowed (no nag loop). Bash stays available
- * for everything else (pipes, compound commands, real shell work).
- *
- * IMPORTANT: some target tools (e.g. `ls`, `find`) are GATED from the system
- * prompt — registered but prompt-hidden until the model discovers them via
- * toolbox. They ARE still in the function-calling definitions (always callable).
- * The nudge checks `pi.getActiveTools()` first: if the tool is prompt-visible,
- * recommend it directly; if it is gated, tell the model to enable it via toolbox
- * but note that all tools are always callable via function definitions.
- *
- * The nudge is deliberately SURGICAL: it names only the single tool that maps
- * to the command just blocked. It does NOT dump a full tool inventory — that
- * floods the model with gated tools it can't call and is the opposite of the
- * lazy-gate's purpose (a lean prompt). Point at the one right tool; don't list
- * the menu.
- */
-
-import {
-	type ExtensionAPI,
-	isToolCallEventType,
-} from "@earendil-works/pi-coding-agent";
-
-/** Categories that map a raw shell command to a dedicated Pi tool. */
-type Category = "read" | "ls" | "grep" | "find" | "edit";
-
-interface Rule {
-	category: Category;
-	/** Match the *leading* command word(s). */
-	test: (cmd: string) => boolean;
-	tool: string;
-	reason: string;
-}
-
-/** First bare word of a command segment (strips env-var prefixes like FOO=bar). */
-const leadWord = (segment: string): string => {
-	const toks = segment.trim().split(/\s+/);
-	let i = 0;
-	while (i < toks.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(toks[i])) i++;
-	return (toks[i] ?? "").replace(/^\\/, ""); // unalias e.g. \grep
-};
-
-const RULES: Rule[] = [
-	{
-		category: "read",
-		test: (c) => /^(cat|head|tail|less|more|bat)$/.test(leadWord(c)),
-		tool: "read",
-		reason: "Reading a file via bash cat/head/tail.",
-	},
-	{
-		category: "ls",
-		test: (c) => /^(ls|tree|exa|eza)$/.test(leadWord(c)),
-		tool: "ls",
-		reason: "Listing a directory via bash ls/tree.",
-	},
-	{
-		category: "grep",
-		test: (c) => /^(grep|rg|ag|ack)$/.test(leadWord(c)),
-		tool: "grep",
-		reason: "Searching file contents via bash grep/rg.",
-	},
-	{
-		category: "find",
-		test: (c) => /^(find|fd|fdfind)$/.test(leadWord(c)),
-		tool: "find",
-		reason: "Locating files via bash find/fd.",
-	},
-	{
-		category: "edit",
-		test: (c) => /^sed$/.test(leadWord(c)) && /\s-i\b/.test(c),
-		tool: "edit",
-		reason: "Editing a file in place via bash `sed -i`.",
-	},
-];
-
-/**
- * Pick a rule only when the command is a *simple* single-command invocation
- * standing in for a tool. Skip anything with pipes, redirects, command
- * chaining, or subshells — those are legitimate shell work bash should handle.
- */
-export function classify(command: string): Rule | undefined {
-	const cmd = command.trim();
-	if (!cmd) return undefined;
-	// Bail on compound / piped / redirected commands — real shell work.
-	if (/[|&;]|\$\(|`|<|>|\n/.test(cmd)) return undefined;
-	return RULES.find((r) => r.test(cmd));
-}
-
-/**
- * A segment of a compound command, paired with the operator that *follows* it.
- * The trailing operator distinguishes a stand-in (`cat x ||`, `cat x ;`) from a
- * genuine pipe producer (`cat x |`) whose output feeds a downstream consumer.
- */
-interface Segment {
-	text: string;
-	/** Operator immediately after this segment: "|", ";", "&&", "||", "&", or "". */
-	followedBy: string;
-}
-
-/**
- * Split a command line into segments on shell control operators, recording the
- * operator that follows each segment. Subshells and redirects are NOT split —
- * a segment containing `$(...)`, backticks, or a redirect is treated as opaque
- * shell work and will fail the single-command `classify` check below.
- */
-export function splitSegments(command: string): Segment[] {
-	const out: Segment[] = [];
-	const re = /(\|\||&&|[|;&\n])/g;
-	let last = 0;
-	let m: RegExpExecArray | null;
-	while ((m = re.exec(command)) !== null) {
-		out.push({ text: command.slice(last, m.index), followedBy: m[1] });
-		last = m.index + m[1].length;
-	}
-	out.push({ text: command.slice(last), followedBy: "" });
-	return out.filter((s) => s.text.trim().length > 0);
-}
-
-/**
- * Classify a possibly-compound command. Returns the FIRST rule matching a
- * segment that is a *pure tool stand-in*: a simple single-command invocation
- * whose output is not piped into a downstream consumer.
- *
- * - `cat x || ls y`      → nudge (read) — chaining-dodge, not real shell work.
- * - `ls; pwd`            → nudge (ls)  — sequential stand-in alongside other cmd.
- * - `cat x | jq .`       → undefined   — `cat` feeds a pipe; legitimate.
- * - `grep x y > out`     → undefined   — redirect; opaque per-segment.
- * - `git log | cat`      → undefined   — no segment is a leading stand-in.
- */
-export function classifyCompound(command: string): Rule | undefined {
-	const cmd = command.trim();
-	if (!cmd) return undefined;
-
-	// Fast path: a truly simple command (no operators/subshell/redirect).
-	const simple = classify(cmd);
-	if (simple) return simple;
-
-	// Otherwise inspect each segment of the compound command. A segment is a
-	// legitimate part of a pipeline — not a stand-in — when it either feeds a
-	// pipe (producer) or is fed by one (consumer). Only segments outside any
-	// pipe relationship are candidate tool stand-ins.
-	const segs = splitSegments(cmd);
-	for (let i = 0; i < segs.length; i++) {
-		const seg = segs[i];
-		if (seg.followedBy === "|") continue; // producer feeding a pipe
-		if (i > 0 && segs[i - 1].followedBy === "|") continue; // consumer of a pipe
-		// Per-segment we reuse the strict single-command classifier, which itself
-		// rejects redirects/subshells/nested operators inside the segment.
-		const rule = classify(seg.text);
-		if (rule) return rule;
-	}
-	return undefined;
-}
-
-/**
- * Build the one-line guidance for a nudge. When the target tool is active, point
- * straight at it. When it's gated out, point at toolbox to enable it — never
- * imply a gated tool is callable now. Pure + exported for unit testing.
- */
-export function nudgeReason(
-	baseReason: string,
-	tool: string,
-	toolActive: boolean,
-): string {
-	const how = toolActive
-		? `Use \`${tool}\` instead — it's in the function definitions, call it directly.`
-		: `\`${tool}\` is prompt-hidden — enable it via toolbox(action:"enable", name:"${tool}") to make it known, then call it; bash is fine until then. (All tools are always callable via function definitions.)`;
-	return `${baseReason} ${how} (Fires once per category; bash stays available for pipes & compound commands.)`;
-}
-
-export default function registerToolsNudge(pi: ExtensionAPI): void {
-	// Categories already nudged this session — block once, then allow.
-	const nudged = new Set<Category>();
-
-	/** Is `name` in the host's current active set (i.e. callable right now)? */
-	function isActive(name: string): boolean {
-		try {
-			// getActiveTools() returns string[] (tool NAMES), not ToolInfo[].
-			return (pi.getActiveTools() ?? []).includes(name);
-		} catch {
-			// If we can't tell, assume active so we don't suppress a valid nudge.
-			return true;
-		}
-	}
-
-	pi.on("tool_call", async (event) => {
-		if (!isToolCallEventType("bash", event)) return;
-		const command = event.input.command;
-		if (typeof command !== "string") return;
-
-		const rule = classifyCompound(command);
-		if (!rule) return;
-		if (nudged.has(rule.category)) return; // already taught — allow.
-
-		nudged.add(rule.category);
-
-		// One short, targeted line: name only the tool that maps to THIS command,
-		// and route through toolbox when it's gated rather than implying it's
-		// callable now. No full-inventory dump — that's what confused the model.
-		return {
-			block: true,
-			reason: nudgeReason(rule.reason, rule.tool, isActive(rule.tool)),
-		};
-	});
-}