@iworkforces/tracelattice 2.0.3

package/dist/lib.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.js","sources":["../src/lib.ts"],"sourcesContent":["// Library exports for tracelattice\n// This module contains all public API exports with NO CLI side effects.\n// For the CLI entry point, see cli.ts.\n\nimport { EventEmitter } from 'node:events';\nimport type * as v from 'valibot';\nimport type { ThoughtData } from './core/thought.js';\nimport type { BranchId } from './contracts/ids.js';\nimport type { SequentialThinkingSchema } from './schema.js';\nimport { SEQUENTIAL_THINKING_TOOL } from './schema.js';\nimport type { IDisposable } from './types/disposable.js';\nimport { getErrorMessage } from './errors.js';\nimport { assertNever } from './utils.js';\n\n// New component imports\nimport { DiscoveryCache } from './cache/DiscoveryCache.js';\nimport type { ConfigFileOptions } from './config/ConfigLoader.js';\nimport { ConfigLoader } from './config/ConfigLoader.js';\nimport { HistoryManager } from './core/HistoryManager.js';\nimport { EdgeStore } from './core/graph/EdgeStore.js';\nimport { InMemorySummaryStore } from './core/compression/InMemorySummaryStore.js';\nimport { CompressionService } from './core/compression/CompressionService.js';\nimport { InMemorySuspensionStore } from './core/tools/InMemorySuspensionStore.js';\nimport { ThoughtEvaluator } from './core/ThoughtEvaluator.js';\nimport { Calibrator } from './core/evaluator/Calibrator.js';\nimport { OutcomeRecorder } from './core/reasoning/OutcomeRecorder.js';\nimport { createReasoningStrategy } from './core/reasoning/strategies/StrategyFactory.js';\nimport { ThoughtFormatter } from './core/ThoughtFormatter.js';\nimport { ThoughtProcessor, type CallToolResult } from './core/ThoughtProcessor.js';\nimport { SessionLock } from './core/SessionLock.js';\nimport { SessionLifecycleCoordinator } from './core/SessionLifecycleCoordinator.js';\nimport { Container } from './di/Container.js';\nimport { StructuredLogger } from './logger/StructuredLogger.js';\nimport { Metrics } from './metrics/metrics.impl.js';\nimport type { PersistenceBackend } from './contracts/PersistenceBackend.js';\nimport { createPersistenceBackend } from './persistence/PersistenceFactory.js';\nimport { SkillRegistry } from './registry/SkillRegistry.js';\nimport { ToolRegistry } from './registry/ToolRegistry.js';\nimport { ServerConfig } from './ServerConfig.js';\nimport type { SseTransportOptions } from './transport/SseTransport.js';\nimport { SkillWatcher } from './watchers/SkillWatcher.js';\nimport { ToolWatcher } from './watchers/ToolWatcher.js';\n\nexport interface ServerOptions {\n\tmaxHistorySize?: number;\n\tmaxBranches?: number;\n\tmaxBranchSize?: number;\n\tlogger?: StructuredLogger;\n\tenableWatcher?: boolean;\n\tconfig?: ServerConfig;\n\tfileConfig?: ConfigFileOptions;\n\tcontainer?: Container;\n\t/**\n\t * Enable automatic tool and skill discovery on server startup.\n\t * @default true\n\t */\n\tautoDiscover?: boolean;\n\t/**\n\t * Suppress startup discovery so callers can discover through registry APIs explicitly.\n\t * @default false\n\t */\n\tlazyDiscovery?: boolean;\n\t/**\n\t * Load history from persistence on initialization\n\t * @default true\n\t */\n\tloadFromPersistence?: boolean;\n\t/**\n\t * Transport type to use\n\t * @default 'stdio'\n\t */\n\ttransport?: 'stdio' | 'sse';\n\t/**\n\t * SSE transport options (used when transport: 'sse')\n\t */\n\tsseTransportOptions?: SseTransportOptions;\n}\n\n/**\n * Server error events for event-driven error handling\n */\ninterface ServerEvents {\n\tpersistenceError: { operation: string; error: Error };\n\tdiscoveryError: { directory: string; error: Error };\n\ttransportError: { transport: string; error: Error };\n\tthoughtProcessed: { thoughtNumber: number; duration: number };\n}\n\ntype CleanupOperation = () => void | Promise<void>;\n\nfunction appendCleanupFailure(failures: unknown[], failure: unknown): void {\n\tif (failure instanceof AggregateError) {\n\t\tfailures.push(...failure.errors);\n\t\treturn;\n\t}\n\tfailures.push(failure);\n}\n\nasync function collectCleanupFailures(operations: readonly CleanupOperation[]): Promise<unknown[]> {\n\tconst failures: unknown[] = [];\n\tfor (const operation of operations) {\n\t\ttry {\n\t\t\tawait operation();\n\t\t} catch (error) {\n\t\t\tappendCleanupFailure(failures, error);\n\t\t}\n\t}\n\treturn failures;\n}\n\n/**\n * Public API contract for the tool-aware sequential thinking server.\n *\n * Extends {@link IDisposable} for resource cleanup. Concrete implementations\n * are expected to also extend Node's `EventEmitter` to support the typed\n * `emit`/`on` overloads.\n */\nexport interface IToolAwareSequentialThinkingServer extends IDisposable {\n\t/** Direct access to the history manager. */\n\treadonly history: HistoryManager;\n\n\t/** Direct access to the tool registry. */\n\treadonly tools: ToolRegistry;\n\n\t/** Direct access to the skill registry. */\n\treadonly skills: SkillRegistry;\n\n\t/** Server configuration. */\n\treadonly config: ServerConfig;\n\n\t/**\n\t * Discover skills asynchronously without blocking server startup.\n\t *\n\t * @returns The number of skills discovered\n\t */\n\tdiscoverSkillsAsync(): Promise<number>;\n\n\t/**\n\t * Get all branches from the history manager.\n\t *\n\t * @returns Map of branch IDs to thought arrays\n\t */\n\tgetBranches(): Record<string, ThoughtData[]>;\n\n\t/**\n\t * Process a thought through the configured pipeline.\n\t *\n\t * @param input - Validated thought input matching the schema\n\t * @returns The processing result\n\t */\n\tprocessThought(input: v.InferInput<typeof SequentialThinkingSchema>): Promise<CallToolResult>;\n\n\t/**\n\t * Export the current Prometheus metrics snapshot.\n\t */\n\tgetMetricsSnapshot(): string;\n\n\t/**\n\t * Get the DI container used by this server.\n\t * Useful for testing and advanced customizations.\n\t */\n\tgetContainer(): Container;\n\n\t/**\n\t * Stop the server and clean up watchers, suspension stores, and persistence.\n\t */\n\tstop(): Promise<void>;\n\n\t/**\n\t * Clear all server state (history, tools, skills).\n\t */\n\tclear(): void;\n\n\t/** Awaitably reset one session and all matching auxiliary state. */\n\tresetSession(sessionId: string): Promise<void>;\n\n\t/** Awaitably reset all state from a trusted ownerless context. */\n\tresetAll(): Promise<void>;\n\n\t/**\n\t * Dispose of the server and all container services.\n\t */\n\tdispose(): Promise<void>;\n}\n\nexport class ToolAwareSequentialThinkingServer\n\textends EventEmitter\n\timplements IToolAwareSequentialThinkingServer\n{\n\t/**\n\t * Factory method to create a new server instance with async initialization.\n\t * This is the recommended way to create server instances.\n\t *\n\t * @param options - Server configuration options\n\t * @returns A Promise that resolves to a configured server instance\n\t */\n\tstatic async create(options: ServerOptions = {}): Promise<ToolAwareSequentialThinkingServer> {\n\t\tconst container = await ToolAwareSequentialThinkingServer._createContainerAsyncStatic(options);\n\t\tlet server: ToolAwareSequentialThinkingServer | undefined;\n\t\ttry {\n\t\t\tserver = new ToolAwareSequentialThinkingServer({\n\t\t\t\t...options,\n\t\t\t\tcontainer,\n\t\t\t});\n\t\t\tawait Promise.all([\n\t\t\t\tserver._skillWatcher?.ready() ?? Promise.resolve(),\n\t\t\t\tserver._toolWatcher?.ready() ?? Promise.resolve(),\n\t\t\t]);\n\n\t\t\tif (options.loadFromPersistence !== false) {\n\t\t\t\tawait server.history.loadFromPersistence();\n\t\t\t}\n\n\t\t\tif (options.autoDiscover !== false && options.lazyDiscovery !== true) {\n\t\t\t\tawait Promise.all([server.tools.discoverAsync(), server.discoverSkillsAsync()]);\n\t\t\t}\n\n\t\t\treturn server;\n\t\t} catch (error) {\n\t\t\tconst startedServer = server;\n\t\t\tconst cleanupFailures = await collectCleanupFailures(\n\t\t\t\tstartedServer\n\t\t\t\t\t? [() => startedServer.dispose()]\n\t\t\t\t\t: [\n\t\t\t\t\t\t\t() => {\n\t\t\t\t\t\t\t\tif (container.has('suspensionStore')) {\n\t\t\t\t\t\t\t\t\tcontainer.resolve('suspensionStore').stop();\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t() => container.resolve('Persistence')?.close(),\n\t\t\t\t\t\t\t() => container.dispose(),\n\t\t\t\t\t\t]\n\t\t\t);\n\t\t\tif (cleanupFailures.length > 0) {\n\t\t\t\tthrow new AggregateError(\n\t\t\t\t\t[error, ...cleanupFailures],\n\t\t\t\t\t'Server startup failed and cleanup also failed',\n\t\t\t\t\t{ cause: error }\n\t\t\t\t);\n\t\t\t}\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\t// Type-safe event emission\n\toverride emit<K extends keyof ServerEvents>(event: K, payload: ServerEvents[K]): boolean {\n\t\treturn super.emit(event, payload);\n\t}\n\n\toverride on<K extends keyof ServerEvents>(\n\t\tevent: K,\n\t\tlistener: (payload: ServerEvents[K]) => void\n\t): this {\n\t\treturn super.on(event, listener);\n\t}\n\n\t// DI Container for managing dependencies\n\tprivate _container: Container;\n\n\t// Component instances (private)\n\tprivate _logger: StructuredLogger;\n\tprivate _historyManager: HistoryManager;\n\tprivate _thoughtProcessor: ThoughtProcessor;\n\tprivate _metrics: Metrics;\n\tprivate _skillWatcher: SkillWatcher | null = null;\n\tprivate _toolWatcher: ToolWatcher | null = null;\n\tprivate _config: ServerConfig;\n\tprivate _stopPromise: Promise<void> | null = null;\n\tprivate _disposePromise: Promise<void> | null = null;\n\n\t// Public manager properties (recommended API)\n\t/**\n\t * Direct access to the history manager\n\t * @example\n\t * ```typescript\n\t * server.history.getHistory();\n\t * server.history.clear();\n\t * ```\n\t */\n\tpublic readonly history: HistoryManager;\n\n\t/**\n\t * Direct access to the tool registry\n\t * @example\n\t * ```typescript\n\t * server.tools.addTool(tool);\n\t * server.tools.getTool('my-tool');\n\t * ```\n\t */\n\tpublic readonly tools: ToolRegistry;\n\n\t/**\n\t * Direct access to the skill registry\n\t * @example\n\t * ```typescript\n\t * server.skills.addSkill(skill);\n\t * server.skills.getSkill('my-skill');\n\t * ```\n\t */\n\tpublic readonly skills: SkillRegistry;\n\n\t/**\n\t * Server configuration\n\t * @example\n\t * ```typescript\n\t * console.log(server.config.maxHistorySize);\n\t * ```\n\t */\n\tpublic readonly config: ServerConfig;\n\n\tconstructor(options: ServerOptions = {}) {\n\t\t// Use provided container or create a new one\n\t\tsuper();\n\t\tif (!options.container) {\n\t\t\tthrow new Error('Container is required. Use createServer() or provide a container.');\n\t\t}\n\t\tthis._container = options.container;\n\n\t\t// Resolve dependencies from container\n\t\tthis._logger = this._container.resolve('Logger');\n\t\tthis._historyManager = this._container.resolve('HistoryManager');\n\t\tthis._historyManager.bindShutdownOwner(() => this.stop());\n\t\tthis._thoughtProcessor = this._container.resolve('ThoughtProcessor');\n\t\tthis._metrics = this._container.resolve('Metrics');\n\t\tthis._config = this._container.resolve('Config');\n\n\t\t// Expose managers as public properties (recommended API)\n\t\tthis.history = this._historyManager;\n\n\t\t// Wire up persistence error event emitter\n\t\tthis._historyManager.setEventEmitter(this);\n\t\tthis.tools = this._container.resolve('ToolRegistry');\n\t\tthis.skills = this._container.resolve('SkillRegistry');\n\t\tthis.config = this._config;\n\n\t\t// Always include the sequential thinking tool\n\t\tthis.tools.addTool(SEQUENTIAL_THINKING_TOOL);\n\n\t\t// Initialize watchers if enabled\n\t\tif (options.enableWatcher) {\n\t\t\tthis._skillWatcher = new SkillWatcher(this.skills, this._logger, this.config.skillDirs);\n\t\t\tthis._toolWatcher = new ToolWatcher(this.tools, this._logger, this.config.toolDirs);\n\t\t}\n\t}\n\n\t/**\n\t * Shared core logic for container creation.\n\t * This method contains all common initialization logic between sync and async paths.\n\t */\n\tprivate static _createContainerCore(\n\t\toptions: ServerOptions,\n\t\tfileConfig: ConfigFileOptions | null,\n\t\tpersistence: PersistenceBackend | null\n\t): Container {\n\t\tconst container = new Container();\n\t\tconst metrics = new Metrics({\n\t\t\tprefix: 'sequentialthinking',\n\t\t});\n\n\t\tconst config = ToolAwareSequentialThinkingServer._resolveEffectiveConfig(options, fileConfig);\n\n\t\t// Initialize logger\n\t\tconst logger =\n\t\t\toptions.logger ??\n\t\t\tnew StructuredLogger({\n\t\t\t\tlevel: fileConfig?.logLevel ?? 'info',\n\t\t\t\tcontext: 'SequentialThinking',\n\t\t\t\tpretty: fileConfig?.prettyLog ?? true,\n\t\t\t});\n\n\t\t// Register all services in the container\n\t\tcontainer.registerInstance('Logger', logger);\n\t\tcontainer.registerInstance('Config', config);\n\t\tcontainer.registerInstance('FileConfig', fileConfig || {});\n\t\tcontainer.registerInstance('Persistence', persistence);\n\t\tcontainer.registerInstance('Metrics', metrics);\n\t\tToolAwareSequentialThinkingServer._registerDiscoveryRegistries(\n\t\t\tcontainer,\n\t\t\toptions.lazyDiscovery\n\t\t);\n\n\t\t// Register EdgeStore as a lazy singleton (always registered; flag gates writes)\n\t\tcontainer.register('EdgeStore', () => new EdgeStore());\n\n\t\t// Register SummaryStore as a lazy singleton (always registered; flag gates writes)\n\t\tcontainer.register('summaryStore', () => new InMemorySummaryStore());\n\n\t\t// Register SuspensionStore as a lazy singleton (only when toolInterleave flag is on)\n\t\tif (config.features.toolInterleave) {\n\t\t\tcontainer.register('suspensionStore', () => {\n\t\t\t\tconst store = new InMemorySuspensionStore({\n\t\t\t\t\tttlMs: config.toolInterleaveTtlMs,\n\t\t\t\t\tsweepIntervalMs: config.toolInterleaveSweepMs,\n\t\t\t\t\tlogger,\n\t\t\t\t});\n\t\t\t\tstore.start();\n\t\t\t\treturn store;\n\t\t\t});\n\t\t}\n\n\t\t// Register CompressionService as a lazy singleton (always registered; flag gates invocation)\n\t\tcontainer.register('compressionService', () => {\n\t\t\tconst historyManager = container.resolve('HistoryManager');\n\t\t\tconst edgeStore = container.resolve('EdgeStore');\n\t\t\tconst summaryStore = container.resolve('summaryStore');\n\t\t\tconst log = container.resolve('Logger');\n\t\t\treturn new CompressionService({\n\t\t\t\thistoryManager,\n\t\t\t\tedgeStore,\n\t\t\t\tsummaryStore,\n\t\t\t\tonSummaryCreated: (summary) => {\n\t\t\t\t\thistoryManager.bufferSummaries(\n\t\t\t\t\t\tsummary.sessionId,\n\t\t\t\t\t\tsummaryStore.forSession(summary.sessionId)\n\t\t\t\t\t);\n\t\t\t\t},\n\t\t\t\tlogger: log,\n\t\t\t});\n\t\t});\n\n\t\t// Register ReasoningStrategy as a lazy singleton (selected via feature flag)\n\t\tcontainer.register('reasoningStrategy', () =>\n\t\t\tcreateReasoningStrategy(config.features.reasoningStrategy)\n\t\t);\n\n\t\t// Register SessionLock as a lazy singleton (always registered;\n\t\t// serializes ThoughtProcessor.process() per-session).\n\t\tcontainer.register('sessionLock', () => new SessionLock());\n\t\tcontainer.register('sessionLifecycle', () => new SessionLifecycleCoordinator());\n\n\t\tToolAwareSequentialThinkingServer._registerHistoryManager(container);\n\t\tToolAwareSequentialThinkingServer._registerThoughtPipeline(container, config);\n\n\t\treturn container;\n\t}\n\n\tprivate static _resolveEffectiveConfig(\n\t\toptions: ServerOptions,\n\t\tfileConfig: ConfigFileOptions | null\n\t): ServerConfig {\n\t\tif (options.config) return options.config;\n\t\tconst loadedOptions = new ConfigLoader().toServerConfigOptions(fileConfig ?? {});\n\t\treturn new ServerConfig({\n\t\t\t...loadedOptions,\n\t\t\tmaxHistorySize: options.maxHistorySize ?? loadedOptions.maxHistorySize,\n\t\t\tmaxBranches: options.maxBranches ?? loadedOptions.maxBranches,\n\t\t\tmaxBranchSize: options.maxBranchSize ?? loadedOptions.maxBranchSize,\n\t\t});\n\t}\n\n\tprivate static _registerDiscoveryRegistries(\n\t\tcontainer: Container,\n\t\tlazyDiscovery: ServerOptions['lazyDiscovery']\n\t): void {\n\t\tconst logger = container.resolve('Logger');\n\t\tconst config = container.resolve('Config');\n\t\tconst metrics = container.resolve('Metrics');\n\n\t\tcontainer.register(\n\t\t\t'ToolRegistry',\n\t\t\t() =>\n\t\t\t\tnew ToolRegistry({\n\t\t\t\t\tlogger,\n\t\t\t\t\tcache: config.discoveryCache\n\t\t\t\t\t\t? new DiscoveryCache({ ...config.discoveryCache, metrics })\n\t\t\t\t\t\t: undefined,\n\t\t\t\t\ttoolDirs: config.toolDirs,\n\t\t\t\t\tlazyDiscovery,\n\t\t\t\t})\n\t\t);\n\t\tcontainer.register(\n\t\t\t'SkillRegistry',\n\t\t\t() =>\n\t\t\t\tnew SkillRegistry({\n\t\t\t\t\tlogger,\n\t\t\t\t\tcache: config.discoveryCache\n\t\t\t\t\t\t? new DiscoveryCache({ ...config.discoveryCache, metrics })\n\t\t\t\t\t\t: undefined,\n\t\t\t\t\tskillDirs: config.skillDirs,\n\t\t\t\t\tlazyDiscovery,\n\t\t\t\t})\n\t\t);\n\t}\n\n\tprivate static _registerHistoryManager(container: Container): void {\n\t\t// Register HistoryManager with lazy initialization\n\t\tcontainer.register('HistoryManager', () => {\n\t\t\tconst cfg = container.resolve('Config');\n\t\t\tconst log = container.resolve('Logger');\n\t\t\tconst pers = container.resolve('Persistence');\n\t\t\tconst componentMetrics = container.resolve('Metrics');\n\t\t\tconst edgeStore = container.resolve('EdgeStore');\n\t\t\tconst summaryStore = container.resolve('summaryStore');\n\t\t\treturn new HistoryManager({\n\t\t\t\tmaxHistorySize: cfg.maxHistorySize,\n\t\t\t\tmaxBranches: cfg.maxBranches,\n\t\t\t\tmaxBranchSize: cfg.maxBranchSize,\n\t\t\t\tlogger: log,\n\t\t\t\tpersistence: pers,\n\t\t\t\tmetrics: componentMetrics,\n\t\t\t\tpersistenceBufferSize: cfg.persistenceBufferSize,\n\t\t\t\tpersistenceFlushInterval: cfg.persistenceFlushInterval,\n\t\t\t\tpersistenceMaxRetries: cfg.persistenceMaxRetries,\n\t\t\t\tedgeStore,\n\t\t\t\tsummaryStore,\n\t\t\t\tdagEdges: cfg.features.dagEdges,\n\t\t\t\tmaxSessionsPerOwner: cfg.maxSessionsPerOwner,\n\t\t\t\tsessionLock: container.resolve('sessionLock'),\n\t\t\t\tlifecycleCoordinator: container.resolve('sessionLifecycle'),\n\t\t\t\tclearSessionAuxiliaryState: (sessionId) =>\n\t\t\t\t\tcontainer.resolve('ThoughtProcessor').clearSessionAuxiliaryState(sessionId),\n\t\t\t\tclearAllAuxiliaryState: () =>\n\t\t\t\t\tcontainer.resolve('ThoughtProcessor').clearAllAuxiliaryState(),\n\t\t\t});\n\t\t});\n\t}\n\n\tprivate static _registerThoughtPipeline(container: Container, config: ServerConfig): void {\n\t\t// Register ThoughtFormatter (can be transient)\n\t\tcontainer.registerFactory('ThoughtFormatter', () => new ThoughtFormatter());\n\n\t\t// Register OutcomeRecorder as a lazy singleton (gated by feature flag)\n\t\tcontainer.register(\n\t\t\t'outcomeRecorder',\n\t\t\t() => new OutcomeRecorder({ enabled: config.features.outcomeRecording ?? false })\n\t\t);\n\n\t\t// Register Calibrator as a lazy singleton (gated by feature flag)\n\t\tcontainer.register(\n\t\t\t'calibrator',\n\t\t\t() =>\n\t\t\t\tnew Calibrator(container.resolve('outcomeRecorder'), config.features.calibration ?? false)\n\t\t);\n\n\t\t// Register ThoughtEvaluator (stateless, transient) with injected calibrator\n\t\tcontainer.registerFactory(\n\t\t\t'ThoughtEvaluator',\n\t\t\t() => new ThoughtEvaluator(container.resolve('calibrator'))\n\t\t);\n\n\t\t// Register ThoughtProcessor\n\t\tcontainer.register('ThoughtProcessor', () => {\n\t\t\tconst history = container.resolve('HistoryManager');\n\t\t\tconst formatter = container.resolve('ThoughtFormatter');\n\t\t\tconst evaluator = container.resolve('ThoughtEvaluator');\n\t\t\tconst log = container.resolve('Logger');\n\t\t\tconst strategy = container.resolve('reasoningStrategy');\n\t\t\tconst compressionService = config.features.compression\n\t\t\t\t? container.resolve('compressionService')\n\t\t\t\t: undefined;\n\t\t\tconst suspensionStore = config.features.toolInterleave\n\t\t\t\t? container.resolve('suspensionStore')\n\t\t\t\t: undefined;\n\t\t\tconst toolRegistry = container.resolve('ToolRegistry');\n\t\t\tconst sessionLock = container.resolve('sessionLock');\n\t\t\treturn new ThoughtProcessor(\n\t\t\t\thistory,\n\t\t\t\tformatter,\n\t\t\t\tevaluator,\n\t\t\t\tlog,\n\t\t\t\tstrategy,\n\t\t\t\tcompressionService,\n\t\t\t\tsuspensionStore,\n\t\t\t\ttoolRegistry,\n\t\t\t\tconfig.features,\n\t\t\t\tsessionLock,\n\t\t\t\tcontainer.resolve('outcomeRecorder'),\n\t\t\t\tcontainer.resolve('sessionLifecycle'),\n\t\t\t\tcontainer.resolve('calibrator')\n\t\t\t);\n\t\t});\n\t}\n\n\t/**\n\t * Create and configure the DI container with async persistence initialization.\n\t * This is used internally by the static create() factory.\n\t */\n\tprivate static async _createContainerAsyncStatic(options: ServerOptions): Promise<Container> {\n\t\tlet fileConfig: ConfigFileOptions | null;\n\t\tlet config: ServerConfig;\n\t\tif (options.config) {\n\t\t\tfileConfig = options.fileConfig ?? null;\n\t\t\tconfig = options.config;\n\t\t} else {\n\t\t\tconst configLoader = new ConfigLoader();\n\t\t\tfileConfig =\n\t\t\t\toptions.fileConfig === undefined\n\t\t\t\t\t? configLoader.load()\n\t\t\t\t\t: configLoader.applyEnvironmentOverrides(options.fileConfig);\n\t\t\tconfig = ToolAwareSequentialThinkingServer._resolveEffectiveConfig(options, fileConfig);\n\t\t}\n\n\t\tlet persistence: PersistenceBackend | null = null;\n\t\ttry {\n\t\t\tpersistence = await createPersistenceBackend(config.persistence);\n\t\t\treturn ToolAwareSequentialThinkingServer._createContainerCore(\n\t\t\t\t{ ...options, config },\n\t\t\t\tfileConfig,\n\t\t\t\tpersistence\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tconst acquiredPersistence = persistence;\n\t\t\tconst cleanupFailures =\n\t\t\t\tacquiredPersistence === null\n\t\t\t\t\t? []\n\t\t\t\t\t: await collectCleanupFailures([() => acquiredPersistence.close()]);\n\t\t\tif (cleanupFailures.length > 0) {\n\t\t\t\tthrow new AggregateError(\n\t\t\t\t\t[error, ...cleanupFailures],\n\t\t\t\t\t'Container construction failed and cleanup also failed',\n\t\t\t\t\t{ cause: error }\n\t\t\t\t);\n\t\t\t}\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\t/**\n\t * Get the DI container used by this server\n\t * Useful for testing and advanced customizations\n\t */\n\tpublic getContainer(): Container {\n\t\treturn this._container;\n\t}\n\n\t/**\n\t * Discover skills asynchronously without blocking server startup.\n\t * This is the recommended method for skill discovery.\n\t * @returns Promise<number> - The number of skills discovered\n\t */\n\tpublic async discoverSkillsAsync(): Promise<number> {\n\t\tconst discovered = await this.skills.discoverAsync();\n\t\treturn discovered;\n\t}\n\n\t/**\n\t * Get all branches from the history manager\n\t * @returns Record<string, ThoughtData[]> - Map of branch IDs to thought arrays\n\t */\n\tpublic getBranches(): Record<BranchId, ThoughtData[]> {\n\t\treturn this._historyManager.getBranches();\n\t}\n\n\t// Main processing method - delegate to ThoughtProcessor\n\tpublic async processThought(input: v.InferInput<typeof SequentialThinkingSchema>) {\n\t\tconst startTime = Date.now();\n\t\tconst result = await this._thoughtProcessor.process(input as ThoughtData);\n\t\tconst durationSeconds = (Date.now() - startTime) / 1000;\n\t\tthis._metrics.histogram('thought_processing_duration_seconds', durationSeconds, {});\n\t\treturn result;\n\t}\n\n\tpublic getMetricsSnapshot(): string {\n\t\treturn this._metrics.export();\n\t}\n\n\t/**\n\t * Stop the server and clean up watchers.\n\t * Closes persistence backend gracefully to ensure data is flushed.\n\t */\n\tpublic stop(): Promise<void> {\n\t\tif (this._stopPromise) return this._stopPromise;\n\t\tthis._stopPromise = this._container.resolve('sessionLifecycle').shutdown(async () => {\n\t\t\tconst failures: unknown[] = [];\n\t\t\tconst watcherResults = await Promise.allSettled([\n\t\t\t\tthis._skillWatcher?.stop() ?? Promise.resolve(),\n\t\t\t\tthis._toolWatcher?.stop() ?? Promise.resolve(),\n\t\t\t]);\n\t\t\tfor (const result of watcherResults) {\n\t\t\t\tswitch (result.status) {\n\t\t\t\t\tcase 'fulfilled':\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase 'rejected':\n\t\t\t\t\t\tappendCleanupFailure(failures, result.reason);\n\t\t\t\t\t\tthis._logger.error('Error stopping watcher', {\n\t\t\t\t\t\t\terror: getErrorMessage(result.reason),\n\t\t\t\t\t\t});\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tdefault:\n\t\t\t\t\t\tassertNever(result);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// Stop suspension store sweeper if registered\n\t\t\tif (this._config.features.toolInterleave && this._container.has('suspensionStore')) {\n\t\t\t\ttry {\n\t\t\t\t\tconst suspensionStore = this._container.resolve('suspensionStore');\n\t\t\t\t\tsuspensionStore.stop();\n\t\t\t\t} catch (error) {\n\t\t\t\t\tappendCleanupFailure(failures, error);\n\t\t\t\t\tthis._logger.error('Error stopping suspension store', {\n\t\t\t\t\t\terror: getErrorMessage(error),\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// Flush any buffered writes before closing persistence\n\t\t\ttry {\n\t\t\t\tawait this._historyManager.shutdownWithinLifecycle();\n\t\t\t} catch (error) {\n\t\t\t\tappendCleanupFailure(failures, error);\n\t\t\t\tthis._logger.error('Error flushing write buffer during shutdown', {\n\t\t\t\t\terror: getErrorMessage(error),\n\t\t\t\t});\n\t\t\t}\n\n\t\t\t// Close persistence backend if available\n\t\t\tconst persistence = this._container.resolve('Persistence');\n\t\t\tif (persistence) {\n\t\t\t\ttry {\n\t\t\t\t\tawait persistence.close();\n\t\t\t\t\tthis._logger.info('Persistence backend closed');\n\t\t\t\t} catch (error) {\n\t\t\t\t\tappendCleanupFailure(failures, error);\n\t\t\t\t\tthis._logger.error('Error closing persistence backend', {\n\t\t\t\t\t\terror: getErrorMessage(error),\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (failures.length > 0) {\n\t\t\t\tthrow new AggregateError(failures, 'Failed to stop server cleanly');\n\t\t\t}\n\t\t\tthis._historyManager.clearLiveStateAfterShutdown();\n\t\t\tthis._logger.info('Server stopped, watchers cleaned up');\n\t\t});\n\t\treturn this._stopPromise;\n\t}\n\n\t/**\n\t * Clear all server state (history, tools, skills)\n\t * Useful for testing to reset state between tests\n\t */\n\tpublic clear(): void {\n\t\tthis._historyManager.clear();\n\t\tthis._logger.info('Server state cleared');\n\t}\n\n\t/** Awaitably resets one session and matching processor-owned state. */\n\tpublic async resetSession(sessionId: string): Promise<void> {\n\t\tawait this._thoughtProcessor.resetSession(sessionId);\n\t\tthis._logger.info('Server session reset', { sessionId });\n\t}\n\n\t/** Awaitably resets all server state from a trusted ownerless context. */\n\tpublic async resetAll(): Promise<void> {\n\t\tawait this._thoughtProcessor.resetAll();\n\t\tthis._logger.info('All server sessions reset');\n\t}\n\n\t/**\n\t * Dispose of the server and all container services.\n\t * Implements the IDisposable interface.\n\t * Calls stop() for existing cleanup, then disposes the DI container.\n\t */\n\tpublic dispose(): Promise<void> {\n\t\tif (this._disposePromise) return this._disposePromise;\n\t\tthis._disposePromise = (async () => {\n\t\t\tconst failures = await collectCleanupFailures([\n\t\t\t\t() => this.stop(),\n\t\t\t\t() => this._container.dispose(),\n\t\t\t]);\n\t\t\tif (failures.length > 0) {\n\t\t\t\tthrow new AggregateError(failures, 'Failed to dispose server cleanly');\n\t\t\t}\n\t\t\tthis._logger.info('Server disposed, all resources released');\n\t\t})();\n\t\treturn this._disposePromise;\n\t}\n}\n\n/**\n * Factory function to create a new server instance with async initialization.\n *\n * This is the recommended way to create server instances, especially for testing,\n * as it allows for proper async initialization, dependency injection, and persistence.\n *\n * @param options - Server configuration options\n * @returns A Promise that resolves to a configured server instance\n *\n * @example\n * ```typescript\n * // Basic usage (with async discovery and persistence)\n * const server = await createServer();\n *\n * // With custom options\n * const server = await createServer({\n *   autoDiscover: false,\n *   lazyDiscovery: true,\n *   maxHistorySize: 500,\n *   loadFromPersistence: true\n * });\n *\n * // With custom container for testing\n * const mockContainer = new Container();\n * mockContainer.registerInstance('Logger', mockLogger);\n * const server = await createServer({ container: mockContainer });\n * ```\n */\nexport async function createServer(\n\toptions: ServerOptions = {}\n): Promise<ToolAwareSequentialThinkingServer> {\n\treturn ToolAwareSequentialThinkingServer.create(options);\n}\n\n// Initialize server\nexport async function initializeServer(): Promise<ToolAwareSequentialThinkingServer> {\n\t// Create logger for initialization\n\tconst configLoader = new ConfigLoader();\n\tconst fileConfig = configLoader.load() ?? {};\n\tconst config = new ServerConfig(configLoader.toServerConfigOptions(fileConfig));\n\n\tconst logger = new StructuredLogger({\n\t\tlevel: fileConfig.logLevel ?? 'info',\n\t\tcontext: 'SequentialThinking',\n\t\tpretty: fileConfig.prettyLog ?? true,\n\t});\n\n\t// Create server instance\n\tconst thinkingServer = await createServer({\n\t\tlogger,\n\t\tenableWatcher: true,\n\t\tconfig,\n\t\tfileConfig,\n\t});\n\n\tlogger.info('Server initialized successfully');\n\treturn thinkingServer;\n}\n"],"names":["appendCleanupFailure","failures","failure","AggregateError","collectCleanupFailures","operations","operation","error","ToolAwareSequentialThinkingServer","EventEmitter","options","container","server","Promise","startedServer","cleanupFailures","event","payload","listener","Error","SEQUENTIAL_THINKING_TOOL","SkillWatcher","ToolWatcher","fileConfig","persistence","Container","metrics","Metrics","config","logger","StructuredLogger","EdgeStore","InMemorySummaryStore","store","InMemorySuspensionStore","historyManager","edgeStore","summaryStore","log","CompressionService","summary","createReasoningStrategy","SessionLock","SessionLifecycleCoordinator","loadedOptions","ConfigLoader","ServerConfig","lazyDiscovery","ToolRegistry","DiscoveryCache","undefined","SkillRegistry","cfg","pers","componentMetrics","HistoryManager","sessionId","ThoughtFormatter","OutcomeRecorder","Calibrator","ThoughtEvaluator","history","formatter","evaluator","strategy","compressionService","suspensionStore","toolRegistry","sessionLock","ThoughtProcessor","configLoader","createPersistenceBackend","acquiredPersistence","discovered","input","startTime","Date","result","durationSeconds","watcherResults","getErrorMessage","assertNever","createServer","initializeServer","thinkingServer"],"mappings":"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"}

