@ar-ai/brink-cli 0.0.0-stage → 1.0.4

package/support/client-setup.js

@@ -0,0 +1,620 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const { constants } = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { createHash, randomBytes } = require('node:crypto');
+const { adaptModelCatalog } = require('./model-catalog');
+
+const RELEASES = 'https://downloads.claude.ai/claude-code-releases';
+const MIN_CLAUDE = [2, 1, 242];
+const own = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const notify = (callback, label, detail) => callback?.({ label, detail });
+const homes = options => ({
+  codex: path.resolve(options.codexHome || process.env.CODEX_HOME || path.join(os.homedir(), '.codex')),
+  claude: path.resolve(options.claudeHome || process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude')),
+});
+
+function checkClient(client) {
+  if (client !== 'claude' && client !== 'codex') throw new Error('Choose Claude Code or Codex.');
+}
+
+function abortError() {
+  const error = new Error('Client installation cancelled.');
+  error.name = 'AbortError';
+  return error;
+}
+
+function checkAbort(signal) {
+  if (signal?.aborted) throw abortError();
+}
+
+async function accessible(filename) {
+  try {
+    await fs.access(filename, process.platform === 'win32' ? constants.F_OK : constants.X_OK);
+    return (await fs.stat(filename)).isFile();
+  } catch { return false; }
+}
+
+function searchDirectories() {
+  return [...new Set([
+    ...(process.env.PATH || '').split(path.delimiter).filter(Boolean),
+    path.join(os.homedir(), '.local', 'bin'),
+    path.join(os.homedir(), '.local'),
+    path.join(os.homedir(), '.npm-global', 'bin'),
+    path.join(os.homedir(), '.npm-global'),
+    path.dirname(process.execPath),
+    ...(process.env.APPDATA ? [path.join(process.env.APPDATA, 'npm')] : []),
+  ])];
+}
+
+async function findExecutables(name) {
+  const names = process.platform === 'win32' ? [`${name}.exe`, `${name}.cmd`, name] : [name];
+  const found = [];
+  for (const directory of searchDirectories()) {
+    for (const filename of names) {
+      const candidate = path.resolve(directory, filename);
+      if (await accessible(candidate)) found.push(candidate);
+    }
+  }
+  return [...new Set(found)];
+}
+
+// Windows npm shims need cmd.exe, which treats arguments as shell text. Resolve
+// only the known npm entrypoints instead, and pass every argument directly to Node.
+async function invocation(executable, args) {
+  if (process.platform !== 'win32' || !/\.(?:cmd|bat)$/i.test(executable)) {
+    return { executable, args };
+  }
+  const name = path.basename(executable).replace(/\.(?:cmd|bat)$/i, '').toLowerCase();
+  const entry = {
+    npm: ['npm', 'bin', 'npm-cli.js'],
+    codex: ['@openai', 'codex', 'bin', 'codex.js'],
+    claude: ['@anthropic-ai', 'claude-code', 'cli.js'],
+  }[name];
+  if (entry) {
+    const directory = path.dirname(executable);
+    for (const modules of [path.join(directory, 'node_modules'), path.join(directory, '..', 'lib', 'node_modules')]) {
+      const script = path.join(modules, ...entry);
+      try {
+        if ((await fs.stat(script)).isFile()) return { executable: process.execPath, args: [script, ...args] };
+      } catch { /* Try the next standard npm layout. */ }
+    }
+  }
+  throw new Error(`Cannot safely run ${name}'s Windows shim. Reinstall its official native or npm package.`);
+}
+
+async function run(executable, args, { signal, timeout = 30000, env = process.env } = {}) {
+  checkAbort(signal);
+  const command = await invocation(executable, args);
+  return new Promise((resolve, reject) => {
+    let output = '';
+    let timedOut = false;
+    let killTimer;
+    const child = spawn(command.executable, command.args, {
+      env, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], shell: false,
+    });
+    const stop = () => {
+      child.kill('SIGTERM');
+      killTimer = setTimeout(() => child.kill('SIGKILL'), 3000);
+      killTimer.unref();
+    };
+    const timer = setTimeout(() => { timedOut = true; stop(); }, timeout);
+    timer.unref();
+    signal?.addEventListener('abort', stop, { once: true });
+    if (signal?.aborted) stop();
+    const collect = chunk => { if (output.length < 8192) output += chunk.toString().slice(0, 8192 - output.length); };
+    child.stdout.on('data', collect);
+    child.stderr.on('data', collect);
+    const cleanup = () => {
+      clearTimeout(timer);
+      clearTimeout(killTimer);
+      signal?.removeEventListener('abort', stop);
+    };
+    child.once('error', error => {
+      cleanup();
+      reject(signal?.aborted ? abortError() : new Error(`Could not start ${path.basename(executable)} (${error.code || 'spawn error'}).`));
+    });
+    child.once('close', code => {
+      cleanup();
+      if (signal?.aborted) reject(abortError());
+      else if (timedOut) reject(new Error(`${path.basename(executable)} timed out. Check your connection and try again.`));
+      else if (code !== 0) reject(new Error(`${path.basename(executable)} exited with code ${code ?? 'signal'}.`));
+      else resolve(output);
+    });
+  });
+}
+
+function clientVersion(client, output) {
+  const match = output.match(client === 'claude' ? /\b(\d+\.\d+\.\d+(?:-[\w.-]+)?)\b/ : /\bcodex(?:-cli)?\s+(\d+\.\d+\.\d+(?:-[\w.-]+)?)\b/i);
+  return match?.[1] || null;
+}
+
+function supportsPicker(version) {
+  const parts = version.split(/[.-]/).slice(0, 3).map(Number);
+  for (let index = 0; index < 3; index++) {
+    if (parts[index] !== MIN_CLAUDE[index]) return parts[index] > MIN_CLAUDE[index];
+  }
+  return true;
+}
+
+async function installedClient(client, signal) {
+  for (const executable of await findExecutables(client)) {
+    try {
+      const version = clientVersion(client, await run(executable, ['--version'], { signal }));
+      if (version) return { executable, version };
+    } catch (error) { if (error.name === 'AbortError') throw error; }
+  }
+  return null;
+}
+
+async function response(url, signal) {
+  checkAbort(signal);
+  const timeout = AbortSignal.timeout(180000);
+  let result;
+  try {
+    result = await fetch(url, {
+      signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+      headers: { 'accept-encoding': 'identity' },
+    });
+  } catch {
+    checkAbort(signal);
+    throw new Error('Could not reach the official Claude download service. Check your network and try brink setup again.');
+  }
+  if (!result.ok || !result.body) {
+    await result.body?.cancel();
+    throw new Error(`Official Claude download failed (HTTP ${result.status}). Check your network or supported region.`);
+  }
+  return result;
+}
+
+async function nativePlatform(signal) {
+  if (!['darwin', 'linux', 'win32'].includes(process.platform) || !['arm64', 'x64'].includes(process.arch)) {
+    throw new Error('Claude Code requires a supported 64-bit Windows, macOS, or Linux machine. See https://code.claude.com/docs/en/setup.');
+  }
+  let arch = process.arch;
+  if (process.platform === 'darwin' && arch === 'x64') {
+    try { if ((await run('/usr/sbin/sysctl', ['-n', 'sysctl.proc_translated'], { signal })).trim() === '1') arch = 'arm64'; }
+    catch (error) { if (error.name === 'AbortError') throw error; }
+  }
+  if (process.platform === 'win32' && /ARM64/i.test(process.env.PROCESSOR_ARCHITEW6432 || process.env.PROCESSOR_ARCHITECTURE || '')) arch = 'arm64';
+  let suffix = '';
+  if (process.platform === 'linux') {
+    const musl = path.join('/lib', arch === 'arm64' ? 'libc.musl-aarch64.so.1' : 'libc.musl-x86_64.so.1');
+    try { await fs.access(musl); suffix = '-musl'; } catch { /* glibc */ }
+  }
+  return `${process.platform}-${arch}${suffix}`;
+}
+
+async function installClaude(onProgress, signal) {
+  const platform = await nativePlatform(signal);
+  notify(onProgress, 'Getting official Claude Code release', platform);
+  const version = (await (await response(`${RELEASES}/latest`, signal)).text()).trim();
+  if (!/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(version)) throw new Error('The official Claude service returned an invalid release version. Try again later.');
+  const manifest = await (await response(`${RELEASES}/${version}/manifest.json`, signal)).json();
+  const release = manifest.platforms?.[platform];
+  if (!release || !/^[a-f0-9]{64}$/i.test(release.checksum)) throw new Error('No verified official Claude download is available for this platform.');
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'brink-claude-'));
+  const filename = path.join(directory, process.platform === 'win32' ? 'claude.exe' : 'claude');
+  try {
+    const download = await response(`${RELEASES}/${version}/${platform}/${path.basename(filename)}`, signal);
+    const declared = Number(download.headers.get('content-length'));
+    const expected = Number.isSafeInteger(release.size) && release.size > 0 ? release.size : 0;
+    const total = Number.isSafeInteger(declared) && declared > 0 ? declared : expected;
+    const hash = createHash('sha256');
+    const handle = await fs.open(filename, 'wx', 0o600);
+    let bytes = 0;
+    let lastUpdate = 0;
+    const progress = () => {
+      const detail = `${(bytes / 1048576).toFixed(1)} MiB${total ? ` / ${(total / 1048576).toFixed(1)} MiB` : ' downloaded'}`;
+      onProgress?.({ label: 'Downloading Claude Code', detail, ...(total ? { percent: Math.min(100, bytes * 100 / total) } : {}) });
+    };
+    try {
+      progress();
+      for await (const chunk of download.body) {
+        checkAbort(signal);
+        await handle.writeFile(chunk);
+        hash.update(chunk);
+        bytes += chunk.length;
+        if (Date.now() - lastUpdate >= 100) { progress(); lastUpdate = Date.now(); }
+      }
+      progress();
+    } finally { await handle.close(); }
+    if ((expected && bytes !== expected) || hash.digest('hex') !== release.checksum.toLowerCase()) {
+      throw new Error('Claude Code download checksum or size did not match. Nothing was installed; try again.');
+    }
+    await fs.chmod(filename, 0o700);
+    notify(onProgress, 'Installing Claude Code', 'Official native installer; waiting for completion');
+    await run(filename, ['install', version], { signal, timeout: 600000 });
+    const executable = path.join(os.homedir(), '.local', 'bin', process.platform === 'win32' ? 'claude.exe' : 'claude');
+    if (await accessible(executable)) {
+      const installedVersion = clientVersion('claude', await run(executable, ['--version'], { signal }));
+      if (installedVersion && supportsPicker(installedVersion)) return { executable, version: installedVersion };
+    }
+    const found = await installedClient('claude', signal);
+    if (!found || !supportsPicker(found.version)) throw new Error('Claude installation finished, but the new command was not found. Add ~/.local/bin to PATH and run brink setup again.');
+    return found;
+  } finally { await fs.rm(directory, { recursive: true, force: true }); }
+}
+
+async function installCodex(onProgress, signal) {
+  const npms = await findExecutables('npm');
+  let npm;
+  for (const candidate of npms) {
+    try { await run(candidate, ['--version'], { signal }); npm = candidate; break; }
+    catch (error) { if (error.name === 'AbortError') throw error; }
+  }
+  if (!npm) throw new Error('Codex needs Node.js with npm. Install Node.js LTS from https://nodejs.org, reopen your terminal, and run brink setup again. No sudo is needed.');
+  const prefix = path.join(os.homedir(), '.local');
+  notify(onProgress, 'Installing Codex', 'Downloading and installing @openai/codex in your user folder; npm does not report a reliable total');
+  try {
+    await run(npm, ['install', '--global', '--prefix', prefix, '--no-audit', '--no-fund', '--loglevel=error', '@openai/codex@latest'], {
+      signal, timeout: 600000,
+      env: { ...process.env, PATH: [path.dirname(process.execPath), process.env.PATH || ''].join(path.delimiter) },
+    });
+  } catch (error) {
+    if (error.name === 'AbortError') throw error;
+    throw new Error(`${error.message} Codex was not configured. Check npm registry access and write permission to ${prefix}, then run brink setup again.`);
+  }
+  const executable = path.join(prefix, process.platform === 'win32' ? 'codex.cmd' : 'bin/codex');
+  const version = clientVersion('codex', await run(executable, ['--version'], { signal }));
+  if (!version) throw new Error('The Codex package installed but its version could not be read. Reopen your terminal and run brink setup again.');
+  return { executable, version };
+}
+
+async function ensureClient(client, { onProgress, signal } = {}) {
+  checkClient(client);
+  checkAbort(signal);
+  const name = client === 'claude' ? 'Claude Code' : 'Codex';
+  const existing = await installedClient(client, signal);
+  if (existing && (client !== 'claude' || supportsPicker(existing.version))) {
+    notify(onProgress, `${name} ready`, existing.version);
+    return existing;
+  }
+  notify(onProgress, existing ? 'Updating Claude Code for the full model picker' : `${name} unavailable; installing`, existing ? 'Model picker requires Claude Code 2.1.242 or later' : 'User installation; no administrator access needed');
+  try {
+    const installed = client === 'claude' ? await installClaude(onProgress, signal) : await installCodex(onProgress, signal);
+    notify(onProgress, `${name} installed`, installed.version);
+    return installed;
+  } catch (error) {
+    if (error.name !== 'AbortError') notify(onProgress, `${name} installation failed`, error.message);
+    throw error;
+  }
+}
+
+async function readOptional(filename) {
+  try { return await fs.readFile(filename, 'utf8'); }
+  catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw new Error(`Cannot read ${filename} (${error.code || 'file error'}). Existing configuration was not changed.`);
+  }
+}
+
+function parseSettings(text, filename) {
+  if (text === null) return {};
+  try {
+    const settings = JSON.parse(text.replace(/^\uFEFF/, ''));
+    if (!record(settings) || (own(settings, 'env') && !record(settings.env))) throw new Error();
+    return settings;
+  } catch { throw new Error(`Invalid JSON settings in ${filename}. Fix this file first; it was not changed.`); }
+}
+
+let tomlParser;
+function parseToml(text, filename) {
+  if (!tomlParser) {
+    try { tomlParser = require('toml-eslint-parser'); }
+    catch { throw new Error('Brink needs its TOML parser. Reinstall Brink, or run npm install in the Brink installation folder.'); }
+  }
+  try { return tomlParser.parseTOML(text, { tomlVersion: '1.0' }); }
+  catch { throw new Error(`Invalid TOML in ${filename}. Fix this file first; it was not changed.`); }
+}
+
+const keyParts = key => key.keys.map(part => part.type === 'TOMLBare' ? part.name : part.value);
+const startsWith = (parts, prefix) => parts.length >= prefix.length && prefix.every((part, index) => part === parts[index]);
+const samePath = (left, right) => left.length === right.length && startsWith(left, right);
+const tomlKey = parts => parts.map(part => /^[A-Za-z0-9_-]+$/.test(part) ? part : JSON.stringify(part)).join('.');
+const tomlValue = value => typeof value === 'string' ? JSON.stringify(value).replace(/\u007f/gi, '\\u007f') : String(value);
+
+function tomlEntries(ast) {
+  const entries = [];
+  const walk = (body, prefix) => {
+    for (const node of body) {
+      if (node.type === 'TOMLTable') {
+        if (node.kind === 'standard') walk(node.body, node.resolvedKey);
+      } else {
+        const parts = [...prefix, ...keyParts(node.key)];
+        entries.push({ node, parts });
+        if (node.value.type === 'TOMLInlineTable') walk(node.value.body, parts);
+      }
+    }
+  };
+  walk(ast.body[0].body, []);
+  return entries;
+}
+
+function headerEnd(ast, table) {
+  const closing = ast.tokens.find(token => token.range[0] >= table.key.range[1] && token.value === ']');
+  if (!closing) throw new Error('Cannot locate the TOML table header safely. Configuration was not changed.');
+  return closing.range[1];
+}
+
+// Mutate value spans, not lines: quoted/dotted keys and multiline strings keep
+// their surrounding comments, whitespace, and all unrelated provider tables.
+function setToml(text, parts, value, filename) {
+  const ast = parseToml(text, filename);
+  const entries = tomlEntries(ast);
+  const existing = entries.find(entry => samePath(entry.parts, parts));
+  const literal = tomlValue(value);
+  if (existing) {
+    const [start, end] = existing.node.value.range;
+    return text.slice(0, start) + literal + text.slice(end);
+  }
+  const inline = entries.filter(entry => entry.node.value.type === 'TOMLInlineTable' && startsWith(parts, entry.parts)).sort((a, b) => b.parts.length - a.parts.length)[0];
+  if (inline) {
+    const node = inline.node.value;
+    const offset = node.range[1] - 1;
+    return text.slice(0, offset) + `${node.body.length ? ',' : ''} ${tomlKey(parts.slice(inline.parts.length))} = ${literal} ` + text.slice(offset);
+  }
+  const newline = text.includes('\r\n') ? '\r\n' : '\n';
+  const tables = ast.body[0].body.filter(node => node.type === 'TOMLTable');
+  const table = tables.filter(node => node.kind === 'standard' && startsWith(parts, node.resolvedKey)).sort((a, b) => b.resolvedKey.length - a.resolvedKey.length)[0];
+  if (table) {
+    const end = headerEnd(ast, table);
+    const lineEnd = text.indexOf('\n', end);
+    const offset = lineEnd === -1 ? text.length : lineEnd + 1;
+    return text.slice(0, offset) + (lineEnd === -1 ? newline : '') + `${tomlKey(parts.slice(table.resolvedKey.length))} = ${literal}${newline}` + text.slice(offset);
+  }
+  const offset = tables[0]?.range[0] ?? text.length;
+  return text.slice(0, offset) + (offset && text[offset - 1] !== '\n' ? newline : '') + `${tomlKey(parts)} = ${literal}${newline}` + text.slice(offset);
+}
+
+function removeToml(text, parts, filename) {
+  const ast = parseToml(text, filename);
+  const entries = tomlEntries(ast);
+  const match = entries.find(entry => samePath(entry.parts, parts));
+  const spans = [];
+  if (match) {
+    const node = match.node;
+    let [start, end] = node.range;
+    if (node.parent.type === 'TOMLInlineTable') {
+      const siblings = node.parent.body;
+      const index = siblings.indexOf(node);
+      if (index < siblings.length - 1) end = siblings[index + 1].range[0];
+      else if (index > 0) start = siblings[index - 1].range[1];
+    }
+    spans.push([start, end]);
+  } else {
+    for (const entry of entries) {
+      if (startsWith(entry.parts, parts) && entry.node.parent.type !== 'TOMLInlineTable') spans.push(entry.node.range);
+    }
+    for (const table of ast.body[0].body) {
+      if (table.type === 'TOMLTable' && startsWith(table.resolvedKey, parts)) spans.push([table.range[0], headerEnd(ast, table)]);
+    }
+  }
+  for (const [start, end] of spans.sort((a, b) => b[0] - a[0])) text = text.slice(0, start) + text.slice(end);
+  return text;
+}
+
+async function atomicWrite(filename, content, expected) {
+  await fs.mkdir(path.dirname(filename), { recursive: true, mode: 0o700 });
+  try {
+    const stat = await fs.lstat(filename);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`Refusing to replace non-regular configuration ${filename}.`);
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const temporary = `${filename}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+  let handle;
+  try {
+    handle = await fs.open(temporary, 'wx', 0o600);
+    await handle.writeFile(content, 'utf8');
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    if (expected !== undefined && await readOptional(filename) !== expected) throw new Error(`Configuration changed during setup: ${filename}. Run brink setup again; the other edit was preserved.`);
+    await fs.rename(temporary, filename);
+  } finally {
+    await handle?.close();
+    await fs.rm(temporary, { force: true });
+  }
+}
+
+function validateSelection({ apiKey, model, modelIds, port }) {
+  if (typeof apiKey !== 'string' || !apiKey.trim() || /[\x00-\x20\x7f]/.test(apiKey)) throw new Error('Enter a non-empty AgentRouter API key without whitespace.');
+  if (typeof model !== 'string' || !model || model.trim() !== model || /[\x00-\x1f\x7f]/.test(model)) throw new Error('Choose an exact model ID from the AgentRouter catalog.');
+  if (!Array.isArray(modelIds) || modelIds.some(id => typeof id !== 'string' || !id || id.trim() !== id || /[\x00-\x1f\x7f]/.test(id))) throw new Error('AgentRouter model IDs must be non-empty exact strings.');
+  if (!modelIds.includes(model)) throw new Error('The selected model is not in the supplied AgentRouter catalog.');
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('Choose a local port between 1 and 65535.');
+  return [...new Set(modelIds)];
+}
+
+async function configureClient(client, options = {}) {
+  checkClient(client);
+  const { apiKey, model, modelIds = [], port = 8787, onProgress } = options;
+  const ids = validateSelection({ apiKey, model, modelIds, port });
+  const directories = homes(options);
+  if (client === 'claude') {
+    const configPath = path.join(directories.claude, 'settings.json');
+    const previous = await readOptional(configPath);
+    const settings = parseSettings(previous, configPath);
+    settings.env = {
+      ...settings.env,
+      ANTHROPIC_BASE_URL: `http://127.0.0.1:${port}`,
+      ANTHROPIC_AUTH_TOKEN: apiKey,
+      // A blank setting overrides an inherited API key; deletion would restore it.
+      ANTHROPIC_API_KEY: '',
+      BRINK_GATEWAY_PROVIDER: 'agentrouter',
+      CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: '1',
+      CLAUDE_CODE_MAX_RETRIES: '0',
+      CLAUDE_CODE_RETRY_WATCHDOG: '0',
+      CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK: '1',
+    };
+    delete settings.env.ANTHROPIC_MODEL;
+    for (const flag of ['CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY', 'CLAUDE_CODE_USE_ANTHROPIC_AWS']) settings.env[flag] = '';
+    settings.model = model;
+    settings.fallbackModel = [];
+    settings.modelPicker = {
+      ...(record(settings.modelPicker) ? settings.modelPicker : {}),
+      options: ids.map(id => ({ model: id, label: id })),
+      replaceBuiltInOptions: true,
+    };
+    if (Array.isArray(settings.availableModels))
+      settings.availableModels = [...new Set([...settings.availableModels, ...ids])];
+    await atomicWrite(configPath, `${JSON.stringify(settings, null, 2)}\n`, previous);
+    notify(onProgress, 'Claude Code configured', `Messages API at http://127.0.0.1:${port}; gateway token saved privately`);
+    notify(onProgress, 'Claude model compatibility', 'All supplied IDs are configured for /model. GPT requests use the Responses bridge; other models require gateway Messages support. Managed restrictions can still apply.');
+    return { configPath };
+  }
+  const configPath = path.join(directories.codex, 'config.toml');
+  const previous = await readOptional(configPath);
+  let text = previous ?? '';
+  parseToml(text, configPath);
+  const catalog = `${JSON.stringify(adaptModelCatalog({ data: ids.map(id => ({ id })) }), null, 2)}\n`;
+  const digest = createHash('sha256').update(catalog).digest('hex').slice(0, 16);
+  const catalogPath = path.join(directories.codex, `brink-models-${digest}.json`);
+  const provider = ['model_providers', 'brink'];
+  // Brink owns this provider. Saved OAuth and unrelated providers stay intact;
+  // a recognized legacy AgentRouter credential is rotated below as requested.
+  for (const field of ['env_key', 'env_key_instructions', 'auth', 'http_headers', 'env_http_headers', 'query_params']) text = removeToml(text, [...provider, field], configPath);
+  for (const [field, value] of Object.entries({
+    name: 'Brink / AgentRouter',
+    base_url: `http://127.0.0.1:${port}/v1`,
+    wire_api: 'responses',
+    experimental_bearer_token: apiKey,
+    requires_openai_auth: false,
+    request_max_retries: 0,
+    stream_max_retries: 0,
+    supports_websockets: false,
+  })) text = setToml(text, [...provider, field], value, configPath);
+  for (const [field, value] of Object.entries({ model, model_provider: 'brink', model_catalog_json: catalogPath })) text = setToml(text, [field], value, configPath);
+  const legacyEntries = tomlEntries(parseToml(text, configPath));
+  const legacyBase = legacyEntries.find(entry => samePath(entry.parts, ['model_providers', 'agentrouter', 'base_url']))?.node.value.value;
+  if (agentRouterUrl(legacyBase, true)) {
+    text = setToml(text, ['model_providers', 'agentrouter', 'experimental_bearer_token'], apiKey, configPath);
+    for (const field of ['env_key', 'env_key_instructions', 'auth']) text = removeToml(text, ['model_providers', 'agentrouter', field], configPath);
+  }
+  parseToml(text, configPath);
+  // Content-addressed catalogs leave the previous working catalog untouched if
+  // saving config fails, and never overwrite a user's unrelated catalog file.
+  await atomicWrite(catalogPath, catalog);
+  await atomicWrite(configPath, text, previous);
+  notify(onProgress, 'Codex configured', `Responses API at http://127.0.0.1:${port}/v1; gateway token saved privately`);
+  const hasProfile = tomlEntries(parseToml(text, configPath)).some(entry => samePath(entry.parts, ['profile']));
+  if (hasProfile) notify(onProgress, 'Existing Codex profile preserved', 'A selected profile can override your model or provider; launch without that profile to use Brink.');
+  return { configPath, catalogPath };
+}
+
+function agentRouterUrl(value, namedProvider = false) {
+  if (typeof value !== 'string') return false;
+  try {
+    const url = new URL(value);
+    if (url.protocol === 'https:' && ['agentrouter.org', 'api.agentrouter.org', 'agentrouter.us', 'api.agentrouter.us'].includes(url.hostname)) return true;
+    return namedProvider && ['http:', 'https:'].includes(url.protocol) && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname);
+  } catch { return false; }
+}
+
+async function existingKey(options = {}) {
+  const directories = homes(options);
+  const configPath = path.join(directories.codex, 'config.toml');
+  const text = await readOptional(configPath);
+  if (text !== null) {
+    const entries = tomlEntries(parseToml(text, configPath));
+    const value = parts => entries.find(entry => samePath(entry.parts, parts))?.node.value.value;
+    const names = [...new Set(['brink', 'agentrouter', ...entries.filter(entry => entry.parts[0] === 'model_providers').map(entry => entry.parts[1])])];
+    for (const name of names) {
+      const prefix = ['model_providers', name];
+      if (!agentRouterUrl(value([...prefix, 'base_url']), name === 'brink' || name === 'agentrouter')) continue;
+      const direct = value([...prefix, 'experimental_bearer_token']);
+      if (typeof direct === 'string' && direct.trim()) return direct;
+      const envKey = value([...prefix, 'env_key']);
+      if (typeof envKey === 'string' && typeof process.env[envKey] === 'string' && process.env[envKey].trim()) return process.env[envKey];
+    }
+  }
+  const settingsPath = path.join(directories.claude, 'settings.json');
+  const settings = parseSettings(await readOptional(settingsPath), settingsPath);
+  const env = settings.env || {};
+  // A localhost Claude endpoint alone is not proof that its secret belongs to
+  // AgentRouter. Only recognize Brink's own saved setup for local endpoints.
+  const localBrink = env.BRINK_GATEWAY_PROVIDER === 'agentrouter';
+  if (agentRouterUrl(env.ANTHROPIC_BASE_URL, localBrink)) {
+    for (const field of ['ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY']) {
+      if (typeof env[field] === 'string' && env[field].trim()) return env[field];
+    }
+  }
+  return null;
+}
+
+async function checkClientConfig(client, options = {}) {
+  checkClient(client);
+  const directories = homes(options);
+  const { apiKey, model, modelIds = [], port = 8787 } = options;
+  const ids = validateSelection({ apiKey, model, modelIds, port });
+  const issues = [];
+  let selected = model;
+  let configPath;
+  let catalogPath;
+  if (client === 'claude') {
+    configPath = path.join(directories.claude, 'settings.json');
+    const settings = parseSettings(await readOptional(configPath), configPath);
+    if (ids.includes(settings.model)) selected = settings.model;
+    else issues.push('Default model is missing or no longer in the supplied catalog.');
+    const env = settings.env || {};
+    const required = {
+      ANTHROPIC_BASE_URL: `http://127.0.0.1:${port}`,
+      ANTHROPIC_AUTH_TOKEN: apiKey,
+      ANTHROPIC_API_KEY: '',
+      BRINK_GATEWAY_PROVIDER: 'agentrouter',
+      CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: '1',
+      CLAUDE_CODE_MAX_RETRIES: '0',
+      CLAUDE_CODE_RETRY_WATCHDOG: '0',
+      CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK: '1',
+    };
+    if (Object.entries(required).some(([key, value]) => env[key] !== value)) issues.push('Gateway address, credential, or retry settings need repair.');
+    if (own(env, 'ANTHROPIC_MODEL')) issues.push('An obsolete model environment override is present.');
+    if (['CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY', 'CLAUDE_CODE_USE_ANTHROPIC_AWS'].some(key => env[key] || process.env[key] && env[key] !== '')) issues.push('A conflicting cloud-provider override is present.');
+    const pickerIds = Array.isArray(settings.modelPicker?.options) ? settings.modelPicker.options.map(entry => entry?.model) : null;
+    if (settings.modelPicker?.replaceBuiltInOptions !== true || JSON.stringify(pickerIds) !== JSON.stringify(ids)) issues.push('The model picker needs the current exact model IDs.');
+    if (Array.isArray(settings.availableModels) && ids.some(id => !settings.availableModels.includes(id))) issues.push('The local model allowlist hides catalog models.');
+    if (!Array.isArray(settings.fallbackModel) || settings.fallbackModel.length) issues.push('Automatic model fallback needs disabling.');
+  } else {
+    configPath = path.join(directories.codex, 'config.toml');
+    const entries = tomlEntries(parseToml(await readOptional(configPath) ?? '', configPath));
+    const value = parts => entries.find(entry => samePath(entry.parts, parts))?.node.value.value;
+    if (ids.includes(value(['model']))) selected = value(['model']);
+    else issues.push('Default model is missing or no longer in the supplied catalog.');
+    const required = {
+      base_url: `http://127.0.0.1:${port}/v1`,
+      wire_api: 'responses',
+      experimental_bearer_token: apiKey,
+      requires_openai_auth: false,
+      request_max_retries: 0,
+      stream_max_retries: 0,
+      supports_websockets: false,
+    };
+    if (value(['model_provider']) !== 'brink' || Object.entries(required).some(([key, expected]) => value(['model_providers', 'brink', key]) !== expected)) issues.push('Gateway address, credential, provider, or retry settings need repair.');
+    if (entries.some(entry => startsWith(entry.parts, ['model_providers', 'brink']) && ['env_key', 'env_key_instructions', 'auth', 'http_headers', 'env_http_headers', 'query_params'].includes(entry.parts[2]))) issues.push('Conflicting Brink provider authentication or request overrides are present.');
+    const legacy = ['model_providers', 'agentrouter'];
+    if (agentRouterUrl(value([...legacy, 'base_url']), true) && (value([...legacy, 'experimental_bearer_token']) !== apiKey || entries.some(entry => startsWith(entry.parts, legacy) && ['env_key', 'env_key_instructions', 'auth'].includes(entry.parts[2])))) issues.push('The older AgentRouter provider credential needs rotation.');
+    catalogPath = value(['model_catalog_json']);
+    if (typeof catalogPath !== 'string' || !path.isAbsolute(catalogPath)) issues.push('A Brink model catalog must be configured.');
+    else {
+      try {
+        const catalog = JSON.parse(await readOptional(catalogPath) ?? 'null');
+        const slugs = catalog?.models?.map(entry => entry.slug);
+        if (!Array.isArray(slugs) || JSON.stringify([...slugs].sort()) !== JSON.stringify([...ids].sort())) issues.push('The model catalog is missing or stale.');
+      } catch { issues.push('The model catalog is unreadable or invalid.'); }
+    }
+  }
+  return { needsRepair: issues.length > 0, model: selected, issues, configPath, ...(catalogPath ? { catalogPath } : {}) };
+}
+
+async function repairClient(client, options = {}) {
+  const check = await checkClientConfig(client, options);
+  if (!check.needsRepair) return { configPath: check.configPath, ...(check.catalogPath ? { catalogPath: check.catalogPath } : {}), model: check.model };
+  notify(options.onProgress, `Repairing ${client === 'claude' ? 'Claude Code' : 'Codex'} configuration`, check.issues.join(' '));
+  const configured = await configureClient(client, { ...options, model: check.model });
+  return { ...configured, model: check.model };
+}
+
+module.exports = { ensureClient, configureClient, existingKey, checkClientConfig, repairClient };