@j0hanz/thinkseq-mcp 1.2.2 → 1.2.4

package/README.md

@@ -268,7 +268,7 @@ Output:
 
 ## Behavior and validation
 
-- Inputs are validated with Zod and unknown keys are stripped (ignored).
+- Inputs are validated with Zod and unknown keys are rejected.
 - `thoughtNumber` is auto-incremented (1, 2, 3...).
 - `totalThoughts` defaults to 3, must be in 1-25, and is adjusted up to at least `thoughtNumber`.
 - The engine stores thoughts in memory and prunes when limits are exceeded:
@@ -282,7 +282,6 @@ This server publishes events via `node:diagnostics_channel`:
 
 - `thinkseq:tool` for `tool.start` and `tool.end` (includes duration, errors, and request context).
 - `thinkseq:lifecycle` for `lifecycle.started` and `lifecycle.shutdown`.
-- `thinkseq:engine` for internal engine events such as `engine.sequence_gap`.
 
 ## Configuration
 

package/dist/app.js

@@ -1,5 +1,5 @@
 import { buildShutdownDependencies, resolvePackageIdentity, resolveRunDependencies, } from './appConfig.js';
-import { installInitializationGuards } from './lib/protocolGuards.js';
+import { installMcpLogging } from './lib/mcpLogging.js';
 const toError = (value) => value instanceof Error ? value : new Error(String(value));
 const createExit = (proc, exit) => exit ?? ((code) => proc.exit(code));
 const createHandlerFor = (logError, exit) => (label) => (value) => {
@@ -19,14 +19,14 @@ export async function run(deps = {}) {
     const resolved = resolveRunDependencies(deps);
     const pkg = await resolved.readPackageJson(AbortSignal.timeout(resolved.packageReadTimeoutMs));
     const { name, version } = resolvePackageIdentity(pkg);
+    const server = resolved.createServer(name, version);
+    installMcpLogging(server);
     resolved.publishLifecycleEvent({
         type: 'lifecycle.started',
         ts: resolved.now(),
     });
-    const server = resolved.createServer(name, version);
     const engine = resolved.engineFactory();
     resolved.registerTool(server, engine);
-    installInitializationGuards(server);
     const transport = await resolved.connectServer(server);
     resolved.installShutdownHandlers(buildShutdownDependencies(resolved, { server, engine, transport }));
 }

package/dist/appConfig/runDependencies.js

@@ -1,73 +1,71 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { readFileSync } from 'node:fs';
+import { McpServer, ResourceTemplate, } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ThinkingEngine } from '../engine.js';
 import { publishLifecycleEvent } from '../lib/diagnostics.js';
 import { readSelfPackageJson } from '../lib/package.js';
-import { installStdioInvalidMessageGuards, installStdioParseErrorResponder, } from '../lib/stdioGuards.js';
+import { installStdioInitializationGuards, installStdioInvalidMessageGuards, installStdioParseErrorResponder, } from '../lib/stdioGuards.js';
 import { registerThinkSeq } from '../tools/thinkseq.js';
 import { installShutdownHandlers } from './shutdown.js';
