@prplkane/roundtable 0.0.0-stage → 0.6.4

package/src/diagnostics.js

@@ -0,0 +1,133 @@
+// Local support data uses an allowlist, never error messages, request bodies or CLI output.
+import { mkdirSync, appendFileSync, readFileSync, renameSync, lstatSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { safeProgress } from './progress.js';
+
+const CODES = new Set(['request-failed', 'provider-failed', 'call-cancelled', 'reply-invalid', 'engine-failed', 'export-failed',
+  'transcript-warning', 'status-failed', 'storage-failed', 'server-crash', 'server-start',
+  'browser-network', 'browser-timeout', 'browser-response', 'browser-error', 'browser-rejection', 'browser-stream', 'browser-validation']);
+export const BROWSER_CODES = new Set([...CODES].filter((c) => c.startsWith('browser-')));
+const ACTIONS = new Set(['setup', 'pick-folder', 'history', 'delete', 'clear', 'clear-finished', 'preflight', 'preview', 'create', 'events', 'state', 'continue', 'finish', 'stop', 'hold',
+  'resume', 'export', 'synthesize', 'accept', 'pools', 'terms', 'diagnostics', 'catalogue', 'quota', 'calibration', 'startup', 'shutdown', 'health', 'unknown']);
+const KINDS = new Set(['quota', 'throttled', 'auth', 'missing', 'network', 'timeout', 'killed', 'format', 'budget', 'policy', 'compatibility', 'other']);
+const SYSTEM_CODES = new Set(['STALL', 'ENOENT', 'EACCES', 'EPERM', 'ENOSPC', 'EIO', 'EISDIR', 'EROFS', 'EMFILE', 'ENFILE',
+  'TOOL_POLICY', 'OUTPUT_LIMIT', 'PROVIDER_PROTOCOL', 'CLI_EXIT', 'CLI_FAILURE', 'ISOLATION_REQUIRED', 'TERMS_ACK_REQUIRED', 'RESEARCH_LIMIT', 'RESEARCH_INVALID',
+  'EADDRINUSE', 'ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'TIMEOUT', 'KILLED', 'TRANSCRIPT_CORRUPT', 'TRANSCRIPT_TAIL',
+  'SEAT_LENS_REQUIRED', 'SEAT_LENS_DUPLICATE', 'SEAT_MOOD_REQUIRED']);
+const FILES = new Set(['server.js', 'store.js', 'history.js', 'engine.js', 'export.js', 'validate.js', 'estimate.js',
+  'seats.js', 'preflight.js', 'diagnostics.js', 'snapshot.js', 'review-view.js', 'ui/app.js', 'ui/help.js', 'adapters/common.js', 'adapters/spawn.js',
+  'adapters/endpoint.js', 'adapters/claude.js', 'adapters/codex.js', 'adapters/agy.js']);
+const ID = /^RT-[a-f0-9]{16}$/;
+const integer = (n, max) => Number.isInteger(n) && n >= 0 && n <= max;
+export const diagnosticId = () => `RT-${randomBytes(8).toString('hex')}`;
+
+export function diagnosticAction(pathname) {
+  if (pathname === '/api/seats') return 'setup';
+  if (pathname === '/api/health') return 'health';
+  if (pathname === '/api/shutdown') return 'shutdown';
+  if (pathname === '/api/debates') return 'history';
+  if (pathname === '/api/preflight') return 'preflight';
+  if (pathname === '/api/preview') return 'preview';
+  if (/^\/api\/pools\/[a-z]+$/.test(pathname)) return 'pools';
+  if (/^\/api\/terms\/[a-z]+$/.test(pathname)) return 'terms';
+  if (pathname.startsWith('/api/diagnostics')) return 'diagnostics';
+  const match = /^\/api\/debates\/[^/]+\/([a-z]+)$/.exec(pathname);
+  return match && ACTIONS.has(match[1]) ? match[1] : 'unknown';
+}
+
+// Project only fixed categories and bounded numbers. Even an endpoint echoing a secret cannot
+// put it in this log. Source locations omit function names and absolute filesystem paths.
+function fields(input) {
+  const out = { code: CODES.has(input?.code) ? input.code : 'request-failed',
+    action: ACTIONS.has(input?.action) ? input.action : 'unknown' };
+  if (['claude', 'codex', 'agy', 'api'].includes(input?.vendor)) out.vendor = input.vendor;
+  if (KINDS.has(input?.kind)) out.kind = input.kind;
+  const progress = safeProgress(input?.progress);
+  if (Object.keys(progress).length) out.progress = progress;
+  if (SYSTEM_CODES.has(input?.systemCode)) out.systemCode = input.systemCode;
+  if (['lens', 'moodText'].includes(input?.field)) out.field = input.field;
+  if (['human', 'wall-clock'].includes(input?.cancelReason)) out.cancelReason = input.cancelReason;
+  for (const [key, max] of Object.entries({ seatIndex: 7, status: 599, round: 100, line: 1_000_000, column: 1_000_000 })) {
+    if (integer(input?.[key], max)) out[key] = input[key];
+  }
+  if (Array.isArray(input?.frames)) out.frames = input.frames.filter((f) => FILES.has(f?.file) && integer(f.line, 1_000_000) && integer(f.column, 1_000_000))
+    .slice(0, 5).map(({ file, line, column }) => ({ file, line, column }));
+  return out;
+}
+
+export function diagnosticError(error) {
+  const frames = [];
+  for (const m of String(error?.stack || '').matchAll(/[\\/]src[\\/]([\w./\\-]+):(\d+):(\d+)/g)) {
+    const file = m[1].replaceAll('\\', '/');
+    if (FILES.has(file)) frames.push({ file, line: Number(m[2]), column: Number(m[3]) });
+  }
+  return { systemCode: error?.code, frames: frames.slice(0, 5) };
+}
+
+export function validateBrowserDiagnostics(body) {
+  if (!Array.isArray(body?.events) || body.events.length > 20) throw new Error('Send at most 20 diagnostic events.');
+  return body.events.map((e) => {
+    if (!e || !ID.test(e.id) || !BROWSER_CODES.has(e.code) || !ACTIONS.has(e.action)) throw new Error('Invalid diagnostic event.');
+    // Browser callers cannot impersonate a server/provider event or inject stack frames.
+    return { id: e.id, ...fields({ code: e.code, action: e.action, status: e.status, line: e.line, column: e.column, seatIndex: e.seatIndex, field: e.field }) };
+  });
+}
+
+export function createDiagnostics(root, { mode = 'live', version = 'unknown', maxBytes = 256 * 1024,
+  maxPerMinute = 120, now = Date.now, warn = (s) => console.warn(s) } = {}) {
+  const dir = path.join(root, '_diagnostics');
+  const current = path.join(dir, 'events.jsonl'), previous = path.join(dir, 'previous.jsonl');
+  const environment = { mode: mode === 'demo' ? 'demo' : 'live',
+    version: /^\d+\.\d+\.\d+$/.test(version) ? version : 'unknown', platform: process.platform, nodeMajor: Number(process.versions.node.split('.')[0]) };
+  let available = true, dropped = 0, windowAt = now(), count = 0;
+  const safeFile = (file) => {
+    let stat;
+    try { stat = lstatSync(file); } catch (e) { if (e.code === 'ENOENT') return 0; throw e; }
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('Invalid diagnostic file.');
+    return stat.size;
+  };
+  function fail() {
+    if (available) warn('[diagnostics] Could not save the local error log. Check free disk space and data-folder permissions.');
+    available = false;
+  }
+  function write(input, error) {
+    const id = ID.test(input?.id) ? input.id : diagnosticId();
+    if (now() - windowAt >= 60_000) { windowAt = now(); count = 0; }
+    if (++count > maxPerMinute) { dropped++; return { id, saved: false }; }
+    const entry = { id, at: new Date(now()).toISOString(), ...environment, ...fields({ ...input, ...diagnosticError(error) }) };
+    try {
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+      if (lstatSync(dir).isSymbolicLink()) throw new Error('Invalid diagnostic directory.');
+      const line = JSON.stringify(entry) + '\n';
+      const size = safeFile(current);
+      if (size > maxBytes || Buffer.byteLength(line) > maxBytes) throw new Error('Oversized diagnostic file.');
+      if (size + Buffer.byteLength(line) > maxBytes && existsSync(current)) { safeFile(previous); renameSync(current, previous); }
+      appendFileSync(current, line, { mode: 0o600 });
+      available = true;
+      return { id, saved: true };
+    } catch { fail(); return { id, saved: false }; }
+  }
+  function read() {
+    const entries = [];
+    try {
+      if (existsSync(dir) && lstatSync(dir).isSymbolicLink()) throw new Error('Invalid diagnostic directory.');
+      for (const file of [previous, current]) {
+        if (!existsSync(file)) continue;
+        if (safeFile(file) > maxBytes) throw new Error('Oversized diagnostic file.');
+        for (const line of readFileSync(file, 'utf8').split('\n')) {
+          try {
+            const e = JSON.parse(line);
+            if (!ID.test(e.id) || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(e.at) || !CODES.has(e.code)) continue;
+            entries.push({ id: e.id, at: e.at, ...fields(e), mode: e.mode === 'demo' ? 'demo' : 'live',
+              version: /^\d+\.\d+\.\d+$/.test(e.version) ? e.version : 'unknown',
+              platform: ['win32', 'darwin', 'linux'].includes(e.platform) ? e.platform : 'other',
+              ...(integer(e.nodeMajor, 1000) ? { nodeMajor: e.nodeMajor } : {}) });
+          } catch { /* an interrupted diagnostic line is not a debate record */ }
+        }
+      }
+    } catch { fail(); }
+    return { format: 'roundtable-diagnostics-v1', generatedAt: new Date(now()).toISOString(), ...environment, available, dropped, entries };
+  }
+  return { write, read, status: () => ({ available, dropped }) };
+}

package/src/doctor.js

@@ -0,0 +1,101 @@
+// node src/doctor.js [--live] [--profile <name>] [--vendor <name>] [--allow-limited-isolation] [--acknowledge-terms-risk]
+//
+// What this machine can seat. Per vendor: the binary and where it was found, its version, the
+// models and effort levels the setup screen will offer, the live pool read where one exists
+// (codex, agy), and, with --live, one trivial model call through the adapter: logged in or not,
+// what it answered, whether it reached for tools (the guard must see false on a plain reply),
+// tokens and the quota it reported (claude). --profile <name> prints how to log that profile
+// in for each vendor. A vendor with a terms notice (config.js terms: Antigravity) is sent nothing,
+// not its model list or pool read either, without --acknowledge-terms-risk; only its CLI's
+// --version still runs.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ADAPTERS } from './adapters/config.js';
+import { resolveBinary, runProcess, profileHome, dataDir } from './adapters/spawn.js';
+import { dataDirectory } from './history.js';
+import { paintVendor } from './terminal.js';
+
+// Shell lines that log a profile in, per vendor, for the platform the user is on. Pure.
+export function loginInstructions(vendor, profile, where = {}) {
+  const a = ADAPTERS[vendor];
+  if (!a?.home) return [`${a?.label || vendor}: the CLI documents no state-directory variable, so a profile cannot be separated from the terminal's login.`];
+  const dir = profileHome(vendor, profile, where);
+  const login = { claude: 'claude /login', codex: 'codex login' }[vendor] || `${a.binary} login`;
+  const platform = where.platform || process.platform;
+  const set = platform === 'win32' ? [`set ${a.home.env}=${dir}`, login] : [`${a.home.env}="${dir}" ${login}`];
+  return [`${a.label} profile "${profile}" lives in ${dir}`, ...set.map((l) => `  ${l}`), '  (PowerShell: $env:' + a.home.env + ' = "' + dir + '"; ' + login + ')'];
+}
+
+async function version(bin, vendor) {
+  try {
+    const r = await runProcess(bin, ['--version'], { timeoutMs: 20_000 });
+    const line = (r.stdout + r.stderr).trim().split('\n').find((l) => /\d+\.\d+/.test(l)) || (r.stdout + r.stderr).trim().split('\n')[0];
+    return line ? line.trim().slice(0, 80) : `exit ${r.code}`;
+  } catch (e) { return `(${e.message})`; }
+}
+
+const flag = (name) => { const i = process.argv.indexOf(`--${name}`); return i > 0 ? (process.argv[i + 1] || true) : null; };
+
+async function main() {
+  const live = process.argv.includes('--live');
+  const allowLimitedIsolation = process.argv.includes('--allow-limited-isolation');
+  const acknowledgeTermsRisk = process.argv.includes('--acknowledge-terms-risk');
+  const profile = flag('profile');
+  const only = flag('vendor');
+  const { vendorCatalogue } = await import('./adapters/catalogue.js');
+  const { adapters, quotaReaders } = await import('./adapters/index.js');
+  const catalogue = await vendorCatalogue(ADAPTERS.agy.terms && !acknowledgeTermsRisk ? { agyModels: async () => [] } : {});
+  console.log(`roundtable doctor  (${process.platform}, node ${process.version}, data dir ${dataDir()})`);
+  console.log(live ? 'live: one trivial model call per vendor' : 'static only; add --live for one trivial model call per vendor');
+  const missing = []; // CLIs not on PATH: one line at the end, a full block only when asked for by --vendor
+  for (const [vendor, a] of Object.entries(ADAPTERS)) {
+    if (only && only !== vendor) continue;
+    let bin = null, lookup = null;
+    if (a.kind === 'cli') try { bin = resolveBinary(a.binary, a.npmBin); } catch (e) { lookup = e.message; }
+    if (a.kind === 'cli' && !bin && only !== vendor) { missing.push(`${a.label} (${a.binary})`); continue; }
+    console.log(`\n== ${paintVendor(a)} (${vendor})  pool: ${a.pool}`);
+    if (a.kind === 'api') { // no binary: everything about an endpoint seat is on its card
+      console.log('  seat it    on the board: base URL (…/v1), model id, and for a hosted API the NAME of the key variable');
+      console.log(`  efforts    ${a.effortLevels.join(', ')}  (reasoning_effort, sent only when set)`);
+      console.log(`  read-only  ${a.readOnly}`);
+      console.log(`  isolation  ${a.isolation}`);
+      continue;
+    }
+    const held = !!a.terms && !acknowledgeTermsRisk;
+    const heldLine = `held: nothing is sent to ${a.binary} without --acknowledge-terms-risk`;
+    console.log(`  binary     ${bin ? bin.prefix.length ? `${bin.prefix[0]} (via node)` : bin.file : `NOT FOUND: ${lookup}`}`);
+    if (bin) console.log(`  version    ${await version(bin, vendor)}`);
+    const c = catalogue[vendor];
+    if (held) console.log(`  models     ${heldLine}`);
+    else console.log(`  models     ${c.models.length ? c.models.map((m) => m.id).join(', ') : '(free text; the CLI lists none)'}${c.defaultModel ? `  default: ${c.defaultModel}` : ''}`);
+    console.log(`  efforts    ${c.efforts.join(', ')}${c.defaultEffort ? `  default: ${c.defaultEffort}` : ''}${c.effortInModel ? '  (a model id may carry the level)' : ''}`);
+    console.log(`  read-only  ${a.readOnly}`);
+    console.log(`  isolation  ${a.isolation}`);
+    if (a.terms) console.log(`  terms      ${a.terms.notice} (${a.terms.url}, checked ${a.terms.read})`);
+    if (held && quotaReaders[vendor]) console.log(`  pool read  ${heldLine}`);
+    else if (quotaReaders[vendor]) {
+      const q = bin ? await quotaReaders[vendor]() : null;
+      console.log(`  pool read  ${q ? q.windows.map((w) => `${w.label} ${(w.used * 100).toFixed(0)}% used`).join(', ') + (q.plan ? ` (plan ${q.plan})` : '') : 'no figure (not logged in, or the read failed)'}`);
+    } else console.log(`  pool read  ${a.quota === 'per-call' ? 'rides on each reply (shown with --live)' : `none headless; usage page ${a.usageUrl}`}`);
+    if (live && bin && held) console.log(`  live call  skipped: ${heldLine}, and then only if your plan allows it`);
+    else if (live && bin && a.limitedIsolation && !allowLimitedIsolation) console.log('  live call  skipped: Antigravity has limited isolation. Add --allow-limited-isolation to consent, or use another provider.');
+    if (live && bin && !held && (!a.limitedIsolation || allowLimitedIsolation)) {
+      const t0 = Date.now();
+      try {
+        const r = await adapters[vendor]('Reply with exactly the word pong.', null, { timeoutMs: 180_000, cwd: path.join(dataDirectory(), '_doctor', vendor), allowLimitedIsolation, acknowledgeTermsRisk });
+        console.log(`  logged in  yes (${Date.now() - t0} ms)  reply: ${JSON.stringify(r.text.slice(0, 40))}  session: ${r.sessionId}`);
+        console.log(`  usedTools  ${r.usedTools}`);
+        const cost = r.usage?.cost ?? r.cost;
+        console.log(`  usage      ${r.usage ? `in ${r.usage.input} cache ${r.usage.cacheRead + r.usage.cacheWrite} out ${r.usage.output} think ${r.usage.thinking}` : 'tokens unknown'}${cost != null ? ` $${cost.toFixed(2)}` : ''}`);
+        if (r.quota) console.log(`  windows    ${r.quota.windows.map((w) => `${w.label} ${(w.used * 100).toFixed(0)}% used`).join(', ')}`);
+      } catch (e) { console.log(`  live call  failed (${e.kind || 'other'}, ${Date.now() - t0} ms): ${e.message.slice(0, 200)}`); }
+    }
+    if (profile) for (const l of loginInstructions(vendor, profile)) console.log(`  profile    ${l}`);
+  }
+  if (missing.length) console.log(`\nnot installed: ${missing.join(', ')}; install and sign in to seat them, or add --vendor <name> for that block`);
+  if (!profile) console.log('\nadd --profile <name> to see how to log a named account profile in for each vendor');
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((e) => { console.error(e); process.exit(1); });
+}