@xynogen/pix-optimizer 1.0.2 → 1.0.7

package/README.md

@@ -6,7 +6,7 @@ shared status-bar cell:
 
 - **Caveman** (`⛏`) — terse-output system prompt
 - **RTK** (`⚔`) — prefixes shell commands with `rtk` + injects RTK prompt
-- **TOON** (`✂`) — jq + TOON guidance for dense JSON (+ bundled skill)
+- **TOON** (`✂`) — jq + TOON guidance for dense JSON (skill lives in pix-skills)
 
 ## Command
 
@@ -63,11 +63,14 @@ cargo install rtk-ai
 
 ### TOON / JSON Compression (`✂`)
 
-Guidance + a bundled `toon-json` skill for handling information-dense JSON via
-`jq` (query/reshape) and `toon` (compress). The system-prompt nudge is injected
-**only when the user prompt mentions JSON** (`json`/`jsonl`/`jq`/`toon`/
-`openapi`/…). TOON shines on uniform/tabular arrays; deeply nested or
-array-of-arrays data and API contracts stay as JSON.
+Guidance for handling information-dense JSON via `jq` (query/reshape) and
+`toon` (compress). The system-prompt nudge is injected **only when the user
+prompt mentions JSON** (`json`/`jsonl`/`jq`/`toon`/`openapi`/…). TOON shines
+on uniform/tabular arrays; deeply nested or array-of-arrays data and API
+contracts stay as JSON.
+
+The `toon-json` skill (full workflow + when-NOT-to-use guidance) is bundled in
+`pix-skills` and auto-discovered from there.
 
 **Requirement:** `jq` and `toon` on `PATH`.
 
@@ -90,7 +93,7 @@ pi install npm:@xynogen/pix-optimizer
 | `src/status.ts`   | Shared status-bar cell + `OptimizerHandle` contract       |
 | `src/caveman.ts`  | Caveman logic, levels, prompt, settings dialog            |
 | `src/rtk.ts`      | RTK prompt + bash command rewriting                       |
-| `src/json.ts`     | jq+TOON guidance, heuristics, bundled skill registration  |
+| `src/json.ts`     | jq+TOON guidance, heuristics, system-prompt injection     |
 
 Each tool registers its own lifecycle hooks and exposes an `OptimizerHandle`
 that `/opt` dispatches to. All three share one `OptimizerStatus`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-optimizer",
-	"version": "1.0.2",
+	"version": "1.0.7",
 	"description": "Performance optimization suite for Pi Coding Agent - caveman mode + RTK tool rewriting + jq/TOON JSON compression",
 	"type": "module",
 	"main": "src/index.ts",

package/src/json.test.ts

@@ -5,7 +5,6 @@ import {
 	JSON_SYSTEM_PROMPT,
 	mentionsJson,
 	objectDepth,
-	skillDir,
 } from "./json.ts";
 
 describe("JSON_SYSTEM_PROMPT", () => {
@@ -168,10 +167,3 @@ describe("adviseToon", () => {
 		expect(adviseToon(d2, 2).useToon).toBe(true);
 	});
 });
-
-describe("skillDir", () => {
-	it("points at the bundled toon-json skill", () => {
-		const dir = skillDir();
-		expect(dir.endsWith("skills/toon-json")).toBe(true);
-	});
-});

package/src/json.ts

@@ -1,12 +1,12 @@
 /**
  * json.ts — JSON token-optimization via jq + TOON.
  *
- * Two parts, mirroring rtk.ts/caveman.ts:
- *   1. A small system-prompt nudge teaching the model to run JSON through
- *      `jq` (query/reshape) and `toon` (compress for context), and to convert
- *      back to JSON only when a strict contract requires it.
- *   2. A bundled `toon-json` skill, surfaced via `resources_discover`, that
- *      holds the full workflow + when-NOT-to-use guidance.
+ * A small system-prompt nudge teaching the model to run JSON through
+ * `jq` (query/reshape) and `toon` (compress for context), and to convert
+ * back to JSON only when a strict contract requires it.
+ *
+ * The bundled `toon-json` skill lives in pix-skills and is auto-discovered
+ * from there — no resources_discover hook needed here.
  *
  * TOON = Token-Oriented Object Notation (https://github.com/toon-format/spec).
  * It shines on uniform/tabular arrays of objects (declare keys once, stream
@@ -17,8 +17,6 @@
  * by index.ts alongside caveman(pi) and rtk(pi).
  */
 
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
 import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
