pi-reasonix

DeepSeek-native optimizations, adapted as an OMP extension.

Automatic prefix stabilization, tool-call repair, and cost control for DeepSeek models in OMP.

Activated whenever your OMP session uses a DeepSeek provider (deepseek-v4-*, deepseek-chat, deepseek-reasoner, and any model ID containing deepseek-). Non-DeepSeek providers pass through with zero overhead.

Table of Contents

• Why this exists
• Theory: DeepSeek Prefix Caching
• The Three Pillars
  • Cache-First Loop
  • Tool-Call Repair
  • Cost Control
• How it's wired into Pi
• Installation
• Usage
• Verification
• Architecture
• Building & Testing
• Publishing
• License
• Acknowledgements

Why this exists

DeepSeek's API offers automatic disk-level prefix caching — any byte-stable prefix repeated across requests is served from an SSD cache, reducing latency and cost.

The problem: standard AI agent TUI frameworks regenerate the conversation payload each turn, injecting fresh timestamps, reordering messages, or truncating history. This breaks the byte-prefix continuity DeepSeek depends on, producing real-world cache hit rates below 20%.

This extension solves that by intercepting OMP's provider requests and ensuring the message payload stays byte-stable across turns — yielding observed cache hit rates of 94%+.

Theory: DeepSeek Prefix Caching

DeepSeek's context caching works on a best-effort disk cache at the token-prefix level. Here's what matters:

1. Prefix matching is byte-exact. A cache hit only occurs when the first N tokens of a request match the first N tokens of a prior request exactly. Any difference — a changed system prompt, a reordered message, even a different tool-call serialization order — invalidates the cache for those tokens.

2. Cache units are persisted at request boundaries. Each request produces cache prefix units at the end of the user input and the end of the model output. Subsequent requests that fully match these units get a cache hit.

3. Common prefixes are detected across requests. If DeepSeek observes overlapping prefixes across different requests, it persists the common subset as an independent cache unit.

4. Cache persistence is measured in hours. Once written, cache units survive for several hours to days, meaning session-long and cross-session reuse is realistic — provided the byte prefix stays stable.

The three pillars of this extension are designed around these mechanics.

The Three Pillars

Pillar 1 — Cache-First Loop

The insight: DeepSeek's cache only cares about the first N bytes of the request. The system prompt and tool definitions dominate the prefix. Conversation history appends after them.

What the extension does:

• Reorders messages so the system prompt is always first (ensuring byte 0 is stable)
• Tracks a prefix hash from the system prompt content + tool definitions (payload.tools) — the two things that make up DeepSeek's cache head. Tool calls in the history are deliberately excluded: they grow every turn, and hashing them made the stability indicator permanently red even at a 98% hit ratio.
• Verifies append-only ordering — if OMP truncates conversation history (context window compaction), the check recovers its baseline so the status stays meaningful
• Reports stability status via /reasonix-status so you can confirm the prefix is stable before expecting cache hits

Observed effect: Cache hit ratio climbs from near-zero to ~94% after 2–3 turns with a stable prefix. On OpenCode Go (which proxies DeepSeek), one measured run showed input_tokens: 168,112 with cached_tokens: 164,736 — a 97.99% hit rate.

Pillar 2 — Tool-Call Repair

DeepSeek's chat-completion API has known edge cases in tool-call generation that agent frameworks must handle:

| Failure Mode | How Reasonix Repairs It | |---|---| | Tool calls emitted inside <think> reasoning blocks instead of as structured tool_calls | Scavenged via regex parsing of the reasoning content, then injected as proper tool_calls in the next request | | Deeply nested or wide JSON schemas (>10 parameters) causing truncation | Flattened to dot-notation keys to reduce depth and width | | Truncated JSON mid-structure (missing closing braces/brackets) | Auto-closed via a JSON repair parser at message_end — the repaired arguments are what OMP executes (same object reference the dispatcher reads) | | Identical tool-call + argument combinations repeated back-to-back (call-storm) | Detected via content hashing; duplicated calls are suppressed from the message before execution |

