npm - @litfamily/lithermes - Versions diffs - 1.0.0 - Mend

@litfamily/lithermes 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (557) hide show

package/assets/lithermes-plugin/deliverable_hedge_guard.py ADDED Viewed

@@ -0,0 +1,562 @@
+"""Declaration-driven hedge findings for completed reader-facing writes.
+Hermes discards ``post_tool_call`` return values. This module therefore records
+only bounded, trusted finding metadata at that event and renders it through the
+next ``pre_llm_call`` context. Artifact text and paths never enter model context.
+"""
+from __future__ import annotations
+import os
+import re
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+SKILLS_ROOT = Path(__file__).resolve().parent / "skills"
+MAX_SESSIONS = 64
+MAX_FILE_BYTES = 2 * 1024 * 1024
+MAX_ARTIFACT_PATHS = 32
+MAX_AGGREGATE_FILE_BYTES = 4 * 1024 * 1024
+MAX_CONTEXT_FINDINGS = 100
+READER_FACING_SUFFIXES = frozenset(
+    {".adoc", ".csv", ".htm", ".html", ".md", ".mdx", ".rst", ".tex", ".txt"}
+)
+CHANNEL_BY_GENRE = {
+    "client_deliverable": "reply",
+    "internal_analysis": "designated_section",
+    "audit_report": "methodology_paragraph",
+    "working_note": "inline",
+    "no_artifact": "reply",
+}
+ROUTE_SKILL_ALIASES = {
+    "korean-prose-cleanup": "lit-korean",
+}
+REFERENCE_CONTRACT_SKILLS = frozenset({"frontend-ui-ux", "visual-qa"})
+_OUTPUT_BLOCK = re.compile(
+    r"(?ms)^## #contract\.output_channels\s*$\s*^```yaml\s*$\n(?P<body>.*?)^```\s*$"
+)
+_SCALAR = re.compile(
+    r"^\s*(artifact_genre|limitations_channel)\s*:\s*([a-z_]+)\s*$",
+    re.MULTILINE,
+)
+_FENCE = re.compile(r"^\s*(`{3,}|~{3,})")
+_YAML_OR_JSON_SCALAR = re.compile(
+    r'^\s*(?:[A-Za-z_][A-Za-z0-9_.-]*|"[^"]+"|\'[^\']+\')\s*:\s*.+?\s*,?\s*$'
+)
+_QUOTED = re.compile(r'(["\'`])([^"\'`]+)\1')
+_STATUS_VALUE = re.compile(
+    r"^(?:pending|blocked|in[_ -]?progress|done|complete|pass|fail|보류\s*중|진행\s*중|완료|차단)$",
+    re.IGNORECASE,
+)
+_EVIDENCE_NOUN_KO = (
+    r"(?:근거|자료|데이터|측정(?:값|치|자료)|관찰\s*기록|사용자\s*관찰|실험\s*결과|"
+    r"검증\s*결과|평가\s*자료|출처|문헌|증거|수치)"
+)
+_ABSENCE_KO = (
+    r"(?:없(?:다|습니다|음|어|어서|으므로|기\s*때문)?|부재|제공되지\s*않|주어지지\s*않|"
+    r"확인되지\s*않|검증되지\s*않)"
+)
+_ABILITY_KO = r"(?:(?:평가|판단|산정)할\s*수\s*없|알\s*수\s*없)"
+_ABSENT_EVIDENCE_KO = re.compile(
+    rf"(?:{_EVIDENCE_NOUN_KO}.{{0,48}}{_ABSENCE_KO}|{_ABSENCE_KO}.{{0,24}}{_EVIDENCE_NOUN_KO}|"
+    rf"{_EVIDENCE_NOUN_KO}.{{0,64}}{_ABILITY_KO})",
+    re.IGNORECASE,
+)
+_ABSENT_EVIDENCE_EN = re.compile(
+    r"(?:no\s+(?:supporting\s+)?evidence\s+yet|not\s+yet\s+substantiated|"
+    r"(?:evidence|data|measurements?|observations?|records?|sources?|citations?|test\s+results?)"
+    r".{0,48}(?:is|are|was|were)?\s*(?:absent|missing|unavailable|not\s+provided|not\s+verified)|"
+    r"(?:cannot|could\s+not)\s+(?:assess|determine|calculate).{0,48}"
+    r"(?:evidence|data|measurements?|observations?|records?|sources?|citations?))",
+    re.IGNORECASE,
+)
+_PATTERNS = (
+    (
+        "deferred",
+        re.compile(
+            r"보류\s*중|별도로\s*진행|추후\s*진행|to be determined separately",
+            re.IGNORECASE,
+        ),
+    ),
+    ("absent-evidence", _ABSENT_EVIDENCE_KO),
+    ("absent-evidence", _ABSENT_EVIDENCE_EN),
+    (
+        "scope-limit",
+        re.compile(
+            r"한정됩니다|국한됩니다|범위\s*내에서만|limited to the provided evidence",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        "negated-action",
+        re.compile(
+            r"하지\s*않았습니다|포함되지\s*않습니다|다루지\s*않습니다|was not performed|is not included",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        "self-protection",
+        re.compile(
+            r"참고용|추가\s*검증이\s*필요|완전하지\s*않을\s*수\s*있|for reference only|may be incomplete",
+            re.IGNORECASE,
+        ),
+    ),
+    ("process-meta", re.compile(r"as an AI|이\s*작업에서는|프롬프트가", re.IGNORECASE)),
+)
+@dataclass(frozen=True)
+class OutputChannel:
+    artifact_genre: str
+    limitations_channel: str
+@dataclass(frozen=True)
+class Finding:
+    pattern_class: str
+    line_number: int
+@dataclass(frozen=True)
+class PendingReceipt:
+    skill_id: str
+    contract: OutputChannel
+    finding_count: int
+    line_numbers: tuple[int, ...]
+    file_count: int
+@dataclass(frozen=True)
+class _StableText:
+    text: str
+    byte_count: int
+class _ReadBudgetExceeded:
+    pass
+_READ_BUDGET_EXCEEDED = _ReadBudgetExceeded()
+_ACTIVE_SKILLS: dict[str, str] = {}
+_ROOT_TURNS: dict[str, str] = {}
+_PENDING_RECEIPTS: dict[str, list[PendingReceipt]] = {}
+def reset_state() -> None:
+    """Clear in-memory hook state; used by host lifecycle and isolated drivers."""
+    _ACTIVE_SKILLS.clear()
+    _ROOT_TURNS.clear()
+    _PENDING_RECEIPTS.clear()
+def release_session(session_id: object) -> None:
+    key = str(session_id or "")
+    if not key:
+        return
+    _ACTIVE_SKILLS.pop(key, None)
+    _ROOT_TURNS.pop(key, None)
+    _PENDING_RECEIPTS.pop(key, None)
+def _bounded_set(mapping: dict[str, object], key: str, value: object) -> None:
+    mapping.pop(key, None)
+    mapping[key] = value
+    while len(mapping) > MAX_SESSIONS:
+        mapping.pop(next(iter(mapping)), None)
+def _contract_path(skill_id: str) -> Path:
+    skill_root = SKILLS_ROOT / skill_id
+    entrypoint = skill_root / "SKILL.md"
+    if skill_id not in REFERENCE_CONTRACT_SKILLS:
+        return entrypoint
+    if entrypoint.is_file() and "## #contract.output_channels" in entrypoint.read_text(encoding="utf-8"):
+        raise ValueError(f"lazy-reference skill declares output channel in entrypoint: {skill_id}")
+    return skill_root / "references" / "complete-contract.md"
+def load_output_channel(skill_id: str) -> OutputChannel:
+    if not re.fullmatch(r"[a-z0-9-]+", str(skill_id or "")):
+        raise ValueError("invalid skill id")
+    path = _contract_path(skill_id)
+    text = path.read_text(encoding="utf-8")
+    match = _OUTPUT_BLOCK.search(text)
+    if match is None:
+        raise ValueError(f"output channel declaration missing for {skill_id}")
+    values = dict(_SCALAR.findall(match.group("body")))
+    genre = values.get("artifact_genre", "")
+    channel = values.get("limitations_channel", "")
+    if genre not in CHANNEL_BY_GENRE or CHANNEL_BY_GENRE[genre] != channel:
+        raise ValueError(f"invalid output channel declaration for {skill_id}")
+    return OutputChannel(genre, channel)
+def activate_skill(session_id: object, route_or_skill: object) -> bool:
+    key = str(session_id or "")
+    candidate = ROUTE_SKILL_ALIASES.get(str(route_or_skill or ""), str(route_or_skill or ""))
+    if not key:
+        return False
+    try:
+        load_output_channel(candidate)
+    except (OSError, UnicodeError, ValueError):
+        _ACTIVE_SKILLS.pop(key, None)
+        return False
+    _bounded_set(_ACTIVE_SKILLS, key, candidate)
+    return True
+def clear_active_skill(session_id: object) -> None:
+    """End the previous root turn without discarding a pending finding receipt."""
+    _ACTIVE_SKILLS.pop(str(session_id or ""), None)
+def begin_root_turn(session_id: object, turn_id: object) -> None:
+    """Rebind guard state only at a host-authored root-turn boundary.
+    Current Hermes passes a fresh ``turn_id`` into ``pre_llm_call`` once per
+    root turn. Repeated callbacks carrying that same identity belong to the
+    assistant/tool loop and must keep the active skill after an advisory is
+    consumed. Missing identities are not promoted into boundaries from raw user
+    text; session lifecycle hooks remain the fallback reset surface.
+    """
+    key = str(session_id or "")
+    identity = turn_id if isinstance(turn_id, str) else ""
+    if not key or not identity or len(identity.encode("utf-8")) > 512:
+        return
+    if _ROOT_TURNS.get(key) != identity:
+        clear_active_skill(key)
+        _bounded_set(_ROOT_TURNS, key, identity)
+def _quoted_status_contains(line: str, start: int, end: int) -> bool:
+    for match in _QUOTED.finditer(line):
+        if (
+            match.start(2) <= start
+            and end <= match.end(2)
+            and _STATUS_VALUE.fullmatch(match.group(2).strip())
+        ):
+            return True
+    return False
+def _status_table_line(line: str) -> bool:
+    if "|" not in line:
+        return False
+    cells = [cell.strip().strip("`\"'") for cell in line.strip().strip("|").split("|")]
+    return any(_STATUS_VALUE.fullmatch(cell) for cell in cells)
+def _methodology_lines(lines: list[str]) -> set[int]:
+    paragraphs: list[list[int]] = []
+    current: list[int] = []
+    for index, line in enumerate(lines):
+        if line.strip():
+            current.append(index)
+        elif current:
+            paragraphs.append(current)
+            current = []
+    if current:
+        paragraphs.append(current)
+    marker = re.compile(r"(?:methodology|method|방법론|검토\s*방법)", re.IGNORECASE)
+    for position, paragraph in enumerate(paragraphs):
+        if not marker.search(" ".join(lines[index] for index in paragraph)):
+            continue
+        allowed = set(paragraph)
+        if (
+            len(paragraph) == 1
+            and lines[paragraph[0]].lstrip().startswith("#")
+            and position + 1 < len(paragraphs)
+        ):
+            allowed.update(paragraphs[position + 1])
+        return allowed
+    return set()
+def _designated_section_lines(lines: list[str]) -> set[int]:
+    heading = re.compile(r"^\s*(#{1,6})\s+.*(?:limitations?|한계|제한)", re.IGNORECASE)
+    allowed: set[int] = set()
+    active_level: int | None = None
+    for index, line in enumerate(lines):
+        matched = heading.match(line)
+        if matched:
+            active_level = len(matched.group(1))
+            allowed.add(index)
+            continue
+        next_heading = re.match(r"^\s*(#{1,6})\s+", line)
+        if active_level is not None and next_heading and len(next_heading.group(1)) <= active_level:
+            active_level = None
+        if active_level is not None:
+            allowed.add(index)
+    return allowed
+def scan_text(text: str, contract: OutputChannel) -> list[Finding]:
+    if contract.artifact_genre in {"working_note", "no_artifact"}:
+        return []
+    lines = str(text or "").splitlines()
+    allowed = (
+        _methodology_lines(lines)
+        if contract.artifact_genre == "audit_report"
+        else _designated_section_lines(lines)
+        if contract.artifact_genre == "internal_analysis"
+        else set()
+    )
+    findings: list[Finding] = []
+    fence: str | None = None
+    for index, line in enumerate(lines):
+        fence_match = _FENCE.match(line)
+        if fence_match:
+            marker = fence_match.group(1)[0]
+            fence = None if fence == marker else marker if fence is None else fence
+            continue
+        if fence is not None or index in allowed:
+            continue
+        scalar = bool(_YAML_OR_JSON_SCALAR.fullmatch(line))
+        table = _status_table_line(line)
+        for pattern_class, pattern in _PATTERNS:
+            match = pattern.search(line)
+            if match is None:
+                continue
+            if pattern_class == "deferred" and (
+                scalar or table or _quoted_status_contains(line, match.start(), match.end())
+            ):
+                continue
+            findings.append(Finding(pattern_class, index + 1))
+            break
+    return findings
+def _directory_flags() -> int | None:
+    nofollow = getattr(os, "O_NOFOLLOW", 0)
+    directory = getattr(os, "O_DIRECTORY", 0)
+    if os.name != "posix" or not nofollow or not directory:
+        return None
+    return os.O_RDONLY | directory | nofollow | getattr(os, "O_CLOEXEC", 0)
+def _relative_artifact_path(path_text: str, workspace: Path) -> Path | None:
+    candidate = Path(path_text).expanduser()
+    target = candidate if candidate.is_absolute() else workspace / candidate
+    absolute = Path(os.path.abspath(os.fspath(target)))
+    try:
+        relative = absolute.relative_to(workspace)
+    except ValueError:
+        return None
+    if (
+        not relative.parts
+        or any(part in {"", ".", ".."} for part in relative.parts)
+        or relative.suffix.lower() not in READER_FACING_SUFFIXES
+    ):
+        return None
+    return relative
+def _read_stable_text_file_result(
+    path_text: str,
+    workspace: Path,
+    byte_limit: int,
+) -> _StableText | _ReadBudgetExceeded | None:
+    relative = _relative_artifact_path(path_text, workspace)
+    directory_flags = _directory_flags()
+    if relative is None or directory_flags is None or byte_limit < 0:
+        return None
+    read_limit = min(MAX_FILE_BYTES, byte_limit)
+    root_parts = tuple(part for part in workspace.parts if part != os.path.sep)
+    directory_fds: list[int] = []
+    edges: list[tuple[int, str, tuple[int, int], bool]] = []
+    artifact_fd = -1
+    def open_directory(name: str) -> bool:
+        child_fd = -1
+        try:
+            parent_fd = directory_fds[-1]
+            child_fd = os.open(name, directory_flags, dir_fd=parent_fd)
+            opened = os.fstat(child_fd)
+            if not stat.S_ISDIR(opened.st_mode):
+                return False
+            edges.append((parent_fd, name, (opened.st_dev, opened.st_ino), True))
+            directory_fds.append(child_fd)
+            child_fd = -1
+            return True
+        except OSError:
+            return False
+        finally:
+            if child_fd >= 0:
+                os.close(child_fd)
+    try:
+        directory_fds.append(os.open(os.path.sep, directory_flags))
+        for part in (*root_parts, *relative.parts[:-1]):
+            if not open_directory(part):
+                return None
+        parent_fd = directory_fds[-1]
+        artifact_fd = os.open(
+            relative.parts[-1],
+            os.O_RDONLY
+            | getattr(os, "O_NOFOLLOW", 0)
+            | getattr(os, "O_NONBLOCK", 0)
+            | getattr(os, "O_CLOEXEC", 0),
+            dir_fd=parent_fd,
+        )
+        initial = os.fstat(artifact_fd)
+        if not stat.S_ISREG(initial.st_mode) or initial.st_size > MAX_FILE_BYTES:
+            return None
+        if initial.st_size > read_limit:
+            return _READ_BUDGET_EXCEEDED
+        edges.append(
+            (parent_fd, relative.parts[-1], (initial.st_dev, initial.st_ino), False)
+        )
+        chunks: list[bytes] = []
+        total = 0
+        while total <= read_limit:
+            chunk = os.read(artifact_fd, min(65_536, read_limit + 1 - total))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            total += len(chunk)
+        raw = b"".join(chunks)
+        if len(raw) > read_limit:
+            return _READ_BUDGET_EXCEEDED
+        final = os.fstat(artifact_fd)
+        if (
+            not stat.S_ISREG(final.st_mode)
+            or (final.st_dev, final.st_ino) != (initial.st_dev, initial.st_ino)
+            or final.st_size != initial.st_size
+            or final.st_mtime_ns != initial.st_mtime_ns
+            or final.st_ctime_ns != initial.st_ctime_ns
+            or len(raw) != initial.st_size
+        ):
+            return None
+        for parent_fd, name, identity, is_directory in edges:
+            current = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+            correct_type = (
+                stat.S_ISDIR(current.st_mode)
+                if is_directory
+                else stat.S_ISREG(current.st_mode)
+            )
+            if (current.st_dev, current.st_ino) != identity or not correct_type:
+                return None
+        return _StableText(raw.decode("utf-8"), len(raw))
+    except (OSError, UnicodeError, ValueError):
+        return None
+    finally:
+        if artifact_fd >= 0:
+            try:
+                os.close(artifact_fd)
+            except OSError:
+                pass
+        for descriptor in reversed(directory_fds):
+            try:
+                os.close(descriptor)
+            except OSError:
+                pass
+def _read_stable_text_file(path_text: str, workspace: Path) -> str | None:
+    result = _read_stable_text_file_result(path_text, workspace, MAX_FILE_BYTES)
+    return result.text if isinstance(result, _StableText) else None
+def _bounded_artifact_paths(paths: Iterable[object]) -> list[object] | None:
+    if isinstance(paths, (str, bytes)):
+        return None
+    try:
+        iterator = iter(paths)
+    except TypeError:
+        return None
+    bounded: list[object] = []
+    for raw_path in iterator:
+        if len(bounded) >= MAX_ARTIFACT_PATHS:
+            return None
+        bounded.append(raw_path)
+    return bounded
+def observe_completed_paths(
+    session_id: object,
+    paths: Iterable[object],
+    *,
+    workspace: object = None,
+) -> None:
+    key = str(session_id or "")
+    skill_id = _ACTIVE_SKILLS.get(key)
+    if not key or not skill_id:
+        return
+    try:
+        contract = load_output_channel(skill_id)
+    except (OSError, UnicodeError, ValueError):
+        return
+    if contract.artifact_genre in {"working_note", "no_artifact"}:
+        return
+    bounded_paths = _bounded_artifact_paths(paths)
+    if bounded_paths is None:
+        return
+    try:
+        root = Path(workspace or Path.cwd()).expanduser().resolve(strict=True)
+    except (OSError, RuntimeError):
+        return
+    buffered_text: list[str] = []
+    remaining_bytes = MAX_AGGREGATE_FILE_BYTES
+    for raw_path in bounded_paths:
+        result = _read_stable_text_file_result(
+            str(raw_path or ""),
+            root,
+            remaining_bytes,
+        )
+        if result is _READ_BUDGET_EXCEEDED:
+            return
+        if not isinstance(result, _StableText):
+            continue
+        buffered_text.append(result.text)
+        remaining_bytes -= result.byte_count
+    all_findings: list[Finding] = []
+    file_count = 0
+    for text in buffered_text:
+        findings = scan_text(text, contract)
+        if findings:
+            file_count += 1
+            all_findings.extend(findings)
+    if not all_findings:
+        return
+    receipt = PendingReceipt(
+        skill_id=skill_id,
+        contract=contract,
+        finding_count=min(len(all_findings), MAX_CONTEXT_FINDINGS),
+        line_numbers=tuple(sorted({finding.line_number for finding in all_findings}))[
+            :MAX_CONTEXT_FINDINGS
+        ],
+        file_count=file_count,
+    )
+    pending = list(_PENDING_RECEIPTS.get(key, ()))
+    pending.append(receipt)
+    _bounded_set(_PENDING_RECEIPTS, key, pending[-8:])
+def consume_context(session_id: object) -> str:
+    key = str(session_id or "")
+    receipts = _PENDING_RECEIPTS.pop(key, None)
+    if not receipts:
+        return ""
+    lines = ['<lithermes-deliverable-hedge-guard event="completed-write">']
+    for receipt in receipts:
+        line_numbers = ",".join(str(number) for number in receipt.line_numbers)
+        lines.append(
+            "DELIVERABLE_HEDGE_VIOLATION "
+            f"skill={receipt.skill_id} genre={receipt.contract.artifact_genre} "
+            f"findings={receipt.finding_count} lines={line_numbers} files={receipt.file_count}. "
+            f"Revise the artifact and place limitations in {receipt.contract.limitations_channel}."
+        )
+    lines.append("Artifact text and paths were omitted because they are untrusted data.")
+    lines.append("</lithermes-deliverable-hedge-guard>")
+    return "\n".join(lines)