0xray 3.3.0 → 3.4.1

package/scripts/node/postinstall.cjs

@@ -2,112 +2,53 @@
 
 const fs = require("fs");
 const path = require("path");
-const { execSync } = require("child_process");
+const {
+  installAllBridges,
+  resolveConsumerTargetDir,
+  isConsumerInstall,
+} = require("./install-bridges.cjs");
 
-// Structured logging shim (fwLogger discipline for script context; mirrors FrameworkUsageLogger format to logs/framework/activity.log in full runs)
 function structuredLog(component, action, status, details) {
   const ts = new Date().toISOString();
-  const detailsPart = details ? ` | ${JSON.stringify(details)}` : '';
+  const detailsPart = details ? ` | ${JSON.stringify(details)}` : "";
   console.log(`${ts} [${component}] ${action} - ${String(status).toUpperCase()}${detailsPart}`);
 }
 
 const packageRoot = path.join(__dirname, "..", "..");
-
-let targetDir;
-if (__dirname.includes("node_modules/xray")) {
-  // plain xray (final identity)
-  targetDir = path.join(__dirname, "..", "..", "..", "..");
-} else {
-  targetDir = process.env.PWD || process.cwd();
-}
-
+const targetDir = resolveConsumerTargetDir(packageRoot, process.env.PWD || process.cwd());
 const resolvedPackage = path.resolve(packageRoot);
 const resolvedTarget = path.resolve(targetDir);
 
-
-const SKIP_DIRS = new Set(["node_modules", "logs"]);
-
 // Copy AGENTS-consumer.md → AGENTS.md
 const agentsConsumer = path.join(packageRoot, "AGENTS-consumer.md");
 const agentsDest = path.join(targetDir, "AGENTS.md");
