foreign_sessions.py 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338
  1. """Import sessions from foreign coding agents (Claude Code, Codex CLI). Foreign files are only ever read;
  2. imported history must satisfy the provider role-alternation invariant (see ``_merge_turns``)."""
  3. from __future__ import annotations
  4. import contextlib
  5. import json
  6. import os
  7. import re
  8. import sys
  9. import uuid
  10. from dataclasses import dataclass
  11. from datetime import datetime
  12. from pathlib import Path
  13. from stat import S_ISREG
  14. from typing import Any, Dict, List, Optional, Tuple
  15. from hermes_state_ids import new_session_id
  16. # User-message texts that are really injected context wrappers, not typed input.
  17. _WRAPPER_TAG_RE = re.compile(
  18. r"^<(?:user_instructions|environment_context|recommended_plugins|"
  19. r"skills_instructions|permissions[_-]instructions|turn_context|"
  20. r"command-name|command-message|local-command-stdout|system-reminder)\b", re.IGNORECASE)
  21. _TITLE_MAX = 60
  22. _SOURCE_LABELS = {"claude": "Claude Code", "codex": "Codex CLI"}
  23. _SOURCE_DB_NAMES = {"claude": "claude-code", "codex": "codex-cli"}
  24. @dataclass
  25. class ForeignSession:
  26. """A discoverable session in another tool's on-disk store."""
  27. source: str # "claude" | "codex"
  28. path: Path
  29. mtime: float
  30. cwd: Optional[str] = None
  31. title_guess: Optional[str] = None
  32. turn_count: int = 0
  33. session_id: Optional[str] = None # the foreign tool's own id
  34. @property
  35. def label(self) -> str:
  36. title = (self.title_guess or "").strip() or self.path.stem
  37. return f"[{_SOURCE_LABELS.get(self.source, self.source)}] {title[:_TITLE_MAX]}"
  38. def _read_json_lines(path: Path):
  39. """Yield parsed JSON objects, silently skipping unparseable lines."""
  40. try:
  41. with open(path, "r", encoding="utf-8-sig", errors="replace") as f:
  42. for line in f:
  43. line = line.strip()
  44. if not line:
  45. continue
  46. try:
  47. obj = json.loads(line)
  48. except (json.JSONDecodeError, ValueError):
  49. continue
  50. if isinstance(obj, dict):
  51. yield obj
  52. except OSError:
  53. return
  54. def _block_text(block: Any) -> str:
  55. """Plain text of one content block; tool_result, thinking/reasoning and unknown types yield ''."""
  56. if isinstance(block, str):
  57. return block
  58. if not isinstance(block, dict):
  59. return ""
  60. btype = block.get("type")
  61. if btype in ("text", "input_text", "output_text"):
  62. return text if isinstance(text := block.get("text"), str) else ""
  63. if btype == "tool_use": # Claude Code assistant block
  64. return f"[ran tool: {block.get('name') or 'tool'}]"
  65. return "[image]" if btype == "image" else ""
  66. def _flatten_blocks(content: Any) -> str:
  67. """Flatten a message ``content`` (string or block list) to plain text."""
  68. if isinstance(content, str):
  69. return content
  70. if not isinstance(content, list):
  71. return ""
  72. return "\n\n".join(p for p in (_block_text(b).strip() for b in content) if p)
  73. def _merge_turns(raw_turns: list[tuple[str, str]]) -> list[dict[str, str]]:
  74. """Merge consecutive same-role turns; guarantee strict alternation.
  75. A leading assistant turn (session began before the log window) gets a minimal user stub so the
  76. first message is always ``user``; this is the only place a stub is ever inserted.
  77. """
  78. merged: list[dict[str, str]] = []
  79. for role, text in raw_turns:
  80. if not (text := text.strip()):
  81. continue
  82. if merged and merged[-1]["role"] == role:
  83. merged[-1]["content"] += "\n\n" + text
  84. else:
  85. merged.append({"role": role, "content": text})
  86. if merged and merged[0]["role"] == "assistant":
  87. merged.insert(0, {"role": "user", "content": "(imported conversation begins with an assistant reply)"})
  88. return merged
  89. def _message_turn(message: Any) -> Optional[tuple[str, str]]:
  90. """Normalize one message dict into a ``(role, text)`` turn, or None when it is not importable."""
  91. role = message.get("role") if isinstance(message, dict) else None
  92. if role not in ("user", "assistant"):
  93. return None
  94. text = _flatten_blocks(message.get("content"))
  95. return None if not text or (role == "user" and _WRAPPER_TAG_RE.match(text.lstrip())) else (role, text)
  96. def _first_user_line(turns: list[tuple[str, str]]) -> Optional[str]:
  97. for role, text in turns:
  98. if role == "user" and (line := text.strip().partition("\n")[0].strip()):
  99. return line[:_TITLE_MAX * 2]
  100. return None
  101. def _parsed(turns: list[tuple[str, str]], cwd: Optional[str], session_id: Optional[str],
  102. title: Optional[str] = None) -> dict[str, Any]:
  103. return {"turns": _merge_turns(turns), "cwd": cwd, "title_guess": title or _first_user_line(turns),
  104. "session_id": session_id}
  105. def parse_claude_session(path: Path) -> dict[str, Any]:
  106. """Parse one Claude Code session JSONL into normalized turns + meta."""
  107. turns: list[tuple[str, str]] = []
  108. cwd = summary = session_id = None
  109. for obj in _read_json_lines(path):
  110. otype = obj.get("type")
  111. if otype == "summary":
  112. if isinstance(s := obj.get("summary"), str) and s.strip():
  113. summary = s.strip()
  114. elif otype in ("user", "assistant") and not (obj.get("isSidechain") or obj.get("isMeta")):
  115. if cwd is None and isinstance(obj.get("cwd"), str):
  116. cwd = obj["cwd"]
  117. if session_id is None and isinstance(obj.get("sessionId"), str):
  118. session_id = obj["sessionId"]
  119. if turn := _message_turn(obj.get("message")):
  120. turns.append(turn)
  121. return _parsed(turns, cwd, session_id, summary)
  122. def parse_codex_session(path: Path) -> dict[str, Any]:
  123. """Parse one Codex CLI rollout JSONL into normalized turns + meta."""
  124. turns: list[tuple[str, str]] = []
  125. cwd = session_id = None
  126. for obj in _read_json_lines(path):
  127. otype, payload = obj.get("type"), obj.get("payload")
  128. if not isinstance(payload, dict):
  129. continue
  130. if otype == "session_meta":
  131. if isinstance(payload.get("cwd"), str):
  132. cwd = payload["cwd"]
  133. if isinstance(sid := payload.get("session_id") or payload.get("id"), str):
  134. session_id = sid
  135. elif otype == "response_item":
  136. ptype = payload.get("type")
  137. if ptype == "message" and (turn := _message_turn(payload)): # developer/system payloads skipped
  138. turns.append(turn)
  139. elif ptype in ("custom_tool_call", "function_call", "local_shell_call"):
  140. # Assistant activity; merged into neighbours later. Tool outputs / reasoning skipped.
  141. name = payload.get("name") or payload.get("tool") or "tool"
  142. turns.append(("assistant", f"[ran tool: {name}]"))
  143. return _parsed(turns, cwd, session_id)
  144. # source -> (default root under ~, env override var, subdir under the env root, glob pattern,
  145. # recursive, parser)
  146. _SOURCES = {
  147. "claude": ((".claude", "projects"), "CLAUDE_CONFIG_DIR", "projects", "*/*.jsonl", False,
  148. parse_claude_session),
  149. "codex": ((".codex", "sessions"), "CODEX_HOME", "sessions", "rollout-*.jsonl", True,
  150. parse_codex_session),
  151. }
  152. def _parser(source: str):
  153. return _SOURCES[source][5]
  154. def _default_root(source: str) -> Path:
  155. """Default session store for *source*, honoring the tool's own relocation env var.
  156. Claude Code moves its whole config dir with ``CLAUDE_CONFIG_DIR``; Codex CLI with
  157. ``CODEX_HOME``. A blank/whitespace value is treated as unset (an empty override must not
  158. resolve to a relative ``"projects"`` under the CWD). Ported from cline/cline#13827."""
  159. default_parts, env_var, env_subdir, *_ = _SOURCES[source]
  160. override = os.environ.get(env_var, "").strip()
  161. if override:
  162. return Path(override).expanduser() / env_subdir
  163. return Path.home().joinpath(*default_parts)
  164. def _walk(source: str, root: Optional[Path] = None) -> list[tuple[Path, os.stat_result]]:
  165. """Regular log files of *source* under *root* (default: the tool's env-aware store, see
  166. ``_default_root``) as ``(path, stat)``, newest first. Symlinks escaping the root and
  167. unreadable/rotated entries are skipped, so one bad file never hides the rest. Shared by the
  168. CLI picker and the desktop browser."""
  169. pattern, recursive = _SOURCES[source][3], _SOURCES[source][4]
  170. root = (Path(root) if root else _default_root(source)).resolve()
  171. found: list[tuple[Path, os.stat_result]] = []
  172. for path in (root.rglob(pattern) if recursive else root.glob(pattern)) if root.is_dir() else ():
  173. try:
  174. resolved = path.resolve()
  175. st = resolved.stat()
  176. except OSError:
  177. continue
  178. if resolved.is_relative_to(root) and S_ISREG(st.st_mode):
  179. found.append((resolved, st))
  180. found.sort(key=lambda item: item[1].st_mtime, reverse=True)
  181. return found
  182. def _list_sessions(source: str, root: Optional[Path]) -> list[ForeignSession]:
  183. parse = _parser(source)
  184. results: list[ForeignSession] = []
  185. for path, st in _walk(source, root):
  186. parsed = parse(path)
  187. if parsed["turns"]:
  188. results.append(ForeignSession(source, path, st.st_mtime, parsed["cwd"], parsed["title_guess"],
  189. len(parsed["turns"]), parsed["session_id"]))
  190. return results
  191. def import_foreign_session(source: str, path) -> str:
  192. """Import one foreign session through the gateway's ``session.mutate import`` (the gateway is the
  193. only state.db writer, #106742); returns the new Hermes session id. The row lands as an ordinary
  194. ``cli`` session bound to this importer, so ``hermes --resume`` continues it writable.
  195. Raises ``ValueError`` on unknown source or a session with no usable conversation turns, and
  196. ``GatewayClientError`` (a ``ValueError``) when the gateway refuses the import."""
  197. source = (source or "").strip().lower().lstrip("@")
  198. if source not in _SOURCE_LABELS:
  199. raise ValueError(f"Unknown foreign session source: {source!r}")
  200. path = Path(path).expanduser()
  201. if not path.is_file():
  202. raise ValueError(f"Session file not found: {path}")
  203. parsed = _parser(source)(path)
  204. turns = parsed["turns"]
  205. if not turns:
  206. raise ValueError(f"No user/assistant conversation turns found in {path}")
  207. first_user = _first_user_line([(t["role"], t["content"]) for t in turns]) or path.stem
  208. if len(first_user) > _TITLE_MAX:
  209. first_user = first_user[: _TITLE_MAX - 1] + "…"
  210. from hermes_cli.gateway_client import GatewayClientError
  211. from hermes_cli.gateway_session_store import session_store
  212. store = session_store()
  213. session_id = new_session_id()
  214. cwd = parsed.get("cwd")
  215. # Resume refuses a folder missing here (another machine's, or deleted), as the Desktop import does.
  216. row = {"id": session_id, "source": "cli", "cwd": cwd if cwd and Path(cwd).is_dir() else None, "messages": turns}
  217. receipt = store.call("session.mutate", session_id=session_id, request_id=uuid.uuid4().hex, expected_revision=0,
  218. operation="import", payload={"sessions": [row]})
  219. # Titles are UNIQUE (a re-import's is taken), so the title is a separate, cosmetic rename.
  220. with contextlib.suppress(GatewayClientError):
  221. store.call("session.mutate", session_id=session_id, request_id=uuid.uuid4().hex,
  222. expected_revision=receipt["revision"], operation="rename",
  223. payload={"title": f"Imported from {_SOURCE_LABELS[source]}: {first_user}"})
  224. return session_id
  225. def gather_foreign_sessions(source: Optional[str] = None, *, claude_root: Optional[Path] = None,
  226. codex_root: Optional[Path] = None, limit: int = 25) -> list[ForeignSession]:
  227. """List foreign sessions across sources, newest first."""
  228. sessions = [s for name, root in (("claude", claude_root), ("codex", codex_root)) if source in (None, name)
  229. for s in _list_sessions(name, root)]
  230. sessions.sort(key=lambda s: s.mtime, reverse=True)
  231. return sessions[:limit] if limit else sessions
  232. def pick_foreign_session(source: Optional[str] = None, *, limit: int = 25) -> Optional[ForeignSession]:
  233. """Interactive numbered picker. Returns None when nothing was chosen."""
  234. sessions = gather_foreign_sessions(source, limit=limit)
  235. if not sessions:
  236. where = _SOURCE_LABELS.get(source or "", "Claude Code or Codex CLI")
  237. print(f"No {where} sessions found on this machine.")
  238. return None
  239. print("Foreign sessions (newest first):")
  240. for i, s in enumerate(sessions, 1):
  241. ws = f" ({os.path.basename(s.cwd.rstrip('/')) or s.cwd})" if s.cwd else ""
  242. print(f" {i:>2}. {datetime.fromtimestamp(s.mtime):%Y-%m-%d %H:%M} {s.label}{ws} [{s.turn_count} turns]")
  243. if not sys.stdin.isatty():
  244. print("Non-interactive terminal — pass the file path directly:\n"
  245. " hermes sessions import --from claude|codex <path>")
  246. return None
  247. try:
  248. raw = input(f"Import which session? [1-{len(sessions)}, empty to cancel] ").strip()
  249. idx = int(raw) if raw else None
  250. except (EOFError, KeyboardInterrupt):
  251. return None
  252. except ValueError:
  253. print(f"Not a number: {raw}")
  254. return None
  255. if idx is not None and 1 <= idx <= len(sessions):
  256. return sessions[idx - 1]
  257. if idx is not None:
  258. print(f"Out of range: {idx}")
  259. return None
  260. def run_sessions_import(args) -> Optional[str]:
  261. """`hermes sessions import` entry point. Returns new session id or None."""
  262. source = getattr(args, "from_source", None)
  263. path = getattr(args, "path", None)
  264. if path:
  265. # A missing file is reported as such, not as the misleading "cannot infer source".
  266. if not Path(path).exists():
  267. print(f"Error: file not found: {path}")
  268. return None
  269. if not source: # guess from the path shape; a codex match wins over a claude match
  270. p = str(path)
  271. if "/.claude/" in p or p.endswith(".jsonl") and "claude" in p:
  272. source = "claude"
  273. if "/.codex/" in p or Path(p).name.startswith("rollout-"):
  274. source = "codex"
  275. if not source:
  276. print("Cannot infer source from path; pass --from claude|codex.")
  277. return None
  278. chosen_path = Path(path)
  279. else:
  280. if (picked := pick_foreign_session(source)) is None:
  281. return None
  282. source, chosen_path = picked.source, picked.path
  283. try:
  284. session_id = import_foreign_session(source, chosen_path)
  285. except ValueError as e:
  286. print(f"Error: {e}")
  287. return None
  288. print(f"✓ Imported {_SOURCE_LABELS.get(source, source)} session as {session_id}")
  289. print(f" Continue it with: hermes --resume {session_id}")
  290. return session_id