@xynogen/pix-core 0.2.3 → 0.3.0

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

package/src/tool/ask/ask.test.ts

@@ -1,243 +0,0 @@
-/**
- * ask.test.ts — tests for the ask questionnaire tool
- *
- * Tests cover pure functions (schema validation, sentinel logic, answer
- * formatting). TUI components are not tested here.
- */
-
-import { describe, expect, test } from "bun:test";
-import {
-	buildResponseText,
-	formatAnswerScalar,
-	hasAnyPreview,
-	type OptionData,
-	type QuestionData,
-	sentinelsFor,
-} from "./index.ts";
-
-// ── Fixtures ──────────────────────────────────────────────────────────
-
-const opt = (
-	label: string,
-	description = "Test option",
-	preview?: string,
-): OptionData => ({
-	label,
-	description,
-	...(preview ? { preview } : {}),
-});
-
-const qSingle: QuestionData = {
-	question: "Which approach?",
-	header: "Approach",
-	options: [
-		opt("REST", "Traditional REST API"),
-		opt("GraphQL", "Query language for APIs"),
-	],
-};
-
-const qMulti: QuestionData = {
-	question: "Which features?",
-	header: "Features",
-	options: [
-		opt("Auth", "User authentication"),
-		opt("Search", "Full text search"),
-		opt("Export", "Data export"),
-	],
-	multiSelect: true,
-};
-
-const qWithPreview: QuestionData = {
-	question: "Pick a component?",
-	header: "Component",
-	options: [
-		opt("Button", "Clickable button", "<Button>Primary</Button>"),
-		opt("Card", "Container card", "<Card><Content/></Card>"),
-	],
-};
-
-const qSingleNoPreview: QuestionData = {
-	question: "Color?",
-	header: "Color",
-	options: [opt("Red", "Ruby red"), opt("Blue", "Ocean blue")],
-};
-
-// ── hasAnyPreview ─────────────────────────────────────────────────────
-
-describe("hasAnyPreview", () => {
-	test("returns false when no option has preview", () => {
-		expect(hasAnyPreview(qSingle)).toBe(false);
-		expect(hasAnyPreview(qMulti)).toBe(false);
-	});
-
-	test("returns true when at least one option has preview", () => {
-		expect(hasAnyPreview(qWithPreview)).toBe(true);
-	});
-
-	test("returns false for empty options", () => {
-		const q: QuestionData = { question: "?", header: "X", options: [] };
-		expect(hasAnyPreview(q)).toBe(false);
-	});
-});
-
-// ── sentinelsFor ──────────────────────────────────────────────────────
-
-describe("sentinelsFor", () => {
-	test('single-select without preview appends "Type something."', () => {
-		const r = sentinelsFor(qSingleNoPreview);
-		expect(r).toHaveLength(1);
-		expect(r[0]?.kind).toBe("other");
-		expect(r[0]?.label).toBe("Type something.");
-	});
-
-	test('single-select with preview appends nothing (only "Chat about this" is separate)', () => {
-		const r = sentinelsFor(qWithPreview);
-		expect(r).toHaveLength(0);
-	});
-
-	test('multi-select appends "Next"', () => {
-		const r = sentinelsFor(qMulti);
-		expect(r).toHaveLength(1);
-		expect(r[0]?.kind).toBe("next");
-		expect(r[0]?.label).toBe("Next");
-	});
-
-	test("multi-select never appends Type something.", () => {
-		const r = sentinelsFor({ ...qMulti, multiSelect: true });
-		expect(r.every((s) => s.kind !== "other")).toBe(true);
-	});
-
-	test("empty options still gets freeform sentinel (no preview = single-select)", () => {
-		const r = sentinelsFor({ question: "?", header: "X", options: [] });
-		expect(r).toHaveLength(1);
-		expect(r[0]?.kind).toBe("other");
-	});
-});
-
-// ── formatAnswerScalar ────────────────────────────────────────────────
-
-describe("formatAnswerScalar", () => {
-	test("option kind returns the answer string", () => {
-		const a = {
-			questionIndex: 0,
-			question: "Q",
-			kind: "option" as const,
-			answer: "REST",
-		};
-		expect(formatAnswerScalar(a)).toBe("REST");
-	});
-
-	test("multi kind joins selected with comma", () => {
-		const a = {
-			questionIndex: 0,
-			question: "Q",
-			kind: "multi" as const,
-			answer: null,
-			selected: ["Auth", "Search"],
-		};
-		expect(formatAnswerScalar(a)).toBe("Auth, Search");
-	});
-
-	test("custom kind returns the typed text", () => {
-		const a = {
-			questionIndex: 0,
-			question: "Q",
-			kind: "custom" as const,
-			answer: "my custom answer",
-		};
-		expect(formatAnswerScalar(a)).toBe("my custom answer");
-	});
-
-	test("chat kind returns (chat)", () => {
-		const a = {
-			questionIndex: 0,
-			question: "Q",
-			kind: "chat" as const,
-			answer: null,
-		};
-		expect(formatAnswerScalar(a)).toBe("(chat)");
-	});
-});
-
-// ── buildResponseText ─────────────────────────────────────────────────
-
-describe("buildResponseText", () => {
-	test("formats single answer", () => {
-		const answers = [
-			{
-				questionIndex: 0,
-				question: "Which approach?",
-				kind: "option" as const,
-				answer: "REST",
-			},
-		];
-		const text = buildResponseText(answers, [qSingle]);
-		expect(text).toContain("REST");
-		expect(text).toContain("Which approach?");
-	});
-
-	test("formats multi-select answer", () => {
-		const answers = [
-			{
-				questionIndex: 0,
-				question: "Which features?",
-				kind: "multi" as const,
-				answer: null,
-				selected: ["Auth", "Search"],
-			},
-		];
-		const text = buildResponseText(answers, [qMulti]);
-		expect(text).toContain("Auth, Search");
-		expect(text).toContain("Which features?");
-	});
-
-	test("includes preview in response when present", () => {
-		const answers = [
-			{
-				questionIndex: 0,
-				question: "Pick a component?",
-				kind: "option" as const,
-				answer: "Button",
-				preview: "<Button>Primary</Button>",
-			},
-		];
-		const text = buildResponseText(answers, [qWithPreview]);
-		expect(text).toContain("preview: <Button>Primary</Button>");
-	});
-
-	test("formats multiple answers", () => {
-		const qs = [qSingle, qMulti];
-		const answers = [
-			{
-				questionIndex: 0,
-				question: "Which approach?",
-				kind: "option" as const,
-				answer: "GraphQL",
-			},
-			{
-				questionIndex: 1,
-				question: "Which features?",
-				kind: "multi" as const,
-				answer: null,
-				selected: ["Export"],
-			},
-		];
-		const text = buildResponseText(answers, qs);
-		expect(text).toContain("GraphQL");
-		expect(text).toContain("Export");
-	});
-
-	test("shows declined message when no answers", () => {
-		const text = buildResponseText([], [qSingle]);
-		expect(text).toContain("declined");
-	});
-});
-
-// ── Tool registration shape ─────────────────────────────────────────
-
-describe("registerAsk", () => {
-	test("exports a default function", async () => {
-		const mod = await import("./index.ts");
-		expect(typeof mod.default).toBe("function");
-	});
-});

