tracelattice 1.2.5

package/dist/types/tool.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Tool types for MCP tool recommendations and definitions.
+ *
+ * @module types/tool
+ */
+/**
+ * Represents a recommended MCP tool with associated metadata.
+ *
+ * Tool recommendations are generated by the sequential thinking process to suggest
+ * appropriate tools for completing specific tasks. Each recommendation includes
+ * a confidence score and rationale to help the LLM make informed decisions.
+ *
+ * @example
+ * ```typescript
+ * const recommendation: ToolRecommendation = {
+ *   tool_name: 'mcp__tavily-mcp__tavily-search',
+ *   confidence: 0.9,
+ *   rationale: 'Best for searching current web content',
+ *   priority: 1,
+ *   suggested_inputs: { query: 'TypeScript documentation' },
+ *   alternatives: ['mcp__web_reader__webReader']
+ * };
+ * ```
+ */
+export interface ToolRecommendation {
+    /** The unique name/identifier of the recommended tool. */
+    tool_name: string;
+    /** Confidence score from 0-1 indicating how appropriate this tool is for the current task. */
+    confidence: number;
+    /** Explanation of why this tool is recommended and how it addresses the current need. */
+    rationale: string;
+    /** Order in the recommendation sequence (lower numbers = higher priority). */
+    priority: number;
+    /** Optional suggested parameter values for the tool based on the current context. */
+    suggested_inputs?: Record<string, unknown>;
+    /** Alternative tools that could be used if the primary recommendation is not available. */
+    alternatives?: string[];
+}
+/**
+ * Defines an MCP tool that can be recommended and invoked.
+ *
+ * Tools are the basic building blocks for performing operations
+ * such as reading files, running commands, or making API calls.
+ *
+ * @example
+ * ```typescript
+ * const tool: Tool = {
+ *   name: 'Read',
+ *   description: 'Read a file from the filesystem',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: {
+ *       file_path: { type: 'string' }
+ *     },
+ *     required: ['file_path']
+ *   }
+ * };
+ * ```
+ */
+export interface Tool {
+    /** Unique identifier for the tool. */
+    name: string;
+    /** Human-readable description of what the tool does. */
+    description: string;
+    /** JSON Schema defining the parameters the tool accepts. */
+    inputSchema: Record<string, unknown>;
+}
+//# sourceMappingURL=tool.d.ts.map

package/dist/types/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/types/tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,kBAAkB;IAClC,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAElB,8FAA8F;IAC9F,UAAU,EAAE,MAAM,CAAC;IAEnB,yFAAyF;IACzF,SAAS,EAAE,MAAM,CAAC;IAElB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IAEjB,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE3C,2FAA2F;IAC3F,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,IAAI;IACpB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IAEb,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IAEpB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC"}

package/dist/types/tool.js

@@ -0,0 +1 @@
+export { };

package/dist/watchers/SkillWatcher.d.ts

@@ -0,0 +1,132 @@
+/**
+ * File system watcher for skill directory changes with registry integration.
+ *
+ * This module provides the `SkillWatcher` class which monitors configured
+ * skill directories for file changes using chokidar. When changes are detected,
+ * it automatically triggers skill re-discovery to keep the registry in sync.
+ *
+ * @module watcher
+ */
+import type { Logger } from '../logger/StructuredLogger.js';
+import type { SkillRegistry } from '../registry/SkillRegistry.js';
+/**
+ * File system watcher for skill directories with registry integration.
+ *
+ * This class monitors configured skill directories for file system changes
+ * and automatically triggers skill re-discovery when changes are detected.
+ * It integrates with a `SkillRegistry` to keep the registered skills in sync
+ * with the filesystem.
+ *
+ * @remarks
+ * **Watched Events:**
+ * - `add` - A new skill file was added (triggers re-discovery)
+ * - `change` - A skill file was modified (triggers re-discovery)
+ * - `unlink` - A skill file was removed (attempts to remove from registry)
+ *
+ * **Watched Directories:**
+ * - `.claude/skills` (project-local)
+ * - `~/.claude/skills` (user-global)
+ *
+ * **Ignored Paths:**
+ * - `node_modules` directories are ignored
+ *
+ * **Watcher Behavior:**
+ * - Uses persistent mode to continue watching even if files are temporarily deleted
+ * - Automatically starts watching when instantiated
+ * - File additions/modifications trigger full skill re-discovery
+ * - File removals attempt to remove the specific skill from the registry
+ *
+ * @example
+ * ```typescript
+ * import { SkillWatcher } from './SkillWatcher.js';
+ * import { SkillRegistry } from './registry/SkillRegistry.js';
+ *
+ * const registry = new SkillRegistry();
+ * const watcher = new SkillWatcher(registry);
+ * // Watcher automatically starts monitoring skill directories
+ *
+ * // When a skill file is added/modified, re-discovery is triggered
+ * // When a skill file is deleted, it's removed from the registry
+ *
+ * // When done, stop the watcher
+ * watcher.stop();
+ * ```
+ */
+export declare class SkillWatcher {
+    private skillRegistry;
+    /** The underlying chokidar file system watcher. */
+    private _watcher;
+    private _logger;
+    constructor(skillRegistry: SkillRegistry, logger?: Logger);
+    /**
+     * Create a no-op logger when none is provided.
+     */
+    private _createNoopLogger;
+    /**
+     * Sets up the file system watcher for skill directories.
+     *
+     * Configures chokidar to watch the skill directories and sets up
+     * event handlers for file additions, modifications, and removals.
+     *
+     * @private
+     */
+    private setupWatcher;
+    /**
+     * Handles the event when a skill file is removed.
+     *
+     * This method extracts the skill name from the file path and attempts
+     * to remove it from the skill registry. If the skill name cannot be
+     * extracted, or the skill is not found in the registry, the error is logged
+     * but does not throw.
+     *
+     * @param skillPath - The file path of the removed skill file
+     * @returns A Promise that resolves when handling is complete
+     *
+     * @example
+     * ```typescript
+     * // When 'commit.md' is removed, this will attempt to remove
+     * // the skill named 'commit' from the registry
+     * ```
+     */
+    private handleSkillRemoval;
+    /**
+     * Internal logging method.
+     * @param message - The message to log
+     * @private
+     */
+    private log;
+    /**
+     * Extracts the skill name from a file path.
+     *
+     * This method takes a file path and extracts the filename without
+     * extension, which is used as the skill name. For example:
+     * - `.claude/skills/commit.md` -> `commit.md`
+     * - `.claude/skills/review-pr.yml` -> `review-pr.yml`
+     *
+     * @param skillPath - The file path to extract from
+     * @returns The extracted filename (with extension), or null if extraction fails
+     *
+     * @example
+     * ```typescript
+     * extractSkillNameFromPath('/path/to/skills/commit.md')
+     * // Returns: 'commit.md'
+     * ```
+     */
+    private extractSkillNameFromPath;
+    /**
+     * Stops watching skill directories and cleans up resources.
+     *
+     * This method closes the underlying chokidar watcher and releases
+     * file system resources. After calling this method, the watcher
+     * cannot be restarted.
+     *
+     * @example
+     * ```typescript
+     * const watcher = new SkillWatcher(registry);
+     * // ... use watcher ...
+     * watcher.stop();
+     * ```
+     */
+    stop(): void;
+}
+//# sourceMappingURL=SkillWatcher.d.ts.map

