pi-midrun-compact

Safe mid-run compaction for long Pi tool loops. Trigger Pi's official compaction pipeline between complete tool batches, then continue the interrupted task after compaction succeeds.

Long coding tasks can stay inside one user turn for many model → tools → model cycles. Large tool results may push the next model request close to the context limit before Pi's normal end-of-run compaction check gets a chance to run. pi-midrun-compact closes that gap.

[!IMPORTANT] This extension coordinates when to compact and when to resume. It is not a compaction backend: it does not generate summaries, call provider compaction endpoints, or rewrite provider payloads.

Highlights

• Zero-config default — starts checking at 75% context usage.
• Safe tool boundaries — triggers only after every result in the current tool batch is present.
• Parallel-tool aware — matches tool calls and results by exact ID, independent of completion order.
• Pi-native delegation — calls ctx.compact() and leaves compaction ownership to Pi and installed backend extensions.
• Success-only continuation — resumes in the same session only after compaction completes successfully.
• Fail-safe behavior — malformed configuration, unknown usage, stale callbacks, and repeated failures never cause blind compaction loops.
• No runtime dependencies — uses only Pi's extension API and Node.js built-ins.

Install

Install from npm:

pi install npm:pi-midrun-compact

Try it for one run without installing:

pi -e npm:pi-midrun-compact

No configuration is required. Start Pi and inspect the active settings with:

/midrun-compact status

Update or remove the package later with:

pi update npm:pi-midrun-compact
pi remove npm:pi-midrun-compact

How it works

assistant requests one or more tools
                 │
                 ▼
all matching tool results are complete
                 │
                 ▼
context hook before the next model request
                 │
       ┌─────────┴─────────┐
       │                   │
 usage below threshold   usage at/above threshold
       │                   │
       ▼                   ▼
 continue normally      ctx.compact()
                           │
                 ┌─────────┴─────────┐
                 │                   │
              success             failure
                 │                   │
                 ▼                   ▼
        queue continuation      stop safely;
          in same session       do not resume

Automatic compaction is considered only when all of the following are true:

1. Pi has an active model and usable context-usage data.
2. The outgoing context ends with a complete assistant/tool-result batch.
3. Tool-call IDs and tool-result IDs are valid, unique, and match exactly.
4. Context usage is at or above thresholdPercent.
5. No compaction or continuation dispatch is already in progress.
6. The same approximate context state has not already produced a compaction failure.

This boundary prevents compaction while tools are still running or while a parallel batch is only partially complete.

Responsibilities

pi-midrun-compact owns	Pi or the compaction backend owns
Threshold timing	What history is kept or discarded
Complete-tool-batch validation	Summary generation
Starting ctx.compact()	Native provider compaction calls
Success/failure coordination	Compaction persistence and replay
Follow-up continuation	Backend-specific result details

The extension deliberately does not register session_before_compact or before_provider_request, so it does not compete for compaction ownership.

Compaction backend compatibility

Setup	Compaction behavior
Pi only	Pi uses its built-in model-summary compaction.
Pi + @lll9p/pi-better-compaction	The request still goes through Pi's standard pipeline, allowing that extension to use native /responses/compact where supported or its configured fallback.
Pi + another compaction extension	That extension can participate through Pi's normal compaction hooks; pi-midrun-compact treats the result as opaque.

A common pairing is:

pi install npm:pi-midrun-compact
pi install npm:@lll9p/pi-better-compaction

Loading order between these two packages does not determine compaction ownership.

Configuration

The defaults work without a config file. To customize them, create either or both of:

• Global: ~/.pi/agent/extensions/pi-midrun-compact/config.json
• Project: <project>/.pi/extensions/pi-midrun-compact/config.json

Project settings override global settings and are read only after the project is trusted. Run /reload or start a new Pi session after editing configuration.

Example:

{
  "thresholdPercent": 70,
  "notify": true
}

Options

