@xynogen/pix-runtime 0.4.0 → 0.5.1

package/DESIGN.md

@@ -132,7 +132,6 @@ interface PixConfigV1 {
   optimizer: {
     caveman: "off" | "lite" | "full" | "ultra" | "micro"; // default off
     rtk: "off" | "on";                                      // default on
-    toon: "off" | "on";                                     // default on
     ponytail: "off" | "lite" | "full" | "ultra";          // default off
   };
   gate: {

package/README.md

@@ -10,7 +10,7 @@ See `DESIGN.md` for the full contract.
 ## What it does
 
 - Versioned, sparse `pix.json` (`$version: 1`) — defaults resolve in code.
-- Typed sections: `collapse`, `pretty`, `io`, `optimizer`, `gate`.
+- Typed sections: `collapse`, `pretty`, `io`, `compaction`, `optimizer`, `gate`.
 - Atomic writes behind a serialized in-process queue and a short-lived
   cross-process lock. A failed write leaves the old file intact.
 - Immutable, deeply frozen config snapshots with a monotonic revision.
@@ -49,6 +49,18 @@ with `/pix`. The default is 30 seconds. It applies to Pix network operations,
 including remote skills, web fetch/search/transcription, MCP requests and
 connection bootstrap, background model-data refreshes, and update downloads.
 
+Set `compaction.triggerPercent` in `~/.pi/agent/pix.json`, or change **Compaction →
+Trigger (% ctx)** with `/pix`. It is the context-window usage percent (0–100) used
+to calculate the trigger; the default is `60` and `0` disables the self-trigger
+(pi decides when to compact). The `/pix` picker offers 0, 5, 10, 15, 20, 25, 30,
+40, 50, 60, 70, 80, 90.
+
+`compaction.minimumTokens` is the absolute floor for that calculation. The
+effective threshold is `max(contextWindow × triggerPercent, minimumTokens)`, so
+a 300K-context model at 10% waits for 100K tokens instead of compacting at 30K.
+The default floor is 100K; `/pix` offers 100K, 150K, 200K, 300K, 400K, 500K, and
+600K. pix-core consumes both settings.
+
 Collapse policy helpers:
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-runtime",
-	"version": "0.4.0",
+	"version": "0.5.1",
 	"description": "Pix shared runtime — versioned pix.json config, atomic persistence, typed change events",
 	"type": "module",
 	"main": "src/index.ts",

package/src/index.ts

@@ -31,7 +31,9 @@ export { CONFIG_FORMAT_VERSION, defineSection } from "./schema.ts";
 export {
 	builtinSections,
 	type CollapseConfig,
+	type CompactionConfig,
 	collapseSection,
+	compactionSection,
 	type GateConfig,
 	type GateRuleConfig,
 	gateSection,

package/src/migrations.ts

@@ -25,7 +25,7 @@ const LEGACY_DIFF_COLOR_KEYS = [
 	"fgDel",
 ] as const;
 
-const OPTIMIZER_KEYS = ["caveman", "rtk", "toon", "ponytail"] as const;
+const OPTIMIZER_KEYS = ["caveman", "rtk", "ponytail"] as const;
 
 export interface MigrationResult {
 	document: RawDocument;
@@ -80,6 +80,14 @@ export function migrate(input: RawDocument, ctx: ParseContext): MigrationResult
 		doc.pretty = pretty;
 	}
 
+	// TOON is now an on-demand pix-skills capability, not optimizer state.
+	if (isObj(doc.optimizer) && "toon" in doc.optimizer) {
+		doc.optimizer = Object.fromEntries(
+			Object.entries(doc.optimizer).filter(([key]) => key !== "toon"),
+		);
+		changed = true;
+	}
+
 	if (doc.$version !== CONFIG_FORMAT_VERSION) {
 		doc.$version = CONFIG_FORMAT_VERSION;
 		changed = true;
@@ -128,6 +136,7 @@ export function importOptimizerSidecar(
 	}
 	if (changed) doc.optimizer = existing;
 
+	const hasLegacyToon = typeof raw.toon === "string";
 	const archive = () => {
 		let target = `${sidecarPath}.migrated-v1`;
 		if (existsSync(target)) target = `${target}.${Date.now()}`;
@@ -138,5 +147,5 @@ export function importOptimizerSidecar(
 		}
 	};
 
-	return { changed, archive };
+	return { changed: changed || hasLegacyToon, archive };
 }

package/src/pix-command.ts

@@ -18,6 +18,7 @@ import {
 import type { PixRuntime } from "./runtime.ts";
 import type { DeepPartial, SectionHandle } from "./schema.ts";
 import { collapseSection } from "./sections/collapse.ts";
+import { compactionSection } from "./sections/compaction.ts";
 import { gateSection } from "./sections/gate.ts";
 import { ioSection } from "./sections/io.ts";
 import { prettySection } from "./sections/pretty.ts";
@@ -77,6 +78,22 @@ const SETTINGS: SettingRow<unknown>[] = [
 		read: (v) => String(v.timeoutSec),
 		patch: (value) => ({ timeoutSec: Number(value) }),
 	}),
+	row({
+		section: "Compaction",
+		label: "Trigger (% ctx)",
+		handle: compactionSection,
+		values: ["0", "5", "10", "15", "20", "25", "30", "40", "50", "60", "70", "80", "90"],
+		read: (v) => String(v.triggerPercent),
+		patch: (value) => ({ triggerPercent: Number(value) }),
+	}),
+	row({
+		section: "Compaction",
+		label: "Minimum tokens",
+		handle: compactionSection,
+		values: ["100k", "150k", "200k", "300k", "400k", "500k", "600k"],
+		read: (v) => `${v.minimumTokens / 1000}k`,
+		patch: (value) => ({ minimumTokens: Number.parseInt(value, 10) * 1000 }),
+	}),
 	row({
 		section: "Gate",
 		label: "Guardrails",
@@ -129,6 +146,9 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 					kb: KeybindingsManager,
 					done: (v: null) => void,
 				) => {
+					const guide = (key: string, action: string) =>
+						theme.fg("text", key) + theme.fg("dim", ` ${action}`);
+					const guideSep = theme.fg("dim", " · ");
 					let selected = 0;
 					let bodyOffset = 0;
 					let visibleBodyLines = 1;
@@ -177,7 +197,13 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 								body,
 								footer: [
 									"",
-									theme.fg("dim", "←→ change · ↑↓ move · PgUp/PgDn inspect · esc close"),
+									guide("←→", "change") +
+										guideSep +
+										guide("↑↓", "move") +
+										guideSep +
+										guide("PgUp/PgDn", "inspect") +
+										guideSep +
+										guide("esc", "close"),
 								],
 								bodyOffset,
 								selectedBodyLine: inspectingPage ? undefined : settingBodyLines[selected],

package/src/sections/compaction.ts

@@ -0,0 +1,46 @@
+import { defineSection, isObj } from "../schema.ts";
+
+/**
+ * Custom compaction config. pix-core always replaces pi's built-in compaction
+ * summary. When `triggerPercent > 0` it also drives its own trigger from live
+ * context usage. The effective threshold is the larger of that percentage of
+ * the active model's context window and `minimumTokens`. `0` disables the
+ * self-trigger (pi decides when to compact).
+ */
+export interface CompactionConfig {
+	/** Context-window usage percent that fires compaction; 0 = off. */
+	triggerPercent: number;
+	/** Absolute floor for a percentage-based trigger. */
+	minimumTokens: number;
+}
+
+const MINIMUM_TOKEN_FLOOR = 100_000;
+
+const DEFAULTS: Readonly<CompactionConfig> = {
+	triggerPercent: 60,
+	minimumTokens: MINIMUM_TOKEN_FLOOR,
+};
+
+/** Clamp to [0, 100]; non-numbers fall back. */
+function pctOr(v: unknown, fallback: number): number {
+	if (typeof v !== "number" || !Number.isFinite(v)) return fallback;
+	return Math.min(100, Math.max(0, v));
+}
+
+/** Require a finite token floor of at least 100k. */
+function minimumTokensOr(v: unknown, fallback: number): number {
+	if (typeof v !== "number" || !Number.isFinite(v)) return fallback;
+	return Math.max(MINIMUM_TOKEN_FLOOR, Math.round(v));
+}
+
+export const compactionSection = defineSection<"compaction", CompactionConfig>({
+	key: "compaction",
+	defaults: DEFAULTS,
+	parse(raw) {
+		if (!isObj(raw)) return { ...DEFAULTS };
+		return {
+			triggerPercent: pctOr(raw.triggerPercent, DEFAULTS.triggerPercent),
+			minimumTokens: minimumTokensOr(raw.minimumTokens, DEFAULTS.minimumTokens),
+		};
+	},
+});

package/src/sections/index.ts

@@ -1,4 +1,5 @@
 export { type CollapseConfig, collapseSection } from "./collapse.ts";
+export { type CompactionConfig, compactionSection } from "./compaction.ts";
 export {
 	type GateConfig,
 	type GateRuleConfig,
@@ -22,6 +23,7 @@ export {
 } from "./pretty.ts";
 
 import { collapseSection } from "./collapse.ts";
+import { compactionSection } from "./compaction.ts";
 import { gateSection } from "./gate.ts";
 import { ioSection } from "./io.ts";
 import { optimizerSection } from "./optimizer.ts";
@@ -34,4 +36,5 @@ export const builtinSections = [
 	ioSection,
 	optimizerSection,
 	gateSection,
+	compactionSection,
 ] as const;

package/src/sections/optimizer.ts

@@ -7,7 +7,6 @@ export type Toggle = "off" | "on";
 export interface OptimizerConfig {
 	caveman: CavemanLevel;
 	rtk: Toggle;
-	toon: Toggle;
 	ponytail: PonytailLevel;
 }
 
@@ -18,7 +17,6 @@ const TOGGLE: readonly Toggle[] = ["off", "on"];
 const DEFAULTS: Readonly<OptimizerConfig> = {
 	caveman: "off",
 	rtk: "on",
-	toon: "on",
 	ponytail: "off",
 };
 
@@ -30,7 +28,6 @@ export const optimizerSection = defineSection<"optimizer", OptimizerConfig>({
 		return {
 			caveman: enumOr(raw.caveman, CAVEMAN, DEFAULTS.caveman),
 			rtk: enumOr(raw.rtk, TOGGLE, DEFAULTS.rtk),
-			toon: enumOr(raw.toon, TOGGLE, DEFAULTS.toon),
 			ponytail: enumOr(raw.ponytail, PONYTAIL, DEFAULTS.ponytail),
 		};
 	},