SourceIndex 0.1.0__py3-none-any.whl

sourceindex/build/state.py

@@ -0,0 +1,261 @@
+"""Persistent JSON state for the sourceindex cache directory.
+
+Three artifacts share this module because they're all "what we know about
+the index after the last run":
+
+- ``_summary_cache.json`` — content-hash → {oneliner, functions} so unchanged
+  files skip re-summarization across builds.
+- ``_file_index.json`` — rel_path → {mtime_ns, hash} so lazy refresh can
+  detect working-tree edits without re-hashing every file.
+- ``build_meta.json`` — model + token + cost + timing accounting, merged
+  across init and update runs. Read by eval_summarize.py — schema is stable;
+  add new fields only at the end.
+
+All read/write goes through a duck-typed ``store`` object (one of
+``daemon.EncryptedStore`` / ``daemon.PlaintextStore``). State logic stays
+ignorant of whether bytes on disk are encrypted — the store handles that.
+"""
+
+import json
+from datetime import datetime, timezone
+
+from .. import __version__ as _SOURCEINDEX_VERSION
+from ..lib.languages import Language
+from ..lib.llm import LLMUsage
+from ..lib.log import get_logger
+
+_log = get_logger(__name__)
+
+
+SUMMARY_CACHE_FILENAME = "_summary_cache.json"
+FILE_INDEX_FILENAME = "_file_index.json"
+BUILD_META_FILENAME = "build_meta.json"
+
+
+# ── Summary cache ──────────────────────────────────────────────────────────
+
+
+def load_summary_cache(store) -> dict[str, dict[str, str]]:
+    """Load {content_hash: {"oneliner": ..., "functions": ...}} from store."""
+    if not store.exists(SUMMARY_CACHE_FILENAME):
+        return {}
+    try:
+        data = json.loads(store.read_text(SUMMARY_CACHE_FILENAME))
+    except (json.JSONDecodeError, OSError, Exception) as e:
+        _log.warning(
+            f"Summary cache at {store.path_for(SUMMARY_CACHE_FILENAME)} is unreadable; starting from empty cache.",
+            extra={
+                "event": "cache.decode_failed",
+                "kind": "summary_cache",
+                "path": str(store.path_for(SUMMARY_CACHE_FILENAME)),
+                "error_type": type(e).__name__,
+                "error": str(e),
+            },
+        )
+        return {}
+    # Migrate legacy format: {hash: oneliner_string}
+    migrated: dict[str, dict[str, str]] = {}
+    for h, v in data.items():
+        if isinstance(v, str):
+            migrated[h] = {"oneliner": v, "functions": ""}
+        elif isinstance(v, dict):
+            migrated[h] = {
+                "oneliner": v.get("oneliner", ""),
+                "functions": v.get("functions", ""),
+            }
+    return migrated
+
+
+def save_summary_cache(store, cache: dict[str, dict[str, str]]) -> None:
+    """Persist summary cache to store."""
+    store.write_text(
+        SUMMARY_CACHE_FILENAME,
+        json.dumps(cache, indent=1, sort_keys=True) + "\n",
+    )
+
+
+# ── File index (path → mtime + hash) ───────────────────────────────────────
+
+
+def load_file_index(store) -> dict[str, dict]:
+    """Load {rel_path: {"mtime_ns": int, "hash": str}} from disk.
+
+    Path-keyed companion to ``_summary_cache.json`` (which is keyed by
+    content hash for cross-file dedupe). Used by lazy refresh to detect
+    edits since the last index update.
+    """
+    if not store.exists(FILE_INDEX_FILENAME):
+        return {}
+    try:
+        data = json.loads(store.read_text(FILE_INDEX_FILENAME))
+    except (json.JSONDecodeError, OSError, Exception) as e:
+        _log.warning(
+            f"File index at {store.path_for(FILE_INDEX_FILENAME)} is unreadable; treating as empty.",
+            extra={
+                "event": "cache.decode_failed",
+                "kind": "file_index",
+                "path": str(store.path_for(FILE_INDEX_FILENAME)),
+                "error_type": type(e).__name__,
+                "error": str(e),
+            },
+        )
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    paths = data.get("paths", {})
+    return paths if isinstance(paths, dict) else {}
+
+
+def save_file_index(store, paths: dict[str, dict]) -> None:
+    """Persist path-keyed file index to store."""
+    payload = {"version": 1, "paths": paths}
+    store.write_text(
+        FILE_INDEX_FILENAME,
+        json.dumps(payload, indent=1, sort_keys=True) + "\n",
+    )
+
+
+def write_details(store, rel_path: str, functions_text: str) -> None:
+    """Write tier-2 function index to details/<rel_path>.md."""
+    body = functions_text.strip() or "(LLM indexing failed)"
+    store.write_text(f"details/{rel_path}.md", f"# {rel_path}\n\n{body}\n")
+
+
+def details_exists(store, rel_path: str) -> bool:
+    return store.exists(f"details/{rel_path}.md")
+
+
+def try_summary_cache_hit(
+    summary_cache: dict[str, dict[str, str]],
+    content_hash: str,
+    lang: Language,
+    store,
+    rel_path: str,
+) -> tuple[str, str] | None:
+    """Return ``(oneliner, functions)`` if the summary cache + on-store
+    details are sufficient to skip an LLM call. Writes the details
+    file from cache if missing. Otherwise returns ``None``."""
+    cached = summary_cache.get(content_hash)
+    if not cached or not cached.get("oneliner"):
+        return None
+    oneliner = cached["oneliner"]
+    functions = cached.get("functions", "")
+    if not lang.build_tier2:
+        return oneliner, functions
+    if not (details_exists(store, rel_path) or functions):
+        return None
+    if not details_exists(store, rel_path):
+        write_details(store, rel_path, functions)
+    return oneliner, functions
+
+
+# ── Build meta accounting ──────────────────────────────────────────────────
+
+
+def utcnow_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _compose_meta(
+    base: dict,
+    *,
+    model: str,
+    files_indexed: int,
+    files_from_cache: int | None,
+    usage: LLMUsage,
+    elapsed_s: float,
+    started_at: str,
+) -> dict:
+    """Build the canonical ``build_meta.json`` dict.
+
+    ``base`` is the previous meta (or ``{}`` for a fresh build). Numeric
+    fields sum ``base + new``, the model string is replaced with the
+    latest-used model, and ``started_at`` carries forward from the
+    original build. ``files_from_cache=None`` skips updating that field
+    (update-mode doesn't have a hit/miss split). Schema is stable —
+    eval_summarize.py reads it; add new fields only at the end so old
+    summarizers keep working."""
+    return {
+        "model": model,
+        "files_indexed": int(base.get("files_indexed", 0)) + files_indexed,
+        "files_from_cache": int(base.get("files_from_cache", 0))
+            if files_from_cache is None
+            else files_from_cache,
+        "input_tokens": int(base.get("input_tokens", 0)) + usage.input_tokens,
+        "output_tokens": int(base.get("output_tokens", 0)) + usage.output_tokens,
+        "cache_read_tokens": int(base.get("cache_read_tokens", 0)) + usage.cache_read_tokens,
+        "cache_creation_tokens": int(base.get("cache_creation_tokens", 0)) + usage.cache_creation_tokens,
+        "cost_usd": round(float(base.get("cost_usd", 0.0)) + usage.cost_usd, 6),
+        "elapsed_s": round(float(base.get("elapsed_s", 0.0)) + elapsed_s, 3),
+        "started_at": base.get("started_at", started_at),
+        "sourceindex_version": _SOURCEINDEX_VERSION,
+    }
+
+
+def _read_existing_meta(store) -> dict:
+    if not store.exists(BUILD_META_FILENAME):
+        return {}
+    try:
+        return json.loads(store.read_text(BUILD_META_FILENAME))
+    except (json.JSONDecodeError, OSError, Exception) as e:
+        _log.warning(
+            f"Build meta at {store.path_for(BUILD_META_FILENAME)} is unreadable; treating as fresh.",
+            extra={
+                "event": "cache.decode_failed",
+                "kind": "build_meta",
+                "path": str(store.path_for(BUILD_META_FILENAME)),
+                "error_type": type(e).__name__,
+                "error": str(e),
+            },
+        )
+        return {}
+
+
+def write_build_meta(
+    store,
+    *,
+    model: str,
+    files_indexed: int,
+    files_from_cache: int,
+    usage: LLMUsage,
+    elapsed_s: float,
+    started_at: str,
+) -> None:
+    """Fresh-build write: replace any existing meta with new values."""
+    meta = _compose_meta(
+        base={},
+        model=model,
+        files_indexed=files_indexed,
+        files_from_cache=files_from_cache,
+        usage=usage,
+        elapsed_s=elapsed_s,
+        started_at=started_at,
+    )
+    store.write_text(BUILD_META_FILENAME, json.dumps(meta, indent=2) + "\n")
+
+
+def merge_build_meta(
+    store,
+    *,
+    model: str,
+    files_indexed: int,
+    usage: LLMUsage,
+    elapsed_s: float,
+    started_at: str,
+) -> None:
+    """Update-mode merge: sum tokens/cost into any existing meta and
+    append ``last_updated_at``. No-op when ``files_indexed == 0``."""
+    if files_indexed == 0:
+        return
+    base = _read_existing_meta(store)
+    meta = _compose_meta(
+        base=base,
+        model=model,
+        files_indexed=files_indexed,
+        files_from_cache=None,
+        usage=usage,
+        elapsed_s=elapsed_s,
+        started_at=started_at,
+    )
+    meta["last_updated_at"] = utcnow_iso()
+    store.write_text(BUILD_META_FILENAME, json.dumps(meta, indent=2) + "\n")

