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

session_bridge/readers/claude_code.py

@@ -0,0 +1,226 @@
+"""Reader: Claude Code session JSONL -> IR.
+
+Claude Code interleaves control events with message entries:
+- ``queue-operation`` {operation:enqueue|dequeue, content, sessionId}:
+  user input queued while a turn is running. An enqueue with no matching
+  dequeue is an undelivered (pending) user message.
+- ``user`` / ``assistant`` {parentUuid, uuid, message:{...}, cwd, gitBranch,
+  version, permissionMode, sessionId}: the actual turns. ``message`` is the
+  Anthropic API message; ``content`` is a str (user) or a list of typed blocks
+  (``text`` / ``thinking`` / ``tool_use`` / ``tool_result``). Note tool_result
+  blocks arrive inside ``user`` records.
+- ``ai-title`` / ``last-prompt`` / ``attachment``: metadata, not turns.
+
+Thread order is an explicit parentUuid linked list; we preserve both uid and
+parent_uid on each IR message and emit them in file order (which matches the
+chain in practice).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+from ..ir import (
+    PLACEHOLDER_MODELS,
+    ContentBlock,
+    Message,
+    PendingState,
+    Role,
+    Session,
+    SessionMeta,
+)
+from ._jsonl import load_records
+from ._pending import open_tool_calls
+
+_MESSAGE_TYPES = {"user", "assistant"}
+
+
+def _blocks_from_content(content: Any) -> tuple[ContentBlock, ...]:
+    """Normalize an Anthropic message ``content`` (str or block list) to IR blocks."""
+    if isinstance(content, str):
+        return (ContentBlock.text_block(content),) if content else ()
+    if not isinstance(content, list):
+        return ()
+
+    blocks: list[ContentBlock] = []
+    for b in content:
+        if not isinstance(b, dict):
+            continue
+        bt = b.get("type")
+        if bt == "text":
+            blocks.append(ContentBlock.text_block(b.get("text", "")))
+        elif bt in ("thinking", "redacted_thinking"):
+            blocks.append(ContentBlock.reasoning(b.get("thinking", "")))
+        elif bt == "tool_use":
+            inp = b.get("input")
+            blocks.append(
+                ContentBlock.tool_call(
+                    call_id=b.get("id", ""),
+                    tool_name=b.get("name", ""),
+                    tool_input=inp if isinstance(inp, dict) else {"_value": inp},
+                )
+            )
+        elif bt == "tool_result":
+            result = b.get("content", "")
+            nontext_parts: list[dict[str, Any]] = []
+            if isinstance(result, list):
+                # Anthropic tool_result content can itself be a block list mixing
+                # text with non-text parts (e.g. an image from a Read of a PNG).
+                # Join the text parts for the result payload, and keep each
+                # non-text part as a RAW passthrough sibling so it is preserved
+                # (same-harness) and reported (cross-harness) rather than silently
+                # dropped into an empty result.
+                text_bits = []
+                for part in result:
+                    if isinstance(part, dict) and part.get("type") in (None, "text"):
+                        text_bits.append(part.get("text", ""))
+                    elif isinstance(part, dict) and part.get("type"):
+                        nontext_parts.append(part)
+                    else:
+                        text_bits.append(str(part))
+                result = "\n".join(text_bits)
+            blocks.append(
+                ContentBlock.tool_result(
+                    call_id=b.get("tool_use_id", ""),
+                    text=result if isinstance(result, str) else json.dumps(result),
+                    is_error=bool(b.get("is_error", False)),
+                    # Carry non-text parts ON the result (not as sibling blocks),
+                    # so writers never mistake them for a separate turn.
+                    result_parts=tuple(nontext_parts),
+                )
+            )
+        elif bt:
+            # Unknown block type (e.g. image, document, server_tool_use). Keep the
+            # original block verbatim as a RAW passthrough so a same-harness writer
+            # re-emits it losslessly; cross-harness writers degrade it to a
+            # reported placeholder rather than dropping it silently.
+            blocks.append(ContentBlock.raw(b, bt))
+    return tuple(blocks)
+
+
+def _real_model(value: Any) -> Optional[str]:
+    """Return the model id only if it is a real (routable) one, else None.
+
+    Filters harness placeholders (e.g. Claude Code's "<synthetic>") so they don't
+    become the session model."""
+    if isinstance(value, str) and value and value not in PLACEHOLDER_MODELS:
+        return value
+    return None
+
+
+def _extract_meta(record: dict[str, Any], base: SessionMeta) -> SessionMeta:
+    """Fill session meta from the first message record that carries it."""
+    msg = record.get("message", {})
+    rec_model = _real_model(msg.get("model")) if isinstance(msg, dict) else None
+    return SessionMeta(
+        source_harness="claude-code",
+        session_id=base.session_id or record.get("sessionId"),
+        cwd=base.cwd or record.get("cwd"),
+        # Prefer the first REAL model; ignore synthetic placeholders even if they
+        # appear first in file order.
+        model=base.model or rec_model,
+        model_provider="anthropic",
+        permission_mode=base.permission_mode or record.get("permissionMode"),
+        version=base.version or record.get("version"),
+        # Keep the first branch seen; don't let a later record without gitBranch
+        # clobber it (first-non-null-wins, matching the other meta fields).
+        extra=(
+            base.extra
+            if base.extra.get("gitBranch")
+            else ({"gitBranch": record.get("gitBranch")} if record.get("gitBranch") else base.extra)
+        ),
+    )
+
+
+def _queued_messages(records: list[dict[str, Any]]) -> tuple[str, ...]:
+    """Enqueued user inputs with no matching later dequeue are undelivered.
+
+    Matching is scoped per ``sessionId`` so a dequeue from one session cannot
+    consume another session's queued item when a file mixes sessions. Emission
+    order follows first-enqueue order across sessions.
+    """
+    # Each queued item carries an enqueue sequence number so the still-pending
+    # items can be emitted in global first-enqueue order. Duplicates are kept
+    # (two identical undelivered messages are two pending items, not one) — a
+    # set-based dedup here would undercount genuinely-pending input.
+    per_session: dict[str, list[tuple[int, str]]] = {}
+    seq = 0
+    for rec in records:
+        if rec.get("type") != "queue-operation":
+            continue
+        sid = rec.get("sessionId", "")
+        op = rec.get("operation")
+        content = rec.get("content", "")
+        queue = per_session.setdefault(sid, [])
+        if op == "enqueue" and content:
+            queue.append((seq, content))
+            seq += 1
+        elif op == "dequeue" and queue:
+            # A dequeue (content-less) consumes this session's oldest queued item.
+            queue.pop(0)
+        elif op == "remove" and queue:
+            # Claude Code auto-withdraws an undelivered queued item (e.g. a
+            # background-task notification). Real `remove` records are mixed:
+            # some carry the withdrawn content, some carry none. When content is
+            # present, honor an exact match (newest-first). When absent, a remove
+            # in real traces immediately follows its own enqueue, so it withdraws
+            # the MOST-RECENTLY-enqueued pending item (LIFO).
+            if content:
+                for i in range(len(queue) - 1, -1, -1):
+                    if queue[i][1] == content:
+                        queue.pop(i)
+                        break
+                else:
+                    queue.pop()
+            else:
+                queue.pop()
+        elif op == "popAll":
+            # Claude Code flushes the ENTIRE pending queue in one op (e.g. all
+            # queued input delivered/cleared at once). Ignoring it would leave
+            # stale items that then mis-consume later dequeues; clear the queue.
+            queue.clear()
+    remaining = [item for q in per_session.values() for item in q]
+    remaining.sort(key=lambda item: item[0])
+    return tuple(content for _, content in remaining)
+
+
+def read_claude_code(path: str | Path) -> Session:
+    path = Path(path)
+    records = load_records(path)
+
+    meta = SessionMeta(source_harness="claude-code")
+    messages: list[Message] = []
+
+    for rec in records:
+        rtype = rec.get("type")
+        if rtype not in _MESSAGE_TYPES:
+            continue
+        # Skip Claude Code's own API-error notices (auth failure, rate limit,
+        # connection dropped). They are stamped type:assistant but are harness
+        # status messages, not model output — ingesting their text ("API Error:
+        # ...") would fabricate an assistant turn in the converted transcript.
+        if rec.get("isApiErrorMessage"):
+            continue
+        meta = _extract_meta(rec, meta)
+        msg = rec.get("message", {})
+        content = msg.get("content") if isinstance(msg, dict) else None
+        role = Role.USER if rtype == "user" else Role.ASSISTANT
+        messages.append(
+            Message(
+                role=role,
+                content=_blocks_from_content(content),
+                uid=rec.get("uuid"),
+                parent_uid=rec.get("parentUuid"),
+                timestamp=rec.get("timestamp"),
+                raw=rec,
+            )
+        )
+
+    msgs = tuple(messages)
+    pending = PendingState(
+        open_tool_calls=open_tool_calls(msgs),
+        queued_user_messages=_queued_messages(records),
+    )
+    return Session(meta=meta, messages=msgs, tools=(), pending=pending)

session_bridge/readers/codex.py

@@ -0,0 +1,203 @@
+"""Reader: Codex (rollout-*.jsonl) session -> IR.
+
+Codex wraps everything in ``{timestamp, type, payload}``:
+- ``session_meta``: payload has {id, cwd, model_provider, base_instructions:{text}, cli_version}.
+- ``turn_context``: per-turn {turn_id, model, cwd, approval_policy, sandbox_policy}.
+  Model lives here, not in session_meta.
+- ``event_msg``: UI-facing turn events (task_started/task_complete/user_message/
+  agent_message/token_count). These DUPLICATE content that also appears as
+  ``response_item`` records, so we ignore event_msg for content to avoid doubling.
+- ``response_item``: the canonical conversation, OpenAI Responses shape:
+    - {type:message, role:user|assistant, content:[{type:input_text|output_text, text}]}
+    - {type:reasoning, summary:[{type:summary_text, text}]}
+    - {type:function_call, name, arguments:<json-string>, call_id}
+    - {type:function_call_output, call_id, output}
+
+Purely append-ordered; no parent linkage (grouped by turn_id).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from ..ir import (
+    ContentBlock,
+    Message,
+    PendingState,
+    Role,
+    Session,
+    SessionMeta,
+    recover_tool_error,
+)
+from ._content import content_blocks
+from ._jsonl import load_records
+from ._pending import open_tool_calls
+
+_ROLE_FROM_CODEX = {
+    "user": Role.USER,
+    "assistant": Role.ASSISTANT,
+    "system": Role.SYSTEM,
+    "developer": Role.SYSTEM,
+}
+
+
+def _reasoning_text(payload: dict[str, Any]) -> str:
+    """Codex reasoning appears in either ``summary`` or ``content``, and each may
+    be a list of ``{type, text}`` blocks (real sessions) or a plain string.
+    Prefer non-empty ``content`` (the full reasoning) over ``summary``."""
+
+    def _join(value: Any) -> str:
+        if isinstance(value, str):
+            return value
+        if isinstance(value, list):
+            return "\n".join(
+                b.get("text", "") for b in value if isinstance(b, dict) and b.get("text")
+            )
+        return ""
+
+    content = _join(payload.get("content"))
+    if content.strip():
+        return content
+    return _join(payload.get("summary"))
+
+
+def _parse_arguments(raw_args: Any) -> dict[str, Any]:
+    if isinstance(raw_args, dict):
+        return raw_args
+    if isinstance(raw_args, str) and raw_args.strip():
+        try:
+            parsed = json.loads(raw_args)
+            return parsed if isinstance(parsed, dict) else {"_value": parsed}
+        except json.JSONDecodeError:
+            return {"_raw": raw_args}
+    return {}
+
+
+def read_codex(path: str | Path) -> Session:
+    path = Path(path)
+    records = load_records(path)
+
+    meta = SessionMeta(source_harness="codex", model_provider="openai")
+    messages: list[Message] = []
+    turn_models: set[str] = set()
+
+    for rec in records:
+        rtype = rec.get("type")
+        payload = rec.get("payload", {})
+        if not isinstance(payload, dict):
+            continue
+        ts = rec.get("timestamp")
+
+        if rtype == "session_meta":
+            base = payload.get("base_instructions")
+            instr = base.get("text") if isinstance(base, dict) else base
+            meta = SessionMeta(
+                source_harness="codex",
+                session_id=payload.get("id") or payload.get("session_id"),
+                cwd=payload.get("cwd"),
+                model_provider=payload.get("model_provider", "openai"),
+                system_instructions=instr,
+                version=payload.get("cli_version"),
+            )
+        elif rtype == "turn_context":
+            # Model and approval policy live here; keep the first seen. Also record
+            # every distinct per-turn model so a mid-session model switch (Codex's
+            # per-turn mechanism) can be reported as lossy — the IR keeps only one
+            # session model.
+            from dataclasses import replace
+
+            if payload.get("model"):
+                turn_models.add(payload["model"])
+            updates: dict[str, Any] = {}
+            if not meta.model and payload.get("model"):
+                updates["model"] = payload["model"]
+            if not meta.permission_mode and payload.get("approval_policy"):
+                updates["permission_mode"] = payload["approval_policy"]
+            if not meta.cwd and payload.get("cwd"):
+                updates["cwd"] = payload["cwd"]
+            if updates:
+                meta = replace(meta, **updates)
+        elif rtype == "response_item":
+            ptype = payload.get("type")
+            if ptype == "message":
+                role = _ROLE_FROM_CODEX.get(payload.get("role"), Role.ASSISTANT)
+                # Text parts -> TEXT blocks, non-text parts -> RAW passthrough
+                # (not silently dropped). Empty content is preserved as () so the
+                # turn/message count round-trips.
+                content = content_blocks(payload.get("content"))
+                messages.append(
+                    Message(role=role, content=content, timestamp=ts, raw=rec)
+                )
+            elif ptype == "reasoning":
+                text = _reasoning_text(payload)
+                # A reasoning record means a reasoning block EXISTED, so always
+                # emit one even when its summary text is empty. Real extended
+                # thinking stores content in an (unreadable) signature with empty
+                # visible text, so dropping empty-text reasoning would lose ~all
+                # real reasoning blocks and leave a contentless assistant turn.
+                messages.append(
+                    Message(role=Role.ASSISTANT,
+                            content=(ContentBlock.reasoning(text),),
+                            timestamp=ts, raw=rec)
+                )
+            elif ptype == "function_call":
+                messages.append(
+                    Message(
+                        role=Role.ASSISTANT,
+                        content=(
+                            ContentBlock.tool_call(
+                                call_id=payload.get("call_id", ""),
+                                tool_name=payload.get("name", ""),
+                                tool_input=_parse_arguments(payload.get("arguments")),
+                            ),
+                        ),
+                        timestamp=ts,
+                        raw=rec,
+                    )
+                )
+            elif ptype == "function_call_output":
+                out = payload.get("output", "")
+                is_error = False
+                if isinstance(out, dict):
+                    # A dict output can carry an explicit failure flag; preserve it
+                    # so a failed tool call is not reported as successful. Accept
+                    # both the JSON bool False and a string "false".
+                    success = out.get("success")
+                    failed = (
+                        success is False
+                        or (isinstance(success, str) and success.strip().lower() == "false")
+                        or bool(out.get("error"))
+                    )
+                    if failed:
+                        is_error = True
+                    out = out.get("content", json.dumps(out))
+                text = out if isinstance(out, str) else json.dumps(out)
+                # Recover an error baked into text by a prior hop (a writer with no
+                # native error flag prefixes ERROR_MARKER), so failure survives.
+                text, marked = recover_tool_error(text)
+                messages.append(
+                    Message(
+                        role=Role.TOOL,
+                        content=(
+                            ContentBlock.tool_result(
+                                call_id=payload.get("call_id", ""),
+                                text=text,
+                                is_error=is_error or marked,
+                            ),
+                        ),
+                        timestamp=ts,
+                        raw=rec,
+                    )
+                )
+        # event_msg intentionally ignored (duplicates response_item content)
+
+    if len(turn_models) > 1:
+        from dataclasses import replace
+
+        meta = replace(meta, extra={**meta.extra, "turn_models": sorted(turn_models)})
+
+    msgs = tuple(messages)
+    pending = PendingState(open_tool_calls=open_tool_calls(msgs))
+    return Session(meta=meta, messages=msgs, tools=(), pending=pending)

session_bridge/readers/hermes.py

@@ -0,0 +1,167 @@
+"""Reader: Hermes session JSONL -> IR.
+
+Hermes stores an OpenAI-chat-completion-style log:
+- ``session_meta``: {model, platform, tools:[{type:function, function:{name,description,parameters}}], timestamp}
+- ``user``:      {content, timestamp}
+- ``assistant``: {content, reasoning, tool_calls:[{id/call_id, function:{name, arguments:<json-string>}}], finish_reason, timestamp}
+- ``tool``:      {content, tool_call_id, timestamp}   # a tool result, linked by tool_call_id
+
+Records are append-ordered; there is no explicit parent linkage, so IR
+``parent_uid`` is left None and order is list order.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from ..ir import (
+    ContentBlock,
+    Message,
+    PendingState,
+    Role,
+    Session,
+    SessionMeta,
+    ToolSchema,
+    recover_tool_error,
+)
+from ._content import content_blocks
+from ._jsonl import load_records
+from ._pending import open_tool_calls
+
+
+def _parse_tool_schemas(raw_tools: Any) -> tuple[ToolSchema, ...]:
+    schemas: list[ToolSchema] = []
+    if not isinstance(raw_tools, list):
+        return ()
+    for entry in raw_tools:
+        fn = entry.get("function", entry) if isinstance(entry, dict) else {}
+        name = fn.get("name")
+        if not name:
+            continue
+        schemas.append(
+            ToolSchema(
+                name=name,
+                description=fn.get("description"),
+                parameters=fn.get("parameters"),
+            )
+        )
+    return tuple(schemas)
+
+
+def _parse_arguments(raw_args: Any) -> dict[str, Any]:
+    """Hermes stores tool arguments as a JSON string (OpenAI style)."""
+    if isinstance(raw_args, dict):
+        return raw_args
+    if isinstance(raw_args, str) and raw_args.strip():
+        try:
+            parsed = json.loads(raw_args)
+            return parsed if isinstance(parsed, dict) else {"_value": parsed}
+        except json.JSONDecodeError:
+            return {"_raw": raw_args}
+    return {}
+
+
+def _assistant_blocks(record: dict[str, Any]) -> tuple[ContentBlock, ...]:
+    blocks: list[ContentBlock] = []
+    reasoning = record.get("reasoning")
+    # Reasoning presence has two signals in real Hermes data: the flat visible
+    # `reasoning` string, and a sibling `codex_reasoning_items` list (opaque
+    # encrypted extended-thinking, mirroring Codex). A real record often has
+    # reasoning=null WITH codex_reasoning_items present — emit a reasoning block
+    # from whichever signal exists so a real reasoning turn isn't silently lost.
+    codex_items = record.get("codex_reasoning_items")
+    if isinstance(reasoning, str) and reasoning.strip():
+        blocks.append(ContentBlock.reasoning(reasoning))
+    elif isinstance(codex_items, list) and codex_items:
+        # Content is opaque/encrypted; preserve presence with empty visible text.
+        blocks.append(ContentBlock.reasoning(""))
+    # Text parts -> TEXT, non-text parts -> RAW passthrough (not dropped).
+    blocks.extend(content_blocks(record.get("content")))
+    for call in record.get("tool_calls") or []:
+        if not isinstance(call, dict):
+            continue
+        call_id = call.get("call_id") or call.get("id") or ""
+        fn = call.get("function", {})
+        blocks.append(
+            ContentBlock.tool_call(
+                call_id=call_id,
+                tool_name=fn.get("name", ""),
+                tool_input=_parse_arguments(fn.get("arguments")),
+            )
+        )
+    return tuple(blocks)
+
+
+def read_hermes(path: str | Path) -> Session:
+    path = Path(path)
+    records = load_records(path)
+
+    meta = SessionMeta(source_harness="hermes")
+    tools: tuple[ToolSchema, ...] = ()
+    messages: list[Message] = []
+
+    for rec in records:
+        role = rec.get("role")
+        if role == "session_meta":
+            meta = SessionMeta(
+                source_harness="hermes",
+                model=rec.get("model"),
+                version=rec.get("platform"),
+                extra={"platform": rec.get("platform")},
+            )
+            tools = _parse_tool_schemas(rec.get("tools"))
+        elif role == "user":
+            # Text parts -> TEXT, non-text parts (image_url, ...) -> RAW passthrough.
+            blocks = content_blocks(rec.get("content"))
+            messages.append(
+                Message(
+                    role=Role.USER,
+                    content=blocks,
+                    timestamp=rec.get("timestamp"),
+                    raw=rec,
+                )
+            )
+        elif role == "assistant":
+            messages.append(
+                Message(
+                    role=Role.ASSISTANT,
+                    content=_assistant_blocks(rec),
+                    timestamp=rec.get("timestamp"),
+                    raw=rec,
+                )
+            )
+        elif role == "system":
+            # write_hermes emits SYSTEM messages (e.g. the injected handshake) as
+            # role:system; read them back rather than dropping the whole class.
+            blocks = content_blocks(rec.get("content"))
+            messages.append(
+                Message(
+                    role=Role.SYSTEM,
+                    content=blocks,
+                    timestamp=rec.get("timestamp"),
+                    raw=rec,
+                )
+            )
+        elif role == "tool":
+            text, marked = recover_tool_error(rec.get("content", "") or "")
+            messages.append(
+                Message(
+                    role=Role.TOOL,
+                    content=(
+                        ContentBlock.tool_result(
+                            call_id=rec.get("tool_call_id", ""),
+                            text=text,
+                            is_error=marked,
+                        ),
+                    ),
+                    timestamp=rec.get("timestamp"),
+                    raw=rec,
+                )
+            )
+        # unknown roles are ignored but preserved via raw if needed later
+
+    msgs = tuple(messages)
+    pending = PendingState(open_tool_calls=open_tool_calls(msgs))
+    return Session(meta=meta, messages=msgs, tools=tools, pending=pending)