package/src/tool/ask/components.ts

@@ -1,55 +0,0 @@
-import type { Theme } from "@earendil-works/pi-coding-agent";
-import { type Component, truncateToWidth } from "@earendil-works/pi-tui";
-import type { QuestionData } from "./schema.js";
-
-// ── Color helpers ──────────────────────────────────────────────────────
-
-export function borderColor(theme: Theme): (s: string) => string {
-	return (s: string) => theme.fg("accent", s);
-}
-
-export function dim(theme: Theme): (s: string) => string {
-	return (s: string) => theme.fg("dim", s);
-}
-
-// ── TabBar ─────────────────────────────────────────────────────────────
-
-export class TabBar implements Component {
-	private questions: QuestionData[];
-	private activeIndex: number;
-	private theme: Theme;
-
-	constructor(questions: QuestionData[], activeIndex: number, theme: Theme) {
-		this.questions = questions;
-		this.activeIndex = activeIndex;
-		this.theme = theme;
-	}
-
-	invalidate(): void {}
-
-	render(width: number): string[] {
-		const t = this.theme;
-		const inner = Math.max(10, width - 2);
-
-		const parts: string[] = [];
-		for (let i = 0; i < this.questions.length; i++) {
-			const active = i === this.activeIndex;
-			const num = `${i + 1}`;
-			const tag = `${num}.${this.questions[i]?.header}`;
-			parts.push(active ? t.fg("accent", t.bold(tag)) : t.fg("dim", tag));
-		}
-		const line = parts.join(t.fg("dim", "  "));
-		return [
-			truncateToWidth(
-				t.fg("accent", "╭─") +
-					line +
-					t.fg(
-						"accent",
-						`${"─".repeat(Math.max(0, inner - line.length - 1))}╮`,
-					),
-				width,
-				"",
-			),
-		].filter(Boolean);
-	}
-}

