@nexus-cortex/core 4.26.0

package/dist/orchestrator/SubAgentOrchestrator.js

@@ -0,0 +1,395 @@
+/**
+ * Sub-Agent Orchestrator
+ *
+ * A lightweight orchestrator for sub-agent execution.
+ * Creates a minimal conversation context for the sub-agent task,
+ * tracks tool usage and file operations, and produces a
+ * comprehensive result for the parent orchestrator.
+ *
+ * Design: Uses CortexOrchestrator's built-in agentic loop
+ * which automatically handles tool execution. The sub-agent
+ * orchestrator wraps this to add:
+ * - Event emission for real-time monitoring
+ * - Abort/pause signal handling
+ * - Result aggregation and formatting
+ *
+ * @module orchestrator/SubAgentOrchestrator
+ * @version 1.0.0
+ */
+import { createOrchestrator } from './OrchestratorFactory.js';
+import { SubAgentPermissionChecker } from './SubAgentPermissionChecker.js';
+/**
+ * Sub-Agent Orchestrator
+ *
+ * Manages the lifecycle of a sub-agent execution:
+ * 1. Creates isolated orchestrator with agent's system prompt
+ * 2. Runs the task through orchestrator's agentic loop
+ * 3. Tracks tool usage and file operations from responses
+ * 4. Handles abort/pause signals via polling
+ * 5. Produces comprehensive result for parent
+ */
+export class SubAgentOrchestrator {
+    options;
+    orchestrator;
+    permissionChecker;
+    eventEmitter;
+    pauseController;
+    abortController;
+    // Execution tracking
+    startTime;
+    endTime;
+    turnCount = 0;
+    toolUsage = new Map();
+    filesRead = new Set();
+    filesModified = new Set();
+    inputTokens = 0;
+    outputTokens = 0;
+    cacheHits = 0;
+    fullResponseParts = [];
+    isRunning = false;
+    status = 'completed';
+    error;
+    constructor(options) {
+        this.options = options;
+        this.eventEmitter = options.context.eventEmitter;
+        this.pauseController = options.context.pauseController;
+        this.abortController = options.context.abortController;
+        // Create permission checker
+        this.permissionChecker = new SubAgentPermissionChecker({
+            agentDefinition: options.config.agentDefinition,
+            agentId: options.config.agentId,
+            parentSessionId: options.context.parentSessionId,
+            debug: options.debug,
+        });
+        if (options.parentPolicies) {
+            this.permissionChecker.setParentPolicies(options.parentPolicies);
+        }
+    }
+    /**
+     * Execute the sub-agent task
+     *
+     * @returns SubAgentResult with execution details
+     */
+    async execute() {
+        this.startTime = new Date();
+        this.isRunning = true;
+        const { config, context, baseConfig } = this.options;
+        const { agentDefinition, taskPrompt, modelId, agentId } = config;
+        try {
+            // Emit started event
+            this.eventEmitter.emit('agent:started', {
+                agentId,
+                agentName: agentDefinition.name,
+                model: modelId,
+                task: this.truncateForDisplay(taskPrompt, 200),
+                parentSessionId: context.parentSessionId,
+            });
+            // Create orchestrator for sub-agent using factory
+            const projectPath = baseConfig.projectPath ?? process.cwd();
+            const orchestratorConfig = {
+                ...baseConfig,
+                defaultModelId: modelId,
+                projectPath,
+                debug: this.options.debug,
+                // Sub-agents use minimal middleware
+                enableMcp: false, // Sub-agents don't manage MCP
+                // Include the agent's system prompt
+                systemMessages: [agentDefinition.systemPrompt],
+            };
+            this.orchestrator = await createOrchestrator(orchestratorConfig, {
+                enablePermissions: true,
+                permissionMode: 'auto', // Sub-agents auto-approve within their tool restrictions
+            });
+            // Create session for the sub-agent
+            await this.orchestrator.createSession(projectPath, modelId);
+            // Execute the task through orchestrator's agentic loop
+            await this.runAgenticExecution(taskPrompt);
+        }
+        catch (error) {
+            this.error = error instanceof Error ? error : new Error(String(error));
+            this.status = 'error';
+            this.eventEmitter.emit('agent:error', {
+                agentId,
+                agentName: agentDefinition.name,
+                error: this.error,
+            });
+        }
+        finally {
+            this.isRunning = false;
+            this.endTime = new Date();
+        }
+        return this.buildResult();
+    }
+    /**
+     * Run the agentic execution with abort/pause checking
+     */
+    async runAgenticExecution(taskPrompt) {
+        const { config } = this.options;
+        const timeoutMs = config.timeoutMs ?? 300000; // 5 minutes default
+        const loopStartTime = Date.now();
+        // Check abort before starting
+        if (this.abortController.signal.aborted) {
+            this.status = 'interrupted';
+            this.eventEmitter.emit('agent:interrupted', {
+                agentId: config.agentId,
+                reason: 'Aborted before execution',
+            });
+            return;
+        }
+        // Wait if paused before starting
+        await this.pauseController.waitIfPaused();
+        // Create timeout wrapper
+        const timeoutPromise = new Promise((resolve) => {
+            setTimeout(() => resolve('timeout'), timeoutMs);
+        });
+        // Create abort wrapper
+        const abortPromise = new Promise((resolve) => {
+            this.abortController.signal.addEventListener('abort', () => resolve('abort'));
+        });
+        // Execute the orchestrator's sendMessage which runs the full agentic loop
+        const executionPromise = this.executeWithOrchestrator(taskPrompt);
+        // Race between execution, timeout, and abort
+        const result = await Promise.race([
+            executionPromise.then(() => 'completed'),
+            timeoutPromise,
+            abortPromise,
+        ]);
+        if (result === 'timeout') {
+            const elapsed = Date.now() - loopStartTime;
+            this.status = 'timeout';
+            this.eventEmitter.emit('agent:timeout', {
+                agentId: config.agentId,
+                timeoutMs,
+                elapsedMs: elapsed,
+            });
+        }
+        else if (result === 'abort') {
+            this.status = 'interrupted';
+            this.eventEmitter.emit('agent:interrupted', {
+                agentId: config.agentId,
+                reason: 'User interrupted',
+            });
+        }
+        else {
+            this.status = 'completed';
+        }
+    }
+    /**
+     * Execute the task using orchestrator's built-in agentic loop
+     */
+    async executeWithOrchestrator(taskPrompt) {
+        const { config } = this.options;
+        // The orchestrator's sendMessage handles the full agentic loop
+        // including tool execution, multi-turn conversations, etc.
+        const response = await this.orchestrator.sendMessage(taskPrompt);
+        this.turnCount = 1; // The orchestrator handles multiple internal turns
+        // Track tokens
+        if (response.usage) {
+            this.inputTokens = response.usage.inputTokens ?? 0;
+            this.outputTokens = response.usage.outputTokens ?? 0;
+            // Check for cache stats
+            if (response.usage.cache) {
+                // Use cacheReadTokens as a proxy for cache hits
+                this.cacheHits = response.usage.cache.cacheReadTokens ?? 0;
+            }
+        }
+        // Extract text content from response
+        const textContent = this.extractTextContent(response.content);
+        if (textContent) {
+            this.fullResponseParts.push(textContent);
+            this.eventEmitter.emit('agent:text', {
+                agentId: config.agentId,
+                text: textContent,
+                isFinal: true,
+            });
+        }
+        // Track tool usage from response
+        if (response.toolUses && Array.isArray(response.toolUses)) {
+            for (const toolUse of response.toolUses) {
+                this.trackToolFromResponse(toolUse);
+            }
+        }
+        // Emit progress
+        this.eventEmitter.emit('agent:progress', {
+            agentId: config.agentId,
+            turnNumber: this.turnCount,
+            totalTokens: this.inputTokens + this.outputTokens,
+            elapsedMs: Date.now() - (this.startTime?.getTime() ?? Date.now()),
+        });
+    }
+    /**
+     * Extract text content from response content
+     */
+    extractTextContent(content) {
+        if (typeof content === 'string') {
+            return content;
+        }
+        if (Array.isArray(content)) {
+            const textBlocks = content
+                .filter((block) => typeof block === 'object' && block !== null && 'type' in block && block.type === 'text')
+                .map((block) => block.text);
+            return textBlocks.join('\n\n');
+        }
+        return '';
+    }
+    /**
+     * Track tool usage from response tool use blocks
+     */
+    trackToolFromResponse(toolUse) {
+        if (typeof toolUse !== 'object' || toolUse === null)
+            return;
+        const tu = toolUse;
+        const toolName = tu.name ?? 'unknown';
+        // Update usage stats
+        const existing = this.toolUsage.get(toolName) ?? {
+            name: toolName,
+            callCount: 0,
+            totalDuration: 0,
+            errors: 0,
+        };
+        existing.callCount++;
+        this.toolUsage.set(toolName, existing);
+        // Track file operations
+        if (tu.input) {
+            this.trackFileOperation(toolName, tu.input);
+        }
+        // Emit tool call event
+        this.eventEmitter.emit('agent:tool_call', {
+            agentId: this.options.config.agentId,
+            toolName,
+            toolInput: tu.input ?? {},
+            toolId: tu.id ?? 'unknown',
+        });
+    }
+    /**
+     * Track file operations from tool inputs
+     */
+    trackFileOperation(toolName, input) {
+        const filePath = input.file_path;
+        if (!filePath)
+            return;
+        const lowerName = toolName.toLowerCase();
+        if (lowerName === 'read' || lowerName === 'glob' || lowerName === 'grep') {
+            this.filesRead.add(filePath);
+        }
+        else if (lowerName === 'write' || lowerName === 'edit') {
+            this.filesModified.add(filePath);
+        }
+    }
+    /**
+     * Build the final result
+     */
+    buildResult() {
+        const { config } = this.options;
+        const durationMs = this.endTime && this.startTime
+            ? this.endTime.getTime() - this.startTime.getTime()
+            : 0;
+        // Build tool usage summary
+        const toolsUsed = Array.from(this.toolUsage.values());
+        // Build cost metrics (rough estimate)
+        const cost = {
+            inputTokens: this.inputTokens,
+            outputTokens: this.outputTokens,
+            estimatedCost: this.estimateCost(this.inputTokens, this.outputTokens),
+            cacheHits: this.cacheHits,
+        };
+        // Build summary
+        const summary = this.buildSummary();
+        const result = {
+            agentId: config.agentId,
+            agentName: config.agentDefinition.name,
+            model: config.modelId,
+            startTime: this.startTime ?? new Date(),
+            endTime: this.endTime ?? new Date(),
+            durationMs,
+            turnCount: this.turnCount,
+            status: this.status,
+            summary,
+            fullResponse: this.fullResponseParts.join('\n\n'),
+            toolsUsed,
+            filesRead: Array.from(this.filesRead),
+            filesModified: Array.from(this.filesModified),
+            cost,
+        };
+        // Add error if present
+        if (this.error) {
+            result.error = {
+                message: this.error.message,
+                type: this.error.name,
+                stack: this.error.stack,
+            };
+        }
+        // Emit completed event
+        this.eventEmitter.emit('agent:completed', {
+            agentId: config.agentId,
+            result,
+        });
+        return result;
+    }
+    /**
+     * Build a summary for the parent LLM
+     */
+    buildSummary() {
+        const { config } = this.options;
+        const parts = [];
+        parts.push(`Agent "${config.agentDefinition.name}" ${this.status}`);
+        if (this.turnCount > 0) {
+            parts.push(`Completed ${this.turnCount} turn(s)`);
+        }
+        if (this.toolUsage.size > 0) {
+            const tools = Array.from(this.toolUsage.keys()).join(', ');
+            parts.push(`Used tools: ${tools}`);
+        }
+        if (this.filesModified.size > 0) {
+            parts.push(`Modified ${this.filesModified.size} file(s)`);
+        }
+        if (this.error) {
+            parts.push(`Error: ${this.error.message}`);
+        }
+        // Add last response snippet
+        if (this.fullResponseParts.length > 0) {
+            const lastResponse = this.fullResponseParts[this.fullResponseParts.length - 1] ?? '';
+            const snippet = this.truncateForDisplay(lastResponse, 500);
+            parts.push(`\nFinal response:\n${snippet}`);
+        }
+        return parts.join('. ');
+    }
+    /**
+     * Estimate cost based on model pricing
+     */
+    estimateCost(inputTokens, outputTokens) {
+        // Default pricing (Claude Sonnet 4.5 rates)
+        const inputRate = 3.0 / 1_000_000; // $3 per 1M tokens
+        const outputRate = 15.0 / 1_000_000; // $15 per 1M tokens
+        return inputTokens * inputRate + outputTokens * outputRate;
+    }
+    /**
+     * Truncate text for display
+     */
+    truncateForDisplay(text, maxLen) {
+        if (text.length <= maxLen)
+            return text;
+        return text.substring(0, maxLen - 3) + '...';
+    }
+    /**
+     * Get current execution status
+     */
+    getStatus() {
+        const elapsedMs = this.startTime
+            ? Date.now() - this.startTime.getTime()
+            : 0;
+        return {
+            isRunning: this.isRunning,
+            turnCount: this.turnCount,
+            status: this.status,
+            elapsedMs,
+        };
+    }
+    /**
+     * Get permission summary
+     */
+    getPermissionSummary() {
+        return this.permissionChecker.getSummary();
+    }
+}
+//# sourceMappingURL=SubAgentOrchestrator.js.map

