letta-nightly 0.12.1.dev20251023104211__py3-none-any.whl → 0.13.0.dev20251024223017__py3-none-any.whl

letta/services/tool_executor/core_tool_executor.py

@@ -47,6 +47,7 @@ class LettaCoreToolExecutor(ToolExecutor):
             "core_memory_replace": self.core_memory_replace,
             "memory_replace": self.memory_replace,
             "memory_insert": self.memory_insert,
+            "memory_apply_patch": self.memory_apply_patch,
             "memory_str_replace": self.memory_str_replace,
             "memory_str_insert": self.memory_str_insert,
             "memory_rethink": self.memory_rethink,
@@ -393,6 +394,116 @@ class LettaCoreToolExecutor(ToolExecutor):
         # return None
         return success_msg
 
+    async def memory_apply_patch(self, agent_state: AgentState, actor: User, label: str, patch: str) -> str:
+        """Apply a simplified unified-diff style patch to a memory block, anchored on content and context.
+
+        Args:
+            label: The memory block label to modify.
+            patch: Patch text with lines starting with " ", "-", or "+" and optional "@@" hunk headers.
+
+        Returns:
+            Success message on clean application; raises ValueError on mismatch/ambiguity.
+        """
+        if agent_state.memory.get_block(label).read_only:
+            raise ValueError(f"{READ_ONLY_BLOCK_EDIT_ERROR}")
+
+        # Guardrails: forbid visual line numbers and warning banners
+        if MEMORY_TOOLS_LINE_NUMBER_PREFIX_REGEX.search(patch or ""):
+            raise ValueError(
+                "Patch contains a line number prefix, which is not allowed. Do not include line numbers (they are for display only)."
+            )
+        if CORE_MEMORY_LINE_NUMBER_WARNING in (patch or ""):
+            raise ValueError("Patch contains the line number warning banner, which is not allowed. Provide only the text to edit.")
+
+        current_value = str(agent_state.memory.get_block(label).value).expandtabs()
+        patch = str(patch).expandtabs()
+
+        current_lines = current_value.split("\n")
+        # Ignore common diff headers
+        raw_lines = patch.splitlines()
+        patch_lines = [ln for ln in raw_lines if not ln.startswith("*** ") and not ln.startswith("---") and not ln.startswith("+++")]
+
+        # Split into hunks using '@@' as delimiter
+        hunks: list[list[str]] = []
+        h: list[str] = []
+        for ln in patch_lines:
+            if ln.startswith("@@"):
+                if h:
+                    hunks.append(h)
+                    h = []
+                continue
+            if ln.startswith(" ") or ln.startswith("-") or ln.startswith("+"):
+                h.append(ln)
+            elif ln.strip() == "":
+                # Treat blank line as context for empty string line
+                h.append(" ")
+            else:
+                # Skip unknown metadata lines
+                continue
+        if h:
+            hunks.append(h)
+
+        if not hunks:
+            raise ValueError("No applicable hunks found in patch. Ensure lines start with ' ', '-', or '+'.")
+
+        def find_all_subseq(hay: list[str], needle: list[str]) -> list[int]:
+            out: list[int] = []
+            n = len(needle)
+            if n == 0:
+                return out
+            for i in range(0, len(hay) - n + 1):
+                if hay[i : i + n] == needle:
+                    out.append(i)
+            return out
+
+        # Apply each hunk sequentially against the rolling buffer
+        for hunk in hunks:
+            expected: list[str] = []
+            replacement: list[str] = []
+            for ln in hunk:
+                if ln.startswith(" "):
+                    line = ln[1:]
+                    expected.append(line)
+                    replacement.append(line)
+                elif ln.startswith("-"):
+                    line = ln[1:]
+                    expected.append(line)
+                elif ln.startswith("+"):
+                    line = ln[1:]
+                    replacement.append(line)
+
+            if not expected and replacement:
+                # Pure insertion with no context: append at end
+                current_lines = current_lines + replacement
+                continue
+
+            matches = find_all_subseq(current_lines, expected)
+            if len(matches) == 0:
+                sample = "\n".join(expected[:4])
+                raise ValueError(
+                    "Failed to apply patch: expected hunk context not found in the memory block. "
+                    f"Verify the target lines exist and try providing more context. Expected start:\n{sample}"
+                )
+            if len(matches) > 1:
+                raise ValueError(
+                    "Failed to apply patch: hunk context matched multiple places in the memory block. "
+                    "Please add more unique surrounding context to disambiguate."
+                )
+
+            idx = matches[0]
+            end = idx + len(expected)
+            current_lines = current_lines[:idx] + replacement + current_lines[end:]
+
+        new_value = "\n".join(current_lines)
+        agent_state.memory.update_block_value(label=label, value=new_value)
+        await self.agent_manager.update_memory_if_changed_async(agent_id=agent_state.id, new_memory=agent_state.memory, actor=actor)
+
+        return (
+            f"The core memory block with label `{label}` has been edited. "
+            "Review the changes and make sure they are as expected (correct indentation, no duplicate lines, etc). "
+            "Edit the memory block again if necessary."
+        )
+
     async def memory_insert(
         self,
         agent_state: AgentState,

letta/services/tool_executor/files_tool_executor.py

@@ -2,6 +2,8 @@ import asyncio
 import re
 from typing import Any, Dict, List, Optional
 
+from sqlalchemy.exc import NoResultFound
+
 from letta.constants import PINECONE_TEXT_FIELD_NAME
 from letta.functions.types import FileOpenRequest
 from letta.helpers.pinecone_utils import search_pinecone_index, should_use_pinecone
@@ -389,9 +391,9 @@ class LettaFileToolExecutor(ToolExecutor):
 
             for file_agent in file_agents:
                 # Load file content
-                file = await self.file_manager.get_file_by_id(file_id=file_agent.file_id, actor=self.actor, include_content=True)
-
-                if not file or not file.content:
+                try:
+                    file = await self.file_manager.get_file_by_id(file_id=file_agent.file_id, actor=self.actor, include_content=True)
+                except NoResultFound:
                     files_skipped += 1
                     self.logger.warning(f"Grep: Skipping file {file_agent.file_name} - no content available")
                     continue

letta/services/tool_executor/sandbox_tool_executor.py

@@ -36,7 +36,7 @@ class SandboxToolExecutor(ToolExecutor):
     ) -> ToolExecutionResult:
         # Store original memory state
         if agent_state:
