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

package/dist/engineering.mjs

@@ -0,0 +1,194 @@
+// @ts-check
+
+/**
+ * AISAC Engineering license check (ADR-0047 wave E3).
+ *
+ * The server is the only authority. This answer is shown to the user and
+ * never unlocks anything locally: every failure is reported as
+ * `unavailable`, never as licensed. The account token goes only to the
+ * configured AI Brain origin, redirects are refused, and the response is
+ * size-bounded and validated before any field is displayed.
+ */
+
+const LICENSE_PATH = '/engineering/v1/license';
+export const LICENSE_TIMEOUT_MS = 5_000;
+const MAX_LICENSE_BODY_BYTES = 16 * 1024;
+const MAX_URL_LENGTH = 2_048;
+const ISO_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/u;
+// Reasons are displayed, so only a plain identifier is accepted. New server
+// reasons stay readable by old clients without an allowlist update.
+const SAFE_REASON = /^[a-z][a-z0-9_]{0,63}$/u;
+/** @type {ReadonlyMap<number, string>} */
+const UNAVAILABLE_BY_STATUS = new Map([
+  [401, 'unauthorized'],
+  [404, 'not_offered'],
+  [429, 'rate_limited'],
+  [503, 'license_unavailable'],
+]);
+const SERVER_ERROR_STATUS = 500;
+
+/**
+ * @typedef {{
+ *   state: 'active' | 'inactive' | 'unavailable',
+ *   reason: string,
+ *   validUntil: string | null,
+ *   purchaseUrl: string | null
+ * }} EngineeringLicense
+ */
+
+/** @param {string} reason @returns {EngineeringLicense} */
+export function unavailableLicense(reason) {
+  return { state: 'unavailable', reason, validUntil: null, purchaseUrl: null };
+}
+
+/** @param {string} endpoint */
+export function engineeringLicenseUrl(endpoint) {
+  return new URL(LICENSE_PATH, endpoint).toString();
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+export function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** @param {unknown} value @returns {value is string} */
+export function isPurchaseUrl(value) {
+  if (typeof value !== 'string' || value.length > MAX_URL_LENGTH) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === 'https:' && url.username === '' && url.password === '';
+  } catch {
+    return false;
+  }
+}
+
+/** @param {unknown} value */
+function isValidUntil(value) {
+  return (
+    value === null ||
+    (typeof value === 'string' && ISO_INSTANT.test(value) && Number.isFinite(Date.parse(value)))
+  );
+}
+
+/**
+ * Validate the 200 body of the license route (OpenAPI `EngineeringLicense`).
+ * Unknown extra fields are ignored; anything malformed rejects the whole body.
+ * @param {string} text
+ * @returns {EngineeringLicense | null}
+ */
+export function parseLicenseBody(text) {
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isRecord(body) || body.schema_version !== 1 || body.capability !== 'engineering')
+    return null;
+  const { state, reason, valid_until: validUntil, purchase_url: purchaseUrl } = body;
+  if (state !== 'active' && state !== 'inactive') return null;
+  if (typeof reason !== 'string' || !SAFE_REASON.test(reason)) return null;
+  if (!isValidUntil(validUntil) || !isPurchaseUrl(purchaseUrl)) return null;
+  return {
+    state,
+    reason,
+    validUntil: /** @type {string | null} */ (validUntil),
+    purchaseUrl: /** @type {string} */ (purchaseUrl),
+  };
+}
+
+/**
+ * Read a response body as UTF-8, refusing anything above `limit` bytes.
+ * @param {Response} response
+ * @param {number} [limit]
+ */
+export async function readBoundedText(response, limit = MAX_LICENSE_BODY_BYTES) {
+  const declared = Number(response.headers.get('content-length') ?? '0');
+  if (declared > limit) throw new Error('body_too_large');
+  if (response.body === null) return '';
+  const reader = response.body.getReader();
+  /** @type {Uint8Array[]} */
+  const chunks = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > limit) {
+      await reader.cancel().catch(() => undefined);
+      throw new Error('body_too_large');
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+/** @param {unknown} error */
+export function isTimeout(error) {
+  return error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError');
+}
+
+/** @param {number} status */
+export function unavailableReasonFor(status) {
+  return (
+    UNAVAILABLE_BY_STATUS.get(status) ??
+    (status >= SERVER_ERROR_STATUS ? 'server_error' : 'unexpected_status')
+  );
+}
+
+/**
+ * Ask the server whether this account holds the AISAC Engineering license.
+ * @param {string} endpoint configured AI Brain MCP endpoint (already validated at setup)
+ * @param {string} token account PAT
+ * @param {{ fetchImpl?: typeof fetch, timeoutMs?: number }} [options]
+ * @returns {Promise<EngineeringLicense>}
+ */
+export async function checkEngineeringLicense(endpoint, token, options = {}) {
+  const { fetchImpl = fetch, timeoutMs = LICENSE_TIMEOUT_MS } = options;
+  let url;
+  try {
+    url = engineeringLicenseUrl(endpoint);
+  } catch {
+    return unavailableLicense('invalid_endpoint');
+  }
+  const signal = AbortSignal.timeout(timeoutMs);
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: 'GET',
+      redirect: 'error',
+      signal,
+      headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+    });
+  } catch (error) {
+    return unavailableLicense(isTimeout(error) ? 'timeout' : 'unreachable');
+  }
+  if (response.status !== 200) {
+    await response.body?.cancel().catch(() => undefined);
+    return unavailableLicense(unavailableReasonFor(response.status));
+  }
+  let text;
+  try {
+    text = await readBoundedText(response);
+  } catch (error) {
+    return unavailableLicense(isTimeout(error) ? 'timeout' : 'invalid_response');
+  }
+  return parseLicenseBody(text) ?? unavailableLicense('invalid_response');
+}
+
+/**
+ * One line for `aisac setup`. Returns null while the server does not offer the
+ * capability yet, so memory-only users see no new noise.
+ * @param {EngineeringLicense} license
+ * @returns {string | null}
+ */
+export function licenseLine(license) {
+  if (license.state === 'active') {
+    const until = license.validUntil === null ? '' : ` until ${license.validUntil.slice(0, 10)}`;
+    return `AISAC Engineering: active${until}.`;
+  }
+  if (license.state === 'inactive')
+    return `AISAC Engineering: inactive (${license.reason}) — ${license.purchaseUrl ?? ''}`.trimEnd();
+  if (license.reason === 'not_offered') return null;
+  return `AISAC Engineering: unavailable (${license.reason}); memory and context are unaffected.`;
+}

