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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.58.2
+Version: 1.59.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.58.2 → openhands_sdk-1.59.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,
@@ -109,10 +108,6 @@ from openhands.sdk.workspace import (
 )
 
 
-if TYPE_CHECKING:
-    from openhands.sdk.settings.acp_providers import ACPModelOption
-
-
 try:
     __version__ = version("openhands-sdk")
 except PackageNotFoundError:
@@ -167,7 +162,6 @@ __all__ = [
     "ACP_PROVIDERS",
     "ACPAgentSettings",
     "ACPFileSecretSpec",
-    "ACPModelOption",
     "ACPProviderInfo",
     "AgentSettingsBase",
     "AgentSettingsConfig",
@@ -211,11 +205,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.59.0}/openhands/sdk/agent/acp_agent.py

@@ -23,6 +23,7 @@ import inspect
 import json
 import os
 import re
+import shutil
 import threading
 import time
 import uuid
@@ -106,6 +107,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
@@ -2020,6 +2022,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 +2337,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 +2500,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 +2559,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.
@@ -3161,6 +3198,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 +3302,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 +3348,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,
                 )

openhands_sdk-1.59.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.59.0}/openhands/sdk/agent/agent.py

@@ -52,6 +52,7 @@ from openhands.sdk.event.condenser import (
 )
 from openhands.sdk.event.error_classification import AGENT_OUTCOME
 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 +562,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 +612,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.

{openhands_sdk-1.58.2 → openhands_sdk-1.59.0}/openhands/sdk/conversation/conversation.py

@@ -73,6 +73,7 @@ class Conversation:
         token_callbacks: list[ConversationTokenCallbackType] | None = None,
         hook_config: HookConfig | None = None,
         max_iteration_per_run: int = 500,
