openhands-sdk 1.56.0__tar.gz → 1.58.0__tar.gz

{openhands_sdk-1.56.0 → openhands_sdk-1.58.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.56.0
+Version: 1.58.0
 Summary: OpenHands SDK - Core functionality for building AI agents
 Project-URL: Source, https://github.com/OpenHands/software-agent-sdk
 Project-URL: Homepage, https://github.com/OpenHands/software-agent-sdk

{openhands_sdk-1.56.0 → openhands_sdk-1.58.0}/openhands/sdk/agent/agent.py

@@ -625,6 +625,10 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
         preset = self._prompt_preset or PromptPreset.DEFAULT
         return create_registry(preset).build(ctx).dynamic
 
+    @staticmethod
+    def _mark_conversation_finished(state: ConversationState) -> None:
+        state.execution_status = ConversationExecutionStatus.FINISHED
+
     def _execute_actions(
         self,
         conversation: LocalConversation,
@@ -648,11 +652,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
             check_iterative_refinement=lambda ae: (
                 self._check_iterative_refinement(conversation, ae)
             ),
-            mark_finished=lambda: setattr(
-                state,
-                "execution_status",
-                ConversationExecutionStatus.FINISHED,
-            ),
+            mark_finished=lambda: self._mark_conversation_finished(state),
         )
 
     async def _aexecute_actions(
@@ -683,11 +683,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
             check_iterative_refinement=lambda ae: (
                 self._check_iterative_refinement(conversation, ae)
             ),
-            mark_finished=lambda: setattr(
-                state,
-                "execution_status",
-                ConversationExecutionStatus.FINISHED,
-            ),
+            mark_finished=lambda: self._mark_conversation_finished(state),
         )
 
     @observe(name="agent.step", ignore_inputs=["state", "on_event"])
@@ -1594,7 +1590,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
             condenser_config = self.condenser.model_dump(
                 exclude={"llm"}, exclude_none=True
             )
-            condenser_llm_obj = getattr(self.condenser, "llm", None)
+            condenser_llm_obj = self.condenser.get_llm()
             condenser_llm = (
                 condenser_llm_obj.model if condenser_llm_obj is not None else "N/A"
             )

{openhands_sdk-1.56.0 → openhands_sdk-1.58.0}/openhands/sdk/agent/base.py

@@ -404,9 +404,7 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
             "model_family" not in template_kwargs
             or "model_variant" not in template_kwargs
         ):
-            spec = get_model_prompt_spec(
-                self.llm.model, getattr(self.llm, "model_canonical_name", None)
-            )
+            spec = get_model_prompt_spec(self.llm.model, self.llm.model_canonical_name)
             if "model_family" not in template_kwargs and spec.family:
                 template_kwargs["model_family"] = spec.family
             if "model_variant" not in template_kwargs and spec.variant:

{openhands_sdk-1.56.0 → openhands_sdk-1.58.0}/openhands/sdk/context/condenser/base.py

@@ -29,6 +29,10 @@ class CondenserBase(DiscriminatedUnionMixin, ABC):
     step the condenser will use that condensation event to produce a new `View`.
     """
 
+    def get_llm(self) -> LLM | None:
+        """The LLM used by the condenser, if any."""
+        return None
+
     @abstractmethod
     def condense(self, view: View, agent_llm: LLM | None = None) -> View | Condensation:
         """Condense a sequence of events into a potentially smaller list.

{openhands_sdk-1.56.0 → openhands_sdk-1.58.0}/openhands/sdk/context/condenser/llm_summarizing_condenser.py

@@ -112,6 +112,10 @@ class LLMSummarizingCondenser(RollingCondenser):
     def handles_condensation_requests(self) -> bool:
         return True
 
