@nexus-cortex/core 4.26.0

package/dist/orchestrator/SubAgentIPC.js

@@ -0,0 +1,85 @@
+/**
+ * Sub-Agent IPC Protocol
+ *
+ * Defines the message protocol for communication between parent
+ * orchestrator and child sub-agent processes.
+ *
+ * Child processes are spawned via child_process.fork() and communicate
+ * via Node.js IPC (process.send / process.on('message')).
+ *
+ * @module orchestrator/SubAgentIPC
+ * @version 1.0.0
+ */
+// ============================================
+// TYPE GUARDS
+// ============================================
+export function isParentToChildMessage(msg) {
+    if (typeof msg !== 'object' || msg === null)
+        return false;
+    const m = msg;
+    return ['start', 'abort', 'pause', 'resume', 'guidance', 'permission_response'].includes(m.type ?? '');
+}
+export function isChildToParentMessage(msg) {
+    if (typeof msg !== 'object' || msg === null)
+        return false;
+    const m = msg;
+    return [
+        'ready', 'started', 'progress', 'tool_call', 'tool_result',
+        'thinking', 'text', 'error', 'completed', 'interrupted', 'timeout', 'log',
+        'permission_request'
+    ].includes(m.type ?? '');
+}
+// ============================================
+// HELPER FUNCTIONS
+// ============================================
+/**
+ * Send message from parent to child
+ */
+export function sendToChild(childProcess, message) {
+    if (childProcess.send) {
+        return childProcess.send(message);
+    }
+    return false;
+}
+/**
+ * Send message from child to parent (call from child process)
+ */
+export function sendToParent(message) {
+    if (process.send) {
+        return process.send(message);
+    }
+    return false;
+}
+/**
+ * Create a minimal SubAgentResult for error cases
+ */
+export function createErrorResult(agentId, agentName, model, error, startTime) {
+    const endTime = new Date();
+    return {
+        agentId,
+        agentName,
+        model,
+        startTime,
+        endTime,
+        durationMs: endTime.getTime() - startTime.getTime(),
+        turnCount: 0,
+        status: 'error',
+        summary: `Agent failed: ${error.message}`,
+        fullResponse: '',
+        toolsUsed: [],
+        filesRead: [],
+        filesModified: [],
+        cost: {
+            inputTokens: 0,
+            outputTokens: 0,
+            estimatedCost: 0,
+            cacheHits: 0,
+        },
+        error: {
+            message: error.message,
+            type: error.name,
+            stack: error.stack,
+        },
+    };
+}
+//# sourceMappingURL=SubAgentIPC.js.map

package/dist/orchestrator/SubAgentIPC.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubAgentIPC.js","sourceRoot":"","sources":["../../src/orchestrator/SubAgentIPC.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0QH,+CAA+C;AAC/C,cAAc;AACd,+CAA+C;AAE/C,MAAM,UAAU,sBAAsB,CAAC,GAAY;IACjD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC1D,MAAM,CAAC,GAAG,GAAwB,CAAC;IACnC,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,qBAAqB,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;AACzG,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,GAAY;IACjD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC1D,MAAM,CAAC,GAAG,GAAwB,CAAC;IACnC,OAAO;QACL,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa;QAC1D,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,KAAK;QACzE,oBAAoB;KACrB,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;AAC3B,CAAC;AAED,+CAA+C;AAC/C,mBAAmB;AACnB,+CAA+C;AAE/C;;GAEG;AACH,MAAM,UAAU,WAAW,CACzB,YAA0B,EAC1B,OAA6B;IAE7B,IAAI,YAAY,CAAC,IAAI,EAAE,CAAC;QACtB,OAAO,YAAY,CAAC,IAAI,CAAC,OAAuB,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAA6B;IACxD,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,SAAiB,EACjB,KAAa,EACb,KAAY,EACZ,SAAe;IAEf,MAAM,OAAO,GAAG,IAAI,IAAI,EAAE,CAAC;IAC3B,OAAO;QACL,OAAO;QACP,SAAS;QACT,KAAK;QACL,SAAS;QACT,OAAO;QACP,UAAU,EAAE,OAAO,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,OAAO,EAAE;QACnD,SAAS,EAAE,CAAC;QACZ,MAAM,EAAE,OAAO;QACf,OAAO,EAAE,iBAAiB,KAAK,CAAC,OAAO,EAAE;QACzC,YAAY,EAAE,EAAE;QAChB,SAAS,EAAE,EAAE;QACb,SAAS,EAAE,EAAE;QACb,aAAa,EAAE,EAAE;QACjB,IAAI,EAAE;YACJ,WAAW,EAAE,CAAC;YACd,YAAY,EAAE,CAAC;YACf,aAAa,EAAE,CAAC;YAChB,SAAS,EAAE,CAAC;SACb;QACD,KAAK,EAAE;YACL,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB;KACF,CAAC;AACJ,CAAC"}

