@phantomcodes/cli 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,81 @@
+Phantom Proprietary License
+
+Copyright (c) 2026 Harbor Financial LLC. All rights reserved.
+
+This license covers the Phantom source code, the Phantom website, and the
+Phantom CLI command-line tool ("the CLI"), together "the Software". It
+applies to every copy of the Software that carries this file.
+
+1. Ownership
+
+   Harbor Financial LLC owns all right, title and interest in the Software,
+   including all copyrights and other intellectual property rights. Nothing
+   in this license transfers ownership to you.
+
+2. No grant
+
+   This license grants no rights in the Phantom source code, including the
+   code behind the website. You may not use, copy, modify or distribute any
+   part of it unless Harbor Financial LLC gives you written permission. The only
+   permission this license grants is the one in section 3, and it covers the
+   CLI alone. Visiting phantom.codes and using the Phantom service are
+   governed by the terms of service at phantom.codes/terms, not by this
+   license.
+
+3. Limited permission for the Phantom CLI
+
+   If you got the CLI from Harbor Financial LLC's official release (the
+   @phantomcodes/cli package on npm), you may install and run unmodified
+   copies of it, only to access the Phantom service. This permission is
+   revocable, non-exclusive, non-transferable and non-sublicensable.
+
+4. Restrictions
+
+   Except as section 3 allows, you may not:
+
+   a. copy, modify, translate or create derivative works of the Software;
+   b. distribute, sublicense, rent, lease, lend or sell the Software;
+   c. reverse engineer, decompile or disassemble the Software, except to the
+      extent applicable law allows it despite this limit;
+   d. remove or change any copyright, license or other notice in the
+      Software;
+   e. use the Software, or any knowledge of how it works, to build or train
+      a competing product or service, including a model router; or
+   f. publish benchmarks or performance tests of the Software.
+
+5. Confidentiality
+
+   The non-public parts of the Software, including its source code, routing
+   logic and design, are Harbor Financial LLC's trade secrets. If you see them, you
+   must keep them confidential and use them only as Harbor Financial LLC allows in
+   writing.
+
+6. Termination
+
+   This license, and any permission under section 3, ends automatically if
+   you break any of its terms. Harbor Financial LLC may also end the section 3
+   permission at any time. When it ends, you must stop using the Software and
+   destroy all copies you have.
+
+7. No warranty
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+   PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+8. Limitation of liability
+
+   TO THE FULLEST EXTENT THE LAW ALLOWS, HARBOR FINANCIAL LLC IS NOT LIABLE FOR ANY
+   INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR PUNITIVE DAMAGES, OR FOR
+   ANY LOSS OF DATA, PROFITS OR REVENUE, ARISING FROM THE SOFTWARE OR THIS
+   LICENSE. ITS TOTAL LIABILITY UNDER THIS LICENSE IS LIMITED TO THE AMOUNT
+   YOU PAID FOR THE SOFTWARE, IF ANY.
+
+9. Governing law
+
+   The laws of the Commonwealth of Massachusetts govern this license, without regard to its conflict
+   of laws rules.
+
+10. Contact
+
+   To ask for permission beyond this license, email support@phantom.codes.

package/README.md

