npm - @bitkyc08/opencodex - Versions diffs - 2.7.28 → 2.7.29 - Mend

@bitkyc08/opencodex 2.7.28 → 2.7.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/README.ko.md +1 -0
package/README.md +1 -0
package/README.zh-CN.md +1 -0
package/bin/ocx.mjs +41 -3
package/gui/dist/assets/{index-TZysP4q4.js → index-CMKZnkG9.js} +5 -5
package/gui/dist/index.html +1 -1
package/package.json +1 -1
package/src/cli/account-api.ts +266 -0
package/src/cli/account-extended.ts +282 -0
package/src/cli/account.ts +265 -0
package/src/cli/claude.ts +3 -1
package/src/cli/help.ts +15 -0
package/src/cli/index.ts +58 -17
package/src/cli/init.ts +11 -1
package/src/lib/winsw.ts +14 -3
package/src/oauth/login-cli.ts +15 -4
package/src/providers/registry.ts +21 -1
package/src/server/index.ts +5 -0
package/src/server/ports.ts +20 -0
package/src/server/request-log.ts +98 -0
package/src/service.ts +24 -4
package/src/update/index.ts +35 -8
package/src/update/job.ts +34 -7
package/src/usage/log.ts +98 -1

package/gui/dist/index.html CHANGED Viewed

@@ -16,7 +16,7 @@
         } catch (e) {}
       })();
     </script>
-    <script type="module" crossorigin src="/assets/index-TZysP4q4.js"></script>
+    <script type="module" crossorigin src="/assets/index-CMKZnkG9.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-DyBPh28A.css">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@bitkyc08/opencodex",
-  "version": "2.7.28",
+  "version": "2.7.29",
   "description": "Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code",
   "type": "module",
   "main": "./bin/package-main.mjs",

package/src/cli/account-api.ts ADDED Viewed