+    def get_llm(self) -> LLM | None:
+        """The LLM used by the condenser, if any."""
+        return self.llm
+
     def _effective_max_tokens(self, agent_llm: LLM | None) -> int | None:
         """Return the effective token cap that triggers token-based condensation.
 

{openhands_sdk-1.56.0 → openhands_sdk-1.58.0}/openhands/sdk/conversation/base.py

@@ -2,7 +2,7 @@ import contextlib
 from abc import ABC, abstractmethod
 from collections.abc import AsyncIterator, Iterable, Mapping
 from pathlib import Path
-from typing import TYPE_CHECKING, Protocol, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Protocol, TypeVar, cast
 
 from openhands.sdk.conversation.conversation_stats import ConversationStats
 from openhands.sdk.conversation.events_list_base import EventsListBase
@@ -45,6 +45,7 @@ def _conversation_tag_attributes(
 
 if TYPE_CHECKING:
     from openhands.sdk.agent.base import AgentBase
+    from openhands.sdk.conversation.secret_registry import SecretRegistry
     from openhands.sdk.conversation.state import ConversationExecutionStatus
     from openhands.sdk.hooks import HookConfig
 
@@ -122,6 +123,11 @@ class ConversationStateProtocol(Protocol):
         """The hook configuration for this conversation."""
         ...
 
+    @property
+    def secret_registry(self) -> "SecretRegistry":
+        """The secret registry for this conversation."""
+        ...
+
 
 class BaseConversation(ABC):
     """Abstract base class for conversation implementations.
@@ -131,9 +137,16 @@ class BaseConversation(ABC):
     exchange, execution control, and state management.
     """
 
+    _cleanup_initiated: bool = False
+    _cleanup_complete: bool = False
+    _hook_processor: Any = None
+
     def __init__(self) -> None:
         """Initialize the base conversation with span tracking."""
         self._span_ended = False
+        self._cleanup_initiated = False
+        self._cleanup_complete = False
+        self._hook_processor = None
         # Owned root span. The ``observe`` decorator looks up this attribute
         # (by name ``_observability_root_span``) on ``self`` at every entry
         # point and re-attaches it via ``Laminar.use_span`` so that nested
@@ -142,6 +155,21 @@ class BaseConversation(ABC):
         # that constructed the conversation.
         self._observability_root_span: RootSpan | None = None
 
+    @property
+    def cleanup_initiated(self) -> bool:
+        """Whether conversation cleanup has started."""
+        return self._cleanup_initiated
+
+    @property
+    def cleanup_complete(self) -> bool:
+        """Whether conversation cleanup has finished."""
+        return self._cleanup_complete
+
+    @property
+    def hook_processor(self) -> Any:
+        """The active hook processor for the conversation, if configured."""
+        return self._hook_processor
+
     def _start_observability_span(
         self,
         session_id: str,

{openhands_sdk-1.56.0 → openhands_sdk-1.58.0}/openhands/sdk/conversation/goal/controller.py

@@ -103,12 +103,14 @@ class GoalController:
     def on_run_finished(self, events: Sequence[Event]) -> GoalStep:
         """Judge the objective after a run and decide whether to continue.
 
