letta-nightly 0.12.1.dev20251024104217__py3-none-any.whl → 0.13.0.dev20251025104015__py3-none-any.whl

letta/services/message_manager.py

@@ -7,11 +7,10 @@ from sqlalchemy import delete, exists, func, select, text
 
 from letta.constants import CONVERSATION_SEARCH_TOOL_NAME, DEFAULT_MESSAGE_TOOL, DEFAULT_MESSAGE_TOOL_KWARG
 from letta.log import get_logger
-from letta.orm.agent import Agent as AgentModel
 from letta.orm.errors import NoResultFound
 from letta.orm.message import Message as MessageModel
 from letta.otel.tracing import trace_method
-from letta.schemas.enums import MessageRole
+from letta.schemas.enums import MessageRole, PrimitiveType
 from letta.schemas.letta_message import LettaMessageUpdateUnion
 from letta.schemas.letta_message_content import ImageSourceType, LettaImage, MessageContentType, TextContent
 from letta.schemas.message import Message as PydanticMessage, MessageSearchResult, MessageUpdate
@@ -21,10 +20,104 @@ from letta.services.file_manager import FileManager
 from letta.services.helpers.agent_manager_helper import validate_agent_exists_async
 from letta.settings import DatabaseChoice, settings
 from letta.utils import enforce_types, fire_and_forget
+from letta.validators import raise_on_invalid_id
 
 logger = get_logger(__name__)
 
 
+@trace_method
+def backfill_missing_tool_call_ids(messages: list, agent_id: Optional[str] = None, actor: Optional[PydanticUser] = None) -> list:
+    """Backfill missing tool_call_id values in tool messages from historical bug (oct 1-6, 2025)
+
+    Args:
+        messages: List of messages to backfill
+        agent_id: Optional agent ID for logging
+        actor: Optional actor information for logging
+
+    Returns:
+        List of messages with tool_call_ids backfilled where appropriate
+    """
+    if not messages:
+        return messages
+
+    from letta.schemas.message import Message as PydanticMessage
+
+    # Check if messages are ordered chronologically (oldest first)
+    # If not, reverse the list to ensure proper chronological order
+    was_reversed = False
+    if len(messages) > 1:
+        first_msg = messages[0]
+        last_msg = messages[-1]
+
+        # Only check PydanticMessage objects that have created_at
+        if (
+            isinstance(first_msg, PydanticMessage)
+            and isinstance(last_msg, PydanticMessage)
+            and hasattr(first_msg, "created_at")
+            and hasattr(last_msg, "created_at")
+        ):
+            # If first message is newer than last message, list is reversed
+            if first_msg.created_at > last_msg.created_at:
+                was_reversed = True
+                messages.reverse()
+
+    updated_messages = []
+    last_tool_call_id = None
+    backfilled_count = 0
+
+    for i, message in enumerate(messages):
+        if not isinstance(message, PydanticMessage):
+            updated_messages.append(message)
+            continue
+
+        # check if assistant message has a single tool call to track
+        if message.role == MessageRole.assistant and message.tool_calls:
+            if len(message.tool_calls) == 1 and message.tool_calls[0].id:
+                last_tool_call_id = message.tool_calls[0].id
+            else:
+                # parallel tool calls or missing id - don't backfill
+                last_tool_call_id = None
+
+        # check if tool message needs backfilling
+        elif message.role == MessageRole.tool:
+            needs_update = False
+
+            # only backfill if we have a single tool return and a preceding tool call id
+            if message.tool_returns and len(message.tool_returns) == 1 and last_tool_call_id is not None:
+                # check and update message.tool_call_id
+                if message.tool_call_id is None:
+                    message.tool_call_id = last_tool_call_id
+                    needs_update = True
+
+                # check and update tool_return.tool_call_id
+                tool_return = message.tool_returns[0]
+                if tool_return.tool_call_id is None:
+                    tool_return.tool_call_id = last_tool_call_id
+                    needs_update = True
+
+                if needs_update:
+                    backfilled_count += 1
+                    logger.debug(f"Backfilled tool_call_id '{last_tool_call_id}' for message {i} (id={message.id})")
+
+            # clear last_tool_call_id after processing tool message
+            last_tool_call_id = None
+
+        updated_messages.append(message)
+
+    # log warning with context if any backfilling occurred
+    if backfilled_count > 0:
+        actor_info = f"actor_id={actor.id}" if actor else "actor=unknown"
+        agent_info = f"agent_id={agent_id}" if agent_id else "agent=unknown"
+        logger.warning(
+            f"Backfilled {backfilled_count} missing tool_call_ids for historical messages (oct 1-6, 2025 bug) - {agent_info}, {actor_info}"
+        )
+
+    if was_reversed:
+        updated_messages.reverse()
+
+    return updated_messages
+
+
 class MessageManager:
     """Manager class to handle business logic related to Messages."""
 
