@xynogen/pix-core 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-core",
-	"version": "0.1.1",
+	"version": "0.1.2",
 	"description": "Pi extension — core UI/UX bundle (welcome banner, footer, model picker, self-update)",
 	"type": "module",
 	"main": "src/index.ts",
@@ -42,6 +42,7 @@
 		"access": "public"
 	},
 	"dependencies": {
+		"@xynogen/pix-skills": "^0.1.1",
 		"typebox": "^1.1.38"
 	},
 	"peerDependencies": {

package/src/commands/agent-sop/agent-sop.ts

@@ -0,0 +1,58 @@
+/**
+ * agent-sop — inject AGENT.md (from pix-skills) into system prompt
+ *
+ * Reads AGENT.md from the @xynogen/pix-skills package and appends it to the
+ * system prompt on every agent start via `before_agent_start`.
+ *
+ * This is the "register skill" mechanism for the agent operating spec — no
+ * static SKILL.md file needed. The content becomes part of the model's
+ * standing instructions.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/** Resolve the absolute path to AGENT.md inside @xynogen/pix-skills. */
+function resolveAgentMdPath(): string | null {
+	try {
+		const require = createRequire(import.meta.url);
+		const pkgJson = require.resolve("@xynogen/pix-skills/package.json");
+		return resolve(pkgJson, "..", "AGENT.md");
+	} catch {
+		return null;
+	}
+}
+
+/** Read and return AGENT.md content, or null if unavailable. */
+function loadAgentMd(): string | null {
+	const p = resolveAgentMdPath();
+	if (!p || !existsSync(p)) return null;
+	try {
+		return readFileSync(p, "utf-8");
+	} catch {
+		return null;
+	}
+}
+
+export default function registerAgentSop(pi: ExtensionAPI): void {
+	// Load once at startup (content is static per session).
+	const agentMdContent = loadAgentMd();
+
+	if (!agentMdContent) {
+		// Silent skip — pix-skills might not be installed.
+		return;
+	}
+
+	pi.on("before_agent_start", async (event) => {
+		// Skip if already injected (idempotent check via a simple marker).
+		if (event.systemPrompt.includes("pix-agent-sop")) {
+			return;
+		}
+
+		return {
+			systemPrompt: `${event.systemPrompt}\n\n<pix-agent-sop>\n${agentMdContent}\n</pix-agent-sop>`,
+		};
+	});
+}

package/src/index.ts

@@ -16,6 +16,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import registerAgentSop from "./commands/agent-sop/agent-sop.ts";
 import registerClear from "./commands/clear/clear.ts";
 import registerCopyAll from "./commands/copy-all/copy-all.ts";
 import registerDiff from "./commands/diff/diff.ts";
@@ -24,7 +25,7 @@ import registerModels from "./commands/models/models.ts";
 import registerUpdate from "./commands/update/update.ts";
 import registerYeet from "./commands/yeet/yeet.ts";
 import registerNudges from "./nudge/index.ts";
-import registerAsk from "./tool/ask/ask.ts";
+import registerAsk from "./tool/ask/index.ts";
 import registerTodo from "./tool/todo/todo.ts";
 import registerToolbox from "./tool/toolbox/toolbox.ts";
 import registerDiagnostics from "./ui/diagnostics.ts";
@@ -32,6 +33,7 @@ import registerFooter from "./ui/footer.ts";
 import registerWelcome from "./ui/welcome.ts";
 
 export default function (pi: ExtensionAPI): void {
+	registerAgentSop(pi);
 	registerWelcome(pi);
 	registerFooter(pi);
 	registerDiagnostics(pi);

package/src/nudge/capability.test.ts

@@ -45,8 +45,14 @@ describe("CAPABILITY_REMINDER", () => {
 		expect(CAPABILITY_REMINDER.toLowerCase()).toContain("improvis");
 	});
 
-	test("points at the toolbox tool for discovery", () => {
-		expect(CAPABILITY_REMINDER).toContain("toolbox");
+	test("nudges model to call skill() when a skill matches", () => {
+		expect(CAPABILITY_REMINDER).toContain("skill()");
+	});
+
+	test("points at /toolbox slash command for discovery (not a function call)", () => {
+		expect(CAPABILITY_REMINDER).toContain("/toolbox");
+		// must NOT imply toolbox is a callable function
+		expect(CAPABILITY_REMINDER).not.toContain("toolbox(");
 		expect(CAPABILITY_REMINDER).toContain("function definitions");
 	});
 });
@@ -123,10 +129,13 @@ describe("buildOrientation", () => {
 		expect(out).toContain("2 skills");
 	});
 
-	test("explains how to explore via the toolbox tool", () => {
+	test("explains how to use skill() and /toolbox for discovery", () => {
 		const out = buildOrientation([tool("read", "builtin")], []);
-		expect(out).toContain("toolbox(query");
-		expect(out.toLowerCase()).toMatch(/fuzzy|search|discover/);
+		expect(out).toContain("skill()");
+		expect(out).toContain("/toolbox");
+		// toolbox must NOT appear as a function call
+		expect(out).not.toContain("toolbox(");
+		expect(out.toLowerCase()).toMatch(/discover|enable/);
 	});
 
 	test("calls out gated tools and points at toolbox to enable them", () => {

package/src/nudge/capability.ts

@@ -9,11 +9,15 @@
  * 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.
+ *      and HOW to explore it. We deliberately do NOT dump the whole inventory
+ *      every turn — the model should call skill() 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 points back at toolbox.
+ *      cheap (~40 tok) reinforcement that steers toward skill() 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 `skill` tool IS model-callable: skill() lists/loads bundled skills.
  */
 
 import type {
@@ -26,10 +30,11 @@ 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 " +
+	"Reminder — check 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.";
+	"Matching skill? Call skill() first. " +
+	"Use /toolbox to discover/enable gated tools. " +
+	"All tools callable via function definitions.";
 
 /** Count model-invocable skills (excludes user-only /skill:name entries). */
 export function countInvocableSkills(
@@ -107,7 +112,8 @@ export function buildOrientation(
 	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.",
+		"`skill()` lists/loads bundled skills — call it when a skill matches your task. " +
+			"/toolbox (slash command) discovers and enables gated tools.",
 	);
 	if (skillNames.length) {
 		lines.push(`Skills: ${skillNames.join(", ")}.`);

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

@@ -13,7 +13,7 @@ import {
 	type OptionData,
 	type QuestionData,
 	sentinelsFor,
-} from "./ask.ts";
+} from "./index.ts";
 
 // ── Fixtures ──────────────────────────────────────────────────────────
 
@@ -237,7 +237,7 @@ describe("buildResponseText", () => {
 
 describe("registerAsk", () => {
 	test("exports a default function", async () => {
-		const mod = await import("./ask.ts");
+		const mod = await import("./index.ts");
 		expect(typeof mod.default).toBe("function");
 	});
 });

package/src/tool/ask/components.ts

@@ -0,0 +1,55 @@
+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

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

package/src/tool/ask/index.ts

@@ -0,0 +1,130 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+import { buildResponseText } from "./helpers.js";
+import { AskQuestionnaire } from "./questionnaire.js";
+import { rpcFallback } from "./rpc.js";
+import type { Params } from "./schema.js";
+import {
+	MAX_OPTIONS,
+	MAX_QUESTIONS,
+	MIN_OPTIONS,
+	ParamsSchema,
+	SENTINEL_CHAT,
+	SENTINEL_FREEFORM,
+} from "./schema.js";
+import type { QuestionAnswer, QuestionnaireResult } from "./types.js";
+
+// ── Re-exports (consumed by tests and single-select-layout) ───────────
+
+export {
+	buildResponseText,
+	formatAnswerScalar,
+	hasAnyPreview,
+	sentinelsFor,
+} from "./helpers.js";
+export type { OptionData, QuestionData } from "./schema.js";
+export type {
+	AnswerKind,
+	QuestionAnswer,
+	QuestionnaireResult,
+} from "./types.js";
+
+// ── Tool registration ──────────────────────────────────────────────────
+
+export default function registerAsk(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "ask_user",
+		label: "Ask",
+		description: `Ask the user up to ${MAX_QUESTIONS} structured questions (${MIN_OPTIONS}-${MAX_OPTIONS} options each) when requirements are ambiguous.`,
+		promptSnippet: `Ask the user up to ${MAX_QUESTIONS} structured questions (${MIN_OPTIONS}-${MAX_OPTIONS} options each) when requirements are ambiguous`,
+		promptGuidelines: [
+			`Use ask whenever the user's request is underspecified and you cannot proceed without concrete decisions — you can ask up to ${MAX_QUESTIONS} questions per invocation.`,
+			`Each question MUST have ${MIN_OPTIONS}-${MAX_OPTIONS} options. Every option requires a concise label (1-5 words) and a description explaining what the choice means or its trade-offs. The user can additionally type a custom answer ("${SENTINEL_FREEFORM}" row is appended automatically to single-select questions) or pick "${SENTINEL_CHAT}" to abandon the questionnaire.`,
+			`Set multiSelect: true when multiple answers are valid; this suppresses the "${SENTINEL_FREEFORM}" row. Provide an options[].preview markdown string when an option benefits from richer side-by-side context (mockups, code snippets, diagrams, configs) — single-select only. NOTE: any non-empty preview on a single-select question ALSO suppresses the "${SENTINEL_FREEFORM}" row (no room in the side-by-side layout); "${SENTINEL_CHAT}" remains the escape hatch. If you recommend a specific option, make it the first option and append "(Recommended)" to its label.`,
+			"Do not stack multiple ask calls back-to-back — group all clarifying questions into one invocation.",
+		],
+		executionMode: "sequential",
+		parameters: ParamsSchema,
+
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			if (signal?.aborted) {
+				return {
+					content: [{ type: "text", text: "Cancelled" }],
+					details: { answers: [], cancelled: true },
+				};
+			}
+
+			const typed = params as unknown as Params;
+
+			if (!Array.isArray(typed.questions) || typed.questions.length === 0) {
+				return {
+					content: [
+						{ type: "text", text: "At least one question is required." },
+					],
+					isError: true,
+					details: { answers: [], cancelled: true },
+				};
+			}
+
+			if (!ctx.hasUI) {
+				const result = await rpcFallback(ctx.ui, typed);
+				const text = result.cancelled
+					? "User cancelled the questionnaire"
+					: buildResponseText(result.answers, typed.questions);
+				return { content: [{ type: "text", text }], details: result };
+			}
+
+			const result = await ctx.ui.custom<QuestionnaireResult | null>(
+				(tui, theme, keybindings, done) => {
+					if (signal) {
+						signal.addEventListener(
+							"abort",
+							() => done({ answers: [], cancelled: true }),
+							{ once: true },
+						);
+					}
+					return new AskQuestionnaire(typed, tui, theme, keybindings, done);
+				},
+			);
+
+			if (!result || result.cancelled) {
+				return {
+					content: [{ type: "text", text: "User cancelled the questionnaire" }],
+					details: result ?? { answers: [], cancelled: true },
+				};
+			}
+
+			const text = buildResponseText(result.answers, typed.questions);
+			return { content: [{ type: "text", text }], details: result };
+		},
+
+		renderCall(args, theme) {
+			const questions = Array.isArray(args.questions) ? args.questions : [];
+			const count = questions.length;
+			const firstQ = (questions[0]?.question ?? "") as string;
+			let text = theme.fg("toolTitle", theme.bold(`ask (${count}) `));
+			text += theme.fg("muted", firstQ);
+			if (count > 1) text += theme.fg("dim", ` +${count - 1} more`);
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, options, theme) {
+			const details = result.details as
+				| { answers?: QuestionAnswer[]; cancelled?: boolean }
+				| undefined;
+			if (options.isPartial) {
+				return new Text(theme.fg("muted", "Waiting for user input..."), 0, 0);
+			}
+			if (!details || details.cancelled || !details.answers?.length) {
+				return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+			}
+			const texts = details.answers.map((a) => {
+				const v =
+					a.kind === "multi" ? (a.selected ?? []).join(", ") : (a.answer ?? "");
+				return `${a.questionIndex + 1}: ${v}`;
+			});
+			return new Text(theme.fg("success", `✓ ${texts.join(" • ")}`), 0, 0);
+		},
+	});
+}