@j0hanz/cortex-mcp 1.5.0 → 1.7.0

package/dist/engine/context.d.ts

@@ -1,5 +1,4 @@
 export interface EngineContext {
     readonly sessionId: string;
-    readonly abortSignal?: AbortSignal;
 }
 export declare function runWithContext<T>(ctx: EngineContext, fn: () => T): T;

package/dist/engine/events.d.ts

@@ -26,6 +26,12 @@ interface EngineEvents {
         sessionId: string;
         level: ReasoningLevel;
     }];
+    'session:completed': [{
+        sessionId: string;
+    }];
+    'session:cancelled': [{
+        sessionId: string;
+    }];
     'session:expired': [{
         sessionId: string;
     }];

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

@@ -20,7 +20,7 @@ export async function reason(query, level, options) {
     const session = resolveSession(level, sessionId, query, targetThoughts);
     const config = getLevelConfig(session.level);
     const { totalThoughts } = session;
-    return runWithContext({ sessionId: session.id, ...(abortSignal ? { abortSignal } : {}) }, () => withSessionLock(session.id, async () => {
+    return runWithContext({ sessionId: session.id }, () => withSessionLock(session.id, async () => {
         throwIfReasoningAborted(abortSignal);
         if (rollbackToStep !== undefined) {
             sessionStore.rollback(session.id, rollbackToStep);
@@ -53,7 +53,7 @@ export async function reason(query, level, options) {
             content: addedThought.content,
         });
         const updated = getSessionOrThrow(session.id);
-        void emitBudgetExhaustedIfNeeded({
+        emitBudgetExhaustedIfNeeded({
             session: updated,
             tokenBudget: config.tokenBudget,
             generatedThoughts: addedThought.index + 1,
@@ -63,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);
@@ -129,7 +129,7 @@ function resolveSession(level, sessionId, query, targetThoughts) {
     }
     const config = getLevelConfig(level);
     const totalThoughts = resolveThoughtCount(level, query, config, targetThoughts);
-    const session = sessionStore.create(level, totalThoughts);
+    const session = sessionStore.create(level, totalThoughts, query);
     engineEvents.emit('session:created', {
         sessionId: session.id,
         level,

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

@@ -8,13 +8,15 @@ export declare class SessionStore {
     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);
-    create(level: ReasoningLevel, totalThoughts?: number): Readonly<Session>;
+    ensureCleanupTimer(): void;
+    dispose(): void;
+    create(level: ReasoningLevel, totalThoughts?: number, query?: string): Readonly<Session>;
     get(id: string): Readonly<Session> | undefined;
     getSummary(id: string): Readonly<SessionSummary> | undefined;
     list(): Readonly<Session>[];
@@ -26,7 +28,7 @@ export declare class SessionStore {
     delete(id: string): boolean;
     addThought(sessionId: string, content: string, stepSummary?: string): Thought;
     rollback(sessionId: string, toIndex: number): void;
-    reviseThought(sessionId: string, thoughtIndex: number, content: string): Thought;
+    reviseThought(sessionId: string, thoughtIndex: number, content: string, stepSummary?: string): Thought;
     markCompleted(sessionId: string): void;
     markCancelled(sessionId: string): void;
     private updateSessionStatus;
@@ -47,9 +49,9 @@ export declare class SessionStore {
     private snapshotThought;
     private snapshotSession;
     private snapshotSessionSummary;
-    private emitSessionsListChanged;
-    private emitSessionsResourceUpdated;
-    private emitSessionsCollectionUpdated;
+    private emitListChanged;
+    private emitListResourceUpdated;
+    private emitCollectionUpdated;
     private emitSessionEvicted;
-    private emitSessionResourcesUpdated;
+    private emitSessionResourceUpdated;
 }

package/dist/engine/session-store.js

@@ -1,11 +1,12 @@
 import { Buffer } from 'node:buffer';
 import { randomUUID } from 'node:crypto';
+import { SessionNotFoundError } from '../lib/errors.js';
 import { getLevelConfig } from './config.js';
 import { engineEvents } from './events.js';
 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 TOKEN_ESTIMATE_DIVISOR = 3.5;
 const MIN_SWEEP_INTERVAL_MS = 10;
 const MAX_SWEEP_INTERVAL_MS = 60_000;
 function estimateTokens(text) {
@@ -33,13 +34,26 @@ export class SessionStore {
         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();
     }
-    create(level, totalThoughts) {
+    dispose() {
+        if (!this.cleanupInterval) {
+            return;
+        }
+        clearInterval(this.cleanupInterval);
+        this.cleanupInterval = undefined;
+    }
+    create(level, totalThoughts, query) {
         this.evictIfAtCapacity();
         const config = getLevelConfig(level);
         const now = Date.now();
@@ -53,12 +67,13 @@ export class SessionStore {
             tokensUsed: 0,
             createdAt: now,
             updatedAt: now,
+            ...(query !== undefined ? { query } : {}),
         };
         this.sessions.set(session.id, session);
         this.addToOrder(session.id);
         this.sortedSessionIdsCache = null;
-        this.emitSessionsListChanged();
-        this.emitSessionsResourceUpdated();
+        this.emitListChanged();
+        this.emitListResourceUpdated();
         return this.snapshotSession(session);
     }
     get(id) {
@@ -98,13 +113,13 @@ export class SessionStore {
             return false;
         }
         engineEvents.emit('session:deleted', { sessionId: id });
-        this.emitSessionsCollectionUpdated();
+        this.emitCollectionUpdated();
         return true;
     }
     addThought(sessionId, content, stepSummary) {
         const session = this.sessions.get(sessionId);
         if (!session) {
-            throw new Error(`Session not found: ${sessionId}`);
+            throw new SessionNotFoundError(sessionId);
         }
         const tokens = estimateTokens(content);
         this.evictForTokenHeadroom(tokens, sessionId);
@@ -124,7 +139,7 @@ export class SessionStore {
     rollback(sessionId, toIndex) {
         const session = this.sessions.get(sessionId);
         if (!session) {
-            throw new Error(`Session not found: ${sessionId}`);
+            throw new SessionNotFoundError(sessionId);
         }
         // If toIndex is out of bounds or implies no change, return.
         // We keep thoughts up to and including toIndex.
@@ -141,10 +156,10 @@ export class SessionStore {
         this.totalTokens -= removedTokens;
         this.markSessionTouched(session);
     }
-    reviseThought(sessionId, thoughtIndex, content) {
+    reviseThought(sessionId, thoughtIndex, content, stepSummary) {
         const session = this.sessions.get(sessionId);
         if (!session) {
-            throw new Error(`Session not found: ${sessionId}`);
+            throw new SessionNotFoundError(sessionId);
         }
         const existing = session.thoughts[thoughtIndex];
         if (!existing) {
@@ -156,13 +171,14 @@ export class SessionStore {
         if (delta > 0) {
             this.evictForTokenHeadroom(delta, sessionId);
         }
+        const effectiveStepSummary = stepSummary ?? existing.stepSummary;
         const revised = {
             index: thoughtIndex,
             content,
             revision: existing.revision + 1,
             tokenCount: newTokens,
-            ...(existing.stepSummary !== undefined
-                ? { stepSummary: existing.stepSummary }
+            ...(effectiveStepSummary !== undefined
+                ? { stepSummary: effectiveStepSummary }
                 : {}),
         };
         session.thoughts[thoughtIndex] = revised;
@@ -189,6 +205,12 @@ export class SessionStore {
         if (session?.status === 'active') {
             session.status = status;
             this.markSessionTouched(session);
+            if (status === 'completed') {
+                engineEvents.emit('session:completed', { sessionId });
+            }
+            else {
+                engineEvents.emit('session:cancelled', { sessionId });
+            }
         }
     }
     evictIfAtCapacity() {
@@ -241,7 +263,7 @@ export class SessionStore {
             currentId = nextId;
         }
         if (changed) {
-            this.emitSessionsCollectionUpdated();
+            this.emitCollectionUpdated();
         }
     }
     buildSortedSessionIdsCache() {
@@ -349,7 +371,7 @@ export class SessionStore {
         session._cachedSummary = undefined;
         this.touchOrder(session.id);
         this.sortedSessionIdsCache = null;
-        this.emitSessionResourcesUpdated(session.id);
+        this.emitSessionResourceUpdated(session.id);
     }
     getSessionIdsForIteration() {
         this.sortedSessionIdsCache ??= this.buildSortedSessionIdsCache();
@@ -392,6 +414,7 @@ export class SessionStore {
             tokensUsed: session.tokensUsed,
             createdAt: session.createdAt,
             updatedAt: session.updatedAt,
+            ...(session.query !== undefined ? { query: session.query } : {}),
         };
         Object.freeze(snapshot);
         Object.freeze(snapshot.thoughts);
@@ -417,27 +440,27 @@ export class SessionStore {
         session._cachedSummary = summary;
         return summary;
     }
-    emitSessionsListChanged() {
+    emitListChanged() {
         engineEvents.emit('resources:changed', { uri: 'reasoning://sessions' });
     }
-    emitSessionsResourceUpdated() {
+    emitListResourceUpdated() {
         engineEvents.emit('resource:updated', { uri: 'reasoning://sessions' });
     }
-    emitSessionsCollectionUpdated() {
-        this.emitSessionsListChanged();
-        this.emitSessionsResourceUpdated();
+    emitCollectionUpdated() {
+        this.emitListChanged();
+        this.emitListResourceUpdated();
     }
     emitSessionEvicted(sessionId, reason) {
         engineEvents.emit('session:evicted', {
             sessionId,
             reason,
         });
-        this.emitSessionsCollectionUpdated();
+        this.emitCollectionUpdated();
     }
-    emitSessionResourcesUpdated(sessionId) {
+    emitSessionResourceUpdated(sessionId) {
         engineEvents.emit('resource:updated', {
             uri: `reasoning://sessions/${sessionId}`,
         });
-        this.emitSessionsResourceUpdated();
+        this.emitListResourceUpdated();
     }
 }

package/dist/lib/tool-contracts.js

@@ -30,12 +30,6 @@ const TOOL_CONTRACTS = [
                 required: false,
                 constraints: '1-100,000 chars',
             },
-            {
-                name: 'thoughts',
-                type: 'string[]',
-                required: false,
-                constraints: 'optional',
-            },
             {
                 name: 'targetThoughts',
                 type: 'number',
@@ -85,7 +79,7 @@ const TOOL_CONTRACTS = [
                 constraints: 'optional',
             },
         ],
-        outputShape: '{ok, result: {sessionId, level, status, thoughts[], generatedThoughts, requestedThoughts, totalThoughts, remainingThoughts, tokenBudget, tokensUsed, ttlMs, expiresAt, createdAt, updatedAt, summary}}',
+        outputShape: '{ok, result: {sessionId, query?, level, status, thoughts[], generatedThoughts, requestedThoughts, totalThoughts, remainingThoughts, tokenBudget, tokensUsed, ttlMs, expiresAt, createdAt, updatedAt, summary}}',
     },
 ];
 export function getToolContracts() {

package/dist/lib/types.d.ts

@@ -40,6 +40,7 @@ export interface Thought {
 }
 export interface Session extends SessionBase {
     readonly thoughts: readonly Thought[];
+    readonly query?: string;
 }
 export interface SessionSummary extends SessionBase {
     readonly generatedThoughts: number;

package/dist/lib/validators.d.ts

@@ -9,4 +9,9 @@ export declare function getTargetThoughtsError(level: ReasoningLevel, targetThou
  * if the variable is absent or invalid. Values below `minimum` also fall back.
  */
 export declare function parsePositiveIntEnv(name: string, fallback: number, minimum?: number): number;
+/**
+ * Parse a boolean from an environment variable, returning `fallback` when absent
+ * or when the value is not a recognized boolean literal.
+ */
+export declare function parseBooleanEnv(name: string, fallback: boolean): boolean;
 export declare function collectPrefixMatches(candidates: readonly string[], value: string, limit: number): string[];

package/dist/lib/validators.js

@@ -30,6 +30,24 @@ export function parsePositiveIntEnv(name, fallback, minimum = 1) {
     }
     return parsed;
 }
+/**
+ * Parse a boolean from an environment variable, returning `fallback` when absent
+ * or when the value is not a recognized boolean literal.
+ */
+export function parseBooleanEnv(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined) {
+        return fallback;
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+        return true;
+    }
+    if (['0', 'false', 'no', 'off'].includes(normalized)) {
+        return false;
+    }
+    return fallback;
+}
 export function collectPrefixMatches(candidates, value, limit) {
     const results = [];
     for (const candidate of candidates) {

package/dist/prompts/index.js

@@ -40,17 +40,21 @@ function createTextPrompt(text) {
 function buildPromptText(args) {
     const { context, task, constraints, output } = args;
     return [
-        '# Context',
+        '<context>',
         ...context,
+        '</context>',
         '',
-        '# Task',
+        '<task>',
         ...task,
+        '</task>',
         '',
-        '# Constraints',
+        '<constraints>',
         ...constraints.map((line) => `- ${line}`),
+        '</constraints>',
         '',
-        '# Output',
+        '<output_format>',
         ...output,
+        '</output_format>',
     ].join('\n');
 }
 function buildStartReasoningPrompt(args) {
@@ -64,20 +68,20 @@ function buildStartReasoningPrompt(args) {
                 : String(targetThoughts)}`,
         ],
         task: [
-            `Start a new reasoning session using "${REASONING_TOOL_NAME}".`,
-            'Create the first step with a complete, concrete reasoning thought.',
+            `Start new reasoning session via "${REASONING_TOOL_NAME}".`,
+            'Generate the first concrete reasoning step.',
         ],
         constraints: [
             THOUGHT_PARAMETER_GUIDANCE,
-            'Preserve sessionId from the response for continuation calls.',
-            'Continue until status is completed or remainingThoughts is 0.',
+            'Preserve sessionId for continuation.',
+            'Continue until status="completed" or remainingThoughts=0.',
         ],
         output: [
-            'Return the first tool call payload only.',
-            'Fields: query, level, thought, and optional targetThoughts.',
+            'Return exactly one tool call payload.',
+            'Required fields: query, level, thought.',
         ],
     });
-    return `${base}\n\n---\n\n${getTemplate(level)}`;
+    return `${base}\n\n${getTemplate(level)}`;
 }
 function buildRetryReasoningPrompt(args) {
     const { query, level, targetThoughts } = args;
@@ -90,18 +94,18 @@ function buildRetryReasoningPrompt(args) {
                 : String(targetThoughts)}`,
         ],
         task: [
-            `Retry by calling "${REASONING_TOOL_NAME}" with an improved first thought.`,
+            `Retry calling "${REASONING_TOOL_NAME}" with an improved first thought.`,
         ],
         constraints: [
             THOUGHT_PARAMETER_GUIDANCE,
-            'Use a direct and specific thought with no filler language.',
+            'Write a direct, specific thought. No filler.',
         ],
         output: [
-            'Return one tool call payload only.',
-            'Fields: query, level, thought, and optional targetThoughts.',
+            'Return exactly one tool call payload.',
+            'Required fields: query, level, thought.',
         ],
     });
-    return `${base}\n\n---\n\n${getTemplate(level)}`;
+    return `${base}\n\n${getTemplate(level)}`;
 }
 function buildContinueReasoningPrompt(args) {
     const { sessionId, query, level, targetThoughts } = args;
@@ -119,17 +123,17 @@ function buildContinueReasoningPrompt(args) {
                 : String(targetThoughts)}`,
         ],
         task: [
-            `Continue the existing session using "${REASONING_TOOL_NAME}".`,
-            'Generate the next reasoning step only.',
+            `Continue session via "${REASONING_TOOL_NAME}".`,
+            'Generate the next reasoning step.',
         ],
         constraints: [
             THOUGHT_PARAMETER_GUIDANCE,
-            'Keep the same sessionId in the call payload.',
-            'Prefer concise, concrete reasoning over meta commentary.',
+            'Keep the same sessionId.',
+            'Write concrete reasoning. No meta commentary.',
         ],
         output: [
-            'Return one continuation tool call payload only.',
-            'Fields: sessionId, thought, and optional query/level/targetThoughts.',
+            'Return exactly one continuation tool call payload.',
+            'Required fields: sessionId, thought.',
         ],
     });
 }