@xynogen/pix-core 0.1.0

package/src/nudge/capability.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, test } from "bun:test";
+import {
+	buildOrientation,
+	CAPABILITY_REMINDER,
+	countInvocableSkills,
+	partitionTools,
+} from "./capability.ts";
+
+// Minimal Skill-shaped fixtures (only fields the builder reads).
+const skill = (
+	name: string,
+	description: string,
+	disableModelInvocation = false,
+) =>
+	({
+		name,
+		description,
+		disableModelInvocation,
+		filePath: "",
+		baseDir: "",
+		// biome-ignore lint: test fixture
+		sourceInfo: {} as never,
+	}) as never;
+
+// Minimal ToolInfo-shaped fixture.
+const tool = (name: string, source: string) =>
+	({
+		name,
+		description: `${name} desc.`,
+		parameters: {},
+		sourceInfo: { source, path: "", scope: "user", origin: "package" },
+		// biome-ignore lint: test fixture
+	}) as never;
+
+describe("CAPABILITY_REMINDER", () => {
+	test("is terse — fires every turn, must stay cheap", () => {
+		expect(CAPABILITY_REMINDER.split(/\s+/).length).toBeLessThanOrEqual(28);
+	});
+
+	test("names the core capability surfaces", () => {
+		for (const cap of ["skill", "tool", "MCP", "web", "user"]) {
+			expect(CAPABILITY_REMINDER).toContain(cap);
+		}
+	});
+
+	test("steers away from improvising", () => {
+		expect(CAPABILITY_REMINDER.toLowerCase()).toContain("improvis");
+	});
+
+	test("points at the toolbox tool for discovery", () => {
+		expect(CAPABILITY_REMINDER).toContain("toolbox");
+		expect(CAPABILITY_REMINDER).toContain("function definitions");
+	});
+});
+
+describe("countInvocableSkills", () => {
+	test("zero for undefined / empty", () => {
+		expect(countInvocableSkills(undefined)).toBe(0);
+		expect(countInvocableSkills([])).toBe(0);
+	});
+
+	test("excludes user-only skills", () => {
+		const n = countInvocableSkills([
+			skill("a", "."),
+			skill("b", ".", true),
+			skill("c", "."),
+		]);
+		expect(n).toBe(2);
+	});
+});
+
+describe("partitionTools", () => {
+	test("splits MCP-sourced from other tools by source", () => {
+		const { mcp, other } = partitionTools([
+			tool("read", "builtin"),
+			tool("context7-docs", "mcp:context7"),
+			tool("notion-search", "MCP server notion"),
+			tool("grep", "extension:pix-core"),
+		]);
+		expect(mcp).toBe(2);
+		expect(other).toBe(2);
+	});
+
+	test("handles undefined", () => {
+		expect(partitionTools(undefined)).toEqual({
+			mcp: 0,
+			other: 0,
+			active: 0,
+			gated: 0,
+		});
+	});
+
+	test("without an active set, every tool counts as active (gated 0)", () => {
+		const { active, gated } = partitionTools([
+			tool("read", "builtin"),
+			tool("ast_grep_search", "builtin"),
+		]);
+		expect(active).toBe(2);
+		expect(gated).toBe(0);
+	});
+
+	test("with an active set, splits active vs gated", () => {
+		const { active, gated } = partitionTools(
+			[
+				tool("read", "builtin"),
+				tool("grep", "builtin"),
+				tool("ast_grep_search", "builtin"),
+				tool("ctx_search", "builtin"),
+			],
+			["read", "grep"],
+		);
+		expect(active).toBe(2);
+		expect(gated).toBe(2);
+	});
+});
+
+describe("buildOrientation", () => {
+	test("summarizes counts of tools, MCP tools, and skills", () => {
+		const out = buildOrientation(
+			[tool("read", "builtin"), tool("ctx", "mcp:context7")],
+			[skill("commit", "Commit changes."), skill("plan", "Plan work.")],
+		);
+		expect(out).toContain("1 tool");
+		expect(out).toContain("1 MCP tool");
+		expect(out).toContain("2 skills");
+	});
+
+	test("explains how to explore via the toolbox tool", () => {
+		const out = buildOrientation([tool("read", "builtin")], []);
+		expect(out).toContain("toolbox(query");
+		expect(out.toLowerCase()).toMatch(/fuzzy|search|discover/);
+	});
+
+	test("calls out gated tools and points at toolbox to enable them", () => {
+		const out = buildOrientation(
+			[
+				tool("read", "builtin"),
+				tool("grep", "builtin"),
+				tool("ast_grep_search", "builtin"),
+				tool("ctx_search", "builtin"),
+			],
+			[],
+			["read", "grep"], // active set: 2 gated out
+		);
+		expect(out).toContain("2 are gated");
+		expect(out).toContain("enable via toolbox");
+	});
+
+	test("singular phrasing when exactly one tool is gated", () => {
+		const out = buildOrientation(
+			[tool("read", "builtin"), tool("ast_grep_search", "builtin")],
+			[],
+			["read"],
+		);
+		expect(out).toContain("1 is gated");
+		expect(out).toContain("enable via toolbox");
+	});
+
+	test("no gate line when nothing is gated", () => {
+		const out = buildOrientation(
+			[tool("read", "builtin"), tool("grep", "builtin")],
+			[],
+			["read", "grep"],
+		);
+		expect(out).not.toContain("gated out of the prompt");
+	});
+
+	test("no gate line when active set is unknown", () => {
+		const out = buildOrientation(
+			[tool("read", "builtin"), tool("ast_grep_search", "builtin")],
+			[],
+		);
+		expect(out).not.toContain("gated out of the prompt");
+	});
+
+	test("lists invocable skill names, sorted, excluding user-only", () => {
+		const out = buildOrientation(
+			[],
+			[
+				skill("zebra", "z."),
+				skill("alpha", "a."),
+				skill("hidden", "h.", true),
+			],
+		);
+		expect(out).toContain("Skills: alpha, zebra.");
+		expect(out).not.toContain("hidden");
+	});
+
+	test("omits the skills line when no invocable skills", () => {
+		const out = buildOrientation([tool("read", "builtin")], [skill("x", ".", true)]);
+		expect(out).not.toContain("Skills:");
+	});
+
+	test("steers away from improvising", () => {
+		const out = buildOrientation([tool("read", "builtin")], []);
+		expect(out.toLowerCase()).toContain("improvis");
+	});
+});

