custos-code 0.0.1__py3-none-any.whl

custos_code/__init__.py

@@ -0,0 +1,6 @@
+"""Custos Code: check a coding agent's final report against the log of what it actually did.
+
+Read AGENTS.md before changing anything. Invariants live there. Every module below has a
+docstring saying what it owns and what it must never do.
+"""
+__version__ = "0.0.1"

custos_code/adapters/__init__.py

@@ -0,0 +1,194 @@
+"""Adapters turn a source (harness transcript, hook payload, vendor export) into LedgerEvents.
+
+Contract: every adapter is a function `parse(path_or_payload) -> tuple[Session, list[LedgerEvent], str | None]`
+returning the session, the chained events, and the final report text if present.
+Adapters must set flags.truncated / flags.piped / flags.sidechain honestly; downstream tiers rely on them.
+Golden tests live in tests/golden/<adapter>/ : real input in, expected JSONL out.
+
+`detect` picks the adapter from the file itself so `custos-code check <path>` needs no --agent flag.
+
+`request_and_plan` (docs/SCOPE.md §6.3, issue #58) is scope's other input besides the ledger it
+already gets: what was asked, and what the agent said it would do before doing it. It lives here,
+not in `scope.py`, so scope stays agent-agnostic -- it takes a request and a plan, never a
+harness-specific shape.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from typing import Protocol
+
+from ..models import EventKind, LedgerEvent, Session
+from . import claude_code, codex, copilot, devin, machine, otel
+
+Source = str
+
+
+class Adapter(Protocol):
+    def parse(self, path: str) -> tuple[Session, list[LedgerEvent], str | None]: ...
+
+
+ADAPTERS: dict[Source, Adapter] = {
+    "claude_code": claude_code,
+    "codex": codex,
+    "devin": devin,
+    "machine": machine,
+    "copilot": copilot,
+    "otel": otel,
+}
+
+_CODEX_TYPES = frozenset(
+    {
+        "session_meta",
+        "turn_context",
+        "response_item",
+        "event_msg",
+        "compacted",
+        "thread_rolled_back",
+    }
+)
+
+
+def _bundle_source(obj: dict[str, object]) -> Source | None:
+    """Class-R bundles and OTLP payloads are one JSON object; tell them apart by their keys."""
+    if "resourceSpans" in obj or "scopeSpans" in obj:
+        return "otel"
+    raw = obj.get("session")
+    session: dict[str, object] = raw if isinstance(raw, dict) else {}
+    keys = set(obj) | {f"session.{k}" for k in session}
+    # Copilot first: both bundles carry `pull_request` and a `session.session_id`, and only
+    # Copilot carries a workspace or an attached tool log. Devin's tell is structured_output.
+    if "pull_request" in keys and (keys & {"log", "session.workspace", "session.agent_log"}):
+        return "copilot"
+    if keys & {"session.structured_output", "structured_output"}:
+        return "devin"
+    if keys & {"session.session_id", "session_id", "pull_request", "pull_requests"}:
+        return "devin"
+    return None
+
+
+def _line_source(rec: dict[str, object]) -> Source | None:
+    if "sessionId" in rec or (rec.get("type") in ("assistant", "user") and "message" in rec):
+        return "claude_code"
+    if str(rec.get("type")) in _CODEX_TYPES:
+        return "codex"
+    if rec.get("recorder") in machine.RECORDER_NAMES:
+        return "machine"
+    if "traceId" in rec and "spanId" in rec:
+        return "otel"
+    return None
+
+
+def detect(path: str) -> Source:
+    """Name the adapter for a file, by its shape. Raises ValueError when nothing matches."""
+    with open(path, encoding="utf-8", errors="ignore") as fh:
+        text = fh.read()
+    if not text.strip():
+        raise ValueError(f"{path} is empty")
+    try:
+        whole = json.loads(text)
+    except json.JSONDecodeError:
+        whole = None
+    if isinstance(whole, dict):
+        name = _bundle_source(whole)
+        if name:
+            return name
+    for line in text.splitlines():
+        if not line.strip():
+            continue
+        try:
+            rec = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(rec, dict):
+            name = _line_source(rec)
+            if name:
+                return name
+    raise ValueError(f"cannot tell which agent wrote {path}; pass --agent")
+
+
+def parse(path: str, source: Source | None = None) -> tuple[Session, list[LedgerEvent], str | None]:
+    """Parse a transcript with the adapter named by `source`, or the one `detect` picks."""
+    name = source or detect(path)
+    adapter = ADAPTERS.get(name)
+    if adapter is None:
+        raise ValueError(f"unknown agent {name!r}; one of {', '.join(sorted(ADAPTERS))}")
+    return adapter.parse(path)
+
+
+def _first_user_text(ledger: Sequence[LedgerEvent]) -> str:
+    """The earliest non-sidechain USER event's text -- the literal ask, verbatim.
+
+    Claude Code, Codex, and Devin (when it has a chat transcript) all write these already; nothing
+    new has to be recorded (SCOPE.md §6.3's whole premise).
+    """
+    for event in ledger:
+        if event.kind is EventKind.USER and not event.flags.sidechain and event.output:
+            return event.output
+    return ""
+
+
+def _todo_plan(ledger: Sequence[LedgerEvent]) -> list[str]:
+    """Claude Code's `TodoWrite`: the most recent call's items, oldest first.
+
+    The latest call wins, not the first -- a plan is allowed to change, and the self-authored
+    contract SCOPE.md §3 describes is whatever the agent most recently committed to, not its first
+    draft.
+    """
+    latest: LedgerEvent | None = None
+    for event in ledger:
+        if event.kind is EventKind.CALL and event.tool == "TodoWrite" and not event.flags.sidechain:
+            latest = event
+    if latest is None:
+        return []
+    todos = (latest.input or {}).get("todos")
+    if not isinstance(todos, list):
+        return []
+    out = []
+    for item in todos:
+        if not isinstance(item, dict):
+            continue
+        text = item.get("content") or item.get("activeForm") or item.get("task")
+        if isinstance(text, str) and text.strip():
+            out.append(text.strip())
+    return out
+
+
+def _stated_plan_before_first_call(ledger: Sequence[LedgerEvent]) -> list[str]:
+    """Fallback plan: the last thing the agent said before it touched a tool.
+
+    A message written before any evidence exists is a commitment it cannot later revise -- the
+    same "log it has no write path to" property SCOPE.md §3 grounds the plan in. Applies to any
+    adapter whose ledger has TEXT/CALL events in the shared shape (Claude Code, Codex today).
+    """
+    first_call_seq = next(
+        (e.seq for e in ledger if e.kind is EventKind.CALL and not e.flags.sidechain), None
+    )
+    last_text = ""
+    for event in ledger:
+        if first_call_seq is not None and event.seq >= first_call_seq:
+            break
+        if event.kind is EventKind.TEXT and not event.flags.sidechain and event.output:
+            last_text = event.output
+    return [last_text] if last_text.strip() else []
+
+
+def request_and_plan(
+    session: Session, ledger: Sequence[LedgerEvent], report: str | None = None
+) -> tuple[str, list[str]]:
+    """The spec and the agent's self-authored plan, per docs/SCOPE.md §6.3.
+
+    Deliberately reads the ledger, not the harness: Claude Code and Codex both already write a
+    USER event for the request, so no per-agent branch is needed to find it. Class-R bundles
+    (Copilot, Devin without a chat transcript) have no live back-and-forth to draw either from --
+    there, the PR body (`report`, already the same text `custos-code check` extracts claims from)
+    doubles as the spec, exactly as SCOPE.md §6.3 says, and there is no separate plan to find.
+
+    A `TodoWrite` call is the strongest plan signal where one exists; otherwise the last thing said
+    before the first tool call stands in for it (still empty for a class-R bundle, which has no
+    "before the first call" boundary to speak of).
+    """
+    request = _first_user_text(ledger) or (report or "")
+    plan = _todo_plan(ledger) or _stated_plan_before_first_call(ledger)
+    return request, plan

custos_code/adapters/claude_code.py

@@ -0,0 +1,266 @@
+"""Claude Code session JSONL -> ledger (class F, post-hoc). See docs/ADAPTERS.md §2.
+
+Observed on the transcripts on this machine (299 sessions surveyed):
+- records of interest have `type` in {assistant, user} and `message.content` as a list of blocks;
+  every such record carries `timestamp`, `sessionId`, `cwd`, `gitBranch`, `uuid`, `parentUuid`,
+  `version`, and `isSidechain`.
+- assistant blocks: `text`, `thinking`, `tool_use{id, name, input}`.
+- user blocks: `tool_result{tool_use_id, content, is_error}`; the record also carries `toolUseResult`:
+    Bash  -> {stdout, stderr, interrupted, isImage, noOutputExpected[, gitOperation]}   (no exit code)
+    Edit  -> {filePath, oldString, newString, replaceAll, originalFile, structuredPatch}
+    Write -> {filePath, content, originalFile, structuredPatch, type, userModified}
+    Read  -> {file{filePath, ...}, type}
+- the report for a turn is the last assistant `text` block before the next human user message;
+  the session report is the last one in the file.
+
+Owner: Oliver.
+"""
+from __future__ import annotations
+
+import glob
+import hashlib
+import json
+import os
+import re
+from datetime import datetime
+from typing import Any
+
+from .. import parsers
+from ..ledger import MAX_OUTPUT_BYTES, chain, redact
+from ..models import EventFlags, EventKind, LedgerEvent, Session
+
+# Pipe detection lives in `parsers.is_piped`, which every other adapter already used. The copy
+# that lived here missed `> file` and `>> file`, so `pytest -q > results.txt` was recorded
+# unfiltered and `rules._outcome` CONFIRMED the claim on exit status alone -- a run whose whole
+# output went to a file and was never parsed. This adapter and the live hook were the only two
+# users of the weaker list, which is the worst pair to have it in.
+_PATH_RE = re.compile(r"(?<![\w-])((?:\.{0,2}/)?[\w.-]+(?:/[\w.-]+)+\.[A-Za-z0-9]{1,8})")
+
+
+def _ts(rec: dict[str, Any]) -> datetime:
+    raw = rec.get("timestamp")
+    if isinstance(raw, str):
+        try:
+            return datetime.fromisoformat(raw.replace("Z", "+00:00"))
+        except ValueError:
+            pass
+    return datetime.fromtimestamp(0)
+
+
+def _paths_from_input(tool: str, inp: dict[str, Any], cwd: str | None) -> list[str]:
+    out: list[str] = []
+    for key in ("file_path", "path", "notebook_path"):
+        v = inp.get(key)
+        if isinstance(v, str) and v:
+            out.append(v)
+    if tool == "Bash":
+        cmd = inp.get("command")
+        if isinstance(cmd, str):
+            out.extend(m.group(1) for m in _PATH_RE.finditer(cmd))
+    seen: set[str] = set()
+    res: list[str] = []
+    for p in out:
+        q = p if os.path.isabs(p) or not cwd else os.path.normpath(os.path.join(cwd, p))
+        if q not in seen:
+            seen.add(q)
+            res.append(q)
+    return res
+
+
+def _result_text(block: dict[str, Any], tur: Any) -> str:
+    if isinstance(tur, dict):
+        so, se = tur.get("stdout"), tur.get("stderr")
+        if isinstance(so, str) or isinstance(se, str):
+            return (so or "") + (("\n" + se) if se else "")
+        if isinstance(tur.get("content"), str):
+            return str(tur["content"])
+    c = block.get("content")
+    if isinstance(c, str):
+        return c
+    if isinstance(c, list):
+        return "\n".join(str(x.get("text", "")) for x in c if isinstance(x, dict))
+    return ""
+
+
+_EXIT_RE = re.compile(r"\AExit code (\d+)\b")
+
+
+def _exit_code_from(block: dict[str, Any], text: str) -> int | None:
+    """The exit status, only when the transcript states it.
+
+    Claude Code does not record an exit code field -- but a failing Bash result is delivered as
+    `is_error` with content that begins `Exit code 1`, and 1055 results in a 40-session sample
+    carry it. The adapter hardcoded None, which left `review._corroborate` with one of its three
+    grounding paths dead by construction: no cited event could ever show a non-zero exit, so that
+    branch never fired on this adapter.
+
+    A success is NOT inferred. `is_error` being absent is the harness saying it did not flag the
+    call, which is not the same as the process returning 0, and this project does not get to
+    promote an absence into a witnessed fact -- that is the move it marks `unwitnessed`.
+    """
+    if not block.get("is_error"):
+        return None
+    m = _EXIT_RE.match(text.lstrip())
+    return int(m.group(1)) if m else None
+
+
+def _patch_text(tur: Any) -> str:
+    """The lines an Edit/Write changed, from `structuredPatch`.
+
+    Without this the judge sees `The file ... has been updated successfully.` and nothing else, so
+    every claim about *what* an edit said is unverifiable by construction -- 1369 Edit calls across
+    29 of 96 real sessions. The patch is already in the transcript; we were discarding it.
+
+    Redacted like any other recorded content, because a diff carries file contents.
+    """
+    if not isinstance(tur, dict):
+        return ""
+    hunks = tur.get("structuredPatch")
+    if not isinstance(hunks, list) or not hunks:
+        return ""
+    out: list[str] = []
+    for h in hunks:
+        if not isinstance(h, dict):
+            continue
+        out.append(f"@@ -{h.get('oldStart')},{h.get('oldLines')} +{h.get('newStart')},{h.get('newLines')} @@")
+        out += [str(ln) for ln in h.get("lines", []) if isinstance(ln, str)]
+    return redact("\n".join(out)) if out else ""
+
+
+def _flags_from_result(tool: str | None, inp: dict[str, Any] | None, block: dict[str, Any], tur: Any, sidechain: bool) -> EventFlags:
+    f = EventFlags(sidechain=sidechain)
+    if bool(block.get("is_error")):
+        f.error = True
+    if isinstance(tur, dict) and bool(tur.get("interrupted")):
+        f.interrupted = True
+    if tool == "Bash" and inp and isinstance(inp.get("command"), str) and parsers.is_piped(inp["command"]):
+        f.piped = True
+    return f
+
+
+def parse(path: str) -> tuple[Session, list[LedgerEvent], str | None]:
+    """Parse one Claude Code transcript into a chained ledger.
+
+    Returns the session, all events (main chain and sidechains, flagged), and the session's final
+    report text (last assistant text block on the main chain), or None if there is none.
+    """
+    calls: dict[str, tuple[str, dict[str, Any]]] = {}
+    events: list[LedgerEvent] = []
+    session_id = ""
+    cwd: str | None = None
+    branch: str | None = None
+    started: datetime | None = None
+    ended: datetime | None = None
+    report: str | None = None
+    seq = 0
+
+    with open(path, encoding="utf-8", errors="ignore") as fh:
+        for line in fh:
+            try:
+                rec = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if rec.get("type") not in ("assistant", "user"):
+                continue
+            msg = rec.get("message") or {}
+            content = msg.get("content")
+            if not isinstance(content, list):
+                continue
+            session_id = session_id or str(rec.get("sessionId", ""))
+            cwd = cwd or rec.get("cwd")
+            branch = branch or rec.get("gitBranch")
+            ts = _ts(rec)
+            started = started or ts
+            ended = ts
+            sidechain = bool(rec.get("isSidechain"))
+            rec_cwd = rec.get("cwd") if isinstance(rec.get("cwd"), str) else cwd
+
+            for block in content:
+                if not isinstance(block, dict):
+                    continue
+                kind = block.get("type")
+                if rec["type"] == "assistant" and kind == "tool_use":
+                    tool = str(block.get("name", ""))
+                    raw_inp = block.get("input")
+                    inp: dict[str, Any] = dict(raw_inp) if isinstance(raw_inp, dict) else {}
+                    calls[str(block.get("id"))] = (tool, inp)
+                    events.append(LedgerEvent(
+                        seq=seq, ts=ts, session_id=session_id, kind=EventKind.CALL, tool=tool,
+                        input=redact(inp), paths=_paths_from_input(tool, inp, rec_cwd), cwd=rec_cwd,
+                        flags=EventFlags(sidechain=sidechain),
+                    ))
+                    seq += 1
+                elif rec["type"] == "user" and kind == "tool_result":
+                    call = calls.get(str(block.get("tool_use_id")))
+                    rtool: str | None = call[0] if call else None
+                    rinp: dict[str, Any] = call[1] if call else {}
+                    tur = rec.get("toolUseResult")
+                    full = _result_text(block, tur)
+                    full = redact(full)
+                    flags = _flags_from_result(rtool, rinp, block, tur, sidechain)
+                    paths: list[str] = []
+                    if isinstance(tur, dict):
+                        fp: object = tur.get("filePath")
+                        if fp is None and isinstance(tur.get("file"), dict):
+                            fp = tur["file"].get("filePath")
+                        if isinstance(fp, str):
+                            paths.append(fp)
+                    if (patch := _patch_text(tur)):
+                        full = f"{full}\n{patch}" if full.strip() else patch
+                    if len(full.encode()) > MAX_OUTPUT_BYTES:
+                        flags.truncated = True
+                    events.append(LedgerEvent(
+                        seq=seq, ts=ts, session_id=session_id, kind=EventKind.RESULT, tool=rtool,
+                        output=full.encode()[:MAX_OUTPUT_BYTES].decode(errors="ignore"),
+                        output_hash=hashlib.sha256(full.encode()).hexdigest(),
+                        exit_code=_exit_code_from(block, full), paths=paths, cwd=rec_cwd, flags=flags,
+                    ))
+                    seq += 1
+                elif rec["type"] == "assistant" and kind == "text":
+                    text = str(block.get("text", ""))
+                    if not text.strip():
+                        continue
+                    events.append(LedgerEvent(
+                        seq=seq, ts=ts, session_id=session_id, kind=EventKind.TEXT, tool=None,
+                        output=redact(text), cwd=rec_cwd, flags=EventFlags(sidechain=sidechain),
+                    ))
+                    seq += 1
+                    if not sidechain:
+                        report = text
+                elif rec["type"] == "user" and kind == "text":
+                    events.append(LedgerEvent(
+                        seq=seq, ts=ts, session_id=session_id, kind=EventKind.USER, tool=None,
+                        output=redact(str(block.get("text", "")))[:MAX_OUTPUT_BYTES], cwd=rec_cwd,
+                        flags=EventFlags(sidechain=sidechain),
+                    ))
+                    seq += 1
+
+    events = chain(events)
+    session = Session(
+        id=session_id or os.path.basename(path).removesuffix(".jsonl"), source="claude_code",
+        agent="claude-code", started=started, ended=ended, cwd=cwd, git_branch=branch,
+        n_events=len(events), ledger_root_hash=events[-1].hash if events else "",
+    )
+    return session, events, report
+
+
+def find_last_session(projects_dir: str | None = None) -> str:
+    """Most recently modified transcript under ~/.claude/projects (for `custos-code check --last`)."""
+    root = projects_dir or os.path.expanduser("~/.claude/projects")
+    files = glob.glob(os.path.join(root, "*", "*.jsonl"))
+    if not files:
+        raise FileNotFoundError(f"no Claude Code transcripts under {root}")
+    return max(files, key=os.path.getmtime)
+
+
+def find_sessions(projects_dir: str | None = None, limit: int | None = None) -> list[str]:
+    """Local transcripts, newest first. Powers `custos-code scan`.
+
+    The point of scanning real history rather than a fixture: a staged trap is only caught when the
+    agent takes the bait, and a careful agent simply does not. Real sessions contain the failures
+    that actually happen -- a sample reported as a total, a remembered test count, a "verified
+    working" that skipped the one command that failed.
+    """
+    root = projects_dir or os.path.expanduser("~/.claude/projects")
+    files = sorted(glob.glob(os.path.join(root, "*", "*.jsonl")), key=os.path.getmtime, reverse=True)
+    return files[:limit] if limit else files