Add configurable file read limits to SDK tools

[tombee]

Summary

Implements configurable line-based read limits for the SDK file tool (SPEC-4). This enables LLMs to request bounded file reads that prevent context window exhaustion when only a portion of a file is needed.

Changes

• New Parameters: Added optional max_lines and offset parameters to file read operations
• Memory Efficiency: Implemented streaming line-based reading using bufio.Scanner to avoid loading entire files into memory
• Truncation Metadata: Added structured JSON metadata to read responses indicating truncation status, total lines, and line ranges
• Backward Compatibility: Maintains existing behavior when no parameters are specified (unlimited reads)
• Comprehensive Testing: Added 6 new test functions covering all scenarios including edge cases

Technical Details

Helper Functions

• getIntParam(): Validates and extracts integer parameters with type checking
• readWithLimits(): Memory-efficient bounded line reading using buffered scanner
• countFileLines(): Efficiently counts total lines for truncation metadata
• buildTruncationMetadata(): Constructs structured truncation information

Metadata Structure

{
  "truncated": true,
  "lines_shown": 500,
  "total_lines": 10000,
  "start_line": 0,
  "end_line": 499,
  "more_content": true
}

Test Coverage

• Line-limited reads with various max_lines values
• Offset-based reads skipping initial lines
• Combined max_lines and offset parameters
• Parameter validation (negative values, type errors)
• Backward compatibility (unlimited reads)
• Empty file handling with limits

All existing tests continue to pass, confirming backward compatibility.

Closes

• Fixes Add configurable file read limits to SDK tools #1
• Implements SPEC-4