openhands-sdk 1.50.1__tar.gz → 1.52.0__tar.gz

{openhands_sdk-1.50.1 → openhands_sdk-1.52.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.50.1
+Version: 1.52.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
@@ -17,8 +17,8 @@ Requires-Dist: jsonschema>=4.23.0
 Requires-Dist: joserfc>=1.7.5
 Requires-Dist: litellm>=1.93.0
 Requires-Dist: pillow>=12.3.0
-Requires-Dist: pydantic>=2.12.5
-Requires-Dist: python-frontmatter>=1.1.0
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: python-frontmatter>=1.3.0
 Requires-Dist: python-json-logger>=3.3.0
 Requires-Dist: tenacity>=9.1.2
 Requires-Dist: websockets>=12

{openhands_sdk-1.50.1 → openhands_sdk-1.52.0}/openhands/sdk/agent/agent.py

@@ -7,7 +7,7 @@ from collections.abc import Callable
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any
 
-from pydantic import PrivateAttr, ValidationError, model_validator
+from pydantic import Field, PrivateAttr, ValidationError, model_validator
 
 import openhands.sdk.security.analyzer as analyzer
 import openhands.sdk.security.risk as risk
@@ -452,6 +452,17 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
             )
     """
 
+    persona: str | None = Field(
+        default=None,
+        description=(
+            "Persona text that replaces OpenHands' built-in persona and "
+            "coding-workflow sections of the system prompt. Capability and policy "
+            "sections (memory, security policy, risk assessment, browser, external "
+            "services, process management, model-specific guidance) and the dynamic "
+            "context still apply. Ignored when `system_prompt` is set; a custom "
+            "template receives it as the `persona` kwarg."
+        ),
+    )
     _parallel_executor: ParallelToolExecutor = PrivateAttr(
         default_factory=ParallelToolExecutor
     )
@@ -462,6 +473,12 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
             max_workers=self.tool_concurrency_limit
         )
 
+    def _resolved_template_kwargs(self) -> dict[str, object]:
+        template_kwargs = super()._resolved_template_kwargs()
+        if self.persona is not None:
+            template_kwargs["persona"] = self.persona
+        return template_kwargs
+
     @model_validator(mode="before")
     @classmethod
     def _add_security_prompt_as_default(cls, data):

{openhands_sdk-1.50.1 → openhands_sdk-1.52.0}/openhands/sdk/agent/base.py

@@ -16,6 +16,7 @@ from pydantic import (
     ConfigDict,
     Field,
     PrivateAttr,
+    field_validator,
     model_validator,
 )
 
@@ -32,6 +33,7 @@ from openhands.sdk.mcp.client import MCPClient
 from openhands.sdk.mcp.config import MCPServer
 from openhands.sdk.mcp.tool import MCPToolDefinition, MCPToolExecutor
 from openhands.sdk.tool import (
+    BROWSER_TOOL_NAME,
     BUILT_IN_TOOL_CLASSES,
     BUILT_IN_TOOLS,
     Tool,
@@ -43,6 +45,7 @@ from openhands.sdk.tool.builtins.vision_inspect import (
     VisionInspectTool,
     has_vision_profile_available,
 )
+from openhands.sdk.utils.deprecation import warn_deprecated
 from openhands.sdk.utils.models import DiscriminatedUnionMixin
 from openhands.sdk.utils.path import get_user_persistence_dir
 
@@ -263,6 +266,24 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
             )
         return data
 
+    @field_validator("system_prompt_kwargs")
+    @classmethod
+    def _warn_deprecated_enable_browser(
+        cls, value: dict[str, object]
+    ) -> dict[str, object]:
+        if "enable_browser" in value:
+            warn_deprecated(
+                "system_prompt_kwargs['enable_browser']",
+                deprecated_in="1.51.0",
+                removed_in="1.56.0",
+                details=(
+                    "Browser guidance now comes from the loaded browser tools; "
+                    "only custom Jinja templates still read this kwarg."
+                ),
+                stacklevel=5,
+            )
+        return value
+
     condenser: CondenserBase | None = Field(
         default=None,
         description="Optional condenser to use for condensing conversation history.",
@@ -343,27 +364,41 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         Built-in prompts (the ``default`` and ``planning`` presets) are assembled from
         the typed section registry, which also resolves a custom
         ``security_policy_filename``. Escape hatches keep the Jinja path: an inline
-        ``system_prompt`` is returned verbatim; a custom ``system_prompt_filename`` or
-        subclass ``prompt_dir`` renders its own template.
+        ``system_prompt`` is used verbatim, followed by the loaded tools' guidance; a
+        custom ``system_prompt_filename`` or subclass ``prompt_dir`` renders its own
+        template.
 
         Returns:
             The static system prompt without dynamic context.
         """
         if self.system_prompt is not None:
