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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-agent-wrapper
-Version: 0.1.2
+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
@@ -30,7 +30,7 @@ Description-Content-Type: text/markdown
 
 # caw
 
-**Coding Agent Wrapper** — a Python library and CLI for orchestrating coding agents (Claude Code, Codex) with a unified interface, MCP tool servers, and credential management for Docker containers.
+**Coding Agent Wrapper** — a Python library and CLI for orchestrating coding agents (Claude Code, Codex, opencode) with a unified interface, MCP tool servers, and credential management for Docker containers.
 
 ## Install
 
@@ -85,12 +85,57 @@ 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 |
 |----------|-----|---------------|
 | Claude Code | `claude` | `claude_code` |
 | Codex | `codex` | `codex` |
+| opencode | `opencode` | `opencode` |
 
 Set via constructor, environment variable, or at runtime:
 
@@ -197,7 +242,7 @@ Sessions are persisted to JSONL in `caw_data/` by default.
 
 ## CLI: `caw auth` — Credential Management for Docker Containers
 
-Manages coding agent OAuth credentials so they stay in sync between your host and Docker containers. Supports Claude Code and Codex. Host credential files are never modified — they are bind-mounted into the container at run time.
+Manages coding agent OAuth credentials so they stay in sync between your host and Docker containers. Supports Claude Code, Codex, and opencode. Host credential files are never modified — they are bind-mounted into the container at run time.
 
 ```bash
 caw auth setup                        # snapshot configs, write mount manifest

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

@@ -1,6 +1,6 @@
 # caw
 
-**Coding Agent Wrapper** — a Python library and CLI for orchestrating coding agents (Claude Code, Codex) with a unified interface, MCP tool servers, and credential management for Docker containers.
+**Coding Agent Wrapper** — a Python library and CLI for orchestrating coding agents (Claude Code, Codex, opencode) with a unified interface, MCP tool servers, and credential management for Docker containers.
 
 ## Install
 
@@ -55,12 +55,57 @@ 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 |
 |----------|-----|---------------|
 | Claude Code | `claude` | `claude_code` |
 | Codex | `codex` | `codex` |
+| opencode | `opencode` | `opencode` |
 
 Set via constructor, environment variable, or at runtime:
 
@@ -167,7 +212,7 @@ Sessions are persisted to JSONL in `caw_data/` by default.
 
 ## CLI: `caw auth` — Credential Management for Docker Containers
 
-Manages coding agent OAuth credentials so they stay in sync between your host and Docker containers. Supports Claude Code and Codex. Host credential files are never modified — they are bind-mounted into the container at run time.
+Manages coding agent OAuth credentials so they stay in sync between your host and Docker containers. Supports Claude Code, Codex, and opencode. Host credential files are never modified — they are bind-mounted into the container at run time.
 
 ```bash
 caw auth setup                        # snapshot configs, write mount manifest

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

@@ -1,11 +1,23 @@
 """caw - Coding Agent Wrapper."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.5"
 
 from caw.agent import Agent, Session, register_provider
+from caw.auth import get_docker_flags as auth_get_docker_flags
+from caw.auth import get_status as auth_get_status
+from caw.auth import setup as auth_setup
 from caw.display import Display, DisplayMode, get_global_display, set_global_display
 from caw.faststats import FastStats
-from caw.storage import JsonlWriter, SessionStore
+from caw.logger import AgentLogger
+from caw.mcp import (
+    MCPServerHandle,
+    create_mcp_http_server_bundle,
+    create_stateless_tool_server,
+    create_subagent_tool_server,
+    get_state_from_context,
+    mcp_tool,
+    register_tool,
+)
 from caw.models import (
     AgentSpec,
     ContentBlock,
@@ -24,30 +36,25 @@ from caw.models import (
 from caw.provider import Provider, ProviderSession
 from caw.providers.claude_code import ClaudeCodeProvider
 from caw.providers.codex import CodexProvider
-from caw.mcp import (
-    MCPServerHandle,
-    create_mcp_http_server_bundle,
-    create_stateless_tool_server,
-    create_subagent_tool_server,
-    get_state_from_context,
-    mcp_tool,
-    register_tool,
-)
+from caw.providers.opencode import OpencodeProvider
+from caw.storage import JsonlWriter, SessionStore
 from caw.toolkit import ToolKit, tool
 from caw.viewer import ViewerServer, start_viewer_server
-from caw.auth import setup as auth_setup, get_status as auth_get_status, get_docker_flags as auth_get_docker_flags
 
 # Auto-register built-in providers
 register_provider("claude_code", ClaudeCodeProvider)
 register_provider("claude", ClaudeCodeProvider)
 register_provider("cc", ClaudeCodeProvider)
 register_provider("codex", CodexProvider)
+register_provider("opencode", OpencodeProvider)
 
 __all__ = [
     "Agent",
+    "AgentLogger",
     "AgentSpec",
     "ClaudeCodeProvider",
     "CodexProvider",
+    "OpencodeProvider",
     "JsonlWriter",
     "ContentBlock",
     "InteractiveResult",

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

@@ -16,6 +16,7 @@ from pathlib import Path
 from typing import Any
 
 from caw.display import get_global_display
+from caw.logger import AgentLogger
 from caw.models import AgentSpec, InteractiveResult, MCPServer, ModelTier, ToolGroup, ToolUse, Trajectory, Turn
 from caw.provider import Provider, ProviderSession
 from caw.storage import SessionStore
@@ -64,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.
 
@@ -103,6 +134,7 @@ class Session:
         tool_handles: list[Any] | None = None,
         auto_wait: bool = True,
         metadata: dict[str, Any] | None = None,
+        logger: AgentLogger | None = None,
     ) -> None:
         self._session = provider_session
         self._store = store
@@ -114,6 +146,9 @@ class Session:
         self._send_lock = threading.Lock()
         self._async_send_lock: asyncio.Lock | None = None
         self._traj_path: str | Path | None = None
+        self._logger = logger
+        if logger is not None:
+            self._session.set_logger(logger)
 
     async def send_async(self, message: str) -> Turn:
         """Async version of :meth:`send` — runs in a thread.
