@xynogen/pix-core 0.2.4 → 0.3.0

package/src/nudge/capability.test.ts

@@ -1,258 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import registerCapabilityNudge, {
-	buildOrientation,
-	CAPABILITY_REMINDER,
-	countInvocableSkills,
-	graphifyHint,
-	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: "",
-		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" },
-	}) 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("nudges model to call read_skills() when a skill matches", () => {
-		expect(CAPABILITY_REMINDER).toContain("read_skills()");
-	});
-
-	test("does not mention user-only toolbox command", () => {
-		expect(CAPABILITY_REMINDER).not.toContain("/toolbox");
-		expect(CAPABILITY_REMINDER).not.toContain("toolbox(");
-	});
-});
-
-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("find", "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("find", "builtin"),
-				tool("ls", "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 use read_skills() without user-only toolbox", () => {
-		const out = buildOrientation([tool("read", "builtin")], []);
-		expect(out).toContain("read_skills()");
-		expect(out).not.toContain("/toolbox");
-		expect(out).not.toContain("toolbox(");
-	});
-
-	test("calls out gated tools and points at toolbox to enable them", () => {
-		const out = buildOrientation(
-			[
-				tool("read", "builtin"),
-				tool("grep", "builtin"),
-				tool("find", "builtin"),
-				tool("ls", "builtin"),
-			],
-			[],
-			["read", "grep"], // active set: 2 gated out
-		);
-		expect(out).toContain("2 are gated");
-		expect(out).toContain("function definitions");
-	});
-
-	test("singular phrasing when exactly one tool is gated", () => {
-		const out = buildOrientation(
-			[tool("read", "builtin"), tool("find", "builtin")],
-			[],
-			["read"],
-		);
-		expect(out).toContain("1 is gated");
-		expect(out).toContain("function definitions");
-	});
-
-	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("find", "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");
-	});
-
-	test("frames the block as non-actionable so the model acts on the prompt", () => {
-		const out = buildOrientation([tool("read", "builtin")], []);
-		const last = out.trim().split("\n").at(-1) ?? "";
-		expect(last.toLowerCase()).toContain("not a task");
-		expect(last.toLowerCase()).toContain("do not reply");
-	});
-});
-
-describe("registerCapabilityNudge", () => {
-	test("injects orientation into system prompt, not a custom message", async () => {
-		let handler: ((event: { systemPrompt?: string }) => unknown) | undefined;
-		const pi = {
-			on(event: string, fn: typeof handler) {
-				if (event === "before_agent_start") handler = fn;
-			},
-			getAllTools() {
-				return [tool("read", "builtin")];
-			},
-			getActiveTools() {
-				return ["read"];
-			},
-		} as never;
-
-		registerCapabilityNudge(pi);
-		const result = (await handler?.({ systemPrompt: "BASE" })) as {
-			systemPrompt?: string;
-			message?: unknown;
-		};
-
-		expect(result.message).toBeUndefined();
-		expect(result.systemPrompt).toStartWith("BASE\n\nToolbelt:");
-		expect(result.systemPrompt).toContain("Orientation only");
-	});
-});
-
-describe("graphifyHint", () => {
-	const tmpDir = join(import.meta.dir, ".graphify-hint-test-tmp");
-
-	test("returns undefined when graphify-out/graph.json absent", () => {
-		expect(graphifyHint(tmpDir)).toBeUndefined();
-	});
-
-	test("returns hint string when graphify-out/graph.json exists", () => {
-		try {
-			mkdirSync(join(tmpDir, "graphify-out"), { recursive: true });
-			writeFileSync(join(tmpDir, "graphify-out", "graph.json"), "{}");
-			const hint = graphifyHint(tmpDir);
-			expect(hint).toBeTypeOf("string");
-			expect(hint).toContain("graphify");
-			expect(hint).toContain("graphify query");
-		} finally {
-			rmSync(tmpDir, { recursive: true, force: true });
-		}
-	});
-});

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);
-	});
-});