@saccolabs/pi-claude-cli 0.4.16 → 0.5.0

package/README.md

@@ -95,6 +95,38 @@ allowlists). Model access and your subscription login are unaffected.
 Related knobs: `PI_CLAUDE_CLI_TIMEOUT_MS` overrides the 300s inactivity
 timeout (CLI-side tools can be silent on stdout for minutes).
 
+### Auto-compact window
+
+The provider resumes **one** CLI session for a pi session's whole life, and
+nothing else ever shrinks it. On 1M-context models the CLI's own auto-compact
+default lets that session ratchet toward a million tokens — measured across 26
+real sessions, contexts reached 480k+, the average request carried 202k
+tokens, and every request re-reads the full context. So the provider passes
+`--autocompact 200000` **by default**: Claude Code compacts the session itself
+when its context nears 200k, keeping the cached system-prompt prefix and full
+transcript fidelity.
+
+`PI_CLAUDE_CLI_AUTOCOMPACT` configures it (read per spawn, like the flags
+above):
+
+| Value                   | Behaviour                                                                                      |
+| ----------------------- | ---------------------------------------------------------------------------------------------- |
+| _(unset)_               | `--autocompact 200000` — the 200k budget these models run under everywhere the 1M beta is off. |
+| `400k`, `400000`, `400` | Any window from 100k to 1M; bare numbers are thousands (CLI shorthand).                        |
+| `auto`                  | `--autocompact auto` — the CLI's own default (≈ the model's full window).                      |
+| `off`                   | Omit the flag entirely (use on CLIs that predate `--autocompact`).                             |
+
+The value is a token **count**, not a percentage: cache read/write bill per
+token and every request re-reads the whole context, so the sane budget is the
+same on a 200k model and a 1M one. Invalid values warn and fall back to the
+default instead of reaching the CLI, which rejects them by refusing to start.
+
+Note for pre-existing sessions: the first resumed turn of a session already
+past the window compacts immediately — one summarization pass, then the
+session continues small. That is the remediation, not a bug. pi's own
+compaction is separate (it rewrites pi's transcript, never the CLI session's)
+and with this cap it should rarely trigger.
+
 ### Which system prompt
 
 `PI_CLAUDE_CLI_SYSTEM_PROMPT` chooses whose system prompt the subprocess

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saccolabs/pi-claude-cli",
-  "version": "0.4.16",
+  "version": "0.5.0",
   "description": "Pi coding agent extension that routes LLM calls through the Claude Code CLI",
   "main": "index.ts",
   "keywords": [

package/src/autocompact.ts

@@ -0,0 +1,99 @@
+/**
+ * Auto-compact window resolution (PI_CLAUDE_CLI_AUTOCOMPACT).
+ *
+ * Claude Code compacts a session automatically when its context approaches
+ * the auto-compact window (`--autocompact <auto|tokens>`, claude 2.1.x). On
+ * 1M-context models the CLI's own default lets a long-lived session ratchet
+ * toward a million tokens, and this provider resumes ONE CLI session for a
+ * pi session's whole life — nothing else ever shrinks it. Measured across
+ * 26 real pidex sessions (2026-08-30): contexts ratcheted to 480k+, the
+ * average request carried 202k tokens, and cache reads alone were ~53% of
+ * total spend. Sessions that stayed near 100–150k did the same work at a
+ * fraction of the cost.
+ *
+ * So the provider caps the window at 200k tokens BY DEFAULT — the budget
+ * these models run under everywhere the 1M beta is not enabled — and lets
+ * the host raise, lower, or disable it:
+ *
+ *   PI_CLAUDE_CLI_AUTOCOMPACT=200k      cap at 200k (the default)
+ *   PI_CLAUDE_CLI_AUTOCOMPACT=400000    plain token counts work too
+ *   PI_CLAUDE_CLI_AUTOCOMPACT=400       bare numbers are thousands (CLI shorthand)
+ *   PI_CLAUDE_CLI_AUTOCOMPACT=auto      the CLI's own default behaviour
+ *   PI_CLAUDE_CLI_AUTOCOMPACT=off       omit the flag entirely (also: 0, none,
+ *                                       disable, disabled — for CLIs that
+ *                                       predate --autocompact)
+ *
+ * The value is a token COUNT, not a percentage of the model's window. The
+ * costs this guards against are absolute — cache read/write bill per token,
+ * and every request re-reads the whole context — so "half the window" means
+ * something completely different on a 200k model than on a 1M one, while
+ * 200k tokens costs the same everywhere.
+ *
+ * An invalid or out-of-range value falls back to the default with a warning
+ * rather than being passed through: the CLI rejects bad values by refusing
+ * to start, which would kill every turn of every session over a typo.
+ */
+
+/** Default auto-compact window, in tokens. */
+export const DEFAULT_AUTOCOMPACT_TOKENS = 200_000;
+
+/** The CLI accepts 100k–1M (claude 2.1.231: "It must be 'auto', or between 100k and 1M"). */
+const MIN_TOKENS = 100_000;
+const MAX_TOKENS = 1_000_000;
+
+const OFF_VALUES = new Set([
+  "off",
+  "0",
+  "none",
+  "disable",
+  "disabled",
+  "false",
+]);
+
+/**
+ * Parse a user-supplied window size into a token count.
+ * Mirrors the CLI's accepted forms: `500k`, `1M`, `200000`, and bare `200`
+ * meaning thousands. Returns undefined when unparseable.
+ */
+export function parseAutocompactTokens(raw: string): number | undefined {
+  const m = /^(\d+(?:\.\d+)?)\s*([km])?$/i.exec(raw.trim());
+  if (!m) return undefined;
+  const n = Number(m[1]);
+  if (!Number.isFinite(n) || n <= 0) return undefined;
+  const suffix = (m[2] ?? "").toLowerCase();
+  if (suffix === "k") return Math.round(n * 1_000);
+  if (suffix === "m") return Math.round(n * 1_000_000);
+  // Bare number: the CLI reads `200` as 200k shorthand; anything that already
+  // looks like a token count (>= 100k) is taken literally.
+  return n < MIN_TOKENS ? Math.round(n * 1_000) : Math.round(n);
+}
+
+/**
+ * Resolve the `--autocompact` argument from the environment.
+ *
+ * Returns the string to pass to the flag, or undefined to omit the flag
+ * entirely (explicit off). Unset resolves to the 200k default; `auto` is
+ * passed through so the CLI applies its own default; invalid values warn
+ * and fall back to the default.
+ */
+export function resolveAutocompact(
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const raw = (env.PI_CLAUDE_CLI_AUTOCOMPACT ?? "").trim();
+  if (raw === "") return String(DEFAULT_AUTOCOMPACT_TOKENS);
+
+  const lowered = raw.toLowerCase();
+  if (OFF_VALUES.has(lowered)) return undefined;
+  if (lowered === "auto") return "auto";
+
+  const tokens = parseAutocompactTokens(raw);
+  if (tokens === undefined || tokens < MIN_TOKENS || tokens > MAX_TOKENS) {
+    console.warn(
+      `[pi-claude-cli] PI_CLAUDE_CLI_AUTOCOMPACT=${JSON.stringify(raw)} is not ` +
+        `'auto', 'off', or a window between 100k and 1M — using the default ` +
+        `${DEFAULT_AUTOCOMPACT_TOKENS} tokens`,
+    );
+    return String(DEFAULT_AUTOCOMPACT_TOKENS);
+  }
+  return String(tokens);
+}

package/src/process-manager.ts

@@ -16,6 +16,7 @@ import {
   DEFAULT_SYSTEM_PROMPT_MODE,
   type SystemPromptMode,
 } from "./system-prompt-mode.js";
+import { resolveAutocompact } from "./autocompact.js";
 
 /**
  * Spawn a Claude CLI subprocess with all required flags for stream-json communication.
@@ -143,6 +144,16 @@ export function spawnClaude(
     args.push("--mcp-config", options.mcpConfigPath);
   }
 
+  // Auto-compact window (PI_CLAUDE_CLI_AUTOCOMPACT, default 200k — see
+  // src/autocompact.ts). The CLI does not keep flags across --resume, so
+  // like the system prompt this goes on every spawn. Resolved per spawn so
+  // a host can change the setting without restarting pi; the flag is
+  // config, not context, so changing it never invalidates the prompt cache.
+  const autocompact = resolveAutocompact();
+  if (autocompact !== undefined) {
+    args.push("--autocompact", autocompact);
+  }
+
   const proc = spawn("claude", args, {
     stdio: ["pipe", "pipe", "pipe"],
     cwd: options?.cwd ?? process.cwd(),