@nexus-cortex/core 4.26.0

package/dist/orchestrator/SubAgentPermissionChecker.js

@@ -0,0 +1,239 @@
+/**
+ * Sub-Agent Permission Checker
+ *
+ * Manages permission delegation and tool restriction enforcement
+ * for sub-agents. Ensures sub-agents can only access tools
+ * specified in their agent definition AND approved by the parent's
+ * permission policies.
+ *
+ * Security Model:
+ * - Sub-agents inherit parent's base permissions
+ * - Tool restrictions in agent definition further limit access
+ * - Sub-agents CANNOT gain permissions parent doesn't have
+ *
+ * @module orchestrator/SubAgentPermissionChecker
+ * @version 1.0.0
+ */
+/**
+ * Sub-Agent Permission Checker
+ *
+ * Provides layered permission checking for sub-agents:
+ * 1. First checks if tool is in agent's allowed tool list
+ * 2. Then checks parent's permission policies
+ */
+export class SubAgentPermissionChecker {
+    name;
+    priority = 100; // High priority
+    enabled = true;
+    config;
+    allowedTools;
+    parentPolicies = [];
+    constructor(config) {
+        this.config = config;
+        this.name = `SubAgentPermission:${config.agentId}`;
+        // Build allowed tools set
+        if (config.agentDefinition.tools === 'all') {
+            this.allowedTools = 'all';
+        }
+        else {
+            this.allowedTools = new Set(config.agentDefinition.tools.map((t) => t.toLowerCase()));
+        }
+        if (config.debug) {
+            console.log(`[SubAgentPermissionChecker] Created for agent "${config.agentDefinition.name}"`, `Tools: ${this.allowedTools === 'all' ? 'all' : Array.from(this.allowedTools).join(', ')}`);
+        }
+    }
+    /**
+     * Add a parent permission policy
+     * These policies are checked AFTER agent tool restriction
+     */
+    addParentPolicy(policy) {
+        this.parentPolicies.push(policy);
+        // Keep sorted by priority
+        this.parentPolicies.sort((a, b) => b.priority - a.priority);
+    }
+    /**
+     * Set all parent policies at once
+     */
+    setParentPolicies(policies) {
+        this.parentPolicies = [...policies].sort((a, b) => b.priority - a.priority);
+    }
+    /**
+     * Check if a tool is in the agent's allowed tools list
+     */
+    isToolAllowedByAgent(toolName) {
+        if (this.allowedTools === 'all') {
+            return true;
+        }
+        return this.allowedTools.has(toolName.toLowerCase());
+    }
+    /**
+     * Get the list of allowed tools for this agent
+     */
+    getAllowedTools() {
+        if (this.allowedTools === 'all') {
+            return 'all';
+        }
+        return Array.from(this.allowedTools);
+    }
+    /**
+     * Evaluate permission for a tool call
+     *
+     * @param context Permission context with tool info
+     * @returns Permission decision
+     */
+    async evaluate(context) {
+        const result = await this.checkPermission(context.toolName, context.toolInput, context);
+        return {
+            allowed: result.allowed,
+            reason: result.reason,
+            canApprove: result.canApprove,
+        };
+    }
+    /**
+     * Full permission check with detailed result
+     *
+     * @param toolName Name of the tool being called
+     * @param toolInput Tool input parameters
+     * @param context Optional additional context
+     */
+    async checkPermission(toolName, toolInput, context) {
+        // Step 1: Check agent tool restriction
+        if (!this.isToolAllowedByAgent(toolName)) {
+            const allowedList = this.allowedTools === 'all'
+                ? 'all tools'
+                : Array.from(this.allowedTools).join(', ');
+            if (this.config.debug) {
+                console.log(`[SubAgentPermissionChecker] Tool "${toolName}" blocked by agent restriction.`, `Allowed: ${allowedList}`);
+            }
+            return {
+                allowed: false,
+                reason: `Tool "${toolName}" is not in the agent's allowed tools list. ` +
+                    `Agent "${this.config.agentDefinition.name}" can only use: ${allowedList}`,
+                canApprove: false, // Agent restrictions cannot be overridden
+                blockedBy: 'agent_restriction',
+            };
+        }
+        // Step 2: Check parent policies
+        if (this.parentPolicies.length > 0) {
+            const fullContext = {
+                toolName,
+                toolInput,
+                sessionId: context?.sessionId ?? this.config.agentId,
+                userId: context?.userId,
+                timestamp: context?.timestamp ?? new Date(),
+            };
+            for (const policy of this.parentPolicies) {
+                if (!policy.enabled) {
+                    continue;
+                }
+                try {
+                    const decision = await policy.evaluate(fullContext);
+                    if (!decision.allowed) {
+                        if (this.config.debug) {
+                            console.log(`[SubAgentPermissionChecker] Tool "${toolName}" blocked by parent policy "${policy.name}":`, decision.reason);
+                        }
+                        return {
+                            allowed: false,
+                            reason: decision.reason ?? `Blocked by parent policy "${policy.name}"`,
+                            canApprove: decision.canApprove ?? false,
+                            blockedBy: 'parent_policy',
+                        };
+                    }
+                }
+                catch (error) {
+                    // Policy error - fail closed
+                    console.error(`[SubAgentPermissionChecker] Error in parent policy "${policy.name}":`, error);
+                    return {
+                        allowed: false,
+                        reason: `Policy evaluation error: ${error instanceof Error ? error.message : 'Unknown'}`,
+                        canApprove: false,
+                        blockedBy: 'parent_policy',
+                    };
+                }
+            }
+        }
+        // All checks passed
+        if (this.config.debug) {
+            console.log(`[SubAgentPermissionChecker] Tool "${toolName}" allowed`);
+        }
+        return {
+            allowed: true,
+            reason: 'Tool is in allowed list and passed all parent policies',
+            canApprove: true,
+        };
+    }
+    /**
+     * Filter a list of tools to only those allowed for this agent
+     */
+    filterAllowedTools(tools) {
+        if (this.allowedTools === 'all') {
+            return tools;
+        }
+        return tools.filter((tool) => this.allowedTools !== 'all' && this.allowedTools.has(tool.toLowerCase()));
+    }
+    /**
+     * Get tools that are in agent definition but might be blocked by parent
+     */
+    async getEffectiveTools(availableTools) {
+        const allowed = [];
+        const blocked = [];
+        // First filter by agent definition
+        const agentAllowedTools = this.filterAllowedTools(availableTools);
+        // Then check each against parent policies
+        for (const tool of agentAllowedTools) {
+            const result = await this.checkPermission(tool, {});
+            if (result.allowed) {
+                allowed.push(tool);
+            }
+            else {
+                blocked.push({ tool, reason: result.reason });
+            }
+        }
+        return { allowed, blocked };
+    }
+    /**
+     * Create a summary of permissions for logging/display
+     */
+    getSummary() {
+        return {
+            agentName: this.config.agentDefinition.name,
+            agentId: this.config.agentId,
+            allowedTools: this.getAllowedTools(),
+            parentPolicies: this.parentPolicies.map((p) => p.name),
+        };
+    }
+}
+/**
+ * Create a permission checker for a sub-agent
+ *
+ * @param agentDefinition Agent definition from TaskToolExecutor
+ * @param agentId Unique agent instance ID
+ * @param parentSessionId Parent session ID
+ * @param parentPolicies Optional parent permission policies to inherit
+ */
+export function createSubAgentPermissionChecker(agentDefinition, agentId, parentSessionId, parentPolicies) {
+    const checker = new SubAgentPermissionChecker({
+        agentDefinition,
+        agentId,
+        parentSessionId,
+    });
+    if (parentPolicies) {
+        checker.setParentPolicies(parentPolicies);
+    }
+    return checker;
+}
+/**
+ * Validate that an agent definition has valid tool specifications
+ */
+export function validateAgentTools(agentDefinition, availableTools) {
+    if (agentDefinition.tools === 'all') {
+        return { valid: true, unknownTools: [] };
+    }
+    const availableSet = new Set(availableTools.map((t) => t.toLowerCase()));
+    const unknownTools = agentDefinition.tools.filter((tool) => !availableSet.has(tool.toLowerCase()));
+    return {
+        valid: unknownTools.length === 0,
+        unknownTools,
+    };
+}
+//# sourceMappingURL=SubAgentPermissionChecker.js.map

