@brunobracaioli/aibrain 0.4.0-beta.2 → 0.4.0-beta.4

package/README.md

@@ -21,6 +21,25 @@ private folder, which is deleted on exit. Any failure starts Claude without the
 pack. `aisac setup --lang pt-BR|en` picks the pack language without a network
 call. The pack is never part of this npm package.
 
+`aisac codex` (Codex 0.164.0 or later) loads the same verified pack for that
+session only: its skills are added to the Codex app-server the launch owns
+(call one with `$`, for example `$spec`) and its agents become session agent
+roles. Nothing is written to `~/.codex`, `~/.agents` or the project, and the
+session's folder is deleted on exit. An older Codex starts without the pack and
+says `codex_outdated`.
+
+Licensed `aisac claude` sessions also load guardrail hooks as the session plugin
+`aisac-guardrails`.
+- **Default on:** `secrets-guard` refuses secret files by name. Four more hooks
+  keep continuity: a repository snapshot at start and after a compaction, a
+  docs reminder, and the NOTES/spec/CHANGELOG pass.
+- **Default off:** `git-guard`, `destructive-guard` and `format-on-edit`.
+- **Changing them:** `aisac hooks` lists them, and `aisac hooks enable|disable
+  <id>` or `aisac hooks reset` changes the next session. The agent cannot change
+  them from inside a session.
+- **Code:** it ships in this package and runs locally. Nothing comes from the
+  server.
+
 Codex capture also requires the `flock` utility from `util-linux`, normally
 included in Linux/WSL. The launcher and doctor check availability before a
 monitored Codex session starts. Capture coordination is released by the kernel

package/dist/assets/codex-context-compaction.mjs

@@ -54,6 +54,12 @@ const MAX_OWNED_REQUESTS = 1_000;
 const MAX_RETIRED_REQUESTS = 2_000;
 const MAX_CLIENT_REQUEST_BINDINGS = 128;
 const MAX_OWNED_THREAD_IDS = 256;
+// AISAC Engineering (ADR-0047 E4c): the launcher's skills root is added to the
+// owned app-server before the client sees its initialize answer.
+const ENGINEERING_SKILLS_ROOT_ENV = 'AISAC_ENGINEERING_SKILLS_ROOT';
+const ENGINEERING_SKILLS_ACK_TIMEOUT_MS = 2_000;
+const MAX_ENGINEERING_PATH_LENGTH = 4_096;
+const MAX_TRACKED_INITIALIZE_REQUESTS = 4;
 const MAX_RECOVERY_ITEMS = 128;
 const MAX_RECOVERY_SOURCE_INDEX = 65_536;
 const MAX_NOTE_BYTES = 128 * 1024;
