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

session_bridge/skill_install.py

@@ -0,0 +1,134 @@
+"""Bootstrap the packaged agent skill into every harness on this machine.
+
+Harnesses that support the SKILL.md convention read from a per-user skills
+directory (``~/.claude/skills``, ``~/.codex/skills``, ``~/.hermes/skills``).
+``install_skill`` links (or copies) the packaged ``session-handoff`` skill
+into each harness home that actually exists, so one install command makes the
+handoff instructions available everywhere — the agent-skills bootstrap
+pattern.
+
+Symlink is the default (the skill tracks the installed package; re-installing
+session-bridge updates every harness at once); ``copy`` decouples the skill
+from the package at the cost of going stale. Existing foreign files are never
+silently replaced — that requires ``force``, matching the no-silent-overwrite
+rule everywhere else in this codebase.
+"""
+
+from __future__ import annotations
+
+import filecmp
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+SKILL_NAME = "session-handoff"
+
+#: Default per-user home of each supported harness. A harness is "available"
+#: when this directory exists; its skills dir is created on demand.
+HARNESS_HOMES: dict[str, str] = {
+    "claude-code": "~/.claude",
+    "codex": "~/.codex",
+    "hermes": "~/.hermes",
+}
+
+
+def packaged_skill_dir() -> Path:
+    """Filesystem path of the skill shipped inside this package."""
+    from importlib.resources import files
+
+    return Path(str(files("session_bridge") / "skills" / SKILL_NAME))
+
+
+@dataclass(frozen=True)
+class InstallResult:
+    harness: str
+    target: Path | None
+    action: str  # "linked" | "copied" | "up-to-date" | "skipped" | "error"
+    detail: str
+
+
+def _is_current(target: Path, source: Path) -> bool:
+    """Already installed and pointing at (or identical to) this source?"""
+    if target.is_symlink():
+        try:
+            return target.resolve() == source.resolve()
+        except OSError:
+            return False
+    manifest = target / "SKILL.md"
+    if manifest.is_file():
+        try:
+            return filecmp.cmp(manifest, source / "SKILL.md", shallow=False)
+        except OSError:
+            return False
+    return False
+
+
+def install_skill(
+    harness_homes: dict[str, Path],
+    *,
+    source: Path | None = None,
+    copy: bool = False,
+    force: bool = False,
+) -> list[InstallResult]:
+    """Install the packaged skill into each existing harness home.
+
+    Never raises for a single harness: each one reports its own outcome so
+    one broken home cannot abort the others.
+    """
+    src = source if source is not None else packaged_skill_dir()
+    results: list[InstallResult] = []
+    if not (src / "SKILL.md").is_file():
+        return [
+            InstallResult(
+                harness="*",
+                target=None,
+                action="error",
+                detail=f"packaged skill not found at {src}",
+            )
+        ]
+
+    for harness, home in harness_homes.items():
+        home = Path(home).expanduser()
+        if not home.is_dir():
+            results.append(
+                InstallResult(harness, None, "skipped", f"{home} does not exist")
+            )
+            continue
+        target = home / "skills" / SKILL_NAME
+        try:
+            if target.is_symlink() or target.exists():
+                if _is_current(target, src):
+                    results.append(
+                        InstallResult(harness, target, "up-to-date", str(target))
+                    )
+                    continue
+                if not force:
+                    results.append(
+                        InstallResult(
+                            harness,
+                            target,
+                            "error",
+                            f"{target} already exists and differs; "
+                            "re-run with --force to replace it",
+                        )
+                    )
+                    continue
+                if target.is_symlink() or target.is_file():
+                    target.unlink()
+                else:
+                    shutil.rmtree(target)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            if copy:
+                shutil.copytree(src, target)
+                results.append(InstallResult(harness, target, "copied", str(target)))
+            else:
+                os.symlink(src.resolve(), target, target_is_directory=True)
+                results.append(
+                    InstallResult(
+                        harness, target, "linked", f"{target} -> {src.resolve()}"
+                    )
+                )
+        except OSError as exc:
+            results.append(InstallResult(harness, target, "error", str(exc)))
+    return results

