deepthinking-mcp 2.5.2 → 2.5.4

package/dist/index.js

@@ -991,8 +991,218 @@ var ModeRecommender = class {
   }
 };
 
-// src/session/manager.ts
+// src/utils/errors.ts
+var DeepThinkingError = class extends Error {
+  code;
+  context;
+  timestamp;
+  constructor(message, code, context) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.context = context;
+    this.timestamp = /* @__PURE__ */ new Date();
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  /**
+   * Convert error to JSON for logging/serialization
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      context: this.context,
+      timestamp: this.timestamp.toISOString(),
+      stack: this.stack
+    };
+  }
+};
+var SessionError = class extends DeepThinkingError {
+  constructor(message, context) {
+    super(message, "SESSION_ERROR", context);
+  }
+};
+var SessionNotFoundError = class extends SessionError {
+  constructor(sessionId) {
+    super(`Session not found: ${sessionId}`, { sessionId });
+    this.code = "SESSION_NOT_FOUND";
+  }
+};
+
+// src/utils/sanitization.ts
+var MAX_LENGTHS = {
+  THOUGHT_CONTENT: 1e5,
+  // 100KB for thought content
+  TITLE: 500,
+  DOMAIN: 200,
+  AUTHOR: 300,
+  STRING_FIELD: 1e3
+};
+function sanitizeString(input, maxLength = MAX_LENGTHS.STRING_FIELD, fieldName = "input") {
+  if (typeof input !== "string") {
+    throw new Error(`${fieldName} must be a string`);
+  }
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    throw new Error(`${fieldName} cannot be empty`);
+  }
+  if (trimmed.length > maxLength) {
+    throw new Error(`${fieldName} exceeds maximum length of ${maxLength} characters`);
+  }
+  if (trimmed.includes("\0")) {
+    throw new Error(`${fieldName} contains invalid null bytes`);
+  }
+  return trimmed;
+}
+function validateSessionId(sessionId) {
+  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  if (!uuidRegex.test(sessionId)) {
+    throw new Error(`Invalid session ID format: ${sessionId}`);
+  }
+  return sessionId;
+}
+function sanitizeThoughtContent(content) {
+  return sanitizeString(content, MAX_LENGTHS.THOUGHT_CONTENT, "thought content");
+}
+
+// src/utils/logger.ts
+var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
+  LogLevel2[LogLevel2["DEBUG"] = 0] = "DEBUG";
+  LogLevel2[LogLevel2["INFO"] = 1] = "INFO";
+  LogLevel2[LogLevel2["WARN"] = 2] = "WARN";
+  LogLevel2[LogLevel2["ERROR"] = 3] = "ERROR";
+  LogLevel2[LogLevel2["SILENT"] = 4] = "SILENT";
+  return LogLevel2;
+})(LogLevel || {});
 var DEFAULT_CONFIG = {
+  minLevel: 1 /* INFO */,
+  enableConsole: true,
+  enableTimestamps: true,
+  prettyPrint: true
+};
+var Logger = class {
+  config;
+  logs = [];
+  constructor(config) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+  /**
+   * Log a debug message
+   */
+  debug(message, context) {
+    this.log(0 /* DEBUG */, message, context);
+  }
+  /**
+   * Log an info message
+   */
+  info(message, context) {
+    this.log(1 /* INFO */, message, context);
+  }
+  /**
+   * Log a warning message
+   */
+  warn(message, context) {
+    this.log(2 /* WARN */, message, context);
+  }
+  /**
+   * Log an error message
+   */
+  error(message, error, context) {
+    this.log(3 /* ERROR */, message, context, error);
+  }
+  /**
+   * Internal log method
+   */
+  log(level, message, context, error) {
+    if (level < this.config.minLevel) {
+      return;
+    }
+    const entry = {
+      level,
+      message,
+      timestamp: /* @__PURE__ */ new Date(),
+      context,
+      error
+    };
+    this.logs.push(entry);
+    if (this.config.enableConsole) {
+      this.writeToConsole(entry);
+    }
+  }
+  /**
+   * Write log entry to console
+   */
+  writeToConsole(entry) {
+    const levelName = LogLevel[entry.level];
+    const timestamp = this.config.enableTimestamps ? `[${entry.timestamp.toISOString()}] ` : "";
+    let message = `${timestamp}${levelName}: ${entry.message}`;
+    if (entry.context && this.config.prettyPrint) {
+      message += `
+  Context: ${JSON.stringify(entry.context, null, 2)}`;
+    }
+    if (entry.error) {
+      message += `
+  Error: ${entry.error.message}`;
+      if (entry.error.stack && this.config.prettyPrint) {
+        message += `
+  Stack: ${entry.error.stack}`;
+      }
+    }
+    switch (entry.level) {
+      case 0 /* DEBUG */:
+      case 1 /* INFO */:
+        console.log(message);
+        break;
+      case 2 /* WARN */:
+        console.warn(message);
+        break;
+      case 3 /* ERROR */:
+        console.error(message);
+        break;
+    }
+  }
+  /**
+   * Get all log entries
+   */
+  getLogs(minLevel) {
+    if (minLevel !== void 0) {
+      return this.logs.filter((log) => log.level >= minLevel);
+    }
+    return [...this.logs];
+  }
+  /**
+   * Clear all logs
+   */
+  clearLogs() {
+    this.logs = [];
+  }
+  /**
+   * Set minimum log level
+   */
+  setLevel(level) {
+    this.config.minLevel = level;
+  }
+  /**
+   * Export logs as JSON
+   */
+  exportLogs() {
+    return JSON.stringify(this.logs.map((log) => ({
+      ...log,
+      level: LogLevel[log.level],
+      timestamp: log.timestamp.toISOString()
+    })), null, 2);
+  }
+};
+new Logger();
+function createLogger(config) {
+  return new Logger(config);
+}
+
+// src/session/manager.ts
+var DEFAULT_CONFIG2 = {
   modeConfig: {
     mode: "hybrid" /* HYBRID */,
     strictValidation: false,
@@ -1010,48 +1220,139 @@ var DEFAULT_CONFIG = {
 var SessionManager = class {
   activeSessions;
   config;
-  constructor(config) {
+  logger;
+  /**
+   * Creates a new SessionManager instance
+   *
+   * @param config - Optional default configuration applied to all new sessions
+   * @param logLevel - Optional minimum log level (default: INFO)
+   *
+   * @example
+   * ```typescript
+   * const manager = new SessionManager({
+   *   enableAutoSave: true,
+   *   maxThoughtsInMemory: 500
+   * }, LogLevel.DEBUG);
+   * ```
+   */
+  constructor(config, logLevel) {
     this.activeSessions = /* @__PURE__ */ new Map();
     this.config = config || {};
+    this.logger = createLogger({
+      minLevel: logLevel || 1 /* INFO */,
+      enableConsole: true
+    });
   }
   /**
    * Create a new thinking session
+   *
+   * Creates and initializes a new thinking session with the specified configuration.
+   * Sessions are stored in memory and tracked until explicitly deleted.
+   *
+   * @param options - Session creation options
+   * @param options.title - Session title (default: 'Untitled Session')
+   * @param options.mode - Thinking mode to use (default: HYBRID)
+   * @param options.domain - Problem domain (e.g., 'mathematics', 'physics')
+   * @param options.author - Session creator/author
+   * @param options.config - Session-specific configuration overrides
+   * @returns Promise resolving to the created session
+   *
+   * @example
+   * ```typescript
+   * const session = await manager.createSession({
+   *   title: 'Mathematical Proof',
+   *   mode: ThinkingMode.MATHEMATICS,
+   *   domain: 'number-theory',
+   *   author: 'user@example.com'
+   * });
+   * ```
    */
   async createSession(options = {}) {
+    const title = options.title ? sanitizeString(options.title, MAX_LENGTHS.TITLE, "title") : "Untitled Session";
+    const domain = options.domain ? sanitizeString(options.domain, MAX_LENGTHS.DOMAIN, "domain") : void 0;
+    const author = options.author ? sanitizeString(options.author, MAX_LENGTHS.AUTHOR, "author") : void 0;
     const sessionId = randomUUID();
     const now = /* @__PURE__ */ new Date();
     const session = {
       id: sessionId,
-      title: options.title || "Untitled Session",
+      title,
       mode: options.mode || "hybrid" /* HYBRID */,
-      domain: options.domain,
+      domain,
       config: this.mergeConfig(options.config),
       thoughts: [],
       createdAt: now,
       updatedAt: now,
-      author: options.author,
+      author,
       currentThoughtNumber: 0,
       isComplete: false,
       metrics: this.initializeMetrics(),
       tags: [],
-      collaborators: options.author ? [options.author] : []
+      collaborators: author ? [author] : []
     };
     this.activeSessions.set(sessionId, session);
+    this.logger.info("Session created", {
+      sessionId,
+      title,
+      mode: session.mode,
+      domain,
+      author
+    });
     return session;
   }
   /**
    * Get a session by ID
+   *
+   * Retrieves an active session by its unique identifier.
+   *
+   * @param sessionId - Unique UUID v4 identifier of the session
+   * @returns Promise resolving to the session, or null if not found
+   *
+   * @example
+   * ```typescript
+   * const session = await manager.getSession('550e8400-e29b-41d4-a716-446655440000');
+   * if (session) {
+   *   console.log(`Session: ${session.title}`);
+   *   console.log(`Thoughts: ${session.thoughts.length}`);
+   * }
+   * ```
    */
   async getSession(sessionId) {
     return this.activeSessions.get(sessionId) || null;
   }
   /**
    * Add a thought to a session
+   *
+   * Adds a new thought to an existing session and automatically updates:
+   * - Session metrics (uses O(1) incremental calculation)
+   * - Thought timestamps
+   * - Session completion status
+   * - Mode-specific analytics
+   *
+   * @param sessionId - ID of the session to add thought to
+   * @param thought - The thought object to add
+   * @returns Promise resolving to the updated session
+   * @throws Error if session is not found
+   *
+   * @example
+   * ```typescript
+   * await manager.addThought(session.id, {
+   *   thought: 'Initial hypothesis: the problem can be solved using...',
+   *   thoughtNumber: 1,
+   *   totalThoughts: 5,
+   *   nextThoughtNeeded: true,
+   *   uncertainty: 0.3
+   * });
+   * ```
    */
   async addThought(sessionId, thought) {
+    validateSessionId(sessionId);
     const session = this.activeSessions.get(sessionId);
     if (!session) {
-      throw new Error(`Session ${sessionId} not found`);
+      this.logger.error("Session not found", void 0, { sessionId });
+      throw new SessionNotFoundError(sessionId);
+    }
+    if (thought.content) {
+      thought.content = sanitizeThoughtContent(thought.content);
     }
     thought.sessionId = sessionId;
     thought.timestamp = /* @__PURE__ */ new Date();
@@ -1061,25 +1362,74 @@ var SessionManager = class {
     this.updateMetrics(session, thought);
     if (!thought.nextThoughtNeeded) {
       session.isComplete = true;
+      this.logger.info("Session completed", {
+        sessionId,
+        title: session.title,
+        totalThoughts: session.thoughts.length
+      });
     }
+    this.logger.debug("Thought added", {
+      sessionId,
+      thoughtNumber: thought.thoughtNumber,
+      totalThoughts: session.thoughts.length
+    });
     return session;
   }
   /**
-   * Update session mode
+   * Update session mode (switch reasoning approach mid-session)
+   *
+   * Changes the thinking mode of an active session. This is useful when
+   * the problem requires a different reasoning approach.
+   *
+   * @param sessionId - ID of the session to update
+   * @param newMode - New thinking mode to switch to
+   * @param reason - Optional reason for the mode switch
+   * @returns Promise resolving to the updated session
+   * @throws Error if session is not found
+   *
+   * @example
+   * ```typescript
+   * await manager.switchMode(
+   *   session.id,
+   *   ThinkingMode.CAUSAL,
+   *   'Need to analyze cause-effect relationships'
+   * );
+   * ```
    */
   async switchMode(sessionId, newMode, reason) {
+    validateSessionId(sessionId);
     const session = this.activeSessions.get(sessionId);
     if (!session) {
-      throw new Error(`Session ${sessionId} not found`);
+      this.logger.error("Session not found", void 0, { sessionId });
+      throw new SessionNotFoundError(sessionId);
     }
-    session.mode;
+    const oldMode = session.mode;
     session.mode = newMode;
     session.config.modeConfig.mode = newMode;
     session.updatedAt = /* @__PURE__ */ new Date();
+    this.logger.info("Session mode switched", {
+      sessionId,
+      oldMode,
+      newMode,
+      reason
+    });
     return session;
   }
   /**
-   * List all sessions
+   * List all active sessions with metadata
+   *
+   * Returns summary information for all sessions currently managed
+   * by this SessionManager instance.
+   *
+   * @returns Promise resolving to array of session metadata
+   *
+   * @example
+   * ```typescript
+   * const sessions = await manager.listSessions();
+   * sessions.forEach(s => {
+   *   console.log(`${s.title}: ${s.thoughtCount} thoughts (${s.mode})`);
+   * });
+   * ```
    */
   async listSessions() {
     return Array.from(this.activeSessions.values()).map((session) => ({
@@ -1094,17 +1444,59 @@ var SessionManager = class {
   }
   /**
    * Delete a session
+   *
+   * Removes a session from memory. This operation cannot be undone.
+   *
+   * @param sessionId - ID of the session to delete
+   * @returns Promise that resolves when deletion is complete
+   *
+   * @example
+   * ```typescript
+   * await manager.deleteSession('old-session-id');
+   * ```
    */
   async deleteSession(sessionId) {
-    this.activeSessions.delete(sessionId);
+    const session = this.activeSessions.get(sessionId);
+    const deleted = this.activeSessions.delete(sessionId);
+    if (deleted && session) {
+      this.logger.info("Session deleted", {
+        sessionId,
+        title: session.title,
+        thoughtCount: session.thoughts.length
+      });
+    } else {
+      this.logger.warn("Attempted to delete non-existent session", { sessionId });
+    }
   }
   /**
-   * Generate summary of session
+   * Generate a text summary of a session
+   *
+   * Creates a markdown-formatted summary including:
+   * - Session metadata (title, mode, status)
+   * - Total thought count
+   * - Key thoughts (first 100 characters of each)
+   *
+   * @param sessionId - ID of the session to summarize
+   * @returns Promise resolving to markdown-formatted summary
+   * @throws Error if session is not found
+   *
+   * @example
+   * ```typescript
+   * const summary = await manager.generateSummary(session.id);
+   * console.log(summary);
+   * // Output:
+   * // # Mathematical Proof
+   * // Mode: mathematics
+   * // Total Thoughts: 15
+   * // Status: Complete
+   * // ...
+   * ```
    */
   async generateSummary(sessionId) {
+    validateSessionId(sessionId);
     const session = this.activeSessions.get(sessionId);
     if (!session) {
-      throw new Error(`Session ${sessionId} not found`);
+      throw new SessionNotFoundError(sessionId);
     }
     let summary = `# ${session.title}
 
@@ -1126,17 +1518,22 @@ var SessionManager = class {
     return summary;
   }
   /**
-   * Merge configurations
+   * Merge configurations (private helper)
+   *
+   * Combines default config, instance config, and user config
+   * with proper precedence: user > instance > default
    */
   mergeConfig(userConfig) {
     return {
-      ...DEFAULT_CONFIG,
+      ...DEFAULT_CONFIG2,
       ...this.config,
       ...userConfig
     };
   }
   /**
-   * Initialize metrics
+   * Initialize metrics (private helper)
+   *
+   * Creates a fresh SessionMetrics object with zero values
    */
   initializeMetrics() {
     return {
@@ -1150,7 +1547,13 @@ var SessionManager = class {
     };
   }
   /**
-   * Update session metrics
+   * Update session metrics (private helper)
+   *
+   * Incrementally updates metrics using O(1) algorithms for performance.
+   * Handles mode-specific metrics for temporal, game theory, and evidential modes.
+   *
+   * @param session - Session to update
+   * @param thought - Newly added thought
    */
   updateMetrics(session, thought) {
     const metrics = session.metrics;