tandem-cli 0.1.0__py3-none-any.whl

tandem/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

tandem/cli.py

@@ -0,0 +1,358 @@
+"""tandem — run Claude Code and Codex CLI as one paired session."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from . import compat, paths
+from .constants import SEED_NOTE
+from .events import SessionContext
+from .harness import get_adapter, other
+from .state import PairedSession, StateStore
+
+
+def _cwd() -> str:
+    return str(Path.cwd())
+
+
+# Set by the tandem prompt (shell.py) around each dispatched command so it
+# acts on that shell's own session. Without it, a second `tandem` in the same
+# directory becomes the cwd-MRU and silently steals `status`/`sync`/`run --on`
+# typed in the first shell.
+_SESSION_ID: str | None = None
+
+
+def _resolve_session(store: StateStore) -> PairedSession | None:
+    if _SESSION_ID is not None:
+        return store.get_session(_SESSION_ID)
+    return store.latest_session_for_cwd(_cwd())
+
+
+def _require_session(store: StateStore) -> PairedSession:
+    session = _resolve_session(store)
+    if session is None:
+        click.echo(
+            "No tandem session for this directory. Run `tandem` to start one.",
+            err=True,
+        )
+        sys.exit(1)
+    store.touch_used(session.tandem_id)
+    return session
+
+
+def _check_versions(warn_only: bool = False) -> dict[str, str | None]:
+    versions: dict[str, str | None] = {}
+    for hid in ("claude", "codex"):
+        adapter = get_adapter(hid)
+        v = adapter.detect_version()
+        versions[hid] = v
+        if v is None:
+            msg = f"{adapter.display_name} ({adapter.binary}) not found on PATH."
+            if warn_only:
+                click.secho(f"warning: {msg}", fg="yellow", err=True)
+            else:
+                click.secho(f"error: {msg}", fg="red", err=True)
+                sys.exit(1)
+        elif not adapter.version_supported(v):
+            tested = compat.COMPAT[hid].tested
+            click.secho(
+                f"warning: {adapter.display_name} version {v!r} is outside the "
+                f"range tandem was built against (tested: {tested}). "
+                f"Run `tandem doctor` before trusting sync.",
+                fg="yellow",
+                err=True,
+            )
+    return versions
+
+
+@click.group(invoke_without_command=True)
+@click.version_option(package_name="tandem")
+@click.option(
+    "--active",
+    type=click.Choice(["claude", "codex"]),
+    default="claude",
+    show_default=True,
+    help="Initially active harness for the fresh session.",
+)
+@click.pass_context
+def main(ctx: click.Context, active: str) -> None:
+    """Run Claude Code and Codex as one paired session.
+
+    With no subcommand, pairs a fresh session and enters the active
+    harness; `tandem resume` continues an earlier one.
+    """
+    if ctx.invoked_subcommand is None:
+        _interactive(active)
+
+
+def _pair_session(store: StateStore, cwd: str, active: str) -> PairedSession:
+    """Create a fresh paired session: state row, seeded shadow transcript,
+    write-ahead cursor, memory sync. Echoes what it did."""
+    shadow = other(active)
+    claude_sid = get_adapter("claude").mint_session_id()
+    codex_sid = None if active == "codex" else get_adapter("codex").mint_session_id()
+    session = store.create_session(cwd, active, claude_sid, codex_sid)
+
+    ctx = SessionContext(
+        tandem_id=session.tandem_id,
+        cwd=cwd,
+        direction="claude->codex" if active == "claude" else "codex->claude",
+        claude_session_id=claude_sid,
+        codex_session_id=codex_sid,
+    )
+    note = SEED_NOTE.format(
+        tandem_id=session.tandem_id,
+        other=get_adapter(active).display_name,
+    )
+    # The shadow transcript is created now so it is resume-ready from the
+    # first turn. The active side's file is created by the harness itself
+    # at first launch (claude is pinned via --session-id; codex mints its
+    # own id which tandem captures on first run).
+    shadow_adapter = get_adapter(shadow)
+    if shadow == "claude":
+        shadow_adapter.create_shadow_transcript(cwd, claude_sid, ctx, note)
+        cursor_updates = {"claude_leaf_uuid": ctx.claude_leaf_uuid}
+    else:
+        shadow_adapter.create_shadow_transcript(cwd, codex_sid, ctx, note)
+        cursor_updates = {}
+    cursor = store.get_cursor(session.tandem_id, active)
+    cursor.pending.update(cursor_updates)
+    store.save_cursor(cursor)
+
+    from .memory_sync import sync_memory_files
+
+    mem = sync_memory_files(cwd)
+    click.echo(f"paired {session.tandem_id} ({active} active, {shadow} shadow)")
+    for a in mem.actions:
+        click.echo(f"  memory: {a}")
+    for w in mem.warnings:
+        click.secho(f"  memory: {w}", fg="yellow", err=True)
+    if active == "codex":
+        click.echo("  note: codex session id will be captured on first run")
+    return session
+
+
+@main.command()
+def status() -> None:
+    """Show the paired session for this directory."""
+    with StateStore() as store:
+        session = _require_session(store)
+        versions = _check_versions(warn_only=True)
+        click.echo(f"tandem session {session.tandem_id}  ({session.cwd})")
+        click.echo(f"  created:   {session.created_at}")
+        click.echo(f"  last sync: {session.last_sync_at or 'never'}")
+        for hid in ("claude", "codex"):
+            adapter = get_adapter(hid)
+            sid = getattr(session, f"{hid}_session_id")
+            role = "ACTIVE" if session.active == hid else "shadow"
+            path = adapter.transcript_path(session.cwd, sid) if sid else None
+            click.echo(f"  {adapter.display_name:<12} {role}")
+            click.echo(f"    version: {versions.get(hid) or 'not installed'}")
+            click.echo(f"    session: {sid or '(pending first run)'}")
+            click.echo(f"    file:    {path or '(not created yet)'}")
+        from . import ops
+
+        for source in ("claude", "codex"):
+            cursor = store.get_cursor(session.tandem_id, source)
+            behind = ops.unsynced_lines(session, store, source)
+            if cursor.updated_at or cursor.failed_turns or behind:
+                line = (
+                    f"  sync from {source}: line {cursor.line_index}, "
+                    f"turn {cursor.turn_index}, failed turns: {cursor.failed_turns}"
+                )
+                if behind and source == session.active:
+                    line += f", {behind} lines awaiting translation"
+                click.echo(line)
+        qdir = paths.quarantine_dir(session.tandem_id)
+        if qdir.is_dir() and any(qdir.iterdir()):
+            click.echo(f"  quarantine: {qdir} (has entries)")
+
+
+@main.command()
+@click.argument("tandem_id", required=False)
+def resume(tandem_id: str | None) -> None:
+    """Resume a paired session (most recent for this directory by default).
+
+    The id is printed when you leave a session, and shown by `tandem status`.
+    """
+    cwd = _cwd()
+    _check_versions(warn_only=True)
+    with StateStore() as store:
+        if tandem_id is None:
+            session = store.latest_session_for_cwd(cwd)
+            if session is None:
+                click.echo(
+                    "No tandem session for this directory. Run `tandem` to start one.",
+                    err=True,
+                )
+                sys.exit(1)
+        else:
+            session = store.get_session(tandem_id)
+            if session is None:
+                click.secho(f"error: no tandem session {tandem_id!r}.", fg="red", err=True)
+                sys.exit(1)
+            if session.cwd != cwd:
+                click.secho(
+                    f"error: session {tandem_id} belongs to {session.cwd}; "
+                    "run `tandem resume` from there.",
+                    fg="red",
+                    err=True,
+                )
+                sys.exit(1)
+        store.touch_used(session.tandem_id)
+    sys.exit(_enter_session(session))
+
+
+def _default_sink_factory(store, session, source):
+    """Sync engine by default; TANDEM_LOG_EVENTS=1 switches to the debug
+    event logger (no shadow writes)."""
+    import os
+
+    from .runner import EventLogger
+    from .sync import SyncEngine
+
+    if os.environ.get("TANDEM_LOG_EVENTS"):
+        return EventLogger(session.tandem_id, source)
+    return SyncEngine(store, session, source)
+
+
+def _report_switch(old: str, new_active: str, problems, mem) -> None:
+    """Report the outcome of a role flip. Shared by the one-shot `switch`
+    command and the tandem prompt's `switch`, so neither path drops
+    memory-sync actions or the may-not-resume advisory."""
+    click.echo(
+        f"active harness: {get_adapter(old).display_name} -> "
+        f"{get_adapter(new_active).display_name}"
+    )
+    for a in mem.actions:
+        click.echo(f"  memory: {a}")
+    for w in mem.warnings:
+        click.secho(f"  memory: {w}", fg="yellow", err=True)
+    for p in problems:
+        click.secho(f"  warning: {p}", fg="yellow", err=True)
+    if problems:
+        click.secho(
+            "  the newly active session may not resume cleanly; "
+            "run `tandem doctor` for details.",
+            fg="yellow",
+            err=True,
+        )
+
+
+@main.command()
+def switch() -> None:
+    """Make the shadow harness active (instant; no re-conversion)."""
+    from . import ops
+
+    with StateStore() as store:
+        session = _require_session(store)
+        old = session.active
+        try:
+            new_active, problems, mem = ops.switch_session(store, session)
+        except Exception as exc:
+            click.secho(f"switch failed: {exc}", fg="red", err=True)
+            sys.exit(1)
+        _report_switch(old, new_active, problems, mem)
+        click.echo("Run `tandem resume` to continue in the new harness.")
+
+
+@main.command(name="run")
+@click.option(
+    "--on",
+    "target",
+    type=click.Choice(["claude", "codex"]),
+    required=True,
+    help="Harness to route this one prompt to.",
+)
+@click.argument("prompt", nargs=-1, required=True)
+def run_cmd(target: str, prompt: tuple[str, ...]) -> None:
+    """Run one prompt on the other harness, then return control.
+
+    The resulting turn lands in both session files with attribution."""
+    from . import ops
+
+    text = " ".join(prompt)
+    with StateStore() as store:
+        session = _require_session(store)
+        if target == session.active:
+            click.secho(
+                f"note: {target} is already the active harness; running the "
+                "turn there anyway.",
+                fg="yellow",
+                err=True,
+            )
+        code = ops.run_oneoff(store, session, target, text)
+    sys.exit(code)
+
+
+@main.command()
+@click.option(
+    "--live",
+    is_flag=True,
+    help="Also perform a real resume on both sessions (costs one small model "
+    "call per harness).",
+)
+def doctor(live: bool) -> None:
+    """Validate that both session files are resumable; report drift."""
+    from .doctor import run_doctor
+
+    with StateStore() as store:
+        session = _resolve_session(store)
+        report = run_doctor(store, session, live=live)
+    icons = {"ok": ("✓", "green"), "warn": ("!", "yellow"), "fail": ("✗", "red")}
+    for check in report.checks:
+        icon, color = icons[check.status]
+        click.secho(f" {icon} {check.message}", fg=color if check.status != "ok" else None)
+    if report.failed:
+        sys.exit(1)
+    click.echo("all checks passed" if not any(
+        c.status == "warn" for c in report.checks
+    ) else "passed with warnings")
+
+
+@main.command(name="sync-mcp")
+@click.confirmation_option(
+    prompt="Copy MCP server definitions between ~/.claude.json and "
+    "~/.codex/config.toml (additive, never overwrites existing entries)?"
+)
+def sync_mcp() -> None:
+    """Copy MCP server configs between the two harnesses (opt-in)."""
+    from .memory_sync import copy_mcp
+
+    report = copy_mcp()
+    for a in report.actions:
+        click.echo(f"  {a}")
+    for w in report.warnings:
+        click.secho(f"  warning: {w}", fg="yellow", err=True)
+
+
+@main.command()
+def sync() -> None:
+    """Catch up shadow translation manually (pure local file I/O)."""
+    from . import ops
+
+    with StateStore() as store:
+        session = _require_session(store)
+        n = ops.drain_source(store, session, session.active)
+        click.echo(f"synced {n} new transcript lines from {session.active}.")
+
+
+def _interactive(active: str) -> None:
+    cwd = _cwd()
+    _check_versions()  # hard: pairing needs both binaries on PATH
+    with StateStore() as store:
+        session = _pair_session(store, cwd, active)
+    sys.exit(_enter_session(session))
+
+
+def _enter_session(session: PairedSession) -> int:
+    from .shell import run_shell
+
+    return run_shell(session.tandem_id, _default_sink_factory)
+
+
+if __name__ == "__main__":
+    main()

tandem/compat.py

@@ -0,0 +1,62 @@
+"""Pinned CLI compatibility table and installed-version detection.
+
+Both session formats are internal to their CLIs and drift between releases.
+Tandem pins the ranges it was built against; outside a range we warn and
+require `tandem doctor` before enabling sync (see cli.py).
+"""
+
+from __future__ import annotations
+
+import functools
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CompatRange:
+    tested: str          # exact version this code was developed against
+    min_version: tuple[int, ...]
+    max_exclusive: tuple[int, ...]
+
+
+# Format observations in docs/formats.md correspond to these versions.
+COMPAT: dict[str, CompatRange] = {
+    "claude": CompatRange(tested="2.1.220", min_version=(2, 0), max_exclusive=(3,)),
+    "codex": CompatRange(tested="0.145.0", min_version=(0, 140), max_exclusive=(0, 150)),
+}
+
+_VERSION_RE = re.compile(r"(\d+(?:\.\d+)+)")
+
+
+def parse_version(text: str) -> tuple[int, ...] | None:
+    m = _VERSION_RE.search(text)
+    if not m:
+        return None
+    return tuple(int(x) for x in m.group(1).split("."))
+
+
+@functools.lru_cache(maxsize=8)
+def detect_cli_version(binary: str) -> str | None:
+    """Return the raw version string of an installed CLI, or None if absent.
+    Cached for the process lifetime (renderers stamp it on every entry)."""
+    if shutil.which(binary) is None:
+        return None
+    try:
+        out = subprocess.run(
+            [binary, "--version"], capture_output=True, text=True, timeout=20
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if out.returncode != 0:
+        return None
+    return out.stdout.strip() or out.stderr.strip() or None
+
+
+def version_supported(harness: str, version_text: str) -> bool:
+    rng = COMPAT[harness]
+    v = parse_version(version_text)
+    if v is None:
+        return False
+    return rng.min_version <= v < rng.max_exclusive

tandem/constants.py

@@ -0,0 +1,23 @@
+"""Shared literals: attribution markers and placeholder wording."""
+
+ATTRIBUTION = {
+    "claude": "[via claude-code]",
+    "codex": "[via codex]",
+    "tandem": "[tandem]",
+    "user": "",
+}
+
+SEED_NOTE = (
+    "[tandem] This session is one half of tandem paired session {tandem_id}. "
+    "It was created by tandem (no model has run here yet). Turns executed in "
+    "{other} are synced below as context; text messages are tagged "
+    "[via claude-code] or [via codex] by the agent that produced them. Tool "
+    "calls from the other agent are mirrored as native tool-call records in "
+    "this session's own tool vocabulary."
+)
+
+# Untranslatable-entry placeholder (decision for the spec's open question).
+PLACEHOLDER = (
+    "[tandem: turn {turn} could not be translated from {source} — {reason}; "
+    "raw entry quarantined at {quarantine}]"
+)

tandem/converter.py

@@ -0,0 +1,140 @@
+"""TraceConverter adapter interface + the reference implementation.
+
+The interface mirrors the spec so an external bidirectional converter can be
+swapped in without touching the sync engine:
+
+    translate_entry(entry, direction, ctx) -> list[target entries] | TranslationError
+
+The reference implementation goes through the normalized event model:
+source adapter parses the native entry, this module applies the sync policy
+(attribution tagging, tool-call pairing into native target-vocabulary pairs
+via `toolmap`, dropping non-portable content), and the target adapter renders
+native entries.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Protocol, runtime_checkable
+
+from . import toolmap
+from .constants import ATTRIBUTION
+from .events import (
+    AssistantMessage,
+    NormalizedEvent,
+    SessionContext,
+    ToolCall,
+    ToolResult,
+    UserMessage,
+)
+from .harness import get_adapter, other
+from .summarize import summarize_orphan_result
+
+Direction = Literal["claude->codex", "codex->claude"]
+
+
+@dataclass
+class TranslationError:
+    reason: str
+    entry_summary: str = ""
+
+
+@runtime_checkable
+class TraceConverter(Protocol):
+    def translate_entry(
+        self, entry: dict[str, Any], direction: Direction, ctx: SessionContext
+    ) -> list[dict[str, Any]] | TranslationError: ...
+
+
+class ReferenceConverter:
+    """parse -> normalize -> policy -> render. Handles user messages,
+    assistant text, tool calls and system/compaction events (skip or one-line
+    note).
+
+    Tool activity emits at the result: the call is stashed on arrival, and
+    when its result lands the pair is mapped into the target harness's own
+    tool vocabulary (`toolmap.map_pair`) and emitted as two adjacent events,
+    so the shadow reads as the shadow's own work. A result with no stashed
+    call falls back to a prose note — never a lone native tool_result, which
+    both replay APIs reject."""
+
+    def translate_entry(
+        self, entry: dict[str, Any], direction: Direction, ctx: SessionContext
+    ) -> list[dict[str, Any]] | TranslationError:
+        source_id, target_id = direction.split("->")
+        source = get_adapter(source_id)
+        target = get_adapter(target_id)
+        try:
+            events = source.parse_entry(entry, ctx)
+            out_events = self._apply_policy(events, source_id, ctx)
+            if not out_events:
+                return []
+            return target.render_events(out_events, ctx)
+        except Exception as exc:  # localize any surprise to this one entry
+            return TranslationError(
+                reason=f"{type(exc).__name__}: {exc}",
+                entry_summary=str(entry.get("type", "?")),
+            )
+
+    def _apply_policy(
+        self, events: list[NormalizedEvent], source_id: str, ctx: SessionContext
+    ) -> list[NormalizedEvent]:
+        tag = ATTRIBUTION[source_id]
+        out: list[NormalizedEvent] = []
+        for ev in events:
+            if isinstance(ev, UserMessage):
+                out.append(ev.model_copy(update={"text": f"{tag} {ev.text}".strip()}))
+            elif isinstance(ev, AssistantMessage):
+                if ev.text.strip():
+                    out.append(ev.model_copy(update={"text": f"{tag} {ev.text}"}))
+            elif isinstance(ev, ToolCall):
+                ctx.pending_calls[ev.call_id] = ev.model_dump(exclude_none=True)
+            elif isinstance(ev, ToolResult):
+                stored = ctx.pending_calls.pop(ev.call_id, None) if ev.call_id else None
+                if stored:
+                    # _structured is the codex adapter's out-of-band enrichment
+                    # channel, not a ToolCall field (which forbids extras)
+                    stored.pop("_structured", None)
+                    call = ToolCall.model_validate(stored)
+                    out.extend(toolmap.map_pair(call, ev, other(source_id)))
+                else:
+                    # no stashed call to pair with, so a native tool_result
+                    # would dangle and break resume: prose instead
+                    out.append(
+                        AssistantMessage(
+                            source=ev.source,
+                            timestamp=ev.timestamp,
+                            turn_index=ev.turn_index,
+                            text=f"{tag} {summarize_orphan_result(ev)}",
+                            phase="commentary",
+                        )
+                    )
+            elif ev.kind == "system" and ev.subtype == "compaction":
+                out.append(
+                    AssistantMessage(
+                        source="tandem",
+                        turn_index=ev.turn_index,
+                        text=f"{ATTRIBUTION['tandem']} (the {source_id} side compacted "
+                        "its conversation history here)",
+                        phase="commentary",
+                    )
+                )
+            # thinking and other system events: dropped
+        return out
+
+    def flush_dangling(self, ctx: SessionContext) -> list[NormalizedEvent]:
+        """Mapped call + placeholder-result pairs for every pending call.
+        Both replay APIs reject a call without a result, so a drained source
+        must never leave one behind. Clears ctx.pending_calls."""
+        target_id = ctx.direction.split("->")[1]
+        out: list[NormalizedEvent] = []
+        for call_id, stored in list(ctx.pending_calls.items()):
+            stored.pop("_structured", None)
+            call = ToolCall.model_validate(stored)
+            placeholder = ToolResult(
+                source=call.source, turn_index=call.turn_index,
+                call_id=call_id, output=toolmap.PLACEHOLDER_OUTPUT,
+            )
+            out.extend(toolmap.map_pair(call, placeholder, target_id))
+        ctx.pending_calls.clear()
+        return out