pcode 0.1.0__py3-none-any.whl

pcode/cache_diagnostics.py

@@ -0,0 +1,336 @@
+"""Name what moved the cacheable prefix when a cache collapse fires.
+
+A collapse warning reports only the provider's token verdict, which cannot say
+whether the prompt prefix was rewritten or the cache simply expired. This keeps a
+small rolling fingerprint of each model request so the next collapse answers that
+question partially: unchanged fingerprints leave the cause unknown, and a
+changed prefix names the message index that moved.
+
+Fingerprints are content-free by construction: digests, sizes and kinds only,
+never prompt text. Prompts carry file contents and command output, so writing them
+to a debug file would leak exactly what the rest of pcode refuses to log.
+"""
+
+import hashlib
+import json
+import os
+import time
+from collections import deque
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from pydantic_ai.messages import CachePoint
+
+from pcode.diagnostics import versions
+
+HISTORY = 8
+"""Requests retained per run. A collapse is diagnosed from the preceding request,
+so this only needs enough depth to show the trend that led into it."""
+
+CACHE_SETTINGS = (
+    "anthropic_cache",
+    "anthropic_cache_instructions",
+    "anthropic_cache_tool_definitions",
+)
+
+
+def diagnostics_root() -> Path:
+    """`PCODE_CACHE_DIAGNOSTICS` overrides the directory; `off` disables dumps."""
+    override = os.environ.get("PCODE_CACHE_DIAGNOSTICS", "").strip()
+    if override and override.lower() != "off":
+        return Path(override).expanduser()
+    state = Path(os.environ.get("XDG_STATE_HOME") or Path.home() / ".local" / "state")
+    return state / "pcode" / "cache-diagnostics"
+
+
+def enabled() -> bool:
+    return os.environ.get("PCODE_CACHE_DIAGNOSTICS", "").strip().lower() != "off"
+
+
+def _digest(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8", "replace")).hexdigest()[:12]
+
+
+def _content_text(value) -> str:
+    """Render content for hashing, marking cache points so a moved one is visible."""
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, CachePoint):
+        return f"<cache-point:{value.ttl}>"
+    if isinstance(value, (list, tuple)):
+        return "".join(_content_text(item) for item in value)
+    # Binary and multimodal parts have no stable text; size and type still detect
+    # a change without pulling the payload into the digest.
+    data = getattr(value, "data", None)
+    size = len(data) if isinstance(data, (bytes, bytearray)) else ""
+    return f"<{type(value).__name__}:{size}>"
+
+
+def _cache_points(value) -> int:
+    if isinstance(value, CachePoint):
+        return 1
+    if isinstance(value, (list, tuple)):
+        return sum(_cache_points(item) for item in value)
+    return 0
+
+
+def _part_text(part) -> str:
+    content = getattr(part, "content", None)
+    if content is None and hasattr(part, "args"):
+        # Tool calls carry their payload in `args`; `args_as_json_str` normalizes
+        # the dict/str union so an unchanged call hashes identically either way.
+        try:
+            content = part.args_as_json_str()
+        except Exception:
+            content = repr(part.args)
+    kind = getattr(part, "part_kind", type(part).__name__)
+    name = getattr(part, "tool_name", "") or ""
+    return f"{kind}|{name}|{_content_text(content)}"
+
+
+@dataclass(frozen=True)
+class MessageFingerprint:
+    kind: str
+    parts: tuple[str, ...]
+    chars: int
+    digest: str
+    cache_points: int
+
+    def moved(self, other: "MessageFingerprint") -> bool:
+        return self.kind != other.kind or self.digest != other.digest
+
+    def as_dict(self) -> dict:
+        return {
+            "kind": self.kind,
+            "parts": list(self.parts),
+            "chars": self.chars,
+            "digest": self.digest,
+            "cache_points": self.cache_points,
+        }
+
+
+def fingerprint_message(message) -> MessageFingerprint:
+    parts = tuple(getattr(part, "part_kind", type(part).__name__) for part in message.parts)
+    text = "\n".join(_part_text(part) for part in message.parts)
+    points = sum(_cache_points(getattr(part, "content", None)) for part in message.parts)
+    return MessageFingerprint(
+        kind=getattr(message, "kind", type(message).__name__),
+        parts=parts,
+        chars=len(text),
+        digest=_digest(text),
+        cache_points=points,
+    )
+
+
+@dataclass(frozen=True)
+class RequestFingerprint:
+    step: int
+    model: str
+    at: float
+    instructions: str
+    instruction_chars: int
+    tools: str
+    tool_names: tuple[str, ...]
+    settings: dict
+    messages: tuple[MessageFingerprint, ...]
+    cache_read: int
+    cache_write: int
+    input_tokens: int
+
+    @property
+    def cache_point_indexes(self) -> list[int]:
+        return [i for i, message in enumerate(self.messages) if message.cache_points]
+
+    def as_dict(self) -> dict:
+        return {
+            "step": self.step,
+            "model": self.model,
+            "at": self.at,
+            "instructions": self.instructions,
+            "instruction_chars": self.instruction_chars,
+            "tools": self.tools,
+            "tool_names": list(self.tool_names),
+            "settings": self.settings,
+            "cache_read": self.cache_read,
+            "cache_write": self.cache_write,
+            "input_tokens": self.input_tokens,
+            "cache_point_indexes": self.cache_point_indexes,
+            "messages": [message.as_dict() for message in self.messages],
+        }
+
+
+def _sent_tools(request_context) -> list[tuple[Any, str]]:
+    """Each tool whose definition the request carries, with how the provider sends it.
+
+    A deferred tool stays in `function_tools` whether or not tool search has revealed
+    it, so the list alone cannot see a reveal. Whether a reveal moves the prefix is the
+    provider's call: one that withholds hidden schemas (`claude:`) adds the definition
+    ahead of every cached message, while native deferral keeps sending it as deferred.
+    The model's own `prepare_request` resolves that, exactly as the request did.
+    """
+    parameters = request_context.model_request_parameters
+    model = getattr(request_context, "model", None)
+    if getattr(parameters, "tool_visibility", None) is None and model is not None:
+        try:
+            _, parameters = model.prepare_request(request_context.model_settings, parameters)
+        except Exception:
+            parameters = request_context.model_request_parameters
+    visibility_of = getattr(parameters, "visibility_of", None)
+    sent = []
+    for tool in [
+        *(getattr(parameters, "function_tools", None) or []),
+        *(getattr(parameters, "output_tools", None) or []),
+    ]:
+        visibility = visibility_of(tool.name) if visibility_of is not None else "visible"
+        if visibility in ("visible", "deferred"):
+            sent.append((tool, visibility))
+    return sent
+
+
+def fingerprint(request_context, response, step: int) -> RequestFingerprint:
+    parameters = request_context.model_request_parameters
+    instruction_text = "\n".join(
+        _content_text(getattr(part, "content", None))
+        for part in (getattr(parameters, "instruction_parts", None) or [])
+    )
+    sent = _sent_tools(request_context)
+    tools = [tool for tool, _ in sent]
+    # Definitions reach the provider in list order: a reordered toolset invalidates
+    # the cached block just as an edited schema does, so order stays in the digest.
+    tool_text = "\n".join(
+        f"{tool.name}|{visibility}|{tool.description or ''}|"
+        f"{json.dumps(tool.parameters_json_schema, sort_keys=True, default=str)}"
+        for tool, visibility in sent
+    )
+    settings = request_context.model_settings or {}
+    usage = response.usage
+    return RequestFingerprint(
+        step=step,
+        model="/".join(part for part in (response.provider_name, response.model_name) if part),
+        at=time.time(),
+        instructions=_digest(instruction_text),
+        instruction_chars=len(instruction_text),
+        tools=_digest(tool_text),
+        tool_names=tuple(tool.name for tool in tools),
+        settings={key: settings[key] for key in CACHE_SETTINGS if key in settings},
+        messages=tuple(fingerprint_message(message) for message in request_context.messages),
+        cache_read=usage.cache_read_tokens,
+        cache_write=usage.cache_write_tokens,
+        input_tokens=usage.input_tokens,
+    )
+
+
+def divergence(previous: RequestFingerprint, current: RequestFingerprint) -> str:
+    """Describe the first prefix change, or report the prefix as intact.
+
+    Order matters: instructions and tool definitions sit ahead of every message, so
+    a change there explains a collapse that a message-level diff would misattribute.
+
+    Read this line and the dumped fingerprints before theorizing about Harness's
+    own warning text. Its generic suffix ``(e.g. a gap longer than the cache TTL)``
+    means the gap was *under* the TTL: Harness names the measured gap when it
+    actually exceeds it. Its ``model request N`` is per-run, not per-session.
+    """
+    if previous.instructions != current.instructions:
+        return (
+            "Instructions changed "
+            f"({previous.instruction_chars} -> {current.instruction_chars} chars): "
+            "request prefix differs."
+        )
+    if previous.tools != current.tools:
+        added = [name for name in current.tool_names if name not in previous.tool_names]
+        removed = [name for name in previous.tool_names if name not in current.tool_names]
+        detail = ", ".join(
+            part
+            for part in (
+                f"added {', '.join(added)}" if added else "",
+                f"removed {', '.join(removed)}" if removed else "",
+            )
+            if part
+        )
+        return "Tool definitions changed" + (
+            f" ({detail})." if detail else " (same names, edited schema or order)."
+        )
+    if previous.settings != current.settings:
+        return f"Cache settings changed ({previous.settings} -> {current.settings})."
+    shared = min(len(previous.messages), len(current.messages))
+    for index in range(shared):
+        before, after = previous.messages[index], current.messages[index]
+        if before.moved(after):
+            return (
+                f"Message {index} of {len(previous.messages)} changed "
+                f"(kind {before.kind} -> {after.kind}, {before.chars} -> {after.chars} chars, "
+                f"cache points {before.cache_points} -> {after.cache_points}). "
+                f"{len(previous.messages) - index} prior message(s) from that index."
+            )
+    if len(current.messages) < len(previous.messages):
+        return (
+            f"History shrank from {len(previous.messages)} to {len(current.messages)} "
+            "messages: the tail was dropped or rewritten by a capability."
+        )
+    appended = len(current.messages) - len(previous.messages)
+    points = (
+        f" Cache points moved {previous.cache_point_indexes} -> {current.cache_point_indexes}."
+        if previous.cache_point_indexes != current.cache_point_indexes
+        else ""
+    )
+    gap = current.at - previous.at
+    return (
+        f"Request fingerprints unchanged; {appended} messages appended (~{gap:.0f}s gap), "
+        f"cause unknown.{points}"
+    )
+
+
+@dataclass
+class CacheDiagnostics:
+    """Per-run rolling fingerprints, written out only when a collapse fires."""
+
+    records: deque = field(default_factory=lambda: deque(maxlen=HISTORY))
+    step: int = 0
+
+    def record(self, request_context, response) -> RequestFingerprint:
+        # Count separately from the window: the deque is bounded, so its length
+        # stops growing and would repeat step numbers for exactly the long runs
+        # a collapse is most likely to show up in.
+        self.step += 1
+        current = fingerprint(request_context, response, step=self.step)
+        self.records.append(current)
+        return current
+
+    def summary(self) -> str:
+        if len(self.records) < 2:
+            return ""
+        return divergence(self.records[-2], self.records[-1])
+
+    def dump(self) -> Path | None:
+        """Write the rolling window; return the path, or None when unavailable."""
+        if not enabled() or not self.records:
+            return None
+        current = self.records[-1]
+        root = diagnostics_root()
+        stamp = time.strftime("%Y%m%dT%H%M%S", time.gmtime(current.at))
+        # Two runs in one process can collapse in the same second at the same step,
+        # so the obvious name is not unique. Overwriting would discard the only
+        # record of the earlier collapse.
+        base = f"{stamp}-{os.getpid()}-step{current.step}"
+        path = root / f"{base}.json"
+        for attempt in range(1, 100):
+            if not path.exists():
+                break
+            path = root / f"{base}-{attempt}.json"
+        payload = {
+            "versions": versions(),
+            "model": current.model,
+            "summary": self.summary(),
+            "requests": [record.as_dict() for record in self.records],
+        }
+        try:
+            root.mkdir(parents=True, exist_ok=True)
+            path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+        except OSError:
+            # A diagnostic must never take down the run that produced it.
+            return None
+        return path

