@brunobracaioli/aibrain 0.2.0-beta.1 → 0.3.0-beta.13

package/dist/codex-diagnostics.mjs

@@ -0,0 +1,426 @@
+// @ts-check
+
+import { createHash } from 'node:crypto';
+import { chmod, lstat, mkdir, open, readFile, readdir, rename, rm, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export const CODEX_DIAGNOSTIC_SCHEMA_VERSION = 1;
+export const CODEX_DIAGNOSTIC_ADAPTER_VERSION = '0.3.0-beta.13';
+export const CODEX_DIAGNOSTIC_MAX_LOG_BYTES = 512 * 1024;
+export const CODEX_DIAGNOSTIC_MAX_LOG_FILES = 3;
+export const CODEX_DIAGNOSTIC_MAX_RECORDS = 128;
+const MAX_DIAGNOSTIC_BYTES = 256 * 1024 * 1024;
+
+const LOCK_WAIT_MS = 250;
+const LOCK_STALE_MS = 30_000;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+const VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/u;
+const STAGES = new Set([
+  'capture',
+  'budget',
+  'selection',
+  'notes',
+  'native',
+  'recovery',
+  'transport',
+  'unknown',
+]);
+const PHASES = new Set([
+  'capture',
+  'budget',
+  'selection',
+  'selection_accepted',
+  'candidate_window_bounded',
+  'notes',
+  'notes_written',
+  'native',
+  'native_started',
+  'native_item_completed',
+  'native_completed',
+  'recovery',
+  'recovery_attached',
+  'recovery_uncertain',
+  'transport',
+  'operation_failed',
+  'thread_failure',
+  'transport_end',
+  'process_error',
+  'transport_close',
+]);
+const REASONS = new Set([
+  'requested',
+  'completed',
+  'candidate_window_bounded',
+  'candidate_over_bound',
+  'protected_over_bound',
+  'history_unavailable',
+  'stale_snapshot',
+  'unavailable',
+  'admission_denied',
+  'invalid_response',
+  'request_failed',
+  'source_changed',
+  'timeout',
+  'thread_closed',
+  'protocol_error',
+  'capture_size_exceeded',
+  'capture_item_count_exceeded',
+  'private_storage_failed',
+  'storage_capacity_exceeded',
+  'attached',
+  'uncertain',
+  'disconnected',
+]);
+/* Kept for records produced before the Codex stage contract was closed. */
+const LEGACY_STAGES = new Set([
+  'connected',
+  'thread_read',
+  'selection',
+  'selection_accepted',
+  'notes_persistence',
+  'notes_written',
+  'native_compaction',
+  'native_completed',
+  'recovery_attachment',
+  'recovery_attached',
+  'recovery_uncertain',
+  'thread_failure',
+  'transport_end',
+  'process_error',
+  'transport_close',
+  'unknown',
+]);
+const ERROR_CODES = new Set([
+  'rpc_error',
+  'request_failed',
+  'request_timeout',
+  'admission_denied',
+  'shared_admission_denied',
+  'account_request_limit',
+  'account_token_limit',
+  'global_request_limit',
+  'global_token_limit',
+  'account_in_flight',
+  'database_unavailable',
+  'unknown',
+]);
+
+/** @param {unknown} value @returns {number|null} */
+function safeRpcCode(value) {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value)) return null;
+  return value >= -32_768 && value <= 32_767 ? value : null;
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function record(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** @param {string} value */
+function pseudonym(value) {
+  return createHash('sha256').update(JSON.stringify({ value }), 'utf8').digest('hex').slice(0, 32);
+}
+
+/** @param {string} value */
+function safeVersion(value) {
+  return value.length <= 64 && VERSION.test(value);
+}
+
+/** @param {string} target @param {boolean} allowMissing */
+async function assertNoSymlinkAncestors(target, allowMissing) {
+  const absolute = resolve(target);
+  let current = absolute.startsWith('/') ? '/' : '';
+  for (const part of absolute.split('/').filter(Boolean)) {
+    current = current === '/' ? `/${part}` : join(current, part);
+    try {
+      const entry = await lstat(current);
+      if (entry.isSymbolicLink()) throw new Error('codex_diagnostics_symlink_rejected');
+    } catch (error) {
+      if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+        if (!allowMissing) throw new Error('codex_diagnostics_path_missing');
+        break;
+      }
+      throw error;
+    }
+  }
+}
+
+/** @param {string} path @param {boolean} [create] */
+async function ownedDirectory(path, create = true) {
+  const target = resolve(path);
+  await assertNoSymlinkAncestors(target, create);
+  if (create) await mkdir(target, { recursive: true, mode: 0o700 });
+  await assertNoSymlinkAncestors(target, false);
+  const entry = await lstat(target);
+  if (!entry.isDirectory() || entry.isSymbolicLink())
+    throw new Error('codex_diagnostics_path_invalid');
+  if (typeof process.getuid === 'function' && entry.uid !== process.getuid())
+    throw new Error('codex_diagnostics_owner_mismatch');
+  await chmod(target, 0o700);
+  return target;
+}
+
+/** @param {string} path */
+async function ownedFile(path) {
+  const entry = await lstat(path);
+  if (!entry.isFile() || entry.isSymbolicLink()) throw new Error('codex_diagnostics_file_invalid');
+  if (typeof process.getuid === 'function' && entry.uid !== process.getuid())
+    throw new Error('codex_diagnostics_owner_mismatch');
+  if ((entry.mode & 0o077) !== 0) throw new Error('codex_diagnostics_file_permissions_invalid');
+  if (entry.size > CODEX_DIAGNOSTIC_MAX_LOG_BYTES)
+    throw new Error('codex_diagnostics_file_size_invalid');
+  return entry;
+}
+
+/** @param {string} path */
+/** @param {string} path @param {() => Promise<unknown>} task */
+async function withLock(path, task) {
+  const started = Date.now();
+  while (true) {
+    try {
+      const handle = await open(
+        path,
+        constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+        0o600,
+      );
+      try {
+        return await task();
+      } finally {
+        await handle.close();
+        await rm(path, { force: true });
+      }
+    } catch (error) {
+      if (!(error instanceof Error) || !('code' in error) || error.code !== 'EEXIST') throw error;
+      try {
+        const lock = await stat(path);
+        if (Date.now() - lock.mtimeMs > LOCK_STALE_MS) await rm(path, { force: true });
+      } catch {
+        // A concurrent owner can remove the lock between stat and retry.
+      }
+      if (Date.now() - started >= LOCK_WAIT_MS) throw new Error('codex_diagnostics_lock_timeout');
+      await new Promise((resolvePromise) => setTimeout(resolvePromise, 10));
+    }
+  }
+}
+
+/** @param {string} directory @param {Record<string, unknown>[]} records */
+async function appendRecords(directory, records) {
+  const lock = join(directory, '.events.lock');
+  return withLock(lock, async () => {
+    const active = join(directory, 'events.0.jsonl');
+    let size = 0;
+    try {
+      size = (await ownedFile(active)).size;
+    } catch (error) {
+      if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') throw error;
+    }
+    const payload = records.map((item) => `${JSON.stringify(item)}\n`).join('');
+    if (Buffer.byteLength(payload, 'utf8') > CODEX_DIAGNOSTIC_MAX_LOG_BYTES)
+      throw new Error('codex_diagnostics_record_too_large');
+    if (size + Buffer.byteLength(payload, 'utf8') > CODEX_DIAGNOSTIC_MAX_LOG_BYTES) {
+      for (let index = CODEX_DIAGNOSTIC_MAX_LOG_FILES - 1; index >= 1; index -= 1) {
+        const from = join(directory, `events.${index - 1}.jsonl`);
+        const to = join(directory, `events.${index}.jsonl`);
+        try {
+          await ownedFile(from);
+          await rename(from, to);
+        } catch (error) {
+          if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT')
+            throw error;
+        }
+      }
+      size = 0;
+    }
+    const handle = await open(
+      active,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | constants.O_NOFOLLOW,
+      0o600,
+    );
+    try {
+      await handle.write(payload, undefined, 'utf8');
+    } finally {
+      await handle.close();
+    }
+    await chmod(active, 0o600);
+    return records.length;
+  });
+}
+
+/** @param {unknown} event @param {string} clientVersion @param {string} sessionKey @param {string} instanceKey @param {() => number} now */
+function normalize(event, clientVersion, sessionKey, instanceKey, now) {
+  const input = record(event) ? event : {};
+  /** @type {Record<string, string>} */
+  const phaseStage = {
+    capture: 'capture',
+    budget: 'budget',
+    selection: 'selection',
+    selection_accepted: 'selection',
+    candidate_window_bounded: 'selection',
+    notes: 'notes',
+    notes_written: 'notes',
+    native: 'native',
+    native_started: 'native',
+    native_item_completed: 'native',
+    native_completed: 'native',
+    recovery: 'recovery',
+    recovery_attached: 'recovery',
+    recovery_uncertain: 'recovery',
+    transport: 'transport',
+    operation_failed: 'native',
+    thread_failure: 'native',
+    transport_end: 'transport',
+    process_error: 'transport',
+    transport_close: 'transport',
+  };
+  const rawStage =
+    typeof input.stage === 'string'
+      ? input.stage
+      : typeof input.phase === 'string'
+        ? phaseStage[input.phase]
+        : undefined;
+  const stage =
+    rawStage !== undefined && STAGES.has(rawStage)
+      ? rawStage
+      : rawStage !== undefined && LEGACY_STAGES.has(rawStage)
+        ? 'native'
+        : 'unknown';
+  const rawPhase = typeof input.phase === 'string' ? input.phase : undefined;
+  const phase = rawPhase !== undefined && PHASES.has(rawPhase) ? rawPhase : undefined;
+  const rawReason =
+    typeof input.reason === 'string'
+      ? input.reason
+      : typeof input.reasonCode === 'string'
+        ? input.reasonCode
+        : undefined;
+  const reason = rawReason !== undefined && REASONS.has(rawReason) ? rawReason : undefined;
+  const rawError = typeof input.errorCode === 'string' ? input.errorCode : undefined;
+  const errorCode =
+    rawError !== undefined && ERROR_CODES.has(rawError)
+      ? rawError
+      : rawError === undefined
+        ? undefined
+        : 'unknown';
+  const observedAt = new Date(now()).toISOString();
+  /** @type {Record<string, unknown>} */
+  const output = {
+    schema_version: CODEX_DIAGNOSTIC_SCHEMA_VERSION,
+    client: 'codex-cli',
+    adapter_version: CODEX_DIAGNOSTIC_ADAPTER_VERSION,
+    session_key: sessionKey,
+    instance_id: instanceKey,
+    stage,
+    observed_at: observedAt,
+  };
+  if (phase !== undefined) output.phase = phase;
+  if (reason !== undefined) output.reason = reason;
+  if (errorCode !== undefined) output.error_code = errorCode;
+  const rpcCode = safeRpcCode(input.rpcCode ?? input.rpc_code);
+  if (rpcCode !== null) output.rpc_code = rpcCode;
+  if (safeVersion(clientVersion)) output.client_version = clientVersion;
+  const operationId =
+    typeof input.operation_id === 'string' ? input.operation_id : input.operationId;
+  if (typeof operationId === 'string' && UUID.test(operationId)) output.operation_id = operationId;
+  const correlationId = input.correlation_id;
+  if (typeof correlationId === 'string' && correlationId.length > 0 && correlationId.length <= 128)
+    output.correlation_id = correlationId;
+  /** @type {[string, string, number][]} */
+  const numericFields = [
+    ['batchCount', 'batch_count', 4],
+    ['batch_count', 'batch_count', 4],
+    ['selectedCount', 'selected_count', 1_000_000],
+    ['deferredCount', 'deferred_count', 1_000_000],
+    ['pageCount', 'page_count', 32],
+    ['captureBytes', 'capture_bytes', MAX_DIAGNOSTIC_BYTES],
+    ['durationMs', 'duration_ms', 86_400_000],
+  ];
+  for (const [source, target, max] of numericFields) {
+    const value = input[source];
+    if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= max)
+      output[target] = value;
+  }
+  if (record(input.counts)) {
+    /** @type {Record<string, number>} */
+    const counts = {};
+    for (const [key, value] of Object.entries(input.counts)) {
+      if (
+        /^[a-z_]{1,48}$/u.test(key) &&
+        typeof value === 'number' &&
+        Number.isSafeInteger(value) &&
+        value >= 0 &&
+        value <= (/_bytes$/u.test(key) ? MAX_DIAGNOSTIC_BYTES : 1_000_000)
+      )
+        counts[key] = value;
+    }
+    if (Object.keys(counts).length > 0) output.counts = counts;
+  }
+  return output;
+}
+
+/**
+ * Create the private, content-free sink used by the Codex adapter. The returned
+ * callback is deliberately fire-and-forget: logger failures are swallowed and
+ * never write to the app-server stdout protocol or affect compaction.
+ * @param {{stateDir: string, sessionId: string, instanceId?: string, clientVersion: string, enabled?: boolean, now?: () => number}} options
+ */
+export function createCodexDiagnosticSink(options) {
+  const directoryPromise =
+    options.enabled === false
+      ? null
+      : ownedDirectory(join(resolve(options.stateDir), 'diagnostics', 'codex'));
+  const sessionKey = pseudonym(options.sessionId);
+  const instanceKey = pseudonym(options.instanceId ?? `${process.pid}`);
+  const now = options.now ?? Date.now;
+  let queue = Promise.resolve();
+  /** @param {unknown} event */
+  const sink = (event) => {
+    if (directoryPromise === null) return;
+    const normalized = normalize(event, options.clientVersion, sessionKey, instanceKey, now);
+    queue = queue
+      .then(async () => {
+        const directory = await directoryPromise;
+        await appendRecords(directory, [normalized]);
+      })
+      .catch(() => undefined);
+  };
+  sink.flush = () => queue;
+  return sink;
+}
+
+/** @param {string} stateDir @param {number} [tail] */
+export async function readCodexDiagnostics(stateDir, tail = 20) {
+  const root = resolve(stateDir);
+  const directory = await ownedDirectory(join(root, 'diagnostics', 'codex'), false).catch(
+    (error) => {
+      if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return null;
+      if (error instanceof Error && error.message === 'codex_diagnostics_path_missing') return null;
+      throw error;
+    },
+  );
+  if (directory === null) return [];
+  const files = (await readdir(directory))
+    .filter((file) => /^events\.[0-2]\.jsonl$/u.test(file))
+    .sort((a, b) => Number(b[7]) - Number(a[7]));
+  /** @type {Record<string, unknown>[]} */
+  const records = [];
+  for (const file of files) {
+    const path = join(directory, file);
+    await ownedFile(path);
+    for (const line of (await readFile(path, 'utf8')).split('\n').filter(Boolean)) {
+      try {
+        const value = JSON.parse(line);
+        if (
+          record(value) &&
+          value.schema_version === CODEX_DIAGNOSTIC_SCHEMA_VERSION &&
+          value.client === 'codex-cli'
+        )
+          records.push(value);
+      } catch {
+        // Ignore malformed private lines without exposing their contents.
+      }
+    }
+  }
+  return records.slice(-Math.max(1, Math.min(CODEX_DIAGNOSTIC_MAX_RECORDS, tail)));
+}
+
+export const createPrivateCodexDiagnosticSink = createCodexDiagnosticSink;