headroom-openclaw 0.1.0 → 0.36.0

package/README.md

@@ -4,16 +4,68 @@ Context compression plugin for [OpenClaw](https://github.com/openclaw/openclaw).
 
 ## Install
 
+Recommended one-command setup:
+
+```bash
+headroom wrap openclaw
+```
+
+Manual install:
+
 ```bash
 pip install "headroom-ai[proxy]"
-openclaw plugins install @headroom-ai/openclaw
+openclaw plugins install --dangerously-force-unsafe-install headroom-ai/openclaw
+```
+
+This plugin can auto-start a local `headroom proxy` when needed. OpenClaw treats process-launching plugins as unsafe by default, so `--dangerously-force-unsafe-install` is required even if you plan to use a remote proxy (the capability is declared at install time).
+
+## Local Development Install (Detection-Friendly)
+
+If you are testing from this repo, run npm install/build from the plugin directory so local launcher detection aligns with runtime paths. These linked installs are supported:
+
+```bash
+cd plugins/openclaw
+npm install
+npm run build
+openclaw plugins install --dangerously-force-unsafe-install --link .
+openclaw plugins install --dangerously-force-unsafe-install --link dist
+```
+
+From the repo root, install the plugin directory explicitly:
+
+```bash
+openclaw plugins install --dangerously-force-unsafe-install --link ./plugins/openclaw
+```
+
+Or, from inside `dist/`:
+
+```bash
+cd plugins/openclaw/dist
+openclaw plugins install --dangerously-force-unsafe-install --link .
 ```
 
+Why this matters:
+- The plugin checks launchers in this order: PATH -> local npm bin -> global npm -> python.
+- "local npm bin" means `plugins/openclaw/node_modules/.bin/headroom` relative to the source checkout.
+- Using `--link dist` (or `--link .` from `dist/`) still keeps runtime code adjacent to the checkout, and launcher detection falls back to PATH/global/python if a local npm bin is not present under the installed root.
+- `plugins/openclaw` also carries a no-op hook shim so OpenClaw's hook-pack fallback treats the path as valid instead of emitting a misleading `package.json missing openclaw.hooks` warning.
+- If you install from a `.tgz`, local npm bin may not exist in the installed extension and detection will fall back to PATH/global/python.
+
 ## Configure
 
+Install automatically selects the `contextEngine` slot for `headroom` on current OpenClaw releases. If you need to switch back manually, set `plugins.slots.contextEngine` to `"legacy"` or another engine id.
+
 ```json
 {
   "plugins": {
+    "entries": {
+      "headroom": {
+        "enabled": true,
+        "config": {
+          "proxyUrl": "http://127.0.0.1:8787"
+        }
+      }
+    },
     "slots": {
       "contextEngine": "headroom"
     }
@@ -21,7 +73,117 @@ openclaw plugins install @headroom-ai/openclaw
 }
 ```
 
-That's it. The plugin auto-starts the Headroom proxy if it's not already running.
+`proxyUrl` is optional. If omitted, the plugin auto-detects on localhost:
+- `http://127.0.0.1:<proxyPort>`
+- `http://localhost:<proxyPort>`
+
+Default `proxyPort` is `8787`. Auto-start is opt-in; in production, prefer an externally
+managed proxy such as systemd with `proxyUrl` set and `autoStart: false`.
+
+### Upstream gateway routing
+
+By default, the plugin also rewrites the built-in `openai-codex` provider base URL to a verified active Headroom proxy at runtime. That means Codex provider traffic flows through Headroom, so `/stats` can observe real upstream request and cache activity instead of only local context compression.
+
+This does not replace Headroom's existing Codex routing rules. The proxy already decides between `api.openai.com` and `chatgpt.com/backend-api/codex/responses` based on ChatGPT auth. The plugin change only points OpenClaw's provider config at the active proxy in memory and preserves the rest of the provider config.
+
+You can also route additional provider ids such as `anthropic`, `github-copilot`, `google`, or `openrouter` through the same proxy:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "headroom": {
+        "enabled": true,
+        "config": {
+          "gatewayProviderIds": ["openai-codex", "anthropic", "github-copilot", "google", "openrouter"]
+        }
+      }
+    }
+  }
+}
+```
+
+When `gatewayProviderIds` is set, it becomes the exact list the plugin rewrites in memory for the current gateway process.
+
+For convenience, the plugin also accepts family aliases:
+- `codex` -> `openai-codex`
+- `claude` -> `anthropic`
+- `copilot` -> `github-copilot`
+- `gemini` -> `google`
+
+When OpenClaw has already resolved a provider's upstream `baseUrl`, the plugin preserves protocol-specific path segments while swapping only the origin. That keeps provider families on the right proxy route:
+- Codex / ChatGPT backend: `/backend-api`
+- OpenAI-compatible providers: `/v1` or `/api/v1`
+- GitHub Copilot Claude-family models: `/anthropic`
+- Gemini: `/v1beta`
+
+GitHub Copilot is a special case because OpenClaw can route it through either OpenAI Responses or Anthropic Messages depending on the selected model. The plugin only rewrites Copilot when OpenClaw has already resolved the upstream `baseUrl`, so it can preserve the correct `/v1` or `/anthropic` path instead of guessing.
+
+The routing is intentionally lightweight and reversible:
+- the plugin does not persist provider `baseUrl` changes back to `openclaw.json`
+- disabling the plugin, clearing `gatewayProviderIds`, or restarting without Headroom restores OpenClaw's normal provider resolution
+- if you want durable provider rewrites, use `headroom wrap openclaw` instead of relying on plugin install side effects
+
+If you need to disable that behavior:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "headroom": {
+        "enabled": true,
+        "config": {
+          "routeCodexViaProxy": false
+        }
+      }
+    }
+  }
+}
+```
+
+### Local proxy (auto-start)
+
+When `proxyUrl` points to localhost (or is omitted), the plugin will auto-start `headroom proxy` if no running proxy is detected. Launch order:
+1. `headroom` from `PATH`
+2. local npm bin (`node_modules/.bin/headroom`)
+3. global npm bin
+4. Python module (`python -m headroom.cli proxy ...`)
+
+If `pythonPath` is set, it is tried first in the Python fallback step.
+
+Docker-native Headroom installs intentionally leave `pythonPath` unset so this launcher order prefers the installed host `headroom` wrapper on `PATH`, which then runs Headroom in Docker.
+
+### Remote proxy (connect-only)
+
+Point `proxyUrl` to any reachable Headroom instance:
+
+```json
+{
+  "config": {
+    "proxyUrl": "https://headroom.example.com:8787"
+  }
+}
+```
+
+Remote URLs are **connect-only** — the plugin probes the URL at startup and fails fast if the proxy is not reachable. No subprocess is spawned for remote addresses.
+
+## Manual Proxy Setup
+
+If you prefer to manage the proxy yourself (or are running a remote instance), start it before launching OpenClaw:
+
+Python install:
+
+```bash
+pip install "headroom-ai[proxy]"
+headroom proxy --host 127.0.0.1 --port 8787
+```
+
+NPM install:
+
+```bash
+npm install -g headroom-ai
+headroom proxy --host 127.0.0.1 --port 8787
+```
 
 ## How It Works
 
