@bismawy/pi-auto-compat

Auto-fix missing compat flags in Pi's models.json — mirrors pi-cache-optimizer detection so compat warnings never appear. Registry-driven, credential-safe, refreshes in-process.

Packages

Package details

extension

Install @bismawy/pi-auto-compat from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@bismawy/pi-auto-compat
Package
@bismawy/pi-auto-compat
Version
1.4.3
Published
Sep 11, 2026
Downloads
659/mo · 349/wk
Author
bismawy
License
MIT
Types
extension
Size
47.7 KB
Dependencies
0 dependencies · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./index.ts"
  ],
  "image": "https://raw.githubusercontent.com/bismawy/pi-auto-compat/main/assets/screenshot.webp"
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

🔧 @bismawy/pi-auto-compat

Automatic compat flags self-healer for pi coding agent.

Silently detects and patches missing model compatibility flags in models.json in-process. Ensures prompt caching, adaptive reasoning, session affinity, and custom proxies work flawlessly without manual JSON editing or missing-compat warnings.

pi extension npm license

pi-auto-compat

⚡ Quick Start

1. Installation

pi install npm:@bismawy/pi-auto-compat

(Or install directly from Git: pi install git:github.com/bismawy/pi-auto-compat)

2. Activate & Reload

Run /reload in your Pi session (or restart Pi).

3. Verification

Run /auto-compat at any time to inspect and verify all provider compat flags in your configuration.

🚀 Key Capabilities

  • 🛡️ Zero-Friction Auto-Healing: Patches missing compatibility flags dynamically during session_start, model_select, and via real-time file watching on models.json.
  • ⚡ In-Process Registry Refresh: Applies updates instantly via modelRegistry.refresh({ allowNetwork: false }) without requiring session restarts.
  • 🎯 Full Feature Alignment with pi-cache-optimizer: Automatically configures:
    • Universal long prompt caching (supportsLongCacheRetention: true).
    • Adaptive thinking for Claude 4.6+, Fable 5, and Kimi K3 models.
    • DeepSeek reasoning headers and thinking formats.
    • Proxy session affinity (sendSessionAffinityHeaders: true) and Anthropic cache control headers.
    • Default thinking level maps for unmapped reasoning models.
  • 🔒 Credential-Safe Guarantee: Only touches compat and modelOverrides structures. Never touches API keys, tokens, or base URLs. Creates automatic timestamped backups (max 3) before writing.

📖 Deep Dive & Technical Architecture

Category Conditions Applied Flags
Universal Cache Retention All models/providers where unset (except built-in llama.cpp) supportsLongCacheRetention: true
Adaptive Generation anthropic-messages + Opus/Sonnet ≥ 4.6, Fable ≥ 5, Kimi K3 forceAdaptiveThinking: true, allowEmptySignature: true (for K3)
DeepSeek-like Models openai-completions / openai-responses matching DeepSeek supportsLongCacheRetention: truerequiresReasoningContentOnAssistantMessages: truethinkingFormat: "deepseek"sendSessionAffinityHeaders: true
Claude on Proxies Claude models hosted on OpenAI-compatible proxies cacheControlFormat: "anthropic"
OpenAI-Compatible Proxies Custom openai-completions endpoints sendSessionAffinityHeaders: true (when undefined)
Unmapped Reasoning Reasoning-capable models without declared thinking maps { low, medium, high, xhigh } thinkingLevelMap
  • Hierarchical Fix Placement: Channel-level parameters (e.g. session affinity, retention) are assigned to the provider level; model-specific behavior flags are placed under models[].compat or modelOverrides.
  • Extension-Owned Provider Handling: When an extension registers custom providers with its own dynamic models list, Pi evaluates them after models.json. pi-auto-compat automatically directs fixes for these providers into modelOverrides to ensure precedence.
  • Credential Isolation: Never inspects, copies, or alters apiKey, OAuth tokens, or credential headers.
  • Additive-Only Patches: Fills only missing or corrupt keys without removing user customizations or explicit false flags.
  • Automated Backups: Rotates up to 3 timestamped backups (models.json.backup.*) prior to saving modifications.

📜 License & Acknowledgments