package/dist/orchestrator/SubAgentPermissionChecker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubAgentPermissionChecker.js","sourceRoot":"","sources":["../../src/orchestrator/SubAgentPermissionChecker.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator/SubAgentProcessManager.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Sub-Agent Process Manager
+ *
+ * Manages sub-agents as independent child processes. Each sub-agent runs
+ * in its own Node.js process with its own context window and can execute
+ * in true parallel with other sub-agents.
+ *
+ * Key features:
+ * - True parallelism via child_process.fork()
+ * - Process isolation (crash containment)
+ * - Independent context windows (no parent context consumption)
+ * - Real-time progress streaming via IPC
+ * - Abort/pause/resume controls
+ *
+ * Future: Visual monitoring of each agent's console output
+ *
+ * @module orchestrator/SubAgentProcessManager
+ * @version 1.0.0
+ */
+import { type ChildProcess } from 'child_process';
+import type { AgentDefinition, SubAgentResult, SpawnAgentOptions, ISubAgentManager, ISubAgentEventEmitter } from './SubAgentTypes.js';
+import type { ApprovalHandler } from '../middleware/contracts/MiddlewareContracts.js';
+/**
+ * Configuration for the process manager
+ */
+export interface SubAgentProcessManagerConfig {
+    /** Project path for agents */
+    projectPath: string;
+    /** Parent session ID for correlation */
+    parentSessionId: string;
+    /** Default model ID */
+    defaultModelId: string;
+    /** Maximum concurrent agent processes */
+    maxConcurrentAgents?: number;
+    /** Path to agent-mode.js entry point */
+    agentModulePath?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /**
+     * Approval handler from parent orchestrator.
+     * Used to forward permission requests from sub-agents to the user.
+     * If not provided, all permission requests will be denied.
+     */
+    approvalHandler?: ApprovalHandler;
+}
+/**
+ * State of an active agent process
+ */
+interface AgentProcessState {
+    agentId: string;
+    agentName: string;
+    modelId: string;
+    process: ChildProcess;
+    startTime: Date;
+    status: 'starting' | 'running' | 'completed' | 'error' | 'interrupted' | 'timeout';
+    promise: Promise<SubAgentResult>;
+    resolve: (result: SubAgentResult) => void;
+    reject: (error: Error) => void;
+    toolUseId?: string;
+}
+/**
+ * Sub-Agent Process Manager
+ *
+ * Spawns and manages sub-agent child processes for true parallel execution.
+ *
+ * @example
+ * ```typescript
+ * const manager = new SubAgentProcessManager({
+ *   projectPath: '/workspace',
+ *   parentSessionId: 'session-123',
+ *   defaultModelId: 'claude-sonnet-4-5',
+ * });
+ *
+ * // Spawn multiple agents in parallel
+ * const [result1, result2] = await Promise.all([
+ *   manager.spawnAgent(agentDef1, 'Task 1'),
+ *   manager.spawnAgent(agentDef2, 'Task 2'),
+ * ]);
+ * ```
+ */
+export declare class SubAgentProcessManager implements ISubAgentManager {
+    private config;
+    private activeAgents;
+    private completedAgents;
+    private eventEmitter;
+    private agentModulePath;
+    private tmuxMonitorEnabled;
+    private currentTeamSession;
+    private agentPaneMap;
+    private tmuxAvailable;
+    constructor(config: SubAgentProcessManagerConfig);
+    /**
+     * Resolve the path to the agent-mode.js module
+     */
+    private resolveAgentModulePath;
+    /**
+     * Spawn a new sub-agent as a child process
+     */
+    spawnAgent(agentDefinition: AgentDefinition, taskPrompt: string, options?: SpawnAgentOptions): Promise<SubAgentResult>;
+    /**
+     * Set up handlers for child process events
+     */
+    private setupProcessHandlers;
+    /**
+     * Handle messages from child process
+     */
+    private handleChildMessage;
+    /**
+     * Handle permission request from child process
+     * Forwards the request to the parent's approval handler and sends response back
+     */
+    private handlePermissionRequest;
+    /**
+     * Generate a unique agent ID
+     */
+    private generateAgentId;
+    /**
+     * Pause a running agent
+     */
+    pauseAgent(agentId: string): boolean;
+    /**
+     * Resume a paused agent
+     */
+    resumeAgent(agentId: string): boolean;
+    /**
+     * Interrupt (abort) a running agent
+     */
+    interruptAgent(agentId: string, reason: string): boolean;
+    /**
+     * Send guidance message to a running agent
+     */
+    guideAgent(agentId: string, message: string): Promise<boolean>;
+    /**
+     * Broadcast guidance to all active agents, optionally excluding one.
+     * Used for cross-agent communication — when one agent completes or produces
+     * findings, the orchestrator can forward them to still-running siblings.
+     *
+     * @param message The guidance text to broadcast
+     * @param excludeAgentId Optional agent ID to exclude (e.g., the sender)
+     */
+    broadcastGuidance(message: string, excludeAgentId?: string): void;
+    /**
+     * Get the tmux binary path, respecting TMUX_BIN env var.
+     */
+    private get tmuxBin();
+    /**
+     * Check if tmux is available on the system (cached).
+     */
+    private isTmuxAvailable;
+    /**
+     * Set up a tmux pane for a new agent (if monitoring is enabled).
+     * Creates a tmux session on first agent, splits into panes for subsequent agents.
+     */
+    private setupTmuxPane;
+    /**
+     * Mirror an agent event to its tmux pane.
+     */
+    private mirrorToTmux;
+    /**
+     * Interrupt all active agents
+     */
+    interruptAll(reason: string): number;
+    /**
+     * Wait for all active agents to complete
+     */
+    waitForAll(): Promise<SubAgentResult[]>;
+    /**
+     * Get event emitter for subscribing to agent events
+     */
+    getEventEmitter(): ISubAgentEventEmitter;
+    /**
+     * Get list of active agent IDs
+     */
+    getActiveAgentIds(): string[];
+    /**
+     * Check if an agent is currently active
+     */
+    isAgentActive(agentId: string): boolean;
+    /**
+     * Get status of an active agent
+     */
+    getAgentStatus(agentId: string): {
+        isActive: boolean;
+        status: AgentProcessState['status'];
+        elapsedMs: number;
+        agentName: string;
+        pid?: number;
+    } | null;
+    /**
+     * Get result of a completed agent
+     */
+    getCompletedResult(agentId: string): SubAgentResult | null;
+    /**
+     * Get summary of all agents
+     */
+    getSummary(): {
+        active: number;
+        completed: number;
+        agents: Array<{
+            id: string;
+            name: string;
+            status: AgentProcessState['status'];
+            elapsedMs: number;
+            pid?: number;
+        }>;
+    };
+    /**
+     * Clear completed agents from memory
+     */
+    clearCompleted(): number;
+    /**
+     * Cleanup - kill all processes
+     */
+    cleanup(): Promise<void>;
+    private getSubagentStoreDir;
+    private persistSubAgentResult;
+    /**
+     * Look up a durably persisted sub-agent result by tool_use_id.
+     * Used by validateAndRepairMessages to recover ESC-orphaned work.
+     */
+    static loadPersistedResult(sessionId: string, toolUseId: string, projectRoot?: string): SubAgentResult | null;
+}
+/**
+ * Factory function to create a SubAgentProcessManager
+ */
+export declare function createSubAgentProcessManager(projectPath: string, parentSessionId: string, defaultModelId: string, options?: Partial<SubAgentProcessManagerConfig>): SubAgentProcessManager;
+export {};
+//# sourceMappingURL=SubAgentProcessManager.d.ts.map

package/dist/orchestrator/SubAgentProcessManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubAgentProcessManager.d.ts","sourceRoot":"","sources":["../../src/orchestrator/SubAgentProcessManager.ts"],"names":[],"mappings":"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"}