package/dist/watchers/SkillWatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SkillWatcher.d.ts","sourceRoot":"","sources":["../../src/watchers/SkillWatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,YAAY;IAMvB,OAAO,CAAC,aAAa;IALtB,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,OAAO,CAAS;gBAGf,aAAa,EAAE,aAAa,EACpC,MAAM,CAAC,EAAE,MAAM;IAMhB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAiCpB;;;;;;;;;;;;;;;;OAgBG;YACW,kBAAkB;IAchC;;;;OAIG;IACH,OAAO,CAAC,GAAG;IAQX;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,wBAAwB;IAKhC;;;;;;;;;;;;;OAaG;IACI,IAAI,IAAI,IAAI;CAMnB"}

package/dist/watchers/SkillWatcher.js

@@ -0,0 +1,73 @@
+import { watch } from "chokidar";
+import { homedir } from "node:os";
+import { join } from "node:path";
+class SkillWatcher {
+    skillRegistry;
+    _watcher = null;
+    _logger;
+    constructor(skillRegistry, logger){
+        this.skillRegistry = skillRegistry;
+        this._logger = logger ?? this._createNoopLogger();
+        this.setupWatcher();
+    }
+    _createNoopLogger() {
+        return {
+            info: ()=>{},
+            warn: ()=>{},
+            error: ()=>{},
+            debug: ()=>{},
+            setLevel: ()=>{},
+            getLevel: ()=>'info'
+        };
+    }
+    setupWatcher() {
+        const skillDirs = [
+            '.claude/skills',
+            join(homedir(), '.claude/skills')
+        ];
+        this._watcher = watch(skillDirs, {
+            ignored: [
+                /node_modules/,
+                /\.DS_Store$/
+            ],
+            persistent: true
+        });
+        this._watcher.on('add', async (path)=>{
+            if (!path.includes('.DS_Store')) this.log(`Skill added: ${path.split('/').pop()}`);
+            await this.skillRegistry.discoverAsync();
+        });
+        this._watcher.on('change', async (path)=>{
+            if (!path.includes('.DS_Store')) this.log(`Skill modified: ${path.split('/').pop()}`);
+            await this.skillRegistry.discoverAsync();
+        });
+        this._watcher.on('unlink', async (path)=>{
+            if (!path.includes('.DS_Store')) this.log(`Skill removed: ${path.split('/').pop()}`);
+            this.handleSkillRemoval(path);
+        });
+    }
+    async handleSkillRemoval(skillPath) {
+        const skillName = this.extractSkillNameFromPath(skillPath);
+        if (skillName) try {
+            this.skillRegistry.removeSkillByName(skillName);
+        } catch (error) {
+            console.error(`Failed to remove skill ${skillName}:`, error instanceof Error ? error.message : String(error));
+        }
+    }
+    log(message) {
+        if ('true' !== process.env.WATCHER_VERBOSE) return;
+        this._logger.error(`[Watcher] ${message}`);
+    }
+    extractSkillNameFromPath(skillPath) {
+        const parts = skillPath.split(/[/\\]/);
+        return parts[parts.length - 1] || null;
+    }
+    stop() {
+        if (this._watcher) {
+            this._watcher.close();
+            this._watcher = null;
+        }
+    }
+}
+export { SkillWatcher };
+
+//# sourceMappingURL=SkillWatcher.js.map

