@j0hanz/cortex-mcp 0.1.2

package/dist/engine/reasoner.js

@@ -0,0 +1,208 @@
+import { Buffer } from 'node:buffer';
+import { createSegmenter, truncate } from '../lib/text.js';
+import { assertTargetThoughtsInRange, LEVEL_CONFIGS } from './config.js';
+import { runWithContext } from './context.js';
+import { engineEvents } from './events.js';
+import { SessionStore } from './session-store.js';
+const sessionStore = new SessionStore();
+const graphemeSegmenter = createSegmenter('grapheme');
+const sentenceSegmenter = createSegmenter('sentence');
+const sessionLocks = new Map();
+export { sessionStore };
+export async function reason(query, level, options) {
+    const { sessionId, targetThoughts, abortSignal, onProgress } = options ?? {};
+    const config = LEVEL_CONFIGS[level];
+    const session = resolveSession(level, sessionId, query, config, targetThoughts);
+    const { totalThoughts } = session;
+    return runWithContext({ sessionId: session.id, ...(abortSignal ? { abortSignal } : {}) }, () => withSessionLock(session.id, async () => {
+        throwIfReasoningAborted(abortSignal);
+        const current = getSessionOrThrow(session.id);
+        if (current.tokensUsed >= config.tokenBudget) {
+            emitBudgetExhausted({
+                sessionId: session.id,
+                tokensUsed: current.tokensUsed,
+                tokenBudget: config.tokenBudget,
+                generatedThoughts: 0,
+                requestedThoughts: totalThoughts,
+            });
+            return current;
+        }
+        const nextIndex = current.thoughts.length;
+        if (nextIndex >= totalThoughts) {
+            return current;
+        }
+        const stepContent = generateReasoningStep(query, nextIndex, totalThoughts);
+        if (!stepContent) {
+            throw new Error(`Step content missing at index ${String(nextIndex)}/${String(totalThoughts)}`);
+        }
+        const thought = sessionStore.addThought(session.id, stepContent);
+        engineEvents.emit('thought:added', {
+            sessionId: session.id,
+            index: thought.index,
+            content: thought.content,
+        });
+        const updated = getSessionOrThrow(session.id);
+        if (updated.tokensUsed >= config.tokenBudget) {
+            emitBudgetExhausted({
+                sessionId: session.id,
+                tokensUsed: updated.tokensUsed,
+                tokenBudget: config.tokenBudget,
+                generatedThoughts: thought.index + 1,
+                requestedThoughts: totalThoughts,
+            });
+        }
+        if (onProgress) {
+            await onProgress(thought.index + 1, totalThoughts);
+            throwIfReasoningAborted(abortSignal);
+        }
+        return getSessionOrThrow(session.id);
+    }));
+}
+async function withSessionLock(sessionId, fn) {
+    const previous = sessionLocks.get(sessionId) ?? Promise.resolve();
+    let release;
+    const next = new Promise((resolve) => {
+        release = resolve;
+    });
+    const currentTail = previous.then(() => next);
+    sessionLocks.set(sessionId, currentTail);
+    await previous;
+    try {
+        return await fn();
+    }
+    finally {
+        release?.();
+        if (sessionLocks.get(sessionId) === currentTail) {
+            sessionLocks.delete(sessionId);
+        }
+    }
+}
+function getSessionOrThrow(sessionId) {
+    const session = sessionStore.get(sessionId);
+    if (!session) {
+        throw new Error(`Session not found: ${sessionId}`);
+    }
+    return session;
+}
+function emitBudgetExhausted(data) {
+    engineEvents.emit('thought:budget-exhausted', data);
+}
+function resolveSession(level, sessionId, query, config, targetThoughts) {
+    if (sessionId) {
+        const existing = sessionStore.get(sessionId);
+        if (!existing) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        if (existing.level !== level) {
+            throw new Error(`Session level mismatch: requested ${level}, existing ${existing.level}`);
+        }
+        if (targetThoughts !== undefined &&
+            targetThoughts !== existing.totalThoughts) {
+            throw new Error(`targetThoughts must be ${String(existing.totalThoughts)} for the existing session`);
+        }
+        return existing;
+    }
+    const totalThoughts = resolveThoughtCount(level, query, config, targetThoughts);
+    const session = sessionStore.create(level, totalThoughts);
+    engineEvents.emit('session:created', {
+        sessionId: session.id,
+        level,
+    });
+    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 = /\b(compare|analy[sz]e|trade[- ]?off|design|plan)\b/i.test(queryText)
+        ? 0.15
+        : 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 (sentence.segment.trim().length > 0) {
+            count++;
+        }
+    }
+    return count;
+}
+function getStructureDensityScore(queryText) {
+    const sentenceCount = countSentences(queryText);
+    if (sentenceCount > 1) {
+        return (sentenceCount - 1) * 0.08;
+    }
+    const markerMatches = queryText.match(/[?:;,\n]/g)?.length ?? 0;
+    return markerMatches * 0.05;
+}
+function throwIfReasoningAborted(signal) {
+    if (!signal) {
+        return;
+    }
+    try {
+        signal.throwIfAborted();
+    }
+    catch {
+        throw new Error('Reasoning aborted');
+    }
+}
+const OPENING_TEMPLATE = 'Parsing the query and identifying the core problem';
+const MIDDLE_TEMPLATES = [
+    'Identifying key components and constraints',
+    'Breaking down the problem into sub-problems',
+    'Mapping relationships between identified components',
+    'Considering edge cases and boundary conditions',
+    'Surveying the problem space for hidden assumptions',
+    'Clarifying ambiguous terms and scoping the question',
+    'Evaluating potential approaches and methodologies',
+    'Selecting the most promising approach based on trade-offs',
+    'Developing the solution framework step by step',
+    'Checking logical consistency of intermediate conclusions',
+    'Exploring alternative perspectives on the problem',
+    'Assessing confidence levels in preliminary findings',
+    'Identifying assumptions that require verification',
+    'Weighing trade-offs between competing solutions',
+    'Testing preliminary results against known constraints',
+    'Examining second-order effects and implications',
+    'Synthesizing findings from multiple angles of analysis',
+    'Cross-referencing conclusions with initial premises',
+    'Refining the analysis with additional considerations',
+    'Validating the complete reasoning chain for coherence',
+    'Optimizing the reasoning path for gaps or redundancies',
+    'Reviewing the logical flow from premises to conclusion',
+    'Documenting key insights and decision points',
+];
+const CONCLUSION_TEMPLATE = 'Consolidating the final answer with supporting evidence';
+function generateReasoningStep(query, index, total) {
+    if (total <= 0) {
+        return '';
+    }
+    const step = index + 1;
+    if (step === 1) {
+        const truncatedQuery = truncate(query, 200, graphemeSegmenter);
+        return formatStep(step, total, `${OPENING_TEMPLATE}: "${truncatedQuery}"`);
+    }
+    if (step === total) {
+        return formatStep(step, total, CONCLUSION_TEMPLATE);
+    }
+    const template = MIDDLE_TEMPLATES[(step - 2) % MIDDLE_TEMPLATES.length] ?? '';
+    return formatStep(step, total, template);
+}
+function formatStep(step, total, description) {
+    return `Step ${String(step)}/${String(total)}: ${description}`;
+}
+//# sourceMappingURL=reasoner.js.map