@@ -1,3 +1,232 @@
-# Temporary Holding Version
+# Your agents have expensive taste.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect your agents to Phantom AI. Route models, control spending and pay from your terminal.
+
+**Phantom CLI** (`phantom`) by [Phantom AI](https://phantom.codes) · [Docs](https://phantom.codes/docs) · [npm](https://www.npmjs.com/package/@phantomcodes/cli)
+
+Use Phantom AI's router to send requests to cheaper models when your rules allow
+it, or choose a model yourself. Connect the coding agents you already use, fund
+their inference and control spending—all from your terminal.
+
+## Install the agent skill
+
+The `phantom-ai` skill ships in the package. `phantom setup` installs it for
+each agent it finds:
+
+```bash
+npm i -g @phantomcodes/cli
+phantom setup --agent claude
+```
+
+The skill covers workspace setup, funding, spending controls and model routing.
+[Skill docs](docs/guides/agent-skill.md)
+
+## Let your agent set it up
+
+Copy this into Claude Code, Codex, Cursor or another agent with terminal access:
+
+```text
+Help me set up phantom for AI inference through Phantom AI.
+
+Check that I have Node 24 or newer, then install @phantomcodes/cli if needed.
+Run phantom setup --agent <my agent> to install the phantom-ai skill, and read it.
+Check for an existing workspace and saved keys before changing anything.
+If I need to connect, start phantom login and let me complete the device approval.
+Check the workspace balance. Ask which coding agent I use and what budget I want,
+then create a named workspace key with that cap.
+Ask whether I want to connect my existing agent for future runs or use a temporary
+connection for one run. For saved setup, preview the changes with phantom setup --dry-run
+and show them to me before applying the setup I approve. Make sure any spending cap
+is on the key my agent will actually use. Ask before adding funds or starting paid
+inference. Keep keys and recovery credentials out of chat. Finish with the command
+to launch my agent, and explain how to undo any saved setup.
+```
+
+## Connect your existing agents
+
+Keep using your coding agent, with Phantom AI handling its inference and model
+routing. Connect it using your saved key:
+
+```bash
+npm i -g @phantomcodes/cli
+phantom login
+phantom setup
+```
+
+Used pai, this CLI's old name? Run `phantom setup` once after you install. Until
+then, Claude Code and the shell block pai set up still call `pai`, and phantom
+prints a reminder.
+
+The Phantom CLI detects supported agents, previews the configuration changes, then asks before
+applying them. It connects their model calls to Phantom AI and wires up the saved
+key. Restart your agent, or open a new terminal, to use the connection.
+
+Codex, Claude Code, opencode, Continue, Goose, Aider, GitHub Copilot CLI and Cline
+support saved setup. Cursor gets instructions for its settings screen; pi gets
+the agent skill. [Agent-specific setup](docs/guides/agent-setup.md).
+
+Preview without changing files with `phantom setup --dry-run`. The Phantom CLI keeps backups;
+undo the changes with `phantom setup --restore`.
+
+## Connect for one run
+
+```bash
+npm i -g @phantomcodes/cli
+phantom login
+phantom workspace fund --amount 10 --card
+phantom workspace status
+phantom codex
+```
+
+Both setup options require **Node 24+** and your coding agent installed. Connect, fund your
+workspace, then launch **Codex** (`phantom codex`), **Claude Code** (`phantom claude`),
+**pi** (`phantom pi`), or **any other compatible agent**.
+[Set up other agents](docs/guides/agent-setup.md).
+
+Login opens a device approval page and saves a key privately. Funding opens
+checkout; check your workspace balance after payment. Agent runs use temporary
+configuration and print spending afterward. Your existing agent configuration
+stays in place.
+
+Already have a Phantom key? Use `phantom login --paste` to save it locally.
+
+## Fund your workspace
+
+Add credit first, then let your agents spend from the shared balance:
+
+```bash
+phantom fund --amount 10 --card
+phantom fund --amount 10 --coin usdc
+```
+
+Credit is available after the payment is verified. Check balance anytime with `phantom balance`.
+
+[Funding and payment details](docs/guides/buying-credit.md).
+
+## Give each agent a budget
+
+Create a key with its own cap, sharing your workspace balance:
+
+```bash
+phantom keys create --save coding --limit 5
+phantom claude --key coding
+phantom keys list
+phantom keys set --id <key-id> --limit 10
+```
+
+Workspace key controls include total limits, periodic budgets and spending
+rates. Use the full key ID from `phantom keys list` when changing or revoking a key.
+Revoking a workspace key preserves workspace funds.
+
+## Choose what answers
+
+Let the router choose a model for `auto` requests. Your policy can prefer cheaper
+models and change the choice for tool use, reasoning or spending limits:
+
+```bash
+PHANTOM_KEY_NAME=coding phantom route set --models <model-a>,<model-b>
+PHANTOM_KEY_NAME=coding phantom route test --table
+```
+
+Prefer a specific model? Select it in your agent. Policies that apply only to
+`auto` leave explicit model choices alone.
+[Routing](docs/guides/routing.md) covers conditions, fallback and conversation affinity.
+
+`phantom-1` picks a tier for each request: economy, standard or frontier. Your key's
+lineup picks the model in each tier, and a fallback model to try when it fails:
+
+```bash
+phantom lineup --table
+phantom lineup set --frontier <model> --economy-fallback <model>
+phantom lineup reset
+```
+
+`lineup` shows the choices for each tier. `default` in place of a model puts that tier
+back to its default.
+
+See what a key spent, and what `phantom-1` saved against always running its frontier
+model:
+
+```bash
+phantom spend --table
+phantom spend --from 2026-09-01 --to 2026-09-30
+phantom spend --workspace --table
+```
+
+The dates are UTC days and the default is this month. `--workspace` lists every key in
+your workspace by name; without it you see the key you run as. The saving is an
+estimate: the same tokens at the frontier model's price today.
+
+A Pro ($20 a month) or Max ($100 a month) plan pays for `phantom-1` calls up to an amount
+of model cost in any 7 days, then your credit pays:
+
+```bash
+phantom plan --table
+phantom plan pro
+phantom plan manage
+```
+
+`plan` shows the key's plan and how much of the last 7 days it has paid for. `plan pro`
+and `plan max` print a Stripe Checkout link that puts the plan on this key and open it.
+`plan manage` opens Stripe's billing page, where the card changes, the plan switches and
+it cancels. A named model, not `phantom-1`, still spends credit.
+
+## Commands
+
+| Task | Commands |
+| --- | --- |
+| Connect | `phantom login`, `phantom logout` |
+| Connect existing agents | `phantom setup`, `phantom setup --dry-run`, `phantom setup --restore` |
+| Run inference | `phantom claude`, `phantom codex`, `phantom pi` |
+| Fund and check spending | `phantom workspace fund`, `phantom workspace status`, `phantom balance`, `phantom spend` |
+| Manage workspace keys | `phantom keys create`, `phantom keys set`, `phantom keys rotate`, `phantom keys revoke` |
+| Manage local copies | `phantom keys saved`, `phantom keys save`, `phantom keys rm` |
+| Route models | `phantom route` |
+| Pick phantom-1's models | `phantom lineup`, `phantom lineup set`, `phantom lineup reset` |
+
+Put phantom flags before agent arguments; use `--` to separate them:
+
+```bash
+phantom codex --key coding -- exec "explain this repository"
+```
+
+Commands print JSON; `--table` renders supported results for people. Agent
+commands inherit the terminal and print a spending summary on stderr.
+Exit codes: 0 success, 1 error, 2 rejected key; agent runs return the agent's exit code.
+
+<details>
+<summary><strong>Advanced tools, integrations and legacy commands</strong></summary>
+
+`phantom --help` shows the main workflows. `phantom --help --all` and the
+[interface reference](docs/reference.md) cover every command.
+
+- [Signed receipts](docs/guides/receipts.md): check which model answered with `phantom verify`.
+- [Funding credit](docs/guides/buying-credit.md): `phantom fund` and checking payments.
+- [Saved secrets](docs/guides/saved-secrets.md): macOS Keychain or private files; guest recovery uses `phantom workspace export` and `phantom workspace import`.
+- [Key selection](docs/guides/which-key.md) and [API address](docs/guides/base-url.md): environment overrides and shell integration.
+
+The older `phantom key` commands still work.
+`phantom keys list` reads the workspace; `phantom keys saved` lists local copies.
+`phantom keys show` prints a secret for shell integration; keep it out of chat and logs.
+
+</details>
+
+<details>
+<summary><strong>Development and contributing</strong></summary>
+
+```bash
+npm ci
+npm run typecheck
+npm run build
+npm run coverage
+npm run docs
+node scripts/gen-docs.mjs --check
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
+
+</details>
+
+---
+
+phantom is proprietary, under the [Phantom Proprietary License](LICENSE). It lets you install and run phantom to use Phantom AI, the hosted API it calls.

package/bin/phantom.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * The installed entry point.
+ *
+ * Two reasons this is plain JS rather than the .mts itself. Node refuses to
+ * strip types from anything under node_modules at all, so a published
+ * TypeScript source cannot run in a dependency; and npm links the bin as an
+ * extensionless `phantom`, which Node would not recognise as TypeScript
+ * even if it would. So `npm run build` compiles the source to dist/ and this
+ * file, which never needs compiling, is what npm points at.
+ */
+import { main } from '../dist/phantom.mjs';
+
+await main();

package/dist/agents/command.mjs

@@ -0,0 +1,157 @@
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { die } from "../core/errors.mjs";
+import { DEFAULT_BASE_URL, httpsOnly, request } from "../core/request.mjs";
+import { keyId, readNamedKey, resolveApiKey } from "../keys/saved.mjs";
+import { workspaceLogin } from "../workspace/command.mjs";
+const DEFAULT_MODEL = 'auto';
+/** The key's spend and balance, or null when the answer has no numbers, such as a sign-in page that came back with status 200. */
+async function keyStatus(apiKey, baseUrl) {
+    const s = await request('GET', '/key/balance', apiKey, undefined, baseUrl);
+    return Number.isFinite(s.credit_spent_usd) && Number.isFinite(s.credit_balance_usd) ? s : null;
+}
+import { proxyToken, startProxy } from "./proxy.mjs";
+const hasModel = (args) => args.some((a) => a === '-m' || a === '--model' || a.startsWith('--model=') || /^model=/.test(a));
+/** The agents phantom can run, by command name. */
+export const AGENTS = {
+    claude: {
+        bin: 'claude',
+        prefix: '/claude-code',
+        launch(proxy, args, env, _tmp, token) {
+            // --settings outranks settings.json, so an env block or apiKeyHelper
+            // `phantom setup` wrote can't send Claude Code past the proxy. The helper
+            // reads the token from the environment, so it stays off the command line.
+            const vars = { ANTHROPIC_BASE_URL: proxy, CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: '1', ENABLE_TOOL_SEARCH: 'true' };
+            const { ANTHROPIC_AUTH_TOKEN: _auth, ...rest } = env;
+            return {
+                args: ['--settings', JSON.stringify({ apiKeyHelper: 'printenv PHANTOM_AGENT_TOKEN', env: vars }), ...args],
+                env: { ...rest, ANTHROPIC_BASE_URL: proxy, ANTHROPIC_API_KEY: token, PHANTOM_AGENT_TOKEN: token },
+            };
+        },
+    },
+    codex: {
+        bin: 'codex',
+        prefix: '/codex',
+        launch(proxy, args, env, _tmp, token) {
+            const base = `${proxy}/v1`;
+            const provider = [
+                ['name', 'Phantom AI (phantom)'],
+                ['base_url', base],
+                ['wire_api', 'responses'],
+                ['env_key', 'PHANTOM_AGENT_TOKEN'],
+                ['model_catalog_url', `${base}/models`],
+            ];
+            // phantom_run, not phantom: phantom setup saves [model_providers.phantom],
+            // and -c merges into a table, so keys added there by hand would ride along.
+            const config = [
+                'model_provider="phantom_run"',
+                ...provider.map(([k, v]) => `model_providers.phantom_run.${k}=${JSON.stringify(v)}`),
+                'features.api_key_model_discovery=true',
+                ...(hasModel(args) ? [] : [`model=${JSON.stringify(DEFAULT_MODEL)}`]),
+            ];
+            return { args: [...config.flatMap((c) => ['-c', c]), ...args], env: { ...env, OPENAI_BASE_URL: base, PHANTOM_AGENT_TOKEN: token } };
+        },
+    },
+    pi: {
+        bin: 'pi',
+        prefix: '/coding-agent',
+        launch(proxy, args, env, tmp, token) {
+            // pi reads providers from models.json or an extension; an extension
+            // for this run leaves the user's own files alone. Its key is read from
+            // PHANTOM_AGENT_TOKEN when pi calls, so the file holds no secret.
+            const file = path.join(tmp, 'phantom-provider.ts');
+            const model = { id: DEFAULT_MODEL, name: 'Phantom AI router (phantom)', reasoning: true, input: ['text', 'image'], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 1_000_000, maxTokens: 64_000 };
+            writeFileSync(file, `export default function (pi) {\n  pi.registerProvider('phantom', ${JSON.stringify({ baseUrl: `${proxy}/v1`, api: 'openai-completions', apiKey: '$PHANTOM_AGENT_TOKEN', models: [model] })});\n}\n`, { mode: 0o600 });
+            return { args: ['-e', file, ...(hasModel(args) ? [] : ['--provider', 'phantom', '--model', DEFAULT_MODEL]), ...args], env: { ...env, PHANTOM_AGENT_TOKEN: token } };
+        },
+    },
+};
+/** Waits for the agent and returns its exit code; a signal counts as 128 plus its number. */
+function waitFor(bin, args, env) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, args, { stdio: 'inherit', env: env });
+        // Ctrl-C reaches the agent itself; phantom stays to stop the proxy and print the spend.
+        const ignore = () => { };
+        process.on('SIGINT', ignore);
+        const done = () => process.off('SIGINT', ignore);
+        child.on('error', (err) => {
+            done();
+            reject(err.code === 'ENOENT' ? new Error(`${bin} is not on your PATH. Install it, then run this again.`) : err);
+        });
+        child.on('exit', (code, signal) => {
+            done();
+            resolve(code ?? (signal ? 128 + (os.constants.signals[signal] ?? 0) : 1));
+        });
+    });
+}
+/**
+ * `phantom claude`, `phantom codex` and `phantom pi`: runs the agent through the proxy,
+ * passing every other argument through, and returns its exit code. The Phantom CLI's own
+ * flags come first and stop at the first other argument or at `--`; they are
+ * read here, not with `flags`, because everything after them belongs to the
+ * agent. Run by `run()`.
+ */
+export async function agentCommand(input) {
+    const { argv, env, io, baseUrl } = input;
+    const name = argv[0];
+    const spec = AGENTS[name];
+    let keyName;
+    let noBrowser = false;
+    let i = 1;
+    const value = (flag) => {
+        const v = argv[++i];
+        if (v === undefined || v.startsWith('--'))
+            die(`${flag} needs a value`);
+        return v;
+    };
+    for (; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--') {
+            i++;
+            break;
+        }
+        if (a === '--key')
+            keyName = value(a);
+        else if (a === '--mpp')
+            die('--mpp has been removed. Phantom stays prepaid only. Run phantom login or use a saved key.');
+        else if (a === '--no-browser')
+            noBrowser = true;
+        else
+            break;
+    }
+    const agentArgs = argv.slice(i);
+    let apiKey = keyName ? readNamedKey(env, keyName) : resolveApiKey(env);
+    if (!apiKey) {
+        if (!io.isTTY)
+            die('Connect a key with phantom login.');
+        await workspaceLogin({ ...input, flags: { ...(noBrowser ? { 'no-browser': true } : {}) } });
+        apiKey = resolveApiKey(env);
+    }
+    if (!apiKey)
+        die('No API key. Run: phantom login');
+    const auth = { kind: 'key', apiKey };
+    const before = await keyStatus(apiKey, baseUrl).catch(() => null);
+    const report = async () => {
+        const after = await keyStatus(apiKey, baseUrl).catch(() => null);
+        if (!before || !after)
+            return `could not read spend for key ${keyId(apiKey)}`;
+        return `charged $${(after.credit_spent_usd - before.credit_spent_usd).toFixed(6)} on key ${keyId(apiKey)}, $${after.credit_balance_usd.toFixed(6)} available`;
+    };
+    const origin = httpsOnly(baseUrl || env.PHANTOM_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, '').replace(/\/v1$/, '');
+    const token = proxyToken();
+    const proxy = await startProxy({ upstream: `${origin}${spec.prefix}`, auth, token });
+    const tmp = mkdtempSync(path.join(os.tmpdir(), 'phantom-agent-'));
+    try {
+        const { args, env: childEnv } = spec.launch(proxy.url, agentArgs, env, tmp, token);
+        const code = await waitFor(spec.bin, args, childEnv);
+        await proxy.close();
+        io.stderr(`phantom: ${name} made ${proxy.forwarded} request${proxy.forwarded === 1 ? '' : 's'} to Phantom AI${proxy.rejected ? `, and refused ${proxy.rejected} from other programs` : ''}; ${await report()}.\n`);
+        return code;
+    }
+    finally {
+        await proxy.close().catch(() => { });
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}

package/dist/agents/proxy.mjs

@@ -0,0 +1,140 @@
+import { createServer } from 'node:http';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+/**
+ * The local proxy `phantom claude`, `phantom codex` and `phantom pi` point the agent at.
+ * It listens on 127.0.0.1 only, forwards each request to Phantom AI, and
+ * streams the answer back as it arrives, server-sent events included. The
+ * agent never holds a key: the proxy drops whatever auth the agent sends and
+ * adds its own.
+ *
+ * Because the proxy spends the user's key or wallet, it serves only the agent
+ * it started: each request must carry the run's token ({@link proxyToken}),
+ * must name the proxy in its Host header (so a page that rebinds a DNS name
+ * to 127.0.0.1 is refused), and must carry no Origin header (so no browser
+ * page can call it).
+ */
+/** A fresh secret for one run, which the agent sends as its key. */
+export function proxyToken() {
+    return randomBytes(32).toString('base64url');
+}
+/** True when `given` is `token`, compared in constant time. */
+function sameToken(given, token) {
+    if (!given)
+        return false;
+    const b = Buffer.from(given);
+    return b.length === token.length && timingSafeEqual(b, token);
+}
+const HOP = new Set(['host', 'connection', 'keep-alive', 'proxy-connection', 'transfer-encoding', 'upgrade', 'content-length', 'accept-encoding', 'authorization', 'x-api-key', 'te', 'trailer']);
+const HOP_BACK = new Set(['connection', 'keep-alive', 'transfer-encoding', 'content-encoding', 'content-length']);
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => resolve(Buffer.concat(chunks)));
+        req.on('error', reject);
+    });
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(body));
+}
+/**
+ * Starts the proxy on a free port of 127.0.0.1.
+ * @param opts.upstream Where requests go: Phantom AI's address for this agent, such as `https://phantom.codes/claude-code`. The request's path is added to it.
+ * @param opts.auth A saved key, or a paying fetch.
+ * @param opts.token The run's secret ({@link proxyToken}). A request without it, as `Authorization: Bearer` or `x-api-key`, gets 401.
+ */
+export async function startProxy(opts) {
+    const upstream = opts.upstream.replace(/\/+$/, '');
+    const token = Buffer.from(opts.token);
+    const state = { forwarded: 0, rejected: 0 };
+    let port = 0;
+    const server = createServer(async (req, res) => {
+        const method = req.method ?? 'GET';
+        const host = req.headers.host;
+        if (host !== `127.0.0.1:${port}` && host !== `localhost:${port}`) {
+            state.rejected++;
+            sendJson(res, 403, { error: { type: 'forbidden', message: 'phantom\'s proxy serves only requests addressed to 127.0.0.1.' } });
+            return;
+        }
+        if (req.headers.origin !== undefined) {
+            state.rejected++;
+            sendJson(res, 403, { error: { type: 'forbidden', message: 'phantom\'s proxy refuses requests from web pages.' } });
+            return;
+        }
+        const authorization = req.headers.authorization ?? '';
+        const separator = authorization.search(/\s/);
+        const bearer = separator >= 0 && authorization.slice(0, separator).toLowerCase() === 'bearer'
+            ? authorization.slice(separator).trim() : undefined;
+        const apiKey = req.headers['x-api-key'];
+        if (!sameToken(bearer, token) && !sameToken(Array.isArray(apiKey) ? apiKey[0] : apiKey, token)) {
+            state.rejected++;
+            sendJson(res, 401, { error: { type: 'authentication_error', message: 'phantom\'s proxy serves only the agent phantom started with it.' } });
+            return;
+        }
+        const target = new URL(req.url ?? '/', 'http://127.0.0.1');
+        const headers = {};
+        for (const [k, v] of Object.entries(req.headers)) {
+            if (v === undefined || HOP.has(k.toLowerCase()))
+                continue;
+            headers[k] = Array.isArray(v) ? v.join(', ') : v;
+        }
+        if (/\/v1\/messages(\/|$)/.test(target.pathname))
+            headers['x-api-key'] = opts.auth.apiKey;
+        else
+            headers.authorization = `Bearer ${opts.auth.apiKey}`;
+        const aborter = new AbortController();
+        res.on('close', () => {
+            if (!res.writableFinished)
+                aborter.abort();
+        });
+        try {
+            const body = method === 'GET' || method === 'HEAD' ? undefined : await readBody(req);
+            state.forwarded++;
+            const answer = await fetch(`${upstream}${target.pathname}${target.search}`, {
+                method,
+                headers,
+                ...(body && body.length ? { body: new Uint8Array(body) } : {}),
+                signal: aborter.signal,
+            });
+            const back = {};
+            answer.headers.forEach((v, k) => {
+                if (!HOP_BACK.has(k.toLowerCase()))
+                    back[k] = v;
+            });
+            res.writeHead(answer.status, back);
+            if (answer.body) {
+                for await (const chunk of answer.body)
+                    res.write(chunk);
+            }
+            res.end();
+        }
+        catch (err) {
+            if (aborter.signal.aborted)
+                return;
+            const message = err instanceof Error ? err.message : String(err);
+            if (!res.headersSent)
+                sendJson(res, 502, { error: { type: 'proxy_error', message: `phantom could not get this from Phantom AI: ${message}` } });
+            else
+                res.destroy();
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => resolve());
+    });
+    port = server.address().port;
+    return {
+        url: `http://127.0.0.1:${port}`,
+        get rejected() {
+            return state.rejected;
+        },
+        get forwarded() {
+            return state.forwarded;
+        },
+        close: () => new Promise((resolve) => {
+            server.closeAllConnections();
+            server.close(() => resolve());
+        }),
+    };
+}