@@ -216,6 +309,7 @@ class MessageManager:
 
     @enforce_types
     @trace_method
+    @raise_on_invalid_id(param_name="message_id", expected_prefix=PrimitiveType.MESSAGE)
     async def get_message_by_id_async(self, message_id: str, actor: PydanticUser) -> Optional[PydanticMessage]:
         """Fetch a message by ID."""
         async with db_registry.async_session() as session:
@@ -244,7 +338,14 @@ class MessageManager:
             )
         # Sort results directly based on message_ids
         result_dict = {msg.id: msg.to_pydantic() for msg in results}
-        return list(filter(lambda x: x is not None, [result_dict.get(msg_id, None) for msg_id in message_ids]))
+        messages = list(filter(lambda x: x is not None, [result_dict.get(msg_id, None) for msg_id in message_ids]))
+
+        # backfill missing tool_call_ids from historical bug (oct 1-6, 2025)
+        # Note: we don't have agent_id or actor here, but that's OK for logging
+        # TODO: This can cause bugs technically, if we adversarially craft a series of message_ids that are not contiguous
+        # TODO: But usually, this is being used by the agent loop code to get the in context messages, which are contiguous
+        # TODO: We should remove this as soon as possible, need to inspect for the above log message, if it hasn't happened in a while
+        return backfill_missing_tool_call_ids(messages)
 
     def _create_many_preprocess(self, pydantic_msgs: List[PydanticMessage], actor: PydanticUser) -> List[MessageModel]:
         # Create ORM model instances for all messages
@@ -613,6 +714,7 @@ class MessageManager:
 
     @enforce_types
     @trace_method
+    @raise_on_invalid_id(param_name="message_id", expected_prefix=PrimitiveType.MESSAGE)
     async def delete_message_by_id_async(self, message_id: str, actor: PydanticUser, strict_mode: bool = False) -> bool:
         """Delete a message (async version with turbopuffer support)."""
         # capture agent_id before deletion
@@ -803,7 +905,10 @@ class MessageManager:
             # Execute and convert each Message to its Pydantic representation.
             result = await session.execute(query)
             results = result.scalars().all()
-            return [msg.to_pydantic() for msg in results]
+            messages = [msg.to_pydantic() for msg in results]
+
+            # backfill missing tool_call_ids from historical bug (oct 1-6, 2025)
+            return backfill_missing_tool_call_ids(messages, agent_id=agent_id, actor=actor)
 
     @enforce_types
     @trace_method

letta/services/organization_manager.py

@@ -20,8 +20,8 @@ class OrganizationManager:
 
     @enforce_types
     @trace_method
-    async def get_organization_by_id_async(self, org_id: str) -> Optional[PydanticOrganization]:
-        """Fetch an organization by ID."""
+    async def get_organization_by_id_async(self, org_id: str) -> PydanticOrganization:
+        """Fetch an organization by ID. Raises NoResultFound if not found."""
         async with db_registry.async_session() as session:
             organization = await OrganizationModel.read_async(db_session=session, identifier=org_id)
             return organization.to_pydantic()
@@ -64,7 +64,7 @@ class OrganizationManager:
     @enforce_types
     @trace_method
     async def update_organization_async(self, org_id: str, org_update: OrganizationUpdate) -> PydanticOrganization:
-        """Update an organization."""
+        """Update an organization. Raises NoResultFound if not found."""
         async with db_registry.async_session() as session:
             org = await OrganizationModel.read_async(db_session=session, identifier=org_id)
             if org_update.name:
@@ -77,7 +77,7 @@ class OrganizationManager:
     @enforce_types
     @trace_method
     async def delete_organization_by_id_async(self, org_id: str):
-        """Delete an organization by marking it as deleted."""
+        """Delete an organization by marking it as deleted. Raises NoResultFound if not found."""
         async with db_registry.async_session() as session:
             organization = await OrganizationModel.read_async(db_session=session, identifier=org_id)
             await organization.hard_delete_async(session)

