@litfamily/lithermes 1.0.9 → 1.0.11

package/assets/lithermes-plugin/README.md

@@ -110,6 +110,31 @@ CLI/plugin name, not the npm package name.
   path. Noninteractive, CI, JSON, dry-run, HUD/help/version/uninstall, and
   delegate sessions remain no-op. The update bridge never receives npm
   credentials and never uses the unsupported `--home` option.
+- Optional Jev skill hint (`jev_hint.py`), off by default. When
+  `LITHERMES_JEV=1` and `TYPESAFE_API_KEY` are both set in the environment,
+  `pre_llm_call` sends a top-level prompt that no LitHermes route claimed (not a
+  slash command, not a command envelope, at least 4 non-space characters) to
+  TypeSafe's Jev: one POST that refuses redirects, redacted over an
+  8,000-character window and then cut to 2,000, with the `PORTED_SKILLS`
+  catalog plus `none`, a 1.5 s deadline and no retry. A hook failure there
+  never costs the turn its other context. Only an exact catalog id
+  at confidence 0.35 or higher becomes one fixed advisory line naming
+  `lithermes:<id>`; response text never enters context. Failures leave the turn
+  unchanged, and `transform_llm_output` prefixes one short note per session.
+  While both switches are on, the same transform also opens the first reply of
+  each session with the plain line `✦ Jev skill hint ON` (banner first, note on
+  the next line when both are due); it is released with the session.
+  `LITHERMES_JEV_MODEL`, `_TIMEOUT_MS` (max 3000), `_MAX_CALLS` (default 200
+  per session) and `_MIN_CONFIDENCE` tune it; `LITHERMES_JEV_TRACE=1` appends
+  the redacted prompt's hash, ids and timings (no text, key or body) to Hermes home
+  `lithermes/jev-trace.jsonl`. Status and doctor print `Jev skill hint: ...`;
+  when on, they add the last hinted skill id and latency of the session named
+  by `HERMES_SESSION_ID` (`on — last hint lit-humanizer (0.43s)`) or `on — no
+  hint yet`, and `on — no session` outside any session. The CLI runs in its own
+  process, so an accepted hint also writes only that id, the latency and a
+  timestamp to Hermes home `lithermes/jev-last-<session hash>.json` (mode 0600,
+  atomic), one file per session, removed when the session ends. Neither file is
+  written through a symlink.
 - The `post_tool_call` hook is an observer — Hermes discards its return value — so
   it records the paths a completed `write_file` / `patch` call mutated and
   `pre_llm_call` renders them on the next turn. A source-code edit names

package/assets/lithermes-plugin/__init__.py

@@ -12,6 +12,7 @@ from . import bounded_work
 from . import bounded_work_tools
 from . import deliverable_hedge_guard
 from . import handoff
+from . import jev_hint
 from . import knowledge
 from . import knowledge_tools
 from . import scientific_visualization
@@ -367,9 +368,24 @@ def _pre_llm_call(**kwargs: Any) -> dict[str, str] | None:
         parts.append(str(base["context"]))
     elif isinstance(base, str) and base.strip():
         parts.append(base)
+    routed = bool(parts)
     snapshot = litgoal_hook.snapshot_context(**kwargs)
     if snapshot:
         parts.append(snapshot)
