@j0hanz/cortex-mcp 1.3.0 → 1.5.0

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/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,16 +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 {};
-//# sourceMappingURL=errors.d.ts.map

package/dist/lib/errors.js

@@ -4,7 +4,51 @@ const INSPECT_OPTIONS = {
     breakLength: 120,
 };
 const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
-function isRecord(value) {
+export class ReasoningError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ReasoningError';
+    }
+}
+export class SessionNotFoundError extends ReasoningError {
+    constructor(sessionId) {
+        super('E_SESSION_NOT_FOUND', `Session not found or expired: ${sessionId}`);
+        this.name = 'SessionNotFoundError';
+    }
+}
+export class InvalidThoughtCountError extends ReasoningError {
+    constructor(message) {
+        super('E_INVALID_THOUGHT_COUNT', message);
+        this.name = 'InvalidThoughtCountError';
+    }
+}
+export class InsufficientThoughtsError extends ReasoningError {
+    constructor(message) {
+        super('E_INSUFFICIENT_THOUGHTS', message);
+        this.name = 'InsufficientThoughtsError';
+    }
+}
+export class InvalidRunModeArgsError extends ReasoningError {
+    constructor(message) {
+        super('E_INVALID_RUN_MODE_ARGS', message);
+        this.name = 'InvalidRunModeArgsError';
+    }
+}
+export class ReasoningAbortedError extends ReasoningError {
+    constructor(message = 'Reasoning aborted') {
+        super('E_ABORTED', message);
+        this.name = 'ReasoningAbortedError';
+    }
+}
+export class ServerBusyError extends ReasoningError {
+    constructor(message = 'Server busy — too many concurrent reasoning tasks. Retry shortly.') {
+        super('E_SERVER_BUSY', message);
+        this.name = 'ServerBusyError';
+    }
+}
+export function isObjectRecord(value) {
     return typeof value === 'object' && value !== null;
 }
 function stringifyUnknown(value) {
@@ -17,7 +61,7 @@ function stringifyUnknown(value) {
     return inspect(value, INSPECT_OPTIONS);
 }
 function getMessageFromErrorLike(value) {
-    if (!isRecord(value)) {
+    if (!isObjectRecord(value)) {
         return undefined;
     }
     return typeof value.message === 'string' ? value.message : undefined;
@@ -39,12 +83,9 @@ export function getErrorMessage(error) {
     return stringifyUnknown(error);
 }
 export function createErrorResponse(code, message) {
-    const structured = { ok: false, error: { code, message } };
-    const text = JSON.stringify(structured);
+    const text = JSON.stringify({ ok: false, error: { code, message } });
     return {
         content: [{ type: 'text', text }],
-        structuredContent: structured,
         isError: true,
     };
 }
-//# sourceMappingURL=errors.js.map

package/dist/lib/formatting.d.ts

@@ -30,4 +30,16 @@ export declare function formatThoughtsToMarkdown(session: Readonly<Session>, ran
     start: number;
     end: number;
 }): string;
-//# sourceMappingURL=formatting.d.ts.map
+/**
+ * Format a standardized progress message string.
+ *
+ * Rules:
+ * - Start/Mid: <tool>: <context> [metadata]
+ * - End: <tool>: <context> [metadata] • <outcome>
+ */
+export declare function formatProgressMessage(args: {
+    toolName: string;
+    context: string;
+    metadata?: string;
+    outcome?: string;
+}): string;

package/dist/lib/formatting.js

@@ -21,6 +21,9 @@ export function extractPinnedSections(thoughts) {
     const byTitle = new Map();
     for (const thought of thoughts) {
         const { content } = thought;
+        if (!content.includes(PIN_START)) {
+            continue;
+        }
         let searchFrom = 0;
         while (searchFrom < content.length) {
             const startIdx = content.indexOf(PIN_START, searchFrom);
@@ -120,4 +123,18 @@ export function formatThoughtsToMarkdown(session, range) {
     }
     return sections.join(TRACE_SEPARATOR);
 }
-//# sourceMappingURL=formatting.js.map
+/**
+ * Format a standardized progress message string.
+ *
+ * Rules:
+ * - Start/Mid: <tool>: <context> [metadata]
+ * - End: <tool>: <context> [metadata] • <outcome>
+ */
+export function formatProgressMessage(args) {
+    const { toolName, context, metadata, outcome } = args;
+    const metaPart = metadata ? ` ${metadata}` : '';
+    if (outcome) {
+        return `${toolName}: ${context}${metaPart} • ${outcome}`;
+    }
+    return `${toolName}: ${context}${metaPart}`;
+}

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

@@ -0,0 +1,6 @@
+export interface PromptContract {
+    name: string;
+    title: string;
+    description: string;
+}
+export declare function getPromptContracts(): readonly PromptContract[];

package/dist/lib/prompt-contracts.js

@@ -0,0 +1,35 @@
+const PROMPT_CONTRACTS = [
+    {
+        name: 'get-help',
+        title: 'Get Help',
+        description: 'Return the server usage instructions.',
+    },
+    {
+        name: 'reasoning.basic',
+        title: 'Reasoning Basic',
+        description: 'Prepare a basic-depth reasoning request (3–5 thoughts).',
+    },
+    {
+        name: 'reasoning.normal',
+        title: 'Reasoning Normal',
+        description: 'Prepare a normal-depth reasoning request (6–10 thoughts).',
+    },
+    {
+        name: 'reasoning.high',
+        title: 'Reasoning High',
+        description: 'Prepare a high-depth reasoning request (15–25 thoughts).',
+    },
+    {
+        name: 'reasoning.continue',
+        title: 'Continue Reasoning',
+        description: 'Continue an existing reasoning session (follow-up query optional).',
+    },
+    {
+        name: 'reasoning.retry',
+        title: 'Retry Reasoning',
+        description: 'Retry a failed reasoning task with modified parameters.',
+    },
+];
+export function getPromptContracts() {
+    return PROMPT_CONTRACTS;
+}

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(): readonly ToolContract[];

package/dist/lib/tool-contracts.js

@@ -0,0 +1,93 @@
+const TOOL_CONTRACTS = [
+    {
+        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}}',
+    },
+];
+export function getToolContracts() {
+    return TOOL_CONTRACTS;
+}

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

@@ -1,6 +1,9 @@
 import type { ContentBlock, TextResourceContents } from '@modelcontextprotocol/sdk/types.js';
+import type { IconMeta } from './types.js';
+export declare function withIconMeta(iconMeta?: IconMeta): {
+    icons: IconMeta[];
+} | undefined;
 export declare function createToolResponse<T extends object>(structured: T, embeddedResource?: TextResourceContents): {
     content: ContentBlock[];
     structuredContent: T;
 };
-//# sourceMappingURL=tool-response.d.ts.map

package/dist/lib/tool-response.js

@@ -1,3 +1,6 @@
+export function withIconMeta(iconMeta) {
+    return iconMeta ? { icons: [iconMeta] } : undefined;
+}
 function createStructuredTextBlock(structured) {
     return { type: 'text', text: JSON.stringify(structured) };
 }
@@ -13,4 +16,3 @@ export function createToolResponse(structured, embeddedResource) {
         structuredContent: structured,
     };
 }
-//# sourceMappingURL=tool-response.js.map

package/dist/lib/types.d.ts

@@ -1,6 +1,23 @@
 export type ReasoningLevel = 'basic' | 'normal' | 'high';
+export declare const REASONING_LEVELS: readonly ["basic", "normal", "high"];
+/** Shared level bounds — single source of truth for min/maxThoughts per level. */
+export declare const LEVEL_BOUNDS: {
+    readonly basic: {
+        readonly minThoughts: 3;
+        readonly maxThoughts: 5;
+    };
+    readonly normal: {
+        readonly minThoughts: 6;
+        readonly maxThoughts: 10;
+    };
+    readonly high: {
+        readonly minThoughts: 15;
+        readonly maxThoughts: 25;
+    };
+};
 export type ReasoningRunMode = 'step' | 'run_to_completion';
 export type SessionStatus = 'active' | 'completed' | 'cancelled';
+export declare const SESSION_STATUSES: readonly ["active", "completed", "cancelled"];
 interface Timestamped {
     readonly createdAt: number;
     readonly updatedAt: number;
@@ -19,6 +36,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 +55,3 @@ export interface IconMeta {
     sizes?: string[];
 }
 export {};
-//# sourceMappingURL=types.d.ts.map

package/dist/lib/types.js

@@ -1,2 +1,8 @@
-export {};
-//# sourceMappingURL=types.js.map
+export const REASONING_LEVELS = ['basic', 'normal', 'high'];
+/** Shared level bounds — single source of truth for min/maxThoughts per level. */
+export const LEVEL_BOUNDS = {
+    basic: { minThoughts: 3, maxThoughts: 5 },
+    normal: { minThoughts: 6, maxThoughts: 10 },
+    high: { minThoughts: 15, maxThoughts: 25 },
+};
+export const SESSION_STATUSES = ['active', 'completed', 'cancelled'];

package/dist/lib/validators.d.ts

@@ -1,7 +1,12 @@
-import type { ReasoningLevel } from './types.js';
+import { type ReasoningLevel } from './types.js';
 export declare function getThoughtBounds(level: ReasoningLevel): {
     minThoughts: number;
     maxThoughts: number;
 };
 export declare function getTargetThoughtsError(level: ReasoningLevel, targetThoughts: number): string | undefined;
-//# sourceMappingURL=validators.d.ts.map
+/**
+ * Parse a positive integer from an environment variable, returning `fallback`
+ * if the variable is absent or invalid. Values below `minimum` also fall back.
+ */
+export declare function parsePositiveIntEnv(name: string, fallback: number, minimum?: number): number;
+export declare function collectPrefixMatches(candidates: readonly string[], value: string, limit: number): string[];

package/dist/lib/validators.js

@@ -1,14 +1,9 @@
-/** Level-specific thought count boundaries for validation. */
-const THOUGHT_BOUNDS = Object.freeze({
-    basic: Object.freeze({ minThoughts: 3, maxThoughts: 5 }),
-    normal: Object.freeze({ minThoughts: 6, maxThoughts: 10 }),
-    high: Object.freeze({ minThoughts: 15, maxThoughts: 25 }),
-});
+import { LEVEL_BOUNDS } from './types.js';
 function isOutOfBounds(value, bounds) {
     return value < bounds.minThoughts || value > bounds.maxThoughts;
 }
 export function getThoughtBounds(level) {
-    return THOUGHT_BOUNDS[level];
+    return LEVEL_BOUNDS[level];
 }
 export function getTargetThoughtsError(level, targetThoughts) {
     if (!Number.isInteger(targetThoughts)) {
@@ -20,4 +15,31 @@ export function getTargetThoughtsError(level, targetThoughts) {
     }
     return undefined;
 }
-//# sourceMappingURL=validators.js.map
+/**
+ * Parse a positive integer from an environment variable, returning `fallback`
+ * if the variable is absent or invalid. Values below `minimum` also fall back.
+ */
+export 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;
+}
+export function collectPrefixMatches(candidates, value, limit) {
+    const results = [];
+    for (const candidate of candidates) {
+        if (!candidate.startsWith(value)) {
+            continue;
+        }
+        results.push(candidate);
+        if (results.length >= limit) {
+            break;
+        }
+    }
+    return results;
+}

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