omp packages

pi-context-roll0.1.2

Automatic context rollover for Pi: compacts at a threshold and keeps the agent running

GitLab CI/CD Published 2 days ago MIT ~485 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Did it work for you?

Result

One report per person. A new report replaces your old one.

Reports 0

No reports yet.

Readme

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

Command Effect
/context-roll Status: threshold, usage, rollover count, on/off
/context-roll 70 or 70% Roll at 70% of the context window
/context-roll-static 200k Roll at a fixed token count (200000, 200K also work)
/context-roll clear Remove the threshold (rolling is off until you set one)
/context-roll on / off Toggle rolling (persisted)

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.