0xray 3.5.1 → 3.5.2

package/dist/nucleus/synthesis-completion.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Post-checkpoint side effects — meta-inference refresh + repertoire feedback.
+ */
+import type { PersistedLeadDevPlan } from './lead-dev-plan-persistence.js';
+import type { SynthesisCheckpointState } from './synthesis.js';
+export declare function runSynthesisCheckpointSideEffects(projectRoot: string, sessionId: string, plan: PersistedLeadDevPlan | null, completedState: SynthesisCheckpointState): Promise<void>;

package/dist/nucleus/synthesis-completion.js

@@ -0,0 +1,29 @@
+/**
+ * Post-checkpoint side effects — meta-inference refresh + repertoire feedback.
+ */
+import { getMemoryRoutingProvider } from '../memory-routing/index.js';
+import { getSynthesisConsultTodos, isSynthesisRealignmentPlan } from './lead-dev-plan-persistence.js';
+export async function runSynthesisCheckpointSideEffects(projectRoot, sessionId, plan, completedState) {
+    try {
+        const provider = await getMemoryRoutingProvider();
+        if (provider.refreshMetaInference) {
+            await provider.refreshMetaInference().catch(() => undefined);
+        }
+        if (provider.ingestFeedback && plan && isSynthesisRealignmentPlan(plan)) {
+            const consultTodos = getSynthesisConsultTodos(plan);
+            provider.ingestFeedback({
+                timestamp: new Date().toISOString(),
+                sessionId,
+                taskId: `synthesis-checkpoint-${completedState.synthesisCount}`,
+                assignedAgent: 'orchestrator',
+                memorySignals: ['synthesis', ...consultTodos.map((t) => t.subagent)],
+                complexity: 30,
+                success: true,
+                durationMs: 0,
+            });
+        }
+    }
+    catch {
+        // non-blocking — checkpoint already cleared
+    }
+}

package/dist/nucleus/synthesis-context.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Collocated context for synthesis Aside — delegates to memory routing provider SSOT.
+ */
+export interface SynthesisCollocatedContext {
+    primitive: 'synthesis';
+    dueReason: string | null;
+    collatedText: string;
+    matchedSignals?: Array<{
+        name: string;
+        definition: string;
+        priority: string;
+    }>;
+    codexTermCount?: number;
+    codexExcerpt?: string;
+    planExcerpt?: string;
+    synthesisExcerpt?: string;
+}
+export declare function buildSynthesisCollocatedContext(projectRoot?: string, dueReason?: string | null): Promise<SynthesisCollocatedContext>;
+/** Refresh meta-inference before collation so synthesis.md is current for reflect. */
+export declare function prepareSynthesisCollocatedContext(projectRoot?: string, dueReason?: string | null): Promise<SynthesisCollocatedContext>;
+export declare function isAnalyzeComplexitySuccess(content: Array<{
+    type: string;
+    text: string;
+}>): boolean;
+export declare function appendSynthesisContextToResponse(content: Array<{
+    type: string;
+    text: string;
+}>, collatedText: string): Array<{
+    type: string;
+    text: string;
+}>;

package/dist/nucleus/synthesis-context.js

