@madgagarin/pi-agentrouter

Pi Coding Agent extension for AgentRouter. Adds support for Claude Opus 5.5, GPT-6.1 Sol, GPT-6 Astra, and DeepSeek V4 Flash with in-flight WAF recovery, prompt caching optimization, and live quota monitoring.

---

Why this extension exists

If you configure AgentRouter as a generic OpenAI or Anthropic endpoint in Pi, you will run into several recurring issues:

1. Gateway content filters lock up sessions: AgentRouter's upstream gateway blocks requests containing binary output (such as reading a .so or compiled file) or certain keywords with 400 content-blocked or 500 sensitive words detected. Because Pi sends previous conversation turns with each request, that error stays in context and every subsequent retry fails. This extension catches the error, redacts the problematic output from in-memory history, and retries cleanly.
2. Prompt caching errors & extra costs: Standard Anthropic caching headers (cache_control) trigger 400 Bad Request on non-Anthropic endpoints, and changing prompt prefixes invalidates DeepSeek caches. This extension enforces prefix stability so DeepSeek and Claude hit ~95% cache rates, cutting token costs by ~90% without throwing 400s.
3. Reasoning mode mismatches: DeepSeek and Claude Opus use different schemas for thinking traces. Sending raw thinking payloads through the proxy causes 400 or 422 validation errors. This extension normalizes thinking parameters per-model automatically.
4. Sudden 402 quota errors: Claude Opus 5.5 and GPT-6 quotas are released in daily batches (10:00 & 19:00 Beijing time). When a batch runs out, the API returns 402. Run /agentrouter check to see which models are ready before starting a long task, or switch to unlimited DeepSeek V4 Flash.
5. Subagent rate limits (429): Running concurrent subagents easily trips AgentRouter's per-minute limits. This extension includes file-based request pacing that only throttles AgentRouter calls, leaving direct providers (Gemini, local Ollama) unaffected.

---

Free credits & referral bonus

AgentRouter is completely free to use and does not accept paid top-ups. Compute is distributed via signup bonuses and daily logins:

• $50 signup credit: If you register through this referral link, you get $50 in free credit instead of starting at $0. (It also gives me test credits to maintain this plugin).
• $25 daily login bonus: You get an extra $25 credit automatically every day upon logging in. If you stay logged in from yesterday, just log out and back in once to collect it.
• Quota refresh times: Batch quotas for Claude Opus 5.5 and GPT-6.1 Sol refill daily at 10:00 and 19:00 Beijing time (05:00 and 14:00 MSK / 02:00 and 11:00 UTC). DeepSeek V4 Flash has unlimited availability.

👉 Register on AgentRouter (with $50 bonus)
(Referral code 34dc is attached automatically, whether registering directly or via GitHub OAuth).

---

Quick Start

1. Get an API key (Free $50 on Registration)

Create an account at agentrouter.org/register?aff=34dc to claim your instant $50 welcome credits, and copy your sk-... key from the dashboard.

2. Install the extension

pi install npm:@madgagarin/pi-agentrouter

3. Set your key in Pi chat

/agentrouter key sk-your-agentrouter-key

Or export it in your shell profile:

export AGENTROUTER_API_KEY="sk-your-agentrouter-key"

---

Models & Pricing

Rates are pulled dynamically from the gateway API ($2.00 / 1M tokens base unit):

Model	Provider	Context	Output	Reasoning	Input / 1M	Output / 1M	Cache Read / 1M	Quota Policy
deepseek-v4-flash	agentrouter-openai	1M	64K	Yes	$4.00	$12.00	$2.00	Unlimited
gpt-6.1-sol	agentrouter-openai	1.05M	128K	Yes	$4.00	$20.00	-	Daily batch drops
gpt-6-astra	agentrouter-openai	1M	128K	Yes	$8.00	$40.00	-	Daily batch drops
claude-opus-5-5	agentrouter-clode	1M	128K	Yes (Adaptive)	$12.00	$12.00	-	Daily batch drops

Claude and GPT quotas are released in batches throughout the day. When a batch is consumed (HTTP 402), check availability with /agentrouter check or switch to unlimited deepseek-v4-flash.

---

In-Chat Commands

