agent-statusline 0.3.5__py3-none-any.whl

agent_statusline/__init__.py

@@ -0,0 +1,21 @@
+"""A dense, width-aware status line for coding agents.
+
+Layered so that only the acquisition layer is host-specific:
+
+    paths       where machine-local state lives
+    render      colours, units, bars, and the width-fitting row packer
+    transcript  incremental parsing of a session .jsonl
+    probes      cached subprocess/file probes
+    ledger      cross-session cost accounting
+    statusline  the Claude Code status line built from all of the above
+
+`render`, `probes`, `ledger` and `paths` carry no Claude-specific assumptions;
+see docs/PORTING.md.
+"""
+
+try:  # populated by hatch-vcs at build time
+    from ._version import __version__
+except Exception:  # running straight from a checkout
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

agent_statusline/__main__.py

@@ -0,0 +1,8 @@
+"""Expose the console-script interface through ``python -m``."""
+
+import sys
+
+from agent_statusline.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_statusline/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.3.5'
+__version_tuple__ = version_tuple = (0, 3, 5)
+
+__commit_id__ = commit_id = None

agent_statusline/cli.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""`agent-statusline` -- one entry point for rendering, installing, and hooks.
+
+Dispatch is hand-rolled rather than argparse-based, and the no-argument case
+returns before importing anything else it does not need. That case is the hot
+one: Claude Code spawns this process several times a second to redraw, and every
+avoided import is time the status line is not on screen (ADR 0006).
+"""
+import sys
+
+USAGE = """agent-statusline -- a dense, width-aware status line for coding agents
+
+  agent-statusline                     render a status line from a payload on stdin
+  agent-statusline install [--dry-run] wire it into Claude Code's settings.json
+  agent-statusline uninstall           remove the settings entries and symlink
+  agent-statusline hook <name>         run a hook (session-end, context-guard,
+                                       timestamp-user, timestamp-stop)
+  agent-statusline ledger [...]        inspect or close cost-ledger rows
+  agent-statusline selftest            verify rendering using isolated synthetic state
+  agent-statusline version             print the version
+"""
+
+HOOKS = {
+    "session-end": "session_end",
+    "context-guard": "context_guard",
+    "timestamp-user": "timestamp_user",
+    "timestamp-stop": "timestamp_stop",
+}
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    # Hot path: no arguments means render, and nothing else is imported.
+    if not argv:
+        from agent_statusline.statusline import main as render
+
+        render()
+        return 0
+
+    cmd, rest = argv[0], argv[1:]
+
+    if cmd in ("-h", "--help", "help"):
+        print(USAGE)
+        return 0
+
+    if cmd in ("-V", "--version", "version"):
+        from agent_statusline import __version__
+
+        print(__version__)
+        return 0
+
+    if cmd == "render":
+        from agent_statusline.statusline import main as render
+
+        render()
+        return 0
+
+    if cmd in ("install", "uninstall"):
+        from agent_statusline import installer
+
+        unknown = [a for a in rest if a != "--dry-run"]
+        if unknown:
+            print(f"unknown option: {unknown[0]}", file=sys.stderr)
+            return 2
+        return installer.run(dry_run="--dry-run" in rest, uninstall=cmd == "uninstall")
+
+    if cmd == "hook":
+        if not rest or rest[0] not in HOOKS:
+            print(f"usage: agent-statusline hook {{{','.join(HOOKS)}}}", file=sys.stderr)
+            return 2
+        mod = __import__(f"agent_statusline.hooks.{HOOKS[rest[0]]}", fromlist=["main"])
+        return mod.main()
+
+    if cmd == "ledger":
+        from agent_statusline import ledger
+
+        sys.argv = ["agent-statusline ledger", *rest]
+        return ledger._main()
+
+    if cmd == "selftest":
+        if rest:
+            print(f"unknown option: {rest[0]}", file=sys.stderr)
+            return 2
+        from agent_statusline import selftest
+
+        return selftest.run()
+
+    print(f"unknown command: {cmd}\n\n{USAGE}", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_statusline/coerce.py

@@ -0,0 +1,76 @@
+"""Safe numeric coercion at the untrusted host-input boundary.
+
+The host payload and transcript are decoded by the standard-library JSON
+decoder, which accepts non-finite numeric literals.  Keep that handling in one
+small, host-agnostic module so renderers can degrade instead of raising while
+retaining the distinction between fractional measurements and counts.
+"""
+
+import math
+from typing import Any, Union
+
+# Values beyond this boundary cannot produce useful status-line output.  It is
+# comfortably above realistic token/byte/count values while bounding formatting
+# work and avoiding a lossy conversion of arbitrary-size integers to float.
+MAX_DISPLAY_VALUE = 10**15
+Number = Union[int, float]
+
+
+def _valid_default(default: Number) -> Number:
+    """Return a safe numeric default supplied by a caller."""
+    if isinstance(default, bool):
+        return 0
+    if isinstance(default, int):
+        return default if abs(default) <= MAX_DISPLAY_VALUE else 0
+    if isinstance(default, float) and math.isfinite(default) and abs(default) <= MAX_DISPLAY_VALUE:
+        return default
+    return 0
+
+
+def finite_number(value: Any, default: Number = 0.0) -> Number:
+    """Return a bounded finite number, preserving exact integer inputs.
+
+    Numeric strings retain the existing ``float`` acceptance used by the
+    renderer, including surrounding whitespace and exponent notation.  Bool,
+    null, invalid, non-finite, and out-of-bound values return ``default``.
+    """
+    fallback = _valid_default(default)
+    if value is None or isinstance(value, bool):
+        return fallback
+    if isinstance(value, int):
+        return value if abs(value) <= MAX_DISPLAY_VALUE else fallback
+    try:
+        number = float(value)
+    except (TypeError, ValueError, OverflowError):
+        return fallback
+    if not math.isfinite(number) or abs(number) > MAX_DISPLAY_VALUE:
+        return fallback
+    return number
+
+
+def finite_integer(value: Any, default: int = 0) -> int:
+    """Return a bounded finite integer for count-like host values.
+
+    Numeric strings retain the existing ``int`` acceptance.  Finite float
+    inputs retain Python's existing truncation semantics; booleans, null,
+    invalid, non-finite, and out-of-bound values return ``default``.
+    """
+    fallback = _valid_default(default)
+    if not isinstance(fallback, int):
+        fallback = int(fallback)
+    if value is None or isinstance(value, bool):
+        return fallback
+    if isinstance(value, int):
+        return value if abs(value) <= MAX_DISPLAY_VALUE else fallback
+    try:
+        if isinstance(value, float):
+            if not math.isfinite(value) or abs(value) > MAX_DISPLAY_VALUE:
+                return fallback
+            number = int(value)
+        elif isinstance(value, str):
+            number = int(value)
+        else:
+            return fallback
+    except (TypeError, ValueError, OverflowError):
+        return fallback
+    return number if abs(number) <= MAX_DISPLAY_VALUE else fallback

agent_statusline/diagnostics.py

@@ -0,0 +1,21 @@
+"""Privacy-safe diagnostic evidence for failures hidden by the host."""
+
+import datetime
+import json
+
+from agent_statusline.paths import state
+from agent_statusline.storage import write_text
+
+LAST_RENDER_ERROR = state("statusline-last-error.json")
+ERROR_SCHEMA = 1
+
+
+def record_render_failure(error):
+    """Record only fixed and non-sensitive failure metadata."""
+    record = {
+        "schema": ERROR_SCHEMA,
+        "occurred_at": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+        "phase": "render",
+        "error_type": type(error).__name__,
+    }
+    write_text(LAST_RENDER_ERROR, json.dumps(record, sort_keys=True) + "\n")

agent_statusline/hooks/context_guard.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""UserPromptSubmit: warn when the context window is filling up.
+
+Live token usage is read from the transcript's most recent assistant message,
+so it is never stale. Only the window SIZE comes from the status-line payload
+(it is a constant for the session); it falls back to 1M if unavailable.
+"""
+import json
+import os
+import sys
+import time
+
+if __package__ in (None, ""):  # running as a plain script
+    sys.path.insert(
+        0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__))))
+    )
+
+from agent_statusline.paths import state
+from agent_statusline.storage import read_json, write_text
+
+WARN, CRIT = 80, 90
+
+
+def window_size():
+    try:
+        payload = read_json(state("statusline-last-payload.json"), {})
+        return int(payload["context_window"]["context_window_size"])
+    except Exception:
+        return 1_000_000
+
+
+def live_tokens(path):
+    """Last assistant message's usage == current context occupancy."""
+    if not path or not os.path.exists(path):
+        return 0
+    try:
+        with open(path, "rb") as fh:
+            size = os.fstat(fh.fileno()).st_size
+            fh.seek(max(0, size - 400_000))
+            lines = fh.read().split(b"\n")
+    except Exception:
+        return 0
+    for line in reversed(lines):
+        if b'"assistant"' not in line:
+            continue
+        try:
+            u = json.loads(line)["message"]["usage"]
+        except Exception:
+            continue
+        return sum(
+            int(u.get(k) or 0)
+            for k in ("input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens")
+        )
+    return 0
+
+
+def main():
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+    except Exception:
+        payload = {}
+
+    try:
+        write_text(
+            state("hook-lastrun.json"),
+            json.dumps(
+                {
+                    "hook": "UserPromptSubmit",
+                    "at": time.time(),
+                    "iso": time.strftime("%Y-%m-%d %H:%M:%S"),
+                    "session": payload.get("session_id"),
+                }
+            ),
+        )
+    except Exception:
+        pass
+
+    size = window_size()
+    live = live_tokens(payload.get("transcript_path"))
+    if not live or not size:
+        return 0
+    pct = live / size * 100
+    if pct < WARN:
+        return 0
+
+    urgency = "CRITICAL" if pct >= CRIT else "WARNING"
+    human = f"{urgency}: context window {pct:.0f}% full ({live:,} of {size:,} tokens)."
+    print(
+        json.dumps(
+            {
+                "systemMessage": human + " Consider a focused /compact.",
+                "hookSpecificOutput": {
+                    "hookEventName": "UserPromptSubmit",
+                    "additionalContext": (
+                        f"{human} Before continuing, offer the user a focused compaction: propose "
+                        f"`/compact` with a summary instruction naming only what this task still "
+                        f"needs (current decisions, open questions, active file paths, the "
+                        f"immediate next step), and say explicitly what would be dropped. Do not "
+                        f"compact without their approval, and do not repeat this offer if they "
+                        f"have already declined it this session."
+                    ),
+                },
+            }
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_statusline/hooks/session_end.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""SessionEnd: finalize this session's entry in the cost ledger.
+
+Marks the row `state: closed` and stamps an ISO 8601 `closed` time and a
+`reason`, through `ledger.close_session` so the lifecycle is defined in one
+place. Sessions that never reach this hook -- a killed process, a lost daemon --
+are stamped out of band with `agent-statusline ledger close <id> --reason killed`.
+"""
+import json
+import os
+import sys
+
+if __package__ in (None, ""):  # running as a plain script
+    sys.path.insert(
+        0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__))))
+    )
+
+from agent_statusline import ledger
+
+
+def main():
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+    except Exception:
+        payload = {}
+
+    sid = payload.get("session_id")
+    if sid:
+        try:
+            ledger.close_session(
+                sid,
+                payload.get("reason") or payload.get("source") or "end",
+                transcript=payload.get("transcript_path"),
+                create=True,
+            )
+        except Exception:
+            pass
+    print("")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_statusline/hooks/timestamp_stop.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+"""TEMPORARY: stamp the time Claude finished a turn.
+
+Stopgap until the server-side flag `tengu_silk_hinge` enables Claude Code's
+native `showMessageTimestamps`. Delete this hook once timestamps appear
+natively -- see docs/adrs/0015-timestamp-hooks-are-a-stopgap.md.
+"""
+import json
+import sys
+import time
+
+
+def main():
+    try:
+        sys.stdin.read()
+    except Exception:
+        pass
+    print(
+        json.dumps({"systemMessage": time.strftime("[%Y-%m-%d %H:%M:%S]"), "suppressOutput": True})
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_statusline/hooks/timestamp_user.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""TEMPORARY: stamp the time a user prompt was submitted.
+
+Stopgap until the server-side flag `tengu_silk_hinge` enables Claude Code's
+native `showMessageTimestamps`. Delete this hook once timestamps appear
+natively -- see docs/adrs/0015-timestamp-hooks-are-a-stopgap.md.
+"""
+import json
+import sys
+import time
+
+
+def main():
+    try:
+        sys.stdin.read()
+    except Exception:
+        pass
+    print(json.dumps({"systemMessage": time.strftime("[%Y-%m-%d %H:%M:%S]")}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())