-const DEFAULT_SERVER_INSTRUCTIONS = 'ThinkSeq is a tool for structured, sequential thinking with revision support.';
-function loadServerInstructions() {
+const INSTRUCTIONS_URL = new URL('../instructions.md', import.meta.url);
+const INSTRUCTIONS_FALLBACK = 'ThinkSeq is a tool for structured, sequential thinking with revision support.';
+function readInstructionsText() {
     try {
-        const raw = readFileSync(new URL('../instructions.md', import.meta.url), {
-            encoding: 'utf8',
-        });
-        const trimmed = raw.trim();
-        return trimmed.length > 0 ? trimmed : DEFAULT_SERVER_INSTRUCTIONS;
+        return readFileSync(INSTRUCTIONS_URL, { encoding: 'utf8' });
     }
     catch {
-        return DEFAULT_SERVER_INSTRUCTIONS;
+        return INSTRUCTIONS_FALLBACK;
     }
 }
+function loadServerInstructions() {
+    const raw = readInstructionsText();
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : INSTRUCTIONS_FALLBACK;
+}
+function registerInstructionsResource(server) {
+    server.registerResource('instructions', new ResourceTemplate('internal://instructions', { list: undefined }), { title: 'Instructions', mimeType: 'text/markdown' }, (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                text: readInstructionsText(),
+                mimeType: 'text/markdown',
+            },
+        ],
+    }));
+}
 const SERVER_INSTRUCTIONS = loadServerInstructions();
 const DEFAULT_PACKAGE_READ_TIMEOUT_MS = 2000;
 const defaultCreateServer = (name, version) => {
-    return new McpServer({ name, version }, {
+    const server = new McpServer({ name, version }, {
         instructions: SERVER_INSTRUCTIONS,
-        capabilities: { logging: {} },
+        capabilities: { logging: {}, tools: { listChanged: true } },
     });
+    registerInstructionsResource(server);
+    return server;
 };
 const defaultConnectServer = async (server, createTransport = () => new StdioServerTransport()) => {
     const transport = createTransport();
     await server.connect(transport);
+    installStdioInitializationGuards(transport);
     installStdioInvalidMessageGuards(transport);
     installStdioParseErrorResponder(transport);
     return transport;
 };
-function resolveCoreDependencies(deps) {
+export function resolveRunDependencies(deps) {
     return {
         processLike: deps.processLike ?? process,
         packageReadTimeoutMs: deps.packageReadTimeoutMs ?? DEFAULT_PACKAGE_READ_TIMEOUT_MS,
         readPackageJson: deps.readPackageJson ?? readSelfPackageJson,
         publishLifecycleEvent: deps.publishLifecycleEvent ?? publishLifecycleEvent,
-        now: deps.now ?? Date.now,
-    };
-}
-function resolveServerDependencies(deps) {
-    return {
         createServer: deps.createServer ?? defaultCreateServer,
         connectServer: deps.connectServer ?? defaultConnectServer,
-    };
-}
-function resolveEngineDependencies(deps) {
-    return {
         registerTool: deps.registerTool ?? registerThinkSeq,
         engineFactory: deps.engineFactory ?? (() => new ThinkingEngine()),
         installShutdownHandlers: deps.installShutdownHandlers ?? installShutdownHandlers,
-    };
-}
-function resolveShutdownTimeout(deps) {
-    if (deps.shutdownTimeoutMs === undefined)
-        return {};
-    return { shutdownTimeoutMs: deps.shutdownTimeoutMs };
-}
-export function resolveRunDependencies(deps) {
-    return {
-        ...resolveCoreDependencies(deps),
-        ...resolveServerDependencies(deps),
-        ...resolveEngineDependencies(deps),
-        ...resolveShutdownTimeout(deps),
+        now: deps.now ?? Date.now,
+        ...(deps.shutdownTimeoutMs !== undefined
+            ? { shutdownTimeoutMs: deps.shutdownTimeoutMs }
+            : {}),
     };
 }
 export function resolvePackageIdentity(pkg) {

package/dist/appConfig/shutdown.js

@@ -6,17 +6,24 @@ function isRecord(value) {
 function hasClose(value) {
     return isRecord(value) && typeof value.close === 'function';
 }
-async function closeWithTimeout(value, timeoutMs) {
+async function closeSafely(value) {
+    try {
+        if (hasClose(value))
+            await value.close();
+    }
+    catch {
+        return;
+    }
+}
+async function closeAllWithinTimeout(values, timeoutMs) {
     const timeout = new Promise((resolve) => setTimeout(resolve, timeoutMs));
-    const attempt = (async () => {
-        try {
-            if (hasClose(value))
-                await value.close();
-        }
-        catch {
-            return;
-        }
-    })();
+    const attempt = Promise.allSettled(values.map((value) => closeSafely(value)))
+        .then(() => {
+        return;
+    })
+        .catch(() => {
+        return;
+    });
     await Promise.race([attempt, timeout]);
 }
 function buildShutdownRunner(deps, proc) {
@@ -33,9 +40,7 @@ function buildShutdownRunner(deps, proc) {
             ts: timestamp(),
             signal,
         });
-        await closeWithTimeout(deps.server, timeoutMs);
-        await closeWithTimeout(deps.engine, timeoutMs);
-        await closeWithTimeout(deps.transport, timeoutMs);
+        await closeAllWithinTimeout([deps.server, deps.engine, deps.transport], timeoutMs);
         proc.exit(0);
     };
 }

package/dist/appConfig/types.d.ts

@@ -1,9 +1,5 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { ThinkingEngine } from '../engine.js';
-export type CloseFn = () => Promise<void> | void;
+export type { CloseFn, EngineLike } from '../lib/types.js';
 export type ProcessLike = Pick<typeof process, 'on' | 'exit'>;
 export type TransportLike = Parameters<McpServer['connect']>[0];
-export type ServerLike = Pick<McpServer, 'connect' | 'registerTool'>;
-export type EngineLike = Pick<ThinkingEngine, 'processThought'> & {
-    close?: CloseFn;
-};
+export type ServerLike = Pick<McpServer, 'connect' | 'registerTool' | 'registerResource' | 'sendLoggingMessage'>;

package/dist/engine/revision.js

@@ -1,23 +1,16 @@
 export function resolveRevisionTarget(input, getThoughtByNumber) {
-    const targetNumberResult = getRevisionTargetNumber(input);
-    if (!targetNumberResult.ok) {
-        return targetNumberResult;
+    const targetNumber = input.revisesThought;
+    if (targetNumber === undefined) {
+        return {
+            ok: false,
+            error: buildRevisionError('E_REVISION_MISSING', 'revisesThought is required for revision'),
+        };
     }
-    const validationError = validateRevisionTarget(getThoughtByNumber, targetNumberResult.targetNumber);
+    const validationError = validateRevisionTarget(getThoughtByNumber, targetNumber);
     if (validationError) {
         return { ok: false, error: validationError };
     }
-    return { ok: true, targetNumber: targetNumberResult.targetNumber };
-}
-function getRevisionTargetNumber(input) {
-    const targetNumber = input.revisesThought;
-    if (targetNumber !== undefined) {
-        return { ok: true, targetNumber };
-    }
-    return {
-        ok: false,
-        error: buildRevisionError('E_REVISION_MISSING', 'revisesThought is required for revision'),
-    };
+    return { ok: true, targetNumber };
 }
 function validateRevisionTarget(getThoughtByNumber, targetNumber) {
     const target = getThoughtByNumber(targetNumber);

package/dist/engine/thoughtQueries.js

@@ -1,10 +1,5 @@
-function getRecentActiveThoughts(activeThoughts, limit) {
-    if (limit <= 0)
-        return [];
-    return activeThoughts.slice(-limit);
-}
 export function buildContextSummary(activeThoughts, revisionInfo) {
-    const recent = getRecentActiveThoughts(activeThoughts, 5);
+    const recent = activeThoughts.slice(-5);
     const startIndex = activeThoughts.length - recent.length;
     const recentThoughts = recent.map((thought, index) => ({
         stepIndex: startIndex + index + 1,

package/dist/engine/thoughtStore.js

@@ -4,6 +4,7 @@ export class ThoughtStore {
     #thoughtIndex = new Map();
     #activeThoughts = [];
     #activeThoughtNumbers = [];
+    #activeMaxTotalThoughts = 0;
     #headIndex = 0;
     #nextThoughtNumber = 1;
     #estimatedBytes = 0;
@@ -18,9 +19,10 @@ export class ThoughtStore {
     nextThoughtNumbers(totalThoughts) {
         const thoughtNumber = this.#nextThoughtNumber;
         this.#nextThoughtNumber += 1;
+        const effectiveTotalThoughts = Math.max(totalThoughts, thoughtNumber, this.#activeMaxTotalThoughts);
         return {
             thoughtNumber,
-            totalThoughts: Math.max(totalThoughts, thoughtNumber),
+            totalThoughts: effectiveTotalThoughts,
         };
     }
     storeThought(stored) {
@@ -29,9 +31,17 @@ export class ThoughtStore {
         if (stored.isActive) {
             this.#activeThoughts.push(stored);
             this.#activeThoughtNumbers.push(stored.thoughtNumber);
+            this.#activeMaxTotalThoughts = Math.max(this.#activeMaxTotalThoughts, stored.totalThoughts);
         }
         this.#estimatedBytes += this.#estimateThoughtBytes(stored);
     }
+    #recomputeActiveMaxTotalThoughts() {
+        let maxTotal = 0;
+        for (const thought of this.#activeThoughts) {
+            maxTotal = Math.max(maxTotal, thought.totalThoughts);
+        }
+        this.#activeMaxTotalThoughts = maxTotal;
+    }
     #findActiveThoughtIndex(thoughtNumber) {
         const activeThoughtNumbers = this.#activeThoughtNumbers;
         let low = 0;
@@ -71,6 +81,7 @@ export class ThoughtStore {
         }
         this.#activeThoughts.length = startIndex;
         this.#activeThoughtNumbers.length = startIndex;
+        this.#recomputeActiveMaxTotalThoughts();
         return supersedes;
     }
     getActiveThoughts() {
@@ -114,6 +125,7 @@ export class ThoughtStore {
             return;
         this.#activeThoughts = this.#activeThoughts.slice(startIndex);
         this.#activeThoughtNumbers = this.#activeThoughtNumbers.slice(startIndex);
+        this.#recomputeActiveMaxTotalThoughts();
     }
     #removeOldest(count, options = {}) {
         const totalLength = this.getTotalLength();
@@ -147,27 +159,24 @@ export class ThoughtStore {
     #compactIfNeeded(force = false) {
         if (this.#headIndex === 0)
             return;
-        const totalLength = this.getTotalLength();
-        if (totalLength === 0) {
+        if (this.getTotalLength() === 0) {
             this.#resetThoughts();
             return;
         }
-        if (!this.#shouldCompact(force))
+        if (!force &&
+            this.#headIndex < COMPACT_THRESHOLD &&
+            this.#headIndex < this.#thoughts.length * COMPACT_RATIO) {
             return;
+        }
         this.#thoughts = this.#thoughts.slice(this.#headIndex);
         this.#headIndex = 0;
     }
-    #shouldCompact(force) {
-        if (force)
-            return true;
-        return (this.#headIndex >= COMPACT_THRESHOLD ||
-            this.#headIndex >= this.#thoughts.length * COMPACT_RATIO);
-    }
     #resetThoughts() {
         this.#thoughts = [];
         this.#thoughtIndex.clear();
         this.#activeThoughts = [];
         this.#activeThoughtNumbers = [];
+        this.#activeMaxTotalThoughts = 0;
         this.#headIndex = 0;
         this.#nextThoughtNumber = 1;
         this.#estimatedBytes = 0;

package/dist/engine.js

@@ -24,11 +24,8 @@ export class ThinkingEngine {
         return this.#processNewThought(input);
     }
     #processNewThought(input) {
-        const effectiveTotalThoughts = this.#resolveEffectiveTotalThoughts(input);
-        const numbers = this.#store.nextThoughtNumbers(effectiveTotalThoughts);
-        const stored = this.#buildStoredThought(input, numbers);
-        this.#store.storeThought(stored);
-        this.#store.pruneHistoryIfNeeded();
+        const { stored } = this.#createStoredThought(input);
+        this.#commitThought(stored);
         return this.#buildProcessResult(stored);
     }
     #processRevision(input) {
@@ -36,18 +33,14 @@ export class ThinkingEngine {
         if (!resolved.ok)
             return resolved.error;
         const { targetNumber } = resolved;
-        const effectiveTotalThoughts = this.#resolveEffectiveTotalThoughts(input);
-        const numbers = this.#store.nextThoughtNumbers(effectiveTotalThoughts);
+        const { numbers, stored } = this.#createStoredThought(input, {
+            revisionOf: targetNumber,
+        });
         const supersedesAll = this.#store.supersedeFrom(targetNumber, numbers.thoughtNumber);
         const supersedesTotal = supersedesAll.length;
         const supersedes = capArrayStart(supersedesAll, MAX_SUPERSEDES);
-        const stored = this.#buildStoredThought(input, {
-            ...numbers,
-            revisionOf: targetNumber,
-        });
-        this.#store.storeThought(stored);
         this.#hasRevisions = true;
-        this.#store.pruneHistoryIfNeeded();
+        this.#commitThought(stored);
         return this.#buildProcessResult(stored, {
             revises: targetNumber,
             supersedes,
@@ -69,14 +62,26 @@ export class ThinkingEngine {
             }),
         };
     }
+    #createStoredThought(input, extras = {}) {
+        const effectiveTotalThoughts = this.#resolveEffectiveTotalThoughts(input);
+        const numbers = this.#store.nextThoughtNumbers(effectiveTotalThoughts);
+        const stored = this.#buildStoredThought(input, {
+            ...numbers,
+            ...extras,
+        });
+        return { stored, numbers };
+    }
+    #commitThought(stored) {
+        this.#store.storeThought(stored);
+        this.#store.pruneHistoryIfNeeded();
+    }
     #resolveEffectiveTotalThoughts(input) {
         if (input.totalThoughts !== undefined) {
             return input.totalThoughts;
         }
         const activeThoughts = this.#store.getActiveThoughts();
         const lastActive = activeThoughts[activeThoughts.length - 1];
-        if (lastActive !== undefined &&
-            lastActive.totalThoughts > _a.DEFAULT_TOTAL_THOUGHTS) {
+        if (lastActive !== undefined) {
             return lastActive.totalThoughts;
         }
         return _a.DEFAULT_TOTAL_THOUGHTS;

package/dist/instructions.md

@@ -1,63 +1,40 @@
-# ThinkSeq MCP Server — AI Usage Instructions
+# ThinkSeq MCP Server Instructions
 
-Use this server to record sequential thinking steps to plan, reason, and debug. Prefer these tools over "remembering" state in chat.
+> **Guidance for the Agent:** These instructions are available as a resource (`internal://instructions`). Load them when you are confused about tool usage.
 
-## Operating Rules
+## 1. Core Capability
 
-- Keep thoughts atomic: one decision, calculation, or action per step.
-- Use revisions to fix mistakes in the active chain instead of apologizing in chat.
-- If request is vague, ask clarifying questions.
+- **Domain:** In-memory, sequential thinking with revision (destructive rewind).
+- **Primary Resources:** `Thoughts`, `RevisionChain`, `ProgressContext`.
 
-### Strategies
+## 2. The "Golden Path" Workflows (Critical)
 
-- **Discovery:** Read the tool output's `context` to see recent thoughts and available revision targets.
-- **Action:** Use `thinkseq` to advance the reasoning chain or `revisesThought` to rewind and correct.
+_Follow this order; do not guess indices._
 
-## Data Model
+### Workflow A: Capture a reasoning chain
 
-- **Thinking Step:** `thought` (text), `thoughtNumber` (int), `progress` (0-1), `isComplete` (bool)
+1. Call `thinkseq` with `thought` (and optionally `totalThoughts`).
+2. Continue calling `thinkseq` for each step.
+3. Read `progress` and `isComplete` from the response to know when to stop.
+   > **Constraint:** Keep each step atomic; one decision per call.
 
-## Workflows
+### Workflow B: Revise a prior step
 
-### 1) Structured Reasoning
+1. Call `thinkseq` to get the latest `revisableThoughts` list.
+2. Call `thinkseq` again with `revisesThought` set to a valid entry.
+3. Continue from the revised step.
+   > **Constraint:** Never guess `revisesThought`; always pick from `revisableThoughts`.
 
-```text
-thinkseq(thought="Plan: 1. check, 2. fix", totalThoughts=5) → Start chain
-thinkseq(thought="Check passed, starting fix") → Progress chain
-thinkseq(thought="Revised plan: use new API", revisesThought=1) → Correction
-```
+## 3. Tool Nuances & "Gotchas"
 
-## Tools
+- **`thinkseq`**:
+  - **Side Effects:** Mutates in-memory thought history (write operation).
+  - **Limits:** `thought` max 5000 chars; `totalThoughts` max 25.
+  - **Revisions:** Revising a thought supersedes that step and all later active steps.
+  - **Compatibility:** Set `THINKSEQ_INCLUDE_TEXT_CONTENT=0|false|no|off` to omit the JSON string in `content`.
 
-### thinkseq
+## 4. Error Handling Strategy
 
-Record a concise thinking step (max 5000 chars). Be brief: capture only the essential insight, calculation, or decision.
-
-- **Use when:** You need to structured reasoning, planning, or a decision log.
-- **Args:**
-  - `thought` (string, required): Your current thinking step.
-  - `totalThoughts` (number, optional): Estimated total thoughts (1-25, default: 3).
-  - `revisesThought` (number, optional): Revise a previous thought by number.
-- **Returns:** `thoughtNumber`, `progress`, `isComplete`, `revisableThoughts`, `context` (history previews).
-
-## Response Shape
-
-Success: `{ "ok": true, "result": { ... } }`
-Error: `{ "ok": false, "error": { "code": "...", "message": "..." } }`
-
-### Common Errors
-
-| Code                           | Meaning                                | Resolution                                |
-| ------------------------------ | -------------------------------------- | ----------------------------------------- |
-| `E_REVISION_TARGET_NOT_FOUND`  | Revision target ID does not exist      | Check `revisableThoughts` for valid IDs   |
-| `E_REVISION_TARGET_SUPERSEDED` | Target thought was already overwritten | Revise the current active thought instead |
-| `E_THINK`                      | Generic engine error                   | Check arguments and retry                 |
-
-## Limits
-
-- **Max Thoughts:** 25 (default estimate)
-- **Max Length:** 5000 chars per thought
-
-## Security
-
-- Do not store credentials, secrets, or PII in thoughts. State is in-memory only but may be logged.
+- If `E_REVISION_TARGET_NOT_FOUND`, fetch a fresh `revisableThoughts` list and retry.
+- If `E_REVISION_TARGET_SUPERSEDED`, revise the latest active thought instead.
+- If `E_THINK`, verify inputs and retry once.

package/dist/lib/cli.js

@@ -20,11 +20,24 @@ Options:
   --package-read-timeout-ms <number>  Package.json read timeout
   -h, --help                       Show this help`;
 const BYTES_PER_MB = 1024 * 1024;
+const CLI_OPTION_SPECS = [
+    { key: 'max-thoughts', configKey: 'maxThoughts' },
+    {
+        key: 'max-memory-mb',
+        configKey: 'maxMemoryBytes',
+        map: (value) => value * BYTES_PER_MB,
+    },
+    { key: 'shutdown-timeout-ms', configKey: 'shutdownTimeoutMs' },
+    { key: 'package-read-timeout-ms', configKey: 'packageReadTimeoutMs' },
+];
 function parsePositiveInt(value, label) {
     if (value === undefined)
         return undefined;
-    const parsed = Number.parseInt(value, 10);
-    if (!Number.isFinite(parsed) || parsed <= 0) {
+    if (!/^\d+$/.test(value)) {
+        throw new Error(`Invalid ${label}: ${value}`);
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed <= 0) {
         throw new Error(`Invalid ${label}: ${value}`);
     }
     return parsed;
@@ -40,21 +53,14 @@ function getStringOption(values, key) {
     return typeof value === 'string' ? value : undefined;
 }
 function buildCliConfig(values) {
-    const maxThoughts = parsePositiveInt(getStringOption(values, 'max-thoughts'), 'max-thoughts');
-    const maxMemoryMb = parsePositiveInt(getStringOption(values, 'max-memory-mb'), 'max-memory-mb');
-    const shutdownTimeoutMs = parsePositiveInt(getStringOption(values, 'shutdown-timeout-ms'), 'shutdown-timeout-ms');
-    const packageReadTimeoutMs = parsePositiveInt(getStringOption(values, 'package-read-timeout-ms'), 'package-read-timeout-ms');
     const config = {};
-    if (maxThoughts !== undefined)
-        config.maxThoughts = maxThoughts;
-    if (maxMemoryMb !== undefined) {
-        config.maxMemoryBytes = maxMemoryMb * BYTES_PER_MB;
-    }
-    if (shutdownTimeoutMs !== undefined) {
-        config.shutdownTimeoutMs = shutdownTimeoutMs;
-    }
-    if (packageReadTimeoutMs !== undefined) {
-        config.packageReadTimeoutMs = packageReadTimeoutMs;
+    for (const spec of CLI_OPTION_SPECS) {
+        const raw = getStringOption(values, spec.key);
+        const parsed = parsePositiveInt(raw, spec.key);
+        if (parsed === undefined)
+            continue;
+        const mapped = spec.map ? spec.map(parsed) : parsed;
+        config[spec.configKey] = mapped;
     }
     return config;
 }

package/dist/lib/mcpLogging.d.ts

@@ -0,0 +1,5 @@
+import type { LoggingMessageNotificationParams } from '@modelcontextprotocol/sdk/types.js';
+export interface LoggingTarget {
+    sendLoggingMessage: (params: LoggingMessageNotificationParams, sessionId?: string) => Promise<void>;
+}
+export declare function installMcpLogging(target: LoggingTarget): () => void;

package/dist/lib/mcpLogging.js

@@ -0,0 +1,60 @@
+import diagnosticsChannel from 'node:diagnostics_channel';
+const TOOL_LOGGER = 'thinkseq.tool';
+const LIFECYCLE_LOGGER = 'thinkseq.lifecycle';
+const toolChannel = diagnosticsChannel.channel('thinkseq:tool');
+const lifecycleChannel = diagnosticsChannel.channel('thinkseq:lifecycle');
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isToolEvent(value) {
+    if (!isRecord(value))
+        return false;
+    const { type } = value;
+    if (type !== 'tool.start' && type !== 'tool.end')
+        return false;
+    return value.tool === 'thinkseq';
+}
+function isLifecycleEvent(value) {
+    if (!isRecord(value))
+        return false;
+    return (value.type === 'lifecycle.started' || value.type === 'lifecycle.shutdown');
+}
+function sendLog(target, params) {
+    void target.sendLoggingMessage(params).catch(() => {
+        return;
+    });
+}
+function toolEventToLog(event) {
+    const level = event.type === 'tool.end' && !event.ok ? 'error' : 'info';
+    return {
+        level,
+        logger: TOOL_LOGGER,
+        data: event,
+    };
+}
+function lifecycleEventToLog(event) {
+    const level = event.type === 'lifecycle.shutdown' ? 'notice' : 'info';
+    return {
+        level,
+        logger: LIFECYCLE_LOGGER,
+        data: event,
+    };
+}
+export function installMcpLogging(target) {
+    const onTool = (event) => {
+        if (!isToolEvent(event))
+            return;
+        sendLog(target, toolEventToLog(event));
+    };
+    const onLifecycle = (event) => {
+        if (!isLifecycleEvent(event))
+            return;
+        sendLog(target, lifecycleEventToLog(event));
+    };
+    toolChannel.subscribe(onTool);
+    lifecycleChannel.subscribe(onLifecycle);
+    return () => {
+        toolChannel.unsubscribe(onTool);
+        lifecycleChannel.unsubscribe(onLifecycle);
+    };
+}

package/dist/lib/package.js

@@ -2,7 +2,6 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 const defaultReadFile = (path, options) => readFile(path, options);
-const defaultCwd = () => process.cwd();
 const defaultPackageJsonPath = fileURLToPath(new URL('../../package.json', import.meta.url));
 function isRecord(value) {
     return typeof value === 'object' && value !== null;
@@ -30,25 +29,16 @@ function parsePackageJson(raw) {
         return {};
     }
 }
-function resolveReadFile(deps) {
-    return deps?.readFile ?? defaultReadFile;
-}
-function resolveCwd(deps) {
-    return deps?.cwd ?? defaultCwd;
-}
 function resolvePackageJsonPath(deps) {
     // Only honor cwd injection when readFile is also injected (test seam).
     if (deps?.readFile && deps.cwd)
-        return join(resolveCwd(deps)(), 'package.json');
+        return join(deps.cwd(), 'package.json');
     return defaultPackageJsonPath;
 }
-function buildReadOptions(signal) {
-    return signal ? { encoding: 'utf8', signal } : { encoding: 'utf8' };
-}
 export async function readSelfPackageJson(signal, deps) {
     try {
-        const readFileImpl = resolveReadFile(deps);
-        const raw = await readFileImpl(resolvePackageJsonPath(deps), buildReadOptions(signal));
+        const readFileImpl = deps?.readFile ?? defaultReadFile;
+        const raw = await readFileImpl(resolvePackageJsonPath(deps), signal ? { encoding: 'utf8', signal } : { encoding: 'utf8' });
         return parsePackageJson(raw);
     }
     catch {