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 and runs two summarization stages:

1. 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. This stage is also the fallback summary.
2. Agentic verification. generateAgenticSummary() launches a fresh createAgentSession sub-agent. The sub-agent receives the one-pass summary and a JSONL representation of preparation.messagesToSummarize, explores both with read-only built-in tools, cross-checks facts, and writes the final structured summary through a dedicated write_summary tool.

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 agentic stage summarizes only preparation.messagesToSummarize; Pi keeps the recent conversation after the compaction cut point separately.
• Split-turn prefixes are summarized and merged with history 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.

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
}

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