letta-nightly 0.9.1.dev20250731104458__py3-none-any.whl → 0.10.0.dev20250801060805__py3-none-any.whl

letta/server/rest_api/streaming_response.py

@@ -11,6 +11,7 @@ from starlette.types import Send
 
 from letta.log import get_logger
 from letta.schemas.enums import JobStatus
+from letta.schemas.letta_ping import LettaPing
 from letta.schemas.user import User
 from letta.server.rest_api.utils import capture_sentry_exception
 from letta.services.job_manager import JobManager
@@ -18,6 +19,88 @@ from letta.services.job_manager import JobManager
 logger = get_logger(__name__)
 
 
+class JobCancelledException(Exception):
+    """Exception raised when a job is explicitly cancelled (not due to client timeout)"""
+
+    def __init__(self, job_id: str, message: str = None):
+        self.job_id = job_id
+        super().__init__(message or f"Job {job_id} was explicitly cancelled")
+
+
+async def add_keepalive_to_stream(
+    stream_generator: AsyncIterator[str | bytes],
+    keepalive_interval: float = 30.0,
+) -> AsyncIterator[str | bytes]:
+    """
+    Adds periodic keepalive messages to a stream to prevent connection timeouts.
+
+    Sends a keepalive ping every `keepalive_interval` seconds, regardless of
+    whether data is flowing. This ensures connections stay alive during long
+    operations like tool execution.
+
+    Args:
+        stream_generator: The original stream generator to wrap
+        keepalive_interval: Seconds between keepalive messages (default: 30)
+
+    Yields:
+        Original stream chunks interspersed with keepalive messages
+    """
+    # Use a queue to decouple the stream reading from keepalive timing
+    queue = asyncio.Queue()
+    stream_exhausted = False
+
+    async def stream_reader():
+        """Read from the original stream and put items in the queue."""
+        nonlocal stream_exhausted
+        try:
+            async for item in stream_generator:
+                await queue.put(("data", item))
+        finally:
+            stream_exhausted = True
+            await queue.put(("end", None))
+
+    # Start the stream reader task
+    reader_task = asyncio.create_task(stream_reader())
+
+    try:
+        while True:
+            try:
+                # Wait for data with a timeout equal to keepalive interval
+                msg_type, data = await asyncio.wait_for(queue.get(), timeout=keepalive_interval)
+
+                if msg_type == "end":
+                    # Stream finished
+                    break
+                elif msg_type == "data":
+                    yield data
+
+            except asyncio.TimeoutError:
+                # No data received within keepalive interval
+                if not stream_exhausted:
+                    # Send keepalive ping in the same format as [DONE]
+                    yield f"data: {LettaPing().model_dump_json()}\n\n"
+                else:
+                    # Stream is done but queue might be processing
+                    # Check if there's anything left
+                    try:
+                        msg_type, data = queue.get_nowait()
+                        if msg_type == "end":
+                            break
+                        elif msg_type == "data":
+                            yield data
+                    except asyncio.QueueEmpty:
+                        # Really done now
+                        break
+
+    finally:
+        # Clean up the reader task
+        reader_task.cancel()
+        try:
+            await reader_task
+        except asyncio.CancelledError:
+            pass
+
+
 # TODO (cliandy) wrap this and handle types
 async def cancellation_aware_stream_wrapper(
     stream_generator: AsyncIterator[str | bytes],
@@ -59,8 +142,8 @@ async def cancellation_aware_stream_wrapper(
                         # Send cancellation event to client
                         cancellation_event = {"message_type": "stop_reason", "stop_reason": "cancelled"}
                         yield f"data: {json.dumps(cancellation_event)}\n\n"
-                        # Raise CancelledError to interrupt the stream
-                        raise asyncio.CancelledError(f"Job {job_id} was cancelled")
+                        # Raise custom exception for explicit job cancellation
+                        raise JobCancelledException(job_id, f"Job {job_id} was cancelled")
                 except Exception as e:
                     # Log warning but don't fail the stream if cancellation check fails
                     logger.warning(f"Failed to check job cancellation for job {job_id}: {e}")
@@ -69,9 +152,13 @@ async def cancellation_aware_stream_wrapper(
 
             yield chunk
 
+    except JobCancelledException:
+        # Re-raise JobCancelledException to distinguish from client timeout
+        logger.info(f"Stream for job {job_id} was explicitly cancelled and cleaned up")
+        raise
     except asyncio.CancelledError:
-        # Re-raise CancelledError to ensure proper cleanup
-        logger.info(f"Stream for job {job_id} was cancelled and cleaned up")
+        # Re-raise CancelledError (likely client timeout) to ensure proper cleanup
+        logger.info(f"Stream for job {job_id} was cancelled (likely client timeout) and cleaned up")
         raise
     except Exception as e:
         logger.error(f"Error in cancellation-aware stream wrapper for job {job_id}: {e}")
@@ -140,12 +227,12 @@ class StreamingResponseWithStatusCode(StreamingResponse):
                     }
                 )
 
-        # This should be handled properly upstream?
-        except asyncio.CancelledError as exc:
-            logger.warning("Stream was cancelled by client or job cancellation")
-            # Handle cancellation gracefully
+        # Handle explicit job cancellations (should not throw error)
+        except JobCancelledException as exc:
+            logger.info(f"Stream was explicitly cancelled for job {exc.job_id}")
+            # Handle explicit cancellation gracefully without error
             more_body = False
-            cancellation_resp = {"error": {"message": "Stream cancelled"}}
+            cancellation_resp = {"message": "Job was cancelled"}
             cancellation_event = f"event: cancelled\ndata: {json.dumps(cancellation_resp)}\n\n".encode(self.charset)
             if not self.response_started:
                 await send(
@@ -163,6 +250,31 @@ class StreamingResponseWithStatusCode(StreamingResponse):
                     "more_body": more_body,
                 }
             )