package/dist/engine/reasoner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoner.js","sourceRoot":"","sources":["../../src/engine/reasoner.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,17 @@
+import type { ReasoningLevel, Session, Thought } from '../lib/types.js';
+export declare class SessionStore {
+    private readonly sessions;
+    private readonly cleanupInterval;
+    private readonly ttlMs;
+    constructor(ttlMs?: number);
+    create(level: ReasoningLevel, totalThoughts: number): Session;
+    get(id: string): Readonly<Session> | undefined;
+    list(): Session[];
+    getTtlMs(): number;
+    getExpiresAt(sessionId: string): number | undefined;
+    delete(id: string): boolean;
+    addThought(sessionId: string, content: string): Thought;
+    reviseThought(sessionId: string, thoughtIndex: number, content: string): Thought;
+    private sweep;
+}
+//# sourceMappingURL=session-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.d.ts","sourceRoot":"","sources":["../../src/engine/session-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAEV,cAAc,EACd,OAAO,EACP,OAAO,EACR,MAAM,iBAAiB,CAAC;AAYzB,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IACvD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,KAAK,GAAE,MAAuB;IAS1C,MAAM,CAAC,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO;IAkB7D,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,SAAS;IAI9C,IAAI,IAAI,OAAO,EAAE;IAMjB,QAAQ,IAAI,MAAM;IAIlB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAQnD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAS3B,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAmBvD,aAAa,CACX,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,GACd,OAAO;IA2BV,OAAO,CAAC,KAAK;CAcd"}

