@nexus-cortex/core 4.89.0 → 4.90.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, resolveLiftNudge, resolveHeadlessDropAskUser, resolveDeferredLoading, isNarrowProfile, isToolAllowedByProfile, applyToolProfile, webToolBlocked } from '../tools/ToolProfile.js';
+import { resolveToolProfile, resolveToolAnchor, resolveFrameProfile, resolveLiftNudge, resolveHeadlessDropAskUser, resolveDeferredLoading, isNarrowProfile, isToolAllowedByProfile, applyToolProfile, webToolBlocked, resolveVisionHelperModel } from '../tools/ToolProfile.js';
 import { readStagedDoctrine, applyCuratedDoctrine, runOrientForStaging, withTimeout } from './doctrineCuration.js';
 import { ExactRepeatTracker } from '../training/loopLadder.js';
 import { slashCommandRegistry } from '../commands/SlashCommandRegistry.js';
@@ -44,7 +44,7 @@ import { classifyToolOutcome } from '../training/toolOutcome.js';
 import { LoopLadder, formatLadderSignal } from '../training/loopLadder.js';
 import { shouldNudgeInaction, formatInactionNudge } from './inactionGuard.js';
 import { applyImageTtlForRequest } from './imageTtl.js';
-import { verifyRequirements, resolveEndTurnRequirementsMode } from './requirementsVerification.js';
+import { verifyRequirements, resolveEndTurnRequirementsMode, resolveEndTurnRequirementsStrict } from './requirementsVerification.js';
 import { verifyIntegrity, resolveEndTurnIntegrityMode } from './integrityVerification.js';
 import { detectSurrenderText, resolveSurrenderNudgeMode, SURRENDER_REMINDER } from './turnEndGuards.js';
 import { ModelRouterMatrix } from '../training/ModelRouterMatrix.js';