package/src/nudge/capability.ts

@@ -0,0 +1,152 @@
+/**
+ * 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`, emitted as ONE hidden message (`display: false`).
+ *
+ * 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 on demand via the `toolbox` tool. We deliberately
+ *      do NOT dump the whole inventory every turn — that is what `toolbox`
+ *      (fuzzy search over names + descriptions) is for.
+ *   2. EVERY subsequent prompt — the terse one-line CAPABILITY_REMINDER, a
+ *      cheap (~40 tok) reinforcement that points back at toolbox.
+ */
+
+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. */
+export const CAPABILITY_REMINDER =
+	"Reminder — always check your knowledge resources " +
+	"(skills/tools/MCP/web/user) before improvising. " +
+	"`toolbox(query)` finds the right one; enable gated tools via toolbox. " +
+	"All tools are always callable via function definitions.";
+
+/** 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 toolbox).
+ */
+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) — enable via toolbox to discover. 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.",
+		"toolbox is the gateway: `toolbox(query)` searches tools/MCP/skills/commands; `toolbox(action:'enable'|'disable', name)` toggles a gated tool prompt-visible or gated. Empty query lists all.",
+	);
+	if (skillNames.length) {
+		lines.push(`Skills: ${skillNames.join(", ")}.`);
+	}
+	return lines.join("\n");
+}
+
+export default function registerCapabilityNudge(pi: ExtensionAPI): void {
+	let orientationSent = false;
+
+	pi.on("before_agent_start", async (event) => {
+		const skills = event.systemPromptOptions?.skills;
+
+		let content: string;
+		if (!orientationSent) {
+			orientationSent = true;
+			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 {
+			content = CAPABILITY_REMINDER;
+		}
+
+		return {
+			message: {
+				customType: "pix-capability-nudge",
+				content,
+				display: false,
+			},
+		};
+	});
+}

package/src/nudge/index.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 registerToolsNudge from "./tools.ts";
+import registerCapabilityNudge from "./capability.ts";
+
+export default function registerNudges(pi: ExtensionAPI): void {
+	registerToolsNudge(pi);
+	registerCapabilityNudge(pi);
+}

package/src/nudge/tools.test.ts

@@ -0,0 +1,145 @@
+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);
+	});
+});