pcode/cache_settings.py

@@ -0,0 +1,58 @@
+"""Prompt-cache settings that follow a run, including delegated ones.
+
+`agent.model_settings` covers the main agent only. A sub-agent inherits the
+parent's *model object* but is run with `model_settings=None`
+(`subagents/_toolset.py`), and cache settings live on the agent, not the model,
+so a delegated run would otherwise request no caching at all. Applying them per
+request also tracks a model switch without rebuilding the sub-agent.
+"""
+
+from dataclasses import replace
+from typing import Any
+
+from pydantic_ai import RunContext
+from pydantic_ai.capabilities import AbstractCapability
+from pydantic_ai.models import ModelRequestContext
+
+# Pydantic AI 2.45.0 adds no `cache_control` of its own: without these settings an
+# Anthropic conversation re-reads its whole prefix at full price every request
+# (confirmed against captured request bodies and saved-session usage records).
+# `anthropic_cache` is the server-side automatic breakpoint, which moves forward as
+# history grows; the two explicit breakpoints keep instructions and tool definitions
+# cached. Meridian is excluded on purpose: its passthrough proxy strips client
+# `cache_control` and drives caching from its own lineage hash.
+ANTHROPIC_CACHE_SETTINGS = {
+    "anthropic_cache": "5m",
+    "anthropic_cache_instructions": True,
+    "anthropic_cache_tool_definitions": True,
+}
+
+
+def model_settings(model: str) -> dict | None:
+    """Default settings for a model name, as `Agent(model_settings=...)` wants them."""
+    if model.startswith("openai-codex:"):
+        # Codex does not emit visible reasoning unless summaries are requested.
+        # Always receive them so Ctrl+T can reveal the preview mid-turn; the
+        # display preference remains local and never changes reasoning effort.
+        return {"openai_reasoning_summary": "detailed"}
+    if model.startswith("anthropic:"):
+        return dict(ANTHROPIC_CACHE_SETTINGS)
+    return None
+
+
+class ProviderCacheSettings(AbstractCapability):
+    """Request prompt caching on providers that need it asked for explicitly.
+
+    Settings already on the request win, so `/effort`, `/thinking` and an
+    explicit override are never overwritten.
+    """
+
+    async def before_model_request(
+        self, ctx: RunContext[Any], request_context: ModelRequestContext
+    ) -> ModelRequestContext:
+        if request_context.model.system != "anthropic":
+            return request_context
+        settings = request_context.model_settings or {}
+        if any(key in settings for key in ANTHROPIC_CACHE_SETTINGS):
+            return request_context
+        return replace(request_context, model_settings={**ANTHROPIC_CACHE_SETTINGS, **settings})

