@j0hanz/cortex-mcp 1.4.0 → 1.6.0

package/dist/engine/config.d.ts

@@ -1,19 +1,19 @@
-import type { LevelConfig, ReasoningLevel } from '../lib/types.js';
+import { type LevelConfig, type ReasoningLevel } from '../lib/types.js';
 export declare const LEVEL_CONFIGS: {
     readonly basic: {
+        readonly tokenBudget: 2048;
         readonly minThoughts: 3;
         readonly maxThoughts: 5;
-        readonly tokenBudget: 2048;
     };
     readonly normal: {
+        readonly tokenBudget: 8192;
         readonly minThoughts: 6;
         readonly maxThoughts: 10;
-        readonly tokenBudget: 8192;
     };
     readonly high: {
+        readonly tokenBudget: 32768;
         readonly minThoughts: 15;
         readonly maxThoughts: 25;
-        readonly tokenBudget: 32768;
     };
 };
 export declare function getLevelConfig(level: ReasoningLevel): LevelConfig;

package/dist/engine/config.js

@@ -1,8 +1,10 @@
+import { InvalidThoughtCountError } from '../lib/errors.js';
+import { LEVEL_BOUNDS, } from '../lib/types.js';
 import { getTargetThoughtsError } from '../lib/validators.js';
 export const LEVEL_CONFIGS = {
-    basic: { minThoughts: 3, maxThoughts: 5, tokenBudget: 2048 },
-    normal: { minThoughts: 6, maxThoughts: 10, tokenBudget: 8192 },
-    high: { minThoughts: 15, maxThoughts: 25, tokenBudget: 32768 },
+    basic: { ...LEVEL_BOUNDS.basic, tokenBudget: 2048 },
+    normal: { ...LEVEL_BOUNDS.normal, tokenBudget: 8192 },
+    high: { ...LEVEL_BOUNDS.high, tokenBudget: 32768 },
 };
 export function getLevelConfig(level) {
     return LEVEL_CONFIGS[level];
@@ -12,7 +14,7 @@ export function assertTargetThoughtsInRange(level, targetThoughts) {
     if (!errorMessage) {
         return;
     }
-    throw new Error(errorMessage);
+    throw new InvalidThoughtCountError(errorMessage);
 }
 export function getLevelDescriptionString() {
     return Object.entries(LEVEL_CONFIGS)

package/dist/engine/context.d.ts

@@ -3,4 +3,3 @@ export interface EngineContext {
     readonly abortSignal?: AbortSignal;
 }
 export declare function runWithContext<T>(ctx: EngineContext, fn: () => T): T;
-export declare function getContext(): EngineContext | undefined;

package/dist/engine/context.js

@@ -3,6 +3,3 @@ const storage = new AsyncLocalStorage();
 export function runWithContext(ctx, fn) {
     return storage.run(ctx, fn);
 }
-export function getContext() {
-    return storage.getStore();
-}

package/dist/engine/events.d.ts

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'node:events';
 import type { ReasoningLevel } from '../lib/types.js';
-interface ThoughtBudgetExhaustedPayload {
+export interface ThoughtBudgetExhaustedPayload {
     sessionId: string;
     tokensUsed: number;
     tokenBudget: number;

package/dist/engine/events.js

@@ -1,11 +1,10 @@
 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} `;
+const ENGINE_ERROR_PREFIX = '[engine] ';
 export const engineEvents = new EventEmitter({
     captureRejections: true,
 });
 function logEngineError(err) {
-    process.stderr.write(`${ENGINE_ERROR_PREFIX_WITH_SPACE}${getErrorMessage(err)}\n`);
+    process.stderr.write(`${ENGINE_ERROR_PREFIX}${getErrorMessage(err)}\n`);
 }
 engineEvents.on('error', logEngineError);

package/dist/engine/heuristics.d.ts

@@ -0,0 +1,4 @@
+import type { LevelConfig, ReasoningLevel } from '../lib/types.js';
+export declare function countSentences(queryText: string): number;
+export declare function getStructureDensityScore(queryText: string): number;
+export declare function resolveThoughtCount(level: ReasoningLevel, query: string, config: Pick<LevelConfig, 'minThoughts' | 'maxThoughts'>, targetThoughts?: number): number;

package/dist/engine/heuristics.js

@@ -0,0 +1,65 @@
+import { Buffer } from 'node:buffer';
+import { createSegmenter } from '../lib/text.js';
+import { assertTargetThoughtsInRange } from './config.js';
+const NON_WHITESPACE = /\S/u;
+const COMPLEXITY_KEYWORDS = /\b(compare|analy[sz]e|trade[- ]?off|design|plan|critique|evaluate|review|architecture)\b/i;
+let _sentenceSegmenter;
+let _sentenceSegmenterInitialized = false;
+function getSentenceSegmenter() {
+    if (!_sentenceSegmenterInitialized) {
+        _sentenceSegmenter = createSegmenter('sentence');
+        _sentenceSegmenterInitialized = true;
+    }
+    return _sentenceSegmenter;
+}
+export function countSentences(queryText) {
+    const segmenter = getSentenceSegmenter();
+    if (!segmenter) {
+        return 0;
+    }
+    let count = 0;
+    for (const sentence of segmenter.segment(queryText)) {
+        if (NON_WHITESPACE.test(sentence.segment)) {
+            count++;
+        }
+    }
+    return count;
+}
+export function getStructureDensityScore(queryText) {
+    const sentenceCount = countSentences(queryText);
+    if (sentenceCount > 1) {
+        return (sentenceCount - 1) * 0.08;
+    }
+    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;
+}
+export function resolveThoughtCount(level, query, config, targetThoughts) {
+    if (targetThoughts !== undefined) {
+        assertTargetThoughtsInRange(level, targetThoughts);
+        return targetThoughts;
+    }
+    if (config.minThoughts === config.maxThoughts) {
+        return config.minThoughts;
+    }
+    const queryText = query.trim();
+    const span = config.maxThoughts - config.minThoughts;
+    const queryByteLength = Buffer.byteLength(queryText, 'utf8');
+    const lengthScore = Math.min(1, queryByteLength / 400);
+    const structureScore = Math.min(0.4, getStructureDensityScore(queryText));
+    const keywordScore = COMPLEXITY_KEYWORDS.test(queryText) ? 0.25 : 0;
+    const score = Math.min(1, lengthScore + structureScore + keywordScore);
+    return config.minThoughts + Math.round(span * score);
+}

package/dist/engine/reasoner.d.ts

@@ -13,6 +13,6 @@ interface ReasonOptions {
     isConclusion?: boolean;
     rollbackToStep?: number;
     abortSignal?: AbortSignal;
-    onProgress?: (progress: number, total: number) => void | Promise<void>;
+    onProgress?: (progress: number, total: number, stepSummary?: string) => void | Promise<void>;
 }
 export declare function reason(query: string, level: ReasoningLevel | undefined, options?: ReasonOptions): Promise<Readonly<Session>>;

package/dist/engine/reasoner.js

@@ -1,27 +1,11 @@
-import { Buffer } from 'node:buffer';
-import { createSegmenter } from '../lib/text.js';
-import { assertTargetThoughtsInRange, getLevelConfig } from './config.js';
+import { InvalidRunModeArgsError, ReasoningAbortedError, SessionNotFoundError, } from '../lib/errors.js';
+import { parsePositiveIntEnv } from '../lib/validators.js';
+import { 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) {
-        return fallback;
-    }
-    const parsed = Number.parseInt(raw, 10);
-    if (!Number.isInteger(parsed) || parsed < minimum) {
-        return fallback;
-    }
-    return parsed;
-}
+import { resolveThoughtCount } from './heuristics.js';
+import { DEFAULT_MAX_SESSIONS, DEFAULT_MAX_TOTAL_TOKENS, DEFAULT_SESSION_TTL_MS, SessionStore, } from './session-store.js';
 const sessionStore = new SessionStore(parsePositiveIntEnv('CORTEX_SESSION_TTL_MS', DEFAULT_SESSION_TTL_MS), parsePositiveIntEnv('CORTEX_MAX_SESSIONS', DEFAULT_MAX_SESSIONS), parsePositiveIntEnv('CORTEX_MAX_TOTAL_TOKENS', DEFAULT_MAX_TOTAL_TOKENS));
-const sentenceSegmenter = createSegmenter('sentence');
 const sessionLocks = new Map();
 export { sessionStore };
 export async function reason(query, level, options) {
@@ -31,7 +15,7 @@ export async function reason(query, level, options) {
             hypothesis !== undefined &&
             evaluation !== undefined);
     if (!hasContent && rollbackToStep === undefined) {
-        throw new Error('Either thought (or observation/hypothesis/evaluation) or rollback_to_step is required');
+        throw new InvalidRunModeArgsError('Either thought (or observation/hypothesis/evaluation) or rollback_to_step is required');
     }
     const session = resolveSession(level, sessionId, query, targetThoughts);
     const config = getLevelConfig(session.level);
@@ -69,7 +53,7 @@ export async function reason(query, level, options) {
             content: addedThought.content,
         });
         const updated = getSessionOrThrow(session.id);
-        emitBudgetExhaustedIfNeeded({
+        void emitBudgetExhaustedIfNeeded({
             session: updated,
             tokenBudget: config.tokenBudget,
             generatedThoughts: addedThought.index + 1,
@@ -79,7 +63,7 @@ export async function reason(query, level, options) {
             sessionStore.markCompleted(session.id);
         }
         if (onProgress) {
-            await onProgress(addedThought.index + 1, totalThoughts);
+            await onProgress(addedThought.index + 1, totalThoughts, stepSummary);
             throwIfReasoningAborted(abortSignal);
         }
         return getSessionOrThrow(session.id);
@@ -98,7 +82,7 @@ async function withSessionLock(sessionId, fn) {
         return await fn();
     }
     finally {
-        release?.();
+        release();
         if (sessionLocks.get(sessionId) === currentTail) {
             sessionLocks.delete(sessionId);
         }
@@ -107,51 +91,41 @@ async function withSessionLock(sessionId, fn) {
 function getSessionOrThrow(sessionId) {
     const session = sessionStore.get(sessionId);
     if (!session) {
-        throw new Error(`Session not found: ${sessionId}`);
+        throw new SessionNotFoundError(sessionId);
     }
     return session;
 }
-function emitBudgetExhausted(data) {
-    engineEvents.emit('thought:budget-exhausted', data);
-}
-function createBudgetExhaustedPayload(args) {
+function emitBudgetExhaustedIfNeeded(args) {
     const { session, tokenBudget, generatedThoughts, requestedThoughts } = args;
-    return {
+    if (session.tokensUsed < tokenBudget) {
+        return false;
+    }
+    engineEvents.emit('thought:budget-exhausted', {
         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
-    }
+function assertExistingSessionConstraints(existing, targetThoughts) {
     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)}.`);
+        throw new InvalidRunModeArgsError(`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}`);
+            throw new SessionNotFoundError(sessionId);
         }
-        assertExistingSessionConstraints(existing, level, targetThoughts);
+        assertExistingSessionConstraints(existing, targetThoughts);
         return existing;
     }
     if (level === undefined) {
-        throw new Error('level is required for new sessions');
+        throw new InvalidRunModeArgsError('level is required for new sessions');
     }
     const config = getLevelConfig(level);
     const totalThoughts = resolveThoughtCount(level, query, config, targetThoughts);