-            orig_memory_str = agent_state.memory.compile()
+            orig_memory_str = agent_state.memory.compile(llm_config=agent_state.llm_config)
         else:
             orig_memory_str = None
 
@@ -89,7 +89,7 @@ class SandboxToolExecutor(ToolExecutor):
 
             # Verify memory integrity
             if agent_state:
-                new_memory_str = agent_state.memory.compile()
+                new_memory_str = agent_state.memory.compile(llm_config=agent_state.llm_config)
                 assert orig_memory_str == new_memory_str, "Memory should not be modified in a sandbox tool"
 
             # Update agent memory if needed

letta/services/tool_executor/tool_execution_manager.py

@@ -142,7 +142,7 @@ class ToolExecutionManager:
             )
         except Exception as e:
             status = "error"
-            self.logger.error(f"Error executing tool {function_name}: {str(e)}")
+            self.logger.info(f"Error executing tool {function_name}: {str(e)}")
             error_message = get_friendly_error_msg(
                 function_name=function_name,
                 exception_name=type(e).__name__,

letta/services/tool_manager.py

@@ -1,5 +1,4 @@
 import importlib
-import warnings
 from typing import List, Optional, Set, Union
 
 from sqlalchemy import and_, func, or_, select
@@ -13,6 +12,7 @@ from letta.constants import (
     BASE_VOICE_SLEEPTIME_TOOLS,
     BUILTIN_TOOLS,
     FILES_TOOLS,
+    LETTA_PARALLEL_SAFE_TOOLS,
     LETTA_TOOL_MODULE_NAMES,
     LETTA_TOOL_SET,
     LOCAL_ONLY_MULTI_AGENT_TOOLS,
@@ -26,7 +26,7 @@ from letta.log import get_logger
 from letta.orm.errors import NoResultFound
 from letta.orm.tool import Tool as ToolModel
 from letta.otel.tracing import trace_method
-from letta.schemas.enums import ToolType
+from letta.schemas.enums import PrimitiveType, ToolType
 from letta.schemas.tool import Tool as PydanticTool, ToolCreate, ToolUpdate
 from letta.schemas.user import User as PydanticUser
 from letta.server.db import db_registry
@@ -35,6 +35,7 @@ from letta.services.mcp.types import SSEServerConfig, StdioServerConfig
 from letta.services.tool_schema_generator import generate_schema_for_tool_creation, generate_schema_for_tool_update
 from letta.settings import settings
 from letta.utils import enforce_types, printd
+from letta.validators import raise_on_invalid_id
 
 logger = get_logger(__name__)
 
@@ -202,6 +203,7 @@ class ToolManager:
 
     @enforce_types
     @trace_method
+    @raise_on_invalid_id(param_name="tool_id", expected_prefix=PrimitiveType.TOOL)
     async def get_tool_by_id_async(self, tool_id: str, actor: PydanticUser) -> PydanticTool:
         """Fetch a tool by its ID."""
         async with db_registry.async_session() as session:
@@ -234,6 +236,7 @@ class ToolManager:
 
     @enforce_types
     @trace_method
+    @raise_on_invalid_id(param_name="tool_id", expected_prefix=PrimitiveType.TOOL)
     async def tool_exists_async(self, tool_id: str, actor: PydanticUser) -> bool:
         """Check if a tool exists and belongs to the user's organization (lightweight check)."""
         async with db_registry.async_session() as session:
@@ -506,6 +509,7 @@ class ToolManager:
 
     @enforce_types
     @trace_method
+    @raise_on_invalid_id(param_name="tool_id", expected_prefix=PrimitiveType.TOOL)
     async def update_tool_by_id_async(
         self,
         tool_id: str,
@@ -603,6 +607,7 @@ class ToolManager:
 
     @enforce_types
     @trace_method
+    # @raise_on_invalid_id This is commented out bc it's called by _list_tools_async, when it encounters malformed tools (i.e. if id is invalid will fail validation on deletion)
     async def delete_tool_by_id_async(self, tool_id: str, actor: PydanticUser) -> None:
         """Delete a tool by its ID."""
         async with db_registry.async_session() as session:
@@ -630,7 +635,7 @@ class ToolManager:
                 module = importlib.import_module(module_name)
                 functions_to_schema.update(load_function_set(module))
             except ValueError as e:
-                warnings.warn(f"Error loading function set '{module_name}': {e}")
+                logger.warning(f"Error loading function set '{module_name}': {e}")
             except Exception as e:
                 raise e
 
@@ -662,12 +667,14 @@ class ToolManager:
                 continue
 
             # create pydantic tool for validation and conversion
+            parallel_safe = name in LETTA_PARALLEL_SAFE_TOOLS
             pydantic_tool = PydanticTool(
                 name=name,
                 tags=[tool_type.value],
                 source_type="python",
                 tool_type=tool_type,
                 return_char_limit=BASE_FUNCTION_RETURN_CHAR_LIMIT,
+                enable_parallel_execution=parallel_safe,
             )
 
             # auto-generate description if not provided

letta/services/tool_sandbox/base.py

@@ -57,11 +57,19 @@ class AsyncToolSandboxBase(ABC):
                     f"Agent attempted to invoke tool {self.tool_name} that does not exist for organization {self.user.organization_id}"
                 )
 
+            # Check for reserved keyword arguments
+            tool_arguments = parse_function_arguments(self.tool.source_code, self.tool.name)
+
             # TODO: deprecate this
-            if "agent_state" in parse_function_arguments(self.tool.source_code, self.tool.name):
+            if "agent_state" in tool_arguments:
                 self.inject_agent_state = True
             else:
                 self.inject_agent_state = False
+
+            # Check for Letta client and agent_id injection
+            self.inject_letta_client = "letta_client" in tool_arguments or "client" in tool_arguments
+            self.inject_agent_id = "agent_id" in tool_arguments
+
             self.is_async_function = self._detect_async_function()
         self._initialized = True
 
@@ -112,12 +120,16 @@ class AsyncToolSandboxBase(ABC):
                 tool_args += self.initialize_param(param, self.args[param])
 
         agent_state_pickle = pickle.dumps(agent_state) if self.inject_agent_state else None
+        agent_id = agent_state.id if agent_state else None
 
         code = self._render_sandbox_code(
             future_import=future_import,
             inject_agent_state=self.inject_agent_state,
+            inject_letta_client=self.inject_letta_client,
+            inject_agent_id=self.inject_agent_id,
             schema_imports=schema_code or "",
             agent_state_pickle=agent_state_pickle,
+            agent_id=agent_id,
             tool_args=tool_args,
             tool_source_code=self.tool.source_code,
             local_sandbox_result_var_name=self.LOCAL_SANDBOX_RESULT_VAR_NAME,
@@ -133,8 +145,11 @@ class AsyncToolSandboxBase(ABC):
         *,
         future_import: bool,
         inject_agent_state: bool,
+        inject_letta_client: bool,
+        inject_agent_id: bool,
         schema_imports: str,
         agent_state_pickle: bytes | None,
+        agent_id: str | None,
         tool_args: str,
         tool_source_code: str,
         local_sandbox_result_var_name: str,
@@ -162,6 +177,10 @@ class AsyncToolSandboxBase(ABC):
         if inject_agent_state:
             lines.extend(["import letta", "from letta import *"])  # noqa: F401
 
+        # Import Letta client if needed
+        if inject_letta_client:
+            lines.append("from letta_client import Letta")
+
         if schema_imports:
             lines.append(schema_imports.rstrip())
 
@@ -170,6 +189,34 @@ class AsyncToolSandboxBase(ABC):
         else:
             lines.append("agent_state = None")
 
+        # Initialize Letta client if needed
+        if inject_letta_client:
+            from letta.settings import settings
+
+            lines.extend(
+                [
+                    "# Initialize Letta client for tool execution",
+                    "letta_client = Letta(",
+                    f"    base_url={repr(settings.default_base_url)},",
+                    f"    token={repr(settings.default_token)}",
+                    ")",
+                    "# Compatibility shim for client.agents.get",
+                    "try:",
+                    "    _agents = letta_client.agents",
+                    "    if not hasattr(_agents, 'get') and hasattr(_agents, 'retrieve'):",
+                    "        setattr(_agents, 'get', _agents.retrieve)",
+                    "except Exception:",
+                    "    pass",
+                ]
+            )
+
+        # Set agent_id if needed
+        if inject_agent_id:
+            if agent_id:
+                lines.append(f"agent_id = {repr(agent_id)}")
+            else:
+                lines.append("agent_id = None")
+
         if tool_args:
             lines.append(tool_args.rstrip())
 
@@ -286,9 +333,22 @@ class AsyncToolSandboxBase(ABC):
                 kwargs.append(name)
 
         param_list = [f"{arg}={arg}" for arg in kwargs]
+
+        # Add reserved keyword arguments
         if self.inject_agent_state:
             param_list.append("agent_state=agent_state")
 
+        if self.inject_letta_client:
+            # Check if the function expects 'client' or 'letta_client'
+            tool_arguments = parse_function_arguments(self.tool.source_code, self.tool.name)
+            if "client" in tool_arguments:
+                param_list.append("client=letta_client")
+            elif "letta_client" in tool_arguments:
+                param_list.append("letta_client=letta_client")
+
+        if self.inject_agent_id:
+            param_list.append("agent_id=agent_id")
+
         params = ", ".join(param_list)
         func_call_str = self.tool.name + "(" + params + ")"
         return func_call_str

letta/services/tool_sandbox/local_sandbox.py

@@ -235,9 +235,7 @@ class AsyncToolSandboxLocal(AsyncToolSandboxBase):
             if isinstance(e, TimeoutError):
                 raise e
 
-            logger.error(f"Subprocess execution for tool {self.tool_name} encountered an error: {e}")
-            logger.error(e.__class__.__name__)
-            logger.error(e.__traceback__)
+            logger.exception(f"Subprocess execution for tool {self.tool_name} encountered an error: {e}")
             func_return = get_friendly_error_msg(
                 function_name=self.tool_name,
                 exception_name=type(e).__name__,

letta/services/user_manager.py

@@ -58,7 +58,7 @@ class UserManager:
     @enforce_types
     @trace_method
     async def update_actor_async(self, user_update: UserUpdate) -> PydanticUser:
-        """Update user details (async version)."""
+        """Update user details (async version). Raises NoResultFound if not found."""
         async with db_registry.async_session() as session:
             # Retrieve the existing user by ID
             existing_user = await UserModel.read_async(db_session=session, identifier=user_update.id)
@@ -76,7 +76,7 @@ class UserManager:
     @enforce_types
     @trace_method
     async def delete_actor_by_id_async(self, user_id: str):
-        """Delete a user and their associated records (agents, sources, mappings) asynchronously."""
+        """Delete a user and their associated records (agents, sources, mappings) asynchronously. Raises NoResultFound if not found."""
         async with db_registry.async_session() as session:
             # Delete from user table
             user = await UserModel.read_async(db_session=session, identifier=user_id)

letta/settings.py

@@ -6,10 +6,13 @@ from typing import Optional
 from pydantic import AliasChoices, Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
-from letta.local_llm.constants import DEFAULT_WRAPPER_NAME, INNER_THOUGHTS_KWARG
 from letta.schemas.enums import SandboxType
 from letta.services.summarizer.enums import SummarizationMode
 
+# Define constants here to avoid circular import with letta.log
+DEFAULT_WRAPPER_NAME = "chatml"
+INNER_THOUGHTS_KWARG = "thinking"
+
 
 class ToolSettings(BaseSettings):
     # Sandbox Configurations
@@ -329,6 +332,10 @@ class Settings(BaseSettings):
     file_processing_timeout_minutes: int = 30
     file_processing_timeout_error_message: str = "File processing timed out after {} minutes. Please try again."
 
+    # Letta client settings for tool execution
+    default_base_url: str = Field(default="http://localhost:8283", description="Default base URL for Letta client in tool execution")
+    default_token: Optional[str] = Field(default=None, description="Default token for Letta client in tool execution")
+
     # enabling letta_agent_v1 architecture
     use_letta_v1_agent: bool = False
 
@@ -374,16 +381,53 @@ class TestSettings(Settings):
 
 class LogSettings(BaseSettings):
     model_config = SettingsConfigDict(env_prefix="letta_logging_", extra="ignore")
-    debug: bool | None = Field(False, description="Enable debugging for logging")
-    json_logging: bool = Field(False, description="Enable json logging instead of text logging")
+    debug: bool = Field(default=False, description="Enable debugging for logging")
+    json_logging: bool = Field(
+        default=False,
+        description="Enable structured JSON logging (recommended).",
+    )
     log_level: str | None = Field("WARNING", description="Logging level")
     letta_log_path: Path | None = Field(Path.home() / ".letta" / "logs" / "Letta.log")
-    verbose_telemetry_logging: bool = Field(False)
+    verbose_telemetry_logging: bool = Field(default=False)
 
 
 class TelemetrySettings(BaseSettings):
+    """Configuration for telemetry and observability integrations."""
+
     model_config = SettingsConfigDict(env_prefix="letta_telemetry_", extra="ignore")
-    profiler: bool | None = Field(False, description="Enable use of the profiler.")
+
+    # Google Cloud Profiler
+    profiler: bool = Field(default=False, description="Enable Google Cloud Profiler.")
+
+    # Datadog APM and Profiling
+    enable_datadog: bool = Field(default=False, description="Enable Datadog profiling. Environment is pulled from settings.environment.")
+    datadog_agent_host: str = Field(
+        default="localhost",
+        description="Datadog agent hostname or IP address. Use service name for Kubernetes (e.g., 'datadog-cluster-agent').",
+    )
+    datadog_agent_port: int = Field(default=8126, ge=1, le=65535, description="Datadog trace agent port (typically 8126 for traces).")
+    datadog_service_name: str = Field(default="letta-server", description="Service name for Datadog profiling.")
+    datadog_profiling_memory_enabled: bool = Field(default=False, description="Enable memory profiling in Datadog.")
+    datadog_profiling_heap_enabled: bool = Field(default=False, description="Enable heap profiling in Datadog.")
+
+    # Datadog Source Code Integration (optional, tightly coupled with profiling)
+    # These settings link profiling data and traces to specific Git commits,
+    # enabling code navigation directly from Datadog UI to GitHub/GitLab.
+    datadog_git_repository_url: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("DD_GIT_REPOSITORY_URL", "datadog_git_repository_url"),
+        description="Git repository URL (e.g., 'https://github.com/org/repo'). Set at build time.",
+    )
+    datadog_git_commit_sha: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("DD_GIT_COMMIT_SHA", "datadog_git_commit_sha"),
+        description="Git commit SHA for the deployed code. Set at build time with 'git rev-parse HEAD'.",
+    )
+    datadog_main_package: str = Field(
+        default="letta",
+        validation_alias=AliasChoices("DD_MAIN_PACKAGE", "datadog_main_package"),
+        description="Primary Python package name for source code linking. Datadog uses this setting to determine which code is 'yours' vs. third-party dependencies.",
+    )
 
 
 # singleton

letta/system.py

@@ -1,7 +1,10 @@
 import json
-import warnings
 from typing import Optional
 
+from letta.log import get_logger
+
+logger = get_logger(__name__)
+
 from .constants import (
     INITIAL_BOOT_MESSAGE,
     INITIAL_BOOT_MESSAGE_SEND_MESSAGE_FIRST_MSG,
@@ -42,11 +45,17 @@ def get_initial_boot_messages(version, timezone, tool_call_id):
             },
             # obligatory function return message
             {
-                # "role": "function",
                 "role": "tool",
                 "name": "send_message",  # NOTE: technically not up to spec, this is old functions style
                 "content": package_function_response(True, None, timezone),
                 "tool_call_id": tool_call_id,
+                "tool_returns": [
+                    {
+                        "tool_call_id": tool_call_id,
+                        "status": "success",
+                        "func_response": package_function_response(True, None, timezone),
+                    }
+                ],
             },
         ]
 
@@ -154,7 +163,7 @@ def package_system_message(system_message, timezone, message_type="system_alert"
     try:
         message_json = json.loads(system_message)
         if "type" in message_json and message_json["type"] == message_type:
-            warnings.warn(f"Attempted to pack a system message that is already packed. Not packing: '{system_message}'")
+            logger.warning(f"Attempted to pack a system message that is already packed. Not packing: '{system_message}'")
             return system_message
     except:
         pass  # do nothing, expected behavior that the message is not JSON
@@ -245,7 +254,7 @@ def unpack_message(packed_message: str) -> str:
         if "type" in message_json and message_json["type"] in ["login", "heartbeat"]:
             # This is a valid user message that the ADE expects, so don't print warning
             return packed_message
-        warnings.warn(f"Was unable to find 'message' field in packed message object: '{packed_message}'")
+        logger.warning(f"Was unable to find 'message' field in packed message object: '{packed_message}'")
         return packed_message
     else:
         try:
@@ -254,6 +263,6 @@ def unpack_message(packed_message: str) -> str:
             return packed_message
 
         if message_type != "user_message":
-            warnings.warn(f"Expected type to be 'user_message', but was '{message_type}', so not unpacking: '{packed_message}'")
+            logger.warning(f"Expected type to be 'user_message', but was '{message_type}', so not unpacking: '{packed_message}'")
             return packed_message
         return message_json.get("message")

letta/utils.py

@@ -41,6 +41,7 @@ from letta.helpers.json_helpers import json_dumps, json_loads
 from letta.log import get_logger
 from letta.otel.tracing import log_attributes, trace_method
 from letta.schemas.openai.chat_completion_response import ChatCompletionResponse
+from letta.server.rest_api.dependencies import HeaderParams
 
 logger = get_logger(__name__)
 
@@ -1129,6 +1130,29 @@ def safe_create_task(coro, label: str = "background task"):
     return task
 
 
+@trace_method
+def safe_create_task_with_return(coro, label: str = "background task"):
+    async def wrapper():
+        try:
+            return await coro
+        except Exception as e:
+            logger.exception(f"{label} failed with {type(e).__name__}: {e}")
+            raise
+
+    task = asyncio.create_task(wrapper())
+
+    # Add task to the set to maintain strong reference
+    _background_tasks.add(task)
+
+    # Log task count to trace
+    log_attributes({"total_background_task_count": get_background_task_count()})
+
+    # Remove task from set when done to prevent memory leaks
+    task.add_done_callback(_background_tasks.discard)
+
+    return task
+
+
 def safe_create_shielded_task(coro, label: str = "shielded background task"):
     """
     Create a shielded background task that cannot be cancelled externally.
@@ -1367,7 +1391,7 @@ def fire_and_forget(coro, task_name: Optional[str] = None, error_callback: Optio
             t.result()  # this re-raises exceptions from the task
         except Exception as e:
             task_desc = f"Background task {task_name}" if task_name else "Background task"
-            logger.error(f"{task_desc} failed: {str(e)}\n{traceback.format_exc()}")
+            logger.exception(f"{task_desc} failed: {str(e)}")
 
             if error_callback:
                 try:
@@ -1377,3 +1401,51 @@ def fire_and_forget(coro, task_name: Optional[str] = None, error_callback: Optio
 
     task.add_done_callback(callback)
     return task
+
+
+def is_1_0_sdk_version(headers: HeaderParams):
+    """
+    Check if the SDK version is 1.0.0 or above.
+    1. If sdk_version is provided from stainless (all stainless versions are 1.0.0+)
+    2. If user_agent is provided and in the format
+        @letta-ai/letta-client/version (node) or
+        letta-client/version (python)
+    """
+    sdk_version = headers.sdk_version
+    if sdk_version:
+        return True
+
+    client = headers.user_agent
+    if "/" not in client:
+        return False
+
+    # Split into parts to validate format
+    parts = client.split("/")
+
+    # Should have at least 2 parts (client-name/version)
+    if len(parts) < 2:
+        return False
+
+    if len(parts) == 3:
+        # Format: @letta-ai/letta-client/version
+        if parts[0] != "@letta-ai" or parts[1] != "letta-client":
+            return False
+    elif len(parts) == 2:
+        # Format: letta-client/version
+        if parts[0] != "letta-client":
+            return False
+    else:
+        return False
+
+    # Extract and validate version
+    maybe_version = parts[-1]
+    if "." not in maybe_version:
+        return False
+
+    # Extract major version (handle alpha/beta suffixes like 1.0.0-alpha.2 or 1.0.0a5)
+    version_base = maybe_version.split("-")[0].split("a")[0].split("b")[0]
+    if "." not in version_base:
+        return False
+
+    major_version = version_base.split(".")[0]
+    return major_version == "1"