@xynogen/pix-runtime 0.4.2 → 0.5.2

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,19 @@ 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 and the hard minimum is 25K (values below clamp up);
+`/pix` offers 25K, 50K, 100K, 150K, 200K, 300K, 400K, 600K, 800K, and 1M.
+pix-core consumes both settings.
+
 Collapse policy helpers:
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-runtime",
-	"version": "0.4.2",
+	"version": "0.5.2",
 	"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/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";
@@ -36,6 +37,17 @@ function row<T>(r: SettingRow<T>): SettingRow<unknown> {
 	return r as SettingRow<unknown>;
 }
 
+/** Render a token count as a compact label: 1_000_000 → "1M", 150_000 → "150k". */
+function formatTokens(tokens: number): string {
+	return tokens % 1_000_000 === 0 ? `${tokens / 1_000_000}M` : `${tokens / 1000}k`;
+}
+
+/** Parse a compact token label ("1M", "150k") back to an absolute count. */
+function parseTokens(label: string): number {
+	const n = Number.parseFloat(label);
+	return /m$/i.test(label) ? n * 1_000_000 : n * 1000;
+}
+
 const SETTINGS: SettingRow<unknown>[] = [
 	row({
 		section: "Pretty",
@@ -77,6 +89,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: ["25k", "50k", "100k", "150k", "200k", "300k", "400k", "600k", "800k", "1M"],
+		read: (v) => formatTokens(v.minimumTokens),
+		patch: (value) => ({ minimumTokens: parseTokens(value) }),
+	}),
 	row({
 		section: "Gate",
 		label: "Guardrails",
@@ -97,7 +125,7 @@ function buildSummary(runtime: PixRuntime): string {
 			lastSection = row.section;
 		}
 		const value = row.read(runtime.get(row.handle));
-		const isDefault = value === row.values[0];
+		const isDefault = value === row.read(row.handle.defaults);
 		lines.push(`  ${row.label}: ${value}${isDefault ? "" : " *"}`);
 	}
 	return lines.join("\n");
@@ -169,7 +197,7 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 								const cursor = sel ? theme.fg("accent", "→") : " ";
 								const label = theme.fg(sel ? "accent" : "text", row.label.padEnd(labelW));
 								const value = row.read(runtime.get(row.handle));
-								const isDefault = value === row.values[0];
+								const isDefault = value === row.read(row.handle.defaults);
 								settingBodyLines[i] = body.length;
 								body.push(`${cursor} ${label}  ${theme.fg(isDefault ? "dim" : "success", value)}`);
 							}

package/src/sections/compaction.ts

@@ -0,0 +1,47 @@
+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 = 25_000;
+const MINIMUM_TOKEN_DEFAULT = 100_000;
+
+const DEFAULTS: Readonly<CompactionConfig> = {
+	triggerPercent: 60,
+	minimumTokens: MINIMUM_TOKEN_DEFAULT,
+};
+
+/** 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 25k. */
+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;