program-context-protocol 0.12.4__py3-none-any.whl

pcp/llm/harness/agy.py

@@ -0,0 +1,121 @@
+"""agy (Antigravity CLI / Google Gemini) harness.
+
+Split out of client.py 2026-07-31 -- see llm/harness/__init__.py's
+docstring for the shared contract. Added 2026-07-31 for Loop 3's
+cross-vendor architect-review verifier leg (proposed 2026-07-22, parked,
+resumed -- see memory `project-cross-vendor-verifier-deferred-2026-07-22`).
+Currently the ONLY caller is build.py's _verify_block_findings, scoped
+narrowly to CTRL-005/CTRL-006 -- this file itself doesn't enforce that
+scope, the caller does.
+
+Real usage data, corrected same day: `agy -p ... --output-format json`
+(not the bare text mode this file originally used) returns a genuine
+envelope with `conversation_id` (real session-resume support, verified
+live against `--conversation <id>`) and a `usage` block with
+input/output/thinking/cache_read/total token counts. There is still no
+`cost_usd` -- agy exposes no pricing -- so that field stays an honest
+None, not a fabricated number. But "agy has no usage data" was wrong; it
+just wasn't being asked for it. Real token counts now feed
+pcp.llm.ledger._log_usage like every other harness, and
+PCP_AGY_MAX_TOKENS_PER_CALL is a real circuit breaker on top of real
+numbers, not a guess.
+"""
+
+import json
+import os
+import subprocess
+from pathlib import Path
+
+from pcp.llm.ledger import _log_usage
+
+
+def _agy_bin() -> str:
+    return os.environ.get("PCP_AGY_BIN", "agy")
+
+
+def _agy_timeout() -> int:
+    return int(os.environ.get("PCP_AGY_TIMEOUT", "240"))
+
+
+def _agy_effort() -> str:
+    """Default "low" -- Loop 3's only caller today is a verifier check, not
+    a task that benefits from deep reasoning, and effort is real cost
+    control agy exposes (confirmed: --effort low measurably drops
+    thinking_tokens). PCP_AGY_EFFORT overrides for a caller that needs more."""
+    return os.environ.get("PCP_AGY_EFFORT", "low")
+
+
+def _agy_max_tokens_per_call() -> int:
+    """Per-call ceiling, same role --max-budget-usd plays for claude (a
+    live cap passed/checked per call, not a cumulative tracker) -- except
+    agy has no self-enforcing budget flag, so this is checked AFTER the
+    call returns, against real reported usage. Can't prevent the tokens
+    already spent on a call that blew past it, but does turn that call
+    into a raised, non-silent failure (fails the same way a timeout or
+    missing binary does) rather than a quietly-accepted result -- and
+    stops a caller from treating an oversized response as normal."""
+    return int(os.environ.get("PCP_AGY_MAX_TOKENS_PER_CALL", "200000"))
+
+
+def _call_agy(system: str, user: str, model: str | None = None, pcp_dir: Path | None = None,
+              command: str = "llm.call", return_meta: bool = False) -> str | tuple[str, dict]:
+    """Same contract as harness.claude._call_claude(). `model`, if given, is
+    passed through to agy's own `--model` flag. `--effort` is always passed
+    (see _agy_effort()) -- real cost control, not optional."""
+    prompt = f"{system}\n\n---\n\n{user}"
+    cwd = Path(pcp_dir).parent if pcp_dir else None
+    cmd = [
+        _agy_bin(), "-p", prompt, "--output-format", "json",
+        "--print-timeout", f"{_agy_timeout()}s", "--effort", _agy_effort(),
+    ]
+    if model:
+        cmd += ["--model", model]
+
+    try:
+        result = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=_agy_timeout() + 30, cwd=cwd,
+        )
+    except FileNotFoundError:
+        raise RuntimeError(
+            f"agy CLI not found at '{_agy_bin()}'. Install Antigravity CLI, or unset "
+            "PCP_LLM_HARNESS/PCP_VERIFIER_CROSS_VENDOR to skip it."
+        )
+    except subprocess.TimeoutExpired:
+        raise RuntimeError(f"agy CLI timed out after {_agy_timeout()}s")
+
+    if result.returncode != 0:
+        raise RuntimeError(f"agy CLI exited {result.returncode}: {result.stderr.strip()}")
+
+    try:
+        envelope = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        # Fallback: unexpected/older CLI output -- treat stdout as raw text,
+        # same posture harness.claude._call_claude() takes on the same failure.
+        text = result.stdout.strip()
+        return (text, {"model": model or "agy/default", "session_id": None, "usage": {}, "cost_usd": None, "duration_ms": None}) if return_meta else text
+
+    if envelope.get("status") and envelope.get("status") != "SUCCESS":
+        raise RuntimeError(f"agy CLI reported status={envelope.get('status')}: {envelope.get('response', '')}")
+
+    usage = envelope.get("usage", {}) or {}
+    total_tokens = usage.get("total_tokens", 0)
+    if total_tokens > _agy_max_tokens_per_call():
+        raise RuntimeError(
+            f"agy call used {total_tokens} tokens, over the {_agy_max_tokens_per_call()} "
+            "PCP_AGY_MAX_TOKENS_PER_CALL ceiling -- treated as a failed call, same as a "
+            "timeout, rather than silently accepted."
+        )
+
+    duration_ms = int(envelope.get("duration_seconds", 0) * 1000) if envelope.get("duration_seconds") else None
+    conversation_id = envelope.get("conversation_id")
+
+    _log_usage(pcp_dir, command, model or "agy/default", conversation_id, usage, None)
+
+    text = (envelope.get("response") or "").strip()
+    if not return_meta:
+        return text
+    meta = {
+        "model": model or "agy/default", "session_id": conversation_id,
+        "usage": usage, "cost_usd": None, "duration_ms": duration_ms,
+    }
+    return text, meta

