0xray 3.4.1 → 3.4.3

package/dist/integrations/grok/hooks/grok-hook-utils.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * Shared utilities for Grok CLI hooks — codex load, features, surface checks.
+ * Pure JS (no TS build) so hooks run from dist/ without compilation surprises.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+export const LEAD_DEV_RULES = [
+  'Phased plan + todos; assign best subagent; monitor output',
+  'Lead dev loops test→fix until green; no permission pings',
+  'Per-suite test triage; full suite last',
+  'Lead stays main; subagents execute; update todos',
+  'Read all output; triage fix rerun',
+  'No buck-passing — resolve every error',
+  'Zero open errors at phase completion',
+];
+
+/** Blocking codex patterns detectable in proposed edits (term → regex + message) */
+export const CODEX_BLOCK_PATTERNS = [
+  { terms: [11], pattern: /:\s*any\b|as\s+any\b/g, message: 'Codex 11 Type Safety: no `any` types' },
+  { terms: [11], pattern: /@ts-ignore|@ts-expect-error/g, message: 'Codex 11 Type Safety: no @ts-ignore / @ts-expect-error' },
+  { terms: [29], pattern: /\beval\s*\(/g, message: 'Codex 29 Security: eval() prohibited' },
+  { terms: [2], pattern: /\bTODO\b|\bFIXME\b|\bSTUB\b/g, message: 'Codex 2: no TODO/FIXME/STUB in production code' },
+  { terms: [7], pattern: /console\.log\s*\(/g, message: 'Codex 7: no console.log debugging' },
+];
+
+/** New-surface paths blocked when no_new_surface is on (codex 69) */
+export const SURFACE_DENY_PATTERNS = [
+  { pattern: /(?:^|\/)src\/mcps\/[^/]+\.server\.(ts|js)$/i, message: 'Codex 69: new MCP server — rewire existing mcps/' },
+  { pattern: /(?:^|\/)src\/skills\/[^/]+\/SKILL\.md$/i, message: 'Codex 69: new skill — extend orchestrator skill or existing mcps' },
+  { pattern: /(?:^|\/)src\/mcps\/orchestrator\/handlers\/[^/]+-handler\.(ts|js)$/i, message: 'Codex 69: new orchestrator handler — merge into complexity-handler' },
+  { pattern: /(?:^|\/)src\/nucleus\/autonomy-kernel\.(ts|js)$/i, message: 'Codex 69: parallel autonomy kernel — use existing nucleus' },
+  { pattern: /(?:^|\/)src\/mcps\/[^/]+\/handlers\/autonomy-handler\.(ts|js)$/i, message: 'Codex 69: autonomy-handler removed — use complexity-handler' },
+];
+
+const SUBAGENT_TOOLS = new Set([
+  'spawn_subagent',
+  'task',
+  'Task',
+]);
+
+const WRITE_TOOLS = new Set([
+  'search_replace',
+  'write',
+  'Write',
+  'Edit',
+  'MultiEdit',
+  'edit_notebook',
+  'EditNotebook',
+]);
+
+export function workspaceRoot() {
+  return (
+    process.env.GROK_WORKSPACE_ROOT ||
+    process.env.CLAUDE_PROJECT_DIR ||
+    process.env.XRAY_ROOT ||
+    process.cwd()
+  );
+}
+
+export function resolveFeaturesPath(root = workspaceRoot()) {
+  for (const p of [
+    path.join(root, '.xray', 'features.json'),
+    path.join(process.cwd(), '.xray', 'features.json'),
+  ]) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+export function resolveCodexPath(root = workspaceRoot()) {
+  for (const p of [
+    path.join(root, '.xray', 'codex.json'),
+    path.join(process.cwd(), '.xray', 'codex.json'),
+  ]) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+export function loadFeatures() {
+  const featuresPath = resolveFeaturesPath();
+  if (!featuresPath) return { lead_dev_mode: true, no_new_surface: true, per_suite_triage: true };
+  try {
+    const data = JSON.parse(fs.readFileSync(featuresPath, 'utf8'));
+    const orch = data.multi_agent_orchestration ?? {};
+    return {
+      lead_dev_mode: orch.enabled !== false && orch.lead_dev_mode !== false,
+      no_new_surface: orch.no_new_surface !== false,
+      per_suite_test_triage: orch.per_suite_test_triage !== false,
+    };
+  } catch {
+    return { lead_dev_mode: true, no_new_surface: true, per_suite_triage: true };
+  }
+}
+
+export function loadBlockingCodexTerms() {
+  const codexPath = resolveCodexPath();
+  if (!codexPath) return [];
+  try {
+    const data = JSON.parse(fs.readFileSync(codexPath, 'utf8'));
+    const terms = data.terms ?? {};
+    return Object.values(terms).filter(
+      (t) => t.enforcementLevel === 'blocking' || t.zeroTolerance === true,
+    );
+  } catch {
+    return [];
+  }
+}
+
+export function leadDevPlanPath(root = workspaceRoot()) {
+  return path.join(root, '.xray', 'state', 'lead-dev-plan.json');
+}
+
+export function hasFreshLeadDevPlan(maxAgeMs = 4 * 60 * 60 * 1000) {
+  const planPath = leadDevPlanPath();
+  if (!fs.existsSync(planPath)) return false;
+  try {
+    const stat = fs.statSync(planPath);
+    if (Date.now() - stat.mtimeMs > maxAgeMs) return false;
+    const plan = JSON.parse(fs.readFileSync(planPath, 'utf8'));
+    return plan.active === true;
+  } catch {
+    return false;
+  }
+}
+
+export function extractToolContext(event) {
+  const toolName = event.toolName || process.env.TOOL_NAME || 'unknown';
+  const toolInput = event.toolInput ?? {};
+  const paths = [];
+  let content = '';
+
+  if (toolInput.path) paths.push(String(toolInput.path));
+  if (toolInput.file_path) paths.push(String(toolInput.file_path));
+  if (toolInput.target_notebook) paths.push(String(toolInput.target_notebook));
+  if (Array.isArray(toolInput.paths)) paths.push(...toolInput.paths.map(String));
+
+  if (toolInput.new_string) content += String(toolInput.new_string);
+  if (toolInput.contents) content += String(toolInput.contents);
+  if (toolInput.command) content += String(toolInput.command);
+  if (toolInput.prompt) content += String(toolInput.prompt);
+
+  return { toolName, toolInput, paths, content, cmd: String(toolInput.command || '') };
+}
+
+export function checkCodexPatterns(content) {
+  if (!content) return null;
+  for (const { message, pattern } of CODEX_BLOCK_PATTERNS) {
+    if (pattern.test(content)) return message;
+    pattern.lastIndex = 0;
+  }
+  return null;
+}
+
+export function checkSurfaceArea(paths, root = workspaceRoot()) {
+  for (const rel of paths) {
+    const normalized = rel.replace(/\\/g, '/');
+    const abs = path.isAbsolute(rel) ? rel : path.join(root, rel);
+    if (fs.existsSync(abs)) continue;
+    for (const { pattern, message } of SURFACE_DENY_PATTERNS) {
+      if (pattern.test(normalized)) return `${message} (blocked: ${normalized})`;
+    }
+  }
+  return null;
+}
+
+export function checkSubagentGate(toolName, features) {
+  if (!features.lead_dev_mode) return null;
+  if (!SUBAGENT_TOOLS.has(toolName)) return null;
+  if (hasFreshLeadDevPlan()) return null;
+  return (
+    'Codex 59/67: call xray-orchestrator analyze-complexity first — ' +
+    'writes .xray/state/lead-dev-plan.json required before spawn_subagent'
+  );
+}
+
+export function checkFullTestSuite(cmd, features) {
+  if (!features.per_suite_test_triage) return null;
+  const cmdText = cmd.toLowerCase();
+  const isFullTestSuite =
+    /\b(npm\s+(run\s+)?test|vitest\s+run|pnpm\s+test|yarn\s+test)\b/.test(cmdText) &&
+    !/--\s+\S+\.test/.test(cmdText) &&
+    !/vitest\s+run\s+\S+\.test/.test(cmdText);
+  if (!isFullTestSuite) return null;
+  return (
+    'Lead-dev test protocol: run individual test files first; ' +
+    'full suite only after per-suite passes (override with focused test path)'
+  );
+}
+
+export function isWriteTool(toolName) {
+  return WRITE_TOOLS.has(toolName) || /write|edit|replace/i.test(toolName);
+}
+
+export function isShellTool(toolName) {
+  return /terminal|bash|shell|run_terminal/i.test(toolName);
+}
+
+export async function readStdinJson() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const raw = Buffer.concat(chunks).toString('utf8').trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+export function sessionBootPath(root = workspaceRoot()) {
+  return path.join(root, '.xray', 'state', 'session-boot.json');
+}
+
+export function buildSessionBootPayload(root, source = '0xray/grok-session-start', extra = {}) {
+  const features = loadFeatures();
+  const blockingTerms = loadBlockingCodexTerms();
+  return {
+    hook: source,
+    lead_dev_mode: features.lead_dev_mode,
+    no_new_surface: features.no_new_surface,
+    codexBlockingTermCount: blockingTerms.length,
+    codexTerms: [59, 67, 68, 69],
+    rules: features.lead_dev_mode ? LEAD_DEV_RULES : [],
+    mcpIntake: 'xray-orchestrator → analyze-complexity (required before spawn_subagent)',
+    enforcement: 'PreToolUse hook — codex patterns + surface area + spawn gate',
+    workspaceRoot: root,
+    sessionId: process.env.GROK_SESSION_ID || null,
+    timestamp: new Date().toISOString(),
+    source,
+    ...extra,
+  };
+}
+
+export function writeSessionBoot(root, payload) {
+  try {
+    const stateDir = path.join(root, '.xray', 'state');
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(sessionBootPath(root), JSON.stringify(payload, null, 2));
+    return sessionBootPath(root);
+  } catch {
+    return null;
+  }
+}
+
+/** Boot on SessionStart, UserPromptSubmit, or first PreToolUse if missing. */
+export function ensureSessionBoot(root = workspaceRoot(), source = '0xray/grok-boot') {
+  const bootPath = sessionBootPath(root);
+  if (fs.existsSync(bootPath)) {
+    try {
+      const existing = JSON.parse(fs.readFileSync(bootPath, 'utf8'));
+      if (existing.lead_dev_mode !== undefined) return bootPath;
+    } catch {
+      /* rewrite corrupt boot */
+    }
+  }
+  return writeSessionBoot(root, buildSessionBootPayload(root, source));
+}

package/dist/integrations/grok/hooks/pre-tool-use.js

@@ -1,134 +1,104 @@
 #!/usr/bin/env node
 /**
- * Grok CLI PreToolUse Hook Handler for 0xRay — First Class Citizen
- *
- * Real governance enforcement hook.
- * When Grok is about to execute a tool (write_file, edit, terminal cmd, etc.),
- * this script is spawned and runs the Dynamo Solar SSOT decision matrix.
+ * Grok CLI PreToolUse — ironclad OS gate
+ * Contract: stdin JSON → stdout {"decision":"allow"} | {"decision":"deny","reason":"..."}
  */
 
-import fs from 'fs';
-import path from 'path';
+import {
+  checkCodexPatterns,
+  checkFullTestSuite,
+  checkSubagentGate,
+  checkSurfaceArea,
+  ensureSessionBoot,
+  isShellTool,
+  isWriteTool,
+  loadFeatures,
+  readStdinJson,
+  workspaceRoot,
+} from './grok-hook-utils.js';
+import { appendHookActivity } from './grok-hook-activity.js';
 
-const log = (msg) => { try { console.error(`[0xRay:GrokHook] ${msg}`); } catch { /* noop */ } };
+function finish(root, decision, reason, hint, toolName) {
+  const out = { decision };
+  if (reason) out.reason = reason;
+  if (hint) out.hint = hint;
+  console.log(JSON.stringify(out));
+  appendHookActivity(root, 'grok-pre-tool-use', decision, decision === 'deny' ? 'error' : 'info', {
+    tool: toolName,
+    reason: reason || hint || null,
+    livePath: true,
+  });
+  process.exit(0);
+}
 
-function findGovernanceCore() {
-  const here = path.dirname(new URL(import.meta.url).pathname);
+async function main() {
+  const root = workspaceRoot();
+  let toolName = 'unknown';
 
-  // Priority: explicit dev root
-  const devRoot = process.env.XRAY_ROOT;
-  if (devRoot) {
-    const devCandidate = path.resolve(devRoot, 'dist/governance/governance-core.js');
-    if (fs.existsSync(devCandidate)) return devCandidate;
-  }
+  try {
+    const event = await readStdinJson();
+    const eventRoot = event.workspaceRoot || event.cwd || root;
+    ensureSessionBoot(eventRoot, '0xray/grok-pre-tool-use-boot');
 
-  const candidates = [
-    // Published package layout
-    path.resolve(here, '../../../governance/governance-core.js'),
-    path.resolve(here, '../../../../governance/governance-core.js'),
-    // node_modules installed layout
-    path.resolve(process.cwd(), 'node_modules/0xray/dist/governance/governance-core.js'),
-    // Dev layout fallbacks (no extra dist/)
-    path.resolve(here, '../../../../../governance/governance-core.js'),
-    path.resolve(process.cwd(), 'dist/governance/governance-core.js'),
-    // Strong dev fallback: walk up looking for package.json
-    ...walkUpForCore(here),
-  ];
-
-  for (const c of candidates) {
-    if (fs.existsSync(c)) return c;
-  }
-  return null;
-}
+    const features = loadFeatures();
+    const ctx = extractFromEvent(event);
+    toolName = ctx.toolName;
+    const { paths, content, cmd } = ctx;
 
-function walkUpForCore(startDir, maxLevels = 8) {
-  const results = [];
-  let current = startDir;
-  for (let i = 0; i < maxLevels; i++) {
-    const pkgPath = path.resolve(current, 'package.json');
-    if (fs.existsSync(pkgPath)) {
-      try {
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-        if (pkg.name === '0xray') {
-          results.push(path.resolve(current, 'dist/governance/governance-core.js'));
-          results.push(path.resolve(current, 'governance/governance-core.js'));
-        }
-      } catch {}
+    const subagentBlock = checkSubagentGate(toolName, features);
+    if (subagentBlock) finish(eventRoot, 'deny', subagentBlock, null, toolName);
+
+    if (features.no_new_surface && isWriteTool(toolName) && paths.length) {
+      const surfaceBlock = checkSurfaceArea(paths, eventRoot);
+      if (surfaceBlock) finish(eventRoot, 'deny', surfaceBlock, null, toolName);
     }
-    const parent = path.dirname(current);
-    if (parent === current) break;
-    current = parent;
-  }
-  return results;
-}
 
-function deriveResonance(toolName, extra = '') {
-  const text = (toolName + ' ' + extra).toLowerCase();
-  let score = 0.85; // baseline good
-  const penalties = [
-    ['any', -0.25],
-    ['eval(', -0.35],
-    ['console.log', -0.15],
-    ['// @ts-ignore', -0.2],
-    ['require(', -0.1],
-  ];
-  for (const [pat, pen] of penalties) {
-    if (text.includes(pat)) score += pen;
-  }
-  return Math.max(0.1, Math.min(0.99, score));
-}
+    if (isWriteTool(toolName) && content) {
+      const codexBlock = checkCodexPatterns(content);
+      if (codexBlock) finish(eventRoot, 'deny', codexBlock, null, toolName);
+    }
 
-async function main() {
-  try {
-    const toolName = process.env.TOOL_NAME || process.env.HOOK_TOOL || 'unknown_tool';
-    const cwd = process.env.PWD || process.cwd();
-    const extraContext = process.env.HOOK_ARGS || process.env.TOOL_ARGS || '';
-
-    log(`PreToolUse: ${toolName}`);
-
-    const corePath = findGovernanceCore();
-    let recommendation = 'ALLOW';
-    let resonance = deriveResonance(toolName, extraContext);
-    let govDetails = null;
-
-    if (corePath) {
-      try {
-        const core = await import(`file://${corePath}`);
-        if (typeof core.applyDecisionMatrix === 'function') {
-          const result = core.applyDecisionMatrix({
-            resonance,
-            isotopicRatio: resonance > 0.8 ? 0.96 : 0.7,
-            vortexVolume: 1_000_000,
-            historicalCoherence: 0.82,
-            solarActivity: 'active',
-          });
-          govDetails = result;
-          recommendation = result.recommendation || 'NEEDS_REVISION';
-          log(`Solar decision: ${recommendation} (resonance=${resonance.toFixed(2)})`);
-        }
-      } catch (e) {
-        log(`Governance core error: ${e.message}`);
-      }
-    } else {
-      log('Governance core not located — using safe default');
+    if (isShellTool(toolName) && cmd) {
+      const destructive =
+        /\brm\s+-rf\s+\/\b|\bmkfs\b|\bdd\s+if=|:()\s*\{\s*:\|&\s*\}\s*;:/i.test(cmd);
+      if (destructive) finish(eventRoot, 'deny', 'Blocked destructive shell command', null, toolName);
+
+      const testHint = checkFullTestSuite(cmd, features);
+      if (testHint) finish(eventRoot, 'allow', null, testHint, toolName);
     }
 
-    const decision = {
-      tool: toolName,
-      decision: recommendation === 'PASS' ? 'allow' : 'allow_with_governance_note',
-      resonance: Number(resonance.toFixed(3)),
-      solar_recommendation: recommendation,
-      gov: govDetails,
-      timestamp: new Date().toISOString(),
-      source: '0xray/grok-pre-tool-use',
-    };
-
-    console.log(JSON.stringify(decision));
-    process.exit(0); // non-blocking rollout; future versions can exit(1) on strong reject
+    finish(eventRoot, 'allow', null, null, toolName);
   } catch (err) {
-    log(`Hook failure (non-fatal): ${err.message}`);
-    process.exit(0);
+    appendHookActivity(root, 'grok-pre-tool-use', 'hook-error', 'error', {
+      tool: toolName,
+      error: err.message,
+    });
+    finish(root, 'allow', null, null, toolName);
   }
 }
 
+function extractFromEvent(event) {
+  const toolName = event.toolName || process.env.TOOL_NAME || 'unknown';
+  const toolInput = event.toolInput ?? {};
+  const paths = [];
+  let content = '';
+
+  if (toolInput.path) paths.push(String(toolInput.path));
+  if (toolInput.file_path) paths.push(String(toolInput.file_path));
+  if (toolInput.target_notebook) paths.push(String(toolInput.target_notebook));
+  if (Array.isArray(toolInput.paths)) paths.push(...toolInput.paths.map(String));
+
+  if (toolInput.new_string) content += String(toolInput.new_string);
+  if (toolInput.contents) content += String(toolInput.contents);
+  if (toolInput.command) content += String(toolInput.command);
+  if (toolInput.prompt) content += String(toolInput.prompt);
+
+  return {
+    toolName,
+    paths,
+    content,
+    cmd: String(toolInput.command || ''),
+  };
+}
+
 main();

package/dist/integrations/grok/hooks/session-start.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * Grok SessionStart / UserPromptSubmit — writes session-boot.json + activity.log.
+ * Stdout is ignored by Grok for these events; side effects are the suit contract.
+ */
+
+import {
+  buildSessionBootPayload,
+  ensureSessionBoot,
+  readStdinJson,
+  workspaceRoot,
+  writeSessionBoot,
+} from './grok-hook-utils.js';
+import { appendHookActivity } from './grok-hook-activity.js';
+
+const HOOK_EVENT = process.env.GROK_HOOK_EVENT || 'session_start';
+
+async function main() {
+  const root = workspaceRoot();
+  try {
+    const event = await readStdinJson();
+    const eventRoot = event.workspaceRoot || event.cwd || root;
+    const source =
+      HOOK_EVENT === 'user_prompt_submit'
+        ? '0xray/grok-user-prompt-submit'
+        : '0xray/grok-session-start';
+
+    const payload = buildSessionBootPayload(eventRoot, source, {
+      hookEvent: HOOK_EVENT,
+      sessionId: event.sessionId || process.env.GROK_SESSION_ID || null,
+    });
+
+    const bootPath = writeSessionBoot(eventRoot, payload) || ensureSessionBoot(eventRoot, source);
+
+    appendHookActivity(eventRoot, 'grok-session-start', 'session-boot-written', 'success', {
+      bootPath,
+      hookEvent: HOOK_EVENT,
+      lead_dev_mode: payload.lead_dev_mode,
+    });
+
+    console.log(JSON.stringify(payload));
+    process.exit(0);
+  } catch (err) {
+    appendHookActivity(root, 'grok-session-start', 'session-boot-error', 'error', {
+      error: err.message,
+      hookEvent: HOOK_EVENT,
+    });
+    process.exit(0);
+  }
+}
+
+main();

package/dist/integrations/grok/plugin/0xray/hooks/hooks.json

@@ -20,11 +20,28 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo",
-            "args": ["[0xRay] Grok session started with 0xRay governance enabled"]
+            "command": "node",
+            "args": [
+              "${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/session-start.js"
+            ],
+            "timeout": 15000
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/session-start.js"
+            ],
+            "timeout": 15000
           }
         ]
       }
     ]
   }
-}
+}