@@ -38,10 +200,16 @@ Compression is lossless via CCR (Compress-Cache-Retrieve): originals are stored
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `proxyUrl` | auto-detected | URL of the Headroom proxy |
-| `autoStart` | `true` | Start proxy automatically if not running |
-| `pythonPath` | auto-detected | Path to Python binary |
-| `proxyPort` | `8787` | Port for auto-started proxy |
+| `proxyUrl` | auto-detected | Optional URL of a Headroom proxy. Configured URLs are probe-gated before provider routing. Remote URLs (`https://headroom.example.com`) are connect-only. |
+| `proxyPort` | `8787` | Port used for default auto-detect and optional local auto-start when `proxyUrl` is not set. |
+| `pythonPath` | auto-detected | Optional Python executable override for Python fallback launcher. |
+| `autoStart` | `false` | Opt-in auto-start for a local `headroom proxy` if not already running (local URLs only; ignored for remote proxies). Keep `false` when systemd owns the proxy. |
+| `startupTimeoutMs` | `20000` | Time to wait for auto-started proxy to become healthy |
+| `requestTimeoutMs` | `30000` | Maximum milliseconds to wait for a single `compress()` call. If the proxy hangs or is slow, the call is cancelled after this deadline and the original uncompressed messages are used as a fallback. |
+| `circuitBreakerThreshold` | `3` | Number of consecutive `assemble()` errors before the circuit breaker opens and all requests bypass the proxy. Prevents cascading failures when the proxy is unhealthy. |
+| `circuitBreakerCooldownMs` | `60000` | How long (ms) the circuit breaker stays open after the threshold is reached. After the cool-down the breaker resets automatically and the next request re-probes the proxy via `/health`. |
+| `routeCodexViaProxy` | `true` | Rewrite OpenClaw's built-in `openai-codex` provider to use the active Headroom proxy in memory so upstream Codex requests pass through Headroom. |
+| `gatewayProviderIds` | `[]` | Optional explicit list of OpenClaw provider ids to route through the active Headroom proxy in memory. Friendly aliases `codex`, `claude`, `copilot`, and `gemini` are also accepted. When set, this overrides the default `openai-codex` routing list. |
 
 ## Comparison with lossless-claw
 

