lithermes-ai 0.5.0

package/assets/lithermes-plugin/litgoal/store.py

@@ -0,0 +1,93 @@
+"""Path resolution + atomic persistence for the litgoal durable runtime."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from . import model
+
+# Anchor every litgoal path under the constant declared in core (dual-context).
+try:  # installed as lithermes.litgoal.store
+    from ..core import LITGOAL_STATE_DIRNAME
+except (ImportError, ModuleNotFoundError):  # pragma: no cover - standalone import fallback
+    try:
+        from core import LITGOAL_STATE_DIRNAME  # type: ignore
+    except (ImportError, ModuleNotFoundError):
+        LITGOAL_STATE_DIRNAME = "litgoal"
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def state_dir(workspace: Path) -> Path:
+    return Path(workspace) / ".hermes" / "lithermes" / LITGOAL_STATE_DIRNAME
+
+
+def goals_path(workspace: Path) -> Path:
+    return state_dir(workspace) / "goals.json"
+
+
+def ledger_path(workspace: Path) -> Path:
+    return state_dir(workspace) / "ledger.jsonl"
+
+
+def evidence_dir(workspace: Path) -> Path:
+    return state_dir(workspace) / "evidence"
+
+
+def brief_path(workspace: Path) -> Path:
+    return state_dir(workspace) / "brief.md"
+
+
+def load_or_create(workspace: Path) -> model.LitgoalState:
+    path = goals_path(workspace)
+    if path.exists():
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return model.LitgoalState.from_dict(data)
+    return model.LitgoalState(created_at=_utc_now(), updated_at=_utc_now())
+
+
+def save(workspace: Path, state: model.LitgoalState) -> None:
+    state.updated_at = _utc_now()
+    if not state.created_at:
+        state.created_at = state.updated_at
+    target = goals_path(workspace)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    payload = json.dumps(model.to_dict(state), indent=2, sort_keys=False, ensure_ascii=False)
+    # Atomic: write to a temp file in the same dir, fsync, then os.replace.
+    fd, tmp_name = tempfile.mkstemp(dir=str(target.parent), suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(payload + "\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp_name, target)
+        # Best-effort: fsync the parent directory so the rename is durable.
+        try:
+            dir_fd = os.open(str(target.parent), os.O_RDONLY)
+            try:
+                os.fsync(dir_fd)
+            finally:
+                os.close(dir_fd)
+        except (OSError, PermissionError):
+            pass  # platforms that disallow dir-fsync degrade silently
+    finally:
+        if os.path.exists(tmp_name):
+            os.remove(tmp_name)
+
+
+def append_ledger(workspace: Path, event: dict[str, Any]) -> None:
+    path = ledger_path(workspace)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    entry = {"at": _utc_now(), **event}
+    # NOTE: ledger appends are best-effort append-durable; no fsync here to keep
+    # high-frequency event writes cheap. Data loss on crash is limited to the
+    # last unflushed entry; goals.json (the source of truth) is fsync-durable.
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(entry, ensure_ascii=False) + "\n")

package/assets/lithermes-plugin/litgoal/tools.py

@@ -0,0 +1,228 @@
+"""Model-facing litgoal tools (registered via ctx.register_tool).
+
+These layer durable criteria/evidence/checkpoint/steering/gate tracking on top of
+Hermes' native goal system. They operate on the current workspace (cwd). Each
+returns a JSON string for the model.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Callable
+
+from . import model, runtime, store
+
+TOOLSET = "lithermes-goal"
+
+
+def _workspace() -> Path:
+    return Path.cwd()
+
+
+def _json(obj: Any) -> str:
+    return json.dumps(obj, ensure_ascii=False, indent=2)
+
+
+def _snapshot(workspace: Path) -> dict[str, Any]:
+    goal = runtime.get_active(workspace)
+    if goal is None:
+        return {"active_goal": None}
+    gate = runtime.quality_gate(workspace)
+    return {
+        "active_goal": {
+            "id": goal.id,
+            "objective": goal.objective,
+            "title": goal.title,
+            "status": goal.status,
+            "criteria": [
+                {
+                    "id": c.id,
+                    "scenario": c.scenario,
+                    "qa_channel": c.qa_channel,
+                    "test_ref": c.test_ref,
+                    "status": c.status,
+                    "evidence_kinds": sorted({e.kind for e in c.evidence}),
+                }
+                for c in goal.criteria
+            ],
+            "unresolved_blockers": [b.id for b in goal.review_blockers if not b.resolved],
+        },
+        "quality_gate": gate,
+    }
+
+
+# -- tool handlers (args: dict) -> str --------------------------------------
+
+def tool_goal_status(args: dict | None = None, **kwargs) -> str:
+    return _json(_snapshot(_workspace()))
+
+
+def tool_goal_set(args: dict, **kwargs) -> str:
+    ws = _workspace()
+    objective = str((args or {}).get("objective", "")).strip()
+    title = str((args or {}).get("title", "")).strip()
+    criteria = (args or {}).get("criteria") or []
+    runtime.create_goal(ws, objective, title=title, criteria=criteria)
+    return _json(_snapshot(ws))
+
+
+def tool_goal_add_criterion(args: dict, **kwargs) -> str:
+    ws = _workspace()
+    crit = runtime.add_criterion(
+        ws,
+        str((args or {}).get("scenario", "")),
+        qa_channel=str((args or {}).get("qa_channel", "")),
+        test_ref=str((args or {}).get("test_ref", "")),
+    )
+    return _json({"criterion_id": crit.id, **_snapshot(ws)})
+
+
+def tool_goal_evidence(args: dict, **kwargs) -> str:
+    ws = _workspace()
+    runtime.add_evidence(
+        ws,
+        str((args or {}).get("criterion_id", "")),
+        str((args or {}).get("kind", "note")),
+        str((args or {}).get("ref", "")),
+        str((args or {}).get("detail", "")),
+    )
+    return _json(_snapshot(ws))
+
+
+def tool_goal_criterion_status(args: dict, **kwargs) -> str:
+    ws = _workspace()
+    runtime.set_criterion_status(
+        ws, str((args or {}).get("criterion_id", "")), str((args or {}).get("status", ""))
+    )
+    return _json(_snapshot(ws))
+
+
+def tool_goal_steer(args: dict, **kwargs) -> str:
+    ws = _workspace()
+    try:
+        runtime.record_steering(
+            ws,
+            str((args or {}).get("directive", "")),
+            kind=str((args or {}).get("kind", "redirect")) or "redirect",
+        )
+    except ValueError as exc:
+        return _json({"rejected": True, "reason": str(exc), **_snapshot(ws)})
+    return _json(_snapshot(ws))
+
+
+def tool_goal_checkpoint(args: dict, **kwargs) -> str:
+    ws = _workspace()
+    runtime.record_checkpoint(
+        ws,
+        str((args or {}).get("summary", "")),
+        active_criterion=str((args or {}).get("active_criterion", "")),
+    )
+    return _json(_snapshot(ws))
+
+
+def tool_goal_complete(args: dict | None = None, **kwargs) -> str:
+    return _json(runtime.complete_goal(_workspace()))
+
+
+def _spec(name: str, description: str, handler: Callable, properties: dict, required: list[str]) -> dict:
+    return {
+        "name": name,
+        "toolset": TOOLSET,
+        "description": description,
+        "handler": handler,
+        "schema": {
+            "type": "object",
+            "properties": properties,
+            "required": required,
+            "additionalProperties": False,
+        },
+    }
+
+
+TOOL_SPECS: list[dict] = [
+    _spec("goal_status", "Show the active LitHermes litgoal, its criteria, evidence, and quality gate.", tool_goal_status, {}, []),
+    _spec(
+        "goal_set",
+        "Create the active litgoal with an objective and optional upfront success criteria.",
+        tool_goal_set,
+        {
+            "objective": {"type": "string", "description": "the concrete user-visible objective"},
+            "title": {"type": "string"},
+            "criteria": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "scenario": {"type": "string"},
+                        "qa_channel": {"type": "string", "enum": ["http", "tmux", "browser", "computer", "cli"]},
+                        "test_ref": {"type": "string"},
+                    },
+                    "required": ["scenario"],
+                },
+            },
+        },
+        ["objective"],
+    ),
+    _spec(
+        "goal_add_criterion",
+        "Add one success criterion (scenario + QA channel + test reference) to the active goal.",
+        tool_goal_add_criterion,
+        {
+            "scenario": {"type": "string"},
+            "qa_channel": {"type": "string", "enum": ["http", "tmux", "browser", "computer", "cli"]},
+            "test_ref": {"type": "string"},
+        },
+        ["scenario"],
+    ),
+    _spec(
+        "goal_evidence",
+        "Attach evidence (red|green|scenario|cleanup|note) to a criterion.",
+        tool_goal_evidence,
+        {
+            "criterion_id": {"type": "string"},
+            "kind": {"type": "string", "enum": ["red", "green", "scenario", "cleanup", "note"]},
+            "ref": {"type": "string", "description": "test id or artifact path"},
+            "detail": {"type": "string"},
+        },
+        ["criterion_id", "kind", "ref"],
+    ),
+    _spec(
+        "goal_criterion_status",
+        "Set a criterion status (pending|in_progress|blocked|pass|fail).",
+        tool_goal_criterion_status,
+        {
+            "criterion_id": {"type": "string"},
+            "status": {"type": "string", "enum": list(model.CRITERION_STATUSES)},
+        },
+        ["criterion_id", "status"],
+    ),
+    _spec(
+        "goal_steer",
+        "Record a steering directive that redirects or extends the active goal mid-flight. "
+        "Refused if it tries to weaken the completion gate (skip tests/QA/review or auto-complete).",
+        tool_goal_steer,
+        {
+            "directive": {"type": "string"},
+            "kind": {"type": "string", "enum": list(model.STEERING_KINDS)},
+        },
+        ["directive"],
+    ),
+    _spec("goal_checkpoint", "Record a durable checkpoint snapshot for resume.", tool_goal_checkpoint, {"summary": {"type": "string"}, "active_criterion": {"type": "string"}}, ["summary"]),
+    _spec("goal_complete", "Attempt to complete the goal; refused with reasons unless the quality gate passes.", tool_goal_complete, {}, []),
+]
+
+
+def register_tools(ctx) -> list[str]:
+    """Register every litgoal tool on the plugin context. Returns the names."""
+    names: list[str] = []
+    for spec in TOOL_SPECS:
+        ctx.register_tool(
+            name=spec["name"],
+            toolset=spec["toolset"],
+            schema=spec["schema"],
+            handler=spec["handler"],
+            description=spec["description"],
+        )
+        names.append(spec["name"])
+    return names