pcode 0.1.0__py3-none-any.whl

pcode/claude_sdk/errors.py

@@ -0,0 +1,61 @@
+"""Exceptions for failed `claude:` requests, and what to tell the user about them."""
+
+from pydantic_ai.exceptions import ModelAPIError, ModelHTTPError
+
+MISSING_SDK = (
+    "claude: models need pcode's optional `claude` extra, which is not installed. "
+    "From a pcode checkout run `make install`, or `uv tool install --editable '.[claude]'`."
+)
+
+
+class ClaudeHTTPError(ModelHTTPError):
+    """An API error the CLI reported for a `claude:` request."""
+
+
+class ClaudeProcessError(ModelAPIError):
+    """The CLI process ended mid-request; a retry starts another (transient)."""
+
+
+class ClaudeConnectionError(ModelAPIError):
+    """The CLI's request got no HTTP response: dropped, refused or timed out (transient).
+
+    Verified against the bundled CLI: all three arrive as a `server_error` with
+    no `api_error_status`, where a real 500 or 529 carries its status. With the
+    CLI's own retries off, pcode's transient retry covers these, as it covers
+    the same failures on its other providers.
+    """
+
+
+class ClaudeStartError(ModelAPIError):
+    """The CLI process could not be started or resumed."""
+
+
+class ClaudeSDKMissing(ValueError):
+    """pcode was installed without its `claude` extra."""
+
+
+def failure_hint(error: BaseException) -> str | None:
+    """What to do about a failed `claude:` request, or None for any other provider."""
+    seen = set()
+    while error is not None and id(error) not in seen and len(seen) < 16:
+        seen.add(id(error))
+        if isinstance(error, ClaudeSDKMissing):
+            return MISSING_SDK
+        if isinstance(error, ClaudeConnectionError):
+            # The CLI's own text stays in the diagnostics log.
+            return (
+                "Claude Code got no response from Anthropic (connection dropped, refused "
+                "or timed out). Check network/proxy connectivity and retry when ready."
+            )
+        if isinstance(error, ClaudeHTTPError):
+            body = error.body if isinstance(error.body, dict) else {}
+            kind = (body.get("error") or {}).get("type")
+            if error.status_code in (401, 403) or kind == "authentication_failed":
+                return "Claude Code is not signed in, or its login expired. Run /login claude."
+            return None
+        if isinstance(error, ClaudeStartError):
+            return f"{error.message} Check the Claude Code install, or run /login claude."
+        if isinstance(error, ClaudeProcessError):
+            return f"{error.message} Retry; pcode starts a new Claude Code process."
+        error = error.__cause__ or error.__context__
+    return None

pcode/claude_sdk/messages.py