pcp/llm/harness/agy_coding_loop.py

@@ -0,0 +1,180 @@
+"""Antigravity CLI (agy) coding-agent-loop harness -- implements
+CodingAgentHarness (llm/coding_agent_contract.py).
+
+Provenance: the first draft of this file was written BY agy itself
+(2026-08-01), given the contract and agy's own verified real CLI behavior
+as input -- the same reasoning applied to "let Codex verify its own
+contract instead of guessing" throughout the multi-harness conversation
+(tag `pre-multi-harness-extension`) applies to agy here too. Reviewed and
+lightly corrected before being accepted, same as any other AI-authored
+change in this codebase -- not applied blind.
+
+One correction from the original draft worth recording: it hardcoded
+`--effort low` for every call, copying that choice from harness/agy.py's
+verifier leg (a yes/no judgment call, where low effort is a deliberate,
+measured cost control) without noticing that actual code generation is a
+different kind of task -- forcing low reasoning effort on real coding work
+isn't a cost optimization there, it's a quality regression. Fixed to leave
+effort unset by default (agy's own default reasoning depth), configurable
+via PCP_AGY_CODING_EFFORT for a caller that wants to override it either
+direction.
+
+Honest limitations, stated rather than papered over:
+1. No pre-enforced budget ceiling. agy has no `--max-budget-usd`
+   equivalent -- request.max_budget_usd cannot be pre-enforced at the CLI
+   level, only checked after the fact against real reported tokens
+   (see PCP_AGY_MAX_TOKENS_PER_CALL below, default 500,000/call).
+2. cost_usd is always None. agy reports real token usage but no pricing
+   data -- never fabricated here.
+3. request.session_id (the caller-chosen id for a FRESH session) is
+   advisory only, not actually usable. Unlike Claude Code's
+   `--session-id <id>` (open a NEW session under a caller-picked name),
+   agy always self-assigns its own conversation_id on a fresh call --
+   there is no flag to open one under a name PCP picked. The REAL id
+   PCP must track going forward is whatever comes back in the result,
+   not what it requested. This is a genuine harness capability
+   difference (see the multi-harness conversation's "accept divergence
+   at the implementation layer" conclusion), not a bug to paper over.
+
+Not wired into `pcp build` -- Stage 3/4 of the multi-harness plan still
+require a deliberate decision to actually route criteria through this
+harness instead of Claude Code. This file existing does not change
+`pcp build`'s behavior.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import time
+from pathlib import Path
+
+from pcp.llm.coding_agent_contract import CodingAgentRequest, CodingAgentResult
+
+DEFAULT_MAX_TOKENS_PER_CALL = 500_000
+
+
+def _agy_coding_effort() -> str | None:
+    """None by default -- let agy use its own default reasoning depth for
+    real code-writing, unlike the verifier leg's deliberate --effort low.
+    PCP_AGY_CODING_EFFORT overrides either direction."""
+    return os.environ.get("PCP_AGY_CODING_EFFORT")
+
+
+def _agy_coding_max_tokens_per_call() -> int:
+    env_limit = os.environ.get("PCP_AGY_MAX_TOKENS_PER_CALL")
+    return int(env_limit) if env_limit else DEFAULT_MAX_TOKENS_PER_CALL
+
+
+class AgyCodingAgentHarness:
+    """Coding agent harness implementation wrapping the Antigravity `agy`
+    CLI. See module docstring for what's honestly not supported."""
+
+    def __init__(self, max_tokens_limit: int | None = None) -> None:
+        self.max_tokens_limit = max_tokens_limit if max_tokens_limit is not None else _agy_coding_max_tokens_per_call()
+
+    def run(self, request: CodingAgentRequest) -> CodingAgentResult:
+        """Run one coding-task attempt using the `agy` CLI in unattended
+        file-editing mode against request.cwd."""
+        cmd: list[str] = [
+            "agy", "-p", request.prompt,
+            "--output-format", "json",
+            "--print-timeout", f"{request.timeout_sec}s",
+            "--dangerously-skip-permissions",
+            "--mode", "accept-edits",
+            "--sandbox",
+            "--add-dir", str(request.cwd),
+        ]
+        effort = _agy_coding_effort()
+        if effort:
+            cmd += ["--effort", effort]
+
+        if request.resume_session_id:
+            cmd += ["--conversation", request.resume_session_id]
+        # No else branch: agy has no flag to open a fresh session under a
+        # caller-chosen id (see module docstring, limitation 3) -- a fresh
+        # call just starts a new conversation and self-assigns its own id.
+
+        if request.model:
+            cmd += ["--model", str(request.model)]
+
+        start_time = time.monotonic()
+
+        try:
+            res = subprocess.run(
+                cmd, cwd=request.cwd, capture_output=True, text=True, timeout=request.timeout_sec,
+            )
+            elapsed_ms = int((time.monotonic() - start_time) * 1000)
+        except subprocess.TimeoutExpired:
+            return CodingAgentResult(
+                ok=False, error=f"Execution timed out after {request.timeout_sec} seconds",
+                session_id=request.resume_session_id or request.session_id, model=request.model,
+                duration_ms=int((time.monotonic() - start_time) * 1000),
+            )
+        except FileNotFoundError:
+            return CodingAgentResult(
+                ok=False, error="Executable 'agy' CLI was not found in PATH",
+                session_id=request.resume_session_id or request.session_id, model=request.model,
+                duration_ms=int((time.monotonic() - start_time) * 1000),
+            )
+        except Exception as e:
+            return CodingAgentResult(
+                ok=False, error=f"Subprocess execution failed: {e}",
+                session_id=request.resume_session_id or request.session_id, model=request.model,
+                duration_ms=int((time.monotonic() - start_time) * 1000),
+            )
+
+        stdout = res.stdout.strip()
+        stderr = res.stderr.strip()
+
+        if not stdout:
+            err_msg = stderr or f"Process exited with code {res.returncode} and empty stdout"
+            return CodingAgentResult(
+                ok=False, error=err_msg,
+                session_id=request.resume_session_id or request.session_id, model=request.model,
+                duration_ms=elapsed_ms,
+            )
+
+        try:
+            payload = json.loads(stdout)
+        except json.JSONDecodeError:
+            err_msg = f"Failed to parse JSON response envelope from agy. Raw stdout: {stdout[:500]}"
+            if stderr:
+                err_msg += f" | stderr: {stderr[:500]}"
+            return CodingAgentResult(
+                ok=False, error=err_msg,
+                session_id=request.resume_session_id or request.session_id, model=request.model,
+                duration_ms=elapsed_ms,
+            )
+
+        # The REAL session id going forward -- never what was requested,
+        # see module docstring limitation 3.
+        session_id = payload.get("conversation_id") or request.resume_session_id or request.session_id
+        status = payload.get("status")
+        usage = payload.get("usage") or {}
+        duration_seconds = payload.get("duration_seconds")
+        duration_ms = int(duration_seconds * 1000) if duration_seconds is not None else elapsed_ms
+
+        if res.returncode != 0 or status != "SUCCESS":
+            err_msg = payload.get("error") or payload.get("response") or stderr or f"agy reported status={status} (exit code {res.returncode})"
+            return CodingAgentResult(
+                ok=False, error=str(err_msg), session_id=session_id, model=request.model,
+                usage=usage, cost_usd=None, duration_ms=duration_ms,
+            )
+
+        total_tokens = usage.get("total_tokens", 0)
+        if total_tokens > self.max_tokens_limit:
+            return CodingAgentResult(
+                ok=False,
+                error=(
+                    f"Token usage limit exceeded: call used {total_tokens} total tokens "
+                    f"(limit is {self.max_tokens_limit} tokens)"
+                ),
+                session_id=session_id, model=request.model, usage=usage, cost_usd=None, duration_ms=duration_ms,
+            )
+
+        return CodingAgentResult(
+            ok=True, error=None, session_id=session_id, model=request.model,
+            usage=usage, cost_usd=None, duration_ms=duration_ms,
+        )