package/dist/README.md

@@ -0,0 +1,225 @@
+# @headroom-ai/openclaw
+
+Context compression plugin for [OpenClaw](https://github.com/openclaw/openclaw). Compresses tool outputs, code, logs, and structured data — 70-90% token savings with zero LLM calls.
+
+## Install
+
+Recommended one-command setup:
+
+```bash
+headroom wrap openclaw
+```
+
+Manual install:
+
+```bash
+pip install "headroom-ai[proxy]"
+openclaw plugins install --dangerously-force-unsafe-install headroom-ai/openclaw
+```
+
+This plugin can auto-start a local `headroom proxy` when needed. OpenClaw treats process-launching plugins as unsafe by default, so `--dangerously-force-unsafe-install` is required even if you plan to use a remote proxy (the capability is declared at install time).
+
+## Local Development Install (Detection-Friendly)
+
+If you are testing from this repo, run npm install/build from the plugin directory so local launcher detection aligns with runtime paths. These linked installs are supported:
+
+```bash
+cd plugins/openclaw
+npm install
+npm run build
+openclaw plugins install --dangerously-force-unsafe-install --link .
+openclaw plugins install --dangerously-force-unsafe-install --link dist
+```
+
+From the repo root, install the plugin directory explicitly:
+
+```bash
+openclaw plugins install --dangerously-force-unsafe-install --link ./plugins/openclaw
+```
+
+Or, from inside `dist/`:
+
+```bash
+cd plugins/openclaw/dist
+openclaw plugins install --dangerously-force-unsafe-install --link .
+```
+
+Why this matters:
+- The plugin checks launchers in this order: PATH -> local npm bin -> global npm -> python.
+- "local npm bin" means `plugins/openclaw/node_modules/.bin/headroom` relative to the source checkout.
+- Using `--link dist` (or `--link .` from `dist/`) still keeps runtime code adjacent to the checkout, and launcher detection falls back to PATH/global/python if a local npm bin is not present under the installed root.
+- `plugins/openclaw` also carries a no-op hook shim so OpenClaw's hook-pack fallback treats the path as valid instead of emitting a misleading `package.json missing openclaw.hooks` warning.
+- If you install from a `.tgz`, local npm bin may not exist in the installed extension and detection will fall back to PATH/global/python.
+
+## Configure
+
+Install automatically selects the `contextEngine` slot for `headroom` on current OpenClaw releases. If you need to switch back manually, set `plugins.slots.contextEngine` to `"legacy"` or another engine id.
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "headroom": {
+        "enabled": true,
+        "config": {
+          "proxyUrl": "http://127.0.0.1:8787"
+        }
+      }
+    },
+    "slots": {
+      "contextEngine": "headroom"
+    }
+  }
+}
+```
+
+`proxyUrl` is optional. If omitted, the plugin auto-detects on localhost:
+- `http://127.0.0.1:<proxyPort>`
+- `http://localhost:<proxyPort>`
+
+Default `proxyPort` is `8787`. Auto-start is opt-in; in production, prefer an externally
+managed proxy such as systemd with `proxyUrl` set and `autoStart: false`.
+
+### Upstream gateway routing
+
+By default, the plugin also rewrites the built-in `openai-codex` provider base URL to a verified active Headroom proxy at runtime. That means Codex provider traffic flows through Headroom, so `/stats` can observe real upstream request and cache activity instead of only local context compression.
+
+This does not replace Headroom's existing Codex routing rules. The proxy already decides between `api.openai.com` and `chatgpt.com/backend-api/codex/responses` based on ChatGPT auth. The plugin change only points OpenClaw's provider config at the active proxy in memory and preserves the rest of the provider config.
+
+You can also route additional provider ids such as `anthropic`, `github-copilot`, `google`, or `openrouter` through the same proxy:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "headroom": {
+        "enabled": true,
+        "config": {
+          "gatewayProviderIds": ["openai-codex", "anthropic", "github-copilot", "google", "openrouter"]
+        }
+      }
+    }
+  }
+}
+```
+
+When `gatewayProviderIds` is set, it becomes the exact list the plugin rewrites in memory for the current gateway process.
+
+For convenience, the plugin also accepts family aliases:
+- `codex` -> `openai-codex`
+- `claude` -> `anthropic`
+- `copilot` -> `github-copilot`
+- `gemini` -> `google`
+
+When OpenClaw has already resolved a provider's upstream `baseUrl`, the plugin preserves protocol-specific path segments while swapping only the origin. That keeps provider families on the right proxy route:
+- Codex / ChatGPT backend: `/backend-api`
+- OpenAI-compatible providers: `/v1` or `/api/v1`
+- GitHub Copilot Claude-family models: `/anthropic`
+- Gemini: `/v1beta`
+
+GitHub Copilot is a special case because OpenClaw can route it through either OpenAI Responses or Anthropic Messages depending on the selected model. The plugin only rewrites Copilot when OpenClaw has already resolved the upstream `baseUrl`, so it can preserve the correct `/v1` or `/anthropic` path instead of guessing.
+
+The routing is intentionally lightweight and reversible:
+- the plugin does not persist provider `baseUrl` changes back to `openclaw.json`
+- disabling the plugin, clearing `gatewayProviderIds`, or restarting without Headroom restores OpenClaw's normal provider resolution
+- if you want durable provider rewrites, use `headroom wrap openclaw` instead of relying on plugin install side effects
+
+If you need to disable that behavior:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "headroom": {
+        "enabled": true,
+        "config": {
+          "routeCodexViaProxy": false
+        }
+      }
+    }
+  }
+}
+```
+
+### Local proxy (auto-start)
+
+When `proxyUrl` points to localhost (or is omitted), the plugin will auto-start `headroom proxy` if no running proxy is detected. Launch order:
+1. `headroom` from `PATH`
+2. local npm bin (`node_modules/.bin/headroom`)
+3. global npm bin
+4. Python module (`python -m headroom.cli proxy ...`)
+
+If `pythonPath` is set, it is tried first in the Python fallback step.
+
+Docker-native Headroom installs intentionally leave `pythonPath` unset so this launcher order prefers the installed host `headroom` wrapper on `PATH`, which then runs Headroom in Docker.
+
+### Remote proxy (connect-only)
+
+Point `proxyUrl` to any reachable Headroom instance:
+
+```json
+{
+  "config": {
+    "proxyUrl": "https://headroom.example.com:8787"
+  }
+}
+```
+
+Remote URLs are **connect-only** — the plugin probes the URL at startup and fails fast if the proxy is not reachable. No subprocess is spawned for remote addresses.
+
+## Manual Proxy Setup
+
+If you prefer to manage the proxy yourself (or are running a remote instance), start it before launching OpenClaw:
+
+Python install:
+
+```bash
+pip install "headroom-ai[proxy]"
+headroom proxy --host 127.0.0.1 --port 8787
+```
+
+NPM install:
+
+```bash
+npm install -g headroom-ai
+headroom proxy --host 127.0.0.1 --port 8787
+```
+
+## How It Works
+
+Every time OpenClaw assembles context for the model, the plugin compresses tool outputs and large messages:
+
+- **JSON arrays** (tool outputs, search results) — statistical selection keeps anomalies, errors, boundaries
+- **Code** — AST-aware compression via tree-sitter
+- **Logs** — pattern deduplication, keeps errors and boundaries
+- **Text** — ML-based token compression
+
+Compression is lossless via CCR (Compress-Cache-Retrieve): originals are stored and the agent gets a `headroom_retrieve` tool to access full details when needed.
+
+## Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `proxyUrl` | auto-detected | Optional URL of a Headroom proxy. Configured URLs are probe-gated before provider routing. Remote URLs (`https://headroom.example.com`) are connect-only. |
+| `proxyPort` | `8787` | Port used for default auto-detect and optional local auto-start when `proxyUrl` is not set. |
+| `pythonPath` | auto-detected | Optional Python executable override for Python fallback launcher. |
+| `autoStart` | `false` | Opt-in auto-start for a local `headroom proxy` if not already running (local URLs only; ignored for remote proxies). Keep `false` when systemd owns the proxy. |
+| `startupTimeoutMs` | `20000` | Time to wait for auto-started proxy to become healthy |
+| `requestTimeoutMs` | `30000` | Maximum milliseconds to wait for a single `compress()` call. If the proxy hangs or is slow, the call is cancelled after this deadline and the original uncompressed messages are used as a fallback. |
+| `circuitBreakerThreshold` | `3` | Number of consecutive `assemble()` errors before the circuit breaker opens and all requests bypass the proxy. Prevents cascading failures when the proxy is unhealthy. |
+| `circuitBreakerCooldownMs` | `60000` | How long (ms) the circuit breaker stays open after the threshold is reached. After the cool-down the breaker resets automatically and the next request re-probes the proxy via `/health`. |
+| `routeCodexViaProxy` | `true` | Rewrite OpenClaw's built-in `openai-codex` provider to use the active Headroom proxy in memory so upstream Codex requests pass through Headroom. |
+| `gatewayProviderIds` | `[]` | Optional explicit list of OpenClaw provider ids to route through the active Headroom proxy in memory. Friendly aliases `codex`, `claude`, `copilot`, and `gemini` are also accepted. When set, this overrides the default `openai-codex` routing list. |
+
+## Comparison with lossless-claw
+
+| | lossless-claw | headroom |
+|---|---|---|
+| Compaction method | LLM summarization (DAG) | Content-aware compression (zero LLM) |
+| Cost of compaction | Tokens (LLM calls) | Zero |
+| Best for | Long conversations | Tool-heavy agents with large outputs |
+| Retrieval | `lcm_grep`, `lcm_expand` | `headroom_retrieve` (instant) |
+
+## License
+
+Apache-2.0

