pi-stealth 🥷

Universal zero-fingerprint privacy client and transparent stream-layer retry engine for pi.

pi-stealth turns Pi into a silent, resilient client. It scrubs all tracking, attribution, and SDK fingerprinting metadata before requests leave your machine, and absorbs API rate limits (HTTP 429) across providers using an extensible Provider Resolver Architecture.

---

Key Superpowers

1. Zero-Fingerprint Header Stripping

   • Hooks into Pi's before_provider_headers event.
   • Drops all OpenRouter attribution (X-OpenRouter-Title, HTTP-Referer, X-OpenRouter-Categories).
   • Drops all OpenAI Stainless SDK fingerprinting metadata (X-Stainless-Lang, X-Stainless-OS, X-Stainless-Arch, X-Stainless-Runtime, X-Stainless-Package-Version, X-Stainless-Retry-Count, X-Stainless-Timeout).
   • Drops provider session affinity tags (x-session-id, X-BILLING-INVOKE-ORIGIN, cf-aig-metadata).
   • Outgoing requests retain only Authorization: Bearer <key> and Content-Type: application/json.

2. Transparent Rate-Limit Resiliency (HTTP 429)

   • Intercepts rate limits at the stream layer with jittered exponential backoff (2s → 4s → 8s → 16s → 32s → 60s cap).
   • Up to 20 attempts by default (~5–6 minutes wall-clock), keeping your agent working through aggressive API cooldowns.
   • Prevents partial-stream replays (only retries if an error occurs before token generation starts).
   • Session messages are kept clean; exhaustion errors are rewritten with user-friendly notices without corrupting conversation history.

3. Extensible Provider Resolver Architecture

   • Automatically adapts to the user's active model (openrouter, nvidia, anthropic, cloudflare, stealth/ox-alpha, custom proxies).
   • Third-party extensions and scripts can register custom resolvers via the global registry.

---

Provider Resolvers

pi-stealth ships with built-in resolvers out of the box:

Resolver	Target / Match Pattern	Stripped Attribution Headers	Rate-Limit Detection
openrouter	openrouter, stealth/*, ox-alpha/*, 0x-alpha/*	X-OpenRouter-Title, HTTP-Referer, X-OpenRouter-Categories, x-session-id	429, rate limit, credits, free-tier limit, overloaded
nvidia	nvidia, nvidia/*, *.nvidia.com	X-BILLING-INVOKE-ORIGIN, x-session-affinity	429, rate limit, please wait
cloudflare	cloudflare*, gateway.ai.cloudflare.com	User-Agent: pi-coding-agent, cf-aig-metadata	429, exceeded quota
anthropic	anthropic, api.anthropic.com	anthropic-client-version, x-session-id	429, rate_limit_error, overloaded_error
universal	Any model / OpenAI-compatible endpoint	All X-Stainless-*, OpenAI-Organization, OpenAI-Project, User-Agent, Accept	Standard HTTP 429, too many requests, server is busy

---

Writing Custom Resolvers

You can easily register a custom resolver from any Pi extension or configuration script:

import { registry, type StealthResolver } from "pi-stealth";

const MyCustomGatewayResolver: StealthResolver = {
  id: "my-gateway",
  name: "Corporate AI Gateway",
  matches(model) {
    return model.baseUrl?.includes("gateway.internal.corp") ?? false;
  },
  stripHeaders(headers, model) {
    headers["x-corp-tracking-id"] = null;
    headers["x-user-telemetry"] = null;
  },
  isRateLimit(error) {
    return error?.status === 429 || error?.message?.includes("gateway_concurrency_limit");
  },
  getRetryDelayMs(attempt, error) {
    // Custom backoff curve: 3s, 6s, 12s...
    return 3000 * (2 ** (attempt - 1));
  }
};

// Register directly
registry.register(MyCustomGatewayResolver);

---

Configuration (Environment Variables)

Customize behavior dynamically without editing configuration files:

Variable	Alias	Default	Description
PI_STEALTH_RETRY_MAX	STEALTH_RETRY_MAX	20	Max attempts per burst before giving up
PI_STEALTH_RETRY_BASE_MS	STEALTH_RETRY_BASE_MS	2000	Base backoff in milliseconds
PI_STEALTH_RETRY_CAP_MS	STEALTH_RETRY_CAP_MS	60000	Delay ceiling per retry in milliseconds
PI_STEALTH_RETRY_JITTER	STEALTH_RETRY_JITTER	0.2	Random jitter fraction (0.0–1.0)
PI_STEALTH_STRIP_HEADERS	STEALTH_STRIP_HEADERS	true	Enables/disables header sanitization

---

Installation

Option 1 — Install via Pi CLI

pi install git:github.com/kelvinpraises/pi-stealth@v1

Option 2 — Drop Directly Into Pi Extensions

cp extensions/pi-stealth.ts ~/.pi/agent/extensions/

Then run /reload in your active Pi session.

---

Verification

When Pi boots or /reload is run:

[pi-stealth] loaded — stealth privacy & retries active [max: 20, base: 2000ms, cap: 60000ms, jitter: 20%]. Resolvers: [openrouter, nvidia, cloudflare, anthropic, universal].

When an active rate limit is intercepted:

[pi-stealth] stealth/ox-alpha — rate limited on attempt 1/20; 19 attempt(s) remaining.

---

Acknowledgements

• Inspired by pi-nvidia-rate-limit-retry by Diegovisk,