package/dist/launch.mjs

@@ -4,13 +4,20 @@ import { access, chmod, lstat, mkdir, mkdtemp, open, rm, writeFile } from 'node:
 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 { captureLockPlatformCheck, nativeVersion, resolveNative } from './platform.mjs';
+import { claudeCompatibilityError, resolveClaudeCompatibility } from './claude-compatibility.mjs';
+import { codexCompatibilityError, resolveCodexCompatibility } from './codex-compatibility.mjs';
 import {
   claudeCheckpointConfigBinding,
   claudeObservationConfigBinding,
   telemetryConfigBinding,
 } from './state.mjs';
 import { codexPolicyJson, makePolicy } from './policy.mjs';
+import {
+  prepareEngineeringPack,
+  sweepStaleLaunches,
+  writeLaunchMarker,
+} from './engineering-pack.mjs';
 import {
   CODEX_LAUNCH_ENVELOPE,
   CODEX_MONITOR_CWD,
@@ -359,14 +366,26 @@ async function assertClaudeCheckpointHelper(packageRoot) {
   return helperPath;
 }
 
-/** @param {string} root @param {string} prefix */
+/**
+ * A fresh private directory for one launch. Directories left by launches whose
+ * processes are gone are swept first; this one records its launcher.
+ * @param {string} root @param {string} prefix
+ */
 async function launchDirectory(root, prefix) {
+  await sweepStaleLaunches(root);
   const parent = await privateDirectory(join(root, 'runtime'));
   const directory = await mkdtemp(join(parent, `${prefix}-`));
   await chmod(directory, 0o700);
+  await writeLaunchMarker(directory, { launcherPid: process.pid, childPid: null });
   return directory;
 }
 
+/** @param {string} directory @param {number | undefined} childPid */
+async function recordChild(directory, childPid) {
+  if (childPid === undefined) return;
+  await writeLaunchMarker(directory, { launcherPid: process.pid, childPid }).catch(() => undefined);
+}
+
 /** @param {import('node:child_process').ChildProcess} child @param {string} directory */
 function waitForChild(child, directory) {
   return new Promise((resolvePromise) => {
@@ -399,15 +418,32 @@ function waitForChild(child, directory) {
   });
 }
 
-/** @param {LaunchConfig} config @param {string} root @param {string[]} args */
-export async function launchClaude(config, root, args) {
+/**
+ * @typedef {object} LaunchDependencies
+ * @property {typeof prepareEngineeringPack} [preparePack] AISAC Engineering pack loader (E4b)
+ */
+
+/**
+ * @param {LaunchConfig} config
+ * @param {string} root
+ * @param {string[]} args
+ * @param {LaunchDependencies} [dependencies]
+ */
+export async function launchClaude(config, root, args, dependencies = {}) {
+  const preparePack = dependencies.preparePack ?? prepareEngineeringPack;
   const validated = assertConfig(config);
   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 compatibility = await resolveClaudeCompatibility(executable, validated.packageRoot);
+  if (compatibility.status === 'rejected') throw new Error(claudeCompatibilityError(compatibility));
+  const pinnedExecutable = compatibility.executable ?? executable;
+  if (compatibility.status === 'host_checked')
+    process.stderr.write(
+      `aisac: Claude ${compatibility.version ?? 'unknown'} accepted by the local native host contract; end-to-end recovery remains separately qualified.\n`,
+    );
+  const currentVersion = compatibility.version ?? nativeVersion(pinnedExecutable);
   const pluginRoot = await assertClaudeAssets(validated.packageRoot);
   const telemetryActive =
     validated.telemetry?.enabled === true && validated.telemetry?.disclosedAt != null;
@@ -526,13 +562,22 @@ export async function launchClaude(config, root, args) {
     await rm(directory, { recursive: true, force: true });
     throw error;
   }
+  // The pack never blocks the launch: every failure starts Claude without it.
+  const engineering = await preparePack({
+    endpoint: validated.endpoint,
+    token: validated.token,
+    root,
+    directory,
+    packageRoot: validated.packageRoot,
+  }).catch(() => ({ pluginRoot: null, line: null }));
+  if (engineering.line !== null) process.stderr.write(`${engineering.line}\n`);
   const environment = childEnvironment(root);
   environment.CLAUDE_CODE_ENABLE_FUNCTION_HOOKS = '1';
   /** @type {import('node:child_process').ChildProcess} */
   let child;
   try {
     child = spawn(
-      executable,
+      pinnedExecutable,
       [
         '--settings',
         settingsPath,
@@ -542,6 +587,7 @@ export async function launchClaude(config, root, args) {
         requiredAllow.join(','),
         '--plugin-dir',
         pluginRoot,
+        ...(engineering.pluginRoot === null ? [] : ['--plugin-dir', engineering.pluginRoot]),
         ...launchArgs.args,
       ],
       { cwd: process.cwd(), env: environment, stdio: 'inherit' },
@@ -550,20 +596,28 @@ export async function launchClaude(config, root, args) {
     await rm(directory, { recursive: true, force: true }).catch(() => undefined);
     throw error;
   }
-  return waitForChild(child, directory);
+  // Listen for exit before any await, so a child that exits at once is not missed.
+  const finished = waitForChild(child, directory);
+  await recordChild(directory, child.pid);
+  return finished;
 }
 
 /** @param {LaunchConfig} config @param {string} root @param {string[]} args */
 export async function launchCodex(config, root, args) {
   const validated = assertConfig(config);
   assertCodexArgs(args);
+  const captureLockPlatform = captureLockPlatformCheck();
+  if (!captureLockPlatform.ok) throw new Error(captureLockPlatform.code);
   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(
+      `aisac: 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');
@@ -613,7 +667,7 @@ export async function launchCodex(config, root, args) {
   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';
@@ -627,7 +681,10 @@ export async function launchCodex(config, root, args) {
     env: environment,
     stdio: 'inherit',
   });
-  return waitForChild(child, directory);
+  // Listen for exit before any await, so a child that exits at once is not missed.
+  const finished = waitForChild(child, directory);
+  await recordChild(directory, child.pid);
+  return finished;
 }
 
 export const launchInternals = { MCP_ALIAS, PLUGIN_NAME, PLUGIN_INLINE_NAME };

package/dist/mcp.mjs

@@ -252,7 +252,7 @@ export async function reportContextTelemetry(endpoint, token, report, deadlineMs
       params: {
         protocolVersion: '2025-03-26',
         capabilities: {},
-        clientInfo: { name: 'aibrain-telemetry-report', version: '0.3.0-beta.7' },
+        clientInfo: { name: 'aibrain-telemetry-report', version: '0.3.0-beta.9' },
       },
     },
     undefined,
@@ -344,7 +344,7 @@ export async function selectContextShadow(endpoint, token, request, deadlineMs =
       params: {
         protocolVersion: '2025-03-26',
         capabilities: {},
-        clientInfo: { name: 'aibrain-claude-shadow', version: '0.3.0-beta.7' },
+        clientInfo: { name: 'aibrain-claude-shadow', version: '0.3.0-beta.9' },
       },
     },
     undefined,
@@ -428,7 +428,7 @@ export async function readContextBudget(endpoint, token, deadlineMs = 8_000) {
       params: {
         protocolVersion: '2025-03-26',
         capabilities: {},
-        clientInfo: { name: 'aibrain-context-budget', version: '0.3.0-beta.7' },
+        clientInfo: { name: 'aibrain-context-budget', version: '0.3.0-beta.9' },
       },
     },
     undefined,
@@ -578,7 +578,7 @@ async function providerFreeProbeV1(endpoint, token) {
       params: {
         protocolVersion: '2025-03-26',
         capabilities: {},
-        clientInfo: { name: 'aibrain', version: '0.3.0-beta.7' },
+        clientInfo: { name: 'aibrain', version: '0.3.0-beta.9' },
       },
     },
     undefined,
@@ -632,7 +632,7 @@ async function providerFreeProbeV1(endpoint, token) {
         arguments: {
           schema_version: 1,
           client: 'codex_app_server',
-          client_version: '0.3.0-beta.7',
+          client_version: '0.3.0-beta.9',
           session_ref: sessionRef,
           revision,
           observed_at: new Date().toISOString(),
@@ -724,7 +724,7 @@ export async function providerFreeProbeV2(endpoint, token, policy, clients) {
       params: {
         protocolVersion: '2025-03-26',
         capabilities: {},
-        clientInfo: { name: 'aibrain', version: '0.3.0-beta.7' },
+        clientInfo: { name: 'aibrain', version: '0.3.0-beta.9' },
       },
     },
     undefined,
@@ -928,7 +928,7 @@ export async function providerFreeProbeV2(endpoint, token, policy, clients) {
   await callTool(2, 'brain_context_select', {
     schema_version: 2,
     client: clients === 'claude' ? 'claude_code' : 'codex_app_server',
-    client_version: '0.3.0-beta.7',
+    client_version: '0.3.0-beta.9',
     session_ref: sessionRef,
     revision,
     observed_at: now,
@@ -941,7 +941,7 @@ export async function providerFreeProbeV2(endpoint, token, policy, clients) {
     await callTool(3, 'brain_context_compact', {
       schema_version: 2,
       client: 'claude_code',
-      client_version: '0.3.0-beta.7',
+      client_version: '0.3.0-beta.9',
       session_ref: sessionRef,
       revision,
       observed_at: now,

package/dist/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@brunobracaioli/aibrain",
-  "version": "0.3.0-beta.7",
+  "version": "0.4.0-beta.2",
   "type": "module"
 }

package/dist/platform.mjs

@@ -23,6 +23,19 @@ export function platformCheck() {
   return { ok: true };
 }
 
+/** @param {NodeJS.ProcessEnv} [environment] */
+export function captureLockPlatformCheck(environment = process.env) {
+  const platform = platformCheck();
+  if (!platform.ok) return platform;
+  if (resolveNative('flock', environment) === null)
+    return {
+      ok: false,
+      code: 'CODEX_CAPTURE_LOCK_BACKEND_UNAVAILABLE',
+      message: 'Codex capture requires util-linux flock on Linux/WSL.',
+    };
+  return { ok: true };
+}
+
 /** @param {string} name @param {NodeJS.ProcessEnv} [environment] */
 export function resolveNative(name, environment = process.env) {
   if (!/^[A-Za-z0-9._+-]+$/u.test(name)) return null;
@@ -70,13 +83,44 @@ export function nativeVersion(executable, environment = process.env) {
 export function isTestedNativeVersion(client, version) {
   const value = version.trim();
   if (client === 'claude')
-    return /^(?:(?:claude(?:\s+code)?)\s+)?2\.1\.(?:294|295|296|299|300)(?:\s+\(Claude\s+Code\))?$/iu.test(
+    return /^(?:(?:claude(?:\s+code)?)\s+)?2\.1\.(?:294|295|296|299|300|301|302|303)(?:\s+\(Claude\s+Code\))?$/iu.test(
       value,
     );
-  return /^(?:codex(?:-cli)?\s+)?0\.16(?:1\.0|2\.0|2\.1)$/iu.test(value);
+  return /^(?:codex(?:-cli)?\s+)?0\.16(?:1\.0|2\.0|2\.1|3\.0|4\.0)$/iu.test(value);
+}
+
+const TESTED_NATIVE_VERSIONS = Object.freeze({
+  claude: Object.freeze([
+    '2.1.294',
+    '2.1.295',
+    '2.1.296',
+    '2.1.299',
+    '2.1.300',
+    '2.1.301',
+    '2.1.302',
+    '2.1.303',
+  ]),
+  codex: Object.freeze(['0.161.0', '0.162.0', '0.162.1', '0.163.0', '0.164.0']),
+});
+
+/** @param {'claude'|'codex'} client @param {string} version */
+export function nativeVersionDiagnostic(client, version) {
+  const detected = version.trim();
+  const versionPattern =
+    client === 'claude'
+      ? /^(?:(?:claude(?:\s+code)?)\s+)?(\d{1,3})\.(\d{1,3})\.(\d{1,3})(-[A-Za-z0-9.-]+)?(?:\s+\(Claude\s+Code\))?$/iu
+      : /^(?:codex(?:-cli)?\s+)?(\d{1,3})\.(\d{1,3})\.(\d{1,3})(-[A-Za-z0-9.-]+)?$/iu;
+  const versionMatch = detected.match(versionPattern);
+  const safeDetected = versionMatch
+    ? `${versionMatch[1]}.${versionMatch[2]}.${versionMatch[3]}${versionMatch[4] ? '-prerelease' : ''}`
+    : 'unavailable';
+  const label = client === 'claude' ? 'Claude Code' : 'Codex CLI';
+  const tested = TESTED_NATIVE_VERSIONS[client].join(', ');
+  return `${client}_version_unverified: ${label} detected version ${safeDetected}; tested stable versions: ${tested}. Update AI Brain to a compatible version, then run aisac doctor --json or install a qualified stable native version.`;
 }
 
 /** @param {'claude'|'codex'} client @param {string} version */
 export function assertTestedNativeVersion(client, version) {
-  if (!isTestedNativeVersion(client, version)) throw new Error(`${client}_version_unverified`);
+  if (!isTestedNativeVersion(client, version))
+    throw new Error(nativeVersionDiagnostic(client, version));
 }

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@brunobracaioli/aibrain",
-  "version": "0.3.0-beta.7",
+  "version": "0.4.0-beta.2",
   "private": false,
-  "description": "AI Brain assisted context beta client for Claude Code and Codex",
+  "description": "AISAC client for Claude Code and Codex: AI Brain memory, context management and AISAC Engineering",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {
+    "aisac": "./dist/cli.mjs",
     "aibrain": "./dist/cli.mjs"
   },
   "files": [