0xray 3.5.5 → 4.0.1

package/scripts/node/version-manager.mjs

@@ -166,7 +166,8 @@ export function getFrameworkCounts(baseDir = rootDir) {
   const counts = {
     agents: 0,
     mcps: 0,
-    skills: 0
+    skills: 0,
+    codexTerms: 68,
   };
   
   // Count agents (.yml files in src/opencode/agents/ — source of truth)
@@ -183,7 +184,8 @@ export function getFrameworkCounts(baseDir = rootDir) {
     try {
       const mcpJson = JSON.parse(fs.readFileSync(mcpJsonPath, 'utf-8'));
       const servers = mcpJson.mcpServers || mcpJson.servers || {};
-      counts.mcps = Object.keys(servers).length;
+      const xrayServers = Object.keys(servers).filter((name) => name.startsWith('xray-'));
+      counts.mcps = xrayServers.length || 7;
     } catch {
       counts.mcps = 7;
     }
@@ -199,6 +201,17 @@ export function getFrameworkCounts(baseDir = rootDir) {
       .filter(f => fs.existsSync(path.join(skillsDir, f, 'SKILL.md')))
       .length;
   }
+
+  const codexPath = path.join(baseDir, 'xray/codex.json');
+  if (fs.existsSync(codexPath)) {
+    try {
+      const codex = JSON.parse(fs.readFileSync(codexPath, 'utf-8'));
+      const terms = codex.terms && typeof codex.terms === 'object' ? Object.keys(codex.terms) : [];
+      if (terms.length > 0) counts.codexTerms = terms.length;
+    } catch {
+      /* keep default */
+    }
+  }
   
   return counts;
 }
@@ -271,10 +284,11 @@ function updateReadme(counts, newVersion) {
   
   let readme = fs.readFileSync(readmePath, 'utf-8');
 
-  // Update header line: **v3.4.1** — 42 agents · 45 skills · 7 MCP servers · ...
+  // Kernel header (4.0): exo, not catalog counts
+  const kernel = buildDocsHeader(counts, newVersion);
   readme = readme.replace(
-    /^\*\*v[\d.]+\*\* — \d+ agents · \d+ skills · \d+ MCP servers? · \d+ codex terms(?: · [\d,]+ tests)?/m,
-    `**v${newVersion}** — ${counts.agents} agents · ${counts.skills} skills · ${counts.mcps} MCP servers · 68 codex terms · 3,226 tests`
+    /^\*\*v[\d.]+\*\* — (?:\d+ agents · \d+ skills · \d+ MCP servers? · \d+ codex terms(?: · [\d,]+ tests)?|a suit that survives the context window.*)$/m,
+    kernel,
   );
   
   // Update version badge: [![Version](https://img.shields.io/badge/version-1.6.x-blue...)]
@@ -306,20 +320,23 @@ function updateReadme(counts, newVersion) {
 }
 
 export const DOCS_SITE_HEADER_FILES = [
-  'docs-site/docs/README.md',
   'docs-site/docs/index.md',
   'docs-site/docs/introduction.md',
   'docs-site/docs/guides/getting-started.md',
   'docs-site/docs/full-reference.md',
+  'docs-site/docs/architecture/GROK_GUIDE.md',
+  'docs-site/docs/mcp/README.md',
+  'docs-site/docs/agents/README.md',
 ];
 
-export function buildDocsHeader(counts, newVersion) {
-  return `**v${newVersion}** — ${counts.agents} agents · ${counts.skills} skills · ${counts.mcps} MCP servers · 68 codex terms · 3,226 tests`;
+export function buildDocsHeader(_counts, newVersion) {
+  return `**v${newVersion}** — a suit that survives the context window`;
 }
 
 function syncDocsSiteHeaders(counts, newVersion) {
   const header = buildDocsHeader(counts, newVersion);
-  const headerRe = /^\*{0,2}v?[\d.]*\*{0,2}\s*—?\s*\d+ agents · \d+ skills · \d+ MCP servers? · \d+ codex terms(?: · [\d,]+ tests)?/m;
+  const headerRe =
+    /^\*{0,2}v?[\d.]*\*{0,2}\s*—?\s*(?:\d+ agents · \d+ skills · \d+ MCP servers? · \d+ codex terms(?: · [\d,]+ tests)?|a suit that survives the context window.*|exo, not toolset.*|wear the exo.*)/im;
   for (const rel of DOCS_SITE_HEADER_FILES) {
     const filePath = path.join(rootDir, rel);
     if (!fs.existsSync(filePath)) continue;
@@ -341,13 +358,29 @@ function updatePluginJsonVersion(newVersion) {
   console.log(`✅ Updated .grok-plugin/plugin.json (version: ${newVersion})`);
 }
 
+function updateJsonVersionField(relPath, newVersion) {
+  const full = path.join(rootDir, relPath);
+  if (!fs.existsSync(full)) return;
+  const data = JSON.parse(fs.readFileSync(full, 'utf-8'));
+  data.version = newVersion;
+  fs.writeFileSync(full, JSON.stringify(data, null, 2) + '\n');
+}
+
+function updateFeaturesJsonVersion(newVersion) {
+  updateJsonVersionField('xray/features.json', newVersion);
+}
+
+function updateOpenclawPluginVersion(newVersion) {
+  updateJsonVersionField('src/integrations/openclaw/plugin/xray-pre-tool/package.json', newVersion);
+}
+
 function updateConsumerAgentsHeader(newVersion, counts) {
   const consumerPath = path.join(rootDir, 'AGENTS-consumer.md');
   if (!fs.existsSync(consumerPath)) return;
   let content = fs.readFileSync(consumerPath, 'utf-8');
   content = content.replace(
-    /^\*\*v[\d.]+\*\* — \d+ MCP servers · \d+ skills · \d+ codex terms/m,
-    `**v${newVersion}** — ${counts.mcps} MCP servers · ${counts.skills} skills · 68 codex terms`
+    /^\*\*v[\d.]+\*\* — .+$/m,
+    buildDocsHeader(counts, newVersion),
   );
   fs.writeFileSync(consumerPath, content);
   console.log(`✅ Updated AGENTS-consumer.md version header`);
@@ -386,15 +419,20 @@ function applyAgentCountUpdates(content, counts) {
 /**
  * Update AGENTS.md with actual framework counts
  */
-function updateAgentsMd(counts) {
+function updateAgentsMd(counts, newVersion = getCurrentVersion()) {
   const agentsPath = path.join(rootDir, 'AGENTS.md');
   if (!fs.existsSync(agentsPath)) {
-    console.log(`⚠️  AGENTS.md not found, skipping`);
     return;
   }
 
-  fs.writeFileSync(agentsPath, applyAgentCountUpdates(fs.readFileSync(agentsPath, 'utf-8'), counts));
-  console.log(`✅ Updated AGENTS.md`);
+  let agentsMd = applyAgentCountUpdates(fs.readFileSync(agentsPath, 'utf-8'), counts);
+  agentsMd = agentsMd.replace(/\(\*\*v[\d.]+\*\*\)/, `(**v${newVersion}**)`);
+  agentsMd = agentsMd.replace(
+    /^\*\*v[\d.]+\*\* — a suit that survives the context window\.?$/m,
+    buildDocsHeader(counts, newVersion),
+  );
+  agentsMd = agentsMd.replace(/^## Postinstall \(v[\d.]+\)$/m, `## Postinstall (v${newVersion})`);
+  fs.writeFileSync(agentsPath, agentsMd);
 }
 
 function updateAgentsConsumerMd(counts) {
@@ -501,8 +539,10 @@ function updateVersion(newVersion, changeDescription = '') {
   updateReadme(counts, newVersion);
   syncDocsSiteHeaders(counts, newVersion);
   updatePluginJsonVersion(newVersion);
+  updateFeaturesJsonVersion(newVersion);
+  updateOpenclawPluginVersion(newVersion);
   updateConsumerAgentsHeader(newVersion, counts);
-  updateAgentsMd(counts);
+  updateAgentsMd(counts, newVersion);
   updateAgentsConsumerMd(counts);
   updateSkillsMd(counts, newVersion);
   
@@ -540,7 +580,6 @@ export function getReleaseArtifactPaths() {
     'SKILLS.md',
     '.grok-plugin/plugin.json',
     'docs/README.md',
-    'docs-site/docs/README.md',
     'docs-site/docs/index.md',
     'docs-site/docs/introduction.md',
     'docs-site/docs/guides/getting-started.md',
@@ -554,7 +593,9 @@ export function getReleaseArtifactPaths() {
     'docs-site/docs/guides/consumer-migration.md',
     'docs-site/docs/mcp/README.md',
     'docs-site/docs/agents/README.md',
+    'docs-site/docs/architecture/GROK_GUIDE.md',
     'docs-site/sidebars.ts',
+    'xray/features.json',
   ];
   return candidates.filter((rel) => fs.existsSync(path.join(rootDir, rel)));
 }
@@ -569,9 +610,11 @@ function updateReleaseArtifactsOnly(changeDescription = '') {
   updateReadme(counts, current);
   syncDocsSiteHeaders(counts, current);
   updatePluginJsonVersion(current);
+  updateFeaturesJsonVersion(current);
+  updateOpenclawPluginVersion(current);
   updateConsumerAgentsHeader(current, counts);
   updateDocsReadme(current);
-  updateAgentsMd(counts);
+  updateAgentsMd(counts, current);
   updateAgentsConsumerMd(counts);
   updateSkillsMd(counts, current);
   runReleaseDocsValidation();
@@ -633,6 +676,8 @@ function main() {
     updateReadme(counts, current);
     syncDocsSiteHeaders(counts, current);
     updatePluginJsonVersion(current);
+    updateFeaturesJsonVersion(current);
+    updateOpenclawPluginVersion(current);
     updateConsumerAgentsHeader(current, counts);
     updateDocsReadme(current);
     updateAgentsMd(counts);

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

@@ -2,15 +2,11 @@
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": ".*",
         "hooks": [
           {
             "type": "command",
-            "command": "node",
-            "args": [
-              "${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/pre-tool-use.js"
-            ],
-            "timeout": 30000
+            "command": "XRAY_AI_PATH=\"${XRAY_AI_PATH:-node_modules/0xray}\" node \"${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/pre-tool-use.js\"",
+            "timeout": 30
           }
         ]
       }
@@ -20,11 +16,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node",
-            "args": [
-              "${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/session-start.js"
-            ],
-            "timeout": 15000
+            "command": "XRAY_AI_PATH=\"${XRAY_AI_PATH:-node_modules/0xray}\" node \"${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/session-start.js\"",
+            "timeout": 30
           }
         ]
       }
@@ -34,30 +27,44 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node",
-            "args": [
-              "${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/session-start.js",
-              "--hook-event=user_prompt_submit"
-            ],
-            "timeout": 15000
+            "command": "XRAY_AI_PATH=\"${XRAY_AI_PATH:-node_modules/0xray}\" node \"${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/session-start.js\" --hook-event=user_prompt_submit",
+            "timeout": 30
           }
         ]
       }
     ],
     "PostToolUse": [
       {
-        "matcher": ".*",
         "hooks": [
           {
             "type": "command",
-            "command": "node",
-            "args": [
-              "${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/post-tool-use.js"
-            ],
-            "timeout": 15000
+            "command": "XRAY_AI_PATH=\"${XRAY_AI_PATH:-node_modules/0xray}\" node \"${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/post-tool-use.js\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "XRAY_AI_PATH=\"${XRAY_AI_PATH:-node_modules/0xray}\" node \"${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/session-start.js\" --hook-event=pre_compact",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "XRAY_AI_PATH=\"${XRAY_AI_PATH:-node_modules/0xray}\" node \"${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/session-start.js\" --hook-event=post_compact",
+            "timeout": 30
           }
         ]
       }
     ]
   }
-}
+}

package/src/integrations/openclaw/README.md

@@ -0,0 +1,134 @@
+# OpenClaw Integration
+
+0xray integration for OpenClaw - a self-hosted AI gateway that connects messaging platforms to AI coding agents.
+
+## Overview
+
+This integration allows 0xray to:
+- Connect to OpenClaw Gateway via WebSocket
+- Expose 0xray capabilities through OpenClaw skills
+- Send tool execution events to OpenClaw for real-time tracking
+- Receive commands from OpenClaw channels (WhatsApp, Telegram, Discord, etc.)
+
+## Architecture
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│   User       │────▶│  OpenClaw    │────▶│   0xray   │
+│  (WhatsApp,  │     │   Gateway    │     │    Skills    │
+│  Discord,    │     │              │     │              │
+│  Telegram)   │◀────│              │◀────│              │
+└──────────────┘     └──────────────┘     └──────────────┘
+                           │
+                           ▼
+                   ┌──────────────┐
+                   │  WebSocket   │
+                   │   Client     │
+                   └──────────────┘
+```
+
+## Installation
+
+### 1. Install Dependencies
+
+```bash
+npm install ws
+```
+
+### 2. Configure OpenClaw
+
+Create `.xray/config/openclaw.json`:
+
+```json
+{
+  "gatewayUrl": "ws://127.0.0.1:18789",
+  "authToken": "your-auth-token",
+  "deviceId": "your-device-id",
+  "apiServer": {
+    "enabled": true,
+    "port": 18431,
+    "host": "127.0.0.1",
+    "apiKey": "your-api-key"
+  },
+  "hooks": {
+    "enabled": true
+  },
+  "enabled": true
+}
+```
+
+### 3. Install OpenClaw Skills
+
+Copy skills to your OpenClaw skills directory:
+
+```bash
+cp -r skills/* ~/.openclaw/skills/
+```
+
+## Usage
+
+### Initialize Integration
+
+```typescript
+import { initializeOpenClawIntegration } from './src/integrations/openclaw/index.js';
+
+const integration = await initializeOpenClawIntegration();
+
+// Or with custom agent invoker
+const integration = await initializeOpenClawIntegration('/path/to/config.json', myAgentInvoker);
+```
+
+### Using OpenClaw Commands
+
+After installation, use these commands in any OpenClaw channel:
+
+- `/xray` - Show status
+- `/xray-analyze <file>` - Analyze code
+- `/xray-code <file>` - Code review
+- `/xray-file <file>` - Read file
+- `/xray-exec <command>` - Execute command
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `gatewayUrl` | string | `ws://127.0.0.1:18789` | OpenClaw WebSocket URL |
+| `authToken` | string | - | Authentication token |
+| `deviceId` | string | - | Device ID for pairing |
+| `apiServer.enabled` | boolean | `true` | Enable HTTP API server |
+| `apiServer.port` | number | `18431` | API server port |
+| `apiServer.host` | string | `127.0.0.1` | API server host |
+| `apiServer.apiKey` | string | - | API key for auth |
+| `hooks.enabled` | boolean | `true` | Enable tool hooks |
+| `autoReconnect` | boolean | `true` | Auto reconnect |
+| `enabled` | boolean | `true` | Enable integration |
+
+## API Server
+
+The integration exposes a local HTTP API on port 18431:
+
+- `GET /health` - Health check
+- `POST /api/agent/invoke` - Invoke agent
+- `GET /api/agent/status` - Agent status
+
+## Skills
+
+### 0xray-orchestrator
+
+Main skill providing 0xray commands:
+
+```markdown
+/xray                    - Show status
+/xray-analyze <file>    - Analyze code
+/xray-code <file>       - Code review
+/xray-file <file>       - Read file
+/xray-exec <command>    - Execute command
+```
+
+## Documentation
+
+See `docs/research/openclaw/` for detailed documentation.
+
+## License
+
+MIT

package/src/integrations/openclaw/plugin/xray-pre-tool/index.js

@@ -0,0 +1,75 @@
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
+
+const require = createRequire(import.meta.url);
+const pluginDir = dirname(fileURLToPath(import.meta.url));
+
+function hasGate(root) {
+  return Boolean(root) && existsSync(join(root, 'dist/nucleus/delegation-gate.js'));
+}
+
+function resolveXrayRoot() {
+  if (hasGate(process.env.XRAY_AI_PATH || '')) {
+    return process.env.XRAY_AI_PATH;
+  }
+  const marker = join(homedir(), '.openclaw', 'xray-consumer-root.txt');
+  const marked = existsSync(marker) ? readFileSync(marker, 'utf8').trim() : '';
+  const candidates = [
+    marked,
+    marked ? join(marked, 'node_modules', '0xray') : '',
+    marked ? join(marked, '..', 'xray') : '',
+    // Linked plugin lives at src/integrations/openclaw/plugin/xray-pre-tool
+    join(pluginDir, '..', '..', '..', '..', '..'),
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    if (hasGate(candidate)) {
+      return candidate;
+    }
+  }
+  return '';
+}
+
+export default definePluginEntry({
+  id: 'xray-pre-tool',
+  name: '0xRay PreToolUse',
+  register(api) {
+    api.on(
+      'before_tool_call',
+      (event, ctx) => {
+        try {
+          const xrayRoot = resolveXrayRoot();
+          if (!xrayRoot) {
+            return { block: true, blockReason: '0xRay dist missing — set XRAY_AI_PATH' };
+          }
+          const gate = require(join(xrayRoot, 'dist/nucleus/delegation-gate.js'));
+          const projectRoot =
+            process.env.XRAY_ROOT ||
+            ctx?.workspaceDir ||
+            ctx?.cwd ||
+            process.cwd();
+          const features = gate.loadDelegationGateFeatures(projectRoot, 'openclaw');
+          const outcome = gate.evaluatePreToolGate(event.toolName, event.params || {}, {
+            projectRoot,
+            sessionId: ctx?.sessionId || ctx?.sessionKey || 'openclaw',
+            features,
+            host: 'openclaw',
+          });
+          if (!outcome.allow) {
+            return { block: true, blockReason: outcome.reason || '0xRay constitution' };
+          }
+          return undefined;
+        } catch (err) {
+          return {
+            block: true,
+            blockReason: err instanceof Error ? err.message : String(err),
+          };
+        }
+      },
+      { priority: 80 },
+    );
+  },
+});

package/src/integrations/openclaw/plugin/xray-pre-tool/openclaw.plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "xray-pre-tool",
+  "name": "0xRay PreToolUse",
+  "description": "Constitution and temperament gate for OpenClaw tool calls (Codex 11/29/69, spawn plan).",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/src/integrations/openclaw/plugin/xray-pre-tool/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "xray-pre-tool",
+  "version": "4.0.1",
+  "private": true,
+  "type": "module",
+  "description": "0xRay constitution + temperament PreToolUse for OpenClaw",
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ]
+  }
+}

package/src/mcps/orchestrator/handlers/complexity-handler.ts

@@ -133,7 +133,7 @@ export class ComplexityHandler {
 
       let userAsideReport = '';
       let leadDevPlan = synthesisCheckpoint
-        ? buildSynthesisCheckpointPlan(args.synthesisDueReason ?? null)
+        ? buildSynthesisCheckpointPlan(args.synthesisDueReason ?? null, projectRoot)
         : userAsideIntake
           ? null
           : isLeadDevModeActive() && (primaryDescription || planTaskInputs.length > 0)
@@ -142,6 +142,7 @@ export class ComplexityHandler {
                 taskTypes.length ? taskTypes : ['implement'],
                 planTaskInputs,
                 analysis.overallComplexity,
+                projectRoot,
               )
             : null;