@aria_asi/cli 0.2.30 → 0.2.32

package/src/connectors/codex.ts

@@ -8,6 +8,7 @@ import {
   copyFileSync,
   chmodSync,
   writeFileSync,
+  readFileSync,
 } from 'fs';
 import { homedir } from 'os';
 import * as path from 'path';
@@ -15,6 +16,8 @@ import { fileURLToPath } from 'node:url';
 import type { AriaConfig } from '../config.js';
 import { connectShell } from './shell.js';
 import { installAriaCognitionSkills } from './cognitive-skills.js';
+import { syncDoctrineTriggerMap } from './doctrine-trigger-map.js';
+import { buildMustReadGuide, mustReadIntro } from './must-read.js';
 
 function packageSdkDir(): string {
   const here = path.dirname(fileURLToPath(import.meta.url));
@@ -81,6 +84,528 @@ function installNodePackage(codexDir: string, logs: string[]): void {
   logs.push(`Installed Codex Node package → ${pkgRoot}`);
 }
 
+function tomlString(value: string): string {
+  return JSON.stringify(value);
+}
+
+function buildCodexHookRuntimeClient(): string {
+  return `import { readFileSync, existsSync, mkdirSync, writeFileSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { HTTPHarnessClient } from '@aria_asi/harness-http-client';
+
+const HOME = homedir();
+const DEFAULT_RUNTIME_URL = (process.env.ARIA_RUNTIME_URL || 'http://127.0.0.1:4319').replace(/\\/+$/, '');
+const TURN_STATE_DIR = path.join(HOME, '.codex', 'tmp', 'aria-hook-turn-state');
+
+function readToken() {
+  const envToken = process.env.ARIA_API_KEY || process.env.ARIA_MASTER_TOKEN || process.env.OPENAI_API_KEY;
+  if (envToken) return envToken;
+  const ownerPath = path.join(HOME, '.aria', 'owner-token');
+  if (existsSync(ownerPath)) return readFileSync(ownerPath, 'utf8').trim();
+  const licensePath = path.join(HOME, '.aria', 'license.json');
+  if (existsSync(licensePath)) {
+    const text = readFileSync(licensePath, 'utf8');
+    const harnessToken = text.match(/"harnessToken"\\s*:\\s*"([^"]+)"/)?.[1];
+    if (harnessToken) return harnessToken;
+    const token = text.match(/"token"\\s*:\\s*"([^"]+)"/)?.[1];
+    if (token) return token;
+  }
+  return '';
+}
+
+let clientInstance = null;
+
+export function getHarnessClient() {
+  if (clientInstance) return clientInstance;
+  clientInstance = new HTTPHarnessClient({
+    baseUrl: DEFAULT_RUNTIME_URL,
+    apiKey: readToken(),
+    workspaceRoot: process.cwd(),
+  });
+  return clientInstance;
+}
+
+export function readEventFromStdin() {
+  try {
+    const raw = readFileSync(0, 'utf8');
+    return raw.trim() ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+function extractFirst(value, keys) {
+  if (!value || typeof value !== 'object') return null;
+  for (const key of keys) {
+    const candidate = value[key];
+    if (typeof candidate === 'string' && candidate.trim()) return candidate.trim();
+  }
+  return null;
+}
+
+export function inferSessionId(event) {
+  const threadId =
+    extractFirst(event, ['thread_id', 'threadId', 'conversation_id', 'conversationId']) ||
+    'codex';
+  const turnId =
+    extractFirst(event, ['turn_id', 'turnId', 'session_id', 'sessionId']) ||
+    String(Date.now());
+  return \`codex:\${threadId}:\${turnId}\`;
+}
+
+export function inferUserId(event) {
+  return (
+    extractFirst(event, ['user_id', 'userId']) ||
+    extractFirst(event?.metadata, ['user_id', 'userId'])
+  );
+}
+
+export function extractText(value) {
+  if (!value) return '';
+  if (typeof value === 'string') return value.trim();
+  if (Array.isArray(value)) {
+    return value.map(extractText).filter(Boolean).join('\\n\\n').trim();
+  }
+  if (typeof value === 'object') {
+    const parts = [];
+    for (const key of ['text', 'message', 'content', 'input_text', 'inputText', 'reasoning_text', 'summary_text', 'delta']) {
+      if (key in value) {
+        const piece = extractText(value[key]);
+        if (piece) parts.push(piece);
+      }
+    }
+    return parts.join('\\n\\n').trim();
+  }
+  return '';
+}
+
+function ensureTurnStateDir() {
+  if (!existsSync(TURN_STATE_DIR)) {
+    mkdirSync(TURN_STATE_DIR, { recursive: true, mode: 0o700 });
+  }
+}
+
+function turnStatePath(sessionId) {
+  ensureTurnStateDir();
+  const safe = String(sessionId || 'codex').replace(/[^a-zA-Z0-9._-]+/g, '_');
+  return path.join(TURN_STATE_DIR, \`\${safe}.json\`);
+}
+
+export function loadTurnState(sessionId) {
+  const statePath = turnStatePath(sessionId);
+  if (!existsSync(statePath)) return {};
+  try {
+    return JSON.parse(readFileSync(statePath, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function saveTurnState(sessionId, patch) {
+  const next = {
+    ...loadTurnState(sessionId),
+    ...patch,
+    sessionId,
+    updatedAt: new Date().toISOString(),
+  };
+  writeFileSync(turnStatePath(sessionId), JSON.stringify(next, null, 2) + '\\n', { mode: 0o600 });
+  return next;
+}
+
+export function clearTurnState(sessionId) {
+  const statePath = turnStatePath(sessionId);
+  if (!existsSync(statePath)) return;
+  try {
+    unlinkSync(statePath);
+  } catch {}
+}
+
+export async function runtimePost(route, body = {}) {
+  const token = readToken();
+  const headers = {
+    'Content-Type': 'application/json',
+  };
+  if (token) headers.Authorization = \`Bearer \${token}\`;
+  const response = await fetch(\`\${DEFAULT_RUNTIME_URL}\${route}\`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+  });
+  if (!response.ok) {
+    const detail = await response.text().catch(() => response.statusText);
+    throw new Error(\`runtime \${route} failed (\${response.status}): \${detail}\`);
+  }
+  return response.json();
+}
+
+export function classifyAction(event) {
+  const toolName = String(event?.tool_name || event?.toolName || '').trim();
+  const toolCommand = String(
+    event?.tool_input?.command ??
+    event?.toolInput?.command ??
+    ''
+  ).trim();
+  const haystack = \`\${toolName}\\n\${toolCommand}\\n\${JSON.stringify(event)}\`;
+  if (/deploy|kubectl|docker\\s+push/i.test(haystack)) return 'deploy';
+  if (/\\brm\\b|delete|unlink|drop\\s+table/i.test(haystack)) return 'delete';
+  if (/build|test|tsc|jest|vitest|npm run|pnpm|yarn/i.test(haystack)) return 'build';
+  return 'write';
+}
+
+export function summarizeTarget(event) {
+  return JSON.stringify({
+    tool_name: event?.tool_name || event?.toolName || null,
+    tool_input: event?.tool_input || event?.toolInput || null,
+  }).slice(0, 4000);
+}
+
+export function extractUserText(event) {
+  return extractText(
+    event?.input ??
+    event?.user_input ??
+    event?.userInput ??
+    event?.prompt ??
+    event?.message ??
+    event
+  );
+}
+
+export function extractAssistantText(event) {
+  return extractText(
+    event?.last_assistant_message ??
+    event?.lastAssistantMessage ??
+    event?.output ??
+    event?.response ??
+    event?.message ??
+    event
+  );
+}
+
+export function formatValidationFailure(result) {
+  const parts = [];
+  if (Array.isArray(result?.validation?.violations) && result.validation.violations.length) {
+    parts.push(...result.validation.violations);
+  }
+  if (Array.isArray(result?.layer3?.failures) && result.layer3.failures.length) {
+    parts.push(...result.layer3.failures.map((failure) => failure?.detail || failure?.kind || JSON.stringify(failure)));
+  }
+  if (!parts.length && typeof result?.summary === 'string' && result.summary.trim()) {
+    parts.push(result.summary.trim());
+  }
+  return parts.join(' | ') || 'Aria validation failed.';
+}
+
+export function emitJson(payload, code = 0) {
+  process.stdout.write(\`\${JSON.stringify(payload)}\\n\`);
+  process.exit(code);
+}
+`;
+}
+
+function buildCodexUserPromptHook(): string {
+  return `#!/usr/bin/env node
+import {
+  getHarnessClient,
+  inferSessionId,
+  inferUserId,
+  extractUserText,
+  readEventFromStdin,
+  runtimePost,
+  saveTurnState,
+  emitJson,
+} from './lib/runtime-client.mjs';
+
+const event = readEventFromStdin();
+const client = getHarnessClient();
+const userText = extractUserText(event);
+const sessionId = inferSessionId(event);
+const userId = inferUserId(event);
+
+try {
+  const packet = await client.getHarnessPacket({
+    sessionId,
+    platform: 'codex',
+    message: userText || 'codex turn start',
+  });
+  const result = await runtimePost('/mizan/pre', {
+    sessionId,
+    packet,
+    packetRequest: {
+      sessionId,
+      platform: 'codex',
+      message: userText || 'codex turn start',
+      stage: 'codex-userprompt',
+      actor: 'codex-hook',
+      system: 'codex-hook',
+    },
+    context: {
+      sessionId,
+      surface: 'codex-hooks',
+      platform: 'codex',
+      userText,
+      userId,
+    },
+  });
+  saveTurnState(sessionId, {
+    userId,
+    userText,
+    preReceiptId: result?.receipt?.receiptId || null,
+    packetTimestamp: packet?.timestamp || null,
+    lastEvent: 'UserPromptSubmit',
+  });
+  process.exit(0);
+} catch (error) {
+  emitJson({
+    decision: 'block',
+    reason: \`Aria cognition gate failed before turn start: \${error instanceof Error ? error.message : String(error)}\`,
+  });
+}
+`;
+}
+
+function buildCodexPreToolHook(): string {
+  return `#!/usr/bin/env node
+import {
+  getHarnessClient,
+  inferSessionId,
+  classifyAction,
+  summarizeTarget,
+  readEventFromStdin,
+  loadTurnState,
+  saveTurnState,
+  emitJson,
+} from './lib/runtime-client.mjs';
+
+const event = readEventFromStdin();
+const client = getHarnessClient();
+const sessionId = inferSessionId(event);
+const action = classifyAction(event);
+const target = summarizeTarget(event);
+const state = loadTurnState(sessionId);
+
+try {
+  if (!state?.preReceiptId && !state?.userText) {
+    emitJson({
+      decision: 'block',
+      reason: 'Aria pre-tool gate blocked action because this turn has no pre-turn Mizan receipt. Re-submit the prompt so cognition is established before tool use.',
+    });
+  }
+  const actionCheck = await client.checkAction(action, target);
+  if (actionCheck?.allowed === false) {
+    emitJson({
+      decision: 'block',
+      reason: actionCheck?.reason || \`Aria denied \${action}\`,
+    });
+  }
+  const toolName = String(event?.tool_name || event?.toolName || '').trim() || null;
+  const tools = Array.isArray(state?.tools) ? state.tools.slice(-24) : [];
+  tools.push({
+    at: new Date().toISOString(),
+    action,
+    toolName,
+    target,
+  });
+  saveTurnState(sessionId, {
+    tools,
+    lastEvent: 'PreToolUse',
+  });
+  process.exit(0);
+} catch (error) {
+  emitJson({
+    decision: 'block',
+    reason: \`Aria pre-tool hook failed closed: \${error instanceof Error ? error.message : String(error)}\`,
+  });
+}
+`;
+}
+
+function buildCodexPostToolHook(): string {
+  return `#!/usr/bin/env node
+import {
+  inferSessionId,
+  readEventFromStdin,
+  loadTurnState,
+  saveTurnState,
+} from './lib/runtime-client.mjs';
+
+const event = readEventFromStdin();
+const sessionId = inferSessionId(event);
+const state = loadTurnState(sessionId);
+
+try {
+  const toolResponse = JSON.stringify(event?.tool_response ?? event?.toolResponse ?? null).slice(0, 4000);
+  const toolOutputs = Array.isArray(state?.toolOutputs) ? state.toolOutputs.slice(-24) : [];
+  toolOutputs.push({
+    at: new Date().toISOString(),
+    toolName: event?.tool_name || event?.toolName || null,
+    toolResponse,
+  });
+  saveTurnState(sessionId, {
+    toolOutputs,
+    lastEvent: 'PostToolUse',
+  });
+  process.exit(0);
+} catch {
+  process.exit(0);
+}
+`;
+}
+
+function buildCodexStopHook(): string {
+  return `#!/usr/bin/env node
+import {
+  getHarnessClient,
+  inferSessionId,
+  extractAssistantText,
+  readEventFromStdin,
+  runtimePost,
+  loadTurnState,
+  clearTurnState,
+  formatValidationFailure,
+  emitJson,
+} from './lib/runtime-client.mjs';
+
+const event = readEventFromStdin();
+const client = getHarnessClient();
+const sessionId = inferSessionId(event);
+const state = loadTurnState(sessionId);
+const text = extractAssistantText(event);
+
+try {
+  if (!text) {
+    emitJson({ continue: true });
+  }
+  const validation = await runtimePost('/validate-output', {
+    text,
+    sessionId,
+    packetRequest: {
+      sessionId,
+      platform: 'codex',
+      message: state?.userText || 'codex stop validation',
+      stage: 'codex-stop',
+      actor: 'codex-hook',
+      system: 'codex-hook',
+    },
+    requireCognitionBlock: false,
+    runLayer3: true,
+  });
+  if (validation?.pass === false || validation?.validation?.passed === false || validation?.layer3?.pass === false) {
+    emitJson({
+      decision: 'block',
+      reason: \`Aria stop gate blocked output: \${formatValidationFailure(validation)}\`,
+    });
+  }
+  const post = await runtimePost('/mizan/post', {
+    sessionId,
+    text,
+    evidence: {
+      validated_output: true,
+      validation_severity: validation?.validation?.severity || 'pass',
+      layer3_pass: validation?.layer3?.pass !== false,
+      surface: 'codex-hooks',
+      tool_count: Array.isArray(state?.tools) ? state.tools.length : 0,
+    },
+    context: {
+      sessionId,
+      surface: 'codex-hooks',
+      platform: 'codex',
+      userText: state?.userText || null,
+    },
+    parentReceiptId: state?.preReceiptId || null,
+  });
+  await runtimePost('/decision/log', {
+    session_id: sessionId,
+    decision_type: 'operational',
+    category: 'codex-hooks',
+    context: \`Codex native stop hook for \${sessionId}\`,
+    decision: 'validated output release',
+    reasoning: 'Mounted Aria runtime validated the output, issued Mizan post, and preserved the turn in garden memory.',
+    summary: 'codex native stop hook validated output',
+    outcome: 'success',
+    surface: 'codex-hooks',
+    metadata: {
+      post_receipt_id: post?.receipt?.receiptId || null,
+      pre_receipt_id: state?.preReceiptId || null,
+      tool_count: Array.isArray(state?.tools) ? state.tools.length : 0,
+      validation_severity: validation?.validation?.severity || 'pass',
+      layer3_pass: validation?.layer3?.pass !== false,
+    },
+  });
+  if (typeof state?.userText === 'string' && state.userText.trim()) {
+    await client.gardenTurn(sessionId, state.userText, text, state?.userId || undefined);
+  }
+  clearTurnState(sessionId);
+  emitJson({ continue: true });
+} catch (error) {
+  emitJson({
+    decision: 'block',
+    reason: \`Aria stop hook failed closed: \${error instanceof Error ? error.message : String(error)}\`,
+  });
+}
+`;
+}
+
+function buildCodexHooksToml(codexDir: string): string {
+  const hooksDir = path.join(codexDir, 'hooks');
+  const command = (name: string) => tomlString(`node ${path.join(hooksDir, name)}`);
+  return `# BEGIN ARIA MANAGED HOOKS
+[hooks]
+managed_dir = ${tomlString(hooksDir)}
+
+[[hooks.UserPromptSubmit]]
+hooks = [{ type = "command", command = ${command('aria-userprompt-submit.mjs')} }]
+
+[[hooks.PreToolUse]]
+matcher = ".*"
+hooks = [{ type = "command", command = ${command('aria-pre-tool-use.mjs')} }]
+
+[[hooks.PostToolUse]]
+matcher = ".*"
+hooks = [{ type = "command", command = ${command('aria-post-tool-use.mjs')} }]
+
+[[hooks.Stop]]
+hooks = [{ type = "command", command = ${command('aria-stop.mjs')} }]
+# END ARIA MANAGED HOOKS
+`;
+}
+
+function installCodexHooksConfig(codexDir: string, logs: string[]): void {
+  const configPath = path.join(codexDir, 'config.toml');
+  const managedBlock = buildCodexHooksToml(codexDir);
+  const markerRegex = /# BEGIN ARIA MANAGED HOOKS[\s\S]*?# END ARIA MANAGED HOOKS\n?/m;
+  let text = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
+  if (markerRegex.test(text)) {
+    text = text.replace(markerRegex, managedBlock);
+  } else {
+    if (text && !text.endsWith('\n')) text += '\n';
+    text += `\n${managedBlock}`;
+  }
+  writeFileSync(configPath, text, { mode: 0o600 });
+  logs.push(`Installed Codex managed hooks config → ${configPath}`);
+}
+
+function installCodexHooks(codexDir: string, logs: string[]): void {
+  const hooksDir = path.join(codexDir, 'hooks');
+  mkdirSync(path.join(hooksDir, 'lib'), { recursive: true, mode: 0o755 });
+
+  const files: Array<[string, string]> = [
+    [path.join(hooksDir, 'lib', 'runtime-client.mjs'), buildCodexHookRuntimeClient()],
+    [path.join(hooksDir, 'aria-userprompt-submit.mjs'), buildCodexUserPromptHook()],
+    [path.join(hooksDir, 'aria-pre-tool-use.mjs'), buildCodexPreToolHook()],
+    [path.join(hooksDir, 'aria-post-tool-use.mjs'), buildCodexPostToolHook()],
+    [path.join(hooksDir, 'aria-stop.mjs'), buildCodexStopHook()],
+  ];
+
+  for (const [filePath, content] of files) {
+    writeFileSync(filePath, content, { mode: 0o755 });
+    try { chmodSync(filePath, 0o755); } catch {}
+  }
+
+  logs.push(`Installed Codex native hooks → ${hooksDir}`);
+  installCodexHooksConfig(codexDir, logs);
+}
+
 function buildCodexSkill(_config: AriaConfig): string {
   return `---
 name: aria-http-harness-client
@@ -111,7 +636,7 @@ That means:
 
 - the mounted runtime is the universal control plane
 - the shared SDK at \`~/.aria/sdk\` is the universal client substrate
-- Codex still does not expose Claude-style native user hook interception, so explicit runtime or SDK calls are still required for hard guarantees on this platform
+- Codex native hooks plus the runtime are the hard-gate path for this platform
 
 ## Preferred Call Paths
 
@@ -153,6 +678,8 @@ function buildCodexAgentsMd(config: AriaConfig): string {
 
 Automatically injected by @aria_asi/cli. These instructions are always on for Codex sessions.
 
+${mustReadIntro('codex')}
+
 ## Connected Repositories
 ${repoList || '(none linked yet)'}
 
@@ -173,15 +700,31 @@ ${schemaText || '(no schema images yet — run \`aria repo scan\`)'}
 - If a fix only works by weakening the contract, the mechanism is still broken. Debug the mechanism.
 
 ## 8-Lens Cognition
-Apply multi-perspective analysis for every decision:
-- Truth lens: Is this factually correct?
-- Harm lens: Could this cause damage?
-- Trust lens: Does this maintain sacred trust?
-- Power lens: Am I using capability responsibly?
-- Reflection lens: Have I thought deeply enough?
-- Context lens: Do I have full context?
-- Impact lens: What are second-order effects?
-- Beauty lens: Is this elegant and sustainable?
+Use Aria cognition as a work method, not a checklist:
+- Perceive the real substrate: user intent, repo/runtime state, loaded harness packet, memories, prior tool results, and uncertainty.
+- Infer constraints: what must be true, what must not be harmed, what prior doctrine changes, and what evidence is missing.
+- Shape the next action: choose the smallest useful tool call, edit, question, or answer that satisfies those constraints.
+- Improve the artifact: make the tool input, code change, review finding, or prose more specific because of the cognition.
+- Predict the observable result: define what would prove the action or answer succeeded before claiming it.
+- Report evidence: distinguish observed fact, bounded inference, unresolved risk, and next real action.
+
+Lens roles for decisions:
+- Truth lens: binds claims to observed evidence and missing evidence.
+- Harm lens: removes or changes actions that could damage state, trust, data, or runtime health.
+- Trust lens: preserves user intent, prior directives, and secret/infra boundaries.
+- Power lens: uses capability to serve the task, not convenience or control.
+- Reflection lens: catches mechanism failure, shortcut pressure, and repeated loops.
+- Context lens: integrates repo patterns, runtime state, and loaded substrate.
+- Impact lens: predicts downstream effects and verification predicates.
+- Beauty lens: prefers the simplest durable artifact that preserves the contract.
+
+## Structural Cognition Contract
+- Cognition is not accepted as proof by itself. It must change the next action, tool call, or output claim.
+- Each lens must affect work selection or artifact shape; do not write lenses after the decision is already made.
+- For every non-trivial output, include an \`<applied_cognition>\` block with \`decision_delta\`, \`dominant_domain\`, \`binds_to\`, \`expected_predicate\`, and \`artifact_change\`.
+- Tool-bound cognition must name the exact tool/action it constrains and the measurable predicate that proves the action succeeded.
+- Deploy or destructive actions still require \`<verify>\` and \`<expected>\` blocks before execution.
+- If cognition did not change anything, stop and re-think; \`decision_delta: none\` is treated as performative.
 `;
 }
 
@@ -253,6 +796,10 @@ function installAgentsMd(codexDir: string, config: AriaConfig, logs: string[]):
   const agentsPath = path.join(codexDir, 'AGENTS.md');
   writeFileSync(agentsPath, buildCodexAgentsMd(config), { mode: 0o644 });
   logs.push(`Installed Codex AGENTS.md → ${agentsPath}`);
+
+  const mustReadPath = path.join(codexDir, 'ARIA_MUST_READ.md');
+  writeFileSync(mustReadPath, buildMustReadGuide('codex'), { mode: 0o644 });
+  logs.push(`Installed Codex must-read guide → ${mustReadPath}`);
 }
 
 export async function connectCodex(config: AriaConfig): Promise<string[]> {
@@ -268,7 +815,9 @@ export async function connectCodex(config: AriaConfig): Promise<string[]> {
   installNodePackage(codexDir, logs);
   installAgentsMd(codexDir, config, logs);
   installSkill(codexDir, config, logs);
+  installCodexHooks(codexDir, logs);
   installAriaCognitionSkills(codexDir, logs);
+  syncDoctrineTriggerMap(logs);
   logs.push(...await connectShell('codex', config));
   return logs;
 }