@litfamily/lithermes 1.0.0

package/assets/lithermes-plugin/core_runs.py

@@ -0,0 +1,283 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+try:
+    from .core_contract import (
+        _skill_body_block,
+        contract_route_block,
+        reader_facing_contract_block,
+    )
+    from .core_plans import build_goal_instruction, extract_success_criteria
+    from .core_runtime import _clamp_task, append_jsonl, lithermes_dir, plan_dir, record_event, run_id, slugify, utc_now
+    from .redaction import redact_obj
+except (ImportError, ModuleNotFoundError):
+    from core_contract import (
+        _skill_body_block,
+        contract_route_block,
+        reader_facing_contract_block,
+    )
+    from core_plans import build_goal_instruction, extract_success_criteria
+    from core_runtime import _clamp_task, append_jsonl, lithermes_dir, plan_dir, record_event, run_id, slugify, utc_now
+    from redaction import redact_obj
+
+def build_notepad(task: str, criteria: list[dict[str, str]]) -> str:
+    crit_lines = [
+        f"- {c['id']} [{_clamp_task(c.get('qa_channel') or '?')}] {_clamp_task(c.get('scenario') or '')} (test: {_clamp_task(c.get('test_ref') or '?')})"
+        for c in criteria
+    ] or ["- (define success criteria before claiming progress)"]
+    return "\n".join(
+        [
+            f"# Litwork Notepad — {task}",
+            f"Started: {utc_now().isoformat()}",
+            "",
+            "## Plan (exhaustively detailed)",
+            "<every atomic step, in order>",
+            "",
+            "## Success criteria + QA scenarios",
+            *crit_lines,
+            "",
+            "## Now",
+            "<the single step in progress>",
+            "",
+            "## Todo",
+            "<every remaining step, ordered>",
+            "",
+            "## Findings",
+            "<non-obvious facts with file:line refs>",
+            "",
+            "## Learnings",
+            "<patterns / pitfalls to remember next turn>",
+            "",
+        ]
+    )
+
+
+# The run ledger (.hermes/lithermes/runs/<id>/ledger.jsonl) is its OWN file with
+# its OWN vocabulary, keyed on `event`. It is not the litgoal ledger
+# (.hermes/lithermes/litgoal/**/ledger.jsonl), which is keyed on `kind` — see
+# litgoal.store.LEDGER_SCHEMA. Every entry written here is stamped with the id
+# below so a reader never has to guess which vocabulary a line belongs to.
+RUN_LEDGER_SCHEMA = "lithermes.run.ledger/v1"
+RUN_LEDGER_EVENTS = (
+    "run_started",
+    "criterion_started",
+    "test_red_captured",
+    "test_green_captured",
+    "scenario_executed",
+    "cleanup_receipt",
+    "criterion_complete",
+    "reviewer_verdict",
+)
+
+
+def record_criterion_event(run_dir: Path, criterion_id: str, event: str, **fields: Any) -> None:
+    """Append a TDD/QA criterion event to the run ledger.
+
+    `event` must be one of RUN_LEDGER_EVENTS. That tuple used to live only in
+    this docstring, where nothing enforced it and nothing read it; it is now the
+    single enforced definition of this file's vocabulary.
+
+    NOTE: no production code path calls this yet — the loop records its evidence
+    through the litgoal runtime instead. It is a real, tested API kept for the
+    run-ledger surface, not a dead docstring.
+    """
+    if event not in RUN_LEDGER_EVENTS:
+        raise ValueError(
+            "invalid run ledger event '{0}' (valid: {1})".format(event, RUN_LEDGER_EVENTS)
+        )
+    append_jsonl(
+        run_dir / "ledger.jsonl",
+        {
+            "schema": RUN_LEDGER_SCHEMA,
+            "event": event,
+            "at": utc_now().isoformat(),
+            "criterion_id": criterion_id,
+            **fields,
+        },
+    )
+
+
+def find_plan(name: str, workspace: Path) -> Path | None:
+    plans = plan_dir(workspace)
+    if not plans.exists():
+        return None
+
+    raw = name.strip()
+    if not raw:
+        candidates = sorted(plans.glob("*.md"), key=lambda p: p.stat().st_mtime, reverse=True)
+        return candidates[0] if candidates else None
+
+    direct = Path(raw).expanduser()
+    if direct.exists():
+        return direct.resolve()
+
+    slug = slugify(raw, fallback=raw)
+    candidates = [
+        plans / raw,
+        plans / f"{raw}.md",
+        plans / slug,
+        plans / f"{slug}.md",
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate.resolve()
+    return None
+
+
+def write_run_state(
+    workspace: Path,
+    *,
+    task: str,
+    command: str,
+    plan: Path | None = None,
+    completion_promise: str = "",
+    strategy: str = "continue",
+) -> Path:
+    task = _clamp_task(task)
+    completion_promise = _clamp_task(completion_promise)
+    rid = run_id("lithermes")
+    run_dir = lithermes_dir(workspace) / "runs" / rid
+    evidence_dir = run_dir / "evidence"
+    evidence_dir.mkdir(parents=True, exist_ok=True)
+
+    criteria: list[dict[str, str]] = []
+    if plan and plan.exists():
+        try:
+            criteria = redact_obj(extract_success_criteria(plan.read_text(encoding="utf-8")))
+        except OSError:
+            criteria = []
+
+    notepad = run_dir / "notepad.md"
+    notepad.write_text(build_notepad(task, criteria), encoding="utf-8")
+
+    state = {
+        "run_id": rid,
+        "created_at": utc_now().isoformat(),
+        "workspace": str(workspace),
+        "command": command,
+        "task": task,
+        "completion_promise": completion_promise,
+        "strategy": strategy,
+        "plan": str(plan) if plan else "",
+        "evidence_dir": str(evidence_dir),
+        "notepad_path": str(notepad),
+        "criteria": criteria,
+        "active_criterion": criteria[0]["id"] if criteria else "",
+    }
+    (run_dir / "state.json").write_text(
+        json.dumps(state, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    append_jsonl(
+        run_dir / "ledger.jsonl",
+        {"schema": RUN_LEDGER_SCHEMA, "event": "run_started", **state},
+    )
+    record_event("run_started", workspace=str(workspace), command=command, run_id=rid)
+    return run_dir
+
+
+def load_run_state(run_dir: Path) -> dict[str, Any]:
+    return json.loads((run_dir / "state.json").read_text(encoding="utf-8"))
+
+
+def _same_plan_path(recorded: str, plan: Path) -> bool:
+    if not recorded:
+        return False
+    try:
+        return Path(recorded).expanduser().resolve() == plan.resolve()
+    except OSError:
+        return str(Path(recorded).expanduser()) == str(plan)
+
+
+def latest_start_work_run(workspace: Path, plan: Path) -> Path | None:
+    runs_dir = lithermes_dir(workspace) / "runs"
+    if not runs_dir.exists():
+        return None
+
+    matches: list[tuple[str, float, Path]] = []
+    for state_file in runs_dir.glob("*/state.json"):
+        try:
+            state = json.loads(state_file.read_text(encoding="utf-8"))
+        except (OSError, ValueError, json.JSONDecodeError):
+            continue
+        if state.get("command") != "start-work":
+            continue
+        if not _same_plan_path(str(state.get("plan") or ""), plan):
+            continue
+        try:
+            modified = state_file.stat().st_mtime
+        except OSError:
+            modified = 0.0
+        matches.append((str(state.get("created_at") or ""), modified, state_file.parent))
+
+    if not matches:
+        return None
+    matches.sort(key=lambda item: (item[0], item[1]), reverse=True)
+    return matches[0][2]
+
+
+def build_run_agent_message(
+    state: dict[str, Any],
+    *,
+    include_reader_contract: bool = True,
+    return_mode: str | None = None,
+    return_mode_authority: str | None = None,
+) -> str:
+    plan_line = f"\nPlan: {state['plan']}" if state.get("plan") else ""
+    promise = state.get("completion_promise") or "Complete the requested task with evidence."
+    plan_path = Path(state["plan"]) if state.get("plan") else None
+    workspace = Path(state["workspace"]) if state.get("workspace") else None
+    reader_contract = reader_facing_contract_block(
+        return_mode,
+        authority=return_mode_authority,
+        boundary="parent_synthesis",
+    )
+    return "\n".join(
+        [
+            state["task"],
+            "",
+            build_goal_instruction(state["task"], plan=plan_path, workspace=workspace),
+            "",
+            "<lithermes-run-context>",
+            contract_route_block(str(state.get("command") or "run"), surface="run-context"),
+            f"run_id: {state['run_id']}",
+            f"workspace: {state['workspace']}",
+            f"evidence_dir: {state['evidence_dir']}",
+            f"ledger: {Path(state['evidence_dir']).parent / 'ledger.jsonl'}",
+            f"strategy: {state['strategy']}",
+            f"completion_promise: {promise}",
+            f"task: {state['task']}{plan_line}",
+            "",
+            "Execute this LitHermes request now. Inspect the workspace as needed,",
+            "keep useful evidence under evidence_dir, append meaningful progress to the ledger,",
+            "and answer the user with the result instead of stopping after run creation.",
+            "Loop each criterion RED->GREEN->manual-QA->cleanup-receipt; when the work is risky, spans 3+",
+            "files, or the user demanded rigour, run the reviewer gate (delegate_task a strict reviewer)",
+            "and loop until UNCONDITIONAL approval before declaring done.",
+            _skill_body_block("start-work" if state.get("command") == "start-work" else "litwork"),
+            *([reader_contract] if include_reader_contract else []),
+            "</lithermes-run-context>",
+        ]
+    )
+
+
+def build_dispatch_result(
+    run_dir: Path,
+    *,
+    display: str,
+    return_mode: str | None = None,
+    return_mode_authority: str | None = None,
+) -> dict[str, str]:
+    state = load_run_state(run_dir)
+    return {
+        "display": display,
+        "agent_message": build_run_agent_message(
+            state,
+            return_mode=return_mode,
+            return_mode_authority=return_mode_authority,
+        ),
+        "run_dir": str(run_dir),
+    }

package/assets/lithermes-plugin/core_runtime.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+import importlib
+import json
+import os
+import re
+import shlex
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterable
+
+try:
+    from .redaction import redact_obj, redact_text
+except (ImportError, ModuleNotFoundError):
+    from redaction import redact_obj, redact_text
+
+MAX_TASK_LEN = 4000
+_SLUG_PATTERN = re.compile(r"[^a-z0-9]+")
+
+try:
+    get_hermes_home = importlib.import_module("hermes_constants").get_hermes_home
+except Exception:
+    import os
+
+    def get_hermes_home() -> Path:
+        val = (os.environ.get("HERMES_HOME") or "").strip()
+        return Path(val).expanduser() if val else Path.home() / ".hermes"
+
+
+# Durable litgoal runtime state lives under <workspace>/.hermes/lithermes/<dir>.
+# This constant anchors every litgoal state path (goals/ledger/evidence).
+LITGOAL_STATE_DIRNAME = "litgoal"
+
+@dataclass(frozen=True)
+class CommandArgs:
+    positional: list[str]
+    options: dict[str, str | bool]
+
+def slugify(text: str, fallback: str = "lithermes-plan") -> str:
+    lowered = text.strip().lower()
+    slug = _SLUG_PATTERN.sub("-", lowered).strip("-")
+    return (slug[:60].strip("-") or fallback)
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def run_id(prefix: str = "run") -> str:
+    return f"{prefix}-{utc_now().strftime('%Y%m%dT%H%M%SZ')}-{uuid.uuid4().hex[:8]}"
+
+
+def parse_args(raw_args: str) -> CommandArgs:
+    try:
+        tokens = shlex.split(raw_args or "")
+    except ValueError as exc:
+        raise ValueError(f"could not parse arguments: {exc}") from exc
+
+    positional: list[str] = []
+    options: dict[str, str | bool] = {}
+    i = 0
+    while i < len(tokens):
+        token = tokens[i]
+        if not token.startswith("--"):
+            positional.append(token)
+            i += 1
+            continue
+
+        key_value = token[2:]
+        if not key_value:
+            i += 1
+            continue
+        if "=" in key_value:
+            key, value = key_value.split("=", 1)
+            options[key] = value
+            i += 1
+            continue
+        key = key_value
+        if i + 1 < len(tokens) and not tokens[i + 1].startswith("--"):
+            options[key] = tokens[i + 1]
+            i += 2
+        else:
+            options[key] = True
+            i += 1
+
+    return CommandArgs(positional=positional, options=options)
+
+
+def workspace_from_option(value: str | bool | None) -> Path:
+    if isinstance(value, str) and value.strip():
+        return Path(value).expanduser().resolve()
+    return Path.cwd().resolve()
+
+
+def plan_dir(workspace: Path) -> Path:
+    return workspace / "plans"
+
+
+def lithermes_dir(workspace: Path) -> Path:
+    return workspace / ".hermes" / "lithermes"
+
+
+def event_log_path() -> Path:
+    return get_hermes_home() / "lithermes" / "events.jsonl"
+
+
+class IsolationViolation(RuntimeError):
+    """A durable write escaped the declared isolation root."""
+
+
+# Set LITHERMES_ISOLATED_ROOT=<abs path> to declare "every durable write this
+# process makes must land under here". Any append that resolves outside raises
+# instead of silently succeeding.
+#
+# Why this lives at the EMITTER and not in each probe: the event ledger resolves
+# its own path from HERMES_HOME/HOME (`get_hermes_home`, which the Hermes host
+# owns in production), not from whatever workspace a caller passed. A probe can
+# isolate the workspace perfectly — the plan artifact lands in a temp dir — while
+# the ledger write still goes to the operator's real profile. That happened in
+# this repo twice, from two different call sites, each fixed per-probe. One guard
+# at the single write primitive covers every call site that exists now and every
+# one added later.
+#
+# Inert in production: with the variable unset this is a no-op and behaviour is
+# unchanged. It is the probe harness that sets it, once, for all probes.
+_ISOLATED_ROOT_ENV = "LITHERMES_ISOLATED_ROOT"
+
+
+def isolated_root() -> Path | None:
+    raw = (os.environ.get(_ISOLATED_ROOT_ENV) or "").strip()
+    if not raw:
+        return None
+    try:
+        return Path(raw).expanduser().resolve()
+    except OSError:
+        return None
+
+
+def assert_within_isolation(path: Path) -> None:
+    """Raise IsolationViolation when `path` escapes a declared isolation root."""
+    root = isolated_root()
+    if root is None:
+        return
+    try:
+        resolved = Path(path).expanduser().resolve()
+    except OSError:
+        resolved = Path(path)
+    try:
+        resolved.relative_to(root)
+    except ValueError:
+        raise IsolationViolation(
+            "refusing to write outside the declared isolation root.\n"
+            "  target : {0}\n"
+            "  root   : {1}\n"
+            "  {2} is set, so this write would have escaped the sandbox. "
+            "The emitter resolves its own path from HERMES_HOME/HOME; isolating a "
+            "workspace is not enough.".format(resolved, root, _ISOLATED_ROOT_ENV)
+        )
+
+
+def append_jsonl(path: Path, payload: dict[str, Any]) -> None:
+    assert_within_isolation(path)
+    payload = redact_obj(payload)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(payload, sort_keys=True) + "\n")
+
+
+def record_event(event: str, **fields: Any) -> None:
+    payload = {
+        "event": event,
+        "timestamp": utc_now().isoformat(),
+        **fields,
+    }
+    try:
+        append_jsonl(event_log_path(), payload)
+    except OSError:
+        pass
+
+
+_REMOTE_REF_RE = re.compile(r"https?://[^\s,;\"'<>]+", re.IGNORECASE)
+
+
+def _redact_local_only_preview(value: Any) -> str:
+    """Small local-only diagnostic preview for event metadata.
+
+    Delegate batch events must never become remote telemetry. Keep the preview
+    bounded, secret-redacted, and URL-redacted so audit logs prove intent without
+    preserving endpoints or pasted secret-bearing child context.
+    """
+    text = json.dumps(redact_obj(value), sort_keys=True) if not isinstance(value, str) else redact_text(value)
+    text = _REMOTE_REF_RE.sub("[REDACTED_URL]", text)
+    return text[:1000]
+
+
+def record_delegate_batch_intent(
+    *,
+    workspace: Path,
+    mode: str,
+    lanes: Iterable[str],
+    session_id: str = "",
+    context: Any = None,
+) -> dict[str, Any]:
+    """Record a local, redacted intent event for a Hermes delegate_task batch.
+
+    This is evidence only: it does not orchestrate workers, create persistent
+    teams, or send telemetry anywhere. Hermes performs the actual short
+    parallel work asynchronously and re-enters each child result separately; the parent owns receipt tracking, merging, and batch completion.
+    """
+    rid = run_id("lithermes")
+    batch_id = run_id("delegate-batch")
+    lane_list = [str(lane) for lane in lanes]
+    artifact_dir = lithermes_dir(workspace) / "runs" / rid / "delegate_batches" / batch_id
+    payload = {
+        "event": "delegate_batch_intent",
+        "timestamp": utc_now().isoformat(),
+        "session_id": session_id,
+        "run_id": rid,
+        "batch_id": batch_id,
+        "mode": mode,
+        "lanes": lane_list,
+        "artifact_dir": str(artifact_dir) + "/",
+    }
+    if context is not None:
+        payload["context_preview"] = _redact_local_only_preview(context)
+    try:
+        artifact_dir.mkdir(parents=True, exist_ok=True)
+        (artifact_dir / "summary.json").write_text(
+            json.dumps(redact_obj(payload), indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+    except OSError:
+        pass
+    try:
+        append_jsonl(event_log_path(), payload)
+    except OSError:
+        pass
+    return redact_obj(payload)
+
+def _clamp_task(task: str) -> str:
+    """Bound a triggered task before it enters route context or run-state.
+
+    A pasted multi-thousand-char prompt would otherwise inflate the injected
+    LIT_CONTEXT and the persisted run-state. Clamp to MAX_TASK_LEN chars.
+    """
+    task = redact_text(task).strip()
+    if len(task) > MAX_TASK_LEN:
+        return task[:MAX_TASK_LEN].rstrip() + " […]"
+    return task