@@ -0,0 +1,154 @@
+"""History bookkeeping: normalizing, hashing and replaying Anthropic messages."""
+
+import base64
+import hashlib
+import io
+import json
+from typing import Any
+
+REPLAY_INTRO = (
+    "This conversation began outside the current session, so its earlier messages are "
+    "replayed below as a transcript. Treat them as having happened here and continue "
+    "from the final message.\n\n"
+)
+
+
+def _clean(value: Any) -> Any:
+    """Drop cache markers and make binary sources plain base64 JSON.
+
+    The CLI places its own cache markers, and they never change content.
+    Pydantic AI maps image and PDF bytes to `io.BytesIO`, which the Anthropic
+    SDK encodes on send; the CLI takes JSON, and hashing needs stable values.
+    """
+    if isinstance(value, io.BytesIO):
+        return base64.b64encode(value.getvalue()).decode("ascii")
+    if isinstance(value, dict):
+        return {k: _clean(v) for k, v in value.items() if k != "cache_control"}
+    if isinstance(value, list):
+        return [_clean(v) for v in value]
+    return value
+
+
+def _blocks(message: dict) -> list[dict]:
+    content = message.get("content")
+    if isinstance(content, str):
+        return [{"type": "text", "text": content}] if content else []
+    return list(content or [])
+
+
+def normalize(messages: list[dict]) -> list[dict]:
+    """Anthropic messages without cache markers, consecutive same-role turns merged.
+
+    Pydantic AI leaves an appended reminder as its own user message; the API
+    merges consecutive turns anyway, and one user turn is one CLI input.
+    """
+    merged: list[dict] = []
+    for message in _clean(messages):
+        if merged and merged[-1]["role"] == message["role"]:
+            merged[-1] = {
+                "role": message["role"],
+                "content": _blocks(merged[-1]) + _blocks(message),
+            }
+        else:
+            merged.append({"role": message["role"], "content": _blocks(message)})
+    return merged
+
+
+def _digest(previous: str, message: dict) -> str:
+    text = json.dumps(message, sort_keys=True, separators=(",", ":"), default=str)
+    return hashlib.sha256(f"{previous}\n{text}".encode()).hexdigest()
+
+
+def lineage(messages: list[dict]) -> list[str]:
+    """One hash per message, each covering the whole history up to it."""
+    chain, previous = [], "pcode-claude-1"
+    for message in messages:
+        previous = _digest(previous, message)
+        chain.append(previous)
+    return chain
+
+
+def _tool_use_ids(message: dict) -> tuple[str, ...]:
+    return tuple(b["id"] for b in _blocks(message) if b.get("type") == "tool_use")
+
+
+def _result_ids(message: dict) -> set[str]:
+    return {b["tool_use_id"] for b in _blocks(message) if b.get("type") == "tool_result"}
+
+
+def _result_text(block: dict) -> str:
+    content = block.get("content")
+    if isinstance(content, str):
+        return content
+    return "\n".join(_render_block(item) for item in content or [])
+
+
+def _render_block(block: dict) -> str:
+    kind = block.get("type")
+    if kind == "text":
+        return block.get("text", "")
+    if kind == "tool_use":
+        arguments = json.dumps(block.get("input"), ensure_ascii=False, default=str)
+        return f"[Called tool {block.get('name')} (id {block.get('id')}) with {arguments}]"
+    if kind == "tool_result":
+        status = " (error)" if block.get("is_error") else ""
+        return f"[Result of tool call {block.get('tool_use_id')}{status}]\n{_result_text(block)}"
+    if kind in ("thinking", "redacted_thinking"):
+        return ""
+    return f"[{kind or 'content'} omitted]"
+
+
+def replay(messages: list[dict], open_tool_ids: tuple[str, ...] = ()) -> list[dict]:
+    """One user turn carrying `messages`, for a CLI transcript that lacks them.
+
+    Results for the tool calls the transcript ends on (`open_tool_ids`) stay
+    structured, since the API requires them; everything else becomes text.
+    Images and documents from the final message are still attached.
+    """
+    first = _blocks(messages[0]) if messages else []
+    head = [
+        b for b in first if b.get("type") == "tool_result" and b["tool_use_id"] in open_tool_ids
+    ]
+    answered = {b["tool_use_id"] for b in head}
+    head += [
+        {
+            "type": "tool_result",
+            "tool_use_id": i,
+            "content": "[No result recorded]",
+            "is_error": True,
+        }
+        for i in open_tool_ids
+        if i not in answered
+    ]
+    rest = [
+        {"role": messages[0]["role"], "content": [b for b in first if b not in head]},
+        *messages[1:],
+    ]
+    turns = []
+    for message in rest:
+        text = "\n".join(filter(None, (_render_block(b) for b in _blocks(message))))
+        if text:
+            turns.append(f"[{message['role'].title()}]\n{text}")
+    attached = [b for b in _blocks(messages[-1]) if b.get("type") in ("image", "document")]
+    body = "\n\n".join(turns)
+    text = f"{REPLAY_INTRO}<conversation>\n{body}\n</conversation>" if turns else ""
+    return head + ([{"type": "text", "text": text}] if text else []) + attached
+
+
+def _mcp_content(block: dict) -> list[dict]:
+    """An Anthropic tool_result's content as MCP content blocks."""
+    content = block.get("content")
+    if isinstance(content, str):
+        return [{"type": "text", "text": content}] if content else []
+    items = []
+    for item in content or []:
+        source = item.get("source") or {}
+        if item.get("type") == "text":
+            items.append({"type": "text", "text": item.get("text", "")})
+        elif item.get("type") == "image" and source.get("type") == "base64":
+            items.append(
+                {"type": "image", "data": source["data"], "mimeType": source["media_type"]}
+            )
+        else:
+            items.append({"type": "text", "text": _render_block(item)})
+    return items

pcode/claude_sdk/model.py

