tycho-cli 0.0.1__py3-none-any.whl

tycho/harness.py

@@ -0,0 +1,303 @@
+"""Per-harness adapters for the Stop hook.
+
+The engine is harness-agnostic — it runs on a normalized ``Session``. Only three
+things differ between harnesses, and all three are documented and stable:
+
+1. where the transcript lives (a ``transcript_path`` in the Stop payload),
+2. the repo root in that payload (``cwd`` vs ``workspace_roots``),
+3. the JSON shape that surfaces a message to the human *without* blocking.
+
+Each harness hands us a ``transcript_path`` to JSONL, but the schemas differ.
+The adapter selects the matching pinned parser and output channel.
+"""
+
+from __future__ import annotations
+
+import os
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import events
+from . import opencode as opencode_mod
+
+
+@dataclass(frozen=True)
+class Harness:
+    """How one harness reads its transcript, names the repo root, and formats output."""
+
+    name: str
+    parse: Callable[[Path], tuple]
+    repo_root: Callable[[dict], Path]
+    format_output: Callable[[str], dict]
+    discover: Callable[[Path], Path | None]  # newest transcript for a repo, or None
+    # Materialize the transcript to verify from a hook payload. File harnesses
+    # read the path the harness handed us; OpenCode has no file, so it rebuilds
+    # the transcript from opencode.db by session id (a temp file the caller
+    # unlinks). Returns None when there's nothing to verify.
+    transcript_of: Callable[[dict], Path | None]
+    # Epoch at which the turn under review began, so the Stop reports *this turn's*
+    # work rather than the whole session's (TYCHO-17). Where the boundary lives is
+    # harness knowledge, so it belongs here; what to do with it is the engine's.
+    # Defaulting to 0.0 means "the whole transcript is the turn" — the honest answer
+    # for a harness whose reader already yields one turn, or that can't timestamp.
+    turn_start: Callable[[Path], float] = lambda _: 0.0
+    # Assistant prose reader, for tool_call_provenance. Defaults to none: a harness whose
+    # transcript we don't (yet) mine for prose supplies no messages, and the check degrades
+    # to UNSUPPORTED there rather than guessing. Only Claude Code wires a real reader in v1.
+    messages: Callable[[Path], tuple] = lambda _: ()
+    # How to surface the bootup update-notice (TYCHO-72). This is a *human-only* channel and
+    # is deliberately NOT `format_output`: on Cursor `format_output` is model-facing
+    # (`followup_message`), and a notice that reaches the model could commission it to go
+    # update Tycho (the TYCHO-35 rule). None — the default — means "no user-facing bootup
+    # channel", so the notice is suppressed there rather than risk a model-facing one. Only
+    # Claude/Codex (`systemMessage`) and OpenCode (`message`, toasted by the plugin) have one.
+    notice_output: Callable[[str], dict] | None = None
+
+
+def _payload_transcript(payload: dict) -> Path | None:
+    """File harnesses (Claude/Cursor/Codex) hand us the transcript path directly."""
+    path = payload.get("transcript_path")
+    return Path(path) if path else None
+
+
+def _cwd_root(payload: dict) -> Path:
+    return Path(payload.get("cwd") or os.getcwd())
+
+
+def _cursor_root(payload: dict) -> Path:
+    roots = payload.get("workspace_roots") or []
+    return Path(roots[0]) if roots else Path(os.getcwd())
+
+
+# --- data roots -------------------------------------------------------------
+#
+# Each harness keeps its sessions under a root that defaults to a dotdir in
+# $HOME. That default is only a default: dotfiles get relocated, machines get
+# shared, and Windows puts this somewhere else entirely (TYCHO-15). So every
+# root is overridable — Tycho's own env var first, then the harness's native
+# one (the variable the agent itself honors), then the historical default.
+
+_NATIVE_HOME_ENV = {
+    "claude": "CLAUDE_CONFIG_DIR",
+    "codex": "CODEX_HOME",
+    "cursor": None,  # no documented override
+}
+
+
+def home(name: str) -> Path:
+    """Root of ``name``'s on-disk data — the dir holding ``projects/``/``sessions/``."""
+    for var in (f"TYCHO_{name.upper()}_HOME", _NATIVE_HOME_ENV.get(name)):
+        value = os.environ.get(var) if var else None
+        if value:
+            return Path(value).expanduser()
+    return Path.home() / f".{name}"
+
+
+# --- manual discovery: find a repo's newest transcript on disk --------------
+#
+# Claude and Cursor key transcripts by the (start-time) cwd, encoded by turning every
+# path separator and space into "-". Claude keeps the leading dash from the absolute
+# path; Cursor strips it. Verified against real dirs under ~/.claude and ~/.cursor —
+# including on Windows, where str(cwd) carries a drive colon and backslashes:
+# `C:\Users\me\Swail Labs\tycho` -> `C--Users-me-Swail-Labs-tycho` (TYCHO-24). The POSIX
+# set ("/", ".") is a subset of this, so *nix encoding is unchanged.
+_DIR_SEP_CHARS = str.maketrans({c: "-" for c in "\\/:. "})
+
+
+def _encode(cwd: Path) -> str:
+    return str(cwd).translate(_DIR_SEP_CHARS)
+
+
+def _newest(paths) -> Path | None:
+    files = [p for p in paths if p.is_file()]
+    return max(files, key=lambda p: p.stat().st_mtime, default=None)
+
+
+def _claude_discover(cwd: Path) -> Path | None:
+    root = home("claude") / "projects" / _encode(cwd)
+    return _newest(root.glob("*.jsonl"))
+
+
+def _cursor_discover(cwd: Path) -> Path | None:
+    root = home("cursor") / "projects" / _encode(cwd).lstrip("-") / "agent-transcripts"
+    return _newest(root.glob("*/*.jsonl"))
+
+
+def _opencode_root(payload: dict) -> Path:
+    return Path(payload.get("directory") or payload.get("cwd") or os.getcwd())
+
+
+def _opencode_transcript(payload: dict) -> Path | None:
+    """Rebuild the session named in the plugin payload from opencode.db."""
+    session_id = payload.get("sessionID") or payload.get("session_id")
+    if not session_id:
+        return None
+    return opencode_mod.materialize(session_id, _opencode_root(payload))
+
+
+def _opencode_discover(cwd: Path) -> Path | None:
+    """Materialize the newest opencode.db session for ``cwd`` (or None)."""
+    session_id = opencode_mod.latest_session(cwd)
+    return opencode_mod.materialize(session_id, cwd) if session_id else None
+
+
+def _codex_discover(cwd: Path) -> Path | None:
+    root = home("codex") / "sessions"
+    for path in sorted(root.glob("**/*.jsonl"), key=lambda p: p.stat().st_mtime, reverse=True):
+        try:
+            first = next(line for line in path.read_text(encoding="utf-8").splitlines() if line)
+            payload = json.loads(first).get("payload", {})
+        except (OSError, StopIteration, ValueError):
+            continue
+        if payload.get("cwd") == str(cwd):
+            return path
+    return None
+
+
+def _cursor_output(text: str) -> dict:
+    """Wrap the verdict so Cursor *shows* it instead of acting on it.
+
+    `followup_message` is the only field Cursor's stop hook reads, and Cursor queues
+    it as a UserMessageAction — the model sees it and, left unqualified, would treat
+    a FAILED verdict as a fresh instruction and start fixing things. Tycho reports;
+    it doesn't commission work. So the message carries its own stop condition: relay
+    verbatim, then end the turn. This is a prompt, not an API guarantee — Cursor's
+    loop_count/loop_limit remains the hard backstop, and exit 0 still never blocks.
+    """
+    return {"followup_message": f"{text}\n\n{_CURSOR_RELAY}"}
+
+
+# Addressed to the model, not the human — kept one line so it can't bury the verdict.
+_CURSOR_RELAY = (
+    "[Tycho] The above is an automated verification result, not a request. "
+    "Show it to the user verbatim and end your turn now — do not edit files, "
+    "run commands, or act on it unless the user asks."
+)
+
+
+CLAUDE = Harness(
+    name="claude",
+    parse=events.parse,
+    repo_root=_cwd_root,
+    # Claude renders `systemMessage` to the human; exit 0 never blocks the Stop.
+    format_output=lambda text: {"systemMessage": text},
+    # Bootup notice rides the same human-only field — verified against 2.1.212 that
+    # SessionStart's `systemMessage` renders to the user, not the model (TYCHO-72 step 0).
+    notice_output=lambda text: {"systemMessage": text},
+    discover=_claude_discover,
+    transcript_of=_payload_transcript,
+    turn_start=events.turn_start,
+    messages=events.assistant_messages,
+)
+
+CURSOR = Harness(
+    name="cursor",
+    parse=events.parse_cursor,
+    repo_root=_cursor_root,
+    # `followup_message` is the ONLY field Cursor's stop hook reads — pinned to
+    # cursor-agent 2026.07.09-a3815c0, which validates exactly one output key
+    # ("followup_message must be a string if provided") and forwards it as
+    # StopRequestResponse.followupMessage. The `user_message` sent here previously
+    # was never read on stop (that field exists only on permission-deny steps), so
+    # the verdict silently reached nobody. See tests/fixtures/cursor_stop_payload.json.
+    #
+    # Unlike Claude's `systemMessage`, this re-enters the model loop: Cursor queues it
+    # as a UserMessageAction. That is the only channel Cursor offers — there is no
+    # human-only field — so _cursor_output tells the model to relay and stop.
+    format_output=_cursor_output,
+    discover=_cursor_discover,
+    transcript_of=_payload_transcript,
+    # turn_start stays 0.0: parse_cursor gives every Event ts=0.0 (the transcript
+    # carries no timestamps), so there is nothing to scope *by* — and the sample
+    # transcript is one turn end-to-end (a `<user_query>` through `turn_ended`).
+)
+
+CODEX = Harness(
+    name="codex",
+    parse=events.parse_codex,
+    repo_root=_cwd_root,
+    format_output=lambda text: {"systemMessage": text},
+    # Codex's SessionStart output wire schema clones Claude's — `systemMessage` is the
+    # human-facing field (docs/harness-support.md). Render-path still ⚠️ pending a live
+    # capture (TYCHO-111); worst case the toast is silent, never model-facing.
+    notice_output=lambda text: {"systemMessage": text},
+    discover=_codex_discover,
+    transcript_of=_payload_transcript,
+    # parse_codex returns every turn (TYCHO-20); turn_start_codex anchors the boundary on
+    # the latest turn's task_started, so the engine narrows exactly like Claude. Codex is
+    # the only harness with an explicit turn_id, which is why it can do this precisely.
+    turn_start=events.turn_start_codex,
+)
+
+OPENCODE = Harness(
+    name="opencode",
+    parse=events.parse_opencode,
+    repo_root=_opencode_root,
+    format_output=lambda text: {"message": text},
+    # The plugin reads `.message` and toasts it via client.tui.showToast — a genuinely
+    # user-facing sink. The bootup notice reuses the same shape on the session.created
+    # branch (TYCHO-72).
+    notice_output=lambda text: {"message": text},
+    # OpenCode has no transcript file — the reader rebuilds it from opencode.db,
+    # so discovery and the live plugin both use the same DB-backed materializer.
+    discover=_opencode_discover,
+    transcript_of=_opencode_transcript,
+    # turn_start_opencode anchors on the last user message, which is what opens an
+    # OpenCode turn. The boundary looked underivable while session_json flattened every
+    # part into one synthesized assistant message and dropped the user rows (TYCHO-21);
+    # the DB carries a per-message `time.created` and always did.
+    turn_start=events.turn_start_opencode,
+)
+
+ALL = (CLAUDE, CURSOR, CODEX, OPENCODE)
+BY_NAME = {h.name: h for h in ALL}
+
+# The harness version each adapter's hook contract was last verified against, and the
+# local `--version` command to read the installed one. This is the machine copy of the
+# "Verified against" row in docs/harness-support.md — keep the two in step (a test pins
+# them together). `probe` stays offline (a local subprocess), so the zero-dep/offline
+# invariant holds; drift is advisory ("re-verify"), never a break (TYCHO-34). OpenCode
+# has no CLI version contract (it's read from opencode.db), so it isn't probed.
+VERIFIED_AGAINST = {
+    "claude": {"version": "2.1.210", "probe": ("claude", "--version")},
+    "cursor": {"version": "2026.07.09-a3815c0", "probe": ("cursor-agent", "--version")},
+    "codex": {"version": "0.144.4", "probe": ("codex", "--version")},
+}
+
+
+def detect(payload: dict) -> Harness:
+    """Pick the harness from the Stop payload shape.
+
+    Cursor's payload carries ``workspace_roots``/``cursor_version``; Claude's
+    does not. Default to Claude — it's the harness with a pinned fixture.
+    """
+    if payload.get("harness") == "opencode" or payload.get("sessionID"):
+        return OPENCODE
+    if payload.get("workspace_roots") is not None or payload.get("cursor_version"):
+        return CURSOR
+    if payload.get("hook_event_name") == "Stop" and payload.get("turn_id"):
+        return CODEX
+    return CLAUDE
+
+
+def discover(cwd: Path, only: str | None = None) -> tuple[Path | None, Harness | None]:
+    """Find the most-recently-used transcript for ``cwd`` across harnesses.
+
+    Cursor transcripts carry no internal timestamps, so file mtime is the only
+    signal all harnesses share — and it's exactly "most recently used". With
+    ``only`` set (a harness name), restrict discovery to that harness.
+    Returns (path, harness), or (None, None) when nothing is found.
+    """
+    candidates = []
+    for harness in ALL:
+        if only and harness.name != only:
+            continue
+        path = harness.discover(cwd)
+        if path is not None:
+            candidates.append((path.stat().st_mtime, path, harness))
+    if not candidates:
+        return None, None
+    _, path, harness = max(candidates, key=lambda c: c[0])
+    return path, harness