@@ -0,0 +1,86 @@
+/**
+ * Collocated context for synthesis Aside — delegates to memory routing provider SSOT.
+ */
+import { getMemoryRoutingProvider } from '../memory-routing/index.js';
+function fallbackContext(dueReason) {
+    const lines = [
+        '# Synthesis checkpoint',
+        dueReason ? `Due: ${dueReason}` : '',
+        '(Enable memory_routing with Repertoire for full signal + codex + plan collation)',
+    ].filter(Boolean);
+    return {
+        primitive: 'synthesis',
+        dueReason,
+        collatedText: lines.join('\n\n'),
+    };
+}
+function normalizeProviderContext(raw, dueReason) {
+    const collatedText = typeof raw.collatedText === 'string' && raw.collatedText.trim()
+        ? dueReason && !raw.collatedText.includes('Due:')
+            ? `# Synthesis checkpoint\n\nDue: ${dueReason}\n\n${raw.collatedText}`
+            : raw.collatedText
+        : fallbackContext(dueReason).collatedText;
+    const matchedSignals = Array.isArray(raw.matchedSignals)
+        ? raw.matchedSignals
+        : undefined;
+    return {
+        primitive: 'synthesis',
+        dueReason,
+        collatedText,
+        ...(matchedSignals ? { matchedSignals } : {}),
+        ...(typeof raw.codexTermCount === 'number' ? { codexTermCount: raw.codexTermCount } : {}),
+        ...(typeof raw.codexExcerpt === 'string' ? { codexExcerpt: raw.codexExcerpt } : {}),
+        ...(typeof raw.planExcerpt === 'string' ? { planExcerpt: raw.planExcerpt } : {}),
+        ...(typeof raw.synthesisExcerpt === 'string'
+            ? { synthesisExcerpt: raw.synthesisExcerpt }
+            : {}),
+    };
+}
+export async function buildSynthesisCollocatedContext(projectRoot = process.cwd(), dueReason = null) {
+    try {
+        const provider = await getMemoryRoutingProvider();
+        if (provider.isAvailable() && provider.buildSynthesisContext) {
+            const raw = provider.buildSynthesisContext({ projectRoot, dueReason });
+            if (raw)
+                return normalizeProviderContext(raw, dueReason);
+        }
+    }
+    catch {
+        // fall through to minimal fallback
+    }
+    return fallbackContext(dueReason);
+}
+/** Refresh meta-inference before collation so synthesis.md is current for reflect. */
+export async function prepareSynthesisCollocatedContext(projectRoot = process.cwd(), dueReason = null) {
+    try {
+        const provider = await getMemoryRoutingProvider();
+        if (provider.refreshMetaInference) {
+            await provider.refreshMetaInference().catch(() => undefined);
+        }
+    }
+    catch {
+        // non-blocking — collation still proceeds
+    }
+    return buildSynthesisCollocatedContext(projectRoot, dueReason);
+}
+export function isAnalyzeComplexitySuccess(content) {
+    const text = content.map((c) => c.text).join('\n');
+    return !text.includes('❌') && !/^error handling tool/i.test(text);
+}
+export function appendSynthesisContextToResponse(content, collatedText) {
+    if (!collatedText.trim())
+        return content;
+    const synthesisSection = `
+
+---
+
+## Synthesis checkpoint — collocated context
+
+${collatedText}
+
+**Next:** Spawn Task for each mandatory consult todo (s.1 researcher, s.2 architect-tools, s.3 code-review). Checkpoint clears only when all consult todos complete.`;
+    if (content.length === 0) {
+        return [{ type: 'text', text: synthesisSection.trim() }];
+    }
+    return content.map((block, index) => index === 0 ? { ...block, text: `${block.text}${synthesisSection}` } : block);
+}

package/dist/nucleus/synthesis.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Synthesis — periodic reflect & realign checkpoint SSOT.
+ * Slice counter + feature flag + `.xray/state/synthesis-checkpoint.json`.
+ * PR2 wires pre-tool gate deny via delegation-gate.ts.
+ */
+export declare const SYNTHESIS_PRIMITIVE = "synthesis";
+export type ExecutionSliceKind = 'gate' | 'turn' | 'todo_completed';
+export interface SynthesisConfig {
+    enabled: boolean;
+    every_n_gates: number;
+    every_n_turns: number;
+    every_n_todos_completed: number;
+}
+export interface SynthesisSliceCounters {
+    gates: number;
+    turns: number;
+    todosCompleted: number;
+}
+export interface SynthesisCheckpointState {
+    version: 1;
+    sessionId: string;
+    slicesSinceLastSynthesis: SynthesisSliceCounters;
+    lifetimeSlices: SynthesisSliceCounters;
+    synthesisDue: boolean;
+    dueReason: string | null;
+    lastSynthesisAt: string | null;
+    lastSliceAt: string;
+    synthesisCount: number;
+}
+export interface RecordSliceResult {
+    state: SynthesisCheckpointState;
+    becameDue: boolean;
+    dueReason: string | null;
+}
+export interface SynthesisDueEvaluation {
+    due: boolean;
+    reason: string | null;
+}
+export declare function synthesisCheckpointPath(projectRoot?: string): string;
+export declare function defaultSynthesisConfig(): SynthesisConfig;
+export declare function loadSynthesisConfig(projectRoot?: string): SynthesisConfig;
+export declare function createInitialSynthesisState(sessionId: string): SynthesisCheckpointState;
+export declare function loadSynthesisCheckpointState(projectRoot?: string): SynthesisCheckpointState | null;
+export declare function saveSynthesisCheckpointState(state: SynthesisCheckpointState, projectRoot?: string): string;
+export declare function evaluateSynthesisDue(counters: SynthesisSliceCounters, config: SynthesisConfig): SynthesisDueEvaluation;
+export declare function recordExecutionSlice(kind: ExecutionSliceKind, ctx: {
+    projectRoot?: string;
+    sessionId: string | null;
+}): RecordSliceResult | null;
+export declare function completeSynthesisCheckpoint(projectRoot?: string, sessionId?: string | null): SynthesisCheckpointState | null;
+export declare function isSynthesisCheckpointDue(projectRoot?: string, sessionId?: string | null): boolean;
+export declare function getSynthesisDueReason(projectRoot?: string, sessionId?: string | null): string | null;
+/** Session bound to an active synthesis checkpoint (for MCP when host omits sessionId). */
+export declare function getSynthesisCheckpointSessionId(projectRoot?: string): string | null;