@@ -0,0 +1,179 @@
+"""`ClaudeModel`: an `AnthropicModel` whose requests go through a CLI process."""
+
+import json
+import os
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from functools import cached_property
+from typing import Any
+
+from anthropic import AsyncAnthropic
+from anthropic._models import construct_type
+from anthropic.types.beta import BetaRawMessageStreamEvent
+from pydantic_ai import RunContext
+from pydantic_ai._utils import PeekableAsyncStream
+from pydantic_ai.models import (
+    ModelRequestParameters,
+    StreamedResponse,
+    check_allow_model_requests,
+)
+from pydantic_ai.models.anthropic import AnthropicModel
+from pydantic_ai.providers.anthropic import AnthropicProvider
+
+from pcode.claude_sdk.errors import MISSING_SDK, ClaudeSDKMissing
+from pcode.claude_sdk.messages import _digest, lineage, normalize
+from pcode.claude_sdk.session import SessionConfig
+from pcode.claude_sdk.session_pool import pool
+from pcode.claude_sdk.workspace import CWD_SETTING
+
+PREFIX = "claude:"
+EFFORTS = frozenset({"low", "medium", "high", "xhigh", "max"})
+
+
+class ClaudeProvider(AnthropicProvider):
+    """Names responses `claude`. Its client is never called: the CLI makes every request."""
+
+    @property
+    def name(self) -> str:
+        return "claude"
+
+    def __init__(self) -> None:
+        super().__init__(
+            anthropic_client=AsyncAnthropic(
+                api_key="unused", base_url="https://claude-code.invalid", max_retries=0
+            )
+        )
+
+
+class _Events:
+    """Stream events as the Anthropic SDK types `_process_streamed_response` reads."""
+
+    def __init__(self, events: AsyncIterator[dict]) -> None:
+        self._events = events
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        event = await self._events.__anext__()
+        return construct_type(type_=BetaRawMessageStreamEvent, value=event)
+
+    async def close(self) -> None:
+        await self._events.aclose()
+
+
+# Model setting: False for a one-off request (a session title), whose process
+# is stopped once it answers. Kept, it would be the newest idle process and
+# evict the conversation's warm one under `claude_idle_processes`.
+KEEP_WARM_SETTING = "pcode_claude_keep_warm"
+
+
+class ClaudeModel(AnthropicModel):
+    @cached_property
+    def profile(self):
+        # The CLI forwards only MCP tools, so no Anthropic server tool reaches
+        # the model and web tools fall back to local ones. Like Meridian, wire
+        # tool deferral is off: hidden tools are withheld until found.
+        from pydantic_ai.profiles import merge_profile
+        from pydantic_ai.profiles.anthropic import AnthropicModelProfile
+
+        return merge_profile(
+            super().profile,
+            AnthropicModelProfile(
+                supported_native_tools=frozenset(),
+                tool_deferral_mode=None,
+                tool_addition_mode=None,
+                # The system prompt is fixed per process; mid-conversation
+                # system text must travel as user text instead.
+                supports_inline_system_prompts=False,
+            ),
+        )
+
+    def session_config(self, system, tools, settings) -> SessionConfig:
+        if isinstance(system, str):
+            prompt = system
+        else:
+            prompt = "\n\n".join(block["text"] for block in system if block.get("text"))
+        wire_tools = [
+            {
+                "name": tool["name"],
+                "description": tool.get("description") or "",
+                "input_schema": tool["input_schema"],
+            }
+            for tool in tools
+            if "input_schema" in tool
+        ]
+        effort = settings.get("anthropic_effort")
+        thinking = settings.get("anthropic_thinking")
+        max_tokens = settings.get("max_tokens")
+        return SessionConfig(
+            model=self.model_name,
+            cwd=str(settings.get(CWD_SETTING) or os.getcwd()),
+            system_prompt=prompt,
+            tools=json.dumps(wire_tools, sort_keys=True),
+            effort=effort if effort in EFFORTS else None,
+            thinking=json.dumps(thinking, sort_keys=True) if isinstance(thinking, dict) else None,
+            max_tokens=max_tokens if isinstance(max_tokens, int) and max_tokens > 0 else None,
+        )
+
+    async def request(self, messages, model_settings, model_request_parameters):
+        async with self.request_stream(
+            messages, model_settings, model_request_parameters
+        ) as stream:
+            async for _ in stream:
+                pass
+        return stream.get()
+
+    async def count_tokens(self, messages, model_settings, model_request_parameters):
+        raise NotImplementedError("claude: models cannot count tokens ahead of a request")
+
+    @asynccontextmanager
+    async def request_stream(
+        self,
+        messages,
+        model_settings,
+        model_request_parameters: ModelRequestParameters,
+        run_context: RunContext[Any] | None = None,
+    ) -> AsyncIterator[StreamedResponse]:
+        check_allow_model_requests()
+        settings, parameters = self.prepare_request(model_settings, model_request_parameters)
+        settings = dict(settings or {})
+        system, mapped = await self._map_message(messages, parameters, settings)
+        tools, _ = self._prepare_tools_and_tool_choice(settings, parameters)
+        config = self.session_config(system, tools, settings)
+        mapped = normalize(mapped)
+        chain = lineage(mapped)
+        sessions = pool()
+        checkout = await sessions.checkout(config, mapped, chain)
+        session = checkout.session
+        ok = False
+        try:
+            # `_process_streamed_response` peeks the first event before reading.
+            events = PeekableAsyncStream(_Events(session.response()))
+            stream = await self._process_streamed_response(events, parameters, settings)
+            yield stream
+            # Anything short of the whole message leaves the process mid-turn.
+            # A whole one is a fork point even if the process has since died.
+            if session.complete and session.stray_call:
+                # Resuming any of this history would show the model its own
+                # refused calls again: the next request replays it instead.
+                sessions.index.drop(chain)
+            elif session.complete and settings.get(KEEP_WARM_SETTING, True):
+                _, answer = await self._map_message([stream.get()], parameters, settings)
+                answer = normalize(answer)
+                if len(answer) == 1 and answer[0]["role"] == "assistant":
+                    sessions.record(session, _digest(chain[-1], answer[0]))
+                    ok = not session.dead
+        finally:
+            sessions.release(session, ok=ok)
+
+
+def claude_model(model: str) -> ClaudeModel:
+    from pcode.models import claude_sdk_installed
+
+    name = model.removeprefix(PREFIX)
+    if not name.strip():
+        raise ValueError("Claude requires a model ID: claude:<model-id>")
+    if not claude_sdk_installed():
+        raise ClaudeSDKMissing(MISSING_SDK)
+    return ClaudeModel(name, provider=ClaudeProvider())

