@j0hanz/cortex-mcp 1.3.0 → 1.4.0

package/dist/engine/config.d.ts

@@ -18,4 +18,4 @@ export declare const LEVEL_CONFIGS: {
 };
 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

@@ -14,4 +14,11 @@ export function assertTargetThoughtsInRange(level, targetThoughts) {
     }
     throw new Error(errorMessage);
 }
-//# sourceMappingURL=config.js.map
+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(', ');
+}

package/dist/engine/context.d.ts

@@ -4,4 +4,3 @@ export interface EngineContext {
 }
 export declare function runWithContext<T>(ctx: EngineContext, fn: () => T): T;
 export declare function getContext(): EngineContext | undefined;
-//# sourceMappingURL=context.d.ts.map

package/dist/engine/context.js

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

package/dist/engine/events.d.ts

@@ -51,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

@@ -9,4 +9,3 @@ function logEngineError(err) {
     process.stderr.write(`${ENGINE_ERROR_PREFIX_WITH_SPACE}${getErrorMessage(err)}\n`);
 }
 engineEvents.on('error', logEngineError);
-//# sourceMappingURL=events.js.map

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

@@ -25,16 +25,31 @@ 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 = 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);
+        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,
@@ -44,10 +59,10 @@ export async function reason(query, level, options) {
             return current;
         }
         const nextIndex = current.thoughts.length;
