converse-mcp-server 2.8.5 → 2.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "converse-mcp-server",
-  "version": "2.8.5",
+  "version": "2.9.1",
   "description": "Converse MCP Server - Converse with other LLMs with chat and consensus tools",
   "type": "module",
   "main": "src/index.js",

package/src/providers/anthropic.js

@@ -624,7 +624,11 @@ export const anthropicProvider = {
     }
 
     // Add effort parameter for Opus 4.5 (uses output_config)
-    if (modelConfig.supportsEffort && reasoning_effort && reasoning_effort !== 'none') {
+    if (
+      modelConfig.supportsEffort &&
+      reasoning_effort &&
+      reasoning_effort !== 'none'
+    ) {
       const effortValue = EFFORT_MAP[reasoning_effort];
       if (effortValue) {
         requestPayload.output_config = {
@@ -852,7 +856,8 @@ export const anthropicProvider = {
       const streamingPayload = { ...requestPayload, stream: true };
 
       // Create the streaming request - use beta endpoint when beta features are enabled
-      const hasBetaFeatures = requestPayload.betas && requestPayload.betas.length > 0;
+      const hasBetaFeatures =
+        requestPayload.betas && requestPayload.betas.length > 0;
       const stream = hasBetaFeatures
         ? await anthropic.beta.messages.create(streamingPayload)
         : await anthropic.messages.create(streamingPayload);

package/src/providers/claude.js

@@ -28,8 +28,7 @@ const SUPPORTED_MODELS = {
     supportsTemperature: false, // SDK manages temperature internally
     supportsWebSearch: false, // SDK accesses files directly, not web
     timeout: 120000, // 2 minutes
-    description:
-			'Claude via Agent SDK - requires claude login authentication',
+    description: 'Claude via Agent SDK - requires claude login authentication',
     aliases: ['claude-sdk', 'claude-code'],
   },
 };
@@ -320,10 +319,10 @@ async function* createStreamingGenerator(
                 input_tokens: message.usage.input_tokens || 0,
                 output_tokens: message.usage.output_tokens || 0,
                 total_tokens:
-										(message.usage.input_tokens || 0) +
-										(message.usage.output_tokens || 0),
+                    (message.usage.input_tokens || 0) +
+                    (message.usage.output_tokens || 0),
                 cached_input_tokens:
-										message.usage.cache_read_input_tokens || 0,
+                    message.usage.cache_read_input_tokens || 0,
               },
             };
           }
@@ -336,7 +335,7 @@ async function* createStreamingGenerator(
           };
         } else if (
           message.subtype === 'error_max_turns' ||
-						message.subtype === 'error_during_execution'
+            message.subtype === 'error_during_execution'
         ) {
           throw new ClaudeProviderError(
             `Claude SDK execution failed: ${message.subtype}`,
@@ -359,11 +358,11 @@ async function* createStreamingGenerator(
  */
 export const claudeProvider = {
   /**
-	 * Invoke Claude SDK with messages and options
-	 * @param {Array} messages - Message array (Converse format)
-	 * @param {Object} options - Invocation options
-	 * @returns {Promise<Object>|AsyncGenerator} Response or stream generator
-	 */
+   * Invoke Claude SDK with messages and options
+   * @param {Array} messages - Message array (Converse format)
+   * @param {Object} options - Invocation options
+   * @returns {Promise<Object>|AsyncGenerator} Response or stream generator
+   */
   async invoke(messages, options = {}) {
     const {
       model = 'claude',
@@ -408,7 +407,8 @@ export const claudeProvider = {
       // Returns { prompt, sdkMessage, hasImages }
       // - prompt: string for single message mode (text-only)
       // - sdkMessage: SDK user message for streaming input mode (with images)
-      const { prompt, sdkMessage, hasImages } = convertMessagesToSdkInput(messages);
+      const { prompt, sdkMessage, hasImages } =
+        convertMessagesToSdkInput(messages);
 
       if (hasImages) {
         debugLog('[Claude SDK] Using streaming input mode for image support');
@@ -465,7 +465,7 @@ export const claudeProvider = {
               input_tokens: usage.input_tokens || 0,
               output_tokens: usage.output_tokens || 0,
               total_tokens:
-									(usage.input_tokens || 0) + (usage.output_tokens || 0),
+                  (usage.input_tokens || 0) + (usage.output_tokens || 0),
               cached_input_tokens: usage.cached_input_tokens || 0,
             }
             : null,
@@ -479,8 +479,8 @@ export const claudeProvider = {
       // Map common errors to standard error codes
       if (
         error.message?.includes('authentication') ||
-				error.message?.includes('login') ||
-				error.message?.includes('not authenticated')
+        error.message?.includes('login') ||
+        error.message?.includes('not authenticated')
       ) {
         throw new ClaudeProviderError(
           'Claude SDK authentication failed. Run: claude login',
@@ -519,10 +519,10 @@ export const claudeProvider = {
   },
 
   /**
-	 * Validate Claude SDK configuration
-	 * Claude SDK uses CLI authentication (NOT API keys)
-	 * Returns true optimistically - authentication errors handled at runtime
-	 */
+   * Validate Claude SDK configuration
+   * Claude SDK uses CLI authentication (NOT API keys)
+   * Returns true optimistically - authentication errors handled at runtime
+   */
   validateConfig(_config) {
     // Claude SDK uses CLI authentication, not API keys
     // We can't reliably check auth status, so return true optimistically
@@ -531,22 +531,22 @@ export const claudeProvider = {
   },
 
   /**
-	 * Check if Claude SDK provider is available
-	 */
+   * Check if Claude SDK provider is available
+   */
   isAvailable(config) {
     return this.validateConfig(config);
   },
 
   /**
-	 * Get supported Claude SDK models
-	 */
+   * Get supported Claude SDK models
+   */
   getSupportedModels() {
     return SUPPORTED_MODELS;
   },
 
   /**
-	 * Get model configuration for specific model
-	 */
+   * Get model configuration for specific model
+   */
   getModelConfig(modelName) {
     const modelNameLower = modelName.toLowerCase();
 
@@ -559,7 +559,7 @@ export const claudeProvider = {
     for (const [_name, config] of Object.entries(SUPPORTED_MODELS)) {
       if (
         config.aliases &&
-				config.aliases.some((alias) => alias.toLowerCase() === modelNameLower)
+        config.aliases.some((alias) => alias.toLowerCase() === modelNameLower)
       ) {
         return config;
       }

package/src/providers/gemini-cli.js

@@ -36,7 +36,7 @@ const SUPPORTED_MODELS = {
     supportsWebSearch: true,
     timeout: 300000, // 5 minutes
     description:
-			'Gemini 3.0 Pro Preview via OAuth - requires Gemini CLI authentication',
+      'Gemini 3.0 Pro Preview via OAuth - requires Gemini CLI authentication',
     aliases: ['gemini-cli'],
     // Internal SDK model name (user-facing "gemini" maps to SDK's "gemini-3-pro-preview")
     sdkModelName: 'gemini-3-pro-preview',
@@ -272,11 +272,11 @@ function convertToModelMessages(messages) {
  */
 export const geminiCliProvider = {
   /**
-	 * Invoke Gemini CLI with messages and options
-	 * @param {Array} messages - Message array (Converse format)
-	 * @param {Object} options - Invocation options
-	 * @returns {Promise<Object>|AsyncGenerator} Response or stream generator
-	 */
+   * Invoke Gemini CLI with messages and options
+   * @param {Array} messages - Message array (Converse format)
+   * @param {Object} options - Invocation options
+   * @returns {Promise<Object>|AsyncGenerator} Response or stream generator
+   */
   async invoke(messages, options = {}) {
     const {
       model = 'gemini',
@@ -405,8 +405,8 @@ export const geminiCliProvider = {
       // Map common errors to standard error codes
       if (
         error.message?.includes('authentication') ||
-				error.message?.includes('oauth') ||
-				error.message?.includes('credentials')
+        error.message?.includes('oauth') ||
+        error.message?.includes('credentials')
       ) {
         throw new GeminiCliProviderError(
           'Gemini CLI authentication failed. Run: gemini (interactive CLI) to authenticate',
@@ -441,31 +441,31 @@ export const geminiCliProvider = {
   },
 
   /**
-	 * Validate Gemini CLI configuration
-	 * Gemini CLI uses OAuth authentication (no API keys needed)
-	 */
+   * Validate Gemini CLI configuration
+   * Gemini CLI uses OAuth authentication (no API keys needed)
+   */
   validateConfig(_config) {
     // Check if OAuth credentials file exists
     return hasOAuthCredentials();
   },
 
   /**
-	 * Check if Gemini CLI provider is available
-	 */
+   * Check if Gemini CLI provider is available
+   */
   isAvailable(config) {
     return this.validateConfig(config);
   },
 
   /**
-	 * Get supported Gemini CLI models
-	 */
+   * Get supported Gemini CLI models
+   */
   getSupportedModels() {
     return SUPPORTED_MODELS;
   },
 
   /**
-	 * Get model configuration for specific model
-	 */
+   * Get model configuration for specific model
+   */
   getModelConfig(modelName) {
     const modelNameLower = modelName.toLowerCase();
 

package/src/providers/google.js

@@ -119,11 +119,7 @@ const SUPPORTED_MODELS = {
     timeout: 300000,
     description:
       'Deep reasoning + thinking mode (1M context) - Complex problems, architecture, deep analysis',
-    aliases: [
-      'pro 2.5',
-      'gemini pro 2.5',
-      'gemini-2.5-pro-latest',
-    ],
+    aliases: ['pro 2.5', 'gemini pro 2.5', 'gemini-2.5-pro-latest'],
   },
   'gemini-3-pro-preview': {
     modelName: 'gemini-3-pro-preview',

package/src/tools/chat.js

@@ -375,23 +375,26 @@ export async function chatTool(args, dependencies) {
 
     // Export conversation if requested
     if (shouldExport) {
-      await exportConversation({
-        messages: updatedMessages,
-        provider: providerName,
-        model,
-        lastUpdated: Date.now(),
-        codexThreadId: response.metadata?.threadId,
-      }, {
-        clientCwd: config.server?.client_cwd,
-        continuation_id: continuationId,
-        model,
-        temperature,
-        reasoning_effort,
-        verbosity,
-        use_websearch,
-        files,
-        images,
-      });
+      await exportConversation(
+        {
+          messages: updatedMessages,
+          provider: providerName,
+          model,
+          lastUpdated: Date.now(),
+          codexThreadId: response.metadata?.threadId,
+        },
+        {
+          clientCwd: config.server?.client_cwd,
+          continuation_id: continuationId,
+          model,
+          temperature,
+          reasoning_effort,
+          verbosity,
+          use_websearch,
+          files,
+          images,
+        },
+      );
     }
 
     // Create unified status line (similar to async status display)
@@ -495,7 +498,11 @@ export function mapModelToProvider(model, providers) {
   }
 
   // Check Claude SDK (exact match only - routes to SDK provider instead of Anthropic API)
-  if (modelLower === 'claude' || modelLower === 'claude-sdk' || modelLower === 'claude-code') {
+  if (
+    modelLower === 'claude' ||
+    modelLower === 'claude-sdk' ||
+    modelLower === 'claude-code'
+  ) {
     return 'claude';
   }
 
@@ -963,23 +970,26 @@ async function executeChatWithStreaming(args, dependencies, context) {
 
   // Export conversation if requested
   if (shouldExport) {
-    await exportConversation({
-      messages: updatedMessages,
-      provider: providerName,
-      model,
-      lastUpdated: Date.now(),
-      codexThreadId: response.metadata?.threadId,
-    }, {
-      clientCwd: config.server?.client_cwd,
-      continuation_id: continuationId,
-      model,
-      temperature,
-      reasoning_effort,
-      verbosity,
-      use_websearch,
-      files,
-      images,
-    });
+    await exportConversation(
+      {
+        messages: updatedMessages,
+        provider: providerName,
+        model,
+        lastUpdated: Date.now(),
+        codexThreadId: response.metadata?.threadId,
+      },
+      {
+        clientCwd: config.server?.client_cwd,
+        continuation_id: continuationId,
+        model,
+        temperature,
+        reasoning_effort,
+        verbosity,
+        use_websearch,
+        files,
+        images,
+      },
+    );
   }
 
   // Return complete result for job completion
@@ -1019,7 +1029,7 @@ chatTool.inputSchema = {
       type: 'array',
       items: { type: 'string' },
       description:
-        'File paths to include as context (absolute or relative paths). Example: ["C:\\Users\\username\\project\\src\\auth.js", "./config.json"]',
+        'File paths to include as context (absolute or relative paths). Supports line ranges: file.txt{10:50}, file.txt{100:}. Example: ["./src/utils/auth.js{50:100}", "./config.json"]',
     },
     images: {
       type: 'array',

package/src/tools/consensus.js

@@ -542,7 +542,9 @@ Please provide your refined response:`;
       // Add summary at the end
       formattedContent += `\n**Summary:** Consensus completed with ${initialPhase.successful.length} successful initial responses`;
       if (refinedPhase) {
-        const successfulRefinements = refinedPhase.filter(r => r.status === 'success').length;
+        const successfulRefinements = refinedPhase.filter(
+          (r) => r.status === 'success',
+        ).length;
         formattedContent += ` and ${successfulRefinements} successful refined responses`;
       }
       formattedContent += '.';
@@ -752,7 +754,11 @@ function mapModelToProvider(model, providers) {
   }
 
   // Check Claude SDK (exact match only - routes to SDK provider instead of Anthropic API)
-  if (modelLower === 'claude' || modelLower === 'claude-sdk' || modelLower === 'claude-code') {
+  if (
+    modelLower === 'claude' ||
+    modelLower === 'claude-sdk' ||
+    modelLower === 'claude-code'
+  ) {
     return 'claude';
   }
 
@@ -1251,7 +1257,9 @@ Please provide your refined response:`;
     // Add summary at the end
     formattedContent += `\n**Summary:** Consensus completed with ${initialPhase.successful.length} successful initial responses`;
     if (refinedPhase) {
-      const successfulRefinements = refinedPhase.filter(r => r.status === 'success').length;
+      const successfulRefinements = refinedPhase.filter(
+        (r) => r.status === 'success',
+      ).length;
       formattedContent += ` and ${successfulRefinements} successful refined responses`;
     }
     formattedContent += '.';
@@ -1623,7 +1631,7 @@ consensusTool.inputSchema = {
       type: 'array',
       items: { type: 'string' },
       description:
-        'File paths for additional context (absolute or relative paths). Example: ["C:\\Users\\username\\project\\architecture.md", "./requirements.txt"]',
+        'File paths for additional context (absolute or relative paths). Supports line ranges: file.txt{10:50}, file.txt{100:}. Example: ["./docs/architecture.md{1:100}", "./requirements.txt"]',
     },
     images: {
       type: 'array',

package/src/utils/contextProcessor.js

@@ -11,6 +11,11 @@ import { extname, resolve, isAbsolute } from 'path';
 import { constants } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
+import {
+  parseFilePathWithRange,
+  extractLineRange,
+  validateRange,
+} from './pathParser.js';
 
 // Security: Define allowed directories for file access
 const __filename = fileURLToPath(import.meta.url);
@@ -103,8 +108,6 @@ async function validateFilePath(filePath, options = {}) {
  * @param {string} filePath - Absolute or relative path to the file
  * @param {object} options - Processing options
  * @param {string[]} options.allowedDirectories - Allowed directories for security
- * @param {number} options.maxTextSize - Maximum text file size in bytes
- * @param {number} options.maxImageSize - Maximum image file size in bytes
  * @param {boolean} options.skipSecurityCheck - Skip security validation (for testing)
  * @returns {Promise<object>} Processed content with metadata
  */
@@ -137,8 +140,21 @@ export async function processFileContent(filePath, options = {}) {
       };
     }
 
-    // Security validation for file paths
-    const validatedPath = await validateFilePath(filePath, options);
+    // Parse line range specifier from file path (e.g., "file.txt{10:50}")
+    const { filePath: actualPath, range } = parseFilePathWithRange(filePath);
+
+    // Validate range early (before expensive file operations)
+    const rangeValidation = validateRange(range);
+    if (!rangeValidation.valid) {
+      throw new ContextProcessorError(
+        rangeValidation.error,
+        rangeValidation.code,
+        { path: filePath },
+      );
+    }
+
+    // Security validation for file paths (without range specifier)
+    const validatedPath = await validateFilePath(actualPath, options);
 
     const fileStats = await stat(validatedPath);
     const extension = extname(validatedPath).toLowerCase();
@@ -162,18 +178,9 @@ export async function processFileContent(filePath, options = {}) {
       encoding: null,
     };
 
-    // Check file size limits
-    const maxTextSize = options.maxTextSize || 1024 * 1024; // 1MB default
-    const maxImageSize = options.maxImageSize || 10 * 1024 * 1024; // 10MB default
-
     if (SUPPORTED_IMAGE_EXTENSIONS.includes(extension)) {
       result.type = 'image';
 
-      if (fileStats.size > maxImageSize) {
-        result.error = `Image too large (${fileStats.size} bytes, max ${maxImageSize})`;
-        return result;
-      }
-
       // For images, read as base64 for AI processing
       const buffer = await readFile(validatedPath);
       result.content = buffer.toString('base64');
@@ -183,16 +190,24 @@ export async function processFileContent(filePath, options = {}) {
       // Read everything else as text
       result.type = 'text';
 
-      if (fileStats.size > maxTextSize) {
-        result.error = `File too large (${fileStats.size} bytes, max ${maxTextSize})`;
-        return result;
+      const rawContent = await readFile(validatedPath, 'utf8');
+      const allLines = rawContent.split(/\r?\n/);
+      result.totalLineCount = allLines.length;
+
+      // Apply line range extraction if specified
+      if (range) {
+        const extraction = extractLineRange(allLines, range);
+        result.content = extraction.lines.join('\n');
+        result.lineCount = extraction.lines.length;
+        result.rangeStart = extraction.actualStart;
+        result.rangeEnd = extraction.actualEnd;
+      } else {
+        result.content = rawContent;
+        result.lineCount = allLines.length;
       }
 
-      const content = await readFile(validatedPath, 'utf8');
-      result.content = content;
-      result.lineCount = content.split(/\r?\n/).length;
       result.encoding = 'utf8';
-      result.charCount = content.length;
+      result.charCount = result.content.length;
     }
 
     return result;
@@ -350,7 +365,12 @@ export function createFileContext(processedFiles, options = {}) {
   if (textFiles.length > 0) {
     contextText += '=== FILE CONTEXT ===\n\n';
     for (const file of textFiles) {
-      contextText += `--- ${file.originalPath || file.path} ---\n`;
+      // Show range info if this is a partial file extraction
+      let header = file.originalPath || file.path;
+      if (file.rangeStart !== undefined && file.totalLineCount !== undefined) {
+        header += ` (lines ${file.rangeStart}-${file.rangeEnd} of ${file.totalLineCount})`;
+      }
+      contextText += `--- ${header} ---\n`;
       if (options.includeMetadata) {
         contextText += `Size: ${file.size} bytes, Lines: ${file.lineCount || 'N/A'}\n`;
         contextText += `Last Modified: ${file.lastModified || 'N/A'}\n`;

package/src/utils/conversationExporter.js

@@ -150,7 +150,9 @@ function generateMetadata(conversationState, totalTurns, params) {
     created_at: conversationState.createdAt
       ? new Date(conversationState.createdAt).toISOString()
       : new Date().toISOString(),
-    last_updated: new Date(conversationState.lastUpdated || Date.now()).toISOString(),
+    last_updated: new Date(
+      conversationState.lastUpdated || Date.now(),
+    ).toISOString(),
   };
 
   // Add optional parameters if present
@@ -168,8 +170,8 @@ function generateMetadata(conversationState, totalTurns, params) {
   }
   if (params.images && params.images.length > 0) {
     // Don't store base64 data, just file paths or indicators
-    metadata.images = params.images.map(img =>
-      img.startsWith('data:') ? '[base64 image]' : img
+    metadata.images = params.images.map((img) =>
+      img.startsWith('data:') ? '[base64 image]' : img,
     );
   }
   // Consensus-specific metadata

package/src/utils/fileValidator.js

@@ -8,6 +8,7 @@
 import { access, constants } from 'fs/promises';
 import { resolve, isAbsolute } from 'path';
 import { createToolError } from '../tools/index.js';
+import { parseFilePathWithRange } from './pathParser.js';
 
 /**
  * Validate that all provided file paths exist
@@ -38,11 +39,15 @@ export async function validateFilePaths(
       continue;
     }
 
+    // Parse and strip line range specifier before validation
+    // e.g., "file.txt{5:10}" -> "file.txt"
+    const { filePath: actualPath } = parseFilePathWithRange(filePath);
+
     // Convert to absolute path if needed
     // Use clientCwd if provided (for auto-detected client working directory), otherwise fall back to process.cwd()
-    const absolutePath = isAbsolute(filePath)
-      ? filePath
-      : resolve(options.clientCwd || process.cwd(), filePath);
+    const absolutePath = isAbsolute(actualPath)
+      ? actualPath
+      : resolve(options.clientCwd || process.cwd(), actualPath);
 
     try {
       // Check if file exists and is readable

package/src/utils/pathParser.js

@@ -0,0 +1,173 @@
+/**
+ * Path Parser Utility
+ *
+ * Parses file paths with optional line range specifiers.
+ * Syntax: path/to/file{start:end} where start and end are 1-based line numbers.
+ *
+ * Examples:
+ * - file.txt{10:50} - Lines 10-50 inclusive
+ * - file.txt{:20}   - Lines 1-20
+ * - file.txt{100:}  - Lines 100 to end
+ * - file.txt        - Entire file (no range)
+ */
+
+/**
+ * Regex to match line range specifier at end of path.
+ * Captures: (filePath)(startLine)(endLine)
+ * Pattern: ^(.*)\{(\d*):(\d*)\}$
+ */
+const RANGE_PATTERN = /^(.*)\{(\d*):(\d*)\}$/;
+
+/**
+ * Parse a file path that may contain a line range specifier.
+ *
+ * @param {string} filePath - File path potentially with range specifier
+ * @returns {{filePath: string, range: {start: number|null, end: number|null, isEmpty: boolean}|null}}
+ *
+ * @example
+ * parseFilePathWithRange('file.txt{10:50}')
+ * // => { filePath: 'file.txt', range: { start: 10, end: 50, isEmpty: false } }
+ *
+ * @example
+ * parseFilePathWithRange('file.txt{:20}')
+ * // => { filePath: 'file.txt', range: { start: null, end: 20, isEmpty: false } }
+ *
+ * @example
+ * parseFilePathWithRange('file.txt')
+ * // => { filePath: 'file.txt', range: null }
+ */
+export function parseFilePathWithRange(filePath) {
+  if (!filePath || typeof filePath !== 'string') {
+    return { filePath, range: null };
+  }
+
+  const match = filePath.match(RANGE_PATTERN);
+
+  if (!match) {
+    // No range specifier found, return original path
+    return { filePath, range: null };
+  }
+
+  const [, extractedPath, startStr, endStr] = match;
+
+  // Check for empty range {:}
+  if (startStr === '' && endStr === '') {
+    return {
+      filePath: extractedPath,
+      range: { start: null, end: null, isEmpty: true },
+    };
+  }
+
+  // Parse start line (treat 0 as 1)
+  let start = null;
+  if (startStr !== '') {
+    start = parseInt(startStr, 10);
+    if (start === 0) {
+      start = 1;
+    }
+  }
+
+  // Parse end line
+  let end = null;
+  if (endStr !== '') {
+    end = parseInt(endStr, 10);
+  }
+
+  return {
+    filePath: extractedPath,
+    range: { start, end, isEmpty: false },
+  };
+}
+
+/**
+ * Extract a range of lines from an array of lines.
+ * Both start and end are 1-indexed and inclusive.
+ *
+ * @param {string[]} lines - Array of lines
+ * @param {{start: number|null, end: number|null, isEmpty: boolean}} range - Range specification
+ * @returns {{lines: string[], actualStart: number, actualEnd: number}}
+ *
+ * @example
+ * extractLineRange(['a', 'b', 'c', 'd', 'e'], { start: 2, end: 4, isEmpty: false })
+ * // => { lines: ['b', 'c', 'd'], actualStart: 2, actualEnd: 4 }
+ */
+export function extractLineRange(lines, range) {
+  if (!range || !Array.isArray(lines)) {
+    return {
+      lines: lines || [],
+      actualStart: 1,
+      actualEnd: lines ? lines.length : 0,
+    };
+  }
+
+  const totalLines = lines.length;
+
+  // Determine start index (1-indexed to 0-indexed conversion)
+  // Default to 1 if not specified
+  let startLine = range.start !== null ? range.start : 1;
+
+  // Clamp start to valid range (at least 1)
+  if (startLine < 1) {
+    startLine = 1;
+  }
+
+  // Determine end index (inclusive)
+  // Default to total lines if not specified
+  let endLine = range.end !== null ? range.end : totalLines;
+
+  // Clamp end to actual file bounds
+  if (endLine > totalLines) {
+    endLine = totalLines;
+  }
+
+  // Handle case where start > total lines (return empty)
+  if (startLine > totalLines) {
+    return {
+      lines: [],
+      actualStart: startLine,
+      actualEnd: endLine,
+    };
+  }
+
+  // Convert to 0-indexed for slice
+  // slice(start, end) is exclusive of end, so we use endLine (not endLine - 1)
+  const extractedLines = lines.slice(startLine - 1, endLine);
+
+  return {
+    lines: extractedLines,
+    actualStart: startLine,
+    actualEnd: Math.min(endLine, totalLines),
+  };
+}
+
+/**
+ * Validate a line range.
+ *
+ * @param {{start: number|null, end: number|null, isEmpty: boolean}} range - Range to validate
+ * @returns {{valid: boolean, error: string|null, code: string|null}}
+ */
+export function validateRange(range) {
+  if (!range) {
+    return { valid: true, error: null, code: null };
+  }
+
+  // Empty range {:} is invalid
+  if (range.isEmpty) {
+    return {
+      valid: false,
+      error: 'Empty range specifier {:} is not allowed',
+      code: 'EMPTY_RANGE',
+    };
+  }
+
+  // Check if start > end (when both are specified)
+  if (range.start !== null && range.end !== null && range.start > range.end) {
+    return {
+      valid: false,
+      error: `Invalid range: start (${range.start}) is greater than end (${range.end})`,
+      code: 'INVALID_RANGE',
+    };
+  }
+
+  return { valid: true, error: null, code: null };
+}