@j0hanz/cortex-mcp 1.5.0 → 1.7.0

package/dist/prompts/templates.js

@@ -3,99 +3,220 @@
 // Each template shows correct `thought` depth and step count so the LLM
 // calibrates its output to the selected level requirements.
 // ---------------------------------------------------------------------------
-const BASIC_TEMPLATE = `## Guided Example (basic — 3 thoughts)
-
-**Query:** "Is Set or Array better for deduplicating a list of strings in JavaScript?"
-
-**Thought 1 of 3:**
-> A \`Set\` enforces uniqueness automatically; \`[...new Set(arr)]\` is a single-step O(n) operation. An Array-based approach (\`filter\` + \`indexOf\`) is O(n²) and adds unnecessary complexity.
-
-**Thought 2 of 3:**
-> Edge cases: both preserve insertion order in modern JS engines, so ordering is not a differentiator. \`Set\` converts all values to a common reference internally, which handles string equality correctly.
-
-**Thought 3 of 3 — conclusion:**
-> Use \`Set\`. It is faster (O(n) vs O(n²)), shorter to write, and immediately communicates the intent of deduplication. \`[...new Set(list)]\` is the idiomatic solution.
-
----
-**System Directive:** Follow the pattern above. Each \`thought\` must contain self-contained, concrete analysis — no filler language or meta-commentary. Use 3 to 5 thoughts total.`;
-const NORMAL_TEMPLATE = `## Guided Example (normal — 7 thoughts)
-
-**Query:** "How do I safely handle concurrent writes to a shared in-memory counter in a Node.js service?"
-
-**Thought 1 of 7:**
-> Node.js is single-threaded: synchronous code is never interrupted mid-execution, so a plain \`counter++\` within one event-loop tick is effectively atomic from JavaScript's perspective.
-
-**Thought 2 of 7:**
-> The risk arises in *async* code. A read-modify-write spanning an \`await\` boundary is NOT atomic. Two concurrent callers can both read the same value before either writes, causing a lost update.
-
-**Thought 3 of 7:**
-> Example race: \`const v = await db.get('c'); await db.set('c', v + 1);\` — if two requests interleave at the \`await\` points, both read \`v=5\` and both write \`6\`, losing one increment.
-
-**Thought 4 of 7:**
-> Solution A — atomic DB operation: \`UPDATE counter SET n = n + 1 RETURNING n\` (SQL) or Redis \`INCR\`. The DB engine serialises the read-modify-write internally with no async gap.
-
-**Thought 5 of 7:**
-> Solution B — async mutex: use a library-level lock (e.g. \`async-mutex\`) to serialise access. Works for in-process state but does not scale across multiple processes or restarts.
-
-**Thought 6 of 7:**
-> Solution C — synchronous in-memory only: keep the counter as a plain variable, increment with \`counter++\` (no \`await\` in the read-modify-write path). Valid only for single-process, ephemeral state.
-
-**Thought 7 of 7 — conclusion:**
-> Prefer Solution A (atomic DB op) for correctness across restarts and multi-process deployments. Use Solution C only for in-process, non-persisted counters where an \`await\` never touches the variable. Avoid async read-modify-write without a mutex.
-
----
-**System Directive:** Follow the pattern above. Each \`thought\` must be concrete and progress the analysis. Use 6 to 10 thoughts total; avoid restating earlier thoughts.`;
-const HIGH_TEMPLATE = `## Guided Example (high — 15 thoughts)
-
-**Query:** "Our Node.js API latency jumped from p50=20ms to p50=800ms after a dependency upgrade. How do I diagnose and fix this?"
-
-**Thought 1 of 15:**
-> Establish the change boundary: run \`git log --oneline\` to find the upgrade commit. Use \`git bisect\` between the last known-good tag and HEAD to confirm the exact commit that caused the regression.
-
-**Thought 2 of 15:**
-> Collect baseline metrics before touching anything: event-loop lag (\`perf_hooks.monitorEventLoopDelay\`), GC pause times (\`--expose-gc\` + \`PerformanceObserver\`), and per-route timings. This separates compute regressions from I/O regressions.
-
-**Thought 3 of 15:**
-> If event-loop lag is high (>50ms per tick), the cause is synchronous blocking inserted into the hot path — JSON serialisation of large objects, synchronous file I/O, regex backtracking, or CPU-heavy validation.
-
-**Thought 4 of 15:**
-> If event-loop lag is low but p50 is high, the bottleneck is I/O wait: slow DB queries, connection-pool exhaustion, DNS resolution delays, or increased network RTT to the upgraded service.
-
-**Thought 5 of 15:**
-> Read the dependency's changelog between the old and new version. Look for: new middleware injected at startup, serialisation format changes, default timeout changes, or connection-pool default reductions.
-
-**Thought 6 of 15:**
-> Profile with \`clinic.js flame\` (or \`node --prof\` + \`node --prof-process\`) under representative load. The flame graph will pinpoint whether wall-clock time is in JS compute vs. idle I/O await.
-
-**Thought 7 of 15:**
-> Write a minimal reproduction that calls *only* the upgraded package's API with representative input. Benchmark it against the pinned old version in isolation to confirm the package itself is the source.
-
-**Thought 8 of 15:**
-> Common 40× regression patterns: (a) added synchronous schema validation on every request, (b) HTTP/1.1 → HTTP/2 frame parsing overhead, (c) new middleware that buffers the full request body before routing.
-
-**Thought 9 of 15:**
-> Check connection-pool configuration: if the upgrade changed default pool size or idle timeout, requests may queue waiting for connections. Inspect \`pool.min\`, \`pool.max\`, and \`acquireTimeoutMillis\` in the new version's defaults.
-
-**Thought 10 of 15:**
-> Check middleware registration order: some packages inject global middleware at \`require\`-time. A slow middleware (e.g., large-payload body parser) before fast routes affects all endpoints even if the route itself is unchanged.
-
-**Thought 11 of 15:**
-> Immediate mitigation: pin the dependency to the last known-good version (\`npm install dep@x.y.z\`) and deploy to restore SLA while the full investigation continues. Add a TODO linking to the issue tracker.
-
-**Thought 12 of 15:**
-> If the regression is a bug in the dependency, open an issue with the minimal reproduction from Thought 7. Check if a patch release or a configuration flag exists to disable the slow behaviour.
-
-**Thought 13 of 15:**
-> If the slow path is unavoidable, mitigation options: (a) cache the expensive result at the request or process level, (b) offload CPU work to a \`worker_threads\` worker, (c) evaluate an alternative package.
-
-**Thought 14 of 15:**
-> After applying the fix, run the same load test that revealed the regression. Confirm p50 and p99 return to baseline and do not diverge under sustained load. Check that GC pressure did not increase.
-
-**Thought 15 of 15 — conclusion:**
-> Diagnosis path: git bisect → event-loop lag check → clinic.js flame graph → isolated package benchmark → changelog review → pool/middleware audit. Mitigation: pin version immediately. Fix: configure, cache, or replace. Prevention: add a latency benchmark target to CI.
-
----
-**System Directive:** Follow the pattern above. Each \`thought\` must be specific, advancing the investigation — no summaries of prior steps, no filler. Use 15 to 25 thoughts total; scale depth to complexity.`;
+const BASIC_TEMPLATE = `<example>
+<query>Is Set or Array better for deduplicating a list of strings in JavaScript?</query>
+
+<thought_process>
+<step index="1" total="3">
+<thought>
+[Observation] A \`Set\` enforces uniqueness automatically; \`[...new Set(arr)]\` is a single-step O(n) operation. An Array-based approach (\`filter\` + \`indexOf\`) is O(n²) and adds unnecessary complexity.
+</thought>
+<step_summary>Set is O(n) while Array filter is O(n²).</step_summary>
+</step>
+
+<step index="2" total="3">
+<thought>
+[Evaluation] Edge cases: both preserve insertion order in modern JS engines, so ordering is not a differentiator. \`Set\` converts all values to a common reference internally, which handles string equality correctly.
+</thought>
+<step_summary>Both preserve order, but Set handles string equality natively.</step_summary>
+</step>
+
+<step index="3" total="3">
+<thought>
+[Conclusion] Use \`Set\`. It is faster (O(n) vs O(n²)), shorter to write, and immediately communicates the intent of deduplication. \`[...new Set(list)]\` is the idiomatic solution.
+</thought>
+<step_summary>Set is the optimal and idiomatic choice.</step_summary>
+</step>
+</thought_process>
+</example>
+
+<constraints>
+- Match the depth and quality of the example above.
+- Structure reasoning using: [Observation], [Hypothesis], [Evaluation], [Conclusion].
+- Write concrete, self-contained thoughts. No filler.
+- Provide a 1-sentence \`step_summary\` per step.
+- Total thoughts: 3 to 5.
+</constraints>`;
+const NORMAL_TEMPLATE = `<example>
+<query>How do I safely handle concurrent writes to a shared in-memory counter in a Node.js service?</query>
+
+<thought_process>
+<step index="1" total="7">
+<thought>
+[Observation] Node.js is single-threaded: synchronous code is never interrupted mid-execution, so a plain \`counter++\` within one event-loop tick is effectively atomic from JavaScript's perspective.
+</thought>
+<step_summary>Synchronous increments in Node.js are atomic.</step_summary>
+</step>
+
+<step index="2" total="7">
+<thought>
+[Hypothesis] The risk arises in *async* code. A read-modify-write spanning an \`await\` boundary is NOT atomic. Two concurrent callers can both read the same value before either writes, causing a lost update.
+</thought>
+<step_summary>Async read-modify-write operations are not atomic and risk lost updates.</step_summary>
+</step>
+
+<step index="3" total="7">
+<thought>
+[Evaluation] Example race: \`const v = await db.get('c'); await db.set('c', v + 1);\` — if two requests interleave at the \`await\` points, both read \`v=5\` and both write \`6\`, losing one increment.
+</thought>
+<step_summary>Interleaved async operations lead to data races.</step_summary>
+</step>
+
+<step index="4" total="7">
+<thought>
+[Strategy] Solution A — atomic DB operation: \`UPDATE counter SET n = n + 1 RETURNING n\` (SQL) or Redis \`INCR\`. The DB engine serialises the read-modify-write internally with no async gap.
+</thought>
+<step_summary>Database-level atomic operations prevent races.</step_summary>
+</step>
+
+<step index="5" total="7">
+<thought>
+[Strategy] Solution B — async mutex: use a library-level lock (e.g. \`async-mutex\`) to serialise access. Works for in-process state but does not scale across multiple processes or restarts.
+</thought>
+<step_summary>In-process mutexes work but don't scale horizontally.</step_summary>
+</step>
+
+<step index="6" total="7">
+<thought>
+[Strategy] Solution C — synchronous in-memory only: keep the counter as a plain variable, increment with \`counter++\` (no \`await\` in the read-modify-write path). Valid only for single-process, ephemeral state.
+</thought>
+<step_summary>Synchronous in-memory counters are safe for ephemeral, single-process state.</step_summary>
+</step>
+
+<step index="7" total="7">
+<thought>
+[Conclusion] Prefer Solution A (atomic DB op) for correctness across restarts and multi-process deployments. Use Solution C only for in-process, non-persisted counters where an \`await\` never touches the variable. Avoid async read-modify-write without a mutex.
+</thought>
+<step_summary>Use DB atomic ops for persistence, or sync variables for ephemeral state.</step_summary>
+</step>
+</thought_process>
+</example>
+
+<constraints>
+- Match the depth and quality of the example above.
+- Structure reasoning using: [Observation], [Hypothesis], [Evaluation], [Strategy], [Conclusion].
+- Write concrete thoughts that progress the analysis. Do not restate earlier thoughts.
+- Provide a 1-sentence \`step_summary\` per step.
+- Total thoughts: 6 to 10.
+</constraints>`;
+const HIGH_TEMPLATE = `<example>
+<query>Our Node.js API latency jumped from p50=20ms to p50=800ms after a dependency upgrade. How do I diagnose and fix this?</query>
+
+<thought_process>
+<step index="1" total="15">
+<thought>
+[Strategy] Establish the change boundary: run \`git log --oneline\` to find the upgrade commit. Use \`git bisect\` between the last known-good tag and HEAD to confirm the exact commit that caused the regression.
+</thought>
+<step_summary>Isolate the exact commit causing the regression using git bisect.</step_summary>
+</step>
+
+<step index="2" total="15">
+<thought>
+[Observation] Collect baseline metrics before touching anything: event-loop lag (\`perf_hooks.monitorEventLoopDelay\`), GC pause times (\`--expose-gc\` + \`PerformanceObserver\`), and per-route timings. This separates compute regressions from I/O regressions.
+</thought>
+<step_summary>Collect baseline metrics to distinguish compute vs I/O regressions.</step_summary>
+</step>
+
+<step index="3" total="15">
+<thought>
+[Hypothesis] If event-loop lag is high (>50ms per tick), the cause is synchronous blocking inserted into the hot path — JSON serialisation of large objects, synchronous file I/O, regex backtracking, or CPU-heavy validation.
+</thought>
+<step_summary>High event-loop lag indicates synchronous blocking.</step_summary>
+</step>
+
+<step index="4" total="15">
+<thought>
+[Hypothesis] If event-loop lag is low but p50 is high, the bottleneck is I/O wait: slow DB queries, connection-pool exhaustion, DNS resolution delays, or increased network RTT to the upgraded service.
+</thought>
+<step_summary>Low event-loop lag with high p50 indicates I/O bottlenecks.</step_summary>
+</step>
+
+<step index="5" total="15">
+<thought>
+[Action] Read the dependency's changelog between the old and new version. Look for: new middleware injected at startup, serialisation format changes, default timeout changes, or connection-pool default reductions.
+</thought>
+<step_summary>Review the dependency changelog for breaking changes or new defaults.</step_summary>
+</step>
+
+<step index="6" total="15">
+<thought>
+[Action] Profile with \`clinic.js flame\` (or \`node --prof\` + \`node --prof-process\`) under representative load. The flame graph will pinpoint whether wall-clock time is in JS compute vs. idle I/O await.
+</thought>
+<step_summary>Use flame graphs to pinpoint the exact bottleneck.</step_summary>
+</step>
+
+<step index="7" total="15">
+<thought>
+[Action] Write a minimal reproduction that calls *only* the upgraded package's API with representative input. Benchmark it against the pinned old version in isolation to confirm the package itself is the source.
+</thought>
+<step_summary>Create a minimal reproduction to isolate the package's performance.</step_summary>
+</step>
+
+<step index="8" total="15">
+<thought>
+[Evaluation] Common 40× regression patterns: (a) added synchronous schema validation on every request, (b) HTTP/1.1 → HTTP/2 frame parsing overhead, (c) new middleware that buffers the full request body before routing.
+</thought>
+<step_summary>Evaluate common regression patterns like added validation or middleware.</step_summary>
+</step>
+
+<step index="9" total="15">
+<thought>
+[Evaluation] Check connection-pool configuration: if the upgrade changed default pool size or idle timeout, requests may queue waiting for connections. Inspect \`pool.min\`, \`pool.max\`, and \`acquireTimeoutMillis\` in the new version's defaults.
+</thought>
+<step_summary>Verify connection-pool configurations for reduced defaults.</step_summary>
+</step>
+
+<step index="10" total="15">
+<thought>
+[Evaluation] Check middleware registration order: some packages inject global middleware at \`require\`-time. A slow middleware (e.g., large-payload body parser) before fast routes affects all endpoints even if the route itself is unchanged.
+</thought>
+<step_summary>Check for slow global middleware affecting all routes.</step_summary>
+</step>
+
+<step index="11" total="15">
+<thought>
+[Mitigation] Immediate mitigation: pin the dependency to the last known-good version (\`npm install dep@x.y.z\`) and deploy to restore SLA while the full investigation continues. Add a TODO linking to the issue tracker.
+</thought>
+<step_summary>Pin the dependency to the last known-good version to restore SLA.</step_summary>
+</step>
+
+<step index="12" total="15">
+<thought>
+[Action] If the regression is a bug in the dependency, open an issue with the minimal reproduction from Thought 7. Check if a patch release or a configuration flag exists to disable the slow behaviour.
+</thought>
+<step_summary>Report the bug upstream with the minimal reproduction.</step_summary>
+</step>
+
+<step index="13" total="15">
+<thought>
+[Strategy] If the slow path is unavoidable, mitigation options: (a) cache the expensive result at the request or process level, (b) offload CPU work to a \`worker_threads\` worker, (c) evaluate an alternative package.
+</thought>
+<step_summary>Consider caching, worker threads, or alternative packages if unavoidable.</step_summary>
+</step>
+
+<step index="14" total="15">
+<thought>
+[Validation] After applying the fix, run the same load test that revealed the regression. Confirm p50 and p99 return to baseline and do not diverge under sustained load. Check that GC pressure did not increase.
+</thought>
+<step_summary>Validate the fix under load to ensure metrics return to baseline.</step_summary>
+</step>
+
+<step index="15" total="15">
+<thought>
+[Conclusion] Diagnosis path: git bisect → event-loop lag check → clinic.js flame graph → isolated package benchmark → changelog review → pool/middleware audit. Mitigation: pin version immediately. Fix: configure, cache, or replace. Prevention: add a latency benchmark target to CI.
+</thought>
+<step_summary>Summarize the diagnosis, mitigation, fix, and prevention strategy.</step_summary>
+</step>
+</thought_process>
+</example>
+
+<constraints>
+- Match the depth and quality of the example above.
+- Structure reasoning using: [Observation], [Hypothesis], [Strategy], [Action], [Evaluation], [Mitigation], [Validation], [Conclusion].
+- Write specific thoughts that advance the investigation. No summaries of prior steps, no filler.
+- Provide a 1-sentence \`step_summary\` per step.
+- Total thoughts: 15 to 25. Scale depth to complexity.
+</constraints>`;
 const TEMPLATES = {
     basic: BASIC_TEMPLATE,
     normal: NORMAL_TEMPLATE,

package/dist/resources/index.js

@@ -3,13 +3,14 @@ import { McpError } from '@modelcontextprotocol/sdk/types.js';
 import { sessionStore } from '../engine/reasoner.js';
 import { formatThoughtsToMarkdown } from '../lib/formatting.js';
 import { withIconMeta } from '../lib/tool-response.js';
-import { collectPrefixMatches } from '../lib/validators.js';
+import { collectPrefixMatches, parseBooleanEnv } from '../lib/validators.js';
 import { buildServerInstructions } from './instructions.js';
 import { buildToolCatalog } from './tool-catalog.js';
 import { buildWorkflowGuide } from './workflows.js';
 const SESSIONS_RESOURCE_URI = 'reasoning://sessions';
 const SESSION_RESOURCE_PREFIX = `${SESSIONS_RESOURCE_URI}/`;
 const TRACE_RESOURCE_PREFIX = 'file:///cortex/sessions/';
+const REDACTED_THOUGHT_CONTENT = '[REDACTED]';
 // --- Helpers ---
 function extractStringVariable(variables, name, uri) {
     const raw = variables[name];
@@ -72,6 +73,25 @@ function completeSessionIds(value) {
 function toIsoTimestamp(unixMs) {
     return new Date(unixMs).toISOString();
 }
+function shouldRedactTraceContent() {
+    return parseBooleanEnv('CORTEX_REDACT_TRACE_CONTENT', false);
+}
+function getSessionView(session) {
+    if (!shouldRedactTraceContent()) {
+        return session;
+    }
+    return {
+        ...session,
+        thoughts: session.thoughts.map((thought) => ({
+            index: thought.index,
+            content: REDACTED_THOUGHT_CONTENT,
+            revision: thought.revision,
+            ...(thought.stepSummary !== undefined
+                ? { stepSummary: REDACTED_THOUGHT_CONTENT }
+                : {}),
+        })),
+    };
+}
 function completeThoughtNames(value, sessionId) {
     const session = sessionStore.get(sessionId);
     if (!session) {
@@ -180,7 +200,7 @@ export function registerAllResources(server, iconMeta) {
         ...(withIconMeta(iconMeta) ?? {}),
     }, (uri, variables) => {
         const sessionId = extractStringVariable(variables, 'sessionId', uri);
-        const session = resolveSession(sessionId, uri);
+        const session = getSessionView(resolveSession(sessionId, uri));
         return {
             contents: [
                 {
@@ -214,7 +234,7 @@ export function registerAllResources(server, iconMeta) {
         ...(withIconMeta(iconMeta) ?? {}),
     }, (uri, variables) => {
         const sessionId = extractStringVariable(variables, 'sessionId', uri);
-        const session = resolveSession(sessionId, uri);
+        const session = getSessionView(resolveSession(sessionId, uri));
         const thoughtName = extractStringVariable(variables, 'thoughtName', uri);
         const { index, requestedRevised } = parseThoughtName(thoughtName, session);
         const thought = session.thoughts[index - 1];
@@ -264,7 +284,7 @@ export function registerAllResources(server, iconMeta) {
         ...(withIconMeta(iconMeta) ?? {}),
     }, (uri, variables) => {
         const sessionId = extractStringVariable(variables, 'sessionId', uri);
-        const session = resolveSession(sessionId, uri);
+        const session = getSessionView(resolveSession(sessionId, uri));
         const generatedThoughts = session.thoughts.length;
         const summary = buildSessionSummary({ ...session, generatedThoughts });
         return {

package/dist/resources/instructions.js

@@ -28,76 +28,59 @@ export function buildServerInstructions() {
     const sharedConstraints = getSharedConstraints()
         .map((c) => `- ${c}`)
         .join('\n');
-    return `# 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 LLM-authored thoughts).
-
----
-
-## PROMPTS
-
-- \`get-help\`: Returns these instructions for quick recall.
+    return `<role>
+You are an expert reasoning engine assistant. You decompose queries into structured thought chains at configurable depth levels (basic, normal, high).
+</role>
+
+<capabilities>
+- Domain: Multi-level reasoning engine.
+- Resources: Sessions (in-memory, 30m TTL), thought chains, progress notifications.
+- Tools: \`reasoning_think\` (WRITE: creates/extends sessions).
+</capabilities>
+
+<prompts>
+- \`get-help\`: Returns these instructions.
 ${promptList}
 
-> **Guided templates:** Each \`reasoning.<level>\` prompt embeds a level-specific few-shot example showing the expected \`thought\` depth and step count. Only the template for the requested level is injected — the other two are omitted to keep prompts lean.
-
----
-
-## RESOURCES & RESOURCE LINKS
+> **Guided templates:** Each \`reasoning.<level>\` prompt embeds a level-specific few-shot example showing expected \`thought\` depth and step count.
+</prompts>
 
+<resources>
 - \`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\`.
-- \`file:///cortex/sessions/{sessionId}/trace.md\`: Full Markdown trace of a session. Supports auto-completion on \`sessionId\`.
-- \`file:///cortex/sessions/{sessionId}/{thoughtName}.md\`: Markdown content of a single thought (e.g., \`Thought-1.md\`). Supports auto-completion on \`sessionId\` and \`thoughtName\`.
-- 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, revised, or status changes.
-- Subscribe to \`reasoning://sessions\` to receive aggregate updates as session content and statuses evolve.
-- 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.
-  - Use \`runMode: "run_to_completion"\` with \`thought\` + \`thoughts[]\` to execute multiple reasoning steps in one request.
-
----
-
-## TOOL CONTRACTS
-
+- \`reasoning://sessions\`: List active sessions (JSON).
+- \`reasoning://sessions/{sessionId}\`: Inspect session thoughts/metadata (JSON).
+- \`file:///cortex/sessions/{sessionId}/trace.md\`: Full Markdown trace.
+- \`file:///cortex/sessions/{sessionId}/{thoughtName}.md\`: Single thought Markdown.
+- Subscriptions (\`resources/subscribe\`):
+  - \`reasoning://sessions/{sessionId}\`: Updates on thought additions/revisions.
+  - \`reasoning://sessions\`: Aggregate session updates.
+</resources>
+
+<tasks_and_progress>
+- Pass \`_meta.progressToken\` for \`notifications/progress\`.
+- \`reasoning_think\` supports tasks (\`execution.taskSupport: "optional"\`):
+  - Send \`task\` in \`tools/call\` to get \`taskId\`.
+  - Poll \`tasks/get\`, fetch via \`tasks/result\`, abort via \`tasks/cancel\`.
+- Progress emission: \`high\` level every 2 steps; \`basic\`/\`normal\` every step.
+- \`runMode: "run_to_completion"\`: Pass \`thought\` as string array for batch execution.
+</tasks_and_progress>
+
+<tool_contracts>
 ${toolSections.join('\n\n')}
+</tool_contracts>
 
----
-
-## SHARED CONSTRAINTS
-
+<constraints>
 ${sharedConstraints}
-
----
-
-## 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_INVALID_THOUGHT_COUNT\`: \`targetThoughts\` is outside the level range. Check ranges: basic (3–5), normal (6–10), high (15–25).
-- \`E_INSUFFICIENT_THOUGHTS\`: In \`run_to_completion\`, the request did not provide enough thought inputs for planned remaining steps.
-- \`E_INVALID_RUN_MODE_ARGS\`: Invalid \`runMode\` argument combination (for example, missing \`targetThoughts\` when starting a new run-to-completion session).
-- \`E_ABORTED\`: Reasoning was cancelled via abort signal or task cancellation. Retry with a new request if needed.
-- \`E_SERVER_BUSY\`: Too many concurrent task-mode reasoning calls (default cap: 32). Retry after a short delay, or use normal (non-task) invocation.
-- \`E_REASONING\`: Unexpected engine error. Check the error \`message\` field for details and retry.
+</constraints>
+
+<error_handling>
+- \`E_SESSION_NOT_FOUND\`: Expired/missing. List sessions or start new.
+- \`E_INVALID_THOUGHT_COUNT\`: \`targetThoughts\` out of range (basic: 3-5, normal: 6-10, high: 15-25).
+- \`E_INSUFFICIENT_THOUGHTS\`: Not enough inputs for \`run_to_completion\`.
+- \`E_INVALID_RUN_MODE_ARGS\`: Invalid \`runMode\` args (e.g., missing \`targetThoughts\`).
+- \`E_ABORTED\`: Cancelled. Retry if needed.
+- \`E_SERVER_BUSY\`: Too many concurrent tasks. Retry later or use sync mode.
+- \`E_REASONING\`: Engine error. Check message and retry.
+</error_handling>
 `;
 }

package/dist/resources/tool-catalog.js

@@ -1,19 +1,20 @@
 import { buildCoreContextPack } from './tool-info.js';
-const CATALOG_GUIDE = `# Tool Catalog Details
-## Optional Parameters
-- \`observation\`: What facts are known at this step? Use with \`hypothesis\` and \`evaluation\` as an alternative to \`thought\`.
-- \`hypothesis\`: What is the proposed idea or next logical leap?
-- \`evaluation\`: Critique the hypothesis. Are there flaws?
-- \`step_summary\`: A 1-sentence summary of the conclusion reached in this step. Accumulates in the \`summary\` field for contextual guidance.
-- \`is_conclusion\`: Set to true to end the session early with a final answer.
-- \`rollback_to_step\`: Roll back to a thought index (0-based). All thoughts after this index are discarded.
+const CATALOG_GUIDE = `<optional_parameters>
+- \`observation\`: Facts known at this step. Use with \`hypothesis\` and \`evaluation\` instead of \`thought\`.
+- \`hypothesis\`: Proposed idea or next logical leap.
+- \`evaluation\`: Critique of the hypothesis.
+- \`step_summary\`: 1-sentence conclusion summary. Accumulates in \`summary\` field.
+- \`is_conclusion\`: Set true to end session early.
+- \`rollback_to_step\`: 0-based thought index to rollback to. Discards subsequent thoughts.
+</optional_parameters>
 
-## Cross-Tool Data Flow
+<cross_tool_data_flow>
 \`\`\`
 reasoning_think -> result.sessionId -> reasoning_think.sessionId
 reasoning_think -> result.sessionId -> reasoning://sessions/{sessionId}
 reasoning_think -> result.sessionId -> file:///cortex/sessions/{sessionId}/trace.md
 \`\`\`
+</cross_tool_data_flow>
 `;
 export function buildToolCatalog() {
     return `${buildCoreContextPack()}\n\n${CATALOG_GUIDE}`;

package/dist/resources/tool-info.js

@@ -19,7 +19,7 @@ export function buildCoreContextPack() {
             ? `| \`${e.name}\` | ${e.model} | ${e.timeout} | ${e.maxOutputTokens} | ${e.purpose} |`
             : '';
     });
-    return `# Core Context Pack\n\n| Tool | Model | Timeout | Max Output Tokens | Purpose |\n|------|-------|---------|-------------------|---------|\n${rows.join('\n')}`;
+    return `<core_context_pack>\n| Tool | Model | Timeout | Max Output Tokens | Purpose |\n|------|-------|---------|-------------------|---------|\n${rows.join('\n')}\n</core_context_pack>`;
 }
 export function getSharedConstraints() {
     return [