@@ -2707,6 +2713,8 @@ export function createCodexContextProxy({
   createDiagnosticSink = null,
   brainServer = process.env.AI_BRAIN_MCP_SERVER ?? 'brain',
   clientVersion = process.env.CODEX_CLIENT_VERSION ?? '0.161.0',
+  engineeringSkillsRoot = null,
+  engineeringAckTimeoutMs = ENGINEERING_SKILLS_ACK_TIMEOUT_MS,
 }) {
   const contextPolicy = normalizeContextPolicy(policy);
   const effectiveThreshold = contextPolicy?.compactAtPercent ?? threshold;
@@ -2719,6 +2727,15 @@ export function createCodexContextProxy({
   const telemetryByThread = new Map();
   const diagnosticSinks = new Map();
   let stopped = false;
+  // AISAC Engineering skills root: 'off' without a root; 'waiting' for the
+  // client's first successful initialize; 'holding' app-server output until
+  // skills/extraRoots/set is answered (or times out); then 'done'.
+  let engineeringState =
+    typeof engineeringSkillsRoot === 'string' && engineeringSkillsRoot.length > 0
+      ? 'waiting'
+      : 'off';
+  const initializeRequestKeys = new Set();
+  let engineeringHeld = null;
   function emitDiagnostic(event) {
     try {
       const phase = typeof event?.phase === 'string' ? event.phase : '';
@@ -4131,6 +4148,11 @@ export function createCodexContextProxy({
       const owned = ownedRequests.get(message.id);
       ownedRequests.delete(message.id);
       retire(message.id);
+      if (owned.kind === 'engineering') {
+        // An error leaves the session without the pack skills; it is never shown.
+        releaseEngineering();
+        return false;
+      }
       if (
         owned.kind === 'read' ||
         owned.kind === 'page' ||
@@ -4364,6 +4386,14 @@ export function createCodexContextProxy({
     if (!validRequestId) return;
     const requestKey = clientRequestKey(requestId);
     if (requestKey === null) return;
+    if (
+      message.method === 'initialize' &&
+      engineeringState === 'waiting' &&
+      initializeRequestKeys.size < MAX_TRACKED_INITIALIZE_REQUESTS
+    ) {
+      initializeRequestKeys.add(requestKey);
+      return;
+    }
     if (['thread/start', 'thread/resume', 'thread/fork'].includes(message.method)) {
       const threadId =
         isRecord(message.params) && typeof message.params.threadId === 'string'
@@ -4428,7 +4458,7 @@ export function createCodexContextProxy({
   let passthrough = false;
   let discardOversized = false;
   let pausedForBackpressure = false;
-  const forward = (text) => {
+  const writeOut = (text) => {
     if (!stdout.write(text) && !pausedForBackpressure) {
       pausedForBackpressure = true;
       child.stdout.pause();
@@ -4438,6 +4468,54 @@ export function createCodexContextProxy({
       });
     }
   };
+  const forward = (text) => {
+    if (engineeringHeld === null) {
+      writeOut(text);
+      return;
+    }
+    engineeringHeld.lines.push(text);
+    engineeringHeld.bytes += Buffer.byteLength(text, 'utf8');
+    if (engineeringHeld.bytes > MAX_LINE_BYTES) releaseEngineering();
+  };
+  /** The client's first successful initialize answer, which starts the hold. */
+  function isEngineeringTrigger(message) {
+    if (engineeringState !== 'waiting' || !isRecord(message)) return false;
+    if (message.method !== undefined || !('result' in message)) return false;
+    const key = clientRequestKey(message.id);
+    return key !== null && initializeRequestKeys.has(key);
+  }
+  function holdForEngineering(text) {
+    engineeringState = 'holding';
+    initializeRequestKeys.clear();
+    engineeringHeld = {
+      lines: [text],
+      bytes: Buffer.byteLength(text, 'utf8'),
+      id: null,
+      cancel: null,
+    };
+    try {
+      engineeringHeld.id = sendOwned(
+        'skills/extraRoots/set',
+        { extraRoots: [engineeringSkillsRoot] },
+        'engineering',
+        null,
+      );
+    } catch {
+      releaseEngineering();
+      return;
+    }
+    engineeringHeld.cancel = scheduleTimeout(() => releaseEngineering(), engineeringAckTimeoutMs);
+  }
+  /** Forward everything held, in order. Idempotent; the session never waits on the pack. */
+  function releaseEngineering() {
+    if (engineeringHeld === null) return;
+    const held = engineeringHeld;
+    engineeringHeld = null;
+    engineeringState = 'done';
+    held.cancel?.();
+    if (held.id !== null && ownedRequests.has(held.id)) cleanupRequest(held.id);
+    for (const text of held.lines) writeOut(text);
+  }
   const processLine = (line) => {
     if (Buffer.byteLength(line, 'utf8') + 1 > MAX_LINE_BYTES) {
       const ownedId = internalRequestId(line);
@@ -4451,6 +4529,10 @@ export function createCodexContextProxy({
     try {
       const message = JSON.parse(line.endsWith('\r') ? line.slice(0, -1) : line);
       observeClientResponse(message);
+      if (isEngineeringTrigger(message)) {
+        holdForEngineering(`${line}\n`);
+        return;
+      }
       forwardLine = handle(message);
     } catch {
       /* preserve malformed external protocol lines */
@@ -4536,6 +4618,7 @@ export function createCodexContextProxy({
     }
   });
   child.stdout.on('end', () => {
+    releaseEngineering();
     const tail = inputBuffer + decoder.end();
     if (tail && !discardOversized) forward(tail);
     inputBuffer = '';
@@ -4565,6 +4648,7 @@ export function createCodexContextProxy({
     observeClientRequest,
     observeClientResponse,
     async stop() {
+      releaseEngineering();
       if (stopped) {
         await Promise.all(
           [...diagnosticSinks.values()].map((sink) =>
@@ -4594,6 +4678,18 @@ export function createCodexContextProxy({
   };
 }
 
+/**
+ * The launcher's AISAC Engineering skills root, or null. Only an absolute,
+ * normalized path without control characters is used.
+ */
+export function engineeringSkillsRootFrom(value) {
+  if (typeof value !== 'string' || value.length === 0) return null;
+  if (value.length > MAX_ENGINEERING_PATH_LENGTH || /[\u0000-\u001f\u007f]/u.test(value))
+    return null;
+  if (!value.startsWith('/') || resolve(value) !== value) return null;
+  return value;
+}
+
 async function main() {
   if (process.argv.includes('--help')) {
     process.stderr.write(
@@ -4648,6 +4744,7 @@ async function main() {
     timeoutMs: numberEnv('CODEX_CONTEXT_COMPACT_TIMEOUT_MS', DEFAULT_TIMEOUT_MS),
     policy,
     createDiagnosticSink: diagnosticFactory,
+    engineeringSkillsRoot: engineeringSkillsRootFrom(process.env[ENGINEERING_SKILLS_ROOT_ENV]),
   });
   const clientDecoder = new StringDecoder('utf8');
   let clientInputBuffer = '';

package/dist/claude-observation.mjs

@@ -16,7 +16,7 @@ export const MAX_LOG_FILES = 3;
 const LOCK_WAIT_MS = 250;
 const LOCK_STALE_MS = 30_000;
 const ADMISSION_MS = 60 * 60 * 1000;
-export const ADAPTER_VERSION = '0.4.0-beta.2';
+export const ADAPTER_VERSION = '0.4.0-beta.4';
 const MAX_DIAGNOSTIC_COUNT = 10_000_000;
 const MAX_DIAGNOSTIC_BYTES = 128 * 1024 * 1024;
 const CHECKPOINT_BACKENDS = new Set(['native_store', 'private_file']);

package/dist/cli.mjs

@@ -36,8 +36,10 @@ import {
   resolvePackLocale,
   writeStoredLocale,
 } from './engineering-pack.mjs';
+import { extensionsSummary, hooksCommand } from './extensions-cli.mjs';
+import { anyFormatter } from './guardrails/format.mjs';
 
-const VERSION = '0.4.0-beta.2';
+const VERSION = '0.4.0-beta.4';
 // The command is `aisac`; `aibrain` is an alias installed from the same entry.
 const COMMAND = 'aisac';
 const ENDPOINT = 'https://mcp.ai-brain.aisac.cloud/mcp';
@@ -55,7 +57,10 @@ function usage() {
     'Claude shadow: setup --claude-shadow on|off and --claude-diagnostics on|off (preview stays applied=false).',
   );
   console.log(
-    'AISAC Engineering: `aisac claude` loads the licensed method; setup --lang pt-BR|en picks its language; setup and doctor report the license; status stays offline. `aibrain` is an alias of `aisac`.',
+    'AISAC Engineering: `aisac claude` and `aisac codex` (Codex 0.164+) load the licensed method; setup --lang pt-BR|en picks its language; setup and doctor report the license; status stays offline. `aibrain` is an alias of `aisac`.',
+  );
+  console.log(
+    'Guardrails: `aisac hooks` lists them (a checklist on a terminal); `aisac hooks enable|disable <id>...` and `aisac hooks reset` change the next `aisac claude` session.',
   );
 }
 
@@ -539,6 +544,16 @@ async function setup(args) {
   if (line !== null) console.log(line);
 }
 
+/** Extension state plus whether `format-on-edit` has a formatter in this folder (FR8). */
+async function doctorExtensions() {
+  const summary = await extensionsSummary(stateRoot());
+  if (!summary.hooks.includes('format-on-edit')) return { ...summary, formatOnEdit: 'off' };
+  return {
+    ...summary,
+    formatOnEdit: (await anyFormatter(process.cwd())) ? 'ready' : 'no_formatter_found',
+  };
+}
+
 /** @param {boolean} json */
 async function doctor(json) {
   const platform = platformCheck();
@@ -633,6 +648,7 @@ async function doctor(json) {
     },
     engineering,
     engineeringPack: await engineeringPackState(),
+    extensions: await doctorExtensions(),
     paidOrPilot: probe?.ok
       ? 'provider_free_probe_ok; paid entitlement or pilot invitation remains server-enforced'
       : config
@@ -669,6 +685,7 @@ async function status(json) {
         config?.claudeObservation?.disclosedAt !== undefined,
     },
     engineeringPack: await engineeringPackState(),
+    extensions: await extensionsSummary(stateRoot()),
     monitoredSession: null,
     monitoringStatus: 'not_observed',
   };
@@ -717,6 +734,7 @@ async function main(argv) {
     else console.log(records);
     return;
   }
+  if (command === 'hooks') return hooksCommand(rest);
   if (command === 'disable') {
     if (rest.length > 0) throw new Error('disable_does_not_accept_options');
     return removeOwnedSetup();

package/dist/codex-engineering.mjs

@@ -0,0 +1,165 @@
+// @ts-check
+
+/**
+ * AISAC Engineering for Codex (ADR-0047 wave E4c, spec FR4).
+ *
+ * Codex has no session plugin directory, so the method reaches only the
+ * app-server this launch owns, and nothing is written to `~/.codex`,
+ * `~/.agents` or the project:
+ * - skills: the adapter sends `skills/extraRoots/set` with the pack's
+ *   `skills/` directory right after the client's initialize (in-memory in that
+ *   process);
+ * - agents: one role file per pack agent, declared with `-c agents.<name>.*`
+ *   overrides on the owned app-server (the session-flags config layer).
+ * The launcher hands the monitor one JSON value; the monitor validates it
+ * again before turning it into arguments.
+ */
+
+import { basename, dirname, join, resolve } from 'node:path';
+
+export const CODEX_ENGINEERING_ENV = 'AISAC_ENGINEERING_CODEX';
+export const CODEX_ENGINEERING_SKILLS_ROOT_ENV = 'AISAC_ENGINEERING_SKILLS_ROOT';
+export const CODEX_AGENTS_DIRECTORY = 'codex-agents';
+const SKILLS_DIRECTORY = 'skills';
+const PACK_DIRECTORY = 'engineering';
+const RUNTIME_DIRECTORY = 'runtime';
+const CODEX_LAUNCH_DIRECTORY = /^codex-[A-Za-z0-9]{6}$/u;
+const SCHEMA_VERSION = 1;
+const MAX_SPEC_BYTES = 16 * 1024;
+const MAX_AGENTS = 16;
+const MAX_PATH_LENGTH = 4096;
+export const MAX_AGENT_DESCRIPTION_LENGTH = 1024;
+export const AGENT_NAME = /^[a-z][a-z0-9-]{0,63}$/u;
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/u;
+/** First Codex release whose session mechanism was verified (spike Q4, 2026-11-03). */
+const MIN_CODEX_VERSION = /** @type {const} */ ([0, 164, 0]);
+
+/** @typedef {{ name: string, description: string, configFile: string }} CodexAgentRole */
+/** @typedef {{ schemaVersion: 1, skillsRoot: string, agents: CodexAgentRole[] }} CodexEngineering */
+
+/** @param {string} code @returns {never} */
+function fail(code) {
+  throw new Error(`codex_engineering_${code}`);
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Whether this Codex version receives the pack. A null or malformed version
+ * never does.
+ * @param {string | null | undefined} version
+ */
+export function supportsCodexEngineering(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/u.exec(version ?? '');
+  if (match === null) return false;
+  const parts = match.slice(1).map(Number);
+  for (let index = 0; index < MIN_CODEX_VERSION.length; index += 1) {
+    const part = /** @type {number} */ (parts[index]);
+    const minimum = MIN_CODEX_VERSION[index] ?? 0;
+    if (part !== minimum) return part > minimum;
+  }
+  return true;
+}
+
+/** @param {unknown} value */
+function isCleanAbsolutePath(value) {
+  return (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    value.length <= MAX_PATH_LENGTH &&
+    !CONTROL_CHARACTERS.test(value) &&
+    value.startsWith('/') &&
+    resolve(value) === value
+  );
+}
+
+/**
+ * @param {unknown} value
+ * @param {{ stateDir?: string }} [options] when given, the pack must sit in a
+ *   Codex launch directory of that state directory
+ * @returns {CodexEngineering}
+ */
+export function validateCodexEngineering(value, options = {}) {
+  if (!isRecord(value)) fail('invalid');
+  const keys = Object.keys(value).sort().join(',');
+  if (keys !== 'agents,schemaVersion,skillsRoot') fail('invalid');
+  if (value.schemaVersion !== SCHEMA_VERSION) fail('schema');
+  const skillsRoot = value.skillsRoot;
+  if (!isCleanAbsolutePath(skillsRoot)) fail('path');
+  const skills = /** @type {string} */ (skillsRoot);
+  if (basename(skills) !== SKILLS_DIRECTORY) fail('path');
+  const base = dirname(skills);
+  if (basename(base) !== PACK_DIRECTORY) fail('path');
+  if (options.stateDir !== undefined) {
+    const launch = dirname(base);
+    if (
+      !CODEX_LAUNCH_DIRECTORY.test(basename(launch)) ||
+      dirname(launch) !== join(resolve(options.stateDir), RUNTIME_DIRECTORY)
+    )
+      fail('path');
+  }
+  if (!Array.isArray(value.agents) || value.agents.length > MAX_AGENTS) fail('agents');
+  const seen = new Set();
+  /** @type {CodexAgentRole[]} */
+  const agents = [];
+  for (const agent of value.agents) {
+    if (!isRecord(agent) || Object.keys(agent).sort().join(',') !== 'configFile,description,name')
+      fail('agents');
+    const { name, description, configFile } = agent;
+    if (typeof name !== 'string' || !AGENT_NAME.test(name) || seen.has(name)) fail('agents');
+    if (
+      typeof description !== 'string' ||
+      description.trim().length === 0 ||
+      description.length > MAX_AGENT_DESCRIPTION_LENGTH ||
+      CONTROL_CHARACTERS.test(description)
+    )
+      fail('agents');
+    if (configFile !== join(base, CODEX_AGENTS_DIRECTORY, `${name}.toml`)) fail('agents');
+    seen.add(name);
+    agents.push({ name, description, configFile });
+  }
+  return { schemaVersion: SCHEMA_VERSION, skillsRoot: skills, agents };
+}
+
+/**
+ * Parse the monitor's environment value; null when absent.
+ * @param {string | undefined} raw
+ * @param {{ stateDir?: string }} [options]
+ * @returns {CodexEngineering | null}
+ */
+export function parseCodexEngineering(raw, options = {}) {
+  if (raw === undefined || raw === '') return null;
+  if (Buffer.byteLength(raw, 'utf8') > MAX_SPEC_BYTES) fail('too_large');
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    fail('invalid');
+  }
+  return validateCodexEngineering(value, options);
+}
+
+/**
+ * A TOML basic string. JSON escapes are TOML escapes; DEL is escaped too.
+ * @param {string} value
+ */
+export function tomlBasicString(value) {
+  return JSON.stringify(value).replace(/\u007f/gu, '\\u007F');
+}
+
+/**
+ * Session-only `-c` overrides for the owned app-server, one role per agent.
+ * @param {CodexEngineering} engineering
+ * @returns {string[]}
+ */
+export function codexEngineeringConfigArgs(engineering) {
+  return engineering.agents.flatMap((agent) => [
+    '-c',
+    `agents.${agent.name}.description=${tomlBasicString(agent.description)}`,
+    '-c',
+    `agents.${agent.name}.config_file=${tomlBasicString(agent.configFile)}`,
+  ]);
+}