-        Increments the iteration count, audits ``events`` with the judge LLM,
-        and returns a :class:`GoalContinue` (with a followup) or a terminal
-        :class:`GoalDone` (with a :class:`GoalOutcome`).
+        Audits ``events`` with the judge LLM, counts the round once the judge
+        has returned a verdict, and returns a :class:`GoalContinue` (with a
+        followup) or a terminal :class:`GoalDone` (with a :class:`GoalOutcome`).
+        A judge call that raises leaves the count unchanged: a failed or
+        abandoned audit is not a completed round.
         """
-        self.iteration += 1
         verdict = judge_goal(self.judge_llm, self.objective, events)
+        self.iteration += 1
         logger.info(
             "Goal audit %d/%d: score=%.2f complete=%s",
             self.iteration,

{openhands_sdk-1.56.0 → openhands_sdk-1.58.0}/openhands/sdk/conversation/impl/local_conversation.py

@@ -446,8 +446,14 @@ class LocalConversation(BaseConversation):
             # Single chokepoint: stamps parent_id (catching any event a hook
             # swapped in downstream of _tree_stamping) and advances HEAD.
             self._state.append_event(e)
+
+        def _track_last_user_message(e):
             # Track user MessageEvent IDs here so hook callbacks (which may
             # synthesize or alter user messages) are captured in one place.
+            # This runs after the caller-supplied callbacks: setting the field
+            # can emit a ConversationStateUpdateEvent through on_state_change
+            # (the agent server wires it to this chain), and that update must
+            # reach subscribers after the message that caused it.
             if isinstance(e, MessageEvent) and e.source == "user":
                 # Track the latest real user message ID for hook-blocked checks.
                 # Stop-hook feedback is emitted with source="environment".
@@ -461,7 +467,7 @@ class LocalConversation(BaseConversation):
         # list never run. The visualizer is prepended below and so still renders
         # ahead of persist — that is local terminal output, not an announcement
         # a client can act on.
-        composed_list = [_default_callback] + callback_list
+        composed_list = [_default_callback] + callback_list + [_track_last_user_message]
         # Handle visualization configuration
         if isinstance(visualizer, ConversationVisualizerBase):
             # Use custom visualizer instance
@@ -538,8 +544,8 @@ class LocalConversation(BaseConversation):
         # Idempotent with the create_request() lift; lower priority than
         # request.secrets (below). On resume, fill-if-absent so a persisted
         # value is never downgraded (or lost to redacted/no-cipher serialization).
-        if (ctx := getattr(self.agent, "agent_context", None)) is not None:
-            ctx_secrets = getattr(ctx, "secrets", None)
+        if self.agent is not None and self.agent.agent_context is not None:
+            ctx_secrets = self.agent.agent_context.secrets
             if ctx_secrets:
                 existing_sources = self._state.secret_registry.secret_sources
                 fill_secrets: dict[str, SecretValue] = {}
@@ -1605,6 +1611,13 @@ class LocalConversation(BaseConversation):
                     self._state,
                     on_event=self._on_event,
                 )
+
+                # Deliver any SessionStart additional_context now that
+                # init_state() has emitted the SystemPromptEvent, so the system
+                # prompt stays first in the LLM request. The hook processor
+                # collected it earlier during _ensure_plugins_loaded().
+                if self._hook_processor is not None:
+                    self._hook_processor.inject_pending_additional_context()
             except Exception:
                 self._close_runtime_tools(runtime_mcp_tools)
                 raise
@@ -2846,9 +2859,9 @@ class LocalConversation(BaseConversation):
 
     def close(self) -> None:
         """Close the conversation and clean up all tool executors."""
-        if getattr(self, "_cleanup_complete", False):
+        if self._cleanup_complete:
             return
-        first_attempt = not getattr(self, "_cleanup_initiated", False)
+        first_attempt = not self._cleanup_initiated
         if first_attempt:
             self._cleanup_initiated = True
 
@@ -2863,7 +2876,7 @@ class LocalConversation(BaseConversation):
                 logger.debug(f"Could not register accumulated cost: {e}")
 
             logger.debug("Closing conversation and cleaning up tool executors")
-            hook_processor = getattr(self, "_hook_processor", None)
+            hook_processor = self._hook_processor
             if hook_processor is not None:
                 hook_processor.run_session_end()
             try:

{openhands_sdk-1.56.0 → openhands_sdk-1.58.0}/openhands/sdk/conversation/impl/remote_conversation.py

@@ -29,7 +29,10 @@ from openhands.sdk.conversation.exceptions import (
     ConversationRunError,
     WebSocketConnectionError,
 )
-from openhands.sdk.conversation.secret_registry import SecretValue
+from openhands.sdk.conversation.secret_registry import (
+    SecretRegistry,
+    SecretValue,
+)
 from openhands.sdk.conversation.state import ConversationExecutionStatus
 from openhands.sdk.conversation.title_utils import generate_conversation_title
 from openhands.sdk.conversation.types import (
@@ -719,6 +722,15 @@ class RemoteState(ConversationStateProtocol):
             return HookConfig.model_validate(hook_config_data)
         return None
 
+    @property
+    def secret_registry(self) -> SecretRegistry:
+        """The secret registry for this conversation."""
+        info = self._get_conversation_info()
+        secret_registry_data = info.get("secret_registry")
+        if secret_registry_data is not None:
+            return SecretRegistry.model_validate(secret_registry_data)
+        return SecretRegistry()
+
     def model_dump(self, **_kwargs):
         """Get a dictionary representation of the remote state."""
         info = self._get_conversation_info()
@@ -817,6 +829,7 @@ class RemoteConversation(BaseConversation):
             token_callbacks: Optional callbacks invoked with each streamed token
                       delta the server sends (agent LLM with ``stream=True``).
         """
