switchboard-fyi 0.1.0

package/lib/switchboard-core.mjs

@@ -0,0 +1,779 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const DIFFICULTY_LEVELS = [1, 2, 3, 4, 5];
+export const MODEL_TIERS = ["lower", "mid", "best"];
+
+function codexDifficultyMap() {
+  return {
+    1: { model: "gpt-5.4-mini", reasoningEffort: "low" },
+    2: { model: "gpt-5.4-mini", reasoningEffort: "medium" },
+    3: { model: "gpt-5.4", reasoningEffort: "medium" },
+    4: { model: "gpt-5.5", reasoningEffort: "medium" },
+    5: { model: "gpt-5.5", reasoningEffort: "xhigh" },
+  };
+}
+
+function claudeDifficultyMap() {
+  return {
+    1: { model: "claude-haiku-4-5" },
+    2: { model: "claude-sonnet-4-6", effort: "low" },
+    3: { model: "claude-sonnet-4-6", effort: "medium" },
+    4: { model: "claude-opus-4-7", effort: "medium" },
+    5: { model: "claude-opus-4-7", effort: "xhigh" },
+  };
+}
+
+export const DEFAULT_CONFIG = {
+  schemaVersion: 2,
+  routing: {
+    enabled: true,
+  },
+  updates: {
+    enabled: true,
+    checkIntervalHours: 24,
+    packageName: "switchboard-fyi",
+    registry: "https://registry.npmjs.org",
+    releaseNotesUrl: "https://switchboard.fyi/release/latest",
+  },
+  componentStatus: {
+    enabled: true,
+    url: "",
+    checkIntervalMinutes: 30,
+    timeoutMs: 900,
+    staleAfterHours: 24,
+    overrides: {},
+  },
+  api: {
+    baseUrl: "https://api.switchboard.fyi",
+    appUrl: "https://www.switchboard.fyi",
+    loginTimeoutSeconds: 300,
+  },
+  safety: {
+    routeBreakers: {
+      enabled: true,
+    },
+  },
+  dashboard: {
+    intervalMs: 2000,
+  },
+  sessionReceipt: {
+    enabled: false,
+  },
+  diagnostics: {
+    errorReporting: {
+      enabled: true,
+      timeoutMs: 700,
+      stackLines: 16,
+    },
+  },
+  logging: {
+    redactPrompts: false,
+    promptPreviewChars: 240,
+    maxLogBytes: 5_000_000,
+    maxLogFiles: 3,
+  },
+  router: {
+    provider: "switchboard",
+    timeoutMs: 2500,
+    upstreamIdleTimeoutMs: 600000,
+    routingTextChars: 3000,
+    snippetChars: 900,
+  },
+  codex: {
+    port: 8789,
+    difficultyMap: codexDifficultyMap(),
+  },
+  claude: {
+    port: 8787,
+    difficultyMap: claudeDifficultyMap(),
+  },
+};
+
+export const MODEL_CATALOG = {
+  schemaVersion: 2,
+  catalogVersion: "2026-05-23",
+  harnesses: {
+    codex: {
+      label: "Codex",
+      ownedBy: "openai",
+      models: [
+        {
+          id: "gpt-5.5",
+          ownedBy: "openai",
+          note: "Flagship OpenAI model for complex reasoning and coding.",
+          reasoningEfforts: ["low", "medium", "high", "xhigh"],
+          pricingUsdPerMillionTokens: { input: 5, cachedInput: 0.5, output: 30 },
+          pricingRules: {
+            longContext: { inputTokensOver: 272_000, inputMultiplier: 2, outputMultiplier: 1.5 },
+          },
+          maxInputTokens: 1_000_000,
+        },
+        {
+          id: "gpt-5.4",
+          ownedBy: "openai",
+          note: "More affordable OpenAI model for coding and professional work.",
+          reasoningEfforts: ["low", "medium", "high", "xhigh"],
+          pricingUsdPerMillionTokens: { input: 2.5, cachedInput: 0.25, output: 15 },
+          pricingRules: {
+            longContext: { inputTokensOver: 272_000, inputMultiplier: 2, outputMultiplier: 1.5 },
+          },
+          maxInputTokens: 1_000_000,
+        },
+        {
+          id: "gpt-5.4-mini",
+          ownedBy: "openai",
+          note: "Fast lower-cost OpenAI tier for well-scoped coding work.",
+          reasoningEfforts: ["low", "medium", "high", "xhigh"],
+          pricingUsdPerMillionTokens: { input: 0.75, cachedInput: 0.075, output: 4.5 },
+          maxInputTokens: 400_000,
+        },
+      ],
+    },
+    claude: {
+      label: "Claude Code",
+      ownedBy: "anthropic",
+      models: [
+        {
+          id: "claude-opus-4-7",
+          ownedBy: "anthropic",
+          aliases: ["opus", "opus[1m]", "claude-opus-4-7[1m]"],
+          note: "Most capable generally available Claude model for complex reasoning and agentic coding.",
+          effortLevels: ["low", "medium", "high", "xhigh", "max"],
+          pricingUsdPerMillionTokens: { input: 5, cachedInput: 0.5, output: 25 },
+          maxInputTokens: 1_000_000,
+        },
+        {
+          id: "claude-sonnet-4-6",
+          ownedBy: "anthropic",
+          aliases: ["sonnet", "sonnet[1m]", "claude-sonnet-4-6[1m]"],
+          note: "Best speed/intelligence balance in the current Claude family.",
+          effortLevels: ["low", "medium", "high", "max"],
+          pricingUsdPerMillionTokens: { input: 3, cachedInput: 0.3, output: 15 },
+          maxInputTokens: 1_000_000,
+        },
+        {
+          id: "claude-haiku-4-5",
+          ownedBy: "anthropic",
+          aliases: ["haiku", "claude-haiku-4-5-20251001"],
+          canonicalId: "claude-haiku-4-5-20251001",
+          note: "Fastest current Claude model; alias for claude-haiku-4-5-20251001.",
+          effortLevels: [],
+          pricingUsdPerMillionTokens: { input: 1, cachedInput: 0.1, output: 5 },
+          maxInputTokens: 200_000,
+        },
+      ],
+    },
+  },
+};
+
+function baseDifficultyMap(harness) {
+  return harness === "claude" ? claudeDifficultyMap() : codexDifficultyMap();
+}
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+export function switchboardHome() {
+  return process.env.SWITCHBOARD_HOME || path.join(os.homedir(), ".switchboard");
+}
+
+export function configPath() {
+  return path.join(switchboardHome(), "config.json");
+}
+
+export function ensureHome() {
+  fs.mkdirSync(switchboardHome(), { recursive: true, mode: 0o700 });
+}
+
+function tempPath(file) {
+  return `${file}.${process.pid}.${Date.now()}.tmp`;
+}
+
+function isPlainObject(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+export function mergeConfig(base, override) {
+  const output = { ...base };
+  for (const [key, value] of Object.entries(override || {})) {
+    if (isPlainObject(value) && isPlainObject(output[key])) output[key] = mergeConfig(output[key], value);
+    else output[key] = value;
+  }
+  return output;
+}
+
+function stringValue(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function canonicalDifficultyEntry(entry = {}) {
+  const raw = isPlainObject(entry) ? entry : {};
+  return {
+    model: stringValue(raw.model),
+    reasoningEffort: stringValue(raw.reasoningEffort || raw.reasoning_effort),
+    effort: stringValue(raw.effort),
+  };
+}
+
+function catalogEntryForHarnessModel(harness, model) {
+  const options = MODEL_CATALOG.harnesses[harness]?.models || [];
+  return (
+    options.find((entry) =>
+      [entry.id, entry.canonicalId, ...(entry.aliases || [])]
+        .filter(Boolean)
+        .includes(model),
+    ) || null
+  );
+}
+
+function supportedHarnessEfforts(harness, model) {
+  const entry = catalogEntryForHarnessModel(harness, model);
+  if (!entry) return [];
+  return harness === "codex"
+    ? [...(entry.reasoningEfforts || [])]
+    : [...(entry.effortLevels || [])];
+}
+
+function sanitizeDifficultyEntry(entry, harness, fallbackEntry = {}) {
+  const next = canonicalDifficultyEntry(entry);
+  const fallback = canonicalDifficultyEntry(fallbackEntry);
+  const supportedEfforts = supportedHarnessEfforts(harness, next.model);
+  const reasoningEffort =
+    next.reasoningEffort ||
+    (next.model === fallback.model ? fallback.reasoningEffort : "");
+  const effort =
+    next.effort ||
+    (next.model === fallback.model ? fallback.effort : "");
+  return {
+    model: next.model,
+    reasoningEffort:
+      harness === "codex" && supportedEfforts.length
+        ? supportedEfforts.includes(reasoningEffort)
+          ? reasoningEffort
+          : supportedEfforts[0]
+        : "",
+    effort:
+      harness === "claude" && supportedEfforts.length
+        ? supportedEfforts.includes(effort)
+          ? effort
+          : supportedEfforts[0]
+        : "",
+  };
+}
+
+function normalizeDifficultyMap(rawMap, harness) {
+  const base = baseDifficultyMap(harness);
+  const next = {};
+  for (const level of DIFFICULTY_LEVELS) {
+    const baseEntry = canonicalDifficultyEntry(base[level]);
+    const rawEntry = canonicalDifficultyEntry(rawMap?.[level] || rawMap?.[String(level)]);
+    next[level] = sanitizeDifficultyEntry({
+      model: rawEntry.model || baseEntry.model,
+      reasoningEffort: rawEntry.reasoningEffort,
+      effort: rawEntry.effort,
+    }, harness, baseEntry);
+  }
+  return next;
+}
+
+function difficultyMapToTierModels(difficultyMap) {
+  return {
+    lower: canonicalDifficultyEntry(difficultyMap[1]),
+    mid: canonicalDifficultyEntry(difficultyMap[3]),
+    best: canonicalDifficultyEntry(difficultyMap[5]),
+  };
+}
+
+function legacyHarnessShape(harnessConfig, harness) {
+  const difficultyMap = normalizeDifficultyMap(harnessConfig?.difficultyMap, harness);
+  const tiers = difficultyMapToTierModels(difficultyMap);
+  const next = {
+    ...harnessConfig,
+    difficultyMap,
+    models: tiers,
+    cheapModel: tiers.lower.model,
+    midModel: tiers.mid.model,
+    premiumModel: tiers.best.model,
+    modelProfile: "",
+    mode: "",
+  };
+  if (harness === "codex") {
+    next.reasoningEffortByTier = {
+      lower: tiers.lower.reasoningEffort || "",
+      mid: tiers.mid.reasoningEffort || "",
+      best: tiers.best.reasoningEffort || "",
+    };
+  }
+  return next;
+}
+
+function normalizeConfig(config) {
+  const input = isPlainObject(config) ? config : {};
+  const merged = mergeConfig(DEFAULT_CONFIG, input?.schemaVersion === 2 ? input : {});
+  merged.schemaVersion = 2;
+  merged.codex = legacyHarnessShape(merged.codex, "codex");
+  merged.claude = legacyHarnessShape(merged.claude, "claude");
+  return merged;
+}
+
+export function loadConfig() {
+  ensureHome();
+  try {
+    const raw = fs.readFileSync(configPath(), "utf8");
+    return normalizeConfig(JSON.parse(raw));
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      return { ...clone(DEFAULT_CONFIG), configError: error.message };
+    }
+    return normalizeConfig(DEFAULT_CONFIG);
+  }
+}
+
+export function ensureConfigFile() {
+  ensureHome();
+  const file = configPath();
+  let config = loadConfig();
+  if (!fs.existsSync(file)) {
+    const tmp = tempPath(file);
+    fs.writeFileSync(tmp, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+    config = loadConfig();
+  } else {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+      if (parsed?.schemaVersion !== 2) {
+        const tmp = tempPath(file);
+        fs.writeFileSync(tmp, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`, { mode: 0o600 });
+        fs.renameSync(tmp, file);
+        config = loadConfig();
+      }
+    } catch {}
+  }
+  return config;
+}
+
+export function difficultyProfile(config, harness, level) {
+  const id = normalizeHarness(harness);
+  const safeLevel = Math.max(1, Math.min(5, Number(level) || 1));
+  const map = config?.[id]?.difficultyMap || DEFAULT_CONFIG?.[id]?.difficultyMap || {};
+  return canonicalDifficultyEntry(map[safeLevel] || map[String(safeLevel)]);
+}
+
+export const HARNESS_REGISTRY = {
+  codex: {
+    id: "codex",
+    label: "Codex",
+    aliases: ["codex"],
+  },
+  claude: {
+    id: "claude",
+    label: "Claude Code",
+    aliases: ["claude", "claude-code", "claude_code", "claude code"],
+  },
+};
+
+const HARNESS_ALIASES = Object.fromEntries(
+  Object.values(HARNESS_REGISTRY).flatMap((harness) =>
+    harness.aliases.map((alias) => [String(alias).toLowerCase().replace(/_/g, "-").trim(), harness.id]),
+  ),
+);
+
+export function knownHarnesses() {
+  return Object.keys(HARNESS_REGISTRY);
+}
+
+export function normalizeHarness(value) {
+  const normalized = String(value || "").toLowerCase().replace(/_/g, "-").trim();
+  return HARNESS_ALIASES[normalized] || null;
+}
+
+export function harnessLabel(harness) {
+  const id = normalizeHarness(harness) || harness;
+  return HARNESS_REGISTRY[id]?.label || String(harness || "Unknown");
+}
+
+export function harnessRuntimeDir(harness) {
+  const id = normalizeHarness(harness);
+  if (!id) throw new Error(`Unknown Switchboard harness: ${harness}`);
+  return path.join(switchboardHome(), "harnesses", id);
+}
+
+export function harnessLogPath(harness, name = "events.jsonl") {
+  return path.join(harnessRuntimeDir(harness), name);
+}
+
+export function logPath(name) {
+  return path.join(switchboardHome(), name);
+}
+
+export function healthPath(harness = null) {
+  return harness ? path.join(harnessRuntimeDir(harness), "health.json") : path.join(switchboardHome(), "health.json");
+}
+
+export function redactPrompt(text, config = loadConfig()) {
+  if (!text) return "";
+  if (config.logging?.redactPrompts) return "[redacted]";
+  return redactSensitiveText(String(text)).slice(0, config.logging?.promptPreviewChars || 240);
+}
+
+export function redactSensitiveText(text) {
+  return String(text || "")
+    .replace(/\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9_=-]{12,}\b/g, "[redacted-stripe-key]")
+    .replace(/\bwhsec_[A-Za-z0-9_=-]{12,}\b/g, "[redacted-stripe-secret]")
+    .replace(/\bsk-(?:proj-|svcacct-)?[A-Za-z0-9_-]{16,}\b/g, "[redacted-openai-key]")
+    .replace(/\bsk-ant-[A-Za-z0-9_-]{16,}\b/g, "[redacted-anthropic-key]")
+    .replace(/\bghp_[A-Za-z0-9_]{20,}\b/g, "[redacted-github-token]")
+    .replace(/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, "[redacted-github-token]")
+    .replace(/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, "[redacted-jwt]")
+    .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{16,}\b/gi, "Bearer [redacted-token]")
+    .replace(/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi, "[redacted-email]");
+}
+
+function redactDiagnosticText(text) {
+  return redactSensitiveText(text)
+    .replace(
+      /\b[A-Za-z_][A-Za-z0-9_]*(?:TOKEN|SECRET|PASSWORD|API_KEY|AUTH)[A-Za-z0-9_]*=([^\s]+)/gi,
+      (match) => `${match.split("=")[0]}=[redacted]`,
+    )
+    .replace(/\/Users\/[^/\s]+/g, "~")
+    .replace(/\/home\/[^/\s]+/g, "~")
+    .replace(/[A-Za-z]:\\Users\\[^\\\s]+/g, "~");
+}
+
+function diagnosticText(value, maxChars) {
+  return redactDiagnosticText(String(value || "").replace(/\0/g, "").replace(/\s+/g, " ").trim())
+    .slice(0, Math.max(0, maxChars));
+}
+
+function diagnosticToken(value, maxChars) {
+  return diagnosticText(value, maxChars)
+    .replace(/[^A-Za-z0-9._:-]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, Math.max(0, maxChars));
+}
+
+function diagnosticStack(error, stackLines) {
+  const stack = typeof error?.stack === "string" ? error.stack : "";
+  if (!stack) return "";
+  return stack
+    .split("\n")
+    .map((line) => redactDiagnosticText(line).trimEnd())
+    .filter(Boolean)
+    .slice(0, Math.max(1, Number(stackLines) || 16))
+    .join("\n")
+    .slice(0, 8000);
+}
+
+function diagnosticReportingEnabled(config = loadConfig()) {
+  const override = String(process.env.SWITCHBOARD_ERROR_REPORTING || "").toLowerCase().trim();
+  if (["0", "false", "off", "no"].includes(override)) return false;
+  if (["1", "true", "on", "yes"].includes(override)) return true;
+  return config.diagnostics?.errorReporting?.enabled !== false;
+}
+
+function diagnosticApiUrl(value) {
+  const raw = String(value || DEFAULT_CONFIG.api.baseUrl || "").trim();
+  if (!raw) return "";
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return "";
+  }
+  const host = url.hostname.toLowerCase();
+  const local = ["127.0.0.1", "localhost", "::1"].includes(host);
+  const allowed = local || host === "api.switchboard.fyi";
+  if (process.env.SWITCHBOARD_UNSAFE_API_URL !== "1" && !allowed) return "";
+  if (process.env.SWITCHBOARD_UNSAFE_API_URL !== "1" && url.protocol !== "https:" && !(local && url.protocol === "http:")) return "";
+  return url.toString().replace(/\/+$/, "");
+}
+
+function diagnosticEventId(source = "cli") {
+  const prefix = diagnosticToken(source, 24) || "cli";
+  return `${prefix}_err_${Date.now().toString(36)}_${crypto.randomBytes(8).toString("hex")}`;
+}
+
+function diagnosticPackageInfo() {
+  try {
+    return JSON.parse(fs.readFileSync(path.resolve(new URL("..", import.meta.url).pathname, "package.json"), "utf8"));
+  } catch {
+    return { name: "switchboard-fyi", version: "0.0.0" };
+  }
+}
+
+function diagnosticErrorName(error) {
+  return diagnosticText(error?.name || "Error", 160) || "Error";
+}
+
+function diagnosticErrorCode(error) {
+  return diagnosticToken(error?.code || error?.cause?.code || "", 120);
+}
+
+function diagnosticErrorMessage(error) {
+  if (error?.message) return diagnosticText(error.message, 1000);
+  return diagnosticText(String(error || "Unknown error"), 1000);
+}
+
+function normalizeDiagnosticMessage(message) {
+  return String(message || "")
+    .replace(/\b[0-9a-f]{8}-[0-9a-f-]{27,}\b/gi, "[uuid]")
+    .replace(/\b\d+\b/g, "[n]")
+    .toLowerCase()
+    .slice(0, 300);
+}
+
+function diagnosticFingerprint(error, message, stack) {
+  const name = diagnosticErrorName(error);
+  const code = diagnosticErrorCode(error);
+  const firstFrame = String(stack || "").split("\n").find((line) => /\bat\b|\.mjs:|\.js:|\.ts:/.test(line)) || "";
+  return crypto
+    .createHash("sha256")
+    .update([name, code, normalizeDiagnosticMessage(message), firstFrame].join("\n"))
+    .digest("hex")
+    .slice(0, 24);
+}
+
+function sanitizeDiagnosticJson(value, depth = 0) {
+  if (value == null) return null;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "string") return diagnosticText(value, 500);
+  if (Array.isArray(value)) {
+    if (depth >= 4) return [];
+    return value.slice(0, 20).map((item) => sanitizeDiagnosticJson(item, depth + 1));
+  }
+  if (typeof value !== "object") return null;
+  if (depth >= 4) return {};
+
+  const output = {};
+  for (const [rawKey, rawEntry] of Object.entries(value).slice(0, 60)) {
+    const key = diagnosticText(rawKey, 80);
+    if (!key) continue;
+    if (/(authorization|api[-_]?key|token|secret|password|credential|cookie)/i.test(key)) {
+      output[key] = "[redacted]";
+      continue;
+    }
+    output[key] = sanitizeDiagnosticJson(rawEntry, depth + 1);
+  }
+  return output;
+}
+
+function diagnosticSource(value) {
+  const source = String(value || "cli").toLowerCase().replace(/[_\s]+/g, "-").trim();
+  if (["cli", "gateway", "inspector"].includes(source)) return source;
+  return "cli";
+}
+
+function diagnosticSeverity(value) {
+  return String(value || "").toLowerCase() === "fatal" ? "fatal" : "error";
+}
+
+function diagnosticCommand(value) {
+  return diagnosticToken(value || "", 160) || null;
+}
+
+function diagnosticHarness(value) {
+  return normalizeHarness(value) || null;
+}
+
+function ignoredDiagnosticMessage(error) {
+  const code = diagnosticErrorCode(error).toLowerCase();
+  const text = `${diagnosticErrorName(error)} ${diagnosticErrorMessage(error)}`.toLowerCase();
+  if (["insufficient_credits", "missing_cli_token", "invalid_cli_token"].includes(code)) return true;
+  return [
+    /\binsufficient[_ -]?credits?\b/,
+    /\bnot logged in\b/,
+    /\brun `?switchboard login`?\b/,
+    /\bmissing cli token\b/,
+    /\binvalid or expired cli token\b/,
+    /\bcli token missing scope\b/,
+    /\bunknown (switchboard )?(command|harness|model|difficulty command|status command|auth command|models command)\b/,
+    /\bconfig key is required\b/,
+    /\btop-?up amount must\b/,
+    /\bcould not find the real (codex|claude) binary\b/,
+    /\binstall (codex|claude) first\b/,
+    /\brefusing (untrusted|unsafe|to bind|to install)\b/,
+    /\bwindows browser launch is not available\b/,
+    /\bstatus must be one of\b/,
+    /\bcomponent is required\b/,
+    /\b--real can only be used\b/,
+    /\bis not executable\b/,
+  ].some((pattern) => pattern.test(text));
+}
+
+export function isReportableDiagnosticError(error) {
+  if (!error) return false;
+  if (error.switchboardExpected || error.switchboardFriendly || error.expected) return false;
+  if (ignoredDiagnosticMessage(error)) return false;
+  return true;
+}
+
+export async function reportDiagnosticError(error, options = {}) {
+  try {
+    const config = options.config || loadConfig();
+    if (!diagnosticReportingEnabled(config)) return { reported: false, reason: "disabled" };
+    if (!isReportableDiagnosticError(error)) return { reported: false, reason: "ignored" };
+
+    const token = typeof options.token === "function" ? options.token() : options.token;
+    if (!token) return { reported: false, reason: "missing_token" };
+
+    const apiUrl = diagnosticApiUrl(options.apiUrl || config.api?.baseUrl);
+    if (!apiUrl) return { reported: false, reason: "invalid_api_url" };
+
+    const pkg = options.packageInfo || diagnosticPackageInfo();
+    const stack = diagnosticStack(error, config.diagnostics?.errorReporting?.stackLines);
+    const message = diagnosticErrorMessage(error);
+    const source = diagnosticSource(options.source);
+    const context = { ...(options.context || {}) };
+    if (options.phase) context.phase = options.phase;
+    const payload = {
+      client_event_id: diagnosticEventId(source),
+      source,
+      command: diagnosticCommand(options.command),
+      harness: diagnosticHarness(options.harness),
+      severity: diagnosticSeverity(options.severity),
+      client_session_id: diagnosticToken(options.sessionId || options.clientSessionId || "", 200) || null,
+      error: {
+        name: diagnosticErrorName(error),
+        code: diagnosticErrorCode(error) || null,
+        message,
+        stack,
+        fingerprint: diagnosticFingerprint(error, message, stack),
+      },
+      cli: {
+        name: diagnosticToken(pkg.name || "switchboard-fyi", 80),
+        version: diagnosticToken(options.version || pkg.version || "0.0.0", 80),
+        node_version: diagnosticToken(process.version, 80),
+        platform: diagnosticToken(process.platform, 80),
+        arch: diagnosticToken(process.arch, 80),
+      },
+      context: sanitizeDiagnosticJson(context),
+    };
+
+    const controller = new AbortController();
+    const timeoutMs = Math.max(100, Number(options.timeoutMs || config.diagnostics?.errorReporting?.timeoutMs || 700));
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    timeout.unref?.();
+    try {
+      const response = await fetch(new URL("/v1/cli/error-events", `${apiUrl}/`), {
+        method: "POST",
+        signal: controller.signal,
+        headers: {
+          authorization: `Bearer ${token}`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify(payload),
+      });
+      return { reported: response.ok, status: response.status };
+    } finally {
+      clearTimeout(timeout);
+    }
+  } catch {
+    return { reported: false, reason: "failed" };
+  }
+}
+
+export function rotateLog(file, config = loadConfig()) {
+  const maxBytes = Number(config.logging?.maxLogBytes || 0);
+  const maxFiles = Number(config.logging?.maxLogFiles || 0);
+  if (!maxBytes || !maxFiles) return;
+  try {
+    const stat = fs.statSync(file);
+    if (stat.size < maxBytes) return;
+  } catch (error) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+  for (let index = maxFiles - 1; index >= 1; index -= 1) {
+    const from = `${file}.${index}`;
+    const to = `${file}.${index + 1}`;
+    if (fs.existsSync(from)) fs.renameSync(from, to);
+  }
+  fs.renameSync(file, `${file}.1`);
+}
+
+export function appendJsonl(file, event, config = loadConfig()) {
+  ensureHome();
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  rotateLog(file, config);
+  fs.appendFileSync(
+    file,
+    `${JSON.stringify({
+      ts: new Date().toISOString(),
+      schemaVersion: 2,
+      ...event,
+    })}\n`,
+    { mode: 0o600 },
+  );
+}
+
+export function readHealth(harness = null) {
+  ensureHome();
+  try {
+    const raw = fs.readFileSync(healthPath(harness), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+export function writeHealth(health, harness = null) {
+  ensureHome();
+  const file = healthPath(harness);
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(tmp, `${JSON.stringify(health || {}, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+export function harnessHealth(health, harness, now = Date.now()) {
+  const entry = health?.[harness] || {};
+  return {
+    ...entry,
+    state: entry.state === "observe_only" ? "healthy" : entry.state || "healthy",
+    circuitOpen: false,
+    openUntil: null,
+  };
+}
+
+export function clearExpiredHealth(health, now = Date.now()) {
+  const next = { ...(health || {}) };
+  for (const [harness, entry] of Object.entries(next)) {
+    const state = harnessHealth(next, harness, now);
+    if (!state.circuitOpen && (entry?.state === "observe_only" || entry?.circuitOpen)) {
+      next[harness] = {
+        ...entry,
+        state: "healthy",
+        openUntil: null,
+        reason: "",
+        message: "",
+        lastRecoveredAt: new Date(now).toISOString(),
+      };
+    }
+  }
+  return next;
+}
+
+export function readJsonl(file) {
+  try {
+    return fs
+      .readFileSync(file, "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => {
+        try {
+          return JSON.parse(line);
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}