@xynogen/pix-optimizer 1.2.0 → 1.3.1

package/README.md

@@ -23,7 +23,7 @@ There is no text-arg form: the overlay is the only UI. Selecting a value calls
 the tool's `run()` handler, which persists the new value and repaints the
 shared status cell. Headless/test fallbacks print a plain status summary.
 
-State persists to `~/.pi/agent/optimizer.json` (caveman/rtk/ponytail). **Initial values** for a new session can be set in the `optimizer` section of `~/.pi/agent/pix.json` — the runtime toggle via `/optimizer` still persists changes to `optimizer.json` as before.
+State (caveman/rtk/ponytail) persists in the `optimizer` section of `~/.pi/agent/pix.json`. That section is the only place it is stored; the old `optimizer.json` file is imported once by pix-runtime and never written again.
 
 ## Status bar
 
@@ -63,7 +63,7 @@ article-dropping caveman prompt.
 | micro | Experimental prompt-minimized     |
 
 The `/optimizer` overlay opens a settings dialog when needed. Default level
-for new sessions is restored from `~/.pi/agent/optimizer.json`.
+for new sessions is restored from `pix.json` → `optimizer`.
 
 ### RTK Tool Rewriting (`Rk`)
 
@@ -77,14 +77,26 @@ Two layers, both active automatically:
    `||`, `;` and `|`, and every known segment is prefixed** — e.g.
    `git add . && git push` becomes `rtk git add . && rtk git push`.
    Operators inside quotes are ignored, and unparseable commands are left
-   untouched. Falls back gracefully when the `rtk` binary is missing
-   (warns once).
+   untouched. Commands are never rewritten while `rtk` is missing.
 
-**Requirement:** the `rtk` binary must be on `PATH`.
+**Binary:** pix finds `rtk` in this order: `binary.json` → `~/.pi/agent/bin` →
+PATH (see pix-runtime, Binaries).
 
-```bash
-cargo install rtk-ai
-```
+When RTK is on and `rtk` is missing, pix downloads the latest official
+release from `rtk-ai/rtk` into `~/.pi/agent/bin` the first time Pi loads. It
+verifies the download against the release's `checksums.txt`.
+
+The download is visible: a footer status while it runs, then one line naming
+the version and source. It never blocks startup or a tool call.
+
+The download is skipped when:
+
+- `PI_OFFLINE` is set;
+- RTK is off in `/optimizer`;
+- `binary.json` names a path that doesn't exist.
+
+If you pin a path in `binary.json`, rewritten commands use that quoted path
+instead of a bare `rtk`.
 
 ### Ponytail Mode (`Pt`)
 
@@ -105,7 +117,7 @@ PATH dependency.
 
 ## Configuration via `pix.json`
 
-Set the initial optimizer state for new sessions in `~/.pi/agent/pix.json`. These values are applied once at session start; subsequent changes via `/optimizer` persist to `optimizer.json` and take precedence.
+Optimizer state lives in `~/.pi/agent/pix.json`. You can edit it by hand, or use `/optimizer`, which writes to the same section.
 
 ```jsonc
 {
@@ -117,18 +129,6 @@ Set the initial optimizer state for new sessions in `~/.pi/agent/pix.json`. Thes
 }
 ```
 