@@ -162,56 +136,6 @@ function resolveSession(level, sessionId, query, targetThoughts) {
     });
     return session;
 }
-function resolveThoughtCount(level, query, config, targetThoughts) {
-    if (targetThoughts !== undefined) {
-        assertTargetThoughtsInRange(level, targetThoughts);
-        return targetThoughts;
-    }
-    if (config.minThoughts === config.maxThoughts) {
-        return config.minThoughts;
-    }
-    const queryText = query.trim();
-    const span = config.maxThoughts - config.minThoughts;
-    const queryByteLength = Buffer.byteLength(queryText, 'utf8');
-    const lengthScore = Math.min(1, queryByteLength / 400);
-    const structureScore = Math.min(0.4, getStructureDensityScore(queryText));
-    const keywordScore = COMPLEXITY_KEYWORDS.test(queryText) ? 0.25 : 0;
-    const score = Math.min(1, lengthScore + structureScore + keywordScore);
-    return config.minThoughts + Math.round(span * score);
-}
-function countSentences(queryText) {
-    if (!sentenceSegmenter) {
-        return 0;
-    }
-    let count = 0;
-    for (const sentence of sentenceSegmenter.segment(queryText)) {
-        if (NON_WHITESPACE.test(sentence.segment)) {
-            count++;
-        }
-    }
-    return count;
-}
-function getStructureDensityScore(queryText) {
-    const sentenceCount = countSentences(queryText);
-    if (sentenceCount > 1) {
-        return (sentenceCount - 1) * 0.08;
-    }
-    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) {
     if (!signal) {
         return;
@@ -220,6 +144,6 @@ function throwIfReasoningAborted(signal) {
         signal.throwIfAborted();
     }
     catch {
-        throw new Error('Reasoning aborted');
+        throw new ReasoningAbortedError();
     }
 }

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

@@ -1,16 +1,21 @@
 import type { ReasoningLevel, Session, SessionSummary, Thought } from '../lib/types.js';
+export declare const DEFAULT_SESSION_TTL_MS: number;
+export declare const DEFAULT_MAX_SESSIONS = 100;
+export declare const DEFAULT_MAX_TOTAL_TOKENS = 500000;
 export declare class SessionStore {
     private readonly sessions;
     private readonly sessionOrder;
     private oldestSessionId;
     private newestSessionId;
     private sortedSessionIdsCache;
-    private readonly cleanupInterval;
+    private cleanupInterval;
     private readonly ttlMs;
     private readonly maxSessions;
     private readonly maxTotalTokens;
     private totalTokens;
     constructor(ttlMs?: number, maxSessions?: number, maxTotalTokens?: number);
+    ensureCleanupTimer(): void;
+    dispose(): void;
     create(level: ReasoningLevel, totalThoughts?: number): Readonly<Session>;
     get(id: string): Readonly<Session> | undefined;
     getSummary(id: string): Readonly<SessionSummary> | undefined;
@@ -40,6 +45,7 @@ export declare class SessionStore {
     private deleteSessionInternal;
     private markSessionTouched;
     private getSessionIdsForIteration;
+    private collectSessions;
     private snapshotThought;
     private snapshotSession;
     private snapshotSessionSummary;

package/dist/engine/session-store.js

@@ -2,9 +2,9 @@ import { Buffer } from 'node:buffer';
 import { randomUUID } from 'node:crypto';
 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;
+export const DEFAULT_SESSION_TTL_MS = 30 * 60 * 1000; // 30 minutes
+export const DEFAULT_MAX_SESSIONS = 100;
+export 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;
@@ -12,6 +12,9 @@ function estimateTokens(text) {
     const byteLength = Buffer.byteLength(text, 'utf8');
     return Math.max(1, Math.ceil(byteLength / TOKEN_ESTIMATE_DIVISOR));
 }
+function getThoughtTokenCount(thought) {
+    return thought.tokenCount ?? estimateTokens(thought.content);
+}
 function resolveSweepInterval(ttlMs) {
     return Math.max(MIN_SWEEP_INTERVAL_MS, Math.min(MAX_SWEEP_INTERVAL_MS, ttlMs));
 }
@@ -26,16 +29,29 @@ export class SessionStore {
     maxSessions;
     maxTotalTokens;
     totalTokens = 0;
-    constructor(ttlMs = DEFAULT_TTL_MS, maxSessions = DEFAULT_MAX_SESSIONS, maxTotalTokens = DEFAULT_MAX_TOTAL_TOKENS) {
+    constructor(ttlMs = DEFAULT_SESSION_TTL_MS, maxSessions = DEFAULT_MAX_SESSIONS, maxTotalTokens = DEFAULT_MAX_TOTAL_TOKENS) {
         this.ttlMs = ttlMs;
         this.maxSessions = maxSessions;
         this.maxTotalTokens = maxTotalTokens;
-        const sweepInterval = resolveSweepInterval(ttlMs);
+        this.ensureCleanupTimer();
+    }
+    ensureCleanupTimer() {
+        if (this.cleanupInterval) {
+            return;
+        }
+        const sweepInterval = resolveSweepInterval(this.ttlMs);
         this.cleanupInterval = setInterval(() => {
             this.sweep();
         }, sweepInterval);
         this.cleanupInterval.unref();
     }
+    dispose() {
+        if (!this.cleanupInterval) {
+            return;
+        }
+        clearInterval(this.cleanupInterval);
+        this.cleanupInterval = undefined;
+    }
     create(level, totalThoughts) {
         this.evictIfAtCapacity();
         const config = getLevelConfig(level);
@@ -67,28 +83,14 @@ export class SessionStore {
         return session ? this.snapshotSessionSummary(session) : undefined;
     }
     list() {
-        const sessions = [];
-        for (const sessionId of this.getSessionIdsForIteration()) {
-            const session = this.sessions.get(sessionId);
-            if (session) {
-                sessions.push(this.snapshotSession(session));
-            }
-        }
-        return sessions;
+        return this.collectSessions(this.snapshotSession.bind(this));
     }
     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;
+        return this.collectSessions(this.snapshotSessionSummary.bind(this));
     }
     getTtlMs() {
         return this.ttlMs;
@@ -123,6 +125,7 @@ export class SessionStore {
             index: session.thoughts.length,
             content,
             revision: 0,
+            tokenCount: tokens,
             ...(stepSummary !== undefined ? { stepSummary } : {}),
         };
         session.thoughts.push(thought);
@@ -145,7 +148,7 @@ export class SessionStore {
         session.thoughts = session.thoughts.slice(0, toIndex + 1);
         let removedTokens = 0;
         for (const t of removedThoughts) {
-            removedTokens += estimateTokens(t.content);
+            removedTokens += getThoughtTokenCount(t);
         }
         session.tokensUsed -= removedTokens;
         this.totalTokens -= removedTokens;
@@ -160,7 +163,7 @@ export class SessionStore {
         if (!existing) {
             throw new Error(`Thought index ${String(thoughtIndex)} not found in session ${sessionId}`);
         }
-        const oldTokens = estimateTokens(existing.content);
+        const oldTokens = getThoughtTokenCount(existing);
         const newTokens = estimateTokens(content);
         const delta = newTokens - oldTokens;
         if (delta > 0) {
@@ -170,12 +173,23 @@ export class SessionStore {
             index: thoughtIndex,
             content,
             revision: existing.revision + 1,
+            tokenCount: newTokens,
+            ...(existing.stepSummary !== undefined
+                ? { stepSummary: existing.stepSummary }
+                : {}),
         };
         session.thoughts[thoughtIndex] = revised;
         session.tokensUsed = session.tokensUsed - oldTokens + newTokens;
         this.totalTokens += delta;
         this.markSessionTouched(session);
-        return this.snapshotThought(revised);
+        const snapshotted = this.snapshotThought(revised);
+        engineEvents.emit('thought:revised', {
+            sessionId,
+            index: snapshotted.index,
+            content: snapshotted.content,
+            revision: snapshotted.revision,
+        });
+        return snapshotted;
     }
     markCompleted(sessionId) {
         this.updateSessionStatus(sessionId, 'completed');
@@ -344,6 +358,8 @@ export class SessionStore {
     }
     markSessionTouched(session) {
         session.updatedAt = Date.now();
+        session._cachedSnapshot = undefined;
+        session._cachedSummary = undefined;
         this.touchOrder(session.id);
         this.sortedSessionIdsCache = null;
         this.emitSessionResourcesUpdated(session.id);
@@ -352,8 +368,18 @@ export class SessionStore {
         this.sortedSessionIdsCache ??= this.buildSortedSessionIdsCache();
         return this.sortedSessionIdsCache;
     }
+    collectSessions(mapSession) {
+        const collected = [];
+        for (const sessionId of this.getSessionIdsForIteration()) {
+            const session = this.sessions.get(sessionId);
+            if (session) {
+                collected.push(mapSession(session));
+            }
+        }
+        return collected;
+    }
     snapshotThought(thought) {
-        return {
+        const t = {
             index: thought.index,
             content: thought.content,
             revision: thought.revision,
@@ -361,10 +387,15 @@ export class SessionStore {
                 ? { stepSummary: thought.stepSummary }
                 : {}),
         };
+        Object.freeze(t);
+        return t;
     }
     snapshotSession(session) {
+        if (session._cachedSnapshot) {
+            return session._cachedSnapshot;
+        }
         const thoughts = session.thoughts.map((thought) => this.snapshotThought(thought));
-        return {
+        const snapshot = {
             id: session.id,
             level: session.level,
             status: session.status,
@@ -375,9 +406,16 @@ export class SessionStore {
             createdAt: session.createdAt,
             updatedAt: session.updatedAt,
         };
+        Object.freeze(snapshot);
+        Object.freeze(snapshot.thoughts);
+        session._cachedSnapshot = snapshot;
+        return snapshot;
     }
     snapshotSessionSummary(session) {
-        return {
+        if (session._cachedSummary) {
+            return session._cachedSummary;
+        }
+        const summary = {
             id: session.id,
             level: session.level,
             status: session.status,
@@ -388,6 +426,9 @@ export class SessionStore {
             createdAt: session.createdAt,
             updatedAt: session.updatedAt,
         };
+        Object.freeze(summary);
+        session._cachedSummary = summary;
+        return summary;
     }
     emitSessionsListChanged() {
         engineEvents.emit('resources:changed', { uri: 'reasoning://sessions' });

package/dist/lib/concurrency.d.ts

@@ -0,0 +1,5 @@
+export interface TaskLimiter {
+    tryAcquire: () => boolean;
+    release: () => void;
+}
+export declare function createTaskLimiter(maxActiveTasks: number): TaskLimiter;

package/dist/lib/concurrency.js

@@ -0,0 +1,17 @@
+export function createTaskLimiter(maxActiveTasks) {
+    let activeTasks = 0;
+    return {
+        tryAcquire() {
+            if (activeTasks >= maxActiveTasks) {
+                return false;
+            }
+            activeTasks += 1;
+            return true;
+        },
+        release() {
+            if (activeTasks > 0) {
+                activeTasks -= 1;
+            }
+        },
+    };
+}

package/dist/lib/errors.d.ts

@@ -4,15 +4,31 @@ interface ErrorResponse {
         type: 'text';
         text: string;
     }[];
-    structuredContent: {
-        ok: false;
-        error: {
-            code: string;
-            message: string;
-        };
-    };
     isError: true;
 }
+export declare class ReasoningError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class SessionNotFoundError extends ReasoningError {
+    constructor(sessionId: string);
+}
+export declare class InvalidThoughtCountError extends ReasoningError {
+    constructor(message: string);
+}
+export declare class InsufficientThoughtsError extends ReasoningError {
+    constructor(message: string);
+}
+export declare class InvalidRunModeArgsError extends ReasoningError {
+    constructor(message: string);
+}
+export declare class ReasoningAbortedError extends ReasoningError {
+    constructor(message?: string);
+}
+export declare class ServerBusyError extends ReasoningError {
+    constructor(message?: string);
+}
+export declare function isObjectRecord(value: unknown): value is Record<string, unknown>;
 export declare function getErrorMessage(error: unknown): string;
 export declare function createErrorResponse(code: string, message: string): ErrorResponse;
 export {};