+        super().__init__()
         observability_metadata = merge_observability_metadata(observability_metadata)
         observability_parent_span_context = (
             observability_parent_span_context
@@ -1917,52 +1930,55 @@ class RemoteConversation(BaseConversation):
         The workspace owns the client and will close it during its own cleanup.
         Closing it here would prevent the workspace from making cleanup API calls.
         """
-        if self._cleanup_initiated:
+        if self._cleanup_complete:
             return
-        self._cleanup_initiated = True
-
-        # Best-effort: hand the accumulated LLM cost to the workspace so it can
-        # be included in the automation completion callback. Only read cached
-        # state — close() also runs on the failure path, where a live fetch
-        # could block until timeout against an agent server that is already gone.
-        # The cache tracks this run: the agent server streams a "stats" update
-        # after every LLM response (EventService._setup_stats_streaming), so it
-        # holds the run's spend even on the failure path, which wakes run() from
-        # a per-field ERROR/STUCK update before the post-run full-state snapshot.
-        try:
-            cached = self._state._cached_state
-            # Require an actual "stats" entry: a cache built only from partial
-            # field updates — e.g. the subscribe-time push for a service with no
-            # live conversation — would otherwise yield 0.0 and record a run as
-            # free when its cost is really just unknown.
-            if cached is not None and "stats" in cached:
-                cost = self._state.stats.get_combined_metrics().accumulated_cost
-                self.workspace.register_cost(cost)
-        except Exception as e:
-            logger.debug(f"Could not register accumulated cost: {e}")
-
-        # SessionEnd hooks are executed server-side (via hook_config in payload).
-        try:
-            # Stop WebSocket client if it exists
-            if self._ws_client:
-                self._ws_client.stop()
-                self._ws_client = None
-        except Exception:
-            pass
+        first_attempt = not self._cleanup_initiated
+        if first_attempt:
+            self._cleanup_initiated = True
+
+            # Best-effort: hand the accumulated LLM cost to the workspace so it can
+            # be included in the automation completion callback. Only read cached
+            # state — close() also runs on the failure path, where a live fetch
+            # could block until timeout against an agent server that is already gone.
+            # The cache tracks this run: the agent server streams a "stats" update
+            # after every LLM response (EventService._setup_stats_streaming), so it
+            # holds the run's spend even on the failure path, which wakes run() from
+            # a per-field ERROR/STUCK update before the post-run full-state snapshot.
+            try:
+                cached = self._state._cached_state
+                # Require an actual "stats" entry: a cache built only from partial
+                # field updates — e.g. the subscribe-time push for a service with no
+                # live conversation — would otherwise yield 0.0 and record a run as
+                # free when its cost is really just unknown.
+                if cached is not None and "stats" in cached:
+                    cost = self._state.stats.get_combined_metrics().accumulated_cost
+                    self.workspace.register_cost(cost)
+            except Exception as e:
+                logger.debug(f"Could not register accumulated cost: {e}")
 
-        self._end_observability_span()
-        if self.delete_on_close:
+            # SessionEnd hooks are executed server-side (via hook_config in payload).
             try:
-                # trigger server-side delete_conversation to release resources
-                # like tmux sessions
-                _send_request(
-                    self._client,
-                    "DELETE",
-                    f"{CONVERSATIONS_PATH}/{self.id}",
-                )
+                # Stop WebSocket client if it exists
+                if self._ws_client:
+                    self._ws_client.stop()
+                    self._ws_client = None
             except Exception:
                 pass
 
+            self._end_observability_span()
+            if self.delete_on_close:
+                try:
+                    # trigger server-side delete_conversation to release resources
+                    # like tmux sessions
+                    _send_request(
+                        self._client,
+                        "DELETE",
+                        f"{CONVERSATIONS_PATH}/{self.id}",
+                    )
+                except Exception:
+                    pass
+        self._cleanup_complete = True
+
     def __del__(self) -> None:
         try:
             self.close()

{openhands_sdk-1.56.0 → openhands_sdk-1.58.0}/openhands/sdk/conversation/request.py

@@ -41,7 +41,16 @@ from openhands.sdk.security.confirmation_policy import (
     ConfirmationPolicyBase,
     NeverConfirm,
 )
-from openhands.sdk.settings.model import validate_agent_settings
+from openhands.sdk.settings.model import (
+    DEFAULT_WORKTREE_BRANCH_PREFIX,
+    DOCKER_MEMORY_PATTERN,
+    GIT_BRANCH_PREFIX_PATTERN,
+    GIT_REF_PATTERN,
+    MIN_CONTAINER_CPUS,
+    ConversationRuntime,
+    WorktreeBase,
+    validate_agent_settings,
+)
 from openhands.sdk.skills import Skill
 from openhands.sdk.subagent.schema import AgentDefinition
 from openhands.sdk.tool.client_tool import ClientToolSpec
@@ -151,6 +160,68 @@ class AgentLaunchAdditions(BaseModel):
     )
 
 
+class ConversationContainerOptions(BaseModel):
+    """Resources for a conversation's container.
+
+    Only the Docker runtime applies them, when it creates the conversation's
+    container; a local conversation ignores them. An unset field keeps the
+    server's configured limit; a set one replaces it and is not capped by it.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    memory: str | None = Field(
+        default=None,
+        pattern=DOCKER_MEMORY_PATTERN,
+        description=(
+            "Container memory limit in `docker run --memory` syntax; replaces "
+            "the server's limit and is not capped by it."
+        ),
+    )
+    cpus: float | None = Field(
+        default=None,
+        ge=MIN_CONTAINER_CPUS,
+        description=(
+            "Number of CPUs the container may use (`docker run --cpus`); "
+            "replaces the server's limit and is not capped by it."
+        ),
+    )
+    browser: bool = Field(
+        default=True,
+        description=(
+            "False turns the browser off. True cannot turn it on for an image "
+            "without one."
+        ),
+    )
+
+
+class ConversationWorktreeOptions(BaseModel):
+    """How the server creates a conversation's worktree (``worktree=True``)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    base: WorktreeBase = Field(
+        default="default_branch",
+        description="What the worktree branches from; `ref` uses `ref`.",
+    )
+    ref: str | None = Field(
+        default=None,
+        pattern=GIT_REF_PATTERN,
+        description="Branch, tag or commit to branch from when `base` is `ref`.",
+    )
+    branch_prefix: str = Field(
+        default=DEFAULT_WORKTREE_BRANCH_PREFIX,
+        pattern=GIT_BRANCH_PREFIX_PATTERN,
+        description="Start of the worktree's branch name; the conversation id ends it.",
+    )
+
+    @model_validator(mode="after")
+    def _ref_for_ref_base(self) -> ConversationWorktreeOptions:
+        if self.base == "ref" and self.ref is None:
+            raise ValueError("A `ref` base needs a `ref`")
+        return self
+
+
 class ConversationConfig(BaseModel):
     """Shared conversation configuration — everything except the agent.
 
