@j0hanz/cortex-mcp 1.2.1 → 1.4.0

package/dist/engine/session-store.js

@@ -1,13 +1,19 @@
 import { Buffer } from 'node:buffer';
 import { randomUUID } from 'node:crypto';
-import { LEVEL_CONFIGS } from './config.js';
+import { getLevelConfig } from './config.js';
 import { engineEvents } from './events.js';
 const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 minutes
 const DEFAULT_MAX_SESSIONS = 100;
 const DEFAULT_MAX_TOTAL_TOKENS = 500_000;
+const TOKEN_ESTIMATE_DIVISOR = 4;
+const MIN_SWEEP_INTERVAL_MS = 10;
+const MAX_SWEEP_INTERVAL_MS = 60_000;
 function estimateTokens(text) {
     const byteLength = Buffer.byteLength(text, 'utf8');
-    return Math.max(1, Math.ceil(byteLength / 4));
+    return Math.max(1, Math.ceil(byteLength / TOKEN_ESTIMATE_DIVISOR));
+}
+function resolveSweepInterval(ttlMs) {
+    return Math.max(MIN_SWEEP_INTERVAL_MS, Math.min(MAX_SWEEP_INTERVAL_MS, ttlMs));
 }
 export class SessionStore {
     sessions = new Map();
@@ -24,7 +30,7 @@ export class SessionStore {
         this.ttlMs = ttlMs;
         this.maxSessions = maxSessions;
         this.maxTotalTokens = maxTotalTokens;
-        const sweepInterval = Math.max(10, Math.min(60_000, ttlMs));
+        const sweepInterval = resolveSweepInterval(ttlMs);
         this.cleanupInterval = setInterval(() => {
             this.sweep();
         }, sweepInterval);
@@ -32,7 +38,7 @@ export class SessionStore {
     }
     create(level, totalThoughts) {
         this.evictIfAtCapacity();
-        const config = LEVEL_CONFIGS[level];
+        const config = getLevelConfig(level);
         const now = Date.now();
         const session = {
             id: randomUUID(),
@@ -56,10 +62,13 @@ export class SessionStore {
         const session = this.sessions.get(id);
         return session ? this.snapshotSession(session) : undefined;
     }
+    getSummary(id) {
+        const session = this.sessions.get(id);
+        return session ? this.snapshotSessionSummary(session) : undefined;
+    }
     list() {
-        this.sortedSessionIdsCache ??= this.buildSortedSessionIdsCache();
         const sessions = [];
-        for (const sessionId of this.sortedSessionIdsCache) {
+        for (const sessionId of this.getSessionIdsForIteration()) {
             const session = this.sessions.get(sessionId);
             if (session) {
                 sessions.push(this.snapshotSession(session));
@@ -67,6 +76,20 @@ export class SessionStore {
         }
         return sessions;
     }
+    listSessionIds() {
+        this.sortedSessionIdsCache ??= this.buildSortedSessionIdsCache();
+        return [...this.sortedSessionIdsCache];
+    }
+    listSummaries() {
+        const summaries = [];
+        for (const sessionId of this.getSessionIdsForIteration()) {
+            const session = this.sessions.get(sessionId);
+            if (session) {
+                summaries.push(this.snapshotSessionSummary(session));
+            }
+        }
+        return summaries;
+    }
     getTtlMs() {
         return this.ttlMs;
     }
@@ -86,11 +109,10 @@ export class SessionStore {
             return false;
         }
         engineEvents.emit('session:deleted', { sessionId: id });
-        this.emitSessionsListChanged();
-        this.emitSessionsResourceUpdated();
+        this.emitSessionsCollectionUpdated();
         return true;
     }
-    addThought(sessionId, content) {
+    addThought(sessionId, content, stepSummary) {
         const session = this.sessions.get(sessionId);
         if (!session) {
             throw new Error(`Session not found: ${sessionId}`);
@@ -101,16 +123,34 @@ export class SessionStore {
             index: session.thoughts.length,
             content,
             revision: 0,
+            ...(stepSummary !== undefined ? { stepSummary } : {}),
         };
         session.thoughts.push(thought);
         session.tokensUsed += tokens;
         this.totalTokens += tokens;
-        session.updatedAt = Date.now();
-        this.touchOrder(session.id);
-        this.sortedSessionIdsCache = null;
-        this.emitSessionResourcesUpdated(sessionId);
+        this.markSessionTouched(session);
         return this.snapshotThought(thought);
     }
+    rollback(sessionId, toIndex) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        // If toIndex is out of bounds or implies no change, return.
+        // We keep thoughts up to and including toIndex.
+        if (toIndex < 0 || toIndex >= session.thoughts.length - 1) {
+            return;
+        }
+        const removedThoughts = session.thoughts.slice(toIndex + 1);
+        session.thoughts = session.thoughts.slice(0, toIndex + 1);
+        let removedTokens = 0;
+        for (const t of removedThoughts) {
+            removedTokens += estimateTokens(t.content);
+        }
+        session.tokensUsed -= removedTokens;
+        this.totalTokens -= removedTokens;
+        this.markSessionTouched(session);
+    }
     reviseThought(sessionId, thoughtIndex, content) {
         const session = this.sessions.get(sessionId);
         if (!session) {
@@ -134,30 +174,20 @@ export class SessionStore {
         session.thoughts[thoughtIndex] = revised;
         session.tokensUsed = session.tokensUsed - oldTokens + newTokens;
         this.totalTokens += delta;
-        session.updatedAt = Date.now();
-        this.touchOrder(session.id);
-        this.sortedSessionIdsCache = null;
-        this.emitSessionResourcesUpdated(sessionId);
+        this.markSessionTouched(session);
         return this.snapshotThought(revised);
     }
     markCompleted(sessionId) {
-        const session = this.sessions.get(sessionId);
-        if (session?.status === 'active') {
-            session.status = 'completed';
-            session.updatedAt = Date.now();
-            this.touchOrder(session.id);
-            this.sortedSessionIdsCache = null;
-            this.emitSessionResourcesUpdated(sessionId);
-        }
+        this.updateSessionStatus(sessionId, 'completed');
     }
     markCancelled(sessionId) {
+        this.updateSessionStatus(sessionId, 'cancelled');
+    }
+    updateSessionStatus(sessionId, status) {
         const session = this.sessions.get(sessionId);
         if (session?.status === 'active') {
-            session.status = 'cancelled';
-            session.updatedAt = Date.now();
-            this.touchOrder(session.id);
-            this.sortedSessionIdsCache = null;
-            this.emitSessionResourcesUpdated(sessionId);
+            session.status = status;
+            this.markSessionTouched(session);
         }
     }
     evictIfAtCapacity() {
@@ -166,12 +196,7 @@ export class SessionStore {
             if (!oldest)
                 break;
             this.deleteSessionInternal(oldest.id);
-            engineEvents.emit('session:evicted', {
-                sessionId: oldest.id,
-                reason: 'max_sessions',
-            });
-            this.emitSessionsListChanged();
-            this.emitSessionsResourceUpdated();
+            this.emitSessionEvicted(oldest.id, 'max_sessions');
         }
     }
     evictForTokenHeadroom(neededTokens, protectedSessionId) {
@@ -181,12 +206,7 @@ export class SessionStore {
             if (!oldest)
                 break;
             this.deleteSessionInternal(oldest.id);
-            engineEvents.emit('session:evicted', {
-                sessionId: oldest.id,
-                reason: 'max_total_tokens',
-            });
-            this.emitSessionsListChanged();
-            this.emitSessionsResourceUpdated();
+            this.emitSessionEvicted(oldest.id, 'max_total_tokens');
         }
     }
     findOldestSession(excludeId) {
@@ -201,23 +221,26 @@ export class SessionStore {
     }
     sweep() {
         const now = Date.now();
-        const expiredSessionIds = [];
         let changed = false;
-        for (const session of this.sessions.values()) {
-            if (session.updatedAt + this.ttlMs < now) {
-                expiredSessionIds.push(session.id);
-            }
-        }
-        for (const sessionId of expiredSessionIds) {
-            if (!this.deleteSessionInternal(sessionId)) {
+        let currentId = this.oldestSessionId;
+        while (currentId) {
+            const nextId = this.sessionOrder.get(currentId)?.nextId;
+            const session = this.sessions.get(currentId);
+            if (!session) {
+                currentId = nextId;
                 continue;
             }
-            engineEvents.emit('session:expired', { sessionId });
-            changed = true;
+            if (session.updatedAt + this.ttlMs >= now) {
+                break;
+            }
+            if (this.deleteSessionInternal(currentId)) {
+                engineEvents.emit('session:expired', { sessionId: currentId });
+                changed = true;
+            }
+            currentId = nextId;
         }
         if (changed) {
-            this.emitSessionsListChanged();
-            this.emitSessionsResourceUpdated();
+            this.emitSessionsCollectionUpdated();
         }
     }
     buildSortedSessionIdsCache() {
@@ -238,10 +261,7 @@ export class SessionStore {
         }
         const node = { prevId: undefined, nextId: undefined };
         if (this.newestSessionId) {
-            const newest = this.sessionOrder.get(this.newestSessionId);
-            if (newest) {
-                newest.nextId = sessionId;
-            }
+            this.setNextId(this.newestSessionId, sessionId);
             node.prevId = this.newestSessionId;
         }
         else {
@@ -261,27 +281,18 @@ export class SessionStore {
         }
         const { prevId, nextId } = node;
         if (prevId) {
-            const previous = this.sessionOrder.get(prevId);
-            if (previous) {
-                previous.nextId = nextId;
-            }
+            this.setNextId(prevId, nextId);
         }
         else {
             this.oldestSessionId = nextId;
         }
         if (nextId) {
-            const next = this.sessionOrder.get(nextId);
-            if (next) {
-                next.prevId = prevId;
-            }
+            this.setPrevId(nextId, prevId);
         }
         node.prevId = this.newestSessionId;
         node.nextId = undefined;
         if (this.newestSessionId) {
-            const newest = this.sessionOrder.get(this.newestSessionId);
-            if (newest) {
-                newest.nextId = sessionId;
-            }
+            this.setNextId(this.newestSessionId, sessionId);
         }
         else {
             this.oldestSessionId = sessionId;
@@ -295,25 +306,31 @@ export class SessionStore {
         }
         const { prevId, nextId } = node;
         if (prevId) {
-            const previous = this.sessionOrder.get(prevId);
-            if (previous) {
-                previous.nextId = nextId;
-            }
+            this.setNextId(prevId, nextId);
         }
         else {
             this.oldestSessionId = nextId;
         }
         if (nextId) {
-            const next = this.sessionOrder.get(nextId);
-            if (next) {
-                next.prevId = prevId;
-            }
+            this.setPrevId(nextId, prevId);
         }
         else {
             this.newestSessionId = prevId;
         }
         this.sessionOrder.delete(sessionId);
     }
+    setNextId(sessionId, nextId) {
+        const node = this.sessionOrder.get(sessionId);
+        if (node) {
+            node.nextId = nextId;
+        }
+    }
+    setPrevId(sessionId, prevId) {
+        const node = this.sessionOrder.get(sessionId);
+        if (node) {
+            node.prevId = prevId;
+        }
+    }
     deleteSessionInternal(id) {
         const session = this.sessions.get(id);
         if (!session) {
@@ -325,19 +342,46 @@ export class SessionStore {
         this.sortedSessionIdsCache = null;
         return session;
     }
+    markSessionTouched(session) {
+        session.updatedAt = Date.now();
+        this.touchOrder(session.id);
+        this.sortedSessionIdsCache = null;
+        this.emitSessionResourcesUpdated(session.id);
+    }
+    getSessionIdsForIteration() {
+        this.sortedSessionIdsCache ??= this.buildSortedSessionIdsCache();
+        return this.sortedSessionIdsCache;
+    }
     snapshotThought(thought) {
         return {
             index: thought.index,
             content: thought.content,
             revision: thought.revision,
+            ...(thought.stepSummary !== undefined
+                ? { stepSummary: thought.stepSummary }
+                : {}),
         };
     }
     snapshotSession(session) {
+        const thoughts = session.thoughts.map((thought) => this.snapshotThought(thought));
+        return {
+            id: session.id,
+            level: session.level,
+            status: session.status,
+            thoughts,
+            totalThoughts: session.totalThoughts,
+            tokenBudget: session.tokenBudget,
+            tokensUsed: session.tokensUsed,
+            createdAt: session.createdAt,
+            updatedAt: session.updatedAt,
+        };
+    }
+    snapshotSessionSummary(session) {
         return {
             id: session.id,
             level: session.level,
             status: session.status,
-            thoughts: session.thoughts.map((thought) => this.snapshotThought(thought)),
+            generatedThoughts: session.thoughts.length,
             totalThoughts: session.totalThoughts,
             tokenBudget: session.tokenBudget,
             tokensUsed: session.tokensUsed,
@@ -351,6 +395,17 @@ export class SessionStore {
     emitSessionsResourceUpdated() {
         engineEvents.emit('resource:updated', { uri: 'reasoning://sessions' });
     }
+    emitSessionsCollectionUpdated() {
+        this.emitSessionsListChanged();
+        this.emitSessionsResourceUpdated();
+    }
+    emitSessionEvicted(sessionId, reason) {
+        engineEvents.emit('session:evicted', {
+            sessionId,
+            reason,
+        });
+        this.emitSessionsCollectionUpdated();
+    }
     emitSessionResourcesUpdated(sessionId) {
         engineEvents.emit('resource:updated', {
             uri: `reasoning://sessions/${sessionId}`,
@@ -358,4 +413,3 @@ export class SessionStore {
         this.emitSessionsResourceUpdated();
     }
 }
-//# sourceMappingURL=session-store.js.map

package/dist/index.d.ts

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -2,6 +2,8 @@
 import { isMainThread, threadId } from 'node:worker_threads';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createServer } from './server.js';
+const FATAL_SHUTDOWN_REASON = 'fatal error';
+const SHUTDOWN_SIGNALS = ['SIGTERM', 'SIGINT'];
 let activeServer;
 let shutdownPromise;
 function assertMainThread() {
@@ -16,6 +18,11 @@ async function main() {
     const transport = new StdioServerTransport();
     await activeServer.connect(transport);
 }
+function registerShutdownSignals() {
+    for (const signal of SHUTDOWN_SIGNALS) {
+        registerShutdownSignal(signal);
+    }
+}
 async function shutdown(exitCode, reason) {
     if (shutdownPromise) {
         return shutdownPromise;
@@ -35,14 +42,13 @@ async function shutdown(exitCode, reason) {
     })();
     return shutdownPromise;
 }
+function registerShutdownSignal(signal) {
+    process.once(signal, () => {
+        void shutdown(0, signal);
+    });
+}
+registerShutdownSignals();
 main().catch((err) => {
     console.error('Fatal error:', err);
-    void shutdown(1, 'fatal error');
-});
-process.once('SIGTERM', () => {
-    void shutdown(0, 'SIGTERM');
-});
-process.once('SIGINT', () => {
-    void shutdown(0, 'SIGINT');
+    void shutdown(1, FATAL_SHUTDOWN_REASON);
 });
-//# sourceMappingURL=index.js.map

package/dist/lib/errors.d.ts

@@ -16,4 +16,3 @@ interface ErrorResponse {
 export declare function getErrorMessage(error: unknown): string;
 export declare function createErrorResponse(code: string, message: string): ErrorResponse;
 export {};
-//# sourceMappingURL=errors.d.ts.map

package/dist/lib/errors.js

@@ -3,6 +3,10 @@ const INSPECT_OPTIONS = {
     depth: 3,
     breakLength: 120,
 };
+const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
 function stringifyUnknown(value) {
     try {
         return JSON.stringify(value);
@@ -12,6 +16,12 @@ function stringifyUnknown(value) {
     }
     return inspect(value, INSPECT_OPTIONS);
 }
+function getMessageFromErrorLike(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    return typeof value.message === 'string' ? value.message : undefined;
+}
 export function getErrorMessage(error) {
     if (typeof error === 'string') {
         return error;
@@ -20,22 +30,20 @@ export function getErrorMessage(error) {
         return error.message;
     }
     if (error === null || error === undefined) {
-        return 'Unknown error';
+        return UNKNOWN_ERROR_MESSAGE;
     }
-    if (typeof error === 'object') {
-        const maybeError = error;
-        if (typeof maybeError.message === 'string') {
-            return maybeError.message;
-        }
+    const errorLikeMessage = getMessageFromErrorLike(error);
+    if (errorLikeMessage !== undefined) {
+        return errorLikeMessage;
     }
     return stringifyUnknown(error);
 }
 export function createErrorResponse(code, message) {
     const structured = { ok: false, error: { code, message } };
+    const text = JSON.stringify(structured);
     return {
-        content: [{ type: 'text', text: JSON.stringify(structured) }],
+        content: [{ type: 'text', text }],
         structuredContent: structured,
         isError: true,
     };
 }
-//# sourceMappingURL=errors.js.map

package/dist/lib/formatting.d.ts

@@ -30,4 +30,3 @@ export declare function formatThoughtsToMarkdown(session: Readonly<Session>, ran
     start: number;
     end: number;
 }): string;
-//# sourceMappingURL=formatting.d.ts.map

package/dist/lib/formatting.js

@@ -3,6 +3,8 @@
 // ---------------------------------------------------------------------------
 const PIN_START = '<!-- pin:';
 const PIN_END = '<!-- /pin -->';
+const TRACE_SEPARATOR = '\n\n---\n\n';
+const PINNED_SECTION_TITLE = '## 📌 Pinned';
 /**
  * Extract pinned sections from thought content.
  *
@@ -18,28 +20,31 @@ const PIN_END = '<!-- /pin -->';
 export function extractPinnedSections(thoughts) {
     const byTitle = new Map();
     for (const thought of thoughts) {
+        const { content } = thought;
         let searchFrom = 0;
-        while (searchFrom < thought.content.length) {
-            const startIdx = thought.content.indexOf(PIN_START, searchFrom);
+        while (searchFrom < content.length) {
+            const startIdx = content.indexOf(PIN_START, searchFrom);
             if (startIdx === -1) {
                 break;
             }
-            const arrowIdx = thought.content.indexOf('-->', startIdx + PIN_START.length);
+            const arrowIdx = content.indexOf('-->', startIdx + PIN_START.length);
             if (arrowIdx === -1) {
                 break;
             }
-            const title = thought.content
-                .slice(startIdx + PIN_START.length, arrowIdx)
-                .trim();
+            const title = content.slice(startIdx + PIN_START.length, arrowIdx).trim();
             const contentStart = arrowIdx + 3;
-            const endIdx = thought.content.indexOf(PIN_END, contentStart);
+            const endIdx = content.indexOf(PIN_END, contentStart);
             if (endIdx === -1) {
                 break;
             }
-            const content = thought.content.slice(contentStart, endIdx).trim();
+            const pinContent = content.slice(contentStart, endIdx).trim();
             searchFrom = endIdx + PIN_END.length;
             if (title.length > 0) {
-                byTitle.set(title, { title, content, thoughtIndex: thought.index });
+                byTitle.set(title, {
+                    title,
+                    content: pinContent,
+                    thoughtIndex: thought.index,
+                });
             }
         }
     }
@@ -52,7 +57,7 @@ function renderPinnedSections(sections) {
     if (sections.length === 0) {
         return '';
     }
-    const lines = ['## 📌 Pinned', ''];
+    const lines = [PINNED_SECTION_TITLE, ''];
     for (const pin of sections) {
         lines.push(`### ${pin.title} *(Thought ${String(pin.thoughtIndex + 1)})*`);
         if (pin.content.length > 0) {
@@ -70,6 +75,17 @@ function formatThoughtHeading(thought) {
     const suffix = thought.revision > 0 ? ' [Revised]' : '';
     return `𖦹 Thought [${String(thoughtNumber)}]${suffix}`;
 }
+function renderThoughtSection(thought) {
+    return `${formatThoughtHeading(thought)}\n\n${thought.content}`;
+}
+function selectThoughts(allThoughts, range) {
+    if (!range) {
+        return allThoughts;
+    }
+    const startIndex = Math.max(0, range.start - 1);
+    const endIndex = Math.min(allThoughts.length, range.end);
+    return allThoughts.slice(startIndex, endIndex);
+}
 /**
  * Format a session's thoughts as Markdown.
  *
@@ -82,23 +98,16 @@ function formatThoughtHeading(thought) {
 export function formatThoughtsToMarkdown(session, range) {
     const { thoughts: allThoughts } = session;
     const isFullTrace = range === undefined;
-    let thoughts;
-    if (range) {
-        const startIndex = Math.max(0, range.start - 1);
-        const endIndex = Math.min(allThoughts.length, range.end);
-        thoughts = allThoughts.slice(startIndex, endIndex);
-    }
-    else {
-        thoughts = allThoughts;
-    }
+    const thoughts = selectThoughts(allThoughts, range);
+    const hasFullTraceThoughts = isFullTrace && thoughts.length > 0;
     const sections = [];
     // --- Header ---
-    if (isFullTrace && thoughts.length > 0) {
+    if (hasFullTraceThoughts) {
         sections.push(`# Reasoning Trace — [${session.level}]\n` +
             `> Session [${session.id}] · [${String(allThoughts.length)}] thoughts`);
     }
     // --- Pinned sections (full trace only) ---
-    if (isFullTrace && thoughts.length > 0) {
+    if (hasFullTraceThoughts) {
         const pinned = extractPinnedSections(thoughts);
         const pinnedMd = renderPinnedSections(pinned);
         if (pinnedMd.length > 0) {
@@ -107,9 +116,7 @@ export function formatThoughtsToMarkdown(session, range) {
     }
     // --- Thought narrative ---
     for (const thought of thoughts) {
-        const heading = formatThoughtHeading(thought);
-        sections.push(`${heading}\n\n${thought.content}`);
+        sections.push(renderThoughtSection(thought));
     }
-    return sections.join('\n\n---\n\n');
+    return sections.join(TRACE_SEPARATOR);
 }
-//# sourceMappingURL=formatting.js.map

package/dist/lib/prompt-contracts.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+export interface PromptArg {
+    name: string;
+    type: z.ZodType;
+    description: string;
+    required: boolean;
+}
+export interface PromptContract {
+    name: string;
+    title: string;
+    description: string;
+    args: PromptArg[];
+}
+export declare function getPromptContracts(): PromptContract[];