package/dist/logger/NullLogger.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Null logger that discards all log messages.
+ *
+ * This logger implements the same interface as `StructuredLogger` but
+ * silently discards all log messages. It's useful as a default/fallback
+ * logger when logging is disabled or when no logger is provided.
+ *
+ * @module logger
+ */
+import type { LogLevel, Logger, LoggerOptions } from './StructuredLogger.js';
+/**
+ * Null logger that discards all log messages.
+ *
+ * This class provides a no-op implementation of the logger interface.
+ * All method calls are silent and have no effect, making it suitable
+ * for use as a default logger when logging is disabled or not needed.
+ *
+ * @remarks
+ * The `NullLogger` implements the same interface as `StructuredLogger`,
+ * making them interchangeable. Use `NullLogger` when:
+ * - You want to disable logging completely
+ * - You need a logger placeholder that can be swapped later
+ * - Testing components that don't need output
+ * - Reducing overhead in performance-critical sections
+ *
+ * @example
+ * ```typescript
+ * import { NullLogger } from './logger/index.js';
+ *
+ * // Create a null logger
+ * const logger = new NullLogger();
+ *
+ * // All log calls are silently discarded
+ * logger.debug('This will not appear');
+ * logger.info('Nor will this');
+ * logger.warn('Or this warning');
+ * logger.error('Or even this error');
+ *
+ * // Methods exist for compatibility but have no effect
+ * logger.setLevel('debug');
+ * const level = logger.getLevel(); // Returns 'error' (default)
+ * ```
+ */
+export declare class NullLogger implements Logger {
+    /**
+     * Current minimum log level.
+     *
+     * @remarks
+     * Since all messages are discarded, the level setting has no practical
+     * effect. This property exists only for interface compatibility.
+     * @private
+     */
+    private _level;
+    /**
+     * Creates a new NullLogger instance.
+     *
+     * @param options - Configuration options (ignored, but accepted for interface compatibility)
+     *
+     * @example
+     * ```typescript
+     * // Create a null logger
+     * const logger1 = new NullLogger();
+     *
+     * // With options (ignored)
+     * const logger2 = new NullLogger({
+     *   level: 'debug',
+     *   context: 'MyApp',
+     *   pretty: true
+     * });
+     * ```
+     */
+    constructor(options?: LoggerOptions);
+    /**
+     * Log a debug message (no-op).
+     *
+     * This method exists for interface compatibility but does nothing.
+     *
+     * @param _message - Ignored
+     * @param _meta - Ignored
+     */
+    debug(_message: string, _meta?: Record<string, unknown>): void;
+    /**
+     * Log an info message (no-op).
+     *
+     * This method exists for interface compatibility but does nothing.
+     *
+     * @param _message - Ignored
+     * @param _meta - Ignored
+     */
+    info(_message: string, _meta?: Record<string, unknown>): void;
+    /**
+     * Log a warning message (no-op).
+     *
+     * This method exists for interface compatibility but does nothing.
+     *
+     * @param _message - Ignored
+     * @param _meta - Ignored
+     */
+    warn(_message: string, _meta?: Record<string, unknown>): void;
+    /**
+     * Log an error message (no-op).
+     *
+     * This method exists for interface compatibility but does nothing.
+     *
+     * @param _message - Ignored
+     * @param _meta - Ignored
+     */
+    error(_message: string, _meta?: Record<string, unknown>): void;
+    /**
+     * Sets the minimum log level (no-op).
+     *
+     * This method exists for interface compatibility but has no effect
+     * since all messages are discarded anyway.
+     *
+     * @param level - The new minimum log level (ignored)
+     *
+     * @example
+     * ```typescript
+     * logger.setLevel('debug');  // No effect
+     * ```
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Gets the current minimum log level.
+     *
+     * @returns The current log level (stored value, unused)
+     *
+     * @example
+     * ```typescript
+     * const currentLevel = logger.getLevel();
+     * console.log(`Current level: ${currentLevel}`); // 'error' by default
+     * ```
+     */
+    getLevel(): LogLevel;
+    /**
+     * Creates a child null logger (returns a new NullLogger).
+     *
+     * This method exists for interface compatibility. It returns a new
+     * `NullLogger` instance (not a child with extended context) since
+     * context tracking is not applicable for a no-op logger.
+     *
+     * @param _context - Additional context (ignored)
+     * @returns A new NullLogger instance
+     *
+     * @example
+     * ```typescript
+     * const nullLogger = new NullLogger();
+     * const childLogger = nullLogger.createChild('ChildModule');
+     * // childLogger is also a NullLogger
+     * ```
+     */
+    createChild(_context: string): NullLogger;
+}
+//# sourceMappingURL=NullLogger.d.ts.map