pcode/cache_warnings.py

@@ -0,0 +1,139 @@
+"""Report prompt-cache reuse drops, from Harness's detector.
+
+The full notice goes to the session journal for diagnosis; the terminal shows
+only a short footer label (`footer_label`), not a scrollback line.
+
+A drop is information, not a fault: /compact, a new tool, or an expired
+provider cache all shorten what the next request can reuse. The notice says
+how much was reused so the cost is visible; it never claims a cause.
+"""
+
+import re
+import warnings
+from dataclasses import dataclass, field
+
+from pydantic_ai import CapabilityEvent
+from pydantic_ai.messages import NativeToolCallPart
+from pydantic_ai_harness.warn_on_cache_busts import CacheBustWarning, WarnOnCacheBusts
+
+from pcode.cache_diagnostics import CacheDiagnostics
+from pcode.context_usage import compact_tokens
+from pcode.tool_display import command_text
+
+
+@dataclass(kw_only=True)
+class CacheBustEvent(CapabilityEvent, namespace="pcode_cache", name="bust"):
+    text: str
+
+
+def server_tool_iterations(response) -> int:
+    """Count server-side tool calls (web search, code execution) in a response.
+
+    Each one is an extra sampling pass inside a single API call, and the provider
+    reports one ``usage`` summed over every pass: ``cache_read_tokens`` is then
+    roughly ``passes * prefix``, not a prefix anyone can read back.
+    """
+    return sum(isinstance(part, NativeToolCallPart) for part in response.parts)
+
+
+def notice_text(step: int, read: int, established: int, model: str, *, earlier_turn: bool) -> str:
+    """One neutral line: what was reused, against what an earlier request cached."""
+    source = "tokens cached in an earlier turn" if earlier_turn else "previously cached tokens"
+    suffix = f" ({model})" if model else ""
+    return f"Prompt cache: request {step} reused {read:,} of ~{established:,} {source}{suffix}."
+
+
+_REUSE = re.compile(r"reused ([\d,]+) of ~([\d,]+)")
+
+
+def footer_label(text: str) -> str:
+    """The footer's short form of a notice, e.g. `cache miss 0/166k`.
+
+    The notice itself is kept whole in the session journal for diagnosis; the
+    footer only says a drop happened and how large it was.
+    """
+    found = _REUSE.search(text)
+    if found is None:
+        return "cache drop"
+    read, established = (int(value.replace(",", "")) for value in found.groups())
+    kind = "miss" if read == 0 else "drop"
+    label = f"cache {kind} {compact_tokens(read)}/{compact_tokens(established)}"
+    return f"sub-agent {label}" if text.startswith("Sub-agent:") else label
+
+
+@dataclass
+class CacheBustReporting(WarnOnCacheBusts):
+    """Keep Harness's detector, thresholds, latch, and warning filters.
+
+    Upstream keys its marks by `RunContext.conversation_id`, which pcode keeps
+    stable per session, so the first request of a turn is compared with what
+    the previous turn cached (until the conversation idles past the cache TTL).
+    A notice after /compact is therefore expected: it reports the reset.
+    """
+
+    # Write each notice's fingerprint window to disk (the `debug` setting).
+    dump_fingerprints: bool = False
+    # `for_run` copies the capability with `replace()`, which re-initializes
+    # `init=False` fields, so each run fingerprints its own requests -- matching
+    # the upstream detector's per-run step numbering.
+    diagnostics: CacheDiagnostics = field(
+        init=False, default_factory=CacheDiagnostics, compare=False, repr=False
+    )
+
+    async def after_model_request(self, ctx, *, request_context, response):
+        # Harness hooks are filters, not listeners: the return value replaces the
+        # response (or request context, for `before_model_request`). A hook that
+        # only records something must still return it, or the loss surfaces far
+        # away as `AttributeError: 'NoneType' object has no attribute 'usage'`
+        # from the upstream `WarnOnCacheBusts` this class extends.
+        #
+        # The pinned upstream hook does not suspend: only its synchronous warning
+        # emission is captured, never model/tool execution or another task's work.
+        # Emit outside this scope; ctx.emit can suspend. No global warning handler.
+        key = (response.provider_name, response.model_name)
+        prior = self._state.conversation.keys.get(key)
+        with warnings.catch_warnings(record=True) as caught:
+            result = await super().after_model_request(
+                ctx, request_context=request_context, response=response
+            )
+        if server_tool_iterations(response):
+            # Upstream raises its high-water mark to `read + write` of every
+            # response, but a summed multi-pass usage puts the mark several
+            # times above the real prefix, and the next healthy request then
+            # "collapses" against it (seen: 148k established from a 29k prefix
+            # after three web searches; the next request read exactly 47k).
+            # Keep the previous mark; the next single-pass response sets a real
+            # one from its own usage.
+            self._state.conversation.keys[key].prefix = prior.prefix if prior else 0
+        # Fingerprint every request, not just collapsing ones: diagnosing a
+        # collapse needs the healthy request before it to compare against.
+        # Part shapes vary by provider and capability, so a diagnostic that
+        # cannot read one must degrade to silence rather than end the run.
+        try:
+            self.diagnostics.record(request_context, response)
+        except Exception:
+            self.diagnostics.records.clear()
+        for warning in caught:
+            if issubclass(warning.category, CacheBustWarning):
+                # Report measured reuse, not upstream's speculative expiry cause
+                # or an inferred number of tokens billed uncached.
+                model = "/".join(
+                    part for part in (response.provider_name, response.model_name) if part
+                )
+                text = notice_text(
+                    self._state.step,
+                    response.usage.cache_read_tokens,
+                    prior.prefix if prior else 0,
+                    model,
+                    earlier_turn=prior is not None and prior.run_id != ctx.run_id,
+                )
+                text = "\n".join(part for part in (text, self.diagnostics.summary()) if part)
+                path = self.diagnostics.dump() if self.dump_fingerprints else None
+                if path is not None:
+                    text += f"\nRequest fingerprints: {path}"
+                await ctx.emit(CacheBustEvent(text=command_text(text)))
+            else:
+                warnings.warn_explicit(
+                    warning.message, warning.category, warning.filename, warning.lineno
+                )
+        return result

