@j0hanz/cortex-mcp 1.2.1 → 1.4.0

package/README.md

@@ -98,7 +98,7 @@ Add to `~/.cursor/mcp.json`:
 
 ### Tools
 
-#### `reasoning.think`
+#### `reasoning_think`
 
 Perform multi-step reasoning on a query with a selected depth level.
 
@@ -137,7 +137,7 @@ Perform multi-step reasoning on a query with a selected depth level.
 
 ### Tasks
 
-Task-augmented tool calls are supported for `reasoning.think`. Use `tools/call` with task support to run long-running reasoning sessions asynchronously.
+Task-augmented tool calls are supported for `reasoning_think`. Use `tools/call` with task support to run long-running reasoning sessions asynchronously.
 
 ## Configuration
 

package/dist/engine/config.d.ts

@@ -1,4 +1,4 @@
-import type { ReasoningLevel } from '../lib/types.js';
+import type { LevelConfig, ReasoningLevel } from '../lib/types.js';
 export declare const LEVEL_CONFIGS: {
     readonly basic: {
         readonly minThoughts: 3;
@@ -16,5 +16,6 @@ export declare const LEVEL_CONFIGS: {
         readonly tokenBudget: 32768;
     };
 };
+export declare function getLevelConfig(level: ReasoningLevel): LevelConfig;
 export declare function assertTargetThoughtsInRange(level: ReasoningLevel, targetThoughts: number): void;
-//# sourceMappingURL=config.d.ts.map
+export declare function getLevelDescriptionString(): string;

package/dist/engine/config.js

@@ -4,10 +4,21 @@ export const LEVEL_CONFIGS = {
     normal: { minThoughts: 6, maxThoughts: 10, tokenBudget: 8192 },
     high: { minThoughts: 15, maxThoughts: 25, tokenBudget: 32768 },
 };
+export function getLevelConfig(level) {
+    return LEVEL_CONFIGS[level];
+}
 export function assertTargetThoughtsInRange(level, targetThoughts) {
-    const error = getTargetThoughtsError(level, targetThoughts);
-    if (error) {
-        throw new Error(error);
+    const errorMessage = getTargetThoughtsError(level, targetThoughts);
+    if (!errorMessage) {
+        return;
     }
+    throw new Error(errorMessage);
+}
+export function getLevelDescriptionString() {
+    return Object.entries(LEVEL_CONFIGS)
+        .map(([level, config]) => {
+        const budgetK = Math.round(config.tokenBudget / 1024);
+        return `${level} (${config.minThoughts}–${config.maxThoughts} steps, ${budgetK}K budget)`;
+    })
+        .join(', ');
 }
-//# sourceMappingURL=config.js.map

package/dist/engine/context.d.ts

@@ -1,7 +1,6 @@
-interface EngineContext {
-    sessionId: string;
-    abortSignal?: AbortSignal;
+export interface EngineContext {
+    readonly sessionId: string;
+    readonly abortSignal?: AbortSignal;
 }
 export declare function runWithContext<T>(ctx: EngineContext, fn: () => T): T;
-export {};
-//# sourceMappingURL=context.d.ts.map
+export declare function getContext(): EngineContext | undefined;

package/dist/engine/context.js

@@ -3,4 +3,6 @@ const storage = new AsyncLocalStorage();
 export function runWithContext(ctx, fn) {
     return storage.run(ctx, fn);
 }
-//# sourceMappingURL=context.js.map
+export function getContext() {
+    return storage.getStore();
+}

package/dist/engine/events.d.ts

@@ -1,5 +1,12 @@
 import { EventEmitter } from 'node:events';
 import type { ReasoningLevel } from '../lib/types.js';
+interface ThoughtBudgetExhaustedPayload {
+    sessionId: string;
+    tokensUsed: number;
+    tokenBudget: number;
+    generatedThoughts: number;
+    requestedThoughts: number;
+}
 interface EngineEvents {
     'thought:added': [{
         sessionId: string;
@@ -14,15 +21,7 @@ interface EngineEvents {
             revision: number;
         }
     ];
-    'thought:budget-exhausted': [
-        {
-            sessionId: string;
-            tokensUsed: number;
-            tokenBudget: number;
-            generatedThoughts: number;
-            requestedThoughts: number;
-        }
-    ];
+    'thought:budget-exhausted': [ThoughtBudgetExhaustedPayload];
     'session:created': [{
         sessionId: string;
         level: ReasoningLevel;
@@ -52,4 +51,3 @@ interface TypedEmitter<T> extends Omit<EventEmitter, 'on' | 'off' | 'emit'> {
 }
 export declare const engineEvents: TypedEmitter<EngineEvents>;
 export {};
-//# sourceMappingURL=events.d.ts.map

package/dist/engine/events.js

@@ -1,9 +1,11 @@
 import { EventEmitter } from 'node:events';
 import { getErrorMessage } from '../lib/errors.js';
+const ENGINE_ERROR_LOG_PREFIX = '[engine]';
+const ENGINE_ERROR_PREFIX_WITH_SPACE = `${ENGINE_ERROR_LOG_PREFIX} `;
 export const engineEvents = new EventEmitter({
     captureRejections: true,
 });
-engineEvents.on('error', (err) => {
-    process.stderr.write(`[engine] ${getErrorMessage(err)}\n`);
-});
-//# sourceMappingURL=events.js.map
+function logEngineError(err) {
+    process.stderr.write(`${ENGINE_ERROR_PREFIX_WITH_SPACE}${getErrorMessage(err)}\n`);
+}
+engineEvents.on('error', logEngineError);

package/dist/engine/reasoner.d.ts

@@ -5,9 +5,14 @@ export { sessionStore };
 interface ReasonOptions {
     sessionId?: string;
     targetThoughts?: number;
-    thought: string;
+    thought?: string;
+    observation?: string;
+    hypothesis?: string;
+    evaluation?: string;
+    stepSummary?: string;
+    isConclusion?: boolean;
+    rollbackToStep?: number;
     abortSignal?: AbortSignal;
     onProgress?: (progress: number, total: number) => void | Promise<void>;
 }
 export declare function reason(query: string, level: ReasoningLevel | undefined, options?: ReasonOptions): Promise<Readonly<Session>>;
-//# sourceMappingURL=reasoner.d.ts.map

package/dist/engine/reasoner.js

@@ -1,12 +1,14 @@
 import { Buffer } from 'node:buffer';
 import { createSegmenter } from '../lib/text.js';
-import { assertTargetThoughtsInRange, LEVEL_CONFIGS } from './config.js';
+import { assertTargetThoughtsInRange, getLevelConfig } from './config.js';
 import { runWithContext } from './context.js';
 import { engineEvents } from './events.js';
 import { SessionStore } from './session-store.js';
 const DEFAULT_SESSION_TTL_MS = 30 * 60 * 1000;
 const DEFAULT_MAX_SESSIONS = 100;
 const DEFAULT_MAX_TOTAL_TOKENS = 500_000;
+const NON_WHITESPACE = /\S/u;
+const COMPLEXITY_KEYWORDS = /\b(compare|analy[sz]e|trade[- ]?off|design|plan|critique|evaluate|review|architecture)\b/i;
 function parsePositiveIntEnv(name, fallback, minimum = 1) {
     const raw = process.env[name];
     if (raw === undefined) {
@@ -23,48 +25,57 @@ const sentenceSegmenter = createSegmenter('sentence');
 const sessionLocks = new Map();
 export { sessionStore };
 export async function reason(query, level, options) {
-    if (!options?.thought) {
-        throw new Error('thought is required: provide your reasoning content');
+    const { sessionId, targetThoughts, thought, observation, hypothesis, evaluation, stepSummary, isConclusion, rollbackToStep, abortSignal, onProgress, } = options ?? {};
+    const hasContent = thought !== undefined ||
+        (observation !== undefined &&
+            hypothesis !== undefined &&
+            evaluation !== undefined);
+    if (!hasContent && rollbackToStep === undefined) {
+        throw new Error('Either thought (or observation/hypothesis/evaluation) or rollback_to_step is required');
     }
-    const { sessionId, targetThoughts, thought, abortSignal, onProgress } = options;
     const session = resolveSession(level, sessionId, query, targetThoughts);
-    const config = LEVEL_CONFIGS[session.level];
+    const config = getLevelConfig(session.level);
     const { totalThoughts } = session;
     return runWithContext({ sessionId: session.id, ...(abortSignal ? { abortSignal } : {}) }, () => withSessionLock(session.id, async () => {
         throwIfReasoningAborted(abortSignal);
+        if (rollbackToStep !== undefined) {
+            sessionStore.rollback(session.id, rollbackToStep);
+        }
         const current = getSessionOrThrow(session.id);
-        if (current.tokensUsed >= config.tokenBudget) {
-            emitBudgetExhausted({
-                sessionId: session.id,
-                tokensUsed: current.tokensUsed,
-                tokenBudget: config.tokenBudget,
-                generatedThoughts: 0,
-                requestedThoughts: totalThoughts,
-            });
+        let content = thought;
+        if (!content && observation) {
+            content = `**Observation:** ${observation}\n\n**Hypothesis:** ${hypothesis ?? ''}\n\n**Evaluation:** ${evaluation ?? ''}`;
+        }
+        if (!content) {
+            // Only rollback occurred
+            return current;
+        }
+        if (emitBudgetExhaustedIfNeeded({
+            session: current,
+            tokenBudget: config.tokenBudget,
+            generatedThoughts: 0,
+            requestedThoughts: totalThoughts,
+        })) {
             return current;
         }
         const nextIndex = current.thoughts.length;
-        if (nextIndex >= totalThoughts) {
+        if (nextIndex >= totalThoughts && !isConclusion) {
             return current;
         }
-        const stepContent = thought;
-        const addedThought = sessionStore.addThought(session.id, stepContent);
+        const addedThought = sessionStore.addThought(session.id, content, stepSummary);
         engineEvents.emit('thought:added', {
             sessionId: session.id,
             index: addedThought.index,
             content: addedThought.content,
         });
         const updated = getSessionOrThrow(session.id);
-        if (updated.tokensUsed >= config.tokenBudget) {
-            emitBudgetExhausted({
-                sessionId: session.id,
-                tokensUsed: updated.tokensUsed,
-                tokenBudget: config.tokenBudget,
-                generatedThoughts: addedThought.index + 1,
-                requestedThoughts: totalThoughts,
-            });
-        }
-        if (updated.thoughts.length >= totalThoughts) {
+        emitBudgetExhaustedIfNeeded({
+            session: updated,
+            tokenBudget: config.tokenBudget,
+            generatedThoughts: addedThought.index + 1,
+            requestedThoughts: totalThoughts,
+        });
+        if (isConclusion || updated.thoughts.length >= totalThoughts) {
             sessionStore.markCompleted(session.id);
         }
         if (onProgress) {
@@ -103,25 +114,46 @@ function getSessionOrThrow(sessionId) {
 function emitBudgetExhausted(data) {
     engineEvents.emit('thought:budget-exhausted', data);
 }
+function createBudgetExhaustedPayload(args) {
+    const { session, tokenBudget, generatedThoughts, requestedThoughts } = args;
+    return {
+        sessionId: session.id,
+        tokensUsed: session.tokensUsed,
+        tokenBudget,
+        generatedThoughts,
+        requestedThoughts,
+    };
+}
+function emitBudgetExhaustedIfNeeded(args) {
+    const { session, tokenBudget } = args;
+    if (session.tokensUsed < tokenBudget) {
+        return false;
+    }
+    emitBudgetExhausted(createBudgetExhaustedPayload(args));
+    return true;
+}
+function assertExistingSessionConstraints(existing, level, targetThoughts) {
+    if (level !== undefined && existing.level !== level) {
+        // Warning: ignoring provided level in favor of session level
+    }
+    if (targetThoughts !== undefined &&
+        targetThoughts !== existing.totalThoughts) {
+        throw new Error(`Cannot change targetThoughts on an existing session (current: ${String(existing.totalThoughts)}). Omit targetThoughts or pass ${String(existing.totalThoughts)}.`);
+    }
+}
 function resolveSession(level, sessionId, query, targetThoughts) {
     if (sessionId) {
         const existing = sessionStore.get(sessionId);
         if (!existing) {
             throw new Error(`Session not found: ${sessionId}`);
         }
-        if (level !== undefined && existing.level !== level) {
-            // Warning: ignoring provided level in favor of session level
-        }
-        if (targetThoughts !== undefined &&
-            targetThoughts !== existing.totalThoughts) {
-            throw new Error(`Cannot change targetThoughts on an existing session (current: ${String(existing.totalThoughts)}). Omit targetThoughts or pass ${String(existing.totalThoughts)}.`);
-        }
+        assertExistingSessionConstraints(existing, level, targetThoughts);
         return existing;
     }
     if (level === undefined) {
         throw new Error('level is required for new sessions');
     }
-    const config = LEVEL_CONFIGS[level];
+    const config = getLevelConfig(level);
     const totalThoughts = resolveThoughtCount(level, query, config, targetThoughts);
     const session = sessionStore.create(level, totalThoughts);
     engineEvents.emit('session:created', {
@@ -143,8 +175,7 @@ function resolveThoughtCount(level, query, config, targetThoughts) {
     const queryByteLength = Buffer.byteLength(queryText, 'utf8');
     const lengthScore = Math.min(1, queryByteLength / 400);
     const structureScore = Math.min(0.4, getStructureDensityScore(queryText));
-    const keywords = /\b(compare|analy[sz]e|trade[- ]?off|design|plan|critique|evaluate|review|architecture)\b/i;
-    const keywordScore = keywords.test(queryText) ? 0.25 : 0;
+    const keywordScore = COMPLEXITY_KEYWORDS.test(queryText) ? 0.25 : 0;
     const score = Math.min(1, lengthScore + structureScore + keywordScore);
     return config.minThoughts + Math.round(span * score);
 }
@@ -154,7 +185,7 @@ function countSentences(queryText) {
     }
     let count = 0;
     for (const sentence of sentenceSegmenter.segment(queryText)) {
-        if (sentence.segment.trim().length > 0) {
+        if (NON_WHITESPACE.test(sentence.segment)) {
             count++;
         }
     }
@@ -165,7 +196,20 @@ function getStructureDensityScore(queryText) {
     if (sentenceCount > 1) {
         return (sentenceCount - 1) * 0.08;
     }
-    const markerMatches = queryText.match(/[?:;,\n]/g)?.length ?? 0;
+    let markerMatches = 0;
+    for (let index = 0; index < queryText.length; index++) {
+        switch (queryText.charCodeAt(index)) {
+            case 63: // ?
+            case 58: // :
+            case 59: // ;
+            case 44: // ,
+            case 10: // \n
+                markerMatches += 1;
+                break;
+            default:
+                break;
+        }
+    }
     return markerMatches * 0.05;
 }
 function throwIfReasoningAborted(signal) {
@@ -179,4 +223,3 @@ function throwIfReasoningAborted(signal) {
         throw new Error('Reasoning aborted');
     }
 }
-//# sourceMappingURL=reasoner.js.map

package/dist/engine/session-store.d.ts

@@ -1,4 +1,4 @@
-import type { ReasoningLevel, Session, Thought } from '../lib/types.js';
+import type { ReasoningLevel, Session, SessionSummary, Thought } from '../lib/types.js';
 export declare class SessionStore {
     private readonly sessions;
     private readonly sessionOrder;
@@ -13,15 +13,20 @@ export declare class SessionStore {
     constructor(ttlMs?: number, maxSessions?: number, maxTotalTokens?: number);
     create(level: ReasoningLevel, totalThoughts?: number): Readonly<Session>;
     get(id: string): Readonly<Session> | undefined;
+    getSummary(id: string): Readonly<SessionSummary> | undefined;
     list(): Readonly<Session>[];
+    listSessionIds(): readonly string[];
+    listSummaries(): readonly SessionSummary[];
     getTtlMs(): number;
     getExpiresAt(sessionId: string): number | undefined;
     getTotalTokensUsed(): number;
     delete(id: string): boolean;
-    addThought(sessionId: string, content: string): Thought;
+    addThought(sessionId: string, content: string, stepSummary?: string): Thought;
+    rollback(sessionId: string, toIndex: number): void;
     reviseThought(sessionId: string, thoughtIndex: number, content: string): Thought;
     markCompleted(sessionId: string): void;
     markCancelled(sessionId: string): void;
+    private updateSessionStatus;
     private evictIfAtCapacity;
     private evictForTokenHeadroom;
     private findOldestSession;
@@ -30,11 +35,17 @@ export declare class SessionStore {
     private addToOrder;
     private touchOrder;
     private removeFromOrder;
+    private setNextId;
+    private setPrevId;
     private deleteSessionInternal;
+    private markSessionTouched;
+    private getSessionIdsForIteration;
     private snapshotThought;
     private snapshotSession;
+    private snapshotSessionSummary;
     private emitSessionsListChanged;
     private emitSessionsResourceUpdated;
+    private emitSessionsCollectionUpdated;
+    private emitSessionEvicted;
     private emitSessionResourcesUpdated;
 }
-//# sourceMappingURL=session-store.d.ts.map