@lll9p/pi-better-compaction 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lll9p
+
+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,183 @@
+# pi-better-compaction
+
+A Pi extension that upgrades compaction with two coordinated strategies:
+
+1. **OpenAI Responses APIs** (`openai-responses`, `openai-codex-responses`) use the provider's
+   native `/responses/compact` endpoint, then replay the opaque compacted window on later
+   requests without patching Pi core.
+2. **Every other API** (Anthropic, Gemini, etc.) runs Pi's own native compaction method,
+   optionally driven by a **dedicated compaction model** so you can summarize with a cheaper/faster
+   model than the one you are chatting with.
+
+Everything fails open: if any step cannot proceed, the extension returns control to Pi's default
+compaction so a compaction never breaks because of this extension.
+
+## Requirements
+
+- **Minimum Pi version:** `@earendil-works/pi-coding-agent >= 0.80.0`
+
+This extension relies on `modelRegistry.getApiKeyAndHeaders(model)` and the exported native
+`compact()` function.
+
+## Behavior
+
+The `session_before_compact` decision tree:
+
+```
+session_before_compact
+│
+├─ config.enabled == false ───────────────────────► Pi default compaction
+│
+├─ current model API is a Responses API
+│   │  (openai-responses / openai-codex-responses, narrowable via config)
+│   ├─ POST /responses/compact
+│   │   ├─ success ─────────────────────────────────► store opaque window + real summary
+│   │   ├─ user aborted ─────────────────────────────► cancel
+│   │   └─ failure (404 / network / malformed) ──────► fall through ▼
+│   └─ (missing base URL / API key) ─────────────────► fall through ▼
+│
+├─ config.compactionModel is set and resolvable and ≠ current model
+│   └─ run Pi's native compact() with that model ────► use its result
+│
+└─ otherwise ─────────────────────────────────────► Pi default compaction
+      (no model configured, or it equals the current model — Pi runs the
+       same native method itself, keeping its streaming progress UI)
+```
+
+On the next supported Responses request after a native `/responses/compact`, the
+`before_provider_request` hook rewrites Pi's summary-oriented replay into:
+
+- fresh current prompt envelope
+- stored opaque compacted window
+- live post-compaction tail
+
+Requests produced by the native-method fallback carry Pi's standard `{readFiles, modifiedFiles}`
+details, so they replay through Pi's default path — no rewrite, no special handling.
+
+### Selection is by API, not provider
+
+Any provider speaking a Responses API gets a native compact attempt, including OpenAI-compatible
+proxies with a custom `baseUrl`. If such an endpoint does not implement `/responses/compact`, the
+request 404s and the extension fails through to the configured fallback model (or Pi default). To
+avoid the probe entirely for one API, narrow `responsesCompactApis`.
+
+## Install
+
+From npm (recommended):
+
+```bash
+pi install npm:@lll9p/pi-better-compaction
+```
+
+Try it for a single run without installing:
+
+```bash
+pi -e npm:@lll9p/pi-better-compaction
+```
+
+From a checkout (development):
+
+```bash
+git clone https://github.com/lll9p/pi-better-compaction.git
+cd pi-better-compaction
+pi install .
+```
+
+After installation, run `/reload`.
+
+## Configuration
+
+Single source, merged over built-in defaults:
+
+```
+~/.pi/agent/extensions/pi-better-compaction/config.json
+```
+
+A missing file silently uses the defaults below. The extension never writes this file for you.
+
+```json
+{
+  "enabled": true,
+
+  "compactionModel": "openai/gpt-5.1-mini",
+  "compactionThinkingLevel": "off",
+
+  "responsesCompactApis": ["openai-responses", "openai-codex-responses"],
+
+  "notifyOnLoad": false,
+  "debug": false,
+  "logProviderPayloads": false,
+  "logCompactResponses": false,
+  "redactSensitiveData": true,
+  "artifactRoot": "~/.pi/agent/artifacts/pi-better-compaction"
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `enabled` | `true` | Master switch. `false` → Pi default compaction everywhere. |
+| `compactionModel` | *(unset)* | `"provider/model-id"` used for native-method fallback (non-Responses APIs, or when the compact endpoint fails). `null`/unset → use the current model via Pi's default path. The provider is split on the first `/`, so model ids may contain slashes (e.g. `"openrouter/deepseek/deepseek-chat"`). |
+| `compactionThinkingLevel` | `"off"` | Thinking level passed to the native `compact()` fallback. One of `off, minimal, low, medium, high, xhigh, max`. |
+| `responsesCompactApis` | both Responses APIs | Which Responses APIs use the compact endpoint. May only narrow the built-in set; unknown entries are ignored with a warning. |
+| `notifyOnLoad` | `false` | Show a load notification in the TUI. |
+| `debug` | `false` | Write lifecycle + compaction-event artifacts. |
+| `logProviderPayloads` | `false` | Write `before_provider_request` payload artifacts. |
+| `logCompactResponses` | `false` | Write compact endpoint request/response artifacts. |
+| `redactSensitiveData` | `true` | Redact secrets in artifacts. Keep on. |
+| `artifactRoot` | `~/.pi/agent/artifacts/pi-better-compaction` | Debug artifact root. `~/` and relative paths (resolved against the config dir) are supported. |
+
+### Codex-aligned compact request
+
+For Responses compaction, the extension mirrors the latest codex_rs `CompactionInput` fields
+(`tools`, `parallel_tool_calls`, `reasoning`, `service_tier`, `prompt_cache_key`, `text`) by
+capturing them from the most recent live provider request for the same model/session and attaching
+them to the compact request body. When no such request has been seen yet, the compact request falls
+back to the minimal `model` / `input` / `instructions` body.
+
+## Debug artifacts
+
+Written per session under:
+
+```
+<artifactRoot>/sessions/<session-id>/
+├── provider-requests/
+├── compact-responses/
+├── compaction-events/
+└── lifecycle/
+```
+
+Troubleshooting flow:
+
+1. set `debug: true` and `logCompactResponses: true` (keep `redactSensitiveData: true`)
+2. `/reload`
+3. run `/compact`, then send a follow-up message
+4. inspect the newest artifact in the session directory
+
+## Package structure
+
+```
+package-root/
+├── index.ts                     # entrypoint declared in package.json
+├── src/
+│   ├── extension-runtime.ts     # hook registration + compaction decision tree
+│   ├── config.ts                # config.json loader (single source + defaults)
+│   ├── runtime.ts               # API-based environment resolution + auth
+│   ├── compact-client.ts        # /responses/compact client + summary extraction
+│   ├── native-fallback.ts       # configured-model native compact() driver
+│   ├── request-context-cache.ts # captures codex-aligned fields from live requests
+│   ├── serializer.ts            # Responses input serialization
+│   ├── payload-rewrite.ts       # native opaque-window replay rewrite
+│   ├── details-store.ts         # latest-valid native compaction lookup
+│   ├── debug.ts                 # artifact writing + redaction
+│   ├── supported-environment.ts # re-exports
+│   └── types.ts                 # config + persisted native-compaction types
+└── test/
+```
+
+## Tests
+
+```bash
+bun test
+bun test --coverage --coverage-reporter=text --coverage-reporter=lcov
+bun test ./test/pi-smoke.test.ts
+```

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/extension-runtime.ts";

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@lll9p/pi-better-compaction",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Better compaction for pi: native /responses/compact replay for OpenAI Responses APIs, plus a configurable compaction model driving pi's native summarization everywhere else.",
+  "author": "Lilin Lao",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lll9p/pi-better-compaction.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lll9p/pi-better-compaction/issues"
+  },
+  "homepage": "https://github.com/lll9p/pi-better-compaction#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "openai",
+    "compaction",
+    "codex",
+    "responses"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "src/compact-client.ts",
+    "src/config.ts",
+    "src/debug.ts",
+    "src/details-store.ts",
+    "src/extension-runtime.ts",
+    "src/native-fallback.ts",
+    "src/payload-rewrite.ts",
+    "src/request-context-cache.ts",
+    "src/runtime.ts",
+    "src/serializer.ts",
+    "src/supported-environment.ts",
+    "src/types.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=text --coverage-reporter=lcov && node ./scripts/check-lcov.mjs ./coverage/lcov.info",
+    "test:pi": "bun test ./test/pi-smoke.test.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": ">=0.80.0"
+  }
+}

package/src/compact-client.ts

@@ -0,0 +1,428 @@
+import { writeDebugArtifact } from "./debug";
+import type { NativeCompactionRuntime } from "./runtime";
+import type { NativeCompactionRequestBody } from "./serializer";
+import type { ArtifactContext, ExtensionConfig } from "./types";
+
+const JSON_CONTENT_TYPE = "application/json";
+
+type CompactResponseEnvelope = {
+	id?: string;
+	created_at?: number | string;
+	output: unknown[];
+	[key: string]: unknown;
+};
+
+export type NativeCompactionClientFailureReason =
+	| "aborted"
+	| "network-error"
+	| "non-2xx"
+	| "empty-body"
+	| "invalid-json"
+	| "malformed-response"
+	| "empty-output";
+
+export type NativeCompactionClientSuccess = {
+	ok: true;
+	status: number;
+	compactedWindow: unknown[];
+	compactResponseId?: string;
+	createdAt?: string;
+	/** Assistant summary text extracted from the compact output, for CompactionEntry.summary. */
+	summaryText?: string;
+	response: CompactResponseEnvelope;
+};
+
+export type NativeCompactionClientFailure = {
+	ok: false;
+	reason: NativeCompactionClientFailureReason;
+	status?: number;
+	errorMessage?: string;
+	responseText?: string;
+	responseJson?: unknown;
+};
+
+export type NativeCompactionClientResult = NativeCompactionClientSuccess | NativeCompactionClientFailure;
+
+export type ExecuteNativeCompactionOptions = {
+	runtime: NativeCompactionRuntime;
+	request: NativeCompactionRequestBody;
+	signal?: AbortSignal;
+	settings?: ExtensionConfig;
+	context?: ArtifactContext;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isAbortError(error: unknown): boolean {
+	return (
+		(error instanceof DOMException && error.name === "AbortError") ||
+		(error instanceof Error && (error.name === "AbortError" || error.name === "ABORT_ERR"))
+	);
+}
+
+function normalizeResponseTimestamp(value: unknown): string | undefined {
+	if (typeof value === "number" && Number.isFinite(value)) {
+		const milliseconds = value > 1_000_000_000_000 ? value : value * 1000;
+		return new Date(milliseconds).toISOString();
+	}
+
+	if (typeof value !== "string") {
+		return undefined;
+	}
+
+	const trimmed = value.trim();
+	if (!trimmed) {
+		return undefined;
+	}
+
+	const parsed = Date.parse(trimmed);
+	return Number.isNaN(parsed) ? trimmed : new Date(parsed).toISOString();
+}
+
+function isCompactOutputItem(value: unknown): value is Record<string, unknown> {
+	return isRecord(value);
+}
+
+function isCompactResponseEnvelope(value: unknown): value is CompactResponseEnvelope {
+	return isRecord(value) && Array.isArray(value.output) && value.output.every(isCompactOutputItem);
+}
+
+/**
+ * Extract the assistant-authored summary text from the compacted window so the
+ * persisted CompactionEntry.summary carries real context. Without this, switching
+ * to a non-Responses model later would replay a meaningless placeholder.
+ */
+export function extractCompactedSummaryText(output: readonly unknown[]): string | undefined {
+	const texts: string[] = [];
+	for (const item of output) {
+		if (!isRecord(item) || item.type !== "message" || item.role !== "assistant" || !Array.isArray(item.content)) {
+			continue;
+		}
+		for (const block of item.content) {
+			if (isRecord(block) && block.type === "output_text" && typeof block.text === "string" && block.text.trim()) {
+				texts.push(block.text.trim());
+			}
+		}
+	}
+
+	const joined = texts.join("\n\n").trim();
+	return joined.length > 0 ? joined : undefined;
+}
+
+function decodeJwtPayload(token: string): Record<string, unknown> | undefined {
+	const parts = token.split(".");
+	if (parts.length !== 3) {
+		return undefined;
+	}
+
+	try {
+		const payloadText = Buffer.from(parts[1]!, "base64url").toString("utf8");
+		const payload = JSON.parse(payloadText);
+		return isRecord(payload) ? payload : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function extractCodexAccountId(token: string): string | undefined {
+	const payload = decodeJwtPayload(token);
+	const authClaims = payload?.["https://api.openai.com/auth"];
+	if (!isRecord(authClaims)) {
+		return undefined;
+	}
+
+	const accountId = authClaims.chatgpt_account_id;
+	return typeof accountId === "string" && accountId.trim().length > 0 ? accountId.trim() : undefined;
+}
+
+function buildCodexUserAgent(): string {
+	const platform = typeof process !== "undefined" ? process.platform : "browser";
+	const arch = typeof process !== "undefined" ? process.arch : "unknown";
+	return `pi (${platform}; ${arch})`;
+}
+
+function toHeaders(runtime: NativeCompactionRuntime): Record<string, string> {
+	const headers = new Headers(runtime.currentModel.headers ?? {});
+	for (const [key, value] of Object.entries(runtime.headers ?? {})) {
+		headers.set(key, value);
+	}
+	headers.set("accept", JSON_CONTENT_TYPE);
+	headers.set("content-type", JSON_CONTENT_TYPE);
+	if (!headers.has("authorization")) {
+		headers.set("authorization", `Bearer ${runtime.apiKey}`);
+	}
+
+	if (runtime.api === "openai-codex-responses") {
+		const accountId = extractCodexAccountId(runtime.apiKey);
+		if (accountId) {
+			headers.set("chatgpt-account-id", accountId);
+		}
+		headers.set("originator", "pi");
+		headers.set("user-agent", buildCodexUserAgent());
+		headers.set("openai-beta", "responses=experimental");
+	}
+
+	return Object.fromEntries(headers.entries());
+}
+
+function writeCompactArtifact(
+	data: unknown,
+	settings: ExtensionConfig | undefined,
+	context: ArtifactContext | undefined,
+): void {
+	if (!settings || !context) {
+		return;
+	}
+
+	writeDebugArtifact("compact-response", data, settings, context);
+}
+
+export async function executeNativeCompaction(
+	options: ExecuteNativeCompactionOptions,
+): Promise<NativeCompactionClientResult> {
+	const { runtime, request, signal, settings, context } = options;
+	const headers = toHeaders(runtime);
+
+	if (signal?.aborted) {
+		const aborted: NativeCompactionClientFailure = {
+			ok: false,
+			reason: "aborted",
+		};
+		writeCompactArtifact(
+			{
+				request: {
+					url: runtime.compactUrl,
+					headers,
+					body: request,
+				},
+				outcome: aborted,
+			},
+			settings,
+			context,
+		);
+		return aborted;
+	}
+
+	try {
+		const response = await fetch(runtime.compactUrl, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(request),
+			signal,
+		});
+		const responseText = await response.text();
+		const responseHeaders: Record<string, string> = {};
+		response.headers.forEach((value, key) => {
+			responseHeaders[key] = value;
+		});
+
+		if (!response.ok) {
+			let responseJson: unknown;
+			if (responseText.trim().length > 0) {
+				try {
+					responseJson = JSON.parse(responseText);
+				} catch {
+					responseJson = undefined;
+				}
+			}
+
+			const failure: NativeCompactionClientFailure = {
+				ok: false,
+				reason: "non-2xx",
+				status: response.status,
+				responseText: responseText || undefined,
+				responseJson,
+			};
+			writeCompactArtifact(
+				{
+					request: {
+						url: runtime.compactUrl,
+						headers,
+						body: request,
+					},
+					response: {
+						status: response.status,
+						headers: responseHeaders,
+						body: responseJson ?? responseText,
+					},
+					outcome: failure,
+				},
+				settings,
+				context,
+			);
+			return failure;
+		}
+
+		if (!responseText.trim()) {
+			const failure: NativeCompactionClientFailure = {
+				ok: false,
+				reason: "empty-body",
+				status: response.status,
+			};
+			writeCompactArtifact(
+				{
+					request: {
+						url: runtime.compactUrl,
+						headers,
+						body: request,
+					},
+					response: {
+						status: response.status,
+						headers: responseHeaders,
+						body: responseText,
+					},
+					outcome: failure,
+				},
+				settings,
+				context,
+			);
+			return failure;
+		}
+
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(responseText);
+		} catch (error) {
+			const failure: NativeCompactionClientFailure = {
+				ok: false,
+				reason: "invalid-json",
+				status: response.status,
+				errorMessage: error instanceof Error ? error.message : String(error),
+				responseText,
+			};
+			writeCompactArtifact(
+				{
+					request: {
+						url: runtime.compactUrl,
+						headers,
+						body: request,
+					},
+					response: {
+						status: response.status,
+						headers: responseHeaders,
+						body: responseText,
+					},
+					outcome: failure,
+				},
+				settings,
+				context,
+			);
+			return failure;
+		}
+
+		if (!isCompactResponseEnvelope(parsed)) {
+			const failure: NativeCompactionClientFailure = {
+				ok: false,
+				reason: "malformed-response",
+				status: response.status,
+				responseJson: parsed,
+			};
+			writeCompactArtifact(
+				{
+					request: {
+						url: runtime.compactUrl,
+						headers,
+						body: request,
+					},
+					response: {
+						status: response.status,
+						headers: responseHeaders,
+						body: parsed,
+					},
+					outcome: failure,
+				},
+				settings,
+				context,
+			);
+			return failure;
+		}
+
+		if (parsed.output.length === 0) {
+			const failure: NativeCompactionClientFailure = {
+				ok: false,
+				reason: "empty-output",
+				status: response.status,
+				responseJson: parsed,
+			};
+			writeCompactArtifact(
+				{
+					request: {
+						url: runtime.compactUrl,
+						headers,
+						body: request,
+					},
+					response: {
+						status: response.status,
+						headers: responseHeaders,
+						body: parsed,
+					},
+					outcome: failure,
+				},
+				settings,
+				context,
+			);
+			return failure;
+		}
+
+		const success: NativeCompactionClientSuccess = {
+			ok: true,
+			status: response.status,
+			compactedWindow: [...parsed.output],
+			compactResponseId: typeof parsed.id === "string" && parsed.id.trim() ? parsed.id.trim() : undefined,
+			createdAt: normalizeResponseTimestamp(parsed.created_at),
+			summaryText: extractCompactedSummaryText(parsed.output),
+			response: parsed,
+		};
+		writeCompactArtifact(
+			{
+				request: {
+					url: runtime.compactUrl,
+					headers,
+					body: request,
+				},
+				response: {
+					status: response.status,
+					headers: responseHeaders,
+					body: parsed,
+				},
+				outcome: {
+					ok: true,
+					status: success.status,
+					compactResponseId: success.compactResponseId,
+					createdAt: success.createdAt,
+					compactedItems: success.compactedWindow.length,
+				},
+			},
+			settings,
+			context,
+		);
+		return success;
+	} catch (error) {
+		const failure: NativeCompactionClientFailure = isAbortError(error)
+			? {
+				ok: false,
+				reason: "aborted",
+			}
+			: {
+				ok: false,
+				reason: "network-error",
+				errorMessage: error instanceof Error ? error.message : String(error),
+			};
+
+		writeCompactArtifact(
+			{
+				request: {
+					url: runtime.compactUrl,
+					headers,
+					body: request,
+				},
+				outcome: failure,
+			},
+			settings,
+			context,
+		);
+		return failure;
+	}
+}