@iworkforces/tracelattice 2.0.3

package/dist/transport/StreamableHttpTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport/StreamableHttpTransport.js","sources":["../../src/transport/StreamableHttpTransport.ts"],"sourcesContent":["/**\n * Streamable HTTP Transport implementation (MCP spec recommended transport).\n *\n * This transport implements the MCP Streamable HTTP specification, which replaces\n * the deprecated SSE transport as the recommended HTTP-based transport since March 2025.\n *\n * Key features:\n * - POST /mcp for JSON-RPC requests (main MCP endpoint)\n * - GET /mcp for optional SSE server-to-client notifications\n * - Session management via Mcp-Session-Id header\n * - Supports both stateful (session-based) and stateless (per-request) modes\n * - Health endpoints (/health, /ready)\n *\n * @example\n * ```typescript\n * const transport = new StreamableHttpTransport({\n *   port: 3000,\n *   host: 'localhost',\n *   stateful: true,\n * });\n * await transport.connect(server);\n * ```\n */\n\nimport { randomUUID } from 'node:crypto';\nimport { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';\nimport type { McpServer } from 'tmcp';\nimport { safeParse } from 'valibot';\nimport type { IMetrics } from '../contracts/interfaces.js';\nimport { getErrorMessage } from '../errors.js';\nimport { JsonRpcRequestSchema } from '../schema.js';\nimport { BaseTransport, type TransportOptions } from './BaseTransport.js';\nimport type { ITransport, TransportKind } from '../contracts/transport.js';\nimport { asSessionId, type SessionId } from '../contracts/ids.js';\nimport { readRequestBody } from './HttpHelpers.js';\nimport { runWithContext } from '../context/RequestContext.js';\nimport {\n\tAcceptedWorkTracker,\n\tLifecycleFailureReporter,\n\tResponseFinalizer,\n} from './HttpRequestLifecycle.js';\n\n/**\n * MCP Streamable HTTP transport options extending base TransportOptions.\n */\nexport interface StreamableHttpTransportOptions extends TransportOptions {\n\t/**\n\t * Path for the MCP endpoint\n\t * @default '/mcp'\n\t */\n\tpath?: string;\n\n\t/**\n\t * Metrics collector for transport telemetry\n\t */\n\tmetrics?: IMetrics;\n\n\t/**\n\t * Prometheus metrics provider function\n\t */\n\tmetricsProvider?: () => string;\n\n\t/**\n\t * Enable stateful session-based mode.\n\t * When true, sessions are tracked via Mcp-Session-Id header.\n\t * When false, each request is processed independently (stateless).\n\t * @default true\n\t */\n\tstateful?: boolean;\n\n\t/**\n\t * Custom session ID generator function.\n\t * @default () => randomUUID()\n\t */\n\tsessionIdGenerator?: () => string;\n\n\t/**\n\t * Enable request body size limit\n\t * @default true\n\t */\n\tenableBodySizeLimit?: boolean;\n\n\t/**\n\t * Maximum request body size in bytes\n\t * @default 10485760 (10MB)\n\t */\n\tmaxBodySize?: number;\n\n\t/**\n\t * Request timeout in milliseconds\n\t * @default 30000 (30 seconds)\n\t */\n\trequestTimeout?: number;\n}\n\n/**\n * Internal session state for stateful mode.\n */\ninterface SessionState {\n\t/** Unique session identifier */\n\tid: string;\n\t/** Timestamp when the session was created */\n\tcreatedAt: number;\n\t/** Timestamp of the last activity */\n\tlastActivityAt: number;\n\t/** Active SSE notification streams for this session */\n\tnotificationStreams: Set<ServerResponse>;\n}\n\ntype SessionError = {\n\treadonly statusCode: number;\n\treadonly code: number;\n\treadonly message: string;\n};\n\n/**\n * Streamable HTTP Transport for MCP server.\n *\n * This transport implements the MCP Streamable HTTP specification,\n * providing JSON-RPC over HTTP with optional session management\n * and server-to-client SSE notification streams.\n *\n * @remarks\n * **Security Features (inherited from BaseTransport):**\n * - Session ID validation (alphanumeric, max 64 chars)\n * - Query parameter sanitization (whitelist allowed keys)\n * - Rate limiting per IP (configurable, default 100 req/min)\n * - CORS origin validation\n * - Host header validation\n *\n * **MCP Streamable HTTP Spec Compliance:**\n * - POST /mcp — JSON-RPC method calls\n * - GET /mcp — SSE notification stream (server-to-client)\n * - Mcp-Session-Id header for session management\n * - Content-Type: application/json for JSON-RPC responses\n * - Content-Type: text/event-stream for SSE notification streams\n *\n * **HTTP Status Code Mapping:**\n * - 200: Success (JSON-RPC response or SSE stream)\n * - 202: Accepted (JSON-RPC notification, no response body)\n * - 204: CORS Preflight (empty body)\n * - 400: Bad Request (invalid JSON, invalid session ID)\n * - 403: Forbidden (invalid CORS, invalid host)\n * - 404: Not Found\n * - 405: Method Not Allowed\n * - 413: Payload Too Large\n * - 429: Too Many Requests\n * - 500: Internal Server Error\n * - 503: Server Not Ready / Shutting Down\n */\nexport class StreamableHttpTransport extends BaseTransport implements ITransport {\n\tget kind(): TransportKind {\n\t\treturn 'streamable-http';\n\t}\n\tprivate _server: Server | null = null;\n\tprivate _mcpServer: McpServer | null = null;\n\tprivate _path: string;\n\tprivate _stateful: boolean;\n\tprivate _sessionIdGenerator: () => string;\n\tprivate _sessions: Map<SessionId, SessionState> = new Map();\n\tprivate _requestCount: number = 0;\n\tprivate _activeRequests: number = 0;\n\tprivate _bodySizeLimitEnabled: boolean;\n\tprivate _maxBodySize: number;\n\tprivate _requestTimeout: number;\n\tprivate _metrics?: IMetrics;\n\tprivate _metricsProvider: (() => string) | null;\n\tprivate readonly _lifecycleFailureReporter: LifecycleFailureReporter;\n\tprivate readonly _acceptedWork: AcceptedWorkTracker;\n\tprivate _stopPromise: Promise<void> | null = null;\n\n\tconstructor(options: StreamableHttpTransportOptions = {}) {\n\t\tsuper(options);\n\n\t\tthis._path = options.path ?? '/mcp';\n\t\tthis._stateful = options.stateful ?? true;\n\t\tthis._sessionIdGenerator = options.sessionIdGenerator ?? (() => randomUUID());\n\t\tthis._bodySizeLimitEnabled = options.enableBodySizeLimit ?? true;\n\t\tthis._maxBodySize = options.maxBodySize ?? 10 * 1024 * 1024;\n\t\tthis._requestTimeout = options.requestTimeout ?? 30000;\n\t\tthis._metrics = options.metrics;\n\t\tthis._metricsProvider = options.metricsProvider ?? null;\n\t\tthis._lifecycleFailureReporter = new LifecycleFailureReporter((error) => {\n\t\t\tthis.log('error', 'Streamable HTTP request lifecycle failed', {\n\t\t\t\terror: getErrorMessage(error),\n\t\t\t});\n\t\t});\n\t\tthis._acceptedWork = new AcceptedWorkTracker(this._lifecycleFailureReporter);\n\t}\n\n\tprivate _requireMcpServer(): McpServer {\n\t\tif (!this._mcpServer) {\n\t\t\tthrow new Error('MCP server not initialized. Did you call connect()?');\n\t\t}\n\t\treturn this._mcpServer;\n\t}\n\n\t/**\n\t * Get number of active sessions (stateful) or active requests (stateless).\n\t */\n\tget clientCount(): number {\n\t\treturn this._stateful ? this._sessions.size : this._activeRequests;\n\t}\n\n\t/**\n\t * Get the total number of requests handled.\n\t */\n\tget requestCount(): number {\n\t\treturn this._requestCount;\n\t}\n\n\t/**\n\t * Connects MCP server to this transport and starts listening.\n\t */\n\tasync connect(mcpServer: McpServer): Promise<void> {\n\t\tthis._mcpServer = mcpServer;\n\t\tconst server = createServer((req, res) => {\n\t\t\tconst responseFinalizer = new ResponseFinalizer(res, this._lifecycleFailureReporter);\n\t\t\tvoid this._handleRequest(req, res).catch((error: unknown) => {\n\t\t\t\tthis._lifecycleFailureReporter.report(error);\n\t\t\t\tresponseFinalizer.finalize((response) => {\n\t\t\t\t\tthis._sendJsonRpcError(response, 500, -32603, 'Internal error', null, {\n\t\t\t\t\t\tdata: getErrorMessage(error),\n\t\t\t\t\t});\n\t\t\t\t});\n\t\t\t});\n\t\t});\n\t\tthis._server = server;\n\n\t\treturn new Promise((resolve, reject) => {\n\t\t\tconst cleanup = (): void => {\n\t\t\t\tserver.off('error', onError);\n\t\t\t\tserver.off('listening', onListening);\n\t\t\t};\n\t\t\tconst onError = (error: Error): void => {\n\t\t\t\tcleanup();\n\t\t\t\treject(error);\n\t\t\t};\n\t\t\tconst onListening = (): void => {\n\t\t\t\tcleanup();\n\t\t\t\tthis.log(\n\t\t\t\t\t'info',\n\t\t\t\t\t`Streamable HTTP transport listening on http://${this._host}:${this._port}`\n\t\t\t\t);\n\t\t\t\tresolve();\n\t\t\t};\n\t\t\tserver.once('error', onError);\n\t\t\tserver.once('listening', onListening);\n\t\t\ttry {\n\t\t\t\tserver.listen(this._port, this._host);\n\t\t\t} catch (error) {\n\t\t\t\tcleanup();\n\t\t\t\treject(error);\n\t\t\t}\n\t\t});\n\t}\n\n\t/**\n\t * Route and handle incoming HTTP requests.\n\t */\n\tprivate async _handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {\n\t\tconst startTime = Date.now();\n\t\tthis._metrics?.counter(\n\t\t\t'streamable_http_requests_total',\n\t\t\t1,\n\t\t\t{},\n\t\t\t'Total Streamable HTTP transport requests'\n\t\t);\n\t\tres.once('finish', () => {\n\t\t\tconst durationSeconds = (Date.now() - startTime) / 1000;\n\t\t\tthis._metrics?.histogram('streamable_http_request_duration_seconds', durationSeconds, {});\n\t\t});\n\n\t\t// Host validation\n\t\tif (!this.validateHostHeader(req)) {\n\t\t\tthis._sendJsonRpcError(res, 403, -32000, 'Forbidden - invalid host header');\n\t\t\treturn;\n\t\t}\n\n\t\t// Shutdown check\n\t\tif (this.isShuttingDown) {\n\t\t\tthis._sendJsonRpcError(res, 503, -32603, 'Server is shutting down');\n\t\t\treturn;\n\t\t}\n\n\t\t// Rate limiting\n\t\tconst clientIp = this.getClientIp(req);\n\t\tif (this.checkRateLimit(clientIp)) {\n\t\t\tres.setHeader('Retry-After', '60');\n\t\t\tthis._sendJsonRpcError(res, 429, -32000, 'Too many requests');\n\t\t\treturn;\n\t\t}\n\n\t\t// CORS validation\n\t\tif (!this.validateCorsOrigin(req)) {\n\t\t\tthis._sendJsonRpcError(res, 403, -32000, 'Forbidden - invalid origin');\n\t\t\treturn;\n\t\t}\n\n\t\tthis.setCorsHeaders(res);\n\n\t\t// CORS preflight\n\t\tif (req.method === 'OPTIONS') {\n\t\t\tres.setHeader('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id');\n\t\t\tres.writeHead(204);\n\t\t\tres.end();\n\t\t\treturn;\n\t\t}\n\n\t\t// Parse URL path\n\t\tconst urlPath = req.url?.split('?')[0] ?? '/';\n\n\t\t// Metrics endpoint\n\t\tif (req.method === 'GET' && urlPath === '/metrics') {\n\t\t\tthis._handleMetrics(res);\n\t\t\treturn;\n\t\t}\n\n\t\t// Health check (liveness)\n\t\tif (req.method === 'GET' && urlPath === '/health') {\n\t\t\tthis._handleHealthCheck(res);\n\t\t\treturn;\n\t\t}\n\n\t\t// Readiness check\n\t\tif (req.method === 'GET' && urlPath === '/ready') {\n\t\t\tawait this._handleReadinessCheck(res);\n\t\t\treturn;\n\t\t}\n\n\t\t// MCP endpoint routing\n\t\tif (urlPath === this._path) {\n\t\t\tif (req.method === 'POST') {\n\t\t\t\tthis._acceptedWork.track(this._handleMcpPost(req, res));\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (req.method === 'GET') {\n\t\t\t\tthis._handleMcpGet(req, res);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tres.writeHead(405, { 'Content-Type': 'application/json', Allow: 'GET, POST' });\n\t\t\tres.end(\n\t\t\t\tJSON.stringify({\n\t\t\t\t\tjsonrpc: '2.0',\n\t\t\t\t\tid: null,\n\t\t\t\t\terror: { code: -32601, message: 'Method not allowed' },\n\t\t\t\t})\n\t\t\t);\n\t\t\treturn;\n\t\t}\n\n\t\t// 404 for unknown paths\n\t\tthis._sendJsonRpcError(res, 404, -32601, 'Not Found');\n\t}\n\n\t/**\n\t * Send a JSON-RPC error response.\n\t */\n\tprivate _sendJsonRpcError(\n\t\tres: ServerResponse,\n\t\tstatusCode: number,\n\t\tcode: number,\n\t\tmessage: string,\n\t\tid: unknown = null,\n\t\textra?: Record<string, unknown>\n\t): void {\n\t\tconst error: Record<string, unknown> = { code, message };\n\t\tif (extra) {\n\t\t\tObject.assign(error, extra);\n\t\t}\n\t\tres.writeHead(statusCode, { 'Content-Type': 'application/json' });\n\t\tres.end(JSON.stringify({ jsonrpc: '2.0', id, error }));\n\t}\n\n\t/**\n\t * Handle POST /mcp — JSON-RPC method calls.\n\t *\n\t * Per the MCP Streamable HTTP spec:\n\t * - Accepts JSON-RPC request bodies\n\t * - Returns Mcp-Session-Id header for new sessions (stateful mode)\n\t * - Validates Mcp-Session-Id for existing sessions (stateful mode)\n\t * - Content-Type: application/json for responses\n\t */\n\tprivate async _handleMcpPost(req: IncomingMessage, res: ServerResponse): Promise<void> {\n\t\tthis._requestCount++;\n\t\tthis._activeRequests++;\n\t\tconst responseFinalizer = new ResponseFinalizer(res, this._lifecycleFailureReporter);\n\n\t\tconst timeout = setTimeout(() => {\n\t\t\tresponseFinalizer.finalize((response) => {\n\t\t\t\tthis._sendJsonRpcError(response, 500, -32603, 'Request timeout');\n\t\t\t});\n\t\t}, this._requestTimeout);\n\t\ttry {\n\t\t\t// Read request body with size limit\n\t\t\tconst body = await readRequestBody(req, this._bodySizeLimitEnabled ? this._maxBodySize : 0);\n\t\t\tif (body === null) {\n\t\t\t\tresponseFinalizer.finalize((response) => {\n\t\t\t\t\tthis._sendJsonRpcError(response, 413, -32000, 'Request body too large');\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// Parse JSON\n\t\t\tlet rawBody: unknown;\n\t\t\ttry {\n\t\t\t\trawBody = JSON.parse(body) as unknown;\n\t\t\t} catch {\n\t\t\t\tresponseFinalizer.finalize((response) => {\n\t\t\t\t\tthis._sendJsonRpcError(response, 200, -32700, 'Parse error');\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// Validate JSON-RPC schema\n\t\t\tconst parseResult = safeParse(JsonRpcRequestSchema, rawBody);\n\t\t\tconst rawId =\n\t\t\t\trawBody && typeof rawBody === 'object' && 'id' in rawBody\n\t\t\t\t\t? ((rawBody as { id?: unknown }).id ?? null)\n\t\t\t\t\t: null;\n\t\t\tif (!parseResult.success) {\n\t\t\t\tresponseFinalizer.finalize((response) => {\n\t\t\t\t\tthis._sendJsonRpcError(\n\t\t\t\t\t\tresponse,\n\t\t\t\t\t\t200,\n\t\t\t\t\t\t-32600,\n\t\t\t\t\t\t'Invalid Request',\n\t\t\t\t\t\trawId as string | number | null,\n\t\t\t\t\t\t{ data: parseResult.issues }\n\t\t\t\t\t);\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst jsonRpcRequest = parseResult.output;\n\n\t\t\t// Session management (stateful mode)\n\t\t\tlet sessionId: string | undefined;\n\t\t\tif (this._stateful) {\n\t\t\t\tconst sessionResult = this._resolveSession(req);\n\t\t\t\tif (typeof sessionResult !== 'string') {\n\t\t\t\t\tresponseFinalizer.finalize((response) => {\n\t\t\t\t\t\tthis._sendJsonRpcError(\n\t\t\t\t\t\t\tresponse,\n\t\t\t\t\t\t\tsessionResult.statusCode,\n\t\t\t\t\t\t\tsessionResult.code,\n\t\t\t\t\t\t\tsessionResult.message\n\t\t\t\t\t\t);\n\t\t\t\t\t});\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tsessionId = sessionResult;\n\t\t\t}\n\n\t\t\t// Check if MCP server is ready\n\t\t\tif (!this._mcpServer) {\n\t\t\t\tresponseFinalizer.finalize((response) => {\n\t\t\t\t\tthis._sendJsonRpcError(\n\t\t\t\t\t\tresponse,\n\t\t\t\t\t\t503,\n\t\t\t\t\t\t-32603,\n\t\t\t\t\t\t'Server not ready',\n\t\t\t\t\t\tjsonRpcRequest?.id ?? null\n\t\t\t\t\t);\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tawait this._receiveAndFinalize(\n\t\t\t\tjsonRpcRequest as Parameters<McpServer['receive']>[0],\n\t\t\t\tsessionId,\n\t\t\t\tresponseFinalizer\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tresponseFinalizer.finalize((response) => {\n\t\t\t\tthis._sendJsonRpcError(response, 200, -32603, 'Internal error', null, {\n\t\t\t\t\tdata: getErrorMessage(error),\n\t\t\t\t});\n\t\t\t});\n\t\t} finally {\n\t\t\tclearTimeout(timeout);\n\t\t\tthis._activeRequests--;\n\t\t}\n\t}\n\n\tprivate async _receiveAndFinalize(\n\t\tjsonRpcRequest: Parameters<McpServer['receive']>[0],\n\t\tsessionId: string | undefined,\n\t\tresponseFinalizer: ResponseFinalizer\n\t): Promise<void> {\n\t\tconst owner = this._stateful ? (sessionId ?? randomUUID()) : randomUUID();\n\t\tconst response = await runWithContext({ requestId: randomUUID(), owner }, () =>\n\t\t\tthis._requireMcpServer().receive(jsonRpcRequest, { sessionInfo: {} })\n\t\t);\n\t\tconst responseHeaders: Record<string, string> = { 'Content-Type': 'application/json' };\n\t\tif (sessionId) responseHeaders['Mcp-Session-Id'] = sessionId;\n\n\t\tresponseFinalizer.finalize((httpResponse) => {\n\t\t\tif (response) {\n\t\t\t\thttpResponse.writeHead(200, responseHeaders);\n\t\t\t\thttpResponse.end(JSON.stringify(response));\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (sessionId) httpResponse.setHeader('Mcp-Session-Id', sessionId);\n\t\t\thttpResponse.writeHead(202);\n\t\t\thttpResponse.end();\n\t\t});\n\t}\n\n\t/**\n\t * Handle GET /mcp — Optional SSE notification stream.\n\t *\n\t * Per the MCP Streamable HTTP spec, clients may open a GET request\n\t * to receive server-initiated notifications as SSE events.\n\t * Requires a valid Mcp-Session-Id in stateful mode.\n\t */\n\tprivate _handleMcpGet(req: IncomingMessage, res: ServerResponse): void {\n\t\tif (!this._stateful) {\n\t\t\t// SSE notification streams require stateful mode\n\t\t\tres.writeHead(405, {\n\t\t\t\t'Content-Type': 'application/json',\n\t\t\t\tAllow: 'POST',\n\t\t\t});\n\t\t\tres.end(\n\t\t\t\tJSON.stringify({\n\t\t\t\t\tjsonrpc: '2.0',\n\t\t\t\t\tid: null,\n\t\t\t\t\terror: { code: -32601, message: 'GET not supported in stateless mode' },\n\t\t\t\t})\n\t\t\t);\n\t\t\treturn;\n\t\t}\n\n\t\t// Require Mcp-Session-Id for GET requests\n\t\tconst sessionId = this._getSessionIdFromHeader(req);\n\t\tif (!sessionId) {\n\t\t\tres.writeHead(400, { 'Content-Type': 'application/json' });\n\t\t\tres.end(\n\t\t\t\tJSON.stringify({\n\t\t\t\t\tjsonrpc: '2.0',\n\t\t\t\t\tid: null,\n\t\t\t\t\terror: { code: -32600, message: 'Missing Mcp-Session-Id header' },\n\t\t\t\t})\n\t\t\t);\n\t\t\treturn;\n\t\t}\n\n\t\tconst session = this._sessions.get(asSessionId(sessionId));\n\t\tif (!session) {\n\t\t\tres.writeHead(404, { 'Content-Type': 'application/json' });\n\t\t\tres.end(\n\t\t\t\tJSON.stringify({\n\t\t\t\t\tjsonrpc: '2.0',\n\t\t\t\t\tid: null,\n\t\t\t\t\terror: { code: -32001, message: 'Session not found' },\n\t\t\t\t})\n\t\t\t);\n\t\t\treturn;\n\t\t}\n\n\t\t// Set SSE headers\n\t\tres.writeHead(200, {\n\t\t\t'Content-Type': 'text/event-stream',\n\t\t\t'Cache-Control': 'no-cache',\n\t\t\tConnection: 'keep-alive',\n\t\t\t'Mcp-Session-Id': sessionId,\n\t\t});\n\n\t\t// Send initial connected event\n\t\tthis._sendSseEvent(res, 'connected', {\n\t\t\tsessionId,\n\t\t\ttimestamp: Date.now(),\n\t\t});\n\n\t\t// Track this notification stream\n\t\tsession.notificationStreams.add(res);\n\t\tsession.lastActivityAt = Date.now();\n\t\tthis._updateSessionMetrics();\n\n\t\t// Handle client disconnect\n\t\treq.on('close', () => {\n\t\t\tsession.notificationStreams.delete(res);\n\t\t\tthis._updateSessionMetrics();\n\t\t});\n\t}\n\n\t/**\n\t * Resolve or create a session for a stateful request.\n\t *\n\t * @returns Session ID string on success, or the response error to finalize.\n\t */\n\tprivate _resolveSession(req: IncomingMessage): string | SessionError {\n\t\tconst headerSessionId = this._getSessionIdFromHeader(req);\n\n\t\tif (headerSessionId) {\n\t\t\t// Validate format\n\t\t\tif (!this.validateSessionId(headerSessionId)) {\n\t\t\t\treturn {\n\t\t\t\t\tstatusCode: 400,\n\t\t\t\t\tcode: -32600,\n\t\t\t\t\tmessage: 'Invalid Mcp-Session-Id format',\n\t\t\t\t};\n\t\t\t}\n\n\t\t\t// Check if session exists\n\t\t\tconst session = this._sessions.get(asSessionId(headerSessionId));\n\t\t\tif (session) {\n\t\t\t\tsession.lastActivityAt = Date.now();\n\t\t\t\treturn headerSessionId;\n\t\t\t}\n\n\t\t\t// Unknown session ID — per spec, return 404\n\t\t\treturn { statusCode: 404, code: -32001, message: 'Session not found' };\n\t\t}\n\n\t\t// No session header — create new session\n\t\tconst newSessionId = this._sessionIdGenerator();\n\t\tconst sessionState: SessionState = {\n\t\t\tid: newSessionId,\n\t\t\tcreatedAt: Date.now(),\n\t\t\tlastActivityAt: Date.now(),\n\t\t\tnotificationStreams: new Set(),\n\t\t};\n\t\tthis._sessions.set(asSessionId(newSessionId), sessionState);\n\t\tthis.log('info', `New session created: ${newSessionId}`);\n\t\tthis._updateSessionMetrics();\n\n\t\treturn newSessionId;\n\t}\n\n\t/**\n\t * Extract Mcp-Session-Id from request headers.\n\t */\n\tprivate _getSessionIdFromHeader(req: IncomingMessage): string | undefined {\n\t\tconst value = req.headers['mcp-session-id'];\n\t\tif (typeof value === 'string' && value.length > 0) {\n\t\t\treturn value;\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Send an SSE event to a specific client response stream.\n\t */\n\tprivate _sendSseEvent(res: ServerResponse, event: string, data: unknown): void {\n\t\ttry {\n\t\t\tres.write(`event: ${event}\\n`);\n\t\t\tres.write(`data: ${JSON.stringify(data)}\\n\\n`);\n\t\t} catch {\n\t\t\t// Client disconnected — ignore\n\t\t}\n\t}\n\n\t/**\n\t * Broadcast a notification to all SSE streams in a given session.\n\t *\n\t * @param sessionId - Target session ID\n\t * @param event - SSE event name\n\t * @param data - Event payload\n\t */\n\tbroadcastToSession(sessionId: string, event: string, data: unknown): void {\n\t\tconst session = this._sessions.get(asSessionId(sessionId));\n\t\tif (!session) {\n\t\t\treturn;\n\t\t}\n\n\t\tfor (const stream of session.notificationStreams) {\n\t\t\tthis._sendSseEvent(stream, event, data);\n\t\t}\n\t}\n\n\t/**\n\t * Handle GET /metrics endpoint.\n\t */\n\tprivate _handleMetrics(res: ServerResponse): void {\n\t\tif (!this._metricsProvider) {\n\t\t\tres.writeHead(404, { 'Content-Type': 'text/plain' });\n\t\t\tres.end('Not Found');\n\t\t\treturn;\n\t\t}\n\n\t\tres.writeHead(200, { 'Content-Type': 'text/plain; version=0.0.4; charset=utf-8' });\n\t\tres.end(this._metricsProvider());\n\t}\n\n\t/**\n\t * Handle GET /health — Liveness check.\n\t */\n\tprivate _handleHealthCheck(res: ServerResponse): void {\n\t\tconst healthData: Record<string, unknown> = {\n\t\t\tstatus: 'healthy',\n\t\t\trequests: this._requestCount,\n\t\t\tsessions: this._sessions.size,\n\t\t\ttransport: 'streamable-http',\n\t\t};\n\t\tif (this._healthChecker) {\n\t\t\tconst liveness = this._healthChecker.checkLiveness();\n\t\t\thealthData.liveness = liveness;\n\t\t}\n\t\tres.writeHead(200, { 'Content-Type': 'application/json' });\n\t\tres.end(JSON.stringify(healthData));\n\t}\n\n\t/**\n\t * Handle GET /ready — Readiness check.\n\t */\n\tprivate async _handleReadinessCheck(res: ServerResponse): Promise<void> {\n\t\tif (this._healthChecker) {\n\t\t\tconst readiness = await this._healthChecker.checkReadiness();\n\t\t\tconst statusCode = readiness.status === 'ok' ? 200 : 503;\n\t\t\tres.writeHead(statusCode, { 'Content-Type': 'application/json' });\n\t\t\tres.end(JSON.stringify(readiness));\n\t\t} else {\n\t\t\tres.writeHead(200, { 'Content-Type': 'application/json' });\n\t\t\tres.end(\n\t\t\t\tJSON.stringify({\n\t\t\t\t\tstatus: 'ok',\n\t\t\t\t\ttimestamp: new Date().toISOString(),\n\t\t\t\t\tcomponents: {},\n\t\t\t\t})\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Update session-related metrics.\n\t */\n\tprivate _updateSessionMetrics(): void {\n\t\tthis._metrics?.gauge(\n\t\t\t'streamable_http_active_sessions',\n\t\t\tthis._sessions.size,\n\t\t\t{},\n\t\t\t'Active Streamable HTTP sessions'\n\t\t);\n\n\t\tlet totalStreams = 0;\n\t\tfor (const session of this._sessions.values()) {\n\t\t\ttotalStreams += session.notificationStreams.size;\n\t\t}\n\t\tthis._metrics?.gauge(\n\t\t\t'streamable_http_notification_streams',\n\t\t\ttotalStreams,\n\t\t\t{},\n\t\t\t'Active SSE notification streams'\n\t\t);\n\t}\n\n\t/**\n\t * Stop transport server with graceful shutdown.\n\t *\n\t * @param timeout - Maximum time before force-closing HTTP connections (default: 30s)\n\t */\n\tstop(timeout?: number): Promise<void> {\n\t\tif (this._stopPromise) return this._stopPromise;\n\t\tthis._isShuttingDown = true;\n\t\tthis._stopRateLimitCleanup();\n\n\t\tconst shutdownTimeout = timeout ?? 30000;\n\n\t\t// Close all SSE notification streams\n\t\tfor (const session of this._sessions.values()) {\n\t\t\tfor (const stream of session.notificationStreams) {\n\t\t\t\ttry {\n\t\t\t\t\tstream.end();\n\t\t\t\t} catch {\n\t\t\t\t\t// Ignore errors\n\t\t\t\t}\n\t\t\t}\n\t\t\tsession.notificationStreams.clear();\n\t\t}\n\t\tthis._sessions.clear();\n\n\t\tconst server = this._server;\n\t\tconst serverClosed = new Promise<void>((resolve, reject) => {\n\t\t\tif (!server?.listening) {\n\t\t\t\tresolve();\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tlet settled = false;\n\t\t\tlet forceClose: NodeJS.Timeout | null = null;\n\t\t\tserver.close((error) => {\n\t\t\t\tif (settled) return;\n\t\t\t\tsettled = true;\n\t\t\t\tif (forceClose) clearTimeout(forceClose);\n\t\t\t\tif (error) {\n\t\t\t\t\treject(error);\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tresolve();\n\t\t\t});\n\t\t\tif (settled) return;\n\t\t\tforceClose = setTimeout(() => {\n\t\t\t\tif (settled) return;\n\t\t\t\tsettled = true;\n\t\t\t\tthis.log('warn', 'Streamable HTTP transport force-closing after timeout');\n\t\t\t\tserver.closeAllConnections();\n\t\t\t\tresolve();\n\t\t\t}, shutdownTimeout);\n\t\t});\n\t\tconst stopPromise = Promise.all([serverClosed, this._acceptedWork.join()]).then(() => {\n\t\t\tthis.log('info', 'Streamable HTTP transport stopped');\n\t\t});\n\t\tthis._stopPromise = stopPromise;\n\t\tvoid stopPromise.catch(() => {\n\t\t\tif (this._stopPromise === stopPromise) this._stopPromise = null;\n\t\t});\n\t\treturn stopPromise;\n\t}\n}\n\n/**\n * Create a Streamable HTTP transport with given options.\n *\n * @param options - Transport configuration\n * @returns A configured Streamable HTTP transport\n *\n * @example\n * ```typescript\n * const transport = createStreamableHttpTransport({ port: 3000, stateful: true });\n * await transport.connect(server);\n * ```\n */\nexport function createStreamableHttpTransport(\n\toptions: StreamableHttpTransportOptions = {}\n): StreamableHttpTransport {\n\treturn new StreamableHttpTransport(options);\n}\n"],"names":["StreamableHttpTransport","BaseTransport","Map","options","randomUUID","LifecycleFailureReporter","error","getErrorMessage","AcceptedWorkTracker","Error","mcpServer","server","createServer","req","res","responseFinalizer","ResponseFinalizer","response","Promise","resolve","reject","cleanup","onError","onListening","startTime","Date","durationSeconds","clientIp","urlPath","JSON","statusCode","code","message","id","extra","Object","timeout","setTimeout","body","readRequestBody","rawBody","parseResult","safeParse","JsonRpcRequestSchema","rawId","jsonRpcRequest","sessionId","sessionResult","clearTimeout","owner","runWithContext","responseHeaders","httpResponse","session","asSessionId","headerSessionId","newSessionId","sessionState","Set","value","event","data","stream","healthData","liveness","readiness","totalStreams","shutdownTimeout","serverClosed","settled","forceClose","stopPromise","createStreamableHttpTransport"],"mappings":"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"}

package/dist/types/disposable.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Interface for services that need resource cleanup.
+ *
+ * Implement this on any service that holds resources (connections, file handles, timers, etc.)
+ *
+ * @module types/disposable
+ *
+ * @example
+ * ```typescript
+ * class MyService implements IDisposable {
+ *   async dispose(): Promise<void> {
+ *     await this.closeConnections();
+ *     this.clearTimers();
+ *   }
+ * }
+ * ```
+ */
+export interface IDisposable {
+    /** Release all resources held by this service. */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=disposable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"disposable.d.ts","sourceRoot":"","sources":["../../src/types/disposable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,WAAW;IAC3B,kDAAkD;IAClD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}

package/dist/types/disposable.js

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

package/dist/types/server-config.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Runtime server configuration type.
+ *
+ * @module types/server-config
+ */
+import type { Skill } from './skill.js';
+import type { Tool } from './tool.js';
+/**
+ * Runtime server configuration containing available tools and skills.
+ *
+ * This interface represents the active configuration at runtime,
+ * providing access to the registry of available tools and skills.
+ *
+ * @example
+ * ```typescript
+ * const config: ServerConfig = {
+ *   available_tools: new Map([
+ *     ['Read', { name: 'Read', description: '...', inputSchema: {...} }]
+ *   ]),
+ *   available_skills: new Map([
+ *     ['commit', { name: 'commit', description: '...', user_invocable: true }]
+ *   ])
+ * };
+ * ```
+ */
+export interface ServerConfig {
+    /** Map of registered tools indexed by their unique names. */
+    available_tools: Map<string, Tool>;
+    /** Map of registered skills indexed by their unique names. */
+    available_skills: Map<string, Skill>;
+}
+//# sourceMappingURL=server-config.d.ts.map

package/dist/types/server-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/types/server-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,YAAY;IAC5B,6DAA6D;IAC7D,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAEnC,8DAA8D;IAC9D,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CACrC"}

package/dist/types/server-config.js

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

package/dist/types/skill.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Skill types for MCP skill recommendations and definitions.
+ *
+ * @module types/skill
+ */
+/**
+ * Represents a recommended skill with associated metadata.
+ *
+ * Skills are higher-level workflows that coordinate multiple tools and operations.
+ * Skill recommendations include information about which tools the skill is allowed
+ * to use and whether the skill can be invoked directly by users.
+ *
+ * @example
+ * ```typescript
+ * const recommendation: SkillRecommendation = {
+ *   skill_name: 'commit',
+ *   confidence: 0.95,
+ *   rationale: 'Handles the complete git commit workflow',
+ *   priority: 1,
+ *   alternatives: ['review-pr'],
+ *   allowed_tools: ['Bash', 'Read', 'Grep'],
+ *   user_invocable: true
+ * };
+ * ```
+ *
+ * NOTE: Kept as a hand-written interface (not inferred from `SkillRecommendationSchema`)
+ * because `confidence`, `rationale`, and `priority` are REQUIRED here but OPTIONAL in the
+ * schema (the schema accepts partial LLM input; the normalizer fills defaults). An inferred
+ * type would make these fields optional and break call sites that read them without guards.
+ */
+export interface SkillRecommendation {
+    /** The unique name/identifier of the recommended skill. */
+    skill_name: string;
+    /** Confidence score from 0-1 indicating how appropriate this skill is for the current task. */
+    confidence: number;
+    /** Explanation of why this skill is recommended and how it addresses the current need. */
+    rationale: string;
+    /** Order in the recommendation sequence (lower numbers = higher priority). */
+    priority: number;
+    /** Alternative skills that could be used if the primary recommendation is not available. */
+    alternatives?: string[];
+    /** List of tool names this skill is allowed to use during execution. */
+    allowed_tools?: string[];
+    /** Whether this skill can be directly invoked by users (via slash commands). */
+    user_invocable?: boolean;
+}
+/**
+ * Defines a skill that coordinates multiple tools and operations.
+ *
+ * Skills are higher-level workflows that can be invoked directly
+ * by users (via slash commands) or recommended by the sequential
+ * thinking process.
+ *
+ * @example
+ * ```typescript
+ * const skill: Skill = {
+ *   name: 'commit',
+ *   description: 'Create a git commit with proper message formatting',
+ *   user_invocable: true,
+ *   allowed_tools: ['Bash', 'Read', 'Grep']
+ * };
+ * ```
+ */
+export interface Skill {
+    /** Unique identifier for the skill. */
+    name: string;
+    /** Human-readable description of what the skill does. */
+    description: string;
+    /** Whether users can invoke this skill directly via slash commands. */
+    user_invocable?: boolean;
+    /** List of tool names this skill is allowed to use. */
+    allowed_tools?: string[];
+}
+//# sourceMappingURL=skill.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../../src/types/skill.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,mBAAmB;IACnC,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IAEnB,+FAA+F;IAC/F,UAAU,EAAE,MAAM,CAAC;IAEnB,0FAA0F;IAC1F,SAAS,EAAE,MAAM,CAAC;IAElB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IAEjB,4FAA4F;IAC5F,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB,gFAAgF;IAChF,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,KAAK;IACrB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IAEb,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IAEpB,uEAAuE;IACvE,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB"}

package/dist/types/skill.js

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

package/dist/types/tool.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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']
+ * };
+ * ```
+ *
+ * NOTE: Kept as a hand-written interface (not inferred from `ToolRecommendationSchema`)
+ * because `priority` is REQUIRED here but OPTIONAL in the schema (the schema accepts
+ * partial input from LLMs; the normalizer fills the default). An inferred type would
+ * make `priority` optional and break call sites that read it without a guard.
+ */
+/**
+ * JSON Schema definition object. Self-documenting alias over `Record<string, unknown>`
+ * used for tool `inputSchema` parameters.
+ */
+export type JsonSchema = Record<string, unknown>;
+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, string | number | boolean | null>;
+    /** 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: JsonSchema;
+}
+//# 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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,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,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;IAEpE,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,UAAU,CAAC;CACxB"}

package/dist/types/tool.js

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

package/dist/utils.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared utility helpers.
+ *
+ * @module utils
+ */
+/**
+ * Asserts that a value is `never`. Use in switch default cases to enforce
+ * exhaustiveness over discriminated unions. TypeScript will error at compile
+ * time if any variant of the union is unhandled.
+ *
+ * @param value - The value that should be statically `never`.
+ * @param message - Optional error message override.
+ * @returns Never returns; always throws.
+ *
+ * @example
+ * ```ts
+ * function handle(t: ThoughtType): string {
+ *   switch (t) {
+ *     case 'regular': return 'r';
+ *     // ... all other cases ...
+ *     default: assertNever(t);
+ *   }
+ * }
+ * ```
+ */
+export declare function assertNever(value: never, message?: string): never;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAEjE"}

package/dist/utils.js

@@ -0,0 +1,6 @@
+function assertNever(value, message) {
+    throw new Error(message ?? `Unexpected value: ${String(value)}`);
+}
+export { assertNever };
+
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sources":["../src/utils.ts"],"sourcesContent":["/**\n * Shared utility helpers.\n *\n * @module utils\n */\n\n/**\n * Asserts that a value is `never`. Use in switch default cases to enforce\n * exhaustiveness over discriminated unions. TypeScript will error at compile\n * time if any variant of the union is unhandled.\n *\n * @param value - The value that should be statically `never`.\n * @param message - Optional error message override.\n * @returns Never returns; always throws.\n *\n * @example\n * ```ts\n * function handle(t: ThoughtType): string {\n *   switch (t) {\n *     case 'regular': return 'r';\n *     // ... all other cases ...\n *     default: assertNever(t);\n *   }\n * }\n * ```\n */\nexport function assertNever(value: never, message?: string): never {\n\tthrow new Error(message ?? `Unexpected value: ${String(value)}`);\n}\n"],"names":["assertNever","value","message","Error","String"],"mappings":"AA0BO,SAASA,YAAYC,KAAY,EAAEC,OAAgB;IACzD,MAAM,IAAIC,MAAMD,WAAW,CAAC,kBAAkB,EAAEE,OAAOH,QAAQ;AAChE"}

package/dist/watchers/SkillWatcher.d.ts

@@ -0,0 +1,25 @@
+import type { Logger } from '../logger/StructuredLogger.js';
+import type { SkillRegistry } from '../registry/SkillRegistry.js';
+/** Watches skill discovery directories and serializes registry refreshes. */
+export declare class SkillWatcher {
+    private readonly _skillRegistry;
+    private _watcher;
+    private readonly _logger;
+    private readonly _readyPromise;
+    private _pendingRefresh;
+    private _refreshQueued;
+    private _stopped;
+    private _stopPromise;
+    constructor(_skillRegistry: SkillRegistry, logger?: Logger, watchDirs?: readonly string[]);
+    private _createNoopLogger;
+    private _setupWatcher;
+    private _handleEvent;
+    private _scheduleRefresh;
+    private _drainRefreshes;
+    private _log;
+    /** Resolves when Chokidar has completed its initial scan. */
+    ready(): Promise<void>;
+    /** Closes Chokidar and joins any refresh accepted before shutdown. */
+    stop(): Promise<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":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElE,6EAA6E;AAC7E,qBAAa,YAAY;IAUvB,OAAO,CAAC,QAAQ,CAAC,cAAc;IAThC,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,eAAe,CAA8B;IACrD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAA8B;gBAGhC,cAAc,EAAE,aAAa,EAC9C,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,GAAE,SAAS,MAAM,EAA0D;IAMrF,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,gBAAgB;YAUV,eAAe;IAc7B,OAAO,CAAC,IAAI;IAIZ,6DAA6D;IACtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7B,sEAAsE;IAC/D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAS5B"}

package/dist/watchers/SkillWatcher.js

@@ -0,0 +1,96 @@
+import { watch } from "chokidar";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getErrorMessage } from "../errors.js";
+class SkillWatcher {
+    _skillRegistry;
+    _watcher = null;
+    _logger;
+    _readyPromise;
+    _pendingRefresh = null;
+    _refreshQueued = false;
+    _stopped = false;
+    _stopPromise = null;
+    constructor(_skillRegistry, logger, watchDirs = [
+        '.claude/skills',
+        join(homedir(), '.claude/skills')
+    ]){
+        this._skillRegistry = _skillRegistry;
+        this._logger = logger ?? this._createNoopLogger();
+        this._readyPromise = this._setupWatcher(watchDirs);
+    }
+    _createNoopLogger() {
+        return {
+            info: ()=>{},
+            warn: ()=>{},
+            error: ()=>{},
+            debug: ()=>{},
+            setLevel: ()=>{},
+            getLevel: ()=>'info'
+        };
+    }
+    _setupWatcher(watchDirs) {
+        if (0 === watchDirs.length) return Promise.resolve();
+        const watcher = watch([
+            ...watchDirs
+        ], {
+            ignored: [
+                /node_modules/,
+                /\.DS_Store$/
+            ],
+            persistent: true,
+            ignoreInitial: true
+        });
+        this._watcher = watcher;
+        watcher.on('add', (path)=>this._handleEvent('added', path));
+        watcher.on('change', (path)=>this._handleEvent('modified', path));
+        watcher.on('unlink', (path)=>this._handleEvent('removed', path));
+        return new Promise((resolve)=>watcher.on('ready', ()=>resolve()));
+    }
+    _handleEvent(action, path) {
+        if (this._stopped) return Promise.resolve();
+        if (!path.includes('.DS_Store')) this._log(`Skill ${action}: ${path.split(/[/\\]/).pop()}`);
+        return this._scheduleRefresh(path);
+    }
+    _scheduleRefresh(path) {
+        this._refreshQueued = true;
+        if (!this._pendingRefresh) this._pendingRefresh = this._drainRefreshes(path).finally(()=>{
+            this._pendingRefresh = null;
+        });
+        return this._pendingRefresh;
+    }
+    async _drainRefreshes(path) {
+        while(this._refreshQueued){
+            this._refreshQueued = false;
+            try {
+                await this._skillRegistry.refreshAsync();
+            } catch (error) {
+                this._logger.error('Skill discovery refresh failed', {
+                    path,
+                    error: getErrorMessage(error)
+                });
+            }
+        }
+    }
+    _log(message) {
+        if ('true' === process.env.WATCHER_VERBOSE) this._logger.debug(`[Watcher] ${message}`);
+    }
+    ready() {
+        return this._readyPromise;
+    }
+    stop() {
+        if (this._stopPromise) return this._stopPromise;
+        this._stopped = true;
+        const watcher = this._watcher;
+        const pendingRefresh = this._pendingRefresh;
+        this._watcher = null;
+        this._stopPromise = Promise.all([
+            watcher?.close(),
+            pendingRefresh
+        ]).then(()=>void 0);
+        return this._stopPromise;
+    }
+}
+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":["import { watch, type FSWatcher } from 'chokidar';\nimport { homedir } from 'node:os';\nimport { join } from 'node:path';\nimport { getErrorMessage } from '../errors.js';\nimport type { Logger } from '../logger/StructuredLogger.js';\nimport type { SkillRegistry } from '../registry/SkillRegistry.js';\n\n/** Watches skill discovery directories and serializes registry refreshes. */\nexport class SkillWatcher {\n\tprivate _watcher: FSWatcher | null = null;\n\tprivate readonly _logger: Logger;\n\tprivate readonly _readyPromise: Promise<void>;\n\tprivate _pendingRefresh: Promise<void> | null = null;\n\tprivate _refreshQueued = false;\n\tprivate _stopped = false;\n\tprivate _stopPromise: Promise<void> | null = null;\n\n\tconstructor(\n\t\tprivate readonly _skillRegistry: SkillRegistry,\n\t\tlogger?: Logger,\n\t\twatchDirs: readonly string[] = ['.claude/skills', join(homedir(), '.claude/skills')]\n\t) {\n\t\tthis._logger = logger ?? this._createNoopLogger();\n\t\tthis._readyPromise = this._setupWatcher(watchDirs);\n\t}\n\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\tprivate _setupWatcher(watchDirs: readonly string[]): Promise<void> {\n\t\tif (watchDirs.length === 0) return Promise.resolve();\n\t\tconst watcher = watch([...watchDirs], {\n\t\t\tignored: [/node_modules/, /\\.DS_Store$/],\n\t\t\tpersistent: true,\n\t\t\tignoreInitial: true,\n\t\t});\n\t\tthis._watcher = watcher;\n\t\twatcher.on('add', (path) => this._handleEvent('added', path));\n\t\twatcher.on('change', (path) => this._handleEvent('modified', path));\n\t\twatcher.on('unlink', (path) => this._handleEvent('removed', path));\n\t\treturn new Promise((resolve) => watcher.on('ready', () => resolve()));\n\t}\n\n\tprivate _handleEvent(action: string, path: string): Promise<void> {\n\t\tif (this._stopped) return Promise.resolve();\n\t\tif (!path.includes('.DS_Store')) this._log(`Skill ${action}: ${path.split(/[/\\\\]/).pop()}`);\n\t\treturn this._scheduleRefresh(path);\n\t}\n\n\tprivate _scheduleRefresh(path: string): Promise<void> {\n\t\tthis._refreshQueued = true;\n\t\tif (!this._pendingRefresh) {\n\t\t\tthis._pendingRefresh = this._drainRefreshes(path).finally(() => {\n\t\t\t\tthis._pendingRefresh = null;\n\t\t\t});\n\t\t}\n\t\treturn this._pendingRefresh;\n\t}\n\n\tprivate async _drainRefreshes(path: string): Promise<void> {\n\t\twhile (this._refreshQueued) {\n\t\t\tthis._refreshQueued = false;\n\t\t\ttry {\n\t\t\t\tawait this._skillRegistry.refreshAsync();\n\t\t\t} catch (error) {\n\t\t\t\tthis._logger.error('Skill discovery refresh failed', {\n\t\t\t\t\tpath,\n\t\t\t\t\terror: getErrorMessage(error),\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate _log(message: string): void {\n\t\tif (process.env.WATCHER_VERBOSE === 'true') this._logger.debug(`[Watcher] ${message}`);\n\t}\n\n\t/** Resolves when Chokidar has completed its initial scan. */\n\tpublic ready(): Promise<void> {\n\t\treturn this._readyPromise;\n\t}\n\n\t/** Closes Chokidar and joins any refresh accepted before shutdown. */\n\tpublic stop(): Promise<void> {\n\t\tif (this._stopPromise) return this._stopPromise;\n\t\tthis._stopped = true;\n\t\tconst watcher = this._watcher;\n\t\tconst pendingRefresh = this._pendingRefresh;\n\t\tthis._watcher = null;\n\t\tthis._stopPromise = Promise.all([watcher?.close(), pendingRefresh]).then(() => undefined);\n\t\treturn this._stopPromise;\n\t}\n}\n"],"names":["SkillWatcher","_skillRegistry","logger","watchDirs","join","homedir","Promise","watcher","watch","path","resolve","action","error","getErrorMessage","message","process","pendingRefresh","undefined"],"mappings":"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"}

package/dist/watchers/ToolWatcher.d.ts

@@ -0,0 +1,24 @@
+import type { Logger } from '../logger/StructuredLogger.js';
+import type { ToolRegistry } from '../registry/ToolRegistry.js';
+/** Watches tool discovery directories and serializes registry refreshes. */
+export declare class ToolWatcher {
+    private readonly _toolRegistry;
+    private _watcher;
+    private readonly _logger;
+    private readonly _readyPromise;
+    private _pendingRefresh;
+    private _refreshQueued;
+    private _stopped;
+    private _stopPromise;
+    constructor(_toolRegistry: ToolRegistry, logger?: Logger, watchDirs?: readonly string[]);
+    private _createNoopLogger;
+    private _setupWatcher;
+    private _handleEvent;
+    private _scheduleRefresh;
+    private _drainRefreshes;
+    /** Resolves when Chokidar has completed its initial scan. */
+    ready(): Promise<void>;
+    /** Closes Chokidar and joins any refresh accepted before shutdown. */
+    stop(): Promise<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":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEhE,4EAA4E;AAC5E,qBAAa,WAAW;IAUtB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAT/B,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,eAAe,CAA8B;IACrD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAA8B;gBAGhC,aAAa,EAAE,YAAY,EAC5C,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,GAAE,SAAS,MAAM,EAAwD;IAMnF,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,gBAAgB;YAUV,eAAe;IAc7B,6DAA6D;IACtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7B,sEAAsE;IAC/D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAS5B"}

package/dist/watchers/ToolWatcher.js

@@ -0,0 +1,92 @@
+import { watch } from "chokidar";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getErrorMessage } from "../errors.js";
+class ToolWatcher {
+    _toolRegistry;
+    _watcher = null;
+    _logger;
+    _readyPromise;
+    _pendingRefresh = null;
+    _refreshQueued = false;
+    _stopped = false;
+    _stopPromise = null;
+    constructor(_toolRegistry, logger, watchDirs = [
+        '.claude/tools',
+        join(homedir(), '.claude/tools')
+    ]){
+        this._toolRegistry = _toolRegistry;
+        this._logger = logger ?? this._createNoopLogger();
+        this._readyPromise = this._setupWatcher(watchDirs);
+    }
+    _createNoopLogger() {
+        return {
+            info: ()=>{},
+            warn: ()=>{},
+            error: ()=>{},
+            debug: ()=>{},
+            setLevel: ()=>{},
+            getLevel: ()=>'info'
+        };
+    }
+    _setupWatcher(watchDirs) {
+        if (0 === watchDirs.length) return Promise.resolve();
+        const watcher = watch([
+            ...watchDirs
+        ], {
+            ignored: [
+                /node_modules/,
+                /\.DS_Store$/
+            ],
+            persistent: true,
+            ignoreInitial: true
+        });
+        this._watcher = watcher;
+        watcher.on('add', (path)=>this._handleEvent(path));
+        watcher.on('change', (path)=>this._handleEvent(path));
+        watcher.on('unlink', (path)=>this._handleEvent(path));
+        return new Promise((resolve)=>watcher.on('ready', ()=>resolve()));
+    }
+    _handleEvent(path) {
+        if (this._stopped || !path.endsWith('.tool.md')) return Promise.resolve();
+        return this._scheduleRefresh(path);
+    }
+    _scheduleRefresh(path) {
+        this._refreshQueued = true;
+        if (!this._pendingRefresh) this._pendingRefresh = this._drainRefreshes(path).finally(()=>{
+            this._pendingRefresh = null;
+        });
+        return this._pendingRefresh;
+    }
+    async _drainRefreshes(path) {
+        while(this._refreshQueued){
+            this._refreshQueued = false;
+            try {
+                await this._toolRegistry.refreshAsync();
+            } catch (error) {
+                this._logger.error('Tool discovery refresh failed', {
+                    path,
+                    error: getErrorMessage(error)
+                });
+            }
+        }
+    }
+    ready() {
+        return this._readyPromise;
+    }
+    stop() {
+        if (this._stopPromise) return this._stopPromise;
+        this._stopped = true;
+        const watcher = this._watcher;
+        const pendingRefresh = this._pendingRefresh;
+        this._watcher = null;
+        this._stopPromise = Promise.all([
+            watcher?.close(),
+            pendingRefresh
+        ]).then(()=>void 0);
+        return this._stopPromise;
+    }
+}
+export { ToolWatcher };
+
+//# sourceMappingURL=ToolWatcher.js.map