coding-agent-wrapper 0.1.0__py3-none-any.whl

caw/storage.py

@@ -0,0 +1,184 @@
+"""Session data persistence — writes raw session data to disk."""
+
+from __future__ import annotations
+
+import fcntl
+import json
+from pathlib import Path
+from typing import Any
+
+from caw.models import TextBlock, ThinkingBlock, ToolUse, Trajectory, Turn
+
+
+class JsonlWriter:
+    """Append-only JSONL writer with file locking for concurrent safety.
+
+    When *subagent* is set, every entry is tagged with ``"subagent": name``
+    so readers can distinguish parent vs. subagent events.
+    """
+
+    def __init__(self, path: str | Path, *, subagent: str | None = None) -> None:
+        self._path = Path(path)
+        self._subagent = subagent
+
+    def append(self, entry: dict[str, Any]) -> None:
+        """Append a single JSON object as one line (file-locked)."""
+        if self._subagent:
+            entry = {**entry, "subagent": self._subagent}
+        with open(self._path, "a", encoding="utf-8") as f:
+            fcntl.flock(f, fcntl.LOCK_EX)
+            f.write(json.dumps(entry) + "\n")
+
+    # ------------------------------------------------------------------
+    # High-level helpers
+    # ------------------------------------------------------------------
+
+    def write_metadata(self, trajectory: Trajectory) -> None:
+        """Write a metadata entry (typically once at session start)."""
+        self.append(
+            {
+                "type": "metadata",
+                "session_id": trajectory.session_id,
+                "created_at": trajectory.created_at,
+                "agent": trajectory.agent,
+                "model": trajectory.model,
+                "system_prompt": trajectory.system_prompt,
+                "reasoning": trajectory.reasoning,
+                "mcp_servers": [
+                    {"name": s.name, "command": s.command, "args": s.args, "env": s.env, "url": s.url}
+                    for s in trajectory.mcp_servers
+                ],
+                "metadata": trajectory.metadata,
+            }
+        )
+
+    def write_turn_events(self, turn: Turn, turn_index: int) -> None:
+        """Write per-event JSONL lines for a completed turn."""
+        # User message
+        self.append({"type": "user", "message": turn.input, "turn_index": turn_index})
+
+        # Content blocks — mirrors Display event order
+        for block in turn.output:
+            if isinstance(block, ThinkingBlock):
+                self.append(
+                    {
+                        "type": "thinking",
+                        "text": block.text,
+                        "turn_index": turn_index,
+                    }
+                )
+            elif isinstance(block, TextBlock):
+                self.append(
+                    {
+                        "type": "text",
+                        "text": block.text,
+                        "turn_index": turn_index,
+                    }
+                )
+            elif isinstance(block, ToolUse):
+                self.append(
+                    {
+                        "type": "tool_call",
+                        "id": block.id,
+                        "name": block.name,
+                        "arguments": block.arguments,
+                        "turn_index": turn_index,
+                    }
+                )
+                result_entry: dict[str, Any] = {
+                    "type": "tool_result",
+                    "id": block.id,
+                    "name": block.name,
+                    "output": block.output,
+                    "is_error": block.is_error,
+                    "turn_index": turn_index,
+                }
+                if block.subagent_trajectory:
+                    result_entry["subagent_trajectory"] = block.subagent_trajectory.to_dict()
+                self.append(result_entry)
+
+        # Turn-end stats
+        self.append(
+            {
+                "type": "turn_end",
+                "turn_index": turn_index,
+                "usage": turn.usage.to_dict(),
+                "duration_ms": turn.duration_ms,
+            }
+        )
+
+
+class SessionStore:
+    """Persists session data to a directory on disk.
+
+    Layout::
+
+        <data_dir>/sessions/<session_id>/
+            traj.jsonl          # incremental append-only event log
+            trajectory.json     # full trajectory, overwritten after each turn
+            turns/
+                000_input.txt
+                000_raw_output.jsonl
+    """
+
+    def __init__(self, data_dir: str | Path, session_id: str) -> 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
+        self._jsonl = JsonlWriter(self._session_dir / "traj.jsonl")
+
+    @property
+    def session_dir(self) -> Path:
+        """Path to this session's directory."""
+        return self._session_dir
+
+    @property
+    def jsonl_path(self) -> Path:
+        """Path to the traj.jsonl file."""
+        return self._jsonl._path
+
+    # ------------------------------------------------------------------
+    # JSONL delegation
+    # ------------------------------------------------------------------
+
+    def write_metadata(self, trajectory: Trajectory) -> None:
+        """Append a metadata entry to traj.jsonl (called once at session start)."""
+        self._jsonl.write_metadata(trajectory)
+
+    # ------------------------------------------------------------------
+    # Trajectory
+    # ------------------------------------------------------------------
+
+    def _save_trajectory(self, trajectory: Trajectory) -> None:
+        """Overwrite trajectory.json with the full trajectory."""
+        path = self._session_dir / "trajectory.json"
+        path.write_text(json.dumps(trajectory.to_dict(), indent=2) + "\n", encoding="utf-8")
+
+    def finalize(self, trajectory: Trajectory) -> None:
+        """Write trajectory.json with the complete session record."""
+        self._save_trajectory(trajectory)
+
+    # ------------------------------------------------------------------
+    # Turn files
+    # ------------------------------------------------------------------
+
+    def append_turn(self, turn: Turn, trajectory: Trajectory, raw_output: str | None = None) -> None:
+        """Record a completed turn: event JSONL lines, trajectory snapshot, and raw files."""
+        prefix = f"{self._turn_counter:03d}"
+
+        # Raw turn files
+        input_path = self._turns_dir / f"{prefix}_input.txt"
+        input_path.write_text(turn.input, encoding="utf-8")
+
+        if raw_output is not None:
+            output_path = self._turns_dir / f"{prefix}_raw_output.jsonl"
+            output_path.write_text(raw_output, encoding="utf-8")
+
+        # Per-event JSONL lines
+        self._jsonl.write_turn_events(turn, self._turn_counter)
+
+        # Full trajectory snapshot
+        self._save_trajectory(trajectory)
+
+        self._turn_counter += 1

