@litfamily/lithermes 1.0.0

package/assets/lithermes-plugin/plugin.yaml

@@ -0,0 +1,16 @@
+name: lithermes
+version: 1.0.0
+description: "Hermes-native workflow toolkit: litgoal durable runtime, 5-lane review orchestrator, Litwork commands, skills, and prompt steering."
+author: "Hermes Agent"
+kind: standalone
+auto_load: true
+hooks:
+  - on_session_start
+  - pre_llm_call
+  - pre_tool_call
+  - post_tool_call
+  - post_api_request
+  - subagent_stop
+  - transform_llm_output
+  - on_session_finalize
+  - on_session_reset

package/assets/lithermes-plugin/provider_metrics.py

@@ -0,0 +1,161 @@
+"""Local-only numeric provider receipt measurements.
+
+Hermes exposes a sanitized ``post_api_request`` observer payload.  This module
+uses only its runtime labels and normalized numeric ``usage`` buckets; request,
+response, prompt, transcript, URL, and credential fields are deliberately
+ignored.  A zero cache counter is not treated as a cache miss because some
+providers do not report cache details at all.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+from collections.abc import Mapping
+from typing import Any
+
+try:
+    from .core_runtime import record_event
+    from .redaction import redact_text
+except (ImportError, ModuleNotFoundError):
+    from core_runtime import record_event
+    from redaction import redact_text
+
+
+SCHEMA = "lithermes.provider-cache/v1"
+HOOK = "post_api_request"
+RECEIPT_FIELDS = (
+    "input_tokens",
+    "output_tokens",
+    "prompt_tokens",
+    "total_tokens",
+    "reasoning_tokens",
+    "cache_read_tokens",
+    "cache_write_tokens",
+)
+
+
+def capability_report() -> dict[str, Any]:
+    """Return the host capability and the honest live-measurement boundary."""
+    return {
+        "state": "CAPABLE",
+        "surface": HOOK,
+        "receipt_fields": list(RECEIPT_FIELDS),
+        "storage": "local-only numeric event ledger",
+        "live_measurement": "UNPROVEN",
+        "reason": "a provider receipt must arrive before a cache hit is claimed",
+        "raw_payloads": "ignored",
+    }
+
+
+def capability_line() -> str:
+    """Render a short status/doctor line without claiming a live cache hit."""
+    return (
+        "provider cache metrics: CAPABLE (Hermes post_api_request usage receipt; "
+        "local numeric ledger only); live cache hit: UNPROVEN until a receipt arrives"
+    )
+
+
+def _value(source: Any, key: str) -> Any:
+    if isinstance(source, Mapping):
+        return source.get(key)
+    try:
+        return getattr(source, key)
+    except Exception:
+        return None
+
+
+def _nonnegative_int(value: Any) -> int | None:
+    """Accept only finite, non-negative integer-shaped usage values."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value if value >= 0 else None
+    if isinstance(value, float):
+        if not math.isfinite(value) or not value.is_integer() or value < 0:
+            return None
+        return int(value)
+    if isinstance(value, str) and re.fullmatch(r"[0-9]+", value.strip()):
+        return int(value.strip())
+    return None
+
+
+def _label_digest(value: Any) -> str | None:
+    """Keep provider/model labels joinable without persisting their raw text."""
+    text = redact_text(str(value or "")).strip()
+    if not text or "[REDACTED_SECRET]" in text:
+        return None
+    return hashlib.sha256(text.encode("utf-8", "replace")).hexdigest()[:16]
+
+
+def _measurement(kwargs: Mapping[str, Any]) -> dict[str, Any]:
+    usage = kwargs.get("usage")
+    raw_values = (
+        {field: _value(usage, field) for field in RECEIPT_FIELDS}
+        if usage is not None
+        else {}
+    )
+    values = {field: _nonnegative_int(raw_values.get(field)) for field in RECEIPT_FIELDS}
+    cache_read = values["cache_read_tokens"]
+    cache_write = values["cache_write_tokens"]
+    prompt = values["prompt_tokens"]
+    if prompt is None:
+        input_tokens = values["input_tokens"]
+        if input_tokens is not None and cache_read is not None and cache_write is not None:
+            prompt = input_tokens + cache_read + cache_write
+            values["prompt_tokens"] = prompt
+
+    result: dict[str, Any] = {
+        "schema": SCHEMA,
+        "measurement_status": "UNPROVEN",
+        "cache_state": "unknown",
+        "cache_hit_ratio": None,
+        "receipt_fields_present": bool(usage is not None),
+        "provider_sha256_16": _label_digest(kwargs.get("provider")),
+        "model_sha256_16": _label_digest(kwargs.get("model")),
+        "api_mode_sha256_16": _label_digest(kwargs.get("api_mode")),
+    }
+    result.update({field: value for field, value in values.items() if value is not None})
+
+    if usage is None:
+        result["reason"] = "provider usage receipt unavailable"
+        return result
+    missing = [
+        field
+        for field in ("cache_read_tokens", "cache_write_tokens")
+        if values[field] is None
+    ]
+    if missing:
+        result["reason"] = "provider usage receipt missing: " + ", ".join(missing)
+        return result
+    if cache_read is not None and cache_read > 0:
+        result["measurement_status"] = "MEASURED"
+        result["cache_state"] = "hit"
+        if prompt and prompt > 0:
+            result["cache_hit_ratio"] = cache_read / prompt
+        return result
+    if cache_write is not None and cache_write > 0:
+        result["measurement_status"] = "MEASURED"
+        result["cache_state"] = "write_only"
+        result["reason"] = "cache write reported; no positive cache read in this receipt"
+        return result
+    result["reason"] = "zero cache counters are not treated as a provider cache miss"
+    return result
+
+
+def post_api_request(**kwargs: Any) -> None:
+    """Append one bounded numeric receipt; never retain raw hook payloads."""
+    measurement = _measurement(kwargs)
+    record_event("provider_cache_measurement", **measurement)
+    return None
+
+
+__all__ = [
+    "HOOK",
+    "RECEIPT_FIELDS",
+    "SCHEMA",
+    "capability_line",
+    "capability_report",
+    "post_api_request",
+]