+            return
+
+        # Handle client timeouts (should throw error to inform user)
+        except asyncio.CancelledError as exc:
+            logger.warning("Stream was cancelled due to client timeout or unexpected disconnection")
+            # Handle unexpected cancellation with error
+            more_body = False
+            error_resp = {"error": {"message": "Request was unexpectedly cancelled (likely due to client timeout or disconnection)"}}
+            error_event = f"event: error\ndata: {json.dumps(error_resp)}\n\n".encode(self.charset)
+            if not self.response_started:
+                await send(
+                    {
+                        "type": "http.response.start",
+                        "status": 408,  # Request Timeout
+                        "headers": self.raw_headers,
+                    }
+                )
+                raise
+            await send(
+                {
+                    "type": "http.response.body",
+                    "body": error_event,
+                    "more_body": more_body,
+                }
+            )
             capture_sentry_exception(exc)
             return
 

letta/server/server.py

@@ -40,7 +40,7 @@ from letta.schemas.block import Block, BlockUpdate, CreateBlock
 from letta.schemas.embedding_config import EmbeddingConfig
 
 # openai schemas
-from letta.schemas.enums import JobStatus, MessageStreamStatus, ProviderCategory, ProviderType
+from letta.schemas.enums import JobStatus, MessageStreamStatus, ProviderCategory, ProviderType, SandboxType
 from letta.schemas.environment_variables import SandboxEnvironmentVariableCreate
 from letta.schemas.group import GroupCreate, ManagerType, SleeptimeManager, VoiceSleeptimeManager
 from letta.schemas.job import Job, JobUpdate
@@ -67,9 +67,10 @@ from letta.schemas.providers import (
     OpenAIProvider,
     Provider,
     TogetherProvider,
+    VLLMProvider,
     XAIProvider,
 )
-from letta.schemas.sandbox_config import LocalSandboxConfig, SandboxConfigCreate, SandboxType
+from letta.schemas.sandbox_config import LocalSandboxConfig, SandboxConfigCreate
 from letta.schemas.source import Source
 from letta.schemas.tool import Tool
 from letta.schemas.usage import LettaUsageStatistics
