@jiayunxie/aerial 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy Xie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,264 @@
+# Aerial
+
+[![CI](https://github.com/Xiejiayun/aerial/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Xiejiayun/aerial/actions/workflows/ci.yml)
+[![Nightly](https://github.com/Xiejiayun/aerial/actions/workflows/nightly.yml/badge.svg)](https://github.com/Xiejiayun/aerial/actions/workflows/nightly.yml)
+[![npm version](https://img.shields.io/npm/v/@jiayunxie/aerial.svg)](https://www.npmjs.com/package/@jiayunxie/aerial)
+
+Aerial is a lightweight local-only proxy that lets one user connect their own GitHub Copilot subscription to local coding CLIs.
+
+The MVP runs on `127.0.0.1:18181`, requires a local Aerial API key for model routes, stores credentials on the user's machine, and avoids public deployment, account sharing, quota bypass, dashboards, analytics, and image APIs.
+
+## MVP Support
+
+Implemented routes:
+
+- `GET /health` without auth
+- `GET /v1/models` for model discovery, with an `aerial` support annotation per model
+- `POST /v1/responses` for Codex CLI
+- `POST /v1/messages` for Claude Code's Anthropic gateway path
+- `POST /v1/messages/count_tokens` with a local estimate
+- `POST /v1/chat/completions` as a simple passthrough fallback
+
+Implemented CLI commands:
+
+```bash
+aerial login
+aerial key generate
+aerial key print
+aerial start
+aerial setup codex
+aerial setup claude --model <available-copilot-model-id>
+aerial setup all
+aerial doctor
+aerial probe
+```
+
+Service installation, rollback automation, Gemini CLI support, dashboards, and analytics are intentionally out of this MVP. For Codex, local clients keep using HTTP POST /v1/responses. Aerial can optionally use Copilot's upstream `ws:/responses` transport for streaming Responses and translate events back to SSE — this transport is opt-in (`AERIAL_RESPONSES_WEBSOCKET=on`) and HTTP is the default.
+
+## Requirements
+
+- Node.js 22+
+- A GitHub account with an active Copilot subscription
+- Codex CLI and/or Claude Code installed locally
+
+## Install
+
+```bash
+npm install -g @jiayunxie/aerial
+```
+
+After install, the CLI is available as `aerial`.
+
+### Nightly builds (advanced, unstable)
+
+The nightly workflow publishes a `nightly` pre-release of Aerial when there are new commits on `main`. The default install command above is unaffected — nightlies are gated behind the `@nightly` dist-tag and will never be served as `latest`. To opt in:
+
+```bash
+npm install -g @jiayunxie/aerial@nightly
+```
+
+Nightly versions look like `0.1.1-nightly.YYYYMMDD.<sha7>`. They reflect the current `main` and may break; report regressions with `aerial --version` so the exact build can be reproduced. Switch back to stable any time with `npm install -g @jiayunxie/aerial`.
+
+### From source (local development)
+
+For working directly on the Aerial codebase:
+
+```bash
+git clone https://github.com/Xiejiayun/aerial.git
+cd aerial
+npm install -g .
+```
+
+Run without global install:
+
+```bash
+node src/cli.js --help
+```
+
+## First Run
+
+Configure your local clients. This also creates Aerial's local API key and wires it into supported clients:
+
+```bash
+aerial setup all --model <available-copilot-model-id>
+```
+
+On Windows, newly persisted user environment variables are visible to new terminals and newly launched apps. Restart your terminal or VS Code after the first setup if Codex was already open.
+
+Log in to GitHub with device flow:
+
+```bash
+aerial login
+```
+
+Start the local server:
+
+```bash
+aerial start
+```
+
+Check health:
+
+```bash
+curl http://127.0.0.1:18181/health
+```
+
+## Codex CLI Setup
+
+Aerial configures Codex through the Responses wire API provider path:
+
+```bash
+aerial setup codex --model <available-copilot-model-id>
+```
+
+This updates `~/.codex/config.toml` and creates a timestamped backup first. If you only want to inspect the exact change, set `HOME`/`USERPROFILE` to a temporary directory before running setup. The inserted provider uses:
+
+```toml
+[model_providers.aerial]
+base_url = "http://127.0.0.1:18181/v1"
+wire_api = "responses"
+env_key = "AERIAL_API_KEY"
+```
+
+Aerial creates the key automatically and persists `AERIAL_API_KEY` for new user sessions when the platform supports it.
+
+## Claude Code Setup
+
+Aerial configures Claude Code through its Anthropic-compatible gateway settings:
+
+```bash
+aerial setup claude
+```
+
+This updates `~/.claude/settings.json` and creates a timestamped backup first. If you only want to inspect the exact change, set `HOME`/`USERPROFILE` to a temporary directory before running setup. It sets:
+
+```json
+{
+  "model": "<available-copilot-model-id>",
+  "apiKeyHelper": "aerial key print",
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://127.0.0.1:18181",
+    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
+  }
+}
+```
+
+The `model` field is written when you pass `--model` or set Aerial's `defaultModel`; otherwise Aerial leaves any existing Claude Code model choice alone while still switching the gateway to the local Aerial endpoint.
+
+`aerial key print` prints the locally stored Aerial API key for Claude Code's helper flow. Users normally do not need to call it directly.
+
+When switching from another Anthropic-compatible gateway, setup removes stale `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`, and `ANTHROPIC_DEFAULT_*_MODEL` entries from Claude Code's managed `env` block so `apiKeyHelper` and the Aerial gateway are the active route.
+
+## Diagnostics
+
+```bash
+aerial doctor
+aerial probe
+```
+
+The doctor checks config, local API key presence, GitHub login state, Node version, and local bind address.
+
+## Security Boundary
+
+Aerial is for personal local use only.
+
+- It binds to `127.0.0.1` by default.
+- Model routes require `Authorization: Bearer <AERIAL_API_KEY>` or `x-api-key: <AERIAL_API_KEY>`.
+- GitHub tokens are stored under the user config directory with private file permissions where supported.
+- Aerial does not log raw GitHub tokens, Copilot JWTs, API keys, or request bodies by default.
+- Do not expose this service publicly or use it for account sharing.
+
+## Current Limitations
+
+- Copilot inference routes are an observed compatibility target, not a public stable GitHub REST API.
+- `/v1/messages/count_tokens` is a local estimate, not upstream tokenization.
+- Service install/uninstall and disable/rollback are not implemented yet.
+- Model choice is not automated; query `/v1/models` and select an available model explicitly.
+- Chat Completions requests normalize `max_tokens` to `max_completion_tokens` for newer OpenAI models that reject the older field.
+- Prompt caching is upstream-managed: Aerial does not store prompt bodies locally, and it preserves or injects cache protocol fields before forwarding.
+
+
+
+## Capability Probe
+
+Use `aerial probe` to inspect the live Copilot model matrix through the same local credentials Aerial uses for proxying:
+
+```bash
+aerial probe
+```
+
+This prints model IDs, Aerial routes, and unsupported notes such as `embeddings_not_implemented` or `no_supported_endpoint_advertised`. Models with upstream `ws:/responses` support are shown with the `responses_websocket` route.
+
+Run low-cost live route checks when you want to verify end-to-end behavior:
+
+```bash
+aerial probe --live
+# machine-readable output
+aerial probe --live --json
+```
+
+`--live` sends one small request through the first available `responses`, `messages`, and `chat` model. It does not test every model by default, which keeps the command lightweight.
+## Prompt Cache
+
+Aerial uses the upstream Copilot/OpenAI/Anthropic cache protocols instead of keeping a local prompt-content cache. That keeps the MVP lightweight and avoids storing prompts on disk.
+
+Supported behavior:
+
+- Responses and Chat Completions preserve `prompt_cache_retention` and `prompt_cache_key` when the client sends them.
+- Responses and Chat Completions automatically add `prompt_cache_retention: "in_memory"` and a stable hashed `prompt_cache_key` when the client omits them.
+- Anthropic Messages preserves client `cache_control` blocks. When none are present and caching is enabled, Aerial automatically adds `cache_control: { "type": "ephemeral" }` to stable `system` content, or to the final tool definition when there is no system content.
+- Usage fields from upstream are returned unchanged, including `cached_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`, and Copilot `cache_read` / `cache_write` token details when present.
+- Aerial logs cache metadata to stderr as `cache_request` and `cache_observe` events. These logs do not include prompt text or request bodies.
+
+OpenAI's prompt caching documentation says cache hits require an exact prompt prefix match and are only possible once the prompt is at least 1024 tokens. Confirm cache behavior from returned usage fields such as `usage.prompt_tokens_details.cached_tokens` or `usage.input_tokens_details.cached_tokens`; for shorter prompts this value is expected to be zero.
+
+Aerial enables ephemeral prompt caching by default for OpenAI-style routes and Anthropic Messages. Override it only when needed:
+
+```bash
+aerial config set promptCacheRetention in_memory
+# or
+aerial config set promptCacheRetention 24h
+# disable automatic cache hints
+aerial config set promptCacheRetention off
+aerial config set promptCacheKey off
+# pin all requests to an explicit cache partition
+aerial config set promptCacheKey my-project
+```
+
+You can also set it per process:
+
+```bash
+export AERIAL_PROMPT_CACHE_RETENTION=in_memory
+export AERIAL_PROMPT_CACHE_KEY=my-project
+```
+
+Per-request fields win over the configured default. Use `24h` only with models whose upstream route accepts extended retention; Anthropic Messages still uses Anthropic-style `cache_control: { "type": "ephemeral" }`. Set `promptCacheKey` to `auto` to use Aerial's hashed stable key, `off` to omit it, or a string to force a specific cache partition.
+## Model Support
+
+`GET /v1/models` returns Copilot's raw model metadata and adds an Aerial-specific field:
+
+```json
+{
+  "id": "gpt-5.4-mini",
+  "supported_endpoints": ["/responses", "ws:/responses"],
+  "aerial": {
+    "supported": true,
+    "routes": ["responses", "responses_websocket"],
+    "notes": []
+  }
+}
+```
+
+Route meanings:
+
+- `responses`: usable by Codex through HTTP `POST /v1/responses`.
+- `responses_websocket`: Aerial can use Copilot's upstream `ws:/responses` transport for streaming `/v1/responses` requests when `AERIAL_RESPONSES_WEBSOCKET=on` is set, then return SSE to the local client. When the opt-in is off (default), Aerial always uses HTTP upstream Responses even if a model advertises `ws:/responses`.
+- `messages`: usable by Claude Code through `POST /v1/messages`.
+- `chat`: usable by generic OpenAI Chat clients through `POST /v1/chat/completions`.
+
+Local clients should not open WebSocket connections to Aerial directly. Direct WebSocket upgrades still return `501 Not Implemented`; use HTTP `POST /v1/responses` and let Aerial choose the upstream transport. HTTP upstream Responses is the default; set `AERIAL_RESPONSES_WEBSOCKET=on` to opt into Copilot's upstream WebSocket transport for streaming Responses calls (still experimental, only effective for streaming requests on models that advertise `ws:/responses`).
+
+Known unsupported notes:
+
+- `embeddings_not_implemented`: Aerial does not expose `/v1/embeddings` yet.
+- `no_supported_endpoint_advertised`: the model did not declare a route Aerial can safely select.

package/docs/usage.md

@@ -0,0 +1,176 @@
+# Aerial MVP Usage
+
+This document describes the current MVP implementation.
+
+## 1. Install
+
+```bash
+npm install -g @jiayunxie/aerial
+```
+
+After install, the CLI is available as `aerial`.
+
+For local development against the repo source:
+
+```bash
+git clone https://github.com/Xiejiayun/aerial.git
+cd aerial
+npm install -g .
+# or run without global install:
+node src/cli.js --help
+```
+
+## 2. Configure Local Clients
+
+```bash
+aerial setup all --model <model-id>
+```
+
+Aerial creates a local API key, stores it privately, and configures supported clients to use it. On Windows, restart the terminal or VS Code after first setup so newly persisted user environment variables are visible to Codex.
+
+## 3. Login To GitHub
+
+```bash
+aerial login
+```
+
+Open the printed URL, enter the user code, and authorize the GitHub OAuth device flow. Aerial saves the GitHub access token locally and exchanges it for short-lived Copilot JWTs when proxy requests arrive.
+
+## 4. Start Server
+
+```bash
+aerial start
+```
+
+Default URL: `http://127.0.0.1:18181`.
+
+## 5. Configure Codex CLI
+
+```bash
+aerial setup codex --model <model-id>
+```
+
+The setup command backs up and merges `~/.codex/config.toml`, then persists the local key for new user sessions when the platform supports it.
+
+For a dry inspection without touching your real config, set `HOME`/`USERPROFILE` to a temporary directory before running this command.
+
+## 6. Configure Claude Code
+
+```bash
+aerial setup claude --model <model-id>
+```
+
+The setup command backs up and merges `~/.claude/settings.json`, using `apiKeyHelper = "aerial key print"` and `ANTHROPIC_BASE_URL=http://127.0.0.1:18181`. When you pass `--model` or set Aerial's `defaultModel`, it also writes Claude Code's default `model` to that Aerial-routed model.
+
+If Claude Code was previously pointed at another Anthropic-compatible gateway, setup removes stale `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`, and `ANTHROPIC_DEFAULT_*_MODEL` entries from the managed `env` block.
+
+For a dry inspection without touching your real config, set `HOME`/`USERPROFILE` to a temporary directory before running this command.
+
+## 7. Verify
+
+```bash
+aerial doctor
+aerial probe
+```
+
+Each model returned by `/v1/models` includes an `aerial` field that tells you whether the MVP can route it:
+
+```json
+"aerial": {
+  "supported": true,
+  "routes": ["responses", "responses_websocket", "chat"],
+  "notes": []
+}
+```
+
+Use `responses` models for Codex, `messages` models for Claude Code, and `chat` models only for generic Chat Completions clients. `responses_websocket` means Aerial can optionally use Copilot's upstream `ws:/responses` transport for streaming Responses calls when `AERIAL_RESPONSES_WEBSOCKET=on` is set; with the opt-in off (default), Aerial always uses HTTP upstream Responses. Models marked with `embeddings_not_implemented` or `no_supported_endpoint_advertised` need additional Aerial work before they are first-class choices.
+
+
+
+## 8. Probe Capabilities
+
+```bash
+aerial probe
+```
+
+This prints the current model matrix returned by Copilot plus Aerial's route annotations. It is the fastest way to see which models currently expose `responses`, `messages`, or `chat` routes.
+
+For a low-cost end-to-end check:
+
+```bash
+aerial probe --live
+```
+
+`--live` sends one small request through the first available model for each supported route. Use `--json` when you want machine-readable output for CI or debugging.
+
+For streaming `/v1/responses` requests, Aerial defaults to HTTP upstream Responses. Set `AERIAL_RESPONSES_WEBSOCKET=on` to opt into Copilot's upstream `ws:/responses` transport for streaming Responses calls; Aerial then converts upstream WebSocket events back to SSE for the local client. Direct client WebSocket upgrades to Aerial are still not exposed and return `501 Not Implemented`; clients should keep using HTTP `POST /v1/responses`.
+
+## 9. Use Prompt Cache
+
+Aerial does not implement a local prompt-content cache. It forwards cache protocol fields to Copilot and returns upstream usage fields unchanged. This is the intended design: prompts are not written to a local cache, and cache hits are controlled by the upstream service.
+
+For Codex/OpenAI Responses clients, users normally do not need to send cache fields directly. A manual request can still override Aerial's defaults:
+
+```bash
+curl -s http://127.0.0.1:18181/v1/responses \
+  -H "Authorization: Bearer $AERIAL_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gpt-5.4-mini",
+    "input": "<long stable prefix first, variable request last>",
+    "prompt_cache_retention": "in_memory",
+    "prompt_cache_key": "my-project"
+  }'
+```
+
+For Claude Code or Anthropic Messages clients, Aerial automatically adds Anthropic `cache_control` to stable `system` content when the client omits cache hints. You can still send `cache_control` manually to choose the exact breakpoint:
+
+```json
+{
+  "model": "claude-sonnet-4.6",
+  "max_tokens": 1024,
+  "system": [
+    {
+      "type": "text",
+      "text": "Long stable project context...",
+      "cache_control": { "type": "ephemeral" }
+    }
+  ],
+  "messages": [{ "role": "user", "content": "Summarize the current diff" }]
+}
+```
+
+Aerial automatically applies ephemeral prompt cache hints for OpenAI-style `/v1/responses`, `/v1/chat/completions`, and Anthropic-style `/v1/messages` requests that do not set them. Override this only when needed:
+
+```bash
+aerial config set promptCacheRetention in_memory
+# or: aerial config set promptCacheRetention 24h
+# disable automatic cache hints: aerial config set promptCacheRetention off && aerial config set promptCacheKey off
+# pin cache partition: aerial config set promptCacheKey my-project
+# per process: export AERIAL_PROMPT_CACHE_RETENTION=in_memory && export AERIAL_PROMPT_CACHE_KEY=my-project
+```
+
+Look for these usage fields to confirm cache behavior:
+
+- Responses/Chat: `usage.input_tokens_details.cached_tokens` or `usage.prompt_tokens_details.cached_tokens`.
+- Messages: `usage.cache_creation_input_tokens` and `usage.cache_read_input_tokens`.
+- Copilot details when present: `copilot_usage.token_details` entries with `cache_read` or `cache_write`.
+
+When `aerial start` is running in a terminal, Aerial also writes cache-only metadata logs to stderr:
+
+```json
+{"event":"cache_request","route":"/v1/messages","cacheControlBlocks":1}
+{"event":"cache_observe","route":"/v1/messages","usage":{"cacheRead":1920}}
+```
+
+These logs deliberately omit prompt text and request bodies. If `cached` stays zero, first check that the repeated prefix is identical and at least 1024 tokens. This matches OpenAI's prompt caching requirements; GitHub's public Copilot REST docs cover management and usage-metrics APIs, but do not document Copilot inference cache fields.
+
+Best practice: put stable system/project/tool context first, put changing user input last, and keep the prefix identical between requests. OpenAI-style prompt caching generally needs at least 1024 tokens before hits appear.
+## Troubleshooting
+
+- `503 Missing GitHub token`: run `aerial login`.
+- `401 Invalid or missing Aerial API key`: run `aerial setup all`, then restart the client terminal or VS Code.
+- Claude Code cannot read key: ensure `aerial` is on `PATH`; it uses `aerial key print` as its helper.
+- Upstream compatibility error: run `aerial doctor`, then retry with a model returned by `/v1/models`.
+- `Unsupported parameter: max_tokens`: Aerial normalizes Chat Completions `max_tokens` into `max_completion_tokens` before forwarding to newer OpenAI models.
+- Cache hit stays zero: ensure the stable prefix is long enough, unchanged, and placed before variable content. For Responses/Chat, try a stable `prompt_cache_key`; for Messages, keep stable content in `system` or put manual `cache_control` on the stable content block.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@jiayunxie/aerial",
+  "version": "0.1.0",
+  "description": "Local-only GitHub Copilot proxy for Codex CLI and Claude Code.",
+  "type": "module",
+  "private": false,
+  "homepage": "https://github.com/Xiejiayun/aerial#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Xiejiayun/aerial.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Xiejiayun/aerial/issues"
+  },
+  "keywords": [
+    "copilot",
+    "codex",
+    "claude-code",
+    "local-proxy"
+  ],
+  "files": [
+    "src",
+    "docs/usage.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "aerial": "src/cli.js"
+  },
+  "scripts": {
+    "start": "node src/cli.js start",
+    "doctor": "node src/cli.js doctor",
+    "test": "node --test",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "undici": "^7.25.0"
+  }
+}

package/src/auth.js

@@ -0,0 +1,92 @@
+import fs from "node:fs";
+import { COPILOT_TOKEN_URL, GITHUB_CLIENT_ID } from "./constants.js";
+import { githubTokenPath, writePrivateFile } from "./paths.js";
+import { logEvent } from "./log.js";
+
+let cachedCopilotToken;
+let refreshPromise;
+
+function formBody(values) {
+  return new URLSearchParams(values).toString();
+}
+
+export async function startDeviceFlow() {
+  logEvent("login_start");
+  const response = await fetch("https://github.com/login/device/code", {
+    method: "POST",
+    headers: { accept: "application/json", "content-type": "application/x-www-form-urlencoded" },
+    body: formBody({ client_id: GITHUB_CLIENT_ID, scope: "read:user copilot" })
+  });
+  if (!response.ok) throw new Error(`GitHub device flow failed: ${response.status} ${await response.text()}`);
+  return response.json();
+}
+
+export async function pollDeviceFlow(deviceCode, intervalSeconds) {
+  let interval = Math.max(Number(intervalSeconds || 5), 1);
+  while (true) {
+    await new Promise((resolve) => setTimeout(resolve, interval * 1000));
+    const response = await fetch("https://github.com/login/oauth/access_token", {
+      method: "POST",
+      headers: { accept: "application/json", "content-type": "application/x-www-form-urlencoded" },
+      body: formBody({ client_id: GITHUB_CLIENT_ID, device_code: deviceCode, grant_type: "urn:ietf:params:oauth:grant-type:device_code" })
+    });
+    if (!response.ok) throw new Error(`GitHub token poll failed: ${response.status} ${await response.text()}`);
+    const payload = await response.json();
+    if (payload.access_token) {
+      writePrivateFile(githubTokenPath(), `${payload.access_token}\n`);
+      logEvent("login_success");
+      return payload.access_token;
+    }
+    if (payload.error === "authorization_pending") continue;
+    if (payload.error === "slow_down") {
+      interval += 5;
+      continue;
+    }
+    if (payload.error === "expired_token") throw new Error("GitHub device code expired. Run `aerial login` again.");
+    throw new Error(`GitHub login failed: ${payload.error_description || payload.error}`);
+  }
+}
+
+export function readGitHubToken() {
+  if (process.env.AERIAL_GITHUB_TOKEN) return process.env.AERIAL_GITHUB_TOKEN;
+  if (!fs.existsSync(githubTokenPath())) return undefined;
+  return fs.readFileSync(githubTokenPath(), "utf8").trim();
+}
+
+function jwtExpirySeconds(token) {
+  try {
+    const [, payload] = token.split(".");
+    return JSON.parse(Buffer.from(payload, "base64url").toString("utf8")).exp;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function exchangeCopilotToken(githubToken = readGitHubToken()) {
+  if (!githubToken) throw new Error("Missing GitHub token. Run: aerial login");
+  const response = await fetch(COPILOT_TOKEN_URL, {
+    headers: {
+      authorization: `Bearer ${githubToken}`,
+      accept: "application/json",
+      "user-agent": "Aerial/0.1"
+    }
+  });
+  if (!response.ok) throw new Error(`Copilot token exchange failed: ${response.status} ${await response.text()}`);
+  const payload = await response.json();
+  const token = payload.token;
+  if (!token) throw new Error("Copilot token exchange response did not include token");
+  cachedCopilotToken = { token, expiresAt: (payload.expires_at ? Date.parse(payload.expires_at) / 1000 : jwtExpirySeconds(token)) || Math.floor(Date.now() / 1000) + 1200 };
+  logEvent("token_refresh_success", { expiresAt: cachedCopilotToken.expiresAt });
+  return cachedCopilotToken.token;
+}
+
+export async function getCopilotToken({ force = false } = {}) {
+  const now = Math.floor(Date.now() / 1000);
+  if (!force && cachedCopilotToken && cachedCopilotToken.expiresAt - now > 120) return cachedCopilotToken.token;
+  if (!refreshPromise) {
+    refreshPromise = exchangeCopilotToken().finally(() => {
+      refreshPromise = undefined;
+    });
+  }
+  return refreshPromise;
+}