-if (fs.existsSync(agentsConsumer) && resolvedPackage !== resolvedTarget) {
+if (fs.existsSync(agentsConsumer) && isConsumerInstall(resolvedPackage, resolvedTarget)) {
   fs.copyFileSync(agentsConsumer, agentsDest);
 }
 
 // Copy .gitignore.default → .gitignore (never overwrite existing)
 const gitignoreSource = path.join(packageRoot, ".gitignore.default");
 const gitignoreDest = path.join(targetDir, ".gitignore");
-if (!fs.existsSync(gitignoreDest) && resolvedPackage !== resolvedTarget) {
+if (!fs.existsSync(gitignoreDest) && isConsumerInstall(resolvedPackage, resolvedTarget)) {
   fs.copyFileSync(gitignoreSource, gitignoreDest);
-  structuredLog('postinstall', 'Created .gitignore from template', 'info');
+  structuredLog("postinstall", "Created .gitignore from template", "info");
 }
 
-// Sync core skills from dist/ → .opencode/skills/
-const skillsSource = path.join(packageRoot, 'dist', 'skills');
-const skillsDest = path.join(targetDir, '.opencode', 'skills');
-if (fs.existsSync(skillsSource) && resolvedPackage !== resolvedTarget) {
+// Unified 4-platform bridge install (OpenCode, Grok, Hermes, OpenClaw)
+if (isConsumerInstall(resolvedPackage, resolvedTarget)) {
   try {
-    if (!fs.existsSync(skillsDest)) fs.mkdirSync(skillsDest, { recursive: true });
-    const skillDirs = fs.readdirSync(skillsSource, { withFileTypes: true });
-    let copied = 0, skipped = 0;
-    for (const entry of skillDirs) {
-      if (!entry.isDirectory()) continue;
-      const skillMd = path.join(skillsSource, entry.name, 'SKILL.md');
-      if (!fs.existsSync(skillMd)) continue;
-      const destMd = path.join(skillsDest, entry.name, 'SKILL.md');
-      const destDir = path.dirname(destMd);
-      if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
-      if (fs.existsSync(destMd)) {
-        if (fs.statSync(skillMd).mtime <= fs.statSync(destMd).mtime) continue;
-      }
-      fs.copyFileSync(skillMd, destMd);
-      copied++;
-    }
-    if (copied > 0) structuredLog('postinstall', `Skills: ${copied} installed to .opencode/skills/`, 'info');
+    installAllBridges({
+      targetDir,
+      packageRoot,
+      log: structuredLog,
+    });
   } catch (e) {
-    structuredLog('postinstall', `Skills sync skipped: ${e.message}`, 'warn');
+    structuredLog("postinstall", "Bridge install failed", "warn", { error: e.message });
   }
-}
-
-// Register MCP servers with Grok CLI (if available) using absolute paths to installed dist
-// Full v2 surface: governance + skills + orchestrator + enforcer (additive, preserves prior behavior)
-if (resolvedPackage !== resolvedTarget) {
-  try {
-    execSync('which grok', { stdio: 'ignore' });
-    const govServer = path.join(packageRoot, 'dist/mcps/governance.server.js');
-    const skillsServer = path.join(packageRoot, 'dist/mcps/knowledge-skills/skill-invocation.server.js');
-    const orchServer = path.join(packageRoot, 'dist/mcps/orchestrator.server.js');
-    const enforcerServer = path.join(packageRoot, 'dist/mcps/enforcer-tools.server.js');
-    const xrayRoot = targetDir;
 
-    execSync(
-      `grok mcp add xray-governance --command node --args "${govServer}" --env "XRAY_FORCE_MCP_GOVERNANCE=true" --env "XRAY_ROOT=${xrayRoot}"`,
-      { stdio: 'pipe' }
-    );
-    structuredLog('postinstall', 'Registered xray-governance with Grok CLI', 'info');
-
-    execSync(
-      `grok mcp add xray-skills --command node --args "${skillsServer}" --env "XRAY_ROOT=${xrayRoot}"`,
-      { stdio: 'pipe' }
-    );
-    structuredLog('postinstall', 'Registered xray-skills with Grok CLI', 'info');
-
-    execSync(
-      `grok mcp add xray-orchestrator --command node --args "${orchServer}" --env "XRAY_ROOT=${xrayRoot}"`,
-      { stdio: 'pipe' }
-    );
-    structuredLog('postinstall', 'Registered xray-orchestrator with Grok CLI', 'info');
-
-    execSync(
-      `grok mcp add xray-enforcer --command node --args "${enforcerServer}" --env "XRAY_ROOT=${xrayRoot}"`,
-      { stdio: 'pipe' }
-    );
-    structuredLog('postinstall', 'Registered xray-enforcer with Grok CLI', 'info');
-  } catch (_e) {
-    // grok not on PATH or registration failed — skip gracefully
-  }
-}
-
-if (resolvedPackage !== resolvedTarget) {
-  structuredLog('postinstall', 'xray v2 framework installed. Run `npx xray setup` for full configuration (hooks, Hermes, symlinks).', 'success');
-}
+  structuredLog(
+    "postinstall",
+    "0xRay framework installed (4 bridges). Run `npx 0xray setup` for symlinks/Hermes skill extras.",
+    "success"
+  );
+}

package/scripts/node/pre-publish-guard.js

@@ -92,6 +92,7 @@ function checkGitStatus() {
       'logs/',
       'backups/',
       'Users/',
+      '.xray/inference/',
     ];
     
     const realChanges = lines.filter(l => {
@@ -128,32 +129,35 @@ function checkGitStatus() {
 
 function checkVersionSync() {
   log('Checking version synchronization...', 'step');
-  
-  // Load version manager
+
+  const pkgPath = path.join(rootDir, 'package.json');
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  const pkgVersion = pkg.version;
+
   const vmPath = path.join(rootDir, 'scripts/node/universal-version-manager.js');
   const vmContent = fs.readFileSync(vmPath, 'utf-8');
-  const versionMatch = vmContent.match(/version:\s*"([^"]+)"/);
-  
+  const usesPackageSsot =
+    vmContent.includes('readPackageVersion()') &&
+    /version:\s*PACKAGE_VERSION/.test(vmContent);
+
+  if (usesPackageSsot) {
+    log(`Version SSOT: package.json (${pkgVersion})`, 'success');
+    return true;
+  }
+
+  const versionMatch = vmContent.match(/framework:\s*\{[\s\S]*?version:\s*"([^"]+)"/);
   if (!versionMatch) {
-    errors.push('Cannot find version in version manager');
+    errors.push('Cannot find framework version in version manager');
     return false;
   }
-  
+
   const vmVersion = versionMatch[1];
-  
-  // Load package.json
-  const pkgPath = path.join(rootDir, 'package.json');
-  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-  const pkgVersion = pkg.version;
-  
   if (pkgVersion !== vmVersion) {
-    // package.json is often 1 ahead of UVM after npm version patch — non-blocking
     warnings.push(`Version mismatch: package.json (${pkgVersion}) != version manager (${vmVersion})`);
     log(`Version mismatch: package.json=${pkgVersion}, version-manager=${vmVersion}`, 'warn');
-    return true; // non-blocking — matches pre-commit hook behavior
+  } else {
+    log(`Versions aligned: ${pkgVersion}`, 'success');
   }
-  
-  log(`Versions aligned: ${pkgVersion}`, 'success');
   return true;
 }
 

package/scripts/node/setup.cjs

@@ -6,12 +6,8 @@ const path = require("path");
 const packageRoot = path.join(__dirname, "..", "..");
 const homeDir = require("os").homedir();
 
-let targetDir;
-if (__dirname.includes("node_modules/xray")) {
-  targetDir = path.join(__dirname, "..", "..", "..", "..");
-} else {
-  targetDir = process.env.PWD || process.cwd();
-}
+const { resolveConsumerTargetDir, isConsumerInstall } = require("./install-bridges.cjs");
+let targetDir = resolveConsumerTargetDir(packageRoot, process.env.PWD || process.cwd());
 
 const resolvedPackage = path.resolve(packageRoot);
 const resolvedTarget = path.resolve(targetDir);
@@ -159,8 +155,13 @@ if (fs.existsSync(distSource)) {
 }
 
 // 6. Convert MCP paths in consumer opencode.json
-const isConsumer = fs.existsSync(path.join(targetDir, "node_modules", "xray", "package.json"));
-if (!hasHermes && isConsumer) {
+const isConsumer = isConsumerInstall(packageRoot, targetDir);
+const consumerPkgName = isConsumer
+  ? ["0xray", "xray"].find((name) =>
+      fs.existsSync(path.join(targetDir, "node_modules", name, "package.json"))
+    )
+  : null;
+if (!hasHermes && isConsumer && consumerPkgName) {
   const mainOpencodePath = path.join(targetDir, "opencode.json");
   if (fs.existsSync(mainOpencodePath)) {
     try {
@@ -171,13 +172,13 @@ if (!hasHermes && isConsumer) {
           if (server.command && typeof server.command === "string") {
             const normalized = server.command.replace(
               /^[.]{0,2}\/dist\/mcps\//,
-              "node_modules/xray/dist/mcps/"
+              `node_modules/${consumerPkgName}/dist/mcps/`
             );
             if (normalized !== server.command) { server.command = normalized; modified = true; }
           }
           if (Array.isArray(server.command)) {
             server.command = server.command.map(a =>
-              a.replace(/^[.]{0,2}\/dist\/mcps\//, "node_modules/xray/dist/mcps/")
+              a.replace(/^[.]{0,2}\/dist\/mcps\//, `node_modules/${consumerPkgName}/dist/mcps/`)
             );
             modified = true;
           }

package/scripts/node/universal-version-manager.js

@@ -17,7 +17,6 @@
  * - Historical docs (docs/reflections, docs/archive)
  * - Test files with assertions
  *
- * @version 2.0.0
  * @since 2026-01-15
  * @updated 2026-03-09 - Enhanced with documentation management, validation, and backup
  */
@@ -28,6 +27,19 @@ const require = createRequire(import.meta.url);
 import fs from "fs";
 import path from "path";
 import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, "../..");
+
+function readPackageVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf-8"));
+    return pkg.version;
+  } catch {
+    return "0.0.0";
+  }
+}
 
 /**
  * Auto-calculate framework counts from filesystem
@@ -133,10 +145,12 @@ const CALCULATED_COUNTS = calculateCounts();
  * Framework version information - SINGLE SOURCE OF TRUTH
  * Version manager updates this, then propagates to all files
  */
+const PACKAGE_VERSION = readPackageVersion();
+
 const OFFICIAL_VERSIONS = {
-  // Framework version
+  // Framework version — SSOT: package.json
   framework: {
-    version: "3.1.1",
+    version: PACKAGE_VERSION,
       displayName: "xray: Self-Healing AI Governance OS",
       lastUpdated: "2026-06-17",
     // Counts (auto-calculated, but can be overridden)

package/src/mcps/index.ts

@@ -50,6 +50,7 @@ export const MCP_SERVERS: McpServerEntry[] = [
   { serverName: "refactoring-strategies", sourceFile: "mcps/knowledge-skills/refactoring-strategies.server.ts", type: "knowledge-skill", registered: true, description: "Refactoring strategies" },
   { serverName: "security-audit", sourceFile: "mcps/knowledge-skills/security-audit.server.ts", type: "knowledge-skill", registered: true, description: "Security auditing" },
   { serverName: "seo-consultant", sourceFile: "mcps/knowledge-skills/seo-consultant.server.ts", type: "knowledge-skill", registered: false, description: "SEO consulting" },
+  { serverName: "storyteller", sourceFile: "mcps/knowledge-skills/storyteller.server.ts", type: "knowledge-skill", registered: false, description: "Reflections, sagas, and technical narratives" },
   { serverName: "session-management", sourceFile: "mcps/knowledge-skills/session-management.server.ts", type: "knowledge-skill", registered: true, description: "Session management" },
   { serverName: "skill-invocation", sourceFile: "mcps/knowledge-skills/skill-invocation.server.ts", type: "knowledge-skill", registered: true, description: "Skill invocation" },
   { serverName: "strategist", sourceFile: "mcps/knowledge-skills/strategist.server.ts", type: "knowledge-skill", registered: false, description: "Strategic planning" },

package/src/mcps/knowledge-skills/skill-invocation.server.ts

@@ -186,7 +186,7 @@ class SkillInvocationServer extends XrayKnowledgeSkillBase {
       "strategist", "skill-invocation",
     ];
     const knowledgeSkills = [
-      "architecture-patterns", "strategist", "tech-writer",
+      "architecture-patterns", "strategist", "tech-writer", "storyteller",
       "seo-consultant", "content-creator", "growth-strategist",
       "bug-triage-specialist", "log-monitor",
       "mobile-development", "git-workflow", "session-management",
@@ -236,6 +236,7 @@ class SkillInvocationServer extends XrayKnowledgeSkillBase {
       "tech-writer": "documentation-generation",
       "frontend-ui-ux-engineer": "ui-ux-design",
       "frontend-engineer": "project-analysis",
+      "storyteller": "storyteller",
     };
 
     const resolvedSkill = skillAliases[skillName] || skillName;
@@ -253,7 +254,7 @@ class SkillInvocationServer extends XrayKnowledgeSkillBase {
       "git-workflow", "content-creator", "ui-ux-design",
       "multimodal-looker", "refactoring-strategies",
       "project-analysis", "testing-best-practices",
-      "architecture-patterns",
+      "architecture-patterns", "storyteller",
     ];
 
     if (!availableServers.includes(resolvedSkill)) {

package/src/mcps/knowledge-skills/storyteller.server.ts

@@ -0,0 +1,206 @@
+/**
+ * Storyteller MCP Server
+ *
+ * Returns storyteller SKILL.md guidance plus a session-aware writing prompt.
+ * The host LLM writes the story; this server supplies the contract.
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { XrayKnowledgeSkillBase } from '../shared/knowledge-skill-base.js';
+
+const STORY_TYPES = ['reflection', 'saga', 'journey', 'narrative'] as const;
+type StoryType = (typeof STORY_TYPES)[number];
+
+interface WriteStoryArgs {
+  title?: string;
+  context?: Record<string, unknown>;
+  framework?: string;
+  output?: string;
+}
+
+function resolveSkillMd(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join(here, '../../../skills/storyteller/SKILL.md'),
+    join(here, '../../skills/storyteller/SKILL.md'),
+    join(process.cwd(), 'node_modules/0xray/dist/skills/storyteller/SKILL.md'),
+    join(process.cwd(), 'node_modules/xray/dist/skills/storyteller/SKILL.md'),
+  ];
+
+  for (const path of candidates) {
+    if (existsSync(path)) {
+      return readFileSync(path, 'utf-8');
+    }
+  }
+
+  return '# Storyteller\n\nWrite warmly candid technical reflections with scene-first openings.';
+}
+
+function getStoryMeta(storyType: StoryType) {
+  const defaults: Record<
+    StoryType,
+    { location: string; min_words: number; ideal_words: number; framework: string }
+  > = {
+    reflection: {
+      location: 'docs/reflections/',
+      min_words: 2000,
+      ideal_words: 5000,
+      framework: 'three_act_structure',
+    },
+    saga: {
+      location: 'docs/reflections/deep/',
+      min_words: 5000,
+      ideal_words: 15000,
+      framework: 'hero_journey',
+    },
+    journey: {
+      location: 'docs/reflections/deep/',
+      min_words: 1500,
+      ideal_words: 4000,
+      framework: 'three_act_structure',
+    },
+    narrative: {
+      location: 'docs/reflections/',
+      min_words: 1000,
+      ideal_words: 3000,
+      framework: 'three_act_structure',
+    },
+  };
+  return defaults[storyType];
+}
+
+function gitContext(): string {
+  try {
+    const commits = execSync('git log --oneline -20 2>/dev/null', { encoding: 'utf-8' });
+    const files = execSync(
+      'git diff --name-only HEAD~10 2>/dev/null || git ls-files 2>/dev/null | head -50',
+      { encoding: 'utf-8' },
+    );
+    return `Recent commits:\n${commits}\n\nRecent files:\n${files}`;
+  } catch {
+    return 'No git context available in this workspace.';
+  }
+}
+
+function buildPrompt(
+  storyType: StoryType,
+  title: string,
+  meta: ReturnType<typeof getStoryMeta>,
+  extraContext?: Record<string, unknown>,
+): string {
+  const contextBlock = extraContext
+    ? `\n## Provided context\n${JSON.stringify(extraContext, null, 2)}\n`
+    : '';
+
+  return `Write a ${storyType} titled "${title}".
+
+## Requirements
+- Framework: ${meta.framework}
+- Target length: ${meta.ideal_words} words (minimum: ${meta.min_words})
+- Save to: ${meta.location}
+- Follow storyteller SKILL.md voice (warmly candid, scene-first, no executive summary)
+- Include Key Takeaways and What Next sections
+
+## Session / repo context
+${gitContext()}
+${contextBlock}
+
+Write the complete ${storyType} now.`;
+}
+
+function writeStoryTool(storyType: StoryType, args: WriteStoryArgs) {
+  const meta = getStoryMeta(storyType);
+  if (args.framework) meta.framework = args.framework;
+
+  const title =
+    args.title ??
+    `${storyType.charAt(0).toUpperCase() + storyType.slice(1)} - ${new Date().toISOString().split('T')[0]}`;
+  const skillMd = resolveSkillMd();
+  const prompt = buildPrompt(storyType, title, meta, args.context);
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+  const filename = `${storyType}-${slug}-${new Date().toISOString().split('T')[0]}.md`;
+  const outputPath = args.output ?? join(meta.location, filename);
+
+  const outputDir = join(process.cwd(), dirname(outputPath));
+  if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
+
+  const fullPath = join(process.cwd(), outputPath);
+  const frontmatter = `---
+story_type: ${storyType}
+title: "${title}"
+framework: ${meta.framework}
+target_words: ${meta.ideal_words}
+---
+
+`;
+
+  writeFileSync(fullPath, `${frontmatter}\n${prompt}\n`, 'utf-8');
+
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: [
+          `Storyteller ${storyType} brief prepared.`,
+          `Output template: ${outputPath}`,
+          '',
+          '--- SKILL (excerpt) ---',
+          skillMd.slice(0, 4000),
+          skillMd.length > 4000 ? '\n...(truncated; full SKILL.md on disk)' : '',
+          '',
+          '--- WRITING PROMPT ---',
+          prompt,
+          '',
+          'Host LLM: write the full story into the output path using the prompt above.',
+        ].join('\n'),
+      },
+    ],
+  };
+}
+
+class StorytellerServer extends XrayKnowledgeSkillBase {
+  constructor() {
+    super('storyteller', '1.0.0');
+
+    const writeSchema = {
+      type: 'object' as const,
+      properties: {
+        title: { type: 'string', description: 'Story title' },
+        context: { type: 'object', description: 'Session context (commits, changes, notes)' },
+        framework: { type: 'string', description: 'Storytelling framework override' },
+        output: { type: 'string', description: 'Relative output path' },
+      },
+    };
+
+    this.tools = STORY_TYPES.map((storyType) => ({
+      name: `write_${storyType}`,
+      description: `Prepare ${storyType} story brief using storyteller SKILL.md`,
+      inputSchema: writeSchema,
+    }));
+
+    this.handlers = {
+      write_reflection: async (args) => writeStoryTool('reflection', args as WriteStoryArgs),
+      write_saga: async (args) => writeStoryTool('saga', args as WriteStoryArgs),
+      write_journey: async (args) => writeStoryTool('journey', args as WriteStoryArgs),
+      write_narrative: async (args) => writeStoryTool('narrative', args as WriteStoryArgs),
+    };
+
+    this.setupToolHandlers();
+  }
+}
+
+if (import.meta.url === `file://${fileURLToPath(import.meta.url)}`) {
+  const server = new StorytellerServer();
+  server.run().catch((error) => {
+    process.stderr.write(`FATAL: ${String(error)}\n`);
+    process.exit(1);
+  });
+}
+
+export { StorytellerServer };

package/src/mcps/orchestrator/execution/execution-planner.ts

@@ -213,15 +213,18 @@ export class ExecutionPlanner {
     agentAssignments: Map<string, OrchestrationTask[]>
   ): void {
     for (const task of tasks) {
-      const complexity = task.estimatedComplexity || 30;
+      const complexity = this.calculateTaskComplexity(task);
       const requiredCaps = [
         task.type,
         ...(task.metadata?.memorySignals ?? []),
       ];
+      const operationDescription = task.metadata?.memoryHighConfidenceTrap
+        ? `${task.description} TYPE: ontological-trap`
+        : task.description;
       const agent = this.capabilitiesManager.selectAgentForTask(
         requiredCaps,
         complexity,
-        task.description,
+        operationDescription,
       ) || 'orchestrator';
 
       if (!agentAssignments.has(agent)) {
@@ -346,6 +349,15 @@ export class ExecutionPlanner {
       complexity += task.dependencies.length * 5;
     }
 
+    if (task.metadata?.memoryComplexityBoost !== undefined) {
+      complexity += task.metadata.memoryComplexityBoost;
+    } else {
+      const provider = getProvider();
+      if (provider.id !== 'null' && provider.getTaskConfidence) {
+        complexity += provider.getTaskConfidence(toMemoryTask(task)).complexityBoost;
+      }
+    }
+
     return Math.min(Math.max(Math.round(complexity), 1), 100);
   }
 

package/src/mcps/orchestrator/types.ts

@@ -19,6 +19,10 @@ export interface OrchestrationTaskMetadata {
   synthesisContext?: string;
   ontologicalTrapDetected?: boolean;
   memoryProviderId?: string;
+  memorySignalConfidences?: Record<string, number>;
+  memoryAvgConfidence?: number;
+  memoryHighConfidenceTrap?: boolean;
+  memoryComplexityBoost?: number;
 }
 
 export interface OrchestrationTask {

package/src/mcps/registry.json

@@ -1,5 +1,4 @@
 {
-  "version": "3.1.0",
   "description": "0xRay Community MCPs Registry - curated API-focused MCP servers",
   "sources": [
     {