@xynogen/pix-core 0.4.52 → 0.4.59

package/README.md

@@ -22,7 +22,7 @@ Pi activates extensions per installed package via each package's `pi.extensions`
 | `pix-diagnostics` | Compact LSP diagnostic widget |
 | `pix-display` | Paste chip rendering + thinking block display |
 | `pix-prompts` | System-prompt injection (AGENTS.md + repo directive files) |
-| `pix-skills` | Agent skill loader (`read_skills` tool + 29 bundled skills) |
+| `pix-skills` | Agent skill loader (`read_skills` tool + bundled on-demand skills, including TOON) |
 | `pix-nudge` | Tool + capability nudge hooks |
 
 **Tool suite** (drop-in replacements for Pi's built-in tools)
@@ -49,10 +49,12 @@ Pi activates extensions per installed package via each package's `pi.extensions`
 
 | Package | Description |
 |---|---|
-| `pix-data` | Shared model data layer (models.dev + BenchLM) cached at `~/.cache/pi`; hosts the unified `~/.pi/agent/pix.json` config loader and auto-collapse helper |
-| `pix-optimizer` | Caveman mode + RTK tool rewriting + jq/TOON JSON compression (`/opt`) |
+| `pix-data` | Shared model data layer (modelgrep + BenchLM) cached at `~/.cache/pi` |
+| `pix-runtime` | Unified `~/.pi/agent/pix.json` config runtime, `/pix` settings command, once guard, and auto-collapse policy |
+| `pix-optimizer` | Caveman mode + RTK tool rewriting + ponytail lazy-dev mode (`/optimizer`) |
 | `pix-gate` | Permission gate for dangerous bash commands |
 | `pix-subagent` | `agent` / `agent_result` / `agent_steer` — planner-driven sub-agents with live widget |
+| `compaction` | Built into pix-core: replaces pi's built-in context compaction with two levers. **Summary prompt is always pix's** — every compaction (manual `/compact`, threshold, overflow) generates the summary with the current conversation model (no silent routing) from an editable source prompt. **Trigger is pix's when `compaction.triggerPercent > 0`** — after each settled turn pix reads live context usage and compacts at `max(contextWindow × triggerPercent, compaction.minimumTokens)`. The default 100K floor prevents low percentages from compacting too early (for example, 10% of a 300K model waits for 100K rather than 30K); `0` disables pix's trigger and lets pi decide, while pix's summary prompt still applies. After a pix-triggered compaction pix sends a short, visible "resume" user message so the agent continues on its own. Every trigger, resume, and summary run emits a notify line (reason, model, token counts). |
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-core",
-	"version": "0.4.52",
+	"version": "0.4.59",
 	"description": "Pi extension bundle \u2014 installs and activates all core pix-* extensions",
 	"type": "module",
 	"main": "src/extension.ts",
@@ -38,16 +38,16 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@xynogen/pix-runtime": "^0.4.0",
+		"@xynogen/pix-runtime": "^0.5.1",
 		"@xynogen/pix-data": "^0.4.1",
 		"@xynogen/pix-pretty": "^1.8.1",
 		"@xynogen/pix-welcome": "^0.1.18",
 		"@xynogen/pix-footer": "^0.1.20",
 		"@xynogen/pix-diagnostics": "^0.1.10",
-		"@xynogen/pix-display": "^0.1.13",
+		"@xynogen/pix-display": "^0.1.14",
 		"@xynogen/pix-prompts": "^0.3.5",
-		"@xynogen/pix-skills": "^0.7.5",
-		"@xynogen/pix-models": "^0.1.24",
+		"@xynogen/pix-skills": "^0.7.6",
+		"@xynogen/pix-models": "^0.1.27",
 		"@xynogen/pix-update": "^0.1.17",
 		"@xynogen/pix-commands": "^0.2.5",
 		"@xynogen/pix-nudge": "^0.1.13",
@@ -59,12 +59,13 @@
 		"@xynogen/pix-ls": "^0.1.20",
 		"@xynogen/pix-bash": "^0.1.18",
 		"@xynogen/pix-todo": "^0.1.20",
-		"@xynogen/pix-ask": "^0.2.13",
-		"@xynogen/pix-optimizer": "^1.1.20",
-		"@xynogen/pix-gate": "^0.2.1",
+		"@xynogen/pix-ask": "^0.2.15",
+		"@xynogen/pix-optimizer": "^1.1.22",
+		"@xynogen/pix-gate": "^0.2.2",
 		"@xynogen/pix-subagent": "^0.6.3"
 	},
 	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
 		"@earendil-works/pi-coding-agent": "*",
 		"@earendil-works/pi-tui": "*"
 	}