package/dist/logger/NullLogger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NullLogger.d.ts","sourceRoot":"","sources":["../../src/logger/NullLogger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,UAAW,YAAW,MAAM;IACxC;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAW;IAEzB;;;;;;;;;;;;;;;;;OAiBG;gBACS,OAAO,GAAE,aAAkB;IAIvC;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAE9D;;;;;;;OAOG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAE7D;;;;;;;OAOG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAE7D;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAE9D;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI/B;;;;;;;;;;OAUG;IACH,QAAQ,IAAI,QAAQ;IAIpB;;;;;;;;;;;;;;;;OAgBG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU;CAGzC"}

package/dist/logger/NullLogger.js

@@ -0,0 +1,24 @@
+class NullLogger {
+    _level;
+    constructor(options = {}){
+        this._level = options.level ?? 'error';
+    }
+    debug(_message, _meta) {}
+    info(_message, _meta) {}
+    warn(_message, _meta) {}
+    error(_message, _meta) {}
+    setLevel(level) {
+        this._level = level;
+    }
+    getLevel() {
+        return this._level;
+    }
+    createChild(_context) {
+        return new NullLogger({
+            level: this._level
+        });
+    }
+}
+export { NullLogger };
+
+//# sourceMappingURL=NullLogger.js.map

package/dist/logger/NullLogger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger/NullLogger.js","sources":["../../src/logger/NullLogger.ts"],"sourcesContent":["/**\n * Null logger that discards all log messages.\n *\n * This logger implements the same interface as `StructuredLogger` but\n * silently discards all log messages. It's useful as a default/fallback\n * logger when logging is disabled or when no logger is provided.\n *\n * @module logger\n */\n\nimport type { LogLevel, Logger, LoggerOptions } from './StructuredLogger.js';\n\n/**\n * Null logger that discards all log messages.\n *\n * This class provides a no-op implementation of the logger interface.\n * All method calls are silent and have no effect, making it suitable\n * for use as a default logger when logging is disabled or not needed.\n *\n * @remarks\n * The `NullLogger` implements the same interface as `StructuredLogger`,\n * making them interchangeable. Use `NullLogger` when:\n * - You want to disable logging completely\n * - You need a logger placeholder that can be swapped later\n * - Testing components that don't need output\n * - Reducing overhead in performance-critical sections\n *\n * @example\n * ```typescript\n * import { NullLogger } from './logger/index.js';\n *\n * // Create a null logger\n * const logger = new NullLogger();\n *\n * // All log calls are silently discarded\n * logger.debug('This will not appear');\n * logger.info('Nor will this');\n * logger.warn('Or this warning');\n * logger.error('Or even this error');\n *\n * // Methods exist for compatibility but have no effect\n * logger.setLevel('debug');\n * const level = logger.getLevel(); // Returns 'error' (default)\n * ```\n */\nexport class NullLogger implements Logger {\n\t/**\n\t * Current minimum log level.\n\t *\n\t * @remarks\n\t * Since all messages are discarded, the level setting has no practical\n\t * effect. This property exists only for interface compatibility.\n\t * @private\n\t */\n\tprivate _level: LogLevel;\n\n\t/**\n\t * Creates a new NullLogger instance.\n\t *\n\t * @param options - Configuration options (ignored, but accepted for interface compatibility)\n\t *\n\t * @example\n\t * ```typescript\n\t * // Create a null logger\n\t * const logger1 = new NullLogger();\n\t *\n\t * // With options (ignored)\n\t * const logger2 = new NullLogger({\n\t *   level: 'debug',\n\t *   context: 'MyApp',\n\t *   pretty: true\n\t * });\n\t * ```\n\t */\n\tconstructor(options: LoggerOptions = {}) {\n\t\tthis._level = options.level ?? 'error';\n\t}\n\n\t/**\n\t * Log a debug message (no-op).\n\t *\n\t * This method exists for interface compatibility but does nothing.\n\t *\n\t * @param _message - Ignored\n\t * @param _meta - Ignored\n\t */\n\tdebug(_message: string, _meta?: Record<string, unknown>): void {}\n\n\t/**\n\t * Log an info message (no-op).\n\t *\n\t * This method exists for interface compatibility but does nothing.\n\t *\n\t * @param _message - Ignored\n\t * @param _meta - Ignored\n\t */\n\tinfo(_message: string, _meta?: Record<string, unknown>): void {}\n\n\t/**\n\t * Log a warning message (no-op).\n\t *\n\t * This method exists for interface compatibility but does nothing.\n\t *\n\t * @param _message - Ignored\n\t * @param _meta - Ignored\n\t */\n\twarn(_message: string, _meta?: Record<string, unknown>): void {}\n\n\t/**\n\t * Log an error message (no-op).\n\t *\n\t * This method exists for interface compatibility but does nothing.\n\t *\n\t * @param _message - Ignored\n\t * @param _meta - Ignored\n\t */\n\terror(_message: string, _meta?: Record<string, unknown>): void {}\n\n\t/**\n\t * Sets the minimum log level (no-op).\n\t *\n\t * This method exists for interface compatibility but has no effect\n\t * since all messages are discarded anyway.\n\t *\n\t * @param level - The new minimum log level (ignored)\n\t *\n\t * @example\n\t * ```typescript\n\t * logger.setLevel('debug');  // No effect\n\t * ```\n\t */\n\tsetLevel(level: LogLevel): void {\n\t\tthis._level = level;\n\t}\n\n\t/**\n\t * Gets the current minimum log level.\n\t *\n\t * @returns The current log level (stored value, unused)\n\t *\n\t * @example\n\t * ```typescript\n\t * const currentLevel = logger.getLevel();\n\t * console.log(`Current level: ${currentLevel}`); // 'error' by default\n\t * ```\n\t */\n\tgetLevel(): LogLevel {\n\t\treturn this._level;\n\t}\n\n\t/**\n\t * Creates a child null logger (returns a new NullLogger).\n\t *\n\t * This method exists for interface compatibility. It returns a new\n\t * `NullLogger` instance (not a child with extended context) since\n\t * context tracking is not applicable for a no-op logger.\n\t *\n\t * @param _context - Additional context (ignored)\n\t * @returns A new NullLogger instance\n\t *\n\t * @example\n\t * ```typescript\n\t * const nullLogger = new NullLogger();\n\t * const childLogger = nullLogger.createChild('ChildModule');\n\t * // childLogger is also a NullLogger\n\t * ```\n\t */\n\tcreateChild(_context: string): NullLogger {\n\t\treturn new NullLogger({ level: this._level });\n\t}\n}\n"],"names":["NullLogger","options","_message","_meta","level","_context"],"mappings":"AA6CO,MAAMA;IASJ,OAAiB;IAoBzB,YAAYC,UAAyB,CAAC,CAAC,CAAE;QACxC,IAAI,CAAC,MAAM,GAAGA,QAAQ,KAAK,IAAI;IAChC;IAUA,MAAMC,QAAgB,EAAEC,KAA+B,EAAQ,CAAC;IAUhE,KAAKD,QAAgB,EAAEC,KAA+B,EAAQ,CAAC;IAU/D,KAAKD,QAAgB,EAAEC,KAA+B,EAAQ,CAAC;IAU/D,MAAMD,QAAgB,EAAEC,KAA+B,EAAQ,CAAC;IAehE,SAASC,KAAe,EAAQ;QAC/B,IAAI,CAAC,MAAM,GAAGA;IACf;IAaA,WAAqB;QACpB,OAAO,IAAI,CAAC,MAAM;IACnB;IAmBA,YAAYC,QAAgB,EAAc;QACzC,OAAO,IAAIL,WAAW;YAAE,OAAO,IAAI,CAAC,MAAM;QAAC;IAC5C;AACD"}