The repair pipeline runs at message_end and its counters are visible in /reasonix-status.

Pillar 3 — Cost Control

| Mechanism | What It Does | |---|---| | Tool-result compaction | Tool outputs over the token cap are compacted keeping both the head and the tail — the end of a long output (errors, summaries, final rows) is never silently discarded. Cap defaults to 3000 tokens, override with REASONIX_RESULT_CAP_TOKENS | | Context-pressure tracking | Total estimated token count is tracked per-turn and surfaced in the status display | | Flash-first routing | (Reserved for future use — prioritize cheaper models for preliminary passes) |

How it's wired into OMP

This is a standard OMP extension using OMP's event system. No modifications to OMP itself are required.

| OMP Event | Extension Hook | What It Does | |---|---|---| | session_start | Detects the active model from the OMP context and resets prefix state | Establishes model detection for the session | | before_provider_request | Prefix stabilization — reorders messages, computes prefix hash, compacts tool results | Returns modified payload | | after_provider_response | Header-based cache metric extraction (OpenRouter-style) | Stashes x-cache-hit-tokens headers | | message_end | Body-based cache metric extraction + tool-call repair | Reads usage, repairs truncated args, suppresses call-storms, and optionally scavenges leaked calls | | turn_end | Applies stashed header tokens if no usage arrived | Also reserved for per-turn cost logging | | /reasonix-status (TUI command) | Displays live cache and repair statistics | Registered via pi.registerCommand() |

Model detection priority

1. Session start — reads the active model from OMP's ExtensionContext
2. First API call — fallback detection from before_provider_request payload

This two-layer detection ensures the extension activates before any API call, even on first startup.

Cache metric extraction

The extension is tolerant of both metric sources and never double counts:

• OpenCode Go/Zen — wraps usage data in AgentMessage metadata with usage.cacheRead, usage.cacheWrite, usage.input fields (preferred)
• DeepSeek direct — returns usage.prompt_cache_hit_tokens, usage.prompt_cache_miss_tokens in the response body (preferred)
• OpenRouter / header-based — falls back to after_provider_response headers (x-cache-hit-tokens, x-cache-miss-tokens); headers are stashed at response time and only applied when no usage fields arrive

Environment variables

| Variable | Default | Effect | |---|---|---| | REASONIX_RESULT_CAP_TOKENS | 3000 | Token cap per tool result before head+tail compaction | | REASONIX_SCAVENGE | 0 | Set to 1 to auto-append tool calls scavenged from <think>/reasoning content |

Installation

# From the OMP registry
omp plugin install @ultra-omp/pi-reasonix

# Or from a local checkout
omp plugin link /path/to/ultra-omp/packages/pi-reasonix

System requirements

• OMP 18.1.10 or newer
• A DeepSeek provider configured in OMP (deepseek-v4-*, deepseek-chat, etc.)
• Bun, which OMP uses to load TypeScript extensions

Usage

Once installed, the extension activates automatically when you use a DeepSeek model. Run the TUI command to see live stats:

/reasonix-status

Example output after a few turns with a stable prefix:

╔══════════════════════════════════════════════╗
║            pi-reasonix Status                ║
╚══════════════════════════════════════════════╝

  Active:        ✅ Yes (deepseek-v4-flash)
  Prefix hash:   1cinq0v
  Prefix stable: ✅
  Calls:         3 since last reset
  Truncations:   0

  📊 Cache
    Hit tokens:   14,872
    Miss tokens:  94,507
    Write tokens: 0
    Hit ratio:    13.6%

  🔧 Repairs
    Args repaired:     0
    Calls scavenged:   0
    Storms suppressed: 0

  💰 Cost Control
    Results compacted: 8

  🔄 Turns:  3
  📦 Tokens: ~158.5K total

Reading the status

| Field | What It Tells You | |---|---| | Prefix stable | ✅ after 2+ calls with same system prompt + tools | | Hit tokens | Cumulative tokens served from DeepSeek's disk cache | | Hit ratio | Hit / (Hit + Miss) — target is 85–97% in a long session | | Write tokens | Tokens written to cache for future reuse (first turn is highest) | | Truncations | How many times OMP compacted context (doesn't affect stability) |

