openhands-sdk 1.58.2__tar.gz → 1.60.0__tar.gz

{openhands_sdk-1.58.2 → openhands_sdk-1.60.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.58.2
+Version: 1.60.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
@@ -14,9 +14,9 @@ Requires-Dist: fakeredis[lua]>=2.32.1
 Requires-Dist: fastmcp<4,>=3.2.0
 Requires-Dist: filelock>=3.20.1
 Requires-Dist: httpx[socks]>=0.28.1
-Requires-Dist: jsonschema>=4.23.0
+Requires-Dist: jsonschema>=4.26.0
 Requires-Dist: joserfc>=1.7.5
-Requires-Dist: litellm<1.106,>=1.93.0
+Requires-Dist: litellm<1.106,>=1.104.3
 Requires-Dist: pillow>=12.3.0
 Requires-Dist: pydantic>=2.13.5
 Requires-Dist: python-frontmatter>=1.3.0
@@ -31,4 +31,4 @@ Requires-Dist: boto3>=1.35.0; extra == "boto3"
 Provides-Extra: toolshield
 Requires-Dist: toolshield<0.2,>=0.1.3; extra == "toolshield"
 Provides-Extra: vertex
-Requires-Dist: google-cloud-aiplatform>=2.1.3; extra == "vertex"
+Requires-Dist: google-cloud-aiplatform>=2.5.0; extra == "vertex"

{openhands_sdk-1.58.2 → openhands_sdk-1.60.0}/openhands/sdk/__init__.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 from importlib.metadata import PackageNotFoundError, version
-from typing import TYPE_CHECKING, Any
 
 from openhands.sdk.agent import (
     Agent,
@@ -27,6 +26,8 @@ from openhands.sdk.io import FileStore, LocalFileStore
 from openhands.sdk.llm import (
     LLM,
     LLM_PROFILE_SCHEMA_VERSION,
+    DecisionModel,
+    DecisionResult,
     FallbackStrategy,
     ImageContent,
     LLMProfileStore,
@@ -109,10 +110,6 @@ from openhands.sdk.workspace import (
 )
 
 
-if TYPE_CHECKING:
-    from openhands.sdk.settings.acp_providers import ACPModelOption
-
-
 try:
     __version__ = version("openhands-sdk")
 except PackageNotFoundError:
@@ -124,6 +121,8 @@ _print_banner(__version__)
 
 __all__ = [
     "LLM",
+    "DecisionModel",
+    "DecisionResult",
     "LLM_PROFILE_SCHEMA_VERSION",
     "LLMRegistry",
     "LLMProfileStore",
@@ -167,7 +166,6 @@ __all__ = [
     "ACP_PROVIDERS",
     "ACPAgentSettings",
     "ACPFileSecretSpec",
-    "ACPModelOption",
     "ACPProviderInfo",
     "AgentSettingsBase",
     "AgentSettingsConfig",
@@ -211,11 +209,3 @@ __all__ = [
     "page_iterator",
     "__version__",
 ]
-
-
-def __getattr__(name: str) -> Any:
-    if name == "ACPModelOption":
-        from openhands.sdk.settings.acp_providers import _deprecated_model_option
-
-        return _deprecated_model_option()
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{openhands_sdk-1.58.2 → openhands_sdk-1.60.0}/openhands/sdk/agent/acp_agent.py

@@ -19,10 +19,12 @@ from __future__ import annotations
 import asyncio
 import atexit
 import contextlib
+import functools
 import inspect
 import json
 import os
 import re
+import shutil
 import threading
 import time
 import uuid
@@ -106,6 +108,7 @@ from openhands.sdk.agent.acp_file_credentials import (
     write_secret_file,
 )
 from openhands.sdk.agent.acp_models import ACPModelInfo
+from openhands.sdk.agent.acp_skills import render_skill_catalog, write_skill_files
 from openhands.sdk.agent.acp_tracing import ACPTurnTrace
 from openhands.sdk.agent.base import AgentBase
 from openhands.sdk.agent.stream_context import StreamContext
@@ -1340,6 +1343,14 @@ class _OpenHandsACPBridge:
         self.accumulated_text: list[str] = []
         self.accumulated_thoughts: list[str] = []
         self.accumulated_tool_calls: list[dict[str, Any]] = []
+        # Text and thoughts said before a tool call are emitted as their own
+        # message ahead of that call (``on_text_segment``), so the transcript
+        # keeps the agent's narration where it was said. These mark where the
+        # segment not yet emitted starts; the rest of the turn ends it.
+        self._segment_text_start = 0
+        self._segment_thought_start = 0
+        self.text_segments_emitted = 0
+        self.on_text_segment: Callable[[str, str], None] | None = None
         # Emits the LLM/TOOL spans an ACP turn would otherwise never produce.
         self.trace = ACPTurnTrace(acp_server=None, model_id=None)
         self.on_token: Any = None  # ConversationTokenCallbackType | None
@@ -1385,6 +1396,10 @@ class _OpenHandsACPBridge:
         self.accumulated_text.clear()
         self.accumulated_thoughts.clear()
         self.accumulated_tool_calls.clear()
+        self._segment_text_start = 0
+        self._segment_thought_start = 0
+        self.text_segments_emitted = 0
+        self.on_text_segment = None
         self.on_token = None
         self.on_event = None
         self.on_activity = None
@@ -1527,6 +1542,7 @@ class _OpenHandsACPBridge:
             if event is not None:
                 event.set()
         elif isinstance(update, ToolCallStart):
+            self._emit_text_segment()
             entry = {
                 "tool_call_id": update.tool_call_id,
                 "title": update.title,
@@ -1597,6 +1613,41 @@ class _OpenHandsACPBridge:
         else:
             logger.debug("ACP session update: %s", type(update).__name__)
 
+    def segment_text(self) -> str:
+        """Text said since the last emitted segment (the whole turn if none)."""
+        return "".join(self.accumulated_text[self._segment_text_start :])
+
+    def segment_thoughts(self) -> str:
+        """Thoughts since the last emitted segment (the whole turn if none)."""
+        return "".join(self.accumulated_thoughts[self._segment_thought_start :])
+
+    def _emit_text_segment(self) -> None:
+        """Hand the text and thoughts said so far to ``on_text_segment``.
+
+        Called when a tool call starts, so that narration such as "let me run
+        the tests" lands before the tool call it announces instead of joining
+        the turn's final message. The joined segment is masked again because a
+        secret split across chunks only reassembles here.
+        """
+        if self.on_text_segment is None:
+            return
+        text = self.segment_text()
+        thoughts = self.segment_thoughts()
+        if not text.strip() and not thoughts.strip():
+            return
+        try:
+            self.on_text_segment(self._mask_value(text), self._mask_value(thoughts))
+        except CredentialBindingError:
+            # Keep the segment: the turn's final text carries it, and the
+            # recorded masking error fails the turn before anything persists.
+            return
+        except Exception:
+            logger.debug("on_text_segment callback failed", exc_info=True)
+            return
+        self._segment_text_start = len(self.accumulated_text)
+        self._segment_thought_start = len(self.accumulated_thoughts)
+        self.text_segments_emitted += 1
+
     def _emit_tool_call_event(self, tc: dict[str, Any]) -> None:
         """Emit an ACPToolCallEvent reflecting the current state of ``tc``.
 
@@ -2020,6 +2071,10 @@ class ACPAgent(AgentBase):
     # "installed"            — already in subprocess history; skip further injection
     _suffix_install_state: str = PrivateAttr(default="unused")
     _installed_suffix: str | None = PrivateAttr(default=None)
+    # Skills written to disk and listed by path in the prompt, not inlined.
+    _skill_locations: dict[str, Path] = PrivateAttr(default_factory=dict)
+    _skills_root: Path | None = PrivateAttr(default=None)
+    _additional_directories_supported: bool = PrivateAttr(default=False)
     _restart_session_on_next_turn: bool = PrivateAttr(default=False)
     # Stream identity for the turn in flight; see stream_context.py. Held on
     # the agent rather than threaded through the finalizers because the ACP
@@ -2331,6 +2386,7 @@ class ACPAgent(AgentBase):
 
         # Render the suffix once, pulling secrets from the conversation's
         # secret_registry to match the regular Agent's get_dynamic_context().
+        self._materialize_skills(state)
         self._installed_suffix = self._render_suffix(state)
         # A prior session id means we may be resuming; used by ``truly_resumed``
         # below to decide whether the model state reported for this launch
@@ -2493,6 +2549,25 @@ class ACPAgent(AgentBase):
             )
         )
 
+    def _skill_directories(self) -> list[str] | None:
+        if self._skills_root and self._additional_directories_supported:
+            return [str(self._skills_root)]
+        return None
+
+    def _materialize_skills(self, state: ConversationState) -> None:
+        self._skill_locations = {}
+        self._skills_root = None
+        context = self.agent_context
+        if context is None or not context.skills:
+            return
+        _, available = context._partition_skills()
+        if not available:
+            return
+        root = self._acp_file_secret_dir(state, "skills")
+        shutil.rmtree(root, ignore_errors=True)
+        self._skill_locations = write_skill_files(root, available)
+        self._skills_root = root
+
     def _render_suffix(self, state: ConversationState) -> str | None:
         """Render the system suffix once, including secrets from the registry.
 
@@ -2533,12 +2608,23 @@ class ACPAgent(AgentBase):
             if not secret_infos:
                 return None
             agent_context = AgentContext(current_datetime=None)
-        elif agent_context.secrets:
+        listed = [s for s in agent_context.skills if s.name in self._skill_locations]
+        if listed:
+            agent_context = agent_context.model_copy(
+                update={"skills": [s for s in agent_context.skills if s not in listed]}
+            )
+        if agent_context.secrets:
             # The registry already carries these (and their descriptions), so
             # clear the agent_context copy to advertise from the registry alone
             # rather than re-merging a redundant second source.
             agent_context = agent_context.model_copy(update={"secrets": {}})
-        return agent_context.to_acp_prompt_context(additional_secret_infos=secret_infos)
+        rendered = agent_context.to_acp_prompt_context(
+            additional_secret_infos=secret_infos
+        )
+        if not listed:
+            return rendered
+        catalog = render_skill_catalog(listed, self._skill_locations)
+        return f"{rendered}\n\n{catalog}" if rendered else catalog
 
     def _present_file_secret_names(self, state: ConversationState) -> set[str]:
         """Reserved file-content secret names supplied for this conversation.
@@ -2768,16 +2854,19 @@ class ACPAgent(AgentBase):
                     if self._closed:
                         raise CredentialSyncError("Credential binding is closed.")
                 try:
-                    lifecycle.materialize(state.secret_registry, env)
-                    durable_path = (
-                        self._acp_file_secret_dir(state, spec.subdir) / spec.filename
-                    )
-                    try:
-                        durable_path.unlink(missing_ok=True)
-                    except OSError as exc:
-                        raise CredentialSyncError(
-                            "Durable credential copy could not be removed."
-                        ) from exc
+                    # The CLI keeps its state in the conversation's durable
+                    # directory; the lifecycle links the credential in from a
+                    # temporary file, so it never persists there.
+                    home = self._acp_file_secret_dir(state, spec.subdir)
+                    lifecycle.materialize(state.secret_registry, env, home=home)
+                    durable_path = home / spec.filename
+                    if lifecycle.path != durable_path:
+                        try:
+                            durable_path.unlink(missing_ok=True)
+                        except OSError as exc:
+                            raise CredentialSyncError(
+                                "Durable credential copy could not be removed."
+                            ) from exc
                 except BaseException:
                     env.pop("CODEX_HOME", None)
                     lifecycle.discard()
@@ -3161,6 +3250,15 @@ class ACPAgent(AgentBase):
                 if init_response.agent_capabilities is not None
                 else None
             )
+            session_caps = (
+                init_response.agent_capabilities.session_capabilities
+                if init_response.agent_capabilities is not None
+                else None
+            )
+            self._additional_directories_supported = (
+                session_caps is not None
+                and session_caps.additional_directories is not None
+            )
             acp_mcp_servers = _mcp_config_to_acp_servers(self.mcp_config, mcp_caps)
             if acp_mcp_servers:
                 logger.info(
@@ -3256,6 +3354,7 @@ class ACPAgent(AgentBase):
                     load_response = await conn.load_session(
                         cwd=working_dir,
                         session_id=prior_session_id,
+                        additional_directories=self._skill_directories(),
                         mcp_servers=acp_mcp_servers,
                     )
                     session_id = prior_session_id
@@ -3301,6 +3400,7 @@ class ACPAgent(AgentBase):
                 session_meta = build_session_model_meta(agent_name, self.acp_model)
                 response = await conn.new_session(
                     cwd=working_dir,
+                    additional_directories=self._skill_directories(),
                     mcp_servers=acp_mcp_servers,
                     **session_meta,
                 )
@@ -3421,11 +3521,41 @@ class ACPAgent(AgentBase):
         self._client.trace.start_turn(prompt)
         self._client.on_token = on_token
         self._client.on_event = on_event
+        self._client.on_text_segment = functools.partial(
+            self._emit_text_segment, on_event
+        )
         self._client.on_activity = self._on_activity
         # Start the idle-timeout clock fresh for this attempt so the deadline
         # is measured from the send (or retry), not from a stale value.
         self._client.arm_activity_clock()
 
+    def _emit_text_segment(
+        self, on_event: ConversationCallbackType, text: str, thoughts: str
+    ) -> None:
+        """Emit text the agent said before a tool call as its own message.
+
+        It retires the stream slot that carried this text and opens a new one,
+        so the rest of the turn streams below the tool call.
+        """
+        minted: dict[str, Any] = {}
+        if self._stream is not None and (item_id := self._stream.claim()):
+            minted["id"] = item_id
+        on_event(
+            MessageEvent(
+                **minted,
+                source="agent",
+                llm_message=Message(
+                    role="assistant",
+                    content=[TextContent(text=text)],
+                    reasoning_content=thoughts or None,
+                ),
+            )
+        )
+        if self._stream is not None:
+            if minted:
+                self._stream.commit()
+            self._stream.next_item()
+
     def _cancel_inflight_tool_calls(self) -> None:
         """Emit a terminal ``failed`` ACPToolCallEvent for every tool call
         in the accumulator that has not reached a terminal status yet.
@@ -3809,13 +3939,18 @@ class ACPAgent(AgentBase):
         # gets caught before landing in the persisted event stream.
         self._track_file_credentials_for_masking()
         mask = state.secret_registry.mask_secrets_in_output
-        response_text = mask("".join(self._client.accumulated_text))
-        thought_text = mask("".join(self._client.accumulated_thoughts))
-        if not response_text:
+        # Text said before a tool call was already emitted as its own message
+        # (``_emit_text_segment``); the finish carries what the agent said
+        # after its last tool call.
+        response_text = mask(self._client.segment_text())
+        thought_text = mask(self._client.segment_thoughts())
+        if not response_text and not self._client.text_segments_emitted:
             response_text = "(No response from ACP server)"
 
         self._client.trace.finish_turn(
-            response_text, thought_text, self._client.accumulated_tool_calls
+            mask("".join(self._client.accumulated_text)) or response_text,
+            mask("".join(self._client.accumulated_thoughts)),
+            self._client.accumulated_tool_calls,
         )
 
         # ACP step() boundaries are full remote assistant turns, not
@@ -3991,6 +4126,7 @@ class ACPAgent(AgentBase):
             return
         self._client.trace.abandon()
         self._client.on_event = None
+        self._client.on_text_segment = None
         self._client.on_token = None
         self._client.on_activity = None
 

{openhands_sdk-1.58.2 → openhands_sdk-1.60.0}/openhands/sdk/agent/acp_file_credentials.py

@@ -51,7 +51,12 @@ class ACPFileCredentialLifecycle(Protocol):
     secret_name: str
     path: Path | None
 
-    def materialize(self, registry: SecretRegistry, env: dict[str, str]) -> None: ...
+    def materialize(
+        self,
+        registry: SecretRegistry,
+        env: dict[str, str],
+        home: Path | None = None,
+    ) -> None: ...
 
     def track_current(self) -> None: ...
 
@@ -114,6 +119,7 @@ class _CodexAuthLifecycle:
         self.run_async = run_async
         self.path: Path | None = None
         self._runtime_dir: Path | None = None
+        self._home_link: Path | None = None
         self._registry: SecretRegistry | None = None
         self._expected_version: str | None = None
         self._local_digest: str | None = None
@@ -126,7 +132,20 @@ class _CodexAuthLifecycle:
         self._monitor: threading.Thread | None = None
         self._closed = False
 
-    def materialize(self, registry: SecretRegistry, env: dict[str, str]) -> None:
+    def materialize(
+        self,
+        registry: SecretRegistry,
+        env: dict[str, str],
+        home: Path | None = None,
+    ) -> None:
+        """Write the credential to a private temporary file for the CLI.
+
+        With ``home`` (the conversation's durable Codex directory), ``CODEX_HOME``
+        points there so the CLI's threads and state survive a restart, and
+        ``home/auth.json`` is a symlink to the temporary file. codex resolves that
+        link and replaces its target when it refreshes the login, so the
+        credential itself never lands in ``home``.
+        """
         resolved = self._load()
         if not is_valid_codex_auth(resolved.value):
             raise CredentialNeedsReauthentication(
@@ -135,8 +154,13 @@ class _CodexAuthLifecycle:
         runtime_dir = Path(tempfile.mkdtemp(prefix="openhands-codex-"))
         runtime_dir.chmod(0o700)
         path = runtime_dir / "auth.json"
+        codex_home = runtime_dir
         try:
             write_secret_file(path, resolved.value)
+            if home is not None:
+                link = self._link_into_home(home, path)
+                if link is not None:
+                    path, codex_home = link, home
         except BaseException:
             shutil.rmtree(runtime_dir, ignore_errors=True)
             raise
@@ -146,7 +170,7 @@ class _CodexAuthLifecycle:
         self._expected_version = resolved.version
         self._local_digest = self._digest(resolved.value)
         self._track(resolved.value)
-        env["CODEX_HOME"] = str(runtime_dir)
+        env["CODEX_HOME"] = str(codex_home)
         monitor = threading.Thread(
             target=self._monitor_loop,
             name="codex-credential-monitor",
@@ -164,6 +188,26 @@ class _CodexAuthLifecycle:
             extra={"credential": self.secret_name},
         )
 
+    def _link_into_home(self, home: Path, target: Path) -> Path | None:
+        link = home / "auth.json"
+        try:
+            home.mkdir(mode=0o700, parents=True, exist_ok=True)
+            # A real file here is a stale copy (older releases, or a CLI that
+            # replaced the link): the binding's value supersedes it.
+            link.unlink(missing_ok=True)
+            link.symlink_to(target)
+        except OSError:
+            # No symlinks (e.g. Windows without the privilege): keep the CLI's
+            # state in the temporary directory, as before.
+            logger.warning(
+                "credential_binding_home_link_failed",
+                extra={"credential": self.secret_name},
+                exc_info=True,
+            )
+            return None
+        self._home_link = link
+        return link
+
     def track_current(self) -> None:
         try:
             self._raise_sticky_error()
@@ -230,12 +274,22 @@ class _CodexAuthLifecycle:
         self._cleanup_runtime()
 
     def _cleanup_runtime(self) -> None:
+        home_link = self._home_link
+        if home_link is not None:
+            try:
+                home_link.unlink(missing_ok=True)
+            except OSError:
+                logger.warning(
+                    "credential_binding_home_link_cleanup_failed",
+                    extra={"credential": self.secret_name},
+                )
         runtime_dir = self._runtime_dir
         if runtime_dir is not None:
             shutil.rmtree(runtime_dir, ignore_errors=True)
         with self._lock:
             self.path = None
             self._runtime_dir = None
+            self._home_link = None
             self._registry = None
             self._monitor = None
             self._closed = True

openhands_sdk-1.60.0/openhands/sdk/agent/acp_skills.py

@@ -0,0 +1,67 @@
+"""Expose skills to any ACP agent as files plus a catalog that points at them."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Sequence
+from html import escape
+from pathlib import Path
+
+from openhands.sdk.skills import Skill
+
+
+def _description(skill: Skill) -> str:
+    if skill.description:
+        return skill.description
+    return next(
+        (line.strip() for line in skill.content.splitlines() if line.strip()),
+        skill.name,
+    )
+
+
+def _directory_name(name: str, taken: set[str]) -> str:
+    base = re.sub(r"[^A-Za-z0-9._-]+", "-", name).strip(".-") or "skill"
+    candidate, suffix = base, 2
+    while candidate.lower() in taken:
+        candidate, suffix = f"{base}-{suffix}", suffix + 1
+    taken.add(candidate.lower())
+    return candidate
+
+
+def write_skill_files(root: Path, skills: Sequence[Skill]) -> dict[str, Path]:
+    """Write each skill to ``root/<dir>/SKILL.md``; return its path by skill name."""
+    locations: dict[str, Path] = {}
+    taken: set[str] = set()
+    for skill in skills:
+        skill_dir = root / _directory_name(skill.name, taken)
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        path = skill_dir / "SKILL.md"
+        name = json.dumps(skill.name, ensure_ascii=False)
+        description = json.dumps(_description(skill)[:1000], ensure_ascii=False)
+        path.write_text(
+            f"---\nname: {name}\ndescription: {description}\n---\n\n{skill.content}\n",
+            encoding="utf-8",
+        )
+        locations[skill.name] = path
+    return locations
+
+
+def render_skill_catalog(skills: Sequence[Skill], locations: dict[str, Path]) -> str:
+    entries = [
+        "  <skill>\n"
+        f"    <name>{escape(skill.name)}</name>\n"
+        f"    <description>{escape(_description(skill)[:1024])}</description>\n"
+        f"    <location>{escape(str(locations[skill.name]))}</location>\n"
+        "  </skill>"
+        for skill in skills
+        if skill.name in locations
+    ]
+    return (
+        "<SKILLS>\n"
+        "The following skills are available. When one is relevant to the task, "
+        "read its SKILL.md at the given location with your file-reading tool "
+        "and follow its instructions.\n\n"
+        "<available_skills>\n" + "\n".join(entries) + "\n</available_skills>\n"
+        "</SKILLS>"
+    )

{openhands_sdk-1.58.2 → openhands_sdk-1.60.0}/openhands/sdk/agent/agent.py

@@ -51,7 +51,9 @@ from openhands.sdk.event.condenser import (
     CondensationRequest,
 )
 from openhands.sdk.event.error_classification import AGENT_OUTCOME
+from openhands.sdk.event.llm_convertible.observation import ToolValidationError
 from openhands.sdk.event.security import SecurityAnalysisEvent
+from openhands.sdk.event.types import ROOT_PARENT_ID, EventID
 from openhands.sdk.llm import (
     LLM,
     ImageContent,
@@ -561,12 +563,25 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
             )
             return
 
+        # A damaged event log can lose the SystemPromptEvent's file. The first
+        # surviving event still names it as its parent, or names the copy that an
+        # earlier resume re-created under the same id.
+        restored_prompt_id: EventID | None = None
+        if has_user_message:
+            parent_id = state.events[0].parent_id
+            if parent_id is not None and parent_id in state.events:
+                parent = state.events[state.events.get_index(parent_id)]
+                if isinstance(parent, SystemPromptEvent):
+                    return
+            elif parent_id not in (None, ROOT_PARENT_ID):
+                restored_prompt_id = parent_id
+
         # Assert: A user message should never appear before the system prompt.
         #
         # NOTE: This is a best-effort check based on the first few events only.
         # Remote conversations can include a ConversationStateUpdateEvent near the
         # start, so we scan a small prefix window.
-        if has_user_message:
+        if has_user_message and restored_prompt_id is None:
             event_types = [type(e).__name__ for e in prefix_events]
             logger.error(
                 f"init_state: User message found in prefix before SystemPromptEvent! "
@@ -598,7 +613,29 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
             if dynamic_context
             else None,
         )
-        on_event(event)
+        if restored_prompt_id is None:
+            on_event(event)
+            return
+
+        # Re-create it as an explicit root under its old id, so the surviving
+        # history hangs off it again; appending must not move HEAD onto it.
+        logger.warning(
+            "SystemPromptEvent '%s' is missing from the event log (its file was "
+            "lost); re-creating it as the root of the surviving history. "
+            "conversation_id=%s",
+            restored_prompt_id,
+            state.id,
+        )
+        head = state.active_branch(limit=1)
+        head_is_empty = state.head_is_empty
+        on_event(
+            event.model_copy(
+                update={"id": restored_prompt_id, "parent_id": ROOT_PARENT_ID}
+            )
+        )
+        state.leaf_event_id = head[-1].id if head else None
+        state.head_is_empty = head_is_empty
+        state.rebuild_view()
 
     def get_dynamic_context(self, state: ConversationState) -> str | None:
         """Get dynamic context for the system prompt, including secrets from state.
@@ -1286,6 +1323,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
         thinking_blocks: list[ThinkingBlock | RedactedThinkingBlock] | None = None,
         responses_reasoning_item: ReasoningItemModel | None = None,
         stream: StreamContext | None = None,
+        validation_errors: list[ToolValidationError] | None = None,
     ) -> None:
         try:
             json.loads(tool_call.arguments)
@@ -1325,6 +1363,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
             tool_name=tool_name,
             tool_call_id=tool_call.id,
             classification=AGENT_OUTCOME,
+            validation_errors=validation_errors,
         )
         record_tool_result(
             conversation,
@@ -1453,6 +1492,18 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
                 thinking_blocks=thinking_blocks,
                 responses_reasoning_item=responses_reasoning_item,
                 stream=stream,
+                validation_errors=(
+                    [
+                        ToolValidationError(type=detail["type"], loc=detail["loc"])
+                        for detail in e.errors(
+                            include_url=False,
+                            include_context=False,
+                            include_input=False,
+                        )
+                    ]
+                    if isinstance(e, ValidationError)
+                    else None
+                ),
             )
             return