agent-session-bridge 0.2.0__py3-none-any.whl

session_bridge/handshake.py

@@ -0,0 +1,175 @@
+"""Resume handshake.
+
+Structural file conversion alone cannot resume a session that stopped mid-turn:
+the target harness will happily replay a transcript, but it won't *know* that a
+tool call was left open, that a user message was queued but never processed, or
+that a stated goal is still in flight. The handshake turns that pending state
+(plus the lossy-conversion warnings) into an explicit instruction block that is
+injected as the first message of the resumed session, so the receiving agent
+picks up deliberately instead of guessing.
+
+This is the "handshake protocol, not just file conversion" the research flagged.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Any
+
+from .ir import BlockType, ContentBlock, ConversionReport, Message, Role, Session
+
+HANDSHAKE_TITLE = "# Session resume handshake"
+
+# An unforgeable marker embedded in every handshake body. Detection matches on
+# THIS, not the human-readable title: a real user message could legitimately
+# start with the title (e.g. someone quoting a prior handshake), and stripping it
+# would silently delete real content. The HTML comment is invisible in rendered
+# Markdown and vanishingly unlikely to appear by coincidence in genuine input.
+HANDSHAKE_MARKER = "<!-- session-bridge:handshake -->"
+
+
+def is_handshake_message(message: Message) -> bool:
+    # Match on the embedded marker, not the title text or the role: role is
+    # unreliable (SYSTEM can round-trip back as USER once a writer folds it) and
+    # the title alone collides with legitimate user prose.
+    return any(
+        b.type is BlockType.TEXT and HANDSHAKE_MARKER in (b.text or "")
+        for b in message.content
+    )
+
+
+def strip_prior_handshakes(session: Session) -> Session:
+    """Remove any handshake messages a previous conversion hop injected, so a
+    fresh handshake replaces them instead of stacking."""
+    kept = tuple(m for m in session.messages if not is_handshake_message(m))
+    return session.with_messages(kept)
+
+
+# Synthetic result injected for a tool call left unresolved at the tail. Providers
+# reject a tool call with no matching result (OpenAI Responses "No tool output
+# found for function call" 400; Anthropic requires a tool_result), and harness
+# resume-repair passes do NOT stub it. The industry-standard fix is to inject an
+# error tool_result marking the call interrupted, so the transcript is valid AND
+# the model learns the action did not complete.
+INTERRUPTED_RESULT_TEXT = "[session interrupted before this tool call returned]"
+
+
+def stub_open_tool_calls(session: Session) -> Session:
+    """Append a synthetic error tool_result for every genuinely-open tool call,
+    so the resumed session is a valid transcript (no orphaned tool call) and the
+    model sees the call as failed/interrupted rather than crashing the provider.
+
+    Appends one TOOL message carrying the stub results, only for call_ids in
+    ``pending.open_tool_calls`` (tail-outstanding, never resolved). No-op when
+    there are none. Pending state is cleared for those calls since they are now
+    resolved (as interrupted)."""
+    open_ids = session.pending.open_tool_calls
+    if not open_ids:
+        return session
+    stub = Message(
+        role=Role.TOOL,
+        content=tuple(
+            ContentBlock.tool_result(cid, INTERRUPTED_RESULT_TEXT, is_error=True)
+            for cid in open_ids
+        ),
+    )
+    new_pending = replace(session.pending, open_tool_calls=())
+    return replace(
+        session,
+        messages=session.messages + (stub,),
+        pending=new_pending,
+    )
+
+
+def _open_call_details(session: Session) -> list[tuple[str, str, str]]:
+    """(call_id, tool_name, arguments-preview) for each genuinely-open call.
+
+    ``pending.open_tool_calls`` (see readers/_pending.py) already scopes which
+    call_ids are genuinely open. Here, pick the LAST issuing block per open id so
+    a reissued/interrupted call shows its current args, not an earlier occurrence.
+    """
+    open_ids = set(session.pending.open_tool_calls)
+    last_block: dict[str, Any] = {}
+    for m in session.messages:
+        for b in m.content:
+            if b.type is BlockType.TOOL_CALL and b.call_id in open_ids:
+                last_block[b.call_id] = b
+    out = []
+    for call_id in session.pending.open_tool_calls:
+        b = last_block.get(call_id)
+        if b is None:
+            continue
+        args = b.tool_input or {}
+        preview = ", ".join(f"{k}={v!r}" for k, v in list(args.items())[:4])
+        out.append((call_id, b.tool_name or "?", preview))
+    return out
+
+
+def build_handshake(session: Session, report: ConversionReport, target: str) -> str:
+    """Render a human+agent readable resume preamble in Markdown."""
+    src = session.meta.source_harness
+    lines: list[str] = []
+    lines.append(HANDSHAKE_MARKER)
+    lines.append(HANDSHAKE_TITLE)
+    lines.append("")
+    lines.append(f"This session was exported from **{src}** and resumed in **{target}** "
+                 f"by session-bridge. Read this before continuing.")
+    lines.append("")
+
+    # Context recap.
+    lines.append("## Original context")
+    if session.meta.cwd:
+        lines.append(f"- Working directory: `{session.meta.cwd}`")
+    if session.meta.model:
+        lines.append(f"- Source model: `{session.meta.model}`")
+    real_turns = sum(1 for m in session.messages if not is_handshake_message(m))
+    lines.append(f"- Turns carried over: {real_turns}")
+    lines.append("")
+
+    pending = session.pending
+    if pending.is_empty():
+        lines.append("## Pending state")
+        lines.append("- None. The source stopped at a clean turn boundary; continue normally.")
+        lines.append("")
+    else:
+        lines.append("## Pending state — resolve these before proceeding")
+        open_calls = _open_call_details(session)
+        if open_calls:
+            lines.append("")
+            lines.append("### Open tool calls (issued, no result)")
+            for call_id, name, preview in open_calls:
+                lines.append(f"- `{name}`({preview}) — call_id `{call_id}`. "
+                             f"Re-run this tool (or decide it is no longer needed) "
+                             f"before continuing the turn.")
+        if pending.queued_user_messages:
+            lines.append("")
+            lines.append("### Queued user input (typed but never processed)")
+            for q in pending.queued_user_messages:
+                lines.append(f"- {q}")
+        if pending.active_goal:
+            lines.append("")
+            lines.append(f"### Active goal\n- {pending.active_goal}")
+        lines.append("")
+
+    # Lossy conversion notes.
+    if report.warnings:
+        lines.append("## Conversion notes (what did not transfer losslessly)")
+        for w in report.warnings:
+            lines.append(f"- {w}")
+        lines.append("")
+
+    lines.append("## Instruction")
+    if pending.is_empty():
+        lines.append("Resume the conversation from the last turn above.")
+    else:
+        lines.append("First satisfy the pending state above, then resume from the "
+                     "last turn. Do not silently skip open tool calls or queued input.")
+    return "\n".join(lines)
+
+
+def handshake_message(session: Session, report: ConversionReport, target: str) -> Message:
+    """The handshake as an IR system message, ready to prepend before writing."""
+    return Message(
+        role=Role.SYSTEM,
+        content=(ContentBlock.text_block(build_handshake(session, report, target)),),
+    )

session_bridge/ir.py

@@ -0,0 +1,246 @@
+"""Intermediate representation (IR) for cross-harness session portability.
+
+Every harness reader normalizes into this model; every writer renders from it.
+The IR is the union of what Claude Code, Codex, and Hermes can express, so that
+conversion is lossless where the target supports a feature and *explicitly* lossy
+(recorded in ``ConversionReport``) where it does not.
+
+Design rules:
+- Immutable value objects (frozen dataclasses). Transforms return new objects.
+- Content is a list of typed blocks, not a flat string, so reasoning and tool
+  calls survive round-trips instead of being flattened into text.
+- ``raw`` fields preserve the source record so a writer can fall back to
+  harness-specific detail the IR does not model.
+"""
+
+from __future__ import annotations
+
+import copy
+from dataclasses import dataclass, field, replace
+from enum import Enum
+from typing import Any, Optional
+
+# Marker a reader substitutes for a source content block the IR cannot represent
+# (e.g. a Claude Code image block). Lives here so readers and writers share one
+# definition; report_losses scans for it to report the loss.
+UNSUPPORTED_BLOCK_MARKER = "[unsupported "
+
+# Prefix a writer prepends to a failed tool result when the target format has no
+# native error flag (Codex / Hermes). Readers recover is_error from it so a
+# failure survives a multi-hop round trip instead of reading back as success.
+# The token is deliberately unforgeable (like HANDSHAKE_MARKER) so that genuine
+# tool output which merely starts with "[tool error]" is NOT mistaken for a
+# bridge-inserted failure marker. The human-readable prefix follows the token so
+# the result still reads naturally.
+ERROR_MARKER_TOKEN = "<!-- session-bridge:tool-error -->"
+ERROR_MARKER = ERROR_MARKER_TOKEN + "[tool error] "
+
+# Model ids a harness stamps on locally-synthesized (non-completion) messages —
+# e.g. Claude Code's "<synthetic>" on an auth-error notice. Not real, routable
+# model ids; readers must not adopt them as the session model and the loss
+# reporter must not count them as a real model.
+PLACEHOLDER_MODELS = frozenset({"<synthetic>"})
+
+
+def recover_tool_error(text: str) -> tuple[str, bool]:
+    """If ``text`` carries the error marker, strip it and report an error.
+
+    Lets a reader reconstruct ``is_error`` for a result whose failure was baked
+    into text by a prior hop's writer (the target had no native error flag).
+    Matches only the unforgeable token, so genuine output beginning with
+    '[tool error]' is not misclassified."""
+    if text.startswith(ERROR_MARKER):
+        return text[len(ERROR_MARKER):], True
+    return text, False
+
+
+class Role(str, Enum):
+    USER = "user"
+    ASSISTANT = "assistant"
+    SYSTEM = "system"
+    TOOL = "tool"
+
+
+class BlockType(str, Enum):
+    TEXT = "text"
+    REASONING = "reasoning"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    RAW = "raw"
+
+
+@dataclass(frozen=True)
+class ContentBlock:
+    """One typed unit inside a message.
+
+    - TEXT: ``text`` holds the prose.
+    - REASONING: ``text`` holds the thinking content.
+    - TOOL_CALL: ``tool_name`` + ``tool_input`` + ``call_id``.
+    - TOOL_RESULT: ``call_id`` links back to the call; ``text`` holds the
+      result payload; ``is_error`` marks a failed call.
+    - RAW: a source content block the IR has no typed representation for (e.g. a
+      Claude Code image/document block). ``raw_block`` holds the original block
+      verbatim and ``raw_kind`` its source type, so a same-harness writer can
+      re-emit it losslessly; a cross-harness writer degrades it to a reported
+      placeholder. ``text`` holds that human-readable placeholder.
+    """
+
+    type: BlockType
+    text: Optional[str] = None
+    tool_name: Optional[str] = None
+    tool_input: Optional[dict[str, Any]] = None
+    call_id: Optional[str] = None
+    is_error: bool = False
+    raw_block: Optional[dict[str, Any]] = None
+    raw_kind: Optional[str] = None
+    # On a TOOL_RESULT: the original non-text parts (e.g. an image) of a
+    # tool_result whose content was a block list. Carried WITH the result rather
+    # than as sibling RAW blocks, so a same-harness writer re-emits them inside
+    # the result's own content list and no writer mistakes them for a new turn.
+    result_parts: tuple[dict[str, Any], ...] = ()
+
+    @staticmethod
+    def text_block(text: str) -> "ContentBlock":
+        return ContentBlock(type=BlockType.TEXT, text=text)
+
+    @staticmethod
+    def raw(raw_block: dict[str, Any], raw_kind: str) -> "ContentBlock":
+        return ContentBlock(
+            type=BlockType.RAW,
+            text=f"{UNSUPPORTED_BLOCK_MARKER}{raw_kind} block]",
+            raw_block=copy.deepcopy(raw_block),
+            raw_kind=raw_kind,
+        )
+
+    @staticmethod
+    def reasoning(text: str) -> "ContentBlock":
+        return ContentBlock(type=BlockType.REASONING, text=text)
+
+    @staticmethod
+    def tool_call(call_id: str, tool_name: str, tool_input: dict[str, Any]) -> "ContentBlock":
+        return ContentBlock(
+            type=BlockType.TOOL_CALL,
+            call_id=call_id,
+            tool_name=tool_name,
+            tool_input=copy.deepcopy(tool_input),
+        )
+
+    @staticmethod
+    def tool_result(
+        call_id: str,
+        text: str,
+        is_error: bool = False,
+        result_parts: tuple[dict[str, Any], ...] = (),
+    ) -> "ContentBlock":
+        return ContentBlock(
+            type=BlockType.TOOL_RESULT,
+            call_id=call_id,
+            text=text,
+            is_error=is_error,
+            result_parts=tuple(copy.deepcopy(p) for p in result_parts),
+        )
+
+
+@dataclass(frozen=True)
+class Message:
+    """A single turn.
+
+    ``uid`` is a stable identifier within the session. ``parent_uid`` records
+    explicit thread linkage (Claude Code) so a non-linear thread survives; when a
+    harness is purely append-ordered, ``parent_uid`` is left ``None`` and order is
+    the list order.
+    """
+
+    role: Role
+    content: tuple[ContentBlock, ...]
+    uid: Optional[str] = None
+    parent_uid: Optional[str] = None
+    timestamp: Optional[str] = None
+    raw: Optional[dict[str, Any]] = None
+
+    def text(self) -> str:
+        """Concatenated TEXT blocks (convenience for display, not round-trip)."""
+        return "\n".join(b.text or "" for b in self.content if b.type == BlockType.TEXT)
+
+    def display_text(self) -> str:
+        """TEXT blocks plus RAW placeholders — the text a writer that cannot hold
+        RAW should emit, so a RAW block degrades to its placeholder instead of
+        vanishing when a message is flattened to a single string."""
+        return "\n".join(
+            b.text or ""
+            for b in self.content
+            if b.type in (BlockType.TEXT, BlockType.RAW)
+        )
+
+
+@dataclass(frozen=True)
+class ToolSchema:
+    """A tool the source session had available.
+
+    Kept so a target harness can be told which tools the resumed session expects,
+    and so portability gaps (target lacks this tool) can be detected.
+    """
+
+    name: str
+    description: Optional[str] = None
+    parameters: Optional[dict[str, Any]] = None
+
+
+@dataclass(frozen=True)
+class PendingState:
+    """Half-finished state at the point the source session stopped.
+
+    - ``open_tool_calls``: call_ids issued with no matching tool_result.
+    - ``queued_user_messages``: user inputs enqueued but never processed
+      (Claude Code queue-operation enqueue with no dequeue+turn).
+    - ``active_goal``: a stated goal/todo still in flight, if the harness records one.
+    """
+
+    open_tool_calls: tuple[str, ...] = ()
+    queued_user_messages: tuple[str, ...] = ()
+    active_goal: Optional[str] = None
+
+    def is_empty(self) -> bool:
+        return not (self.open_tool_calls or self.queued_user_messages or self.active_goal)
+
+
+@dataclass(frozen=True)
+class SessionMeta:
+    source_harness: str
+    session_id: Optional[str] = None
+    cwd: Optional[str] = None
+    model: Optional[str] = None
+    model_provider: Optional[str] = None
+    system_instructions: Optional[str] = None
+    permission_mode: Optional[str] = None
+    version: Optional[str] = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Session:
+    """A fully normalized session, harness-agnostic."""
+
+    meta: SessionMeta
+    messages: tuple[Message, ...]
+    tools: tuple[ToolSchema, ...] = ()
+    pending: PendingState = field(default_factory=PendingState)
+
+    def with_messages(self, messages: tuple[Message, ...]) -> "Session":
+        return replace(self, messages=messages)
+
+
+@dataclass
+class ConversionReport:
+    """Records what a reader/writer could not represent losslessly.
+
+    Not frozen: accumulated during a conversion, then reported to the user.
+    """
+
+    warnings: list[str] = field(default_factory=list)
+
+    def warn(self, message: str) -> None:
+        self.warnings.append(message)
+
+    def ok(self) -> bool:
+        return not self.warnings

session_bridge/place.py

@@ -0,0 +1,98 @@
+"""Place a converted session where a harness's resume flow will find it.
+
+Currently implemented for Claude Code, whose ``--resume <uuid>`` resolves a
+session directly from ``~/.claude/projects/<encoded-cwd>/<uuid>.jsonl`` when
+``claude`` is launched from the matching cwd. Placement therefore means:
+
+1. encode the target cwd the way Claude Code does (path separators -> ``-``),
+2. rewrite each record's ``sessionId`` and ``cwd`` to the chosen values,
+3. write ``<uuid>.jsonl`` into that directory.
+
+Hermes is intentionally not supported here: it indexes sessions in a SQLite
+store, so a file drop is not enough (see README / issue #1).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Optional
+
+from ._ids import validate_session_id
+
+
+class UnsafeCwdError(ValueError):
+    """The target cwd cannot be encoded into a safe project-dir name."""
+
+
+# encode_cwd collapses the whole cwd into ONE directory-name component (every
+# ``/`` -> ``-``), so its length is bounded by the filesystem's per-component
+# limit (255 on macOS/Linux). Guard well under that so mkdir raises a clean
+# UnsafeCwdError instead of a raw OSError (ENAMETOOLONG) — matching how
+# validate_session_id guards the id half of the same path.
+_MAX_ENCODED_CWD_LEN = 200
+
+
+def encode_cwd(cwd: str) -> str:
+    """Reproduce Claude Code's project-dir encoding: resolve the real path
+    (macOS symlinks such as /tmp -> /private/tmp matter) and replace every
+    path separator with ``-``."""
+    real = os.path.realpath(os.path.expanduser(cwd))
+    return real.replace("/", "-")
+
+
+def claude_project_dir(cwd: str, claude_home: Optional[Path] = None) -> Path:
+    home = claude_home or Path(os.path.expanduser("~/.claude"))
+    return home / "projects" / encode_cwd(cwd)
+
+
+class SessionExistsError(FileExistsError):
+    """A transcript already exists at the target session-id path."""
+
+
+def place_claude_code(
+    records: list[dict[str, Any]],
+    cwd: str,
+    session_id: str,
+    *,
+    claude_home: Optional[Path] = None,
+    overwrite: bool = False,
+) -> Path:
+    """Write ``records`` as a resumable Claude Code session for ``cwd``.
+
+    Returns the transcript path. Rewrites ``sessionId``/``cwd`` on message
+    records so the transcript is internally consistent with where it lives.
+
+    Fails closed if a transcript already exists at the target path (a reused
+    session id) unless ``overwrite`` is set: silently clobbering a placed
+    transcript would destroy a possibly-precious recovered session, mirroring
+    the duplicate-id guard ``register_hermes_session`` already enforces.
+    """
+    validate_session_id(session_id)  # reject path-traversal ids before touching the fs
+    encoded = encode_cwd(cwd)
+    if len(encoded) > _MAX_ENCODED_CWD_LEN:
+        raise UnsafeCwdError(
+            f"target cwd encodes to a {len(encoded)}-char directory name "
+            f"(max {_MAX_ENCODED_CWD_LEN}); use a shorter path"
+        )
+    directory = claude_project_dir(cwd, claude_home)
+    directory.mkdir(parents=True, exist_ok=True)
+    target = directory / f"{session_id}.jsonl"
+    if target.exists() and not overwrite:
+        raise SessionExistsError(
+            f"a session transcript already exists at {target}; "
+            f"choose a different --session-id or pass --force to overwrite"
+        )
+
+    real_cwd = os.path.realpath(os.path.expanduser(cwd))
+    lines: list[str] = []
+    for rec in records:
+        rec = dict(rec)  # immutable-friendly copy
+        if rec.get("type") in ("user", "assistant"):
+            rec["sessionId"] = session_id
+            rec["cwd"] = real_cwd
+        lines.append(json.dumps(rec, ensure_ascii=False))
+
+    target.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return target

session_bridge/readers/_content.py

@@ -0,0 +1,42 @@
+"""Shared content-part normalization for readers.
+
+Codex and Hermes both carry message ``content`` as either a plain string or a
+list of typed parts (OpenAI multi-modal shape). Text parts become TEXT blocks;
+any other part (image, etc.) becomes a RAW passthrough block rather than being
+silently dropped — matching how the Claude Code reader already handles unknown
+blocks, so all three readers preserve+report unrepresentable content uniformly.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..ir import ContentBlock
+
+# Part ``type`` values that carry plain text across Codex and Hermes.
+_TEXT_PART_TYPES = {"input_text", "output_text", "text"}
+
+
+def content_blocks(content: Any) -> tuple[ContentBlock, ...]:
+    """Normalize a message ``content`` (str or list of parts) to IR blocks.
+
+    A string yields one TEXT block (empty string yields no block). A list yields
+    a TEXT block per text part and a RAW block per non-text part, in order.
+    """
+    if isinstance(content, str):
+        return (ContentBlock.text_block(content),) if content else ()
+    if not isinstance(content, list):
+        return ()
+
+    blocks: list[ContentBlock] = []
+    for part in content:
+        if not isinstance(part, dict):
+            continue
+        ptype = part.get("type")
+        if ptype in _TEXT_PART_TYPES:
+            text = part.get("text", "")
+            if text:
+                blocks.append(ContentBlock.text_block(text))
+        elif ptype:
+            blocks.append(ContentBlock.raw(part, ptype))
+    return tuple(blocks)

session_bridge/readers/_jsonl.py

@@ -0,0 +1,50 @@
+"""Shared, defensive JSONL loading for all readers.
+
+Session logs are appended live by a running harness, so a real file can end in a
+half-written final line (the process died mid-flush — exactly the situation this
+tool exists to recover from) or contain a hand-edited/tool-mangled line. Loading
+must therefore be tolerant: skip lines that are not a JSON object rather than
+letting one bad line abort the whole read and lose every valid record before it.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def load_records(path: str | Path) -> list[dict[str, Any]]:
+    """Return the JSON-object records in a JSONL file.
+
+    Tolerates the one benign corruption a live-appended log actually produces: a
+    truncated/partial **final** line (the process died mid-flush). That last line
+    is skipped so every complete record before it survives.
+
+    A parse failure on an **interior** line is NOT benign — it means a real
+    record was corrupted and silently skipping it would drop a turn and orphan
+    the messages that referenced it. Interior parse failures re-raise rather than
+    vanish. Non-object JSON (list/str/number/null) on any line is not a session
+    record and is skipped quietly.
+    """
+    raw_lines = [ln.strip() for ln in open(path, encoding="utf-8")]
+    # Index of the last non-empty line: a parse failure there is a tail truncation.
+    last_content_idx = max((i for i, ln in enumerate(raw_lines) if ln), default=-1)
+
+    records: list[dict[str, Any]] = []
+    for i, line in enumerate(raw_lines):
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError:
+            if i == last_content_idx:
+                # Truncated final line (mid-write crash): safe to drop.
+                continue
+            # Corrupted interior line: a real record is being lost. Fail loudly
+            # rather than silently returning a partial, orphan-linked session.
+            raise
+        if isinstance(obj, dict):
+            records.append(obj)
+        # Non-dict JSON is not a session record; skip.
+    return records

session_bridge/readers/_pending.py

@@ -0,0 +1,63 @@
+"""Shared pending-state computation for all readers.
+
+A tool call is "open" only if the source genuinely stopped mid-turn with that call
+outstanding. Two real cases must both be handled, and they pull in opposite
+directions on "does later activity mean abandoned?":
+
+- OVERLAP (r22): call A issued, then call B issued, then B resolves and the session
+  ends with A never answered. A is genuinely open even though a *different* call
+  resolved after it — the session stopped with A outstanding.
+- ABANDONED RETRY (r21): call A errored, was reissued, then the session moved on
+  and other calls resolved after it. A's retry was dropped; reporting it would tell
+  a resuming agent to blindly re-run stale work.
+- INTERRUPTED RETRY (r22 case 7): call A resolved, reissued+resolved, reissued a
+  third time and the session stopped there. That final retry is genuinely open.
+
+The rule that satisfies all three keys on *this* call_id's own history, not a
+global index: a call is open iff its current (most-recent) issue is unresolved AND
+either it was never resolved in any cycle (overlap/interrupted-turn) OR its
+unresolved issue is at the tail with no later result for any call (interrupted
+retry). A resolved-then-reissued call whose retry is followed by other resolved
+activity is abandoned, not open.
+"""
+
+from __future__ import annotations
+
+from ..ir import BlockType, Message
+
+
+def open_tool_calls(messages: tuple[Message, ...]) -> tuple[str, ...]:
+    """Return call_ids genuinely open at the point the session stopped.
+
+    See the module docstring for the three real cases this rule reconciles
+    (overlap, abandoned retry, interrupted retry). Insertion order preserved.
+    """
+    last_issue_idx: dict[str, int] = {}   # call_id -> index of most recent issue
+    current_cycle_resolved: dict[str, bool] = {}
+    ever_resolved: set[str] = set()
+    last_result_idx = -1
+
+    for i, m in enumerate(messages):
+        for b in m.content:
+            if b.type is BlockType.TOOL_CALL and b.call_id:
+                last_issue_idx[b.call_id] = i
+                current_cycle_resolved[b.call_id] = False
+            elif b.type is BlockType.TOOL_RESULT and b.call_id:
+                last_result_idx = i
+                ever_resolved.add(b.call_id)
+                # Resolve the current cycle only if the result comes after the
+                # call's most recent issue (a result before a reissue doesn't
+                # resolve the reissue).
+                if b.call_id in last_issue_idx and i >= last_issue_idx[b.call_id]:
+                    current_cycle_resolved[b.call_id] = True
+
+    return tuple(
+        cid
+        for cid, idx in last_issue_idx.items()
+        if not current_cycle_resolved[cid]
+        # Open iff the current cycle is unresolved AND either the call was never
+        # resolved at all (overlap / interrupted turn) or its unresolved issue is
+        # at the tail (interrupted retry). A resolved-then-reissued call whose
+        # retry is superseded by later resolved activity is abandoned, not open.
+        and (cid not in ever_resolved or idx > last_result_idx)
+    )