package/dist/hook-shim/HOOK.md

@@ -0,0 +1,21 @@
+---
+name: headroom-link-shim
+description: "No-op hook shim so local plugin source paths are also valid OpenClaw hook-pack paths."
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🪝",
+        "events": ["command"],
+      },
+  }
+---
+
+# Headroom Link Shim
+
+This hook intentionally does nothing.
+
+OpenClaw currently falls back to validating local plugin paths as hook packs when a
+plugin install cannot proceed, such as when the plugin is already installed.
+Including this no-op hook keeps `--link` installs from reporting a misleading
+`package.json missing openclaw.hooks` error for valid Headroom plugin paths.

package/dist/hook-shim/handler.js

@@ -0,0 +1,3 @@
+export default async function headroomLinkShim() {
+  return undefined;
+}

package/dist/index.d.ts

@@ -2,7 +2,7 @@
  * Headroom OpenClaw Plugin — register ContextEngine + CCR retrieval tool.
  *
  * Usage:
- *   openclaw plugins install @headroom-ai/openclaw
+ *   openclaw plugins install headroom-ai/openclaw
  *
  * Configuration (in ~/.openclaw/config.json or ~/.clawdbot/clawdbot.json):
  *   {
@@ -12,20 +12,25 @@
  *     }
  *   }
  */
