@nexus-cortex/core 4.81.0 → 4.83.0

package/dist/training/mentorConsult.js

@@ -0,0 +1,73 @@
+/**
+ * mentorConsult — the AskForAdvice mentor logic (MENTORSHIP_ASK_FOR_ADVICE_SPEC §4–§5).
+ *
+ * Pure core of the AskForAdvice executor: the graduated-escalation RUNG decision, the
+ * mentor system prompts (HINT, never the solution), and the context assembled for the
+ * mentor. The actual off-main model call (via HelperModelMiddleware / MENTORSHIP_HELPER_MODEL)
+ * is the orchestrator's integration; everything here is deterministic + unit-testable.
+ *
+ * Ladder (§4):
+ *   rung 0 'bounce'      — premature (not thrash-eligible): cheap self-help refuse, no LLM.
+ *   rung 1 'reframe'     — first honored consult: mentor's DIRECTED reframe from the trace.
+ *   rung 2 'interview'   — consult again after following the reframe + still failing:
+ *                          structured diagnostic Q&A (à la AskUserQuestion).
+ *   'ratelimited'        — beyond the consult cap: execute the guidance you have.
+ */
+const DEFAULTS = { maxConsults: 2 };
+export function resolveMentorConfig(env = process.env) {
+    const n = parseInt((env.CORTEX_MENTOR_MAX_CONSULTS ?? '').trim(), 10);
+    return { maxConsults: Number.isInteger(n) && n > 0 ? n : DEFAULTS.maxConsults };
+}
+/**
+ * Which rung a given AskForAdvice call lands on.
+ * @param honoredCount  consults already HONORED this task (mentor actually invoked).
+ * @param thrashing     is the agent thrash-eligible right now?
+ */
+export function resolveConsultRung(honoredCount, thrashing, cfg = resolveMentorConfig()) {
+    if (honoredCount >= cfg.maxConsults)
+        return 'ratelimited';
+    if (!thrashing)
+        return 'bounce'; // premature — send them back to self-work
+    return honoredCount === 0 ? 'reframe' : 'interview';
+}
+/** Rung-0 self-help refuse (no LLM). Constructive: reframe + try a distinct approach. */
+export function bounceMessage(attempts) {
+    return (`You've made ${attempts} attempt${attempts === 1 ? '' : 's'} — reframe the goal and try a ` +
+        `different solution before calling AskForAdvice again. Re-read the task, restate what you're ` +
+        `actually trying to achieve, and try a genuinely distinct approach first.`);
+}
+/** Beyond the consult cap. */
+export function rateLimitedMessage(maxConsults) {
+    return (`You have already consulted ${maxConsults} time${maxConsults === 1 ? '' : 's'}. ` +
+        `Execute the guidance you have — do not consult again for this task.`);
+}
+/** Mentor system prompt for rung 1 (directed reframe). HINT, never the solution. */
+export const MENTOR_REFRAME_SYSTEM = 'You are a senior engineer. A junior agent is stuck on a coding task after several failed ' +
+    'attempts. Give a HINT or REDIRECTION — name what they are missing, the wrong assumption ' +
+    "they're making, or the direction to try — in 1–3 sentences. NEVER write the solution, the " +
+    'code, or the exact commands. They must do the work themselves.';
+/** Mentor system prompt for rung 2 (structured diagnostic interview). */
+export const MENTOR_INTERVIEW_SYSTEM = 'You are a senior engineer. The junior followed your earlier hint and is still stuck. Run a ' +
+    'SHORT structured diagnosis: state the 2–3 most likely blockers as concrete options and ask ' +
+    'which matches what they see, or pose one focused diagnostic question whose answer isolates ' +
+    'the issue. Do NOT provide the solution or the code — isolate the blocker so they can fix it.';
+/**
+ * Build the user prompt sent to the mentor. Bounded — most-recent failures only.
+ */
+export function buildMentorUserPrompt(ctx, maxFailed = 6) {
+    const parts = [];
+    parts.push(`TASK:\n${ctx.task.trim().slice(0, 1500)}`);
+    const recent = ctx.failed.slice(-maxFailed);
+    if (recent.length) {
+        parts.push('RECENT FAILED ATTEMPTS (newest last):\n' +
+            recent
+                .map((f, i) => `${i + 1}. ${f.call.slice(0, 240)}\n   → ${f.error.slice(0, 240)}`)
+                .join('\n'));
+    }
+    if (ctx.question && ctx.question.trim()) {
+        parts.push(`THE JUNIOR ASKS:\n${ctx.question.trim().slice(0, 500)}`);
+    }
+    parts.push('Give your hint (or diagnostic question) now. Be specific. Do not write code.');
+    return parts.join('\n\n');
+}
+//# sourceMappingURL=mentorConsult.js.map