+        max_budget_per_run: float | None = None,
         stuck_detection: bool = True,
         stuck_detection_thresholds: (
             StuckDetectionThresholds | Mapping[str, int] | None
@@ -103,6 +104,7 @@ class Conversation:
         token_callbacks: list[ConversationTokenCallbackType] | None = None,
         hook_config: HookConfig | None = None,
         max_iteration_per_run: int = 500,
+        max_budget_per_run: float | None = None,
         stuck_detection: bool = True,
         stuck_detection_thresholds: (
             StuckDetectionThresholds | Mapping[str, int] | None
@@ -133,6 +135,7 @@ class Conversation:
         token_callbacks: list[ConversationTokenCallbackType] | None = None,
         hook_config: HookConfig | None = None,
         max_iteration_per_run: int = 500,
+        max_budget_per_run: float | None = None,
         stuck_detection: bool = True,
         stuck_detection_thresholds: (
             StuckDetectionThresholds | Mapping[str, int] | None
@@ -200,6 +203,7 @@ class Conversation:
                 token_callbacks=token_callbacks,
                 hook_config=hook_config,
                 max_iteration_per_run=max_iteration_per_run,
+                max_budget_per_run=max_budget_per_run,
                 stuck_detection=stuck_detection,
                 stuck_detection_thresholds=stuck_detection_thresholds,
                 visualizer=visualizer,
@@ -223,6 +227,7 @@ class Conversation:
             token_callbacks=token_callbacks,
             hook_config=hook_config,
             max_iteration_per_run=max_iteration_per_run,
+            max_budget_per_run=max_budget_per_run,
             stuck_detection=stuck_detection,
             stuck_detection_thresholds=stuck_detection_thresholds,
             visualizer=visualizer,

{openhands_sdk-1.58.2 → openhands_sdk-1.59.0}/openhands/sdk/conversation/event_store.py

@@ -1,4 +1,5 @@
 # state.py
+import bisect
 import operator
 from collections.abc import Callable, Iterator
 from contextlib import AbstractContextManager, nullcontext
@@ -26,6 +27,9 @@ LOCK_TIMEOUT_SECONDS = 30
 # ``exists()``. The count lives in the name because ``FileStore.read`` is cached.
 LENGTH_MARKER_PATTERN: Final[str] = ".eventlog-len-{length}.marker"
 
+# Holes listed by name in the lost-files warning; the rest are only counted.
+MAX_REPORTED_HOLES: Final[int] = 5
+
 # ROOT_PARENT_ID now lives in event.types (single source of truth); it is used
 # below in _effective_parent_id and re-exported here so existing
 # ``from event_store import ROOT_PARENT_ID`` importers keep working.
@@ -55,6 +59,13 @@ class EventLog(EventsListBase):
         self._dir = dir_path
         self._id_to_idx: dict[EventID, int] = {}
         self._idx_to_id: dict[int, EventID] = {}
+        # On-disk index per log index, recorded only where the two differ (behind
+        # a lost event file). The on-disk index names the file and is the
+        # event's durable seq; new files are allocated after the highest one.
+        self._disk_idx: dict[int, int] = {}
+        self._next_disk_idx = 0
+        self._reported_lost = 0
+        self._reported_missing: set[EventID] = set()
         self._event_cache: dict[int, Event] = {}
         self._lock_path = f"{dir_path}/{LOCK_FILE_NAME}"
         self._write_guard = None
@@ -81,6 +92,28 @@ class EventLog(EventsListBase):
             raise IndexError("Event index out of range")
         return self._idx_to_id[idx]
 
+    def get_seq(self, idx: int) -> int:
+        """Return the durable sequence number of the event at ``idx``.
+
+        The seq is the event's on-disk index (the ``{idx:05d}`` filename
+        component). It equals ``idx`` unless an earlier event file was lost, and
+        unlike ``idx`` it never changes across a reload, so it is the value to
+        hand out as a resume cursor.
+        """
+        if idx < 0:
+            idx += self._length
+        if idx < 0 or idx >= self._length:
+            raise IndexError("Event index out of range")
+        return self._disk_idx.get(idx, idx)
+
+    def index_after_seq(self, seq: int) -> int:
+        """Return the index of the first event whose seq is above ``seq``.
+
+        Returns ``len(self)`` when there is none. Seqs grow with the index, so
+        this is a binary search.
+        """
+        return bisect.bisect_right(range(self._length), seq, key=self.get_seq)
+
     def __contains__(self, item: object) -> bool:
         """Whether the log contains a given event id or ``Event`` (by id).
 
@@ -97,15 +130,30 @@ class EventLog(EventsListBase):
 
         Legacy events predating the tree have no ``parent_id``; they fall back to
         the linear chain (event ``idx - 1``) so old conversations load unbranched
-        with no disk rewrite.
+        with no disk rewrite. An explicit parent whose file was lost is bridged
+        the same way, so the branch keeps its surviving ancestors (the system
+        prompt above all) instead of ending at the hole.
         """
-        if event.parent_id == ROOT_PARENT_ID:
+        parent_id = event.parent_id
+        if parent_id == ROOT_PARENT_ID:
             return None  # explicit root (feature-created root at idx > 0)
-        if event.parent_id is not None:
-            return event.parent_id  # explicit (new events)
+        if parent_id is not None:
+            if parent_id in self._id_to_idx:
+                return parent_id  # explicit (new events)
+            self._report_missing(parent_id)
         if idx == 0:
             return None  # genuine root
-        return self.get_id(idx - 1)  # legacy linear chain (back-compat)
+        return self.get_id(idx - 1)  # legacy linear chain, or bridge over a hole
+
+    def _report_missing(self, event_id: EventID) -> None:
+        """Warn once per id that the log references an event whose file is gone."""
+        if event_id in self._reported_missing:
+            return
+        self._reported_missing.add(event_id)
+        logger.warning(
+            "Event '%s' is missing from the event log (its file was lost).",
+            event_id,
+        )
 
     def path_to_root(
         self, leaf_id: EventID | None, limit: int | None = None
@@ -114,8 +162,9 @@ class EventLog(EventsListBase):
 
         ``leaf_id=None`` yields ``[]``. ``limit`` keeps only the last ``limit``
         events (walking back from the leaf), so callers wanting a recent window
-        stay O(limit) instead of O(branch). Raises ValueError on a cycle, KeyError
-        if ``leaf_id`` or an ancestor is missing.
+        stay O(limit) instead of O(branch). Raises ValueError on a cycle. An
+        ancestor whose file was lost is bridged (see ``_effective_parent_id``);
+        a ``leaf_id`` missing from the log yields ``[]``.
         """
         chain: list[Event] = []
         seen: set[EventID] = set()
@@ -124,7 +173,11 @@ class EventLog(EventsListBase):
             if cur_id in seen:
                 raise ValueError(f"Cycle in event tree at {cur_id}")
             seen.add(cur_id)
-            idx = self.get_index(cur_id)
+            idx = self._id_to_idx.get(cur_id)
+            if idx is None:
+                # Only the leaf can be unknown: ancestors are bridged.
+                self._report_missing(cur_id)
+                break
             chain.append(evt := self[idx])
             cur_id = self._effective_parent_id(idx, evt)
         return chain[::-1]
@@ -227,9 +280,15 @@ class EventLog(EventsListBase):
                     nullcontext() if self._write_guard is None else self._write_guard()
                 )
                 idx = self._length
+                # Never reuse an on-disk index: behind a lost file the dense
+                # index lags it, and a shared index makes the reload order
+                # depend on the event ids.
+                disk_idx = max(idx, self._next_disk_idx)
                 with write_guard:
-                    target_path = self._path(idx, event_id=evt_id)
-                    self._fs.write(target_path, payload)
+                    self._fs.write(self._file_path(disk_idx, evt_id), payload)
+                if disk_idx != idx:
+                    self._disk_idx[idx] = disk_idx
+                self._next_disk_idx = disk_idx + 1
                 self._idx_to_id[idx] = evt_id
                 self._id_to_idx[evt_id] = idx
                 self._event_cache[idx] = event
@@ -292,17 +351,25 @@ class EventLog(EventsListBase):
         Preserves existing index mappings and only scans new events.
         """
         # Preserve existing mappings
-        existing_idx_to_id = dict(self._idx_to_id)
+        existing = [
+            (idx, evt_id, self._disk_idx.get(idx, idx))
+            for idx, evt_id in self._idx_to_id.items()
+        ]
 
         # Re-scan to pick up new events
         scanned_length = self._scan_and_build_index()
 
-        # Restore any mappings that were lost (e.g., for non-UUID event IDs)
-        for idx, evt_id in existing_idx_to_id.items():
-            if idx not in self._idx_to_id:
-                self._idx_to_id[idx] = evt_id
-            if evt_id not in self._id_to_idx:
-                self._id_to_idx[evt_id] = idx
+        # Restore mappings the scan cannot see (e.g., for non-UUID event IDs).
+        # Only whole pairs, and only when neither side was rescanned: behind a
+        # lost file a rescanned index can belong to a different event.
+        for idx, evt_id, disk_idx in existing:
+            if idx in self._idx_to_id or evt_id in self._id_to_idx:
+                continue
+            self._idx_to_id[idx] = evt_id
+            self._id_to_idx[evt_id] = idx
+            if disk_idx != idx:
+                self._disk_idx[idx] = disk_idx
+            self._next_disk_idx = max(self._next_disk_idx, disk_idx + 1)
 
         # Use the higher of scanned length or disk_length
         self._length = max(scanned_length, disk_length)
@@ -311,58 +378,57 @@ class EventLog(EventsListBase):
         return self._length
 
     def _path(self, idx: int, *, event_id: EventID | None = None) -> str:
-        return f"{self._dir}/{
-            EVENT_FILE_PATTERN.format(
-                idx=idx, event_id=event_id or self._idx_to_id[idx]
-            )
-        }"
+        return self._file_path(
+            self._disk_idx.get(idx, idx), event_id or self._idx_to_id[idx]
+        )
+
+    def _file_path(self, disk_idx: int, event_id: EventID) -> str:
+        name = EVENT_FILE_PATTERN.format(idx=disk_idx, event_id=event_id)
+        return f"{self._dir}/{name}"
+
+    def _reset_index(self) -> None:
+        self._id_to_idx.clear()
+        self._idx_to_id.clear()
+        self._disk_idx.clear()
+        self._event_cache.clear()
+        self._next_disk_idx = 0
 
     def _scan_and_build_index(self) -> int:
         try:
             paths = self._fs.list(self._dir)
         except Exception:
-            self._id_to_idx.clear()
-            self._idx_to_id.clear()
-            self._event_cache.clear()
+            self._reset_index()
             return 0
 
-        by_idx: dict[int, EventID] = {}
+        found: list[tuple[int, EventID]] = []
         for p in paths:
             name = posix_path_name(p)
             m = EVENT_NAME_RE.match(name)
             if m:
-                idx = int(m.group("idx"))
-                evt_id = m.group("event_id")
-                by_idx[idx] = evt_id
+                found.append((int(m.group("idx")), m.group("event_id")))
             elif name.startswith("."):
                 # Our own sidecars (lock file, count marker), not event files.
                 continue
             else:
                 logger.warning(f"Unrecognized event file name: {name}")
 
-        if not by_idx:
-            self._id_to_idx.clear()
-            self._idx_to_id.clear()
-            self._event_cache.clear()
-            return 0
-
-        n = 0
-        while True:
-            if n not in by_idx:
-                if any(i > n for i in by_idx.keys()):
-                    logger.warning(
-                        "Event index gap detected: "
-                        f"expect next index {n} but got {sorted(by_idx.keys())}"
-                    )
-                break
-            n += 1
-
-        self._id_to_idx.clear()
-        self._idx_to_id.clear()
-        self._event_cache.clear()
-        for i in range(n):
-            evt_id = by_idx[i]
+        self._reset_index()
+        # Index every event file in on-disk order instead of stopping at the
+        # first missing index, so one lost file does not make every later event
+        # unknown. The dense index closes the hole; the on-disk index stays the
+        # event's file name and seq.
+        found.sort()
+        holes: list[tuple[int, int]] = []
+        lost = 0
+        for i, (disk_idx, evt_id) in enumerate(found):
+            if disk_idx > self._next_disk_idx:
+                lost += disk_idx - self._next_disk_idx
+                if len(holes) < MAX_REPORTED_HOLES:
+                    holes.append((self._next_disk_idx, disk_idx - 1))
+            self._next_disk_idx = disk_idx + 1
             self._idx_to_id[i] = evt_id
+            if disk_idx != i:
+                self._disk_idx[i] = disk_idx
             if evt_id in self._id_to_idx:
                 logger.warning(
                     f"Duplicate event ID '{evt_id}' found during scan. "
@@ -371,4 +437,17 @@ class EventLog(EventsListBase):
                 )
             else:
                 self._id_to_idx[evt_id] = i
-        return n
+        if lost != self._reported_lost:
+            self._reported_lost = lost
+            if lost:
+                listed = ", ".join(str(a) if a == b else f"{a}-{b}" for a, b in holes)
+                logger.warning(
+                    "Event log %s is missing %d event file(s) (on-disk index %s%s); "
+                    "the %d surviving events stay readable.",
+                    self._dir,
+                    lost,
+                    listed,
+                    ", ..." if lost > sum(b - a + 1 for a, b in holes) else "",
+                    len(found),
+                )
+        return len(found)