@@ -478,7 +478,7 @@ export class CortexOrchestrator {
                     const catalogVision = this.getModel(this.currentModelId ?? '')?.vision === true;
                     return [...toolFactory.getAllTools(), ...extras]
                         .filter((t) => endTurnGateOn || t.name !== 'EndTurn')
-                        .filter((t) => catalogVision || t.name !== 'ReadImage')
+                        .filter((t) => catalogVision || !!resolveVisionHelperModel(process.env) || t.name !== 'ReadImage')
                         .filter((t) => (seen.has(t.name) ? false : (seen.add(t.name), true)))
                         .map((t) => ({
                         name: namingHandler.convertName(t.name, convention),
@@ -634,7 +634,7 @@ export class CortexOrchestrator {
         const visionOn = model?.vision === true;
         const factoryTools = this.applyBaseToolAllowlist(toolFactory.getAllTools()
             .filter(t => endTurnGateOn || t.name !== 'EndTurn')
-            .filter(t => visionOn || t.name !== 'ReadImage'));
+            .filter(t => visionOn || !!resolveVisionHelperModel(process.env) || t.name !== 'ReadImage'));
         // Tool-profile: MCP/management/context tools bypass ToolFactory, so the
         // bash-only arm must suppress them here or the surface leaks (lean keeps
         // them — they are part of the "guided" surface under test).
@@ -898,7 +898,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, allowCommandSubstitution: this.approvalMode.autoApproveActions });
+        this.executorRegistry.updateConfig({ activeAnchorProfile: this.cardAnchorProfile, allowCommandSubstitution: this.approvalMode.autoApproveActions, headless: this.approvalMode.autoApproveActions });
         if (toolsToUse && toolsToUse.length > 0) {
             toolsToUse = this.applyAnchorIfArmed(toolsToUse);
         }
@@ -2095,6 +2095,8 @@ export class CortexOrchestrator {
                                     verification: etUse?.input?.verification,
                                     userTaskText: this.lastRealUserText(),
                                     turnUsedMutatingTool,
+                                    strict: resolveEndTurnRequirementsStrict(process.env),
+                                    toolOutputs: thisTurnToolOutputs.join('\n'),
                                 });
                                 if (s4.ok) {
                                     endTurnCalled = true;
@@ -2156,6 +2158,7 @@ export class CortexOrchestrator {
                     // Item 7: scrub ReadImage payloads from metadata BEFORE persist;
                     // the images inject as a user message after the results land.
                     const pendingImages = this.collectPendingImages(toolResults, effectiveModel.vision === true);
+                    await this.applyVisionHandoffs();
                     // Create tool_result messages and add to history
                     for (const toolResult of toolResults) {
                         const toolResultMessageId = uuidv4();
@@ -3196,7 +3199,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, allowCommandSubstitution: this.approvalMode.autoApproveActions });
+        this.executorRegistry.updateConfig({ activeAnchorProfile: this.cardAnchorProfile, allowCommandSubstitution: this.approvalMode.autoApproveActions, headless: this.approvalMode.autoApproveActions });
         if (toolsToUse && toolsToUse.length > 0) {
             toolsToUse = this.applyAnchorIfArmed(toolsToUse);
         }
@@ -3808,6 +3811,7 @@ export class CortexOrchestrator {
                 }
                 // Item 7: scrub ReadImage payloads before persist (streaming parity).
                 const pendingImages = this.collectPendingImages(toolResults, effectiveModel.vision === true);
+                await this.applyVisionHandoffs();
                 // Create tool_result messages and save to history
                 for (const toolResult of toolResults) {
                     // Emit tool result as streaming chunk for CLI display
@@ -6801,6 +6805,43 @@ export class CortexOrchestrator {
      *  hallucinated/PTC call that slipped the surface gate), the result is
      *  rewritten into an actionable error — a text-only model must never have
      *  an image dangled at it. */
+    /** Vision hand-off queue (filled by collectPendingImages for text-only primaries). */
+    pendingVisionHandoffs = [];
+    /** Resolve queued ReadImage hand-offs through the helper middleware: the vision helper's TEXT
+     *  replaces the tool_result content. Failures degrade to the pre-hand-off guidance (bash OCR). */
+    async applyVisionHandoffs() {
+        const queue = this.pendingVisionHandoffs;
+        this.pendingVisionHandoffs = [];
+        for (const h of queue) {
+            const modelId = resolveVisionHelperModel(process.env) || 'deepseek-v4-flash-vision-exp';
+            try {
+                const t0 = Date.now();
+                const text = await this.helperMiddleware.describeImage({
+                    mediaType: h.payload.mediaType, base64: h.payload.base64, prompt: h.prompt, filePath: h.filePath, helperModelId: modelId,
+                });
+                h.tr.is_error = false;
+                h.tr.content =
+                    `[ReadImage → vision helper ${modelId}${h.filePath ? ` on ${h.filePath}` : ''}]\n` +
+                        (text || '(the vision helper returned no description)') +
+                        `\n\n(Read by the vision helper on your behalf — the active model is text-only. Ask again with a more specific \`prompt\` if you need a different reading.)`;
+                if (this.config.debug)
+                    console.log(`[VisionHandoff] ${modelId} described ${h.filePath || 'image'} in ${Date.now() - t0}ms (${(text || '').length} chars)`);
+                const store = this.getDecisionStore();
+                if (store) {
+                    void store.recordEvent({
+                        sessionId: this.currentSessionId ?? 'unknown', kind: 'steering_injected', toolName: 'ReadImage',
+                        detail: { kind: 'vision_handoff', helper: modelId, chars: (text || '').length, filePath: h.filePath },
+                    }).catch(() => { });
+                }
+            }
+            catch (err) {
+                h.tr.is_error = true;
+                h.tr.content =
+                    `ReadImage vision hand-off failed (${modelId}: ${err?.message || err}). ` +
+                        'Extract what you need through bash instead (e.g. tesseract OCR, ffprobe, PIL).';
+            }
+        }
+    }
     collectPendingImages(toolResults, modelVision) {
         const out = [];
         for (const tr of toolResults) {
@@ -6811,6 +6852,16 @@ export class CortexOrchestrator {
             if (tr.is_error)
                 continue;
             if (!modelVision) {
+                // VISION HAND-OFF (2026-09-02): a text-only primary called ReadImage. If a vision helper
+                // is configured, queue the payload for the helper middleware (applyVisionHandoffs runs
+                // right after this at both call sites and REPLACES the tool_result with the helper's
+                // text). The primary never receives an image payload — item 7's safety intent holds.
+                if (resolveVisionHelperModel(process.env)) {
+                    this.pendingVisionHandoffs.push({ tr, payload, prompt: tr.metadata?.imagePrompt, filePath: tr.metadata?.imageFilePath });
+                    delete tr.metadata.imagePrompt;
+                    delete tr.metadata.imageFilePath;
+                    continue;
+                }
                 tr.is_error = true;
                 tr.content =
                     'ReadImage requires a vision-capable model — the active model cannot see images. ' +
@@ -7055,6 +7106,13 @@ export class CortexOrchestrator {
         const store = this.getDecisionStore();
         if (!store)
             return result;
+        // TOOL_TIMEOUT_MODE engagement evidence: a promoted-to-background tool call.
+        if (result.metadata?.promotedToBackground) {
+            void store.recordEvent({
+                sessionId: this.currentSessionId ?? 'unknown', kind: 'steering_injected', toolName: toolUse.name,
+                detail: { kind: 'tool_promoted', bashId: result.metadata.promotedToBackground },
+            }).catch(() => { });
+        }
         // Unified outcome layer (docs/UNIFIED_OUTCOME_LADDER.md): ONE failure
         // semantics for recording + reminders. Critically, a bash command that
         // ran and exited nonzero is a FAILURE here even though its tool result