@@ -261,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."""
@@ -296,12 +357,14 @@ class Agent:
         stateless_tools: list[Any] | None = None,
         name: str = "",
         description: str = "",
+        logger: AgentLogger | None = None,
         **kwargs: Any,
     ) -> None:
         self._provider_name = provider
         self._provider: Provider | None = None
         self._mcp_servers: list[MCPServer] = []
         self._subagents: list[AgentSpec] = []
+        self._logger = logger
         self._tool_servers: list[Any] = []  # list[MCPServerHandle], lazy import
         if tool_servers:
             for ts in tool_servers:
@@ -504,12 +567,144 @@ class Agent:
         traj_path:
             If set, the trajectory is saved to this path after each
             step and when :meth:`Session.end` is called.
+        logger:
+            Optional generic logger (any object with ``info``/``warn``/
+            ``error`` string methods). If set, every major event — user
+            message, tool call, tool result, assistant text, thinking,
+            turn-end stats — is also emitted as a one-line summary
+            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.")
 
-        # Pop auto_wait and metadata — these are Session concerns, not provider kwargs
+        merged = {**self._kwargs, **kwargs}
+        auto_wait, session_metadata, logger = self._pop_session_opts(merged)
+
+        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
         # Agent-level metadata as base, session kwargs override
         if self._metadata:
             session_metadata = {**self._metadata, **session_metadata}
@@ -518,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:
@@ -526,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:
@@ -554,25 +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,
-        )
-
-        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.2 → coding_agent_wrapper-0.1.5}/caw/auth/providers.py

@@ -259,6 +259,78 @@ class CodexAuthProvider(AgentAuthProvider):
         return files
 
 
+# ---------------------------------------------------------------------------
+# opencode
+# ---------------------------------------------------------------------------
+
+
+class OpencodeAuthProvider(AgentAuthProvider):
+    name = "opencode"
+
+    def validate(self, src_home: Path) -> list[str]:
+        missing: list[str] = []
+        if not (src_home / ".local" / "share" / "opencode" / "auth.json").exists():
+            missing.append(str(src_home / ".local" / "share" / "opencode" / "auth.json"))
+        return missing
+
+    def describe(self, src_home: Path) -> str:
+        try:
+            with open(src_home / ".local" / "share" / "opencode" / "auth.json") as f:
+                auth_data = json.load(f)
+            providers = list(auth_data.keys())
+            if not providers:
+                return "Auth file present (no providers configured)"
+            kinds = []
+            for p in providers:
+                entry = auth_data.get(p) or {}
+                kinds.append(f"{p}({entry.get('type', 'unknown')})")
+            return f"Providers: {', '.join(kinds)}"
+        except Exception:
+            return "Could not read auth info"
+
+    def collect(self, src_home: Path) -> list[CollectedFile]:
+        files: list[CollectedFile] = []
+
+        # auth.json — credential (bind-mounted for token refresh write-back)
+        auth_src = src_home / ".local" / "share" / "opencode" / "auth.json"
+        with open(auth_src, "rb") as f:
+            auth_content = f.read()
+        files.append(
+            CollectedFile(
+                manifest_file=ManifestFile(
+                    src="opencode/auth.json",
+                    container_target=".local/share/opencode/auth.json",
+                    host_original=".local/share/opencode/auth.json",
+                    type="credential",
+                    strategy="bind",
+                    mode="0600",
+                ),
+                content=auth_content,
+            )
+        )
+
+        # opencode.jsonc / opencode.json — config, copied (no local-project paths to strip)
+        for fname in ("opencode.jsonc", "opencode.json"):
+            cfg = src_home / ".config" / "opencode" / fname
+            if cfg.exists():
+                files.append(
+                    CollectedFile(
+                        manifest_file=ManifestFile(
+                            src=f"opencode/{fname}",
+                            container_target=f".config/opencode/{fname}",
+                            host_original=f".config/opencode/{fname}",
+                            type="config",
+                            strategy="copy",
+                            mode="0644",
+                        ),
+                        content=cfg.read_bytes(),
+                    )
+                )
+                break  # only one of the two should exist
+
+        return files
+
+
 # ---------------------------------------------------------------------------
 # Provider registry
 # ---------------------------------------------------------------------------
@@ -268,5 +340,6 @@ PROVIDERS: dict[str, AgentAuthProvider] = {
     for p in [
         ClaudeAuthProvider(),
         CodexAuthProvider(),
+        OpencodeAuthProvider(),
     ]
 }