pi-safe-compact

Resilient, high-fidelity context compaction for pi. It combines overflow-safe one-pass summarization with an isolated agentic review, and is installable on any machine through pi install.

The problem it fixes

Pi's built-in compaction chooses a cut point using a token estimate. On content such as dense logs, JSON, and metrics, the real tokenizer can produce more tokens than the estimate, so the summary request can still exceed the model's context window. Auto-compaction may then repeatedly fail with an error such as:

This model's maximum context length is 524288 tokens. However, you requested 13107 output tokens and your prompt contains at least 511182 input tokens ...

A single model call can also miss details or preserve incorrect assumptions in a long, tool-heavy conversation. pi-safe-compact addresses both failure modes.

How it works

The extension hooks session_before_compact, plans a safer retained suffix, and runs two summarization stages:

1. Recent-context retention. Pi normally retains a token-sized suffix. The extension additionally asks to retain at least keepRecentMessages context messages and the complete latest user turn when the resulting suffix fits an adaptive safety budget. It never crosses an existing compaction boundary or starts inside a tool exchange: every retained tool result keeps the preceding assistant tool call that introduced it, including parallel tool-call groups.
2. Overflow-safe one-pass summary. generateOnePassSummary() calls completeSimple. If the provider reports a context-overflow error, it progressively removes the oldest messages from the material being summarized while preserving recent context. Split-turn history and the current turn prefix are summarized independently. This stage is also the fallback summary.
3. Agentic verification. generateAgenticSummary() launches a fresh createAgentSession sub-agent. The sub-agent receives the one-pass summary, all discarded history including preparation.turnPrefixMessages, a recent active-branch tail, and the latest user request in a dedicated file. It explores these inputs with read-only built-in tools, cross-checks facts, and writes the final structured summary through a dedicated write_summary tool.

Every successful extension summary begins with the most recent non-empty user request in an authoritative verbatim block. For split turns, an independent one-pass turn checkpoint is retained alongside the agentic result. This prevents a stale agentic summary from replacing a new task with an older completed task.

The sub-agent is isolated with noExtensions, noSkills, noPromptTemplates, noThemes, and noContextFiles. Its own compaction is disabled. Temporary material is deleted after the run, and cleanupAgenticSummary() removes temporary-path, size/count, and internal-correction artifacts before the result is persisted.

After session_compact, the extension can also repair interrupted autonomous progress. It queues one hidden follow-up continuation only when all of the following are true:

• compaction was automatic (reason is threshold, or a successful overflow compaction for which Pi reports willRetry: false)
• compaction happened inside an active agent run (ctx.isIdle() is false), rather than in the pre-prompt maintenance path
• Pi is not already retrying the overflow (willRetry is false)
• no steering or follow-up message is already pending

Manual /compact never queues a continuation. The hidden prompt tells the model to inspect the compacted summary and retained messages, continue with the next concrete action, avoid repeating completed work, and report completion instead of inventing work if the task is already done.

The extension also handles provider output-cap stops. Pi normalizes provider reasons such as Anthropic max_tokens and OpenAI finish_reason: "length" to an assistant message with stopReason: "length", visible to extensions through agent_end.messages. For an ordinary output-cap stop, pi-safe-compact queues one hidden follow-up instructing the model to continue exactly where it stopped. It does not queue when:

• the length stop is actually Pi's recognized context-overflow form (output === 0 and input fills at least 99% of the context window), because Pi owns compact-and-retry recovery
• another user or extension message is already pending
• the same terminal run already queued a length continuation

If the truncated response contained a tool call, Pi rejects that potentially truncated call instead of executing it; the continuation prompt explicitly tells the model to re-issue the complete tool call. A length continuation also suppresses a later compaction continuation from the same run, preventing duplicate recovery turns.

The output cap normally comes from the active model's maxTokens value in models.json or a built-in model definition. Pi's provider layer clamps it further when the remaining context window cannot fit that output budget.

The fallback chain is:

agentic summary -> one-pass summary -> Pi's built-in compaction

If one-pass generation fails, the extension declines to take over and Pi's built-in compaction runs unchanged. If only the agentic stage fails, the extension returns the one-pass result.

Preserved behavior

• Summaries use the structured sections Goal, Constraints & Preferences, Progress, Key Decisions, Next Steps, and Critical Context.
• The retained suffix contains at least 10 recent context messages by default when they fit the safety budget. The latest user turn takes precedence over the message-count anchor.
• The agentic stage reads both preparation.messagesToSummarize and preparation.turnPrefixMessages; Pi keeps the selected recent suffix separately.
• Split-turn prefixes are present in the one-pass checkpoint, the agentic input, and the deterministic continuity fallback.
• The latest user request is preserved verbatim up to maxVerbatimUserChars; exceptionally large requests retain their beginning and end with an explicit truncation marker when the full turn cannot safely remain as raw context.
• Read and modified file lists come from preparation.fileOps, which Pi computes over the complete relevant message set, so adaptive one-pass trimming does not make those lists incomplete.
• Exact file paths, function names, and error messages are preserved when relevant.
• Duplicate session_compact and output-length terminal events are coalesced until the queued continuation run starts.
• Existing queued work takes precedence; the extension does not add a second continuation.
• Output-length continuation uses agent_end, which is an official extension lifecycle hook; no Pi source patch or private Agent.continue() access is required.

Release notes

0.5.1

• Prevent retained context from starting at a tool result without its matching assistant tool call, which strict providers reject with No tool call found for function call output.
• Preserve complete parallel tool-call/result groups and fall back to Pi's original cut point when the required tool call is before the previous compaction boundary.

Resource limits

The agentic stage defaults to:

• 50 turns
• 3 minutes before a request to finish immediately
• 1 additional minute before forced cancellation

Optional global configuration can be placed at ~/.pi/agent/extensions/pi-safe-compact.json:

{
  "maxTurns": 50,
  "maxRuntimeMs": 180000,
  "graceTimeMs": 60000,
  "keepRecentMessages": 10,
  "maxRetainedTokens": 256000,
  "maxVerbatimUserChars": 32000
}

maxRetainedTokens is optional. When omitted, the retention budget is 25% of the usable model context after two summary reserves, capped at 256,000 tokens and never below Pi's keepRecentTokens. A single message or user turn larger than that budget cannot safely remain as raw context; in that case the core cut point is kept, while the newest user request and split-turn checkpoint are injected deterministically into the summary.

Install

Global, for all projects:

pi install npm:pi-safe-compact

Project-local development checkout:

pi install ./pi-safe-compact -l

Restart Pi after installation. No Pi source patching is required.

Requirements

The extension uses Pi's bundled core packages as peer dependencies:

• @earendil-works/pi-ai
• @earendil-works/pi-agent-core
• @earendil-works/pi-coding-agent
• typebox

It has no additional runtime dependencies and loads its TypeScript entry point directly through Pi.

Verify it is active

Run pi list or inspect ~/.pi/agent/settings.json and confirm that npm:pi-safe-compact appears in packages. Successful takeover is intentionally unobtrusive: compaction simply completes and the session continues.

License

MIT