omp-proactive-compact

A native, user-level Oh My Pi (OMP) extension for hybrid semantic-candidate + context-eligibility proactive compaction with automatic continuation.

Features

• Candidate Generation on Task Transitions: Listens to structured todo tool executions; when tasks genuinely transition to completed, candidate checkpoints are evaluated.
• Context Eligibility & Growth Gates: Injects [Runtime Checkpoint] self-check reminders only when context usage is substantial (>= max(64K, 20% window)) and incremental growth (>= max(16K, 5% window)) is met.
• Agent Semantic Autonomy: Reminds the agent to self-assess whether earlier context is no longer load-bearing and multiple substantive steps remain before compacting.
• Secondary Validation Hard-Gate: Double-checks context eligibility when compact_context is invoked to prevent premature or low-value compaction.
• Safe Turn-Boundary Execution: Arms compaction in-turn and executes cleanly at agent_end without disrupting active tool runs.
• Automatic Continuation: Resumes the session automatically after compaction to continue unfinished work seamlessly.
• Benign No-op & Failure Recovery: Handles "Nothing to compact" as a clean continuation without stalling tasks.

Installation

Option 1: Manual User Extension (Recommended)

Copy proactive-compact.ts to your OMP user extensions directory:

mkdir -p ~/.omp/agent/extensions
cp proactive-compact.ts ~/.omp/agent/extensions/

OMP will automatically discover and load it on startup.

Option 2: NPM Plugin Installation

omp plugin install @shiquda/omp-proactive-compact

How It Works

1. Todo Task Completed: When an agent finishes a task via todo(op="done", ...):
   • If remaining actionable tasks exist AND context usage >= max(64K, 20%) AND growth >= max(16K, 5%), a [Runtime Checkpoint] note is attached to the Todo tool result.
2. Agent Self-Assessment: The agent reviews if earlier context is disposable and multiple future steps remain. If yes, it calls compact_context({ instructions: "..." }).
3. Double Verification: The tool checks that context usage actually warrants compaction.
4. Soft Compaction & Resume: The runtime compacts history at turn end and automatically prompts the agent to continue.

Configuration & Environment Variables

Variable	Default	Description
OMP_COMPACT_MIN_TOKENS	64000	Minimum token floor for proactive compaction
OMP_COMPACT_MIN_PERCENT	0.20	Minimum context window percentage threshold
OMP_COMPACT_MIN_DELTA	16000	Minimum token growth delta between consecutive reminders
OMP_COMPACT_MIN_DELTA_PERCENT	0.05	Minimum growth delta as a percentage of context window

Requirements

• Official Oh My Pi (OMP) CLI (omp >= 18.0.8)
• No source code modifications required.

License

MIT