pi-context-roll

Automatic context rollover for Pi. When the context crosses a threshold in the middle of a task, the extension compacts it and resumes the agent. Nobody has to type "continue".

It replaces the combination of a threshold extension, a compaction extension and AGENTS.md instructions that coordinate them.

Install

pi install npm:pi-context-roll

How it works

1. At each turn_end that ran tools, it reads ctx.getContextUsage().
2. At or above the threshold, it calls plain ctx.compact(). Whatever compactor you configured (Pi core, pi-vcc, ...) does the work.
3. When compaction finishes, it sends a hidden message (display: false) that starts the next turn. The UI shows no extra "continue" turn.

Commands

Changes are saved to context-roll.json in the Pi agent directory and apply immediately.

{
  "enabled": true,
  "thresholdTokens": null,
  "thresholdPercent": 70,
  "resumeMessage": "Context was compacted. Resume the task exactly where you left off; do not restart or repeat completed work.",
  "maxConsecutive": 3
}

At most one of thresholdTokens / thresholdPercent is set. With neither, rolling is off.

Safety rules

• Rolling never starts while Pi has queued steering/follow-up messages (compaction aborts the running turn).
• The effective threshold is capped at contextWindow - 16384 - 1 so it stays below Pi's own auto-compaction point.
• A failed compaction is not retried until usage drops below the threshold or the config changes. The agent is still resumed (compaction already aborted it), except after Compaction cancelled.
• After maxConsecutive rollovers in a row that did not free enough context, rolling pauses until usage drops or you send a message.

Known limits

• Compaction aborts the running turn, so there is a short pause while the summary is generated. A truly pause-free rollover would need the extension to own summarization.
• Thresholds below roughly 40k tokens re-trigger immediately, because Pi keeps about 20k recent tokens after compaction.
• If the newest entry is one huge tool result, Pi's cut-point search can find nothing to summarize (Nothing to compact). The extension then notifies, latches failed and resumes without compacting; Pi's own overflow handling remains the backstop.
• Custom messages queued by other extensions are not detected as pending.
• A tool batch where every tool returns terminate: true still rolls and resumes.
• The config file is written without locking; concurrent Pi sessions can lose an update.

Verified behavior

Checked on Pi 0.83.0 with test/pi-runtime.integration.test.ts (a real AgentSession with Pi's faux provider):

• Aborting at turn_end keeps the turn's tool results.
• A real compaction runs through Pi (including the split-turn double summary).
• The hidden context-roll message starts the next turn and reaches the model as a user message.
• The run then finishes.

Not verified against a live provider or by hand:

• Whether a real provider accepts the hidden message right after a tool-result tail.
• Queued steering/follow-up messages (guarded by ctx.hasPendingMessages(), unit-tested only).
• Typing a prompt while compaction is running.
• pi-vcc as the compactor (plain ctx.compact() is used, so it should apply).

Development

npm run preflight runs lint, build, typecheck and tests.