package/dist/orchestrator/SubAgentOrchestrator.js.map

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

package/dist/orchestrator/SubAgentPermissionChecker.d.ts

@@ -0,0 +1,132 @@
+/**
+ * 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
+ */
+import type { PermissionPolicy, PermissionDecision, PermissionContext } from '../middleware/contracts/MiddlewareContracts.js';
+import type { AgentDefinition } from './SubAgentTypes.js';
+/**
+ * Configuration for sub-agent permission checking
+ */
+export interface SubAgentPermissionConfig {
+    /** The agent definition with tool restrictions */
+    agentDefinition: AgentDefinition;
+    /** Parent session ID for logging/auditing */
+    parentSessionId: string;
+    /** Sub-agent session ID */
+    agentId: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Result of a permission check
+ */
+export interface PermissionCheckResult {
+    /** Whether the tool is allowed */
+    allowed: boolean;
+    /** Reason for the decision */
+    reason: string;
+    /** Whether manual approval can override */
+    canApprove: boolean;
+    /** Which restriction blocked the tool (if denied) */
+    blockedBy?: 'agent_restriction' | 'parent_policy' | 'not_in_whitelist';
+}
+/**
+ * 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 declare class SubAgentPermissionChecker implements PermissionPolicy {
+    readonly name: string;
+    readonly priority: number;
+    readonly enabled: boolean;
+    private config;
+    private allowedTools;
+    private parentPolicies;
+    constructor(config: SubAgentPermissionConfig);
+    /**
+     * Add a parent permission policy
+     * These policies are checked AFTER agent tool restriction
+     */
+    addParentPolicy(policy: PermissionPolicy): void;
+    /**
+     * Set all parent policies at once
+     */
+    setParentPolicies(policies: PermissionPolicy[]): void;
+    /**
+     * Check if a tool is in the agent's allowed tools list
+     */
+    isToolAllowedByAgent(toolName: string): boolean;
+    /**
+     * Get the list of allowed tools for this agent
+     */
+    getAllowedTools(): string[] | 'all';
+    /**
+     * Evaluate permission for a tool call
+     *
+     * @param context Permission context with tool info
+     * @returns Permission decision
+     */
+    evaluate(context: PermissionContext): Promise<PermissionDecision>;
+    /**
+     * Full permission check with detailed result
+     *
+     * @param toolName Name of the tool being called
+     * @param toolInput Tool input parameters
+     * @param context Optional additional context
+     */
+    checkPermission(toolName: string, toolInput: unknown, context?: Partial<PermissionContext>): Promise<PermissionCheckResult>;
+    /**
+     * Filter a list of tools to only those allowed for this agent
+     */
+    filterAllowedTools(tools: string[]): string[];
+    /**
+     * Get tools that are in agent definition but might be blocked by parent
+     */
+    getEffectiveTools(availableTools: string[]): Promise<{
+        allowed: string[];
+        blocked: Array<{
+            tool: string;
+            reason: string;
+        }>;
+    }>;
+    /**
+     * Create a summary of permissions for logging/display
+     */
+    getSummary(): {
+        agentName: string;
+        agentId: string;
+        allowedTools: string[] | 'all';
+        parentPolicies: string[];
+    };
+}
+/**
+ * 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 declare function createSubAgentPermissionChecker(agentDefinition: AgentDefinition, agentId: string, parentSessionId: string, parentPolicies?: PermissionPolicy[]): SubAgentPermissionChecker;
+/**
+ * Validate that an agent definition has valid tool specifications
+ */
+export declare function validateAgentTools(agentDefinition: AgentDefinition, availableTools: string[]): {
+    valid: boolean;
+    unknownTools: string[];
+};
+//# sourceMappingURL=SubAgentPermissionChecker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SubAgentPermissionChecker.d.ts","sourceRoot":"","sources":["../../src/orchestrator/SubAgentPermissionChecker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,gDAAgD,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,kDAAkD;IAClD,eAAe,EAAE,eAAe,CAAC;IAEjC,6CAA6C;IAC7C,eAAe,EAAE,MAAM,CAAC;IAExB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAEhB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IAEjB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IAEf,2CAA2C;IAC3C,UAAU,EAAE,OAAO,CAAC;IAEpB,qDAAqD;IACrD,SAAS,CAAC,EAAE,mBAAmB,GAAG,eAAe,GAAG,kBAAkB,CAAC;CACxE;AAED;;;;;;GAMG;AACH,qBAAa,yBAA0B,YAAW,gBAAgB;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAO;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAQ;IAEjC,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,YAAY,CAAsB;IAC1C,OAAO,CAAC,cAAc,CAA0B;gBAEpC,MAAM,EAAE,wBAAwB;IAqB5C;;;OAGG;IACH,eAAe,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAM/C;;OAEG;IACH,iBAAiB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,IAAI;IAIrD;;OAEG;IACH,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAO/C;;OAEG;IACH,eAAe,IAAI,MAAM,EAAE,GAAG,KAAK;IAOnC;;;;;OAKG;IACG,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAUvE;;;;;;OAMG;IACG,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,OAAO,EAClB,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GACnC,OAAO,CAAC,qBAAqB,CAAC;IAsFjC;;OAEG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IAU7C;;OAEG;IACG,iBAAiB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QACzD,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,OAAO,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAClD,CAAC;IAqBF;;OAEG;IACH,UAAU,IAAI;QACZ,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;QAC/B,cAAc,EAAE,MAAM,EAAE,CAAC;KAC1B;CAQF;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAC7C,eAAe,EAAE,eAAe,EAChC,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,EACvB,cAAc,CAAC,EAAE,gBAAgB,EAAE,GAClC,yBAAyB,CAY3B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,eAAe,EAAE,eAAe,EAChC,cAAc,EAAE,MAAM,EAAE,GACvB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAc5C"}