hamingja 0.1.0__py3-none-any.whl

hamingja/__init__.py

@@ -0,0 +1,16 @@
+"""hamingja — fail-open partner rails for Codex and Claude Code.
+
+The core question every detector answers is "is this agent flailing rather
+than making progress?" — and the architecture keeps that question separate
+from any particular agent harness:
+
+    core/        normalized event schema + session state + the engine
+    detectors/   pluggable signals (repetition, error-streak, ...) — the rules
+    adapters/    thin per-harness glue (claude_code, generic, ...) — the I/O
+
+Add a guardrail = a new file in detectors/. Add a harness = a new folder in
+adapters/. Guardrail evaluation fails OPEN: internal uncertainty defaults to
+allowing the tool call, never inventing a denial.
+"""
+
+__version__ = "0.1.0"

hamingja/adapters/_jsonl_tail.py

@@ -0,0 +1,76 @@
+"""Shared fail-open tail reader for append-only JSONL session logs.
+
+Both harness quota probes (Codex rollout, Claude transcript) need to read the
+*newest* record from a large, live, append-only JSONL file without parsing the
+whole thing. The consistency rules are identical and safety-critical, so they
+live here once rather than drifting between two copies:
+
+* CHEAP — seek to a bounded window at the tail; never read the body. Grow the
+  window (doubling, up to a cap) only if the caller keeps consuming without
+  finding its record; past the cap, stop (the caller then fails open).
+* CONSISTENT — the file is written by a live process, so a window can start
+  mid-line and the final line can be a partial write. Only lines fully
+  delimited by newlines *inside* the window are trusted: the fragment before
+  the first ``\\n`` (possibly truncated by the window) and the fragment after
+  the last ``\\n`` (possibly an in-flight write) are both discarded.
+
+FAIL-OPEN: any error yields no lines (an empty generator), never raises.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterator
+
+# 64 KiB comfortably covers a normal turn's trailing data; the cap bounds
+# worst-case cost when a giant line precedes the record of interest.
+DEFAULT_INITIAL = 64 * 1024
+DEFAULT_CAP = 2 * 1024 * 1024
+
+
+def iter_complete_lines_reversed(
+    path: Path,
+    initial: int = DEFAULT_INITIAL,
+    cap: int = DEFAULT_CAP,
+) -> Iterator[bytes]:
+    """Yield complete JSONL lines from the tail of ``path``, newest first.
+
+    Grows the read window up to ``cap`` if the caller exhausts it. Callers
+    should stop at the first line they want; the overlap re-yielded on each
+    growth step is bounded by ``cap``.
+    """
+    try:
+        size = path.stat().st_size
+    except Exception:
+        return
+    if size <= 0:
+        return
+
+    window = max(1, int(initial))
+    cap = max(window, int(cap))
+    while True:
+        read_from = max(0, size - window)
+        try:
+            with path.open("rb") as fh:
+                fh.seek(read_from)
+                blob = fh.read(size - read_from)
+        except Exception:
+            return
+
+        parts = blob.split(b"\n")
+        # Final element follows the last newline: an in-flight partial write (or
+        # empty if the file ends in \n). Never trust it.
+        parts = parts[:-1]
+        # If we did not reach the start of the file, the first element may be a
+        # line truncated by the window boundary. Drop it; a wider window
+        # recovers it if needed.
+        reached_start = read_from == 0
+        if not reached_start and parts:
+            parts = parts[1:]
+
+        for raw in reversed(parts):
+            if raw.strip():
+                yield raw
+
+        if reached_start or window >= cap:
+            return
+        window = min(window * 2, cap)

hamingja/adapters/capabilities.py

@@ -0,0 +1,95 @@
+"""Static, versioned runtime capability declarations.
+
+Declarations are promises established by adapter fixtures. Runtime probes may
+downgrade a claim for the current session, but callers must never upgrade one.
+"""
+from __future__ import annotations
+
+from copy import deepcopy
+
+
+_MANIFESTS = {
+    "codex": {
+        "version": 3,
+        "runtime": "codex",
+        "pre_tool_enforcement": "partial",
+        "post_tool_outcomes": "partial",
+        "quota_probe": True,
+        "quota_ttl_seconds": 300,
+        "context_probe": True,
+        "operator_turn_observed": True,
+        "delegation_spawn": True,
+        "delegation_completion": True,
+        "delegation_identity": True,
+        "delegation_lineage": False,
+        "delegation_fallback": "monotonic_grants",
+    },
+    "claude_code": {
+        "version": 3,
+        "runtime": "claude_code",
+        "pre_tool_enforcement": "full",
+        "post_tool_outcomes": "full",
+        "quota_probe": False,
+        "quota_ttl_seconds": None,
+        "context_probe": True,
+        "operator_turn_observed": True,
+        "delegation_spawn": True,
+        "delegation_completion": True,
+        "delegation_identity": True,
+        "delegation_lineage": False,
+        "delegation_fallback": "monotonic_grants",
+    },
+}
+
+
+def manifest(runtime: str, downgrades: dict | None = None) -> dict:
+    """Return a copy of a first-class manifest, with fail-open downgrades only."""
+    try:
+        base = deepcopy(_MANIFESTS[str(runtime)])
+        if not isinstance(downgrades, dict):
+            return base
+        for key, value in downgrades.items():
+            if key not in base or key in {"version", "runtime"}:
+                continue
+            current = base[key]
+            if isinstance(current, bool) and value is False:
+                base[key] = False
+            elif current == "full" and value in {"partial", "none"}:
+                base[key] = value
+            elif current == "partial" and value == "none":
+                base[key] = value
+        return base
+    except Exception:
+        return {}
+
+
+def delegation_observation(runtime: str, payload: object) -> dict | None:
+    """Return only delegation facts the runtime payload actually proves."""
+    try:
+        if not isinstance(payload, dict):
+            return None
+        if runtime in {"codex", "claude_code"} and payload.get("hook_event_name") in {
+            "SubagentStart", "SubagentStop",
+        }:
+            agent_id = payload.get("agent_id")
+            agent_type = payload.get("agent_type")
+            session_id = payload.get("session_id")
+            if (not isinstance(agent_id, str) or not agent_id
+                    or not isinstance(agent_type, str) or not agent_type
+                    or not isinstance(session_id, str) or not session_id):
+                return None
+            return {
+                "event": "spawn" if payload["hook_event_name"] == "SubagentStart" else "complete",
+                "agent_id": agent_id,
+                "agent_type": agent_type,
+                "session_id": session_id,
+                "turn_id": payload.get("turn_id") if isinstance(payload.get("turn_id"), str) else "",
+                "spawn_observed": payload["hook_event_name"] == "SubagentStart",
+                "identity_observed": True,
+                "completion_observed": payload["hook_event_name"] == "SubagentStop",
+                "lineage_observed": False,
+                "enforcement": "session_concurrency_advisory",
+            }
+        return None
+    except Exception:
+        return None

hamingja/adapters/claude_code/__init__.py

@@ -0,0 +1,4 @@
+"""Claude Code adapter and its tested capability declaration."""
+from ..capabilities import manifest
+
+CAPABILITIES = manifest("claude_code")

hamingja/adapters/claude_code/install.sh

@@ -0,0 +1,182 @@
+#!/usr/bin/env bash
+#
+# Install the hamingja Claude Code adapter into your global settings.json.
+#
+# Registers:
+#   PreToolUse        -> tripwire.py  (allow / nudge / block)
+#   PostToolUse       -> record.py    (record success, heuristic fallback)
+#   PostToolUseFailure-> record.py    (record failure, authoritative)
+#   SubagentStart/Stop-> delegation.py (identity + active-child lifecycle)
+#   UserPromptSubmit  -> operator_turn.py (prompt-free operator recency)
+# all for matcher "*".
+#
+# Behavior:
+#   * MERGES into existing settings (never overwrites); preserves other hooks.
+#   * Idempotent AND self-healing: an existing entry that references our script
+#     (matched by basename) is UPDATED in place, so moving/renaming the repo
+#     refreshes the path instead of leaving a dead duplicate.
+#   * Backs up settings ONLY when a change is actually written (no backup litter
+#     on no-op re-runs).
+#   * Default detector mode is "observe"; operator resource authority is
+#     configured separately.
+#
+# Override the settings path with CLAUDE_SETTINGS=/path/to/settings.json.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+SETTINGS="${CLAUDE_SETTINGS:-$HOME/.claude/settings.json}"
+PRE="$REPO_ROOT/hamingja/adapters/claude_code/tripwire.py"
+POST="$REPO_ROOT/hamingja/adapters/claude_code/record.py"
+LIFECYCLE="$REPO_ROOT/hamingja/adapters/delegation.py"
+OPERATOR="$REPO_ROOT/hamingja/adapters/operator_turn.py"
+
+PYBIN="${HAMINGJA_PYTHON:-}"
+if [ -z "$PYBIN" ]; then
+    PYBIN="$(command -v python3 || command -v python || true)"
+fi
+if [ -z "$PYBIN" ]; then
+    echo "error: python3 not found on PATH" >&2
+    exit 1
+fi
+
+case "$PYBIN" in
+    */shims/*|*/.venv/*|*/venv/*|*/conda/*|*/envs/*|*/miniconda*|*/anaconda*)
+        echo "warning: python interpreter '$PYBIN' looks like a pyenv/venv/conda shim." >&2
+        echo "         If that environment is changed or removed, the hooks silently stop" >&2
+        echo "         working (they fail open). Consider a stable system python." >&2
+        ;;
+esac
+
+mkdir -p "$(dirname "$SETTINGS")"
+[ -f "$SETTINGS" ] || echo '{}' > "$SETTINGS"
+
+BACKUP="$SETTINGS.bak.$(date +%s).$$"
+cp "$SETTINGS" "$BACKUP"
+
+set +e
+RESULT="$("$PYBIN" - "$SETTINGS" "$PRE" "$POST" "$LIFECYCLE" "$OPERATOR" "$PYBIN" <<'PY'
+import json, os, shlex, sys, tempfile
+
+settings_path, pre, post, lifecycle, operator, pybin = sys.argv[1:7]
+settings_path = os.path.realpath(settings_path)
+
+try:
+    with open(settings_path, encoding="utf-8") as fh:
+        cfg = json.load(fh)
+except Exception as exc:
+    print(f"error: refusing to modify malformed settings: {exc}", file=sys.stderr)
+    raise SystemExit(2)
+if not isinstance(cfg, dict):
+    print("error: refusing to modify settings whose top level is not an object", file=sys.stderr)
+    raise SystemExit(2)
+
+before = json.dumps(cfg, sort_keys=True)
+
+hooks = cfg.get("hooks")
+if hooks is None:
+    hooks = {}
+    cfg["hooks"] = hooks
+elif not isinstance(hooks, dict):
+    print("error: refusing to modify settings whose hooks field is not an object", file=sys.stderr)
+    raise SystemExit(2)
+
+
+def quote(p):
+    return '"' + p.replace('\\', '\\\\').replace('"', '\\"') + '"'
+
+
+def owns_command(value, base):
+    try:
+        parts = shlex.split(str(value))
+    except ValueError:
+        return False
+    return any(
+        os.path.basename(part) == base
+        and any(
+            owned in part.replace("\\", "/")
+            for owned in ("hamingja/adapters/", "agent_rails/adapters/")
+        )
+        for part in parts
+    )
+
+
+def upsert(event, script):
+    cmd = quote(pybin) + " " + quote(script)
+    base = os.path.basename(script)
+    entries = hooks.get(event)
+    if entries is None:
+        entries = []
+        hooks[event] = entries
+    elif not isinstance(entries, list):
+        print(f"error: refusing to replace malformed {event} hooks", file=sys.stderr)
+        raise SystemExit(2)
+    # refresh any existing entry that references our script (by basename)
+    for matcher_obj in entries:
+        if not isinstance(matcher_obj, dict):
+            continue
+        hk = matcher_obj.get("hooks")
+        if not isinstance(hk, list):
+            continue
+        for h in hk:
+            if not isinstance(h, dict):
+                continue
+            if owns_command(h.get("command", ""), base):
+                h["command"] = cmd
+                h["type"] = "command"
+                return
+    entries.append({"matcher": "*", "hooks": [{"type": "command", "command": cmd}]})
+
+
+upsert("PreToolUse", pre)
+upsert("PostToolUse", post)
+upsert("PostToolUseFailure", post)
+upsert("SubagentStart", lifecycle)
+upsert("SubagentStop", lifecycle)
+upsert("UserPromptSubmit", operator)
+
+after = json.dumps(cfg, sort_keys=True)
+if after == before:
+    print("UNCHANGED")
+else:
+    directory = os.path.dirname(settings_path) or "."
+    fd, temporary = tempfile.mkstemp(prefix=".hamingja-install-", dir=directory)
+    try:
+        os.fchmod(fd, os.stat(settings_path).st_mode & 0o7777)
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(cfg, fh, indent=2)
+            fh.write("\n")
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(temporary, settings_path)
+    except Exception:
+        try:
+            os.unlink(temporary)
+        except OSError:
+            pass
+        raise
+    print("CHANGED")
+PY
+)"
+RC=$?
+set -e
+if [ "$RC" -ne 0 ]; then
+    if [ "$RC" -eq 2 ]; then
+        rm -f "$BACKUP"
+    else
+        echo "backup preserved after installer failure: $BACKUP" >&2
+    fi
+    exit "$RC"
+fi
+
+if [ "$RESULT" = "CHANGED" ]; then
+    echo "updated:  $SETTINGS"
+    echo "backup:   $BACKUP"
+else
+    rm -f "$BACKUP"
+    echo "no change: $SETTINGS already up to date"
+fi
+
+echo "detectors: observe by default (operator resource authority is separate)"
+echo
+echo "Opt out per repo: touch .hamingja-off in that project's root."
+echo "Uninstall: hamingja uninstall claude"

hamingja/adapters/claude_code/quota.py

@@ -0,0 +1,150 @@
+"""Claude Code quota probe — context-fill from the session transcript.
+
+Unlike Codex, Claude Code does **not** persist a rate-limit used-percent to disk
+(that lives on API response headers). The transcript
+(``~/.claude/projects/<encoded-cwd>/<session_id>.jsonl``) does carry, per
+assistant message, a ``usage`` block:
+
+    "usage": {"input_tokens": ..., "cache_read_input_tokens": ...,
+              "cache_creation_input_tokens": ..., "output_tokens": ...}
+
+So the one real signal we can recover is **context occupancy** — how full the
+model's context window is — which is itself a top CLI cost (a bloated context is
+re-sent every turn). We therefore populate only ``context_used_pct``;
+``window_used_pct`` / ``weekly_used_pct`` stay None, which means this reading can
+*nudge* on context fill but never grants checkpoint relief (that requires the
+rate-limit signal Codex has and Claude does not).
+
+Two honest limitations, both fail-safe:
+
+* The transcript does not record the context-window *size* (Codex hands us
+  ``model_context_window``; Claude does not), so occupancy is estimated against
+  a configurable denominator (``context_window_tokens``, default 200000). An
+  over-large real window merely under-reports fill; it never over-blocks,
+  because context fill only ever produces an advisory nudge.
+* We read the newest completed assistant turn; the in-flight turn is not yet
+  written. That is the right granularity for an advisory.
+
+FAIL-OPEN: every path returns None on any error, missing file, or missing field.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+from .._jsonl_tail import iter_complete_lines_reversed
+
+# Shared QuotaReading so the budget gate sees one harness-neutral shape.
+from ..codex.quota import QuotaReading
+
+_DEFAULT_CONTEXT_WINDOW = 200_000
+
+
+def _claude_home() -> Path:
+    return Path(os.environ.get("CLAUDE_CONFIG_DIR") or (Path.home() / ".claude"))
+
+
+def _find_transcript(session_id: str, home: Path, cwd: Optional[str]) -> Optional[Path]:
+    """Locate the transcript for a session id. Returns the newest match.
+
+    Transcripts are ``<session_id>.jsonl`` under a per-project directory. We glob
+    by session id (unique) rather than reconstruct the cwd path-encoding, which
+    is brittle. ``cwd`` is accepted for future narrowing but not required.
+    """
+    try:
+        sid = str(session_id).strip()
+        if not sid:
+            return None
+        projects = home / "projects"
+        if not projects.is_dir():
+            return None
+        matches = list(projects.glob(f"*/{sid}.jsonl"))
+        if not matches:
+            return None
+        if len(matches) == 1:
+            return matches[0]
+        return max(matches, key=lambda p: p.stat().st_mtime)
+    except Exception:
+        return None
+
+
+def _as_int(v) -> Optional[int]:
+    if isinstance(v, bool) or not isinstance(v, (int, float)):
+        return None
+    return int(v)
+
+
+def _context_pct(usage: dict, window: int) -> Optional[float]:
+    """Estimate context occupancy from an assistant usage block. None if unusable.
+
+    Occupancy is the input side of the request — the whole prompt the model saw:
+    fresh input + cache-read + cache-creation tokens. output_tokens is the new
+    completion (folded into the *next* turn's input, negligible here).
+    """
+    if not isinstance(usage, dict) or not window or window <= 0:
+        return None
+    total = 0
+    seen = False
+    for key in ("input_tokens", "cache_read_input_tokens", "cache_creation_input_tokens"):
+        v = _as_int(usage.get(key))
+        if v is not None:
+            total += max(0, v)
+            seen = True
+    if not seen:
+        return None
+    return max(0.0, min(100.0, 100.0 * total / window))
+
+
+def read_quota(
+    session_id: str,
+    cwd: Optional[str] = None,
+    context_window_tokens: int = _DEFAULT_CONTEXT_WINDOW,
+    home: Optional[Path] = None,
+) -> Optional[QuotaReading]:
+    """Return a context-fill QuotaReading for a Claude session, or None. Fail-open.
+
+    Tails the session transcript for the newest assistant message carrying a
+    ``usage`` block and reports ``context_used_pct``. ``window_used_pct`` /
+    ``weekly_used_pct`` are always None (Claude does not persist them).
+    """
+    try:
+        base = home or _claude_home()
+        path = _find_transcript(session_id, base, cwd)
+        if path is None:
+            return None
+        try:
+            window = int(context_window_tokens)
+        except (TypeError, ValueError):
+            window = _DEFAULT_CONTEXT_WINDOW
+        if window <= 0:
+            window = _DEFAULT_CONTEXT_WINDOW
+
+        for raw in iter_complete_lines_reversed(path):
+            # Cheap pre-filter before json.loads: only assistant usage lines
+            # matter. Skips large tool-result records.
+            if b"usage" not in raw:
+                continue
+            try:
+                obj = json.loads(raw)
+            except Exception:
+                continue
+            if not isinstance(obj, dict):
+                continue
+            message = obj.get("message")
+            if not isinstance(message, dict):
+                continue
+            usage = message.get("usage")
+            pct = _context_pct(usage, window) if isinstance(usage, dict) else None
+            if pct is not None:
+                return QuotaReading(
+                    window_used_pct=None,
+                    weekly_used_pct=None,
+                    context_used_pct=pct,
+                    plan_type=None,
+                    source="claude-transcript",
+                )
+        return None
+    except Exception:
+        return None

