@j0hanz/cortex-mcp 1.4.0 → 1.5.0

package/dist/schemas/outputs.js

@@ -1,12 +1,11 @@
 import { z } from 'zod';
+import { REASONING_LEVELS, SESSION_STATUSES } from '../lib/types.js';
 const ErrorInfoSchema = z.strictObject({
     code: z.string(),
     message: z.string(),
 });
 const MISSING_RESULT_PATH = ['result'];
 const MISSING_ERROR_PATH = ['error'];
-const LEVEL_VALUES = ['basic', 'normal', 'high'];
-const STATUS_VALUES = ['active', 'completed', 'cancelled'];
 const ThoughtSchema = z.strictObject({
     index: z.number(),
     content: z.string(),
@@ -16,17 +15,12 @@ const ThoughtSchema = z.strictObject({
         .optional()
         .describe('A 1-sentence summary of the conclusion reached in this step, if provided.'),
 });
-export const DefaultOutputSchema = z.strictObject({
-    ok: z.boolean(),
-    result: z.unknown().optional(),
-    error: ErrorInfoSchema.optional(),
-});
 const ReasoningThinkSuccessSchema = z.strictObject({
     ok: z.literal(true),
     result: z.strictObject({
         sessionId: z.string(),
-        level: z.enum(LEVEL_VALUES),
-        status: z.enum(STATUS_VALUES),
+        level: z.enum(REASONING_LEVELS),
+        status: z.enum(SESSION_STATUSES),
         thoughts: z.array(ThoughtSchema),
         generatedThoughts: z.number(),
         requestedThoughts: z.number(),
@@ -53,10 +47,6 @@ const ReasoningThinkErrorSchema = z.strictObject({
     ok: z.literal(false),
     error: ErrorInfoSchema,
 });
-export const ReasoningThinkResultSchema = z.discriminatedUnion('ok', [
-    ReasoningThinkSuccessSchema,
-    ReasoningThinkErrorSchema,
-]);
 function getMissingFieldIssue(data) {
     if (data.ok && data.result === undefined) {
         return {
@@ -92,3 +82,13 @@ export const ReasoningThinkToolOutputSchema = z
         });
     }
 });
+/** Generic ok/error envelope — useful for contract tests and external validators. */
+export const DefaultOutputSchema = z.union([
+    z.strictObject({ ok: z.literal(true), result: z.unknown() }),
+    z.strictObject({ ok: z.literal(false), error: ErrorInfoSchema }),
+]);
+/** Full discriminated union for the reasoning_think tool result. */
+export const ReasoningThinkResultSchema = z.union([
+    ReasoningThinkSuccessSchema,
+    ReasoningThinkErrorSchema,
+]);

package/dist/server.js

@@ -7,7 +7,6 @@ import { getErrorMessage } from './lib/errors.js';
 import { registerAllTools } from './tools/index.js';
 import { registerAllPrompts } from './prompts/index.js';
 import { registerAllResources } from './resources/index.js';
-import { buildServerInstructions } from './resources/instructions.js';
 const ICON_MIME = 'image/svg+xml';
 const SERVER_NAME = 'cortex-mcp';
 const SERVER_TITLE = 'Cortex MCP';
@@ -147,7 +146,6 @@ function installCloseCleanup(server, cleanup) {
     };
 }
 export function createServer() {
-    const instructions = buildServerInstructions();
     const version = loadVersion();
     const taskStore = new InMemoryTaskStore();
     const localIcon = getLocalIconData();
@@ -180,7 +178,7 @@ export function createServer() {
             },
         },
         taskStore,
-        ...(instructions ? { instructions } : {}),
+        instructions: 'Multi-level reasoning MCP server. Use reasoning_think to decompose queries into sequential thought steps at basic (3–5), normal (6–10), or high (15–25) depth. Full usage guide: read internal://instructions or invoke get-help.',
     });
     registerAllTools(server, iconMeta);
     registerAllPrompts(server, iconMeta);

package/dist/tools/reasoning-think.js

@@ -1,13 +1,13 @@
 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 { 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';
 function buildTraceResource(session) {
     return {
         uri: `file:///cortex/sessions/${session.id}/trace.md`,
@@ -15,37 +15,7 @@ function buildTraceResource(session) {
         text: formatThoughtsToMarkdown(session),
     };
 }
-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 +104,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 +121,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)
@@ -203,6 +171,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 +199,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 +226,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 +243,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 +264,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) {
@@ -343,12 +306,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) => {
         await ensureTaskIsActive(taskStore, taskId, controller);
         if (progressToken === undefined) {
             return;
@@ -359,26 +322,23 @@ 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 (!isTerminal &&
+            !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)}]`,
+            ...(isTerminal ? { outcome: 'complete' } : {}),
+        });
+        await notifyProgress({
+            server,
+            progressToken,
+            progress: displayProgress,
+            total: batchTotal,
+            message,
+        });
     };
 }
 async function storeTaskFailure(taskStore, taskId, response) {
@@ -410,31 +370,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 +400,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 +427,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 +439,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 +454,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: 'reasoning',
+                metadata: level ? `starting [${level}]` : 'continuing session',
+            });
+            await notifyProgress({
+                server,
+                progressToken,
+                progress: 0,
+                total: normalizedBatchTotal,
+                message,
+            });
         }
         const progressArgs = {
             server,
@@ -517,7 +476,7 @@ async function runReasoningTask(args) {
             level,
             controller,
             startingCount,
-            batchTotal: Math.max(1, batchTotal),
+            batchTotal: normalizedBatchTotal,
         };
         if (progressToken !== undefined) {
             progressArgs.progressToken = progressToken;
@@ -552,8 +511,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 +536,8 @@ async function runReasoningTask(args) {
             taskId,
             error,
         };
-        if (sessionId !== undefined) {
-            failureArgs.sessionId = sessionId;
+        if (resolvedSessionId !== undefined) {
+            failureArgs.sessionId = resolvedSessionId;
         }
         await handleTaskFailure(failureArgs);
     }
@@ -588,9 +549,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 +556,16 @@ 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).`,
         inputSchema: ReasoningThinkInputSchema,
         outputSchema: ReasoningThinkToolOutputSchema,
         annotations: {
@@ -632,7 +589,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 {

package/package.json

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