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

package/dist/launch.mjs

@@ -1,11 +1,24 @@
 // @ts-check
 
-import { access, chmod, lstat, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { access, chmod, lstat, mkdir, mkdtemp, open, rm, writeFile } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import { constants } from 'node:fs';
 import { isAbsolute, join, resolve, sep } from 'node:path';
 import { assertTestedNativeVersion, nativeVersion, resolveNative } from './platform.mjs';
+import { codexCompatibilityError, resolveCodexCompatibility } from './codex-compatibility.mjs';
+import {
+  claudeCheckpointConfigBinding,
+  claudeObservationConfigBinding,
+  telemetryConfigBinding,
+} from './state.mjs';
 import { codexPolicyJson, makePolicy } from './policy.mjs';
+import {
+  CODEX_LAUNCH_ENVELOPE,
+  CODEX_MONITOR_CWD,
+  makeCodexLaunchEnvelope,
+  parseCodexLaunchArgs,
+  readEffectiveWritableRoots,
+} from './codex-permissions.mjs';
 
 const MCP_ALIAS = 'aibrain_context';
 const PLUGIN_NAME = 'ai-brain-context-compaction';
@@ -17,12 +30,16 @@ const CLAUDE_HEADLESS_FLAGS = new Set([
   '--input-format',
   '--output-style',
 ]);
-const RESERVED_CLAUDE_FLAGS = new Set([
-  '--settings',
-  '--mcp-config',
-  '--plugin-dir',
-  '--allowedTools',
-]);
+const RESERVED_CLAUDE_FLAGS = new Set(['--mcp-config', '--plugin-dir', '--allowedTools']);
+const MAX_CLAUDE_SETTINGS_BYTES = 64 * 1024;
+const MAX_CLAUDE_SETTINGS_DEPTH = 12;
+const MAX_CLAUDE_SETTINGS_NODES = 512;
+const MAX_CLAUDE_SETTINGS_STRING_LENGTH = 16 * 1024;
+const MAX_CLAUDE_PERMISSION_LIST_ITEMS = 256;
+const MAX_CLAUDE_PERMISSION_STRING_LENGTH = 4096;
+const CLAUDE_SETTINGS_SECTIONS = new Set(['sandbox', 'permissions']);
+const CLAUDE_PERMISSION_LISTS = new Set(['allow', 'ask', 'deny', 'additionalDirectories']);
+const CLAUDE_SETTINGS_FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 
 /**
  * @typedef {object} LaunchConfig
@@ -33,6 +50,8 @@ const RESERVED_CLAUDE_FLAGS = new Set([
  * @property {string|null} codexVersion
  * @property {number} schemaVersion
  * @property {import('./policy.mjs').ContextPolicy} [context]
+ * @property {{ enabled: boolean, disclosedAt?: string | null }} [telemetry]
+ * @property {{ shadowEnabled: boolean, diagnosticsEnabled: boolean, disclosedAt?: string | null }} [claudeObservation]
  */
 
 /** @param {LaunchConfig} config */
@@ -105,6 +124,8 @@ function childEnvironment(root) {
   delete environment.AIBRAIN_TOKEN_FILE;
   delete environment.CODEX_CONTEXT_POLICY_JSON;
   delete environment.CODEX_CONTEXT_COMPACT_AT;
+  delete environment[CODEX_LAUNCH_ENVELOPE];
+  delete environment[CODEX_MONITOR_CWD];
   environment.AIBRAIN_STATE_DIR = resolve(root);
   return environment;
 }
@@ -112,6 +133,7 @@ function childEnvironment(root) {
 /** @param {string[]} args */
 function assertClaudeArgs(args) {
   for (const argument of args) {
+    if (argument === '--') break;
     const option = argument.split('=', 1)[0];
     if (CLAUDE_HEADLESS_FLAGS.has(option) || /^-p(?:=|[^-])/u.test(argument))
       throw new Error('claude_headless_mode_unsupported');
@@ -119,6 +141,180 @@ function assertClaudeArgs(args) {
   }
 }
 
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function plainObject(value) {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype
+  );
+}
+
+/** @param {unknown} value */
+function validateClaudeSettingsValue(value, depth = 0, state = { nodes: 0 }) {
+  state.nodes += 1;
+  if (state.nodes > MAX_CLAUDE_SETTINGS_NODES || depth > MAX_CLAUDE_SETTINGS_DEPTH)
+    throw new Error('claude_settings_structure_invalid');
+  if (typeof value === 'string') {
+    if (value.length > MAX_CLAUDE_SETTINGS_STRING_LENGTH)
+      throw new Error('claude_settings_string_too_long');
+    return;
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value) || Math.abs(value) > Number.MAX_SAFE_INTEGER)
+      throw new Error('claude_settings_value_invalid');
+    return;
+  }
+  if (value === null || typeof value === 'boolean') return;
+  if (Array.isArray(value)) {
+    if (value.length > MAX_CLAUDE_SETTINGS_NODES)
+      throw new Error('claude_settings_structure_invalid');
+    for (const item of value) validateClaudeSettingsValue(item, depth + 1, state);
+    return;
+  }
+  if (!plainObject(value)) throw new Error('claude_settings_value_invalid');
+  for (const [key, item] of Object.entries(value)) {
+    if (CLAUDE_SETTINGS_FORBIDDEN_KEYS.has(key)) throw new Error('claude_settings_prototype_key');
+    if (key.length > 256) throw new Error('claude_settings_key_too_long');
+    validateClaudeSettingsValue(item, depth + 1, state);
+  }
+}
+
+/** @param {unknown} value */
+function validateClaudeSettingsFragment(value) {
+  if (!plainObject(value)) throw new Error('claude_settings_root_invalid');
+  validateClaudeSettingsValue(value);
+  for (const key of Object.keys(value)) {
+    if (!CLAUDE_SETTINGS_SECTIONS.has(key)) throw new Error('claude_settings_section_unsupported');
+    const section = value[key];
+    if (!plainObject(section)) throw new Error('claude_settings_section_invalid');
+  }
+  const permissions = value.permissions;
+  if (permissions !== undefined) {
+    const permissionObject = /** @type {Record<string, unknown>} */ (permissions);
+    for (const key of CLAUDE_PERMISSION_LISTS) {
+      const list = permissionObject[key];
+      if (list === undefined) continue;
+      if (
+        !Array.isArray(list) ||
+        list.length > MAX_CLAUDE_PERMISSION_LIST_ITEMS ||
+        list.some(
+          (item) => typeof item !== 'string' || item.length > MAX_CLAUDE_PERMISSION_STRING_LENGTH,
+        )
+      )
+        throw new Error('claude_settings_permission_list_invalid');
+    }
+  }
+  return /** @type {{sandbox?: Record<string, unknown>, permissions?: Record<string, unknown>}} */ (
+    value
+  );
+}
+
+/** @param {string} text */
+function parseClaudeSettingsText(text) {
+  const bytes = Buffer.byteLength(text, 'utf8');
+  if (bytes > MAX_CLAUDE_SETTINGS_BYTES) throw new Error('claude_settings_too_large');
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new Error('claude_settings_invalid_json');
+  }
+  return validateClaudeSettingsFragment(value);
+}
+
+/** @param {string} path */
+async function readClaudeSettingsFile(path) {
+  let handle;
+  try {
+    const link = await lstat(path);
+    if (link.isSymbolicLink() || !link.isFile()) throw new Error('claude_settings_file_invalid');
+    handle = await open(
+      path,
+      constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0),
+    );
+    const entry = await handle.stat();
+    if (!entry.isFile()) throw new Error('claude_settings_file_invalid');
+    if (entry.size > MAX_CLAUDE_SETTINGS_BYTES) throw new Error('claude_settings_too_large');
+    const buffer = Buffer.alloc(MAX_CLAUDE_SETTINGS_BYTES + 1);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const result = await handle.read(buffer, offset, buffer.length - offset, null);
+      if (result.bytesRead === 0) break;
+      offset += result.bytesRead;
+    }
+    if (offset > MAX_CLAUDE_SETTINGS_BYTES) throw new Error('claude_settings_too_large');
+    let text;
+    try {
+      text = new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, offset));
+    } catch {
+      throw new Error('claude_settings_invalid_utf8');
+    }
+    return parseClaudeSettingsText(text);
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('claude_settings_')) throw error;
+    throw new Error('claude_settings_file_invalid');
+  } finally {
+    await handle?.close().catch(() => undefined);
+  }
+}
+
+/** @param {string} value @param {string} cwd */
+async function readClaudeSettings(value, cwd) {
+  const first = value.trimStart()[0];
+  const explicitPath = isAbsolute(value) || value.startsWith('./') || value.startsWith('../');
+  if (Buffer.byteLength(value, 'utf8') > MAX_CLAUDE_SETTINGS_BYTES)
+    throw new Error('claude_settings_too_large');
+  try {
+    return validateClaudeSettingsFragment(JSON.parse(value));
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('claude_settings_')) throw error;
+    if (!explicitPath && (first === '{' || first === '[' || first === '"' || first === '-'))
+      throw new Error('claude_settings_invalid_json');
+  }
+  return readClaudeSettingsFile(resolve(cwd, value));
+}
+
+/**
+ * @param {string[]} args
+ * @param {string} cwd
+ * @returns {Promise<{args: string[], settings?: {sandbox?: Record<string, unknown>, permissions?: Record<string, unknown>}}>}
+ */
+async function parseClaudeLaunchArgs(args, cwd) {
+  const forwarded = [];
+  let settingsValue;
+  let terminated = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (terminated) {
+      forwarded.push(argument);
+      continue;
+    }
+    if (argument === '--') {
+      terminated = true;
+      forwarded.push(argument);
+      continue;
+    }
+    if (argument === '--settings' || argument.startsWith('--settings=')) {
+      if (settingsValue !== undefined) throw new Error('claude_settings_duplicate');
+      const value =
+        argument === '--settings' ? args[++index] : argument.slice('--settings='.length);
+      if (value === undefined || value === '' || value.startsWith('-'))
+        throw new Error('claude_settings_value_required');
+      settingsValue = value;
+      continue;
+    }
+    forwarded.push(argument);
+  }
+  return {
+    args: forwarded,
+    ...(settingsValue === undefined
+      ? {}
+      : { settings: await readClaudeSettings(settingsValue, cwd) }),
+  };
+}
+
 /** @param {string[]} args */
 function assertCodexArgs(args) {
   for (const argument of args) {
@@ -135,11 +331,35 @@ async function assertClaudeAssets(packageRoot) {
     join(pluginRoot, '.claude-plugin', 'plugin.json'),
     join(pluginRoot, 'hooks', 'hooks.json'),
     join(pluginRoot, 'hooks', 'context-compaction.ts'),
+    join(pluginRoot, 'hooks', 'provider-window.js'),
+    join(pluginRoot, 'hooks', 'state-fitting.mjs'),
+    join(pluginRoot, 'hooks', 'state-fitting.d.mts'),
   ];
   await Promise.all(required.map((path) => access(path, constants.R_OK)));
   return pluginRoot;
 }
 
+/** @param {string} packageRoot */
+async function assertTelemetryHelper(packageRoot) {
+  const helperPath = join(packageRoot, 'telemetry-report.mjs');
+  await access(helperPath, constants.R_OK);
+  return helperPath;
+}
+
+/** @param {string} packageRoot */
+async function assertClaudeObservationHelper(packageRoot) {
+  const helperPath = join(packageRoot, 'claude-observation.mjs');
+  await access(helperPath, constants.R_OK);
+  return helperPath;
+}
+
+/** @param {string} packageRoot */
+async function assertClaudeCheckpointHelper(packageRoot) {
+  const helperPath = join(packageRoot, 'claude-checkpoint.mjs');
+  await access(helperPath, constants.R_OK);
+  return helperPath;
+}
+
 /** @param {string} root @param {string} prefix */
 async function launchDirectory(root, prefix) {
   const parent = await privateDirectory(join(root, 'runtime'));
@@ -183,12 +403,31 @@ function waitForChild(child, directory) {
 /** @param {LaunchConfig} config @param {string} root @param {string[]} args */
 export async function launchClaude(config, root, args) {
   const validated = assertConfig(config);
-  assertClaudeArgs(args);
+  const launchArgs = await parseClaudeLaunchArgs(args, process.cwd());
+  assertClaudeArgs(launchArgs.args);
   const executable = resolveNative('claude');
   if (!executable) throw new Error('claude_not_found');
   const currentVersion = nativeVersion(executable);
   assertTestedNativeVersion('claude', currentVersion);
   const pluginRoot = await assertClaudeAssets(validated.packageRoot);
+  const telemetryActive =
+    validated.telemetry?.enabled === true && validated.telemetry?.disclosedAt != null;
+  const telemetryHelperPath = telemetryActive
+    ? await assertTelemetryHelper(validated.packageRoot)
+    : undefined;
+  const telemetryConfigDigest = telemetryActive ? telemetryConfigBinding(validated) : undefined;
+  const observationActive =
+    validated.claudeObservation?.shadowEnabled === true ||
+    validated.claudeObservation?.diagnosticsEnabled === true;
+  const observationHelperPath = observationActive
+    ? await assertClaudeObservationHelper(validated.packageRoot)
+    : undefined;
+  const observationConfigDigest = observationActive
+    ? claudeObservationConfigBinding(validated)
+    : undefined;
+  const checkpointHelperPath = await assertClaudeCheckpointHelper(validated.packageRoot);
+  const checkpointConfigDigest = claudeCheckpointConfigBinding(validated);
+  const checkpointStateDir = await privateDirectory(join(root, 'claude', 'checkpoints'));
   const directory = await launchDirectory(root, 'claude');
   const settingsPath = join(directory, 'settings.json');
   const mcpPath = join(directory, 'mcp.json');
@@ -213,21 +452,63 @@ export async function launchClaude(config, root, args) {
         }),
     enabled: true,
     disclosed: true,
+    compactionStrategy: 'native_summary_notes',
     preservationMode: 'upstream_compatible',
     diagnosticMode: false,
+    telemetryEnabled: validated.telemetry?.enabled === true,
+    telemetryDisclosed:
+      validated.telemetry?.enabled === true && validated.telemetry?.disclosedAt != null,
+    telemetryClientVersion: currentVersion.match(/\b\d+\.\d+\.\d+\b/u)?.[0] ?? '',
+    ...(telemetryActive
+      ? {
+          telemetryNodePath: process.execPath,
+          telemetryHelperPath,
+          telemetryStateDir: resolve(root),
+          telemetryConfigDigest,
+        }
+      : {}),
+    ...(observationActive
+      ? {
+          observationNodePath: process.execPath,
+          observationHelperPath,
+          observationStateDir: resolve(root),
+          observationConfigDigest,
+          observationShadowEnabled: validated.claudeObservation?.shadowEnabled === true,
+          observationDiagnosticsEnabled: validated.claudeObservation?.diagnosticsEnabled === true,
+        }
+      : {}),
+    checkpointNodePath: process.execPath,
+    checkpointHelperPath,
+    checkpointStateDir,
+    checkpointConfigDigest,
+    checkpointBinding: checkpointConfigDigest,
   };
   if (!legacy && context.goal !== undefined) options.goal = context.goal;
+  const requiredAllow = [
+    `mcp__${MCP_ALIAS}__brain_context_status`,
+    `mcp__${MCP_ALIAS}__brain_context_compact`,
+    `mcp__${MCP_ALIAS}__brain_context_select`,
+    `mcp__${MCP_ALIAS}__brain_context_budget`,
+    ...(options.telemetryEnabled && options.telemetryDisclosed
+      ? [`mcp__${MCP_ALIAS}__brain_context_report`]
+      : []),
+  ];
+  const userPermissions = launchArgs.settings?.permissions ?? {};
+  const userAllow = Array.isArray(userPermissions.allow) ? userPermissions.allow : [];
+  /** @type {string[]} */
+  const mergedAllow = [];
+  for (const rule of [...userAllow, ...requiredAllow]) {
+    if (!mergedAllow.includes(rule)) mergedAllow.push(rule);
+  }
   const settings = {
+    ...(launchArgs.settings?.sandbox === undefined ? {} : { sandbox: launchArgs.settings.sandbox }),
     pluginConfigs: {
       [PLUGIN_NAME]: { options },
       [PLUGIN_INLINE_NAME]: { options: { ...options } },
     },
     permissions: {
-      allow: [
-        `mcp__${MCP_ALIAS}__brain_context_status`,
-        `mcp__${MCP_ALIAS}__brain_context_compact`,
-        `mcp__${MCP_ALIAS}__brain_context_select`,
-      ],
+      ...userPermissions,
+      allow: mergedAllow,
     },
   };
   const mcp = {
@@ -259,10 +540,10 @@ export async function launchClaude(config, root, args) {
         '--mcp-config',
         mcpPath,
         '--allowedTools',
-        `mcp__${MCP_ALIAS}__brain_context_status,mcp__${MCP_ALIAS}__brain_context_compact,mcp__${MCP_ALIAS}__brain_context_select`,
+        requiredAllow.join(','),
         '--plugin-dir',
         pluginRoot,
-        ...args,
+        ...launchArgs.args,
       ],
       { cwd: process.cwd(), env: environment, stdio: 'inherit' },
     );
@@ -280,34 +561,72 @@ export async function launchCodex(config, root, args) {
   const executable = resolveNative('codex');
   const node = resolveNative('node');
   if (!executable || !node) throw new Error('codex_or_node_not_found');
-  const currentVersion = nativeVersion(executable);
-  assertTestedNativeVersion('codex', currentVersion);
-  const currentSemver = currentVersion.match(/\b\d+\.\d+\.\d+\b/u)?.[0];
-  if (currentSemver === undefined) throw new Error('codex_version_unverified');
+  const compatibility = await resolveCodexCompatibility(executable);
+  if (compatibility.status === 'rejected') throw new Error(codexCompatibilityError(compatibility));
+  if (compatibility.version === null) throw new Error('codex_version_unverified');
+  if (compatibility.status === 'protocol_match')
+    process.stderr.write(
+      `aibrain: Codex ${compatibility.version} matched the local protocol contract; native behavioral qualification is not established.\n`,
+    );
+  const launchPlan = await parseCodexLaunchArgs(args, process.cwd());
   const packageRoot = resolve(validated.packageRoot);
   const terminal = join(packageRoot, 'assets', 'jev-paid-pilot-terminal.mjs');
   const monitor = join(packageRoot, 'monitor.mjs');
-  await Promise.all([access(terminal, constants.R_OK), access(monitor, constants.X_OK)]);
+  const diagnosticModule = join(packageRoot, 'codex-diagnostics.mjs');
+  await Promise.all([
+    access(terminal, constants.R_OK),
+    access(monitor, constants.X_OK),
+    access(diagnosticModule, constants.R_OK),
+  ]);
   const checkpoints = await privateDirectory(join(root, 'codex', 'checkpoints'));
   const notes = await privateDirectory(join(root, 'codex', 'notes'));
   const directory = await launchDirectory(root, 'codex');
   const environment = childEnvironment(root);
+  try {
+    if (
+      launchPlan.additionalRoots.length > 0 ||
+      Object.keys(launchPlan.server).length > 0 ||
+      launchPlan.profile !== undefined
+    ) {
+      const configuredRoots =
+        launchPlan.additionalRoots.length > 0
+          ? await readEffectiveWritableRoots(
+              executable,
+              launchPlan.effectiveCwd,
+              launchPlan.profile,
+              environment,
+            )
+          : [];
+      const envelope = makeCodexLaunchEnvelope(launchPlan, configuredRoots);
+      environment[CODEX_LAUNCH_ENVELOPE] = JSON.stringify(envelope);
+    }
+  } catch (error) {
+    await rm(directory, { recursive: true, force: true });
+    throw error;
+  }
   environment.AI_BRAIN_MCP_SERVER = MCP_ALIAS;
   environment.CODEX_BIN = executable;
   environment.CODEX_MONITOR_COMMAND = monitor;
+  environment[CODEX_MONITOR_CWD] = launchPlan.effectiveCwd;
   environment.CODEX_CONTEXT_RECOVERY_ENABLED = '1';
   environment.CODEX_CONTEXT_RECOVERY_DISCLOSED = '1';
   environment.CODEX_CONTEXT_CHECKPOINT_DIR = checkpoints;
   environment.CODEX_CONTEXT_RECOVERY_DIR = notes;
+  environment.CODEX_CONTEXT_DIAGNOSTICS_MODULE = diagnosticModule;
+  environment.CODEX_CONTEXT_DIAGNOSTICS_DIR = resolve(root);
+  environment.CODEX_CONTEXT_DIAGNOSTICS_ENABLED = '1';
   environment.AIBRAIN_MCP_URL = validated.endpoint;
   environment.AIBRAIN_MCP_TOKEN = validated.token;
-  environment.CODEX_CLIENT_VERSION = currentSemver;
+  environment.CODEX_CLIENT_VERSION = compatibility.version;
+  environment.CODEX_CONTEXT_TELEMETRY_ENABLED = validated.telemetry?.enabled === true ? '1' : '0';
+  environment.CODEX_CONTEXT_TELEMETRY_DISCLOSED =
+    validated.telemetry?.enabled === true && validated.telemetry?.disclosedAt != null ? '1' : '0';
   if (validated.schemaVersion === 2 && validated.context !== undefined) {
     environment.CODEX_CONTEXT_POLICY_JSON = codexPolicyJson(validated.context);
   } else {
     delete environment.CODEX_CONTEXT_POLICY_JSON;
   }
-  const child = spawn(node, [terminal, '--', ...args], {
+  const child = spawn(node, [terminal, '--', ...launchPlan.nativeArgs], {
     cwd: process.cwd(),
     env: environment,
     stdio: 'inherit',