claude-code-tools 1.30.4__tar.gz → 1.31.0__tar.gz

{claude_code_tools-1.30.4 → claude_code_tools-1.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-tools
-Version: 1.30.4
+Version: 1.31.0
 Summary: Collection of tools for working with Claude Code
 License-File: LICENSE
 Requires-Python: >=3.11

{claude_code_tools-1.30.4 → claude_code_tools-1.31.0}/claude_code_tools/__init__.py

@@ -1,3 +1,3 @@
 """Claude Code Tools - Collection of utilities for Claude Code."""
 
-__version__ = "1.30.4"
+__version__ = "1.31.0"

{claude_code_tools-1.30.4 → claude_code_tools-1.31.0}/claude_code_tools/aichat.py

@@ -1858,12 +1858,31 @@ def _write_lines_atomically(
 @click.argument("session", required=True)
 @click.option("--claude-home", help="Path to Claude home directory")
 @click.option("--codex-home", help="Path to Codex home directory")
+@click.option(
+    "--provider",
+    help=(
+        "Codex model provider for the new session (e.g. openai, "
+        "local-fractal). With a Codex session: copy it onto this "
+        "provider instead of porting to Claude. With a Claude session: "
+        "the new Codex session's provider (default openai)."
+    ),
+)
+@click.option(
+    "--model",
+    help=(
+        "Model to resume the new Codex session with; added to the "
+        "printed resume command as -m (Codex otherwise resumes with "
+        "the session's last model)."
+    ),
+)
 @click.pass_context
 def port_session(
     ctx: click.Context,
     session: str,
     claude_home: "str | None",
     codex_home: "str | None",
+    provider: "str | None",
+    model: "str | None",
 ) -> None:
     """Port a session to the OTHER agent (codex <-> claude).
 
@@ -1872,6 +1891,14 @@ def port_session(
     Claude sessions are converted into a flattened, resumable Codex
     rollout.
 
+    With --provider, a Codex session is instead copied to a new Codex
+    session bound to that model provider (Codex only resumes a thread
+    under the provider it was created with). OpenAI-only encrypted
+    reasoning and compaction summaries (and a local model's reasoning)
+    are dropped; everything else is kept. Use --provider openai to move
+    a local-model session back, with --model naming the model to resume
+    with.
+
     SESSION may be a full session id, a partial id (prefix, middle,
     or suffix fragment), a session name (set with /rename), a
     rollout filename fragment (e.g. 2026-03-25T14-50), or a session
@@ -1883,6 +1910,8 @@ def port_session(
         aichat port abc123 --claude-home ~/.claude-alt
         aichat port my-session-name
         aichat port 2026-03-25T14-50
+        aichat port 01a1a29a --provider local-fractal
+        aichat port 01a1a2aa --provider openai --model gpt-6.1-sol
     """
     import sys
 
@@ -1893,6 +1922,7 @@ def port_session(
         port_claude_session,
         port_codex_session,
         resolve_port_session,
+        retarget_codex_session,
     )
 
     # Group-level --claude-home/--codex-home (given BEFORE the
@@ -1924,13 +1954,34 @@ def port_session(
         display.error(str(e))
         sys.exit(1)
 
-    display.resolved(resolved)
+    if model and resolved.agent == "codex" and not provider:
+        display.error("--model only applies to a Codex target: add --provider")
+        sys.exit(1)
+    target_agent = "codex" if (resolved.agent == "claude" or provider) else "claude"
+    display.resolved(resolved, target_agent)
     if resolved.agent == "claude":
         try:
-            with display.porting(resolved.agent):
+            with display.porting(resolved.agent, target_agent):
                 result = port_claude_session(
                     resolved.session_file,
                     codex_home=codex_home,
+                    provider=provider,
+                    model=model or "",
+                )
+        except PortSessionError as e:
+            display.error(str(e))
+            sys.exit(1)
+        display.complete(result, resolved.agent)
+        return
+
+    if provider:
+        try:
+            with display.porting(resolved.agent, target_agent):
+                result = retarget_codex_session(
+                    resolved.session_file,
+                    provider,
+                    codex_home=codex_home,
+                    model=model or "",
                 )
         except PortSessionError as e:
             display.error(str(e))

{claude_code_tools-1.30.4 → claude_code_tools-1.31.0}/claude_code_tools/port_claude_to_codex.py

@@ -756,6 +756,7 @@ def _append_history_transactional(
 def port_claude_session_to_codex(
     claude_session_file: Union[str, Path],
     codex_home: Optional[Union[str, Path]] = None,
+    model_provider: str = CODEX_MODEL_PROVIDER,
 ) -> tuple[str, Path]:
     """Convert a Claude Code session into a new Codex rollout file.
 
@@ -771,6 +772,9 @@ def port_claude_session_to_codex(
         claude_session_file: Path to the Claude session JSONL file.
         codex_home: Optional Codex home directory (defaults to
             ``~/.codex``).
+        model_provider: Codex model provider the new rollout is bound
+            to (Codex only resumes a thread under the provider it
+            records). Defaults to ``openai``.
 
     Returns:
         Tuple ``(new_session_id, new_file_path)``.
@@ -829,7 +833,7 @@ def port_claude_session_to_codex(
         "cwd": cwd,
         "originator": PORT_ORIGINATOR,
         "cli_version": "aichat-port",
-        "model_provider": CODEX_MODEL_PROVIDER,
+        "model_provider": model_provider,
     }
     if meta["branch"]:
         payload["git"] = {"branch": meta["branch"]}

claude_code_tools-1.31.0/claude_code_tools/port_codex_provider.py

@@ -0,0 +1,268 @@
+"""Re-target a Codex rollout at another model provider.
+
+Codex records the model provider a thread was created with in the
+rollout's ``session_meta`` line (``"model_provider": "openai"``), and the
+Codex TUI refuses to resume a thread under a different provider
+("This chat uses openai, but your current provider is ..."). This module
+writes a NEW rollout, forked from the original, that is bound to the
+requested provider instead, so a session can move between OpenAI and a
+local model (or between any two providers) in either direction.
+
+Everything in the transcript is kept except what one provider cannot
+take from another: reasoning items (OpenAI's are encrypted; a local
+model's carry raw ``reasoning_text`` content, which OpenAI rejects as
+input) and any item carrying ``encrypted_content``, such as OpenAI's
+encrypted compaction summaries. They are dropped from the top-level
+history and from the ``replacement_history`` / ``guardian_history``
+lists inside ``compacted`` records. Visible messages, tool calls, tool
+output and plaintext summaries all survive.
+
+Codex also resumes with the model a session last used, which belongs to
+the old provider; :class:`RetargetStats` reports it so the caller can
+tell the user to pick a model with ``-m``.
+
+The source rollout is never modified. The new rollout goes to the same
+Codex home as the source (or ``codex_home`` when given) and is appended
+to that home's ``history.jsonl`` like every other ported session.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import re
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterator, Optional, Union
+
+from claude_code_tools.port_claude_to_codex import (
+    _append_history_transactional,
+    _new_codex_session_id,
+    _utc_now_codex_timestamp,
+)
+from claude_code_tools.port_codex_to_claude import _write_transcript_atomic
+from claude_code_tools.session_utils import get_codex_home
+
+# Provider ids are TOML table keys in Codex's config ([model_providers.X])
+# and appear unquoted on resume command lines.
+_PROVIDER_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*$")
+
+# History lists inside a ``compacted`` record that hold response items.
+_COMPACTED_HISTORY_KEYS = ("replacement_history", "guardian_history")
+
+
+@dataclass
+class RetargetStats:
+    """What changed while re-targeting a rollout.
+
+    Attributes:
+        source_provider: Provider recorded in the source rollout.
+        dropped: Count of dropped provider-only items, by item type
+            (e.g. ``{"reasoning": 192, "compaction": 2}``).
+        last_model: Model of the session's last turn ("" if none).
+    """
+
+    source_provider: str
+    dropped: Counter = field(default_factory=Counter)
+    last_model: str = ""
+
+
+def validate_provider(provider: str) -> str:
+    """Check a provider id and return it.
+
+    Args:
+        provider: Provider id such as ``openai`` or ``local-fractal``.
+
+    Returns:
+        The provider id, unchanged.
+
+    Raises:
+        ValueError: If the id is empty or not a plain identifier.
+    """
+    if not _PROVIDER_RE.match(provider or ""):
+        raise ValueError(
+            f"Invalid provider {provider!r}: use letters, digits, '-' or '_' "
+            "(e.g. openai, local-fractal)"
+        )
+    return provider
+
+
+def _is_provider_only(item: Any) -> bool:
+    """True for a response item another provider cannot take as input."""
+    return isinstance(item, dict) and (
+        item.get("type") == "reasoning" or bool(item.get("encrypted_content")))
+
+
+def _codex_home_of(rollout: Path) -> Optional[Path]:
+    """Codex home holding ``rollout``.
+
+    Live rollouts sit in ``<home>/sessions/Y/M/D/``; archived ones in
+    ``<home>/archived_sessions/``.
+    """
+    parents = rollout.parents
+    if len(parents) >= 5 and parents[3].name == "sessions":
+        return parents[4]
+    if len(parents) >= 2 and parents[0].name == "archived_sessions":
+        return parents[1]
+    return None
+
+
+def _read_session_meta(rollout: Path) -> dict[str, Any]:
+    """Return the first line's session_meta payload, or raise."""
+    with open(rollout, "r", encoding="utf-8") as f:
+        first = f.readline()
+    try:
+        record = json.loads(first)
+    except ValueError:
+        record = None
+    if not isinstance(record, dict) or record.get("type") != "session_meta" \
+            or not isinstance(record.get("payload"), dict):
+        raise ValueError(f"Not a Codex rollout (no session_meta first): {rollout}")
+    return record["payload"]
+
+
+def _first_user_text(record: dict[str, Any]) -> Optional[str]:
+    """The text of a user_message event, if ``record`` is one."""
+    payload = record.get("payload")
+    if record.get("type") == "event_msg" and isinstance(payload, dict) \
+            and payload.get("type") == "user_message":
+        message = payload.get("message")
+        if isinstance(message, str) and message.strip():
+            return message
+    return None
+
+
+def _retarget_lines(
+    rollout: Path,
+    *,
+    provider: str,
+    new_id: str,
+    now_iso: str,
+    stats: RetargetStats,
+    preview: dict[str, Optional[str]],
+) -> Iterator[dict[str, Any]]:
+    """Stream the source rollout's records, re-targeted at ``provider``."""
+    first = True
+    with open(rollout, "r", encoding="utf-8") as f:
+        for raw in f:
+            if not raw.strip():
+                continue
+            record = json.loads(raw)
+            if not isinstance(record, dict):
+                yield record
+                continue
+            kind = record.get("type")
+            payload = record.get("payload")
+            if kind == "session_meta" and isinstance(payload, dict):
+                payload = {**payload, "model_provider": provider}
+                if first:
+                    old_id = payload.get("id")
+                    payload.update(id=new_id, session_id=new_id,
+                                   timestamp=now_iso, forked_from_id=old_id)
+                    record = {
+                        **record,
+                        "timestamp": now_iso,
+                        "payload": payload,
+                        "continue_metadata": {
+                            "parent_session_id": old_id,
+                            "parent_session_file": str(rollout.absolute()),
+                            "continued_at": now_iso,
+                            "retargeted_from_provider": stats.source_provider,
+                            "retargeted_to_provider": provider,
+                        },
+                    }
+                else:  # lineage line of the thread this one forked from
+                    record = {**record, "payload": payload}
+                first = False
+            elif kind == "turn_context" and isinstance(payload, dict):
+                if isinstance(payload.get("model"), str):
+                    stats.last_model = payload["model"]
+            elif kind == "response_item" and _is_provider_only(payload):
+                stats.dropped[str(payload.get("type"))] += 1
+                continue
+            elif kind == "compacted" and isinstance(payload, dict):
+                payload = dict(payload)
+                for key in _COMPACTED_HISTORY_KEYS:
+                    items = payload.get(key)
+                    if isinstance(items, list):
+                        kept = []
+                        for x in items:
+                            if isinstance(x, dict) and _is_provider_only(x):
+                                stats.dropped[str(x.get("type"))] += 1
+                            else:
+                                kept.append(x)
+                        payload[key] = kept
+                record = {**record, "payload": payload}
+            elif kind == "event_msg" and isinstance(payload, dict) \
+                    and payload.get("type") == "thread_settings_applied":
+                settings = payload.get("thread_settings")
+                if isinstance(settings, dict) and "model_provider_id" in settings:
+                    record = {**record, "payload": {
+                        **payload,
+                        "thread_settings": {**settings,
+                                            "model_provider_id": provider}}}
+            if preview["text"] is None:
+                preview["text"] = _first_user_text(record)
+            yield record
+
+
+def retarget_codex_session(
+    rollout_file: Union[str, Path],
+    provider: str,
+    codex_home: Optional[Union[str, Path]] = None,
+) -> tuple[str, Path, RetargetStats]:
+    """Write a copy of a Codex rollout bound to another model provider.
+
+    Args:
+        rollout_file: Path to the source Codex rollout JSONL file.
+        provider: Target provider id (``openai``, ``local-fractal``, ...).
+        codex_home: Codex home for the new rollout. Defaults to the
+            source rollout's own home, else ``~/.codex``.
+
+    Returns:
+        Tuple ``(new_session_id, new_file_path, stats)``.
+
+    Raises:
+        FileNotFoundError: If the source rollout does not exist.
+        ValueError: If the provider id is invalid, the file is not a
+            Codex rollout, or it already uses ``provider``.
+        OSError: On filesystem failures (no partial file is left, and
+            the history entry is rolled back).
+    """
+    validate_provider(provider)
+    source = Path(rollout_file).expanduser()
+    if not source.is_file():
+        raise FileNotFoundError(f"Codex session not found: {source}")
+    meta = _read_session_meta(source)
+    source_provider = str(meta.get("model_provider") or "openai")
+    if source_provider == provider:
+        raise ValueError(
+            f"Session already uses provider {provider!r}; nothing to change"
+        )
+
+    if codex_home is not None:
+        home_dir = get_codex_home(str(codex_home))
+    else:
+        home_dir = _codex_home_of(source.absolute()) or get_codex_home(None)
+    new_id = _new_codex_session_id()
+    now_iso = _utc_now_codex_timestamp()
+    now_local = datetime.datetime.now()
+    day_dir = home_dir / "sessions" / now_local.strftime("%Y/%m/%d")
+    day_dir.mkdir(parents=True, exist_ok=True)
+    stamp = now_local.strftime("%Y-%m-%dT%H-%M-%S")
+    out_path = day_dir / f"rollout-{stamp}-{new_id}.jsonl"
+
+    stats = RetargetStats(source_provider=source_provider)
+    preview: dict[str, Optional[str]] = {"text": None}
+    _write_transcript_atomic(
+        out_path,
+        _retarget_lines(source, provider=provider, new_id=new_id,
+                        now_iso=now_iso, stats=stats, preview=preview),
+    )
+    _append_history_transactional(
+        home_dir, new_id,
+        preview["text"] or f"Codex session moved to provider {provider}",
+        out_path,
+    )
+    return new_id, out_path, stats

{claude_code_tools-1.30.4 → claude_code_tools-1.31.0}/claude_code_tools/port_render.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import os
+import shlex
 import shutil
 import subprocess
 import sys
@@ -106,9 +107,9 @@ def _target_agent(source_agent: str) -> str:
     return "codex" if source_agent == "claude" else "claude"
 
 
-def _target_label(source_agent: str) -> str:
+def _target_label(source_agent: str, target_agent: str = "") -> str:
     """Return the product label for a destination agent."""
-    target = _target_agent(source_agent)
+    target = target_agent or _target_agent(source_agent)
     return "Claude Code" if target == "claude" else "Codex"
 
 
@@ -161,15 +162,16 @@ class PortDisplay:
             session_file=Path(record.session_file),
         )
 
-    def resolved(self, session: "ResolvedSession") -> None:
+    def resolved(self, session: "ResolvedSession", target_agent: str = "") -> None:
         """Print the chosen source and detected direction."""
         source = _agent_label(session.agent)
-        target = _target_label(session.agent)
+        target = _target_label(session.agent, target_agent)
         self.console.print(
             Text.assemble(
                 ("  ✓ ", "bold green"),
                 (f"Detected source agent: {session.agent}", "bold"),
-                f" — porting to {target}",
+                " — copying to a new Codex session on another provider"
+                if target_agent == session.agent else f" — porting to {target}",
             )
         )
         self.console.print(
@@ -177,9 +179,9 @@ class PortDisplay:
         )
         self.console.print(f"[bold cyan]2/3[/]  Porting {source} → {target}")
 
-    def porting(self, source_agent: str) -> Status:
+    def porting(self, source_agent: str, target_agent: str = "") -> Status:
         """Return the conversion-phase spinner."""
-        target = _target_label(source_agent)
+        target = _target_label(source_agent, target_agent)
         return self.console.status(
             f"[dim]Converting transcript and creating {target} session...[/dim]",
             spinner="dots",
@@ -187,7 +189,7 @@ class PortDisplay:
 
     def complete(self, result: "PortResult", source_agent: str) -> None:
         """Render the final destination details and resume command."""
-        target_agent = _target_agent(source_agent)
+        target_agent = result.target_agent or _target_agent(source_agent)
         target = _agent_label(target_agent)
         self.console.print("[bold cyan]3/3[/]  Ready")
 
@@ -200,6 +202,8 @@ class PortDisplay:
         )
         table.add_row("Session cwd:", Text(result.cwd or "Unknown"))
         table.add_row("Output file:", Text(str(result.output_file)))
+        if result.provider:
+            table.add_row("Model provider:", Text(result.provider))
         self.console.print(
             Panel(
                 table,
@@ -215,18 +219,29 @@ class PortDisplay:
             overflow="ignore",
         )
         self.console.print(command, soft_wrap=True)
-        if target_agent == "codex":
+        for note in result.notes:
+            self.console.print(Text(f"  {note}", style="dim"))
+        if target_agent == "codex" and source_agent == "claude":
             self.console.print()
             self.console.print(
                 "[dim]Tip: Codex's /import is also available as an "
                 "interactive alternative.[/dim]"
             )
-        self.offer_session_id_copy(result.new_session_id, target_agent)
+        # The follow-up command keeps every flag of the resume hint
+        # (provider, model, CODEX_HOME), with the id left to paste. The
+        # services build the hint as `cd <quoted cwd> && <command>`.
+        prefix = f"cd {shlex.quote(result.cwd)} && "
+        command = ""
+        if result.resume_hint.startswith(prefix):
+            command = result.resume_hint[len(prefix):].replace(
+                result.new_session_id, "<paste session ID>")
+        self.offer_session_id_copy(result.new_session_id, target_agent, command)
 
     def offer_session_id_copy(
         self,
         session_id: str,
         target_agent: str,
+        command: str = "",
     ) -> None:
         """Offer to copy a newly created session ID in interactive terminals."""
         if not self.console.is_terminal or not sys.stdin.isatty():
@@ -250,14 +265,11 @@ class PortDisplay:
             self.console.print(
                 "[bold green]✓ Session ID copied to clipboard.[/bold green]"
             )
-            command = "codex resume" if target_agent == "codex" else "claude --resume"
+            if not command:
+                command = ("codex resume" if target_agent == "codex"
+                           else "claude --resume") + " <paste session ID>"
             self.console.print("[bold]Now you can run:[/bold]")
-            self.console.print(
-                Text(
-                    f"  {command} <paste session ID>",
-                    style="bold cyan",
-                )
-            )
+            self.console.print(Text(f"  {command}", style="bold cyan"))
             return
         self.console.print(
             "[yellow]Could not find a working system clipboard command. "