0xray 4.0.11 → 4.0.13

package/dist/nucleus/user-aside.js

@@ -1,393 +0,0 @@
-/**
- * User aside — parallel work tracks (worktree-like) declared by the user.
- * SSOT: `.xray/state/asides/{id}.json` + `_active.json`.
- * Todo ids: `{asideId}.a.{phase}.{todo}` — globally unique per aside.
- */
-import * as fs from 'fs';
-import * as path from 'path';
-import { buildLeadDevPlan, isLeadDevModeActive, } from './autonomy-kernel.js';
-import { allPlanTodos, getNextRequiredTodo, getOutstandingTodos, } from './lead-dev-plan-persistence.js';
-export const USER_ASIDE_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/;
-/** Namespaced aside todo: `suit-nft.a.1.1` */
-export const USER_ASIDE_TODO_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}\.a\.\d+\.\d+$/;
-export const USER_ASIDE_STATE_VERSION = 1;
-export class UserAsideValidationError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'UserAsideValidationError';
-    }
-}
-export function assertSafeAsideId(asideId) {
-    const trimmed = asideId.trim();
-    if (!trimmed || !USER_ASIDE_ID_PATTERN.test(trimmed)) {
-        throw new UserAsideValidationError(`Invalid aside id "${asideId}" — use [a-zA-Z0-9][a-zA-Z0-9._-]{0,63}`);
-    }
-    if (trimmed.includes('..') || trimmed.includes('/') || trimmed.includes('\\')) {
-        throw new UserAsideValidationError(`Invalid aside id "${asideId}" — path characters forbidden`);
-    }
-    return trimmed;
-}
-export function asideTodoId(asideId, phaseIndex, todoIndex) {
-    return `${assertSafeAsideId(asideId)}.a.${phaseIndex + 1}.${todoIndex + 1}`;
-}
-export function isUserAsideTodoId(todoId) {
-    return USER_ASIDE_TODO_PATTERN.test(todoId);
-}
-export function parseAsideIdFromTodoId(todoId) {
-    if (!isUserAsideTodoId(todoId))
-        return null;
-    const dotA = todoId.indexOf('.a.');
-    if (dotA <= 0)
-        return null;
-    const asideId = todoId.slice(0, dotA);
-    try {
-        return assertSafeAsideId(asideId);
-    }
-    catch {
-        return null;
-    }
-}
-export function userAsidesDir(projectRoot = process.cwd()) {
-    return path.join(projectRoot, '.xray', 'state', 'asides');
-}
-export function userAsidePath(asideId, projectRoot = process.cwd()) {
-    const safe = assertSafeAsideId(asideId);
-    const resolved = path.resolve(userAsidesDir(projectRoot), `${safe}.json`);
-    const base = path.resolve(userAsidesDir(projectRoot));
-    if (!resolved.startsWith(base + path.sep) && resolved !== base) {
-        throw new UserAsideValidationError(`Aside path escapes asides directory: ${asideId}`);
-    }
-    return resolved;
-}
-export function activeAsidePointerPath(projectRoot = process.cwd()) {
-    return path.join(userAsidesDir(projectRoot), '_active.json');
-}
-export function isUserAsidesEnabled(projectRoot = process.cwd()) {
-    const featuresPath = path.join(projectRoot, '.xray', 'features.json');
-    if (!fs.existsSync(featuresPath))
-        return isLeadDevModeActive();
-    try {
-        const data = JSON.parse(fs.readFileSync(featuresPath, 'utf8'));
-        const raw = data.multi_agent_orchestration?.user_asides;
-        if (raw?.enabled === false)
-            return false;
-        return isLeadDevModeActive();
-    }
-    catch {
-        return isLeadDevModeActive();
-    }
-}
-function validateLoadedAside(parsed, expectedId) {
-    if (!parsed || typeof parsed !== 'object')
-        return null;
-    const row = parsed;
-    if (row.version !== USER_ASIDE_STATE_VERSION)
-        return null;
-    if (!row.id || !row.title || !row.description || !row.plan)
-        return null;
-    if (!Array.isArray(row.plan.phases))
-        return null;
-    try {
-        assertSafeAsideId(row.id);
-    }
-    catch {
-        return null;
-    }
-    if (expectedId && row.id !== expectedId)
-        return null;
-    for (const phase of row.plan.phases) {
-        if (!phase?.todos || !Array.isArray(phase.todos))
-            return null;
-    }
-    return row;
-}
-function remapPhasesToAsidePrefix(asideId, phases) {
-    const safeId = assertSafeAsideId(asideId);
-    return phases.map((phase, phaseIndex) => ({
-        ...phase,
-        id: phase.id.startsWith('phase-') ? `aside-phase-${phaseIndex + 1}` : phase.id,
-        todos: phase.todos.map((todo, todoIndex) => ({
-            ...todo,
-            id: asideTodoId(safeId, phaseIndex, todoIndex),
-            status: todo.status ?? 'pending',
-        })),
-    }));
-}
-/** Build a phased aside plan from task intake (mirrors lead-dev plan, namespaced todo ids). */
-export function buildUserAsidePlan(asideId, title, description, taskInputs = [], mcpOverallComplexity, projectRoot = process.cwd()) {
-    if (!isUserAsidesEnabled(projectRoot))
-        return null;
-    const safeId = assertSafeAsideId(asideId);
-    const taskTypes = taskInputs.map((t) => t.type ?? 'implement');
-    const basePlan = buildLeadDevPlan(description, taskTypes, taskInputs, mcpOverallComplexity, projectRoot);
-    if (!basePlan)
-        return null;
-    return {
-        version: USER_ASIDE_STATE_VERSION,
-        id: safeId,
-        title,
-        status: 'active',
-        description,
-        persistedAt: new Date().toISOString(),
-        plan: {
-            ...basePlan,
-            description: `[Aside ${safeId}] ${description}`,
-            phases: remapPhasesToAsidePrefix(safeId, basePlan.phases),
-        },
-    };
-}
-/** Merge new task intake into an existing aside (re-intake). */
-export function mergeUserAsideIntake(existing, description, taskInputs, mcpOverallComplexity, projectRoot = process.cwd()) {
-    const fresh = buildUserAsidePlan(existing.id, existing.title, description || existing.description, taskInputs.length > 0 ? taskInputs : [{ description: existing.description, type: 'implement' }], mcpOverallComplexity, projectRoot);
-    if (!fresh)
-        return existing;
-    const mergedPhases = [...existing.plan.phases];
-    for (const phase of fresh.plan.phases) {
-        const match = mergedPhases.find((p) => p.id === phase.id);
-        if (match) {
-            const existingIds = new Set(match.todos.map((t) => t.id));
-            for (const todo of phase.todos) {
-                if (!existingIds.has(todo.id))
-                    match.todos.push(todo);
-            }
-        }
-        else {
-            mergedPhases.push(phase);
-        }
-    }
-    return {
-        ...existing,
-        description: description || existing.description,
-        status: existing.status === 'completed' ? 'active' : existing.status,
-        plan: { ...existing.plan, phases: mergedPhases },
-    };
-}
-export function loadUserAside(asideId, projectRoot = process.cwd()) {
-    try {
-        const filePath = userAsidePath(asideId, projectRoot);
-        if (!fs.existsSync(filePath))
-            return null;
-        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-        return validateLoadedAside(parsed, assertSafeAsideId(asideId));
-    }
-    catch {
-        return null;
-    }
-}
-export function saveUserAside(aside, projectRoot = process.cwd()) {
-    assertSafeAsideId(aside.id);
-    const dir = userAsidesDir(projectRoot);
-    fs.mkdirSync(dir, { recursive: true });
-    const filePath = userAsidePath(aside.id, projectRoot);
-    const payload = {
-        ...aside,
-        version: USER_ASIDE_STATE_VERSION,
-        persistedAt: new Date().toISOString(),
-    };
-    fs.writeFileSync(filePath, JSON.stringify(payload, null, 2));
-    return filePath;
-}
-export function listUserAsideIds(projectRoot = process.cwd()) {
-    const dir = userAsidesDir(projectRoot);
-    if (!fs.existsSync(dir))
-        return [];
-    return fs
-        .readdirSync(dir)
-        .filter((f) => f.endsWith('.json') && f !== '_active.json')
-        .map((f) => f.replace(/\.json$/, ''))
-        .filter((id) => USER_ASIDE_ID_PATTERN.test(id));
-}
-export function loadActiveAsidePointer(projectRoot = process.cwd()) {
-    const pointerPath = activeAsidePointerPath(projectRoot);
-    if (!fs.existsSync(pointerPath))
-        return null;
-    try {
-        const parsed = JSON.parse(fs.readFileSync(pointerPath, 'utf8'));
-        if (!parsed?.asideId)
-            return null;
-        assertSafeAsideId(parsed.asideId);
-        return parsed;
-    }
-    catch {
-        return null;
-    }
-}
-export function getActiveAsideId(projectRoot = process.cwd(), sessionId) {
-    if (!isUserAsidesEnabled(projectRoot))
-        return null;
-    const pointer = loadActiveAsidePointer(projectRoot);
-    if (!pointer)
-        return null;
-    if (pointer.sessionId) {
-        if (!sessionId || pointer.sessionId !== sessionId)
-            return null;
-    }
-    const aside = loadUserAside(pointer.asideId, projectRoot);
-    if (!aside || aside.status !== 'active')
-        return null;
-    return pointer.asideId;
-}
-export function setActiveAsideId(asideId, projectRoot = process.cwd(), sessionId) {
-    const safeId = assertSafeAsideId(asideId);
-    const aside = loadUserAside(safeId, projectRoot);
-    if (!aside) {
-        throw new UserAsideValidationError(`Cannot activate aside "${safeId}" — file not found at .xray/state/asides/${safeId}.json`);
-    }
-    if (aside.status !== 'active' && aside.status !== 'paused') {
-        throw new UserAsideValidationError(`Cannot activate aside "${safeId}" — status is ${aside.status}`);
-    }
-    if (aside.status === 'paused') {
-        aside.status = 'active';
-        saveUserAside(aside, projectRoot);
-    }
-    const dir = userAsidesDir(projectRoot);
-    fs.mkdirSync(dir, { recursive: true });
-    const pointer = {
-        asideId: safeId,
-        activatedAt: new Date().toISOString(),
-        ...(sessionId ? { sessionId } : {}),
-    };
-    fs.writeFileSync(activeAsidePointerPath(projectRoot), JSON.stringify(pointer, null, 2));
-    return pointer;
-}
-export function clearActiveAside(projectRoot = process.cwd()) {
-    const pointerPath = activeAsidePointerPath(projectRoot);
-    if (!fs.existsSync(pointerPath))
-        return false;
-    fs.unlinkSync(pointerPath);
-    return true;
-}
-export function loadActiveUserAside(projectRoot = process.cwd(), sessionId) {
-    const id = getActiveAsideId(projectRoot, sessionId);
-    if (!id) {
-        const pointer = loadActiveAsidePointer(projectRoot);
-        if (pointer) {
-            const aside = loadUserAside(pointer.asideId, projectRoot);
-            if (aside && aside.status !== 'active')
-                clearActiveAside(projectRoot);
-        }
-        return null;
-    }
-    const aside = loadUserAside(id, projectRoot);
-    if (!aside || aside.status !== 'active') {
-        clearActiveAside(projectRoot);
-        return null;
-    }
-    return aside;
-}
-/** PersistedLeadDevPlan view of an aside for spawn-gate reuse. */
-export function asideToSpawnPlan(aside) {
-    const plan = { ...aside.plan };
-    if (aside.persistedAt)
-        plan.persistedAt = aside.persistedAt;
-    if (aside.sessionId)
-        plan.sessionId = aside.sessionId;
-    return plan;
-}
-/** Aside routable when active for session, or pointer is unscoped (accepted exception). */
-export function isAsideActiveForSession(asideId, projectRoot = process.cwd(), sessionId) {
-    const activeId = getActiveAsideId(projectRoot, sessionId);
-    if (activeId === asideId)
-        return true;
-    const pointer = loadActiveAsidePointer(projectRoot);
-    if (!pointer || pointer.asideId !== asideId)
-        return false;
-    if (!pointer.sessionId)
-        return true;
-    return Boolean(sessionId && pointer.sessionId === sessionId);
-}
-export function findAsideContainingTodo(todoId, projectRoot = process.cwd(), preferredAsideId) {
-    if (!isUserAsideTodoId(todoId))
-        return null;
-    if (preferredAsideId) {
-        const direct = loadUserAside(preferredAsideId, projectRoot);
-        if (direct) {
-            const hit = allPlanTodos(asideToSpawnPlan(direct)).some((t) => t.id === todoId);
-            if (hit)
-                return direct;
-        }
-    }
-    const parsedId = parseAsideIdFromTodoId(todoId);
-    if (parsedId) {
-        const aside = loadUserAside(parsedId, projectRoot);
-        if (aside) {
-            const hit = allPlanTodos(asideToSpawnPlan(aside)).some((t) => t.id === todoId);
-            if (hit)
-                return aside;
-        }
-    }
-    return null;
-}
-export function updateUserAsideTodoStatus(todoId, status, projectRoot = process.cwd(), sessionId) {
-    const parsedId = parseAsideIdFromTodoId(todoId);
-    let aside = parsedId
-        ? findAsideContainingTodo(todoId, projectRoot, parsedId)
-        : null;
-    if (aside && parsedId && !isAsideActiveForSession(parsedId, projectRoot, sessionId)) {
-        aside = null;
-    }
-    if (!aside)
-        aside = loadActiveUserAside(projectRoot, sessionId);
-    if (!aside)
-        return false;
-    let updated = false;
-    for (const phase of aside.plan.phases) {
-        for (const todo of phase.todos) {
-            if (todo.id === todoId) {
-                todo.status = status;
-                updated = true;
-            }
-        }
-    }
-    if (!updated)
-        return false;
-    const outstanding = getOutstandingTodos(asideToSpawnPlan(aside));
-    if (outstanding.length === 0) {
-        aside.status = 'completed';
-        clearActiveAside(projectRoot);
-    }
-    saveUserAside(aside, projectRoot);
-    return true;
-}
-export function getNextAsideTodo(aside) {
-    return getNextRequiredTodo(asideToSpawnPlan(aside));
-}
-export function formatUserAsideSummary(aside) {
-    const todos = allPlanTodos(asideToSpawnPlan(aside));
-    const done = todos.filter((t) => t.status === 'completed').length;
-    const lines = [
-        `**Aside \`${aside.id}\`** — ${aside.title}`,
-        `Status: ${aside.status} | Todos: ${done}/${todos.length}`,
-        aside.worktree ? `Worktree: \`${aside.worktree}\`` : null,
-        aside.branch ? `Branch: \`${aside.branch}\`` : null,
-        '',
-        ...todos.map((t) => `- [${t.status === 'completed' ? 'x' : ' '}] ${t.id} (${t.subagent}): ${t.task}`),
-    ].filter(Boolean);
-    return lines.join('\n');
-}
-export function getUserAsideBootHints(projectRoot = process.cwd(), sessionId) {
-    if (!isUserAsidesEnabled(projectRoot))
-        return null;
-    const aside = loadActiveUserAside(projectRoot, sessionId);
-    if (!aside)
-        return null;
-    const hints = {
-        activeAside: aside.id,
-        asideTitle: aside.title,
-        asideStatus: aside.status,
-        asideTodoPrefix: `${aside.id}.a.*`,
-        asideHint: 'Spawns route to active aside todos; orchestrate-task clearActiveAside to resume main',
-    };
-    if (aside.worktree)
-        hints.asideWorktree = aside.worktree;
-    if (aside.branch)
-        hints.asideBranch = aside.branch;
-    if (aside.governance?.trapSignals?.length) {
-        hints.asideTrapSignals = aside.governance.trapSignals;
-    }
-    if (aside.governance?.conferOnPhaseStart) {
-        hints.asideConferRecommended = true;
-        hints.asideConferTrigger = 'orchestrate-task { confer: true } or synthesis analyze-complexity';
-    }
-    return hints;
-}

