@oar-sh/oar 0.9.0

package/server/services/grok-billing-usage.mjs

@@ -0,0 +1,120 @@
+'use strict';
+
+/**
+ * Live Grok subscription quota for the Check Usage card.
+ *
+ * OIDC subscription logins have no USD billing; the authoritative quota is
+ * the weekly SuperGrok percentage shown on grok.com → Settings → Usage. The
+ * Grok CLI's chat proxy serves the same payload:
+ *
+ *   GET https://cli-chat-proxy.grok.com/v1/billing?format=credits
+ *   Authorization: Bearer <key from ~/.grok/auth.json>
+ *
+ * (Discovered 2026-08-08 by tracing the TUI's subscription watcher; the ACP
+ * agent itself exposes no quota RPC — `x.ai/auth/check_subscription` is a
+ * leader-side method.)
+ *
+ * The bearer key is the relay host's own CLI login (same host-login trust
+ * model as turn execution). It is read fresh per fetch — the CLI rotates it
+ * every few hours — and never logged or forwarded to clients.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const GROK_BILLING_URL = 'https://cli-chat-proxy.grok.com/v1/billing?format=credits';
+const FETCH_TIMEOUT_MS = 6_000;
+
+/**
+ * Read the newest OIDC access key from the Grok CLI's auth store. Returns
+ * null when the CLI is not logged in. Never throws.
+ */
+export function readGrokCliAuthKey({ homeDir = os.homedir(), fsImpl = fs } = {}) {
+  try {
+    const raw = fsImpl.readFileSync(path.join(homeDir, '.grok', 'auth.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return null;
+    let best = null;
+    for (const entry of Object.values(parsed)) {
+      const key = String(entry?.key || '').trim();
+      if (!key) continue;
+      const createTime = Date.parse(entry?.create_time || '') || 0;
+      if (!best || createTime > best.createTime) {
+        best = { key, createTime, expiresAt: String(entry?.expires_at || '') || null };
+      }
+    }
+    return best ? { key: best.key, expiresAt: best.expiresAt } : null;
+  } catch {
+    return null;
+  }
+}
+
+function toPercent(value) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) && numeric >= 0 ? numeric : null;
+}
+
+function toIso(value) {
+  const parsed = Date.parse(String(value || ''));
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+
+/**
+ * Normalize the proxy's billing payload into the fields the plan card needs.
+ * Pure; returns null when nothing usable is present.
+ */
+export function normalizeGrokBillingCredits(payload = null) {
+  const config = payload?.config && typeof payload.config === 'object' ? payload.config : payload;
+  if (!config || typeof config !== 'object') return null;
+
+  const usagePercent = toPercent(config.creditUsagePercent);
+  const period = config.currentPeriod && typeof config.currentPeriod === 'object'
+    ? config.currentPeriod
+    : {};
+  const periodType = String(period.type || '').trim();
+  const products = (Array.isArray(config.productUsage) ? config.productUsage : [])
+    .map((entry) => ({
+      product: String(entry?.product || '').trim(),
+      usagePercent: toPercent(entry?.usagePercent),
+    }))
+    .filter((entry) => entry.product && entry.usagePercent !== null);
+
+  const normalized = {
+    usagePercent,
+    // "USAGE_PERIOD_TYPE_WEEKLY" → "weekly"
+    periodType: periodType.replace(/^USAGE_PERIOD_TYPE_/, '').toLowerCase() || null,
+    periodStart: toIso(period.start || config.billingPeriodStart),
+    periodEnd: toIso(period.end || config.billingPeriodEnd),
+    products,
+  };
+  if (normalized.usagePercent === null && !products.length) return null;
+  return normalized;
+}
+
+/**
+ * Build the best-effort fetcher the usage route calls. Errors and missing
+ * logins yield `null` so the card degrades to the local estimated view.
+ */
+export function createGrokBillingUsageFetcher({
+  fetchImpl = globalThis.fetch,
+  readAuthKeyImpl = readGrokCliAuthKey,
+  url = GROK_BILLING_URL,
+  timeoutMs = FETCH_TIMEOUT_MS,
+} = {}) {
+  return async function fetchGrokBillingUsage() {
+    if (typeof fetchImpl !== 'function') return null;
+    const auth = readAuthKeyImpl();
+    if (!auth?.key) return null;
+    try {
+      const response = await fetchImpl(url, {
+        headers: { Authorization: `Bearer ${auth.key}` },
+        signal: AbortSignal.timeout?.(timeoutMs),
+      });
+      if (!response?.ok) return null;
+      return normalizeGrokBillingCredits(await response.json());
+    } catch {
+      return null;
+    }
+  };
+}

package/server/services/image-context-service.mjs

@@ -0,0 +1,106 @@
+'use strict';
+
+function parseAttachmentList(value) {
+  if (Array.isArray(value)) return value;
+  if (!value) return [];
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+export function createImageContextService({
+  db,
+  repository,
+  uuidv4,
+} = {}) {
+  if (!db || !repository || typeof uuidv4 !== 'function') {
+    throw new Error('Image context service dependencies are required');
+  }
+
+  const getMessage = db.prepare(`
+    SELECT id, conversation_id, role, attachments, timestamp
+    FROM messages
+    WHERE id = ?
+  `);
+
+  function resolveGeneratedAttachmentTarget({
+    conversationId,
+    target,
+    createdAt,
+  } = {}) {
+    const messageId = String(target?.messageId || '').trim();
+    const imageId = String(target?.imageId || '').trim();
+    const requestedNodeId = String(target?.nodeId || '').trim();
+    if (!conversationId || !messageId || !imageId) {
+      throw new Error('Image edit target requires messageId and imageId');
+    }
+
+    const message = getMessage.get(messageId);
+    if (!message || message.conversation_id !== conversationId || message.role !== 'assistant') {
+      throw new Error('Image edit target is not available in this conversation');
+    }
+    const attachment = parseAttachmentList(message.attachments).find((entry) => (
+      String(entry?.generatedImage?.imageId || '').trim() === imageId
+    ));
+    if (!attachment?.generatedImage) {
+      throw new Error('Image edit target is not a generated image');
+    }
+
+    let node = repository.getNodeByAttachment.get(messageId, imageId);
+    if (node && requestedNodeId && node.id !== requestedNodeId) {
+      throw new Error('Image edit target node does not match the generated image');
+    }
+    if (node) {
+      return { node, attachment, reconstructionMode: 'native' };
+    }
+
+    const now = String(createdAt || new Date().toISOString());
+    const imageSessionId = `img_session_${uuidv4()}`;
+    const bridgeOperationId = `img_op_${uuidv4()}`;
+    const nodeId = `img_node_${uuidv4()}`;
+    repository.insertSession.run({
+      id: imageSessionId,
+      conversationId,
+      origin: 'legacy_reconstructed',
+      schemaVersion: repository.imageSchemaVersion,
+      createdAt: message.timestamp || now,
+      updatedAt: now,
+    });
+    repository.insertOperation.run({
+      id: bridgeOperationId,
+      imageSessionId,
+      sourceMessageId: messageId,
+      queueMessageId: `legacy:${messageId}:${imageId}`,
+      kind: 'legacy_edit',
+      parentNodeId: null,
+      prompt: '',
+      selectedImageModel: 'legacy-generated-image',
+      orchestrationModel: null,
+      provider: 'openai',
+      executionMode: 'direct_images',
+      parametersJson: '{}',
+      requestFingerprint: `legacy:${messageId}:${imageId}`,
+      idempotencyKey: bridgeOperationId,
+      replacesOperationId: null,
+      createdAt: message.timestamp || now,
+    });
+    repository.insertNode.run({
+      id: nodeId,
+      imageSessionId,
+      operationId: bridgeOperationId,
+      assistantMessageId: messageId,
+      attachmentImageId: imageId,
+      outputIndex: 0,
+      createdAt: message.timestamp || now,
+    });
+    node = repository.getNode.get(nodeId);
+    return { node, attachment, reconstructionMode: 'image_only' };
+  }
+
+  return {
+    resolveGeneratedAttachmentTarget,
+  };
+}

package/server/services/image-operation-service.mjs

@@ -0,0 +1,135 @@
+'use strict';
+
+import crypto from 'crypto';
+import { createImageContextService } from './image-context-service.mjs';
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(String(value)).digest('hex');
+}
+
+export function createImageOperationService({
+  db,
+  repository,
+  uuidv4,
+} = {}) {
+  const contextService = createImageContextService({ db, repository, uuidv4 });
+
+  function createEnqueuedOperation({
+    conversationId,
+    sourceMessageId,
+    queueMessageId,
+    prompt,
+    selectedImageModel,
+    orchestrationModel = null,
+    executionMode = 'direct_images',
+    parameters = {},
+    attachments = [],
+    imageTarget = null,
+    replacesOperationId = null,
+    createdAt = new Date().toISOString(),
+  } = {}) {
+    const operationId = `img_op_${uuidv4()}`;
+    let imageSessionId;
+    let parentNodeId = null;
+    let reconstructionMode = executionMode === 'native_responses' ? 'native' : 'image_only';
+    let kind = 'generate';
+
+    if (imageTarget) {
+      const resolved = contextService.resolveGeneratedAttachmentTarget({
+        conversationId,
+        target: imageTarget,
+        createdAt,
+      });
+      imageSessionId = resolved.node.image_session_id;
+      parentNodeId = resolved.node.id;
+      reconstructionMode = resolved.reconstructionMode;
+      kind = resolved.reconstructionMode === 'image_only' ? 'legacy_edit' : 'edit';
+    } else {
+      imageSessionId = `img_session_${uuidv4()}`;
+      repository.insertSession.run({
+        id: imageSessionId,
+        conversationId,
+        origin: 'native',
+        schemaVersion: repository.imageSchemaVersion,
+        createdAt,
+        updatedAt: createdAt,
+      });
+    }
+
+    const assets = attachments
+      .map((attachment, ordinal) => ({
+        ordinal,
+        uploadId: String(attachment?.sha256 || '').trim().toLowerCase(),
+        contentSha256: String(attachment?.sha256 || '').trim().toLowerCase(),
+        mediaType: String(attachment?.type || '').trim().toLowerCase(),
+      }))
+      .filter((asset) => asset.contentSha256 && asset.mediaType.startsWith('image/'));
+    const immutableIntent = {
+      conversationId,
+      sourceMessageId,
+      queueMessageId,
+      kind,
+      parentNodeId,
+      prompt: String(prompt || ''),
+      selectedImageModel,
+      orchestrationModel,
+      provider: 'openai',
+      executionMode,
+      parameters,
+      assets: assets.map(({ contentSha256, mediaType }) => ({ contentSha256, mediaType })),
+      replacesOperationId,
+    };
+    repository.insertOperation.run({
+      id: operationId,
+      imageSessionId,
+      sourceMessageId,
+      queueMessageId,
+      kind,
+      parentNodeId,
+      prompt: String(prompt || ''),
+      selectedImageModel,
+      orchestrationModel,
+      provider: 'openai',
+      executionMode,
+      parametersJson: canonicalJson(parameters),
+      requestFingerprint: sha256(canonicalJson(immutableIntent)),
+      idempotencyKey: operationId,
+      replacesOperationId,
+      createdAt,
+    });
+    for (const asset of assets) {
+      repository.insertAsset.run({
+        operationId,
+        ordinal: asset.ordinal,
+        role: 'reference',
+        uploadId: asset.uploadId,
+        contentSha256: asset.contentSha256,
+        mediaType: asset.mediaType,
+        createdAt,
+      });
+    }
+    repository.linkQueueOperation.run(operationId, queueMessageId);
+    repository.touchSession.run(createdAt, imageSessionId);
+
+    return {
+      id: operationId,
+      imageSessionId,
+      kind,
+      parentNodeId,
+      mode: executionMode,
+      reconstructionMode,
+    };
+  }
+
+  return {
+    createEnqueuedOperation,
+  };
+}

package/server/services/keyed-mutex-service.mjs

@@ -0,0 +1,82 @@
+// ---------------------------------------------------------------------------
+// Keyed async mutex
+//
+// Node is single-threaded but not single-tasked: any handler that awaits can be
+// interleaved by another request. Anything that reads state, mutates processes
+// and writes state back needs to hold a lock across those awaits.
+//
+// Generic and dependency-free so it can be unit-tested and reused.
+// ---------------------------------------------------------------------------
+
+const DEFAULT_STALE_AFTER_MS = 120_000;
+
+export function createKeyedMutex({
+  nowMs = Date.now,
+  staleAfterMs = DEFAULT_STALE_AFTER_MS,
+  warn = console.warn,
+} = {}) {
+  /** @type {Map<string, { tail: Promise<unknown>, depth: number, acquiredAtMs: number }>} */
+  const entries = new Map();
+
+  function warnIfStale(key, entry) {
+    if (!entry || !staleAfterMs) return;
+    const heldForMs = nowMs() - entry.acquiredAtMs;
+    if (heldForMs > staleAfterMs) {
+      warn(`[keyed-mutex] "${key}" has been held for ${heldForMs}ms`);
+    }
+  }
+
+  function acquire(key) {
+    const existing = entries.get(key);
+    if (existing) {
+      warnIfStale(key, existing);
+      existing.depth += 1;
+      return existing;
+    }
+    const created = { tail: Promise.resolve(), depth: 1, acquiredAtMs: nowMs() };
+    entries.set(key, created);
+    return created;
+  }
+
+  function release(key, entry) {
+    entry.depth -= 1;
+    if (entry.depth <= 0 && entries.get(key) === entry) entries.delete(key);
+  }
+
+  async function runExclusive(key, fn) {
+    const lockKey = String(key || '');
+    const entry = acquire(lockKey);
+    const previous = entry.tail;
+    let releaseTurn;
+    entry.tail = new Promise((resolve) => { releaseTurn = resolve; });
+    try {
+      await previous;
+      entry.acquiredAtMs = nowMs();
+      return await fn();
+    } finally {
+      releaseTurn();
+      release(lockKey, entry);
+    }
+  }
+
+  async function tryRunExclusive(key, fn) {
+    const lockKey = String(key || '');
+    if (entries.has(lockKey)) {
+      warnIfStale(lockKey, entries.get(lockKey));
+      return { ok: false, busy: true, result: undefined };
+    }
+    const result = await runExclusive(lockKey, fn);
+    return { ok: true, busy: false, result };
+  }
+
+  return {
+    runExclusive,
+    tryRunExclusive,
+    isLocked: (key) => entries.has(String(key || '')),
+    size: () => entries.size,
+    stats: () => ({
+      held: entries.size,
+      waiting: [...entries.values()].reduce((total, entry) => total + Math.max(0, entry.depth - 1), 0),
+    }),
+  };
+}

package/server/services/mime-sniffer.mjs

@@ -0,0 +1,118 @@
+// Magic-byte sniffing for uploads.
+//
+// `/api/upload` receives the MIME type from a client-controlled header, so an
+// executable can claim to be `image/png`. Sniffing the real content type lets the
+// stored metadata reflect the bytes rather than the claim.
+
+const TEXTUAL_CLAIM_PATTERN = /^(text\/|application\/(json|xml|javascript|x-yaml|yaml)|image\/svg\+xml)/;
+
+function startsWith(buffer, bytes, offset = 0) {
+  if (!buffer || buffer.length < offset + bytes.length) return false;
+  for (let i = 0; i < bytes.length; i += 1) {
+    if (buffer[offset + i] !== bytes[i]) return false;
+  }
+  return true;
+}
+
+function asciiAt(buffer, offset, length) {
+  if (!buffer || buffer.length < offset + length) return '';
+  return buffer.toString('latin1', offset, offset + length);
+}
+
+const FTYP_BRANDS = new Map([
+  ['avif', 'image/avif'],
+  ['avis', 'image/avif'],
+  ['heic', 'image/heic'],
+  ['heix', 'image/heic'],
+  ['hevc', 'image/heic'],
+  ['heim', 'image/heic'],
+  ['mif1', 'image/heif'],
+  ['msf1', 'image/heif'],
+  ['qt  ', 'video/quicktime'],
+  ['isom', 'video/mp4'],
+  ['iso2', 'video/mp4'],
+  ['mp41', 'video/mp4'],
+  ['mp42', 'video/mp4'],
+  ['M4V ', 'video/x-m4v'],
+]);
+
+/**
+ * Returns the detected MIME type, or '' when the bytes are not recognised.
+ * Absence of a signature is not evidence of anything: plain text, CSV and source
+ * files legitimately have no magic bytes.
+ */
+export function sniffMimeType(buffer) {
+  if (!Buffer.isBuffer(buffer) || !buffer.length) return '';
+
+  if (startsWith(buffer, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return 'image/png';
+  if (startsWith(buffer, [0xff, 0xd8, 0xff])) return 'image/jpeg';
+  if (startsWith(buffer, [0x47, 0x49, 0x46, 0x38])) return 'image/gif';
+  if (startsWith(buffer, [0x42, 0x4d])) return 'image/bmp';
+  if (startsWith(buffer, [0x00, 0x00, 0x01, 0x00])) return 'image/x-icon';
+
+  if (asciiAt(buffer, 0, 4) === 'RIFF') {
+    const form = asciiAt(buffer, 8, 4);
+    if (form === 'WEBP') return 'image/webp';
+    if (form === 'WAVE') return 'audio/wav';
+    if (form === 'AVI ') return 'video/x-msvideo';
+  }
+
+  if (asciiAt(buffer, 4, 4) === 'ftyp') {
+    const brand = asciiAt(buffer, 8, 4);
+    if (FTYP_BRANDS.has(brand)) return FTYP_BRANDS.get(brand);
+  }
+
+  if (startsWith(buffer, [0x25, 0x50, 0x44, 0x46, 0x2d])) return 'application/pdf';
+  if (startsWith(buffer, [0x50, 0x4b, 0x03, 0x04])
+    || startsWith(buffer, [0x50, 0x4b, 0x05, 0x06])
+    || startsWith(buffer, [0x50, 0x4b, 0x07, 0x08])) return 'application/zip';
+  if (startsWith(buffer, [0x1f, 0x8b])) return 'application/gzip';
+  if (startsWith(buffer, [0x37, 0x7a, 0xbc, 0xaf, 0x27, 0x1c])) return 'application/x-7z-compressed';
+  if (startsWith(buffer, [0x52, 0x61, 0x72, 0x21, 0x1a, 0x07])) return 'application/vnd.rar';
+
+  // Executables. These are the reason sniffing exists at all.
+  if (startsWith(buffer, [0x4d, 0x5a])) return 'application/vnd.microsoft.portable-executable';
+  if (startsWith(buffer, [0x7f, 0x45, 0x4c, 0x46])) return 'application/x-elf';
+  if (startsWith(buffer, [0xca, 0xfe, 0xba, 0xbe])
+    || startsWith(buffer, [0xcf, 0xfa, 0xed, 0xfe])
+    || startsWith(buffer, [0xce, 0xfa, 0xed, 0xfe])) return 'application/x-mach-binary';
+  if (startsWith(buffer, [0x23, 0x21])) return 'text/x-shellscript';
+
+  return '';
+}
+
+export function normalizeClaimedMimeType(value) {
+  return String(value || '').trim().toLowerCase().split(';')[0].slice(0, 127);
+}
+
+/**
+ * Reconciles the client's claim against the sniffed reality. The sniffed type
+ * wins on disagreement so a disguised executable is stored as what it is, while
+ * unrecognised bytes leave the claim untouched.
+ */
+export function reconcileMimeType(claimed, sniffed) {
+  const claim = normalizeClaimedMimeType(claimed) || 'application/octet-stream';
+  const detected = normalizeClaimedMimeType(sniffed);
+
+  if (!detected) return { mimeType: claim, corrected: false, claimed: claim, sniffed: '' };
+  if (detected === claim) return { mimeType: claim, corrected: false, claimed: claim, sniffed: detected };
+
+  // JPEG has two spellings in the wild; treat them as agreement.
+  if ((claim === 'image/jpg' && detected === 'image/jpeg') || (claim === 'image/jpeg' && detected === 'image/jpg')) {
+    return { mimeType: 'image/jpeg', corrected: false, claimed: claim, sniffed: detected };
+  }
+
+  // Office/OpenDocument files and JARs are ZIP containers; the specific claim is
+  // more informative than the generic container type.
+  if (detected === 'application/zip' && claim !== 'application/octet-stream' && TEXTUAL_CLAIM_PATTERN.test(claim) === false) {
+    if (claim.includes('officedocument') || claim.includes('opendocument') || claim.includes('epub') || claim.includes('java-archive')) {
+      return { mimeType: claim, corrected: false, claimed: claim, sniffed: detected };
+    }
+  }
+
+  return { mimeType: detected, corrected: true, claimed: claim, sniffed: detected };
+}
+
+export function resolveUploadMimeType(buffer, claimedType) {
+  return reconcileMimeType(claimedType, sniffMimeType(buffer));
+}

package/server/services/oar-cli-helpers.mjs

@@ -0,0 +1,109 @@
+/**
+ * Pure helpers behind `oar setup` and `oar doctor` — everything here is
+ * deterministic and unit-testable; the interactive glue stays in bin/oar.js.
+ */
+
+import { randomBytes } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+
+export function generateAuthToken() {
+  return randomBytes(32).toString('base64url');
+}
+
+export function buildDefaultConfig({ token = generateAuthToken(), port = 3333, localhostOnly = true } = {}) {
+  return {
+    authToken: token,
+    port,
+    localhostOnly,
+    pollIntervalMs: 3000,
+    processingTimeoutMs: 600000,
+    conversationSessionMode: 'isolated',
+    updateCheck: true,
+  };
+}
+
+/** First non-internal IPv4 address, for the phone-facing URL when LAN access is on. */
+export function primaryLanAddress(interfaces = os.networkInterfaces()) {
+  for (const entries of Object.values(interfaces)) {
+    for (const entry of entries || []) {
+      if (entry && entry.family === 'IPv4' && !entry.internal) return entry.address;
+    }
+  }
+  return null;
+}
+
+export function relayUrl({ config, lanAddress = null } = {}) {
+  const host = !config?.localhostOnly && lanAddress ? lanAddress : 'localhost';
+  const token = String(config?.authToken || '').trim();
+  return `http://${host}:${config?.port || 3333}/?token=${encodeURIComponent(token)}`;
+}
+
+/**
+ * A systemd *user* unit for the relay server. The launcher is not used here —
+ * the service runs server.js directly with the same env the launcher would set,
+ * so a `gh copilot` session is not tied to the unit's lifetime.
+ */
+export function buildSystemdUnit({ nodeBin, packageRoot, configPath, dataDir, logDir }) {
+  return [
+    '[Unit]',
+    'Description=OAR — Open Agent Relay',
+    'After=network-online.target',
+    '',
+    '[Service]',
+    `ExecStart=${nodeBin} ${path.join(packageRoot, 'server', 'server.js')}`,
+    `Environment=COPILOT_WEB_RELAY_CONFIG=${configPath}`,
+    `Environment=COPILOT_WEB_RELAY_DATA_DIR=${dataDir}`,
+    `Environment=COPILOT_WEB_RELAY_LOG_DIR=${logDir}`,
+    'Restart=on-failure',
+    'RestartSec=5',
+    '',
+    '[Install]',
+    'WantedBy=default.target',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Provider CLIs `oar doctor` probes, with the args that answer fast. Cursor is
+ * deliberately absent: the relay drives it through the bundled @cursor/sdk npm
+ * package and never invokes a cursor-agent binary.
+ */
+export const DOCTOR_PROBES = Object.freeze([
+  { id: 'gh (Copilot)', binary: 'gh', args: ['--version'] },
+  { id: 'claude', binary: 'claude', args: ['--version'] },
+  { id: 'grok', binary: 'grok', args: ['--version'] },
+]);
+
+export function renderDoctorReport({
+  version,
+  nodeVersion,
+  platform,
+  layout,
+  configPath,
+  config,
+  dbPath,
+  dbSizeBytes,
+  probes = [],
+}) {
+  const yesNo = (v) => (v ? 'yes' : 'no');
+  const lines = [
+    `OAR ${version}`,
+    `  node          : ${nodeVersion} (${platform})`,
+    `  mode          : ${layout?.checkout ? 'git checkout' : 'global install'}`,
+    `  state root    : ${layout?.checkout ? '(repo-local server/)' : layout?.root}`,
+    `  config        : ${configPath}${config ? '' : '  (missing — run: oar setup)'}`,
+  ];
+  if (config) {
+    lines.push(`  port          : ${config.port ?? 3333} (localhostOnly: ${yesNo(config.localhostOnly !== false)})`);
+    lines.push(`  auth token    : ${String(config.authToken || '').trim() ? 'set' : 'MISSING'}`);
+    const tunnel = config.cloudflaredTunnel || {};
+    lines.push(`  tunnel        : ${tunnel.enabled === true || tunnel.mode === 'managed' ? 'managed' : 'disabled'}`);
+  }
+  lines.push(`  database      : ${dbSizeBytes !== null ? `${dbPath} (${(dbSizeBytes / 1048576).toFixed(1)} MB)` : `${dbPath} (not created yet)`}`);
+  lines.push('  provider CLIs :');
+  for (const probe of probes) {
+    lines.push(`    ${probe.id.padEnd(14)}: ${probe.ok ? probe.version || 'installed' : 'not found'}`);
+  }
+  return lines.join('\n');
+}