package/dist/engine/session-store.js

@@ -0,0 +1,120 @@
+import { Buffer } from 'node:buffer';
+import { randomUUID } from 'node:crypto';
+import { LEVEL_CONFIGS } from './config.js';
+import { engineEvents } from './events.js';
+const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 minutes
+function estimateTokens(text) {
+    const byteLength = Buffer.byteLength(text, 'utf8');
+    return Math.max(1, Math.ceil(byteLength / 4));
+}
+export class SessionStore {
+    sessions = new Map();
+    cleanupInterval;
+    ttlMs;
+    constructor(ttlMs = DEFAULT_TTL_MS) {
+        this.ttlMs = ttlMs;
+        const sweepInterval = Math.max(10, Math.min(60_000, ttlMs));
+        this.cleanupInterval = setInterval(() => {
+            this.sweep();
+        }, sweepInterval);
+        this.cleanupInterval.unref();
+    }
+    create(level, totalThoughts) {
+        const config = LEVEL_CONFIGS[level];
+        const now = Date.now();
+        const session = {
+            id: randomUUID(),
+            level,
+            thoughts: [],
+            totalThoughts,
+            tokenBudget: config.tokenBudget,
+            tokensUsed: 0,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.sessions.set(session.id, session);
+        engineEvents.emit('resources:changed', { uri: 'reasoning://sessions' });
+        return session;
+    }
+    get(id) {
+        return this.sessions.get(id);
+    }
+    list() {
+        return [...this.sessions.values()].sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    getTtlMs() {
+        return this.ttlMs;
+    }
+    getExpiresAt(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return undefined;
+        }
+        return session.updatedAt + this.ttlMs;
+    }
+    delete(id) {
+        const deleted = this.sessions.delete(id);
+        if (deleted) {
+            engineEvents.emit('session:deleted', { sessionId: id });
+            engineEvents.emit('resources:changed', { uri: 'reasoning://sessions' });
+        }
+        return deleted;
+    }
+    addThought(sessionId, content) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        const thought = {
+            index: session.thoughts.length,
+            content,
+            revision: 0,
+        };
+        session.thoughts.push(thought);
+        session.tokensUsed += estimateTokens(content);
+        session.updatedAt = Date.now();
+        engineEvents.emit('resource:updated', {
+            uri: `reasoning://sessions/${sessionId}`,
+        });
+        return thought;
+    }
+    reviseThought(sessionId, thoughtIndex, content) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        const existing = session.thoughts[thoughtIndex];
+        if (!existing) {
+            throw new Error(`Thought index ${String(thoughtIndex)} not found in session ${sessionId}`);
+        }
+        const oldTokens = estimateTokens(existing.content);
+        const revised = {
+            index: thoughtIndex,
+            content,
+            revision: existing.revision + 1,
+        };
+        session.thoughts[thoughtIndex] = revised;
+        session.tokensUsed =
+            session.tokensUsed - oldTokens + estimateTokens(content);
+        session.updatedAt = Date.now();
+        engineEvents.emit('resource:updated', {
+            uri: `reasoning://sessions/${sessionId}`,
+        });
+        return revised;
+    }
+    sweep() {
+        const now = Date.now();
+        let changed = false;
+        for (const session of this.sessions.values()) {
+            if (session.updatedAt + this.ttlMs < now) {
+                this.sessions.delete(session.id);
+                engineEvents.emit('session:expired', { sessionId: session.id });
+                changed = true;
+            }
+        }
+        if (changed) {
+            engineEvents.emit('resources:changed', { uri: 'reasoning://sessions' });
+        }
+    }
+}
+//# sourceMappingURL=session-store.js.map