+    if not routed:
+        # No deterministic route claimed this turn; the optional Jev hint may
+        # add one advisory line. It is inert unless LITHERMES_JEV and the key are set,
+        # and an unexpected failure there never costs the turn its other context.
+        try:
+            skill_hint = jev_hint.pre_llm_call(
+                session_id=str(kwargs.get("session_id") or ""),
+                user_message=str(kwargs.get("user_message") or ""),
+                catalog=PORTED_SKILLS,
+            )
+        except Exception:  # noqa: BLE001 - advisory only
+            skill_hint = ""
+        if skill_hint:
+            parts.append(skill_hint)
     if not parts:
         return _merge_knowledge(_merge_post_edit(None, post_edit), knowledge_context)
     return _merge_knowledge(
@@ -527,12 +543,20 @@ def _command_handler(ctx, handler, route=None):
 
 def _transform_llm_output(**kwargs: Any) -> str | None:
     named = handoff.transform_llm_output(**kwargs)
-    if named is not None:
-        return named
-    named = scientific_visualization.transform_llm_output(**kwargs)
-    if named is not None:
+    if named is None:
+        named = scientific_visualization.transform_llm_output(**kwargs)
+    if named is None:
+        named = core.transform_llm_output(**kwargs)
+    # The reply transform is the plugin's only user-visible channel, so the
+    # once-per-session Jev banner and fallback note are prefixed here, banner
+    # first; the reply stays intact.
+    session_id = str(kwargs.get("session_id") or "")
+    lines = (jev_hint.consume_banner(session_id), jev_hint.consume_note(session_id))
+    prefix = "\n".join(line for line in lines if line)
+    if not prefix:
         return named
-    return core.transform_llm_output(**kwargs)
+    reply = named if named is not None else str(kwargs.get("response_text") or "")
+    return f"{prefix}\n\n{reply}"
 
 
 def _pre_tool_call(**kwargs: Any) -> dict[str, str] | None:
@@ -568,6 +592,7 @@ def _release_bounded_session(**kwargs: Any) -> None:
     core.release_browser_drive_state(raw_session_id)
     session_id = raw_session_id if isinstance(raw_session_id, str) else ""
     bounded_work.release_bounded_session(session_id)
+    jev_hint.release_session(session_id)
     # A finalized/reset session must not leave its rule dedup ledger behind: the
     # next session reusing the id would see every rule as "already injected".
     core.release_rules_session(session_id)

package/assets/lithermes-plugin/diagnostics.py

@@ -21,6 +21,11 @@ try:
 except (ImportError, ModuleNotFoundError):
     import provider_metrics as _provider_metrics  # type: ignore
 
+try:
+    from . import jev_hint as _jev_hint
+except (ImportError, ModuleNotFoundError):
+    import jev_hint as _jev_hint  # type: ignore
+
 try:
     from .core_contract import KOREAN_PROSE_ALIASES, KOREAN_PROSE_COMMANDS
 except (ImportError, ModuleNotFoundError):
@@ -477,6 +482,7 @@ def status_report(host_version: str | None = None) -> str:
         "litgoal state: .hermes/lithermes/litgoal/   (drive via: hermes lithermes goal status)",
         _knowledge.status_line(Path.cwd()),
         _provider_metrics.capability_line(),
+        _jev_hint.status_line(),
         f"litgoal evidence kinds: {', '.join(_evidence_kinds())}",
         f"scientific visualization: {_science.dependency_summary()}",
         *_motion_runtime_lines(),
@@ -562,6 +568,9 @@ def doctor_report(host_version: str | None = None) -> tuple[list[str], int]:
     )
     healthy = healthy and knowledge_ok
     lines.append(f"[NOTE] {_provider_metrics.capability_line()}")
+    jev_state = _jev_hint.status()
+    jev_tag = {"on": "OK", "off": "NOTE"}.get(jev_state, "WARN")
+    lines.append(f"[{jev_tag}] {_jev_hint.status_line()}")
     if version != "unknown":
         lines.append(f"[OK] Hermes host detected (v{version})")
     else:

package/assets/lithermes-plugin/humanizer_detector.py

@@ -20,7 +20,7 @@ VALID_SCOPES = {"line", "sentence", "document"}
 
 
 def _js_compatible_pattern(pattern: str) -> str:
-    """Port JavaScript ASCII word classes without narrowing Unicode ``\s``."""
+    r"""Port JavaScript ASCII word classes without narrowing Unicode ``\s``."""
     result: list[str] = []
     in_class = False
     index = 0

package/assets/lithermes-plugin/jev_hint.py