package/assets/lithermes-plugin/redaction.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+from urllib.parse import urlsplit
+
+
+_KEY_VALUE_RE = re.compile(
+    r"(?i)(?<![A-Z0-9_.-])("
+    r"[\"']?[A-Z0-9_.-]*(?:api[_-]?key|access[_-]?token|secret[_-]?access[_-]?key|private[_-]?key|database[_-]?url|authorization|password|token|secret)[A-Z0-9_.-]*[\"']?"
+    r"\s*[=:]\s*(?:(?:basic|bearer|token)\s+)?[\"']?)([^\s,;\"'}]+)([\"']?)"
+)
+_SENSITIVE_KEY_FRAGMENTS = (
+    "apikey",
+    "accesskey",
+    "accesstoken",
+    "secretaccesskey",
+    "privatekey",
+    "databaseurl",
+    "authorization",
+    "password",
+    "token",
+    "secret",
+)
+
+_URI_PATTERN = re.compile(r"(?i)(?<![A-Z0-9])((?:[A-Z][A-Z0-9+.-]*:)?//[^\s<>\"']+)")
+
+_SECRET_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = (
+    (
+        re.compile(
+            r"(?im)(?<![A-Z0-9_.-])((?:proxy-)?authorization)\s*:[ \t]*([^\r\n]*\S[^\r\n]*)"
+        ),
+        r"\1: [REDACTED_SECRET]",
+    ),
+    (
+        re.compile(r"(?i)\b(?:basic|bearer)\s+[A-Za-z0-9+/=_-]{8,}\b"),
+        "[REDACTED_SECRET]",
+    ),
+    (
+        re.compile(
+            r"-----BEGIN(?: [A-Z0-9]+)* PRIVATE KEY(?: BLOCK)?-----"
+            r"[\s\S]*?"
+            r"(?:-----END(?: [A-Z0-9]+)* PRIVATE KEY(?: BLOCK)?-----|$)",
+            re.IGNORECASE,
+        ),
+        "[REDACTED_SECRET]",
+    ),
+    (
+        re.compile(r"\b(sk-[A-Za-z0-9_-]{8,})\b"),
+        "[REDACTED_SECRET]",
+    ),
+    (
+        re.compile(r"\b((?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{8,})\b"),
+        "[REDACTED_SECRET]",
+    ),
+    (
+        re.compile(r"(?i)\bgithub_pat_[A-Za-z0-9_]{16,}\b"),
+        "[REDACTED_SECRET]",
+    ),
+    (
+        re.compile(r"\b(?:AKIA|ASIA|AIDA)[0-9A-Z]{12,}\b"),
+        "[REDACTED_SECRET]",
+    ),
+    (
+        re.compile(r"\b(?:xox[baprs]|xapp)-[A-Za-z0-9-]{8,}\b"),
+        "[REDACTED_SECRET]",
+    ),
+    (
+        re.compile(r"\bnpm_[A-Za-z0-9_-]{8,}\b"),
+        "[REDACTED_SECRET]",
+    ),
+    (
+        re.compile(r"(?i)\bwhsec_[A-Za-z0-9]{16,}\b"),
+        "[REDACTED_SECRET]",
+    ),
+    (
+        re.compile(r"(?i)\b[A-Za-z][A-Za-z0-9+.-]*://[^/\s:@]+:[^@\s]+@[^ \t\r\n]+"),
+        "[REDACTED_SECRET]",
+    ),
+    (
+        re.compile(r"\bAIza[0-9A-Za-z_-]{20,}\b"),
+        "[REDACTED_SECRET]",
+    ),
+    (
+        re.compile(r"\bhf_[A-Za-z0-9_-]{20,}\b"),
+        "[REDACTED_SECRET]",
+    ),
+    (
+        re.compile(r"\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}\b"),
+        "[REDACTED_SECRET]",
+    ),
+    (
+        re.compile(r"\bglpat-[A-Za-z0-9_-]{8,}\b"),
+        "[REDACTED_SECRET]",
+    ),
+    (
+        re.compile(r"\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b"),
+        "[REDACTED_SECRET]",
+    ),
+)
+
+
+def _redact_key_value(match: re.Match[str]) -> str:
+    key = match.group(1)
+    normalized = re.sub(r"[^a-z0-9]", "", key.lower())
+    if any(fragment in normalized for fragment in _SENSITIVE_KEY_FRAGMENTS):
+        return f"{key}[REDACTED_SECRET]{match.group(3)}"
+    return match.group(0)
+
+
+def _redact_uri_userinfo(match: re.Match[str]) -> str:
+    candidate = match.group(1)
+    try:
+        parsed = urlsplit(candidate)
+    except ValueError:
+        if "@" in candidate:
+            return "[REDACTED_SECRET]"
+        return candidate
+    if "@" in parsed.netloc:
+        return "[REDACTED_SECRET]"
+    return candidate
+
+
+def redact_text(value: str) -> str:
+    """Best-effort redaction before user text is persisted or re-injected.
+
+    This is intentionally conservative and local: it catches common bearer-token,
+    key/value, OpenAI-style, GitHub-style, and AWS-style secrets without trying to
+    classify every high-entropy string as a secret.
+    """
+    text = str(value or "")
+    for pattern, replacement in _SECRET_PATTERNS:
+        text = pattern.sub(replacement, text)
+    text = _KEY_VALUE_RE.sub(_redact_key_value, text)
+    text = _URI_PATTERN.sub(_redact_uri_userinfo, text)
+    return text
+
+
+def redact_obj(value: Any) -> Any:
+    if isinstance(value, str):
+        return redact_text(value)
+    if isinstance(value, list):
+        return [redact_obj(item) for item in value]
+    if isinstance(value, tuple):
+        return tuple(redact_obj(item) for item in value)
+    if isinstance(value, dict):
+        return {key: redact_obj(item) for key, item in value.items()}
+    return value