@@ -0,0 +1,266 @@
+/**
+ * Data-access layer for `ocx account` (issue #180) — live-proxy HTTP client and
+ * per-family account readers. Kept separate from account.ts (command handlers)
+ * per the 400-line module budget.
+ */
+import { findLiveProxy, probeHostname } from "../server/proxy-liveness";
+import { runningProxyUpdateHeaders } from "../oauth/login-cli";
+import { isPublicOAuthProvider } from "../oauth/index";
+import { getProviderRegistryEntry, providerCodexAccountMode } from "../providers/registry";
+import type { OcxConfig } from "../types";
+export type AccountType = "codex" | "oauth" | "api-key";
+export interface AccountRow {
+  provider: string;
+  type: AccountType;
+  id: string;
+  label?: string;
+  email?: string;
+  plan?: string;
+  masked?: string;
+  active: boolean;
+  needsReauth?: boolean;
+  quota?: CodexQuotaDto | null;
+}
+export type ClassifyResult = { type: AccountType } | { error: string };
+export type AccountStdin = NodeJS.ReadableStream & { isTTY?: boolean };
+export interface AccountDeps {
+  /** Test injection: skip findLiveProxy and call the API at this base URL. */
+  baseUrl?: string;
+  fetchImpl?: typeof fetch;
+  loadConfigImpl?: () => OcxConfig;
+  stdinImpl?: AccountStdin;
+  stdinTimeoutMs?: number;
+}
+export function classifyAccount(config: OcxConfig, name: string): ClassifyResult {
+  const provider = config.providers?.[name];
+  if (providerCodexAccountMode(name, provider)) return { type: "codex" };
+  const entry = getProviderRegistryEntry(name);
+  if (entry?.authKind === "local") {
+    return { error: `provider "${name}" is a local provider and has no credentials` };
+  }
+  if (provider?.authMode === "forward") {
+    return { error: `provider "${name}" uses forward auth and has no switchable credentials` };
+  }
+  if (provider?.authMode === "key") return { type: "api-key" };
+  if (provider && !provider.authMode && (provider.apiKey || (provider.apiKeyPool?.length ?? 0) > 0)) {
+    return { type: "api-key" };
+  }
+  if (isPublicOAuthProvider(name)) return { type: "oauth" };
+  if (provider) return { type: "api-key" };
+  return { error: `unknown provider "${name}"` };
+}
+export interface ApiResult {
+  /** 0 = network-level failure (proxy unreachable). */
+  status: number;
+  json: Record<string, unknown>;
+}
+export async function apiJson(
+  deps: AccountDeps,
+  baseUrl: string,
+  method: "GET" | "PUT" | "POST" | "DELETE",
+  path: string,
+  body?: unknown,
+): Promise<ApiResult> {
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  try {
+    const res = await fetchImpl(`${baseUrl}${path}`, {
+      method,
+      headers: runningProxyUpdateHeaders(),
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const json = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+    return { status: res.status, json };
+  } catch {
+    return { status: 0, json: {} };
+  }
+}
+export async function resolveBaseUrl(deps: AccountDeps): Promise<string | null> {
+  if (deps.baseUrl) return deps.baseUrl;
+  const live = await findLiveProxy();
+  if (!live) return null;
+  return `http://${probeHostname(live.hostname)}:${live.port}`;
+}
+export function proxyUnreachable(): number {
+  console.error("Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'.");
+  return 1;
+}
+export function apiError(json: Record<string, unknown>, fallback: string): number {
+  const message = typeof json.error === "string" ? json.error : fallback;
+  console.error(`Error: ${message}`);
+  return 1;
+}
+export interface FamilyRows {
+  rows: AccountRow[];
+  activeId: string | null;
+  autoSwitchThreshold?: number;
+  /** HTTP status for a completed family read, including failures. */
+  status?: number;
+  /** Set when the family endpoint returned an error. */
+  errorJson?: Record<string, unknown>;
+  networkDown?: boolean;
+}
+export interface CodexQuotaDto {
+  weeklyPercent?: number;
+  monthlyPercent?: number;
+  weeklyResetAt?: number;
+  monthlyResetAt?: number;
+}
+export interface ProviderQuotaWindowDto {
+  label: string;
+  percent: number;
+  resetAt?: number;
+}
+export interface ProviderQuotaDto extends CodexQuotaDto {
+  fiveHourPercent?: number;
+  fiveHourResetAt?: number;
+  customWindows?: ProviderQuotaWindowDto[];
+  updatedAt?: number;
+}
+export interface ProviderQuotaReportDto {
+  provider: string;
+  label?: string;
+  source?: string;
+  quota: ProviderQuotaDto;
+  updatedAt?: number;
+  reverseEngineered?: boolean;
+}
+interface CodexAccountDto {
+  id: string;
+  email?: string;
+  plan?: string;
+  isMain?: boolean;
+  needsReauth?: boolean;
+  quota?: CodexQuotaDto | null;
+}
+function projectQuota(quota: CodexQuotaDto | null | undefined): CodexQuotaDto | null {
+  if (!quota) return null;
+  const projected: CodexQuotaDto = {};
+  for (const key of ["weeklyPercent", "monthlyPercent", "weeklyResetAt", "monthlyResetAt"] as const) {
+    if (typeof quota[key] === "number" && Number.isFinite(quota[key])) projected[key] = quota[key];
+  }
+  return projected;
+}
+export async function fetchCodexRows(
+  deps: AccountDeps,
+  baseUrl: string,
+  forceRefresh = false,
+): Promise<FamilyRows> {
+  const accountsPath = `/api/codex-auth/accounts${forceRefresh ? "?refresh=1" : ""}`;
+  const [accountsRes, activeRes] = await Promise.all([
+    apiJson(deps, baseUrl, "GET", accountsPath),
+    apiJson(deps, baseUrl, "GET", "/api/codex-auth/active"),
+  ]);
+  if (accountsRes.status !== 0 && accountsRes.status !== 200) {
+    return { rows: [], activeId: null, status: accountsRes.status, errorJson: accountsRes.json };
+  }
+  if (activeRes.status !== 0 && activeRes.status !== 200) {
+    return { rows: [], activeId: null, status: activeRes.status, errorJson: activeRes.json };
+  }
+  if (accountsRes.status === 0 || activeRes.status === 0) {
+    return { rows: [], activeId: null, status: 0, networkDown: true };
+  }
+  const activeId = typeof activeRes.json.activeCodexAccountId === "string"
+    ? activeRes.json.activeCodexAccountId
+    : null;
+  const autoSwitchThreshold = typeof activeRes.json.autoSwitchThreshold === "number"
+    ? activeRes.json.autoSwitchThreshold
+    : undefined;
+  const accounts = Array.isArray(accountsRes.json.accounts) ? accountsRes.json.accounts as CodexAccountDto[] : [];
+  const rows = accounts.map(a => ({
+    provider: "openai",
+    type: "codex" as const,
+    id: a.id,
+    label: a.plan ?? a.email,
+    email: a.email,
+    plan: a.plan,
+    active: a.id === activeId,
+    needsReauth: a.needsReauth,
+    ...(forceRefresh ? { quota: projectQuota(a.quota) } : {}),
+  }));
+  return { rows, activeId, autoSwitchThreshold, status: 200 };
+}
+interface OAuthAccountDto {
+  id: string;
+  email?: string;
+  active?: boolean;
+  needsReauth?: boolean;
+}
+async function fetchOAuthRows(deps: AccountDeps, baseUrl: string, name: string): Promise<FamilyRows> {
+  const res = await apiJson(deps, baseUrl, "GET", `/api/oauth/accounts?provider=${encodeURIComponent(name)}`);
+  if (res.status === 0) return { rows: [], activeId: null, status: 0, networkDown: true };
+  if (res.status !== 200) return { rows: [], activeId: null, status: res.status, errorJson: res.json };
+  const activeId = typeof res.json.activeAccountId === "string" ? res.json.activeAccountId : null;
+  const accounts = Array.isArray(res.json.accounts) ? res.json.accounts as OAuthAccountDto[] : [];
+  const rows = accounts.map((a, i) => ({
+    provider: name,
+    type: "oauth" as const,
+    id: a.id,
+    label: a.email ?? `Account ${i + 1}`,
+    email: a.email,
+    active: a.active ?? a.id === activeId,
+    needsReauth: a.needsReauth,
+  }));
+  return { rows, activeId, status: 200 };
+}
+interface ApiKeyDto {
+  id: string;
+  label?: string;
+  masked?: string;
+  active?: boolean;
+}
+async function fetchKeyRows(deps: AccountDeps, baseUrl: string, name: string): Promise<FamilyRows> {
+  const res = await apiJson(deps, baseUrl, "GET", `/api/providers/keys?name=${encodeURIComponent(name)}`);
+  if (res.status === 0) return { rows: [], activeId: null, status: 0, networkDown: true };
+  if (res.status !== 200) return { rows: [], activeId: null, status: res.status, errorJson: res.json };
+  const activeId = typeof res.json.activeId === "string" ? res.json.activeId : null;
+  const keys = Array.isArray(res.json.keys) ? res.json.keys as ApiKeyDto[] : [];
+  const rows = keys.map(k => ({
+    provider: name,
+    type: "api-key" as const,
+    id: k.id,
+    label: k.label ?? k.masked,
+    masked: k.masked,
+    active: k.active ?? k.id === activeId,
+  }));
+  return { rows, activeId, status: 200 };
+}
+export function fetchRows(deps: AccountDeps, baseUrl: string, name: string, type: AccountType): Promise<FamilyRows> {
+  if (type === "codex") return fetchCodexRows(deps, baseUrl);
+  if (type === "oauth") return fetchOAuthRows(deps, baseUrl, name);
+  return fetchKeyRows(deps, baseUrl, name);
+}
+export async function fetchProviderQuotaReport(
+  deps: AccountDeps,
+  baseUrl: string,
+  name: string,
+): Promise<{ status: number; report: ProviderQuotaReportDto | null; errorJson?: Record<string, unknown> }> {
+  const res = await apiJson(deps, baseUrl, "GET", "/api/provider-quotas?refresh=1");
+  if (res.status !== 200) return { status: res.status, report: null, errorJson: res.json };
+  const reports = Array.isArray(res.json.reports) ? res.json.reports as ProviderQuotaReportDto[] : [];
+  return { status: 200, report: reports.find(report => report?.provider === name) ?? null };
+}

package/src/cli/account-extended.ts ADDED Viewed

@@ -0,0 +1,282 @@
+import { loadConfig } from "../config";
+import {
+  apiError,
+  apiJson,
+  classifyAccount,
+  fetchCodexRows,
+  fetchProviderQuotaReport,
+  fetchRows,
+  proxyUnreachable,
+  resolveBaseUrl,
+  type AccountDeps, type AccountStdin, type FamilyRows,
+  type ProviderQuotaDto, type ProviderQuotaReportDto,
+} from "./account-api";
+const MAIN_ID = "__main__";
+const AUTO_NOTE = "auto (no pin — lowest-usage account is selected per request)";
+const EXTENDED_USAGE = `Usage:
+  ocx account refresh <provider> [--json]
+  ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]
+  ocx account remove <provider> <id|main> --yes [--json]
+  ocx account add-key <provider> [--label <label>] [--json]`;
+const PIPE_GUIDANCE = `Pipe the API key on stdin, for example:
+  ocx account add-key <provider> <<< "$MY_KEY"
+  security find-generic-password -w <item> | ocx account add-key <provider>`;
+function flag(args: string[], value: string): boolean {
+  const index = args.indexOf(value);
+  if (index < 0) return false;
+  args.splice(index, 1);
+  return true;
+}
+function flagValue(args: string[], value: string): { found: boolean; value?: string } {
+  const index = args.indexOf(value);
+  if (index < 0) return { found: false };
+  if (index + 1 >= args.length) return { found: true };
+  const result = args[index + 1];
+  args.splice(index, 2);
+  return { found: true, value: result };
+}
+function usage(message?: string): number {
+  if (message) console.error(message);
+  console.error(EXTENDED_USAGE);
+  return 1;
+}
+function configAndType(deps: AccountDeps, name: string) {
+  return classifyAccount(deps.loadConfigImpl?.() ?? loadConfig(), name);
+}
+function familyFailure(result: FamilyRows, fallback: string): number | null {
+  if (result.networkDown) return proxyUnreachable();
+  if (result.errorJson) return apiError(result.errorJson, fallback);
+  return null;
+}
+function errorText(json: Record<string, unknown> | undefined, fallback: string): string {
+  return typeof json?.error === "string" ? json.error : fallback;
+}
+function resetIso(value: number | undefined): string | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  const date = new Date(value < 10_000_000_000 ? value * 1000 : value);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+function refreshLine(row: FamilyRows["rows"][number]): string {
+  const parts = [row.id === MAIN_ID ? "main" : row.id, row.email, row.plan];
+  const quota = row.quota;
+  if (!quota || (quota.weeklyPercent === undefined && quota.monthlyPercent === undefined)) {
+    parts.push("quota: unknown");
+  } else {
+    if (quota.weeklyPercent !== undefined) parts.push(`weekly ${quota.weeklyPercent}%`);
+    const weeklyReset = resetIso(quota.weeklyResetAt);
+    if (weeklyReset) parts.push(`resets ${weeklyReset}`);
+    if (quota.monthlyPercent !== undefined) parts.push(`monthly ${quota.monthlyPercent}%`);
+    const monthlyReset = resetIso(quota.monthlyResetAt);
+    if (monthlyReset) parts.push(`resets ${monthlyReset}`);
+  }
+  if (row.needsReauth) parts.push("needs-reauth");
+  return parts.filter(Boolean).join(" ");
+}
+function quotaParts(quota: ProviderQuotaDto): string[] {
+  const parts: string[] = [];
+  const add = (label: string, percent: number | undefined, resetAt?: number) => {
+    if (percent === undefined) return;
+    parts.push(`${label} ${percent}%`);
+    const reset = resetIso(resetAt);
+    if (reset) parts.push(`resets ${reset}`);
+  };
+  add("5h", quota.fiveHourPercent, quota.fiveHourResetAt);
+  add("weekly", quota.weeklyPercent, quota.weeklyResetAt);
+  add("monthly", quota.monthlyPercent, quota.monthlyResetAt);
+  for (const window of quota.customWindows ?? []) add(window.label, window.percent, window.resetAt);
+  return parts;
+}
+function providerQuotaLine(name: string, report: ProviderQuotaReportDto): string {
+  return [name, ...quotaParts(report.quota)].join(" ");
+}
+export async function readStdinLine(deps: AccountDeps): Promise<string> {
+  const input: AccountStdin = deps.stdinImpl ?? process.stdin;
+  const timeoutMs = deps.stdinTimeoutMs ?? 15_000;
+  return await new Promise<string>((resolve, reject) => {
+    let buffer = "";
+    let settled = false;
+    const cleanup = () => {
+      clearTimeout(timer);
+      input.removeListener("data", onData);
+      input.removeListener("end", onEnd);
+      input.removeListener("error", onError);
+    };
+    const finish = (fn: () => void) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      fn();
+    };
+    const onData = (chunk: unknown) => {
+      buffer += Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
+      const newline = buffer.search(/[\r\n]/);
+      if (newline >= 0) finish(() => resolve(buffer.slice(0, newline).trim()));
+    };
+    const onEnd = () => finish(() => resolve(buffer.trim()));
+    const onError = (error: Error) => finish(() => reject(error));
+    const timer = setTimeout(() => finish(() => reject(new Error("timed out waiting for API key on stdin"))), timeoutMs);
+    input.on("data", onData);
+    input.on("end", onEnd);
+    input.on("error", onError);
+  });
+}
+export async function cmdRefresh(args: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = flag(args, "--json");
+  const name = args.shift();
+  if (!name || args.length) return usage();
+  const classified = configAndType(deps, name);
+  if ("error" in classified) return usage(`Error: ${classified.error}`);
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+  if (classified.type !== "codex") {
+    const result = await fetchProviderQuotaReport(deps, baseUrl, name);
+    if (result.status === 0) return proxyUnreachable();
+    if (result.status !== 200) return apiError(result.errorJson ?? {}, `failed to refresh ${name}`);
+    if (wantsJson) console.log(JSON.stringify({ provider: name, report: result.report }, null, 2));
+    else console.log(result.report ? providerQuotaLine(name, result.report) : `no quota report available for ${name}`);
+    return 0;
+  }
+  const result = await fetchCodexRows(deps, baseUrl, true);
+  const failed = familyFailure(result, `failed to refresh ${name}`);
+  if (failed !== null) return failed;
+  if (wantsJson) console.log(JSON.stringify({ accounts: result.rows }, null, 2));
+  else for (const row of result.rows) console.log(refreshLine(row));
+  return 0;
+}
+export async function cmdAutoSwitch(args: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = flag(args, "--json");
+  const name = args.shift();
+  const action = args.shift();
+  if (!name || !action) return usage();
+  const classified = configAndType(deps, name);
+  if ("error" in classified || classified.type !== "codex") {
+    return usage("Error: auto-switch only applies to the openai Codex account pool");
+  }
+  let threshold: number | undefined;
+  if (action === "on" && args.length === 0) threshold = 80;
+  else if (action === "off" && args.length === 0) threshold = 0;
+  else if (action === "threshold" && args.length === 1 && /^\d+$/.test(args[0]!)) threshold = Number(args[0]);
+  else if (action !== "status" || args.length !== 0) return usage();
+  if (threshold !== undefined && (!Number.isInteger(threshold) || threshold < 0 || threshold > 100)) {
+    return usage("Error: threshold must be an integer 0-100");
+  }
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+  if (action === "status") {
+    const response = await apiJson(deps, baseUrl, "GET", "/api/codex-auth/active");
+    if (response.status === 0) return proxyUnreachable();
+    if (response.status !== 200 || typeof response.json.autoSwitchThreshold !== "number") {
+      return apiError(response.json, "failed to read auto-switch status");
+    }
+    threshold = response.json.autoSwitchThreshold;
+  } else {
+    const response = await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/auto-switch", { threshold });
+    if (response.status === 0) return proxyUnreachable();
+    if (response.status !== 200) return apiError(response.json, "failed to update auto-switch");
+  }
+  const enabled = threshold! > 0;
+  if (wantsJson) console.log(JSON.stringify({ provider: name, autoSwitchThreshold: threshold, enabled }, null, 2));
+  else console.log(enabled ? `auto-switch: on (threshold ${threshold}%)` : "auto-switch: off");
+  return 0;
+}
+function deletePath(type: "codex" | "oauth" | "api-key", name: string, id: string): string {
+  if (type === "codex") return `/api/codex-auth/accounts?id=${encodeURIComponent(id)}`;
+  if (type === "oauth") return `/api/oauth/accounts?provider=${encodeURIComponent(name)}&id=${encodeURIComponent(id)}`;
+  return `/api/providers/keys?name=${encodeURIComponent(name)}&id=${encodeURIComponent(id)}`;
+}
+export async function cmdRemove(args: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = flag(args, "--json");
+  const fail = (message: string): number => {
+    if (wantsJson) console.error(JSON.stringify({ error: message }));
+    else console.error(`Error: ${message}`);
+    return 1;
+  };
+  const confirmed = flag(args, "--yes");
+  const name = args.shift();
+  const requestedId = args.shift();
+  if (!name || !requestedId || args.length) return wantsJson ? fail("provider and account id are required") : usage();
+  if (!confirmed) {
+    const message = `Confirmation required. Re-run: ocx account remove ${name} ${requestedId} --yes`;
+    return wantsJson ? fail(message) : usage(message);
+  }
+  const classified = configAndType(deps, name);
+  if ("error" in classified) return wantsJson ? fail(classified.error) : usage(`Error: ${classified.error}`);
+  const id = classified.type === "codex" && requestedId === "main" ? MAIN_ID : requestedId;
+  if (classified.type === "codex" && id === MAIN_ID) return wantsJson
+    ? fail("the main Codex App login cannot be removed")
+    : usage("Error: the main Codex App login cannot be removed");
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return fail("Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'.");
+  const before = await fetchRows(deps, baseUrl, name, classified.type);
+  if (before.networkDown) return fail("Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'.");
+  if (before.errorJson) return fail(errorText(before.errorJson, `failed to verify ${name} before removal`));
+  if (!before.rows.some(row => row.id === id)) return wantsJson
+    ? fail(`account or key "${requestedId}" was not found`)
+    : usage(`Error: account or key "${requestedId}" was not found`);
+  const response = await apiJson(deps, baseUrl, "DELETE", deletePath(classified.type, name, id));
+  if (response.status === 0) return fail("Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'.");
+  if (response.status !== 200) return fail(errorText(response.json, `failed to remove ${requestedId}`));
+  const after = await fetchRows(deps, baseUrl, name, classified.type);
+  if (after.networkDown || after.errorJson) {
+    const detail = after.networkDown ? "proxy not reachable" : typeof after.errorJson?.error === "string" ? after.errorJson.error : "unknown error";
+    return fail(`post-delete verification failed; delete may have succeeded: ${detail}`);
+  }
+  const removedActive = before.activeId === id;
+  const result = { ok: true, provider: name, id, removedActive, promotedActiveId: after.activeId };
+  if (wantsJson) console.log(JSON.stringify(result, null, 2));
+  else if (classified.type === "codex" && removedActive && after.activeId === null) console.log(`openai: ${AUTO_NOTE}`);
+  else if (classified.type === "oauth") console.log(after.rows.length ? `${name}: active account is now ${after.activeId}` : `${name}: no accounts remaining`);
+  else if (classified.type === "api-key") console.log(after.rows.length ? `${name}: active key is now ${after.activeId}` : `${name}: no keys remaining`);
+  else console.log(`${name}: removed account ${requestedId}`);
+  return 0;
+}
+export async function cmdAddKey(args: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = flag(args, "--json");
+  const labelArg = flagValue(args, "--label");
+  const name = args.shift();
+  if (!name || args.length || (labelArg.found && labelArg.value === undefined)) return usage();
+  const classified = configAndType(deps, name);
+  if ("error" in classified || classified.type !== "api-key") return usage("Error: add-key only applies to API-key providers");
+  const input: AccountStdin = deps.stdinImpl ?? process.stdin;
+  if (input.isTTY) return usage(PIPE_GUIDANCE);
+  let key: string;
+  try {
+    key = await readStdinLine(deps);
+  } catch (error) {
+    return usage(`Error: ${error instanceof Error ? error.message : String(error)}\n${PIPE_GUIDANCE}`);
+  }
+  if (!key) return usage(`Error: API key input was empty\n${PIPE_GUIDANCE}`);
+  const label = labelArg.value?.trim();
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+  const response = await apiJson(deps, baseUrl, "POST", "/api/providers/keys", { name, key, ...(label ? { label } : {}) });
+  if (response.status === 0) return proxyUnreachable();
+  if (response.status !== 201) return apiError(response.json, `failed to add a key for ${name}`);
+  const id = typeof response.json.id === "string" ? response.json.id : null;
+  // Redact the key inside the label BEFORE serialization — a key containing
+  // JSON-escaped characters (" or \) would otherwise survive the whole-output
+  // pass in escaped form (audit finding, Carver WP3-C).
+  const safeLabel = label ? label.replaceAll(key, "[redacted]") : undefined;
+  const result = { ok: true, id, ...(safeLabel ? { label: safeLabel } : {}) };
+  const output = wantsJson ? JSON.stringify(result, null, 2)
+    : `${name}: added API key ${id ?? ""}${safeLabel ? ` (${safeLabel})` : ""}`.trim();
+  console.log(output.replaceAll(key, "[redacted]"));
+  return 0;
+}