@nexus-cortex/core 4.84.0 → 4.86.0

package/dist/orchestrator/CortexOrchestrator.js

@@ -30,7 +30,7 @@ import { CacheMetricsAccumulator } from '../session/CacheMetricsAccumulator.js';
 import { SubAgentProcessManager, createSubAgentProcessManager } from './SubAgentProcessManager.js';
 // Phase 1: Tool Architecture Refactor - Unified Tool Registry
 import { toolFactory } from '../tools/ToolFactory.js';
-import { resolveToolProfile, resolveToolAnchor, resolveFrameProfile, isNarrowProfile, isToolAllowedByProfile, applyToolProfile } from '../tools/ToolProfile.js';
+import { resolveToolProfile, resolveToolAnchor, resolveFrameProfile, resolveLiftNudge, resolveHeadlessDropAskUser, resolveDeferredLoading, isNarrowProfile, isToolAllowedByProfile, applyToolProfile } from '../tools/ToolProfile.js';
 import { readStagedDoctrine, applyCuratedDoctrine, runOrientForStaging, withTimeout } from './doctrineCuration.js';
 import { ExactRepeatTracker } from '../training/loopLadder.js';
 import { slashCommandRegistry } from '../commands/SlashCommandRegistry.js';
@@ -163,6 +163,7 @@ export class CortexOrchestrator {
      *  exactly once, at the anchor-lift boundary. One-shot per orchestrator. */
     deferredCorpusDelivered = false;
     liftNudgeDelivered = false; // A′ proposal-1: lift-boundary SearchTools/AskForAdvice nudge, one-shot
+    effectiveDeferredLoading = true; // per-turn resolved deferred-loading (card > env > settings); set at assembly
     /**
      * Item 10 — helper-curated doctrine freshness (operator-designed; docs/
      * HARNESS_IMPROVEMENT_BACKLOG.md). SYNCHRONOUS-BY-BOUNDARY: under defer the
@@ -272,11 +273,6 @@ export class CortexOrchestrator {
             console.warn(`[Anchor] deferred corpus delivery failed (continuing without): ${e?.message ?? e}`);
         }
     }
-    /** Truthy check for a raw env flag (mirrors the CORTEX_PROMPT_MASS parse idiom). */
-    envOn(v) {
-        const s = (v ?? '').trim().toLowerCase();
-        return s === '1' || s === 'true' || s === 'yes' || s === 'on';
-    }
     /** A′ proposal-2: in a NON-INTERACTIVE session (stateless /v1/messages, headless
      *  API, piped oneshot) there is no human to answer AskUserQuestion — it becomes a
      *  stall trap. When CORTEX_HEADLESS_DROP_ASKUSER is truthy AND the session is
@@ -284,9 +280,9 @@ export class CortexOrchestrator {
      *  (deferred filter, anchor, lift rebuild, re-filter) excludes it. Kept in
      *  interactive TUIs (a real user can answer). Headless swaps the human-ask for the
      *  model-ask (AskForAdvice, which the lift nudge signposts). Gated + idempotent. */
-    stripHeadlessOnlyTools(tools) {
-        if (!this.envOn(process.env.CORTEX_HEADLESS_DROP_ASKUSER))
-            return tools;
+    stripHeadlessOnlyTools(tools, model) {
+        if (!resolveHeadlessDropAskUser(process.env, model?.headlessDropAskUser))
+            return tools; // card > env > false
         if (!this.approvalMode.autoApproveActions)
             return tools; // interactive: keep it
         return tools.filter((t) => t.name !== 'AskUserQuestion');
@@ -299,12 +295,12 @@ export class CortexOrchestrator {
      *  AFTER the model has committed to acting (post-lift is where prompt mass is safe —
      *  this is a one-line signpost, NOT defer's full corpus). Fires at most once.
      *  Mirrors deliverDeferredCorpusAtLift's append-to-last-tool_result mechanism. */
-    deliverLiftNudge(allTools) {
+    deliverLiftNudge(allTools, model) {
         if (this.liftNudgeDelivered)
             return;
-        if (!this.envOn(process.env.CORTEX_LIFT_NUDGE))
-            return;
-        if (!this.config.enableDeferredToolLoading)
+        if (!resolveLiftNudge(process.env, model?.liftNudge))
+            return; // card > env > false
+        if (!this.effectiveDeferredLoading)
             return; // deferred off ⇒ no hidden tools to point at
         this.liftNudgeDelivered = true; // one-shot even if assembly fails
         try {
@@ -441,7 +437,7 @@ export class CortexOrchestrator {
         // The closure captures `this` so it resolves the active model's naming
         // convention at call-time — names in SearchTools results match the tools
         // array the model sees (e.g. snake_case for XAI, PascalCase for Anthropic).
-        if (this.config.enableDeferredToolLoading) {
+        if (this.config.enableDeferredToolLoading) { // constructor setup — base capability, not per-turn
             const searchExecutor = this.executorRegistry.getExecutor('SearchTools');
             if (searchExecutor && typeof searchExecutor.setToolProvider === 'function') {
                 const namingHandler = new ToolNamingHandler();
@@ -480,7 +476,7 @@ export class CortexOrchestrator {
             console.log(`[Orchestrator] Dependency injection pattern - all components injected`);
             console.log(`[Orchestrator] ExecutorRegistry: ${this.executorRegistry.getExecutorCount()} executors`);
             console.log(`[Orchestrator] MCP enabled: ${mcpManager !== null}`);
-            if (this.config.enableDeferredToolLoading) {
+            if (this.config.enableDeferredToolLoading) { // constructor debug log
                 console.log(`[Orchestrator] Deferred tool loading: ENABLED`);
             }
         }
@@ -613,11 +609,16 @@ export class CortexOrchestrator {
         const mcpTools = this.mcpAutoInject && !bashOnlyProfile ? this.getMcpToolsAsCanonical() : [];
         const mcpManagementTools = bashOnlyProfile ? [] : this.getMcpManagementTools();
         const contextManagementTools = bashOnlyProfile ? [] : this.getContextManagementTools();
+        // Per-model deferred-loading resolved ONCE per turn (card > env > settings), so every per-request
+        // deferred gate below flips together — this is what makes the pro card's deferredToolLoading:false
+        // toggle (or a global env) coherent instead of split-brain. Constructor SearchTools wiring keeps
+        // this.config (base capability, pre-turn).
+        this.effectiveDeferredLoading = resolveDeferredLoading(process.env, model?.deferredToolLoading, this.config.enableDeferredToolLoading);
         // Include all default tools by default, or custom tools if provided
         // A′ proposal-2: strip AskUserQuestion in non-interactive sessions (gated) at the source.
         const allTools = this.stripHeadlessOnlyTools(options.tools !== undefined
             ? [...factoryTools, ...mcpTools, ...mcpManagementTools, ...contextManagementTools, ...options.tools]
-            : [...factoryTools, ...mcpTools, ...mcpManagementTools, ...contextManagementTools]);
+            : [...factoryTools, ...mcpTools, ...mcpManagementTools, ...contextManagementTools], model);
         // Phase 2.3: Inject server-side tools when enabled and model supports them
         // R20: provider-aware — XAI gets web/x/code; OpenAI gets web/code/file/image
         // (Responses API hosted tools); other providers stay client-only.
@@ -726,7 +727,7 @@ export class CortexOrchestrator {
         }
         // Deferred tool loading: categorized announcement with descriptions so
         // the model can match user intent to tool names without needing full schemas.
-        if (this.config.enableDeferredToolLoading && Array.isArray(injectedContent)) {
+        if (this.effectiveDeferredLoading && Array.isArray(injectedContent)) {
             const convention = model.tools?.namingConvention || 'PascalCase';
             const announcement = this.buildDeferredToolAnnouncement(convention);
             if (announcement) {
@@ -850,7 +851,7 @@ export class CortexOrchestrator {
         // Check if PTC should be used for this request
         const isPTCEnabled = this.config.enablePTC && effectiveModel.supportsPTC && effectiveModel.provider === 'anthropic';
         // Deferred loading: filter tools for non-PTC paths (essential + recently-used only)
-        if (!isPTCEnabled && this.config.enableDeferredToolLoading && toolsToUse && toolsToUse.length > 0) {
+        if (!isPTCEnabled && this.effectiveDeferredLoading && toolsToUse && toolsToUse.length > 0) {
             toolsToUse = this.toolFilter.getFilteredTools(toolsToUse);
         }
         // First-turn anchoring narrows further while armed (no-op once lifted).
@@ -861,7 +862,7 @@ export class CortexOrchestrator {
         // Thread the CARD's anchor to the executors (per-orchestrator config, by
         // reference) so framing-aware executor behavior (ShellTool steering
         // default) is model-card/registry-scoped, not process-global env.
-        this.executorRegistry.updateConfig({ activeAnchorProfile: this.cardAnchorProfile });
+        this.executorRegistry.updateConfig({ activeAnchorProfile: this.cardAnchorProfile, allowCommandSubstitution: this.approvalMode.autoApproveActions });
         if (toolsToUse && toolsToUse.length > 0) {
             toolsToUse = this.applyAnchorIfArmed(toolsToUse);
         }
@@ -886,7 +887,7 @@ export class CortexOrchestrator {
         // Reset sequential call counter at start of each user turn
         this.mentorshipMiddleware?.resetSequentialCalls(this.currentSessionId);
         // §13-B2: force AskForAdvice this turn on high-confidence thrash (mentor-force armed).
-        const forcedMentorChoice = await this.resolveForcedMentorChoice(toolsToUse);
+        const forcedMentorChoice = await this.resolveForcedMentorChoice(toolsToUse, 0); // initial request: 0 tool calls yet
         const preparedRequest = this.gatewayTranslation.prepareRequest(canonicalHistory, toolsToUse, effectiveModel, {
             temperature: options.parameters?.temperature,
             maxTokens: options.parameters?.maxTokens,
@@ -2116,7 +2117,7 @@ export class CortexOrchestrator {
                         // Mark this tool_use_id as processed
                         processedToolUseIds.add(toolResult.tool_use_id);
                         // Progressive filter: record tool use for deferred loading
-                        if (this.config.enableDeferredToolLoading) {
+                        if (this.effectiveDeferredLoading) {
                             this.toolFilter.recordToolUse(toolResult.tool_name);
                             // Record discovered tools from SearchTools results
                             if (toolResult.tool_name === 'SearchTools' && !toolResult.is_error) {
@@ -2307,7 +2308,7 @@ export class CortexOrchestrator {
                         // surface — never lift, never deliver the deferred corpus.
                         resolveFrameProfile(process.env, this.cardFrameProfile) !== 'persist') {
                         this.anchorLifted = true;
-                        if (!(this.config.enableDeferredToolLoading && !isPTCEnabled)) {
+                        if (!(this.effectiveDeferredLoading && !isPTCEnabled)) {
                             toolsToUse = allTools;
                             if (structuredOutputState) {
                                 toolsToUse = ensureStructuredOutputTool(toolsToUse, structuredOutputState);
@@ -2316,13 +2317,13 @@ export class CortexOrchestrator {
                         // P6 deferral: the static corpus arrives at the same boundary as the
                         // full tool catalog (no-op unless CORTEX_PROMPT_MASS=defer).
                         await this.deliverDeferredCorpusAtLift(effectiveModel);
-                        this.deliverLiftNudge(allTools); // A′ proposal-1: SearchTools/AskForAdvice signpost at lift
+                        this.deliverLiftNudge(allTools, effectiveModel); // A′ proposal-1: SearchTools/AskForAdvice signpost at lift
                         if (this.config.debug)
                             console.log('[Anchor] lifted at first tool_result boundary — session profile applies');
                     }
                     // Re-filter tools after SearchTools discovery so newly discovered tools
                     // are included in the continuation request's tools array
-                    if (this.config.enableDeferredToolLoading && !isPTCEnabled) {
+                    if (this.effectiveDeferredLoading && !isPTCEnabled) {
                         const beforeCount = toolsToUse.length;
                         toolsToUse = this.toolFilter.getFilteredTools(allTools);
                         // StructuredOutput: the re-filter rebuilds from allTools (which never
@@ -2347,6 +2348,10 @@ export class CortexOrchestrator {
                         ? this.messageHistory.slice(this.messageCountAtLastResponse)
                         : this.messageHistory;
                     const continuationCanonicalHistory = this.convertToCanonicalMessages([...continuationHistorySource]);
+                    // §13-B2: re-evaluate the forced mentor choice on THIS continuation — thrash develops HERE
+                    // (turnNumber ≥ 1 with accumulating failing outcomes), NOT on the initial request (turnNumber 0
+                    // where the window is empty). Attaching it only to the initial assembly made the force unreachable.
+                    const continuationForcedChoice = await this.resolveForcedMentorChoice(toolsToUse, toolCallIteration);
                     const continuationRequest = this.gatewayTranslation.prepareRequest(continuationCanonicalHistory, toolsToUse, effectiveModel, {
                         temperature: options.parameters?.temperature,
                         maxTokens: options.parameters?.maxTokens,
@@ -2354,7 +2359,8 @@ export class CortexOrchestrator {
                         reasoningEffort: options.parameters?.reasoningEffort, // GPT-5.1 reasoning level
                         stream: options.streaming,
                         staticSystemPrompt: this.currentStaticSystemPrompt, // R28
-                        conversationId: this.currentConversationId // R28b
+                        conversationId: this.currentConversationId, // R28b
+                        toolChoice: continuationForcedChoice // §13-B2 forced mentor tool_choice (continuation)
                     });
                     // Stateful Responses API: chain with previous_response_id for server-side reasoning preservation
                     if (this.lastResponseId && effectiveModel.api.pattern === 'responses') {
@@ -2919,10 +2925,12 @@ export class CortexOrchestrator {
         const mcpTools = this.mcpAutoInject && !bashOnlyProfile2 ? this.getMcpToolsAsCanonical() : [];
         const mcpManagementTools = bashOnlyProfile2 ? [] : this.getMcpManagementTools();
         const contextManagementTools = bashOnlyProfile2 ? [] : this.getContextManagementTools();
+        // Per-model deferred-loading resolved once per turn (card > env > settings) — streaming mirror.
+        this.effectiveDeferredLoading = resolveDeferredLoading(process.env, model?.deferredToolLoading, this.config.enableDeferredToolLoading);
         // A′ proposal-2: strip AskUserQuestion in non-interactive sessions (gated) at the source.
         const allTools = this.stripHeadlessOnlyTools(options.tools !== undefined
             ? [...factoryTools, ...mcpTools, ...mcpManagementTools, ...contextManagementTools, ...options.tools]
-            : [...factoryTools, ...mcpTools, ...mcpManagementTools, ...contextManagementTools]);
+            : [...factoryTools, ...mcpTools, ...mcpManagementTools, ...contextManagementTools], model);
         // Phase 2.3: Inject server-side tools when enabled and model supports them
         // R20: provider-aware (streaming path mirror of non-streaming injection above).
         if (isServerSideToolsEnabled() && modelSupportsServerSideTools(model)) {
@@ -3019,7 +3027,7 @@ export class CortexOrchestrator {
         }
         // Deferred tool loading: categorized announcement with descriptions so
         // the model can match user intent to tool names without needing full schemas.
-        if (this.config.enableDeferredToolLoading && Array.isArray(injectedContent)) {
+        if (this.effectiveDeferredLoading && Array.isArray(injectedContent)) {
             const convention = model.tools?.namingConvention || 'PascalCase';
             const announcement = this.buildDeferredToolAnnouncement(convention);
             if (announcement) {
@@ -3097,7 +3105,7 @@ export class CortexOrchestrator {
         // Check if PTC should be used for this request (streaming)
         const isPTCEnabled = this.config.enablePTC && effectiveModel.supportsPTC && effectiveModel.provider === 'anthropic';
         // Deferred loading: filter tools for non-PTC paths (essential + recently-used only)
-        if (!isPTCEnabled && this.config.enableDeferredToolLoading && toolsToUse && toolsToUse.length > 0) {
+        if (!isPTCEnabled && this.effectiveDeferredLoading && toolsToUse && toolsToUse.length > 0) {
             toolsToUse = this.toolFilter.getFilteredTools(toolsToUse);
         }
         // First-turn anchoring narrows further while armed (no-op once lifted).
@@ -3108,7 +3116,7 @@ export class CortexOrchestrator {
         // Thread the CARD's anchor to the executors (per-orchestrator config, by
         // reference) so framing-aware executor behavior (ShellTool steering
         // default) is model-card/registry-scoped, not process-global env.
-        this.executorRegistry.updateConfig({ activeAnchorProfile: this.cardAnchorProfile });
+        this.executorRegistry.updateConfig({ activeAnchorProfile: this.cardAnchorProfile, allowCommandSubstitution: this.approvalMode.autoApproveActions });
         if (toolsToUse && toolsToUse.length > 0) {
             toolsToUse = this.applyAnchorIfArmed(toolsToUse);
         }
@@ -3143,7 +3151,7 @@ export class CortexOrchestrator {
             console.log(`[Orchestrator Streaming] Input-sliced initial for cross-turn chain: sent ${initialHistoryForApiStreaming.length}/${messageHistoryForApi.length} messages`);
         }
         // §13-B2: force AskForAdvice this turn on high-confidence thrash (mentor-force armed).
-        const forcedMentorChoice = await this.resolveForcedMentorChoice(toolsToUse);
+        const forcedMentorChoice = await this.resolveForcedMentorChoice(toolsToUse, 0); // initial request: 0 tool calls yet
         // Prepare request
         const preparedRequest = this.gatewayTranslation.prepareRequest(canonicalHistory, toolsToUse, effectiveModel, {
             temperature: options.parameters?.temperature,
@@ -3766,7 +3774,7 @@ export class CortexOrchestrator {
                     // Mark this tool_use_id as processed to prevent duplicate in error handler
                     processedToolUseIds.add(toolResult.tool_use_id);
                     // Progressive filter: record tool use for deferred loading (streaming)
-                    if (this.config.enableDeferredToolLoading) {
+                    if (this.effectiveDeferredLoading) {
                         this.toolFilter.recordToolUse(toolResult.tool_name);
                         if (toolResult.tool_name === 'SearchTools' && !toolResult.is_error) {
                             const content = typeof toolResult.content === 'string'
@@ -3932,7 +3940,7 @@ export class CortexOrchestrator {
                     // surface — never lift, never deliver the deferred corpus.
                     resolveFrameProfile(process.env, this.cardFrameProfile) !== 'persist') {
                     this.anchorLifted = true;
-                    if (!(this.config.enableDeferredToolLoading && !isPTCEnabled)) {
+                    if (!(this.effectiveDeferredLoading && !isPTCEnabled)) {
                         toolsToUse = allTools;
                         if (structuredOutputState) {
                             toolsToUse = ensureStructuredOutputTool(toolsToUse, structuredOutputState);
@@ -3940,12 +3948,12 @@ export class CortexOrchestrator {
                     }
                     // P6 deferral: same one-shot corpus delivery as the sendMessage path.
                     await this.deliverDeferredCorpusAtLift(effectiveModel);
-                    this.deliverLiftNudge(allTools); // A′ proposal-1: SearchTools/AskForAdvice signpost at lift
+                    this.deliverLiftNudge(allTools, effectiveModel); // A′ proposal-1: SearchTools/AskForAdvice signpost at lift
                     if (this.config.debug)
                         console.log('[Anchor] lifted at first tool_result boundary — session profile applies');
                 }
                 // Re-filter tools after SearchTools discovery (same as sendMessage path)
-                if (this.config.enableDeferredToolLoading && !isPTCEnabled) {
+                if (this.effectiveDeferredLoading && !isPTCEnabled) {
                     toolsToUse = this.toolFilter.getFilteredTools(allTools);
                     // StructuredOutput: re-filter rebuilds from allTools — re-append the
                     // request-scoped tool (same as the sendMessage continuation path).
@@ -3962,6 +3970,9 @@ export class CortexOrchestrator {
                     ? this.messageHistory.slice(this.messageCountAtLastResponse)
                     : this.messageHistory;
                 const continuationCanonicalHistory = this.convertToCanonicalMessages([...streamContinuationHistorySource]);
+                // §13-B2: re-evaluate the forced mentor choice on THIS streaming continuation — thrash
+                // develops here, not on the initial request (mirror of the non-stream continuation fix).
+                const continuationForcedChoice = await this.resolveForcedMentorChoice(toolsToUse, toolCallIteration);
                 // Phase 2.8: Prepare continuation request
                 // All providers maintain thinking throughout multi-turn execution
                 const continuationRequest = this.gatewayTranslation.prepareRequest(continuationCanonicalHistory, toolsToUse, // Updated tools including SearchTools discoveries
@@ -3973,6 +3984,7 @@ export class CortexOrchestrator {
                     stream: true, // STREAMING continuation
                     staticSystemPrompt: this.currentStaticSystemPrompt, // R28
                     conversationId: this.currentConversationId, // R28b
+                    toolChoice: continuationForcedChoice // §13-B2 forced mentor tool_choice (continuation)
                     // Thinking enabled for all providers in continuations
                     // This allows interleaved thinking during tool execution
                 });
@@ -6812,7 +6824,7 @@ export class CortexOrchestrator {
      * of mostly-failures, currently failing). Returns the CANONICAL forced choice; the
      * gateway converts its name to the wire form. `tool_choice` is body-level → cache-safe.
      */
-    async resolveForcedMentorChoice(toolsToUse) {
+    async resolveForcedMentorChoice(toolsToUse, turnCount) {
         if (!this.config.reactiveMentorship?.enabled)
             return undefined;
         if (process.env.CORTEX_MENTOR_FORCE !== 'true')
@@ -6827,7 +6839,7 @@ export class CortexOrchestrator {
             return undefined;
         try {
             const outcomes = await store.recentOutcomes(resolveThrashConfig().window);
-            return resolveThrashState(outcomes, this.turnNumber).thrashing
+            return resolveThrashState(outcomes, turnCount).thrashing
                 ? { type: 'tool', name: 'AskForAdvice' }
                 : undefined;
         }