0xray 3.4.10 → 3.5.0

package/dist/nucleus/pending-delegations.js

@@ -0,0 +1,285 @@
+/**
+ * Pending delegations SSOT — written by task-handler on delegate-deferred.
+ * Grok hooks read the same file; PostToolUse never re-parses MCP output.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { featuresConfigLoader } from '../core/features-config.js';
+import { updatePlanTodoStatus } from './lead-dev-plan-persistence.js';
+export const DEFAULT_PENDING_TTL_MS = 4 * 60 * 60 * 1000;
+const AGENT_ALIASES = {
+    'bug-triage-specialist': 'bug-triage',
+    'code-reviewer': 'code-review',
+    'security-auditor': 'security-audit',
+};
+const TASK_TYPE_BY_AGENT = {
+    'backend-engineer': 'backend-engineer',
+    'frontend-engineer': 'frontend-engineer',
+    'bug-triage': 'bug-triage',
+    'bug-triage-specialist': 'bug-triage',
+    strategist: 'strategist',
+    researcher: 'generalPurpose',
+    'architect-tools': 'generalPurpose',
+    'code-review': 'code-review',
+    'code-reviewer': 'code-review',
+};
+export function pendingDelegationsPath(projectRoot = process.cwd()) {
+    return path.join(projectRoot, '.xray', 'state', 'pending-delegations.json');
+}
+export function leadDevPlanPath(projectRoot = process.cwd()) {
+    return path.join(projectRoot, '.xray', 'state', 'lead-dev-plan.json');
+}
+export function isAutoChainDelegationsEnabled(projectRoot = process.cwd()) {
+    try {
+        const localPath = path.join(projectRoot, '.xray', 'features.json');
+        if (fs.existsSync(localPath)) {
+            const data = JSON.parse(fs.readFileSync(localPath, 'utf8'));
+            const cfg = data.multi_agent_orchestration ?? {};
+            if (cfg.enabled === false || cfg.lead_dev_mode === false)
+                return false;
+            return cfg.auto_chain_delegations !== false;
+        }
+        const cfg = featuresConfigLoader.loadConfig().multi_agent_orchestration;
+        if (!cfg.enabled || cfg.lead_dev_mode === false)
+            return false;
+        return cfg.auto_chain_delegations !== false;
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeAgent(agent) {
+    const key = agent.toLowerCase().trim();
+    return AGENT_ALIASES[key] ?? key;
+}
+function loadLeadDevPlan(projectRoot) {
+    const planPath = leadDevPlanPath(projectRoot);
+    if (!fs.existsSync(planPath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(planPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function allPlanTodos(plan) {
+    return plan.phases.flatMap((p) => p.todos);
+}
+export function matchPlanTodo(agent, taskDescription, taskId, plan) {
+    if (!plan) {
+        return { todo: null, method: 'none', confidence: 0 };
+    }
+    const normalizedAgent = normalizeAgent(agent);
+    const pendingTodos = allPlanTodos(plan).filter((t) => t.status === 'pending');
+    const byTaskId = pendingTodos.find((t) => t.id === taskId || t.task.includes(taskId));
+    if (byTaskId) {
+        return { todo: byTaskId, method: 'taskId', confidence: 0.95 };
+    }
+    const desc = taskDescription.toLowerCase().trim();
+    if (desc) {
+        const byDesc = pendingTodos.find((t) => {
+            const todoText = t.task.toLowerCase();
+            return todoText.includes(desc) || desc.includes(todoText.slice(0, 40));
+        });
+        if (byDesc) {
+            return { todo: byDesc, method: 'description', confidence: 0.75 };
+        }
+    }
+    const byAgent = pendingTodos.find((t) => normalizeAgent(t.subagent) === normalizedAgent);
+    if (byAgent) {
+        return { todo: byAgent, method: 'agent-only', confidence: 0.5 };
+    }
+    return { todo: null, method: 'none', confidence: 0 };
+}
+export function mapSubagentToTaskType(agent) {
+    const key = agent.toLowerCase().trim();
+    return TASK_TYPE_BY_AGENT[key] ?? TASK_TYPE_BY_AGENT[normalizeAgent(key)] ?? 'generalPurpose';
+}
+export function buildSpawnHint(delegation) {
+    const todoLine = delegation.planTodoTask
+        ? `[plan todo ${delegation.planTodoId}] ${delegation.planTodoTask}`
+        : delegation.taskDescription;
+    return {
+        tool: 'Task',
+        subagent_type: mapSubagentToTaskType(delegation.agent),
+        description: `Lead-dev implementation delegation. ${todoLine}. ` +
+            `Complete this todo per .xray/state/lead-dev-plan.json; run per-suite tests; report results.`,
+        planTodoId: delegation.planTodoId,
+        delegationId: delegation.id,
+    };
+}
+export function loadPendingDelegationsState(projectRoot = process.cwd()) {
+    const filePath = pendingDelegationsPath(projectRoot);
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function savePendingDelegationsState(state, projectRoot = process.cwd()) {
+    const filePath = pendingDelegationsPath(projectRoot);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(state, null, 2));
+    return filePath;
+}
+function newDelegationId() {
+    return `del-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+export function recordDeferredDelegations(sessionId, deferrals, projectRoot = process.cwd()) {
+    if (!isAutoChainDelegationsEnabled(projectRoot) || deferrals.length === 0) {
+        return [];
+    }
+    const plan = loadLeadDevPlan(projectRoot);
+    const existing = loadPendingDelegationsState(projectRoot);
+    const now = new Date().toISOString();
+    const base = existing && existing.sessionId === sessionId
+        ? existing
+        : {
+            sessionId,
+            createdAt: now,
+            ttlMs: DEFAULT_PENDING_TTL_MS,
+            delegations: [],
+        };
+    const created = [];
+    for (const d of deferrals) {
+        const { todo, method, confidence } = matchPlanTodo(d.agent, d.description, d.taskId, plan);
+        const partial = {
+            id: newDelegationId(),
+            taskId: d.taskId,
+            agent: d.agent,
+            taskDescription: d.description,
+            taskType: d.type ?? 'implement',
+            sessionId,
+            planTodoId: todo?.id ?? null,
+            planTodoTask: todo?.task ?? null,
+            matchMethod: method,
+            matchConfidence: confidence,
+            status: 'pending',
+            createdAt: now,
+            satisfiedAt: null,
+        };
+        created.push({
+            ...partial,
+            spawnHint: buildSpawnHint(partial),
+        });
+    }
+    base.delegations = [
+        ...base.delegations.filter((d) => d.status === 'pending'),
+        ...created,
+    ];
+    if (base.sessionId !== sessionId) {
+        base.sessionId = sessionId;
+        base.createdAt = now;
+        base.delegations = created;
+    }
+    savePendingDelegationsState(base, projectRoot);
+    return created;
+}
+export function isPendingStateActive(state, sessionId) {
+    if (!state)
+        return false;
+    if (!sessionId || state.sessionId !== sessionId)
+        return false;
+    const age = Date.now() - new Date(state.createdAt).getTime();
+    if (age > state.ttlMs)
+        return false;
+    return state.delegations.some((d) => d.status === 'pending');
+}
+export function getActivePendingDelegations(sessionId, projectRoot = process.cwd()) {
+    const state = loadPendingDelegationsState(projectRoot);
+    if (!isPendingStateActive(state, sessionId))
+        return [];
+    return state.delegations.filter((d) => d.status === 'pending');
+}
+export function satisfyDelegation(input, projectRoot = process.cwd()) {
+    const state = loadPendingDelegationsState(projectRoot);
+    if (!state)
+        return { satisfied: [], clearedAll: false };
+    const pending = state.delegations.filter((d) => d.status === 'pending');
+    if (pending.length === 0)
+        return { satisfied: [], clearedAll: false };
+    const prompt = (input.toolPrompt ?? '').toLowerCase();
+    let matches = [];
+    if (input.delegationId) {
+        matches = pending.filter((d) => d.id === input.delegationId);
+    }
+    else if (input.planTodoId) {
+        matches = pending.filter((d) => d.planTodoId === input.planTodoId || prompt.includes(input.planTodoId.toLowerCase()));
+    }
+    else if (input.taskId) {
+        matches = pending.filter((d) => d.taskId === input.taskId || prompt.includes(input.taskId.toLowerCase()));
+    }
+    else if (input.agent) {
+        const norm = normalizeAgent(input.agent);
+        matches = pending.filter((d) => normalizeAgent(d.agent) === norm);
+    }
+    if (matches.length === 0 && prompt) {
+        for (const d of pending) {
+            if (d.planTodoId && prompt.includes(d.planTodoId.toLowerCase())) {
+                matches.push(d);
+                break;
+            }
+            if (prompt.includes(d.taskId.toLowerCase())) {
+                matches.push(d);
+                break;
+            }
+        }
+    }
+    if (matches.length === 0 && pending.length === 1) {
+        const only = pending[0];
+        const hint = only.spawnHint.description.toLowerCase();
+        if (prompt && hint && prompt.includes(hint.slice(0, 40))) {
+            matches = [only];
+        }
+    }
+    if (matches.length === 0) {
+        return { satisfied: [], clearedAll: false };
+    }
+    const now = new Date().toISOString();
+    const matchIds = new Set(matches.map((m) => m.id));
+    for (const d of state.delegations) {
+        if (matchIds.has(d.id) && d.status === 'pending') {
+            d.status = 'satisfied';
+            d.satisfiedAt = now;
+        }
+    }
+    savePendingDelegationsState(state, projectRoot);
+    for (const m of matches) {
+        if (m.planTodoId) {
+            updatePlanTodoStatus(m.planTodoId, 'in_progress', projectRoot);
+        }
+    }
+    const stillPending = state.delegations.some((d) => d.status === 'pending');
+    return { satisfied: matches, clearedAll: !stillPending };
+}
+export function clearPendingDelegations(projectRoot = process.cwd()) {
+    const filePath = pendingDelegationsPath(projectRoot);
+    if (!fs.existsSync(filePath))
+        return false;
+    fs.unlinkSync(filePath);
+    return true;
+}
+export function clearPendingDelegationsForSessionChange(newSessionId, projectRoot = process.cwd()) {
+    const state = loadPendingDelegationsState(projectRoot);
+    if (!state)
+        return false;
+    if (newSessionId && state.sessionId === newSessionId)
+        return false;
+    fs.unlinkSync(pendingDelegationsPath(projectRoot));
+    return true;
+}
+export function delegationSummaryForResponse(delegations) {
+    return delegations.map((d) => ({
+        id: d.id,
+        taskId: d.taskId,
+        agent: d.agent,
+        planTodoId: d.planTodoId,
+        matchMethod: d.matchMethod,
+        matchConfidence: d.matchConfidence,
+        spawnHint: d.spawnHint,
+    }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "0xray",
-  "version": "3.4.10",
+  "version": "3.5.0",
   "description": "Multi-agent orchestration and Codex governance for OpenCode, Hermes, Grok Build, and OpenClaw",
   "readme": "README.md",
   "license": "MIT",
@@ -126,7 +126,8 @@
     "safe-publish": "npm run prepare-consumer && npm run build",
     "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: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"
   },
   "files": [
     "dist/",
@@ -139,6 +140,7 @@
     "scripts/mjs/validate-mcp-connectivity.cjs",
     "scripts/mjs/validate-postinstall-config.mjs",
     "scripts/mjs/verify-orchestrator-behavior.mjs",
+    "scripts/mjs/verify-grok-delegation-gate.mjs",
     "src/opencode/",
     "src/opencode/codex.codex",
     "src/opencode/commands/",

package/scripts/mjs/verify-grok-delegation-gate.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * Hook fixture verify — PreToolUse delegation gate with seeded pending-delegations.json.
+ * Run: node scripts/mjs/verify-grok-delegation-gate.mjs
+ */
+import { execSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(__dirname, '../..');
+const preToolHook = join(packageRoot, 'dist/integrations/grok/hooks/pre-tool-use.js');
+
+let failed = 0;
+function pass(n) {
+  console.log(`✅ ${n}`);
+}
+function fail(n, d = '') {
+  failed++;
+  console.error(`❌ ${n}${d ? ` — ${d}` : ''}`);
+}
+
+function runHook(fixture, env = {}) {
+  const payload = JSON.stringify(fixture);
+  const out = execSync(`printf '%s' '${payload.replace(/'/g, "'\\''")}' | node "${preToolHook}"`, {
+    encoding: 'utf8',
+    env: { ...process.env, ...env },
+  });
+  return JSON.parse(out.trim());
+}
+
+const tmp = mkdtempSync(join(tmpdir(), 'xray-gate-verify-'));
+mkdirSync(join(tmp, '.xray', 'state'), { recursive: true });
+writeFileSync(
+  join(tmp, '.xray', 'features.json'),
+  JSON.stringify({
+    multi_agent_orchestration: {
+      enabled: true,
+      lead_dev_mode: true,
+      auto_chain_delegations: true,
+    },
+  }),
+);
+writeFileSync(
+  join(tmp, '.xray', 'state', 'lead-dev-plan.json'),
+  JSON.stringify({ active: true }),
+);
+writeFileSync(
+  join(tmp, '.xray', 'state', 'pending-delegations.json'),
+  JSON.stringify({
+    sessionId: 'verify-gate',
+    createdAt: new Date().toISOString(),
+    ttlMs: 14400000,
+    delegations: [
+      {
+        id: 'del-verify',
+        taskId: 'impl-1',
+        agent: 'backend-engineer',
+        taskDescription: 'implement',
+        taskType: 'implement',
+        sessionId: 'verify-gate',
+        planTodoId: '2.1',
+        planTodoTask: 'swap deps',
+        matchMethod: 'agent-only',
+        matchConfidence: 0.5,
+        status: 'pending',
+        createdAt: new Date().toISOString(),
+        satisfiedAt: null,
+        spawnHint: {
+          tool: 'Task',
+          subagent_type: 'backend-engineer',
+          description: 'Lead-dev delegation 2.1',
+          planTodoId: '2.1',
+          delegationId: 'del-verify',
+        },
+      },
+    ],
+  }),
+);
+
+const baseEnv = {
+  GROK_WORKSPACE_ROOT: tmp,
+  GROK_SESSION_ID: 'verify-gate',
+};
+
+try {
+  const deny = runHook(
+    {
+      toolName: 'search_replace',
+      workspaceRoot: tmp,
+      sessionId: 'verify-gate',
+      toolInput: { path: 'src/a.ts', new_string: 'x' },
+    },
+    baseEnv,
+  );
+  if (deny.decision === 'deny' && deny.gate === 'auto-chain-pending') {
+    pass('PreToolUse denies write while pending');
+  } else {
+    fail('write deny', JSON.stringify(deny));
+  }
+
+  const allowRead = runHook(
+    {
+      toolName: 'read_file',
+      workspaceRoot: tmp,
+      sessionId: 'verify-gate',
+      toolInput: { path: 'src/a.ts' },
+    },
+    baseEnv,
+  );
+  if (allowRead.decision === 'allow') pass('PreToolUse allows read while pending');
+  else fail('read allow', JSON.stringify(allowRead));
+
+  const allowTask = runHook(
+    {
+      toolName: 'Task',
+      workspaceRoot: tmp,
+      sessionId: 'verify-gate',
+      toolInput: { prompt: 'plan todo 2.1 swap deps', subagent_type: 'backend-engineer' },
+    },
+    baseEnv,
+  );
+  if (allowTask.decision === 'allow') pass('PreToolUse allows Task while pending');
+  else fail('Task allow', JSON.stringify(allowTask));
+
+  writeFileSync(
+    join(tmp, '.xray', 'state', 'lead-dev-plan.json'),
+    JSON.stringify({
+      active: true,
+      persistedAt: new Date().toISOString(),
+      phases: [
+        {
+          id: 'phase-2',
+          todos: [
+            {
+              id: '2.1',
+              task: 'swap deps',
+              subagent: 'backend-engineer',
+              status: 'pending',
+            },
+          ],
+        },
+      ],
+    }),
+  );
+
+  const denyWrongTodo = runHook(
+    {
+      toolName: 'Task',
+      workspaceRoot: tmp,
+      sessionId: 'verify-gate',
+      toolInput: { prompt: 'explore only', subagent_type: 'explore' },
+    },
+    baseEnv,
+  );
+  if (denyWrongTodo.decision === 'deny' && denyWrongTodo.gate === 'spawn-todo-persistence') {
+    pass('PreToolUse denies spawn skipping required plan todo');
+  } else {
+    fail('spawn todo persistence', JSON.stringify(denyWrongTodo));
+  }
+} finally {
+  rmSync(tmp, { recursive: true, force: true });
+}
+
+console.log(
+  '\n' +
+    (failed === 0
+      ? '🎉 Grok delegation gate verify passed (4/4).'
+      : `⚠️  ${failed} gate check(s) failed.`),
+);
+process.exit(failed === 0 ? 0 : 1);

package/scripts/mjs/verify-orchestrator-behavior.mjs

@@ -3,6 +3,7 @@
  * Consumer behavior verify — orchestrator honesty (ships in 0xray tarball).
  * Run: node node_modules/0xray/scripts/mjs/verify-orchestrator-behavior.mjs
  */
+import { existsSync, readFileSync, unlinkSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
 
@@ -113,10 +114,55 @@ if (text.includes('Deferred') && text.includes('❌ FAILED')) {
   fail('defer honesty', text.slice(0, 200));
 }
 
+// 6. delegations[] block in response
+if (text.includes('delegations') && text.includes('spawnHint')) {
+  pass('orchestrate-task includes delegations[] JSON block');
+} else {
+  fail('delegations block', 'missing JSON delegations in response');
+}
+
+// 7. pending-delegations.json written on defer (consumer cwd, not package root)
+const pendingPath = join(process.cwd(), '.xray', 'state', 'pending-delegations.json');
+if (existsSync(pendingPath)) {
+  try {
+    const pending = JSON.parse(readFileSync(pendingPath, 'utf8'));
+    if (pending.delegations?.some((d) => d.status === 'pending' && d.agent === 'backend-engineer')) {
+      pass('pending-delegations.json recorded on defer');
+    } else {
+      fail('pending file content', 'no pending backend-engineer delegation');
+    }
+  } catch (e) {
+    fail('pending file parse', e.message);
+  }
+} else {
+  fail('pending-delegations.json', 'file missing after defer');
+}
+
+// 8. spawnHint includes Task tool
+try {
+  const match = text.match(/```json\n([\s\S]*?)\n```/);
+  const block = match ? JSON.parse(match[1]) : null;
+  const hint = block?.delegations?.[0]?.spawnHint;
+  if (hint?.tool === 'Task' && hint?.subagent_type) {
+    pass('delegations spawnHint routes to host Task');
+  } else {
+    fail('spawnHint', JSON.stringify(hint));
+  }
+} catch (e) {
+  fail('spawnHint parse', e.message);
+}
+
+try {
+  if (existsSync(pendingPath)) unlinkSync(pendingPath);
+} catch {
+  /* cleanup best-effort */
+}
+
+const total = 8;
 console.log(
   '\n' +
     (failed === 0
-      ? '🎉 Orchestrator behavior verify passed (5/5).'
+      ? `🎉 Orchestrator behavior verify passed (${total}/${total}).`
       : `⚠️  ${failed} behavior check(s) failed.`),
 );
 process.exit(failed === 0 ? 0 : 1);

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

@@ -42,6 +42,21 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/post-tool-use.js"
+            ],
+            "timeout": 15000
+          }
+        ]
+      }
     ]
   }
 }

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