package/dist/training/mentorConsult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mentorConsult.js","sourceRoot":"","sources":["../../src/training/mentorConsult.ts"],"names":[],"mappings":"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"}

package/dist/training/thrashDetector.d.ts

@@ -0,0 +1,42 @@
+/**
+ * thrashDetector — shape-agnostic STRUGGLE signal (MENTORSHIP_ASK_FOR_ADVICE_SPEC §2).
+ *
+ * The dominant bench failure mode is DIVERSE-exploration thrash: the model makes many
+ * DIFFERENT failing attempts (44–105 calls on hard tasks) that the loop/approach
+ * detectors miss because it is not a clean repeated loop. This fires on failure
+ * DENSITY over a recent window — regardless of shape — once past a turn floor (a few
+ * failing probes early are normal debugging; cf. MAX_CONSECUTIVE_ERRORS=6). Pure +
+ * env-configurable; the orchestrator feeds it the recent tool outcomes it already
+ * tracks (the decision-store success/fail signal). Sterile-bench-safe (hot tier, no key).
+ */
+export interface ThrashConfig {
+    /** Failures within the window that trip thrash. Default 4. */
+    failThreshold: number;
+    /** Size of the recent tool-outcome window examined. Default 6. */
+    window: number;
+    /** Do not fire before this many tool calls total (early failures are normal). Default 5. */
+    minTurns: number;
+}
+export interface ThrashState {
+    /** True when the model is thrashing and the mentor path should engage. */
+    thrashing: boolean;
+    /** Failures counted in the examined window. */
+    failures: number;
+    /** Outcomes actually examined (== min(window, available)). */
+    examined: number;
+}
+export declare const THRASH_DEFAULTS: ThrashConfig;
+export declare function resolveThrashConfig(env?: NodeJS.ProcessEnv): ThrashConfig;
+/**
+ * Decide whether the agent is thrashing.
+ *
+ * @param outcomes   success booleans of tool calls, chronological (oldest→newest).
+ * @param turnCount  total tool calls so far (>= outcomes.length).
+ * @param cfg        thresholds (defaults from env).
+ *
+ * Fires only when: past the turn floor, a FULL window is available, the failure
+ * count meets the threshold, AND the most-recent outcome is a failure (so it never
+ * fires right after the model just made progress).
+ */
+export declare function resolveThrashState(outcomes: boolean[], turnCount: number, cfg?: ThrashConfig): ThrashState;
+//# sourceMappingURL=thrashDetector.d.ts.map

package/dist/training/thrashDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thrashDetector.d.ts","sourceRoot":"","sources":["../../src/training/thrashDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,eAAe,EAAE,YAA2D,CAAC;AAO1F,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,CAMtF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,OAAO,EAAE,EACnB,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,YAAoC,GACxC,WAAW,CAUb"}

package/dist/training/thrashDetector.js