package/dist/nucleus/synthesis.js

@@ -0,0 +1,196 @@
+/**
+ * Synthesis — periodic reflect & realign checkpoint SSOT.
+ * Slice counter + feature flag + `.xray/state/synthesis-checkpoint.json`.
+ * PR2 wires pre-tool gate deny via delegation-gate.ts.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export const SYNTHESIS_PRIMITIVE = 'synthesis';
+const STATE_VERSION = 1;
+export function synthesisCheckpointPath(projectRoot = process.cwd()) {
+    return path.join(projectRoot, '.xray', 'state', 'synthesis-checkpoint.json');
+}
+export function defaultSynthesisConfig() {
+    return {
+        enabled: false,
+        every_n_gates: 12,
+        every_n_turns: 0,
+        every_n_todos_completed: 0,
+    };
+}
+export function loadSynthesisConfig(projectRoot = process.cwd()) {
+    const featuresPath = path.join(projectRoot, '.xray', 'features.json');
+    if (!fs.existsSync(featuresPath)) {
+        return defaultSynthesisConfig();
+    }
+    try {
+        const data = JSON.parse(fs.readFileSync(featuresPath, 'utf8'));
+        const raw = data.synthesis ?? {};
+        const defaults = defaultSynthesisConfig();
+        return {
+            enabled: raw.enabled === true,
+            every_n_gates: normalizeThreshold(raw.every_n_gates, defaults.every_n_gates),
+            every_n_turns: normalizeThreshold(raw.every_n_turns, defaults.every_n_turns),
+            every_n_todos_completed: normalizeThreshold(raw.every_n_todos_completed, defaults.every_n_todos_completed),
+        };
+    }
+    catch {
+        return defaultSynthesisConfig();
+    }
+}
+function normalizeThreshold(value, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        return fallback;
+    }
+    return Math.floor(value);
+}
+function emptyCounters() {
+    return { gates: 0, turns: 0, todosCompleted: 0 };
+}
+export function createInitialSynthesisState(sessionId) {
+    const now = new Date().toISOString();
+    return {
+        version: STATE_VERSION,
+        sessionId,
+        slicesSinceLastSynthesis: emptyCounters(),
+        lifetimeSlices: emptyCounters(),
+        synthesisDue: false,
+        dueReason: null,
+        lastSynthesisAt: null,
+        lastSliceAt: now,
+        synthesisCount: 0,
+    };
+}
+export function loadSynthesisCheckpointState(projectRoot = process.cwd()) {
+    const statePath = synthesisCheckpointPath(projectRoot);
+    if (!fs.existsSync(statePath))
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+        if (parsed.version !== STATE_VERSION)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveSynthesisCheckpointState(state, projectRoot = process.cwd()) {
+    const statePath = synthesisCheckpointPath(projectRoot);
+    fs.mkdirSync(path.dirname(statePath), { recursive: true });
+    fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+    return statePath;
+}
+export function evaluateSynthesisDue(counters, config) {
+    if (!config.enabled) {
+        return { due: false, reason: null };
+    }
+    if (config.every_n_gates > 0 && counters.gates >= config.every_n_gates) {
+        return {
+            due: true,
+            reason: `gate threshold (${counters.gates}/${config.every_n_gates})`,
+        };
+    }
+    if (config.every_n_turns > 0 && counters.turns >= config.every_n_turns) {
+        return {
+            due: true,
+            reason: `turn threshold (${counters.turns}/${config.every_n_turns})`,
+        };
+    }
+    if (config.every_n_todos_completed > 0 &&
+        counters.todosCompleted >= config.every_n_todos_completed) {
+        return {
+            due: true,
+            reason: `todo threshold (${counters.todosCompleted}/${config.every_n_todos_completed})`,
+        };
+    }
+    return { due: false, reason: null };
+}
+function incrementCounter(counters, kind) {
+    const next = { ...counters };
+    if (kind === 'gate')
+        next.gates += 1;
+    else if (kind === 'turn')
+        next.turns += 1;
+    else
+        next.todosCompleted += 1;
+    return next;
+}
+export function recordExecutionSlice(kind, ctx) {
+    if (!ctx.sessionId)
+        return null;
+    const projectRoot = ctx.projectRoot ?? process.cwd();
+    const config = loadSynthesisConfig(projectRoot);
+    if (!config.enabled)
+        return null;
+    const existing = loadSynthesisCheckpointState(projectRoot);
+    const base = existing && existing.sessionId === ctx.sessionId
+        ? existing
+        : createInitialSynthesisState(ctx.sessionId);
+    if (base.synthesisDue && kind !== 'todo_completed')
+        return null;
+    const now = new Date().toISOString();
+    const slicesSinceLastSynthesis = incrementCounter(base.slicesSinceLastSynthesis, kind);
+    const lifetimeSlices = incrementCounter(base.lifetimeSlices, kind);
+    let synthesisDue = base.synthesisDue;
+    let dueReason = base.dueReason;
+    let becameDue = false;
+    if (!synthesisDue) {
+        const evaluation = evaluateSynthesisDue(slicesSinceLastSynthesis, config);
+        if (evaluation.due) {
+            synthesisDue = true;
+            dueReason = evaluation.reason;
+            becameDue = true;
+        }
+    }
+    const state = {
+        ...base,
+        slicesSinceLastSynthesis,
+        lifetimeSlices,
+        synthesisDue,
+        dueReason,
+        lastSliceAt: now,
+    };
+    saveSynthesisCheckpointState(state, projectRoot);
+    return { state, becameDue, dueReason };
+}
+export function completeSynthesisCheckpoint(projectRoot = process.cwd(), sessionId) {
+    const state = loadSynthesisCheckpointState(projectRoot);
+    if (!state)
+        return null;
+    if (sessionId && state.sessionId !== sessionId)
+        return null;
+    const completed = {
+        ...state,
+        slicesSinceLastSynthesis: emptyCounters(),
+        synthesisDue: false,
+        dueReason: null,
+        lastSynthesisAt: new Date().toISOString(),
+        synthesisCount: state.synthesisCount + 1,
+    };
+    saveSynthesisCheckpointState(completed, projectRoot);
+    return completed;
+}
+export function isSynthesisCheckpointDue(projectRoot = process.cwd(), sessionId) {
+    const state = loadSynthesisCheckpointState(projectRoot);
+    if (!state?.synthesisDue)
+        return false;
+    if (sessionId && state.sessionId !== sessionId)
+        return false;
+    return loadSynthesisConfig(projectRoot).enabled;
+}
+export function getSynthesisDueReason(projectRoot = process.cwd(), sessionId) {
+    const state = loadSynthesisCheckpointState(projectRoot);
+    if (!state?.synthesisDue)
+        return null;
+    if (sessionId && state.sessionId !== sessionId)
+        return null;
+    return state.dueReason;
+}
+/** Session bound to an active synthesis checkpoint (for MCP when host omits sessionId). */
+export function getSynthesisCheckpointSessionId(projectRoot = process.cwd()) {
+    const state = loadSynthesisCheckpointState(projectRoot);
+    if (!state?.synthesisDue)
+        return null;
+    return state.sessionId;
+}