package/dist/logger/StructuredLogger.d.ts

@@ -0,0 +1,327 @@
+/**
+ * Lightweight structured logging without external dependencies.
+ *
+ * This module provides a structured logging implementation that writes to stderr
+ * for MCP server compatibility. It supports multiple log levels, pretty printing,
+ * and hierarchical child loggers with inherited context.
+ *
+ * @module logger
+ */
+/**
+ * Log level severity ordering.
+ *
+ * Levels are ordered from least severe (debug) to most severe (error).
+ * Only messages at or above the configured level will be logged.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Common logger interface for all logger implementations.
+ *
+ * This interface defines the contract that all loggers must implement,
+ * allowing them to be used interchangeably throughout the application.
+ */
+export interface Logger {
+    /**
+     * Log a debug message.
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     */
+    debug(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log an info message.
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     */
+    info(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log a warning message.
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     */
+    warn(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log an error message.
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     */
+    error(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Sets the minimum log level.
+     * @param level - The new minimum log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Gets the current minimum log level.
+     * @returns The current log level
+     */
+    getLevel(): LogLevel;
+}
+/**
+ * A single log entry with all relevant metadata.
+ *
+ * @example
+ * ```typescript
+ * const entry: LogEntry = {
+ *   level: 'info',
+ *   message: 'Server started',
+ *   timestamp: '2026-01-18T10:30:00.000Z',
+ *   context: 'SequentialThinking',
+ *   meta: { port: 3000 }
+ * };
+ * ```
+ */
+export interface LogEntry {
+    /** Severity level of the log entry. */
+    readonly level: LogLevel;
+    /** The primary log message. */
+    readonly message: string;
+    /** ISO 8601 timestamp of when the log was created. */
+    readonly timestamp: string;
+    /** Optional context/module name for categorization. */
+    readonly context?: string;
+    /** Optional request correlation ID for tracing. */
+    readonly requestId?: string;
+    /** Additional structured metadata to include with the log. */
+    readonly meta?: Record<string, unknown>;
+}
+/**
+ * Configuration options for creating a `StructuredLogger` instance.
+ *
+ * @example
+ * ```typescript
+ * const options: LoggerOptions = {
+ *   level: 'debug',
+ *   context: 'MyModule',
+ *   pretty: true
+ * };
+ * ```
+ */
+export interface LoggerOptions {
+    /**
+     * Minimum log level to output.
+     * Messages below this level will be suppressed.
+     * @default 'info'
+     */
+    level?: LogLevel;
+    /**
+     * Default context for log messages.
+     * Can be extended with child loggers.
+     * @default 'SequentialThinking'
+     */
+    context?: string;
+    /**
+     * Whether to enable pretty (human-readable) output.
+     * When false, outputs JSON-formatted logs.
+     * @default true
+     */
+    pretty?: boolean;
+}
+/**
+ * Structured logger with level filtering and context support.
+ *
+ * This logger provides structured logging capabilities with configurable
+ * output formats, log levels, and hierarchical context. All output is
+ * written to stderr for compatibility with MCP servers.
+ *
+ * @remarks
+ * **Log Level Priority** (lowest to highest):
+ * - `debug` (0) - Detailed debugging information
+ * - `info` (1) - General informational messages
+ * - `warn` (2) - Warning messages for potential issues
+ * - `error` (3) - Error messages for failures
+ *
+ * Only messages at or above the configured level will be output.
+ *
+ * **Output Formats:**
+ * - Pretty (default): `[timestamp] [LEVEL] [context] message {meta}`
+ * - JSON: `{"level":"info","message":"...","timestamp":"...","context":"...","meta":{...}}`
+ *
+ * @example
+ * ```typescript
+ * // Create a logger
+ * const logger = new StructuredLogger({
+ *   level: 'info',
+ *   context: 'SequentialThinking',
+ *   pretty: true
+ * });
+ *
+ * // Log messages
+ * logger.debug('Detailed debug info', { userId: '123' });
+ * logger.info('Server started', { port: 3000 });
+ * logger.warn('High memory usage', { usage: '85%' });
+ * logger.error('Connection failed', { error: 'ECONNREFUSED' });
+ *
+ * // Create a child logger with extended context
+ * const childLogger = logger.createChild('Database');
+ * childLogger.info('Query executed', { rows: 42 });
+ * // Output: [timestamp] [INFO] [SequentialThinking:Database] Query executed {"rows":42}
+ * ```
+ */
+export declare class StructuredLogger {
+    /** Current minimum log level. */
+    private _level;
+    /** Default context for log messages. */
+    private _context;
+    /** Whether pretty printing is enabled. */
+    private _pretty;
+    /**
+     * Log level priority ordering for filtering.
+     * Higher numbers = higher severity.
+     * @private
+     */
+    private static readonly LEVEL_PRIORITY;
+    /**
+     * Creates a new StructuredLogger instance.
+     *
+     * @param options - Configuration options for the logger
+     *
+     * @example
+     * ```typescript
+     * // Default configuration
+     * const logger1 = new StructuredLogger();
+     *
+     * // Custom configuration
+     * const logger2 = new StructuredLogger({
+     *   level: 'debug',
+     *   context: 'MyApp',
+     *   pretty: false  // JSON output
+     * });
+     * ```
+     */
+    constructor(options?: LoggerOptions);
+    /**
+     * Determines whether a message at the given level should be logged.
+     * @param level - The log level to check
+     * @returns true if the level meets the threshold, false otherwise
+     * @private
+     */
+    private shouldLog;
+    /**
+     * Formats a log entry for output.
+     * @param entry - The log entry to format
+     * @returns Formatted string representation
+     * @private
+     */
+    private format;
+    /**
+     * Internal logging method that handles level filtering and output.
+     * @param level - The log level for this message
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     * @private
+     */
+    private log;
+    /**
+     * Log a debug message.
+     *
+     * Debug messages contain detailed information typically used for
+     * troubleshooting and development. Only output when log level is 'debug'.
+     *
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     *
+     * @example
+     * ```typescript
+     * logger.debug('Processing request', { path: '/api/users', method: 'GET' });
+     * ```
+     */
+    debug(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log an info message.
+     *
+     * Info messages contain general informational messages about normal operation.
+     * Output when log level is 'info' or lower.
+     *
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     *
+     * @example
+     * ```typescript
+     * logger.info('Server started', { port: 3000, env: 'production' });
+     * ```
+     */
+    info(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log a warning message.
+     *
+     * Warning messages indicate potential issues that don't prevent operation
+     * but may require attention. Output when log level is 'warn' or lower.
+     *
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     *
+     * @example
+     * ```typescript
+     * logger.warn('High memory usage detected', { usage: '85%', threshold: '80%' });
+     * ```
+     */
+    warn(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log an error message.
+     *
+     * Error messages indicate failures or error conditions. Always output
+     * regardless of log level setting.
+     *
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     *
+     * @example
+     * ```typescript
+     * logger.error('Database connection failed', { error: err.message, code: err.code });
+     * ```
+     */
+    error(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Creates a child logger with inherited settings and extended context.
+     *
+     * Child loggers inherit the parent's log level and pretty print setting,
+     * but have their context appended to the parent's context for hierarchical logging.
+     *
+     * @param context - Additional context to append to the parent's context
+     * @returns A new logger instance with extended context
+     *
+     * @example
+     * ```typescript
+     * const parentLogger = new StructuredLogger({ context: 'App' });
+     * const dbLogger = parentLogger.createChild('Database');
+     * const queryLogger = dbLogger.createChild('Query');
+     *
+     * parentLogger.info('Starting up');
+     * // Output: [timestamp] [INFO] [App] Starting up
+     *
+     * dbLogger.info('Connected');
+     * // Output: [timestamp] [INFO] [App:Database] Connected
+     *
+     * queryLogger.info('Executed in 5ms');
+     * // Output: [timestamp] [INFO] [App:Database:Query] Executed in 5ms
+     * ```
+     */
+    createChild(context: string): StructuredLogger;
+    /**
+     * Sets the minimum log level.
+     *
+     * Only messages at or above this level will be output.
+     *
+     * @param level - The new minimum log level
+     *
+     * @example
+     * ```typescript
+     * logger.setLevel('debug');  // Enable all logging
+     * logger.setLevel('error');  // Only show errors
+     * ```
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Gets the current minimum log level.
+     *
+     * @returns The current log level
+     *
+     * @example
+     * ```typescript
+     * const currentLevel = logger.getLevel();
+     * console.log(`Current level: ${currentLevel}`);
+     * ```
+     */
+    getLevel(): LogLevel;
+}
+//# sourceMappingURL=StructuredLogger.d.ts.map

package/dist/logger/StructuredLogger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StructuredLogger.d.ts","sourceRoot":"","sources":["../../src/logger/StructuredLogger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACtB;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE7D;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE5D;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE5D;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE7D;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IAEhC;;;OAGG;IACH,QAAQ,IAAI,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,QAAQ;IACxB,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IAEzB,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,uDAAuD;IACvD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC7B;;;;OAIG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC;IAEjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAAa,gBAAgB;IAC5B,iCAAiC;IACjC,OAAO,CAAC,MAAM,CAAW;IAEzB,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAAS;IAEzB,0CAA0C;IAC1C,OAAO,CAAC,OAAO,CAAU;IAEzB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAKpC;IAEF;;;;;;;;;;;;;;;;;OAiBG;gBACS,OAAO,GAAE,aAAkB;IAMvC;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAIjB;;;;;OAKG;IACH,OAAO,CAAC,MAAM;IASd;;;;;;OAMG;IACH,OAAO,CAAC,GAAG;IAoBX;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB;IAQ9C;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI/B;;;;;;;;;;OAUG;IACH,QAAQ,IAAI,QAAQ;CAGpB"}