Command	Description
/agentrouter	Show active model, monthly spend, extension ordering, and pacing delay.
/agentrouter check	Probe live batch quota status across all models (🟢 Ready vs ⏳ 402 Exhausted) and show monthly spend.
/agentrouter pricing	Display current pricing table from the gateway.
/agentrouter sync	Add active flagship models to enabledModels in settings.json.
/agentrouter key <key>	Save API key to configuration.
/agentrouter pacing <ms>	Set delay between requests (default: 3500 ms).
/agentrouter fix-order	Ensure extension loads before pi-cache-optimizer in settings.json.
/compact	Compact session history with stripped reasoning traces and file dumps.

---

Keybindings

Shortcut	Action
Ctrl + P	Cycle to next model (deepseek-v4-flash ➔ gpt-6-astra ➔ gpt-6.1-sol ➔ claude-opus-5-5)
Shift + Ctrl + P	Cycle to previous model
Shift + Tab	Change reasoning depth (off ➔ minimal ➔ low ➔ medium ➔ high)
Ctrl + T	Toggle reasoning visibility
Ctrl + L	Fuzzy-search model picker

---

Recommended settings.json

Add this to ~/.pi/agent/settings.json for quick model switching:

{
  "defaultProvider": "agentrouter-openai",
  "defaultModel": "deepseek-v4-flash",
  "defaultThinkingLevel": "low",
  "enabledModels": [
    "agentrouter-openai/deepseek-v4-flash",
    "agentrouter-openai/gpt-6-astra",
    "agentrouter-openai/gpt-6.1-sol",
    "agentrouter-clode/claude-opus-5-5"
  ]
}

---

FAQ

How does error recovery work?

The extension intercepts requests at the transport level. If the gateway returns a temporary error (such as a 429 rate limit, 405 WAF challenge, 500/503 service issue, thinking validation mismatch, or WAF content-blocked error), it strips sticky routing headers to failing nodes, proactively strips binary dumps, performs non-destructive in-flight poison redaction on tool results while preserving all tool arguments and assistant turns, waits with exponential backoff, and retries up to 10 times. Diagnostic events are logged to ~/.pi/agent/.agentrouter-debug.log.

Why does prompt caching matter?

DeepSeek charges ~$0.014 per 1M cached input tokens versus ~$0.14 for uncached ones. Because this extension prevents dynamic prompt rewrites and ensures prefix determinism, multi-turn coding sessions routinely achieve 95%+ cache hit rates, saving substantial costs over long runs.

How do batch quotas and /agentrouter check work?

AgentRouter releases daily quotas for premium models (Claude Opus 5.5, GPT-6.1 Sol, GPT-6 Astra) in periodic batch drops. When a batch is fully consumed, the API returns HTTP 402. Running /agentrouter check sends lightweight live health probes to all models in parallel, immediately displaying which models are Ready (🟢 200 OK) or Exhausted (⏳ 402), along with your current monthly spend in USD. If a premium batch is empty, switch to deepseek-v4-flash which has unlimited capacity.

How do free credits and daily check-ins work?

AgentRouter is completely free and does not accept paid top-ups. Compute is distributed via welcome bonuses and daily rewards:

• Registration Bonus: You receive $50.00 in free balance upon registration when using the community referral link (versus $0 on plain direct signup).
• Daily Login Check-In: The platform uses automatic login check-in (登录签到). You receive $25.00 every day upon logging in (no manual button required). If you remain logged in from the previous day, simply log out and back in to trigger the daily check-in ("签到成功，新增额度已到账").
• Quota Drops: Quotas for flagship models (Claude Opus 5.5, GPT-6.1 Sol) refresh daily in batches at 10:00 and 19:00 Beijing time (05:00 and 14:00 MSK / 02:00 and 11:00 UTC). Between batch drops, deepseek-v4-flash remains available around the clock.

Does pacing slow down other providers?

No. Request pacing is isolated per provider via dedicated lock files and applied exclusively to requests routed to agentrouter.org. Direct provider connections (Google Gemini, Anthropic, local Ollama) run without pacing delays.

Using custom subagents (pi-subagents)

AgentRouter validates requests against the pi-code signature. If you define custom subagents in ~/.pi/agent/agents/*.md, set systemPromptMode: append in their frontmatter.

---

License

MIT © madgagarin