pcode/claude_sdk/__init__.py

@@ -0,0 +1,96 @@
+"""`claude:` models: Claude Code's own login through the Claude Agent SDK, no proxy.
+
+`ClaudeModel` (in `model`) is an `AnthropicModel` whose requests never touch
+its HTTP client. Each conversation keeps one `claude` CLI process (the one
+bundled with `claude-agent-sdk`) alive across requests, where Meridian starts a
+fresh one per request behind a Node proxy. pcode's tools are served to that
+process as an in-process MCP server whose handlers *park*: the model calls a
+tool, the CLI invokes the handler, the streamed assistant message ends, and
+Pydantic AI runs the tool itself. The next request carries the result, which
+releases the parked handler, and the CLI goes on to its next API call. The CLI
+streams raw Anthropic events, so parsing reuses `AnthropicModel`'s
+streamed-response code. `session` holds one such process (`ClaudeSession`);
+`cli` the binary and environment it runs with.
+
+pcode's history stays the source of truth; the CLI transcript is a disposable
+copy. `messages` normalizes and hashes that history so it can be compared. A
+request continues a live process only when that process holds exactly the
+history before the new user message. Otherwise it forks the CLI transcript at
+the last assistant message both share (`resume` + `fork_session` +
+`resume_session_at`: structured history, warm cache), found through a persisted
+index of history hashes (`resume`), and failing that starts over with the
+history replayed as text, as Meridian does. `session_pool` makes that choice
+and keeps idle processes within limits. See dev/anthropic-providers.md.
+
+`ClaudeWorkspace` (in `workspace`) points each request's CLI at the agent's
+workspace, and `errors` holds the failures and what to tell the user about
+them. pcode holds no credentials here: the CLI signs in itself (`/login claude`).
+
+Tests patch the submodule that defines a name (`pcode.claude_sdk.session_pool`),
+never this package: a re-export is a copy, so patching it changes nothing the
+submodules read. Tuning knobs and pool state are left out of the re-exports for
+that reason.
+"""
+
+from pcode.claude_sdk.cli import CLI_ENV, LOGIN_ENV, cli_path
+from pcode.claude_sdk.errors import (
+    MISSING_SDK,
+    ClaudeConnectionError,
+    ClaudeHTTPError,
+    ClaudeProcessError,
+    ClaudeSDKMissing,
+    ClaudeStartError,
+    failure_hint,
+)
+from pcode.claude_sdk.messages import REPLAY_INTRO, lineage, normalize, replay
+from pcode.claude_sdk.model import PREFIX, ClaudeModel, ClaudeProvider, claude_model
+from pcode.claude_sdk.resume import ForkPoint, ResumeIndex, index_path
+from pcode.claude_sdk.session import (
+    SERVER,
+    TOOL_PREFIX,
+    TOOL_USE_ID,
+    ClaudeSession,
+    SessionConfig,
+)
+from pcode.claude_sdk.session_pool import (
+    Checkout,
+    SessionPool,
+    pool,
+    shutdown,
+)
+from pcode.claude_sdk.workspace import CWD_SETTING, ClaudeWorkspace
+
+__all__ = [
+    "CLI_ENV",
+    "CWD_SETTING",
+    "LOGIN_ENV",
+    "MISSING_SDK",
+    "PREFIX",
+    "REPLAY_INTRO",
+    "SERVER",
+    "TOOL_PREFIX",
+    "TOOL_USE_ID",
+    "Checkout",
+    "ClaudeConnectionError",
+    "ClaudeHTTPError",
+    "ClaudeModel",
+    "ClaudeProcessError",
+    "ClaudeProvider",
+    "ClaudeSDKMissing",
+    "ClaudeSession",
+    "ClaudeStartError",
+    "ClaudeWorkspace",
+    "ForkPoint",
+    "ResumeIndex",
+    "SessionConfig",
+    "SessionPool",
+    "claude_model",
+    "cli_path",
+    "failure_hint",
+    "index_path",
+    "lineage",
+    "normalize",
+    "pool",
+    "replay",
+    "shutdown",
+]