package/assets/lithermes-plugin/rules/__init__.py

@@ -0,0 +1,55 @@
+"""LitHermes repo-rule engine.
+
+Public surface consumed by core.py. Everything else in this package is internal.
+"""
+
+from __future__ import annotations
+
+from .constants import (
+    DEFAULT_MAX_RESULT_CHARS,
+    DEFAULT_MAX_RULE_CHARS,
+    DYNAMIC_MAX_RESULT_CHARS,
+    DYNAMIC_MAX_RULE_CHARS,
+    POST_COMPACT_MAX_RESULT_CHARS,
+    POST_COMPACT_MAX_RULE_CHARS,
+    SOURCE_PRIORITY,
+)
+from .discovery import find_candidates, find_project_root, path_bases
+from .engine import (
+    begin_session,
+    consume_compaction_budget,
+    dynamic_rules_block,
+    end_session,
+    history_was_compacted,
+    load_rule,
+    match_rule,
+    sort_candidates,
+    static_rules_block,
+)
+from .frontmatter import parse_rule
+from .globmatch import DIVERGENCES, matches
+
+__all__ = [
+    "DEFAULT_MAX_RESULT_CHARS",
+    "DEFAULT_MAX_RULE_CHARS",
+    "DIVERGENCES",
+    "DYNAMIC_MAX_RESULT_CHARS",
+    "DYNAMIC_MAX_RULE_CHARS",
+    "POST_COMPACT_MAX_RESULT_CHARS",
+    "POST_COMPACT_MAX_RULE_CHARS",
+    "SOURCE_PRIORITY",
+    "begin_session",
+    "consume_compaction_budget",
+    "dynamic_rules_block",
+    "end_session",
+    "find_candidates",
+    "find_project_root",
+    "history_was_compacted",
+    "load_rule",
+    "match_rule",
+    "matches",
+    "parse_rule",
+    "path_bases",
+    "sort_candidates",
+    "static_rules_block",
+]