package/dist/engine/session-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.js","sourceRoot":"","sources":["../../src/engine/session-store.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

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

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { isMainThread, threadId } from 'node:worker_threads';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+let activeServer;
+let shutdownPromise;
+function assertMainThread() {
+    if (isMainThread) {
+        return;
+    }
+    throw new Error(`cortex-mcp must run on the main thread (received worker thread ${String(threadId)}).`);
+}
+async function main() {
+    assertMainThread();
+    activeServer = createServer();
+    const transport = new StdioServerTransport();
+    await activeServer.connect(transport);
+}
+async function shutdown(exitCode, reason) {
+    if (shutdownPromise) {
+        return shutdownPromise;
+    }
+    shutdownPromise = (async () => {
+        let resolvedCode = exitCode;
+        try {
+            await activeServer?.close();
+        }
+        catch (err) {
+            resolvedCode = 1;
+            console.error(`Shutdown failure (${reason}):`, err);
+        }
+        finally {
+            process.exit(resolvedCode);
+        }
+    })();
+    return shutdownPromise;
+}
+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');
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,IAAI,YAAyD,CAAC;AAC9D,IAAI,eAA0C,CAAC;AAE/C,SAAS,gBAAgB;IACvB,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO;IACT,CAAC;IACD,MAAM,IAAI,KAAK,CACb,kEAAkE,MAAM,CAAC,QAAQ,CAAC,IAAI,CACvF,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,gBAAgB,EAAE,CAAC;IACnB,YAAY,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AACxC,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,QAAgB,EAAE,MAAc;IACtD,IAAI,eAAe,EAAE,CAAC;QACpB,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,eAAe,GAAG,CAAC,KAAK,IAAI,EAAE;QAC5B,IAAI,YAAY,GAAG,QAAQ,CAAC;QAE5B,IAAI,CAAC;YACH,MAAM,YAAY,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,YAAY,GAAG,CAAC,CAAC;YACjB,OAAO,CAAC,KAAK,CAAC,qBAAqB,MAAM,IAAI,EAAE,GAAG,CAAC,CAAC;QACtD,CAAC;gBAAS,CAAC;YACT,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;IAEL,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;IACnC,KAAK,QAAQ,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC;AAClC,CAAC,CAAC,CAAC;AAEH,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE;IAC3B,KAAK,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;AAC9B,CAAC,CAAC,CAAC;AACH,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE;IAC1B,KAAK,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;AAC7B,CAAC,CAAC,CAAC"}

package/dist/instructions.md