package/src/tool/ask/helpers.ts

@@ -1,77 +0,0 @@
-import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
-import type { MarkdownTheme } from "@earendil-works/pi-tui";
-import type { OptionData, QuestionData } from "./schema.js";
-import { SENTINEL_CHAT, SENTINEL_FREEFORM, SENTINEL_NEXT } from "./schema.js";
-import type { AnswerKind, QuestionAnswer } from "./types.js";
-
-// ── Markdown theme ─────────────────────────────────────────────────────
-
-export function safeMarkdownTheme(): MarkdownTheme | undefined {
-	try {
-		const md = getMarkdownTheme();
-		if (!md) return undefined;
-		md.bold("");
-		return md;
-	} catch {
-		return undefined;
-	}
-}
-
-// ── Option / question helpers ──────────────────────────────────────────
-
-export function hasAnyPreview(q: QuestionData): boolean {
-	return q.options.some(
-		(o) => typeof o.preview === "string" && o.preview.length > 0,
-	);
-}
-
-/** Which sentinel rows are auto-appended for a question. */
-export function sentinelsFor(
-	q: QuestionData,
-): Array<{ kind: string; label: string }> {
-	const out: Array<{ kind: string; label: string }> = [];
-	if (q.multiSelect) {
-		out.push({ kind: "next", label: SENTINEL_NEXT });
-	} else if (!hasAnyPreview(q)) {
-		out.push({ kind: "other", label: SENTINEL_FREEFORM });
-	}
-	return out;
-}
-
-// ── Answer formatting ──────────────────────────────────────────────────
-
-export function formatAnswerScalar(a: QuestionAnswer): string {
-	if (a.kind === "multi") return (a.selected ?? []).join(", ");
-	if (a.kind === "custom") return a.answer ?? "(custom)";
-	if (a.kind === "chat") return "(chat)";
-	return a.answer ?? "(selected)";
-}
-
-export function buildResponseText(
-	answers: QuestionAnswer[],
-	questions: QuestionData[],
-): string {
-	const segs: string[] = [];
-	for (const a of answers) {
-		const q = questions[a.questionIndex]?.question ?? `Q${a.questionIndex + 1}`;
-		let s = `"${q}"="${formatAnswerScalar(a)}"`;
-		if (a.preview) s += `. selected preview: ${a.preview}`;
-		segs.push(s);
-	}
-	return segs.length
-		? `User answered: ${segs.join(". ")}.`
-		: "User declined to answer questions.";
-}
-
-// ── Scroll indicator ───────────────────────────────────────────────────
-
-export function scrollIndicator(index: number, total: number): string {
-	if (total <= 1) return "";
-	const pos = Math.round((index / (total - 1)) * 6);
-	const bar = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦"][pos] ?? "·";
-	return ` ${bar} ${index + 1}/${total}`;
-}
-
-export type { AnswerKind, OptionData, QuestionData };
-// Re-export sentinel constants so callers don't need to import schema directly
-export { SENTINEL_CHAT, SENTINEL_FREEFORM, SENTINEL_NEXT };