-## Installation
-
-```bash
-pi install npm:@xynogen/pix-optimizer
-```
-
-> Also included in [`@xynogen/pix-core`](https://www.npmjs.com/package/@xynogen/pix-core):
->
-> ```bash
-> pi install npm:@xynogen/pix-core
-> ```
-
 ## Architecture
 
 | File              | Role                                                      |
@@ -139,7 +139,7 @@ pi install npm:@xynogen/pix-optimizer
 | `src/caveman.ts`  | Caveman logic, levels, prompt                            |
 | `src/rtk.ts`      | RTK prompt + bash command rewriting                       |
 | `src/ponytail.ts` | Ponytail logic, levels, prompt                            |
-| `src/persist.ts`  | Disk-backed `~/.pi/agent/optimizer.json` persistence; seeds initial state from `pix.json` |
+| `src/persist.ts`  | Reads/writes the `optimizer` section of `pix.json` via pix-runtime |
 | `src/tool-result-filter.ts` | Strips model-guidance warnings from tool_result |
 
 Each tool registers its own lifecycle hooks and exposes an `OptimizerHandle`
@@ -172,16 +172,28 @@ All upstreams are MIT licensed. No codebase was copied directly — the logic wa
 rewritten and combined into a single extension with a unified `/optimizer`
 command and shared status bar. This package does not sync back to any upstream.
 
-## Full distro
+## Install
+
+```bash
+pi install npm:@xynogen/pix-optimizer
+```
+
+> Bundled in [`@xynogen/pix-core`](https://www.npmjs.com/package/@xynogen/pix-core). Install it alone only if you do not use pix-core.
 
-Source: [github.com/xynogen/pix-mono](https://github.com/xynogen/pix-mono)
+## Full distro
 
-To install the complete pix suite (all packages + Pi itself):
+This package is part of [Pix](https://github.com/xynogen/pix-mono). The installer sets up Pi and the full distro. See [Install](https://github.com/xynogen/pix-mono#install) for the notes for each OS.
 
 ```bash
+# Linux / macOS
 curl -fsSL https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.sh | sh
 ```
 
+```powershell
+# Windows
+irm https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.ps1 | iex
+```
+
 ## License
 
-MIT
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-optimizer",
-	"version": "1.2.0",
+	"version": "1.3.1",
 	"description": "Performance optimization suite for Pi Coding Agent - caveman mode + RTK tool rewriting + ponytail lazy-dev mode",
 	"type": "module",
 	"main": "src/index.ts",
@@ -43,7 +43,8 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@xynogen/pix-pretty": "^1.24.0"
+		"@xynogen/pix-pretty": "^1.30.0",
+		"@xynogen/pix-runtime": "^0.13.0"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*",

package/src/caveman.ts

@@ -80,7 +80,7 @@ Write in Simplified Technical English. Use short common words, the active voice,
 const INTENSITY: Record<Exclude<Level, "off" | "micro">, string> = {
 	lite: `\
 STE-flavored words. Keep the sentence, tense, active-voice, and no-phrasal-verb discipline. \
-Relax the strict dictionary. Apply Layer 2 lightly: lead with the answer, no preamble or closer.
+Relax the strict dictionary. Apply the reply shape lightly: lead with the answer, no preamble or closer.
 Example: "The component re-renders because you create a new object reference each render. Wrap it in \`useMemo\`."`,
 
 	full: `\
@@ -109,6 +109,9 @@ Boundaries: this governs prose, not code. "stop caveman" or "normal mode" revert
 export function buildPrompt(level: Level): string {
 	if (level === "off") return "";
 	if (level === "micro") return MICRO_PROMPT;
+	// ponytail: lite relaxes most of BASE, so it ships the short MICRO rules + its intensity (~800 tokens less).
+	if (level === "lite")
+		return [MICRO_PROMPT, "", `Intensity: ${INTENSITY.lite}`, "", SAFETY].join("\n");
 	return [BASE, "", `Intensity: ${INTENSITY[level]}`, "", SAFETY].join("\n");
 }
 

package/src/mode.ts

@@ -14,6 +14,7 @@ import type {
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { showTransientError } from "@xynogen/pix-pretty/transient-error";
+import { getErrorMessage } from "@xynogen/pix-pretty/utils";
 import { loadOptValue, saveOptValue } from "./persist.ts";
 import type { OptimizerHandle, OptimizerStatus, OptimizerTool } from "./status.ts";
 
@@ -87,7 +88,7 @@ export function createMode<L extends string>(
 			}
 		}
 		const saved = loadOptValue(name);
-		if (saved && levels.includes(saved as L)) level = saved as L;
+		if (levels.includes(saved as L)) level = saved as L;
 		syncStatus(ctx);
 	});
 
@@ -102,9 +103,9 @@ export function createMode<L extends string>(
 
 		pi.appendEntry(customType, { level });
 		try {
-			saveOptValue(name, level);
+			await saveOptValue(name, level);
 		} catch (error) {
-			const detail = error instanceof Error ? error.message : String(error);
+			const detail = getErrorMessage(error);
 			showTransientError(ctx.ui, `optimizer: failed to save ${name}: ${detail}`);
 		}
 		syncStatus(ctx);

package/src/opt.ts

@@ -16,6 +16,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type KeybindingsManager, matchesKey } from "@earendil-works/pi-tui";
+import { icon } from "@xynogen/pix-pretty/icon-catalog";
 import {
 	frameModal,
 	MIN_MODAL_HEIGHT,
@@ -153,7 +154,7 @@ export function registerOptCommand(
 								width,
 								maxHeight: terminalModalHeight(tui.terminal?.rows),
 								minHeight: MIN_MODAL_HEIGHT,
-								header: [theme.fg("accent", theme.bold("󱎫  Optimizer")), ""],
+								header: [theme.fg("accent", theme.bold(`${icon("opt.title")}  Optimizer`)), ""],
 								body: rows,
 								footer: [
 									"",

package/src/persist.ts

@@ -1,54 +1,27 @@
 /**
- * persist.ts — disk-backed persistence for the /optimizer tool states.
- *
- * caveman/ponytail previously saved only to the session log (lost on a fresh
- * session); rtk never persisted at all. This stores every tool's current
- * value in one file under the agent dir so the picker survives a full quit and
- * restart. Each tool reads its value on session_start and writes on run().
- *
- *   ~/.pi/agent/optimizer.json  →  { "caveman": "lite", "rtk": "on", ... }
+ * persist.ts — /optimizer tool states live in pix.json `optimizer` (owned by
+ * pix-runtime). Replaces the old `optimizer.json` sidecar, which pix-runtime
+ * imports and archives on init; writing it again made two sources of truth
+ * that overwrote each other.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { config, updateConfig } from "@xynogen/pix-runtime/config";
+import { type OptimizerConfig, optimizerSection } from "@xynogen/pix-runtime/sections";
 import type { OptimizerTool } from "./status.ts";
 
-type OptimizerFileConfig = Partial<Record<OptimizerTool, string>>;
-
-const OPTIMIZER_TOOLS: readonly OptimizerTool[] = ["caveman", "rtk", "ponytail"];
-
-function getStatePath(): string {
-	return join(getAgentDir(), "optimizer.json");
-}
-
-function readFile(): OptimizerFileConfig {
-	try {
-		const sp = getStatePath();
-		if (!existsSync(sp)) return {};
-		const raw = JSON.parse(readFileSync(sp, "utf-8")) as unknown;
-		if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
-
-		const config: OptimizerFileConfig = {};
-		for (const tool of OPTIMIZER_TOOLS) {
-			const value = (raw as Record<string, unknown>)[tool];
-			if (typeof value === "string") config[tool] = value;
-		}
-		return config;
-	} catch {
-		return {};
-	}
+/** Read a tool's value from pix.json (section defaults when unset). */
+export function loadOptValue(tool: OptimizerTool): string {
+	return config(optimizerSection)[tool];
 }
 
-/** Read a single tool's persisted value from optimizer.json. */
-export function loadOptValue(tool: OptimizerTool): string | undefined {
-	return readFile()[tool];
-}
-
-/** Persist a single tool's value, merging into the shared config file. */
-export function saveOptValue(tool: OptimizerTool, value: string): void {
-	const sp = getStatePath();
-	mkdirSync(dirname(sp), { recursive: true });
-	const next = { ...readFile(), [tool]: value };
-	writeFileSync(sp, JSON.stringify(next, null, 2), "utf-8");
+/**
+ * Persist a tool's value into pix.json. Invalid values are rejected by the
+ * section parser and snap to the default. Rejects on write failure so the UI
+ * caller can render it.
+ */
+export async function saveOptValue(tool: OptimizerTool, value: string): Promise<void> {
+	await updateConfig(optimizerSection, { [tool]: value } as Partial<OptimizerConfig>, {
+		origin: "command",
+		source: "pix-optimizer",
+	});
 }

package/src/ponytail.ts

@@ -94,8 +94,7 @@ error handling that prevents data loss, security, accessibility, or anything the
 The hardware is never the spec ideal. Leave the calibration knob.
 Lazy code without its check is unfinished. Non-trivial logic leaves ONE runnable check behind \
 (an assert-based self-check or one small test file, no frameworks). A trivial one-liner needs no test.
-Output: write the code first, then at most three short lines — what you skipped, and when to add it. \
-Write these lines in Simplified Technical English: short common words, the active voice, and simple tenses.
+Output: write the code first, then at most three short lines — what you skipped, and when to add it.
 Boundaries: ponytail governs what you build, not how you talk. "stop ponytail" or "normal mode" reverts.`;
 
 /**

package/src/rtk.ts

@@ -11,8 +11,10 @@ import type {
 	ExtensionCommandContext,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { reportToolStatus } from "@xynogen/pix-pretty/tool-status";
 import { showTransientError } from "@xynogen/pix-pretty/transient-error";
-import { canExecute } from "./capability.ts";
+import { getErrorMessage } from "@xynogen/pix-pretty/utils";
+import { ensureTool, type ResolvedTool, resolveTool } from "@xynogen/pix-runtime/binaries";
 import { loadOptValue, saveOptValue } from "./persist.ts";
 import type { OptimizerHandle, OptimizerStatus } from "./status.ts";
 
@@ -75,7 +77,7 @@ export function buildSudoBlockReason(sudoCmds: string[], hasSudoRunTool: boolean
 
 export function applyRtkRewrite(
 	event: BashCallEvent,
-	opts: { enabled: boolean; rtkAvailable: boolean },
+	opts: { enabled: boolean; rtkAvailable: boolean; rtkCommand?: string },
 ): boolean {
 	if (!opts.enabled) return false;
 	if (!opts.rtkAvailable) return false;
@@ -84,7 +86,7 @@ export function applyRtkRewrite(
 	const command = event.input?.command;
 	if (typeof command !== "string" || !command) return false;
 
-	const rewritten = rewriteChain(command);
+	const rewritten = rewriteChain(command, opts.rtkCommand);
 	if (rewritten === command) return false;
 
 	event.input.command = rewritten;
@@ -128,12 +130,31 @@ const RTK_COMMANDS = new Set([
 
 interface RtkStatus {
 	available: boolean;
+	/** Command prefix to inject: bare `rtk`, or the quoted path for a binary.json pin. */
+	command: string;
 	checkedAt: number;
 }
 
-/** Probe the command we actually use instead of relying on a platform-specific locator. */
-export function probeRtkAvailability(pi: Pick<ExtensionAPI, "exec">): Promise<boolean> {
-	return canExecute(pi, "rtk", ["--version"]);
+/**
+ * Prefix used in rewritten commands. The bash tool puts `<agentDir>/bin` on
+ * PATH and PATH hits resolve by name, so those stay a readable bare `rtk`;
+ * only a user-chosen path (binary.json) must be spelled out, single-quoted
+ * with forward slashes so Git Bash on Windows runs it too.
+ */
+export function rtkCommandFor(tool: Pick<ResolvedTool, "path" | "source">): string {
+	if (tool.source !== "user") return "rtk";
+	const posix = tool.path.replaceAll("\\", "/");
+	return `'${posix.replaceAll("'", "'\\''")}'`;
+}
+
+/** Locate rtk (binary.json → agent bin → PATH) without running anything. */
+export function probeRtk(): RtkStatus {
+	const tool = resolveTool("rtk");
+	return {
+		available: tool !== undefined,
+		command: tool ? rtkCommandFor(tool) : "rtk",
+		checkedAt: Date.now(),
+	};
 }
 
 /**
@@ -195,7 +216,7 @@ const CHAIN_OPERATORS = new Set(["&&", "||", ";", "|"]);
  * RTK command and it is not already prefixed. Operators are preserved.
  * Returns the rewritten command, or the original if nothing changed.
  */
-export function rewriteChain(command: string): string {
+export function rewriteChain(command: string, rtkCommand = "rtk"): string {
 	const parts = splitChain(command);
 	if (!parts) return command; // unparseable — leave untouched
 
@@ -208,11 +229,11 @@ export function rewriteChain(command: string): string {
 		if (!body) return part;
 
 		const firstWord = body.split(/\s+/)[0] ?? "";
-		if (firstWord === "rtk") return part;
+		if (firstWord === "rtk" || firstWord === rtkCommand) return part;
 		if (!RTK_COMMANDS.has(firstWord)) return part;
 
 		changed = true;
-		return `${leading}rtk ${body}`;
+		return `${leading}${rtkCommand} ${body}`;
 	});
 
 	return changed ? rewritten.join("") : command;
@@ -239,15 +260,33 @@ export function rtk(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHandle
 			return rtkStatus;
 		}
 
-		const available = await probeRtkAvailability(pi);
-		rtkStatus = {
-			available,
-			checkedAt: Date.now(),
-		};
-		if (available) warnedMissing = false;
+		rtkStatus = probeRtk();
+		if (rtkStatus.available) warnedMissing = false;
 		return rtkStatus;
 	};
 
+	// First load without rtk: download it once, visibly (footer status + one
+	// transient line naming repo and version). Never blocks startup or a tool
+	// call; PI_OFFLINE, a broken binary.json path, or RTK off skip it.
+	let installing: Promise<void> | undefined;
+	const installRtk = (ctx: Pick<ExtensionContext, "ui">) => {
+		installing ??= ensureTool("rtk", { onStatus: reportToolStatus(ctx.ui) })
+			.then(() => {
+				rtkStatus = null;
+			})
+			.catch((error: unknown) => {
+				if (warnedMissing) return;
+				warnedMissing = true;
+				const detail = getErrorMessage(error);
+				ctx.ui.notify(`RTK rewriting disabled: ${detail}`, "warning");
+			})
+			.then(async () => {
+				await checkRtkAvailability();
+				syncStatus(ctx);
+			});
+		return installing;
+	};
+
 	// Detect sudo_run tool availability. No system-prompt injection — the
 	// tool_call rewrite hook adds the rtk prefix on its own, so we keep zero
 	// always-on context cost (ponytail: manual `rtk err`/`rtk summary`/`rtk
@@ -266,14 +305,8 @@ export function rtk(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHandle
 		const saved = loadOptValue("rtk");
 		if (saved === "on" || saved === "off") enabled = saved === "on";
 		const probe = await checkRtkAvailability();
-		if (!probe.available && !warnedMissing) {
-			ctx.ui.notify(
-				"rtk not found — RTK rewriting disabled. Install: cargo install rtk-ai",
-				"warning",
-			);
-			warnedMissing = true;
-		}
 		syncStatus(ctx);
+		if (!probe.available && enabled) void installRtk(ctx);
 	});
 	pi.on("agent_start", async (_event, ctx) => {
 		syncStatus(ctx);
@@ -287,15 +320,16 @@ export function rtk(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHandle
 	async function run(value: string, ctx: ExtensionCommandContext): Promise<void> {
 		enabled = value === "on";
 		try {
-			saveOptValue("rtk", enabled ? "on" : "off");
+			await saveOptValue("rtk", enabled ? "on" : "off");
 		} catch (error) {
-			const detail = error instanceof Error ? error.message : String(error);
+			const detail = getErrorMessage(error);
 			showTransientError(ctx.ui, `optimizer: failed to save rtk: ${detail}`);
 		}
 
-		await checkRtkAvailability();
+		const probe = await checkRtkAvailability();
 		syncStatus(ctx);
 		ctx.ui.notify(`RTK rewriting ${enabled ? "on" : "off"}.`, "info");
+		if (enabled && !probe.available) void installRtk(ctx);
 	}
 
 	// Rewrite bash commands to add rtk prefix.
@@ -339,7 +373,7 @@ export function rtk(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHandle
 		// Rewrite every segment in the command chain that uses a known RTK
 		// command (e.g. `git add . && git push` -> `rtk git add . && rtk git push`).
 		// Mutates `event.input.command` in place — the SDK's supported patch path.
-		applyRtkRewrite(event, { enabled, rtkAvailable: probe.available });
+		applyRtkRewrite(event, { enabled, rtkAvailable: probe.available, rtkCommand: probe.command });
 		return undefined;
 	});
 

package/src/capability.ts

@@ -1,16 +0,0 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-/** Test whether a command can perform a harmless operation through Pi's executor. */
-export async function canExecute(
-	pi: Pick<ExtensionAPI, "exec">,
-	command: string,
-	args: string[],
-	timeout = 3000,
-): Promise<boolean> {
-	try {
-		const result = await pi.exec(command, args, { timeout });
-		return result.code === 0;
-	} catch {
-		return false;
-	}
-}