0xray 4.0.13 → 4.0.15

package/dist/nucleus/aside-worktree.js

@@ -0,0 +1,164 @@
+/**
+ * User-aside worktree path resolution, spawn cwd validation, optional git provision.
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { isUserAsidesEnabled } from './user-aside.js';
+export function normalizeWorktreePath(worktree, projectRoot) {
+    const trimmed = worktree.trim().replace(/\/$/, '');
+    const resolved = path.isAbsolute(trimmed) ? trimmed : path.resolve(projectRoot, trimmed);
+    return resolved.replace(/\/$/, '');
+}
+export function isAutoProvisionWorktreeEnabled(projectRoot = process.cwd()) {
+    if (!isUserAsidesEnabled(projectRoot))
+        return false;
+    const featuresPath = path.join(projectRoot, '.xray', 'features.json');
+    if (!fs.existsSync(featuresPath))
+        return false;
+    try {
+        const data = JSON.parse(fs.readFileSync(featuresPath, 'utf8'));
+        const raw = data.multi_agent_orchestration?.user_asides;
+        if (raw?.enabled === false)
+            return false;
+        return raw?.auto_provision_worktree === true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Extract spawn cwd from host Task / spawn_subagent tool input. */
+export function extractSpawnCwd(toolInput, projectRoot) {
+    const isolation = toolInput.isolation ?? toolInput.isolation_mode;
+    if (isolation === 'worktree' || isolation === 'git_worktree') {
+        const wt = toolInput.worktree_path ??
+            toolInput.worktreePath ??
+            toolInput.worktree ??
+            toolInput.cwd ??
+            toolInput.working_directory ??
+            toolInput.workingDirectory;
+        if (wt != null && String(wt).trim() !== '') {
+            return normalizeWorktreePath(String(wt), projectRoot);
+        }
+    }
+    const raw = toolInput.cwd ??
+        toolInput.working_directory ??
+        toolInput.workingDirectory;
+    if (raw == null || String(raw).trim() === '')
+        return null;
+    return normalizeWorktreePath(String(raw), projectRoot);
+}
+export function validateAsideWorktreeCwd(worktree, toolInput, projectRoot) {
+    if (!worktree?.trim())
+        return { valid: true };
+    const expected = normalizeWorktreePath(worktree, projectRoot);
+    const projectNorm = path.resolve(projectRoot).replace(/\/$/, '');
+    if (projectNorm === expected || projectNorm.startsWith(`${expected}/`)) {
+        return { valid: true };
+    }
+    const spawnCwd = extractSpawnCwd(toolInput, projectRoot);
+    if (!spawnCwd) {
+        return {
+            valid: false,
+            gate: 'aside-worktree-cwd-missing',
+            reason: `Aside worktree is ${expected} but project root is ${projectNorm} — ` +
+                'spawn must set cwd / working_directory / isolation:worktree to the aside worktree',
+            hint: {
+                worktree: expected,
+                projectRoot: projectNorm,
+                required: ['cwd', 'working_directory', 'isolation:worktree'],
+            },
+        };
+    }
+    if (spawnCwd !== expected && !spawnCwd.startsWith(`${expected}/`)) {
+        return {
+            valid: false,
+            gate: 'aside-worktree-cwd-mismatch',
+            reason: `Spawn cwd ${spawnCwd} does not match aside worktree ${expected}`,
+            hint: { worktree: expected, spawnCwd, projectRoot: projectNorm },
+        };
+    }
+    return { valid: true };
+}
+function gitBranchExists(projectRoot, branch) {
+    try {
+        execFileSync('git', ['rev-parse', '--verify', branch], {
+            cwd: projectRoot,
+            stdio: 'pipe',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolvePathForCompare(p) {
+    try {
+        return fs.realpathSync.native(p).replace(/\/$/, '');
+    }
+    catch {
+        return path.resolve(p).replace(/\/$/, '');
+    }
+}
+function isGitWorktreePath(wtPath, projectRoot) {
+    try {
+        const out = execFileSync('git', ['worktree', 'list', '--porcelain'], {
+            cwd: projectRoot,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const normalized = resolvePathForCompare(wtPath);
+        return out.split('\n').some((line) => {
+            if (!line.startsWith('worktree '))
+                return false;
+            const listed = line.slice('worktree '.length).trim();
+            return resolvePathForCompare(listed) === normalized;
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Guarded `git worktree add` when auto_provision_worktree is enabled.
+ * Creates branch with -b when it does not exist locally.
+ */
+export function provisionGitWorktree(opts) {
+    const wtPath = normalizeWorktreePath(opts.worktree, opts.projectRoot);
+    const branch = opts.branch.trim();
+    if (!branch) {
+        return { ok: false, path: wtPath, created: false, message: 'branch is required' };
+    }
+    if (fs.existsSync(wtPath)) {
+        if (isGitWorktreePath(wtPath, opts.projectRoot)) {
+            return { ok: true, path: wtPath, created: false, message: 'worktree already exists' };
+        }
+        return {
+            ok: false,
+            path: wtPath,
+            created: false,
+            message: `path exists but is not a git worktree: ${wtPath}`,
+        };
+    }
+    const gitDir = path.join(opts.projectRoot, '.git');
+    if (!fs.existsSync(gitDir)) {
+        return {
+            ok: false,
+            path: wtPath,
+            created: false,
+            message: `not a git repository: ${opts.projectRoot}`,
+        };
+    }
+    const branchExists = gitBranchExists(opts.projectRoot, branch);
+    const args = branchExists
+        ? ['worktree', 'add', wtPath, branch]
+        : ['worktree', 'add', '-b', branch, wtPath];
+    try {
+        execFileSync('git', args, { cwd: opts.projectRoot, stdio: 'pipe' });
+        return { ok: true, path: wtPath, created: true, message: 'worktree provisioned' };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, path: wtPath, created: false, message };
+    }
+}

package/dist/nucleus/autonomy-kernel.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Lead-dev plan builder — internal implementation for orchestrator + hooks.
+ * Config: features.json → multi_agent_orchestration (lead_dev_mode), NOT a separate surface.
+ */
+export declare const LEAD_DEV_RULES: readonly ["Phased plan + detailed todos; assign best subagent; monitor output; iterate fully", "Lead dev takes helm — loop test fix until complete; no permission pings", "Per-suite test triage after major changes; full suite only when individuals pass", "Lead stays main thread; subagents execute; update todos continuously", "Read all console and test output; triage fix rerun", "Never defer errors as pre-existing — add todo and resolve", "Resolve all errors before phase completion"];
+export declare const SYNTHESIS_REALIGNMENT_PHASE_ID = "phase-synthesis";
+export declare const MANDATORY_MAJOR_CONSULTS: readonly ["researcher", "architect-tools", "code-review"];
+export type SubagentRoute = 'strategist' | 'architect-tools' | 'researcher' | 'backend-engineer' | 'frontend-engineer' | 'bug-triage' | 'code-review' | 'security-audit' | 'enforcer';
+export interface LeadDevTodo {
+    id: string;
+    task: string;
+    subagent: SubagentRoute;
+    status: 'pending' | 'in_progress' | 'completed';
+}
+export interface LeadDevPhase {
+    id: string;
+    name: string;
+    goal: string;
+    definitionOfDone: string;
+    todos: LeadDevTodo[];
+}
+export interface LeadDevPlanTaskInput {
+    description: string;
+    type?: string;
+}
+export interface LeadDevPlan {
+    active: boolean;
+    rules: readonly string[];
+    codexTerms: [59, 67, 68, 69];
+    description: string;
+    complexity: number;
+    requiresPhasedPlan: boolean;
+    recommendedStrategy: string;
+    mandatoryConsults: string[];
+    phases: LeadDevPhase[];
+    testProtocol: {
+        perSuiteFirst: boolean;
+        fullSuiteGate: boolean;
+        hint: string;
+    };
+}
+export declare function isLeadDevModeActive(): boolean;
+export declare function routeSubagent(taskType: string): SubagentRoute;
+export declare function shouldFlagFullTestSuite(command: string): boolean;
+/** Mandatory-consult plan for synthesis checkpoint realignment (no implementation phase). */
+export declare function buildSynthesisCheckpointPlan(dueReason: string | null, projectRoot?: string): LeadDevPlan | null;
+export declare function buildLeadDevPlan(description: string, taskTypes?: string[], taskInputs?: LeadDevPlanTaskInput[], mcpOverallComplexity?: number, projectRoot?: string): LeadDevPlan | null;
+export declare function buildSessionBootContext(): Record<string, unknown>;
+/** Persist plan for PreToolUse spawn_subagent gate */
+export declare function persistLeadDevPlan(plan: LeadDevPlan, projectRoot?: string): string;
+/** @deprecated Use isLeadDevModeActive */
+export declare const isAutonomyKernelActive: typeof isLeadDevModeActive;
+/** @deprecated Use buildLeadDevPlan */
+export declare const buildAutonomyIntake: typeof buildLeadDevPlan;
+export declare const AUTONOMY_RULES: readonly ["Phased plan + detailed todos; assign best subagent; monitor output; iterate fully", "Lead dev takes helm — loop test fix until complete; no permission pings", "Per-suite test triage after major changes; full suite only when individuals pass", "Lead stays main thread; subagents execute; update todos continuously", "Read all console and test output; triage fix rerun", "Never defer errors as pre-existing — add todo and resolve", "Resolve all errors before phase completion"];

package/dist/nucleus/autonomy-kernel.js

@@ -0,0 +1,234 @@
+/**
+ * Lead-dev plan builder — internal implementation for orchestrator + hooks.
+ * Config: features.json → multi_agent_orchestration (lead_dev_mode), NOT a separate surface.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { featuresConfigLoader } from '../core/features-config.js';
+import { scoreComplexity } from './thin-dispatch.js';
+import { conferDefaultForProfile, resolveRuntimeSuitProfile } from './suit-temperament.js';
+export const LEAD_DEV_RULES = [
+    'Phased plan + detailed todos; assign best subagent; monitor output; iterate fully',
+    'Lead dev takes helm — loop test fix until complete; no permission pings',
+    'Per-suite test triage after major changes; full suite only when individuals pass',
+    'Lead stays main thread; subagents execute; update todos continuously',
+    'Read all console and test output; triage fix rerun',
+    'Never defer errors as pre-existing — add todo and resolve',
+    'Resolve all errors before phase completion',
+];
+export const SYNTHESIS_REALIGNMENT_PHASE_ID = 'phase-synthesis';
+export const MANDATORY_MAJOR_CONSULTS = [
+    'researcher',
+    'architect-tools',
+    'code-review',
+];
+const TASK_TYPE_ROUTES = {
+    plan: 'strategist',
+    architecture: 'architect-tools',
+    research: 'researcher',
+    implement: 'backend-engineer',
+    frontend: 'frontend-engineer',
+    test: 'bug-triage',
+    review: 'code-review',
+    security: 'security-audit',
+    governance: 'enforcer',
+};
+function orchestrationConfig() {
+    try {
+        return featuresConfigLoader.loadConfig().multi_agent_orchestration;
+    }
+    catch {
+        return { enabled: true };
+    }
+}
+export function isLeadDevModeActive() {
+    const cfg = orchestrationConfig();
+    return cfg.enabled && cfg.lead_dev_mode !== false;
+}
+export function routeSubagent(taskType) {
+    return TASK_TYPE_ROUTES[taskType.toLowerCase().trim()] ?? 'backend-engineer';
+}
+export function shouldFlagFullTestSuite(command) {
+    const cfg = orchestrationConfig();
+    if (!cfg.enabled || cfg.per_suite_test_triage === false)
+        return false;
+    const cmd = command.toLowerCase();
+    const isTest = /\b(npm\s+(run\s+)?test|vitest\s+run|pnpm\s+test|yarn\s+test)\b/.test(cmd);
+    const hasFocusedTarget = /--\s+\S+\.test/.test(cmd) ||
+        /vitest\s+run\s+\S+\.test/.test(cmd) ||
+        /\btest:\w+/.test(cmd);
+    return isTest && !hasFocusedTarget;
+}
+function buildImplementationTodos(description, taskTypes, taskInputs, idPrefix) {
+    if (taskInputs.length > 0) {
+        return taskInputs.map((t, i) => ({
+            id: `${idPrefix}.${i + 1}`,
+            task: t.description.slice(0, 200),
+            subagent: routeSubagent(t.type ?? 'implement'),
+            status: 'pending',
+        }));
+    }
+    return taskTypes.map((type, i) => ({
+        id: `${idPrefix}.${i + 1}`,
+        task: description.slice(0, 200),
+        subagent: routeSubagent(type),
+        status: 'pending',
+    }));
+}
+/** Mandatory-consult plan for synthesis checkpoint realignment (no implementation phase). */
+export function buildSynthesisCheckpointPlan(dueReason, projectRoot = process.cwd()) {
+    if (!isLeadDevModeActive())
+        return null;
+    const cfg = orchestrationConfig();
+    const profile = resolveRuntimeSuitProfile(projectRoot);
+    const autoConsult = profile === 'frontier'
+        ? cfg.confer?.enabled === true || cfg.confer_on_synthesis === true
+        : profile === 'strict'
+            ? true
+            : cfg.auto_consult_major_work !== false;
+    const mandatoryConsults = autoConsult ? [...MANDATORY_MAJOR_CONSULTS] : [];
+    if (mandatoryConsults.length === 0)
+        return null;
+    const reasonSuffix = dueReason ? ` (${dueReason})` : '';
+    return {
+        active: true,
+        rules: LEAD_DEV_RULES,
+        codexTerms: [59, 67, 68, 69],
+        description: `Synthesis checkpoint: reflect and realign${reasonSuffix}`,
+        complexity: 30,
+        requiresPhasedPlan: true,
+        recommendedStrategy: 'sequential',
+        mandatoryConsults,
+        phases: [
+            {
+                id: SYNTHESIS_REALIGNMENT_PHASE_ID,
+                name: 'Reflect & realign',
+                goal: 'Review collocated context and mandatory consults before resuming execution',
+                definitionOfDone: 'researcher + architect-tools + code-review consulted; todos realigned',
+                todos: mandatoryConsults.map((subagent, i) => ({
+                    id: `s.${i + 1}`,
+                    task: `Synthesis consult ${subagent}: review checkpoint context and realign plan`,
+                    subagent: subagent,
+                    status: 'pending',
+                })),
+            },
+        ],
+        testProtocol: {
+            perSuiteFirst: cfg.per_suite_test_triage !== false,
+            fullSuiteGate: false,
+            hint: 'Synthesis checkpoint — consult mandatory agents before resuming gated work',
+        },
+    };
+}
+export function buildLeadDevPlan(description, taskTypes = ['implement'], taskInputs = [], mcpOverallComplexity, projectRoot = process.cwd()) {
+    if (!isLeadDevModeActive())
+        return null;
+    const cfg = orchestrationConfig();
+    const profile = resolveRuntimeSuitProfile(projectRoot);
+    const threshold = cfg.phased_plan_threshold ?? 25;
+    const score = scoreComplexity(description, { taskTypes });
+    const mcpScore = mcpOverallComplexity !== undefined && Number.isFinite(mcpOverallComplexity)
+        ? Math.round(mcpOverallComplexity)
+        : 0;
+    const complexity = Math.max(score.score, mcpScore);
+    const requiresPhasedPlan = complexity > threshold || taskInputs.length > 1;
+    const autoConsult = profile === 'frontier'
+        ? cfg.confer?.enabled === true || cfg.confer_on_synthesis === true
+        : profile === 'strict' || conferDefaultForProfile(profile)
+            ? cfg.auto_consult_major_work !== false
+            : false;
+    const mandatoryConsults = autoConsult && requiresPhasedPlan ? [...MANDATORY_MAJOR_CONSULTS] : [];
+    const phases = requiresPhasedPlan
+        ? [
+            {
+                id: 'phase-1',
+                name: 'Research & architecture',
+                goal: 'Understand scope before edits',
+                definitionOfDone: 'researcher + architect-tools + code-review consulted',
+                todos: mandatoryConsults.map((subagent, i) => ({
+                    id: `1.${i + 1}`,
+                    task: `Consult ${subagent} on: ${description.slice(0, 120)}`,
+                    subagent: subagent,
+                    status: 'pending',
+                })),
+            },
+            {
+                id: 'phase-2',
+                name: 'Implementation',
+                goal: 'Execute with best subagent per todo',
+                definitionOfDone: 'Affected per-suite tests green',
+                todos: buildImplementationTodos(description, taskTypes, taskInputs, '2'),
+            },
+            {
+                id: 'phase-3',
+                name: 'Verification',
+                goal: 'Per-suite triage then full suite gate',
+                definitionOfDone: 'Full test suite green; zero open errors',
+                todos: [
+                    {
+                        id: '3.1',
+                        task: 'Run affected test files individually; triage and fix',
+                        subagent: 'bug-triage',
+                        status: 'pending',
+                    },
+                    {
+                        id: '3.2',
+                        task: 'Run full test suite gate',
+                        subagent: 'bug-triage',
+                        status: 'pending',
+                    },
+                ],
+            },
+        ]
+        : [
+            {
+                id: 'phase-1',
+                name: 'Direct execution',
+                goal: description.slice(0, 120),
+                definitionOfDone: 'Task complete with tests green',
+                todos: buildImplementationTodos(description, taskTypes, taskInputs, '1'),
+            },
+        ];
+    return {
+        active: true,
+        rules: LEAD_DEV_RULES,
+        codexTerms: [59, 67, 68, 69],
+        description,
+        complexity,
+        requiresPhasedPlan,
+        recommendedStrategy: score.recommendedStrategy,
+        mandatoryConsults,
+        phases,
+        testProtocol: {
+            perSuiteFirst: cfg.per_suite_test_triage !== false,
+            fullSuiteGate: true,
+            hint: 'After major changes: npm test -- path/to/file.test.ts → fix → repeat → full npm test last',
+        },
+    };
+}
+export function buildSessionBootContext() {
+    if (!isLeadDevModeActive()) {
+        return { lead_dev_mode: false, reason: 'multi_agent_orchestration.lead_dev_mode=false' };
+    }
+    return {
+        lead_dev_mode: true,
+        codexTerms: [67, 68],
+        rules: LEAD_DEV_RULES,
+        mcpBoot: 'xray-orchestrator → analyze-complexity (includes lead-dev plan when active)',
+        message: '[0xRay] Lead dev mode ON — phased todos, subagent dispatch, loop until green.',
+    };
+}
+/** Persist plan for PreToolUse spawn_subagent gate */
+export function persistLeadDevPlan(plan, projectRoot = process.cwd()) {
+    const stateDir = path.join(projectRoot, '.xray', 'state');
+    fs.mkdirSync(stateDir, { recursive: true });
+    const planPath = path.join(stateDir, 'lead-dev-plan.json');
+    const payload = { ...plan, persistedAt: new Date().toISOString() };
+    fs.writeFileSync(planPath, JSON.stringify(payload, null, 2));
+    return planPath;
+}
+/** @deprecated Use isLeadDevModeActive */
+export const isAutonomyKernelActive = isLeadDevModeActive;
+/** @deprecated Use buildLeadDevPlan */
+export const buildAutonomyIntake = buildLeadDevPlan;
+export const AUTONOMY_RULES = LEAD_DEV_RULES;

package/dist/nucleus/confer.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Confer — mandatory 3-agent quorum SSOT (researcher / architect-tools / code-review).
+ * Triggered automatically at synthesis checkpoint; records consult receipts + plan todos.
+ */
+import { type SynthesisConsultReceipt } from './synthesis-consult-receipt.js';
+export declare const CONFER_AGENTS: readonly ["researcher", "architect-tools", "code-review"];
+export interface ConferConfig {
+    enabled: boolean;
+    on_synthesis: boolean;
+}
+export interface ConferCheckpointState {
+    version: 1;
+    sessionId: string;
+    triggeredAt: string;
+    dueReason: string | null;
+    status: 'pending' | 'in_progress' | 'completed' | 'failed';
+    completedAgents: string[];
+    lastError?: string;
+}
+export interface ConferAgentResult {
+    todoId: string;
+    subagent: string;
+    outputText: string;
+    receiptRecorded: boolean;
+    todoCompleted: boolean;
+    verdict: SynthesisConsultReceipt['verdict'] | null;
+    error?: string;
+}
+export interface ConferQuorumResult {
+    status: 'completed' | 'partial' | 'skipped' | 'failed';
+    agents: ConferAgentResult[];
+    message: string;
+}
+export declare function conferCheckpointPath(projectRoot?: string): string;
+export declare function defaultConferConfig(): ConferConfig;
+export declare function loadConferConfig(projectRoot?: string): ConferConfig;
+export declare function isConferEnabled(projectRoot?: string): boolean;
+export declare function loadConferCheckpoint(projectRoot?: string): ConferCheckpointState | null;
+export declare function saveConferCheckpoint(state: ConferCheckpointState, projectRoot?: string): string;
+export declare function triggerConferCheckpoint(sessionId: string, dueReason: string | null, projectRoot?: string): ConferCheckpointState;
+export declare function isConferPending(projectRoot?: string, sessionId?: string | null): boolean;
+export declare function buildConferPrompt(subagent: string, todoTask: string, collocatedText: string, dueReason: string | null): string;
+/** Map confer subagent → MCP server + tool. */
+export declare function conferAgentMcpTarget(subagent: string): {
+    server: string;
+    tool: string;
+    args: (prompt: string, projectRoot: string) => Record<string, unknown>;
+};
+export declare function invokeConferAgent(subagent: string, prompt: string, projectRoot?: string): Promise<string>;
+export declare function applyConferConsultResult(todoId: string, subagent: string, sessionId: string, outputText: string, projectRoot?: string): ConferAgentResult;
+export declare function writeFixtureConferReceipt(todoId: string, subagent: string, sessionId: string, projectRoot?: string): ConferAgentResult;
+export declare function runConferQuorum(projectRoot: string | undefined, sessionId: string, options?: {
+    collocatedText?: string;
+    dueReason?: string | null;
+    fixture?: boolean;
+}): Promise<ConferQuorumResult>;
+export declare function formatConferQuorumReport(result: ConferQuorumResult): string;