pi-jev-compact 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing to pi-jev-compact
+
+Thanks for considering a contribution!
+
+## Setup
+
+```sh
+git clone https://github.com/019ec6e2/pi-jev-compact && cd pi-jev-compact
+npm install
+export TYPESAFE_API_KEY=...   # optional; only for `npm run demo`
+```
+
+No build step: pi loads extensions via jiti, so TypeScript source runs as-is.
+
+## Verify before opening a PR
+
+```sh
+npm run typecheck   # tsc --noEmit (TS 7, strict flags)
+npm run lint        # biome check (auto-fix: npm run lint:fix)
+npm test            # vitest, offline, no API key needed
+```
+
+CI-ready chain: `npm run lint && npm run typecheck && npm test`.
+
+## Ground rules
+
+- **The engine (`src/jev/`) is shared with upstream
+  [`fast-jev-compaction`](https://github.com/019ec6e2/fast-jev-compaction)** and its
+  behavior is pinned by the ported test suite (decisions, state fitting, batching,
+  request format). Change it only with tests updated accordingly, and note in the PR
+  description whether the change belongs upstream too.
+- **Host code (`src/index.ts`, `src/adapter.ts`, `src/config.ts`)** must keep the
+  fallback contract: any error, missing key, or insufficient reduction returns
+  `undefined` so pi's built-in summary runs. Compaction must never hard-fail a session.
+- **No API keys in code, tests, or fixtures.** Tests use a fake asker; the only live
+  network check is `npm run demo`, gated on the environment key.
+- Keep the zero-build property: no syntax that requires codegen (erasable-syntax-only),
+  no bundler, `.ts` import specifiers.
+- Formatting/lint is Biome; run `npm run lint:fix` rather than hand-formatting.
+
+## What's worth contributing
+
+- The phase-2 `context`-event soft-pruning mode (`FAST_JEV_MODE=context`, see
+  `ADAPTATION.md` §3 Option B)
+- Tokenizer-accurate size estimates to replace the heuristic estimator
+- Live-session validation reports (threshold auto-compact, overflow/`willRetry` path)
+- Docs: real-world configuration examples, provider notes
+
+## Commit style
+
+Conventional-ish prefixes (`feat:`, `fix:`, `docs:`, `test:`, `chore:`), one logical
+change per commit.

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 pi-jev-compact contributors
+
+Engine ported from fast-jev-compaction (https://github.com/019ec6e2/fast-jev-compaction), MIT.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# pi-jev-compact
+
+[![tests](https://img.shields.io/badge/tests-37%20passing-brightgreen)]() [![typescript](https://img.shields.io/badge/TypeScript-7-3178c6)]() [![pi](https://img.shields.io/badge/pi-extension-blueviolet)]()
+
+**Verbatim context compaction for [pi](https://pi.dev)**, powered by the [TypeSafe Jev](https://api.typesafe.ai) model.
+
+Replaces pi's LLM-written compaction summary with surgical pruning: every historical
+tool call is scored in one fast Jev request — stale calls are dropped, results that are
+no longer needed are truncated to a bounded head + note, and **everything kept stays
+word-for-word**. No lossy summarization, ever.
+
+Port of [`fast-jev-compaction`](https://github.com/019ec6e2/fast-jev-compaction)
+(Claude Code plugin) to a pi extension. See [`ADAPTATION.md`](./ADAPTATION.md) for the
+design mapping.
+
+## Why
+
+Most context compaction asks an LLM to summarize old turns. A summary is lossy: a file
+path, exact error, constraint, or command can disappear even when it matters later.
+This extension never rewrites anything. It only deletes tool calls and results Jev says
+are no longer needed, and it asks Jev while showing it the whole conversation. User and
+assistant text stays verbatim and in order.
+
+## How it works
+
+```
+pi auto-compact (threshold) ─┐
+/compact ────────────────────┼─► session_before_compact ─► [fast-jev engine]
+/jev-compact ────────────────┘         │
+                                       ▼
+                     1. Pair every tool call with its result
+                     2. Pin the kept tail (pi's firstKeptEntryId)
+                     3. Send the whole history (results omitted) as state,
+                        fitted to 25k tokens in stages
+                     4. Ask Jev per call: keep the call? keep the result verbatim?
+                     5. Decide: keep · truncate result (head + note) · drop call+result
+                     6. Return the pruned transcript VERBATIM as the compaction summary
+                         │
+                         └─ not enough reduction / Jev failed / no key?
+                            → pi's built-in LLM summary (graceful fallback)
+```
+
+Dropped results keep their first `FAST_JEV_TRUNCATE_HEAD_CHARS` characters plus a
+note (`[fast-jev-compaction truncated N chars of this tool result; re-run the tool if
+needed]`), so the model knows it can re-run the tool. Repeated compactions chain:
+the previous pruned history is prepended as `[Earlier compacted history]`.
+
+## Install
+
+**From a checkout (dev, hot-reloadable):**
+
+```sh
+git clone https://github.com/019ec6e2/pi-jev-compact
+ln -s "$PWD/pi-jev-compact" ~/.pi/agent/extensions/pi-jev-compact
+```
+
+**As a pi package (npm or git):**
+
+```sh
+pi install git:github.com/019ec6e2/pi-jev-compact@v1
+# or
+pi install npm:pi-jev-compact
+```
+
+Runtime dependency is `typebox` only; pi resolves it on install.
+
+## Setup
+
+```sh
+export TYPESAFE_API_KEY=...   # or FAST_JEV_API_KEY
+```
+
+Without a key the extension stays passive — pi's built-in compaction runs untouched.
+
+## Usage
+
+Nothing to do: pi's own auto-compaction threshold routes through fast-jev, as do
+`/compact` and overflow recovery. Extras:
+
+| Command | Effect |
+|---|---|
+| `/jev-compact` | Trigger compaction now (pi's flow, fast-jev decides) |
+| `/jev-compact focus on the DB migration` | Optional instructions → used by the built-in summary if we fall back |
+
+After each compaction you get a notification with the outcome and a footer widget:
+
+```
+fast-jev: compaction done (fast-jev, extension-provided, manual) —
+messages 4/10, calls 0 kept / 0 truncated / 3 dropped / 0 pinned —
+state ~531 tokens (full), 1 request(s), 623ms
+```
+
+Falls back with an explicit reason, e.g. `fast-jev: fallback to built-in summary
+(below 25% minimum: …)`.
+
+## Configuration
+
+Precedence: defaults < environment < project file.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `FAST_JEV_API_KEY` / `TYPESAFE_API_KEY` | — | TypeSafe API key (extension is passive without it) |
+| `FAST_JEV_MODEL` | `jev-latest` | Jev model |
+| `FAST_JEV_KEEP_THRESHOLD` | `0.5` | Minimum keep probability for a call or result to stay |
+| `FAST_JEV_MIN_REDUCTION` | `0.25` | Below this character reduction, fall back to the built-in summary |
+| `FAST_JEV_PRESERVE_RECENT` | `2` | Newest messages *inside the summarized span* never touched (pi already keeps its own recent tail) |
+| `FAST_JEV_MAX_STATE_TOKENS` | `25000` | Token ceiling for the state sent to Jev |
+| `FAST_JEV_MAX_REQUEST_TOKENS` | `30000` | Ceiling for state plus one batch of questions |
+| `FAST_JEV_TRUNCATE_HEAD_CHARS` | `300` | Characters of a truncated result retained |
+| `FAST_JEV_GOAL` | last user prompts | Task hint included in the state |
+
+Project-local overrides in `.pi/fast-jev.json` (read only for trusted projects), same
+keys in camelCase (`apiKey`, `model`, `keepThreshold`, `minReductionRatio`,
+`preserveRecentMessages`, `maxStateTokens`, `maxRequestTokens`, `truncateHeadChars`, `goal`).
+
+## Architecture
+
+```
+src/
+├── index.ts      entry: session_before_compact handler, /jev-compact, stats reporting
+├── adapter.ts    pi AgentMessage ⇄ library Message (via pi's convertToLlm),
+│                 verbatim summary serializer with previousSummary chaining
+├── config.ts     env + project-file config resolution
+└── jev/          host-agnostic engine (ported from fast-jev-compaction):
+    types, request/client, state fitting, batching, decisions, rebuild
+```
+
+pi loads extensions via jiti — no build step. `tsc` is type-checking only.
+
+| Milestone tool | Role |
+|---|---|
+| TypeScript 7 | type checking only (`tsc --noEmit`), strictest flags |
+| Biome 2 | lint + format + import organizing |
+| Vitest 4 | unit tests (fake Jev asker — no network in tests) |
+
+## Development
+
+```sh
+npm install
+npm run typecheck        # tsc --noEmit
+npm run lint             # biome check
+npm test                 # vitest, offline
+npm run demo             # live Jev round-trip; skips safely without TYPESAFE_API_KEY
+npm run dev              # pi -e ./src/index.ts
+```
+
+The test suite covers the ported engine (options, token estimation, call collection,
+state-fitting stages, batching, decisions, HTTP client) plus pi-side adapter mapping,
+verbatim serialization, config layering, and an end-to-end pi-transcript round trip.
+
+## Notes and limitations
+
+- Pruned content is gone: Jev is a probability, not a guarantee. The assistant can
+  always re-run a tool.
+- The summarized span becomes text — images and thinking blocks in that span are not
+  reproduced (pi's kept tail is untouched, images there survive).
+- The full state is resent with each question batch (near the state ceiling that is
+  one request per handful of calls).
+- Token sizes are estimates from character counts, not a tokenizer.
+- API keys are read from the environment at session start; never commit one. A
+  project `.pi/fast-jev.json` is only honored for trusted projects.
+
+## Credits
+
+Engine and algorithm by [`fast-jev-compaction`](https://github.com/019ec6e2/fast-jev-compaction)
+(MIT). pi adaptation by this repository (MIT).

package/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Root entry point so pi's directory auto-discovery
+ * (`~/.pi/agent/extensions/stigmergy/` → `index.ts`) finds the extension,
+ * with the real implementation in `src/index.ts`.
+ */
+
+export * from "./src/index.ts";
+export { default } from "./src/index.ts";

package/package.json

@@ -0,0 +1,61 @@
+{
+	"name": "pi-jev-compact",
+	"version": "0.1.0",
+	"description": "Verbatim context compaction for pi, powered by the TypeSafe Jev model",
+	"type": "module",
+	"license": "MIT",
+	"keywords": [
+		"pi-package",
+		"pi",
+		"pi-extension",
+		"compaction",
+		"context-window"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/019ec6e2/pi-jev-compact.git"
+	},
+	"bugs": "https://github.com/019ec6e2/pi-jev-compact/issues",
+	"files": [
+		"index.ts",
+		"src",
+		"README.md",
+		"LICENSE",
+		"CONTRIBUTING.md"
+	],
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	},
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check .",
+		"lint:fix": "biome check --write .",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"demo": "tsx scripts/demo.ts",
+		"dev": "pi -e ./src/index.ts"
+	},
+	"dependencies": {},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"typebox": "*"
+	},
+	"peerDependenciesMeta": {
+		"@earendil-works/pi-coding-agent": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.14",
+		"@earendil-works/pi-coding-agent": "^0.85.1",
+		"@types/node": "^26",
+		"tsx": "^4.23.13",
+		"typescript": "^7.0.2",
+		"vitest": "^4.0.18"
+	}
+}

package/src/adapter.ts

@@ -0,0 +1,125 @@
+/**
+ * Adapter between pi's AgentMessage[] and the library's Message[].
+ *
+ * pi custom message types (bashExecution, custom, branchSummary,
+ * compactionSummary) are normalized first with pi's own `convertToLlm`, so the
+ * mapper below only deals with plain user/assistant/toolResult messages.
+ */
+import { convertToLlm } from "@earendil-works/pi-coding-agent";
+import type { Message, ToolResult, ToolUse } from "./jev/types.ts";
+
+/** Structurally derived so the extension doesn't import pi-agent-core directly. */
+type AgentMessageLike = Parameters<typeof convertToLlm>[0][number];
+
+function textOf(content: string | { type: string; text?: string; data?: string }[]): string {
+	if (typeof content === "string") return content;
+	return content
+		.map((block) => {
+			if (block.type === "text") return block.text ?? "";
+			if (block.type === "image") return "[image]";
+			return "";
+		})
+		.filter((text) => text.length > 0)
+		.join("\n");
+}
+
+/**
+ * Maps pi messages to library messages 1:1 (same order). Custom message types
+ * are already normalized to user/assistant/toolResult by `convertToLlm`.
+ */
+export function toLibraryMessages(messages: readonly AgentMessageLike[]): Message[] {
+	const llm = convertToLlm([...messages]);
+	const lib: Message[] = [];
+	for (const message of llm) {
+		if (message.role === "user") {
+			lib.push({ role: "user", text: textOf(message.content), toolUses: [] });
+		} else if (message.role === "assistant") {
+			const toolUses: ToolUse[] = [];
+			let text = "";
+			for (const block of message.content) {
+				if (block.type === "text") {
+					if (block.text.length > 0) text = text ? `${text}\n${block.text}` : block.text;
+				} else if (block.type === "toolCall") {
+					toolUses.push({
+						tool_use_id: block.id,
+						tool: block.name,
+						input: (block.arguments ?? {}) as Record<string, unknown>,
+					});
+				}
+			}
+			lib.push({ role: "assistant", text, toolUses });
+		} else if (message.role === "toolResult") {
+			const toolResults: ToolResult[] = [
+				{
+					tool_use_id: message.toolCallId,
+					text: textOf(message.content),
+					isError: message.isError,
+				},
+			];
+			lib.push({ role: "user", text: "", toolUses: [], toolResults });
+		}
+	}
+	return lib;
+}
+
+/**
+ * Serializes the pruned transcript as a verbatim summary. Dropped calls are
+ * absent; everything kept is word-for-word, including tool results (which may
+ * carry the library's bounded truncation note).
+ */
+export function serializePruned(
+	previousSummary: string | undefined,
+	messages: readonly Message[],
+): string {
+	const parts: string[] = [];
+	if (previousSummary && previousSummary.trim().length > 0) {
+		parts.push(`[Earlier compacted history]\n${previousSummary.trim()}`);
+	}
+	for (const message of messages) {
+		const header = message.role === "user" ? "[User]" : "[Assistant]";
+		const hasCalls = message.toolUses.length > 0;
+		const hasResults = (message.toolResults ?? []).length > 0;
+		if (message.text.trim().length > 0) {
+			parts.push(`${header}: ${message.text}`);
+		}
+		for (const use of message.toolUses) {
+			let input: string;
+			try {
+				input = JSON.stringify(use.input);
+			} catch {
+				input = "[unserializable input]";
+			}
+			parts.push(`[Tool Call] ${use.tool} id=${use.tool_use_id} ${input}`);
+		}
+		for (const toolResult of message.toolResults ?? []) {
+			const status = toolResult.isError ? "error" : "ok";
+			parts.push(`[Tool Result] id=${toolResult.tool_use_id} ${status}:\n${toolResult.text}`);
+		}
+		if (message.text.trim().length === 0 && !hasCalls && !hasResults) continue;
+	}
+	return parts.join("\n\n");
+}
+
+/** One-line human summary of the compaction outcome, for notifications. */
+export function describeStats(
+	stats: {
+		calls: number;
+		kept: number;
+		resultsDropped: number;
+		callsDropped: number;
+		pinned: number;
+		requests: number;
+		ms: number;
+	},
+	ratio: number,
+): string {
+	const percent = `${Math.round(ratio * 100)}%`;
+	const parts: string[] = [];
+	if (stats.kept > 0) parts.push(`${stats.kept} kept`);
+	if (stats.resultsDropped > 0) parts.push(`${stats.resultsDropped} results truncated`);
+	if (stats.callsDropped > 0) parts.push(`${stats.callsDropped} calls dropped`);
+	if (stats.pinned > 0) parts.push(`${stats.pinned} pinned`);
+	return `${percent} reduction; ${parts.join(", ") || "no tool calls"}; ${
+		stats.requests
+	} request(s), ${stats.ms}ms`;
+}

package/src/config.ts

@@ -0,0 +1,136 @@
+/**
+ * Configuration resolution for the fast-jev compaction extension.
+ *
+ * Order (later wins): built-in defaults < environment < project config file.
+ * The project file (`.pi/fast-jev.json`) is only read for trusted projects.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_MODEL } from "./jev/request.ts";
+import type { CompactOptions } from "./jev/types.ts";
+
+export const CONFIG_FILE = "fast-jev.json";
+
+export interface FastJevConfig extends CompactOptions {
+	/** TypeSafe API key; empty means "not configured" (extension stays passive). */
+	apiKey: string;
+	/** Jev model name. */
+	model?: string;
+	/** Minimum character reduction to accept the pruned transcript over the built-in summary. */
+	minReductionRatio: number;
+	/** Newest messages inside the summarized span never touched by Jev. */
+	preserveRecentMessages: number;
+}
+
+const DEFAULTS: FastJevConfig = {
+	apiKey: "",
+	minReductionRatio: 0.25,
+	preserveRecentMessages: 2,
+};
+
+type Mutable<T> = { -readonly [K in keyof T]: T[K] };
+
+function numberOr(value: unknown, fallback: number): number {
+	return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function stringOr(value: unknown): string | undefined {
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/** Reads `FAST_JEV_*` / `TYPESAFE_API_KEY` environment variables. */
+export function envConfig(env: NodeJS.ProcessEnv = process.env): Partial<FastJevConfig> {
+	const config: Partial<FastJevConfig> = {};
+	const key = stringOr(env["FAST_JEV_API_KEY"]) ?? stringOr(env["TYPESAFE_API_KEY"]);
+	if (key) config.apiKey = key;
+	const model = stringOr(env["FAST_JEV_MODEL"]);
+	if (model) config.model = model;
+	const threshold = env["FAST_JEV_KEEP_THRESHOLD"];
+	if (threshold !== undefined) {
+		const parsed = Number(threshold);
+		if (Number.isFinite(parsed)) config.keepThreshold = parsed;
+	}
+	const reduction = env["FAST_JEV_MIN_REDUCTION"];
+	if (reduction !== undefined) {
+		const parsed = Number(reduction);
+		if (Number.isFinite(parsed)) config.minReductionRatio = parsed;
+	}
+	const preserve = env["FAST_JEV_PRESERVE_RECENT"];
+	if (preserve !== undefined) {
+		const parsed = Number(preserve);
+		if (Number.isFinite(parsed)) config.preserveRecentMessages = Math.max(0, Math.floor(parsed));
+	}
+	const stateTokens = env["FAST_JEV_MAX_STATE_TOKENS"];
+	if (stateTokens !== undefined) {
+		const parsed = Number(stateTokens);
+		if (Number.isFinite(parsed)) config.maxStateTokens = parsed;
+	}
+	const requestTokens = env["FAST_JEV_MAX_REQUEST_TOKENS"];
+	if (requestTokens !== undefined) {
+		const parsed = Number(requestTokens);
+		if (Number.isFinite(parsed)) config.maxRequestTokens = parsed;
+	}
+	const head = env["FAST_JEV_TRUNCATE_HEAD_CHARS"];
+	if (head !== undefined) {
+		const parsed = Number(head);
+		if (Number.isFinite(parsed)) config.truncateHeadChars = Math.max(0, Math.floor(parsed));
+	}
+	const goal = stringOr(env["FAST_JEV_GOAL"]);
+	if (goal) config.goal = goal;
+	return config;
+}
+
+/**
+ * Reads the optional project-local config file (`.pi/fast-jev.json`). Only call
+ * this after confirming the project is trusted (`ctx.isProjectTrusted()`).
+ */
+export function fileConfig(cwd: string, configDirName = ".pi"): Partial<FastJevConfig> {
+	try {
+		const raw = readFileSync(join(cwd, configDirName, CONFIG_FILE), "utf8");
+		const parsed: unknown = JSON.parse(raw);
+		if (parsed === null || typeof parsed !== "object") return {};
+		const out: Partial<FastJevConfig> = {};
+		const record = parsed as Record<string, unknown>;
+		const key = stringOr(record["apiKey"]);
+		if (key) out.apiKey = key;
+		const model = stringOr(record["model"]);
+		if (model) out.model = model;
+		for (const field of ["keepThreshold", "minReductionRatio"] as const) {
+			if (record[field] !== undefined) {
+				const parsed2 = numberOr(record[field], Number.NaN);
+				if (Number.isFinite(parsed2)) out[field] = parsed2;
+			}
+		}
+		for (const field of [
+			"preserveRecentMessages",
+			"maxStateTokens",
+			"maxRequestTokens",
+			"truncateHeadChars",
+		] as const) {
+			if (record[field] !== undefined) {
+				const parsed2 = numberOr(record[field], Number.NaN);
+				if (Number.isFinite(parsed2)) out[field] = Math.max(0, Math.floor(parsed2));
+			}
+		}
+		const goal = stringOr(record["goal"]);
+		if (goal) out.goal = goal;
+		return out;
+	} catch {
+		return {};
+	}
+}
+
+export function resolveFastJevConfig(
+	...layers: (Partial<FastJevConfig> | undefined)[]
+): FastJevConfig {
+	const merged: Mutable<FastJevConfig> = { ...DEFAULTS };
+	for (const layer of layers) {
+		if (!layer) continue;
+		for (const [key, value] of Object.entries(layer)) {
+			if (value !== undefined) (merged as Record<string, unknown>)[key] = value;
+		}
+	}
+	return merged;
+}
+
+export { DEFAULT_MODEL };