@@ -0,0 +1,45 @@
+/**
+ * thrashDetector — shape-agnostic STRUGGLE signal (MENTORSHIP_ASK_FOR_ADVICE_SPEC §2).
+ *
+ * The dominant bench failure mode is DIVERSE-exploration thrash: the model makes many
+ * DIFFERENT failing attempts (44–105 calls on hard tasks) that the loop/approach
+ * detectors miss because it is not a clean repeated loop. This fires on failure
+ * DENSITY over a recent window — regardless of shape — once past a turn floor (a few
+ * failing probes early are normal debugging; cf. MAX_CONSECUTIVE_ERRORS=6). Pure +
+ * env-configurable; the orchestrator feeds it the recent tool outcomes it already
+ * tracks (the decision-store success/fail signal). Sterile-bench-safe (hot tier, no key).
+ */
+export const THRASH_DEFAULTS = { failThreshold: 4, window: 6, minTurns: 5 };
+function posInt(v, d) {
+    const n = parseInt((v ?? '').trim(), 10);
+    return Number.isInteger(n) && n > 0 ? n : d;
+}
+export function resolveThrashConfig(env = process.env) {
+    return {
+        failThreshold: posInt(env.CORTEX_THRASH_FAILS, THRASH_DEFAULTS.failThreshold),
+        window: posInt(env.CORTEX_THRASH_WINDOW, THRASH_DEFAULTS.window),
+        minTurns: posInt(env.CORTEX_THRASH_MIN_TURNS, THRASH_DEFAULTS.minTurns),
+    };
+}
+/**
+ * Decide whether the agent is thrashing.
+ *
+ * @param outcomes   success booleans of tool calls, chronological (oldest→newest).
+ * @param turnCount  total tool calls so far (>= outcomes.length).
+ * @param cfg        thresholds (defaults from env).
+ *
+ * Fires only when: past the turn floor, a FULL window is available, the failure
+ * count meets the threshold, AND the most-recent outcome is a failure (so it never
+ * fires right after the model just made progress).
+ */
+export function resolveThrashState(outcomes, turnCount, cfg = resolveThrashConfig()) {
+    const win = outcomes.slice(-cfg.window);
+    const failures = win.reduce((n, ok) => n + (ok ? 0 : 1), 0);
+    const currentlyFailing = win.length > 0 && win[win.length - 1] === false;
+    const thrashing = turnCount >= cfg.minTurns &&
+        win.length >= cfg.window &&
+        failures >= cfg.failThreshold &&
+        currentlyFailing;
+    return { thrashing, failures, examined: win.length };
+}
+//# sourceMappingURL=thrashDetector.js.map

package/dist/training/thrashDetector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thrashDetector.js","sourceRoot":"","sources":["../../src/training/thrashDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAoBH,MAAM,CAAC,MAAM,eAAe,GAAiB,EAAE,aAAa,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;AAE1F,SAAS,MAAM,CAAC,CAAqB,EAAE,CAAS;IAC9C,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACzC,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACtE,OAAO;QACL,aAAa,EAAE,MAAM,CAAC,GAAG,CAAC,mBAAmB,EAAE,eAAe,CAAC,aAAa,CAAC;QAC7E,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,oBAAoB,EAAE,eAAe,CAAC,MAAM,CAAC;QAChE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,uBAAuB,EAAE,eAAe,CAAC,QAAQ,CAAC;KACxE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAmB,EACnB,SAAiB,EACjB,MAAoB,mBAAmB,EAAE;IAEzC,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5D,MAAM,gBAAgB,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC;IACzE,MAAM,SAAS,GACb,SAAS,IAAI,GAAG,CAAC,QAAQ;QACzB,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM;QACxB,QAAQ,IAAI,GAAG,CAAC,aAAa;QAC7B,gBAAgB,CAAC;IACnB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;AACvD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexus-cortex/core",
-  "version": "4.81.0",
+  "version": "4.83.0",
   "description": "Core orchestration library implementing Claude CLI architecture patterns",
   "type": "module",
   "main": "./dist/index.js",
@@ -47,8 +47,8 @@
     "@google/generative-ai": "^0.2.1",
     "@gradio/client": "^2.3.1",
     "@modelcontextprotocol/sdk": "^1.20.2",
-    "@nexus-cortex/executors": "4.81.0",
-    "@nexus-cortex/types": "4.81.0",
+    "@nexus-cortex/executors": "4.83.0",
+    "@nexus-cortex/types": "4.83.0",
     "@types/uuid": "^10.0.0",
     "ajv": "^8.12.0",
     "chokidar": "^3.6.0",