@nexus-cortex/core 4.81.0 → 4.83.0

package/dist/orchestrator/CortexOrchestrator.js

@@ -37,6 +37,8 @@ import { slashCommandRegistry } from '../commands/SlashCommandRegistry.js';
 import { prefixMcpToolName, parseMcpToolName } from '../mcp/mcpToolNamespacing.js';
 import { DecisionStore } from '../training/DecisionStore.js';
 import { formatPriorReminder, formatFamilyReminder, formatApproachReminder } from '../training/DecisionPriorInjector.js';
+import { resolveConsultRung, resolveMentorConfig, bounceMessage, rateLimitedMessage, } from '../training/mentorConsult.js';
+import { resolveThrashState, resolveThrashConfig } from '../training/thrashDetector.js';
 import { classifyErrorFamily } from '../training/errorFamily.js';
 import { classifyToolOutcome } from '../training/toolOutcome.js';
 import { LoopLadder, formatLadderSignal } from '../training/loopLadder.js';
@@ -811,8 +813,15 @@ export class CortexOrchestrator {
         if (structuredOutputState) {
             toolsToUse = ensureStructuredOutputTool(toolsToUse, structuredOutputState);
         }
+        // AskForAdvice (MENTORSHIP_ASK_FOR_ADVICE_SPEC §12): append the mentor tool AFTER
+        // the deferred filter + anchor (standard-tier tools are otherwise stripped), so a
+        // thrashing model can call it without a SearchTools round-trip. Session-stable (gated
+        // on mentorship-active, off by default), so the tool-prefix cache is not toggled mid-run.
+        toolsToUse = this.ensureAskForAdviceTool(toolsToUse);
         // 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 preparedRequest = this.gatewayTranslation.prepareRequest(canonicalHistory, toolsToUse, effectiveModel, {
             temperature: options.parameters?.temperature,
             maxTokens: options.parameters?.maxTokens,
@@ -820,7 +829,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: forcedMentorChoice // §13-B2 forced mentor tool_choice
         });
         // Stateful Responses API: chain from prior response when available
         // (works across user turns — lastResponseId is preserved between messages).
