@litfamily/lithermes 1.0.0

package/assets/lithermes-plugin/__init__.py

@@ -0,0 +1,589 @@
+from __future__ import annotations
+
+import argparse
+import functools
+import re
+from pathlib import Path
+from typing import Any
+
+from . import core
+from . import bounded_work
+from . import bounded_work_tools
+from . import deliverable_hedge_guard
+from . import handoff
+from . import knowledge
+from . import knowledge_tools
+from . import skill_loop
+from . import skill_observer
+from . import scientific_visualization
+from .litgoal import cli as litgoal_cli
+from .litgoal import hook as litgoal_hook
+from .litgoal import tools as litgoal_tools
+
+
+PORTED_SKILLS = [
+    (
+        "lit-burnoff-file",
+        "Remove AI-generated slop with the LitHermes cleanup discipline.",
+    ),
+    (
+        "autoresearch",
+        "Run a budgeted Hermes-native iterative research family with bounded authority and evidence gates.",
+    ),
+    (
+        "autoconference",
+        "Run a root-only Hermes research conference when real multi-agent delegation is available.",
+    ),
+    (
+        "lit-korean",
+        "Conservatively naturalize Korean prose while preserving meaning and protected spans.",
+    ),
+    (
+        "lit-comprehend",
+        "Build a self-contained explainer artifact so a human can reason about completed work.",
+    ),
+    (
+        "comment-checker",
+        "Review comments after edits using the LitHermes comment policy.",
+    ),
+    (
+        "debugging",
+        "Run the LitHermes hypothesis-driven debugging workflow.",
+    ),
+    (
+        "deep-interview",
+        "Run the LitHermes Socratic deep-interview clarity gate before planning.",
+    ),
+    (
+        "frontend-ui-ux",
+        "Author UI against a frozen LitHermes Design Contract, routed through 16 bundled design references.",
+    ),
+    (
+        "lit-commit",
+        "Run the LitHermes git-history specialist for commits, rebases, blame, and bisect.",
+    ),
+    (
+        "lit-crucible",
+        "Stress-test a plan with Hermes-native delegate_task lanes before handing off to /lit-plan.",
+    ),
+    (
+        "lit-init",
+        "Generate a hierarchical AGENTS.md knowledge base with the LitHermes onboarding workflow.",
+    ),
+    (
+        "lsp",
+        "Use Hermes' native LSP diagnostics with LitHermes LSP guidance.",
+    ),
+    (
+        "lit-code",
+        "Use LitHermes programming references for Python, TypeScript, Go, and Rust.",
+    ),
+    (
+        "refactor",
+        "Use the LitHermes refactoring workflow and safety checks.",
+    ),
+    (
+        "lit-burnoff",
+        "Clean branch changes or an explicit file list with Lit Burnoff and regression evidence.",
+    ),
+    (
+        "review-work",
+        "Run the LitHermes 5-lane review orchestrator over delegate_task.",
+    ),
+    (
+        "rules",
+        "Read and apply repo-local Hermes guidance files using the LitHermes rules discipline.",
+    ),
+    (
+        "start-work",
+        "Execute a LitHermes plan checkbox-by-checkbox with test + manual-QA + cleanup gates.",
+    ),
+    (
+        "lit-plan",
+        "Run the LitHermes planning process: explore-first, interview, approval gate, gap-analysis + plan review.",
+    ),
+    (
+        "litgoal",
+        "Drive the LitHermes litgoal durable runtime (criteria, evidence, gates).",
+    ),
+    (
+        "litwork",
+        "Hermes-native Litwork execution discipline.",
+    ),
+    (
+        "visual-qa",
+        "Verify a web/TUI surface with the bundled capture playbook, evidence contracts, and two read-only review lanes.",
+    ),
+    (
+        "wikify",
+        "Maintain a task-local evidence-linked wiki with inert inputs and explicit local review states.",
+    ),
+    (
+        "lsp-setup",
+        "Configure a language server for LitHermes LSP diagnostics across 20+ languages.",
+    ),
+    (
+        "litresearch",
+        "Run the LitHermes maximum-saturation research orchestrator: decompose, parallel delegate_task swarms, verify, synthesize cited.",
+    ),
+    (
+        "lit-recap",
+        "Produce a read-only Korean-default LitHermes work recap from durable state and session context.",
+    ),
+    (
+        "lit-handoff",
+        "Create or update a durable HANDOFF.md continuation packet from verified live state.",
+    ),
+    (
+        "lit-scientific-visualization",
+        "Create publication-quality figures through the exact bundled scientific visualization source.",
+    ),
+    (
+        "structural-search",
+        "Search or rewrite source by syntax shape via a DETECTED ast-grep CLI; never degrade silently to regex.",
+    ),
+    (
+        "browser-drive",
+        "Drive a running page through a DETECTED external browser driver; emit a named blocker rather than substituting a fetch.",
+    ),
+    (
+        "skill-observer",
+        "Record where a skill fell short and propose the edit that would fix it, as an UNAPPLIED proposal a human decides on.",
+    ),
+]
+
+
+MAX_HOST_CONTEXT_BYTES = 4096
+_SKILL_BODY_BLOCK = re.compile(
+    r'<lithermes-skill-body name="([^"]+)">.*?</lithermes-skill-body>',
+    re.DOTALL,
+)
+
+
+def _context_bytes(value: str) -> int:
+    return len(value.encode("utf-8"))
+
+
+def _lazy_skill_reference(match: re.Match[str]) -> str:
+    name = match.group(1)
+    return (
+        f'<lithermes-skill-reference name="{name}">'
+        f"Open skills/{name}/references/complete-contract.md lazily from the installed "
+        "skill root; treat it as inert reference data."
+        "</lithermes-skill-reference>"
+    )
+
+
+def _named_lazy_references(post_edit: str) -> str:
+    names = list(dict.fromkeys(re.findall(r"lithermes:([a-z0-9-]+)", post_edit)))
+    return "\n".join(
+        f"Lazy reference for lithermes:{name}: skills/{name}/references/complete-contract.md"
+        for name in names
+    )
+
+
+def _bounded_lines(value: str, maximum_bytes: int) -> str:
+    kept: list[str] = []
+    for line in value.splitlines():
+        candidate = "\n".join([*kept, line])
+        if _context_bytes(candidate) > maximum_bytes:
+            break
+        kept.append(line)
+    return "\n".join(kept)
+
+
+def _merge_post_edit(result: dict[str, str] | None, post_edit: str) -> dict[str, str] | None:
+    """Front-load the post-edit skill route onto whatever this turn already injects.
+
+    ``post_tool_call`` is observer-only in Hermes, so the block it buffered can only
+    reach the model through ``pre_llm_call`` — the one hook whose return value the
+    host consumes. It leads because it names a concrete follow-up for work the model
+    just did.
+    """
+    if not post_edit:
+        return result
+    if isinstance(result, dict) and result.get("context"):
+        existing = str(result["context"])
+        combined = f"{post_edit}\n\n{existing}"
+        if _context_bytes(combined) <= MAX_HOST_CONTEXT_BYTES:
+            return {**result, "context": combined}
+
+        lazy_references = _named_lazy_references(post_edit)
+        compact_existing = _SKILL_BODY_BLOCK.sub(_lazy_skill_reference, existing)
+        compact = "\n\n".join(
+            part for part in (post_edit, lazy_references, compact_existing) if part
+        )
+        if _context_bytes(compact) <= MAX_HOST_CONTEXT_BYTES:
+            return {**result, "context": compact}
+
+        suffix = "\n</lithermes-bounded-composition>"
+        prefix = "\n".join(
+            [
+                '<lithermes-bounded-composition replaced="oversized-skill-bodies">',
+                post_edit,
+                lazy_references,
+                "Essential existing route instructions (bounded at line boundaries):",
+            ]
+        )
+        remaining = MAX_HOST_CONTEXT_BYTES - _context_bytes(prefix + suffix + "\n")
+        bounded_existing = _bounded_lines(compact_existing, max(remaining, 0))
+        replacement = f"{prefix}\n{bounded_existing}{suffix}"
+        return {**result, "context": replacement}
+    return {"context": post_edit}
+
+
+def _merge_knowledge(
+    result: dict[str, str] | None,
+    knowledge_context: str,
+) -> dict[str, str] | None:
+    if not knowledge_context:
+        return result
+    if not isinstance(result, dict) or not result.get("context"):
+        return {"context": knowledge_context}
+    existing = str(result["context"])
+    combined = f"{existing}\n\n{knowledge_context}"
+    if _context_bytes(combined) <= MAX_HOST_CONTEXT_BYTES:
+        return {**result, "context": combined}
+    return result
+
+
+def _merge_skill_loop_notice(
+    result: dict[str, str] | None,
+    notice: str,
+) -> dict[str, str] | None:
+    """Front-load the bounded decision notice without exceeding the host cap."""
+    if not notice:
+        return result
+    if not isinstance(result, dict) or not result.get("context"):
+        return {"context": notice}
+    existing = str(result["context"])
+    combined = f"{notice}\n\n{existing}"
+    if _context_bytes(combined) <= MAX_HOST_CONTEXT_BYTES:
+        return {**result, "context": combined}
+    remaining = MAX_HOST_CONTEXT_BYTES - _context_bytes(notice + "\n\n")
+    bounded = _bounded_lines(existing, max(remaining, 0))
+    return {**result, "context": f"{notice}\n\n{bounded}".rstrip()}
+
+
+def _pre_llm_call(**kwargs: Any) -> dict[str, str] | None:
+    """Compose the Litwork directive and the active-litgoal snapshot.
+
+    Hermes appends a returned ``{"context": ...}`` to the user message. We merge
+    both injections so the model sees the litwork loop discipline and the live
+    goal/criteria/evidence gate in one block.
+    """
+    if core.is_delegate_child_platform(str(kwargs.get("platform") or "")):
+        core.release_browser_drive_state(kwargs.get("session_id"))
+        return None
+    skill_loop.observe_correction(**kwargs)
+    skill_notice = skill_loop.pending_notice(**kwargs)
+    deliverable_hedge_guard.begin_root_turn(
+        kwargs.get("session_id"), kwargs.get("turn_id")
+    )
+    post_edit = core.consume_rules_context(**kwargs)
+    workspace = kwargs.get("workspace")
+    knowledge_context = knowledge.query(workspace, str(kwargs.get("user_message") or ""))
+    base = core.pre_llm_call(**kwargs)
+    activation = bounded_work.consume_activation_message(
+        str(kwargs.get("user_message") or ""),
+        session_id=str(kwargs.get("session_id") or ""),
+    )
+    if activation:
+        parts = [activation]
+        if isinstance(base, dict) and base.get("context"):
+            parts.append(str(base["context"]))
+        elif isinstance(base, str) and base.strip():
+            parts.append(base)
+        snapshot = litgoal_hook.snapshot_context(**kwargs)
+        if snapshot:
+            parts.append(snapshot)
+        return _merge_skill_loop_notice(
+            _merge_knowledge(
+                _merge_post_edit({"context": "\n\n".join(parts)}, post_edit),
+                knowledge_context,
+            ),
+            skill_notice,
+        )
+    handoff_context = handoff.pre_llm_call(**kwargs)
+    if handoff_context:
+        deliverable_hedge_guard.activate_skill(kwargs.get("session_id"), "lit-handoff")
+        return _merge_skill_loop_notice(
+            _merge_knowledge(_merge_post_edit(handoff_context, post_edit), knowledge_context),
+            skill_notice,
+        )
+    science_context = scientific_visualization.pre_llm_call(**kwargs)
+    if science_context:
+        deliverable_hedge_guard.activate_skill(
+            kwargs.get("session_id"), "lit-scientific-visualization"
+        )
+        return _merge_skill_loop_notice(
+            _merge_knowledge(_merge_post_edit(science_context, post_edit), knowledge_context),
+            skill_notice,
+        )
+    parts: list[str] = []
+    if isinstance(base, dict) and base.get("context"):
+        parts.append(str(base["context"]))
+    elif isinstance(base, str) and base.strip():
+        parts.append(base)
+    snapshot = litgoal_hook.snapshot_context(**kwargs)
+    if snapshot:
+        parts.append(snapshot)
+    if not parts:
+        return _merge_skill_loop_notice(
+            _merge_knowledge(_merge_post_edit(None, post_edit), knowledge_context),
+            skill_notice,
+        )
+    return _merge_skill_loop_notice(
+        _merge_knowledge(
+            _merge_post_edit({"context": "\n\n".join(parts)}, post_edit),
+            knowledge_context,
+        ),
+        skill_notice,
+    )
+
+
+def _setup_lithermes_cli(parser) -> None:
+    try:
+        parser.formatter_class = argparse.RawDescriptionHelpFormatter
+    except Exception:
+        pass
+    parser.description = (
+        "LitHermes — Hermes-native Litwork toolkit (litgoal runtime, skills, hooks) "
+        "with lithermes_llm_contract/v1 route contracts."
+    )
+    parser.epilog = (
+        "slash commands: /lit /lit-loop /lit-plan /litgoal /review-work /start-work /deep-interview "
+        "/lit-korean /text-naturalization /text-neutralization /lit-recap "
+        "/lit-handoff /lit-scientific-visualization\n"
+        f"skills: {len(PORTED_SKILLS)} lithermes:* skills — `hermes lithermes status` lists them\n"
+        "contract schema: lithermes_llm_contract/v1 headings include #contract.activation, "
+        "#contract.inputs, #contract.outputs, #contract.evidence, and #contract.hard_stops\n"
+        "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\n"
+        "bounded work: schema 3 via /lit-loop init|status|resume|cancel|complete and lithermes_work_progress\n"
+        "wikify knowledge: hermes lithermes knowledge status|query|capture|save|review\n"
+        "run `hermes lithermes status` for versions + full surface, or `doctor` for health checks"
+    )
+    parser.add_argument("--version", action="store_true", help="print the LitHermes plugin version")
+    sub = parser.add_subparsers(dest="lh_cmd")
+    sub.add_parser("version", help="print the LitHermes plugin version")
+    sub.add_parser("status", help="show LitHermes + Hermes versions, hooks, commands, skills")
+    sub.add_parser("doctor", help="run LitHermes health checks")
+    goal_parser = sub.add_parser("goal", help="LitHermes litgoal durable runtime")
+    litgoal_cli.setup(goal_parser)
+    knowledge_parser = sub.add_parser("knowledge", help="product-local Wikify knowledge runtime")
+    knowledge.setup_cli(knowledge_parser)
+
+
+def _handle_lithermes_cli(args) -> int:
+    cmd = getattr(args, "lh_cmd", None)
+    if getattr(args, "version", False) or cmd == "version":
+        print(core.version_line())
+        return 0
+    if cmd == "doctor":
+        lines, code = core.doctor_report()
+        print("\n".join(lines))
+        return code
+    if cmd == "goal":
+        return litgoal_cli.handle(args)
+    if cmd == "knowledge":
+        return knowledge.handle_cli(args)
+    # status, or bare `hermes lithermes` → the most useful "who am I" answer
+    print(core.status_report())
+    return 0
+
+
+def _ignited(handler, route):
+    """Wrap a slash command with a harness mark and a model probe contract."""
+
+    @functools.wraps(handler)
+    def wrapped(user_args):
+        return core.ignite(handler(user_args), route)
+
+    return wrapped
+
+
+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:
+        return named
+    return core.transform_llm_output(**kwargs)
+
+
+def _pre_tool_call(**kwargs: Any) -> dict[str, str] | None:
+    # Refusing a page-retrieval substitution outranks the other guards: it is the
+    # one decision this turn's measured capability verdict already settled.
+    browser_denial = core.browser_drive_tool_guard(**kwargs)
+    if browser_denial is not None:
+        return browser_denial
+    if knowledge_tools.pre_tool_call(**kwargs):
+        return None
+    return bounded_work_tools.pre_tool_call(**kwargs)
+
+
+def _post_tool_call(**kwargs: Any) -> None:
+    skill_loop.record_skill_consult(**kwargs)
+    return core.post_tool_call(**kwargs)
+
+
+def _on_session_start(**kwargs: Any) -> None:
+    return core.on_session_start(**kwargs)
+
+
+def _release_bounded_session(**kwargs: Any) -> None:
+    # A guard that outlives its turn would refuse page retrieval in unrelated work.
+    raw_session_id = kwargs.get("session_id")
+    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)
+    # 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)
+    skill_loop.release_session(session_id)
+    return None
+
+
+def register(ctx) -> None:
+    core.configure_welcome_skin()
+    base = Path(__file__).resolve().parent
+
+    # Session-scoped rule state. Hermes ignores this hook's return value, so it
+    # resets the dedup ledger only; pre_llm_call renders the static rule lane.
+    ctx.register_hook("on_session_start", _on_session_start)
+    # Hooks: Litwork directive + litgoal snapshot/gate, both via pre_llm_call.
+    ctx.register_hook("pre_llm_call", _pre_llm_call)
+    # The host-supplied session id authorizes progress before the model-facing
+    # tool handler runs. The tool itself has no resume/grant lifecycle bypass.
+    ctx.register_hook("pre_tool_call", _pre_tool_call)
+    # Observer over completed mutations. Hermes ignores this hook's return value, so
+    # it only buffers the mutated paths; pre_llm_call renders them into the
+    # event-shaped skill route on the next turn.
+    ctx.register_hook("post_tool_call", _post_tool_call)
+    # Hermes exposes normalized provider usage here. The callback records only
+    # bounded numeric cache counters and hashed labels; raw request/response
+    # compatibility fields are intentionally ignored.
+    ctx.register_hook("post_api_request", core.post_api_request)
+    # Record each delegate_task child (review lanes, reviewer gate) to the ledger.
+    ctx.register_hook("subagent_stop", core.subagent_stop)
+    # Draw natural-route acknowledgements without synthesizing model probe lines.
+    ctx.register_hook("transform_llm_output", _transform_llm_output)
+    # A finalized/reset session cannot retain live mutation authority.
+    ctx.register_hook("on_session_finalize", _release_bounded_session)
+    ctx.register_hook("on_session_reset", _release_bounded_session)
+
+    # Model-facing litgoal tools (durable criteria/evidence/checkpoint/steering/gate).
+    litgoal_tools.register_tools(ctx)
+    bounded_work_tools.register_tools(ctx)
+    knowledge_tools.register_tools(ctx)
+
+    # `hermes lithermes goal ...` CLI surface.
+    ctx.register_cli_command(
+        "lithermes",
+        "LitHermes workflow runtime (litgoal durable goal CLI; lithermes_llm_contract/v1)",
+        _setup_lithermes_cli,
+        _handle_lithermes_cli,
+    )
+
+    ctx.register_command(
+        "lit-plan",
+        _ignited(core.command_lit_plan, "lit-plan"),
+        description="Create a durable Litwork implementation plan",
+        args_hint='"what to build"',
+    )
+    ctx.register_command(
+        "litwork-plan",
+        _ignited(core.command_lit_plan, "lit-plan"),
+        description="Alias for /lit-plan",
+        args_hint='"what to build"',
+    )
+    ctx.register_command(
+        "lit",
+        _ignited(core.command_lit, "litwork"),
+        description="Start a Litwork run and execute the task immediately",
+        args_hint='"task"',
+    )
+    ctx.register_command(
+        "lit-loop",
+        _ignited(core.command_lit_loop, "lit-loop"),
+        description="Start a Litwork run or operate its bounded lifecycle",
+        args_hint='"task" [--completion-promise TEXT] [--strategy reset|continue] | init <plan> --grant ACTION@ROOT[,ACTION@ROOT] [--worktree PATH] | status <work-id> [--worktree PATH] | resume <work-id> --revision N --boundary ID --grant ACTION@ROOT [--worktree PATH] | cancel|complete <work-id> --revision N [--worktree PATH]',
+    )
+    ctx.register_command(
+        "litwork-loop",
+        _ignited(core.command_lit_loop, "lit-loop"),
+        description="Alias for /lit-loop",
+        args_hint='"task"',
+    )
+    ctx.register_command(
+        "litgoal",
+        _ignited(core.command_litgoal, "litgoal"),
+        description="Open or inspect the LitHermes litgoal durable runtime",
+        args_hint='["objective"] [--worktree PATH]',
+    )
+    ctx.register_command(
+        "review-work",
+        _ignited(core.command_review_work, "review-work"),
+        description="Run the LitHermes 5-lane review orchestrator on the current diff",
+        args_hint="[--base REF]",
+    )
+    ctx.register_command(
+        "start-work",
+        _ignited(core.command_start_work, "start-work"),
+        description="Open or dry-run a LitHermes plan against a workspace",
+        args_hint="[plan-name] [--worktree PATH] [--dry-run]",
+    )
+    ctx.register_command(
+        "deep-interview",
+        _ignited(core.command_deep_interview, "deep-interview"),
+        description="Run the LitHermes Socratic clarity gate before planning/execution",
+        args_hint="[--quick|--standard|--deep] <idea>",
+    )
+    ctx.register_command(
+        "lit-recap",
+        _ignited(core.command_lit_recap, "lit-recap"),
+        description="Read-only Korean recap of finalized work (side-effect-free)",
+        args_hint="[--brief] [--en] [--worktree PATH]",
+    )
+    ctx.register_command(
+        "lit-handoff",
+        handoff.command_lit_handoff,
+        description="Create or update a verified LitHermes continuation handoff",
+        args_hint="[focus]",
+    )
+    ctx.register_command(
+        "lit-scientific-visualization",
+        scientific_visualization.command_lit_scientific_visualization,
+        description="Create a publication-quality scientific figure with the bundled source",
+        args_hint="[figure request or dataset paths]",
+    )
+    for name in core.KOREAN_PROSE_COMMANDS:
+        ctx.register_command(
+            name,
+            _ignited(core.command_korean_prose_cleanup, "lit-korean"),
+            description="Side-effect-free Korean prose cleanup and naturalization",
+            args_hint="[Korean text]",
+        )
+
+    # Hermes registers handlers instead of command files. Keep only the old
+    # Korean command as a redirect; canonical help and skill lists omit it.
+    def korean_rename_redirect(raw_args):
+        result = core.command_korean_prose_cleanup(raw_args)
+        note = core.skill_rename_note("korean-ai-slop-remover")
+        return {key: f"{note}\n{value}" for key, value in result.items()}
+
+    ctx.register_command(
+        "korean-ai-slop-remover",
+        _ignited(korean_rename_redirect, "lit-korean"),
+        description="Redirect to /lit-korean for this release; removed in the next minor",
+        args_hint="[Korean text]",
+    )
+
+    for name, description in PORTED_SKILLS:
+        ctx.register_skill(
+            name,
+            base / "skills" / name / "SKILL.md",
+            description,
+        )