zeno-cli 0.3.4__py3-none-any.whl

zeno_cli/hud/zeno_hud.py

@@ -0,0 +1,496 @@
+#!/usr/bin/env python3
+"""zeno-hud - a Claude Code statusline that shows, every render (~300ms):
+
+    zeno · Opus 4.8 · zeno
+    ctx ███████░░░ 68%   5h ██░░░░░░░░ 22%   wk ████░░░░░░ 41%
+    att ███████▇░░ 74 ▲ sharp · keep going    eff ████████ 60 · drv ██████░░ 45
+
+The first three meters (context %, 5h usage %, weekly usage %) come straight from
+the JSON Claude Code pipes on stdin - no API call. The bottom line is the cognition
+read - three bars sharing one model (zeno_cognition):
+
+  att  the composite attention score, with its label/nudge ("sharp · keep going")
+       and, when notable, the most-deviant OFF-bar driver as a tag (e.g. ↑fatigue).
+  eff  how hard you are driving this turn - the effort driver.
+  drv  how hands-on you are vs delegating - the inverse of the autonomy (AI-led)
+       driver, i.e. your share of the wheel.
+
+Capped at three bars on purpose. The session count + RTLX-S SCED progress moved to
+the tailnet dashboard - the bar stays a pure, glanceable cognitive read.
+
+Design: stdlib-only, Python 3.9+ safe, never raises (a broken statusline shows
+nothing), targets <60ms. The attention model is a documented, tunable v1 heuristic
+(see README.md); env vars ZENO_HUD_* override the weights/widths.
+
+Pairs with the zeno-cc-bridge hook (the WRITE/capture surface); this is the READ
+surface. Wire via ~/.claude/settings.json statusLine -> see README.md.
+"""
+
+import json
+import os
+import re
+import sys
+
+# zeno_attention is the single source of truth for the attention formula: the
+# cc-bridge hook persists the score and the bar reads it back, so HUD and dashboard
+# never diverge (see docs/COGNITION_UNIFIED_PLAN.md Phase 2). zeno_cognition is the v2
+# per-turn model the cc-bridge hook writes and the HUD reads back through
+# COG.present_sample (falling back to the v1 transcript compute when no row exists).
+# Both are siblings in this package (zeno_cli.hud), so the imports are plain relative.
+from . import zeno_attention as A
+from . import zeno_cognition as COG
+
+# ---------------------------------------------------------------------------
+# config (env-overridable)
+# ---------------------------------------------------------------------------
+NO_COLOR = bool(os.environ.get("NO_COLOR"))
+BAR_W = int(os.environ.get("ZENO_HUD_BAR_WIDTH", "10"))
+ATT_BAR_W = int(os.environ.get("ZENO_HUD_ATT_WIDTH", "10"))
+COG_BAR_W = int(os.environ.get("ZENO_HUD_COG_WIDTH", "8"))  # the eff/drv sub-bars
+ZENO_DB = os.environ.get("ZENO_DB_PATH") or os.path.join(
+    os.environ.get("ZENO_HOME", os.path.join(os.path.expanduser("~"), ".zeno")), "zeno.db"
+)
+# attention model knobs live in the shared module; re-exported so existing
+# importers/tests that read H.WINDOW / H.TAIL_BYTES keep working unchanged.
+W_EFFORT, W_DELIB, W_TREND = A.W_EFFORT, A.W_DELIB, A.W_TREND
+WINDOW = A.WINDOW
+TAIL_BYTES = A.TAIL_BYTES
+
+# ANSI codes (GREEN/YELLOW/RED/CYAN match zeno_attention's color bands)
+GREEN, YELLOW, RED, CYAN, DIM, BOLD = "92", "93", "91", "96", "90", "1"
+
+
+# ---------------------------------------------------------------------------
+# rendering primitives
+# ---------------------------------------------------------------------------
+def c(s, code):
+    """Wrap s in an ANSI color unless NO_COLOR."""
+    if NO_COLOR or code is None:
+        return s
+    return f"\x1b[{code}m{s}\x1b[0m"
+
+
+def bar(frac, width=BAR_W):
+    """A unicode block bar with eighth-cell partials. Returns exactly `width` chars."""
+    frac = 0.0 if frac is None else max(0.0, min(1.0, frac))
+    eighths = int(round(frac * width * 8))
+    full, rem = divmod(eighths, 8)
+    full = min(full, width)
+    out = "█" * full
+    if full < width:
+        out += " ▏▎▍▌▋▊▉"[rem] if rem else "░"
+        out += "░" * (width - full - 1)
+    return out
+
+
+def pct_color(pct, lo=70, hi=85):
+    """Context/usage coloring: green under lo, yellow lo..hi, red above hi."""
+    if pct is None:
+        return DIM
+    if pct < lo:
+        return GREEN
+    if pct < hi:
+        return YELLOW
+    return RED
+
+
+def meter(label, pct, width=BAR_W, lo=70, hi=85):
+    if pct is None:
+        return "{} {} {}".format(c(label, DIM), c("░" * width, DIM), c("--", DIM))
+    col = pct_color(pct, lo, hi)
+    return "{} {} {}".format(c(label, DIM), c(bar(pct / 100.0, width), col), f"{pct:>3.0f}%")
+
+
+# ---------------------------------------------------------------------------
+# stdin (the native, accurate data)
+# ---------------------------------------------------------------------------
+def read_stdin():
+    try:
+        raw = sys.stdin.read()
+    except Exception:
+        return {}
+    raw = (raw or "").strip()
+    if not raw:
+        return {}
+    try:
+        return json.loads(raw)
+    except Exception:
+        return {}
+
+
+def _dig(d, *path):
+    cur = d
+    for k in path:
+        if not isinstance(cur, dict):
+            return None
+        cur = cur.get(k)
+    return cur
+
+
+def context_pct(stdin):
+    p = _dig(stdin, "context_window", "used_percentage")
+    if isinstance(p, (int, float)):
+        return float(p)
+    # fall back to current_usage / size
+    used = _dig(stdin, "context_window", "current_usage", "input_tokens")
+    size = _dig(stdin, "context_window", "context_window_size")
+    if isinstance(used, (int, float)) and isinstance(size, (int, float)) and size:
+        return 100.0 * used / size
+    return None
+
+
+def rate_pct(stdin, window):
+    p = _dig(stdin, "rate_limits", window, "used_percentage")
+    return float(p) if isinstance(p, (int, float)) else None
+
+
+def session_id(stdin):
+    """Map the Claude Code session id to the same zeno session UUID the
+    cc-bridge uses (uuid5 over 'cc:<id>'), so HUD samples and bridge
+    sessions/runs join on session_id. Returns None if no session id."""
+    cc = stdin.get("session_id")
+    if not isinstance(cc, str) or not cc:
+        return None
+    try:
+        import uuid
+
+        return str(uuid.uuid5(uuid.NAMESPACE_URL, "cc:" + cc))
+    except Exception:
+        return None
+
+
+def effort_level(stdin):
+    e = stdin.get("effort")
+    if isinstance(e, dict):
+        return e.get("level")
+    if isinstance(e, str):
+        return e
+    return None
+
+
+def model_name(stdin):
+    name = _dig(stdin, "model", "display_name") or ""
+    name = re.sub(r"\s*\([^)]*context[^)]*\)", "", name).strip()  # strip "(1M context)"
+    return name or "claude"
+
+
+def project_name(stdin):
+    d = _dig(stdin, "workspace", "current_dir") or stdin.get("cwd") or ""
+    return os.path.basename(d.rstrip("/")) if d else ""
+
+
+# ---------------------------------------------------------------------------
+# cognitive-attention engine - the formula lives in zeno_attention (single
+# source of truth). These thin aliases preserve the public names the HUD and
+# its tests call so the writer + bar + dashboard all share one model.
+# ---------------------------------------------------------------------------
+_clean_prompt_text = A.clean_prompt_text
+_prompt_effort = A.prompt_effort
+_delib_score = A.delib_score
+_parse_ts = A.parse_ts
+parse_transcript = A.parse_transcript
+attention = A.attention
+
+
+def attention_meter(stdin, a=None, width=None):
+    width = ATT_BAR_W if width is None else width
+    if a is None:
+        prompts, asst = parse_transcript(stdin.get("transcript_path"))
+        a = attention(prompts, asst)
+    if not a.get("ok"):
+        return "{} {} {}".format(c("att", DIM), c("░" * width, DIM), c("--", DIM))
+    # v2: append the most-deviant driver ("one big thing") as a small arrow tag.
+    # effort + autonomy already have their own bars on this line (eff / drv), so the
+    # tag only surfaces an OFF-bar driver (verification / fatigue / flow) - the thing
+    # you would otherwise miss. Absent on v1 rows / live fallback.
+    tag = ""
+    top = a.get("top_driver")
+    drivers = a.get("drivers")
+    if top and top not in ("effort", "autonomy") and isinstance(drivers, dict) and top in drivers:
+        v = drivers[top]
+        arrow = "↑" if v >= 55 else ("↓" if v <= 45 else "·")
+        tag = "  " + c(arrow + top, DIM)
+    return "{} {} {} {} {}{}".format(
+        c("att", DIM),
+        c(bar(a["score"] / 100.0, width), a["color"]),
+        "{:>2d}".format(a["score"]),
+        c(a["glyph"] + " " + a["label"], a["color"]),
+        c("· " + a["nudge"], DIM),
+        tag,
+    )
+
+
+# ---------------------------------------------------------------------------
+# cognition sub-bars (eff / drv) - the two component drivers shown beside the
+# composite attention bar. They read the same per-turn drivers the cc-bridge hook
+# writes; no DB query of their own.
+# ---------------------------------------------------------------------------
+def _driver_pct(a, name):
+    """0..100 for a named v2 driver from the presented attention dict, else None.
+
+    The cc-bridge hook writes the five standardized drivers and the HUD reads them
+    back. Absent on a v1 row / fresh session, where the caller falls back."""
+    drivers = a.get("drivers")
+    if isinstance(drivers, dict):
+        v = drivers.get(name)
+        if isinstance(v, (int, float)):
+            return float(v)
+    return None
+
+
+def effort_pct(a):
+    """The 'eff' bar value (0..100): how hard the human is driving this turn.
+
+    Prefers the v2 effort driver (standardized to your own baseline; 50 == your
+    median). Falls back to the v1 raw 0..1 effort scaled to 0..100 when no driver
+    row exists yet (no hook / fresh session)."""
+    p = _driver_pct(a, "effort")
+    if p is not None:
+        return p
+    v1 = a.get("effort")
+    return float(v1) * 100.0 if isinstance(v1, (int, float)) else None
+
+
+def drive_pct(a):
+    """The 'drv' bar value (0..100): how hands-on you are vs delegating - your share
+    of the wheel. It is the inverse of the autonomy driver (the AI-led ratio: tool
+    activity + thin prompts + long autonomous runs). v2 only - None on a v1 row."""
+    auto = _driver_pct(a, "autonomy")
+    return (100.0 - auto) if auto is not None else None
+
+
+def cog_meter(label, pct, width=COG_BAR_W):
+    """A neutral cognition sub-bar: label + bar + 0..100 value.
+
+    Unlike the usage meters these carry NO good/bad coloring - high effort or low
+    drive are not 'bad' (a clean autonomous run is healthy delegation), so the fill
+    is a flat accent (CYAN) and the read stays descriptive, not a target. Renders a
+    dim '--' when the value is absent (v1 row / fresh session)."""
+    if pct is None:
+        return "{} {} {}".format(c(label, DIM), c("░" * width, DIM), c("--", DIM))
+    return "{} {} {}".format(c(label, DIM), c(bar(pct / 100.0, width), CYAN), f"{pct:>2.0f}")
+
+
+# ---------------------------------------------------------------------------
+# cognition_samples reader (the READ half). The WRITE half lives in the
+# zeno-cc-bridge hook (the event-time writer of the rich v2 rows); the bar is
+# read-only, so the statusline render never writes the store.
+# ---------------------------------------------------------------------------
+def latest_cognition_sample(sid):
+    """Read the most recent persisted cognition_samples row for this session.
+
+    Returns a dict of column->value (the attention_* + token + ts fields) or
+    None when there is no DB, no table, no row for the session, or any error.
+    Read-only and best-effort: it must never slow or break the render. This is
+    the READ half that lets the bar show the exact row the dashboard reads, so
+    the two surfaces can never disagree."""
+    if sid is None:
+        return None
+    try:
+        import sqlite3
+    except Exception:
+        return None
+    if not os.path.exists(ZENO_DB):
+        return None
+    try:
+        con = sqlite3.connect(f"file:{ZENO_DB}?mode=ro", uri=True, timeout=0.3)
+        try:
+            con.row_factory = sqlite3.Row
+            # SELECT * so we pick up the v2 driver columns (attention_autonomy/
+            # verification/fatigue/flow) when present, and still work on a v1 DB
+            # that lacks them (present_sample treats absent drivers as missing).
+            row = con.execute(
+                """
+                SELECT * FROM cognition_samples
+                WHERE session_id = ?
+                ORDER BY ts DESC
+                LIMIT 1
+                """,
+                (sid,),
+            ).fetchone()
+        finally:
+            con.close()
+        return dict(row) if row is not None else None
+    except Exception:
+        return None
+
+
+def attention_for_render(stdin, live_att):
+    """The attention dict the bar should show: prefer the persisted sample so the
+    HUD matches the dashboard exactly, fall back to the live compute when no row
+    exists yet (fresh session, capture disabled, or read failure).
+
+    `live_att` is the freshly computed attention dict (the fallback). When a stored row
+    carries a score, we re-present it through the shared classifier so the rendered bar
+    equals the row a dashboard would draw - identical by construction."""
+    sid = session_id(stdin)
+    row = latest_cognition_sample(sid)
+    if row is not None:
+        # carry the live long-session framing so the nudge band matches; the row
+        # itself does not persist session length.
+        if isinstance(live_att, dict) and live_att.get("nudge") in ("wrap soon", "rest soon"):
+            row = dict(row)
+            row["long_session"] = True
+        # Pick the presenter by what the row actually carries. A v2 row (any of the
+        # four v2 driver columns present) goes through COG.present_sample (drivers +
+        # off-bar tag). A v1-only row (no v2 drivers) goes through A.present_sample,
+        # which scales the legacy 0..1 attention_effort correctly - so eff is right,
+        # not a 0..100 misread of a 0..1 value. Each falls back to the other if the
+        # chosen presenter cannot render the row, then to the live compute.
+        has_v2 = any(
+            isinstance(row.get("attention_" + d), (int, float))
+            for d in ("autonomy", "verification", "fatigue", "flow")
+        )
+        presented = COG.present_sample(row) if has_v2 else A.present_sample(row)
+        if not presented.get("ok"):
+            presented = A.present_sample(row) if has_v2 else COG.present_sample(row)
+        if presented.get("ok"):
+            return presented
+    return live_att
+
+
+# ---------------------------------------------------------------------------
+# the cognition bar (the one differentiated line)
+# ---------------------------------------------------------------------------
+def _bar_widths():
+    """Pick (att_bar_width, cog_bar_width) for the current terminal.
+
+    The ZENO_HUD_*_WIDTH env knobs are the wide-terminal default (att 10, eff/drv 8),
+    and that default is also exactly the COLUMNS-unset behavior - so the bar's output
+    is byte-for-byte the historical `line3` whenever COLUMNS is unset or comfortably
+    wide (the golden regression + determinism hold). When COLUMNS IS set and narrow,
+    the three bars shrink together to a floor of 3 cells so the line stays single-line
+    on a narrow pane; on a wide pane the bars never grow past the knob default and
+    never pad, so there is no overflow or padding garbage. Width is presentation only -
+    the att/eff/drv numbers and labels (the cognition meaning) are unchanged."""
+    att_w, cog_w = ATT_BAR_W, COG_BAR_W
+    cols = os.environ.get("COLUMNS")
+    if not cols:
+        return att_w, cog_w
+    try:
+        cols = int(cols)
+    except (TypeError, ValueError):
+        return att_w, cog_w
+    # at >= 90 cols the default bars + their text fit comfortably; below that, scale
+    # the bars down linearly to a floor so the fill shrinks instead of forcing a wrap.
+    if cols >= 90:
+        return att_w, cog_w
+    scale = max(0.0, (cols - 10)) / 80.0  # 1.0 at 90 cols, ~0.375 at 40, 0 at <=10
+    return max(3, int(round(att_w * scale))), max(3, int(round(cog_w * scale)))
+
+
+def render_bar(stdin):
+    """Render the single differentiated cognition line - the former HUD `line3`.
+
+    Output (one line): the composite attention bar (with its label/nudge and, when
+    notable, the most-deviant OFF-bar driver tag), then the two component sub-bars -
+    effort (how hard you drive) and drive (how hands-on vs delegating). Capped at
+    three bars by design; the session + SCED counters live on the dashboard now.
+
+    This is the renderer shared by the whole-HUD `zeno-hud` (its third line) and the
+    standalone `zeno-hud-bar` add-on, so the two can never diverge. It is READ-ONLY:
+    it reads the latest persisted cognition_samples row (written by the zeno-cc-bridge
+    capture hook) and re-presents it, falling back to a live transcript compute when no
+    row exists yet. The statusline render never writes the store.
+    """
+    prompts, asst = parse_transcript(stdin.get("transcript_path"))
+    live_att = attention(prompts, asst)
+    # READ-only: render the bar from the latest persisted sample (falling back to the
+    # live compute) so the in-terminal HUD shows the exact number the dashboard reads
+    # from the same row - zero divergence by construction. The cc-bridge hook is the
+    # writer; the bar never writes (decision revised 2026-06-26: the bar is pure-read).
+    att = attention_for_render(stdin, live_att)
+    att_w, cog_w = _bar_widths()
+    return "{}    {} · {}".format(
+        attention_meter(stdin, att, att_w),
+        cog_meter("eff", effort_pct(att), cog_w),
+        cog_meter("drv", drive_pct(att), cog_w),
+    )
+
+
+# ---------------------------------------------------------------------------
+# render
+# ---------------------------------------------------------------------------
+def render(stdin):
+    line1_parts = [c("zeno", BOLD)]
+    mn = model_name(stdin)
+    if mn:
+        line1_parts.append(c(mn, DIM))
+    pn = project_name(stdin)
+    if pn:
+        line1_parts.append(c(pn, DIM))
+    eff = effort_level(stdin)
+    if eff:
+        line1_parts.append(c("⚡" + eff, DIM))
+    line1 = c(" · ", DIM).join(line1_parts)
+
+    line2 = "   ".join(
+        [
+            meter("ctx", context_pct(stdin), BAR_W, 70, 85),
+            meter("5h", rate_pct(stdin, "five_hour"), BAR_W, 60, 85),
+            meter("wk", rate_pct(stdin, "seven_day"), BAR_W, 60, 85),
+        ]
+    )
+
+    # the cognition line is the shared bar renderer, so the whole HUD's third line
+    # and the standalone zeno-hud-bar are byte-for-byte identical (the golden
+    # regression). render_bar also owns the throttled cognition_samples write.
+    line3 = render_bar(stdin)
+
+    return "\n".join([line1, line2, line3])
+
+
+def _read_stdin_object():
+    """Read stdin for the bar: return (ok, dict).
+
+    ok is False for the three crash-safe-empty cases - no/empty stdin, malformed
+    JSON, or valid JSON whose top level is not an object - so bar_main prints an
+    empty line. ok is True for any JSON object (even `{}`), where render_bar
+    degrades the missing fields to `--` rather than emitting nothing.
+    """
+    try:
+        raw = sys.stdin.read()
+    except Exception:
+        return False, {}
+    raw = (raw or "").strip()
+    if not raw:
+        return False, {}
+    try:
+        data = json.loads(raw)
+    except Exception:
+        return False, {}
+    if not isinstance(data, dict):
+        return False, {}
+    return True, data
+
+
+def main():
+    try:
+        sys.stdout.write(render(read_stdin()))
+    except Exception:
+        # a statusline must never crash; degrade to the brand mark
+        sys.stdout.write(c("zeno", BOLD))
+    sys.stdout.write("\n")
+
+
+def bar_main():
+    """Entry point for the `zeno-hud-bar` console_script and `zeno hud bar`.
+
+    Crash-safe contract (stricter than main): on ANY error - no/empty stdin,
+    malformed JSON, or an internal failure - print an empty line and exit 0. The
+    bar is an APPENDAGE stacked UNDER the host HUD (claude-hud / ccstatusline), so
+    its failure must never pollute the host's output. main() prints the `zeno`
+    brand mark because it owns the whole statusline; the bar owns only one row, so
+    its fallback is an empty row, not a brand mark.
+    """
+    try:
+        ok, stdin = _read_stdin_object()
+        out = render_bar(stdin) if ok else ""
+    except Exception:
+        out = ""
+    sys.stdout.write(out)
+    sys.stdout.write("\n")
+
+
+if __name__ == "__main__":
+    main()