@@ -207,15 +205,6 @@ export function objectDepth(value: unknown): number {
 
 // ── Bundled skill path ────────────────────────────────────────────────────────
 
-/**
- * Absolute path to the bundled `toon-json` skill directory, resolved relative
- * to this module so it works regardless of the extension's install location.
- */
-export function skillDir(): string {
-	const here = fileURLToPath(new URL(".", import.meta.url));
-	return join(here, "skills", "toon-json");
-}
-
 // ── Pi extension ──────────────────────────────────────────────────────────────
 
 export function json(
@@ -223,10 +212,16 @@ export function json(
 	status: OptimizerStatus,
 ): OptimizerHandle {
 	let enabled = true;
+	let jqAvailable: boolean | null = null;
+	let toonAvailable: boolean | null = null;
 
 	// Report into the shared optimizer indicator.
 	function syncStatus(ctx: Pick<ExtensionContext, "ui">) {
-		status.set("toon", enabled, ctx);
+		status.set(
+			"toon",
+			enabled && jqAvailable !== false && toonAvailable !== false,
+			ctx,
+		);
 	}
 
 	pi.on("session_start", async (_event, ctx) => {
@@ -239,18 +234,38 @@ export function json(
 		syncStatus(ctx);
 	});
 
-	// Surface the bundled skill so the model can load the full workflow.
-	pi.on("resources_discover", async () => {
-		if (!enabled) return undefined;
-		return { skillPaths: [skillDir()] };
-	});
-
 	// Inject the JSON-handling nudge into the system prompt, but ONLY when the
 	// user prompt actually mentions JSON / a related token — otherwise it's dead
-	// weight in every turn.
-	pi.on("before_agent_start", async (event) => {
+	// weight in every turn. Probe jq/toon lazily here (not at session_start) so
+	// we don't add startup overhead for a workflow the user may never trigger.
+	pi.on("before_agent_start", async (event, ctx) => {
 		if (!enabled) return undefined;
 		if (!mentionsJson(event.prompt)) return undefined;
+
+		// Probe once on first JSON-relevant prompt.
+		if (jqAvailable === null || toonAvailable === null) {
+			const [jqRes, toonRes] = await Promise.all([
+				pi.exec("which", ["jq"], { timeout: 1000 }).catch(() => ({ code: 1 })),
+				pi
+					.exec("which", ["toon"], { timeout: 1000 })
+					.catch(() => ({ code: 1 })),
+			]);
+			jqAvailable = jqRes.code === 0;
+			toonAvailable = toonRes.code === 0;
+			if (!jqAvailable)
+				ctx.ui.notify(
+					"jq not found — JSON/TOON guidance disabled. Install: sudo apt install jq  or  brew install jq",
+					"warning",
+				);
+			if (!toonAvailable)
+				ctx.ui.notify(
+					"toon not found — JSON/TOON guidance disabled. Install: bun add -g @toon-format/cli  or  npm i -g @toon-format/cli",
+					"warning",
+				);
+			syncStatus(ctx);
+		}
+
+		if (jqAvailable === false || toonAvailable === false) return undefined;
 		const existing = event.systemPrompt ?? "";
 		return { systemPrompt: `${JSON_SYSTEM_PROMPT}\n\n${existing}` };
 	});

package/src/rtk.ts

@@ -286,7 +286,14 @@ export function rtk(
 	// Keep the status indicator in sync across the agent lifecycle. Probe
 	// availability on session start so the icon reflects reality immediately.
 	pi.on("session_start", async (_event, ctx) => {
-		await checkRtkAvailability();
+		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);
 	});
 	pi.on("agent_start", async (_event, ctx) => {
@@ -340,13 +347,6 @@ export function rtk(
 		const probe = await checkRtkAvailability();
 
 		if (!probe.available) {
-			if (!warnedMissing) {
-				ctx.ui.notify(
-					"RTK binary not found. Install: cargo install rtk-ai",
-					"warning",
-				);
-				warnedMissing = true;
-			}
 			return undefined; // Don't rewrite if rtk not available
 		}
 

package/src/skills/toon-json/SKILL.md

@@ -1,101 +0,0 @@
----
-name: toon-json
-description: Manipulate information-dense JSON efficiently with jq + TOON. Use when fetching/reading large or repetitive JSON (LLM schemas, OpenAPI specs, API responses, datasets, config dumps) into context. Query/reshape with jq, compress to TOON to cut tokens, decode back to JSON only when a strict contract needs it.
----
-
-# TOON + jq: Dense JSON Workflow
-
-## Goal
-Carry only the JSON slice you need, in the cheapest encoding. Query with `jq`,
-compress with `toon`, and round-trip back to JSON **only** when a contract
-requires strict JSON.
-
-TOON (Token-Oriented Object Notation, https://github.com/toon-format/spec) is a
-line-oriented encoding of the JSON data model. Uniform arrays of objects declare
-their keys once and stream bare rows, so token cost drops sharply on tabular and
-dense data.
-
-## The pipeline
-
-```bash
-# Fetch → reshape → compress (most common)
-curl -s https://api.example.com/models | jq '.data' | toon
-
-# Local file, show token savings
-cat openapi.json | jq '.paths' | toon --stats
-
-# Just compress, no query
-cat data.json | toon
-
-# Convert TOON back to JSON (strict contract / downstream parser)
-echo "$TOON_BLOB" | toon -d
-cat data.toon | toon --decode
-```
-
-`toon` auto-detects direction from input. Force it with `-e` (encode JSON→TOON)
-or `-d` (decode TOON→JSON).
-
-### Useful flags
-- `--stats` — print token/byte statistics for the conversion
-- `--delimiter=,|\t|"|"` — array delimiter (comma default; tab/pipe can tokenize better)
-- `--keyFolding=safe` — collapse single-key nesting chains
-- `--no-strict` — lenient decode
-
-## Decide before you compress
-
-TOON is not always smaller. Pick based on shape:
-
-| Shape | Action | Why |
-|---|---|---|
-| Uniform array of objects (same keys, primitive values) | **TOON** | Sweet spot — keys declared once, rows streamed; savings scale with rows × fields |
-| Flat object / primitive array | **TOON** | Drops quotes and braces |
-| Shallow nesting | **TOON** | Indentation cheaper than braces at low depth |
-| Deeply nested / non-uniform | **JSON** | Indentation cost grows; compact JSON can win |
-| Array of arrays | **JSON** | TOON's one structurally-worse case (explicit list markers + inner headers) |
-| API contract / payload to send or store | **JSON** | Must stay valid JSON for the consumer |
-
-Rule of thumb: **TOON for reading dense data into context. JSON for contracts.**
-
-## When NOT to use TOON
-- Anything sent to or stored by an API that expects JSON.
-- Data a downstream tool/parser must consume as strict JSON.
-- Deeply nested config trees or highly irregular structures.
-- Tiny payloads where the conversion overhead isn't worth it.
-
-In those cases, still use `jq` to slice down to what you need — just skip the
-`| toon` step.
-
-## Worked examples
-
-LLM model list (uniform array → great TOON candidate):
-
-```bash
-curl -s https://api.example.com/v1/models | jq '.data | map({id, owned_by, context})' | toon
-```
-```
-[3]{id,owned_by,context}:
-  gpt-x,acme,128000
-  gpt-y,acme,200000
-  gpt-z,acme,1000000
-```
-
-OpenAPI paths summary (reshape first, then compress):
-
-```bash
-cat openapi.json \
-  | jq '[.paths | to_entries[] | {path: .key, methods: (.value | keys)}]' \
-  | toon --stats
-```
-
-Round-trip back to JSON for an API call:
-
-```bash
-RESHAPED=$(cat payload.toon | toon -d)
-curl -s -X POST https://api.example.com/ingest -d "$RESHAPED"
-```
-
-## Checklist
-1. **Query** — narrow with `jq` to the exact slice needed.
-2. **Decide** — uniform/tabular/shallow → TOON; nested/array-of-arrays/contract → JSON.
-3. **Compress** — `| toon` (add `--stats` to confirm savings).
-4. **Round-trip** — `toon -d` only when strict JSON is required downstream.