pcode/claude_sdk/cli.py

@@ -0,0 +1,52 @@
+"""The `claude` CLI binary pcode runs, and the environment it runs with."""
+
+import sys
+from pathlib import Path
+
+# The child inherits pcode's environment. An empty value is unset to the CLI
+# (verified: requests then bill the subscription), so neither pcode's own
+# Anthropic key, token or endpoint nor a cloud route exported for other Claude
+# Code use can silently redirect or bill a `claude:` request.
+LOGIN_ENV = {
+    "ANTHROPIC_API_KEY": "",
+    "ANTHROPIC_AUTH_TOKEN": "",
+    "ANTHROPIC_BASE_URL": "",
+    "CLAUDE_CODE_USE_BEDROCK": "",
+    "CLAUDE_CODE_USE_VERTEX": "",
+    "CLAUDE_CODE_USE_FOUNDRY": "",
+    "CLAUDE_CODE_USE_GATEWAY": "",
+    "CLAUDE_CODE_USE_MANTLE": "",
+    "CLAUDE_CODE_USE_ANTHROPIC_AWS": "",
+    "CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD": "",
+}
+CLI_ENV = {
+    **LOGIN_ENV,
+    # pcode owns retries (visible in the UI), compaction and tool deferral. A
+    # transcript the CLI compacted itself would no longer match pcode's history.
+    "CLAUDE_CODE_MAX_RETRIES": "0",
+    "DISABLE_AUTO_COMPACT": "1",
+    "DISABLE_COMPACT": "1",
+    "ENABLE_TOOL_SEARCH": "false",
+    # pcode already bounds tool output; never let the CLI truncate it again.
+    "MAX_MCP_OUTPUT_TOKENS": "1000000",
+    # A subscription login defaults to 1-hour cache writes (2x input, against
+    # 1.25x). pcode's tool loops send requests well inside five minutes, so the
+    # hour rarely pays off (dev/anthropic-providers.md). This variable wins
+    # over ENABLE_PROMPT_CACHING_1H; only FORCE_PROMPT_CACHING_5M outranks it.
+    "CLAUDE_CODE_PROMPT_CACHE_TTL": "5m",
+    # A parked handler lasts as long as the tool runs, delegations included.
+    "MCP_TOOL_TIMEOUT": str(7 * 24 * 3600 * 1000),
+    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
+    "DISABLE_AUTOUPDATER": "1",
+}
+
+
+def cli_path() -> str | None:
+    """The CLI the SDK runs: its bundled binary, else `claude` on PATH."""
+    import shutil
+
+    import claude_agent_sdk
+
+    name = "claude.exe" if sys.platform == "win32" else "claude"
+    bundled = Path(claude_agent_sdk.__file__).parent / "_bundled" / name
+    return str(bundled) if bundled.is_file() else shutil.which("claude")