@@ -361,22 +362,17 @@ class SyncServer(Server):
             )
         if model_settings.vllm_api_base:
             # vLLM exposes both a /chat/completions and a /completions endpoint
-            self._enabled_providers.append(
-                VLLMCompletionsProvider(
-                    name="vllm",
-                    base_url=model_settings.vllm_api_base,
-                    default_prompt_formatter=model_settings.default_prompt_formatter,
-                )
-            )
             # NOTE: to use the /chat/completions endpoint, you need to specify extra flags on vLLM startup
             # see: https://docs.vllm.ai/en/stable/features/tool_calling.html
             # e.g. "... --enable-auto-tool-choice --tool-call-parser hermes"
             self._enabled_providers.append(
-                VLLMChatCompletionsProvider(
+                VLLMProvider(
                     name="vllm",
                     base_url=model_settings.vllm_api_base,
+                    default_prompt_formatter=model_settings.default_prompt_formatter,
                 )
             )
+
         if model_settings.aws_access_key_id and model_settings.aws_secret_access_key and model_settings.aws_default_region:
             self._enabled_providers.append(
                 BedrockProvider(

letta/services/agent_manager.py

@@ -86,8 +86,10 @@ from letta.services.helpers.agent_manager_helper import (
     calculate_multi_agent_tools,
     check_supports_structured_output,
     compile_system_message,
+    compile_system_message_async,
     derive_system_message,
     initialize_message_sequence,
+    initialize_message_sequence_async,
     package_initial_message_sequence,
     validate_agent_exists_async,
 )
@@ -621,7 +623,7 @@ class AgentManager:
 
                 # initial message sequence (skip if _init_with_no_messages is True)
                 if not _init_with_no_messages:
-                    init_messages = self._generate_initial_message_sequence(
+                    init_messages = await self._generate_initial_message_sequence_async(
                         actor,
                         agent_state=result,
                         supplied_initial_message_sequence=agent_create.initial_message_sequence,
@@ -666,6 +668,35 @@ class AgentManager:
 
         return init_messages
 
+    @enforce_types
+    async def _generate_initial_message_sequence_async(
+        self, actor: PydanticUser, agent_state: PydanticAgentState, supplied_initial_message_sequence: Optional[List[MessageCreate]] = None
+    ) -> List[Message]:
+        init_messages = await initialize_message_sequence_async(
+            agent_state=agent_state, memory_edit_timestamp=get_utc_time(), include_initial_boot_message=True
+        )
+        if supplied_initial_message_sequence is not None:
+            # We always need the system prompt up front
+            system_message_obj = PydanticMessage.dict_to_message(
+                agent_id=agent_state.id,
+                model=agent_state.llm_config.model,
+                openai_message_dict=init_messages[0],
+            )
+            # Don't use anything else in the pregen sequence, instead use the provided sequence
+            init_messages = [system_message_obj]
+            init_messages.extend(
+                package_initial_message_sequence(
+                    agent_state.id, supplied_initial_message_sequence, agent_state.llm_config.model, agent_state.timezone, actor
+                )
+            )
+        else:
+            init_messages = [
+                PydanticMessage.dict_to_message(agent_id=agent_state.id, model=agent_state.llm_config.model, openai_message_dict=msg)
+                for msg in init_messages
+            ]
+
+        return init_messages
+
     @enforce_types
     @trace_method
     def append_initial_message_sequence_to_in_context_messages(
@@ -679,7 +710,7 @@ class AgentManager:
     async def append_initial_message_sequence_to_in_context_messages_async(
         self, actor: PydanticUser, agent_state: PydanticAgentState, initial_message_sequence: Optional[List[MessageCreate]] = None
     ) -> PydanticAgentState:
-        init_messages = self._generate_initial_message_sequence(actor, agent_state, initial_message_sequence)
+        init_messages = await self._generate_initial_message_sequence_async(actor, agent_state, initial_message_sequence)
         return await self.append_to_in_context_messages_async(init_messages, agent_id=agent_state.id, actor=actor)
 
     @enforce_types
@@ -1034,6 +1065,7 @@ class AgentManager:
         include_relationships: Optional[List[str]] = None,
         ascending: bool = True,
         sort_by: Optional[str] = "created_at",
+        show_hidden_agents: Optional[bool] = None,
     ) -> List[PydanticAgentState]:
         """
         Retrieves agents with optimized filtering and optional field selection.
@@ -1055,6 +1087,7 @@ class AgentManager:
             include_relationships (Optional[List[str]]): List of fields to load for performance optimization.
             ascending (bool): Sort agents in ascending order.
             sort_by (Optional[str]): Sort agents by this field.
+            show_hidden_agents (bool): If True, include agents marked as hidden in the results.
 
         Returns:
             List[PydanticAgentState]: The filtered list of matching agents.
@@ -1068,6 +1101,10 @@ class AgentManager:
             query = _apply_identity_filters(query, identity_id, identifier_keys)
             query = _apply_tag_filter(query, tags, match_all_tags)
             query = _apply_relationship_filters(query, include_relationships)
+
+            # Apply hidden filter
+            if not show_hidden_agents:
+                query = query.where((AgentModel.hidden.is_(None)) | (AgentModel.hidden == False))
             query = await _apply_pagination_async(query, before, after, session, ascending=ascending, sort_by=sort_by)
 
             if limit:
@@ -1668,7 +1705,7 @@ class AgentManager:
 
         # update memory (TODO: potentially update recall/archival stats separately)
 
-        new_system_message_str = compile_system_message(
+        new_system_message_str = await compile_system_message_async(
             system_prompt=agent_state.system,
             in_context_memory=agent_state.memory,
             in_context_memory_last_edit=memory_edit_timestamp,
@@ -1803,7 +1840,7 @@ class AgentManager:
 
         # Optionally add default initial messages after the system message
         if add_default_initial_messages:
-            init_messages = initialize_message_sequence(
+            init_messages = await initialize_message_sequence_async(
                 agent_state=agent_state, memory_edit_timestamp=get_utc_time(), include_initial_boot_message=True
             )
             # Skip index 0 (system message) since we preserved the original

letta/services/block_manager.py

@@ -2,7 +2,7 @@ import asyncio
 from datetime import datetime
 from typing import Dict, List, Optional
 
-from sqlalchemy import delete, or_, select
+from sqlalchemy import and_, delete, func, or_, select
 from sqlalchemy.orm import Session
 
 from letta.log import get_logger
@@ -182,6 +182,12 @@ class BlockManager:
         before: Optional[str] = None,
         after: Optional[str] = None,
         limit: Optional[int] = 50,
+        label_search: Optional[str] = None,
+        description_search: Optional[str] = None,
+        value_search: Optional[str] = None,
+        connected_to_agents_count_gt: Optional[int] = None,
+        connected_to_agents_count_lt: Optional[int] = None,
+        connected_to_agents_count_eq: Optional[List[int]] = None,
         ascending: bool = True,
     ) -> List[PydanticBlock]:
         """Async version of get_blocks method. Retrieve blocks based on various optional filters."""
@@ -214,8 +220,64 @@ class BlockManager:
             if project_id:
                 query = query.where(BlockModel.project_id == project_id)
 
+            if label_search and not label:
+                query = query.where(BlockModel.label.ilike(f"%{label_search}%"))
+
+            if description_search:
+                query = query.where(BlockModel.description.ilike(f"%{description_search}%"))
+
+            if value_search:
+                query = query.where(BlockModel.value.ilike(f"%{value_search}%"))
+
             needs_distinct = False
 
+            needs_agent_count_join = any(
+                condition is not None
+                for condition in [connected_to_agents_count_gt, connected_to_agents_count_lt, connected_to_agents_count_eq]
+            )
+
+            # If any agent count filters are specified, create a single subquery and apply all filters
+            if needs_agent_count_join:
+                # Create a subquery to count agents per block
+                agent_count_subquery = (
+                    select(BlocksAgents.block_id, func.count(BlocksAgents.agent_id).label("agent_count"))
+                    .group_by(BlocksAgents.block_id)
+                    .subquery()
+                )
+
+                # Determine if we need a left join (for cases involving 0 counts)
+                needs_left_join = (connected_to_agents_count_lt is not None) or (
+                    connected_to_agents_count_eq is not None and 0 in connected_to_agents_count_eq
+                )
+
+                if needs_left_join:
+                    # Left join to include blocks with no agents
+                    query = query.outerjoin(agent_count_subquery, BlockModel.id == agent_count_subquery.c.block_id)
+                    # Use coalesce to treat NULL as 0 for blocks with no agents
+                    agent_count_expr = func.coalesce(agent_count_subquery.c.agent_count, 0)
+                else:
+                    # Inner join since we don't need blocks with no agents
+                    query = query.join(agent_count_subquery, BlockModel.id == agent_count_subquery.c.block_id)
+                    agent_count_expr = agent_count_subquery.c.agent_count
+
+                # Build the combined filter conditions
+                conditions = []
+
+                if connected_to_agents_count_gt is not None:
+                    conditions.append(agent_count_expr > connected_to_agents_count_gt)
+
+                if connected_to_agents_count_lt is not None:
+                    conditions.append(agent_count_expr < connected_to_agents_count_lt)
+
+                if connected_to_agents_count_eq is not None:
+                    conditions.append(agent_count_expr.in_(connected_to_agents_count_eq))
+
+                # Apply all conditions with AND logic
+                if conditions:
+                    query = query.where(and_(*conditions))
+
+                needs_distinct = True
+
             if identifier_keys:
                 query = query.join(BlockModel.identities).filter(
                     BlockModel.identities.property.mapper.class_.identifier_key.in_(identifier_keys)

letta/services/file_processor/chunker/line_chunker.py

@@ -130,37 +130,38 @@ class LineChunker:
         # Apply the appropriate chunking strategy
         if strategy == ChunkingStrategy.DOCUMENTATION:
             content_lines = self._chunk_by_sentences(text)
-        elif strategy == ChunkingStrategy.PROSE:
-            content_lines = self._chunk_by_characters(text)
         elif strategy == ChunkingStrategy.CODE:
             content_lines = self._chunk_by_lines(text, preserve_indentation=True)
         else:  # STRUCTURED_DATA or LINE_BASED
             content_lines = self._chunk_by_lines(text, preserve_indentation=False)
 
         total_chunks = len(content_lines)
-        chunk_type = (
-            "sentences" if strategy == ChunkingStrategy.DOCUMENTATION else "chunks" if strategy == ChunkingStrategy.PROSE else "lines"
-        )
+        chunk_type = "sentences" if strategy == ChunkingStrategy.DOCUMENTATION else "lines"
 
-        # Validate range if requested
-        if validate_range and (start is not None or end is not None):
+        # Handle range validation and clamping
+        if start is not None or end is not None:
+            # Always validate that start < end if both are specified
+            if start is not None and end is not None and start >= end:
+                if validate_range:
+                    raise ValueError(f"Invalid range: start ({start}) must be less than end ({end})")
+                # If validation is off, we still need to handle this case sensibly
+                # but we'll allow it to proceed with an empty result
+
+            # Always check that start is within bounds - this should error regardless of validation flag
             if start is not None and start >= total_chunks:
-                # Convert to 1-indexed for user-friendly error message
-                start_display = start + 1
                 raise ValueError(
-                    f"File {file_metadata.file_name} has only {total_chunks} lines, but requested offset {start_display} is out of range"
+                    f"File {file_metadata.file_name} has only {total_chunks} {chunk_type}, but requested offset {start + 1} is out of range"
                 )
 
-            if start is not None and end is not None and end > total_chunks:
-                # Convert to 1-indexed for user-friendly error message
-                start_display = start + 1
-                end_display = end
-                raise ValueError(
-                    f"File {file_metadata.file_name} has only {total_chunks} lines, but requested range {start_display} to {end_display} extends beyond file bounds"
-                )
+            # Apply bounds checking
+            if start is not None:
+                start = max(0, start)  # Ensure non-negative
 
-        # Handle start/end slicing
-        if start is not None or end is not None:
+            # Only clamp end if it exceeds the file length
+            if end is not None:
+                end = min(end, total_chunks)
+
+            # Apply slicing
             content_lines = content_lines[start:end]
             line_offset = start if start is not None else 0
         else:

letta/services/file_processor/file_processor.py

@@ -12,7 +12,6 @@ from letta.schemas.passage import Passage
 from letta.schemas.user import User
 from letta.services.agent_manager import AgentManager
 from letta.services.file_manager import FileManager
-from letta.services.file_processor.chunker.line_chunker import LineChunker
 from letta.services.file_processor.chunker.llama_index_chunker import LlamaIndexChunker
 from letta.services.file_processor.embedder.base_embedder import BaseEmbedder
 from letta.services.file_processor.parser.base_parser import FileParser
@@ -35,7 +34,6 @@ class FileProcessor:
         max_file_size: int = 50 * 1024 * 1024,  # 50MB default
     ):
         self.file_parser = file_parser
-        self.line_chunker = LineChunker()
         self.embedder = embedder
         self.max_file_size = max_file_size
         self.file_manager = FileManager()

letta/services/file_processor/file_types.py

@@ -17,7 +17,6 @@ class ChunkingStrategy(str, Enum):
     CODE = "code"  # Line-based chunking for code files
     STRUCTURED_DATA = "structured_data"  # Line-based chunking for JSON, XML, etc.
     DOCUMENTATION = "documentation"  # Paragraph-aware chunking for Markdown, HTML
-    PROSE = "prose"  # Character-based wrapping for plain text
     LINE_BASED = "line_based"  # Default line-based chunking
 
 
@@ -44,7 +43,7 @@ class FileTypeRegistry:
         """Register all default supported file types."""
         # Document formats
         self.register(".pdf", "application/pdf", False, "PDF document", ChunkingStrategy.LINE_BASED)
-        self.register(".txt", "text/plain", True, "Plain text file", ChunkingStrategy.PROSE)
+        self.register(".txt", "text/plain", True, "Plain text file", ChunkingStrategy.LINE_BASED)
         self.register(".md", "text/markdown", True, "Markdown document", ChunkingStrategy.DOCUMENTATION)
         self.register(".markdown", "text/markdown", True, "Markdown document", ChunkingStrategy.DOCUMENTATION)
         self.register(".json", "application/json", True, "JSON data file", ChunkingStrategy.STRUCTURED_DATA)

letta/services/files_agents_manager.py

@@ -1,5 +1,5 @@
 from datetime import datetime, timezone
-from typing import List, Optional, Union
+from typing import Dict, List, Optional, Union
 
 from sqlalchemy import and_, delete, func, or_, select, update
 
@@ -34,6 +34,8 @@ class FileAgentManager:
         max_files_open: int,
         is_open: bool = True,
         visible_content: Optional[str] = None,
+        start_line: Optional[int] = None,
+        end_line: Optional[int] = None,
     ) -> tuple[PydanticFileAgent, List[str]]:
         """
         Idempotently attach *file_id* to *agent_id* with LRU enforcement.
@@ -48,7 +50,7 @@ class FileAgentManager:
         """
         if is_open:
             # Use the efficient LRU + open method
-            closed_files, was_already_open = await self.enforce_max_open_files_and_open(
+            closed_files, was_already_open, _ = await self.enforce_max_open_files_and_open(
                 agent_id=agent_id,
                 file_id=file_id,
                 file_name=file_name,
@@ -56,6 +58,8 @@ class FileAgentManager:
                 actor=actor,
                 visible_content=visible_content or "",
                 max_files_open=max_files_open,
+                start_line=start_line,
+                end_line=end_line,
             )
 
             # Get the updated file agent to return
@@ -85,6 +89,8 @@ class FileAgentManager:
                         existing.visible_content = visible_content
 
                     existing.last_accessed_at = now_ts
+                    existing.start_line = start_line
+                    existing.end_line = end_line
 
                     await existing.update_async(session, actor=actor)
                     return existing.to_pydantic(), []
@@ -98,6 +104,8 @@ class FileAgentManager:
                     is_open=is_open,
                     visible_content=visible_content,
                     last_accessed_at=now_ts,
+                    start_line=start_line,
+                    end_line=end_line,
                 )
                 await assoc.create_async(session, actor=actor)
                 return assoc.to_pydantic(), []
@@ -112,6 +120,8 @@ class FileAgentManager:
         actor: PydanticUser,
         is_open: Optional[bool] = None,
         visible_content: Optional[str] = None,
+        start_line: Optional[int] = None,
+        end_line: Optional[int] = None,
     ) -> PydanticFileAgent:
         """Patch an existing association row."""
         async with db_registry.async_session() as session:
@@ -121,6 +131,10 @@ class FileAgentManager:
                 assoc.is_open = is_open
             if visible_content is not None:
                 assoc.visible_content = visible_content
+            if start_line is not None:
+                assoc.start_line = start_line
+            if end_line is not None:
+                assoc.end_line = end_line
 
             # touch timestamp
             assoc.last_accessed_at = datetime.now(timezone.utc)
@@ -373,8 +387,18 @@ class FileAgentManager:
     @enforce_types
     @trace_method
     async def enforce_max_open_files_and_open(
-        self, *, agent_id: str, file_id: str, file_name: str, source_id: str, actor: PydanticUser, visible_content: str, max_files_open: int
-    ) -> tuple[List[str], bool]:
+        self,
+        *,
+        agent_id: str,
+        file_id: str,
+        file_name: str,
+        source_id: str,
+        actor: PydanticUser,
+        visible_content: str,
+        max_files_open: int,
+        start_line: Optional[int] = None,
+        end_line: Optional[int] = None,
+    ) -> tuple[List[str], bool, Dict[str, tuple[Optional[int], Optional[int]]]]:
         """
         Efficiently handle LRU eviction and file opening in a single transaction.
 
@@ -387,7 +411,8 @@ class FileAgentManager:
             visible_content: Content to set for the opened file
 
         Returns:
-            Tuple of (closed_file_names, file_was_already_open)
+            Tuple of (closed_file_names, file_was_already_open, previous_ranges)
+            where previous_ranges maps file names to their old (start_line, end_line) ranges
         """
         async with db_registry.async_session() as session:
             # Single query to get ALL open files for this agent, ordered by last_accessed_at (oldest first)
@@ -423,6 +448,17 @@ class FileAgentManager:
 
             file_was_already_open = file_to_open is not None and file_to_open.is_open
 
+            # Capture previous line range if file was already open and we're changing the range
+            previous_ranges = {}
+            if file_was_already_open and file_to_open:
+                old_start = file_to_open.start_line
+                old_end = file_to_open.end_line
+                # Only record if there was a previous range or if we're setting a new range
+                if old_start is not None or old_end is not None or start_line is not None or end_line is not None:
+                    # Only record if the range is actually changing
+                    if old_start != start_line or old_end != end_line:
+                        previous_ranges[file_name] = (old_start, old_end)
+
             # Calculate how many files need to be closed
             current_other_count = len(other_open_files)
             target_other_count = max_files_open - 1  # Reserve 1 slot for file we're opening
@@ -458,6 +494,8 @@ class FileAgentManager:
                 file_to_open.is_open = True
                 file_to_open.visible_content = visible_content
                 file_to_open.last_accessed_at = now_ts
+                file_to_open.start_line = start_line
+                file_to_open.end_line = end_line
                 await file_to_open.update_async(session, actor=actor)
             else:
                 # Create new file association
@@ -470,10 +508,12 @@ class FileAgentManager:
                     is_open=True,
                     visible_content=visible_content,
                     last_accessed_at=now_ts,
+                    start_line=start_line,
+                    end_line=end_line,
                 )
                 await new_file_agent.create_async(session, actor=actor)
 
-            return closed_file_names, file_was_already_open
+            return closed_file_names, file_was_already_open, previous_ranges
 
     @enforce_types
     @trace_method