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,