@brunobracaioli/aibrain 0.3.0-beta.7 → 0.4.0-beta.2

package/dist/codex-compatibility.mjs

@@ -0,0 +1,481 @@
+// @ts-check
+
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { mkdtemp, open, rm, lstat } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import fingerprint from './codex-protocol-fingerprint.json' with { type: 'json' };
+
+const MAX_OUTPUT_BYTES = 64 * 1024;
+const MAX_SCHEMA_BYTES = 8 * 1024 * 1024;
+const MAX_SCHEMA_SET_BYTES = 24 * 1024 * 1024;
+const MAX_SCHEMA_DEPTH = 96;
+const MAX_SCHEMA_NODES = 250_000;
+const ROOTS = Object.keys(fingerprint.roots);
+const PAGINATION_CONTRACT = fingerprint.consumed_pagination ?? null;
+const PAGINATION_CONTRACT_VALID =
+  PAGINATION_CONTRACT === null ||
+  (PAGINATION_CONTRACT.method === 'thread/turns/list' &&
+    PAGINATION_CONTRACT.request_schema === 'v2/ThreadTurnsListParams.json' &&
+    PAGINATION_CONTRACT.response_schema === 'v2/ThreadTurnsListResponse.json' &&
+    PAGINATION_CONTRACT.request_schema_sha256 ===
+      fingerprint.roots[PAGINATION_CONTRACT.request_schema]?.sha256 &&
+    PAGINATION_CONTRACT.response_schema_sha256 ===
+      fingerprint.roots[PAGINATION_CONTRACT.response_schema]?.sha256 &&
+    typeof PAGINATION_CONTRACT.graph_sha256 === 'string' &&
+    PAGINATION_CONTRACT.graph_sha256.length === 64);
+const QUALIFIED_VERSIONS = new Set(['0.161.0', '0.162.0', '0.162.1', '0.163.0', '0.164.0']);
+const ANNOTATIONS = new Set([
+  '$comment',
+  'title',
+  'description',
+  'examples',
+  'deprecated',
+  'readOnly',
+  'writeOnly',
+  'externalDocs',
+]);
+const SCHEMA_MAP_KEYS = new Set([
+  'properties',
+  'definitions',
+  '$defs',
+  'patternProperties',
+  'dependentSchemas',
+]);
+const LITERAL_KEYS = new Set(['enum', 'const', 'default']);
+/** @typedef {Record<string, unknown>} JsonObject */
+
+/** @param {unknown} value @param {boolean} [map] @param {boolean} [literal] @returns {unknown} */
+function normalize(value, map = false, literal = false) {
+  if (literal) return value;
+  if (Array.isArray(value)) return value.map((item) => normalize(item));
+  if (value === null || typeof value !== 'object') return value;
+  /** @type {JsonObject} */
+  const output = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (!map && ANNOTATIONS.has(key)) continue;
+    if (LITERAL_KEYS.has(key)) {
+      output[key] = normalize(child, false, true);
+    } else if (
+      SCHEMA_MAP_KEYS.has(key) &&
+      child &&
+      typeof child === 'object' &&
+      !Array.isArray(child)
+    ) {
+      output[key] = Object.fromEntries(
+        Object.entries(child).map(([name, schema]) => [name, normalize(schema)]),
+      );
+    } else output[key] = normalize(child);
+  }
+  return output;
+}
+
+/** @param {unknown} value @returns {string} */
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const object = /** @type {JsonObject} */ (value);
+    return `{${Object.keys(object)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonical(object[key])}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/** @param {unknown} value */
+function sha(value) {
+  return createHash('sha256').update(canonical(value), 'utf8').digest('hex');
+}
+
+/** @param {string} output */
+function parseStableVersion(output) {
+  const match = output
+    .trim()
+    .match(
+      /^(?:codex(?:-cli)?\s+)?(0|[1-9]\d{0,2})\.(0|[1-9]\d{0,2})\.(0|[1-9]\d{0,2})(-[A-Za-z0-9.-]+)?$/iu,
+    );
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] !== undefined,
+    text: `${match[1]}.${match[2]}.${match[3]}`,
+  };
+}
+
+/** @param {unknown} value */
+function assertBoundedSchema(value) {
+  const state = { nodes: 0 };
+  /** @param {unknown} current @param {number} depth */
+  function visit(current, depth) {
+    state.nodes += 1;
+    if (depth > MAX_SCHEMA_DEPTH || state.nodes > MAX_SCHEMA_NODES)
+      throw new Error('schema_shape_too_large');
+    if (Array.isArray(current)) {
+      for (const item of current) visit(item, depth + 1);
+    } else if (current && typeof current === 'object') {
+      for (const child of Object.values(current)) visit(child, depth + 1);
+    }
+  }
+  visit(value, 0);
+}
+
+/** @param {JsonObject} parsed @param {string} reference @returns {unknown} */
+function localDefinition(parsed, reference) {
+  const prefix = reference.startsWith('#/definitions/') ? '#/definitions/' : '#/$defs/';
+  const name = reference.slice(prefix.length);
+  let current = prefix === '#/definitions/' ? parsed.definitions : parsed.$defs;
+  for (const part of name.split('/')) {
+    if (part === '__proto__' || part === 'prototype' || part === 'constructor') return undefined;
+    if (!current || typeof current !== 'object' || Array.isArray(current)) return undefined;
+    current = /** @type {JsonObject} */ (current)[part];
+  }
+  return current;
+}
+
+/** @param {JsonObject} target @param {string} reference @param {unknown} value */
+function setLocalDefinition(target, reference, value) {
+  const prefix = reference.startsWith('#/definitions/') ? '#/definitions/' : '#/$defs/';
+  const parts = reference.slice(prefix.length).split('/');
+  let current = target;
+  for (const part of parts.slice(0, -1)) {
+    if (part === '__proto__' || part === 'prototype' || part === 'constructor')
+      throw new Error('schema_reference_unsafe');
+    if (!current[part] || typeof current[part] !== 'object' || Array.isArray(current[part]))
+      current[part] = {};
+    current = /** @type {JsonObject} */ (current[part]);
+  }
+  if (
+    parts.at(-1) === '__proto__' ||
+    parts.at(-1) === 'prototype' ||
+    parts.at(-1) === 'constructor'
+  )
+    throw new Error('schema_reference_unsafe');
+  current[parts.at(-1) ?? ''] = value;
+}
+
+/**
+ * Project one generated schema root using the same consumed-method and reachable-reference
+ * rules used by the runtime compatibility check. A missing or duplicated method is reported
+ * separately so the runtime can retain its bounded diagnostic.
+ * @param {unknown} parsed
+ * @param {string[]|null} methods
+ * @returns {{normalized:unknown, methodMissing:boolean}}
+ */
+export function projectCodexSchema(parsed, methods) {
+  if (methods === null) return { normalized: normalize(parsed), methodMissing: false };
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+    return { normalized: null, methodMissing: true };
+  const root = /** @type {JsonObject} */ (parsed);
+  const oneOf = Array.isArray(root.oneOf) ? root.oneOf : [];
+  const selected = [];
+  for (const methodName of methods) {
+    const matches = oneOf.filter((/** @type {unknown} */ rawBranch) => {
+      if (!rawBranch || typeof rawBranch !== 'object' || Array.isArray(rawBranch)) return false;
+      const branch = /** @type {JsonObject} */ (rawBranch);
+      const properties = /** @type {JsonObject} */ (branch.properties ?? {});
+      const method = /** @type {JsonObject} */ (properties.method ?? {});
+      const values = Array.isArray(method.enum) ? method.enum : [];
+      return values.length === 1 && values[0] === methodName;
+    });
+    if (matches.length !== 1) return { normalized: null, methodMissing: true };
+    selected.push(matches[0]);
+  }
+  /** @type {JsonObject} */
+  const definitions = {};
+  const found = new Set();
+  /** @param {unknown} value @param {boolean} [map] */
+  const visit = (value, map = false) => {
+    if (!value || typeof value !== 'object') return;
+    if (Array.isArray(value)) {
+      value.forEach((item) => visit(item));
+      return;
+    }
+    const object = /** @type {JsonObject} */ (value);
+    if (typeof object.$ref === 'string') {
+      if (!object.$ref.startsWith('#/definitions/') && !object.$ref.startsWith('#/$defs/'))
+        throw new Error('schema_reference_nonlocal');
+      const prefix = object.$ref.startsWith('#/definitions/') ? '#/definitions/' : '#/$defs/';
+      const name = object.$ref.slice(prefix.length);
+      const source = localDefinition(root, object.$ref);
+      if (source === undefined) throw new Error('schema_reference_missing');
+      if (!found.has(`${prefix}${name}`)) {
+        found.add(`${prefix}${name}`);
+        visit(source);
+      }
+    }
+    for (const [key, child] of Object.entries(object)) {
+      if (map) {
+        visit(child);
+      } else if (
+        key !== 'definitions' &&
+        key !== '$defs' &&
+        !LITERAL_KEYS.has(key) &&
+        !ANNOTATIONS.has(key)
+      ) {
+        if (
+          SCHEMA_MAP_KEYS.has(key) &&
+          child &&
+          typeof child === 'object' &&
+          !Array.isArray(child)
+        ) {
+          for (const schema of Object.values(child)) visit(schema);
+        } else visit(child);
+      }
+    }
+  };
+  for (const [key, child] of Object.entries(root)) {
+    if (
+      key === 'oneOf' ||
+      key === 'definitions' ||
+      key === '$defs' ||
+      LITERAL_KEYS.has(key) ||
+      ANNOTATIONS.has(key)
+    )
+      continue;
+    if (SCHEMA_MAP_KEYS.has(key) && child && typeof child === 'object' && !Array.isArray(child)) {
+      for (const schema of Object.values(child)) visit(schema);
+    } else visit(child);
+  }
+  visit(selected);
+  for (const reference of [...found].sort()) {
+    setLocalDefinition(definitions, reference, normalize(localDefinition(root, reference)));
+  }
+  const projectedRoot = /** @type {JsonObject} */ (normalize(root));
+  delete projectedRoot.oneOf;
+  delete projectedRoot.definitions;
+  delete projectedRoot.$defs;
+  projectedRoot.oneOf = selected.map((/** @type {unknown} */ branch) => normalize(branch));
+  projectedRoot.definitions = definitions;
+  return { normalized: projectedRoot, methodMissing: false };
+}
+
+/** @param {unknown} value @returns {string} */
+export function codexSchemaHash(value) {
+  return sha(value);
+}
+
+/** @param {string} path @param {number} maximumBytes @returns {Promise<string>} */
+async function readBoundedFile(path, maximumBytes) {
+  const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.size > maximumBytes) throw new Error('schema_file_too_large');
+    const buffer = Buffer.alloc(info.size);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const result = await handle.read(buffer, offset, buffer.length - offset, offset);
+      if (result.bytesRead === 0) break;
+      offset += result.bytesRead;
+    }
+    if (offset !== info.size) throw new Error('schema_file_short_read');
+    return buffer.toString('utf8');
+  } finally {
+    await handle.close();
+  }
+}
+
+/** @param {string} path */
+async function assertOwnedDirectory(path) {
+  const info = await lstat(path);
+  const uid = process.getuid?.();
+  if (!info.isDirectory() || info.isSymbolicLink() || (uid !== undefined && info.uid !== uid))
+    throw new Error('schema_directory_invalid');
+}
+
+/** @param {string} executable @param {string[]} args @param {NodeJS.ProcessEnv} environment */
+function runBounded(executable, args, environment) {
+  return new Promise((resolvePromise) => {
+    const child = spawn(executable, args, {
+      cwd: environment.CODEX_COMPAT_CWD,
+      env: environment,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
+    });
+    let output = '';
+    let error = '';
+    const outputState = { bytes: 0, overflow: false };
+    const errorState = { bytes: 0, overflow: false };
+    let settled = false;
+    /** @type {NodeJS.Timeout|undefined} */
+    let timeoutTimer;
+    /** @param {number|null} code @param {boolean} [timedOut] */
+    const finish = (code, timedOut = false) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearTimeout(timeoutTimer);
+      resolvePromise({
+        code,
+        output,
+        error,
+        outputOverflow: outputState.overflow,
+        errorOverflow: errorState.overflow,
+        timedOut,
+      });
+    };
+    const killOwnedProcess = () => {
+      if (child.pid === undefined) return;
+      try {
+        if (process.platform !== 'win32') process.kill(-child.pid, 'SIGKILL');
+        else child.kill('SIGKILL');
+      } catch {
+        try {
+          child.kill('SIGKILL');
+        } catch {
+          // The owned child may have exited between the group and direct kill.
+        }
+      }
+    };
+    const timer = setTimeout(() => {
+      killOwnedProcess();
+      timeoutTimer = setTimeout(() => finish(null, true), 1_000);
+    }, 15_000);
+    /** @param {string} target @param {Buffer|string} chunk @param {{bytes:number, overflow:boolean}} state */
+    const collect = (target, chunk, state) => {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), 'utf8');
+      const remaining = MAX_OUTPUT_BYTES - state.bytes;
+      if (remaining <= 0) {
+        state.overflow = true;
+        return target;
+      }
+      if (bytes.length > remaining) state.overflow = true;
+      const accepted = bytes.subarray(0, remaining);
+      state.bytes += accepted.length;
+      return `${target}${accepted.toString('utf8')}`;
+    };
+    child.stdout.on('data', (chunk) => {
+      output = collect(output, chunk, outputState);
+    });
+    child.stderr.on('data', (chunk) => {
+      error = collect(error, chunk, errorState);
+    });
+    child.once('error', () => finish(null));
+    child.once('close', (code) => finish(code));
+  });
+}
+
+/** @param {string} executable @param {NodeJS.ProcessEnv} [baseEnvironment] */
+export async function resolveCodexCompatibility(executable, baseEnvironment = process.env) {
+  if (!PAGINATION_CONTRACT_VALID)
+    return { status: 'rejected', reason: 'protocol_fingerprint_invalid', version: null };
+  const environment = { PATH: baseEnvironment.PATH ?? '', LANG: 'C.UTF-8' };
+  const versionRun = await runBounded(executable, ['--version'], {
+    ...environment,
+    CODEX_COMPAT_CWD: process.cwd(),
+  });
+  if (versionRun.code !== 0 || versionRun.outputOverflow)
+    return { status: 'rejected', reason: 'version_unavailable', version: null };
+  const version = parseStableVersion(versionRun.output);
+  if (version === null) return { status: 'rejected', reason: 'version_unavailable', version: null };
+  if (version.prerelease || version.major !== 0)
+    return { status: 'rejected', reason: 'version_not_stable_0x', version: version.text };
+  if (QUALIFIED_VERSIONS.has(version.text))
+    return { status: 'qualified', reason: 'native_qualified', version: version.text };
+  if (version.minor < 163)
+    return { status: 'rejected', reason: 'version_unqualified', version: version.text };
+  const root = await mkdtemp(join(tmpdir(), 'aibrain-codex-compat-'));
+  const schemaDir = join(root, 'schema');
+  try {
+    const env = { ...environment, CODEX_HOME: join(root, 'codex-home'), CODEX_COMPAT_CWD: root };
+    const generated = await runBounded(
+      executable,
+      ['app-server', 'generate-json-schema', '--experimental', '--out', schemaDir],
+      env,
+    );
+    if (generated.code !== 0)
+      return { status: 'rejected', reason: 'schema_generation_failed', version: version.text };
+    if (generated.outputOverflow)
+      return { status: 'rejected', reason: 'schema_generation_failed', version: version.text };
+    /** @type {Record<string, string>} */
+    const hashes = {};
+    let aggregateBytes = 0;
+    await assertOwnedDirectory(schemaDir);
+    for (const file of ROOTS) {
+      const path = join(schemaDir, file);
+      let directory = schemaDir;
+      for (const part of file.split('/').slice(0, -1)) {
+        directory = join(directory, part);
+        const directoryEntry = await lstat(directory).catch(() => null);
+        if (directoryEntry === null)
+          return {
+            status: 'rejected',
+            reason: 'schema_root_missing_or_invalid',
+            version: version.text,
+          };
+        await assertOwnedDirectory(directory);
+      }
+      const entry = await lstat(path).catch(() => null);
+      if (
+        entry === null ||
+        entry.isSymbolicLink() ||
+        !entry.isFile() ||
+        (process.getuid?.() !== undefined && entry.uid !== process.getuid()) ||
+        entry.size > MAX_SCHEMA_BYTES
+      )
+        return {
+          status: 'rejected',
+          reason: 'schema_root_missing_or_invalid',
+          version: version.text,
+        };
+      aggregateBytes += entry.size;
+      if (aggregateBytes > MAX_SCHEMA_SET_BYTES)
+        return { status: 'rejected', reason: 'schema_set_too_large', version: version.text };
+      const parsed = JSON.parse(await readBoundedFile(path, MAX_SCHEMA_BYTES));
+      assertBoundedSchema(parsed);
+      const rootMap = /** @type {Record<string, {methods: string[]|null, sha256: string}>} */ (
+        fingerprint.roots
+      );
+      const expectedRoot = rootMap[file];
+      const projection = projectCodexSchema(parsed, expectedRoot.methods);
+      if (projection.methodMissing)
+        return { status: 'rejected', reason: 'protocol_method_missing', version: version.text };
+      hashes[file] = sha(projection.normalized);
+      if (hashes[file] !== expectedRoot.sha256)
+        return { status: 'rejected', reason: 'protocol_schema_mismatch', version: version.text };
+    }
+    const help = await runBounded(executable, ['app-server', '--help'], env);
+    const terminalHelp = await runBounded(executable, ['--help'], env);
+    if (
+      help.code !== 0 ||
+      help.outputOverflow ||
+      !help.output.includes('--listen') ||
+      !help.output.includes('stdio://') ||
+      terminalHelp.code !== 0 ||
+      terminalHelp.outputOverflow ||
+      !terminalHelp.output.includes('--remote') ||
+      !terminalHelp.output.includes('unix://')
+    )
+      return { status: 'rejected', reason: 'transport_flags_missing', version: version.text };
+    const recheck = await runBounded(executable, ['--version'], {
+      ...environment,
+      CODEX_COMPAT_CWD: process.cwd(),
+    });
+    const recheckedVersion = parseStableVersion(recheck.output);
+    if (
+      recheck.code !== 0 ||
+      recheck.outputOverflow ||
+      recheckedVersion?.text !== version.text ||
+      recheckedVersion?.prerelease
+    )
+      return { status: 'rejected', reason: 'version_changed_during_probe', version: version.text };
+    return {
+      status: 'protocol_match',
+      reason: 'protocol_fingerprint_match',
+      version: version.text,
+    };
+  } catch {
+    return { status: 'rejected', reason: 'protocol_probe_failed', version: version.text };
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+/** @param {{reason:string, version:string|null}} decision @returns {string} */
+export function codexCompatibilityError(decision) {
+  return `codex_protocol_incompatible:${decision.reason}:detected=${decision.version ?? 'unavailable'};run aisac doctor --json`;
+}

package/dist/codex-diagnostics.mjs

@@ -2,14 +2,32 @@
 
 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 { constants, readFileSync } 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.7';
+const PACKAGE_VERSION_PATTERN =
+  /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/u;
+function packageVersion() {
+  for (const packageUrl of [
+    new URL('./package.json', import.meta.url),
+    new URL('../package.json', import.meta.url),
+  ]) {
+    try {
+      const value = JSON.parse(readFileSync(packageUrl, 'utf8'));
+      if (typeof value?.version === 'string' && PACKAGE_VERSION_PATTERN.test(value.version))
+        return value.version;
+    } catch {
+      // Source and packaged dist use different relative package metadata locations.
+    }
+  }
+  throw new Error('codex_diagnostics_package_version_unavailable');
+}
+export const CODEX_DIAGNOSTIC_ADAPTER_VERSION = packageVersion();
 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;
@@ -63,6 +81,14 @@ const REASONS = new Set([
   'timeout',
   'thread_closed',
   'protocol_error',
+  'capture_size_exceeded',
+  'capture_item_count_exceeded',
+  'private_storage_failed',
+  'storage_capacity_exceeded',
+  'capture_lock_timeout',
+  'capture_lock_legacy',
+  'capture_lock_owner_unverifiable',
+  'capture_lock_backend_unavailable',
   'attached',
   'uncertain',
   'disconnected',
@@ -101,6 +127,12 @@ const ERROR_CODES = new Set([
   '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);
@@ -304,6 +336,8 @@ function normalize(event, clientVersion, sessionKey, instanceKey, now) {
   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;
@@ -317,6 +351,8 @@ function normalize(event, clientVersion, sessionKey, instanceKey, now) {
     ['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) {
@@ -333,7 +369,7 @@ function normalize(event, clientVersion, sessionKey, instanceKey, now) {
         typeof value === 'number' &&
         Number.isSafeInteger(value) &&
         value >= 0 &&
-        value <= 1_000_000
+        value <= (/_bytes$/u.test(key) ? MAX_DIAGNOSTIC_BYTES : 1_000_000)
       )
         counts[key] = value;
     }