pi-amber 🟠

Context compaction with structured summaries, validation, and self-repair — a pi extension that replaces the default context compression with an amber-grade checkpoint system.

When your conversation grows too long, pi compacts it into a summary. pi-amber makes that summary structured, verified, and language-aware — so the next model can continue the work without losing decisions, dead ends, or exact file references.

Features

• Structured XML checkpoints — dense handoff documents with task / constraints / state / artifacts / decisions / dead_ends / knowledge / open_loops / next_steps / breadcrumbs
• Anti-hallucination validation — summaries must keep required sections and at least one recent technical reference (paths/commands) verbatim; failures trigger an automatic self-repair pass
• Self-repair pipeline — auth errors → re-fetch OAuth credentials and retry (tokens rotate on short TTLs); overflow → shrink input and retry; transient errors → backoff retry; empty output (exhausted budget) → double maxTokens once; validation failure → feed the invalid output back for one repair
• Language-aware summaries — detects CJK-dominant conversations (Chinese / Japanese / Korean) and writes the summary in the user's language
• Pressure escalation ladder — consecutive ineffective compactions raise the trim aggressiveness (persisted across compactions), decaying after 5 idle minutes
• Deterministic file ledger — pi's extracted read/written/edited file operations are injected into the summarizer context, so artifacts never rely on the model's memory alone
• Iterative context — the previous summary is passed to the next compaction
• Uses pi's own machinery — convertToLlm, serializeConversation, estimateTokens, model registry auth — no re-implemented infrastructure
• Themed footer status — subtle idle badge, animated spinner with live message/token counts during compaction, and a persistent before → after checkpoint result; notifications stay plain and emoji-free

Install

pi install npm:@shinynito/pi-amber

Or run once without installing:

pi -e npm:@shinynito/pi-amber

Configuration

Optional config at ~/.pi/pi-amber.json:

{
  "model": "google/gemini-2.5-flash",
  "maxTokens": 8192,
  "enabled": true
}

Key	Default	Description
model	"" (current session model)	Provider/model used for summarization, e.g. "google/gemini-2.5-flash". Empty uses the active session model.
maxTokens	8192	Max output tokens for the summary request.
enabled	true	Set false to fall back to pi's default compaction entirely.

When compaction fails, pi-amber falls back to pi's default and appends a diagnostics line (model, message count, stopReason, token usage, validation excerpt) to ~/.pi/pi-amber-debug.jsonl — check that file first when reporting issues.

How it works

session grows past threshold
      │
      ▼
session_before_compact (pi event)
      │
      ├─ convertToLlm + serializeConversation (pi official)
      ├─ inject: system prompt · file ledger · previous summary
      ├─ detect summary language (CJK-aware)
      │
      ▼
summarizer (recovery pipeline)
   overflow → shrink input (keep tail) → retry
   transient → backoff retry
   invalid  → self-repair (feed error back)
      │
      ▼
validate
   ✓ required sections present
   ✓ artifacts format `- [kind] ref | status`
   ✓ recent technical refs preserved
   ✓ not too short (CJK-aware token estimate)
      │
      ▼
CompactionEntry with { summary, usage, details }
   details carry pressure state for the next round

Design notes

• Why structured XML? A fixed schema makes validation possible: we can prove the summary kept the required sections and didn't hallucinate away recent file references — then ask the model to fix it if it did.
• Why keep the tail? When the input must shrink, recent work is the most valuable context for continuing; the head is already covered by the previous summary.
• Why a pressure ladder instead of a hard cap? Compaction counts are a poor proxy for health. Tracking ineffective compactions and escalating trim aggressiveness keeps the session alive without ever hard-blocking the user.

Development

pnpm install
pnpm typecheck        # tsc --noEmit
pnpm test             # node --experimental-strip-types --test tests.test.ts

Files

index.ts           # extension entry: before_agent_start + session_before_compact + session_compact
ui.ts              # themed footer status: idle badge, animated compaction spinner, checkpoint result
policy.ts          # summarizer system prompt (XML schema + security + language rule)
summarizer.ts      # request pipeline: serialize → recover (shrink/retry/repair)
validate.ts        # XML parsing + structural/technical-ref validation
pressure.ts        # escalation ladder (persisted across compactions)
summaryLanguage.ts # CJK-dominant language detection
tokenLedger.ts     # plain-text CJK-aware token estimation (for validation)
config.ts          # ~/.pi/pi-amber.json loader

License

MIT