coding-agent-wrapper 0.1.4__tar.gz → 0.1.5__tar.gz

{coding_agent_wrapper-0.1.4 → coding_agent_wrapper-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-agent-wrapper
-Version: 0.1.4
+Version: 0.1.5
 Summary: Unified Python library and CLI for orchestrating coding agents (Claude Code, Codex, etc.) with MCP tool servers and credential management.
 Project-URL: Homepage, https://github.com/zzjas/caw
 Project-URL: Repository, https://github.com/zzjas/caw
@@ -85,6 +85,50 @@ with agent.start_session() as session:
 # session.end() called automatically, returns full Trajectory
 ```
 
+### Resuming sessions across processes
+
+Grab a `resume_handle` (a string) and store it anywhere — a database, a file, a
+queue. Later, in a different process, resume the conversation:
+
+```python
+# Process 1: start, communicate, persist the handle.
+agent = Agent(provider="claude_code")
+session = agent.start_session()
+session.send("My deploy target is staging-eu. Remember that.")
+handle = session.resume_handle          # store this string
+session.end()
+
+# Process 2 (later, after a restart): resume by handle.
+agent = Agent(provider="claude_code")
+session = agent.resume_session(handle)
+print(session.send("Where am I deploying?").result)   # -> "staging-eu"
+session.end()
+```
+
+The handle is a **self-contained JSON string** carrying the backend's own resume
+key, so resuming works even with no `data_dir` — the underlying CLI still has the
+conversation:
+
+```json
+{"version": 1, "provider": "claude_code", "session_id": "bd260210-…", "resume_key": "bd260210-…"}
+```
+
+(`resume_key` is claude's session id, Codex's `thread_id`, or opencode's session
+id — for codex/opencode it differs from `session_id`.) Send at least one message
+before reading `resume_handle`; the backend assigns its key on the first
+exchange. Works across all three providers.
+
+> The handle grants resume access to the conversation — treat it like a secret,
+> not an opaque random id.
+
+`data_dir` is optional and additive:
+
+| | without `data_dir` | with the original `data_dir` |
+|---|---|---|
+| backend conversation | resumed | resumed |
+| caw trajectory | starts empty | full history restored |
+| new turns | not persisted | appended to the original session dir |
+
 ### Providers
 
 | Provider | CLI | Provider name |

{coding_agent_wrapper-0.1.4 → coding_agent_wrapper-0.1.5}/README.md

@@ -55,6 +55,50 @@ with agent.start_session() as session:
 # session.end() called automatically, returns full Trajectory
 ```
 
+### Resuming sessions across processes
+
+Grab a `resume_handle` (a string) and store it anywhere — a database, a file, a
+queue. Later, in a different process, resume the conversation:
+
+```python
+# Process 1: start, communicate, persist the handle.
+agent = Agent(provider="claude_code")
+session = agent.start_session()
+session.send("My deploy target is staging-eu. Remember that.")
+handle = session.resume_handle          # store this string
+session.end()
+
+# Process 2 (later, after a restart): resume by handle.
+agent = Agent(provider="claude_code")
+session = agent.resume_session(handle)
+print(session.send("Where am I deploying?").result)   # -> "staging-eu"
+session.end()
+```
+
+The handle is a **self-contained JSON string** carrying the backend's own resume
+key, so resuming works even with no `data_dir` — the underlying CLI still has the
+conversation:
+
+```json
+{"version": 1, "provider": "claude_code", "session_id": "bd260210-…", "resume_key": "bd260210-…"}
+```
+
+(`resume_key` is claude's session id, Codex's `thread_id`, or opencode's session
+id — for codex/opencode it differs from `session_id`.) Send at least one message
+before reading `resume_handle`; the backend assigns its key on the first
+exchange. Works across all three providers.
+
+> The handle grants resume access to the conversation — treat it like a secret,
+> not an opaque random id.
+
+`data_dir` is optional and additive:
+
+| | without `data_dir` | with the original `data_dir` |
+|---|---|---|
+| backend conversation | resumed | resumed |
+| caw trajectory | starts empty | full history restored |
+| new turns | not persisted | appended to the original session dir |
+
 ### Providers
 
 | Provider | CLI | Provider name |

{coding_agent_wrapper-0.1.4 → coding_agent_wrapper-0.1.5}/caw/__init__.py

@@ -1,6 +1,6 @@
 """caw - Coding Agent Wrapper."""
 
-__version__ = "0.1.4"
+__version__ = "0.1.5"
 
 from caw.agent import Agent, Session, register_provider
 from caw.auth import get_docker_flags as auth_get_docker_flags

{coding_agent_wrapper-0.1.4 → coding_agent_wrapper-0.1.5}/caw/agent.py

@@ -65,6 +65,36 @@ def _resolve_provider(name: str | None) -> Provider:
     return _PROVIDER_REGISTRY[provider_name]()
 
 
+def _encode_resume_handle(provider: str, session_id: str, resume_key: str) -> str:
+    """Pack everything needed to resume — provider, caw session id, and the
+    backend resume key — into a JSON handle string.  Self-contained so a
+    session can be resumed in a new process with or without the original
+    ``data_dir``."""
+    return json.dumps(
+        {
+            "version": 1,
+            "provider": provider,
+            "session_id": session_id,
+            "resume_key": resume_key,
+        }
+    )
+
+
+def _decode_resume_handle(handle: str) -> dict[str, Any] | None:
+    """Parse a JSON handle produced by :func:`_encode_resume_handle`.
+
+    Returns the payload dict, or ``None`` if *handle* is not a self-contained
+    handle (e.g. a bare session id), so callers can fall back to disk lookup.
+    """
+    try:
+        data = json.loads(handle)
+    except (ValueError, TypeError):
+        return None
+    if isinstance(data, dict) and data.get("resume_key"):
+        return data
+    return None
+
+
 def _attach_subagent_trajectories(turn: Turn, traj_dir: str | None) -> None:
     """Scan a turn's tool outputs for trajectory markers and attach them.
 
@@ -266,6 +296,32 @@ class Session:
         session._loaded_trajectory = traj
         return session
 
+    @property
+    def resume_handle(self) -> str:
+        """Opaque string for resuming this session later, possibly in another
+        process.
+
+        Store it anywhere (a database, a file, …) and pass it to
+        :meth:`Agent.resume_session`.  The handle is self-contained: it carries
+        the backend resume key, so resuming works even without the original
+        ``data_dir`` (you just won't get the prior trajectory restored).  If
+        the resuming :class:`Agent` *does* share the same ``data_dir``, the
+        full history is restored and new turns are appended.
+
+        Raises if the backend has not yet assigned a resume key — send at least
+        one message first.
+        """
+        traj = self.trajectory
+        if not self._readonly and self._session is not None:
+            resume_key = self._session.resume_key
+        else:
+            resume_key = _resolve_provider(traj.agent).resume_key_from_trajectory(traj)
+        if not resume_key:
+            raise RuntimeError(
+                "No resume key available yet — send at least one message before requesting a resume handle."
+            )
+        return _encode_resume_handle(traj.agent, traj.session_id, resume_key)
+
     @property
     def session_dir(self) -> Path | None:
         """Path to the session's data directory, or None if persistence is disabled."""
@@ -519,8 +575,133 @@ class Agent:
             through it. See :mod:`caw.logger`.
         """
         merged = {**self._kwargs, **kwargs}
+        auto_wait, session_metadata, logger = self._pop_session_opts(merged)
+
+        # Generate session_id early so the JSONL path is known before MCP configs
+        session_id: str | None = None
+        store: SessionStore | None = None
+        if self._data_dir:
+            session_id = str(uuid_mod.uuid4())
+            store = SessionStore(self._data_dir, session_id)
+
+        subagent_traj_dir, all_handles, all_mcp = self._build_tool_context(merged, store)
+
+        # Pass our session_id so the provider uses it (instead of generating its own)
+        if session_id:
+            merged["session_id"] = session_id
+
+        provider_session = self.provider.start_session(mcp_servers=all_mcp, **merged)
+
+        session = Session(
+            provider_session,
+            store=store,
+            subagent_traj_dir=subagent_traj_dir,
+            tool_handles=all_handles,
+            auto_wait=auto_wait,
+            metadata=session_metadata,
+            logger=logger,
+        )
+
+        if traj_path is not None:
+            session._traj_path = traj_path
+
+        if store:
+            store.write_metadata(session.trajectory)
+
+        return session
+
+    def resume_session(self, resume_handle: str, **kwargs: Any) -> Session:
+        """Resume a session from a handle produced by :attr:`Session.resume_handle`.
+
+        Returns a live :class:`Session` whose next :meth:`Session.send`
+        continues the original conversation.
+
+        - **Without ``data_dir`` (or if the session isn't on disk):** the backend
+          conversation is resumed using the key embedded in the handle, but
+          caw's trajectory starts empty (no prior turns restored).
+        - **With the original ``data_dir``:** the full trajectory is restored
+          and new turns are appended to the original session directory.
+
+        A bare session id is also accepted in place of a full handle, but only
+        when ``data_dir`` is set (the resume key is then read from disk).
+        """
+        decoded = _decode_resume_handle(resume_handle)
+        if decoded is not None:
+            provider_name = decoded["provider"]
+            session_id = decoded["session_id"]
+            resume_key: str | None = decoded["resume_key"]
+            if provider_name != self.provider.name:
+                raise ValueError(
+                    f"Handle is for provider {provider_name!r} but this Agent uses {self.provider.name!r}."
+                )
+        else:
+            # Treat the string as a bare caw session id; the resume key must
+            # then come from the on-disk trajectory.
+            session_id = resume_handle
+            resume_key = None
+
+        # Load the persisted trajectory if a data_dir is available.
+        trajectory: Trajectory | None = None
+        store: SessionStore | None = None
+        had_existing = False
+        if self._data_dir:
+            traj_path = Path(self._data_dir) / "sessions" / session_id / "trajectory.json"
+            if traj_path.exists():
+                with open(traj_path) as f:
+                    trajectory = Trajectory.from_dict(json.load(f))
+                had_existing = True
+
+        if resume_key is None:
+            if trajectory is None:
+                raise FileNotFoundError(
+                    f"Cannot resume {resume_handle!r}: it is not a self-contained "
+                    f"handle and no persisted session was found"
+                    + (f" under {self._data_dir}" if self._data_dir else " (no data_dir set)")
+                    + "."
+                )
+            resume_key = self.provider.resume_key_from_trajectory(trajectory)
+            if not resume_key:
+                raise ValueError(f"Cannot resume {resume_handle!r}: no resume key was persisted for this session.")
+
+        merged = {**self._kwargs, **kwargs}
+        auto_wait, session_metadata, logger = self._pop_session_opts(merged)
 
-        # Pop auto_wait, metadata, logger — these are Session concerns, not provider kwargs
+        if self._data_dir:
+            store = SessionStore(self._data_dir, session_id, resume=True)
+
+        subagent_traj_dir, all_handles, all_mcp = self._build_tool_context(merged, store)
+
+        # session_id is fixed by the handle/trajectory, not generated.
+        merged.pop("session_id", None)
+        provider_session = self.provider.resume_session(
+            mcp_servers=all_mcp,
+            session_id=session_id,
+            resume_key=resume_key,
+            trajectory=trajectory,
+            **merged,
+        )
+
+        session = Session(
+            provider_session,
+            store=store,
+            subagent_traj_dir=subagent_traj_dir,
+            tool_handles=all_handles,
+            auto_wait=auto_wait,
+            metadata=session_metadata,
+            logger=logger,
+        )
+        # Fresh on-disk session (data_dir set but nothing persisted yet): seed
+        # the metadata line like start_session does.
+        if store is not None and not had_existing:
+            store.write_metadata(session.trajectory)
+        return session
+
+    def _pop_session_opts(self, merged: dict[str, Any]) -> tuple[bool, dict[str, Any], AgentLogger | None]:
+        """Strip Session-only kwargs out of *merged* and resolve a model tier.
+
+        Returns ``(auto_wait, session_metadata, logger)``; *merged* is left
+        holding only provider ``start_session``/``resume_session`` kwargs.
+        """
         auto_wait = merged.pop("auto_wait", True)
         session_metadata: dict[str, Any] = merged.pop("metadata", {})
         logger: AgentLogger | None = merged.pop("logger", None) or self._logger
@@ -532,7 +713,17 @@ class Agent:
         model = merged.get("model")
         if isinstance(model, ModelTier):
             merged["model"] = self.provider.resolve_model(model)
+        return auto_wait, session_metadata, logger
+
+    def _build_tool_context(
+        self, merged: dict[str, Any], store: SessionStore | None
+    ) -> tuple[str | None, list[Any], list[MCPServer]]:
+        """Resolve tool restrictions and start tool/subagent servers.
 
+        Consumes ``tools`` from *merged* (applying the default), updates
+        *merged* with provider-specific tool restriction kwargs, and returns
+        ``(subagent_traj_dir, all_handles, all_mcp)``.
+        """
         # Resolve tool restrictions: default to ALL - INTERACTION for automated pipelines
         tools = merged.pop("tools", None)
         if tools is None:
@@ -540,13 +731,6 @@ class Agent:
         restrictions = self.provider.resolve_tool_restrictions(tools)
         merged.update(restrictions)
 
-        # Generate session_id early so the JSONL path is known before MCP configs
-        session_id: str | None = None
-        store: SessionStore | None = None
-        if self._data_dir:
-            session_id = str(uuid_mod.uuid4())
-            store = SessionStore(self._data_dir, session_id)
-
         # Create temp dir for subagent trajectory files (if subagents exist)
         subagent_traj_dir: str | None = None
         if self._subagents:
@@ -568,26 +752,4 @@ class Agent:
         for handle in all_handles:
             all_mcp.append(MCPServer(name=handle.server_id, url=handle.url))
 
-        # Pass our session_id so the provider uses it (instead of generating its own)
-        if session_id:
-            merged["session_id"] = session_id
-
-        provider_session = self.provider.start_session(mcp_servers=all_mcp, **merged)
-
-        session = Session(
-            provider_session,
-            store=store,
-            subagent_traj_dir=subagent_traj_dir,
-            tool_handles=all_handles,
-            auto_wait=auto_wait,
-            metadata=session_metadata,
-            logger=logger,
-        )
-
-        if traj_path is not None:
-            session._traj_path = traj_path
-
-        if store:
-            store.write_metadata(session.trajectory)
-
-        return session
+        return subagent_traj_dir, all_handles, all_mcp

{coding_agent_wrapper-0.1.4 → coding_agent_wrapper-0.1.5}/caw/provider.py

@@ -43,6 +43,33 @@ class ProviderSession(ABC):
         """Provider-assigned session ID (if any)."""
         return None
 
+    @property
+    def resume_key(self) -> str | None:
+        """The provider-side key needed to resume this conversation.
+
+        This is whatever the backend CLI accepts to continue an existing
+        session (claude's session id, codex's thread id, opencode's session
+        id).  ``None`` until the backend has assigned one — typically after the
+        first :meth:`send`.
+        """
+        return None
+
+    def _restore_from_trajectory(self, trajectory: Trajectory) -> None:
+        """Re-seed a freshly built session with a prior trajectory's state.
+
+        Used by :meth:`Provider.resume_session` so a session reconstructed in a
+        new process carries the original history, usage totals, and creation
+        time forward.  All concrete provider sessions share these attribute
+        names; resume-specific keys (thread id, etc.) are restored by the
+        provider's own ``resume_session``.
+        """
+        self._turns = list(trajectory.turns)
+        self._total_usage = trajectory.usage
+        self._total_duration_ms = trajectory.duration_ms
+        if trajectory.created_at:
+            self._created_at = trajectory.created_at
+        self._has_sent = True
+
     @property
     def last_raw_output(self) -> str | None:
         """Raw CLI stdout from the most recent send() call (if available)."""
@@ -138,3 +165,35 @@ class Provider(ABC):
     def start_session(self, mcp_servers: list[MCPServer], **kwargs: Any) -> ProviderSession:
         """Create and return a new provider session."""
         ...
+
+    def resume_key_from_trajectory(self, trajectory: Trajectory) -> str | None:
+        """Extract the resume key from a persisted *trajectory*.
+
+        Mirrors :attr:`ProviderSession.resume_key` but reads from a stored
+        trajectory rather than a live session.  Returns ``None`` if the
+        trajectory predates resume support or was never sent to.
+        """
+        return None
+
+    def resume_session(
+        self,
+        mcp_servers: list[MCPServer],
+        *,
+        session_id: str,
+        resume_key: str,
+        trajectory: Trajectory | None = None,
+        **kwargs: Any,
+    ) -> ProviderSession:
+        """Rebuild a live session ready to continue an existing conversation.
+
+        ``resume_key`` is the provider-side key the backend CLI needs to resume
+        (see :attr:`ProviderSession.resume_key`); ``session_id`` is caw's own
+        bookkeeping id (the on-disk directory name).  The next
+        :meth:`ProviderSession.send` must resume rather than start fresh.
+
+        When ``trajectory`` is given, the prior history/usage is carried forward
+        via :meth:`ProviderSession._restore_from_trajectory`.  When it is
+        ``None`` (e.g. resuming without a ``data_dir``), the backend session is
+        still resumed but caw's trajectory starts empty.
+        """
+        raise NotImplementedError(f"{self.name} provider does not support resuming sessions.")

{coding_agent_wrapper-0.1.4 → coding_agent_wrapper-0.1.5}/caw/providers/claude_code.py

@@ -475,6 +475,11 @@ class ClaudeCodeSession(ProviderSession):
     def session_id(self) -> str:
         return self._session_id
 
+    @property
+    def resume_key(self) -> str | None:
+        # claude resumes via `--resume <session_id>`; the key is the id itself.
+        return self._session_id
+
     @property
     def last_raw_output(self) -> str:
         return self._last_raw_output
@@ -677,3 +682,31 @@ class ClaudeCodeProvider(Provider):
             disallowed_tools=disallowed_tools,
             reasoning=reasoning,
         )
+
+    def resume_key_from_trajectory(self, trajectory: Trajectory) -> str | None:
+        # claude's resume key is its session id.
+        return trajectory.session_id or None
+
+    def resume_session(
+        self,
+        mcp_servers: list[MCPServer],
+        *,
+        session_id: str,
+        resume_key: str,
+        trajectory: Trajectory | None = None,
+        **kwargs: Any,
+    ) -> ClaudeCodeSession:
+        # For claude the resume key *is* the session id (passed to the CLI as
+        # --resume once _has_sent is set).
+        session = ClaudeCodeSession(
+            mcp_servers=mcp_servers,
+            model=kwargs.get("model") or (trajectory.model if trajectory else None),
+            system_prompt=(trajectory.system_prompt if trajectory else None) or None,
+            session_id=resume_key,
+            disallowed_tools=kwargs.get("disallowed_tools"),
+            reasoning=(trajectory.reasoning if trajectory else None) or None,
+        )
+        session._has_sent = True
+        if trajectory is not None:
+            session._restore_from_trajectory(trajectory)
+        return session

{coding_agent_wrapper-0.1.4 → coding_agent_wrapper-0.1.5}/caw/providers/codex.py

@@ -513,6 +513,11 @@ class CodexSession(ProviderSession):
     def session_id(self) -> str:
         return self._session_id
 
+    @property
+    def resume_key(self) -> str | None:
+        # codex resumes via `codex exec resume <thread_id>`.
+        return self._thread_id
+
     @property
     def last_raw_output(self) -> str:
         return self._last_raw_output
@@ -530,7 +535,9 @@ class CodexSession(ProviderSession):
             turns=list(self._turns),
             usage=self._total_usage,
             duration_ms=self._total_duration_ms,
-            metadata={},
+            # thread_id is the codex-side resume key; persist it so the session
+            # can be resumed in a new process (see CodexProvider.resume_session).
+            metadata={"thread_id": self._thread_id} if self._thread_id else {},
         )
 
     def end(self) -> Trajectory:
@@ -599,3 +606,30 @@ class CodexProvider(Provider):
             reasoning=kwargs.get("reasoning"),
             sandbox=kwargs.get("sandbox"),
         )
+
+    def resume_key_from_trajectory(self, trajectory: Trajectory) -> str | None:
+        return trajectory.metadata.get("thread_id")
+
+    def resume_session(
+        self,
+        mcp_servers: list[MCPServer],
+        *,
+        session_id: str,
+        resume_key: str,
+        trajectory: Trajectory | None = None,
+        **kwargs: Any,
+    ) -> CodexSession:
+        session = CodexSession(
+            mcp_servers=mcp_servers,
+            model=kwargs.get("model") or (trajectory.model if trajectory else None),
+            system_prompt=(trajectory.system_prompt if trajectory else None) or None,
+            session_id=session_id,
+            reasoning=(trajectory.reasoning if trajectory else None) or None,
+            sandbox=kwargs.get("sandbox"),
+        )
+        # The codex CLI resumes via `codex exec resume <thread_id>`.
+        session._thread_id = resume_key
+        session._has_sent = True
+        if trajectory is not None:
+            session._restore_from_trajectory(trajectory)
+        return session

{coding_agent_wrapper-0.1.4 → coding_agent_wrapper-0.1.5}/caw/providers/opencode.py

@@ -511,6 +511,12 @@ class OpencodeSession(ProviderSession):
     def session_id(self) -> str:
         return self._session_id
 
+    @property
+    def resume_key(self) -> str | None:
+        # opencode resumes via `--session <opencode_session_id>` (the CLI's own
+        # id, captured from the event stream — distinct from caw's session_id).
+        return self._opencode_session_id
+
     @property
     def last_raw_output(self) -> str:
         return self._last_raw_output
@@ -581,6 +587,33 @@ class OpencodeProvider(Provider):
             disabled_tools=kwargs.get("disabled_tools"),
         )
 
+    def resume_key_from_trajectory(self, trajectory: Trajectory) -> str | None:
+        return trajectory.metadata.get("opencode_session_id")
+
+    def resume_session(
+        self,
+        mcp_servers: list[MCPServer],
+        *,
+        session_id: str,
+        resume_key: str,
+        trajectory: Trajectory | None = None,
+        **kwargs: Any,
+    ) -> OpencodeSession:
+        session = OpencodeSession(
+            mcp_servers=mcp_servers,
+            model=kwargs.get("model") or (trajectory.model if trajectory else None),
+            system_prompt=(trajectory.system_prompt if trajectory else None) or None,
+            session_id=session_id,
+            reasoning=(trajectory.reasoning if trajectory else None) or None,
+            disabled_tools=kwargs.get("disabled_tools"),
+        )
+        # The opencode CLI resumes via `--session <opencode_session_id>`.
+        session._opencode_session_id = resume_key
+        session._has_sent = True
+        if trajectory is not None:
+            session._restore_from_trajectory(trajectory)
+        return session
+
     def start_interactive(self, initial_prompt, mcp_servers, capture_bytes=0, **kwargs):  # type: ignore[override]
         """Launch ``opencode`` interactively (TUI) with an initial prompt.
 

{coding_agent_wrapper-0.1.4 → coding_agent_wrapper-0.1.5}/caw/storage.py

@@ -121,13 +121,20 @@ class SessionStore:
                 000_raw_output.jsonl
     """
 
-    def __init__(self, data_dir: str | Path, session_id: str) -> None:
+    def __init__(self, data_dir: str | Path, session_id: str, resume: bool = False) -> None:
         self._session_dir = Path(data_dir) / "sessions" / session_id
         self._turns_dir = self._session_dir / "turns"
         self._turns_dir.mkdir(parents=True, exist_ok=True)
-        self._turn_counter = 0
+        # On resume, continue numbering after the existing turn files so we
+        # append to — rather than overwrite — the original session's record.
+        self._turn_counter = self._next_turn_index() if resume else 0
         self._jsonl = JsonlWriter(self._session_dir / "traj.jsonl")
 
+    def _next_turn_index(self) -> int:
+        """One past the highest ``NNN_input.txt`` index already on disk."""
+        indices = [int(p.name[:3]) for p in self._turns_dir.glob("*_input.txt") if p.name[:3].isdigit()]
+        return max(indices) + 1 if indices else 0
+
     @property
     def session_dir(self) -> Path:
         """Path to this session's directory."""

{coding_agent_wrapper-0.1.4 → coding_agent_wrapper-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "coding-agent-wrapper"
-version = "0.1.4"
+version = "0.1.5"
 description = "Unified Python library and CLI for orchestrating coding agents (Claude Code, Codex, etc.) with MCP tool servers and credential management."
 readme = "README.md"
 requires-python = ">=3.10"