@@ -10,6 +10,8 @@ import {
   isLeadDevModeActive,
   persistLeadDevPlan,
 } from '../../../nucleus/autonomy-kernel.js';
+import { bindPlanToSession } from '../../../nucleus/lead-dev-plan-persistence.js';
+import { clearPendingDelegations } from '../../../nucleus/pending-delegations.js';
 import { getExecutionPlanner } from '../execution/execution-planner.js';
 import { addObservations, extractComplexityObservations } from '../aside-context.js';
 import type { OrchestrationTask, ComplexityAnalysis } from '../types.js';
@@ -65,7 +67,7 @@ export class ComplexityHandler {
    * Handle analyze-complexity request
    */
   async handleAnalyzeComplexity(
-    args: { tasks: AnalyzeComplexityInput[] },
+    args: { tasks: AnalyzeComplexityInput[]; sessionId?: string },
     asideId?: string,
   ): Promise<{ content: Array<{ type: string; text: string }> }> {
     const tasks = normalizeAnalyzeTasks(args.tasks ?? []);
@@ -102,13 +104,18 @@ export class ComplexityHandler {
 
       if (leadDevPlan) {
         try {
+          const sessionId = args.sessionId ?? `analyze-${Date.now()}`;
+          clearPendingDelegations();
           const planPath = persistLeadDevPlan(leadDevPlan);
+          const bound = bindPlanToSession(sessionId);
           await frameworkLogger.log(
             'orchestrator.server',
             'lead-dev-plan-persisted',
             'info',
             {
               planPath,
+              sessionId,
+              planGeneration: bound?.planGeneration,
               phaseCount: leadDevPlan.phases.length,
               todoCount: leadDevPlan.phases.reduce((n, p) => n + p.todos.length, 0),
             },