pcp/llm/harness/claude.py

@@ -0,0 +1,241 @@
+"""Claude Code harness -- `claude -p` CLI subprocess. No API key required.
+
+Everything in this file is genuinely Claude-Code-specific: exact CLI flags,
+the --output-format json / --input-format stream-json envelope shapes,
+session_id/usage/cost field names. Split out of client.py 2026-07-31 so the
+common dispatch layer (client.py) and per-harness implementations (this
+file, agy.py) are physically separated, not just logically -- see
+llm/harness/__init__.py's docstring for the contract every file here must
+implement.
+"""
+
+import base64
+import json
+import os
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from pcp.llm.ledger import _log_usage
+
+_MEDIA_TYPES = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp"}
+
+
+def _claude_bin() -> str:
+    return os.environ.get("PCP_CLAUDE_BIN", "claude")
+
+
+def _timeout() -> int:
+    return int(os.environ.get("PCP_LLM_TIMEOUT", "300"))
+
+
+def _call_claude(system: str, user: str, model: str | None = None, pcp_dir: Path | None = None,
+                  command: str = "llm.call", return_meta: bool = False) -> str | tuple[str, dict]:
+    """Run prompt through claude CLI (one-shot, no session reuse). Returns text output.
+
+    model: explicit model for this call site (e.g. JUDGE_MODEL). PCP_MODEL env overrides
+    everything if set, so a human can force a model for debugging.
+    pcp_dir/command: if given, usage+cost is appended to .pcp/token_ledger.yaml.
+    return_meta: if True, returns (text, meta) where meta has model/session_id/usage/
+    cost_usd/duration_ms — for callers building richer per-event telemetry (see telemetry.py).
+    """
+    prompt = f"{system}\n\n---\n\n{user}"
+
+    resolved_model = os.environ.get("PCP_MODEL") or model
+    cmd = [_claude_bin(), "-p", "--output-format", "json"]
+    if resolved_model:
+        cmd += ["--model", resolved_model]
+
+    # Real bug, found 2026-07-08: this call never passed cwd, so it always
+    # ran in whatever the calling PROCESS's actual OS cwd happened to be --
+    # not necessarily the target project. Harmless when the CLI is invoked
+    # from the project root (the common case), actively wrong otherwise: a
+    # test process (or any caller) with a different cwd would silently run
+    # the agent against the wrong directory. pcp_dir is already passed by
+    # every call site for token-ledger logging, so it doubles as the correct
+    # anchor here — project_root = pcp_dir.parent.
+    cwd = Path(pcp_dir).parent if pcp_dir else None
+
+    try:
+        result = subprocess.run(
+            cmd,
+            input=prompt,
+            capture_output=True,
+            text=True,
+            timeout=_timeout(),
+            cwd=cwd,
+        )
+    except FileNotFoundError:
+        raise RuntimeError(
+            f"claude CLI not found at '{_claude_bin()}'. "
+            "Install Claude Code: https://claude.ai/download"
+        )
+    except subprocess.TimeoutExpired:
+        raise RuntimeError(f"claude CLI timed out after {_timeout()}s")
+
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"claude CLI exited {result.returncode}: {result.stderr.strip()}"
+        )
+
+    try:
+        envelope = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        # Fallback: older CLI or unexpected output — treat stdout as raw text.
+        text = result.stdout.strip()
+        return (text, {}) if return_meta else text
+
+    if envelope.get("is_error"):
+        raise RuntimeError(f"claude CLI returned an error: {envelope.get('result', '')}")
+
+    _log_usage(
+        pcp_dir, command, resolved_model, envelope.get("session_id"),
+        envelope.get("usage", {}), envelope.get("total_cost_usd"),
+    )
+
+    text = (envelope.get("result") or "").strip()
+    if not return_meta:
+        return text
+
+    meta = {
+        "model": resolved_model or "default",
+        "session_id": envelope.get("session_id"),
+        "usage": envelope.get("usage", {}),
+        "cost_usd": envelope.get("total_cost_usd"),
+        "duration_ms": envelope.get("duration_ms"),
+    }
+    return text, meta
+
+
+def call_with_images(system: str, user: str, image_paths: list[Path], model: str | None = None,
+                     pcp_dir: Path | None = None, command: str = "llm.call_with_images",
+                     return_meta: bool = False) -> str | tuple[str, dict]:
+    """Same contract as _call_claude(), but attaches one or more images as
+    inline multimodal content blocks. Plain text stdin (what _call_claude()
+    uses) has no image channel -- `claude -p` only accepts an image via
+    `--input-format stream-json` (a single JSON message with text + image
+    content blocks), which in turn requires `--output-format stream-json`
+    (confirmed by the CLI's own error: "requires --verbose" once stream-json
+    output is set). The final envelope is the last `type: "result"` line on
+    stdout -- same fields (result/session_id/usage/total_cost_usd) as
+    --output-format json.
+
+    Claude-Code-only, genuinely -- not part of the harness dispatch seam in
+    client.py (no agy equivalent exists). Enables VLM-based checks
+    (uat.check_visual_quality) that judge a rendered screenshot -- optionally
+    against a second reference image -- without requiring the coding agent
+    itself to have filesystem access to the image at judge-call time.
+    Verified live 2026-07-18: the model sometimes first attempts a Read tool
+    call on a hallucinated file path for an inline image before falling back
+    to inspecting it directly -- the explicit instruction below cuts that
+    wasted turn most of the time but not always; harmless either way, just
+    an extra attempt."""
+    content = [{
+        "type": "text",
+        "text": (
+            f"{system}\n\n---\n\n{user}\n\n"
+            f"{'The image is' if len(image_paths) == 1 else 'The images are'} attached "
+            "inline in this message's content as image blocks -- not files on disk. "
+            "Do not attempt to Read a file path for them; analyze the attached "
+            "image(s) directly."
+        ),
+    }]
+    for image_path in image_paths:
+        media_type = _MEDIA_TYPES.get(image_path.suffix.lower(), "image/png")
+        data = base64.b64encode(image_path.read_bytes()).decode()
+        content.append({"type": "image", "source": {"type": "base64", "media_type": media_type, "data": data}})
+    message = {"type": "user", "message": {"role": "user", "content": content}}
+
+    resolved_model = os.environ.get("PCP_MODEL") or model
+    cmd = [_claude_bin(), "-p", "--input-format", "stream-json", "--output-format", "stream-json", "--verbose"]
+    if resolved_model:
+        cmd += ["--model", resolved_model]
+    cwd = Path(pcp_dir).parent if pcp_dir else None
+
+    try:
+        result = subprocess.run(
+            cmd, input=json.dumps(message), capture_output=True, text=True,
+            timeout=_timeout(), cwd=cwd,
+        )
+    except FileNotFoundError:
+        raise RuntimeError(
+            f"claude CLI not found at '{_claude_bin()}'. "
+            "Install Claude Code: https://claude.ai/download"
+        )
+    except subprocess.TimeoutExpired:
+        raise RuntimeError(f"claude CLI timed out after {_timeout()}s")
+
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"claude CLI exited {result.returncode}: {result.stderr.strip()}"
+        )
+
+    envelope = None
+    for line in result.stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if obj.get("type") == "result":
+            envelope = obj
+    if envelope is None:
+        raise RuntimeError("claude CLI stream-json output had no result event")
+
+    if envelope.get("is_error"):
+        raise RuntimeError(f"claude CLI returned an error: {envelope.get('result', '')}")
+
+    _log_usage(
+        pcp_dir, command, resolved_model, envelope.get("session_id"),
+        envelope.get("usage", {}), envelope.get("total_cost_usd"),
+    )
+
+    text = (envelope.get("result") or "").strip()
+    if not return_meta:
+        return text
+
+    meta = {
+        "model": resolved_model or "default",
+        "session_id": envelope.get("session_id"),
+        "usage": envelope.get("usage", {}),
+        "cost_usd": envelope.get("total_cost_usd"),
+        "duration_ms": envelope.get("duration_ms"),
+    }
+    return text, meta
+
+
+def call_with_image(system: str, user: str, image_path: Path, model: str | None = None,
+                     pcp_dir: Path | None = None, command: str = "llm.call_with_image",
+                     return_meta: bool = False) -> str | tuple[str, dict]:
+    """Single-image convenience wrapper over call_with_images()."""
+    return call_with_images(
+        system, user, [image_path], model=model, pcp_dir=pcp_dir, command=command, return_meta=return_meta,
+    )
+
+
+def call_json_with_images(system: str, user: str, image_paths: list[Path], model: str | None = None,
+                           pcp_dir: Path | None = None, command: str = "llm.call_json_with_images",
+                           return_meta: bool = False) -> Any:
+    """call_with_images + JSON parsing, same contract as client.call_json()."""
+    out = call_with_images(
+        system, user + "\n\nRespond with valid JSON only. No markdown fences.",
+        image_paths, model=model, pcp_dir=pcp_dir, command=command, return_meta=return_meta,
+    )
+    text, meta = out if return_meta else (out, None)
+    text = text.strip()
+    if text.startswith("```"):
+        lines = text.split("\n")
+        text = "\n".join(lines[1:-1])
+    parsed = json.loads(text)
+    return (parsed, meta) if return_meta else parsed
+
+
+def call_json_with_image(system: str, user: str, image_path: Path, model: str | None = None,
+                          pcp_dir: Path | None = None, command: str = "llm.call_json_with_image",
+                          return_meta: bool = False) -> Any:
+    """Single-image convenience wrapper over call_json_with_images()."""
+    return call_json_with_images(
+        system, user, [image_path], model=model, pcp_dir=pcp_dir, command=command, return_meta=return_meta,
+    )

