@j0hanz/cortex-mcp 1.4.0 → 1.6.0

package/dist/tools/reasoning-think.js

@@ -1,51 +1,38 @@
 import { getLevelDescriptionString } from '../engine/config.js';
 import { reason, sessionStore } from '../engine/reasoner.js';
 import { ReasoningThinkInputSchema, } from '../schemas/inputs.js';
-import { ReasoningThinkToolOutputSchema } from '../schemas/outputs.js';
-import { createErrorResponse, getErrorMessage } from '../lib/errors.js';
-import { formatThoughtsToMarkdown } from '../lib/formatting.js';
-import { createToolResponse } from '../lib/tool-response.js';
+import { ReasoningThinkToolOutputSchema, } from '../schemas/outputs.js';
+import { createTaskLimiter } from '../lib/concurrency.js';
+import { createErrorResponse, getErrorMessage, InsufficientThoughtsError, InvalidRunModeArgsError, isObjectRecord, ReasoningAbortedError, ReasoningError, ServerBusyError, SessionNotFoundError, } from '../lib/errors.js';
+import { formatProgressMessage, formatThoughtsToMarkdown, } from '../lib/formatting.js';
+import { createToolResponse, withIconMeta } from '../lib/tool-response.js';
+import { parseBooleanEnv, parsePositiveIntEnv } from '../lib/validators.js';
 const DEFAULT_MAX_ACTIVE_REASONING_TASKS = 32;
-// Use explicit server busy error code for better client handling
-const TASK_OVERLOAD_MESSAGE = 'Server busy: too many active reasoning tasks';
+const REDACTED_THOUGHT_CONTENT = '[REDACTED]';
+function shouldRedactTraceContent() {
+    return parseBooleanEnv('CORTEX_REDACT_TRACE_CONTENT', false);
+}
 function buildTraceResource(session) {
+    const sessionView = shouldRedactTraceContent()
+        ? {
+            ...session,
+            thoughts: session.thoughts.map((thought) => ({
+                index: thought.index,
+                content: REDACTED_THOUGHT_CONTENT,
+                revision: thought.revision,
+                ...(thought.stepSummary !== undefined
+                    ? { stepSummary: REDACTED_THOUGHT_CONTENT }
+                    : {}),
+            })),
+        }
+        : session;
     return {
         uri: `file:///cortex/sessions/${session.id}/trace.md`,
         mimeType: 'text/markdown',
-        text: formatThoughtsToMarkdown(session),
+        text: formatThoughtsToMarkdown(sessionView),
     };
 }