Option	Type	Default	Behavior
enabled	boolean	true	Enables automatic threshold triggering. Explicit commands remain available when false.
thresholdPercent	number	75	Triggers at or above this percentage. Must be finite and strictly between 0 and 100.
autoResume	boolean	true	Queues a continuation after successful compaction. When false, compaction completes without starting another run.
notify	boolean	true	Shows informational notifications and footer status. Errors and command output remain visible when UI is available.
customCompactionInstructions	string	continuity-focused instructions	Passed to whichever backend owns the Pi compaction operation. An empty string passes no custom instruction.

Default compaction instructions:

Preserve the active user task, completed work, decisions, changed files, failures, pending tool-loop state, and exact next steps so execution can resume immediately after compaction.

Configuration is fail-safe:

• missing files use defaults;
• unknown keys are ignored with a warning;
• unreadable files, invalid JSON, or invalid known fields disable automatic triggering;
• a malformed project override cannot silently replace an invalid global safety configuration;
• explicit commands remain available for inspection and manual recovery.

Commands

Command	Description
/midrun-compact	Show status.
/midrun-compact status	Show runtime phase, effective settings, config paths, last trigger, and any failure guard.
/midrun-compact now [instructions]	Compact immediately, even below the configured threshold.
/midrun-compact retry [instructions]	Clear the recorded failure guard and retry after a compaction failure.

Additional command instructions are appended to customCompactionInstructions for that operation only:

/midrun-compact now Preserve the benchmark results and the unresolved regression in src/cache.ts.

Failure and recovery

Compaction errors fail closed:

• the interrupted run is not resumed;
• no automatic retry is scheduled;
• another automatic attempt at nearly the same session/context size is blocked instead of looping;
• the error remains visible even when notify is false.

Inspect the state, fix the active compaction backend or provider, and retry explicitly:

/midrun-compact status
/midrun-compact retry

Pending callbacks are tied to the session and runtime generation. Switching sessions, reloading, or shutting down invalidates stale continuation work.

Continuation behavior

With autoResume: true, successful compaction queues this protocol-marked user follow-up using deliverAs: "followUp":

[pi-midrun-compact/v1]
Continue the interrupted task from the compacted context. Do not restart completed work. Review the preserved task state and proceed with the next unfinished step. Do not discuss this control message unless it affects the task.

Operationally, this is:

abort the old internal run → compact through Pi → start a continuation run in the same session

It is not an in-place continuation of the same internal agent run. Pi currently classifies extension calls through ctx.compact() as compaction reason "manual", including automatic threshold triggers from this package.

Privacy and scope

pi-midrun-compact makes no direct network requests. It checks context usage and message structure, then delegates compaction to Pi. Any summary generation, provider request, native compact endpoint, or persisted compaction data is controlled by Pi and the selected backend.

The extension does not prune, truncate, summarize, or otherwise rewrite tool output.

Limitations

• One very large tool result can still jump past the usable limit before the next safe boundary. Tools should continue to truncate, paginate, or persist oversized output.
• The threshold is an early-warning policy, not a guarantee that every backend can compact a context of that size.
• A backend cannot necessarily recover once the context already exceeds its own input limit.
• Immediately after compaction, Pi may report context usage as unknown until a successful assistant response provides fresh usage. The extension intentionally skips that interval.
• If the active compaction backend is incompatible with a provider or proxy, this extension reports the failure rather than pretending recovery succeeded.

Development

The target Pi runtime loads TypeScript extensions directly. For local development:

npm ci
npm run check

Useful test commands:

npm run test:unit
npm run test:smoke

Try a checkout in isolation:

pi --no-extensions -e /path/to/pi-midrun-compact

The test suite covers serial and parallel tool batches, threshold and configuration safety, single-flight and stale-session behavior, failure recovery, Pi RPC loading, built-in compaction, and coexistence with pi-better-compaction in either load order.

License

MIT