package/dist/plugin/xray-codex-injection.js

@@ -281,6 +281,23 @@ export default async function xrayCodexPlugin(input) {
             if (!textContent) {
                 return;
             }
+            try {
+                const { recordExecutionSlice } = await import("../nucleus/synthesis.js");
+                let sessionId = process.env.GROK_SESSION_ID ?? null;
+                try {
+                    const boot = JSON.parse(readFileSync(join(directory, ".xray", "state", "session-boot.json"), "utf8"));
+                    sessionId = boot.sessionId ?? sessionId;
+                }
+                catch {
+                    /* no session boot */
+                }
+                if (sessionId) {
+                    recordExecutionSlice("turn", { projectRoot: directory, sessionId });
+                }
+            }
+            catch {
+                /* synthesis turn slice optional */
+            }
             const agentMentionRegex = /@([\w-]+)(?:\s+(.+?))?(?=$|\n\n|\r\r)/g;
             let match;
             let hasAgentMention = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "0xray",
-  "version": "3.5.1",
+  "version": "3.5.2",
   "description": "Multi-agent orchestration and Codex governance for OpenCode, Hermes, Grok Build, and OpenClaw",
   "readme": "README.md",
   "license": "MIT",
@@ -127,9 +127,13 @@
     "publish": "npm run release:gate && npm run safe-publish && npm publish --access public",
     "release:patch": "node scripts/node/release.mjs patch",
     "verify:orchestrator-behavior": "npm run build && node scripts/mjs/verify-orchestrator-behavior.mjs",
-    "verify:grok-delegation-gate": "npm run build && node scripts/mjs/verify-grok-delegation-gate.mjs",
+    "verify:grok-delegation-gate": "npm run build && node scripts/mjs/verify-grok-delegation-gate.mjs && node scripts/mjs/verify-grok-synthesis-gate.mjs",
+    "verify:grok-synthesis-gate": "npm run build && node scripts/mjs/verify-grok-synthesis-gate.mjs",
     "verify:hermes-delegation-gate": "npm run build && node scripts/mjs/verify-hermes-delegation-gate.mjs",
-    "verify:delegation-gate": "npm run build && node scripts/mjs/verify-delegation-gate-core.mjs --host=grok && node scripts/mjs/verify-delegation-gate-core.mjs --host=hermes && node scripts/mjs/verify-delegation-gate-core.mjs --host=opencode && node scripts/mjs/verify-grok-delegation-gate.mjs && node scripts/mjs/verify-hermes-delegation-gate.mjs"
+    "verify:delegation-gate": "npm run build && node scripts/mjs/verify-delegation-gate-core.mjs --host=grok && node scripts/mjs/verify-delegation-gate-core.mjs --host=hermes && node scripts/mjs/verify-delegation-gate-core.mjs --host=opencode && node scripts/mjs/verify-grok-delegation-gate.mjs && node scripts/mjs/verify-grok-synthesis-gate.mjs && node scripts/mjs/verify-hermes-delegation-gate.mjs",
+    "verify:synthesis": "npm run build && node scripts/mjs/verify-synthesis-core.mjs && node scripts/mjs/verify-synthesis-gate-core.mjs && node scripts/mjs/verify-synthesis-outcome-core.mjs && node scripts/mjs/verify-synthesis-p2-core.mjs && node scripts/mjs/verify-synthesis-e2e-core.mjs",
+    "verify:find-project-root": "node scripts/mjs/verify-find-project-root-core.mjs",
+    "verify:consumer-gitignore": "node scripts/mjs/verify-consumer-gitignore-core.mjs"
   },
   "files": [
     "dist/",

package/scripts/helpers/find-project-root.mjs

@@ -0,0 +1,92 @@
+/**
+ * Consumer project root SSOT for bridge hooks and installers.
+ * Prefers git root when 0xray is a dependency or devDependency.
+ */
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { execSync } from 'node:child_process';
+import { homedir } from 'node:os';
+
+export function hasXrayDependency(pkg) {
+  if (!pkg || typeof pkg !== 'object') return false;
+  return (
+    pkg.name === '0xray' ||
+    Boolean(pkg.dependencies?.['0xray']) ||
+    Boolean(pkg.devDependencies?.['0xray'])
+  );
+}
+
+export function isConsumerWorkspace(dir) {
+  return (
+    existsSync(join(dir, '.xray', 'features.json')) ||
+    existsSync(join(dir, 'node_modules', '0xray', 'package.json'))
+  );
+}
+
+function normalizePath(dir) {
+  try {
+    return realpathSync(dir);
+  } catch {
+    return dir;
+  }
+}
+
+function readPkg(dir) {
+  try {
+    const pkgPath = join(dir, 'package.json');
+    if (!existsSync(pkgPath)) return null;
+    return JSON.parse(readFileSync(pkgPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function findGitRoot(cwd = process.cwd()) {
+  try {
+    const gitRoot = execSync('git rev-parse --show-toplevel 2>/dev/null', {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return gitRoot ? normalizePath(gitRoot) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function findProjectRoot(extraCandidates = []) {
+  const envHome = process.env.XRAY_HOME || process.env.XRAY_ROOT;
+  if (envHome) {
+    const resolved = normalizePath(resolve(envHome));
+    const pkg = readPkg(resolved);
+    if (pkg && (isConsumerWorkspace(resolved) || hasXrayDependency(pkg))) {
+      return resolved;
+    }
+  }
+
+  const gitRoot = findGitRoot();
+  if (gitRoot) {
+    const pkg = readPkg(gitRoot);
+    if (pkg && hasXrayDependency(pkg) && pkg.name !== '0xray') {
+      return gitRoot;
+    }
+  }
+
+  let dir = process.cwd();
+  for (let i = 0; i < 12; i++) {
+    if (isConsumerWorkspace(dir)) return dir;
+    const pkg = readPkg(dir);
+    if (pkg && hasXrayDependency(pkg) && pkg.name !== '0xray') return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  const candidates = [process.cwd(), join(homedir(), 'dev', 'xray'), ...extraCandidates];
+  for (const candidate of candidates) {
+    const pkg = readPkg(candidate);
+    if (pkg && pkg.name === '0xray') return candidate;
+  }
+
+  return normalizePath(gitRoot || process.cwd());
+}