@amir83nasr/10router 0.1.0

package/bin/10router.mjs

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+// ── 10ROUTER CLI ────────────────────────────────────────────────────
+// Local lifecycle: start/stop/status/logs/open/doctor. No Docker.
+// Stdlib only (+ already-installed `open` for the `open` command).
+
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const DEV_PORT = "20127";
+const PROD_PORT = "20128";
+// Repo checkout (pnpm-lock) → dev workflow; npm-installed package → prod only.
+const IS_REPO = fs.existsSync(path.join(ROOT, "pnpm-lock.yaml"));
+
+// ── DATA DIR (mirrors src/lib/dataDir.js, sync version) ─────────────
+function getDataDir() {
+  const configured = process.env.DATA_DIR;
+  const fallback = path.join(os.homedir(), ".10router");
+  if (!configured) return fallback;
+  try {
+    fs.mkdirSync(configured, { recursive: true });
+    return configured;
+  } catch {
+    return fallback;
+  }
+}
+
+const DATA_DIR = getDataDir();
+const PID_FILE = path.join(DATA_DIR, "10router.pid");
+const LOG_FILE = path.join(DATA_DIR, "10router.log");
+
+function readState() {
+  try {
+    return JSON.parse(fs.readFileSync(PID_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function baseUrl(port) {
+  return `http://localhost:${port}`;
+}
+
+async function health(port) {
+  try {
+    const r = await fetch(`${baseUrl(port)}/api/health`, {
+      signal: AbortSignal.timeout(3000),
+    });
+    return r.ok;
+  } catch {
+    return false;
+  }
+}
+
+// ── COMMANDS ────────────────────────────────────────────────────────
+async function cmdStart(opts) {
+  // npm-installed package has a prebuilt .next — default to prod there.
+  const mode = opts.dev && IS_REPO ? "dev" : opts.prod || !IS_REPO ? "prod" : "dev";
+  const port = opts.port || (mode === "prod" ? PROD_PORT : DEV_PORT);
+  const st = readState();
+  if (st && isAlive(st.pid)) {
+    console.log(`already running (pid ${st.pid}, ${st.mode} :${st.port})`);
+    return;
+  }
+  if (st) fs.rmSync(PID_FILE, { force: true }); // stale pidfile
+
+  const env = { ...process.env, PORT: String(port), DATA_DIR };
+  let cmd, args;
+  if (mode === "prod") {
+    if (!fs.existsSync(path.join(ROOT, ".next"))) {
+      console.error("no .next build found — run `pnpm build` first");
+      process.exitCode = 1;
+      return;
+    }
+    cmd = process.execPath;
+    args = [path.join(ROOT, "custom-server.js"), "--port", String(port)];
+  } else {
+    // Repo-only dev mode (IS_REPO) — pnpm is the repo's package manager.
+    cmd = "pnpm";
+    args = ["exec", "next", "dev", "--port", String(port)];
+  }
+
+  if (opts.foreground) {
+    console.log(`[${mode}] ${baseUrl(port)} (foreground, Ctrl+C to stop)`);
+    const child = spawn(cmd, args, { cwd: ROOT, stdio: "inherit", env });
+    const stop = () => child.kill();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    child.on("exit", (code) => process.exit(code ?? 0));
+    return;
+  }
+
+  fs.mkdirSync(DATA_DIR, { recursive: true });
+  const logFd = fs.openSync(LOG_FILE, "a");
+  const child = spawn(cmd, args, {
+    cwd: ROOT,
+    stdio: ["ignore", logFd, logFd],
+    env,
+    detached: process.platform !== "win32",
+    shell: process.platform === "win32",
+  });
+  child.unref();
+  fs.writeFileSync(
+    PID_FILE,
+    JSON.stringify({ pid: child.pid, port: String(port), mode, startedAt: Date.now() }),
+  );
+  console.log(`started ${mode} (pid ${child.pid}) → ${baseUrl(port)}`);
+  console.log(`logs: ${LOG_FILE}`);
+}
+
+function killTree(pid) {
+  if (process.platform === "win32") {
+    spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore" });
+  } else {
+    try {
+      process.kill(-pid, "SIGTERM"); // process group (dev spawns pnpm→next)
+    } catch {
+      try {
+        process.kill(pid, "SIGTERM");
+      } catch {
+        /* already dead */
+      }
+    }
+  }
+}
+
+function cmdStop() {
+  const st = readState();
+  if (!st) {
+    console.log("not running (no pidfile)");
+    return;
+  }
+  if (!isAlive(st.pid)) {
+    fs.rmSync(PID_FILE, { force: true });
+    console.log("stale pidfile removed — was not running");
+    return;
+  }
+  killTree(st.pid);
+  fs.rmSync(PID_FILE, { force: true });
+  console.log(`stopped (was pid ${st.pid}, ${st.mode} :${st.port})`);
+}
+
+async function cmdStatus() {
+  const st = readState();
+  const alive = st ? isAlive(st.pid) : false;
+  if (st && !alive) fs.rmSync(PID_FILE, { force: true }); // clean stale
+  const port = st?.port || process.env.PORT;
+  const ok = port ? await health(port) : false;
+  console.log(`running: ${alive ? `yes (pid ${st.pid}, ${st.mode})` : "no"}`);
+  console.log(
+    port
+      ? `health:  ${ok ? `ok ${baseUrl(port)}/api/health` : `down :${port}`}`
+      : "health:  — (nothing started, PORT unset)",
+  );
+  console.log(`data:    ${DATA_DIR}`);
+  if (!alive) process.exitCode = 1;
+}
+
+function cmdLogs(opts) {
+  let text;
+  try {
+    text = fs.readFileSync(LOG_FILE, "utf8");
+  } catch {
+    console.log("no logs yet");
+    return;
+  }
+  const lines = text.trimEnd().split("\n");
+  const n = opts.n || 50;
+  process.stdout.write(lines.slice(-n).join("\n") + "\n");
+  if (!opts.follow) return;
+  // follow: poll for appended bytes (cross-platform, no `tail` dep)
+  let pos = fs.statSync(LOG_FILE).size;
+  const timer = setInterval(() => {
+    const size = fs.statSync(LOG_FILE).size;
+    if (size > pos) {
+      const fd = fs.openSync(LOG_FILE, "r");
+      const buf = Buffer.alloc(size - pos);
+      fs.readSync(fd, buf, 0, buf.length, pos);
+      fs.closeSync(fd);
+      process.stdout.write(buf.toString());
+      pos = size;
+    }
+  }, 500);
+  process.once("SIGINT", () => {
+    clearInterval(timer);
+    process.exit(0);
+  });
+}
+
+async function cmdOpen(opts) {
+  const st = readState();
+  const port = opts.port || st?.port || process.env.PORT || PROD_PORT;
+  const url = `${baseUrl(port)}/dashboard`;
+  const { default: open } = await import("open");
+  await open(url);
+  console.log(url);
+}
+
+function cmdDoctor() {
+  const fails = [];
+  const check = (name, ok, hint = "") => {
+    console.log(`${ok ? "ok  " : "FAIL"}  ${name}${ok ? "" : ` — ${hint}`}`);
+    if (!ok) fails.push(name);
+  };
+  const major = Number(process.versions.node.split(".")[0]);
+  check(`node ${process.version}`, major >= 20, "need node >= 20");
+  if (IS_REPO) {
+    const pnpm = spawnSync("pnpm", ["--version"], { encoding: "utf8" });
+    check(`pnpm ${pnpm.stdout?.trim() || "?"}`, pnpm.status === 0, "need pnpm for dev mode");
+  }
+  try {
+    fs.mkdirSync(DATA_DIR, { recursive: true });
+    fs.accessSync(DATA_DIR, fs.constants.W_OK);
+    check(`DATA_DIR ${DATA_DIR}`, true);
+  } catch {
+    check(`DATA_DIR ${DATA_DIR}`, false, "not writable");
+  }
+  check(
+    ".next build (for start --prod)",
+    fs.existsSync(path.join(ROOT, ".next")),
+    "run pnpm build",
+  );
+  if (fails.length) process.exitCode = 1;
+}
+
+function help() {
+  console.log(`10router — local gateway lifecycle (DATA_DIR=${DATA_DIR})
+
+usage: 10router <command> [options]
+
+  start [--prod|--dev] [--port N] [--foreground]  start gateway
+                                   (repo default: dev :${DEV_PORT}; npm install: prod :${PROD_PORT})
+  stop                                        stop background gateway
+  status                                      pid alive? health? paths?
+  logs [-n N] [-f]                            tail log (default last 50 lines)
+  open [--port N]                             open dashboard in browser
+  doctor                                      node/pnpm/DATA_DIR/build checks
+  help | --help                               this text
+  --version                                   package version
+
+env: DATA_DIR (default ~/.10router), PORT. prod default :${PROD_PORT}.`);
+}
+
+// ── ARGS ────────────────────────────────────────────────────────────
+const [cmd, ...rest] = process.argv.slice(2);
+const flag = (s, l) => rest.includes(s) || (l && rest.includes(l));
+const val = (s, l) => {
+  const i = rest.findIndex((a) => a === s || a === l);
+  return i >= 0 ? rest[i + 1] : undefined;
+};
+const opts = {
+  prod: flag("--prod"),
+  dev: flag("--dev"),
+  foreground: flag("--foreground") || flag("--fg"),
+  follow: flag("-f", "--follow"),
+  port: val("--port", "-p"),
+  n: Number(val("-n", "--lines")) || undefined,
+};
+
+const run = async () => {
+  switch (cmd) {
+    case "start":
+      return cmdStart(opts);
+    case "stop":
+      return cmdStop();
+    case "status":
+      return cmdStatus();
+    case "logs":
+      return cmdLogs(opts);
+    case "open":
+      return cmdOpen(opts);
+    case "doctor":
+      return cmdDoctor();
+    case "--version":
+    case "version": {
+      const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8"));
+      console.log(pkg.version);
+      return;
+    }
+    default:
+      help();
+      if (cmd && cmd !== "help" && cmd !== "--help") process.exitCode = 1;
+  }
+};
+
+run().catch((e) => {
+  console.error(e?.message || e);
+  process.exitCode = 1;
+});

package/custom-server.js

@@ -0,0 +1,147 @@
+const http = require("http");
+const path = require("path");
+const fs = require("fs");
+const crypto = require("crypto");
+const { pathToFileURL } = require("url");
+
+const origCreate = http.createServer.bind(http);
+
+// Per-process secret proving x-10r-real-ip was stamped below rather than sent by the client.
+// A bare `next start` / `next dev` never loads this file, so it cannot produce a matching
+// header even though the env var is inherited by child processes. Named like x-10r-cli-token
+// so the request-detail header sanitizer redacts it too.
+const PEER_TOKEN = crypto.randomBytes(24).toString("hex");
+process.env.TENROUTER_PEER_TOKEN = PEER_TOKEN;
+
+let backgroundRefreshStarted = false;
+
+function startBackgroundTokenRefreshFromCustomServer() {
+  if (backgroundRefreshStarted) return;
+  backgroundRefreshStarted = true;
+  // Prefer source path (repo / standalone that still has src). Fail-open if missing
+  // — initializeApp also starts the same scheduler when the Next app boots.
+  const modPath = path.join(__dirname, "src", "sse", "services", "backgroundTokenRefresh.js");
+  import(pathToFileURL(modPath).href)
+    .then((m) => {
+      try {
+        m.startBackgroundTokenRefresh();
+      } catch (e) {
+        console.error("[BackgroundTokenRefresh] start failed:", e && e.message ? e.message : e);
+      }
+      const stop = () => {
+        try {
+          m.stopBackgroundTokenRefresh();
+        } catch {
+          /* ignore */
+        }
+      };
+      process.once("SIGINT", stop);
+      process.once("SIGTERM", stop);
+    })
+    .catch((e) => {
+      // Expected in published CLI standalone (src/ not on disk). App bootstrap covers it.
+      if (process.env.DEBUG_BACKGROUND_TOKEN_REFRESH) {
+        console.error("[BackgroundTokenRefresh] import failed:", e && e.message ? e.message : e);
+      }
+    });
+}
+
+// Wrap Next standalone HTTP server: derive client IP from the TCP socket
+// (unspoofable) and strip client-supplied forwarding headers so downstream
+// rate-limiting keys on the real peer address instead of attacker-controlled XFF.
+http.createServer = (...args) => {
+  const handler = args.find((a) => typeof a === "function");
+  const rest = args.filter((a) => typeof a !== "function");
+  if (!handler) return origCreate(...args);
+  const wrapped = (req, res) => {
+    const socketIp = req.socket && req.socket.remoteAddress ? req.socket.remoteAddress : "";
+    const xff = req.headers["x-forwarded-for"];
+    const xRealIp = req.headers["x-real-ip"];
+    const viaProxy = !!(xff || xRealIp);
+    const isLoopbackProxy =
+      socketIp === "127.0.0.1" || socketIp === "::1" || socketIp === "::ffff:127.0.0.1";
+    // Trust forwarding headers only when the TCP peer is a local reverse proxy.
+    // Direct/public sockets remain keyed by the unspoofable peer address.
+    const proxyIp = xRealIp || (xff ? String(xff).split(",")[0].trim() : "");
+    const ip = isLoopbackProxy && proxyIp ? proxyIp : socketIp;
+    delete req.headers["x-10r-real-ip"];
+    delete req.headers["x-forwarded-for"];
+    delete req.headers["x-10r-via-proxy"];
+    delete req.headers["x-10r-peer-token"];
+    req.headers["x-10r-real-ip"] = ip;
+    req.headers["x-10r-peer-token"] = PEER_TOKEN;
+    if (viaProxy) req.headers["x-10r-via-proxy"] = "1";
+    return handler(req, res);
+  };
+  const server = origCreate(...rest, wrapped);
+  server.once("listening", () => {
+    startBackgroundTokenRefreshFromCustomServer();
+  });
+  const origEmit = server.emit;
+  // JBR 25 sends h2c upgrades that the HTTP/1.1 server would otherwise close.
+  server.emit = function (event, ...eventArgs) {
+    const [req, socket, head] = eventArgs;
+    if (event !== "upgrade" || String(req.headers.upgrade || "").toLowerCase() !== "h2c") {
+      return origEmit.call(this, event, ...eventArgs);
+    }
+
+    const contentLength = Number(req.headers["content-length"] || 0);
+    if (!Number.isSafeInteger(contentLength) || contentLength < 0) {
+      socket.destroy();
+      return true;
+    }
+    const chunks = [head];
+    let received = head.length;
+    const serve = () => {
+      // Replay the upgraded request through the existing HTTP/1.1 handler.
+      const replay = new http.IncomingMessage(socket);
+      Object.assign(replay, {
+        method: req.method,
+        url: req.url,
+        headers: req.headers,
+        complete: true,
+      });
+      if (received) replay.push(Buffer.concat(chunks, received).subarray(0, contentLength));
+      replay.push(null);
+      const res = new http.ServerResponse(replay);
+      res.shouldKeepAlive = false;
+      res.assignSocket(socket);
+      res.once("finish", () => socket.end());
+      Promise.resolve()
+        .then(() => wrapped(replay, res))
+        .catch((error) => {
+          console.error("Failed to downgrade h2c request", error);
+          socket.destroy();
+        });
+    };
+    if (received >= contentLength) serve();
+    else {
+      socket.on("data", function readBody(chunk) {
+        chunks.push(chunk);
+        received += chunk.length;
+        if (received < contentLength) return;
+        socket.off("data", readBody);
+        serve();
+      });
+      socket.resume();
+    }
+    delete req.headers.upgrade;
+    delete req.headers["http2-settings"];
+    req.headers.connection = "close";
+    return true;
+  };
+  return server;
+};
+
+if (require.main === module) {
+  const standalone = path.join(__dirname, "server.js");
+  if (fs.existsSync(standalone)) {
+    require(standalone);
+  } else {
+    // Repo checkout has no standalone build next to us. `next start` builds its HTTP
+    // server in-process, so the wrapper above still sanitizes every request.
+    const nextBin = require.resolve("next/dist/bin/next");
+    process.argv = [process.argv[0], nextBin, "start", ...process.argv.slice(2)];
+    require(nextBin);
+  }
+}

package/next.config.mjs

@@ -0,0 +1,110 @@
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const projectRoot = dirname(fileURLToPath(import.meta.url));
+// CLI bundling needs workspace root so tracing includes hoisted node_modules (slim ~50MB).
+// Docker / default uses projectRoot so server.js lands at /app/server.js (not nested).
+const tracingRoot =
+  process.env.NEXT_TRACING_ROOT_MODE === "workspace" ? join(projectRoot, "..") : projectRoot;
+const proxyClientMaxBodySize = process.env.TENROUTER_PROXY_CLIENT_MAX_BODY_SIZE || "128mb";
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  distDir: process.env.NEXT_DIST_DIR || ".next",
+  output: "standalone",
+  // `open` must stay external. It derives its own directory from `import.meta.url`, and
+  // webpack replaces that with the absolute path of the BUILD machine as a string literal.
+  // A release built on macOS therefore ships `file:///Users/.../open/index.js`, which
+  // `fileURLToPath` rejects on Windows ("File URL path must be absolute" — no drive
+  // letter). That throw happens at module scope, so every consumer of `open` dies on
+  // import — including xAI/Grok token refresh, which loads the OAuth service that imports
+  // it. Keeping it external preserves the real `import.meta.url` at runtime.
+  serverExternalPackages: ["better-sqlite3", "sql.js", "node:sqlite", "bun:sqlite", "open"],
+  turbopack: {
+    root: tracingRoot,
+  },
+  outputFileTracingRoot: tracingRoot,
+  outputFileTracingExcludes: {
+    "*": ["./gitbook/**/*"],
+  },
+  images: {
+    unoptimized: true,
+  },
+  // Incremental TS migration: don't fail the build on the growing set of
+  // JS files still being converted (route handlers return non-Response objects,
+  // etc.). `tsc --noEmit` stays the source of truth; tighten once migration landss.
+  typescript: {
+    ignoreBuildErrors: true,
+  },
+  env: {},
+  experimental: {
+    // #1529/#1572: LLM clients can send long context or base64 image payloads through /v1 rewrites.
+    proxyClientMaxBodySize,
+    // Cache fetch responses across HMR refreshes for faster dev reloads.
+    serverComponentsHmrCache: true,
+    // Tree-shake heavy barrel imports to cut compile + bundle size
+    optimizePackageImports: [
+      "@xyflow/react",
+      "@dnd-kit/core",
+      "@dnd-kit/sortable",
+      "material-symbols",
+      "marked",
+    ],
+  },
+  webpack: (config, { isServer }) => {
+    // Ignore fs/path modules in browser bundle
+    if (!isServer) {
+      config.resolve.fallback = {
+        ...config.resolve.fallback,
+        fs: false,
+        path: false,
+      };
+    }
+    // Exclude non-source dirs from watcher to reduce inotify load
+    config.watchOptions = {
+      ...config.watchOptions,
+      aggregateTimeout: 300,
+      ignored:
+        /[\\/](node_modules|\.git|logs|\.next|\.next-cli-build|gitbook|open-sse\.old|tests|docs)[\\/]/,
+    };
+    return config;
+  },
+  async rewrites() {
+    return [
+      {
+        source: "/v1/v1/:path*",
+        destination: "/api/v1/:path*",
+      },
+      {
+        source: "/v1/v1",
+        destination: "/api/v1",
+      },
+      {
+        source: "/codex/:path*",
+        destination: "/api/v1/responses",
+      },
+      {
+        source: "/responses",
+        destination: "/api/v1/responses",
+      },
+      {
+        source: "/v1beta/:path*",
+        destination: "/api/v1beta/:path*",
+      },
+      {
+        source: "/v1beta",
+        destination: "/api/v1beta",
+      },
+      {
+        source: "/v1/:path*",
+        destination: "/api/v1/:path*",
+      },
+      {
+        source: "/v1",
+        destination: "/api/v1",
+      },
+    ];
+  },
+};
+
+export default nextConfig;

package/open-sse/AGENTS.md

@@ -0,0 +1,39 @@
+# open-sse
+
+Provider-agnostic SSE engine: one OpenAI-style request → any provider (chat, image, embedding, tts, stt, video, search), streamed back in the client's format.
+
+## Request lifecycle (chat)
+
+`handlers/chatCore.js` → `services/model.js` `parseModel` (resolve `provider/model`) + `services/provider.js` (`detectFormat`, `getTargetFormat`, `resolveTransport`) → **pre-translate hooks** (tool dedupe, `rtk/` compress, `headroom`, `pxpipe`, `caveman`/`ponytail` inject, image prefetch, modality strip — all fail-open) → `executors/index.js` `getExecutor(provider)` → `translator/index.js` `translateRequest` → `executor.execute()` → `translateResponse` → `handlers/chatCore/{streaming,nonStreaming,sseToJson}Handler.js` → SSE out.
+
+## Directory map
+
+- `config/` — ALL constants (no hardcode elsewhere). `providers.js` + `registry/` (provider defs), `providerModels.js` (alias→models matrix), `runtimeConfig.js` (timeouts, token limits), per-area files (`grokCli.js`, `mediaConfig.js`, `ttsModels.js`, `ollamaModels.js`…).
+- `translator/` — format conversion. `request/` (7 files) + `response/` (6 files), `schema/` (roles, blocks, finishReasons), `concerns/` (thinking, toolCall, modality, prefetch…), `formats/` (openai, claude, gemini, responsesApi, maxTokens). `index.js` is the registry/entry.
+- `executors/` — per-provider upstream call. `base.js` (BaseExecutor) + specialized: `antigravity`, `codex`, `cursor`, `opencode` (+`go`, +`zen`), `xiaomi-mimo`, `xiaomi-tokenplan`, `zed`. Everything else falls back to `default.js` (OpenAI-compatible).
+- `providers/` — registry build + `capabilities.js` + `pricing.js` + `thinkingLevels.js` + `visionPatterns.js` + `models/`. Entry: `index.js` (PROVIDERS).
+- `handlers/` — per-modality cores (`chatCore`, `imageGenerationCore`, `embeddingsCore`, `ttsCore`, `sttCore`, `videoCore`, `responsesHandler`, `systemoneCore`) + per-provider subfolders. `chatCore/` splits streaming / non-streaming / sse-to-json / requestDetail.
+- `rtk/` — token savers, all **fail-open**. `index.js` (`tool_result` compress), `headroom.js` (external proxy), `pxpipe.js`, `caveman.js` + `ponytail.js` (system inject), `filters/` + `registry.js` + `applyFilter.js`.
+- `transformer/` — `responsesTransformer.js` (Chat SSE → Codex Responses SSE), `streamToJsonConverter.js`.
+- `shared/` — cross-provider auth: `machineId.js`, `mimoAccount.js`, `zedAuth.js`, `qoder/`.
+- `services/` — `model.js`, `provider.js`, `accountFallback.js`, `combo.js`, `compact.js`, `oauthCredentialManager.js`, `tokenRefresh/`+`tokenRefresh.js`, `projectId.js`, `usage/`, per-provider model files (`cursorModels`, `copilotModels`, `grokCliModels`, `kimchiModels`, `qoderModels`), `thoughtSignatureStore.js`, `capacityAdapter.js`.
+- `utils/` — `streamHandler`, `stream`, `sse`, `error`, `sessionManager`, `clientDetector`, `proxyFetch`, `toolDeduper`, `bypassHandler`, `requestLogger`, `usageTracking`, `cursorProtobuf`/`cursorChecksum`, `claudeCloaking`, `ollamaTransform`, `modelMarkers`.
+
+## Conventions
+
+- Config-driven, DRY, camelCase. NEVER hardcode values, models, or block/role strings — use `config/` + `schema/` constants.
+- Pipeline pivots through OpenAI. A translator on the exact `source:target` pair runs as a **direct route**, skipping the lossy double-hop.
+- Translators self-register via `register(from, to, reqFn, resFn)` as an import side-effect — new files MUST be imported in `translator/index.js`.
+
+## How to add
+
+- **Provider**: copy `providers/REGISTRY_TEMPLATE.js` → `providers/registry/{id}.js`; add models to `config/providerModels.js`. No executor needed for OpenAI-compatible APIs.
+- **Executor** (only non-standard upstream): subclass `BaseExecutor` (override `getBaseUrls`/`buildHeaders`/`buildUrl`/`execute`), register in `executors/index.js` map. `getExecutor` falls back to cached `DefaultExecutor` when absent.
+- **Translator**: add `request|response/<from>-to-<to>.js` calling `register(...)`, import it in `translator/index.js`. Reuse `schema/` + `concerns/` — don't re-implement parsing.
+
+## Pitfalls
+
+- OpenAI bridge is lossy (thinking, non-base64 images, tool ids, is_error) — prefer a direct route for fragile pairs.
+- `providers/registry/index.js` is auto-generated; regenerate via `scripts/migrate-registry.mjs` (don't hand-edit). REGISTRY_TEMPLATE is excluded by design.
+- Binary/protobuf formats (kiro EventStream, cursor protobuf, commandcode NDJSON) don't round-trip through OpenAI — handle in their executor.
+- `rtk/` hooks mutate the body in-place and are **fail-open**: never throw; RTK skips `is_error`/`status:"error"` tool results to preserve traces.