tycho/hook.py

@@ -0,0 +1,212 @@
+"""The Stop-hook entrypoint: stdin JSON → verify → print, never block.
+
+Wired by ``tycho init`` (next milestone) into the harness's Stop hook. Reads the
+hook payload on stdin, locates the transcript + repo, runs the engine, and emits
+the verdict as the harness's JSON output.
+
+A verifier must never break the agent: any bad input, missing transcript, or
+internal error exits 0 with no output. Unlike ``tycho verify`` (which exits 1 on
+FAILED so CI can gate), the *hook* always exits 0 — it annotates the Stop, it
+never blocks it. That is a design invariant: Tycho never blocks.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from . import harness as harness_mod
+from . import state
+from . import verify as engine
+from .report import render
+
+
+def run(stdin_text: str) -> dict | None:
+    """Pure-ish core: hook payload text → output dict (or None for "say nothing").
+
+    Split from stdin/stdout so it's testable without patching the process.
+    Returns None whenever there is nothing to report or anything goes wrong.
+    """
+    try:
+        payload = json.loads(stdin_text)
+    except (json.JSONDecodeError, TypeError):
+        return None
+    if not isinstance(payload, dict):
+        return None
+
+    harness = harness_mod.detect(payload)
+    repo = harness.repo_root(payload)
+    # Heartbeat, up front on every path: it answers "did the wiring fire?" — the basis of
+    # `tycho doctor` (TYCHO-8) — so it must land even when there's nothing to verify.
+    # `pending=True` shows the badge "verifying"; every path below re-beats a terminal state
+    # so it never sticks (TYCHO-59). Never raises.
+    state.record_run(repo, harness.name, pending=True)
+
+    transcript = harness.transcript_of(payload)
+    if not transcript:
+        state.record_run(repo, harness.name)  # nothing to verify — clear "verifying" (grey)
+        return None  # transcripts disabled (Cursor) or absent
+
+    try:
+        session = engine.gather(
+            Path(transcript), repo, parse=harness.parse, turn_start=harness.turn_start,
+            messages=harness.messages,
+        )
+        if not engine.has_verifiable_activity(session):
+            state.record_run(repo, harness.name)  # fired, nothing to report — clear pending (grey)
+            return None
+        results = engine.run_checks(session)
+        verdict = engine.verdict_of(results)
+        # Re-beat with the verdict, for `tycho status` to render passively (TYCHO-39).
+        # Only here, where a verdict exists: the entry beat above already proved liveness,
+        # and claiming a verdict we never reached would be the one lie Tycho can't tell.
+        state.record_run(repo, harness.name, verdict=verdict.name)
+        # And log it to the catch record with its evidence trail, if adverse/intermediate
+        # (TYCHO-62). No-op for VERIFIED/UNSUPPORTED; never raises.
+        state.record_catch(repo, harness.name, verdict.name, results)
+    except Exception:
+        # broad catch is the correct behavior here — fail open, never
+        # break the agent's Stop over an unreadable transcript or git hiccup. Clear the
+        # pending beat so the badge doesn't sit on "verifying" forever.
+        state.record_run(repo, harness.name)
+        return None
+    finally:
+        # OpenCode's transcript is a rebuilt temp file — clean it up either way.
+        if harness.name == "opencode":
+            Path(transcript).unlink(missing_ok=True)
+    report = render(verdict, results)
+    relayed = _relay_output(repo, harness, verdict, report)
+    return relayed if relayed is not None else harness.format_output(report)
+
+
+# --- verdict relay (TYCHO-35, opt-in, default OFF) --------------------------
+#
+# When the operator turns the relay on, feed a non-VERIFIED verdict back to the *Claude* agent
+# as Stop-hook additionalContext. Verified against Claude Code 2.1.212 (binary disassembly, see
+# docs/harness-support.md): a Stop hook's `hookSpecificOutput.additionalContext` is injected as a
+# `hook_additional_context` message AND makes Claude Code continue the turn (preventContinuation
+# stays false — it is not `decision:"block"`, so the "never blocks" invariant holds: exit stays 0
+# and nothing is halted). That continuation is what lets the agent keep working "until VERIFIED".
+#
+# It is *bounded* by state.relay_streak: at most relay_max() auto-continuations per user turn,
+# after which Tycho goes quiet and the turn ends normally — an unsatisfiable verdict can't cycle
+# forever. Off by default and Claude-only, so every other harness and the un-opted-in path emit
+# exactly the human-only output they always did (no agent context used, no extra generations).
+
+
+def _relay_output(repo: Path, harness, verdict, report: str) -> dict | None:
+    """The relay output dict, or None to fall through to the normal human-only output.
+
+    Returns None (unchanged behaviour) unless the relay is enabled here, the harness is Claude,
+    and the verdict is worth acting on. VERIFIED clears the streak and ends the turn (nothing to
+    fix); once the streak reaches relay_max() the relay goes quiet and hands control back.
+    """
+    if harness.name != "claude" or not state.relay_enabled(repo):
+        return None
+    if verdict.name == "VERIFIED":  # proven good — end the turn, reset the leash
+        state.reset_relay_streak(repo)
+        return None
+    if state.relay_streak(repo) >= state.relay_max():
+        # Leash spent for this user turn — go quiet and let the turn end. Deliberately do NOT
+        # reset here: resetting would re-arm the relay on the very next Stop and oscillate
+        # (inject N, rest 1, inject N…) instead of stopping. The streak stays maxed until a real
+        # user prompt (prompt_submit) resets it — that is what scopes the bound to one user turn.
+        return None
+    attempt = state.bump_relay_streak(repo)
+    guard = _relay_guard(attempt, state.relay_max())
+    # systemMessage keeps the human seeing the verdict, now with a pointer to manage/turn off the
+    # relay (TYCHO-114); additionalContext is the model-facing copy that also drives the continuation.
+    manage = "[TYCHO] Relay is on — the agent keeps working until VERIFIED. Manage or turn it off: `tycho relay` (/tycho-relay)."
+    return {
+        "systemMessage": f"{report}\n\n{manage}",
+        "hookSpecificOutput": {
+            "hookEventName": "Stop",
+            "additionalContext": f"{report}\n\n{guard}",
+        },
+    }
+
+
+def _relay_guard(attempt: int, cap: int) -> str:
+    """The instruction appended to the model-facing verdict. Frames it as a report, points at
+    fixing the root cause, and — crucially — offers the escape hatch of stopping to tell the
+    user, so a verdict the agent can't satisfy converges on a conversation rather than a loop.
+    Names the attempt count so the model knows the leash is finite."""
+    if attempt >= cap:
+        tail = (" This is the final automatic re-check — after this the turn ends and control "
+                "returns to the user regardless of the verdict.")
+    else:
+        tail = f" Automatic re-check {attempt} of {cap}."
+    return (
+        "[TYCHO] The above is an automated verification of the turn you just finished — a report, "
+        "not a new instruction from the user. If a check FAILED or is STALE, fix the underlying "
+        "cause and finish so the next check can confirm it. If you believe the verdict is wrong, "
+        "or the work is genuinely out of scope, stop and say so to the user instead of continuing. "
+        "Do not start unrelated work. The user can manage or turn off this relay with `tycho relay` "
+        "(/tycho-relay in Claude Code)." + tail
+    )
+
+
+def session_start() -> int:
+    """SessionStart / bootup hook: surface a *user-facing* update notice at agent bootup
+    (TYCHO-53, generalized to Codex/OpenCode in TYCHO-72). The output shape is the harness's
+    `notice_output` — a human-only channel (`systemMessage` on Claude/Codex, `message` toasted
+    by the OpenCode plugin). A harness with no such channel (Cursor: `notice_output is None`)
+    gets nothing, so the notice can never reach the model and commission a self-update
+    (TYCHO-35's rule). We parse the payload only to pick that shape; the update check itself is
+    machine-global, not per-repo.
+
+    Same invariants as the Stop hook: never raises, always exit 0, prints nothing when
+    offline / opted out / already current. A bootup hook must never break the session.
+    """
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+        harness = harness_mod.detect(payload) if isinstance(payload, dict) else harness_mod.CLAUDE
+        # Codex's SessionStart payload isn't Stop-shaped so `detect` reads it as Claude — which
+        # is harmless here: both emit `systemMessage`, so the notice shape is identical either way.
+        if harness.notice_output is None:
+            return 0  # no user-facing bootup channel on this harness (e.g. Cursor)
+        from . import version as version_mod
+
+        note = version_mod.notice(refresh_first=True)
+        if note:
+            print(json.dumps(harness.notice_output(f"Tycho: {note}")))
+    except Exception:
+        pass
+    return 0
+
+
+def prompt_submit() -> int:
+    """UserPromptSubmit hook (Claude Code): the user just submitted a prompt, so a turn is
+    starting. Record a `pending` beat so the status badge shows frost-blue "verifying" for the
+    whole run (TYCHO-94); the Stop hook clears it to the verdict when the turn ends.
+
+    Prints nothing — a UserPromptSubmit hook's stdout is injected into the agent's context, and
+    Tycho must never put words in the user's prompt. Same invariants as every hook: never
+    raises, always exit 0, touches only the heartbeat.
+    """
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+        if isinstance(payload, dict):
+            harness = harness_mod.detect(payload)
+            repo = harness.repo_root(payload)
+            state.record_run(repo, harness.name, pending=True)
+            # A real user prompt opens a fresh turn, so the verdict-relay leash resets here: the
+            # bound (TYCHO-35) counts auto-continuations *within* one user turn, not across them.
+            # Auto-continuations don't re-fire UserPromptSubmit, so this only ever runs for the
+            # human's own prompts — exactly the boundary the bound is scoped to.
+            state.reset_relay_streak(repo)
+    except Exception:
+        pass
+    return 0
+
+
+def main() -> int:
+    output = run(sys.stdin.read())
+    if output is not None:
+        print(json.dumps(output))
+    return 0  # the hook annotates; it never blocks the Stop.
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())