tandem-cli 0.1.0__py3-none-any.whl

tandem/doctor.py

@@ -0,0 +1,265 @@
+"""tandem doctor: is this pairing healthy, and would both sessions resume?
+
+validate_transcript() is the structural "dry resume" — it checks that a
+session file is something its CLI can load without spending a model call.
+run_doctor() layers version checks, pairing checks, sync-state checks and an
+optional live mode (a real one-word resume per harness — costs two model
+calls) on top.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_CLAUDE_ENTRY_TYPES = {
+    "user", "assistant", "attachment", "system", "summary",
+    "queue-operation", "last-prompt", "progress", "file-history-snapshot",
+    "mode",  # {"type":"mode","mode":"normal",...} observed on --resume runs
+    # uuid-less metadata entries claude 2.1.220 interleaves with conversation
+    "permission-mode", "ai-title", "file-history-delta", "pr-link",
+    "relocated", "worktree-state",
+}
+_CODEX_LINE_TYPES = {
+    "session_meta", "response_item", "event_msg", "turn_context",
+    "world_state", "compacted",
+}
+
+
+def validate_transcript(harness: str, path: Path, session_id: str | None) -> list[str]:
+    """Return a list of problems (empty = looks resumable)."""
+    problems: list[str] = []
+    try:
+        raw = path.read_bytes()
+    except OSError as exc:
+        return [f"cannot read transcript: {exc}"]
+    if not raw.strip():
+        return ["transcript is empty"]
+
+    entries: list[tuple[int, dict]] = []
+    for i, line in enumerate(raw.splitlines()):
+        if not line.strip():
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError:
+            problems.append(f"line {i}: not valid JSON")
+            continue
+        if not isinstance(obj, dict):
+            problems.append(f"line {i}: not a JSON object")
+            continue
+        entries.append((i, obj))
+    if not entries:
+        return problems + ["no parseable entries"]
+
+    if harness == "claude":
+        problems += _validate_claude(entries, session_id)
+    else:
+        problems += _validate_codex(entries, session_id)
+    return problems
+
+
+def _validate_claude(entries: list[tuple[int, dict]], session_id: str | None) -> list[str]:
+    problems = []
+    seen_uuids: set[str] = set()
+    convo = 0
+    for i, e in entries:
+        etype = e.get("type")
+        if etype not in _CLAUDE_ENTRY_TYPES:
+            problems.append(f"line {i}: unknown entry type {etype!r}")
+            continue
+        if etype in ("user", "assistant"):
+            convo += 1
+            if session_id and e.get("sessionId") not in (None, session_id):
+                problems.append(
+                    f"line {i}: sessionId {e.get('sessionId')!r} != {session_id!r}"
+                )
+            if not e.get("uuid"):
+                problems.append(f"line {i}: conversation entry missing uuid")
+            parent = e.get("parentUuid")
+            if parent and parent not in seen_uuids:
+                # claude tolerates forward/dangling parents poorly; flag it
+                problems.append(f"line {i}: parentUuid {parent!r} not seen earlier")
+            msg = e.get("message")
+            if not isinstance(msg, dict) or "content" not in msg:
+                problems.append(f"line {i}: malformed message")
+        if e.get("uuid"):
+            seen_uuids.add(e["uuid"])
+    if convo == 0:
+        problems.append("no conversation entries (user/assistant)")
+    return problems
+
+
+def _validate_codex(entries: list[tuple[int, dict]], session_id: str | None) -> list[str]:
+    problems = []
+    first = entries[0][1]
+    if first.get("type") != "session_meta":
+        problems.append("first line is not session_meta")
+    else:
+        payload = first.get("payload") or {}
+        meta_id = payload.get("id") or payload.get("session_id")
+        if session_id and meta_id != session_id:
+            problems.append(f"session_meta id {meta_id!r} != {session_id!r}")
+    for i, e in entries:
+        etype = e.get("type")
+        if etype not in _CODEX_LINE_TYPES:
+            problems.append(f"line {i}: unknown line type {etype!r}")
+            continue
+        if "payload" not in e:
+            problems.append(f"line {i}: missing payload")
+        if etype == "response_item":
+            p = e.get("payload") or {}
+            if p.get("type") == "message" and not isinstance(p.get("content"), list):
+                problems.append(f"line {i}: message content is not a list")
+    if not any(e.get("type") == "response_item" for _, e in entries):
+        problems.append("no response_item entries (model context would be empty)")
+    return problems
+
+
+# -- full doctor -------------------------------------------------------------
+
+
+@dataclass
+class Check:
+    status: str  # 'ok' | 'warn' | 'fail'
+    message: str
+
+
+@dataclass
+class DoctorReport:
+    checks: list[Check] = field(default_factory=list)
+
+    def ok(self, msg: str) -> None:
+        self.checks.append(Check("ok", msg))
+
+    def warn(self, msg: str) -> None:
+        self.checks.append(Check("warn", msg))
+
+    def fail(self, msg: str) -> None:
+        self.checks.append(Check("fail", msg))
+
+    @property
+    def failed(self) -> bool:
+        return any(c.status == "fail" for c in self.checks)
+
+
+def run_doctor(store, session, live: bool = False) -> DoctorReport:
+    from . import compat, ops, paths
+    from .harness import get_adapter
+
+    report = DoctorReport()
+
+    for hid in ("claude", "codex"):
+        adapter = get_adapter(hid)
+        v = adapter.detect_version()
+        if v is None:
+            report.fail(f"{adapter.display_name}: not found on PATH")
+        elif not adapter.version_supported(v):
+            report.warn(
+                f"{adapter.display_name}: version {v!r} outside supported range "
+                f"(tested against {compat.COMPAT[hid].tested}); session formats "
+                f"may have drifted — treat sync results with suspicion"
+            )
+        else:
+            report.ok(f"{adapter.display_name}: {v}")
+
+    if session is None:
+        report.fail("no tandem session for this directory (run `tandem` to start one)")
+        return report
+
+    report.ok(
+        f"paired session {session.tandem_id} (active: "
+        f"{get_adapter(session.active).display_name})"
+    )
+
+    transcripts: dict[str, Path | None] = {}
+    for hid in ("claude", "codex"):
+        adapter = get_adapter(hid)
+        sid = getattr(session, f"{hid}_session_id")
+        if not sid:
+            report.warn(f"{hid}: session id pending (harness has not run yet)")
+            transcripts[hid] = None
+            continue
+        path = adapter.transcript_path(session.cwd, sid)
+        transcripts[hid] = path
+        if path is None:
+            if hid == session.active:
+                report.warn(f"{hid}: transcript not created yet (first run pending)")
+            else:
+                report.fail(f"{hid}: shadow transcript missing for session {sid}")
+            continue
+        problems = validate_transcript(hid, path, sid)
+        if problems:
+            for p in problems[:5]:
+                report.fail(f"{hid}: {p}")
+            if len(problems) > 5:
+                report.fail(f"{hid}: ... {len(problems) - 5} more problems")
+        else:
+            report.ok(f"{hid}: transcript resumable by structure ({path.name})")
+
+    for source in ("claude", "codex"):
+        cursor = store.get_cursor(session.tandem_id, source)
+        if cursor.pending.get("intent"):
+            report.warn(
+                f"sync from {source}: unresolved write intent (crash during "
+                f"append); it will be resolved automatically on next sync"
+            )
+        if cursor.failed_turns:
+            report.warn(
+                f"sync from {source}: {cursor.failed_turns} turn(s) fell back "
+                f"to placeholders"
+            )
+        behind = ops.unsynced_lines(session, store, source)
+        if behind and source == session.active:
+            report.warn(
+                f"sync from {source}: {behind} line(s) awaiting translation "
+                f"(run `tandem sync`)"
+            )
+
+    qdir = paths.quarantine_dir(session.tandem_id)
+    qfiles = sorted(qdir.iterdir()) if qdir.is_dir() else []
+    if qfiles:
+        report.warn(
+            f"{len(qfiles)} quarantined raw entr(y/ies) under {qdir}"
+        )
+
+    if live:
+        _live_resume_checks(report, session, transcripts)
+    return report
+
+
+def _live_resume_checks(report: DoctorReport, session, transcripts) -> None:
+    """Real resumes: one tiny model call per harness, run in the session cwd."""
+    from .harness import get_adapter
+
+    prompt = "tandem doctor live check - reply with exactly: ok"
+    if session.claude_session_id and transcripts.get("claude"):
+        argv = get_adapter("claude").oneoff_argv(session.claude_session_id, prompt)
+        _live_one(report, "claude", argv, session.cwd)
+    else:
+        report.warn("claude: skipping live resume (no transcript yet)")
+    if session.codex_session_id and transcripts.get("codex"):
+        argv = get_adapter("codex").oneoff_argv(session.codex_session_id, prompt)
+        _live_one(report, "codex", argv, session.cwd)
+    else:
+        report.warn("codex: skipping live resume (no transcript yet)")
+
+
+def _live_one(report: DoctorReport, hid: str, argv: list[str], cwd: str) -> None:
+    try:
+        out = subprocess.run(
+            argv, cwd=cwd, capture_output=True, text=True, timeout=180
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        report.fail(f"{hid}: live resume errored: {exc}")
+        return
+    if out.returncode == 0:
+        report.ok(f"{hid}: live resume succeeded")
+    else:
+        tail = (out.stderr or out.stdout or "").strip().splitlines()
+        report.fail(
+            f"{hid}: live resume exited {out.returncode}"
+            + (f" - {tail[-1][:160]}" if tail else "")
+        )

tandem/events.py

@@ -0,0 +1,107 @@
+"""Normalized internal event model.
+
+This schema is derived from the entries actually written by claude 2.1.220
+and codex-cli 0.145.0 (docs/formats.md), not from any published spec. It is
+the hub of the sync pipeline: each harness adapter parses its native entries
+into these events, and renders these events into its native entries.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+Agent = Literal["claude", "codex", "tandem", "user"]
+
+
+class _EventBase(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    source: Agent
+    timestamp: str | None = None
+    turn_index: int = 0
+    raw_line_index: int | None = None
+
+
+class UserMessage(_EventBase):
+    kind: Literal["user_message"] = "user_message"
+    text: str
+
+
+class AssistantMessage(_EventBase):
+    kind: Literal["assistant_message"] = "assistant_message"
+    text: str
+    phase: Literal["final", "commentary"] = "final"
+    model: str | None = None
+
+
+class ToolCall(_EventBase):
+    """A tool invocation by the active model. Paired with its ToolResult and
+    re-expressed in the shadow harness's own tool vocabulary, then rendered
+    as a native call/result pair (see converter policy and toolmap)."""
+
+    kind: Literal["tool_call"] = "tool_call"
+    call_id: str
+    tool: str
+    arguments: dict[str, Any] | str
+
+
+class ToolResult(_EventBase):
+    kind: Literal["tool_result"] = "tool_result"
+    call_id: str | None = None
+    tool: str | None = None
+    output: str = ""
+    is_error: bool = False
+    # Harness-specific structured result when available (e.g. Claude's
+    # toolUseResult with structuredPatch, or Codex patch_apply_end changes).
+    structured: dict[str, Any] | None = None
+
+
+class Thinking(_EventBase):
+    """Reasoning blocks. Claude's are signature-bound, Codex's encrypted;
+    neither is portable, so converters drop these."""
+
+    kind: Literal["thinking"] = "thinking"
+
+
+class SystemEvent(_EventBase):
+    """Session meta, hooks, attachments, compaction markers, token counts —
+    anything that is not conversation content. Converters skip these (or
+    summarize compaction)."""
+
+    kind: Literal["system"] = "system"
+    subtype: str = ""
+    text: str = ""
+
+
+NormalizedEvent = Annotated[
+    Union[UserMessage, AssistantMessage, ToolCall, ToolResult, Thinking, SystemEvent],
+    Field(discriminator="kind"),
+]
+
+
+class SessionContext(BaseModel):
+    """Mutable per-direction translation context, persisted in the sync
+    cursor so a restart resumes mid-turn without losing tool-call pairings."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    tandem_id: str
+    cwd: str
+    direction: Literal["claude->codex", "codex->claude"]
+    turn_index: int = 0
+    # call_id -> serialized ToolCall event awaiting its result
+    pending_calls: dict[str, dict[str, Any]] = Field(default_factory=dict)
+    # uuid of the last entry in the Claude shadow file (parentUuid chain)
+    claude_leaf_uuid: str | None = None
+    # message.id shared by the current contiguous run of rendered assistant
+    # entries; any rendered user-side entry resets it (a real transcript has
+    # one id per API response, and regrouping by id must not strand a
+    # tool_use away from its tool_result)
+    claude_run_msg_id: str | None = None
+    claude_session_id: str | None = None
+    codex_session_id: str | None = None
+    # model claude itself last used; rendered assistant entries carry it so
+    # `claude --resume` can restore the session model (it rejects "<synced>")
+    claude_model: str | None = None

tandem/harness/__init__.py

@@ -0,0 +1,16 @@
+from .base import HarnessAdapter
+from .claude_code import ClaudeCodeAdapter
+from .codex import CodexAdapter
+
+ADAPTERS: dict[str, HarnessAdapter] = {
+    "claude": ClaudeCodeAdapter(),
+    "codex": CodexAdapter(),
+}
+
+
+def get_adapter(harness_id: str) -> HarnessAdapter:
+    return ADAPTERS[harness_id]
+
+
+def other(harness_id: str) -> str:
+    return "codex" if harness_id == "claude" else "claude"

tandem/harness/base.py

@@ -0,0 +1,87 @@
+"""Per-harness adapter interface.
+
+Each supported CLI gets exactly one module implementing this interface, so a
+session-format change in one tool touches one file. The interface is generic
+over harnesses (a future Gemini CLI adapter would slot in here) but v1 ships
+only claude_code and codex.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+
+from ..events import NormalizedEvent, SessionContext
+
+
+class HarnessAdapter(ABC):
+    id: str          # 'claude' | 'codex'
+    display_name: str
+    binary: str      # executable name on PATH
+
+    # -- environment ---------------------------------------------------------
+
+    @abstractmethod
+    def detect_version(self) -> str | None:
+        """Raw --version output of the installed CLI, or None if missing."""
+
+    @abstractmethod
+    def version_supported(self, version_text: str) -> bool: ...
+
+    # -- session files -------------------------------------------------------
+
+    @abstractmethod
+    def transcript_path(self, cwd: str, session_id: str) -> Path | None:
+        """Expected transcript location for (cwd, session id). For harnesses
+        whose filename embeds a creation timestamp (codex) this returns the
+        discovered existing file, or None if not created yet."""
+
+    @abstractmethod
+    def mint_session_id(self) -> str:
+        """Mint a new session id in this harness's native id format."""
+
+    @abstractmethod
+    def create_shadow_transcript(
+        self, cwd: str, session_id: str, ctx: SessionContext, note: str
+    ) -> Path:
+        """Create a resume-ready transcript file containing only tandem-seeded
+        content (no model was involved). Used when this harness starts life as
+        the shadow."""
+
+    # -- launching the real CLI ----------------------------------------------
+
+    @abstractmethod
+    def interactive_argv(self, session_id: str | None, fresh: bool) -> list[str]:
+        """argv to run the harness interactively, pinned/resumed to session_id.
+        fresh=True means the session file does not exist yet."""
+
+    @abstractmethod
+    def oneoff_argv(self, session_id: str, prompt: str) -> list[str]:
+        """argv for a single non-interactive turn appended to session_id's
+        native session (claude -p / codex exec resume)."""
+
+    @abstractmethod
+    def hook_argv_extra(self, sentinel: Path) -> list[str]:
+        """Extra per-invocation argv that wires a turn-complete hook touching
+        `sentinel`, without mutating the user's persistent config. The tailer
+        uses the sentinel as a flush signal; fs-watching remains the
+        fallback."""
+
+    # -- transcript parsing / rendering (the converter halves) ---------------
+
+    @abstractmethod
+    def parse_entry(self, raw: dict[str, Any], ctx: SessionContext) -> list[NormalizedEvent]:
+        """Translate one native transcript entry into normalized events.
+        Unknown/irrelevant entry shapes yield SystemEvents (never raise)."""
+
+    @abstractmethod
+    def render_events(
+        self, events: list[NormalizedEvent], ctx: SessionContext
+    ) -> list[dict[str, Any]]:
+        """Render normalized events into native transcript entries ready to
+        append to this harness's session file (the shadow direction)."""
+
+    @abstractmethod
+    def render_placeholder(self, text: str, ctx: SessionContext) -> list[dict[str, Any]]:
+        """Native entries for an untranslatable-turn placeholder."""