@@ -175,6 +246,10 @@ class ConversationConfig(BaseModel):
             "`/tmp/conversation-worktrees/<conversation_id>/<project_name>`."
         ),
     )
+    worktree_options: ConversationWorktreeOptions | None = Field(
+        default=None,
+        description="How the worktree is created (`worktree=True`); unset: defaults.",
+    )
     conversation_id: UUID | None = Field(
         default=None,
         description=(
@@ -346,6 +421,17 @@ class ConversationConfig(BaseModel):
             "the agent's LLM."
         ),
     )
+    prompt: str | None = Field(
+        default=None,
+        max_length=2000,
+        description=(
+            "Optional prompt that replaces the default title-generation user "
+            "message. Use {conversation_content} to place the first user "
+            "message and {max_length} to place the title length limit. If the "
+            "conversation placeholder is omitted, the message is appended "
+            "automatically. Empty or unset values use the default prompt."
+        ),
+    )
 
 
 class StartConversationRequest(ConversationConfig):
@@ -379,6 +465,18 @@ class StartConversationRequest(ConversationConfig):
         ),
     )
     agent: AgentBase = Field(default=cast(AgentBase, None))
+    conversation_runtime: ConversationRuntime | None = Field(
+        default=None,
+        description=(
+            "Runtime that executes this conversation. Unset uses the server's "
+            "configured `conversation_runtime`; another value is only accepted "
+            "when the server lists it in `available_conversation_runtimes`."
+        ),
+    )
+    container: ConversationContainerOptions | None = Field(
+        default=None,
+        description="Resources for the conversation's container (Docker runtime).",
+    )
 
     @model_validator(mode="before")
     @classmethod