pcode/claude_sdk/resume.py

@@ -0,0 +1,114 @@
+"""The persisted index of fork points that lets a restarted pcode resume warm."""
+
+import json
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+
+logger = logging.getLogger(__name__)
+
+INDEX_LIMIT = 4000
+
+
+@dataclass(frozen=True)
+class ForkPoint:
+    """Where one assistant message pcode received lives in a CLI transcript."""
+
+    session_id: str
+    uuid: str
+    cwd: str
+
+
+def index_path() -> Path:
+    state = Path(os.environ.get("XDG_STATE_HOME") or Path.home() / ".local" / "state")
+    return state / "pcode" / "claude-sessions.jsonl"
+
+
+class ResumeIndex:
+    """History hash -> fork point, persisted so a restarted pcode resumes warm.
+
+    Append-only lines shared by every pcode process; losing an entry only
+    costs a replay, so concurrent writers need no lock beyond `O_APPEND`.
+    """
+
+    def __init__(self, path: Path | None = None) -> None:
+        self.path = path
+        self._loaded: dict[str, ForkPoint] | None = None
+
+    def _file(self) -> Path:
+        return self.path or index_path()
+
+    @property
+    def _entries(self) -> dict[str, ForkPoint]:
+        # Read once per process, synchronously: at most INDEX_LIMIT short lines,
+        # and no await in between means no second reader can interleave.
+        if self._loaded is None:
+            self._loaded = self._load()
+        return self._loaded
+
+    def _load(self) -> dict[str, ForkPoint]:
+        entries: dict[str, ForkPoint] = {}
+        try:
+            lines = self._file().read_text().splitlines()
+        except OSError:
+            return entries
+        for line in lines:
+            try:
+                row = json.loads(line)
+                if row.get("dropped"):
+                    entries.pop(row["key"], None)
+                    continue
+                entries[row["key"]] = ForkPoint(row["session"], row["uuid"], row["cwd"])
+            except (ValueError, KeyError, TypeError, AttributeError):
+                continue
+        if len(lines) > INDEX_LIMIT:
+            kept = list(entries.items())[-INDEX_LIMIT // 2 :]
+            entries = dict(kept)
+            temporary = None
+            try:
+                with NamedTemporaryFile(
+                    "w", dir=self._file().parent, suffix=".tmp", delete=False
+                ) as file:
+                    temporary = Path(file.name)
+                    file.write("".join(self._line(k, p) for k, p in kept))
+                temporary.replace(self._file())
+            except OSError:
+                if temporary is not None:
+                    temporary.unlink(missing_ok=True)
+        return entries
+
+    @staticmethod
+    def _line(key: str, point: ForkPoint) -> str:
+        row = {"key": key, "session": point.session_id, "uuid": point.uuid, "cwd": point.cwd}
+        return json.dumps(row) + "\n"
+
+    def get(self, key: str) -> ForkPoint | None:
+        return self._entries.get(key)
+
+    def forget(self, session_id: str) -> None:
+        """Stop offering a transcript that could not be resumed, for this process."""
+        for key in [k for k, p in self._entries.items() if p.session_id == session_id]:
+            del self._entries[key]
+
+    def drop(self, keys: list[str]) -> None:
+        """Never fork these histories again, in any pcode process."""
+        dropped = [key for key in keys if self._entries.pop(key, None) is not None]
+        self._append("".join(json.dumps({"key": key, "dropped": True}) + "\n" for key in dropped))
+
+    def add(self, key: str, point: ForkPoint) -> None:
+        if self._entries.get(key) == point:
+            return
+        self._entries[key] = point
+        self._append(self._line(key, point))
+
+    def _append(self, lines: str) -> None:
+        if not lines:
+            return
+        try:
+            self._file().parent.mkdir(parents=True, exist_ok=True)
+            with self._file().open("a") as file:
+                file.write(lines)
+        except OSError:
+            logger.debug("could not update the Claude fork index", exc_info=True)