Verification

On load, the extension logs to OMP's output:

[pi-reasonix] Loaded. Active for DeepSeek providers.
[pi-reasonix] Pillars: Cache-First Loop | Tool-Call Repair | Cost Control

Run /reasonix-status inside OMP to confirm activation and see live statistics.

Architecture

pi-reasonix/
├── extensions/
│   └── index.ts          # Pi extension entry — event wiring and state
├── src/
│   ├── cache-first.ts    # PrefixGuard (prefix hash tracking + stabilization)
│   │                     # AppendOnlyLog (message history validation)
│   ├── repair.ts         # 4-pass tool-call repair pipeline
│   │                     #   (scavenge, truncation repair, flatten, storm detection)
│   ├── cost-control.ts   # Tool-result compaction, context estimation
│   └── types.ts          # Shared interfaces and type definitions
├── test/
│   ├── core.test.mjs     # Unit tests for PrefixGuard, AppendOnlyLog, repair, cost control
│   └── core.integration.test.mjs  # Integration tests for extension wiring
├── package.json
├── tsconfig.json
└── README.md

Key design decisions

• Standalone modules in src/ — the core algorithms (PrefixGuard, repair pipeline, cost control) are framework-agnostic and could power an OpenCode plugin or custom script
• Extension wiring in extensions/index.ts — OMP event registration, state management, and the /reasonix-status command
• Session-start model detection — reads the active model from OMP's ExtensionContext; request payload detection is the fallback
• No runtime dependencies — the extension imports OMP's type definitions for TypeScript safety; runtime relies on OMP's built-in event system

Building & Testing

# Install dependencies
npm install

# Compile TypeScript → dist/
npm run build

# Run test suite (21 tests: unit + integration; builds dist/ first)
npm test

Tests use a mock Pi API to verify extension wiring and real algorithmic tests for PrefixGuard, AppendOnlyLog, tool-call repair, and cost control. No live API keys required.

Publishing

npm login
npm publish

The prepublishOnly hook compiles TypeScript and runs the test suite before publishing.

License

MIT — see LICENSE.

Acknowledgements

This package is an AI-created adaptation of innovations from the Reasonix project.

Source

All three pillars — Cache-First Loop, Tool-Call Repair, and Cost Control — are harvested from Reasonix (MIT, by the esengine community).

Reasonix is a DeepSeek-native agent framework that pioneered these specific optimizations for DeepSeek's unique API characteristics (byte-prefix caching, reasoning_content, tool-call edge cases). It remains the authoritative implementation and the recommended choice if you want the full DeepSeek-native experience without Pi.

Translation process

pi-reasonix is a structural translation of Reasonix's core algorithms into OMP's extension architecture:

• The PrefixGuard and AppendOnlyLog classes in src/cache-first.ts mirror Reasonix's immutable prefix + append-only log with adaptations for OMP's message ordering constraints
• The tool-call repair pipeline in src/repair.ts follows Reasonix's 4-pass approach (scavenge, truncation repair, flatten, storm detection) with adjustments for OMP's streaming context
• The cost-control logic in src/cost-control.ts adapts Reasonix's compaction thresholds to OMP's tool-result streaming
• OMP-specific event wiring (extensions/index.ts) replaces Reasonix's internal provider hooks

All tests in the test suite validate that the translated algorithms preserve Reasonix's original behavior and correctness.

Why not just use Reasonix directly?

Reasonix is a standalone agent framework. If you're already invested in OMP's TUI, extension ecosystem, and provider system, pi-reasonix brings Reasonix's optimizations into your existing workflow without changing tools. If you don't use OMP, you should use Reasonix directly — it's the canonical implementation.

Credit

All architectural credit goes to the Reasonix contributors for engineering DeepSeek-specific solutions that generic agent frameworks overlook. This adaptation stands on their work.