package/dist/orchestrator/agent-spawn-governor.d.ts

@@ -1,126 +0,0 @@
-/**
- * Agent Spawn Governor
- *
- * Critical governance component that prevents infinite agent spawning
- * and enforces spawn limits across the multi-agent orchestration system.
- *
- * @since 2026-01-23
- */
-export interface SpawnContext {
-    agentType: string;
-    parentAgent?: string;
-    operation?: string;
-    triggeredBy?: string;
-    sessionId?: string;
-    priority?: "high" | "medium" | "low";
-}
-export interface SpawnRecord {
-    id: string;
-    agentType: string;
-    parentAgent?: string | undefined;
-    timestamp: number;
-    status: "active" | "completed" | "failed" | "terminated";
-    context: SpawnContext;
-}
-export interface SpawnLimits {
-    perAgentType: Record<string, number>;
-    totalConcurrent: number;
-    spawnRateLimit: {
-        maxPerMinute: number;
-        windowMs: number;
-    };
-    memoryLimit: {
-        maxMemoryMB: number;
-        emergencyThresholdMB: number;
-        cleanupIntervalMs: number;
-    };
-}
-export interface SpawnAuthorization {
-    authorized: boolean;
-    trackingId?: string;
-    reason?: string;
-    warnings?: string[];
-}
-export declare class AgentSpawnGovernor {
-    private limits;
-    private activeAgents;
-    private spawnHistory;
-    private readonly maxHistorySize;
-    private readonly cleanupInterval;
-    private readonly persistenceTimeout;
-    private readonly maxRetries;
-    private readonly retryDelay;
-    private cleanupTimer?;
-    private memoryMonitorInterval?;
-    private authorizationQueue;
-    private isProcessingAuthorization;
-    private getDefaultLimits;
-    private readonly defaultLimits;
-    constructor(limits?: Partial<SpawnLimits>, autoStart?: boolean);
-    private startPeriodicCleanup;
-    private startMemoryMonitoring;
-    private checkMemoryBudget;
-    private emergencyMemoryCleanup;
-    private aggressiveCleanup;
-    private deepCleanupContexts;
-    private sanitizeContext;
-    /**
-     * Authorize a new agent spawn
-     */
-    authorizeSpawn(context: SpawnContext): Promise<SpawnAuthorization>;
-    private processNextAuthorization;
-    private performAuthorization;
-    private checkAgentLimitsWithRetry;
-    private getTotalActiveWithRetry;
-    private registerSpawnWithRetry;
-    private handleAuthorizationError;
-    private categorizeError;
-    private emergencyCleanup;
-    /**
-     * Complete an agent spawn (mark as completed)
-     */
-    completeSpawn(trackingId: string, result?: boolean): Promise<void>;
-    /**
-     * Fail an agent spawn
-     */
-    failSpawn(trackingId: string, error?: Error): Promise<void>;
-    /**
-     * Terminate an agent spawn (force stop)
-     */
-    terminateSpawn(trackingId: string, reason?: string): Promise<void>;
-    /**
-     * Get current active count for agent type
-     */
-    getActiveCount(agentType: string): number;
-    /**
-     * Get total active agents system-wide
-     */
-    getTotalActive(): number;
-    /**
-     * Get spawn statistics
-     */
-    getSpawnStats(): {
-        perAgentType: Record<string, {
-            active: number;
-            total: number;
-        }>;
-        totalActive: number;
-        totalHistory: number;
-    };
-    /**
-     * Emergency: Terminate all active agents
-     */
-    emergencyShutdown(reason?: string): Promise<void>;
-    private registerSpawn;
-    private checkSpawnRateLimit;
-    private detectInfiniteSpawn;
-    private getRecentSpawns;
-    private findRecord;
-    private generateTrackingId;
-    private cleanupOldRecords;
-    private withTimeout;
-    private withRetry;
-    start(): void;
-    destroy(): void;
-}
-export declare const agentSpawnGovernor: AgentSpawnGovernor;