@@ -0,0 +1,483 @@
+"""Optional Jev skill hint for the per-turn ``pre_llm_call`` route.
+
+Off by default. It runs only when ``LITHERMES_JEV=1`` and ``TYPESAFE_API_KEY``
+are both present in the process environment, on a top-level turn that no
+deterministic LitHermes route already claimed. One POST per eligible turn asks
+Jev which bundled LitHermes skill fits the redacted prompt. The answer is
+untrusted data: only an exact catalog id with enough confidence becomes one
+fixed advisory sentence. Every failure falls back to the unchanged turn, with
+one visible note per session delivered through ``transform_llm_output``. When
+both switches are on, the first reply of each session also opens with one plain
+``✦ Jev skill hint ON`` line so the user notices the feature is enabled.
+
+Status and doctor show the last accepted hint (skill id and latency only) of
+one session. They run as a separate ``hermes`` CLI process, so the hinting
+process also writes that pair, with a timestamp, to Hermes home
+``lithermes/jev-last-<session hash>.json``, one file per session, removed when
+the session ends. Status reads the file of the session named by
+``HERMES_SESSION_ID``, which Hermes sets for commands run inside a session;
+outside a session it shows no hint, so concurrent sessions never see each
+other's.
+
+The key is read from the environment and used only in the request header. It
+is never logged, traced, stored, or placed in an error or note.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import math
+import os
+import re
+import threading
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any, Callable, Iterable
+
+try:
+    from .core_runtime import assert_within_isolation, get_hermes_home, redact_obj, utc_now
+except (ImportError, ModuleNotFoundError):
+    from core_runtime import assert_within_isolation, get_hermes_home, redact_obj, utc_now  # type: ignore
+
+
+FLAG = "LITHERMES_JEV"
+KEY_ENV = "TYPESAFE_API_KEY"
+SESSION_ENV = "HERMES_SESSION_ID"
+ENDPOINT = "https://api.typesafe.ai/v1/systemone"
+DEFAULT_MODEL = "jev-1.13.0"
+DEFAULT_TIMEOUT_MS = 1500
+MAX_TIMEOUT_MS = 3000
+DEFAULT_MAX_CALLS = 200
+DEFAULT_MIN_CONFIDENCE = 0.35
+MAX_PROMPT_CHARS = 2000
+REDACTION_WINDOW_CHARS = 8000
+MAX_DESCRIPTION_CHARS = 300
+MAX_REQUEST_BYTES = 64 * 1024
+MAX_RESPONSE_BYTES = 64 * 1024
+MAX_TRACKED_SESSIONS = 256
+LAST_HINT_PREFIX = "jev-last-"
+MAX_LAST_HINT_BYTES = 4096
+NONE_ID = "none"
+_NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)
+# Reply transforms land in Markdown and transcripts, where the product keeps
+# every mark plain; the banner therefore carries no ANSI colour.
+BANNER = "✦ Jev skill hint ON"
+QUESTION = (
+    "Which one skill, if any, is the best fit for the user's request? "
+    "Choose none when no catalog skill fits."
+)
+NONE_CRITERION = "No specialized skill in this catalog fits; answer the user directly."
+
+# A transport takes (url, headers, body, timeout seconds) and returns
+# (HTTP status, response bytes). Tests replace it; production uses urllib.
+Transport = Callable[[str, dict[str, str], bytes, float], tuple[int, bytes]]
+
+
+class TransportTimeout(Exception):
+    """The request did not finish inside the hard timeout."""
+
+
+class TransportError(Exception):
+    """The request failed before an HTTP status was available."""
+
+
+class _RefuseRedirects(urllib.request.HTTPRedirectHandler):
+    """A redirect surfaces as its own HTTP status instead of being followed."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+_OPENER = urllib.request.build_opener(_RefuseRedirects())
+
+
+def _urllib_transport(url: str, headers: dict[str, str], body: bytes, timeout: float) -> tuple[int, bytes]:
+    plain = {name: value for name, value in headers.items() if name.lower() != "authorization"}
+    request = urllib.request.Request(url, data=body, headers=plain, method="POST")
+    for name, value in headers.items():
+        if name.lower() == "authorization":
+            # Never copied onto a follow-up request, should a redirect ever be taken.
+            request.add_unredirected_header(name, value)
+    try:
+        with _OPENER.open(request, timeout=timeout) as response:  # noqa: S310 - fixed https endpoint
+            return int(response.status), response.read(MAX_RESPONSE_BYTES + 1)
+    except urllib.error.HTTPError as exc:
+        exc.close()
+        return int(exc.code), b""
+    except (TimeoutError, OSError) as exc:
+        # Exception text can carry request details; only the category leaves here.
+        if isinstance(exc, TimeoutError) or "timed out" in str(getattr(exc, "reason", "")):
+            raise TransportTimeout() from None
+        raise TransportError() from None
+
+
+TRANSPORT: Transport = _urllib_transport
+
+_CALLS: dict[str, int] = {}
+_NOTED: dict[str, bool] = {}
+_PENDING_NOTE: dict[str, str] = {}
+_BANNERED: dict[str, bool] = {}
+_LAST_HINT: dict[str, dict[str, Any]] = {}
+_SKILL_ID = re.compile(r"[a-z0-9][a-z0-9-]{0,63}")
+
+
+def _env(env: dict[str, str] | None) -> dict[str, str]:
+    return os.environ if env is None else env  # type: ignore[return-value]
+
+
+def _flag_on(env: dict[str, str]) -> bool:
+    return (env.get(FLAG) or "").strip() == "1"
+
+
+def _key(env: dict[str, str]) -> str:
+    return (env.get(KEY_ENV) or "").strip()
+
+
+def status(env: dict[str, str] | None = None) -> str:
+    values = _env(env)
+    if not _flag_on(values):
+        return "off"
+    if not _key(values):
+        return "flag on but TYPESAFE_API_KEY missing"
+    return "on"
+
+
+def _last_hint_path(session: str) -> Path:
+    # A hash keeps the raw session id out of the file name and out of the path.
+    key = hashlib.sha256(session.encode("utf-8")).hexdigest()[:32]
+    return get_hermes_home() / "lithermes" / f"{LAST_HINT_PREFIX}{key}.json"
+
+
+def _refuse_symlink(path: Path) -> None:
+    if path.is_symlink():
+        raise OSError(f"refusing to write through a symlink: {path.name}")
+
+
+def _append_private(path: Path, payload: dict[str, Any]) -> None:
+    """Append one JSON line without following a symlink planted at ``path``."""
+    assert_within_isolation(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _refuse_symlink(path)
+    fd = os.open(path, os.O_WRONLY | os.O_APPEND | os.O_CREAT | _NOFOLLOW, 0o600)
+    with os.fdopen(fd, "a", encoding="utf-8") as handle:
+        handle.write(json.dumps(redact_obj(payload), sort_keys=True) + "\n")
+
+
+def _record_hint(session: str, skill_id: str, latency_ms: int) -> None:
+    """Keep the session's last accepted hint for status and doctor: id, latency and time only."""
+    if not session:
+        return
+    record = {"skill": skill_id, "latency_ms": latency_ms, "timestamp": utc_now().isoformat()}
+    _LAST_HINT[session] = record
+    _bound_sessions()
+    path = _last_hint_path(session)
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.{threading.get_ident()}.tmp")
+    try:
+        assert_within_isolation(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        _refuse_symlink(temporary)
+        fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_TRUNC | _NOFOLLOW, 0o600)
+        if hasattr(os, "fchmod"):
+            os.fchmod(fd, 0o600)  # a leftover temporary keeps its old mode otherwise
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(record, handle, sort_keys=True)
+        # os.replace swaps a symlink at ``path`` for the file; it never writes through it.
+        os.replace(temporary, path)
+    except (OSError, RuntimeError):  # RuntimeError: the isolation root refused the path
+        with contextlib.suppress(OSError):
+            temporary.unlink()
+
+
+def last_hint(session: str) -> tuple[str, int] | None:
+    """Return (skill id, latency ms) of the session's last accepted hint, or None when unknown or unreadable."""
+    if not session:
+        return None
+    record: Any = dict(_LAST_HINT.get(session) or {})
+    if not record:
+        try:
+            with _last_hint_path(session).open("rb") as handle:
+                record = json.loads(handle.read(MAX_LAST_HINT_BYTES + 1)[:MAX_LAST_HINT_BYTES].decode("utf-8"))
+        except (OSError, ValueError, UnicodeDecodeError):
+            return None
+    if not isinstance(record, dict):
+        return None
+    skill, latency = record.get("skill"), record.get("latency_ms")
+    if not isinstance(skill, str) or not _SKILL_ID.fullmatch(skill):
+        return None
+    if isinstance(latency, bool) or not isinstance(latency, int) or not 0 <= latency <= 600_000:
+        return None
+    return skill, latency
+
+
+def status_line(env: dict[str, str] | None = None) -> str:
+    values = _env(env)
+    state = status(values)
+    if state != "on":
+        return f"Jev skill hint: {state}"
+    session = (values.get(SESSION_ENV) or "").strip()
+    if not session:
+        return "Jev skill hint: on — no session (last hints are per session)"
+    last = last_hint(session)
+    if last is None:
+        return "Jev skill hint: on — no hint yet"
+    skill, latency_ms = last
+    return f"Jev skill hint: on — last hint {skill} ({latency_ms / 1000:.2f}s)"
+
+
+def _int_setting(env: dict[str, str], name: str, default: int, low: int, high: int) -> int:
+    try:
+        value = int((env.get(name) or "").strip())
+    except ValueError:
+        return default
+    return value if low <= value <= high else default
+
+
+def _float_setting(env: dict[str, str], name: str, default: float) -> float:
+    try:
+        value = float((env.get(name) or "").strip())
+    except ValueError:
+        return default
+    return value if 0.0 <= value <= 1.0 else default
+
+
+# A home folder, with or without a trailing separator, up to the next separator.
+_HOME_PATHS = (
+    (re.compile(r"/(?:Users|home)/[^/\s]+"), "~"),
+    (re.compile(r"[A-Za-z]:\\Users\\[^\\/\s]+\\"), "~/"),
+    (re.compile(r"[A-Za-z]:\\Users\\[^\\/\s]+"), "~"),
+)
+_EMAIL = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}")
+_TOKENS = (
+    re.compile(r"-----BEGIN [A-Z0-9 ]+-----[\s\S]*?(?:-----END [A-Z0-9 ]+-----|$)"),
+    re.compile(r"eyJ[A-Za-z0-9_-]*\.eyJ[A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]*)?"),
+    re.compile(r"(?<![A-Za-z0-9])(?:sk-ant-|sk-|ghp_|gho_|github_pat_|npm_|apikey_|xox[abprs]-)[A-Za-z0-9_-]{8,}"),
+    re.compile(r"(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}(?![A-Za-z0-9])"),
+    re.compile(r"(?<![A-Za-z0-9])AIza[0-9A-Za-z_-]{20,}"),
+    re.compile(r"[A-Za-z0-9+/_-]{32,}={0,2}"),
+)
+_TRAILING_TOKEN_RUN = re.compile(r"[A-Za-z0-9+/_=-]{8,}\Z")
+
+
+def redact_prompt(text: str) -> str:
+    """Redact a bounded window, then cut to the prompt limit.
+
+    Redacting before the cut means a secret straddling the limit is matched
+    whole; a token-character run the cut still splits becomes ``[secret]``.
+    """
+    value = str(text or "")[:REDACTION_WINDOW_CHARS]
+    for pattern, replacement in _HOME_PATHS:
+        value = pattern.sub(replacement, value)
+    value = _EMAIL.sub("[email]", value)
+    for pattern in _TOKENS:
+        value = pattern.sub("[secret]", value)
+    if len(value) > MAX_PROMPT_CHARS:
+        value = _TRAILING_TOKEN_RUN.sub("[secret]", value[:MAX_PROMPT_CHARS])
+    return value
+
+
+def eligible(user_message: str) -> bool:
+    """A plain top-level prompt: no slash command and no LitHermes command envelope."""
+    text = str(user_message or "").strip()
+    if len(re.sub(r"\s+", "", text)) < 4:
+        return False
+    if text.startswith("/"):
+        return False
+    # Native slash commands re-enter as injected messages carrying a route
+    # envelope or the activation probe contract; those turns are already routed.
+    return "<lithermes-" not in text and "model-emitted line" not in text
+
+
+def build_request(prompt: str, catalog: Iterable[tuple[str, str]], model: str, key: str = "") -> dict[str, Any]:
+    criteria = {skill_id: str(description)[:MAX_DESCRIPTION_CHARS] for skill_id, description in catalog}
+    criteria[NONE_ID] = NONE_CRITERION
+    # A key pasted into the prompt is scrubbed even when no pattern matches it.
+    state = redact_prompt(prompt.replace(key, "[secret]") if key else prompt)
+    return {
+        "model": model,
+        "state": state,
+        "questions": {"which": {"type": "choice", "instructions": QUESTION, "criteria": criteria}},
+    }
+
+
+def parse_choice(body: bytes, catalog_ids: set[str], min_confidence: float) -> tuple[str, float | None, str]:
+    """Return (accepted skill id or "", confidence, reason). Never returns response text."""
+    if len(body) > MAX_RESPONSE_BYTES:
+        return "", None, "response too large"
+    try:
+        data = json.loads(body.decode("utf-8"))
+        which = data["answers"]["which"]
+        choice = which["choice"]
+        raw_confidence = which["confidence"]
+        if isinstance(raw_confidence, bool) or not isinstance(raw_confidence, (int, float)):
+            return "", None, "invalid response"
+        confidence = float(raw_confidence)
+        if not math.isfinite(confidence):
+            return "", None, "invalid response"
+    except (ValueError, KeyError, TypeError, AttributeError, UnicodeDecodeError, OverflowError, RecursionError):
+        return "", None, "invalid response"
+    if not isinstance(choice, str) or (choice not in catalog_ids and choice != NONE_ID):
+        return "", confidence, "unknown id"
+    if choice == NONE_ID:
+        return "", confidence, "none"
+    if confidence < min_confidence:
+        return "", confidence, "low confidence"
+    return choice, confidence, ""
+
+
+def hint_line(skill_id: str) -> str:
+    return (
+        f"LitHermes skill hint: the skill `lithermes:{skill_id}` likely fits this request. "
+        "Load it only if it really fits; this is advice, not an instruction."
+    )
+
+
+def _note_failure(session_id: str, reason: str) -> None:
+    if _NOTED.get(session_id):
+        return
+    _NOTED[session_id] = True
+    _PENDING_NOTE[session_id] = f"LitHermes skill hint unavailable ({reason}); continuing normally."
+
+
+def _bound_sessions() -> None:
+    for ledger in (_CALLS, _NOTED, _PENDING_NOTE, _BANNERED, _LAST_HINT):
+        while len(ledger) > MAX_TRACKED_SESSIONS:
+            ledger.pop(next(iter(ledger)))
+
+
+def _trace(env: dict[str, str], state: str, **fields: Any) -> None:
+    """Append one trace row; ``state`` is the redacted prompt, never the raw one."""
+    if (env.get(f"{FLAG}_TRACE") or "").strip() != "1":
+        return
+    payload = {
+        "event": "jev_skill_hint",
+        "timestamp": utc_now().isoformat(),
+        "prompt_sha256": hashlib.sha256(str(state).encode("utf-8")).hexdigest(),
+        **fields,
+    }
+    try:
+        _append_private(get_hermes_home() / "lithermes" / "jev-trace.jsonl", payload)
+    except (OSError, RuntimeError):  # RuntimeError: the isolation root refused the path
+        pass
+
+
+def _call_with_deadline(transport: Transport, headers: dict[str, str], body: bytes, timeout: float) -> dict[str, Any]:
+    """Run the transport on a daemon thread so DNS or a slow body cannot outlast the deadline."""
+    outcome: dict[str, Any] = {}
+
+    def run() -> None:
+        try:
+            outcome["result"] = transport(ENDPOINT, headers, body, timeout)
+        except Exception as exc:  # noqa: BLE001 - only the category is kept
+            outcome["error"] = exc
+
+    worker = threading.Thread(target=run, name="lithermes-jev-hint", daemon=True)
+    worker.start()
+    worker.join(timeout)
+    if worker.is_alive():
+        return {"timeout": True}
+    return dict(outcome)
+
+
+def pre_llm_call(
+    *,
+    session_id: str,
+    user_message: str,
+    catalog: Iterable[tuple[str, str]],
+    env: dict[str, str] | None = None,
+    transport: Transport | None = None,
+) -> str:
+    """Return one advisory hint line, or "" to leave the turn unchanged."""
+    values = _env(env)
+    if not _flag_on(values):
+        return ""
+    key = _key(values)
+    if not key or not eligible(user_message):
+        return ""
+    session = str(session_id or "")
+    catalog_list = [(str(skill_id), str(description)) for skill_id, description in catalog]
+    model = (values.get(f"{FLAG}_MODEL") or "").strip() or DEFAULT_MODEL
+    request = build_request(str(user_message), catalog_list, model, key)
+    state = request["state"]
+    calls = _CALLS.get(session, 0)
+    if calls >= _int_setting(values, f"{FLAG}_MAX_CALLS", DEFAULT_MAX_CALLS, 0, 1_000_000):
+        _note_failure(session, "call cap reached")
+        _trace(values, state, choice="", confidence=None, latency_ms=0, http_status=None, fallback_reason="call cap reached")
+        return ""
+    body = json.dumps(request, ensure_ascii=False).encode("utf-8")
+    if len(body) > MAX_REQUEST_BYTES:
+        _note_failure(session, "request too large")
+        _trace(values, state, choice="", confidence=None, latency_ms=0, http_status=None, fallback_reason="request too large")
+        return ""
+    _CALLS[session] = calls + 1
+    _bound_sessions()
+    timeout_ms = _int_setting(values, f"{FLAG}_TIMEOUT_MS", DEFAULT_TIMEOUT_MS, 1, MAX_TIMEOUT_MS)
+    headers = {
+        "Authorization": f"Bearer {key}",
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+    started = time.monotonic()
+    http_status: int | None = None
+    response = b""
+    outcome = _call_with_deadline(transport or TRANSPORT, headers, body, timeout_ms / 1000.0)
+    if "result" in outcome:
+        http_status, response = outcome["result"]
+        reason = "" if http_status == 200 else f"HTTP {http_status}"
+    elif outcome.get("timeout") or isinstance(outcome.get("error"), TransportTimeout):
+        reason = "timeout"
+    else:
+        reason = "network error"
+    latency_ms = int((time.monotonic() - started) * 1000)
+    if reason:
+        _note_failure(session, reason)
+        _trace(values, state, choice="", confidence=None, latency_ms=latency_ms, http_status=http_status, fallback_reason=reason)
+        return ""
+    min_confidence = _float_setting(values, f"{FLAG}_MIN_CONFIDENCE", DEFAULT_MIN_CONFIDENCE)
+    choice, confidence, reason = parse_choice(response, {skill_id for skill_id, _ in catalog_list}, min_confidence)
+    if reason in {"invalid response", "response too large"}:
+        _note_failure(session, reason)
+    _trace(
+        values,
+        state,
+        choice=choice,
+        confidence=confidence,
+        latency_ms=latency_ms,
+        http_status=http_status,
+        fallback_reason=reason,
+    )
+    if not choice:
+        return ""
+    _record_hint(session, choice, latency_ms)
+    return hint_line(choice)
+
+
+def consume_note(session_id: str) -> str:
+    return _PENDING_NOTE.pop(str(session_id or ""), "")
+
+
+def consume_banner(session_id: str, env: dict[str, str] | None = None) -> str:
+    """Return the enabled banner once per session while both switches are on, else ""."""
+    session = str(session_id or "")
+    if status(env) != "on" or _BANNERED.get(session):
+        return ""
+    _BANNERED[session] = True
+    _bound_sessions()
+    return BANNER
+
+
+def release_session(session_id: str) -> None:
+    session = str(session_id or "")
+    _CALLS.pop(session, None)
+    _NOTED.pop(session, None)
+    _PENDING_NOTE.pop(session, None)
+    _BANNERED.pop(session, None)
+    _LAST_HINT.pop(session, None)
+    if session:
+        with contextlib.suppress(OSError, RuntimeError):  # RuntimeError: the isolation root refused the path
+            path = _last_hint_path(session)
+            assert_within_isolation(path)
+            path.unlink()  # removes a planted symlink itself, never its target