@@ -0,0 +1,131 @@
+# CORTEX-MCP INSTRUCTIONS
+
+These instructions are available as a resource (internal://instructions) or prompt (get-help). Load them when unsure about tool usage.
+
+---
+
+## CORE CAPABILITY
+
+- Domain: Multi-level reasoning engine that decomposes queries into structured thought chains at configurable depth levels (basic, normal, high).
+- Primary Resources: Reasoning sessions (in-memory, 30-minute TTL), thought chains, progress notifications.
+- Tools: `reasoning.think` (WRITE — creates/extends sessions with generated thoughts).
+
+---
+
+## PROMPTS
+
+- `get-help`: Returns these instructions for quick recall.
+- `reasoning.basic`: Prepare a basic-depth reasoning request (3–5 thoughts).
+- `reasoning.normal`: Prepare a normal-depth reasoning request (6–10 thoughts).
+- `reasoning.high`: Prepare a high-depth reasoning request (15–25 thoughts).
+- `reasoning.continue`: Continue an existing reasoning session with a follow-up query.
+
+---
+
+## RESOURCES & RESOURCE LINKS
+
+- `internal://instructions`: This document.
+- `reasoning://sessions`: List all active reasoning sessions with metadata (JSON).
+- `reasoning://sessions/{sessionId}`: Inspect a specific session's thoughts and metadata (JSON). Supports auto-completion on `sessionId`.
+
+### Resource Subscriptions
+
+- The server supports `resources/subscribe` for real-time change notifications on individual resources.
+- Subscribe to `reasoning://sessions/{sessionId}` to receive `notifications/resources/updated` when thoughts are added or revised.
+- Use subscriptions to monitor session progress without polling.
+
+---
+
+## PROGRESS & TASKS
+
+- Include `_meta.progressToken` in requests to receive `notifications/progress` updates during reasoning.
+- Task-augmented tool calls are supported for `reasoning.think`:
+  - `execution.taskSupport: "optional"` — invoke normally or as a task.
+  - Send `tools/call` with `task` to get a task id.
+  - Poll `tasks/get` and fetch results via `tasks/result`.
+  - Use `tasks/cancel` to abort a running task.
+  - For `high` level, progress is emitted every 2 steps to reduce noise; `basic` and `normal` emit after every step.
+
+---
+
+## THE "GOLDEN PATH" WORKFLOWS (CRITICAL)
+
+### WORKFLOW A: Sequential Reasoning
+
+1. Call `reasoning.think` with `{ query: "...", level: "basic" | "normal" | "high" }`.
+2. Read `result.thoughts` for the accumulated reasoning chain (each call appends at most one new thought).
+3. Repeat calls with the same `sessionId` until `result.totalThoughts` is reached.
+   NOTE: Choose level based on query complexity — `basic` for straightforward questions, `high` for multi-faceted analysis.
+
+### WORKFLOW B: Multi-Turn Reasoning (Session Continuation)
+
+1. Call `reasoning.think` with `{ query: "initial question", level: "normal" }` — note the returned `sessionId`.
+2. Call `reasoning.think` with `{ query: "follow-up", level: "normal", sessionId: "<id>" }` to append the next thought.
+3. Repeat until `result.totalThoughts` is reached, then read `reasoning://sessions/{sessionId}` for the full chain.
+   NOTE: The `level` MUST match the original session level. Mismatches return `E_SESSION_LEVEL_MISMATCH`.
+
+### WORKFLOW C: Controlled Depth Reasoning
+
+1. Call `reasoning.think` with `{ query: "...", level: "normal", targetThoughts: 8 }` to set the session's planned step count.
+2. Repeat calls with the returned `sessionId` until `result.totalThoughts` is reached.
+   NOTE: `targetThoughts` must fall within the level range (basic: 3–5, normal: 6–10, high: 15–25). Out-of-range values return `E_INVALID_THOUGHT_COUNT`.
+
+### WORKFLOW D: Async Task Execution
+
+1. Call `reasoning.think` as a task (send `tools/call` with `task` field) for long-running `high`-level reasoning.
+2. Poll `tasks/get` until status is `completed` or `failed`.
+3. Retrieve the result via `tasks/result`.
+4. Use `tasks/cancel` to abort if needed.
+
+---
+
+## TOOL NUANCES & GOTCHAS
+
+`reasoning.think`
+
+- Purpose: Generate a multi-step reasoning chain for a given query at a specified depth level.
+- Input:
+  - `query` (string, 1–10,000 chars): The question or problem to reason about.
+  - `level` (enum: `basic` | `normal` | `high`): Controls reasoning depth and token budget.
+  - `targetThoughts` (int, 1–25, optional): Override automatic step count. Must fit within the level range.
+  - `sessionId` (string, 1–128 chars, optional): Continue an existing session. Level must match.
+- Output: `{ ok, result: { sessionId, level, thoughts[], generatedThoughts, requestedThoughts, totalThoughts, tokenBudget, tokensUsed, ttlMs, expiresAt, createdAt, updatedAt, summary } }`
+- Side effects: Creates or modifies an in-memory session. Sessions expire after 30 minutes of inactivity.
+- Gotcha: Each call appends at most one thought. When continuing a session, `generatedThoughts` reflects only the newly added thought (0 or 1), not the cumulative total.
+- Gotcha: `requestedThoughts` is the effective requested count for this run: it equals `targetThoughts` when provided, otherwise `totalThoughts`.
+- Gotcha: Token counting is approximate (UTF-8 byte length ÷ 4), not true tokenization.
+- Gotcha: Without `targetThoughts`, the planned step count (`totalThoughts`) is determined by a heuristic based on query length and structural complexity (punctuation markers, keywords like "compare", "analyse", "trade-off").
+- Limits: Level ranges — basic: 3–5 thoughts (2K token budget), normal: 6–10 (8K), high: 15–25 (32K).
+
+---
+
+## CROSS-FEATURE RELATIONSHIPS
+
+- Use `reasoning.basic` / `reasoning.normal` / `reasoning.high` prompts to construct a correctly parameterized `reasoning.think` call.
+- Use `reasoning.continue` prompt to construct a session-continuation call — it enforces `sessionId` and `level` pairing.
+- After calling `reasoning.think`, read `reasoning://sessions/{sessionId}` to retrieve the full session state including all accumulated thoughts.
+- Use `reasoning://sessions` to discover active sessions before attempting continuation — avoids `E_SESSION_NOT_FOUND`.
+
+---
+
+## CONSTRAINTS & LIMITATIONS
+
+- Sessions are in-memory — all data is lost on process restart.
+- Session TTL: 30 minutes from last update. Expired sessions cannot be recovered.
+- Maximum query length: 10,000 characters.
+- Token budget enforcement is approximate (character-based proxy, not true tokenization).
+- stdio transport only — no HTTP endpoint available.
+- Reasoning steps are structural decompositions, not LLM-generated content.
+- `targetThoughts` must be an integer within the level's min/max range.
+
+---
+
+## ERROR HANDLING STRATEGY
+
+- `E_SESSION_NOT_FOUND`: Session expired or never existed. Call `reasoning://sessions` to list active sessions, or start a new session without `sessionId`.
+- `E_SESSION_LEVEL_MISMATCH`: Requested level differs from the existing session. Use the same level as the original session, or start a new session.
+- `E_INVALID_THOUGHT_COUNT`: `targetThoughts` is outside the level range. Check ranges: basic (3–5), normal (6–10), high (15–25).
+- `E_ABORTED`: Reasoning was cancelled via abort signal or task cancellation. Retry with a new request if needed.
+- `E_REASONING`: Unexpected engine error. Check the error `message` field for details and retry.
+
+---

package/dist/lib/errors.d.ts

@@ -0,0 +1,19 @@
+interface ErrorResponse {
+    [key: string]: unknown;
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    structuredContent: {
+        ok: false;
+        error: {
+            code: string;
+            message: string;
+        };
+    };
+    isError: true;
+}
+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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAOA,UAAU,aAAa;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC1C,iBAAiB,EAAE;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IAC3E,OAAO,EAAE,IAAI,CAAC;CACf;AAWD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAiBtD;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,aAAa,CAOf"}

package/dist/lib/errors.js

@@ -0,0 +1,41 @@
+import { inspect } from 'node:util';
+const INSPECT_OPTIONS = {
+    depth: 3,
+    breakLength: 120,
+};
+function stringifyUnknown(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        // Fall through to inspect-based serialization.
+    }
+    return inspect(value, INSPECT_OPTIONS);
+}
+export function getErrorMessage(error) {
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (error === null || error === undefined) {
+        return 'Unknown error';
+    }
+    if (typeof error === 'object') {
+        const maybeError = error;
+        if (typeof maybeError.message === 'string') {
+            return maybeError.message;
+        }
+    }
+    return stringifyUnknown(error);
+}
+export function createErrorResponse(code, message) {
+    const structured = { ok: false, error: { code, message } };
+    return {
+        content: [{ type: 'text', text: JSON.stringify(structured) }],
+        structuredContent: structured,
+        isError: true,
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,eAAe,GAAG;IACtB,KAAK,EAAE,CAAC;IACR,WAAW,EAAE,GAAG;CACR,CAAC;AASX,SAAS,gBAAgB,CAAC,KAAc;IACtC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,+CAA+C;IACjD,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,OAAO,eAAe,CAAC;IACzB,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,UAAU,GAAG,KAA8B,CAAC;QAClD,IAAI,OAAO,UAAU,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC3C,OAAO,UAAU,CAAC,OAAO,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,OAAe;IAEf,MAAM,UAAU,GAAG,EAAE,EAAE,EAAE,KAAc,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC;IACpE,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;QACtE,iBAAiB,EAAE,UAAU;QAC7B,OAAO,EAAE,IAAa;KACvB,CAAC;AACJ,CAAC"}

package/dist/lib/instructions.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Loads the instructions from the instructions.md file. If the file cannot be read or is empty, returns a fallback message.
+ */
+export declare function loadInstructions(fallback?: string): string;
+//# sourceMappingURL=instructions.d.ts.map

package/dist/lib/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/lib/instructions.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,SAAiC,GACxC,MAAM,CAUR"}