package/assets/lithermes-plugin/rules/bundled-rules/baseline-discipline.md

@@ -0,0 +1,20 @@
+---
+description: Baseline LitHermes working discipline that applies to every repository.
+alwaysApply: true
+---
+
+# Baseline discipline
+
+- Restate the completion promise before changing files. Vague goals produce vague
+  verdicts.
+- Preserve unrelated worktree changes. Never revert, stash, or reformat work you
+  did not author in this session.
+- Never run destructive git commands (`reset --hard`, `clean -fd`, force-push) or
+  stage, commit, tag, publish, or bump a version without an explicit request from
+  the current user in this turn.
+- Tests alone never prove done. Run the real surface once and capture the artifact
+  path, then tear down every artifact the run spawned and record a cleanup receipt.
+- A gate you did not run is not green. Paste the command and its actual output;
+  never describe a red or unrun gate as passing.
+- If an instruction and this rule conflict, the current user wins — but say which
+  rule you are setting aside and why.

package/assets/lithermes-plugin/rules/bundled-rules/build-decision-gate.md

@@ -0,0 +1,19 @@
+---
+description: Minimum-first build decision gate applied before writing new code.
+alwaysApply: true
+---
+
+# Build decision gate
+
+Before writing a new abstraction, ask in order:
+
+1. Does this work need to exist at all? Delete the requirement before building it.
+2. Does the repository already do this? Reuse beats re-implementation.
+3. Does the standard library or a native Hermes surface already do this? Prefer it
+   over a hand-rolled version and over a new dependency.
+4. Is one clear line enough? Prefer it to a configurable helper.
+
+Minimum-first constrains how much code each item costs. It never licenses
+delivering less of the request than was asked for: the smallest *complete*
+solution still includes the shared helpers, validation, security, accessibility,
+realistic error handling, and regression tests the criteria require.

package/assets/lithermes-plugin/rules/bundled-rules/windows-git-bash.md

@@ -0,0 +1,17 @@
+---
+description: Shell expectations when Hermes runs on Windows under Git Bash.
+alwaysApply: true
+---
+
+# Windows / Git Bash
+
+This rule is bundled but only discovered when the host platform is Windows.
+
+- Assume Git Bash, not PowerShell or `cmd.exe`. POSIX path separators and quoting
+  apply; do not emit `%VAR%` or backtick-escaped PowerShell.
+- Paths reaching tools may arrive as `C:\...`. Normalize to `/c/...` for shell
+  commands and keep `/`-separated paths in any file you write.
+- `&&` and `||` work; `;` between commands works. PowerShell-only builtins
+  (`Get-ChildItem`, `Select-String`) do not exist here.
+- Line endings: write LF. A tool that rewrites a file to CRLF creates a diff the
+  user did not ask for.

package/assets/lithermes-plugin/rules/constants.py

