yoru-cli 0.1.0__py3-none-any.whl

yoru_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

yoru_cli/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

yoru_cli/api.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class ReceiptClient:
+    def __init__(self, base_url: str, token: str | None = None) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+
+    def start_device_code(self, label: str | None = None) -> dict[str, Any]:
+        """Begin the device-pairing handshake — no auth needed."""
+        r = httpx.post(
+            f"{self.base_url}/api/v1/auth/device-code",
+            json={"label": label} if label else {},
+            timeout=5.0,
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def poll_device_code(self, device_code: str) -> dict[str, Any]:
+        """Poll for approval — returns {status, token?}."""
+        r = httpx.post(
+            f"{self.base_url}/api/v1/auth/device-code/poll",
+            json={"device_code": device_code},
+            timeout=10.0,
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def post_events(self, events: list[dict[str, Any]]) -> httpx.Response:
+        headers = {"Authorization": f"Bearer {self.token}"} if self.token else {}
+        return httpx.post(
+            f"{self.base_url}/api/v1/sessions/events",
+            json={"events": events},
+            headers=headers,
+            timeout=5.0,
+        )

yoru_cli/cli.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import argparse
+
+from . import __version__
+from . import config, doctor_cmd, init_cmd, tail_cmd
+
+DEFAULT_SERVER = "https://api.yoru.sh"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="yoru",
+        description="Yoru — audit-grade session receipts for autonomous AI coding agents.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"yoru {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="cmd", required=True, metavar="{init,tail,doctor}")
+
+    p_init = subparsers.add_parser(
+        "init",
+        help="Install the Claude Code hook and write ~/.config/yoru/config.json.",
+    )
+    p_init.add_argument("--server", default=DEFAULT_SERVER, help=f"Backend URL (default: {DEFAULT_SERVER})")
+    p_init.add_argument(
+        "--token",
+        default=None,
+        help="Pre-minted hook token (rcpt_...) — for headless/CI/server setups. "
+             "Also read from $YORU_TOKEN. Without this, yoru init launches "
+             "interactive device pairing.",
+    )
+    p_init.add_argument(
+        "--label",
+        default=None,
+        help="Human-readable machine label shown in the dashboard "
+             "(default: <hostname> · <os>).",
+    )
+    p_init.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="Don't try to auto-open the pairing URL in a browser.",
+    )
+    p_init.add_argument("--force", action="store_true", help="Overwrite an existing install.")
+
+    p_tail = subparsers.add_parser(
+        "tail",
+        help="Read JSON events from stdin and POST them as a batch (dev/debug).",
+    )
+    p_tail.add_argument(
+        "--server",
+        default=None,
+        help=f"Backend URL (default: value from config, else {DEFAULT_SERVER}).",
+    )
+    p_tail.add_argument("--session-id", default=None, help="Session id to stamp on events missing one.")
+
+    subparsers.add_parser(
+        "doctor",
+        help="Diagnose the install: config, backend, token, hook.",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.cmd == "tail" and args.server is None:
+        cfg = config.load() or {}
+        args.server = cfg.get("server", DEFAULT_SERVER)
+
+    if args.cmd == "init":
+        return init_cmd.run(args)
+    if args.cmd == "tail":
+        return tail_cmd.run(args)
+    if args.cmd == "doctor":
+        return doctor_cmd.run(args)
+
+    parser.error(f"unknown command: {args.cmd!r}")
+    return 2

yoru_cli/config.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def _config_dir() -> Path:
+    return Path.home() / ".config" / "yoru"
+
+
+def _config_file() -> Path:
+    return _config_dir() / "config.json"
+
+
+CONFIG_DIR: Path = _config_dir()
+CONFIG_FILE: Path = _config_file()
+
+
+def exists() -> bool:
+    return _config_file().is_file()
+
+
+def load() -> dict[str, Any] | None:
+    path = _config_file()
+    if not path.is_file():
+        return None
+    with path.open("r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def save(data: dict[str, Any]) -> None:
+    dir_path = _config_dir()
+    file_path = _config_file()
+    os.makedirs(dir_path, mode=0o700, exist_ok=True)
+    payload = dict(data)
+    payload.setdefault("created_at", datetime.now(timezone.utc).isoformat())
+    fd = os.open(file_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        json.dump(payload, f, indent=2, sort_keys=True)
+        f.write("\n")

yoru_cli/doctor_cmd.py

@@ -0,0 +1,92 @@
+"""`yoru doctor` — diagnostic subcommand.
+
+Read-only check of the install:
+  1. config.json present                   → else exit 1
+  2. backend /health/ready reachable       → else exit 2
+  3. hook-token valid (GET /hook-tokens)   → else exit 3 on 401
+  4. ~/.claude/hooks/yoru.sh is 0755    → else exit 4
+
+Prints ✓ lines to stdout on success (exit 0). Failures go to stderr with a
+short human-readable reason. No fixes attempted.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import stat
+import sys
+from pathlib import Path
+
+import httpx
+
+from . import config
+
+
+def _token_suffix(token: str) -> str:
+    tail = token[-4:] if len(token) >= 4 else token
+    return f"rcpt_...{tail}"
+
+
+def _hook_path() -> Path:
+    return Path.home() / ".claude" / "hooks" / "yoru.sh"
+
+
+def run(args: argparse.Namespace) -> int:  # noqa: ARG001 — argparse hands args, unused for now
+    # 1. config
+    cfg = config.load()
+    if cfg is None:
+        print("yoru init not run", file=sys.stderr)
+        return 1
+    server = (cfg.get("server") or "").rstrip("/")
+    token = cfg.get("token") or ""
+    if not server or not token:
+        print("yoru init not run", file=sys.stderr)
+        return 1
+
+    # 2. backend /health/ready
+    try:
+        r = httpx.get(f"{server}/health/ready", timeout=5.0)
+    except httpx.HTTPError:
+        print(f"backend unreachable at {server}", file=sys.stderr)
+        return 2
+    if r.status_code != 200:
+        print(f"backend unreachable at {server}", file=sys.stderr)
+        return 2
+
+    # 3. hook-token validity
+    try:
+        r = httpx.get(
+            f"{server}/api/v1/auth/hook-tokens",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=5.0,
+        )
+    except httpx.HTTPError:
+        print(f"backend unreachable at {server}", file=sys.stderr)
+        return 2
+    if r.status_code == 401:
+        print("token revoked or expired", file=sys.stderr)
+        return 3
+    if r.status_code != 200:
+        print(
+            f"hook-token check failed: HTTP {r.status_code}",
+            file=sys.stderr,
+        )
+        return 3
+
+    # 4. hook file + perms
+    hook = _hook_path()
+    if not hook.is_file():
+        print("hook file missing or not 0755", file=sys.stderr)
+        return 4
+    mode = stat.S_IMODE(hook.stat().st_mode)
+    if mode != 0o755:
+        print("hook file missing or not 0755", file=sys.stderr)
+        return 4
+
+    # all green
+    user = cfg.get("user") or "authenticated"
+    print(f"\u2713 config at ~/.config/yoru/config.json (token {_token_suffix(token)})")
+    print(f"\u2713 backend {server} reachable")
+    print(f"\u2713 hook-token valid (user: {user})")
+    print("\u2713 hook installed at ~/.claude/hooks/yoru.sh")
+    return 0

yoru_cli/hook_template.py

@@ -0,0 +1,119 @@
+"""Bundled Claude Code hook script — written verbatim by `yoru init`.
+
+Shape is frozen in vault/CLI-V0-DESIGN.md §4. Bash (not Python) for fast startup;
+`curl --max-time 2 || true` keeps the hook from ever blocking the agent.
+v0 posts one event per tool call — batching is a v1 optimization.
+
+Subscribed hook events (configured in ~/.claude/settings.json):
+  - SessionStart        → kind=session_start
+  - UserPromptSubmit    → kind=message (prompt text captured)
+  - PostToolUse         → kind inferred (tool_use | file_change)
+  - Notification        → kind=message (permission/input prompts)
+  - Stop                → kind=session_end
+  - SubagentStop        → kind=message (lightweight, doesn't close session)
+
+PreToolUse is NOT subscribed — PostToolUse carries the same tool_input plus
+tool_response, so subscribing to both doubles traffic for no gain.
+"""
+
+HOOK_SCRIPT: str = """#!/usr/bin/env bash
+# Claude Code hook — Receipt ingest. Handles all subscribed hook events.
+set -euo pipefail
+# Skip events when AGENT_RELAY_CHILD=1 (agent-relay-spawned children — prevents dashboard noise)
+[ "${AGENT_RELAY_CHILD:-0}" = "1" ] && exit 0
+CFG="${HOME}/.config/yoru/config.json"
+[ -r "$CFG" ] || exit 0          # silent no-op if uninstalled
+SERVER=$(python3 -c 'import json,os;print(json.load(open(os.path.expanduser("~/.config/yoru/config.json")))["server"])')
+TOKEN=$(python3 -c 'import json,os;print(json.load(open(os.path.expanduser("~/.config/yoru/config.json")))["token"])')
+# Claude Code pipes the hook event as JSON on stdin. We parse the original
+# payload, attach it verbatim to `raw` (so the backend sees tool_input /
+# tool_response — Pydantic drops unknown top-level fields otherwise), then
+# mutate the top-level envelope with `kind` + extracted `content` for the
+# renderer-friendly shape.
+#
+# Routing context (Phase C): hook detects cwd + git remote/branch and ships
+# them with every event so the server can route the session to the right
+# workspace. `git` calls are cached per-session in $TMPDIR to keep the hook
+# fast on hot PostToolUse paths.
+BODY=$(python3 -c 'import sys,json,os,subprocess
+original=json.loads(sys.stdin.read())
+e=dict(original)
+e["raw"]=original
+
+# Routing context — cwd from Claude payload (reliable), git info cached.
+cwd = original.get("cwd")
+if isinstance(cwd, str) and cwd:
+    e["cwd"] = cwd
+
+sess_id = original.get("session_id") or original.get("sessionId") or ""
+cache_dir = os.environ.get("TMPDIR", "/tmp")
+cache = os.path.join(cache_dir, f".receipt-ctx-{sess_id}.env") if sess_id else None
+git_remote = None
+git_branch = None
+if cache and os.path.exists(cache):
+    try:
+        for line in open(cache, encoding="utf-8"):
+            k,_,v = line.strip().partition("=")
+            if k == "git_remote": git_remote = v or None
+            elif k == "git_branch": git_branch = v or None
+    except Exception:
+        pass
+if (git_remote is None or git_branch is None) and isinstance(cwd, str) and cwd:
+    def _run(args):
+        try:
+            return subprocess.check_output(args, cwd=cwd, stderr=subprocess.DEVNULL, timeout=1).decode().strip() or None
+        except Exception:
+            return None
+    if git_remote is None:
+        git_remote = _run(["git","remote","get-url","origin"])
+    if git_branch is None:
+        git_branch = _run(["git","rev-parse","--abbrev-ref","HEAD"])
+    if cache:
+        try:
+            with open(cache, "w", encoding="utf-8") as f:
+                if git_remote: f.write(f"git_remote={git_remote}\\n")
+                if git_branch: f.write(f"git_branch={git_branch}\\n")
+        except Exception:
+            pass
+if git_remote: e["git_remote"] = git_remote
+if git_branch: e["git_branch"] = git_branch
+
+hen=e.get("hook_event_name")
+if hen=="SessionStart":
+    e["kind"]="session_start"
+elif hen=="UserPromptSubmit":
+    e["kind"]="message"
+    e["tool"]="user"
+    p=e.get("prompt")
+    if isinstance(p,str) and p: e["content"]=p[:2000]
+elif hen=="Notification":
+    e["kind"]="message"
+    e["tool"]="notification"
+    m=e.get("message")
+    if isinstance(m,str) and m: e["content"]=m[:2000]
+elif hen=="SubagentStop":
+    e["kind"]="message"
+    e["tool"]="subagent"
+    e["content"]="subagent stopped"
+elif hen=="Stop":
+    e["kind"]="session_end"
+# PostToolUse / PreToolUse: leave kind unset → backend _infer_kind() from tool
+print(json.dumps({"events":[e]}))')
+curl -sS --max-time 2 -X POST "${SERVER}/api/v1/sessions/events" \\
+  -H "Authorization: Bearer ${TOKEN}" \\
+  -H "Content-Type: application/json" \\
+  -d "${BODY}" >/dev/null 2>&1 || true   # never block the agent
+"""
+
+
+# Hook subscriptions to write into ~/.claude/settings.json.
+# Each entry is a (hook_event_name, description) pair; the installer writes a
+# single `matcher:"*"` entry per event pointing at ~/.claude/hooks/yoru.sh.
+HOOK_SUBSCRIPTIONS: list[tuple[str, str]] = [
+    ("SessionStart",     "capture session boundary"),
+    ("UserPromptSubmit", "capture user prompts (message events)"),
+    ("PostToolUse",      "capture tool_use + file_change"),
+    ("Notification",     "capture permission/input prompts"),
+    ("Stop",             "capture session close"),
+    ("SubagentStop",     "capture subagent lifecycle"),
+]

yoru_cli/init_cmd.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import socket
+import sys
+import time
+import webbrowser
+from datetime import datetime, timezone
+from pathlib import Path
+
+import httpx
+
+from . import config
+from .api import ReceiptClient
+from .hook_template import HOOK_SCRIPT
+
+
+def _default_label() -> str:
+    """Best-effort human label for this machine — 'macbook-air · darwin'."""
+    host = socket.gethostname().split(".")[0] or "unknown"
+    return f"{host} · {platform.system().lower()}"
+
+
+RECEIPT_MATCHERS: list[tuple[str, str]] = [
+    ("PostToolUse", "*"),
+    ("SessionStart", "*"),
+    ("Stop", "*"),
+]
+
+
+def _merge_settings_json(settings_path: Path, hook_path: Path) -> None:
+    """Register the receipt hook in ~/.claude/settings.json, preserving user keys.
+
+    Registers PostToolUse + SessionStart + Stop so the timeline has bookends.
+    """
+    if settings_path.exists():
+        try:
+            obj = json.loads(settings_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            obj = {}
+        if not isinstance(obj, dict):
+            obj = {}
+    else:
+        obj = {}
+
+    hooks = obj.setdefault("hooks", {})
+    if not isinstance(hooks, dict):
+        hooks = {}
+        obj["hooks"] = hooks
+
+    def _is_receipt_entry(entry: object) -> bool:
+        if not isinstance(entry, dict):
+            return False
+        inner = entry.get("hooks")
+        if not isinstance(inner, list) or not inner:
+            return False
+        first = inner[0]
+        if not isinstance(first, dict):
+            return False
+        cmd = first.get("command")
+        return isinstance(cmd, str) and cmd.endswith("yoru.sh")
+
+    for event_name, matcher_glob in RECEIPT_MATCHERS:
+        entries = hooks.setdefault(event_name, [])
+        if not isinstance(entries, list):
+            entries = []
+            hooks[event_name] = entries
+
+        receipt_entry = {
+            "matcher": matcher_glob,
+            "hooks": [{"type": "command", "command": str(hook_path)}],
+        }
+
+        replaced = False
+        for idx, entry in enumerate(entries):
+            if _is_receipt_entry(entry):
+                entries[idx] = receipt_entry
+                replaced = True
+                break
+        if not replaced:
+            entries.append(receipt_entry)
+
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = settings_path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(obj, indent=2), encoding="utf-8")
+    os.replace(tmp, settings_path)
+
+
+def _pair_device(server: str, label: str, *, no_browser: bool) -> str | None:
+    """Run the device-code pairing handshake — returns the raw token or None."""
+    client = ReceiptClient(server)
+    try:
+        start = client.start_device_code(label=label)
+    except httpx.HTTPError as e:
+        print(f"error: failed to contact {server}: {e}", file=sys.stderr)
+        return None
+
+    user_code = start["user_code"]
+    verify_uri = start["verification_uri"]
+    verify_complete = start["verification_uri_complete"]
+    device_code = start["device_code"]
+    expires_in = int(start.get("expires_in", 600))
+    interval = int(start.get("interval", 2))
+
+    print()
+    print(f"  Pair this device with your Yoru account:")
+    print(f"    1. Open  {verify_uri}")
+    print(f"    2. Enter {user_code}")
+    print()
+    if not no_browser:
+        try:
+            webbrowser.open(verify_complete)
+        except Exception:
+            pass
+
+    deadline = time.time() + expires_in
+    while time.time() < deadline:
+        try:
+            resp = client.poll_device_code(device_code)
+        except httpx.HTTPError as e:
+            print(f"\nerror: poll failed: {e}", file=sys.stderr)
+            return None
+        s = resp.get("status")
+        if s == "approved":
+            token = resp.get("token")
+            if not token:
+                print("error: approved but no token returned", file=sys.stderr)
+                return None
+            print(f"  ✓ Paired as {label}")
+            return token
+        if s in ("expired", "denied"):
+            print(f"\nerror: pairing {s} — re-run `yoru init`", file=sys.stderr)
+            return None
+        # pending — sleep and keep polling
+        sys.stdout.write("  waiting for approval…\r")
+        sys.stdout.flush()
+        time.sleep(interval)
+
+    print("\nerror: pairing timed out — re-run `yoru init`", file=sys.stderr)
+    return None
+
+
+def run(args: argparse.Namespace) -> int:
+    if config.exists() and not getattr(args, "force", False):
+        print("Already installed (use --force to overwrite)", file=sys.stderr)
+        return 1
+
+    server: str = args.server
+    token: str | None = getattr(args, "token", None)
+    # Also accept YORU_TOKEN from env for headless / CI / server deployments.
+    if not token:
+        token = os.environ.get("YORU_TOKEN", "").strip() or None
+
+    if not token:
+        label = (getattr(args, "label", None) or "").strip() or _default_label()
+        no_browser = bool(getattr(args, "no_browser", False))
+        token = _pair_device(server, label, no_browser=no_browser)
+        if not token:
+            return 2
+
+    config.save({
+        "server": server,
+        "token": token,
+        "created_at": datetime.now(timezone.utc).isoformat(),
+    })
+
+    hook_dir = Path.home() / ".claude" / "hooks"
+    hook_path = hook_dir / "yoru.sh"
+    os.makedirs(hook_dir, exist_ok=True)
+    hook_path.write_text(HOOK_SCRIPT, encoding="utf-8")
+    os.chmod(hook_path, 0o755)
+
+    settings_path = Path.home() / ".claude" / "settings.json"
+    _merge_settings_json(settings_path, hook_path)
+
+    print("\u2713 config   \u2192 ~/.config/yoru/config.json")
+    print("\u2713 hook     \u2192 ~/.claude/hooks/yoru.sh")
+    print("\u2713 settings \u2192 ~/.claude/settings.json (hook registered)")
+    print("Next: run Claude Code normally; first event streams to /sessions/events.")
+    return 0

yoru_cli/tail_cmd.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+import httpx
+
+from . import config
+from .api import ReceiptClient
+
+
+def run(args: argparse.Namespace) -> int:
+    cfg = config.load()
+    server = getattr(args, "server", None) or (cfg.get("server") if cfg else None)
+    if not server:
+        print("error: no server configured (run `yoru init` or pass --server)", file=sys.stderr)
+        return 2
+    token = cfg.get("token") if cfg else None
+
+    raw = sys.stdin.read().strip()
+    if not raw:
+        print("error: no input on stdin", file=sys.stderr)
+        return 2
+
+    events: list[dict[str, Any]]
+    if raw.lstrip().startswith("["):
+        events = json.loads(raw)
+    else:
+        events = [json.loads(line) for line in raw.splitlines() if line.strip()]
+
+    session_id = getattr(args, "session_id", None)
+    if session_id:
+        for e in events:
+            e["session_id"] = session_id
+
+    client = ReceiptClient(server, token)
+    try:
+        resp = client.post_events(events)
+    except httpx.HTTPError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 4
+
+    print(f"HTTP {resp.status_code}")
+    print(resp.text[:500])
+    if 200 <= resp.status_code < 300:
+        return 0
+    if 400 <= resp.status_code < 500:
+        return 3
+    return 4

yoru_cli/transcript_tailer.py

@@ -0,0 +1,438 @@
+"""Transcript tailer — captures AssistantMessage events that hooks can't.
+
+Claude Code hooks expose user prompts, tool calls, and session lifecycle, but
+emit no event when Claude itself speaks. For a complete audit trail Receipt
+must read the transcript file (`~/.claude/projects/<slug>/<session>.jsonl`),
+which Claude Code appends to in real time with every message (user, assistant,
+tool_use, tool_result).
+
+Strategy:
+  * Discover all `.jsonl` under `~/.claude/projects/` on startup + via 2-sec
+    rescan for new sessions.
+  * Per file, remember the last byte offset in a small state file so a restart
+    never reprocesses.
+  * On every new JSONL line, route:
+      type=assistant + content[].type=text     → kind=message tool=assistant
+      type=assistant + content[].type=thinking → kind=message tool=thinking
+    (user prompts + tool calls + tool results are already captured by hooks.)
+  * POST one event at a time via the same /api/v1/sessions/events endpoint.
+
+Daemonize: run as LaunchAgent (`launchctl load …plist`) or in a tmux pane.
+
+v0 keeps it dependency-free — stdlib-only, one thread per file.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any, Iterable
+
+_PROJECTS_DIR = Path.home() / ".claude/projects"
+_CONFIG_PATH = Path.home() / ".config/yoru/config.json"
+_STATE_PATH = Path.home() / ".config/yoru/tail-state.json"
+_POLL_INTERVAL_SEC = 1.0
+_RESCAN_INTERVAL_SEC = 5.0
+
+# Pricing is computed backend-side (see backend/apps/api/api/routers/receipt/
+# pricing.py which auto-refreshes from LiteLLM's public JSON). The tailer
+# ships raw usage + model and lets the backend resolve the rate so we never
+# have stale hardcoded prices here — and new providers (Cursor, Aider,
+# whatever emits OpenAI/Gemini) work without touching the tailer.
+
+
+def _load_config() -> tuple[str, str]:
+    with open(_CONFIG_PATH) as f:
+        cfg = json.load(f)
+    return cfg["server"].rstrip("/"), cfg["token"]
+
+
+def _load_state() -> dict[str, int]:
+    if not _STATE_PATH.exists():
+        return {}
+    try:
+        with open(_STATE_PATH) as f:
+            return json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _save_state(state: dict[str, int]) -> None:
+    _STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    tmp = _STATE_PATH.with_suffix(".tmp")
+    with open(tmp, "w") as f:
+        json.dump(state, f)
+    tmp.replace(_STATE_PATH)
+
+
+def _post(server: str, token: str, event: dict[str, Any]) -> None:
+    """One-event ingest. Silent on non-2xx; we never block on Yoru outages."""
+    _post_batch(server, token, [event])
+
+
+def _post_batch(server: str, token: str, events: list[dict[str, Any]]) -> None:
+    """Batch ingest — POST up to 1000 events in one request. Respects the
+    Retry-After header returned by the backend's token-bucket rate limiter
+    (slowapi-style), so a long backfill throttles instead of losing events."""
+    if not events:
+        return
+    body = json.dumps({"events": events}).encode("utf-8")
+    for attempt in range(6):
+        req = urllib.request.Request(
+            f"{server}/api/v1/sessions/events",
+            data=body,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+            },
+            method="POST",
+        )
+        try:
+            urllib.request.urlopen(req, timeout=30).read()
+            return
+        except urllib.error.HTTPError as e:
+            if e.code == 429:
+                retry_after = 1
+                try:
+                    retry_after = int(e.headers.get("Retry-After", "1"))
+                except (TypeError, ValueError):
+                    pass
+                time.sleep(retry_after + 0.2)
+                continue
+            print(f"[tailer] POST {e.code}: {e.reason}", file=sys.stderr)
+            return
+        except (urllib.error.URLError, TimeoutError) as e:
+            print(f"[tailer] POST failed: {e}", file=sys.stderr)
+            return
+    print(f"[tailer] gave up after 6 retries (rate-limited)", file=sys.stderr)
+
+
+# In-memory set of Anthropic message IDs we've already ingested. Prevents
+# Claude Code's occasional duplicate transcript writes (streaming deltas +
+# final consolidation, or a session compaction replaying history) from
+# double-counting tokens and cost. The set grows unboundedly in a long run
+# but each entry is ~40 bytes so millions fit comfortably.
+_SEEN_MSG_IDS: set[str] = set()
+
+
+def _iter_assistant_events(line: str) -> Iterable[dict[str, Any]]:
+    """Parse one JSONL line, yield Receipt events.
+
+    Handles two line types:
+      * type=user  → emits kind=message tool=user (the hook UserPromptSubmit
+        only fires live, so backfill has to replay prompts from transcript)
+      * type=assistant → emits:
+          - kind=message tool=assistant per text block
+          - kind=message tool=thinking per thinking block
+          - kind=token per assistant message (usage rollup → cost)
+
+    Returns nothing for other types (attachment/snapshot/etc) or for message
+    IDs we've already processed this session.
+    """
+    try:
+        d = json.loads(line)
+    except json.JSONDecodeError:
+        return
+    t = d.get("type")
+    if t == "user":
+        # User prompt replay for backfill. Live tailer also emits these (dup
+        # with the hook) but the hook-sourced events have no `message.id`
+        # from the transcript — they're deduped by session_id+ts pair on
+        # the backend if anyone cares, which for now we don't (duplicates
+        # under kind=message tool=user are cosmetic in the timeline).
+        msg = d.get("message") or {}
+        content = msg.get("content")
+        # Claude Code writes either a string content ("hi") or an array of
+        # blocks ([{type:text,text:"hi"}, {type:tool_result,...}]). We only
+        # keep the text blocks, join them.
+        text = ""
+        if isinstance(content, str):
+            text = content
+        elif isinstance(content, list):
+            parts = [b.get("text") for b in content
+                     if isinstance(b, dict) and b.get("type") == "text" and isinstance(b.get("text"), str)]
+            text = "\n".join(p for p in parts if p)
+        text = (text or "").strip()
+        if not text:
+            return
+        session_id = d.get("sessionId") or ""
+        ts = d.get("timestamp") or ""
+        if not session_id:
+            return
+        # Dedup: a message.id-style key would be ideal but user lines don't
+        # always carry one; use (uuid) from the line which is transcript-
+        # unique.
+        key = d.get("uuid")
+        if isinstance(key, str) and key:
+            if key in _SEEN_MSG_IDS:
+                return
+            _SEEN_MSG_IDS.add(key)
+        yield {
+            "session_id": session_id,
+            "ts": ts,
+            "kind": "message",
+            "tool": "user",
+            "content": text[:2000],
+            "raw": {"hook_event_name": "TranscriptTail", "uuid": key},
+        }
+        return
+
+    if t != "assistant":
+        return
+    message = d.get("message") or {}
+    content = message.get("content") or []
+    if not isinstance(content, list):
+        return
+    session_id = d.get("sessionId") or ""
+    ts = d.get("timestamp") or ""
+    if not session_id:
+        return
+    # Dedup by Anthropic message.id. First-seen wins; later dupes silently
+    # dropped. Avoids counting the same assistant turn 2+ times.
+    msg_id = message.get("id")
+    if isinstance(msg_id, str) and msg_id:
+        if msg_id in _SEEN_MSG_IDS:
+            return
+        _SEEN_MSG_IDS.add(msg_id)
+    for block in content:
+        if not isinstance(block, dict):
+            continue
+        block_type = block.get("type")
+        if block_type == "text":
+            text = block.get("text")
+            if isinstance(text, str) and text.strip():
+                yield {
+                    "session_id": session_id,
+                    "ts": ts,
+                    "kind": "message",
+                    "tool": "assistant",
+                    "content": text[:4000],
+                    "raw": {"hook_event_name": "TranscriptTail", "block": block},
+                }
+        elif block_type == "thinking":
+            think = block.get("thinking")
+            if isinstance(think, str) and think.strip():
+                yield {
+                    "session_id": session_id,
+                    "ts": ts,
+                    "kind": "message",
+                    "tool": "thinking",
+                    "content": think[:4000],
+                    "raw": {"hook_event_name": "TranscriptTail", "block": block},
+                }
+
+    # One usage event per message — the backend's events_router aggregates
+    # tokens_input/output/cost_usd onto the session row, so this is where the
+    # Hero "cost" sparkline gets its numbers. Attaching model to `raw` keeps
+    # the assumption auditable.
+    usage = message.get("usage") or {}
+    if isinstance(usage, dict) and usage:
+        model = str(message.get("model") or "")
+        input_tokens = (
+            int(usage.get("input_tokens") or 0)
+            + int(usage.get("cache_read_input_tokens") or 0)
+            + int(usage.get("cache_creation_input_tokens") or 0)
+        )
+        output_tokens = int(usage.get("output_tokens") or 0)
+        if input_tokens > 0 or output_tokens > 0:
+            # Put the full usage breakdown under `raw.tool_input` so the
+            # backend's existing _enrich_events path (`raw.tool_input` →
+            # `EventOut.tool_input`) surfaces it to the frontend TokenPanel
+            # without a schema change. The backend's pricing compute reads
+            # `raw.usage` for cost calculation — we duplicate to keep both
+            # paths working.
+            yield {
+                "session_id": session_id,
+                "ts": ts,
+                "kind": "token",
+                "tool": model or "usage",
+                "tokens_input": input_tokens,
+                "tokens_output": output_tokens,
+                "content": f"{model} · {input_tokens}→{output_tokens} tok",
+                "raw": {
+                    "hook_event_name": "TranscriptTail",
+                    "model": model,
+                    "usage": usage,
+                    "tool_input": {"model": model, **usage},
+                },
+            }
+
+
+def _drain_file(
+    path: Path,
+    offset: int,
+    server: str,
+    token: str,
+) -> int:
+    """Read from `offset` to EOF, POSTing each derived event. Returns new offset."""
+    try:
+        with open(path, "rb") as f:
+            f.seek(offset)
+            remainder = f.read()
+    except OSError as e:
+        print(f"[tailer] read {path}: {e}", file=sys.stderr)
+        return offset
+    if not remainder:
+        return offset
+    # If we caught a partial line at EOF, rewind to the last newline.
+    last_nl = remainder.rfind(b"\n")
+    if last_nl == -1:
+        return offset  # no complete line yet
+    consumed, pending = remainder[: last_nl + 1], remainder[last_nl + 1 :]
+    new_offset = offset + len(consumed)
+    text = consumed.decode("utf-8", errors="replace")
+    for line in text.splitlines():
+        if not line:
+            continue
+        for ev in _iter_assistant_events(line):
+            _post(server, token, ev)
+    _ = pending  # drop — next drain re-reads from new_offset
+    return new_offset
+
+
+def run() -> None:
+    server, token = _load_config()
+    state = _load_state()
+    last_rescan = 0.0
+    tracked: dict[str, Path] = {}  # abs-path-str → Path
+    print(f"[tailer] server={server} watching {_PROJECTS_DIR}", file=sys.stderr)
+    while True:
+        now = time.time()
+        if now - last_rescan > _RESCAN_INTERVAL_SEC:
+            if _PROJECTS_DIR.is_dir():
+                for p in _PROJECTS_DIR.glob("**/*.jsonl"):
+                    key = str(p)
+                    if key not in tracked:
+                        tracked[key] = p
+                        # First-ever discovery: seek to END so we only pick up
+                        # NEW assistant messages, never backfill (audit-safe —
+                        # backfill would duplicate old messages already viewed
+                        # from older CLI hooks).
+                        if key not in state:
+                            try:
+                                state[key] = p.stat().st_size
+                            except OSError:
+                                state[key] = 0
+            last_rescan = now
+
+        any_change = False
+        for key, path in list(tracked.items()):
+            offset = state.get(key, 0)
+            new_offset = _drain_file(path, offset, server, token)
+            if new_offset != offset:
+                state[key] = new_offset
+                any_change = True
+        if any_change:
+            _save_state(state)
+        time.sleep(_POLL_INTERVAL_SEC)
+
+
+def backfill(session_id: str, wipe: bool = True) -> None:
+    """One-shot: re-ingest every assistant event for a given session.
+
+    Finds `~/.claude/projects/**/<session_id>.jsonl`, optionally DELETEs
+    existing tailer-origin events on the backend (avoids double-counting
+    tokens + cost), then replays the file from offset 0 through
+    `_iter_assistant_events` → POST /sessions/events.
+
+    Use cases:
+      * Import a session that started before the tailer was installed.
+      * Re-import after changing pricing rates (backend recomputes cost_usd
+        at ingest time from the current rate table).
+
+    Running it twice WITHOUT `wipe=True` will emit every event twice →
+    doubled aggregates. Default `wipe=True` is safe.
+    """
+    server, token = _load_config()
+    # 1. locate the transcript
+    candidates = list(_PROJECTS_DIR.glob(f"**/{session_id}.jsonl"))
+    if not candidates:
+        print(f"[backfill] no transcript found for session {session_id}", file=sys.stderr)
+        return
+    path = candidates[0]
+    print(f"[backfill] using {path}", file=sys.stderr)
+
+    # 2. wipe existing tailer events server-side so aggregates stay honest
+    if wipe:
+        req = urllib.request.Request(
+            f"{server}/api/v1/sessions/{session_id}/tailer-events",
+            headers={"Authorization": f"Bearer {token}"},
+            method="DELETE",
+        )
+        try:
+            urllib.request.urlopen(req, timeout=10).read()
+            print(f"[backfill] wiped existing tailer events for {session_id}", file=sys.stderr)
+        except urllib.error.HTTPError as e:
+            print(f"[backfill] wipe returned {e.code} — continuing", file=sys.stderr)
+        except (urllib.error.URLError, TimeoutError) as e:
+            print(f"[backfill] wipe failed: {e} — aborting to avoid dupes", file=sys.stderr)
+            return
+
+    # 3. replay the file — batch size kept small (50) because each event can
+    # carry a multi-kB `raw` payload (full tool_input + tool_response) and
+    # the backend has a body-size limit that rejects big batches with 413.
+    BATCH = 50
+    batch: list[dict[str, Any]] = []
+    count = 0
+    def _flush() -> None:
+        nonlocal batch, count
+        if not batch: return
+        _post_batch(server, token, batch)
+        count += len(batch)
+        batch = []
+    with open(path) as f:
+        for line in f:
+            for ev in _iter_assistant_events(line):
+                batch.append(ev)
+                if len(batch) >= BATCH:
+                    _flush()
+                    time.sleep(0.1)  # breathing room for slowapi
+    _flush()
+    print(f"[backfill] emitted {count} events for session {session_id}", file=sys.stderr)
+
+    # 4. bump the saved offset to EOF so the live tailer doesn't re-emit
+    state = _load_state()
+    try:
+        state[str(path)] = path.stat().st_size
+        _save_state(state)
+    except OSError:
+        pass
+
+
+def backfill_all(wipe: bool = True) -> None:
+    """Backfill every transcript under ~/.claude/projects/. Useful once."""
+    for path in _PROJECTS_DIR.glob("**/*.jsonl"):
+        sid = path.stem
+        print(f"[backfill-all] ▶ {sid}", file=sys.stderr)
+        backfill(sid, wipe=wipe)
+
+
+if __name__ == "__main__":
+    import argparse
+    ap = argparse.ArgumentParser(
+        prog="yoru-tailer",
+        description="Stream Claude Code assistant messages into Yoru.",
+    )
+    sub = ap.add_subparsers(dest="cmd")
+    sub.add_parser("run", help="follow every transcript live (default)")
+    bf = sub.add_parser("backfill", help="re-ingest one session's transcript")
+    bf.add_argument("session_id")
+    bf.add_argument("--no-wipe", action="store_true",
+                    help="skip the DELETE tailer-events pre-step (will duplicate)")
+    bfa = sub.add_parser("backfill-all", help="re-ingest every transcript on disk")
+    bfa.add_argument("--no-wipe", action="store_true")
+
+    args = ap.parse_args()
+    try:
+        if args.cmd == "backfill":
+            backfill(args.session_id, wipe=not args.no_wipe)
+        elif args.cmd == "backfill-all":
+            backfill_all(wipe=not args.no_wipe)
+        else:
+            run()
+    except KeyboardInterrupt:
+        pass

yoru_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: yoru-cli
+Version: 0.1.0
+Summary: Yoru — audit-grade session receipts for autonomous AI coding agents.
+Project-URL: Homepage, https://yoru.sh
+Project-URL: Documentation, https://yoru.sh/docs
+Project-URL: Repository, https://github.com/helios-code/overnight-saas
+Project-URL: Issues, https://github.com/helios-code/overnight-saas/issues
+Author-email: Yoru authors <hello@opentruth.ch>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,aider,audit,claude-code,cursor,observability
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# yoru-cli
+
+Yoru — audit-grade session receipts for autonomous AI coding agents.
+
+One command installs a Claude Code hook that streams every tool call into the Yoru backend; the dashboard turns that feed into a signed session receipt.
+
+## Install
+
+```bash
+pip install -e .          # from the monorepo
+# or once published:
+# pip install yoru-cli
+```
+
+Requires Python 3.10+. Only runtime dep is `httpx`.
+
+## Usage
+
+```bash
+yoru init                         # writes ~/.claude/hooks/yoru.sh + ~/.config/yoru/config.json (0600)
+yoru init --server http://localhost:8002 --user you@example.com    # non-interactive (CI/smoke)
+yoru init --server http://localhost:8002 --token rcpt_xxx --force
+
+yoru tail                         # reads JSON events on stdin, POSTs them as a batch (dev/debug)
+echo '{"session_id":"s1","user":"dev","kind":"tool_use","tool":"Bash"}' | yoru tail
+
+receipt --version                    # receipt 0.1.0
+receipt --help
+```
+
+Exit codes: `0` ok, `1` already installed without `--force`, `2` auth failed, `3` 4xx, `4` 5xx/network.
+
+## Spec
+
+Frozen design doc: `vault/CLI-V0-DESIGN.md` in the monorepo (§1 layout, §2 pyproject, §3 subcommands, §4 hook shape, §5 auth, §7 event schema).

yoru_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+yoru_cli/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+yoru_cli/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+yoru_cli/api.py,sha256=Q29oFcpgg864UVqI276qPmYEtAmpDzeL7Y3smHejEBM,1341
+yoru_cli/cli.py,sha256=-SZs5eUi7Rd8jI873yda1rJ8ke_En_k6lvdkfpYAvUA,2691
+yoru_cli/config.py,sha256=u1UgK_UOsCaYWGg7DuGLej7IGA0NtPg6ahLQcymT0S0,1069
+yoru_cli/doctor_cmd.py,sha256=A7Is43Ocv2dV_LiTCKqarPX7BCHUTqrmAmdA93y5QzQ,2854
+yoru_cli/hook_template.py,sha256=R_77i16g9q1tNw0-8ZWfWxUip7UmnpeiM1gF5rJ63oE,5342
+yoru_cli/init_cmd.py,sha256=ShQ6St6Wu74FJEB6mty1DO3PgJxUN9u-Q6EqVEgOzNc,6137
+yoru_cli/tail_cmd.py,sha256=oWOsGR9LpuTKDRUARVfLAT2_SDPJZc0cp3jR76YMl9w,1334
+yoru_cli/transcript_tailer.py,sha256=BUGp15953zIYVEd-fNqJRINGGrkFfypJHRAFtUFQSnw,17156
+yoru_cli-0.1.0.dist-info/METADATA,sha256=LOeOcqWJrFXbfBtBZXfeP1VzeiKNIqFh4nPedSw_CgY,2280
+yoru_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+yoru_cli-0.1.0.dist-info/entry_points.txt,sha256=PjwjTQLl09ujQ2fxl1oIRtZSmmRZwgkIK6bl-k2ivbU,43
+yoru_cli-0.1.0.dist-info/licenses/LICENSE,sha256=wld15WFSfVpLvSbFRo8lPewGKHccwME11CYcN_JAgy8,1717
+yoru_cli-0.1.0.dist-info/RECORD,,

yoru_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

yoru_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+yoru = yoru_cli.cli:main

yoru_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,31 @@
+MIT License
+
+Copyright (c) 2026 Yoru authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+─────────────────────────────────────────────────────────────────────────
+
+SCOPE: The Yoru CLI — everything inside the `yoru-cli/` directory in
+the Yoru monorepo. The CLI is intentionally MIT so it can be freely
+embedded in proprietary dev environments, CI pipelines, internal tooling,
+and closed-source forks without viral license obligations.
+
+The SERVER (backend + dashboard + marketing + infra) is AGPL-3.0 — see the
+`LICENSE` file at the repository root and `LICENSING.md` for the rationale.