@nexus-cortex/core 4.26.0

package/dist/orchestrator/CortexOrchestrator.d.ts

@@ -0,0 +1,986 @@
+/**
+ * Cortex Orchestrator - Phase 2.1
+ * Central Coordination Layer with Real API Integration
+ *
+ * Phase 2.0: Basic structure [OK]
+ * Phase 2.1: Real API calls, GatewayTranslationLayer, ModelRegistry ⚙
+ *
+ * Based on: docs/v4-core_library/Orchestrator_ARCHITECTURE.md
+ */
+import { AdapterRegistry } from '../adapters/AdapterRegistry.js';
+import { GatewayTranslationLayer } from '../adapters/GatewayTranslationLayer.js';
+import type { ModelConfig } from '../models/ModelConfig.interface.js';
+import { type ServerSideToolMetadata } from '../tools/ServerSideTools.js';
+import type { Message } from '../session/MessageTypes.js';
+import { APIClient, type StreamChunk } from './APIClient.js';
+import { ModularModelRegistry } from '../models/registry/ModularModelRegistry.js';
+import { ModelAliasResolver } from '../models/registry/ModelAliasResolver.js';
+import { JSONLHistoryStore } from '../session/JSONLHistoryStore.js';
+import { type CheckpointOptions, type ResumeOptions } from '../session/CheckpointManager.js';
+import type { Checkpoint } from '../session/SessionTimeline.js';
+import { HistoricalContextService } from '../tools/historical/HistoricalContextService.js';
+import { SystemReminderInjector } from '../system-messages/SystemReminderInjector.js';
+import { SystemMessageLoader } from '../system-messages/SystemMessageLoader.js';
+import { toolFactory } from '../tools/ToolFactory.js';
+import { McpClientManager } from '../mcp/index.js';
+import { McpConfigManager } from '../mcp/McpConfigManager.js';
+import { McpServerRegistry } from '../mcp/McpServerRegistry.js';
+import { ContextBudgetManager } from '../conversation/ContextBudgetManager.js';
+import type { ExecutorRegistry } from '@nexus-cortex/types';
+import { HelperModelMiddleware } from '../middleware/HelperModelMiddleware.js';
+import { StoredCompactionManager } from '../conversation/StoredCompactionManager.js';
+import { ErrorClassificationMiddleware } from '../middleware/ErrorClassificationMiddleware.js';
+import { RetryMiddleware } from '../middleware/RetryMiddleware.js';
+import { PermissionsMiddleware } from '../middleware/PermissionsMiddleware.js';
+import { SystemMessageMiddleware } from '../middleware/SystemMessageMiddleware.js';
+import { MentorshipMiddleware } from '../middleware/MentorshipMiddleware.js';
+import type { PermissionPolicy, PermissionAuditEntry, ApprovalHandler } from '../middleware/contracts/MiddlewareContracts.js';
+/**
+ * Orchestrator Configuration
+ */
+export interface OrchestratorConfig {
+    /** Default model to use if not specified */
+    defaultModelId: string;
+    /** Project path for file operations */
+    projectPath: string;
+    /** Enable automatic compaction */
+    autoCompact?: boolean;
+    /** Enable helper model fallback */
+    useHelperModels?: boolean;
+    /** Enable timeline tracking */
+    enableTimeline?: boolean;
+    /** Storage directory for sessions */
+    storageDir?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Permission profile to use ('dev', 'test', 'prod', or 'custom') */
+    permissionProfile?: 'dev' | 'test' | 'prod' | 'custom';
+    /** Enable MCP integration (Phase 2.9) */
+    enableMcp?: boolean;
+    /**
+     * Restrict the model-facing BASE/factory tools to this allowlist (case- and
+     * separator-insensitive). MCP, management, and context tools are NEVER
+     * filtered by this — they're added on top. Used by forked sub-agents to
+     * enforce their `tools` whitelist (e.g. the browse-agent gets only its
+     * read tools + the injected nexus-browser MCP tools, with no WebFetch/
+     * WebSearch/Browse fallback). Undefined = no restriction (all base tools).
+     */
+    allowedBaseTools?: string[];
+    /** Working directory for tool execution (Phase 2.5) */
+    workingDirectory?: string;
+    /** Enable sandbox for tool execution (Phase 2.5) */
+    enableSandbox?: boolean;
+    /** Allowed bash commands for sandbox (Phase 2.5) */
+    allowedCommands?: string[];
+    /** Reactive mentorship configuration */
+    reactiveMentorship?: {
+        /** Enable reactive mentorship system */
+        enabled: boolean;
+        /** Trigger mentorship on tool errors */
+        triggerOnError: boolean;
+        /** Error severity threshold for triggering mentorship */
+        errorSeverityThreshold: 'low' | 'medium' | 'high';
+        /** Enable keyword triggers (@ultrathink, @analyze, @rethink) */
+        enableKeywords: boolean;
+        /** Custom keywords for mentorship triggering */
+        customKeywords?: string[];
+        /** Helper model ID for mentorship (defaults to 'grok-4-1-fast-non-reasoning') */
+        helperModelId?: string;
+        /** Enable turn-based periodic mentorship review (Phase 2) */
+        turnBasedEnabled?: boolean;
+        /** Number of turns between periodic mentorship reviews (Phase 2) */
+        turnInterval?: number;
+        /** Enable interleaved thinking assistance for non-reasoning models (Phase 2) */
+        interleavedThinking?: boolean;
+        /** Enable pattern detection for repeated failures (Phase 2) */
+        patternDetection?: boolean;
+        /** Number of similar errors to trigger pattern detection (Phase 2) */
+        patternThreshold?: number;
+        /** Enable Active Discovery guidance to encourage thorough file reading */
+        activeDiscovery?: boolean;
+    };
+    /** Loop control configuration (inline detection) */
+    loopControl?: {
+        /** Maximum tool execution iterations per turn */
+        maxToolIterations?: number;
+        /** Maximum consecutive tool errors before stopping */
+        maxConsecutiveErrors?: number;
+        /** Soft tool-call budget per turn (R29b brake): escalating reminders at
+         *  1x and 1.5x, hard force-synthesis at 2x. */
+        toolBudgetSoft?: number;
+        /** Tool execution timeout in milliseconds */
+        toolTimeoutMs?: number;
+        /** Maximum identical tool call repetitions before detecting loop */
+        maxLoopRepetitions?: number;
+    };
+    /** Enable Anthropic Programmatic Tool Calling (PTC) — server-side code execution sandbox. */
+    enablePTC?: boolean;
+    /** Enable local code execution tool for non-PTC models. */
+    enableLocalCodeExecution?: boolean;
+    /** Enable deferred tool loading — only essential tools loaded initially. */
+    enableDeferredToolLoading?: boolean;
+    /** Model router configuration. */
+    modelRouter?: {
+        enabled: boolean;
+        strategy: 'auto' | 'matrix-only';
+        autoRecord: boolean;
+    };
+    /**
+     * Sub-agent event callback for UI integration
+     * Receives events from parallel sub-agent processes
+     */
+    onSubAgentEvent?: SubAgentEventCallback;
+}
+/**
+ * Sub-agent event types for UI integration
+ */
+export type SubAgentEventType = 'started' | 'progress' | 'tool_call' | 'text' | 'completed' | 'error';
+/**
+ * Sub-agent event payload
+ */
+export interface SubAgentEvent {
+    type: SubAgentEventType;
+    agentId: string;
+    agentName: string;
+    data: {
+        model?: string;
+        turnNumber?: number;
+        totalTokens?: number;
+        elapsedMs?: number;
+        toolName?: string;
+        toolSummary?: string;
+        text?: string;
+        isFinal?: boolean;
+        status?: string;
+        error?: string;
+    };
+}
+/**
+ * Callback for sub-agent events
+ */
+export type SubAgentEventCallback = (event: SubAgentEvent) => void;
+/**
+ * Send Message Options
+ */
+export interface SendMessageOptions {
+    /** Override current model */
+    modelId?: string;
+    /** Available tools for this request */
+    tools?: any[];
+    /** Additional system messages */
+    systemMessages?: string[];
+    /** Model parameters */
+    parameters?: {
+        temperature?: number;
+        maxTokens?: number;
+        topP?: number;
+        [key: string]: any;
+    };
+    /** Enable streaming */
+    streaming?: boolean;
+    /** User metadata */
+    metadata?: Record<string, any>;
+    /** Abort signal for cancelling long-running operations (e.g., ESC key in CLI) */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Orchestrator Response
+ */
+export interface OrchestratorResponse {
+    /** UUID of response message */
+    messageId: string;
+    /** Response content */
+    content: string | any[];
+    /** Tool uses (if any) */
+    toolUses?: any[];
+    /** Token usage */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cache?: {
+            cacheCreationTokens: number;
+            cacheReadTokens: number;
+            uncachedInputTokens: number;
+            cacheHitRate: number;
+            costSavingsRatio: number;
+        };
+        /** xAI authoritative billed cost for the request (1 USD = 1e10 ticks). */
+        costUsdTicks?: number;
+        /** costUsdTicks / 1e10. */
+        costUsd?: number;
+        /** Server-side tool invocations xAI billed for this request. */
+        serverSideToolsUsed?: number;
+    };
+    /** Model used */
+    model: {
+        id: string;
+        provider: string;
+    };
+    /** Metadata */
+    metadata: {
+        conversationId: string;
+        usedHelperModel: boolean;
+        helperModelCost?: number;
+        compactionTriggered: boolean;
+        serverSideTools?: ServerSideToolMetadata;
+        turnSummary?: string;
+        nextActionPrediction?: string;
+    };
+}
+/**
+ * Stream Chunk
+ */
+/**
+ * Session
+ */
+export interface Session {
+    sessionId: string;
+    conversationId: string;
+    modelId: string;
+    projectPath: string;
+    createdAt: string;
+    lastActivityAt: string;
+    messageCount: number;
+}
+/**
+ * Model Switch Options
+ */
+export interface SwitchModelOptions {
+    /** Strategy for context adjustment if needed */
+    strategy?: 'sliding-window' | 'preserve-critical' | 'compact-and-fit';
+    /** Reason for switching (for timeline) */
+    reason?: string;
+}
+/**
+ * Model Switch Result
+ */
+export interface ModelSwitchResult {
+    success: boolean;
+    previousModel: string;
+    newModel: string;
+    contextAdjustment?: {
+        strategy: string;
+        messagesKept: number;
+        messagesDropped: number;
+        compactionTriggered: boolean;
+    };
+    timelineEventId: string;
+}
+/**
+ * Cortex Orchestrator - Phase 2.1
+ *
+ * Phase 2.0: Basic message flow [OK]
+ * Phase 2.1: Real API calls, gateway, model registry ⚙
+ * Phase 2.2: Timeline, compaction, checkpoints
+ * Phase 2.3: Historical retrieval
+ */
+export declare class CortexOrchestrator {
+    private adapterRegistry;
+    private gatewayTranslation;
+    private modelRegistry;
+    private modelAliasResolver;
+    private helperMiddleware;
+    private compactionManager;
+    private contextBudgetManager;
+    private historyStore;
+    private historicalService;
+    private executorRegistry;
+    private mcpConfigManager;
+    private mcpRegistry;
+    private mcpManager;
+    private apiClient;
+    private systemReminderInjector;
+    private systemMessageLoader;
+    private currentSessionId;
+    private currentConversationId;
+    private currentModelId;
+    private messageHistory;
+    private turnNumber;
+    private approvalMode;
+    private errorPatterns;
+    private currentToolTokens;
+    private currentStaticSystemPrompt?;
+    private staticSystemPromptByConversation;
+    private lastResponseId;
+    private lastResponseIdProvider;
+    private messageCountAtLastResponse;
+    private errorClassifier?;
+    private retryMiddleware?;
+    private permissionsMiddleware?;
+    private systemMessageMiddleware?;
+    private mentorshipMiddleware?;
+    private toolFilter;
+    private config;
+    private sessionTimeline?;
+    private checkpointManager?;
+    private fileCheckpointManager?;
+    private mcpAutoInject;
+    private cacheMetricsAccumulator;
+    private subAgentProcessManager?;
+    constructor(adapterRegistry: AdapterRegistry, gatewayTranslation: GatewayTranslationLayer, modelRegistry: ModularModelRegistry, modelAliasResolver: ModelAliasResolver, helperMiddleware: HelperModelMiddleware, compactionManager: StoredCompactionManager, contextBudgetManager: ContextBudgetManager, historyStore: JSONLHistoryStore, historicalService: HistoricalContextService, executorRegistry: ExecutorRegistry, mcpConfigManager: McpConfigManager, mcpRegistry: McpServerRegistry, mcpManager: McpClientManager | undefined, apiClient: APIClient, systemReminderInjector: SystemReminderInjector, systemMessageLoader: SystemMessageLoader, config: OrchestratorConfig, errorClassifier?: ErrorClassificationMiddleware, retryMiddleware?: RetryMiddleware, permissionsMiddleware?: PermissionsMiddleware, systemMessageMiddleware?: SystemMessageMiddleware, mentorshipMiddleware?: MentorshipMiddleware);
+    /**
+     * Send a message and get a response
+     *
+     * Phase 2.1: [OK] Real API calls via GatewayTranslationLayer
+     * Phase 2.2.1: [OK] Timeline tracking and history storage
+     * TODO Phase 2.2.3: Helper middleware fallback
+     * TODO Phase 2.2.4: Compaction integration
+     */
+    sendMessage(content: string | any[], options?: SendMessageOptions): Promise<OrchestratorResponse>;
+    /**
+     * Stream a message response with real-time chunks
+     *
+     * Phase 2.7: True Streaming Implementation
+     * - Yields chunks in real-time for UI updates
+     * - Uses SDK streaming (Anthropic MessageStream, OpenAI stream)
+     * - Gets final accumulated message from SDK
+     * - Uses EXISTING adapter conversion for final message
+     * - Saves to history using EXISTING flow
+     */
+    streamMessage(content: string | any[], options?: SendMessageOptions): AsyncGenerator<StreamChunk, void, unknown>;
+    /**
+     * Switch to a different model mid-conversation (Phase 2.2.1)
+     *
+     * Workflow:
+     * 1. Validate new model exists
+     * 2. Load current conversation history
+     * 3. Check if history fits in new model's context
+     * 4. Apply selection strategy if needed
+     * 5. Record model_switch event in timeline
+     * 6. Update current model
+     */
+    switchModel(newModelId: string, options?: SwitchModelOptions): Promise<ModelSwitchResult>;
+    /**
+     * Get current model configuration
+     */
+    getCurrentModel(): ModelConfig;
+    /**
+     * Get current model ID string
+     */
+    getCurrentModelId(): string;
+    /**
+     * List all available models
+     */
+    listAvailableModels(): ModelConfig[];
+    /**
+     * List all base tool definitions (canonical names, schemas, categories).
+     * Surfaces the existing tools from the factory — does not create new ones.
+     */
+    getToolDefinitions(): ReturnType<typeof toolFactory.getAllTools>;
+    /**
+     * Normalize a tool name for whitelist matching: lowercase + strip non-
+     * alphanumerics so PascalCase canonical names match the lower/snake_case
+     * names used in agent definitions (e.g. `WebSearch` ≡ `web_search`).
+     */
+    private static normalizeToolName;
+    /**
+     * Apply `config.allowedBaseTools` to the factory/base tool list. Returns the
+     * list unchanged when no allowlist is configured. MCP/management/context
+     * tools are filtered elsewhere — never here — so an allowlisted sub-agent
+     * still receives its injected MCP tools on top of its base whitelist.
+     */
+    private applyBaseToolAllowlist;
+    /**
+     * Get adapter registry (for advanced use cases)
+     */
+    getAdapterRegistry(): AdapterRegistry;
+    /**
+     * Get resolved loop control configuration with unified defaults.
+     * Single source of truth for both streaming and non-streaming paths.
+     */
+    getLoopControlConfig(): {
+        maxToolIterations: number;
+        maxConsecutiveErrors: number;
+        toolBudgetSoft: number;
+        toolTimeoutMs: number;
+        maxLoopRepetitions: number;
+    };
+    getDiversityWarning(toolCallCounts: Map<string, number>): string | null;
+    isMutationTool(toolName: string): boolean;
+    /**
+     * Get historical context service (Phase 2.2.5)
+     *
+     * Advanced users can access historical tools directly
+     */
+    getHistoricalService(): HistoricalContextService;
+    /**
+     * Create a new session (Phase 2.2.1 - with Timeline)
+     */
+    createSession(projectPath: string, initialModelId?: string): Promise<Session>;
+    /**
+     * Get current session ID
+     */
+    getSessionId(): string;
+    /**
+     * Get current conversation ID
+     */
+    getConversationId(): string;
+    /**
+     * Get message history
+     */
+    getMessageHistory(): Message[];
+    /**
+     * Resume an existing session by loading its full history
+     *
+     * @param sessionId - Session ID to resume
+     * @param projectPath - Project path for the session
+     */
+    resumeSession(sessionId: string, projectPath: string): Promise<Session>;
+    /**
+     * Create a checkpoint at the current conversation position
+     *
+     * Phase 2.2.4: User-created checkpoints with resume capability
+     *
+     * @param options - Checkpoint options (description, file states, metadata)
+     * @returns Created checkpoint
+     */
+    createCheckpoint(options?: CheckpointOptions): Promise<Checkpoint>;
+    /**
+     * Resume from a checkpoint (creates new conversation branch)
+     *
+     * Phase 2.2.4: Cross-provider resume and conversation branching
+     *
+     * @param checkpointId - ID of checkpoint to resume from
+     * @param options - Resume options (model ID, preserve history)
+     * @returns Resume result with new conversation and messages
+     */
+    resumeFromCheckpoint(checkpointId: string, options?: ResumeOptions): Promise<{
+        conversationId: string;
+        messageCount: number;
+        model: string;
+    }>;
+    /**
+     * List all checkpoints for current session
+     *
+     * Phase 2.2.4: Checkpoint browsing
+     */
+    listCheckpoints(): Checkpoint[];
+    /**
+     * Get a specific checkpoint by ID
+     *
+     * Phase 2.2.4: Checkpoint retrieval
+     */
+    getCheckpoint(checkpointId: string): Checkpoint | undefined;
+    /**
+     * Get MCP client manager
+     *
+     * Phase 2.9: Access to MCP functionality
+     * Consumers (like tool executors) can use this to access MCP servers
+     */
+    getMcpManager(): McpClientManager | undefined;
+    /**
+     * Check if MCP is enabled
+     *
+     * Phase 2.9: MCP status check
+     */
+    isMcpEnabled(): boolean;
+    /**
+     * Get MCP server info
+     *
+     * Phase 2.9: MCP server status
+     */
+    getMcpServerInfo(): Array<{
+        name: string;
+        status: string;
+        toolCount: number;
+        resourceCount: number;
+    }>;
+    /**
+     * Get discovered MCP tool declarations
+     *
+     * Returns all tools discovered from MCP servers with their metadata.
+     * Consumers should wrap these in DiscoveredMcpToolExecutor instances
+     * and register them with the ToolRegistry.
+     *
+     * Phase 2.9: Dynamic MCP tool registration
+     */
+    getMcpToolDeclarations(): Array<{
+        serverName: string;
+        toolName: string;
+        description: string;
+        inputSchema: any;
+    }>;
+    /**
+     * Cleanup orchestrator resources
+     *
+     * Phase 2.9: Proper cleanup including MCP connections
+     * Should be called when shutting down or destroying the orchestrator
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Get MCP config manager (for model tools to use)
+     */
+    getMcpConfigManager(): McpConfigManager;
+    /**
+     * Get MCP server registry (for model tools to use)
+     */
+    getMcpServerRegistry(): McpServerRegistry;
+    /**
+     * Check if MCP auto-injection is enabled
+     */
+    isMcpAutoInjectEnabled(): boolean;
+    /**
+     * Get MCP tools as CanonicalTools (public getter)
+     */
+    getMcpTools(): any[];
+    /**
+     * Get cache performance metrics for current session
+     *
+     * @returns Session cache metrics including hit rate and cost savings
+     */
+    getCacheMetrics(): import("../session/CacheMetricsAccumulator.js").SessionCacheMetrics;
+    /**
+     * Get formatted cache performance report
+     *
+     * @returns Human-readable text report of cache performance
+     */
+    getCacheReport(): string;
+    /**
+     * Reset cache metrics (useful when starting new session)
+     */
+    resetCacheMetrics(): void;
+    /**
+     * Persist cache metrics to session metadata file
+     * Called after each API request to preserve metrics across restarts.
+     *
+     * @param effectiveModelId The model that actually produced the response (may differ
+     *   from this.currentModelId when the caller passed options.modelId to override for
+     *   a single request). The chain modelId must match the model that generated
+     *   lastResponseId — otherwise chain-break-on-model-switch logic reads the wrong id
+     *   on resume. Falls back to this.currentModelId when not provided (legacy callers).
+     */
+    private persistCacheMetrics;
+    /**
+     * Ensure message history fits within model's context window
+     *
+     * Proactively manages context size BEFORE sending API requests to prevent
+     * exponential growth and context limit errors. Uses the canonical history
+     * architecture's built-in compaction infrastructure.
+     *
+     * Design principle: compaction first, windowing last. The system exhausts
+     * helper-model compaction before falling back to sliding-window truncation
+     * of oldest messages. Retained content leverages prompt caching to minimize
+     * re-processing costs.
+     *
+     * Phase 1: Core Protection
+     * - Monitors token count before each API request
+     * - Triggers compaction when approaching context limits
+     * - Uses ContextBudgetManager for message selection
+     * - Preserves critical messages (tool calls, recent context)
+     */
+    private ensureHistoryFitsModel;
+    /**
+     * Process tool result to handle large outputs intelligently
+     *
+     * Two-tier strategy:
+     * 1. First large output: Reject with guidance (encourages better approach)
+     * 2. Subsequent or unavoidable: Truncate and continue
+     *
+     * This guides the model to use more targeted commands while providing
+     * fallback protection for cases where truncation is necessary.
+     */
+    private processToolResult;
+    /**
+     * Smart truncation for tool outputs
+     * Keeps first 60% and last 40% with clear truncation marker
+     */
+    private truncateToolOutput;
+    /**
+     * Initialize MCP from MCP_CONFIG.md discovery
+     *
+     * Phase 2.5 Day 4.5: Config-based opt-in auto-injection
+     */
+    private initializeMcpFromConfig;
+    /**
+     * Handle tool calls by executing them through ExecutorRegistry
+     *
+     * Phase 2.5: Tool execution integration
+     *
+     * @param toolUseBlocks Array of tool_use content blocks from model response
+     * @param signal AbortSignal for cancellation
+     * @returns Array of tool results
+     */
+    private handleToolCalls;
+    /**
+     * Execute a single tool call - extracted for parallel execution support
+     *
+     * @param toolUse The tool use block to execute
+     * @param signal AbortSignal for cancellation
+     * @returns Single tool result
+     */
+    /**
+     * Training-aware wrapper around executeSingleToolCall. Looks up priors
+     * for the same (toolName, input) and prepends a system-reminder when
+     * relevant; records the outcome to the decision store afterwards. Both
+     * sides are individually env-gated and never block tool execution.
+     */
+    private executeSingleToolCallWithTraining;
+    private executeSingleToolCall;
+    /**
+     * Determine if an error is retryable
+     *
+     * Phase 2.5 Day 3: Error classification for retry logic
+     *
+     * @param error The error to check
+     * @returns true if the error is transient and should be retried
+     */
+    private isRetryableError;
+    /**
+     * Convert MCP tools to CanonicalTool format
+     *
+     * Phase 2.5 Day 4: MCP tool integration
+     *
+     * @returns Array of CanonicalTools from MCP servers
+     */
+    private getMcpToolsAsCanonical;
+    /**
+     * Get MCP management tools as CanonicalTools
+     *
+     * Phase 2.6: MCP Model Management Tools
+     *
+     * These tools allow models to discover, enable, configure, and manage MCP servers autonomously.
+     *
+     * @returns Array of MCP management tools
+     */
+    private getMcpManagementTools;
+    /**
+     * Get context management tools
+     *
+     * These tools allow models to generate and manage project context (CORTEX.md).
+     *
+     * @returns Array of context management tools
+     */
+    private getContextManagementTools;
+    /**
+     * Get or create SubAgentProcessManager instance
+     *
+     * Lazy initialization pattern - only creates manager when first Task tool is executed.
+     * This avoids overhead for sessions that don't use sub-agents.
+     *
+     * Sub-agents run as independent child processes:
+     * - True parallelism (multiple agents can run simultaneously)
+     * - Independent context windows (don't consume parent's context)
+     * - Process isolation (crashes don't affect parent)
+     *
+     * @returns SubAgentProcessManager instance
+     */
+    /**
+     * Inject team briefing into parallel Task tool calls.
+     *
+     * When multiple Task tools are dispatched in parallel, each agent benefits from
+     * knowing about its teammates. This method enriches each Task tool's prompt with
+     * a briefing section listing all parallel assignments.
+     *
+     * @param taskTools Array of Task tool_use blocks being dispatched in parallel
+     * @returns The same array with enriched prompts
+     */
+    private injectTeamBriefing;
+    private getOrCreateSubAgentProcessManager;
+    /**
+     * Set up real-time progress listeners for sub-agent events
+     *
+     * Subscribes to events from the SubAgentProcessManager and either:
+     * - Calls the onSubAgentEvent callback (for UI integration like NeonCortex)
+     * - Falls back to console.log (for FuzzyCortex/chalk CLI)
+     *
+     * @param eventEmitter SubAgent event emitter
+     * @param agentName Name of the agent for display
+     * @returns Object with cleanup function to remove listeners
+     */
+    private setupSubAgentProgressListeners;
+    /**
+     * Summarize tool input for display (keep it short)
+     */
+    private summarizeToolInput;
+    /**
+     * Format SubAgentResult for LLM consumption
+     *
+     * Fire-and-forget: generate a session title from the first user message
+     * and persist it in the session .meta.json.
+     */
+    private generateAndSaveSessionTitle;
+    /**
+     * Converts the structured SubAgentResult into a format suitable for the tool result.
+     *
+     * @param result SubAgentResult from completed sub-agent
+     * @returns Formatted string for LLM
+     */
+    private formatSubAgentResultForLLM;
+    /**
+     * Check if a tool is an MCP tool by name
+     *
+     * Phase 2.5 Day 4: MCP tool detection
+     *
+     * @param toolName Name of the tool
+     * @returns ServerName if it's an MCP tool, undefined otherwise
+     */
+    private getMcpServerForTool;
+    /**
+     * Resolve the raw (un-prefixed) tool name for an MCP tool reference. The
+     * input may be either `<serverName>__<rawName>` (preferred) or the raw
+     * name (back-compat). Returns the raw name suitable for `mcpManager.callTool`.
+     */
+    private getRawMcpToolName;
+    private decisionStore;
+    private routerMatrix;
+    private getRouterMatrix;
+    private getDecisionStore;
+    private isRecordingEnabled;
+    private isLookupEnabled;
+    /**
+     * Apply lookup-before-action training: prepend a <system-reminder> with
+     * prior decision context (only when there are prior failures for this
+     * exact tool+input) and record the current outcome.
+     *
+     * Returns the (possibly-augmented) result. Failures in the store path
+     * are swallowed so training never breaks tool execution.
+     */
+    private processToolTraining;
+    /**
+     * Inject thinking block into message history
+     *
+     * Reactive Mentorship: Phase 1 - Thinking Block Injection
+     *
+     * Creates a synthetic thinking block message from helper model guidance
+     */
+    private injectThinkingBlock;
+    /**
+     * Inject guidance from the orchestrator or a sibling agent into the conversation.
+     *
+     * Reuses the same dual-path as injectThinkingBlock():
+     * - For thinking-capable APIs (Google GenerateContent): thinking block
+     * - For all others: <system-reminder> text
+     *
+     * The guidance is ephemeral — cleaned up after the current turn via cleanupEphemeralMessages().
+     * This is the public API for cross-agent communication (team updates, guidance forwarding).
+     *
+     * @param text The guidance text to inject
+     * @param source Label for the guidance source (e.g., 'team_update', 'guidance')
+     */
+    injectGuidance(text: string, source?: 'team_update' | 'guidance'): void;
+    /**
+     * Remove ephemeral mentorship messages from in-memory history after a turn completes.
+     *
+     * Mentorship thinking blocks are injected during the tool loop so the model sees them
+     * in API calls, but they should NOT persist across turns because:
+     * 1. Old guidance is stale (reflects on previous tool results)
+     * 2. Accumulation pollutes context budget
+     * 3. Changing content in mid-history breaks prompt cache prefix stability
+     *
+     * These messages were never written to JSONL (injectThinkingBlock skips appendMessage),
+     * so this cleanup just removes them from the in-memory array.
+     */
+    private cleanupEphemeralMessages;
+    /**
+     * Detect mentorship keywords in user message
+     *
+     * Reactive Mentorship: Phase 1 - Keyword Detection
+     */
+    private detectMentorshipKeyword;
+    /**
+     * Remove keyword from content
+     *
+     * Reactive Mentorship: Phase 1 - Keyword Removal
+     */
+    private removeKeyword;
+    /**
+     * Check if periodic review should trigger (Phase 2)
+     */
+    private shouldTriggerPeriodicReview;
+    /**
+     * Handle periodic review (Phase 2)
+     */
+    private handlePeriodicReview;
+    /**
+     * Track error pattern for pattern detection (Phase 2)
+     */
+    private trackErrorPattern;
+    /**
+     * Extract error pattern from error message
+     */
+    private extractErrorPattern;
+    /**
+     * Check if pattern detection should trigger (Phase 2)
+     */
+    private shouldTriggerPatternDetection;
+    /**
+     * Handle pattern detection (Phase 2)
+     */
+    private handlePatternDetection;
+    /**
+     * Check if interleaved thinking should be provided (Phase 2)
+     */
+    private shouldUseInterleavedThinking;
+    /**
+     * Handle interleaved thinking (Phase 2)
+     */
+    private handleInterleavedThinking;
+    /**
+     * Extract file paths from Read tool results in message history
+     * Used by Active Discovery to know what files have been read
+     */
+    private extractFilesReadFromHistory;
+    /**
+     * Get model by ID (Phase 2.1 - Real ModelRegistry)
+     */
+    private getModel;
+    /**
+     * Validate and repair canonical messages for API consistency
+     *
+     * Claude API requires every tool_use block to have a corresponding tool_result
+     * in the immediately following message. This can break if a crash occurs between
+     * saving the assistant message and saving the tool_result.
+     *
+     * This method adds synthetic error tool_results for any orphaned tool_use blocks.
+     */
+    private validateAndRepairMessages;
+    /**
+     * Round 5 (parallel-bench output): per-uuid canonical conversion cache.
+     *
+     * `convertToCanonicalMessages` runs from 4 call sites (sendMessage initial,
+     * sendMessage continuation, streamMessage initial, streamMessage
+     * continuation), each pass rebuilding canonical blocks for every message
+     * in history. Messages 0..N-2 are immutable (persisted append-only JSONL,
+     * uuid-keyed) — their canonical form never changes, so we cache by uuid.
+     *
+     * The LAST message (N-1) is intentionally excluded from the cache. Three
+     * reasons:
+     *   1. Last message can be substituted with an injected-content variant
+     *      (see `userMessageForApi`) carrying per-turn `cache_control` markers
+     *      that differ from the persisted message.
+     *   2. Budget/diversity signals are appended in-place to the trailing
+     *      tool_result block between tool iterations.
+     *   3. The orphan-repair pass below may mutate content when it prepends
+     *      synthetic tool_results.
+     *
+     * Repair always runs on the merged array — never cached past repair, since
+     * orphan detection needs full-history visibility.
+     */
+    private canonicalConversionCache;
+    /**
+     * Convert Message[] to CanonicalMessage[]
+     *
+     * Also validates and repairs the message history to handle crash recovery scenarios
+     * where tool_use blocks might be orphaned without matching tool_results.
+     */
+    private convertToCanonicalMessages;
+    /**
+     * Pure conversion of a single Message to its CanonicalMessage form.
+     * Extracted from the original `.map(...)` body so both the cache hit/miss
+     * paths and the always-recompute tail path call the same code.
+     */
+    private convertSingleMessage;
+    /**
+     * Get current approval mode settings
+     *
+     * @returns Current approval mode configuration
+     */
+    getApprovalMode(): {
+        autoApproveActions: boolean;
+    };
+    /**
+     * Set approval mode for session
+     *
+     * @param mode - Approval mode configuration
+     */
+    setApprovalMode(mode: {
+        autoApproveActions: boolean;
+    }): void;
+    /**
+     * Enable YOLO mode - auto-approve ALL operations (white/gray/blacklist)
+     *
+     * WARNING: This bypasses all security checks. Use with caution.
+     */
+    enableYoloMode(): Promise<void>;
+    /**
+     * Disable YOLO mode - return to interactive approval
+     */
+    disableYoloMode(): Promise<void>;
+    /**
+     * Check if YOLO mode is active
+     */
+    isYoloModeActive(): boolean;
+    updateRuntimeConfig(updates: Partial<Pick<OrchestratorConfig, 'debug' | 'autoCompact' | 'useHelperModels' | 'reactiveMentorship' | 'loopControl' | 'modelRouter'>>): void;
+    /**
+     * Set a custom approval handler for tool permissions
+     *
+     * This allows UI frameworks (like React/Ink) to provide their own
+     * approval dialog implementation instead of using the default CLI handler.
+     *
+     * @param handler - Custom ApprovalHandler implementation
+     */
+    setApprovalHandler(handler: ApprovalHandler): void;
+    /**
+     * Get the current approval handler
+     */
+    getApprovalHandler(): ApprovalHandler | undefined;
+    /**
+     * Set sub-agent event callback for real-time UI updates.
+     * This allows UI frameworks (like React/Ink) to display sub-agent progress.
+     *
+     * @param callback - Function to receive sub-agent events
+     */
+    setSubAgentEventCallback(callback: SubAgentEventCallback): void;
+    /**
+     * Get all registered permission policies
+     *
+     * @returns Array of registered policies
+     */
+    getPolicies(): ReadonlyArray<PermissionPolicy>;
+    /**
+     * Get audit log for current session or specific session
+     *
+     * @param sessionId - Optional session ID (defaults to current session)
+     * @returns Array of audit entries
+     */
+    getAuditLog(sessionId?: string): PermissionAuditEntry[];
+    /**
+     * Get audit statistics
+     *
+     * @returns Audit statistics or null if not available
+     */
+    getAuditStatistics(): Promise<{
+        totalEntries: number;
+        allowedCount: number;
+        deniedCount: number;
+        approvalRequestCount: number;
+        approvalGrantedCount: number;
+        uniqueSessions: number;
+        uniqueTools: Set<string>;
+    } | null>;
+    /**
+     * Get all denied operations across all sessions
+     *
+     * @returns Array of denied operations
+     */
+    getAllDeniedOperations(): Promise<PermissionAuditEntry[]>;
+    /**
+     * Register a new permission policy
+     *
+     * @param policy - Policy to register
+     */
+    registerPolicy(policy: PermissionPolicy): void;
+    /**
+     * Unregister a permission policy
+     *
+     * @param policyName - Name of policy to unregister
+     * @returns True if policy was found and removed
+     */
+    unregisterPolicy(policyName: string): boolean;
+    /**
+     * Inject the per-turn "Repository State" harness-note (git branch / uncommitted
+     * changes / recent commits + cross-agent staleness). Fires EVERY turn (git
+     * state is turn-varying), unlike the turn-0-only MCP/command announcements.
+     * Cache-safe: unshifted into the ephemeral user-turn content (uncached tail).
+     */
+    private injectRepoStateNote;
+    /**
+     * Inject the PM delegation hint for the auto-research subagent feature
+     * (AUTORESEARCH_AGENTS). No-op when off or inside a subagent — the injector gates it.
+     * Keeps the main model a clean PM: it learns it can delegate, not the tool surface.
+     */
+    private injectAutoResearchCapability;
+    private buildDeferredToolAnnouncement;
+}
+//# sourceMappingURL=CortexOrchestrator.d.ts.map