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

package/dist/codex-compatibility.mjs

@@ -0,0 +1,467 @@
+// @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']);
+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;
+}
+
+/** @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];
+      let normalized;
+      if (expectedRoot.methods === null) normalized = normalize(parsed);
+      else {
+        const oneOf = Array.isArray(parsed.oneOf) ? parsed.oneOf : [];
+        const selected = [];
+        for (const methodName of expectedRoot.methods) {
+          const matches = oneOf.filter((/** @type {unknown} */ rawBranch) => {
+            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 { status: 'rejected', reason: 'protocol_method_missing', version: version.text };
+          selected.push(matches[0]);
+        }
+        /** @type {JsonObject} */
+        const definitions = /** @type {JsonObject} */ ({});
+        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(parsed, 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(parsed)) {
+          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(parsed, reference)));
+        }
+        const projectedRoot = /** @type {JsonObject} */ (normalize(parsed));
+        delete projectedRoot.oneOf;
+        delete projectedRoot.definitions;
+        delete projectedRoot.$defs;
+        projectedRoot.oneOf = selected.map((/** @type {unknown} */ branch) => normalize(branch));
+        projectedRoot.definitions = definitions;
+        normalized = projectedRoot;
+      }
+      hashes[file] = sha(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 aibrain doctor --json`;
+}