caw/toolkit.py

@@ -0,0 +1,198 @@
+"""ToolKit base class and @tool decorator for declarative MCP tool servers.
+
+Usage::
+
+    from caw import Agent, ToolKit, tool
+
+    class UserDB(ToolKit, server_name="user_db", display_name="User Database"):
+        def __init__(self):
+            self.users = ["Alice", "Bob"]
+
+        @tool(description="List all users")
+        async def list_users(self) -> str:
+            return ", ".join(self.users)
+
+    db = UserDB()
+    agent = Agent(system_prompt="You have a user DB.", tool_servers=[db])
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import threading
+import uuid as uuid_mod
+from typing import Any, ClassVar
+
+from caw.mcp import (
+    Context,
+    MCPServerHandle,
+    create_mcp_http_server_bundle,
+    get_state_from_context,
+    register_tool,
+)
+
+
+# -- @tool decorator ----------------------------------------------------------
+
+
+def tool(
+    name: str | None = None,
+    *,
+    description: str | None = None,
+    title: str | None = None,
+    annotations: Any | None = None,
+    structured_output: bool | None = None,
+):
+    """Mark a method as an MCP tool.  Does NOT modify the function itself."""
+
+    def decorator(method):
+        method._toolkit_tool_info = {
+            "name": name,
+            "description": description,
+            "title": title,
+            "annotations": annotations,
+            "structured_output": structured_output,
+        }
+        return method
+
+    return decorator
+
+
+# -- ToolKit base class -------------------------------------------------------
+
+
+class ToolKit:
+    """Base class for declarative MCP tool servers.
+
+    Subclass, decorate methods with ``@tool``, call ``as_server()``
+    to get an :class:`MCPServerHandle`.
+    """
+
+    _server_name: ClassVar[str] = ""
+    _display_name: ClassVar[str] = ""
+    _thread_safe: ClassVar[bool] = False
+
+    def __init_subclass__(
+        cls,
+        server_name: str = "",
+        display_name: str = "",
+        thread_safe: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        super().__init_subclass__(**kwargs)
+        cls._server_name = server_name or cls._server_name
+        cls._display_name = display_name or cls._display_name
+        if thread_safe:
+            cls._thread_safe = True
+
+    def as_server(self, server_id: str | None = None) -> MCPServerHandle:
+        """Build and return an :class:`MCPServerHandle` with all ``@tool`` methods registered."""
+        cls = type(self)
+        if cls._thread_safe and not hasattr(self, "_toolkit_lock"):
+            self._toolkit_lock = threading.Lock()
+        sid = server_id or f"{cls._server_name or cls.__name__}_{uuid_mod.uuid4().hex[:6]}"
+
+        handle = create_mcp_http_server_bundle(
+            sid,
+            display_name=cls._display_name or cls._server_name or cls.__name__,
+            state_instance=self,
+        )
+
+        for attr_name in dir(cls):
+            attr = getattr(cls, attr_name, None)
+            if attr is None:
+                continue
+            info = getattr(attr, "_toolkit_tool_info", None)
+            if info is None:
+                continue
+            wrapper = _make_tool_func(attr, info)
+            register_tool(handle.server, wrapper)
+
+        return handle
+
+
+# -- Wrapper generator --------------------------------------------------------
+
+
+def _make_tool_func(method, info: dict[str, Any]):
+    """Create an MCP-compatible free function from a ToolKit method.
+
+    The generated wrapper:
+    - Drops ``self`` from the signature.
+    - Appends ``ctx: Context`` (or keeps it if the user already declared it).
+    - At call time, retrieves the ToolKit instance from context and delegates.
+    """
+    sig = inspect.signature(method)
+    params = list(sig.parameters.values())
+
+    # Remove 'self'
+    if params and params[0].name == "self":
+        params = params[1:]
+
+    # Check if the user declared a 'ctx' parameter
+    user_has_ctx = any(p.name == "ctx" for p in params)
+
+    # Build new parameter list: all user params (minus ctx if present) + ctx at end
+    new_params = [p for p in params if p.name != "ctx"]
+    ctx_param = inspect.Parameter(
+        "ctx",
+        inspect.Parameter.KEYWORD_ONLY,
+        annotation=Context,
+    )
+    new_params.append(ctx_param)
+
+    new_sig = sig.replace(parameters=new_params)
+
+    is_async = asyncio.iscoroutinefunction(method)
+
+    if is_async:
+
+        async def wrapper(**kwargs):
+            ctx = kwargs.pop("ctx")
+            self_instance = get_state_from_context(ctx)
+            if user_has_ctx:
+                kwargs["ctx"] = ctx
+            lock = getattr(self_instance, "_toolkit_lock", None)
+            if lock is not None:
+                with lock:
+                    return await method(self_instance, **kwargs)
+            return await method(self_instance, **kwargs)
+
+    else:
+
+        async def wrapper(**kwargs):
+            ctx = kwargs.pop("ctx")
+            self_instance = get_state_from_context(ctx)
+            if user_has_ctx:
+                kwargs["ctx"] = ctx
+            lock = getattr(self_instance, "_toolkit_lock", None)
+            if lock is not None:
+                with lock:
+                    return method(self_instance, **kwargs)
+            return method(self_instance, **kwargs)
+
+    tool_name = info.get("name") or method.__name__
+    wrapper.__name__ = tool_name
+    wrapper.__qualname__ = tool_name
+    wrapper.__doc__ = info.get("description") or method.__doc__ or ""
+    wrapper.__signature__ = new_sig
+    # Set __annotations__ so typing.get_type_hints() can find the Context
+    # parameter — FastMCP uses get_type_hints (not __signature__) to detect
+    # which params to strip from the input schema and inject at call time.
+    wrapper.__annotations__ = {
+        p.name: p.annotation for p in new_sig.parameters.values() if p.annotation is not inspect.Parameter.empty
+    }
+    if new_sig.return_annotation is not inspect.Signature.empty:
+        wrapper.__annotations__["return"] = new_sig.return_annotation
+
+    # Attach _mcp_tool_info for register_tool()
+    wrapper._mcp_tool_info = {
+        "name": tool_name,
+        "title": info.get("title"),
+        "description": info.get("description") or method.__doc__ or "",
+        "annotations": info.get("annotations"),
+        "structured_output": info.get("structured_output"),
+    }
+
+    return wrapper

caw/viewer/__init__.py

@@ -0,0 +1,149 @@
+"""Trajectory viewer web interface.
+
+Provides a simple HTTP server that serves a self-contained trajectory viewer.
+The viewer loads trajectory JSON files by absolute path.
+
+Usage::
+
+    from caw.viewer import start_viewer_server
+
+    server = start_viewer_server()          # auto host/port
+    server = start_viewer_server(port=8080) # fixed port
+    print(server.url)                       # http://localhost:8080
+    server.check_status()                   # True / False
+    server.stop()
+"""
+
+from __future__ import annotations
+
+import json
+import socket
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from socketserver import ThreadingMixIn
+from urllib.parse import parse_qs, urlparse
+
+__all__ = ["ViewerServer", "start_viewer_server"]
+
+STATIC_DIR = Path(__file__).parent / "static"
+
+
+def _find_free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("", 0))
+        return s.getsockname()[1]
+
+
+class _ThreadedHTTPServer(ThreadingMixIn, HTTPServer):
+    daemon_threads = True
+
+
+class ViewerServer:
+    """Handle for a running trajectory viewer server."""
+
+    def __init__(
+        self,
+        httpd: HTTPServer,
+        thread: threading.Thread,
+        host: str,
+        port: int,
+    ) -> None:
+        self._httpd = httpd
+        self._thread = thread
+        self.host = host
+        self.port = port
+
+    @property
+    def url(self) -> str:
+        return f"http://{self.host}:{self.port}"
+
+    def check_status(self) -> bool:
+        """Return True if the server is running."""
+        return self._thread.is_alive()
+
+    def stop(self) -> None:
+        """Shut down the server."""
+        self._httpd.shutdown()
+        self._thread.join(timeout=5)
+
+    def __repr__(self) -> str:
+        status = "running" if self.check_status() else "stopped"
+        return f"ViewerServer({self.url}, {status})"
+
+
+class _Handler(BaseHTTPRequestHandler):
+    def log_message(self, format, *args):  # noqa: A002
+        pass  # suppress request logging
+
+    def do_GET(self):  # noqa: N802
+        parsed = urlparse(self.path)
+        path = parsed.path
+
+        if path == "/" or path == "/index.html":
+            self._serve_file(STATIC_DIR / "index.html", "text/html")
+        elif path == "/api/trajectory":
+            self._handle_trajectory(parse_qs(parsed.query))
+        else:
+            self.send_error(404)
+
+    def _send_json(self, data, status: int = 200):
+        body = json.dumps(data).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _serve_file(self, filepath: Path, content_type: str):
+        if not filepath.is_file():
+            self.send_error(404)
+            return
+        content = filepath.read_bytes()
+        self.send_response(200)
+        self.send_header("Content-Type", f"{content_type}; charset=utf-8")
+        self.send_header("Content-Length", str(len(content)))
+        self.end_headers()
+        self.wfile.write(content)
+
+    def _handle_trajectory(self, params):
+        paths = params.get("path", [])
+        if not paths:
+            self._send_json({"detail": "Missing 'path' parameter"}, 400)
+            return
+        filepath = Path(paths[0]).resolve()
+        if not filepath.is_file():
+            self._send_json({"detail": f"File not found: {paths[0]}"}, 404)
+            return
+        try:
+            raw = filepath.read_text()
+            data = json.loads(raw)
+        except json.JSONDecodeError as e:
+            self._send_json({"detail": f"Invalid JSON: {e}"}, 500)
+            return
+        self._send_json(data)
+
+
+def start_viewer_server(
+    host: str | None = None,
+    port: int | None = None,
+) -> ViewerServer:
+    """Start a trajectory viewer web server.
+
+    Args:
+        host: Host to bind to.  Defaults to ``"localhost"``.
+        port: Port to bind to.  If *None*, a free port is chosen automatically.
+
+    Returns:
+        A :class:`ViewerServer` handle.
+    """
+    host = host or "localhost"
+    port = port or _find_free_port()
+
+    httpd = _ThreadedHTTPServer((host, port), _Handler)
+
+    thread = threading.Thread(target=httpd.serve_forever, daemon=True)
+    thread.start()
+
+    return ViewerServer(httpd, thread, host, port)