session_bridge/skills/session-handoff/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: session-handoff
+description: Hand off the CURRENT agent session to another harness (Claude Code, Codex, or Hermes) so the user can resume it there. Use when the user says "move/continue this session in <harness>", "convert this session", "hand off to codex/hermes/claude", or when a usage limit is about to stop this session. The source is the session this skill runs in; the destination is whatever harness the user names.
+---
+
+# Session handoff: continue this session in another harness
+
+You are running inside a coding-agent session. The user wants this session
+(or another one they name) to become resumable in a different harness. Use
+the `session-bridge` CLI from this repo to do it. Everything is local files;
+no network.
+
+```
+locate source file ─▶ inspect ─▶ convert or register ─▶ give resume command
+```
+
+## 0. Ensure session-bridge is installed
+
+```bash
+session-bridge --help >/dev/null 2>&1 || python3 -m pip install -e <path-to-this-repo>
+```
+
+(`<path-to-this-repo>` = the repo containing this skill file.)
+
+## 1. Locate the source session file (the session you are in)
+
+| You are running in | Where the transcript lives |
+|---|---|
+| Claude Code | `~/.claude/projects/<encoded-cwd>/<session-uuid>.jsonl` |
+| Codex | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` |
+| Hermes | `~/.hermes/sessions/<ts>_<id>.jsonl` (exports; state.db is the truth) |
+
+- **Claude Code:** encode the project cwd the way Claude Code does — resolve
+  the real path (`os.path.realpath`; macOS symlinks like `/tmp` →
+  `/private/tmp` matter), then replace every `/` with `-`. List that
+  directory's `*.jsonl` by mtime; the newest one being actively written is
+  the current session. Confirm by grepping it for a distinctive string from
+  the current conversation.
+- **Codex / Hermes:** newest file under the sessions tree, same confirmation
+  grep.
+- If the user names a *different* session ("yesterday's session about X"),
+  find it the same way — by store, mtime, and a content grep — or run
+  `session-bridge tui` and let the user pick from the discovery list.
+
+## 2. Inspect before converting
+
+```bash
+session-bridge inspect --from <source-harness> <file>
+```
+
+Check the pending state it prints. If there are **open tool calls** (the
+session stopped mid-turn), plan to add `--stub-open-calls` in step 3 —
+providers reject a transcript whose tool call has no result, so the flag
+appends a synthetic interrupted result and the handshake still discloses it.
+
+## 3. Convert or register, by destination
+
+Harness names: `claude-code`, `codex`, `hermes`.
+
+**Destination Claude Code** — file placement is enough:
+
+```bash
+session-bridge convert --from <source> --to claude-code <file> \
+  --place-claude-cwd <project-cwd> [--stub-open-calls]
+```
+
+It prints the placed path and the exact resume command
+(`cd <cwd> && claude --resume <uuid>`). The cwd you place for must be the
+directory the user will launch `claude` from.
+
+**Destination Hermes** — needs a SQLite registration (a file drop is NOT
+resumable):
+
+```bash
+session-bridge register --from <source> <file> \
+  --model <hermes-configured-model> --title "<short title>" [--stub-open-calls]
+```
+
+`--model` matters: a cross-harness source id (e.g. `claude-*`) that Hermes
+cannot route makes the resumed turn silently lose context. Ask the user
+which Hermes model to use, or check `~/.hermes/` config. Resume:
+`hermes --resume <printed sb_… id>`.
+
+**Destination Codex** — rollout + SQLite index:
+
+```bash
+session-bridge register-codex --from <source> <file> \
+  --cwd <project-cwd> --title "<short title>" [--stub-open-calls]
+```
+
+The model defaults to the most recently used one for provider `openai`;
+pass `--model`/`--model-provider` if the user wants otherwise. Resume:
+`cd <cwd> && codex resume <uuid>`.
+
+Both register commands back up the store first and print the backup path —
+keep `--no-backup` off unless the user explicitly asks.
+
+## 4. Finish
+
+- Relay the printed **resume command** to the user verbatim; that is the
+  deliverable.
+- Conversion notes on stderr list what could not transfer losslessly
+  (thread forks, tool schemas, reasoning signatures, …). Summarize any that
+  matter; the same notes are embedded in the transcript's resume handshake,
+  so the receiving agent will see them too.
+- A handoff of the CURRENT session captures it only up to the last flushed
+  turn — anything after the conversion runs is not carried over, so run the
+  handoff last, right before the user switches tools.
+
+## Pitfalls
+
+- Never `--force`/overwrite an existing placed transcript unless the user
+  confirms — it may be a previously recovered session.
+- Session ids must be UUID-shaped for Codex; let the tool generate them.
+- Transcripts can contain secrets. Never commit converted session files;
+  write outputs outside the repo (`fixtures/real/` is gitignored for a
+  reason).
+- Prefer `session-bridge tui` when the user should choose interactively;
+  prefer the plain CLI when you already know source, file, and destination.

session_bridge/tui/actions.py

@@ -0,0 +1,123 @@
+"""Side-effect layer behind the TUI's convert flow.
+
+Split in two so the TUI can preview before committing:
+
+- ``run_conversion`` is PURE — it produces a ``ConversionResult`` (records,
+  loss report, handshake text) without touching the filesystem, so the TUI can
+  render a preview and let the user back out.
+- ``execute_writes`` performs every write the CLI's ``convert`` command would
+  (output JSONL, optional handshake file, optional Claude Code placement) and
+  reports the outcome as data. It never raises: the TUI renders errors, and a
+  partial outcome (e.g. output written but placement refused) must survive the
+  failure so the user knows what actually landed on disk.
+"""
+
+from __future__ import annotations
+
+import shlex
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+
+from .._ids import UnsafeSessionIdError
+from ..convert import ConversionResult, convert, dump_jsonl, now_codex_timestamp
+from ..place import SessionExistsError, UnsafeCwdError, place_claude_code
+from .options import ConvertOptions, resolve_output
+
+
+def run_conversion(opts: ConvertOptions) -> ConversionResult:
+    """Convert per ``opts`` without writing anything.
+
+    Stamps Codex output with the real current time, matching the CLI (the
+    writer's placeholder date would hide the session from Codex's recency
+    sort).
+    """
+    codex_ts = now_codex_timestamp() if opts.target == "codex" else None
+    return convert(
+        opts.source,
+        opts.target,
+        opts.path,
+        inject_handshake=not opts.no_handshake,
+        codex_timestamp=codex_ts,
+        stub_open_calls=opts.stub_open_calls,
+    )
+
+
+@dataclass
+class WriteOutcome:
+    output_path: Path | None
+    record_count: int
+    handshake_path: Path | None
+    placed_path: Path | None
+    resume_hint: str | None
+    error: str | None  # None = full success
+
+
+def execute_writes(
+    result: ConversionResult,
+    opts: ConvertOptions,
+    *,
+    claude_home: Path | None = None,
+) -> WriteOutcome:
+    """Perform all writes for a previously-run conversion.
+
+    Errors are returned, never raised. Paths that were successfully written
+    before the failure stay set in the outcome alongside ``error``.
+    """
+    output_path: Path | None = None
+    handshake_path: Path | None = None
+    placed_path: Path | None = None
+    resume_hint: str | None = None
+
+    def outcome(error: str | None) -> WriteOutcome:
+        return WriteOutcome(
+            output_path=output_path,
+            record_count=len(result.records),
+            handshake_path=handshake_path,
+            placed_path=placed_path,
+            resume_hint=resume_hint,
+            error=error,
+        )
+
+    try:
+        # A codex target's session_meta timestamp was stamped when the dry-run
+        # conversion ran; the user may sit on that screen indefinitely, and the
+        # CLI stamps immediately before writing. Re-run the (pure) conversion
+        # so the written timestamp is bound to the write, like the CLI's.
+        if opts.target == "codex":
+            result = run_conversion(opts)
+
+        out = resolve_output(opts)
+        dump_jsonl(result.records, out)
+        output_path = Path(out)
+
+        if opts.handshake_out:
+            hs = Path(opts.handshake_out)
+            hs.write_text(result.handshake, encoding="utf-8")
+            handshake_path = hs
+
+        if opts.place_claude_cwd:
+            session_id = opts.session_id or str(uuid.uuid4())
+            placed_path = place_claude_code(
+                result.records,
+                opts.place_claude_cwd,
+                session_id,
+                claude_home=claude_home,
+                overwrite=opts.force,
+            )
+            # Same hint the CLI prints after a successful placement.
+            resume_hint = (
+                f"(cd {shlex.quote(opts.place_claude_cwd)} "
+                f"&& claude --resume {shlex.quote(session_id)})"
+            )
+    except (
+        UnsafeSessionIdError,
+        UnsafeCwdError,
+        SessionExistsError,
+        OSError,
+        # The codex re-conversion re-reads the source file, which can have
+        # changed since the dry run: parse failures are ValueErrors.
+        ValueError,
+    ) as exc:
+        return outcome(str(exc))
+    return outcome(None)

session_bridge/tui/app.py

@@ -0,0 +1,65 @@
+"""The session-bridge TUI application shell.
+
+Importing this module requires textual (the ``[tui]`` extra); cli.py imports it
+lazily and prints an install hint when the import fails.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from textual.app import App
+
+from .screens import PickerScreen
+
+
+class SessionBridgeApp(App):
+    """Linear convert wizard: pick a session, inspect, configure, dry-run, write."""
+
+    TITLE = "session-bridge"
+    CSS = """
+    #picker-status { padding: 0 1; color: $text-muted; }
+    #sessions { height: 1fr; }
+    VerticalScroll { padding: 1 2; }
+    .switch-row { height: auto; align-vertical: middle; }
+    .switch-row Label { padding: 1 0 0 1; }
+    #place-group { border: round $primary; padding: 0 1; margin: 1 0; }
+    #form-errors { color: $error; }
+    #dryrun-buttons { height: auto; padding: 0 2 1 2; }
+    #dryrun-buttons Button { margin-right: 2; }
+    #plan-buttons { height: auto; padding: 0 2 1 2; }
+    #plan-buttons Button { margin-right: 2; }
+    Label { margin-top: 1; }
+    """
+
+    def __init__(
+        self,
+        *,
+        claude_home: Optional[Path] = None,
+        codex_home: Optional[Path] = None,
+        hermes_home: Optional[Path] = None,
+    ) -> None:
+        super().__init__()
+        # Explicit store overrides (tests and unusual layouts); None means the
+        # discovery module's real defaults (~/.claude, ~/.codex, ~/.hermes).
+        self.claude_home = claude_home
+        self.codex_home = codex_home
+        self.hermes_home = hermes_home
+
+    def on_mount(self) -> None:
+        self.push_screen(PickerScreen())
+
+
+def run_tui(
+    *,
+    claude_home: Optional[Path] = None,
+    codex_home: Optional[Path] = None,
+    hermes_home: Optional[Path] = None,
+) -> int:
+    SessionBridgeApp(
+        claude_home=claude_home,
+        codex_home=codex_home,
+        hermes_home=hermes_home,
+    ).run()
+    return 0

session_bridge/tui/discovery.py

@@ -0,0 +1,208 @@
+"""Cheap session discovery across the three harness stores.
+
+The TUI needs a fast, fault-tolerant listing of every session on disk without
+paying for a full parse of each transcript. Each scanner reads only the head of
+a file (``_head_lines``) to extract identity metadata (session id, cwd) and a
+one-line preview, and stats each file exactly once.
+
+Design rules:
+- Never raise for a single bad file: any candidate that cannot be read or
+  parsed is silently skipped so one corrupt transcript cannot blank the picker.
+- Never decode Claude Code's dashed project directory names back into a cwd —
+  that encoding is lossy ("-" is both the separator and a literal). The cwd is
+  taken from the records themselves.
+- This module imports only stdlib + session_bridge internals; it must stay
+  usable without the optional TUI framework installed.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+_PREVIEW_LIMIT = 120
+
+
+@dataclass(frozen=True)
+class SessionEntry:
+    harness: str  # one of convert.HARNESSES
+    path: Path
+    mtime: float
+    size: int
+    session_id: str | None
+    cwd: str | None
+    preview: str | None  # first user-message text, truncated
+
+
+# Real Claude Code transcripts open with a variable-length preamble of header
+# records (file-history-snapshot, ai-title, last-prompt, ...) before the first
+# user turn, so the head window must reach well past it to find cwd/preview.
+_HEAD_WINDOW = 64
+# Identity/preview metadata lives near the head in small records; cap the read
+# so one pathological single-line file cannot exhaust memory mid-scan.
+_MAX_LINE_BYTES = 1 << 20
+
+
+def _head_lines(path: Path, n: int = _HEAD_WINDOW) -> list[dict]:
+    """Parse the first ``n`` JSON lines of a JSONL file, skipping bad lines."""
+    records: list[dict] = []
+    with open(path, encoding="utf-8", errors="replace") as fh:
+        for _ in range(n):
+            line = fh.readline(_MAX_LINE_BYTES)
+            if not line:
+                break
+            if len(line) >= _MAX_LINE_BYTES and not line.endswith("\n"):
+                break  # over-long line: stop rather than misparse its remainder
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(obj, dict):
+                records.append(obj)
+    return records
+
+
+def _truncate(text: str) -> str | None:
+    text = text.strip()
+    if not text:
+        return None
+    if len(text) > _PREVIEW_LIMIT:
+        return text[: _PREVIEW_LIMIT - 1] + "…"
+    return text
+
+
+def _joined_text(content: object, text_key: str = "text") -> str:
+    """Flatten a message content value (str or list of blocks) to plain text."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for block in content:
+            if isinstance(block, dict) and isinstance(block.get(text_key), str):
+                parts.append(block[text_key])
+        return "\n".join(parts)
+    return ""
+
+
+def scan_claude_code(claude_home: Path | None = None) -> list[SessionEntry]:
+    home = Path(claude_home) if claude_home is not None else Path.home() / ".claude"
+    entries: list[SessionEntry] = []
+    for path in sorted(home.glob("projects/*/*.jsonl")):
+        try:
+            stat = path.stat()
+            head = _head_lines(path)
+            cwd = None
+            preview = None
+            for rec in head:
+                if cwd is None and isinstance(rec.get("cwd"), str):
+                    cwd = rec["cwd"]
+                if preview is None and rec.get("type") == "user":
+                    message = rec.get("message")
+                    if isinstance(message, dict):
+                        preview = _truncate(_joined_text(message.get("content")))
+            entries.append(
+                SessionEntry(
+                    harness="claude-code",
+                    path=path,
+                    mtime=stat.st_mtime,
+                    size=stat.st_size,
+                    session_id=path.stem,
+                    cwd=cwd,
+                    preview=preview,
+                )
+            )
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError, KeyError, TypeError, ValueError):
+            continue
+    return entries
+
+
+def scan_codex(codex_home: Path | None = None) -> list[SessionEntry]:
+    home = Path(codex_home) if codex_home is not None else Path.home() / ".codex"
+    entries: list[SessionEntry] = []
+    # Sessions nest under YYYY/MM/DD date directories.
+    for path in sorted(home.glob("sessions/*/*/*/rollout-*.jsonl")):
+        try:
+            stat = path.stat()
+            head = _head_lines(path)
+            session_id = None
+            cwd = None
+            preview = None
+            for rec in head:
+                payload = rec.get("payload")
+                if not isinstance(payload, dict):
+                    continue
+                if rec.get("type") == "session_meta":
+                    if session_id is None and isinstance(payload.get("id"), str):
+                        session_id = payload["id"]
+                    if cwd is None and isinstance(payload.get("cwd"), str):
+                        cwd = payload["cwd"]
+                elif (
+                    preview is None
+                    and rec.get("type") == "response_item"
+                    and payload.get("type") == "message"
+                    and payload.get("role") == "user"
+                ):
+                    preview = _truncate(_joined_text(payload.get("content")))
+            entries.append(
+                SessionEntry(
+                    harness="codex",
+                    path=path,
+                    mtime=stat.st_mtime,
+                    size=stat.st_size,
+                    session_id=session_id,
+                    cwd=cwd,
+                    preview=preview,
+                )
+            )
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError, KeyError, TypeError, ValueError):
+            continue
+    return entries
+
+
+def scan_hermes(hermes_home: Path | None = None) -> list[SessionEntry]:
+    home = Path(hermes_home) if hermes_home is not None else Path.home() / ".hermes"
+    entries: list[SessionEntry] = []
+    for path in sorted(home.glob("sessions/*.jsonl")):
+        try:
+            stat = path.stat()
+            # The Hermes session id IS the full filename stem (e.g.
+            # "20260416_004124_10f12c82") — it's what state.db sessions.id
+            # holds and what `hermes --resume` expects. Never split it.
+            session_id = path.stem
+            head = _head_lines(path)
+            preview = None
+            for rec in head:
+                if rec.get("role") == "user":
+                    preview = _truncate(_joined_text(rec.get("content")))
+                    break
+            entries.append(
+                SessionEntry(
+                    harness="hermes",
+                    path=path,
+                    mtime=stat.st_mtime,
+                    size=stat.st_size,
+                    session_id=session_id or None,
+                    cwd=None,
+                    preview=preview,
+                )
+            )
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError, KeyError, TypeError, ValueError):
+            continue
+    return entries
+
+
+def discover_sessions(
+    *,
+    claude_home: Path | None = None,
+    codex_home: Path | None = None,
+    hermes_home: Path | None = None,
+) -> list[SessionEntry]:
+    """All sessions across the three stores, newest first."""
+    entries = (
+        scan_claude_code(claude_home)
+        + scan_codex(codex_home)
+        + scan_hermes(hermes_home)
+    )
+    entries.sort(key=lambda entry: entry.mtime, reverse=True)
+    return entries