sourceindex/build/walker.py

@@ -0,0 +1,94 @@
+"""Filesystem traversal + content hashing + mtime-delta change detection.
+
+Owns the question "which files in the working tree need (re-)indexing?"
+"""
+
+import hashlib
+import os
+from pathlib import Path
+
+from ..lib.languages import Language, all_extensions, all_skip_dirs
+from ..lib.log import get_logger, log_file_error
+from .state import load_file_index
+
+_log = get_logger(__name__)
+
+
+def collect_source_files(root: str | Path, languages: list[Language]) -> list[str]:
+    """Collect all source files for the given languages, pruning non-source dirs."""
+    root_path = Path(root)
+    skip = all_skip_dirs(languages)
+    exts = all_extensions(languages)
+    found: list[str] = []
+    for dirpath, dirnames, filenames in os.walk(root_path):
+        dirnames[:] = [d for d in dirnames if d not in skip]
+        for f in filenames:
+            if f.lower().endswith(exts):
+                found.append(str(Path(dirpath, f).relative_to(root_path)))
+    return sorted(found)
+
+
+def hash_file_content(content: str) -> str:
+    """SHA-256 prefix of file content for deduplication."""
+    return hashlib.sha256(content.encode()).hexdigest()[:16]
+
+
+def detect_changes_by_mtime(
+    repo_root: Path,
+    store,
+    languages: list[Language],
+) -> tuple[list[str], dict[str, dict], list[str], dict[str, dict]]:
+    """Walk the working tree, diff each path's mtime against _file_index.json.
+
+    Returns ``(changed, updated_path_map, deleted, stored)``:
+
+    - ``changed``: paths whose content hash differs from what's stored
+      (i.e. need to be re-indexed). The caller routes these through
+      ``update_index``, which itself short-circuits on summary_cache hits.
+    - ``updated_path_map``: complete path → {mtime_ns, hash} map for the
+      working tree as it stands now. Authoritative — caller persists this
+      verbatim. Includes touch-only and unchanged entries.
+    - ``deleted``: paths that were in the stored map but no longer exist on
+      disk (caller must remove them from index.md and details/).
+    - ``stored``: the previously persisted map. Returned so callers can
+      compare without re-reading the file.
+
+    Touch-only edits (mtime moved but content hash unchanged) skip the
+    re-index while still bumping the stored mtime so the next search
+    short-circuits without re-hashing.
+    """
+    current_paths = set(collect_source_files(repo_root, languages))
+    stored = load_file_index(store)
+
+    updated: dict[str, dict] = {}
+    changed: list[str] = []
+
+    for rel in sorted(current_paths):
+        full_path = repo_root / rel
+        try:
+            mtime = full_path.stat().st_mtime_ns
+        except OSError as e:
+            log_file_error(_log, rel, e, phase="mtime_scan.stat")
+            continue
+
+        prev = stored.get(rel)
+        if prev is not None and prev.get("mtime_ns") == mtime:
+            updated[rel] = {"mtime_ns": mtime, "hash": prev.get("hash", "")}
+            continue
+
+        try:
+            content = full_path.read_text(errors="replace")
+        except OSError as e:
+            log_file_error(_log, rel, e, phase="mtime_scan.read")
+            continue
+        if not content.strip():
+            continue
+
+        h = hash_file_content(content)
+        updated[rel] = {"mtime_ns": mtime, "hash": h}
+
+        if prev is None or prev.get("hash") != h:
+            changed.append(rel)
+
+    deleted = [rel for rel in stored if rel not in current_paths]
+    return changed, updated, deleted, stored