package/src/compaction.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "bun:test";
+import { compactionThresholdTokens } from "./compaction.ts";
+
+describe("compactionThresholdTokens", () => {
+	it("uses the 100k floor when the percentage threshold is lower", () => {
+		expect(compactionThresholdTokens(300_000, 10, 100_000)).toBe(100_000);
+	});
+
+	it("uses the percentage threshold when it is higher than the floor", () => {
+		expect(compactionThresholdTokens(1_000_000, 60, 100_000)).toBe(600_000);
+	});
+});

package/src/compaction.ts

@@ -0,0 +1,183 @@
+/**
+ * pix-core compaction — replaces pi's built-in compaction so the prompt and
+ * trigger are ours to experiment with.
+ *
+ * Two independent levers (see AGENTS.md product constraints):
+ *
+ *   1. Summary prompt — ALWAYS ours. `session_before_compact` fires for every
+ *      compaction (manual, threshold, overflow); we generate the summary with
+ *      the CURRENT conversation model (no silent routing) using SUMMARY_PROMPT
+ *      below. Edit the prompt/format to experiment.
+ *
+ *   2. Trigger — ours when `compaction.triggerPercent > 0`. After each settled
+ *      turn we read live context usage and call ctx.compact() once token usage
+ *      reaches the larger of that percentage of the active model's context
+ *      window and `compaction.minimumTokens`. This prevents low percentages on
+ *      smaller models from compacting too early. Pi's own threshold stays as an
+ *      overflow safety net. `triggerPercent === 0` disables our trigger: we
+ *      keep our prompt but let pi decide when to compact.
+ *
+ * After a self-triggered compaction we send a short user message (RESUME_NUDGE)
+ * so the agent picks its task back up on its own. It's a normal user message —
+ * visible in the transcript, no hidden automation.
+ *
+ * Everything stays visible: each self-trigger, resume, and summary run emit a
+ * notify line with reason, model, and token counts.
+ */
+
+import { complete } from "@earendil-works/pi-ai/compat";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { convertToLlm, serializeConversation } from "@earendil-works/pi-coding-agent";
+import { config } from "@xynogen/pix-runtime/config";
+import { compactionSection } from "@xynogen/pix-runtime/sections";
+
+// ── Editable summary prompt ──────────────────────────────────────────────────
+// Keep-recent-turns strategy: summarize the OLD span into high-signal notes;
+// pi keeps recent turns verbatim (via firstKeptEntryId). This matches current
+// context-engineering guidance — recency is highest-signal, and "context rot"
+// makes full-history replacement risky. Tune freely.
+const SUMMARY_PROMPT = (previousSummary: string | undefined, conversation: string): string => {
+	const prior = previousSummary
+		? `\n\nPrevious summary (fold in, do not repeat verbatim):\n${previousSummary}`
+		: "";
+	return `You are summarizing the OLDER part of a coding session. Recent turns are kept verbatim after your summary, so capture only what those recent turns would otherwise lose.${prior}
+
+Produce compact, high-signal markdown with these sections (omit a section if empty):
+
+## Goal
+## Constraints & Preferences
+## Progress (Done / In Progress / Blocked)
+## Key Decisions (with rationale)
+## Next Steps
+## Critical Context (facts, paths, values needed to continue)
+
+Be terse. Prefer names, paths, numbers over prose. No filler.
+
+<conversation>
+${conversation}
+</conversation>`;
+};
+
+const MAX_SUMMARY_TOKENS = 8192;
+
+export function compactionThresholdTokens(
+	contextWindow: number,
+	triggerPercent: number,
+	minimumTokens: number,
+): number {
+	return Math.max(minimumTokens, Math.ceil((contextWindow * triggerPercent) / 100));
+}
+
+// Sent as a user message after a self-triggered compaction so the agent picks
+// its task back up on its own. Kept short — the freshly written summary already
+// carries the goal, progress, and next steps. Edit to taste.
+const RESUME_NUDGE =
+	"Context was just compacted. Review the summary above and continue the task from where you left off, following its Next Steps. If the task is already complete, say so.";
+
+export default function registerCompaction(pi: ExtensionAPI): void {
+	// ── Lever 1: always supply our own summary ────────────────────────────────
+	pi.on("session_before_compact", async (event, ctx) => {
+		const { preparation, reason, signal } = event;
+		const model = ctx.model;
+		if (!model) return; // no model → fall back to pi's built-in compaction
+
+		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+		if (!auth.ok) {
+			ctx.ui.notify(`Compaction: auth failed (${auth.error}); using built-in`, "warning");
+			return;
+		}
+
+		const messages = [...preparation.messagesToSummarize, ...preparation.turnPrefixMessages];
+		const conversation = serializeConversation(convertToLlm(messages));
+		ctx.ui.notify(
+			`Compaction (${reason}): summarizing ${messages.length} msgs / ${preparation.tokensBefore.toLocaleString()} tok with ${model.id}`,
+			"info",
+		);
+
+		try {
+			const response = await complete(
+				model,
+				{
+					messages: [
+						{
+							role: "user" as const,
+							content: [
+								{
+									type: "text" as const,
+									text: SUMMARY_PROMPT(preparation.previousSummary, conversation),
+								},
+							],
+							timestamp: Date.now(),
+						},
+					],
+				},
+				{
+					apiKey: auth.apiKey,
+					headers: auth.headers,
+					env: auth.env,
+					maxTokens: MAX_SUMMARY_TOKENS,
+					signal,
+					cacheRetention: "none",
+				},
+			);
+
+			const summary = response.content
+				.filter((c): c is { type: "text"; text: string } => c.type === "text")
+				.map((c) => c.text)
+				.join("\n")
+				.trim();
+
+			if (!summary) {
+				if (!signal.aborted) ctx.ui.notify("Compaction: empty summary; using built-in", "warning");
+				return;
+			}
+
+			return {
+				compaction: {
+					summary,
+					firstKeptEntryId: preparation.firstKeptEntryId,
+					tokensBefore: preparation.tokensBefore,
+					usage: response.usage,
+				},
+			};
+		} catch (error) {
+			if (signal.aborted) return;
+			const message = error instanceof Error ? error.message : String(error);
+			ctx.ui.notify(`Compaction failed (${message}); using built-in`, "error");
+			return;
+		}
+	});
+
+	// ── Lever 2: our own trigger, driven by live context usage ────────────────
+	let compacting = false;
+	pi.on("agent_settled", (_event, ctx) => {
+		if (compacting) return;
+		const { triggerPercent, minimumTokens } = config(compactionSection);
+		if (triggerPercent <= 0) return;
+
+		const usage = ctx.getContextUsage?.();
+		if (!usage || usage.tokens === null) return;
+		const tokens = usage.tokens;
+		const threshold = compactionThresholdTokens(usage.contextWindow, triggerPercent, minimumTokens);
+		if (tokens < threshold) return;
+
+		compacting = true;
+		ctx.ui.notify(
+			`Compaction: ${tokens.toLocaleString()} tok ≥ ${threshold.toLocaleString()} tok threshold (${triggerPercent}% ctx, ${minimumTokens.toLocaleString()} floor) — compacting`,
+			"info",
+		);
+		ctx.compact({
+			onComplete: () => {
+				compacting = false;
+				// Nudge the agent to pick its task back up. Visible as a normal
+				// user message in the transcript (no hidden automation).
+				ctx.ui.notify("Compaction: resuming task", "info");
+				pi.sendUserMessage(RESUME_NUDGE);
+			},
+			onError: (err) => {
+				compacting = false;
+				ctx.ui.notify(`Compaction trigger failed: ${err.message}`, "error");
+			},
+		});
+	});
+}

package/src/extension.ts

@@ -38,6 +38,7 @@ import registerTodo from "@xynogen/pix-todo/src/index.ts";
 import registerUpdate from "@xynogen/pix-update/src/extension.ts";
 import registerWelcome from "@xynogen/pix-welcome/src/extension.ts";
 import registerWrite from "@xynogen/pix-write/src/extension.ts";
+import registerCompaction from "./compaction.ts";
 
 // Members accept either the full `ExtensionAPI` or pix-pretty's looser
 // `PiPrettyApi` view of it. `ExtensionAPI` satisfies both, so we erase the
@@ -76,6 +77,9 @@ const MEMBERS: Factory[] = [
 	registerOptimizer,
 	registerGate,
 	registerSubagent,
+	// Custom compaction: replaces pi's built-in summary + trigger (reads
+	// compaction section; runs after runtime is live).
+	registerCompaction,
 ];
 
 export default function (pi: ExtensionAPI): void {