{openhands_sdk-1.56.0 → openhands_sdk-1.58.0}/openhands/sdk/conversation/state.py

@@ -5,7 +5,7 @@ from collections.abc import Callable, Sequence
 from contextlib import AbstractContextManager
 from enum import Enum
 from pathlib import Path
-from typing import Any, Self
+from typing import Any, Self, cast
 
 from pydantic import Field, PrivateAttr
 
@@ -230,7 +230,7 @@ class ConversationState(OpenHandsModel):
     )
 
     # ===== Private attrs (NOT Fields) =====
-    _fs: FileStore = PrivateAttr()  # filestore for persistence
+    _fs: FileStore = PrivateAttr(default=cast(Any, None))  # filestore for persistence
     _events: EventLog = PrivateAttr()  # now the storage for events
     # Cached projection of `_events` for the *active branch*, lazily updated on
     # read. Derived state — never persisted. `_view_branch_leaf` is the resolved
@@ -603,8 +603,8 @@ class ConversationState(OpenHandsModel):
         super().__setattr__(name, value)
 
         is_field = name in self.__class__.model_fields
-        autosave_enabled = getattr(self, "_autosave_enabled", False)
-        fs = getattr(self, "_fs", None)
+        autosave_enabled = self._autosave_enabled
+        fs = self._fs
 
         if not (autosave_enabled and is_field and fs is not None):
             return
@@ -612,7 +612,7 @@ class ConversationState(OpenHandsModel):
         if old is _sentinel or old != value:
             # Inside a context-manager block, defer the save until __exit__
             # so that multiple field mutations produce a single I/O write.
-            if getattr(self, "_save_depth", 0) > 0:
+            if self._save_depth > 0:
                 self._dirty = True
             else:
                 try:
@@ -625,7 +625,7 @@ class ConversationState(OpenHandsModel):
             # skipped: they are internal HEAD bookkeeping (leaf_event_id changes
             # every event, so broadcasting it would ~double the persisted log) and
             # the HEAD is recoverable from the just-appended event.
