u1s1-cli 1.14.6 → 1.15.1

package/dist/usage.js

@@ -72,7 +72,7 @@ function groupPackages(packages) {
 }
 function packageScopeNote(pkg) {
     if (pkg.kind === "login_checkin") {
-        return tr("仅限 u1s1 客户端使用 · 全模型可用", "u1s1 clients only · all models");
+        return tr("全模型可用", "All models");
     }
     if (pkg.scope === "free") {
         // 只有按日发放的免费包(首月/年度包的每日额度)才 0 点恢复;一次性免费包用完就没了。
@@ -80,7 +80,7 @@ function packageScopeNote(pkg) {
             ? tr("免费包适用模型 · 每日额度北京时间 0 点恢复", "Free-tier models · daily quota resets at 00:00 Beijing time (UTC+8)")
             : tr("免费包适用模型", "Free-tier models");
     }
-    return tr("仅限 u1s1 客户端使用 · 免费包适用模型", "u1s1 clients only · free-tier models");
+    return tr("免费包适用模型", "Free-tier models");
 }
 function packageLabel(pkg) {
     const count = pkg.count > 1 ? ` ×${pkg.count}` : "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u1s1-cli",
-  "version": "1.14.6",
+  "version": "1.15.1",
   "description": "u1s1 — 有一说一,最省心的 AI 编程搭子。终端里用中文说需求,AI 帮你读文件、改代码、跑命令。",
   "type": "module",
   "bin": {

package/scripts/p0-claude-code/README.md

@@ -0,0 +1,39 @@
+# P0 验证:签名代理带起官方 Claude Code + /v1/messages 提示缓存
+
+规划见 `docs/multi-client-launcher-plan-2026-11-13.md` 第 3.4、4.3、4.4、7 节。只用于本地验证,不上线。
+
+| 文件 | 作用 |
+| --- | --- |
+| `seed-local.mjs` | 给本机 `wrangler dev --env intl` 的网关建渠道、Claude Haiku 模型行、测试用户(购买余额)和设备凭证,写出隔离 HOME 下的 `.u1s1/config.json` |
+| `launch-claude.ts` | 起 CLI 的 `ensureSigningProxy`,以子进程启动 `claude`(独立 `CLAUDE_CONFIG_DIR`、`ANTHROPIC_BASE_URL` 不带 `/v1`、`ANTHROPIC_AUTH_TOKEN`=本地 token、`--settings`),父进程等子进程退出 |
+| `tap.mjs` | 本地录包反代:`P0_TAP_DIR` 时插在 claude 与代理之间;单独跑时配 `UPSTREAM_OVERRIDES` 插在网关与上游之间 |
+| `replay.ts` | 把录到的一次 Claude Code 请求重放 N 次(直连上游 / 经本地网关),打印 usage |
+
+测试:`packages/cli/test/signing-proxy-claude-code.test.ts`(代理对 Claude Code 请求的处理)、`workers/gateway/test/anthropic-cache-roundtrip.test.ts`(两次转换丢了什么,特征测试)。
+
+## 跑法
+
+```bash
+# 网关:见 scratchpad 的 p0-local-stack.md(wrangler dev 需要转出入口 + -c + --local-upstream)
+set -a; . ~/code/selfhost/secrets/u1s1-prod/wokey.env; set +a
+node packages/cli/scripts/p0-claude-code/seed-local.mjs --home $SCRATCH/home
+cd $SCRATCH/work && HOME=$SCRATCH/home P0_CLAUDE_CONFIG_DIR=$SCRATCH/claude-cfg P0_TAP_DIR=$SCRATCH/tap \
+  <repo>/packages/cli/node_modules/.bin/tsx <repo>/packages/cli/scripts/p0-claude-code/launch-claude.ts \
+  -p "Use the Bash tool to run: cat note.txt — then reply with just the number in it." \
+  --output-format stream-json --verbose --max-turns 4
+```
+
+## 2026-11-13 实测结果(claude 2.1.322,claude-haiku-4-5)
+
+- Bash 工具一轮往返、ToolSearch → TaskCreate 三轮往返都正常结束(exit 0)。
+- usage 行:`client_type=terminal`、`auth_kind=device`、`client_security_verdict=suspected_relay`,信号
+  `client_signature_claude_code, external_client_ua, missing_brand_prompt, third_party_harness_prompt, valid_device_attestation`。
+  只能花购买余额;admin 发的赠送余额会被 403 拒。
+- 同一份 21.6k token 的 Claude Code 请求重放两次:
+
+| 路径 | 第 1 次 | 第 2 次 | 计费 |
+| --- | --- | --- | --- |
+| 直连上游(原生 Messages,带 Claude Code 自己的 3 个 cache_control) | 写缓存 21597 | 读缓存 21597 | — |
+| 网关 → `openai-chat` 渠道(网关自己补 3 个断点,`chat-compat.ts`) | 写缓存 21492 | 读缓存 21492 | 写/读都按售价计,正确 |
+| 网关 → `anthropic-messages` 渠道,单条消息 | 无缓存 21673 | 无缓存 21673 | 全价 |
+| 网关 → `anthropic-messages` 渠道,多条消息 | 上游自动写 21615 | 读 21615 | 写入 0 计费,读取只记 $0.00003(实付约 $0.0022) |

package/scripts/p0-claude-code/launch-claude.ts

@@ -0,0 +1,94 @@
+// P0 verification: start the CLI's local signing proxy and launch the official
+// Claude Code as a child process through it, without touching the user's own
+// ~/.claude or ~/.u1s1.
+//
+//   HOME=<isolated home with .u1s1/config.json> \
+//   P0_CLAUDE_CONFIG_DIR=<isolated dir> [P0_TAP_DIR=<dir>] [P0_MODEL=claude-haiku-4-5] \
+//   npx tsx packages/cli/scripts/p0-claude-code/launch-claude.ts -p "..." --output-format stream-json --verbose
+//
+// P0_TAP_DIR inserts a recording hop between claude and the signing proxy
+// (tap.mjs), so the exact Claude Code request bodies/headers and the SSE the
+// proxy relays back are captured.
+import { spawn } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { userInfo } from "node:os";
+import { join, resolve } from "node:path";
+import { fetchModels } from "../../src/api.js";
+import { loadConfig } from "../../src/config.js";
+import { ensureSigningProxy } from "../../src/device-auth.js";
+import { startTap } from "./tap.mjs";
+
+const realHome = userInfo().homedir;
+if (!process.env.HOME || resolve(process.env.HOME) === resolve(realHome)) {
+  throw new Error("HOME must point at an isolated directory, not the real home");
+}
+const configDir = process.env.P0_CLAUDE_CONFIG_DIR;
+if (!configDir || resolve(configDir) === resolve(realHome, ".claude")) {
+  throw new Error("P0_CLAUDE_CONFIG_DIR must be set to an isolated directory");
+}
+mkdirSync(configDir, { recursive: true });
+
+const cfg = loadConfig();
+if (!/^http:\/\/127\.0\.0\.1:\d+\/v1$/.test(cfg.baseUrl)) {
+  throw new Error(`config baseUrl must be a local gateway, got ${cfg.baseUrl}`);
+}
+
+// Same order as web.ts prepareWebEnv: one /v1/models fetch seeds the attestation.
+const models = await fetchModels(cfg);
+const signing = await ensureSigningProxy(cfg, "terminal", {
+  token: models.clientAttestation,
+  expiresInSeconds: models.clientAttestationExpiresInSeconds,
+  refresh: async () => {
+    const refreshed = await fetchModels(cfg);
+    return { token: refreshed.clientAttestation, expiresInSeconds: refreshed.clientAttestationExpiresInSeconds };
+  },
+});
+let origin = new URL(signing.baseUrl).origin; // no /v1: Claude Code appends /v1/messages itself
+let tap: { port: number; close: () => void } | undefined;
+if (process.env.P0_TAP_DIR) {
+  tap = await startTap({ target: origin, out: process.env.P0_TAP_DIR, label: "claude->proxy" });
+  origin = `http://127.0.0.1:${tap!.port}`;
+}
+
+// Mirrors workers/gateway/src/claude-code-config.ts claudeCodeSettings (minus base URL / token,
+// which go through env so the real credential never lands in a settings file).
+const model = process.env.P0_MODEL ?? "claude-haiku-4-5";
+const settingsPath = join(configDir, "..", "u1s1-claude-settings.json");
+writeFileSync(settingsPath, JSON.stringify({
+  env: {
+    ANTHROPIC_DEFAULT_HAIKU_MODEL: model,
+    ANTHROPIC_DEFAULT_SONNET_MODEL: model,
+    ANTHROPIC_DEFAULT_OPUS_MODEL: model,
+  },
+  model,
+  modelPicker: {
+    replaceBuiltInOptions: true,
+    options: models.models.map((m) => ({ model: m.id, label: m.name ?? m.id, description: "u1s1 local" })),
+  },
+  permissions: { deny: ["WebSearch"] },
+}, null, 2));
+
+// scrubForeignProviderEnv() deletes ANTHROPIC_AUTH_TOKEN from process.env in the real
+// launcher, so the child env is built explicitly here.
+const childEnv: NodeJS.ProcessEnv = {
+  ...process.env,
+  CLAUDE_CONFIG_DIR: configDir,
+  ANTHROPIC_BASE_URL: origin,
+  ANTHROPIC_AUTH_TOKEN: signing.localKey,
+  DISABLE_AUTOUPDATER: "1",
+  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1",
+};
+delete childEnv.ANTHROPIC_API_KEY;
+
+const claudeBin = process.env.P0_CLAUDE_BIN ?? "claude";
+const child = spawn(claudeBin, ["--settings", settingsPath, ...process.argv.slice(2)], {
+  env: childEnv,
+  stdio: "inherit",
+});
+for (const signal of ["SIGINT", "SIGTERM"] as const) {
+  process.on(signal, () => child.kill(signal));
+}
+// The proxy server is unref'd: keep the parent alive until the child exits.
+const code: number = await new Promise((done) => child.on("exit", (c, s) => done(c ?? (s ? 128 : 1))));
+tap?.close();
+process.exit(code);

package/scripts/p0-claude-code/replay.ts

@@ -0,0 +1,74 @@
+// P0 ② live check: replay one captured Claude Code request N times, either
+// straight to the upstream (native Messages baseline) or through the LOCAL
+// gateway with the device credential, and print the usage each response reports.
+//
+//   direct : WOKEY_API_KEY=... npx tsx replay.ts --capture <tap json> --mode direct --times 2
+//   gateway: HOME=<isolated> npx tsx replay.ts --capture <tap json> --mode gateway --model claude-haiku-4-5 --times 2
+//
+// Keep requests few and the model cheap: each replay of a Claude Code turn is ~22k input tokens.
+import { readFileSync } from "node:fs";
+import { loadConfig } from "../../src/config.js";
+import { authorizedFetch } from "../../src/device-auth.js";
+
+function arg(name: string, fallback?: string): string | undefined {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > 0 ? process.argv[i + 1] : fallback;
+}
+
+const capture = JSON.parse(readFileSync(arg("capture")!, "utf8"));
+const mode = arg("mode", "gateway");
+const times = Number(arg("times", "2"));
+const body = { ...capture.request.body };
+if (arg("model")) body.model = arg("model");
+if (arg("strip-signatures") === "1") {
+  // Signatures minted by the gateway are "" (anthropic-inbound.ts); a native upstream rejects them.
+  for (const m of body.messages) {
+    if (Array.isArray(m.content)) m.content = m.content.filter((b: { type?: string }) => b.type !== "thinking");
+  }
+}
+
+const passHeaders: Record<string, string> = { "content-type": "application/json" };
+for (const name of ["anthropic-version", "anthropic-beta", "user-agent", "x-app", "x-claude-code-session-id"]) {
+  const value = capture.request.headers[name];
+  if (typeof value === "string") passHeaders[name] = value;
+}
+
+function usageOf(text: string): { start?: unknown; delta?: unknown } {
+  const out: { start?: unknown; delta?: unknown } = {};
+  for (const line of text.split("\n")) {
+    if (!line.startsWith("data: ")) continue;
+    try {
+      const event = JSON.parse(line.slice(6));
+      if (event.type === "message_start") out.start = event.message?.usage;
+      if (event.type === "message_delta") out.delta = event.usage;
+      if (event.type === "error") out.delta = event.error;
+    } catch {
+      // ignore non-JSON frames
+    }
+  }
+  return out;
+}
+
+for (let i = 1; i <= times; i++) {
+  let response: Response;
+  if (mode === "direct") {
+    const key = process.env.WOKEY_API_KEY;
+    if (!key) throw new Error("WOKEY_API_KEY not set");
+    response = await fetch("https://api.wokey.ai/v1/messages", {
+      method: "POST",
+      headers: { ...passHeaders, "x-api-key": key },
+      body: JSON.stringify(body),
+    });
+  } else {
+    const cfg = loadConfig();
+    if (!/^http:\/\/127\.0\.0\.1:\d+\/v1$/.test(cfg.baseUrl)) throw new Error(`not a local gateway: ${cfg.baseUrl}`);
+    response = await authorizedFetch(cfg, `${cfg.baseUrl}/messages?beta=true`, {
+      method: "POST",
+      headers: passHeaders,
+      body: JSON.stringify(body),
+    });
+  }
+  const text = await response.text();
+  const usage = usageOf(text);
+  console.log(JSON.stringify({ mode, round: i, model: body.model, status: response.status, ...usage, ...(response.ok ? {} : { error: text.slice(0, 300) }) }));
+}

package/scripts/p0-claude-code/seed-local.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// P0 verification only: seed a LOCAL intl gateway (wrangler dev on 127.0.0.1) with
+// two upstream channels, Claude Haiku model rows, a test user with balance and a
+// device credential, then write a u1s1 CLI config.json into an isolated HOME.
+//
+// Never point this at a deployed gateway: it writes straight into the local D1
+// sqlite file and refuses non-loopback gateway URLs.
+//
+// Usage (from repo root, gateway already running via wrangler dev --env intl):
+//   WOKEY_API_KEY=... node packages/cli/scripts/p0-claude-code/seed-local.mjs --home <dir>
+// Options:
+//   --gateway http://127.0.0.1:8787   local gateway origin
+//   --home <dir>                      isolated HOME; config lands in <dir>/.u1s1/config.json
+//   --d1 <sqlite>                     local D1 file (auto-detected under workers/gateway/.wrangler)
+import { execFileSync } from "node:child_process";
+import { createHash, randomBytes, webcrypto } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../../..");
+const gatewayDir = join(repoRoot, "workers/gateway");
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > 0 ? process.argv[i + 1] : fallback;
+}
+
+const gateway = arg("gateway", "http://127.0.0.1:8787");
+const home = arg("home");
+if (!home) throw new Error("--home <dir> is required (isolated HOME for the u1s1 CLI config)");
+if (!/^http:\/\/(127\.0\.0\.1|localhost)(:\d+)?$/.test(gateway)) {
+  throw new Error(`refusing non-loopback gateway ${gateway}`);
+}
+const wokeyKey = process.env.WOKEY_API_KEY;
+if (!wokeyKey) throw new Error("WOKEY_API_KEY must be set in the environment");
+
+function devVar(name) {
+  const text = readFileSync(join(gatewayDir, ".dev.vars"), "utf8");
+  const line = text.split("\n").find((l) => l.startsWith(`${name}=`));
+  if (!line) throw new Error(`${name} missing from workers/gateway/.dev.vars`);
+  return line.slice(name.length + 1).trim();
+}
+
+function d1Path() {
+  const explicit = arg("d1");
+  if (explicit) return explicit;
+  const dir = join(gatewayDir, ".wrangler/state/v3/d1/miniflare-D1DatabaseObject");
+  const files = readdirSync(dir).filter((f) => f.endsWith(".sqlite") && f !== "metadata.sqlite");
+  if (files.length !== 1) throw new Error(`expected exactly one local D1 file in ${dir}, got ${files.join(", ")}`);
+  return join(dir, files[0]);
+}
+
+const adminKey = devVar("ADMIN_KEY");
+const db = d1Path();
+
+function sql(statement) {
+  return execFileSync("sqlite3", [db, statement], { encoding: "utf8" }).trim();
+}
+
+const q = (v) => (v === null ? "NULL" : typeof v === "number" ? String(v) : `'${String(v).replaceAll("'", "''")}'`);
+
+async function admin(method, path, body) {
+  const init = { method, headers: { authorization: `Bearer ${adminKey}`, "content-type": "application/json" } };
+  if (body !== undefined) init.body = JSON.stringify(body);
+  const res = await fetch(`${gateway}/admin${path}`, init);
+  const text = await res.text();
+  if (!res.ok) throw new Error(`admin ${method} ${path} -> ${res.status} ${text.slice(0, 300)}`);
+  return JSON.parse(text);
+}
+
+// 1. Channels. wokey-msg mirrors "Claude model + anthropic-messages upstream"; wokey is the
+//    openai-chat shape the production intl site uses today, kept for comparison.
+await admin("POST", "/channels", {
+  name: "wokey-msg",
+  group_name: "wokey-msg",
+  chat_url: "https://api.wokey.ai/v1/messages",
+  protocol: "anthropic-messages",
+  api_key: wokeyKey,
+  headers: { "anthropic-version": "2023-06-01" },
+  note: "P0 local test",
+});
+await admin("POST", "/channels", {
+  name: "wokey",
+  group_name: "wokey",
+  chat_url: "https://api.wokey.ai/v1/chat/completions",
+  protocol: "openai-chat",
+  api_key: wokeyKey,
+  note: "P0 local test",
+});
+
+// 2. Models (cost = Wokey Haiku 4.5 list: $1 / $5 / $0.10 cache read per Mtok) + retail rows.
+const MODELS = [
+  { id: "claude-haiku-4-5", provider: "wokey-msg", display: "Claude Haiku 4.5 (anthropic-messages)" },
+  { id: "claude-haiku-4-5-oc", provider: "wokey", display: "Claude Haiku 4.5 (openai-chat)" },
+];
+for (const m of MODELS) {
+  sql(`DELETE FROM models WHERE id = ${q(m.id)}; DELETE FROM model_prices WHERE model_id = ${q(m.id)};`);
+  sql(`INSERT INTO models (id, provider, upstream_model, display_name, vendor, enabled, reasoning, vision,
+         price_currency, input_price, output_price, cache_read_price, context_window, max_tokens, sort, priority)
+       VALUES (${q(m.id)}, ${q(m.provider)}, 'claude-haiku-4-5', ${q(m.display)}, 'anthropic', 1, 1, 1,
+         'USD', 1, 5, 0.1, 200000, 64000, 10, 0)`);
+  sql(`INSERT INTO model_prices (model_id, price_currency, input_price, output_price, cache_read_price,
+         price_source, checked_at, cost_markup)
+       VALUES (${q(m.id)}, 'USD', 1.22, 6.1, 0.122, 'p0-local-test', datetime('now'), 0.22)`);
+}
+
+// 3. Test user + paid balance + device credential.
+const email = `p0-${Date.now()}@example.invalid`;
+const user = await admin("POST", "/users", { email, name: "p0 local" });
+await admin("POST", `/users/${user.user_id}/grant`, { amount_usd: 5, note: "P0 local test" });
+// Admin grants are gift balance, usable only by official u1s1 clients (credits.ts balanceGrantStatements).
+// Claude Code is classified suspected_relay -> paid balance only, so simulate a top-up instead.
+sql(`UPDATE users SET gift_balance_usd = 0 WHERE id = ${user.user_id}`);
+const keyId = Number(sql(`SELECT id FROM keys WHERE user_id = ${user.user_id} ORDER BY id DESC LIMIT 1`));
+
+const pair = await webcrypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);
+const privateJwk = await webcrypto.subtle.exportKey("jwk", pair.privateKey);
+const publicJwk = await webcrypto.subtle.exportKey("jwk", pair.publicKey);
+const deviceToken = `u1s1d-g${randomBytes(32).toString("hex")}`;
+const tokenHash = createHash("sha256").update(deviceToken).digest("hex");
+const storedJwk = JSON.stringify({ kty: "EC", crv: "P-256", x: publicJwk.x, y: publicJwk.y, ext: true });
+sql(`INSERT INTO devices (user_id, key_id, token_hash, public_jwk, name, client_version)
+     VALUES (${user.user_id}, ${keyId}, ${q(tokenHash)}, ${q(storedJwk)}, 'p0-local', '1.14.6')`);
+const deviceId = Number(sql(`SELECT id FROM devices WHERE token_hash = ${q(tokenHash)}`));
+
+const configDir = join(home, ".u1s1");
+mkdirSync(configDir, { recursive: true, mode: 0o700 });
+writeFileSync(join(configDir, "config.json"), JSON.stringify({
+  deviceToken,
+  deviceId,
+  devicePrivateJwk: privateJwk,
+  devicePublicJwk: publicJwk,
+  baseUrl: `${gateway}/v1`,
+  model: "claude-haiku-4-5",
+  email,
+}, null, 2), { mode: 0o600 });
+
+console.log(JSON.stringify({
+  ok: true,
+  user_id: user.user_id,
+  device_id: deviceId,
+  config: join(configDir, "config.json"),
+  models: MODELS.map((m) => `${m.id} -> ${m.provider}`),
+}, null, 2));

package/scripts/p0-claude-code/tap.mjs

@@ -0,0 +1,105 @@
+// P0 verification helper: a loopback reverse proxy that records every exchange
+// (request headers + body, response status/headers + full body) as JSON files,
+// then forwards to the target origin. Credentials are redacted in the records
+// but forwarded untouched.
+//
+// Standalone: node tap.mjs --port 8797 --target https://api.wokey.ai --out <dir>
+// Library:    import { startTap } from "./tap.mjs"
+import { createServer } from "node:http";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REDACT = new Set(["authorization", "x-api-key", "dpop", "x-u1s1-attestation", "cookie"]);
+const HOP = new Set(["host", "connection", "content-length", "transfer-encoding", "keep-alive"]);
+
+function redactedHeaders(headers) {
+  const out = {};
+  for (const [name, value] of Object.entries(headers)) {
+    out[name] = REDACT.has(name.toLowerCase()) ? `<redacted:${String(value).length}>` : value;
+  }
+  return out;
+}
+
+function parseMaybeJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+/** @returns {Promise<{ port: number, close: () => void }>} */
+export async function startTap({ port = 0, target, out, label = "tap" }) {
+  mkdirSync(out, { recursive: true });
+  let seq = 0;
+  const server = createServer(async (req, res) => {
+    const id = String(++seq).padStart(3, "0");
+    const chunks = [];
+    for await (const chunk of req) chunks.push(chunk);
+    const body = Buffer.concat(chunks);
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+      if (HOP.has(name) || value === undefined) continue;
+      if (Array.isArray(value)) for (const v of value) headers.append(name, v);
+      else headers.set(name, value);
+    }
+    const record = {
+      label,
+      at: new Date().toISOString(),
+      request: {
+        method: req.method,
+        url: req.url,
+        headers: redactedHeaders(req.headers),
+        body: body.length ? parseMaybeJson(body.toString("utf8")) : null,
+      },
+    };
+    try {
+      const upstream = await fetch(new URL(req.url, target), {
+        method: req.method,
+        headers,
+        body: body.length ? body : undefined,
+      });
+      const responseHeaders = {};
+      upstream.headers.forEach((value, name) => {
+        if (!["content-length", "transfer-encoding", "connection", "content-encoding"].includes(name)) {
+          responseHeaders[name] = value;
+        }
+      });
+      res.writeHead(upstream.status, responseHeaders);
+      const decoder = new TextDecoder();
+      let text = "";
+      if (upstream.body) {
+        for await (const chunk of upstream.body) {
+          text += decoder.decode(chunk, { stream: true });
+          res.write(chunk);
+        }
+      }
+      res.end();
+      record.response = { status: upstream.status, headers: responseHeaders, body: text };
+    } catch (error) {
+      record.error = String(error);
+      if (!res.headersSent) res.writeHead(502, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: { message: `tap forward failed: ${error}` } }));
+    }
+    mkdirSync(out, { recursive: true });
+    writeFileSync(join(out, `${id}-${(req.url ?? "").replace(/[^a-z0-9]+/gi, "_").slice(0, 40)}.json`),
+      JSON.stringify(record, null, 2));
+  });
+  await new Promise((resolve) => server.listen(port, "127.0.0.1", resolve));
+  return { port: server.address().port, close: () => server.close() };
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const arg = (name) => {
+    const i = process.argv.indexOf(`--${name}`);
+    return i > 0 ? process.argv[i + 1] : undefined;
+  };
+  const tap = await startTap({
+    port: Number(arg("port") ?? 0),
+    target: arg("target"),
+    out: arg("out"),
+    label: arg("label") ?? "tap",
+  });
+  console.log(`tap listening on http://127.0.0.1:${tap.port} -> ${arg("target")}`);
+}