pcp/llm/ledger.py

@@ -0,0 +1,47 @@
+"""token_ledger.yaml — usage/cost logging shared by every harness.
+
+Split out of client.py 2026-07-31 (harness/common split, see llm/harness/
+package docstring) -- this is PCP's own ledger format, not a harness
+implementation detail, so it lives independent of both client.py's
+dispatch layer and any individual harness/*.py file to avoid a circular
+import between them (client.py -> harness.claude -> needs _log_usage ->
+would need client.py back, without this module in between).
+"""
+
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+# Guards token_ledger.yaml's read-modify-write -- gate checks in build.py's
+# per-criterion loop that make an LLM call (architect-review, gate,
+# design-justification) run concurrently with each other (2026-07-18,
+# Project O dogfood finding: gate stages were needlessly sequential).
+# Without this lock, two concurrent calls reading the same ledger snapshot
+# before either writes back would silently drop one call's usage record.
+_LEDGER_LOCK = threading.Lock()
+
+
+def _log_usage(pcp_dir: Path | None, command: str, model: str | None, session_id: str | None,
+               usage: dict, cost_usd: float | None) -> None:
+    if pcp_dir is None:
+        return
+    with _LEDGER_LOCK:
+        ledger_path = Path(pcp_dir) / "token_ledger.yaml"
+        entries = []
+        if ledger_path.exists():
+            data = yaml.safe_load(ledger_path.read_text()) or {}
+            entries = data.get("calls", [])
+        entries.append({
+            "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "command": command,
+            "model": model or "default",
+            "session_id": session_id,
+            "input_tokens": usage.get("input_tokens", 0),
+            "output_tokens": usage.get("output_tokens", 0),
+            "cache_read_tokens": usage.get("cache_read_input_tokens", 0),
+            "cache_creation_tokens": usage.get("cache_creation_input_tokens", 0),
+            "cost_usd": cost_usd,
+        })
+        ledger_path.write_text(yaml.dump({"calls": entries}, default_flow_style=False))