@xynogen/pix-runtime 0.4.2 → 0.5.1

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.2",
+	"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/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",

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;