package/dist/orchestrator/SubAgentManager.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Sub-Agent Manager
+ *
+ * Central manager for spawning, tracking, and controlling sub-agents.
+ * Implements the ISubAgentManager interface and provides:
+ * - Agent spawning with model resolution
+ * - Concurrent agent tracking
+ * - Pause/resume/interrupt controls
+ * - Guidance message injection
+ * - Event streaming coordination
+ *
+ * @module orchestrator/SubAgentManager
+ * @version 1.0.0
+ */
+import type { AgentDefinition, SubAgentResult, ISubAgentManager, ISubAgentEventEmitter, SpawnAgentOptions } from './SubAgentTypes.js';
+import { SubAgentEventEmitter } from './SubAgentEventEmitter.js';
+import { ModelAliasResolver } from '../models/registry/ModelAliasResolver.js';
+import type { OrchestratorConfig } from './CortexOrchestrator.js';
+import type { PermissionPolicy } from '../middleware/contracts/MiddlewareContracts.js';
+/**
+ * Configuration for the sub-agent manager
+ */
+export interface SubAgentManagerConfig {
+    /** Base orchestrator configuration for child agents */
+    baseOrchestratorConfig: Partial<OrchestratorConfig>;
+    /** Parent session ID for correlation */
+    parentSessionId: string;
+    /** Parent turn number when manager was created */
+    parentTurnNumber: number;
+    /** Parent's permission policies */
+    parentPolicies?: PermissionPolicy[];
+    /** Default model ID if not specified */
+    defaultModelId?: string;
+    /** Custom model alias resolver */
+    modelResolver?: ModelAliasResolver;
+    /** Custom event emitter (default: global emitter) */
+    eventEmitter?: SubAgentEventEmitter;
+    /** Maximum concurrent agents */
+    maxConcurrentAgents?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Sub-Agent Manager
+ *
+ * Main entry point for spawning and managing sub-agents.
+ *
+ * @example
+ * ```typescript
+ * const manager = new SubAgentManager({
+ *   baseOrchestratorConfig: { projectPath: '/workspace' },
+ *   parentSessionId: 'session-123',
+ *   parentTurnNumber: 5,
+ * });
+ *
+ * const result = await manager.spawnAgent(agentDef, 'Review the auth module');
+ * console.log(result.summary);
+ * ```
+ */
+export declare class SubAgentManager implements ISubAgentManager {
+    private config;
+    private eventEmitter;
+    private modelResolver;
+    private activeAgents;
+    private completedAgents;
+    private guidanceMessages;
+    constructor(config: SubAgentManagerConfig);
+    /**
+     * Spawn a new sub-agent to execute a task
+     *
+     * @param agentDefinition Agent definition from TaskToolExecutor
+     * @param taskPrompt The task for the agent to perform
+     * @param options Optional spawn options
+     * @returns Promise resolving to the agent's result
+     */
+    spawnAgent(agentDefinition: AgentDefinition, taskPrompt: string, options?: SpawnAgentOptions): Promise<SubAgentResult>;
+    /**
+     * Execute an agent and handle cleanup
+     */
+    private executeAgent;
+    /**
+     * Resolve model ID from agent definition or override
+     */
+    private resolveModel;
+    private routerMatrix?;
+    private getRouterMatrix;
+    /**
+     * Resolve an explicit `model: 'auto'` sub-agent dispatch via the model router.
+     *
+     * This is the per-dispatch OPT-IN: passing 'auto' lets the orchestrator
+     * delegate model choice to the router, and it overrides the global
+     * MODEL_ROUTER_ENABLED flag (the orchestrator chose to route by passing
+     * 'auto'). But it only ACTUALLY routes when the decision is trustworthy —
+     * the task classifies with enough confidence AND the matrix has >= minSamples
+     * real benchmark observations for that task type. Otherwise it inherits the
+     * parent's model. The whole point of the router is to raise routing-decision
+     * quality over time; until a task type has earned trust, 'auto' is a safe
+     * no-op (parent model), and the recorded outcomes push it toward trust.
+     *
+     * Never returns 'auto', so the sub-agent always gets a concrete, resolvable
+     * model — the auto path can never crash on getModel('auto').
+     */
+    private resolveAutoModel;
+    /**
+     * Build enhanced prompt with additional context
+     */
+    private buildEnhancedPrompt;
+    /**
+     * Generate a unique agent ID
+     */
+    private generateAgentId;
+    /**
+     * Pause a running agent
+     *
+     * @param agentId Agent ID to pause
+     * @returns true if agent was found and paused
+     */
+    pauseAgent(agentId: string): boolean;
+    /**
+     * Resume a paused agent
+     *
+     * @param agentId Agent ID to resume
+     * @returns true if agent was found and resumed
+     */
+    resumeAgent(agentId: string): boolean;
+    /**
+     * Interrupt (abort) a running agent
+     *
+     * @param agentId Agent ID to interrupt
+     * @param reason Reason for interruption
+     * @returns true if agent was found and interrupted
+     */
+    interruptAgent(agentId: string, reason: string): boolean;
+    /**
+     * Send guidance message to a running agent
+     *
+     * The guidance will be injected into the agent's next turn.
+     *
+     * @param agentId Agent ID to guide
+     * @param message Guidance message
+     * @returns true if agent was found
+     */
+    guideAgent(agentId: string, message: string): Promise<boolean>;
+    /**
+     * Get pending guidance messages for an agent
+     */
+    getGuidanceMessages(agentId: string): string[];
+    /**
+     * Clear guidance messages after they've been processed
+     */
+    clearGuidanceMessages(agentId: string): void;
+    /**
+     * Get the 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;
+        isPaused: boolean;
+        elapsedMs: number;
+        agentName?: string;
+    } | null;
+    /**
+     * Get result of a completed agent
+     */
+    getCompletedResult(agentId: string): SubAgentResult | null;
+    /**
+     * Wait for all active agents to complete
+     */
+    waitForAll(): Promise<SubAgentResult[]>;
+    /**
+     * Interrupt all active agents
+     */
+    interruptAll(reason: string): number;
+    /**
+     * Pause all active agents
+     */
+    pauseAll(): number;
+    /**
+     * Resume all paused agents
+     */
+    resumeAll(): number;
+    /**
+     * Get summary of all agents
+     */
+    getSummary(): {
+        active: number;
+        completed: number;
+        agents: Array<{
+            id: string;
+            name: string;
+            status: 'active' | 'paused' | 'completed';
+            elapsedMs: number;
+        }>;
+    };
+    /**
+     * Clear completed agents from memory
+     */
+    clearCompleted(): number;
+}
+/**
+ * Create a sub-agent manager with sensible defaults
+ */
+export declare function createSubAgentManager(parentSessionId: string, parentTurnNumber: number, projectPath: string, options?: Partial<SubAgentManagerConfig>): SubAgentManager;
+//# sourceMappingURL=SubAgentManager.d.ts.map

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

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