-            return self.system_prompt
+            return "\n\n".join((self.system_prompt, *self._tool_guidance()))
 
         # Escape hatch: a custom filename or a subclass's own prompt_dir renders its
         # own Jinja template; everything else (incl. custom policies) uses the registry.
         preset = self._prompt_preset
         if preset is None:
+            # Deprecated kwarg, kept until 1.56.0 for templates that branch on it.
+            template_kwargs = {
+                "enable_browser": any(t.name == BROWSER_TOOL_NAME for t in self.tools),
+                **self._resolved_template_kwargs(),
+            }
             return render_template(
                 prompt_dir=self.prompt_dir,
                 template_name=self.system_prompt_filename,
-                **self._resolved_template_kwargs(),
+                **template_kwargs,
             )
 
         return create_registry(preset).build(self._build_prompt_context()).static
 
+    def _tool_guidance(self) -> tuple[str, ...]:
+        """Distinct ``prompt_guidance`` texts of the loaded tools, in tool order."""
+        with self._tools_lock:
+            tools = list(self._tools.values())
+        return tuple(
+            dict.fromkeys(t.prompt_guidance for t in tools if t.prompt_guidance)
+        )
+
     def _resolved_template_kwargs(self) -> dict[str, object]:
         """Resolve the system-prompt template kwargs.
 
@@ -376,10 +411,6 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         if "soul_content" not in template_kwargs:
             template_kwargs["soul_content"] = _load_soul_md()
 
-        template_kwargs.setdefault(
-            "enable_browser",
-            any(t.name == "browser_tool_set" for t in self.tools),
-        )
         template_kwargs.setdefault(
             "memory_enabled",
             self.agent_context is not None and self.agent_context.load_memory,
@@ -484,6 +515,7 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         return PromptContext(
             template_kwargs=template_kwargs,
             tool_names=tuple(t.name for t in self.tools),
+            tool_guidance=self._tool_guidance(),
             platform=Platform.current(),
             working_dir=None,
             now=now,

openhands_sdk-1.52.0/openhands/sdk/automation/__init__.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from typing import NotRequired, TypedDict
+
+from openhands.sdk.conversation.types import TraceMetadataValue
+from openhands.sdk.logger import get_logger
+from openhands.sdk.observability.laminar import (
+    default_observability_span_name_from_env,
+    observability_metadata_from_env,
+    observability_parent_span_context_from_env,
+    observability_tags_from_env,
+)
+
+
+logger = get_logger(__name__)
+
+_AUTOMATION_ID_KEY = "automation.id"
+_AUTOMATION_NAME_KEY = "automation.name"
+_AUTOMATION_RUN_ID_KEY = "automation.run_id"
+_AUTOMATION_TRIGGER_SOURCE_KEY = "automation.trigger_source"
+_DEFAULT_AUTOMATION_SPAN_NAME = "automation.conversation"
+
+
+class AutomationObservabilityContext(TypedDict):
+    observability_metadata: NotRequired[dict[str, TraceMetadataValue]]
+    observability_tags: NotRequired[list[str]]
+    observability_span_name: NotRequired[str]
+    observability_parent_span_context: NotRequired[str]
+
+
+class AutomationConversationKwargs(AutomationObservabilityContext, total=False):
+    tags: dict[str, str]
+
+
+def _merge_metadata(
+    metadata: Mapping[str, TraceMetadataValue] | None,
+) -> dict[str, TraceMetadataValue]:
+    merged = observability_metadata_from_env()
+    if metadata:
+        merged.update(dict(metadata))
+    return merged
+
+
+def _merge_tags(tags: Sequence[str] | None) -> list[str]:
+    merged: list[str] = []
+    seen: set[str] = set()
+    for tag in [*observability_tags_from_env(), *(tags or [])]:
+        tag = tag.strip()
+        if tag and tag not in seen:
+            seen.add(tag)
+            merged.append(tag)
+    return merged
+
+
+def _metadata_str(metadata: Mapping[str, TraceMetadataValue], key: str) -> str | None:
+    value = metadata.get(key)
+    if value is None or isinstance(value, bool | list):
+        return None
+    return str(value)
+
+
+def automation_observability_context(
+    *,
+    metadata: Mapping[str, TraceMetadataValue] | None = None,
+    tags: Sequence[str] | None = None,
+    span_name: str | None = None,
+    parent_span_context: str | None = None,
+) -> AutomationObservabilityContext:
+    """Collect generic automation observability fields for SDK conversations.
+
+    The automation service owns automation-specific values and supplies them via
+    generic ``OPENHANDS_OBSERVABILITY_*`` environment variables. This helper
+    collects those generic values and merges caller-provided additions, so custom
+    automation scripts do not need to duplicate the boilerplate for every
+    ``Conversation(...)`` call.
+    """
+    context: AutomationObservabilityContext = {}
+
+    merged_metadata = _merge_metadata(metadata)
+    if merged_metadata:
+        context["observability_metadata"] = merged_metadata
+
+    merged_tags = _merge_tags(tags)
+    if merged_tags:
+        context["observability_tags"] = merged_tags
+
+    resolved_span_name = span_name or default_observability_span_name_from_env()
+    if resolved_span_name:
+        context["observability_span_name"] = resolved_span_name
+
+    resolved_parent_context = (
+        parent_span_context or observability_parent_span_context_from_env()
+    )
+    if resolved_parent_context:
+        context["observability_parent_span_context"] = resolved_parent_context
+
+    return context
+
+
+def automation_conversation_tags(
+    metadata: Mapping[str, TraceMetadataValue] | None = None,
+) -> dict[str, str]:
+    """Build product conversation tags from automation observability metadata."""
+    merged_metadata = _merge_metadata(metadata)
+    tags: dict[str, str] = {}
+
+    automation_id = _metadata_str(merged_metadata, _AUTOMATION_ID_KEY)
+    automation_name = _metadata_str(merged_metadata, _AUTOMATION_NAME_KEY)
+    automation_run_id = _metadata_str(merged_metadata, _AUTOMATION_RUN_ID_KEY)
+    trigger_source = _metadata_str(merged_metadata, _AUTOMATION_TRIGGER_SOURCE_KEY)
+
+    if automation_id or automation_name or automation_run_id or trigger_source:
+        tags["automationtrigger"] = "automation"
+    if automation_id:
+        tags["automationid"] = automation_id
+    if automation_name:
+        tags["automationname"] = automation_name
+    if automation_run_id:
+        tags["automationrunid"] = automation_run_id
+
+    return tags
+
+
+def automation_conversation_kwargs(
+    *,
+    metadata: Mapping[str, TraceMetadataValue] | None = None,
+    observability_tags: Sequence[str] | None = None,
+    conversation_tags: Mapping[str, str] | None = None,
+    span_name: str | None = None,
+    parent_span_context: str | None = None,
+    include_conversation_tags: bool = True,
+) -> AutomationConversationKwargs:
+    """Return kwargs to pass into ``Conversation(...)`` from an automation script.
+
+    Example:
+        ``Conversation(..., **automation_conversation_kwargs())``
+    """
+    kwargs: AutomationConversationKwargs = {}
+    resolved_span_name = (
+        span_name
+        or default_observability_span_name_from_env()
+        or _DEFAULT_AUTOMATION_SPAN_NAME
+    )
+    context = automation_observability_context(
+        metadata=metadata,
+        tags=observability_tags,
+        span_name=resolved_span_name,
+        parent_span_context=parent_span_context,
+    )
+    if context_metadata := context.get("observability_metadata"):
+        kwargs["observability_metadata"] = context_metadata
+    if context_tags := context.get("observability_tags"):
+        kwargs["observability_tags"] = context_tags
+    if context_span_name := context.get("observability_span_name"):
+        kwargs["observability_span_name"] = context_span_name
+    if context_parent := context.get("observability_parent_span_context"):
+        kwargs["observability_parent_span_context"] = context_parent
+
+    if include_conversation_tags:
+        merged_conversation_tags = automation_conversation_tags(metadata)
+        if conversation_tags:
+            merged_conversation_tags.update(dict(conversation_tags))
+        if merged_conversation_tags:
+            kwargs["tags"] = merged_conversation_tags
+
+    return kwargs
+
+
+def automation_observability_headers(
+    *,
+    metadata: Mapping[str, TraceMetadataValue] | None = None,
+    tags: Sequence[str] | None = None,
+    span_name: str | None = None,
+    parent_span_context: str | None = None,
+) -> dict[str, str]:
+    """Return observability headers for direct agent-server API calls."""
+    context = automation_observability_context(
+        metadata=metadata,
+        tags=tags,
+        span_name=span_name,
+        parent_span_context=parent_span_context,
+    )
+    headers: dict[str, str] = {}
+    if context_metadata := context.get("observability_metadata"):
+        headers["X-OpenHands-Observability-Metadata"] = json.dumps(
+            context_metadata, separators=(",", ":")
+        )
+    if context_tags := context.get("observability_tags"):
+        headers["X-OpenHands-Observability-Tags"] = ",".join(context_tags)
+    if context_span_name := context.get("observability_span_name"):
+        headers["X-OpenHands-Observability-Span-Name"] = context_span_name
+    if context_parent := context.get("observability_parent_span_context"):
+        headers["X-OpenHands-Observability-Parent-Span-Context"] = context_parent
+
+    try:
+        from opentelemetry.propagate import inject
+
+        inject(headers)
+    except Exception:
+        logger.debug(
+            "Failed to inject OpenTelemetry propagation headers", exc_info=True
+        )
+    return headers
+
+
+__all__ = [
+    "AutomationConversationKwargs",
+    "AutomationObservabilityContext",
+    "automation_conversation_kwargs",
+    "automation_conversation_tags",
+    "automation_observability_context",
+    "automation_observability_headers",
+]

{openhands_sdk-1.50.1 → openhands_sdk-1.52.0}/openhands/sdk/context/prompts/presets.py

@@ -10,11 +10,16 @@ repo/skills/suffix/secrets/datetime are preset-independent -- so a planning agen
 with an ``agent_context`` still gets its dynamic block.
 """
 