-        if (nextIndex >= totalThoughts) {
+        if (nextIndex >= totalThoughts && !isConclusion) {
             return current;
         }
-        const addedThought = sessionStore.addThought(session.id, thought);
+        const addedThought = sessionStore.addThought(session.id, content, stepSummary);
         engineEvents.emit('thought:added', {
             sessionId: session.id,
             index: addedThought.index,
@@ -60,7 +75,7 @@ export async function reason(query, level, options) {
             generatedThoughts: addedThought.index + 1,
             requestedThoughts: totalThoughts,
         });
-        if (updated.thoughts.length >= totalThoughts) {
+        if (isConclusion || updated.thoughts.length >= totalThoughts) {
             sessionStore.markCompleted(session.id);
         }
         if (onProgress) {
@@ -208,4 +223,3 @@ function throwIfReasoningAborted(signal) {
         throw new Error('Reasoning aborted');
     }
 }
-//# sourceMappingURL=reasoner.js.map

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

@@ -21,7 +21,8 @@ export declare class SessionStore {
     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;
@@ -48,4 +49,3 @@ export declare class SessionStore {
     private emitSessionEvicted;
     private emitSessionResourcesUpdated;
 }
-//# sourceMappingURL=session-store.d.ts.map

package/dist/engine/session-store.js

@@ -112,7 +112,7 @@ export class SessionStore {
         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}`);
@@ -123,6 +123,7 @@ export class SessionStore {
             index: session.thoughts.length,
             content,
             revision: 0,
+            ...(stepSummary !== undefined ? { stepSummary } : {}),
         };
         session.thoughts.push(thought);
         session.tokensUsed += tokens;
@@ -130,6 +131,26 @@ export class SessionStore {
         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) {
@@ -336,6 +357,9 @@ export class SessionStore {
             index: thought.index,
             content: thought.content,
             revision: thought.revision,
+            ...(thought.stepSummary !== undefined
+                ? { stepSummary: thought.stepSummary }
+                : {}),
         };
     }
     snapshotSession(session) {
@@ -389,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

@@ -52,4 +52,3 @@ main().catch((err) => {
     console.error('Fatal error:', err);
     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

@@ -47,4 +47,3 @@ export function createErrorResponse(code, message) {
         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

@@ -120,4 +120,3 @@ export function formatThoughtsToMarkdown(session, range) {
     }
     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[];

package/dist/lib/prompt-contracts.js

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+export function getPromptContracts() {
+    return [
+        {
+            name: 'get-help',
+            title: 'Get Help',
+            description: 'Return the server usage instructions.',
+            args: [],
+        },
+        {
+            name: 'reasoning.basic',
+            title: 'Reasoning Basic',
+            description: 'Prepare a basic-depth reasoning request (3–5 thoughts).',
+            args: [
+                {
+                    name: 'query',
+                    type: z.string().min(1).max(10000),
+                    description: 'The question or problem to reason about',
+                    required: true,
+                },
+                {
+                    name: 'targetThoughts',
+                    type: z.number().int().min(1).max(25),
+                    description: 'Optional exact step count within the selected level range (max 25)',
+                    required: false,
+                },
+            ],
+        },
+        {
+            name: 'reasoning.normal',
+            title: 'Reasoning Normal',
+            description: 'Prepare a normal-depth reasoning request (6–10 thoughts).',
+            args: [
+                {
+                    name: 'query',
+                    type: z.string().min(1).max(10000),
+                    description: 'The question or problem to reason about',
+                    required: true,
+                },
+                {
+                    name: 'targetThoughts',
+                    type: z.number().int().min(1).max(25),
+                    description: 'Optional exact step count within the selected level range (max 25)',
+                    required: false,
+                },
+            ],
+        },
+        {
+            name: 'reasoning.high',
+            title: 'Reasoning High',
+            description: 'Prepare a high-depth reasoning request (15–25 thoughts).',
+            args: [
+                {
+                    name: 'query',
+                    type: z.string().min(1).max(10000),
+                    description: 'The question or problem to reason about',
+                    required: true,
+                },
+                {
+                    name: 'targetThoughts',
+                    type: z.number().int().min(1).max(25),
+                    description: 'Optional exact step count within the selected level range (max 25)',
+                    required: false,
+                },
+            ],
+        },
+        {
+            name: 'reasoning.continue',
+            title: 'Continue Reasoning',
+            description: 'Continue an existing reasoning session (follow-up query optional).',
+            args: [
+                {
+                    name: 'sessionId',
+                    type: z.string().min(1).max(128),
+                    description: 'Existing session ID to continue',
+                    required: true,
+                },
+                {
+                    name: 'query',
+                    type: z.string().min(1).max(10000),
+                    description: 'Follow-up query for the existing session',
+                    required: false,
+                },
+                {
+                    name: 'level',
+                    type: z.enum(['basic', 'normal', 'high']),
+                    description: 'Optional in the tool; session level is used if provided',
+                    required: false,
+                },
+                {
+                    name: 'targetThoughts',
+                    type: z.number().int().min(1).max(25),
+                    description: 'Optional exact step count within the selected level range (max 25)',
+                    required: false,
+                },
+            ],
+        },
+        {
+            name: 'reasoning.retry',
+            title: 'Retry Reasoning',
+            description: 'Retry a failed reasoning task with modified parameters.',
+            args: [
+                {
+                    name: 'query',
+                    type: z.string().min(1).max(10000),
+                    description: 'The original or modified query',
+                    required: true,
+                },
+                {
+                    name: 'level',
+                    type: z.enum(['basic', 'normal', 'high']),
+                    description: 'The reasoning level to use',
+                    required: true,
+                },
+                {
+                    name: 'targetThoughts',
+                    type: z.number().int().min(1).max(25),
+                    description: 'Optional exact step count',
+                    required: false,
+                },
+            ],
+        },
+    ];
+}

package/dist/lib/text.d.ts

@@ -12,4 +12,3 @@ export declare function truncate(str: string, maxLength: number, segmenter?: Int
  * Drops incomplete characters at the end rather than using replacement characters.
  */
 export declare function truncateByUtf8Boundary(str: string, maxBytes: number): string;
-//# sourceMappingURL=text.d.ts.map

package/dist/lib/text.js

@@ -72,4 +72,3 @@ export function truncateByUtf8Boundary(str, maxBytes) {
     const decoder = new StringDecoder(UTF8);
     return decoder.write(encoded.subarray(0, safeMaxBytes));
 }
-//# sourceMappingURL=text.js.map

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

@@ -0,0 +1,15 @@
+export interface ToolContract {
+    name: string;
+    purpose: string;
+    model: string;
+    timeoutMs: number;
+    maxOutputTokens: number;
+    params: {
+        name: string;
+        type: string;
+        required: boolean;
+        constraints: string;
+    }[];
+    outputShape: string;
+}
+export declare function getToolContracts(): ToolContract[];

package/dist/lib/tool-contracts.js

@@ -0,0 +1,92 @@
+export function getToolContracts() {
+    return [
+        {
+            name: 'reasoning_think',
+            purpose: 'Structured multi-step reasoning tool. Decomposes analysis into sequential thought steps stored in a persistent session trace.',
+            model: 'none (engine)',
+            timeoutMs: 0,
+            maxOutputTokens: 0,
+            params: [
+                {
+                    name: 'query',
+                    type: 'string',
+                    required: false,
+                    constraints: '1-10,000 chars',
+                },
+                {
+                    name: 'level',
+                    type: 'string',
+                    required: false,
+                    constraints: 'basic | normal | high',
+                },
+                {
+                    name: 'runMode',
+                    type: 'string',
+                    required: false,
+                    constraints: 'step | run_to_completion',
+                },
+                {
+                    name: 'thought',
+                    type: 'string | string[]',
+                    required: false,
+                    constraints: '1-100,000 chars',
+                },
+                {
+                    name: 'thoughts',
+                    type: 'string[]',
+                    required: false,
+                    constraints: 'optional',
+                },
+                {
+                    name: 'targetThoughts',
+                    type: 'number',
+                    required: false,
+                    constraints: '1-25',
+                },
+                {
+                    name: 'sessionId',
+                    type: 'string',
+                    required: false,
+                    constraints: '1-128 chars',
+                },
+                {
+                    name: 'observation',
+                    type: 'string',
+                    required: false,
+                    constraints: 'optional',
+                },
+                {
+                    name: 'hypothesis',
+                    type: 'string',
+                    required: false,
+                    constraints: 'optional',
+                },
+                {
+                    name: 'evaluation',
+                    type: 'string',
+                    required: false,
+                    constraints: 'optional',
+                },
+                {
+                    name: 'step_summary',
+                    type: 'string',
+                    required: false,
+                    constraints: 'optional',
+                },
+                {
+                    name: 'is_conclusion',
+                    type: 'boolean',
+                    required: false,
+                    constraints: 'optional',
+                },
+                {
+                    name: 'rollback_to_step',
+                    type: 'number',
+                    required: false,
+                    constraints: 'optional',
+                },
+            ],
+            outputShape: '{ok, result: {sessionId, level, status, thoughts[], generatedThoughts, requestedThoughts, totalThoughts, remainingThoughts, tokenBudget, tokensUsed, ttlMs, expiresAt, createdAt, updatedAt, summary}}',
+        },
+    ];
+}

package/dist/lib/tool-response.d.ts

@@ -3,4 +3,3 @@ export declare function createToolResponse<T extends object>(structured: T, embe
     content: ContentBlock[];
     structuredContent: T;
 };
-//# sourceMappingURL=tool-response.d.ts.map

package/dist/lib/tool-response.js

@@ -13,4 +13,3 @@ export function createToolResponse(structured, embeddedResource) {
         structuredContent: structured,
     };
 }
-//# sourceMappingURL=tool-response.js.map

package/dist/lib/types.d.ts

@@ -19,6 +19,7 @@ export interface Thought {
     readonly index: number;
     readonly content: string;
     readonly revision: number;
+    readonly stepSummary?: string;
 }
 export interface Session extends SessionBase {
     readonly thoughts: readonly Thought[];
@@ -37,4 +38,3 @@ export interface IconMeta {
     sizes?: string[];
 }
 export {};
-//# sourceMappingURL=types.d.ts.map

package/dist/lib/types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types.js.map

package/dist/lib/validators.d.ts

@@ -4,4 +4,3 @@ export declare function getThoughtBounds(level: ReasoningLevel): {
     maxThoughts: number;
 };
 export declare function getTargetThoughtsError(level: ReasoningLevel, targetThoughts: number): string | undefined;
-//# sourceMappingURL=validators.d.ts.map

package/dist/lib/validators.js

@@ -20,4 +20,3 @@ export function getTargetThoughtsError(level, targetThoughts) {
     }
     return undefined;
 }
-//# sourceMappingURL=validators.js.map

package/dist/prompts/index.d.ts

@@ -1,4 +1,3 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { IconMeta } from '../lib/types.js';
 export declare function registerAllPrompts(server: McpServer, iconMeta?: IconMeta): void;
-//# sourceMappingURL=index.d.ts.map