package/dist/watchers/SkillWatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchers/SkillWatcher.js","sources":["../../src/watchers/SkillWatcher.ts"],"sourcesContent":["/**\n * File system watcher for skill directory changes with registry integration.\n *\n * This module provides the `SkillWatcher` class which monitors configured\n * skill directories for file changes using chokidar. When changes are detected,\n * it automatically triggers skill re-discovery to keep the registry in sync.\n *\n * @module watcher\n */\n\nimport { watch, type FSWatcher } from 'chokidar';\nimport { homedir } from 'node:os';\nimport { join } from 'node:path';\nimport type { Logger } from '../logger/StructuredLogger.js';\nimport type { SkillRegistry } from '../registry/SkillRegistry.js';\n\n/**\n * File system watcher for skill directories with registry integration.\n *\n * This class monitors configured skill directories for file system changes\n * and automatically triggers skill re-discovery when changes are detected.\n * It integrates with a `SkillRegistry` to keep the registered skills in sync\n * with the filesystem.\n *\n * @remarks\n * **Watched Events:**\n * - `add` - A new skill file was added (triggers re-discovery)\n * - `change` - A skill file was modified (triggers re-discovery)\n * - `unlink` - A skill file was removed (attempts to remove from registry)\n *\n * **Watched Directories:**\n * - `.claude/skills` (project-local)\n * - `~/.claude/skills` (user-global)\n *\n * **Ignored Paths:**\n * - `node_modules` directories are ignored\n *\n * **Watcher Behavior:**\n * - Uses persistent mode to continue watching even if files are temporarily deleted\n * - Automatically starts watching when instantiated\n * - File additions/modifications trigger full skill re-discovery\n * - File removals attempt to remove the specific skill from the registry\n *\n * @example\n * ```typescript\n * import { SkillWatcher } from './SkillWatcher.js';\n * import { SkillRegistry } from './registry/SkillRegistry.js';\n *\n * const registry = new SkillRegistry();\n * const watcher = new SkillWatcher(registry);\n * // Watcher automatically starts monitoring skill directories\n *\n * // When a skill file is added/modified, re-discovery is triggered\n * // When a skill file is deleted, it's removed from the registry\n *\n * // When done, stop the watcher\n * watcher.stop();\n * ```\n */\nexport class SkillWatcher {\n\t/** The underlying chokidar file system watcher. */\n\tprivate _watcher: FSWatcher | null = null;\n\tprivate _logger: Logger;\n\n\tconstructor(\n\t\tprivate skillRegistry: SkillRegistry,\n\t\tlogger?: Logger\n\t) {\n\t\tthis._logger = logger ?? this._createNoopLogger();\n\t\tthis.setupWatcher();\n\t}\n\n\t/**\n\t * Create a no-op logger when none is provided.\n\t */\n\tprivate _createNoopLogger(): Logger {\n\t\treturn {\n\t\t\tinfo: () => {},\n\t\t\twarn: () => {},\n\t\t\terror: () => {},\n\t\t\tdebug: () => {},\n\t\t\tsetLevel: () => {},\n\t\t\tgetLevel: () => 'info',\n\t\t};\n\t}\n\n\t/**\n\t * Sets up the file system watcher for skill directories.\n\t *\n\t * Configures chokidar to watch the skill directories and sets up\n\t * event handlers for file additions, modifications, and removals.\n\t *\n\t * @private\n\t */\n\tprivate setupWatcher(): void {\n\t\tconst skillDirs = ['.claude/skills', join(homedir(), '.claude/skills')];\n\n\t\tthis._watcher = watch(skillDirs, {\n\t\t\tignored: [/node_modules/, /\\.DS_Store$/],\n\t\t\tpersistent: true,\n\t\t});\n\n\t\tthis._watcher.on('add', async (path) => {\n\t\t\t// Only log if not .DS_Store\n\t\t\tif (!path.includes('.DS_Store')) {\n\t\t\t\tthis.log(`Skill added: ${path.split('/').pop()}`);\n\t\t\t}\n\t\t\tawait this.skillRegistry.discoverAsync();\n\t\t});\n\n\t\tthis._watcher.on('change', async (path) => {\n\t\t\t// Only log if not .DS_Store\n\t\t\tif (!path.includes('.DS_Store')) {\n\t\t\t\tthis.log(`Skill modified: ${path.split('/').pop()}`);\n\t\t\t}\n\t\t\tawait this.skillRegistry.discoverAsync();\n\t\t});\n\n\t\tthis._watcher.on('unlink', async (path) => {\n\t\t\t// Only log if not .DS_Store\n\t\t\tif (!path.includes('.DS_Store')) {\n\t\t\t\tthis.log(`Skill removed: ${path.split('/').pop()}`);\n\t\t\t}\n\t\t\tthis.handleSkillRemoval(path);\n\t\t});\n\t}\n\n\t/**\n\t * Handles the event when a skill file is removed.\n\t *\n\t * This method extracts the skill name from the file path and attempts\n\t * to remove it from the skill registry. If the skill name cannot be\n\t * extracted, or the skill is not found in the registry, the error is logged\n\t * but does not throw.\n\t *\n\t * @param skillPath - The file path of the removed skill file\n\t * @returns A Promise that resolves when handling is complete\n\t *\n\t * @example\n\t * ```typescript\n\t * // When 'commit.md' is removed, this will attempt to remove\n\t * // the skill named 'commit' from the registry\n\t * ```\n\t */\n\tprivate async handleSkillRemoval(skillPath: string): Promise<void> {\n\t\tconst skillName = this.extractSkillNameFromPath(skillPath);\n\t\tif (skillName) {\n\t\t\ttry {\n\t\t\t\tthis.skillRegistry.removeSkillByName(skillName);\n\t\t\t} catch (error) {\n\t\t\t\tconsole.error(\n\t\t\t\t\t`Failed to remove skill ${skillName}:`,\n\t\t\t\t\terror instanceof Error ? error.message : String(error)\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * Internal logging method.\n\t * @param message - The message to log\n\t * @private\n\t */\n\tprivate log(message: string): void {\n\t\t// Optional: check environment variable to disable watcher logs\n\t\tif (process.env.WATCHER_VERBOSE !== 'true') {\n\t\t\treturn;\n\t\t}\n\t\tthis._logger.error(`[Watcher] ${message}`);\n\t}\n\n\t/**\n\t * Extracts the skill name from a file path.\n\t *\n\t * This method takes a file path and extracts the filename without\n\t * extension, which is used as the skill name. For example:\n\t * - `.claude/skills/commit.md` -> `commit.md`\n\t * - `.claude/skills/review-pr.yml` -> `review-pr.yml`\n\t *\n\t * @param skillPath - The file path to extract from\n\t * @returns The extracted filename (with extension), or null if extraction fails\n\t *\n\t * @example\n\t * ```typescript\n\t * extractSkillNameFromPath('/path/to/skills/commit.md')\n\t * // Returns: 'commit.md'\n\t * ```\n\t */\n\tprivate extractSkillNameFromPath(skillPath: string): string | null {\n\t\tconst parts = skillPath.split(/[/\\\\]/);\n\t\treturn parts[parts.length - 1] || null;\n\t}\n\n\t/**\n\t * Stops watching skill directories and cleans up resources.\n\t *\n\t * This method closes the underlying chokidar watcher and releases\n\t * file system resources. After calling this method, the watcher\n\t * cannot be restarted.\n\t *\n\t * @example\n\t * ```typescript\n\t * const watcher = new SkillWatcher(registry);\n\t * // ... use watcher ...\n\t * watcher.stop();\n\t * ```\n\t */\n\tpublic stop(): void {\n\t\tif (this._watcher) {\n\t\t\tthis._watcher.close();\n\t\t\tthis._watcher = null;\n\t\t}\n\t}\n}\n"],"names":["SkillWatcher","skillRegistry","logger","skillDirs","join","homedir","watch","path","skillPath","skillName","error","console","Error","String","message","process","parts"],"mappings":";;;AA2DO,MAAMA;;IAEJ,WAA6B,KAAK;IAClC,QAAgB;IAExB,YACSC,aAA4B,EACpCC,MAAe,CACd;aAFOD,aAAa,GAAbA;QAGR,IAAI,CAAC,OAAO,GAAGC,UAAU,IAAI,CAAC,iBAAiB;QAC/C,IAAI,CAAC,YAAY;IAClB;IAKQ,oBAA4B;QACnC,OAAO;YACN,MAAM,KAAO;YACb,MAAM,KAAO;YACb,OAAO,KAAO;YACd,OAAO,KAAO;YACd,UAAU,KAAO;YACjB,UAAU,IAAM;QACjB;IACD;IAUQ,eAAqB;QAC5B,MAAMC,YAAY;YAAC;YAAkBC,KAAKC,WAAW;SAAkB;QAEvE,IAAI,CAAC,QAAQ,GAAGC,MAAMH,WAAW;YAChC,SAAS;gBAAC;gBAAgB;aAAc;YACxC,YAAY;QACb;QAEA,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,OAAOI;YAE9B,IAAI,CAACA,KAAK,QAAQ,CAAC,cAClB,IAAI,CAAC,GAAG,CAAC,CAAC,aAAa,EAAEA,KAAK,KAAK,CAAC,KAAK,GAAG,IAAI;YAEjD,MAAM,IAAI,CAAC,aAAa,CAAC,aAAa;QACvC;QAEA,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,UAAU,OAAOA;YAEjC,IAAI,CAACA,KAAK,QAAQ,CAAC,cAClB,IAAI,CAAC,GAAG,CAAC,CAAC,gBAAgB,EAAEA,KAAK,KAAK,CAAC,KAAK,GAAG,IAAI;YAEpD,MAAM,IAAI,CAAC,aAAa,CAAC,aAAa;QACvC;QAEA,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,UAAU,OAAOA;YAEjC,IAAI,CAACA,KAAK,QAAQ,CAAC,cAClB,IAAI,CAAC,GAAG,CAAC,CAAC,eAAe,EAAEA,KAAK,KAAK,CAAC,KAAK,GAAG,IAAI;YAEnD,IAAI,CAAC,kBAAkB,CAACA;QACzB;IACD;IAmBA,MAAc,mBAAmBC,SAAiB,EAAiB;QAClE,MAAMC,YAAY,IAAI,CAAC,wBAAwB,CAACD;QAChD,IAAIC,WACH,IAAI;YACH,IAAI,CAAC,aAAa,CAAC,iBAAiB,CAACA;QACtC,EAAE,OAAOC,OAAO;YACfC,QAAQ,KAAK,CACZ,CAAC,uBAAuB,EAAEF,UAAU,CAAC,CAAC,EACtCC,iBAAiBE,QAAQF,MAAM,OAAO,GAAGG,OAAOH;QAElD;IAEF;IAOQ,IAAII,OAAe,EAAQ;QAElC,IAAIC,AAAgC,WAAhCA,QAAQ,GAAG,CAAC,eAAe,EAC9B;QAED,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,UAAU,EAAED,SAAS;IAC1C;IAmBQ,yBAAyBN,SAAiB,EAAiB;QAClE,MAAMQ,QAAQR,UAAU,KAAK,CAAC;QAC9B,OAAOQ,KAAK,CAACA,MAAM,MAAM,GAAG,EAAE,IAAI;IACnC;IAgBO,OAAa;QACnB,IAAI,IAAI,CAAC,QAAQ,EAAE;YAClB,IAAI,CAAC,QAAQ,CAAC,KAAK;YACnB,IAAI,CAAC,QAAQ,GAAG;QACjB;IACD;AACD"}

package/dist/watchers/ToolWatcher.d.ts

@@ -0,0 +1,109 @@
+/**
+ * File system watcher for tool directory changes.
+ *
+ * This module provides the `ToolWatcher` class which monitors configured
+ * tool directories for file changes using chokidar. It watches for
+ * file additions and removals to enable dynamic tool discovery and registration.
+ *
+ * @module watcher
+ */
+import type { Logger } from '../logger/StructuredLogger.js';
+import type { ToolRegistry } from '../registry/ToolRegistry.js';
+/**
+ * File system watcher for tool directories.
+ *
+ * This class monitors configured tool directories for file system changes,
+ * watching for tool file additions and removals. When tool files are added
+ * or removed, it automatically updates the tool registry.
+ *
+ * The watched directories are:
+ * - `.claude/tools` (project-local)
+ * - `~/.claude/tools` (user-global)
+ *
+ * @remarks
+ * **Watched Events:**
+ * - `add` - A new tool file was added (triggers rediscovery)
+ * - `unlink` - A tool file was removed (unregisters the tool)
+ *
+ * **Ignored Paths:**
+ * - `node_modules` directories are ignored
+ *
+ * **Watcher Behavior:**
+ * - Uses persistent mode to continue watching even if files are temporarily deleted
+ * - Automatically starts watching when instantiated
+ * - On file add: Triggers tool rediscovery to pick up new tools
+ * - On file remove: Extracts tool name and unregisters it
+ *
+ * @example
+ * ```typescript
+ * import { ToolWatcher } from './ToolWatcher.js';
+ * import { ToolRegistry } from './registry/ToolRegistry.js';
+ *
+ * const registry = new ToolRegistry();
+ * const watcher = new ToolWatcher(registry);
+ * // Watcher automatically starts monitoring tool directories
+ *
+ * // When done, stop the watcher
+ * watcher.stop();
+ * ```
+ */
+export declare class ToolWatcher {
+    /** The underlying chokidar file system watcher. */
+    private _watcher;
+    /** The tool registry to update when tools change. */
+    private readonly _toolRegistry;
+    private _logger;
+    constructor(toolRegistry: ToolRegistry, logger?: Logger);
+    /**
+     * Create a no-op logger when none is provided.
+     */
+    private _createNoopLogger;
+    /**
+     * Sets up the file system watcher for tool directories.
+     *
+     * Configures chokidar to watch the tool directories and sets up
+     * event handlers for file additions and removals.
+     *
+     * @private
+     */
+    private setupWatcher;
+    /**
+     * Handles the event when a tool file is added.
+     *
+     * When a new `.tool.md` file is detected, this method triggers
+     * tool rediscovery to pick up the new tool.
+     *
+     * @param toolPath - The file path of the added tool file
+     * @returns A Promise that resolves when handling is complete
+     * @private
+     */
+    private handleToolFileAdd;
+    /**
+     * Handles the event when a tool file is removed.
+     *
+     * When a `.tool.md` file is deleted, this method extracts the tool
+     * name from the filename and removes it from the registry.
+     *
+     * @param toolPath - The file path of the removed tool file
+     * @returns A Promise that resolves when handling is complete
+     * @private
+     */
+    private handleToolFileRemoval;
+    /**
+     * Stops watching tool directories and cleans up resources.
+     *
+     * This method closes the underlying chokidar watcher and releases
+     * file system resources. After calling this method, the watcher
+     * cannot be restarted.
+     *
+     * @example
+     * ```typescript
+     * const registry = new ToolRegistry();
+     * const watcher = new ToolWatcher(registry);
+     * // ... use watcher ...
+     * watcher.stop();
+     * ```
+     */
+    stop(): void;
+}
+//# sourceMappingURL=ToolWatcher.d.ts.map

package/dist/watchers/ToolWatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolWatcher.d.ts","sourceRoot":"","sources":["../../src/watchers/ToolWatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,WAAW;IACvB,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAA0B;IAC1C,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAC7C,OAAO,CAAC,OAAO,CAAS;gBAEZ,YAAY,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,MAAM;IAMvD;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAiBpB;;;;;;;;;OASG;YACW,iBAAiB;IAc/B;;;;;;;;;OASG;YACW,qBAAqB;IAqBnC;;;;;;;;;;;;;;OAcG;IACI,IAAI,IAAI,IAAI;CAMnB"}

package/dist/watchers/ToolWatcher.js

@@ -0,0 +1,71 @@
+import { watch } from "chokidar";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+class ToolWatcher {
+    _watcher = null;
+    _toolRegistry;
+    _logger;
+    constructor(toolRegistry, logger){
+        this._toolRegistry = toolRegistry;
+        this._logger = logger ?? this._createNoopLogger();
+        this.setupWatcher();
+    }
+    _createNoopLogger() {
+        return {
+            info: ()=>{},
+            warn: ()=>{},
+            error: ()=>{},
+            debug: ()=>{},
+            setLevel: ()=>{},
+            getLevel: ()=>'info'
+        };
+    }
+    setupWatcher() {
+        const toolDirs = [
+            '.claude/tools',
+            join(homedir(), '.claude/tools')
+        ];
+        this._watcher = watch(toolDirs, {
+            ignored: [
+                /node_modules/,
+                /\.DS_Store$/
+            ],
+            persistent: true
+        });
+        this._watcher.on('add', async (path)=>{
+            await this.handleToolFileAdd(path);
+        });
+        this._watcher.on('unlink', async (path)=>{
+            await this.handleToolFileRemoval(path);
+        });
+    }
+    async handleToolFileAdd(toolPath) {
+        if (!toolPath.endsWith('.tool.md')) return;
+        try {
+            await this._toolRegistry.discoverAsync();
+        } catch (error) {
+            this._logger.error("Failed to discover tools:", {
+                error
+            });
+        }
+    }
+    async handleToolFileRemoval(toolPath) {
+        if (!toolPath.endsWith('.tool.md')) return;
+        const fileName = basename(toolPath);
+        const toolName = fileName.replace('.tool.md', '');
+        if (toolName) try {
+            this._toolRegistry.removeTool(toolName);
+        } catch (error) {
+            this._logger.error(`Tool '${toolName}' not registered: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    stop() {
+        if (this._watcher) {
+            this._watcher.close();
+            this._watcher = null;
+        }
+    }
+}
+export { ToolWatcher };
+
+//# sourceMappingURL=ToolWatcher.js.map

package/dist/watchers/ToolWatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchers/ToolWatcher.js","sources":["../../src/watchers/ToolWatcher.ts"],"sourcesContent":["/**\n * File system watcher for tool directory changes.\n *\n * This module provides the `ToolWatcher` class which monitors configured\n * tool directories for file changes using chokidar. It watches for\n * file additions and removals to enable dynamic tool discovery and registration.\n *\n * @module watcher\n */\n\nimport { watch, type FSWatcher } from 'chokidar';\nimport { homedir } from 'node:os';\nimport { basename, join } from 'node:path';\nimport type { Logger } from '../logger/StructuredLogger.js';\nimport type { ToolRegistry } from '../registry/ToolRegistry.js';\n\n/**\n * File system watcher for tool directories.\n *\n * This class monitors configured tool directories for file system changes,\n * watching for tool file additions and removals. When tool files are added\n * or removed, it automatically updates the tool registry.\n *\n * The watched directories are:\n * - `.claude/tools` (project-local)\n * - `~/.claude/tools` (user-global)\n *\n * @remarks\n * **Watched Events:**\n * - `add` - A new tool file was added (triggers rediscovery)\n * - `unlink` - A tool file was removed (unregisters the tool)\n *\n * **Ignored Paths:**\n * - `node_modules` directories are ignored\n *\n * **Watcher Behavior:**\n * - Uses persistent mode to continue watching even if files are temporarily deleted\n * - Automatically starts watching when instantiated\n * - On file add: Triggers tool rediscovery to pick up new tools\n * - On file remove: Extracts tool name and unregisters it\n *\n * @example\n * ```typescript\n * import { ToolWatcher } from './ToolWatcher.js';\n * import { ToolRegistry } from './registry/ToolRegistry.js';\n *\n * const registry = new ToolRegistry();\n * const watcher = new ToolWatcher(registry);\n * // Watcher automatically starts monitoring tool directories\n *\n * // When done, stop the watcher\n * watcher.stop();\n * ```\n */\nexport class ToolWatcher {\n\t/** The underlying chokidar file system watcher. */\n\tprivate _watcher: FSWatcher | null = null;\n\t/** The tool registry to update when tools change. */\n\tprivate readonly _toolRegistry: ToolRegistry;\n\tprivate _logger: Logger;\n\n\tconstructor(toolRegistry: ToolRegistry, logger?: Logger) {\n\t\tthis._toolRegistry = toolRegistry;\n\t\tthis._logger = logger ?? this._createNoopLogger();\n\t\tthis.setupWatcher();\n\t}\n\n\t/**\n\t * Create a no-op logger when none is provided.\n\t */\n\tprivate _createNoopLogger(): Logger {\n\t\treturn {\n\t\t\tinfo: () => {},\n\t\t\twarn: () => {},\n\t\t\terror: () => {},\n\t\t\tdebug: () => {},\n\t\t\tsetLevel: () => {},\n\t\t\tgetLevel: () => 'info',\n\t\t};\n\t}\n\n\t/**\n\t * Sets up the file system watcher for tool directories.\n\t *\n\t * Configures chokidar to watch the tool directories and sets up\n\t * event handlers for file additions and removals.\n\t *\n\t * @private\n\t */\n\tprivate setupWatcher(): void {\n\t\tconst toolDirs = ['.claude/tools', join(homedir(), '.claude/tools')];\n\n\t\tthis._watcher = watch(toolDirs, {\n\t\t\tignored: [/node_modules/, /\\.DS_Store$/],\n\t\t\tpersistent: true,\n\t\t});\n\n\t\tthis._watcher.on('add', async (path) => {\n\t\t\tawait this.handleToolFileAdd(path);\n\t\t});\n\n\t\tthis._watcher.on('unlink', async (path) => {\n\t\t\tawait this.handleToolFileRemoval(path);\n\t\t});\n\t}\n\n\t/**\n\t * Handles the event when a tool file is added.\n\t *\n\t * When a new `.tool.md` file is detected, this method triggers\n\t * tool rediscovery to pick up the new tool.\n\t *\n\t * @param toolPath - The file path of the added tool file\n\t * @returns A Promise that resolves when handling is complete\n\t * @private\n\t */\n\tprivate async handleToolFileAdd(toolPath: string): Promise<void> {\n\t\t// Only process .tool.md files\n\t\tif (!toolPath.endsWith('.tool.md')) {\n\t\t\treturn;\n\t\t}\n\n\t\t// Trigger rediscovery to pick up the new tool\n\t\ttry {\n\t\t\tawait this._toolRegistry.discoverAsync();\n\t\t} catch (error) {\n\t\t\tthis._logger.error(`Failed to discover tools:`, { error });\n\t\t}\n\t}\n\n\t/**\n\t * Handles the event when a tool file is removed.\n\t *\n\t * When a `.tool.md` file is deleted, this method extracts the tool\n\t * name from the filename and removes it from the registry.\n\t *\n\t * @param toolPath - The file path of the removed tool file\n\t * @returns A Promise that resolves when handling is complete\n\t * @private\n\t */\n\tprivate async handleToolFileRemoval(toolPath: string): Promise<void> {\n\t\t// Only process .tool.md files\n\t\tif (!toolPath.endsWith('.tool.md')) {\n\t\t\treturn;\n\t\t}\n\n\t\t// Extract tool name from filename (e.g., \"my-tool.tool.md\" -> \"my-tool\")\n\t\tconst fileName = basename(toolPath);\n\t\tconst toolName = fileName.replace('.tool.md', '');\n\n\t\tif (toolName) {\n\t\t\ttry {\n\t\t\t\tthis._toolRegistry.removeTool(toolName);\n\t\t\t} catch (error) {\n\t\t\t\tthis._logger.error(\n\t\t\t\t\t`Tool '${toolName}' not registered: ${error instanceof Error ? error.message : String(error)}`\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * Stops watching tool directories and cleans up resources.\n\t *\n\t * This method closes the underlying chokidar watcher and releases\n\t * file system resources. After calling this method, the watcher\n\t * cannot be restarted.\n\t *\n\t * @example\n\t * ```typescript\n\t * const registry = new ToolRegistry();\n\t * const watcher = new ToolWatcher(registry);\n\t * // ... use watcher ...\n\t * watcher.stop();\n\t * ```\n\t */\n\tpublic stop(): void {\n\t\tif (this._watcher) {\n\t\t\tthis._watcher.close();\n\t\t\tthis._watcher = null;\n\t\t}\n\t}\n}\n"],"names":["ToolWatcher","toolRegistry","logger","toolDirs","join","homedir","watch","path","toolPath","error","fileName","basename","toolName","Error","String"],"mappings":";;;AAsDO,MAAMA;IAEJ,WAA6B,KAAK;IAEzB,cAA4B;IACrC,QAAgB;IAExB,YAAYC,YAA0B,EAAEC,MAAe,CAAE;QACxD,IAAI,CAAC,aAAa,GAAGD;QACrB,IAAI,CAAC,OAAO,GAAGC,UAAU,IAAI,CAAC,iBAAiB;QAC/C,IAAI,CAAC,YAAY;IAClB;IAKQ,oBAA4B;QACnC,OAAO;YACN,MAAM,KAAO;YACb,MAAM,KAAO;YACb,OAAO,KAAO;YACd,OAAO,KAAO;YACd,UAAU,KAAO;YACjB,UAAU,IAAM;QACjB;IACD;IAUQ,eAAqB;QAC5B,MAAMC,WAAW;YAAC;YAAiBC,KAAKC,WAAW;SAAiB;QAEpE,IAAI,CAAC,QAAQ,GAAGC,MAAMH,UAAU;YAC/B,SAAS;gBAAC;gBAAgB;aAAc;YACxC,YAAY;QACb;QAEA,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,OAAOI;YAC9B,MAAM,IAAI,CAAC,iBAAiB,CAACA;QAC9B;QAEA,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,UAAU,OAAOA;YACjC,MAAM,IAAI,CAAC,qBAAqB,CAACA;QAClC;IACD;IAYA,MAAc,kBAAkBC,QAAgB,EAAiB;QAEhE,IAAI,CAACA,SAAS,QAAQ,CAAC,aACtB;QAID,IAAI;YACH,MAAM,IAAI,CAAC,aAAa,CAAC,aAAa;QACvC,EAAE,OAAOC,OAAO;YACf,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,6BAA6B;gBAAEA;YAAM;QACzD;IACD;IAYA,MAAc,sBAAsBD,QAAgB,EAAiB;QAEpE,IAAI,CAACA,SAAS,QAAQ,CAAC,aACtB;QAID,MAAME,WAAWC,SAASH;QAC1B,MAAMI,WAAWF,SAAS,OAAO,CAAC,YAAY;QAE9C,IAAIE,UACH,IAAI;YACH,IAAI,CAAC,aAAa,CAAC,UAAU,CAACA;QAC/B,EAAE,OAAOH,OAAO;YACf,IAAI,CAAC,OAAO,CAAC,KAAK,CACjB,CAAC,MAAM,EAAEG,SAAS,kBAAkB,EAAEH,iBAAiBI,QAAQJ,MAAM,OAAO,GAAGK,OAAOL,QAAQ;QAEhG;IAEF;IAiBO,OAAa;QACnB,IAAI,IAAI,CAAC,QAAQ,EAAE;YAClB,IAAI,CAAC,QAAQ,CAAC,KAAK;YACnB,IAAI,CAAC,QAAQ,GAAG;QACjB;IACD;AACD"}

package/package.json

@@ -0,0 +1,95 @@
+{
+	"name": "tracelattice",
+	"version": "1.2.5",
+	"description": "Semantic Sequential Thinking Tools For Agentic Tools",
+	"type": "module",
+	"main": "dist/lib.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"bin": {
+		"tracelattice": "./dist/cli.js"
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"build": "rslib build && rsbuild build -c rsbuild.config.ts && node scripts/postbuild-cli.mjs",
+		"build:lib": "rslib build",
+		"build:cli": "rsbuild build -c rsbuild.config.ts && node scripts/postbuild-cli.mjs",
+		"start": "bun dist/cli.js",
+		"dev": "bunx @modelcontextprotocol/inspector dist/cli.js",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"test:coverage": "vitest run --coverage",
+		"lint": "eslint src/",
+		"lint:fix": "eslint src/ --fix",
+		"format": "prettier --write \"src/**/*.ts\" \"*.{json,md}\"",
+		"format:check": "prettier --check \"src/**/*.ts\" \"*.{json,md}\"",
+		"type-check": "tsc --noEmit",
+		"prepublishOnly": "npm run type-check && npm run lint && npm run test"
+	},
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"sequential-thinking",
+		"problem-solving",
+		"tool-recommendation",
+		"decision-making",
+		"thought-process",
+		"step-by-step",
+		"llm",
+		"ai",
+		"branching-thoughts",
+		"thought-revision",
+		"tool-analysis",
+		"problem-breakdown",
+		"solution-planning",
+		"adaptive-thinking",
+		"reflective-analysis",
+		"tool-confidence"
+	],
+	"author": "CCWorkforces Engineers",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/OCWorkforces/TraceLattice.git"
+	},
+	"bugs": {
+		"url": "https://github.com/OCWorkforces/TraceLattice/issues"
+	},
+	"homepage": "https://github.com/OCWorkforces/TraceLattice#readme",
+	"dependencies": {
+		"@tmcp/adapter-valibot": "^0.1.5",
+		"@tmcp/transport-stdio": "^0.4.2",
+		"chalk": "^5.6.2",
+		"chokidar": "^5.0.0",
+		"tmcp": "^1.19.3",
+		"valibot": "^1.3.1",
+		"yaml": "^2.8.3"
+	},
+	"devDependencies": {
+		"@changesets/cli": "^2.30.0",
+		"@eslint/js": "^10.0.1",
+		"@rsbuild/core": "^1.7.5",
+		"@rslib/core": "^0.21.0",
+		"@tsconfig/node24": "^24.0.4",
+		"@types/node": "^25.6.0",
+		"@typescript-eslint/eslint-plugin": "^8.58.1",
+		"@typescript-eslint/parser": "^8.58.1",
+		"@vitest/coverage-v8": "^4.1.4",
+		"eslint": "^10.2.0",
+		"globals": "^17.4.0",
+		"prettier": "^3.8.2",
+		"typescript": "^6.0.2",
+		"typescript-eslint": "^8.58.1",
+		"vitest": "^4.1.4"
+	}
+}