letta/services/passage_manager.py

@@ -120,12 +120,8 @@ class PassageManager:
     @trace_method
     async def get_passage_by_id_async(self, passage_id: str, actor: PydanticUser) -> Optional[PydanticPassage]:
         """DEPRECATED: Use get_agent_passage_by_id_async() or get_source_passage_by_id_async() instead."""
-        import warnings
-
-        warnings.warn(
-            "get_passage_by_id_async is deprecated. Use get_agent_passage_by_id_async() or get_source_passage_by_id_async() instead.",
-            DeprecationWarning,
-            stacklevel=2,
+        logger.warning(
+            "get_passage_by_id_async is deprecated. Use get_agent_passage_by_id_async() or get_source_passage_by_id_async() instead."
         )
 
         async with db_registry.async_session() as session:
@@ -231,13 +227,7 @@ class PassageManager:
     @trace_method
     async def create_passage_async(self, pydantic_passage: PydanticPassage, actor: PydanticUser) -> PydanticPassage:
         """DEPRECATED: Use create_agent_passage_async() or create_source_passage_async() instead."""
-        import warnings
-
-        warnings.warn(
-            "create_passage_async is deprecated. Use create_agent_passage_async() or create_source_passage_async() instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        logger.warning("create_passage_async is deprecated. Use create_agent_passage_async() or create_source_passage_async() instead.")
 
         # Common fields for both passage types
         passage = self._preprocess_passage_for_creation(pydantic_passage=pydantic_passage)
@@ -365,9 +355,8 @@ class PassageManager:
         """DEPRECATED: Use create_many_agent_passages() or create_many_source_passages() instead."""
         import warnings
 
-        warnings.warn(
+        logger.warning(
             "create_many_passages is deprecated. Use create_many_agent_passages() or create_many_source_passages() instead.",
-            DeprecationWarning,
             stacklevel=2,
         )
         return [self.create_passage(p, actor) for p in passages]
@@ -378,9 +367,8 @@ class PassageManager:
         """DEPRECATED: Use create_many_agent_passages_async() or create_many_source_passages_async() instead."""
         import warnings
 
-        warnings.warn(
+        logger.warning(
             "create_many_passages_async is deprecated. Use create_many_agent_passages_async() or create_many_source_passages_async() instead.",
-            DeprecationWarning,
             stacklevel=2,
         )
 
@@ -437,9 +425,7 @@ class PassageManager:
         )
 
         # Get or create the default archive for the agent
-        archive = await self.archive_manager.get_or_create_default_archive_for_agent_async(
-            agent_id=agent_state.id, agent_name=agent_state.name, actor=actor
-        )
+        archive = await self.archive_manager.get_or_create_default_archive_for_agent_async(agent_state=agent_state, actor=actor)
 
         text_chunks = list(parse_and_chunk_text(text, embedding_chunk_size))
 
@@ -653,9 +639,8 @@ class PassageManager:
         """DEPRECATED: Use delete_agent_passage_by_id_async() or delete_source_passage_by_id_async() instead."""
         import warnings
 
-        warnings.warn(
+        logger.warning(
             "delete_passage_by_id_async is deprecated. Use delete_agent_passage_by_id_async() or delete_source_passage_by_id_async() instead.",
-            DeprecationWarning,
             stacklevel=2,
         )
 
@@ -767,9 +752,8 @@ class PassageManager:
         """DEPRECATED: Use delete_agent_passages() or delete_source_passages() instead."""
         import warnings
 
-        warnings.warn(
+        logger.warning(
             "delete_passages is deprecated. Use delete_agent_passages() or delete_source_passages() instead.",
-            DeprecationWarning,
             stacklevel=2,
         )
         # TODO: This is very inefficient
@@ -789,7 +773,7 @@ class PassageManager:
         """DEPRECATED: Use agent_passage_size() instead (this only counted agent passages anyway)."""
         import warnings
 
-        warnings.warn("size is deprecated. Use agent_passage_size() instead.", DeprecationWarning, stacklevel=2)
+        logger.warning("size is deprecated. Use agent_passage_size() instead.", stacklevel=2)
         return self.agent_passage_size(actor=actor, agent_id=agent_id)
 
     @enforce_types

letta/services/provider_manager.py

@@ -2,11 +2,13 @@ from typing import List, Optional, Tuple, Union
 
 from letta.orm.provider import Provider as ProviderModel
 from letta.otel.tracing import trace_method
-from letta.schemas.enums import ProviderCategory, ProviderType
+from letta.schemas.enums import PrimitiveType, ProviderCategory, ProviderType
 from letta.schemas.providers import Provider as PydanticProvider, ProviderCheck, ProviderCreate, ProviderUpdate
+from letta.schemas.secret import Secret
 from letta.schemas.user import User as PydanticUser
 from letta.server.db import db_registry
 from letta.utils import enforce_types
+from letta.validators import raise_on_invalid_id
 
 
 class ProviderManager:
@@ -27,12 +29,19 @@ class ProviderManager:
             # Lazily create the provider id prior to persistence
             provider.resolve_identifier()
 
+            # Explicitly populate encrypted fields from plaintext
+            if provider.api_key is not None:
+                provider.api_key_enc = Secret.from_plaintext(provider.api_key)
+            if provider.access_key is not None:
+                provider.access_key_enc = Secret.from_plaintext(provider.access_key)
+
             new_provider = ProviderModel(**provider.model_dump(to_orm=True, exclude_unset=True))
             await new_provider.create_async(session, actor=actor)
             return new_provider.to_pydantic()
 
     @enforce_types
     @trace_method
+    @raise_on_invalid_id(param_name="provider_id", expected_prefix=PrimitiveType.PROVIDER)
     async def update_provider_async(self, provider_id: str, provider_update: ProviderUpdate, actor: PydanticUser) -> PydanticProvider:
         """Update provider details."""
         async with db_registry.async_session() as session:
@@ -43,6 +52,50 @@ class ProviderManager:
 
             # Update only the fields that are provided in ProviderUpdate
             update_data = provider_update.model_dump(to_orm=True, exclude_unset=True, exclude_none=True)
+
+            # Handle encryption for api_key if provided
+            # Only re-encrypt if the value has actually changed
+            if "api_key" in update_data and update_data["api_key"] is not None:
+                # Check if value changed
+                existing_api_key = None
+                if existing_provider.api_key_enc:
+                    existing_secret = Secret.from_encrypted(existing_provider.api_key_enc)
+                    existing_api_key = existing_secret.get_plaintext()
+                elif existing_provider.api_key:
+                    existing_api_key = existing_provider.api_key
+
+                # Only re-encrypt if different
+                if existing_api_key != update_data["api_key"]:
+                    existing_provider.api_key_enc = Secret.from_plaintext(update_data["api_key"]).get_encrypted()
+                    # Keep plaintext for dual-write during migration
+                    existing_provider.api_key = update_data["api_key"]
+
+                # Remove from update_data since we set directly on existing_provider
+                update_data.pop("api_key", None)
+                update_data.pop("api_key_enc", None)
+
+            # Handle encryption for access_key if provided
+            # Only re-encrypt if the value has actually changed
+            if "access_key" in update_data and update_data["access_key"] is not None:
+                # Check if value changed
+                existing_access_key = None
+                if existing_provider.access_key_enc:
+                    existing_secret = Secret.from_encrypted(existing_provider.access_key_enc)
+                    existing_access_key = existing_secret.get_plaintext()
+                elif existing_provider.access_key:
+                    existing_access_key = existing_provider.access_key
+
+                # Only re-encrypt if different
+                if existing_access_key != update_data["access_key"]:
+                    existing_provider.access_key_enc = Secret.from_plaintext(update_data["access_key"]).get_encrypted()
+                    # Keep plaintext for dual-write during migration
+                    existing_provider.access_key = update_data["access_key"]
+
+                # Remove from update_data since we set directly on existing_provider
+                update_data.pop("access_key", None)
+                update_data.pop("access_key_enc", None)
+
+            # Apply remaining updates
             for key, value in update_data.items():
                 setattr(existing_provider, key, value)
 
@@ -52,6 +105,7 @@ class ProviderManager:
 
     @enforce_types
     @trace_method
+    @raise_on_invalid_id(param_name="provider_id", expected_prefix=PrimitiveType.PROVIDER)
     async def delete_provider_by_id_async(self, provider_id: str, actor: PydanticUser):
         """Delete a provider."""
         async with db_registry.async_session() as session:
@@ -102,6 +156,7 @@ class ProviderManager:
 
     @enforce_types
     @trace_method
+    @raise_on_invalid_id(param_name="provider_id", expected_prefix=PrimitiveType.PROVIDER)
     async def get_provider_async(self, provider_id: str, actor: PydanticUser) -> PydanticProvider:
         async with db_registry.async_session() as session:
             provider_model = await ProviderModel.read_async(db_session=session, identifier=provider_id, actor=actor)
@@ -117,13 +172,21 @@ class ProviderManager:
     @trace_method
     def get_override_key(self, provider_name: Union[str, None], actor: PydanticUser) -> Optional[str]:
         providers = self.list_providers(name=provider_name, actor=actor)
-        return providers[0].api_key if providers else None
+        if providers:
+            # Decrypt the API key before returning
+            api_key_secret = providers[0].get_api_key_secret()
+            return api_key_secret.get_plaintext()
+        return None
 
     @enforce_types
     @trace_method
     async def get_override_key_async(self, provider_name: Union[str, None], actor: PydanticUser) -> Optional[str]:
         providers = await self.list_providers_async(name=provider_name, actor=actor)
-        return providers[0].api_key if providers else None
+        if providers:
+            # Decrypt the API key before returning
+            api_key_secret = providers[0].get_api_key_secret()
+            return api_key_secret.get_plaintext()
+        return None
 
     @enforce_types
     @trace_method
@@ -131,10 +194,15 @@ class ProviderManager:
         self, provider_name: Union[str, None], actor: PydanticUser
     ) -> Tuple[Optional[str], Optional[str], Optional[str]]:
         providers = await self.list_providers_async(name=provider_name, actor=actor)
-        access_key = providers[0].access_key if providers else None
-        secret_key = providers[0].api_key if providers else None
-        region = providers[0].region if providers else None
-        return access_key, secret_key, region
+        if providers:
+            # Decrypt the credentials before returning
+            access_key_secret = providers[0].get_access_key_secret()
+            api_key_secret = providers[0].get_api_key_secret()
+            access_key = access_key_secret.get_plaintext()
+            secret_key = api_key_secret.get_plaintext()
+            region = providers[0].region
+            return access_key, secret_key, region
+        return None, None, None
 
     @enforce_types
     @trace_method
@@ -142,10 +210,14 @@ class ProviderManager:
         self, provider_name: Union[str, None], actor: PydanticUser
     ) -> Tuple[Optional[str], Optional[str], Optional[str]]:
         providers = self.list_providers(name=provider_name, actor=actor)
-        api_key = providers[0].api_key if providers else None
-        base_url = providers[0].base_url if providers else None
-        api_version = providers[0].api_version if providers else None
-        return api_key, base_url, api_version
+        if providers:
+            # Decrypt the API key before returning
+            api_key_secret = providers[0].get_api_key_secret()
+            api_key = api_key_secret.get_plaintext()
+            base_url = providers[0].base_url
+            api_version = providers[0].api_version
+            return api_key, base_url, api_version
+        return None, None, None
 
     @enforce_types
     @trace_method
@@ -153,10 +225,14 @@ class ProviderManager:
         self, provider_name: Union[str, None], actor: PydanticUser
     ) -> Tuple[Optional[str], Optional[str], Optional[str]]:
         providers = await self.list_providers_async(name=provider_name, actor=actor)
-        api_key = providers[0].api_key if providers else None
-        base_url = providers[0].base_url if providers else None
-        api_version = providers[0].api_version if providers else None
-        return api_key, base_url, api_version
+        if providers:
+            # Decrypt the API key before returning
+            api_key_secret = providers[0].get_api_key_secret()
+            api_key = api_key_secret.get_plaintext()
+            base_url = providers[0].base_url
+            api_version = providers[0].api_version
+            return api_key, base_url, api_version
+        return None, None, None
 
     @enforce_types
     @trace_method

letta/services/run_manager.py

@@ -3,8 +3,6 @@ from pickletools import pyunicode
 from typing import List, Literal, Optional
 
 from httpx import AsyncClient
-from sqlalchemy import select
-from sqlalchemy.orm import Session
 
 from letta.helpers.datetime_helpers import get_utc_time
 from letta.log import get_logger
@@ -16,7 +14,7 @@ from letta.orm.run_metrics import RunMetrics as RunMetricsModel
 from letta.orm.sqlalchemy_base import AccessType
 from letta.orm.step import Step as StepModel
 from letta.otel.tracing import log_event, trace_method
-from letta.schemas.enums import AgentType, MessageRole, RunStatus
+from letta.schemas.enums import AgentType, ComparisonOperator, MessageRole, RunStatus, PrimitiveType
 from letta.schemas.job import LettaRequestConfig
 from letta.schemas.letta_message import LettaMessage, LettaMessageUnion
 from letta.schemas.letta_response import LettaResponse
@@ -33,6 +31,7 @@ from letta.services.helpers.agent_manager_helper import validate_agent_exists_as
 from letta.services.message_manager import MessageManager
 from letta.services.step_manager import StepManager
 from letta.utils import enforce_types
+from letta.validators import raise_on_invalid_id
 
 logger = get_logger(__name__)
 
@@ -87,6 +86,7 @@ class RunManager:
         return run.to_pydantic()
 
     @enforce_types
+    @raise_on_invalid_id(param_name="run_id", expected_prefix=PrimitiveType.RUN)
     async def get_run_by_id(self, run_id: str, actor: PydanticUser) -> PydanticRun:
         """Get a run by its ID."""
         async with db_registry.async_session() as session:
@@ -108,10 +108,14 @@ class RunManager:
         ascending: bool = False,
         stop_reason: Optional[str] = None,
         background: Optional[bool] = None,
+        template_family: Optional[str] = None,
+        step_count: Optional[int] = None,
+        step_count_operator: ComparisonOperator = ComparisonOperator.EQ,
+        tools_used: Optional[List[str]] = None,
     ) -> List[PydanticRun]:
         """List runs with filtering options."""
         async with db_registry.async_session() as session:
-            from sqlalchemy import select
+            from sqlalchemy import or_, select
 
             query = select(RunModel).filter(RunModel.organization_id == actor.organization_id)
 
@@ -133,6 +137,33 @@ class RunManager:
             if background is not None:
                 query = query.filter(RunModel.background == background)
 
+            # Filter by template_family (base_template_id)
+            if template_family:
+                query = query.filter(RunModel.base_template_id == template_family)
+
+            # Filter by step_count and/or tools_used - join with run_metrics
+            if step_count is not None or tools_used:
+                query = query.join(RunMetricsModel, RunModel.id == RunMetricsModel.id)
+
+                # Filter by step_count with the specified operator
+                if step_count is not None:
+                    if step_count_operator == ComparisonOperator.EQ:
+                        query = query.filter(RunMetricsModel.num_steps == step_count)
+                    elif step_count_operator == ComparisonOperator.GTE:
+                        query = query.filter(RunMetricsModel.num_steps >= step_count)
+                    elif step_count_operator == ComparisonOperator.LTE:
+                        query = query.filter(RunMetricsModel.num_steps <= step_count)
+
+                # Filter by tools used ids
+                if tools_used:
+                    from sqlalchemy import String, cast as sa_cast, type_coerce
+                    from sqlalchemy.dialects.postgresql import ARRAY, JSONB
+
+                    # Use ?| operator to check if any tool_id exists in the array (OR logic)
+                    jsonb_tools = sa_cast(RunMetricsModel.tools_used, JSONB)
+                    tools_array = type_coerce(tools_used, ARRAY(String))
+                    query = query.filter(jsonb_tools.op("?|")(tools_array))
+
             # Apply pagination
             from letta.services.helpers.run_manager_helper import _apply_pagination_async
 
@@ -147,24 +178,22 @@ class RunManager:
             return [run.to_pydantic() for run in runs]
 
     @enforce_types
-    async def delete_run(self, run_id: str, actor: PydanticUser) -> PydanticRun:
+    @raise_on_invalid_id(param_name="run_id", expected_prefix=PrimitiveType.RUN)
+    async def delete_run(self, run_id: str, actor: PydanticUser) -> None:
         """Delete a run by its ID."""
         async with db_registry.async_session() as session:
             run = await RunModel.read_async(db_session=session, identifier=run_id, actor=actor, access_type=AccessType.ORGANIZATION)
             if not run:
                 raise NoResultFound(f"Run with id {run_id} not found")
 
-            pydantic_run = run.to_pydantic()
             await run.hard_delete_async(db_session=session, actor=actor)
 
-        return pydantic_run
-
     @enforce_types
+    @raise_on_invalid_id(param_name="run_id", expected_prefix=PrimitiveType.RUN)
     async def update_run_by_id_async(
         self, run_id: str, update: RunUpdate, actor: PydanticUser, refresh_result_messages: bool = True
     ) -> PydanticRun:
         """Update a run using a RunUpdate object."""
-
         async with db_registry.async_session() as session:
             run = await RunModel.read_async(db_session=session, identifier=run_id, actor=actor)
 
@@ -203,15 +232,38 @@ class RunManager:
 
         # update run metrics table
         num_steps = len(await self.step_manager.list_steps_async(run_id=run_id, actor=actor))
+
+        # Collect tools used from run messages
+        tools_used = set()
+        messages = await self.message_manager.list_messages(actor=actor, run_id=run_id)
+        for message in messages:
+            if message.tool_calls:
+                for tool_call in message.tool_calls:
+                    if hasattr(tool_call, "function") and hasattr(tool_call.function, "name"):
+                        # Get tool ID from tool name
+                        from letta.services.tool_manager import ToolManager
+
+                        tool_manager = ToolManager()
+                        tool_name = tool_call.function.name
+                        tool_id = await tool_manager.get_tool_id_by_name_async(tool_name, actor)
+                        if tool_id:
+                            tools_used.add(tool_id)
+
         async with db_registry.async_session() as session:
             metrics = await RunMetricsModel.read_async(db_session=session, identifier=run_id, actor=actor)
             # Calculate runtime if run is completing
-            if is_terminal_update and metrics.run_start_ns:
-                import time
-
-                current_ns = int(time.time() * 1e9)
-                metrics.run_ns = current_ns - metrics.run_start_ns
+            if is_terminal_update:
+                # Use total_duration_ns from RunUpdate if provided
+                # Otherwise fall back to system time
+                if update.total_duration_ns is not None:
+                    metrics.run_ns = update.total_duration_ns
+                elif metrics.run_start_ns:
+                    import time
+
+                    current_ns = int(time.time() * 1e9)
+                    metrics.run_ns = current_ns - metrics.run_start_ns
             metrics.num_steps = num_steps
+            metrics.tools_used = list(tools_used) if tools_used else None
             await metrics.update_async(db_session=session, actor=actor, no_commit=True, no_refresh=True)
             await session.commit()
 
@@ -267,7 +319,7 @@ class RunManager:
                 log_event("POST callback finished")
                 result["callback_status_code"] = resp.status_code
         except Exception as e:
-            error_message = f"Failed to dispatch callback for run {callback_info['run_id']} to {callback_info['callback_url']}: {e!s}"
+            error_message = f"Failed to dispatch callback for run {callback_info['run_id']} to {callback_info['callback_url']}: {e!r}"
             logger.error(error_message)
             result["callback_error"] = error_message
             # Continue silently - callback failures should not affect run completion
@@ -275,6 +327,7 @@ class RunManager:
             return result
 
     @enforce_types
+    @raise_on_invalid_id(param_name="run_id", expected_prefix=PrimitiveType.RUN)
     async def get_run_usage(self, run_id: str, actor: PydanticUser) -> LettaUsageStatistics:
         """Get usage statistics for a run."""
         async with db_registry.async_session() as session:
@@ -292,6 +345,7 @@ class RunManager:
         return total_usage
 
     @enforce_types
+    @raise_on_invalid_id(param_name="run_id", expected_prefix=PrimitiveType.RUN)
     async def get_run_messages(
         self,
         run_id: str,
@@ -326,6 +380,7 @@ class RunManager:
         return letta_messages
 
     @enforce_types
+    @raise_on_invalid_id(param_name="run_id", expected_prefix=PrimitiveType.RUN)
     async def get_run_request_config(self, run_id: str, actor: PydanticUser) -> Optional[LettaRequestConfig]:
         """Get the letta request config from a run."""
         async with db_registry.async_session() as session:
@@ -336,6 +391,7 @@ class RunManager:
             return pydantic_run.request_config
 
     @enforce_types
+    @raise_on_invalid_id(param_name="run_id", expected_prefix=PrimitiveType.RUN)
     async def get_run_metrics_async(self, run_id: str, actor: PydanticUser) -> PydanticRunMetrics:
         """Get metrics for a run."""
         async with db_registry.async_session() as session:
@@ -343,6 +399,7 @@ class RunManager:
             return metrics.to_pydantic()
 
     @enforce_types
+    @raise_on_invalid_id(param_name="run_id", expected_prefix=PrimitiveType.RUN)
     async def get_run_steps(
         self,
         run_id: str,