-function parsePositiveInt(rawValue, fallbackValue) {
-    if (rawValue === undefined) {
-        return fallbackValue;
-    }
-    const parsed = Number.parseInt(rawValue, 10);
-    if (!Number.isInteger(parsed) || parsed < 1) {
-        return fallbackValue;
-    }
-    return parsed;
-}
-function createTaskLimiter(maxActiveTasks) {
-    let activeTasks = 0;
-    return {
-        tryAcquire() {
-            if (activeTasks >= maxActiveTasks) {
-                return false;
-            }
-            activeTasks += 1;
-            return true;
-        },
-        release() {
-            if (activeTasks > 0) {
-                activeTasks -= 1;
-            }
-        },
-    };
-}
-const reasoningTaskLimiter = createTaskLimiter(parsePositiveInt(process.env.CORTEX_MAX_ACTIVE_REASONING_TASKS, DEFAULT_MAX_ACTIVE_REASONING_TASKS));
-function isObjectRecord(value) {
-    return typeof value === 'object' && value !== null;
-}
+const reasoningTaskLimiter = createTaskLimiter(parsePositiveIntEnv('CORTEX_MAX_ACTIVE_REASONING_TASKS', DEFAULT_MAX_ACTIVE_REASONING_TASKS));
 function isTaskStoreLike(value) {
     if (!isObjectRecord(value)) {
         return false;
@@ -134,27 +121,11 @@ function assertCallToolResult(value) {
         throw new Error('Stored task result is not a valid CallToolResult.');
     }
 }
-function mapReasoningErrorCode(message) {
-    switch (true) {
-        case message === 'Reasoning aborted':
-        case message === 'Reasoning task cancelled':
-            return 'E_ABORTED';
-        case message.startsWith('targetThoughts must be'):
-        case message.startsWith('Cannot change targetThoughts'):
-            return 'E_INVALID_THOUGHT_COUNT';
-        case message.startsWith('Session not found:'):
-            return 'E_SESSION_NOT_FOUND';
-        case message.startsWith('Session level mismatch:'):
-            return 'E_SESSION_LEVEL_MISMATCH';
-        case message.startsWith('run_to_completion requires at least'):
-            return 'E_INSUFFICIENT_THOUGHTS';
-        case message.startsWith('targetThoughts is required for run_to_completion when sessionId is not provided'):
-            return 'E_INVALID_RUN_MODE_ARGS';
-        case message === TASK_OVERLOAD_MESSAGE:
-            return 'E_SERVER_BUSY';
-        default:
-            return 'E_REASONING';
+function getReasoningErrorCode(error) {
+    if (error instanceof ReasoningError) {
+        return error.code;
     }
+    return 'E_REASONING';
 }
 function shouldEmitProgress(progress, total, level) {
     if (progress <= 1 || progress >= total) {
@@ -167,8 +138,22 @@ function shouldEmitProgress(progress, total, level) {
     // Basic/Normal: emit every step
     return true;
 }
-function resolveRunMode(params) {
-    return params.runMode ?? 'step';
+async function notifyProgress(args) {
+    const { server, progressToken, progress, total, message } = args;
+    try {
+        await server.server.notification({
+            method: 'notifications/progress',
+            params: {
+                progressToken,
+                progress,
+                total,
+                message,
+            },
+        });
+    }
+    catch {
+        // Ignore notification errors
+    }
 }
 function buildThoughtInputs(params) {
     const primary = Array.isArray(params.thought)
@@ -176,7 +161,7 @@ function buildThoughtInputs(params) {
         : params.thought
             ? [params.thought]
             : [];
-    return [...primary, ...(params.thoughts ?? [])];
+    return primary;
 }
 function getStartingThoughtCount(sessionId) {
     if (sessionId === undefined) {
@@ -203,6 +188,20 @@ async function executeReasoningSteps(args) {
             rollbackToStep !== undefined)) {
         maxSteps = 1;
     }
+    // Build first-step-only extras once, outside the loop.
+    const firstStepExtras = {
+        ...(observation !== undefined ? { observation } : {}),
+        ...(hypothesis !== undefined ? { hypothesis } : {}),
+        ...(evaluation !== undefined ? { evaluation } : {}),
+        ...(stepSummary !== undefined ? { stepSummary } : {}),
+        ...(isConclusion !== undefined ? { isConclusion } : {}),
+        ...(rollbackToStep !== undefined ? { rollbackToStep } : {}),
+    };
+    const baseOptions = {
+        ...(targetThoughts !== undefined ? { targetThoughts } : {}),
+        abortSignal: controller.signal,
+        onProgress,
+    };
     for (let index = 0; index < maxSteps; index++) {
         await ensureTaskIsActive(taskStore, taskId, controller);
         const inputThought = thoughtInputs[index];
@@ -217,30 +216,11 @@ async function executeReasoningSteps(args) {
             break;
         }
         const reasonOptions = {
+            ...baseOptions,
             ...(inputThought !== undefined ? { thought: inputThought } : {}),
-            abortSignal: controller.signal,
-            onProgress,
+            ...(activeSessionId !== undefined ? { sessionId: activeSessionId } : {}),
+            ...(index === 0 ? firstStepExtras : {}),
         };
-        if (index === 0) {
-            if (observation !== undefined)
-                reasonOptions.observation = observation;
-            if (hypothesis !== undefined)
-                reasonOptions.hypothesis = hypothesis;
-            if (evaluation !== undefined)
-                reasonOptions.evaluation = evaluation;
-            if (stepSummary !== undefined)
-                reasonOptions.stepSummary = stepSummary;
-            if (isConclusion !== undefined)
-                reasonOptions.isConclusion = isConclusion;
-            if (rollbackToStep !== undefined)
-                reasonOptions.rollbackToStep = rollbackToStep;
-        }
-        if (activeSessionId !== undefined) {
-            reasonOptions.sessionId = activeSessionId;
-        }
-        if (targetThoughts !== undefined) {
-            reasonOptions.targetThoughts = targetThoughts;
-        }
         session = await reason(queryText, level, reasonOptions);
         activeSessionId = session.id;
         if (shouldStopReasoningLoop(session, runMode)) {
@@ -263,7 +243,7 @@ function buildStructuredResult(session, generatedThoughts, targetThoughts) {
             sessionId: session.id,
             level: session.level,
             status: session.status,
-            thoughts: session.thoughts,
+            thoughts: [...session.thoughts],
             generatedThoughts,
             requestedThoughts,
             totalThoughts: session.totalThoughts,
@@ -280,10 +260,10 @@ function buildStructuredResult(session, generatedThoughts, targetThoughts) {
 }
 function buildSummary(session, remainingThoughts) {
     if (session.status === 'completed') {
-        return `Reasoning complete. ${String(session.thoughts.length)} thoughts produced at level "${session.level}". Session ${session.id}.`;
+        return `Reasoning complete — ${String(session.thoughts.length)} thoughts at [${session.level}] level. Session ${session.id}.`;
     }
     if (session.status === 'cancelled') {
-        return `Session cancelled at thought ${String(session.thoughts.length)}/${String(session.totalThoughts)}. Session ${session.id}.`;
+        return `Reasoning cancelled at thought ${String(session.thoughts.length)}/${String(session.totalThoughts)}. Session ${session.id}.`;
     }
     const recentSummaries = session.thoughts
         .filter((t) => t.stepSummary)
@@ -301,7 +281,7 @@ function buildSummary(session, remainingThoughts) {
     else if (progress < 0.7) {
         prompt = 'Formulate and critique hypotheses based on the facts.';
     }
-    return (`CONTINUE: ${prompt} Call reasoning_think with { sessionId: "${session.id}", level: "${session.level}", thought: "<your next reasoning step>" }. ` +
+    return (`CONTINUE: ${prompt} Call reasoning_think with { sessionId: "${session.id}", thought: "<your next reasoning step>" }. ` +
         `${summaryText}Progress: ${String(session.thoughts.length)}/${String(session.totalThoughts)} thoughts, ${String(remainingThoughts)} remaining.`);
 }
 async function emitLog(server, level, data, sessionId) {
@@ -320,16 +300,22 @@ function createCancellationController(signal) {
     const controller = new AbortController();
     if (signal.aborted) {
         controller.abort();
-        return controller;
+        return {
+            controller,
+            cleanup: () => {
+                // No listener to clean up when already aborted.
+            },
+        };
     }
     const onAbort = () => {
         controller.abort();
     };
-    signal.addEventListener('abort', onAbort, { once: true });
-    controller.signal.addEventListener('abort', () => {
+    const cleanup = () => {
         signal.removeEventListener('abort', onAbort);
-    }, { once: true });
-    return controller;
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    controller.signal.addEventListener('abort', cleanup, { once: true });
+    return { controller, cleanup };
 }
 async function isTaskCancelled(taskStore, taskId) {
     try {
@@ -343,12 +329,12 @@ async function isTaskCancelled(taskStore, taskId) {
 async function ensureTaskIsActive(taskStore, taskId, controller) {
     if (await isTaskCancelled(taskStore, taskId)) {
         controller.abort();
-        throw new Error('Reasoning task cancelled');
+        throw new ReasoningAbortedError('Reasoning task cancelled');
     }
 }
 function createProgressHandler(args) {
     const { server, taskStore, taskId, level, progressToken, controller, startingCount, batchTotal, } = args;
-    return async (progress, total) => {
+    return async (progress, _total, summary) => {
         await ensureTaskIsActive(taskStore, taskId, controller);
         if (progressToken === undefined) {
             return;
@@ -359,26 +345,25 @@ function createProgressHandler(args) {
         const isTerminal = displayProgress >= batchTotal;
         // We must emit if it's the terminal update for this batch,
         // otherwise we respect the session-level skipping rules.
-        if (!isTerminal && !shouldEmitProgress(progress, total, level)) {
+        // If a summary is provided, we force an emit to show the meaningful update.
+        if (!isTerminal &&
+            !summary &&
+            !shouldEmitProgress(displayProgress, batchTotal, level)) {
             return;
         }
-        const message = isTerminal
-            ? `.𖦹°‧ reasoning_think: [${String(total)}/${String(total)}] • done`
-            : `.𖦹°‧ reasoning_think: [${String(progress)}/${String(total)}]`;
-        try {
-            await server.server.notification({
-                method: 'notifications/progress',
-                params: {
-                    progressToken,
-                    progress: displayProgress,
-                    total: batchTotal,
-                    message,
-                },
-            });
-        }
-        catch {
-            // Ignore notification errors
-        }
+        const message = formatProgressMessage({
+            toolName: `꩜ ${TOOL_NAME}`,
+            context: 'Thought',
+            metadata: `[${String(displayProgress)}/${String(batchTotal)}]${summary ? ` ${summary}` : ''}`,
+            ...(isTerminal ? { outcome: 'complete' } : {}),
+        });
+        await notifyProgress({
+            server,
+            progressToken,
+            progress: displayProgress,
+            total: batchTotal,
+            message,
+        });
     };
 }
 async function storeTaskFailure(taskStore, taskId, response) {
@@ -410,31 +395,29 @@ async function notifyTaskStatus(server, taskId, status) {
 }
 function assertRunToCompletionInputCount(params, thoughtInputs) {
     const { sessionId, targetThoughts } = params;
-    if (sessionId === undefined && targetThoughts === undefined) {
-        throw new Error('targetThoughts is required for run_to_completion when sessionId is not provided');
+    if (!sessionId && !targetThoughts) {
+        throw new InvalidRunModeArgsError('targetThoughts is required for run_to_completion when sessionId is not provided');
     }
     let requiredInputs = targetThoughts ?? 0;
-    if (sessionId !== undefined) {
+    if (sessionId) {
         const existing = sessionStore.get(sessionId);
         if (!existing) {
-            throw new Error(`Session not found: ${sessionId}`);
+            throw new SessionNotFoundError(sessionId);
         }
         requiredInputs = Math.max(0, existing.totalThoughts - existing.thoughts.length);
     }
     if (thoughtInputs.length < requiredInputs) {
-        throw new Error(`run_to_completion requires at least ${String(requiredInputs)} thought inputs; received ${String(thoughtInputs.length)}`);
+        throw new InsufficientThoughtsError(`run_to_completion requires at least ${String(requiredInputs)} thought inputs; received ${String(thoughtInputs.length)}`);
     }
 }
 function getActionableMessage(errorCode, originalMessage) {
     switch (errorCode) {
-        case 'E_SESSION_LEVEL_MISMATCH':
-            return `${originalMessage} ACTION REQUIRED: Re-call reasoning_think with the correct level matching the session.`;
         case 'E_INVALID_THOUGHT_COUNT':
-            return `${originalMessage} ACTION REQUIRED: Ensure targetThoughts is within the level's range.`;
+            return `${originalMessage} Fix: set targetThoughts within the level range (basic 3–5, normal 6–10, high 15–25).`;
         case 'E_INSUFFICIENT_THOUGHTS':
-            return `${originalMessage} ACTION REQUIRED: Provide enough thoughts for run_to_completion or switch to step mode.`;
+            return `${originalMessage} Fix: provide enough thought inputs for the remaining steps, or use runMode: "step".`;
         case 'E_INVALID_RUN_MODE_ARGS':
-            return `${originalMessage} ACTION REQUIRED: Provide targetThoughts when starting a new session in run_to_completion mode.`;
+            return `${originalMessage} Fix: set targetThoughts when starting a new session with runMode: "run_to_completion".`;
         default:
             return originalMessage;
     }
@@ -442,10 +425,13 @@ function getActionableMessage(errorCode, originalMessage) {
 async function handleTaskFailure(args) {
     const { server, taskStore, taskId, sessionId, error } = args;
     const originalMessage = getErrorMessage(error);
-    const errorCode = mapReasoningErrorCode(originalMessage);
+    const errorCode = getReasoningErrorCode(error);
     const message = getActionableMessage(errorCode, originalMessage);
     const response = createErrorResponse(errorCode, message);
     if (await isTaskCancelled(taskStore, taskId)) {
+        if (sessionId) {
+            sessionStore.markCancelled(sessionId);
+        }
         await emitLog(server, 'notice', { event: 'task_cancelled', taskId, reason: message }, sessionId);
         return;
     }
@@ -466,9 +452,10 @@ async function handleTaskFailure(args) {
 async function runReasoningTask(args) {
     const { server, taskStore, taskId, params, progressToken, controller, sessionId, } = args;
     const { query, level, targetThoughts } = params;
-    const runMode = resolveRunMode(params);
+    const runMode = params.runMode ?? 'step';
     const thoughtInputs = buildThoughtInputs(params);
     const queryText = query ?? '';
+    let resolvedSessionId = params.sessionId ?? sessionId;
     await emitLog(server, 'info', {
         event: 'task_started',
         taskId,
@@ -477,7 +464,7 @@ async function runReasoningTask(args) {
         hasSessionId: params.sessionId !== undefined,
         targetThoughts: targetThoughts ?? null,
         thoughtInputs: thoughtInputs.length,
-    }, sessionId);
+    }, resolvedSessionId);
     try {
         if (runMode === 'run_to_completion') {
             assertRunToCompletionInputCount(params, thoughtInputs);
@@ -492,23 +479,20 @@ async function runReasoningTask(args) {
                 params.rollback_to_step !== undefined)) {
             batchTotal = 1;
         }
+        const normalizedBatchTotal = Math.max(1, batchTotal);
         if (progressToken !== undefined) {
-            try {
-                await server.server.notification({
-                    method: 'notifications/progress',
-                    params: {
-                        progressToken,
-                        progress: 0,
-                        total: Math.max(1, batchTotal),
-                        message: level !== undefined
-                            ? `reasoning_think: starting [${level}]`
-                            : 'reasoning_think: continuing session',
-                    },
-                });
-            }
-            catch {
-                // Ignore notification errors
-            }
+            const message = formatProgressMessage({
+                toolName: `꩜ ${TOOL_NAME}`,
+                context: level ? 'starting' : 'continuing',
+                metadata: level ? `[${level}]` : 'session',
+            });
+            await notifyProgress({
+                server,
+                progressToken,
+                progress: 0,
+                total: normalizedBatchTotal,
+                message,
+            });
         }
         const progressArgs = {
             server,
@@ -517,7 +501,7 @@ async function runReasoningTask(args) {
             level,
             controller,
             startingCount,
-            batchTotal: Math.max(1, batchTotal),
+            batchTotal: normalizedBatchTotal,
         };
         if (progressToken !== undefined) {
             progressArgs.progressToken = progressToken;
@@ -552,8 +536,10 @@ async function runReasoningTask(args) {
         if (params.rollback_to_step !== undefined)
             executeArgs.rollbackToStep = params.rollback_to_step;
         const session = await executeReasoningSteps(executeArgs);
+        resolvedSessionId = session.id;
         if (await isTaskCancelled(taskStore, taskId)) {
-            await emitLog(server, 'notice', { event: 'task_cancelled_before_result', taskId }, sessionId);
+            sessionStore.markCancelled(resolvedSessionId);
+            await emitLog(server, 'notice', { event: 'task_cancelled_before_result', taskId }, resolvedSessionId);
             return;
         }
         const generatedThoughts = Math.max(0, session.thoughts.length - startingCount);
@@ -575,8 +561,8 @@ async function runReasoningTask(args) {
             taskId,
             error,
         };
-        if (sessionId !== undefined) {
-            failureArgs.sessionId = sessionId;
+        if (resolvedSessionId !== undefined) {
+            failureArgs.sessionId = resolvedSessionId;
         }
         await handleTaskFailure(failureArgs);
     }
@@ -588,9 +574,6 @@ function getTaskId(extra) {
     return extra.taskId;
 }
 const TOOL_NAME = 'reasoning_think';
-function withIconMeta(iconMeta) {
-    return iconMeta ? { icons: [iconMeta] } : undefined;
-}
 export function registerReasoningThinkTool(server, iconMeta) {
     server.experimental.tasks.registerToolTask(TOOL_NAME, {
         title: 'Reasoning Think',
@@ -598,17 +581,17 @@ export function registerReasoningThinkTool(server, iconMeta) {
 
 USAGE PATTERN:
 1. Start: { query: "...", level: "basic"|"normal"|"high", thought: "your analysis..." }
-2. Continue: { sessionId: "<from response>", level: "<same level>", thought: "next step..." }
-3. Repeat step 2 until response shows status: "completed"
+2. Continue: { sessionId: "<from response>", thought: "next step..." } — level is optional; session level is used
+3. Repeat until status: "completed" — the summary field contains the exact next call to make
 
-IMPORTANT: You MUST pass the returned sessionId on every continuation call, and use the same level throughout.
+IMPORTANT: Pass the returned sessionId on every continuation call.
 The thought parameter stores YOUR reasoning verbatim — write thorough analysis in each step.
-Use step_summary to record a 1-sentence conclusion per step — these accumulate in the summary field for context.
+Use step_summary for a 1-sentence conclusion per step — these accumulate in the summary field for navigation.
 
 Levels: ${getLevelDescriptionString()}.
-Alternative: Use runMode="run_to_completion" with thought + thoughts[] to submit all steps in one call.
-Alternative input: Use observation/hypothesis/evaluation fields instead of thought for structured reasoning.
-Error recovery: If E_SESSION_NOT_FOUND, the session expired — start a new session. If E_INVALID_THOUGHT_COUNT, check level ranges.`,
+Alternatives: runMode="run_to_completion" (batch), or observation/hypothesis/evaluation fields (structured).
+Errors: E_SESSION_NOT_FOUND (expired — start new), E_INVALID_THOUGHT_COUNT (check level ranges).
+Protocol validation: malformed task metadata/arguments fail at request level before task start; runtime reasoning failures return tool isError=true payloads.`,
         inputSchema: ReasoningThinkInputSchema,
         outputSchema: ReasoningThinkToolOutputSchema,
         annotations: {
@@ -632,7 +615,7 @@ Error recovery: If E_SESSION_NOT_FOUND, the session expired — start a new sess
             const extra = parseReasoningTaskExtra(rawExtra);
             const progressToken = extra._meta?.progressToken;
             if (!reasoningTaskLimiter.tryAcquire()) {
-                throw new Error(TASK_OVERLOAD_MESSAGE);
+                throw new ServerBusyError();
             }
             let task;
             try {
@@ -645,13 +628,13 @@ Error recovery: If E_SESSION_NOT_FOUND, the session expired — start a new sess
                 reasoningTaskLimiter.release();
                 throw error;
             }
-            const controller = createCancellationController(extra.signal);
+            const cancellation = createCancellationController(extra.signal);
             const runReasoningArgs = {
                 server,
                 taskStore: extra.taskStore,
                 taskId: task.taskId,
                 params,
-                controller,
+                controller: cancellation.controller,
             };
             if (progressToken !== undefined) {
                 runReasoningArgs.progressToken = progressToken;
@@ -660,6 +643,7 @@ Error recovery: If E_SESSION_NOT_FOUND, the session expired — start a new sess
                 runReasoningArgs.sessionId = extra.sessionId;
             }
             void runReasoningTask(runReasoningArgs).finally(() => {
+                cancellation.cleanup();
                 reasoningTaskLimiter.release();
             });
             return { task };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/cortex-mcp",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "mcpName": "io.github.j0hanz/cortex-mcp",
   "author": "Johanz",
   "license": "MIT",