+from dataclasses import dataclass, field
 from enum import StrEnum
 from typing import Final
 
 from openhands.sdk.context.prompts.registry import PromptRegistry
-from openhands.sdk.context.prompts.section import PromptSection
+from openhands.sdk.context.prompts.section import (
+    CacheTier,
+    PromptContext,
+    PromptSection,
+)
 from openhands.sdk.context.prompts.sections.dynamic import (
     AvailableSkillsSection,
     CustomSecretsSection,
@@ -25,7 +30,6 @@ from openhands.sdk.context.prompts.sections.dynamic import (
 )
 from openhands.sdk.context.prompts.sections.planning import PlanningSection
 from openhands.sdk.context.prompts.sections.static import (
-    BrowserSection,
     CodeQualitySection,
     EfficiencySection,
     EnvironmentSetupSection,
@@ -33,6 +37,7 @@ from openhands.sdk.context.prompts.sections.static import (
     FileSystemSection,
     MemorySection,
     ModelSpecificSection,
+    PersonaSection,
     ProblemSolvingSection,
     ProcessManagementSection,
     PullRequestsSection,
@@ -41,6 +46,7 @@ from openhands.sdk.context.prompts.sections.static import (
     SecuritySection,
     SelfDocumentationSection,
     SoulSection,
+    ToolGuidanceSection,
     TroubleshootingSection,
     VersionControlSection,
 )
@@ -56,28 +62,50 @@ class PromptPreset(StrEnum):
     PLANNING = "planning"
 
 
+@dataclass(frozen=True, slots=True)
+class _ReplacedByPersona:
+    """A persona-layer section: dropped when the agent supplies its own persona."""
+
+    section: PromptSection
+    name: str = field(init=False)
+    cache_tier: CacheTier = field(init=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "name", self.section.name)
+        object.__setattr__(self, "cache_tier", self.section.cache_tier)
+
+    def guard(self, ctx: PromptContext) -> bool:
+        return ctx.persona is None and self.section.guard(ctx)
+
+    def render(self, ctx: PromptContext) -> str | None:
+        return self.section.render(ctx)
+
+
 _DEFAULT_STATIC_SECTIONS: Final[tuple[PromptSection, ...]] = (
-    SoulSection(),
-    RoleSection(),
+    PersonaSection(),  # guard: persona set
+    _ReplacedByPersona(SoulSection()),
+    _ReplacedByPersona(RoleSection()),
     MemorySection(),
-    EfficiencySection(),
-    FileSystemSection(),
-    CodeQualitySection(),
-    VersionControlSection(),
-    PullRequestsSection(),
-    ProblemSolvingSection(),
-    SelfDocumentationSection(),
+    _ReplacedByPersona(EfficiencySection()),
+    _ReplacedByPersona(FileSystemSection()),
+    _ReplacedByPersona(CodeQualitySection()),
+    _ReplacedByPersona(VersionControlSection()),
+    _ReplacedByPersona(PullRequestsSection()),
+    _ReplacedByPersona(ProblemSolvingSection()),
+    _ReplacedByPersona(SelfDocumentationSection()),
     SecuritySection(),  # guard: security_policy_filename set
     SecurityRiskAssessmentSection(),  # guard: llm_security_analyzer
-    BrowserSection(),  # guard: ctx.enable_browser
+    ToolGuidanceSection(),  # guard: loaded tools supply prompt_guidance
     ExternalServicesSection(),
-    EnvironmentSetupSection(),
-    TroubleshootingSection(),
+    _ReplacedByPersona(EnvironmentSetupSection()),
+    _ReplacedByPersona(TroubleshootingSection()),
     ProcessManagementSection(),
     ModelSpecificSection(),  # guard: model_family resolved
 )
-
-_PLANNING_STATIC_SECTIONS: Final[tuple[PromptSection, ...]] = (PlanningSection(),)
+_PLANNING_STATIC_SECTIONS: Final[tuple[PromptSection, ...]] = (
+    PersonaSection(),
+    PlanningSection(),
+)
 
 _DYNAMIC_SECTIONS: Final[tuple[PromptSection, ...]] = (
     RepoContextSection(),  # guard: gated repo skills present

{openhands_sdk-1.50.1 → openhands_sdk-1.52.0}/openhands/sdk/context/prompts/section.py

@@ -53,8 +53,8 @@ class PromptContext(BaseModel):
     """Frozen snapshot of everything that shapes a system prompt.
 
     ``template_kwargs`` is the resolved kwarg dict for the static, cache-stable
-    block; the other fields snapshot per-conversation signals. ``enable_browser``
-    / ``model_family`` / ``cli_mode`` are typed views over ``template_kwargs``.
+    block; the other fields snapshot per-conversation signals. ``model_family`` /
+    ``cli_mode`` are typed views over ``template_kwargs``.
     """
 
     model_config = ConfigDict(frozen=True)
@@ -63,6 +63,7 @@ class PromptContext(BaseModel):
         default_factory=dict, validate_default=True
     )
     tool_names: tuple[str, ...] = Field(default_factory=tuple)
+    tool_guidance: tuple[str, ...] = Field(default_factory=tuple)
     platform: Platform = Field(default_factory=Platform.current)
     working_dir: str | None = None
     now: str | None = None
@@ -86,10 +87,6 @@ class PromptContext(BaseModel):
         # store a read-only copy so the snapshot and its views cannot drift.
         return MappingProxyType(dict(value))
 
-    @property
-    def enable_browser(self) -> bool:
-        return bool(self.template_kwargs.get("enable_browser", False))
-
     @property
     def model_family(self) -> str | None:
         value = self.template_kwargs.get("model_family")
@@ -99,6 +96,11 @@ class PromptContext(BaseModel):
     def cli_mode(self) -> bool:
         return bool(self.template_kwargs.get("cli_mode", False))
 
+    @property
+    def persona(self) -> str | None:
+        value = self.template_kwargs.get("persona")
+        return value if isinstance(value, str) and value.strip() else None
+
 
 @runtime_checkable
 class PromptSection(Protocol):
@@ -109,17 +111,20 @@ class PromptSection(Protocol):
     :meth:`guard` decides whether the section applies (if ``False`` it is
     skipped and :meth:`render` never runs), then :meth:`render` produces the
     text. The split is intentional -- ``guard`` returning ``False`` means "not
-    applicable here" (e.g. browser disabled, wrong platform), while ``render``
-    returning ``None`` means "applicable, but nothing to add right now" (e.g. no
-    skills present).
+    applicable here" (e.g. security policy disabled), while ``render`` returning
+    ``None`` means "applicable, but nothing to add right now" (e.g. no skills
+    present).
 
     Both must be pure -- read-only on ``ctx``, no I/O -- so sections are
     testable in isolation. ``name`` is the registry's unique key for
     dedup/override; ``cache_tier`` selects the static or dynamic block.
     """
 
-    name: str
-    cache_tier: CacheTier
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def cache_tier(self) -> CacheTier: ...
 
     def guard(self, ctx: PromptContext) -> bool:
         """Return ``True`` if this section applies to ``ctx``."""

{openhands_sdk-1.50.1 → openhands_sdk-1.52.0}/openhands/sdk/context/prompts/sections/__init__.py

@@ -17,7 +17,6 @@ from openhands.sdk.context.prompts.sections.dynamic import (
 )
 from openhands.sdk.context.prompts.sections.planning import PlanningSection
 from openhands.sdk.context.prompts.sections.static import (
-    BrowserSection,
     CodeQualitySection,
     EfficiencySection,
     EnvironmentSetupSection,
@@ -25,6 +24,7 @@ from openhands.sdk.context.prompts.sections.static import (
     FileSystemSection,
     MemorySection,
     ModelSpecificSection,
+    PersonaSection,
     ProblemSolvingSection,
     ProcessManagementSection,
     PullRequestsSection,
@@ -33,6 +33,7 @@ from openhands.sdk.context.prompts.sections.static import (
     SecuritySection,
     SelfDocumentationSection,
     SoulSection,
+    ToolGuidanceSection,
     TroubleshootingSection,
     VersionControlSection,
 )
@@ -40,7 +41,6 @@ from openhands.sdk.context.prompts.sections.static import (
 
 __all__ = [
     "AvailableSkillsSection",
-    "BrowserSection",
     "CodeQualitySection",
     "CustomSecretsSection",
     "CustomSuffixSection",
@@ -52,6 +52,7 @@ __all__ = [
     "MemoryContextSection",
     "MemorySection",
     "ModelSpecificSection",
+    "PersonaSection",
     "PlanningSection",
     "ProblemSolvingSection",
     "ProcessManagementSection",
@@ -62,6 +63,7 @@ __all__ = [
     "SecuritySection",
     "SelfDocumentationSection",
     "SoulSection",
+    "ToolGuidanceSection",
     "TroubleshootingSection",
     "VersionControlSection",
 ]

{openhands_sdk-1.50.1 → openhands_sdk-1.52.0}/openhands/sdk/context/prompts/sections/static.py

@@ -23,7 +23,6 @@ from openhands.sdk.utils.path import get_user_persistence_dir, to_posix_path
 
 
 __all__ = [
-    "BrowserSection",
     "CodeQualitySection",
     "EfficiencySection",
     "EnvironmentSetupSection",
@@ -31,6 +30,7 @@ __all__ = [
     "FileSystemSection",
     "MemorySection",
     "ModelSpecificSection",
+    "PersonaSection",
     "ProblemSolvingSection",
     "ProcessManagementSection",
     "PullRequestsSection",
@@ -39,6 +39,7 @@ __all__ = [
     "SecuritySection",
     "SelfDocumentationSection",
     "SoulSection",
+    "ToolGuidanceSection",
     "TroubleshootingSection",
     "VersionControlSection",
 ]
@@ -99,6 +100,18 @@ class RoleSection(_StaticTextSection):
 </ROLE>"""
 
 
+class PersonaSection(_StaticTextSection):
+    """The agent's own persona, standing in for the persona sections it replaces."""
+
+    name = "persona"
+
+    def guard(self, ctx: PromptContext) -> bool:
+        return ctx.persona is not None
+
+    def render(self, ctx: PromptContext) -> str | None:
+        return ctx.persona
+
+
 class MemorySection(_StaticTextSection):
     """``<MEMORY>`` -- exactly one of two guidance variants fills the block:
     the default ``AGENTS.md`` guidance, or the two-tier persistent-memory
@@ -378,21 +391,16 @@ When an action originates from or is influenced by repository-provided context (
         return _refine(body, ctx.platform)
 
 
-class BrowserSection(_StaticTextSection):
-    name = "browser"
-    body = """\
-<BROWSER_TOOLS>
-You have a browser for navigating pages and interacting with web UIs.
-* Try curl/wget/fetch first. Use the browser only when simpler tools fail or the page requires JS/interaction.
-* ALWAYS call `browser_get_state` before EVERY `browser_click` or `browser_type` — indices change after each action. Flow: navigate → get_state → interact → get_state → get_content.
-* Max 10 browser actions per sub-task. If stuck, switch approach entirely.
-* If 20+ total steps without converging, stop exploring and commit to your best answer.
-* On 403/CAPTCHA/login wall: try one alternative, then abandon the browser.
-* Do NOT submit forms or create accounts unless explicitly asked.
-</BROWSER_TOOLS>"""
+class ToolGuidanceSection(_StaticTextSection):
+    """Usage guidance supplied by the loaded tools (e.g. ``<BROWSER_TOOLS>``)."""
+
+    name = "tool_guidance"
 
     def guard(self, ctx: PromptContext) -> bool:
-        return ctx.enable_browser
+        return bool(ctx.tool_guidance)
+
+    def render(self, ctx: PromptContext) -> str | None:
+        return "\n\n".join(ctx.tool_guidance)
 
 
 class ExternalServicesSection(_StaticTextSection):