package/dist/integrations/openclaw/api-server.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 0xRay API Server
+ *
+ * HTTP API server that OpenClaw skills call to invoke 0xRay capabilities.
+ * This is the bridge between OpenClaw skills and 0xRay.
+ *
+ * @since 2026-03-14
+ */
+import { XrayAPIServerConfig, AgentInvokeRequest, AgentInvokeResponse, APIServerStatistics } from './types.js';
+/**
+ * Agent invoker interface - implemented by 0xRay
+ */
+export interface AgentInvoker {
+    invoke(request: AgentInvokeRequest): Promise<AgentInvokeResponse>;
+    getStatus?(): Promise<{
+        healthy: boolean;
+        version: string;
+    }>;
+}
+/**
+ * 0xRay API Server
+ */
+export declare class XrayAPIServer {
+    private server;
+    private config;
+    private agentInvoker;
+    private apiKey;
+    private stats;
+    private responseTimes;
+    private logger;
+    constructor(config: XrayAPIServerConfig);
+    /**
+     * Set the agent invoker
+     */
+    setAgentInvoker(invoker: AgentInvoker): void;
+    /**
+     * Start the API server
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the API server
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if server is running
+     */
+    isRunning(): boolean;
+    /**
+     * Get server statistics
+     */
+    getStats(): APIServerStatistics;
+    /**
+     * Handle incoming HTTP request
+     */
+    private handleRequest;
+    /**
+     * Handle health check request
+     */
+    private handleHealth;
+    /**
+     * Handle agent invoke request
+     */
+    private handleAgentInvoke;
+    /**
+     * Handle agent status request
+     */
+    private handleAgentStatus;
+    private handleGovern;
+    private handleApply;
+    /**
+     * Validate API key using constant-time comparison to prevent timing attacks
+     */
+    private validateApiKey;
+    /**
+     * Read request body
+     */
+    private readBody;
+    /**
+     * Send JSON response
+     */
+    private sendResponse;
+}
+/**
+ * Factory function to create API server
+ */
+export declare function createXrayAPIServer(config: XrayAPIServerConfig): XrayAPIServer;