-declare function headroomPlugin(api: any): void;
-
 /**
- * Manages the Headroom proxy process lifecycle.
- *
- * - Detects if a proxy is already running (e.g., user has `headroom proxy` for Claude Code)
- * - If not, spawns one as a child process with auto-assigned port
- * - Health checks, restart on crash, graceful shutdown
+ * OpenClaw 2026.x plugin API requires a `{ register(api) }` object export.
+ * The previous bare-function default export was silently skipped by the loader.
+ * See: https://github.com/chopratejas/headroom/issues/XXX
  */
+declare const _default: {
+    register: typeof registerHeadroomPlugin;
+};
+
+declare function registerHeadroomPlugin(api: any): void;
+
 interface ProxyManagerConfig {
     proxyUrl?: string;
+    proxyPort?: number;
     pythonPath?: string;
     autoStart?: boolean;
-    proxyPort?: number;
+    startupTimeoutMs?: number;
+    retryMaxAttempts?: number;
+    connectTimeoutSeconds?: number;
 }
 interface ProxyManagerLogger {
     info(message: string): void;
@@ -33,41 +38,44 @@ interface ProxyManagerLogger {
     error(message: string): void;
     debug(message: string): void;
 }
+/** Default logger that prefixes all messages with `[headroom]`. */
+declare const defaultLogger: ProxyManagerLogger;
+interface ProxyProbeResult {
+    reachable: boolean;
+    isHeadroom: boolean;
+    reason?: string;
+}
 declare class ProxyManager {
     private config;
     private logger;
-    private process;
     private proxyUrl;
-    private weStartedIt;
-    private restartCount;
-    private healthInterval;
-    private disposed;
     constructor(config?: ProxyManagerConfig, logger?: ProxyManagerLogger);
     /**
-     * Ensure a proxy is available. Returns the URL.
-     *
-     * 1. If proxyUrl is configured, use it
-     * 2. Check if proxy is already running on default port
-     * 3. If autoStart, spawn one
+     * Ensure a proxy is available. Returns the normalized URL origin.
      */
     start(): Promise<string>;
+    private getProxyPort;
+    private getDefaultProxyCandidates;
     /**
-     * Spawn the headroom proxy as a child process.
-     */
-    private spawnProxy;
-    /**
-     * Stop the proxy if we started it.
+     * Stop manager state. Spawned proxy processes are detached and externally managed.
      */
     stop(): Promise<void>;
     getUrl(): string | null;
-    private healthCheck;
-    private waitForHealthy;
-    private startHealthMonitor;
-    private handleCrash;
-    private findPython;
-    private checkHeadroomInstalled;
-    private findFreePort;
+    private startHeadroomProxy;
+    private buildLaunchSpecs;
+    private getConfiguredPythonCommand;
+    private getPyenvResolvedHeadroom;
+    private getPythonCommands;
+    private canExecute;
+    private getNpmGlobalPrefix;
 }
+declare function normalizeAndValidateProxyUrl(proxyUrl: string): string;
+/** Returns true if the URL points to a local address (localhost or 127.0.0.1). */
+declare function isLocalProxyUrl(proxyUrl: string): boolean;
+/**
+ * Probe a configured URL and verify whether it is a running Headroom proxy.
+ */
+declare function probeHeadroomProxy(proxyUrl: string): Promise<ProxyProbeResult>;
 
 /**
  * HeadroomContextEngine — ContextEngine implementation for OpenClaw.
@@ -78,6 +86,9 @@ declare class ProxyManager {
 
 interface HeadroomEngineConfig extends ProxyManagerConfig {
     enabled?: boolean;
+    requestTimeoutMs?: number;
+    circuitBreakerThreshold?: number;
+    circuitBreakerCooldownMs?: number;
 }
 declare class HeadroomContextEngine {
     readonly info: {
@@ -90,7 +101,11 @@ declare class HeadroomContextEngine {
     private proxyUrl;
     private config;
     private logger;
+    private proxyReadyListeners;
+    private proxyStartupPromise;
+    private proxyStartupError;
     private stats;
+    private circuit;
     constructor(config?: HeadroomEngineConfig, logger?: ProxyManagerLogger);
     bootstrap(params: {
         sessionId: string;
@@ -181,6 +196,14 @@ declare class HeadroomContextEngine {
         compactions: number;
     };
     getProxyUrl(): string | null;
+    getProxyStartupError(): unknown;
+    private isCircuitOpen;
+    private tripCircuit;
+    private resetCircuit;
+    ensureProxyStarted(): void;
+    onProxyReady(listener: (proxyUrl: string) => void | Promise<void>): () => void;
+    ensureProxyUrl(): Promise<string>;
+    private notifyProxyReady;
 }
 
 /**
@@ -202,6 +225,7 @@ interface OpenAIMessage {
     tool_calls?: any[];
     tool_call_id?: string;
     name?: string;
+    _headroomMeta?: Record<string, unknown>;
 }
 /**
  * Convert AgentMessage[] to OpenAI message format for compression.
@@ -211,6 +235,7 @@ declare function agentToOpenAI(messages: any[]): OpenAIMessage[];
  * Convert compressed OpenAI messages back to AgentMessage format.
  */
 declare function openAIToAgent(messages: OpenAIMessage[]): any[];
+declare function normalizeAgentMessages(messages: any[]): any[];
 
 /**
  * CCR (Compress-Cache-Retrieve) tool for OpenClaw.
@@ -231,17 +256,20 @@ declare function createHeadroomRetrieveTool(config: RetrieveToolConfig): {
                 type: string;
                 description: string;
             };
-            query: {
-                type: string;
-                description: string;
-            };
         };
         required: string[];
     };
     execute: (args: {
         hash: string;
-        query?: string;
     }) => Promise<string>;
 };
 
-export { HeadroomContextEngine, ProxyManager, agentToOpenAI, createHeadroomRetrieveTool, headroomPlugin as default, openAIToAgent };
+declare const DEFAULT_GATEWAY_PROVIDER_IDS: readonly ["openai-codex"];
+declare function resolveGatewayProviderIds(config: Record<string, unknown> | undefined): string[];
+declare function applyGatewayProviderBaseUrls<T>(cfg: T, proxyUrl: string, providerIds: readonly string[]): {
+    changed: boolean;
+    config: T;
+};
+declare function applyGatewayProviderBaseUrlsInPlace(cfg: any, proxyUrl: string, providerIds: readonly string[]): boolean;
+
+export { DEFAULT_GATEWAY_PROVIDER_IDS, HeadroomContextEngine, ProxyManager, agentToOpenAI, applyGatewayProviderBaseUrls, applyGatewayProviderBaseUrlsInPlace, createHeadroomRetrieveTool, _default as default, defaultLogger, isLocalProxyUrl, normalizeAgentMessages, normalizeAndValidateProxyUrl, openAIToAgent, probeHeadroomProxy, registerHeadroomPlugin, resolveGatewayProviderIds };