@nexus-cortex/core 4.80.0 → 4.82.0

package/dist/orchestrator/CortexOrchestrator.js

@@ -36,7 +36,8 @@ import { ExactRepeatTracker } from '../training/loopLadder.js';
 import { slashCommandRegistry } from '../commands/SlashCommandRegistry.js';
 import { prefixMcpToolName, parseMcpToolName } from '../mcp/mcpToolNamespacing.js';
 import { DecisionStore } from '../training/DecisionStore.js';
-import { formatPriorReminder, formatFamilyReminder } from '../training/DecisionPriorInjector.js';
+import { formatPriorReminder, formatFamilyReminder, formatApproachReminder } from '../training/DecisionPriorInjector.js';
+import { resolveConsultRung, resolveMentorConfig, bounceMessage, rateLimitedMessage, } from '../training/mentorConsult.js';
 import { classifyErrorFamily } from '../training/errorFamily.js';
 import { classifyToolOutcome } from '../training/toolOutcome.js';
 import { LoopLadder, formatLadderSignal } from '../training/loopLadder.js';
@@ -811,6 +812,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);
         const preparedRequest = this.gatewayTranslation.prepareRequest(canonicalHistory, toolsToUse, effectiveModel, {
@@ -3045,6 +3051,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
@@ -5468,6 +5479,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 +5495,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 +5580,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 +6716,82 @@ 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;
+    }
+    /** 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) {
+            // Reward-labeled episode for the apprentice pipeline (data pump). Best-effort.
+            store.recordEvent({
+                sessionId,
+                kind: 'mentor_consult',
+                toolName: 'AskForAdvice',
+                detail: {
+                    rung,
+                    helperModel: this.config.reactiveMentorship?.helperModelId ?? 'default',
+                    hint: hint.slice(0, 400),
+                    failedCount: failed.length,
+                },
+            }).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)
@@ -6732,11 +6825,26 @@ export class CortexOrchestrator {
                     // failures spanning >=2 distinct inputs. Gated on the UNIFIED
                     // outcome (not is_error) so failing-command loops are covered.
                     const family = outcome.family ?? classifyErrorFamily(String(result.content).slice(0, 200));
+                    let fired = false;
                     if (family) {
                         const ff = await store.familyFailures(toolUse.name, family);
                         const famReminder = formatFamilyReminder(toolUse.name, family, ff.count, ff.distinctInputs, ff.recent);
                         if (famReminder) {
                             augmented = { ...result, content: famReminder + result.content };
+                            fired = true;
+                        }
+                    }
+                    // Approach lens (BUILD 1a — the ×98 varied-retry class): neither the
+                    // exact-input nor the error-family reminder fired, but the CURRENT
+                    // failure may be the latest of a repeated command-SHAPE loop (same
+                    // approach, tweaked args, differing errors). Fires on >=2 failures of
+                    // this approachHash across >=2 distinct inputs — the fuzzy net the
+                    // exact/family lenses miss. Last, so more-specific lenses win.
+                    if (!fired && outcome.approachHash) {
+                        const af = await store.approachFailures(toolUse.name, outcome.approachHash);
+                        const apReminder = formatApproachReminder(toolUse.name, af.count, af.distinctInputs, af.recent);
+                        if (apReminder) {
+                            augmented = { ...result, content: apReminder + result.content };
                         }
                     }
                 }
@@ -6761,6 +6869,10 @@ export class CortexOrchestrator {
                     ...(outcome.status !== 'ok'
                         ? { errorSnippet: String(result.content).slice(0, 200) }
                         : {}),
+                    // BUILD 1a: persist the command-shape fingerprint so the cross-turn
+                    // approach lens (approachFailures) can see varied retries of one
+                    // approach. Cheap, always recorded (both lenses read failures only).
+                    approachHash: outcome.approachHash,
                 });
             }
             catch (err) {