@@ -3045,6 +3055,11 @@ export class CortexOrchestrator {
         if (structuredOutputState) {
             toolsToUse = ensureStructuredOutputTool(toolsToUse, structuredOutputState);
         }
+        // AskForAdvice (MENTORSHIP_ASK_FOR_ADVICE_SPEC §12): append the mentor tool AFTER
+        // the deferred filter + anchor (standard-tier tools are otherwise stripped), so a
+        // thrashing model can call it without a SearchTools round-trip. Session-stable (gated
+        // on mentorship-active, off by default), so the tool-prefix cache is not toggled mid-run.
+        toolsToUse = this.ensureAskForAdviceTool(toolsToUse);
         // Reset sequential call counter at start of each user turn
         this.mentorshipMiddleware?.resetSequentialCalls(this.currentSessionId);
         // Input-slicing at initial (streaming) request: send only items since last checkpoint
@@ -3060,6 +3075,8 @@ export class CortexOrchestrator {
         if (initialCanSliceInputStreaming && this.config.debug) {
             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);
         // Prepare request
         const preparedRequest = this.gatewayTranslation.prepareRequest(canonicalHistory, toolsToUse, effectiveModel, {
             temperature: options.parameters?.temperature,
@@ -3068,7 +3085,8 @@ export class CortexOrchestrator {
             reasoningEffort: options.parameters?.reasoningEffort, // GPT-5.1 reasoning level
             stream: true, // Enable streaming!
             staticSystemPrompt: this.currentStaticSystemPrompt, // R28
-            conversationId: this.currentConversationId // R28b
+            conversationId: this.currentConversationId, // R28b
+            toolChoice: forcedMentorChoice // §13-B2 forced mentor tool_choice
         });
         // Stateful Responses API: chain from prior response when available (cross-turn).
         if (this.lastResponseId && effectiveModel.api.pattern === 'responses') {
@@ -5468,6 +5486,8 @@ export class CortexOrchestrator {
                     'MemoryRecall'
                 ];
                 const isContextManagementTool = contextManagementToolNames.includes(toolUse.name);
+                // AskForAdvice (MENTORSHIP_ASK_FOR_ADVICE_SPEC): orchestrator-dispatched mentor tool.
+                const isMentorTool = toolUse.name === 'AskForAdvice';
                 // Phase 2.6: Check if this is an MCP management tool
                 const mcpManagementToolNames = [
                     'ListAvailableMcpServers',
@@ -5482,8 +5502,8 @@ export class CortexOrchestrator {
                 // Phase 2.5 Day 4: Check if this is an MCP tool
                 const mcpServerName = this.getMcpServerForTool(toolUse.name);
                 const isMcpTool = mcpServerName !== undefined;
-                // Check if tool exists (context management, MCP management, MCP, or executor)
-                if (!isContextManagementTool && !isMcpManagementTool && !isMcpTool && !this.executorRegistry.hasExecutor(toolUse.name)) {
+                // Check if tool exists (context management, mentor, MCP management, MCP, or executor)
+                if (!isContextManagementTool && !isMentorTool && !isMcpManagementTool && !isMcpTool && !this.executorRegistry.hasExecutor(toolUse.name)) {
                     const availableExecutors = this.executorRegistry.getExecutorNames();
                     const availableMcpTools = this.mcpManager ? this.mcpManager.getAllTools().map(t => t.name) : [];
                     const allAvailable = [...availableExecutors, ...availableMcpTools, ...contextManagementToolNames, ...mcpManagementToolNames];
@@ -5567,6 +5587,10 @@ export class CortexOrchestrator {
                                 }
                             };
                         }
+                        // AskForAdvice — consult the stronger mentor for a hint (spec §4-§5)
+                        else if (isMentorTool) {
+                            result = await this.executeAskForAdvice(toolUse.input);
+                        }
                         // Phase 2.6: Execute MCP management tool
                         else if (isMcpManagementTool) {
                             if (this.config.debug) {
@@ -6699,6 +6723,123 @@ export class CortexOrchestrator {
      * Returns the (possibly-augmented) result. Failures in the store path
      * are swallowed so training never breaks tool execution.
      */
+    /** Include AskForAdvice in the turn's tool set when mentorship is active (spec §12).
+     *  Appended post-filter so the deferred filter can't strip this standard-tier tool;
+     *  gated on reactiveMentorship.enabled (off by default) and idempotent. */
+    ensureAskForAdviceTool(tools) {
+        if (!this.config.reactiveMentorship?.enabled || !tools)
+            return tools;
+        if (tools.some((t) => t.name === 'AskForAdvice'))
+            return tools;
+        const def = toolFactory.getTool('AskForAdvice');
+        return def ? [...tools, def] : tools;
+    }
+    /**
+     * AskForAdvice v2 (§13-B2): decide whether to FORCE `AskForAdvice` for the NEXT
+     * request (delivers the mentor hint through the heed-friendly tool-result channel,
+     * routing around flash's weak voluntary heed — v1 measured 0/6). Gated on ALL of:
+     * mentorship active, `CORTEX_MENTOR_FORCE=true` (default off), the tool is present
+     * in this request's surface, the session is not yet rate-limited, and HIGH-confidence
+     * thrash (the full `resolveThrashState` window — past the turn floor, a full window
+     * 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) {
+        if (!this.config.reactiveMentorship?.enabled)
+            return undefined;
+        if (process.env.CORTEX_MENTOR_FORCE !== 'true')
+            return undefined;
+        if (!toolsToUse?.some((t) => t.name === 'AskForAdvice'))
+            return undefined;
+        const sessionId = this.currentSessionId ?? 'unknown';
+        if ((this.mentorConsultCounts.get(sessionId) ?? 0) >= resolveMentorConfig().maxConsults)
+            return undefined;
+        const store = this.getDecisionStore();
+        if (!store)
+            return undefined;
+        try {
+            const outcomes = await store.recentOutcomes(resolveThrashConfig().window);
+            return resolveThrashState(outcomes, this.turnNumber).thrashing
+                ? { type: 'tool', name: 'AskForAdvice' }
+                : undefined;
+        }
+        catch {
+            return undefined; // fail-open: never let the thrash read break a turn
+        }
+    }
+    /** Honored AskForAdvice consults per session (rate-limit + rung state; persists across turns). */
+    mentorConsultCounts = new Map();
+    /**
+     * AskForAdvice executor (MENTORSHIP_ASK_FOR_ADVICE_SPEC v1). Orchestrator-dispatched
+     * because it needs helperMiddleware + the decision store + session state, which the
+     * packages/executors executors structurally lack. Graduated ladder: premature bounce →
+     * mentor DIRECTED REFRAME → structured interview → rate-limited. The stronger mentor
+     * (reactiveMentorship.helperModelId, e.g. deepseek-v4-pro) returns a HINT, never the
+     * solution. Banks a `mentor_consult` episode for the apprentice data lake. Fail-open —
+     * a mentor error never breaks the turn.
+     */
+    async executeAskForAdvice(input) {
+        const sessionId = this.currentSessionId ?? 'unknown';
+        const store = this.getDecisionStore();
+        const failedRows = store ? await store.recentFailures(6) : [];
+        const failed = failedRows.map((d) => ({
+            call: d.inputSummary || d.toolName,
+            error: d.errorSnippet || '',
+        }));
+        const honored = this.mentorConsultCounts.get(sessionId) ?? 0;
+        // v1 gate: the model self-selected by CALLING the tool, so a light "real struggle
+        // exists" check (>=2 recent failures) suffices. The full thrashDetector drives the
+        // proactive invite/forced-choice path (v2), not this executor.
+        const thrashing = failed.length >= 2;
+        const rung = resolveConsultRung(honored, thrashing);
+        if (rung === 'bounce') {
+            return { success: true, llmContent: bounceMessage(failed.length), metadata: { source: 'mentor-consult', rung } };
+        }
+        if (rung === 'ratelimited') {
+            return { success: true, llmContent: rateLimitedMessage(resolveMentorConfig().maxConsults), metadata: { source: 'mentor-consult', rung } };
+        }
+        let hint;
+        try {
+            hint = await this.helperMiddleware.generateMentorHint({
+                rung,
+                task: this.lastRealUserText(),
+                failed,
+                question: input?.question,
+                helperModelId: this.config.reactiveMentorship?.helperModelId,
+            });
+        }
+        catch (err) {
+            return {
+                success: true,
+                llmContent: 'Advice is unavailable right now — keep working the problem: re-read the task and try a distinct approach.',
+                metadata: { source: 'mentor-consult', rung, error: String(err).slice(0, 120) },
+            };
+        }
+        this.mentorConsultCounts.set(sessionId, honored + 1);
+        if (store) {
+            // §13-B3: the FULL episode for the apprentice data pump (§10). Tagged
+            // `mentor_episode` so the distiller/canon can filter; `turn` lets it JOIN to
+            // this task's graded outcome (the reward label lives on the task row, known
+            // only at grade time). Full hint (not truncated) + the question + the failed
+            // trace = the training-ready thrash→ask→hint record. Best-effort, never throws.
+            store.recordEvent({
+                sessionId,
+                kind: 'mentor_consult',
+                toolName: 'AskForAdvice',
+                detail: {
+                    tag: 'mentor_episode',
+                    rung,
+                    turn: this.turnNumber,
+                    helperModel: this.config.reactiveMentorship?.helperModelId ?? 'default',
+                    question: input?.question ?? null,
+                    hint,
+                    failedCount: failed.length,
+                    failedTrace: failed.slice(0, 6),
+                },
+            }).catch(() => { });
+        }
+        return { success: true, llmContent: hint, metadata: { source: 'mentor-consult', rung, helperModel: this.config.reactiveMentorship?.helperModelId } };
+    }
     async processToolTraining(toolUse, result) {
         const store = this.getDecisionStore();
         if (!store)