@@ -0,0 +1,122 @@
+"""Discovery tables, ordering priorities, and injection budgets for the rules engine.
+
+Values are ported from the reference rules component (`src/rules/constants.ts` in
+the sibling product) except where a table names a Hermes-native surface instead;
+each such change is noted inline so a reviewer can tell a port from an invention.
+
+Two source ids are assembled from fragments rather than written as literals. The
+repo-wide token scanner blocks the sibling product brands in every packed
+surface, and `diagnostics.py` already builds its runtime stem the same way. These
+are real directory names a user may genuinely have, so they are supported; the
+assembly is the repo's existing convention, not concealment.
+"""
+
+from __future__ import annotations
+
+# Walk UP from the start directory until a directory contains one of these.
+PROJECT_MARKERS = (
+    ".git",
+    "pnpm-workspace.yaml",
+    "package.json",
+    "pyproject.toml",
+    "Cargo.toml",
+    "go.mod",
+    ".venv",
+)
+
+# (parent directory under an anchor, subdirectory scanned recursively).
+# ".lit" + the sibling product's stem — see the module docstring.
+_SIBLING_DIR = ".lit" + "".join(("co", "dex"))
+_SIBLING_HOME_DIR = "." + "".join(("open", "code"))
+
+PROJECT_RULE_SUBDIRS = (
+    (".lithermes", "rules"),
+    (_SIBLING_DIR, "rules"),
+    (".claude", "rules"),
+    (".cursor", "rules"),
+    (".github", "instructions"),
+)
+
+# Single-file project rules: frontmatter optional, they always apply.
+PROJECT_SINGLE_FILES = (".github/copilot-instructions.md", "CONTEXT.md")
+
+# User-home rule directories. LitHermes substitutes its own product directory and
+# the Hermes host home for the reference's two sibling-product entries; the Hermes
+# entry resolves through HERMES_HOME so an isolated probe never reads a live profile.
+USER_HOME_LITHERMES = ".lithermes/rules"
+USER_HOME_CLAUDE = ".claude/rules"
+HERMES_HOME_RULES = "rules"
+
+BUNDLED_RULE_SUBDIR = "bundled-rules"
+# Discovered only when the host platform is Windows (reference: win32 filter).
+WINDOWS_ONLY_BUNDLED_RULE = "windows-git-bash.md"
+RULE_FILE_EXTENSIONS = (".md", ".mdc")
+
+SOURCE_LITHERMES_RULES = ".lithermes/rules"
+SOURCE_SIBLING_RULES = _SIBLING_DIR + "/rules"
+SOURCE_CLAUDE_RULES = ".claude/rules"
+SOURCE_CURSOR_RULES = ".cursor/rules"
+SOURCE_GITHUB_INSTRUCTIONS = ".github/instructions"
+SOURCE_COPILOT_INSTRUCTIONS = ".github/copilot-instructions.md"
+SOURCE_CONTEXT_MD = "CONTEXT.md"
+SOURCE_HOME_LITHERMES = "~/.lithermes/rules"
+SOURCE_HOME_HERMES = "$HERMES_HOME/rules"
+SOURCE_HOME_CLAUDE = "~/.claude/rules"
+SOURCE_BUNDLED = "plugin-bundled"
+
+# Lower sorts earlier. Project sources beat user-home sources; bundled rules last.
+SOURCE_PRIORITY = {
+    SOURCE_LITHERMES_RULES: 0,
+    SOURCE_SIBLING_RULES: 1,
+    SOURCE_CLAUDE_RULES: 2,
+    SOURCE_CURSOR_RULES: 3,
+    SOURCE_GITHUB_INSTRUCTIONS: 4,
+    SOURCE_COPILOT_INSTRUCTIONS: 5,
+    SOURCE_CONTEXT_MD: 7,
+    SOURCE_HOME_LITHERMES: 100,
+    SOURCE_HOME_HERMES: 101,
+    SOURCE_HOME_CLAUDE: 102,
+    SOURCE_BUNDLED: 200,
+}
+
+# Distance assigned to user-home and bundled rules: they are never "near" a file.
+GLOBAL_DISTANCE = 9999
+
+# Directories the recursive scanner never descends into.
+SCANNER_EXCLUDED_DIRS = frozenset({
+    "node_modules", ".git", "dist", "build", ".turbo", ".next", "coverage",
+    "__pycache__", ".venv", "venv", ".tox", "target",
+})
+
+MAX_SCAN_FILES = 1000
+MAX_WALK_UP_DEPTH = 40
+MAX_RULE_BYTES = 512 * 1024
+
+# Per-rule body cap and total-per-injection cap.
+DEFAULT_MAX_RULE_CHARS = 12000
+DEFAULT_MAX_RESULT_CHARS = 40000
+# Dynamic (post-edit) injection stays far smaller so a mid-session match is cheap.
+DYNAMIC_MAX_RULE_CHARS = 4000
+DYNAMIC_MAX_RESULT_CHARS = 10000
+# After a context compaction both lanes shrink and the dedup ledger reopens once.
+POST_COMPACT_MAX_RULE_CHARS = 3500
+POST_COMPACT_MAX_RESULT_CHARS = 4000
+
+TRUNCATION_NOTICE = "\n\n[Truncated. Full: {path}]"
+NEVER_TRUNCATED_BASENAME = "baseline-discipline.md"
+
+# Hermes marks a compaction summary message with this key
+# (agent/context_compressor.py: COMPRESSED_SUMMARY_METADATA_KEY). Structural
+# detection is exact; the text markers below are a fallback for hosts or
+# transports that drop message metadata.
+COMPACTION_METADATA_KEY = "_compressed_summary"
+COMPACTION_TEXT_MARKERS = (
+    "[context summary]",
+    "context compacted",
+    "context_length_exceeded",
+    "context_too_large",
+    "have been compressed to save context space",
+    "your input exceeds the context window",
+)
+
+MAX_TRACKED_SESSIONS = 64