sourceindex/claudecode/savings.py

@@ -0,0 +1,325 @@
+"""Report sourceindex savings for the current session (Stop-hook entry point).
+
+Wired into Claude Code as a Stop hook: after every assistant turn, walks the
+transcript JSONL referenced by `payload.transcript_path`, attributes cost
+from the first sourceindex invocation onward (with `/compact` and `/clear`
+resetting the credit window), and persists a per-session savings entry
+plus a weekly ledger to ~/.claude/sourceindex_savings.json. The companion
+`sourceindex statusline` subcommand reads that ledger and renders the
+one-liner
+
+    SourceIndex saved $~0.18 this session · $~4.20 this week
+
+into the Claude Code status line. The Stop hook itself no longer prints to
+stdout — keeping the message out of the assistant's response area.
+
+Attribution is "from the first sourceindex invocation onward, until the
+roadmap is wiped." Once the agent invokes the sourceindex subagent, every
+subsequent turn is credited — the check is purely structural (presence of
+an Agent/Task tool_use with subagent_type="sourceindex"); we don't inspect
+the tool_result text, so error paths and synthesized summaries still count.
+Pre-invocation turns (recon the agent did before deciding to call
+sourceindex) don't get credit.
+
+Two events wipe the roadmap from context and reset the credit window:
+  * `/compact` (or auto-compact at context limit) — emits a record with
+    `isCompactSummary: true`. The verbose roadmap is exactly the detail
+    compaction strips out, so we conservatively require a new invocation.
+  * `/clear` — emits a user message whose content contains
+    `<command-name>/clear</command-name>`. Wipes context entirely.
+
+After either marker, `active` resets to False until the next sourceindex
+call re-activates it.
+
+Pricing table is mirrored from inspect/lib/report_print.py:55-73. Savings
+ratios come from reports/2026-05-06_haiku-vs-gpt5nano-cache.md (N=5, 100
+runs; sourceindex-bare with gpt-5.4-nano cache). Those numbers measure the
+bare variant, not the subagent variant detected here, but they share the
+same Pass 1a/1b core — best-available proxy until subagent N=5 numbers land.
+
+`SAVINGS_RATIO[m]` is the fraction of the *baseline* cost that sourceindex
+saves. The transcript cost we measure is the *post*-reduction cost, so the
+amount saved is `total_cost * ratio / (1 - ratio)`, not `total_cost * ratio`
+— the latter under-reports because it scales the wrong denominator.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import sys
+import tempfile
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+STATE_PATH = Path.home() / ".claude" / "sourceindex_savings.json"
+LOG_PATH = Path.home() / ".claude" / "sourceindex_savings.log"
+
+PRICING: dict[str, tuple[float, float, float, float]] = {
+    # Source: https://platform.claude.com/docs/en/about-claude/pricing
+    # Tuples are (input, output, cache_read, cache_creation_5m) per MTok.
+    # Order matters: the substring matcher in `_match` returns the first key
+    # contained in the model name, so put more-specific keys first.
+    # cache_creation defaults to the 5-minute write rate (1.25x input);
+    # the 1-hour rate (2x input) costs 60% more but the transcript's
+    # `cache_creation_input_tokens` field doesn't distinguish the two.
+    # Opus 4.5+ is priced at 1/3 of Opus 4.0/4.1.
+    "claude-opus-4-7":  ( 5.00, 25.00,  0.50,  6.25),
+    "claude-opus-4-6":  ( 5.00, 25.00,  0.50,  6.25),
+    "claude-opus-4-5":  ( 5.00, 25.00,  0.50,  6.25),
+    "claude-opus-4":    (15.00, 75.00,  1.50, 18.75),
+    "claude-sonnet-4":  ( 3.00, 15.00,  0.30,  3.75),
+    "claude-haiku-4-5": ( 1.00,  5.00,  0.10,  1.25),
+    "claude-haiku-4":   ( 0.80,  4.00,  0.08,  1.00),
+}
+
+SAVINGS_RATIO: dict[str, float] = {
+    "claude-opus-4":   0.25,
+    "claude-sonnet-4": 0.25,
+    "claude-haiku-4":  0.05,
+}
+DEFAULT_RATIO = 0.20
+
+
+def _match(table: dict[str, Any], model: str | None) -> Any:
+    m = (model or "").lower()
+    for key, val in table.items():
+        if key in m:
+            return val
+    return None
+
+
+def _line_cost(model: str | None, usage: Any) -> float:
+    rates = _match(PRICING, model)
+    if not rates or not isinstance(usage, dict):
+        return 0.0
+    inp = usage.get("input_tokens", 0) or 0
+    out = usage.get("output_tokens", 0) or 0
+    cr = usage.get("cache_read_input_tokens", 0) or 0
+    cc = usage.get("cache_creation_input_tokens", 0) or 0
+    in_r, out_r, cr_r, cc_r = rates
+    return (inp * in_r + out * out_r + cr * cr_r + cc * cc_r) / 1_000_000
+
+
+def _sourceindex_call_id(blocks: Any) -> str | None:
+    """If `blocks` contains a sourceindex Agent/Task tool_use, return its id."""
+    if not isinstance(blocks, list):
+        return None
+    for b in blocks:
+        if not isinstance(b, dict):
+            continue
+        if b.get("type") != "tool_use":
+            continue
+        if b.get("name") not in ("Agent", "Task"):
+            continue
+        if (b.get("input") or {}).get("subagent_type") == "sourceindex":
+            cid = b.get("id")
+            return cid if isinstance(cid, str) else None
+    return None
+
+
+CLEAR_MARKER = "<command-name>/clear</command-name>"
+
+
+def _is_reset_marker(rec: dict) -> bool:
+    """True if `rec` is a /compact summary or a /clear slash-command."""
+    if rec.get("isCompactSummary"):
+        return True
+    msg = rec.get("message") or {}
+    if msg.get("role") != "user":
+        return False
+    content = msg.get("content")
+    if isinstance(content, str):
+        return CLEAR_MARKER in content
+    if isinstance(content, list):
+        return any(
+            isinstance(b, dict)
+            and isinstance(b.get("text"), str)
+            and CLEAR_MARKER in b["text"]
+            for b in content
+        )
+    return False
+
+
+def walk_transcript(path: str | os.PathLike) -> tuple[bool, float, str | None, bool]:
+    """Return (used, total_cost, main_model, last_turn_invoked) from a transcript JSONL.
+
+    Cost runs from the first sourceindex invocation onward. The check is
+    purely structural — any assistant turn whose content contains an
+    Agent/Task tool_use with subagent_type="sourceindex" activates the
+    credit window. We do not inspect the tool_result, so error paths and
+    synthesized summaries still count. `/compact` and `/clear` reset the
+    active window — after either, a new sourceindex call is required.
+
+    `last_turn_invoked` is True iff the *chronologically last* assistant
+    turn carried a sourceindex tool_use. The Stop hook uses this to
+    decide whether to refresh `updated_at` — otherwise the statusline's
+    60s freshness window would re-arm on every turn, keeping the row lit
+    until the user goes idle. We want it to fade 60s after the actual
+    sourceindex invocation, not after the most recent assistant turn.
+
+    Skips sidechain (subagent) lines — we account parent cost only.
+    Unknown models (no PRICING substring match) contribute zero cost.
+    """
+    total = 0.0
+    any_used = False
+    main_model: str | None = None
+    active = False
+    last_turn_invoked = False
+
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    rec = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if rec.get("isSidechain"):
+                    continue
+                if _is_reset_marker(rec):
+                    active = False
+                    continue
+
+                msg = rec.get("message") or {}
+                if msg.get("role") != "assistant":
+                    continue
+                model = msg.get("model")
+                if main_model is None and model:
+                    main_model = model
+
+                this_turn_invoked = bool(_sourceindex_call_id(msg.get("content")))
+                last_turn_invoked = this_turn_invoked
+                if not active and this_turn_invoked:
+                    active = True
+                    any_used = True
+                if active:
+                    total += _line_cost(model, msg.get("usage"))
+    except (OSError, IOError):
+        pass
+    return any_used, total, main_model, last_turn_invoked
+
+
+def load_state(path: Path | None = None) -> dict[str, dict[str, Any]]:
+    p = path if path is not None else STATE_PATH
+    try:
+        with open(p, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        if isinstance(data, dict):
+            return data
+    except (OSError, json.JSONDecodeError):
+        pass
+    return {}
+
+
+def save_state(state: dict[str, Any], path: Path | None = None) -> None:
+    p = path if path is not None else STATE_PATH
+    try:
+        p.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(prefix=".sourceindex_savings.", dir=str(p.parent))
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                json.dump(state, f)
+            os.replace(tmp, p)
+        except Exception:
+            with contextlib.suppress(OSError):
+                os.unlink(tmp)
+            raise
+    except OSError:
+        pass
+
+
+def prune(state: dict[str, Any], today: date, days: int = 7) -> dict[str, dict[str, Any]]:
+    cutoff = today - timedelta(days=days)
+    keep: dict[str, dict[str, Any]] = {}
+    for sid, entry in state.items():
+        if not isinstance(entry, dict):
+            continue
+        d = entry.get("date")
+        try:
+            ed = datetime.strptime(d, "%Y-%m-%d").date()
+        except (TypeError, ValueError):
+            continue
+        if ed >= cutoff:
+            keep[sid] = entry
+    return keep
+
+
+def format_message(saved_session: float, weekly: float) -> str:
+    return f"SourceIndex saved $~{saved_session:0.2f} this session · $~{weekly:0.2f} this week."
+
+
+def run(payload: dict[str, Any], *, stdout=sys.stdout, now: datetime | None = None) -> int:
+    """Hook entry point. Returns process exit code (always 0).
+
+    `payload` is the parsed Stop-hook JSON. `now` is injectable for tests.
+    """
+    if payload.get("stop_hook_active") is True:
+        return 0
+
+    transcript = payload.get("transcript_path")
+    session_id = payload.get("session_id") or "unknown-session"
+    if not transcript:
+        return 0
+
+    used, total_cost, main_model, last_turn_invoked = walk_transcript(transcript)
+    if not used:
+        return 0
+
+    ratio = _match(SAVINGS_RATIO, main_model)
+    if ratio is None:
+        ratio = DEFAULT_RATIO
+    saved_session = total_cost * ratio / (1.0 - ratio)
+
+    actual_now = now or datetime.now()
+    today = actual_now.date()
+    state = load_state()
+    # Only refresh updated_at when this turn invoked sourceindex — otherwise
+    # preserve the prior timestamp so the statusline's 60s freshness window
+    # is anchored to the invocation, not to every Stop-hook fire.
+    prior = state.get(session_id) if isinstance(state.get(session_id), dict) else None
+    if last_turn_invoked or prior is None or not prior.get("updated_at"):
+        updated_at = actual_now.isoformat(timespec="seconds")
+    else:
+        updated_at = prior["updated_at"]
+    state[session_id] = {
+        "date": today.isoformat(),
+        "saved": saved_session,
+        "updated_at": updated_at,
+    }
+    state = prune(state, today)
+    save_state(state)
+
+    weekly = sum(e.get("saved", 0.0) for e in state.values() if isinstance(e, dict))
+    msg = format_message(saved_session, weekly)
+
+    try:
+        LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+        with open(LOG_PATH, "a", encoding="utf-8") as f:
+            f.write(f"{actual_now.isoformat(timespec='seconds')}\t{session_id}\t{msg}\n")
+    except OSError:
+        pass
+
+    return 0
+
+
+def main() -> int:
+    """CLI entry point — read JSON payload from stdin and run."""
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 0
+    if not isinstance(payload, dict):
+        return 0
+    try:
+        return run(payload)
+    except Exception:
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())