-            callback = getattr(self, "_on_state_change", None)
+            callback = self._on_state_change
             if (
                 callback is not None
                 and old is not _sentinel
@@ -755,8 +755,8 @@ class ConversationState(OpenHandsModel):
         try:
             self._save_depth -= 1
             if self._save_depth == 0 and self._dirty:
-                fs = getattr(self, "_fs", None)
-                autosave_enabled = getattr(self, "_autosave_enabled", False)
+                fs = self._fs
+                autosave_enabled = self._autosave_enabled
                 if autosave_enabled and fs is not None:
                     self._save_base_state(fs)
                 self._dirty = False

{openhands_sdk-1.56.0 → openhands_sdk-1.58.0}/openhands/sdk/conversation/title_utils.py

@@ -2,6 +2,7 @@
 
 import re
 from collections.abc import Callable, Sequence
+from typing import Final
 
 from openhands.sdk.event import MessageEvent
 from openhands.sdk.event.base import Event
@@ -30,6 +31,9 @@ categories = [
     {"emoji": "♻️", "name": "refactor", "description": "Code refactoring"},
 ]
 
+CONVERSATION_CONTENT_PLACEHOLDER: Final[str] = "{conversation_content}"
+MAX_LENGTH_PLACEHOLDER: Final[str] = "{max_length}"
+
 
 def extract_message_text(event: MessageEvent) -> str | None:
     """Extract plain-text content from a message event."""
@@ -83,6 +87,7 @@ def generate_title_with_llm(
     *,
     call_context: LLMCallContext | None = None,
     on_error: Callable[[Exception], None] | None = None,
+    prompt: str | None = None,
 ) -> str | None:
     """Generate a conversation title using LLM.
 
@@ -93,6 +98,10 @@ def generate_title_with_llm(
         on_error: Optional callback invoked with the exception when the LLM
             call fails. Title generation still falls back (returns None); the
             callback lets callers surface the otherwise-swallowed error.
+        prompt: Optional user-message prompt override. The
+            ``{conversation_content}`` and ``{max_length}`` placeholders are
+            replaced when present. If the conversation placeholder is omitted,
+            the message content is appended automatically.
 
     Returns:
         Generated title, or None if LLM fails or returns empty response.
@@ -107,6 +116,23 @@ def generate_title_with_llm(
         f"{c['emoji']} {c['name']}: {c['description']}" for c in categories
     )
 
+    template = (prompt or "").strip()
+    if template:
+        user_prompt = template.replace(
+            CONVERSATION_CONTENT_PLACEHOLDER, truncated_message
+        ).replace(MAX_LENGTH_PLACEHOLDER, str(max_length))
+        if CONVERSATION_CONTENT_PLACEHOLDER not in template:
+            user_prompt = f"{user_prompt}\n\nConversation content:\n{truncated_message}"
+    else:
+        user_prompt = (
+            f"Generate a title (maximum {max_length} characters) "
+            f"for a conversation that starts with this message:\n\n"
+            f"{truncated_message}."
+            "Also make sure to include ONE most relevant emoji at "
+            "the start of the title."
+            f" Choose the emoji from this list:{emojis_descriptions} "
+        )
+
     try:
         # Create messages for the LLM to generate a title
         messages = [
@@ -130,18 +156,7 @@ def generate_title_with_llm(
             ),
             Message(
                 role="user",
-                content=[
-                    TextContent(
-                        text=(
-                            f"Generate a title (maximum {max_length} characters) "
-                            f"for a conversation that starts with this message:\n\n"
-                            f"{truncated_message}."
-                            "Also make sure to include ONE most relevant emoji at "
-                            "the start of the title."
-                            f" Choose the emoji from this list:{emojis_descriptions} "
-                        )
-                    )
-                ],
+                content=[TextContent(text=user_prompt)],
             ),
         ]
 
@@ -204,6 +219,7 @@ def generate_title_from_message(
     *,
     call_context: LLMCallContext | None = None,
     on_error: Callable[[Exception], None] | None = None,
+    prompt: str | None = None,
 ) -> str:
     """Generate a title from an already-extracted user message."""
     # Skip the ACP sentinel LLM — it has no credentials and cannot be
@@ -218,6 +234,7 @@ def generate_title_from_message(
             max_length,
             call_context=call_context,
             on_error=on_error,
+            prompt=prompt,
         )
         if llm_title:
             return llm_title