hamingja/adapters/claude_code/record.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Claude Code recorder — records the outcome of each tool call.
+
+Wired as BOTH:
+  * PostToolUse        -> the call succeeded (record OK), with a payload
+                          heuristic fallback in case a failure is delivered here
+  * PostToolUseFailure -> the call failed (record ERROR), authoritative
+
+Detecting errors by the EVENT is deterministic; the per-tool shape of the
+result payload is undocumented, so we don't rely on parsing it. The heuristic
+below is only a best-effort fallback for harness versions that route a failure
+through PostToolUse.
+
+It never blocks anything and always exits 0 — recording is pure observation.
+Recording also honors mode=off / .hamingja-off (handled in core.api.record),
+so an opted-out repo stays fully inert.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+# make `hamingja` importable when run as a standalone hook script
+sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
+
+from hamingja.core.api import record  # noqa: E402
+from hamingja.adapters.progress import record_workflow_progress  # noqa: E402
+from hamingja.adapters.framework_progress import record_framework_progress  # noqa: E402
+
+
+def _looks_like_error(result) -> bool:
+    """Best-effort fallback error detection from an undocumented result shape."""
+    if isinstance(result, dict):
+        if result.get("is_error") is True:
+            return True
+        if result.get("success") is False:
+            return True
+        err = result.get("error")
+        if isinstance(err, str) and err.strip():
+            return True
+        if err is True:
+            return True
+    return False
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        return 0  # fail-open: unparseable payload, record nothing
+
+    try:
+        event = str(payload.get("hook_event_name", ""))
+        session_id = str(payload.get("session_id", "default"))
+        tool = str(payload.get("tool_name", "unknown"))
+        tool_input = payload.get("tool_input", {})
+        cwd = payload.get("cwd")
+
+        result = payload.get("tool_response", payload.get("tool_output"))
+        if event == "PostToolUseFailure":
+            ok = False  # authoritative: this event only fires on failure
+        else:
+            ok = not _looks_like_error(result)
+
+        record(session_id, tool, tool_input, ok, project_dir=cwd, output=result)
+        record_workflow_progress(session_id, tool, tool_input, result, project_dir=cwd)
+        record_framework_progress(session_id, tool, tool_input, result, project_dir=cwd, ok=ok)
+    except Exception:
+        pass  # never let recording surface an error to the agent
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())