write_approval.py 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413
  1. #!/usr/bin/env python3
  2. """Write-approval gate + pending store for memory and skill writes.
  3. A per-subsystem boolean ``write_approval`` gates the agent's cross-session writes —
  4. **memory** (MEMORY.md / USER.md) and **skills** (SKILL.md + files) — from either
  5. origin (**foreground** turn or **background_review** fork). ``false`` (default)
  6. writes freely; ``true`` never commits directly: it prompts inline (memory,
  7. interactive CLI only) or **stages** the write under
  8. ``<HERMES_HOME>/pending/{memory,skills}/<id>.json`` for out-of-band review.
  9. """
  10. from __future__ import annotations
  11. import difflib
  12. import json
  13. import logging
  14. import os
  15. import re
  16. import time
  17. import uuid
  18. from contextlib import suppress
  19. from dataclasses import dataclass
  20. from pathlib import Path
  21. from typing import Any, Dict, List, Optional
  22. from hermes_constants import get_hermes_home
  23. from utils import atomic_json_write
  24. logger = logging.getLogger(__name__)
  25. # Subsystem identifiers
  26. MEMORY = "memory"
  27. SKILLS = "skills"
  28. _SUBSYSTEMS = (MEMORY, SKILLS)
  29. # Per-subsystem config key. Intentionally a single boolean with no "block all writes"
  30. # state — to disable a subsystem use its own enable flag (e.g. ``memory.memory_enabled``).
  31. CONFIG_KEY = "write_approval"
  32. _TRUTHY_STRINGS = frozenset({"on", "true", "yes", "1", "approve", "enabled"})
  33. # --- Config resolution ---
  34. def write_approval_enabled(subsystem: str) -> bool:
  35. """Read ``<subsystem>.write_approval``; any unset/invalid value means gate off."""
  36. if subsystem not in _SUBSYSTEMS:
  37. return False
  38. try:
  39. from hermes_cli.config import load_config, cfg_get
  40. return _normalize_enabled(cfg_get(load_config(), subsystem, CONFIG_KEY, default=False))
  41. except Exception:
  42. return False
  43. def _normalize_enabled(value: Any) -> bool:
  44. """Coerce a config value to bool; unknown → False (gate off). The string branch
  45. covers hand-edited configs (YAML already parses bare on/off/yes/no)."""
  46. if isinstance(value, bool):
  47. return value
  48. return isinstance(value, str) and value.strip().lower() in _TRUTHY_STRINGS
  49. # --- Pending store (file-backed) ---
  50. def _pending_path(subsystem: str, pending_id: str) -> Path:
  51. return get_hermes_home() / "pending" / subsystem / f"{pending_id}.json"
  52. def _pending_files(subsystem: str) -> list:
  53. d = _pending_path(subsystem, "").parent
  54. return list(d.glob("*.json")) if d.exists() else []
  55. def stage_write(subsystem: str, payload: dict[str, Any], *, summary: str, origin: str) -> dict[str, Any]:
  56. """Persist a pending write and return its record (``id`` + metadata). ``payload`` is the exact
  57. kwargs to replay the write on approval; ``origin`` is ``foreground`` or ``background_review``.
  58. Best-effort: on disk failure it logs and still returns a record — the write is lost, which is
  59. the safe failure for an approval gate (nothing silently committed)."""
  60. pid = uuid.uuid4().hex[:8]
  61. record = {
  62. "id": pid, "subsystem": subsystem, "action": payload.get("action", ""),
  63. "summary": (summary or "").strip(), "origin": origin or "foreground",
  64. "created_at": time.time(), "payload": payload,
  65. }
  66. try:
  67. atomic_json_write(_pending_path(subsystem, pid), record)
  68. except Exception as e: # pragma: no cover - disk failure path
  69. logger.error("Failed to stage pending %s write: %s", subsystem, e, exc_info=True)
  70. return record
  71. def list_pending(subsystem: str) -> list[dict[str, Any]]:
  72. """Return all pending records for ``subsystem``, oldest first."""
  73. records: list[dict[str, Any]] = []
  74. for p in _pending_files(subsystem):
  75. try:
  76. record = json.loads(p.read_text(encoding="utf-8-sig"))
  77. if not isinstance(record, dict):
  78. raise ValueError(f"expected a JSON object, got {type(record).__name__}")
  79. records.append(record)
  80. except Exception:
  81. logger.warning("Skipping unreadable pending record: %s", p)
  82. records.sort(key=lambda r: r.get("created_at", 0))
  83. return records
  84. def get_pending(subsystem: str, pending_id: str) -> Optional[dict[str, Any]]:
  85. """Return a single pending record by id, or None."""
  86. path = _pending_path(subsystem, pending_id)
  87. if not path.exists():
  88. return None
  89. try:
  90. data = json.loads(path.read_text(encoding="utf-8-sig"))
  91. return data if isinstance(data, dict) else None
  92. except Exception:
  93. return None
  94. def discard_pending(subsystem: str, pending_id: str) -> bool:
  95. """Delete a pending record. Returns True if it existed."""
  96. try:
  97. path = _pending_path(subsystem, pending_id)
  98. if path.exists():
  99. path.unlink()
  100. return True
  101. except Exception as e: # pragma: no cover
  102. logger.error("Failed to discard pending %s/%s: %s", subsystem, pending_id, e)
  103. return False
  104. def pending_count(subsystem: str) -> int:
  105. """Cheap count of pending records (for notification badges)."""
  106. d = _pending_path(subsystem, "").parent
  107. if not d.exists():
  108. return 0
  109. with suppress(Exception):
  110. return sum(1 for _ in d.glob("*.json"))
  111. return 0
  112. # --- Write origin ---
  113. def current_origin() -> str:
  114. """``foreground`` or ``background_review`` — reuses the skill-provenance ContextVar
  115. the background review fork sets; foreground turns leave it at the default."""
  116. with suppress(Exception):
  117. from tools.skill_provenance import get_current_write_origin
  118. return get_current_write_origin()
  119. return "foreground"
  120. # --- Gate decision ---
  121. @dataclass(slots=True, kw_only=True)
  122. class GateDecision:
  123. """Result of evaluating the write gate; exactly one flag is True. ``allow``: do the real write;
  124. ``blocked``: user denied the inline prompt (``message`` says why); ``stage``: caller must
  125. ``stage_write`` the payload (``message`` is the user-facing "staged for approval" note)."""
  126. allow: bool = False
  127. blocked: bool = False
  128. stage: bool = False
  129. message: str = ""
  130. def _slash_review_surface() -> bool:
  131. """Whether the ACTIVE turn has a human who can type ``/<subsystem> pending``: the interactive
  132. CLI, TUI/desktop (exec route), and chat-gateway sessions all answer it now. Headless worker
  133. contexts — cron (``HERMES_CRON_SESSION``), kanban (``HERMES_KANBAN_TASK``) and the unattended
  134. programmatic platforms (api_server, webhook delivery) — have nobody at a prompt, so the staged
  135. hint must not name a command nobody can deliver (#98330); it names the pending dir instead."""
  136. def _env(name: str) -> str:
  137. try:
  138. from gateway.session_context import get_session_env
  139. return get_session_env(name, "") or ""
  140. except Exception: # standalone/tests: process env is the fallback
  141. return os.environ.get(name, "") or ""
  142. if _env("HERMES_KANBAN_TASK").strip():
  143. return False
  144. try:
  145. from utils import is_truthy_value
  146. if is_truthy_value(_env("HERMES_CRON_SESSION")):
  147. return False
  148. except Exception:
  149. pass
  150. platform = (_env("HERMES_SESSION_PLATFORM") or os.environ.get("HERMES_PLATFORM", "")).strip().lower()
  151. return platform not in {"webhook", "msgraph_webhook", "api_server"}
  152. def _staged(subsystem: str) -> GateDecision:
  153. command = f"/{subsystem} pending"
  154. if _slash_review_surface():
  155. where = f"review with {command}"
  156. else:
  157. where = (f"pending records live in {_pending_path(subsystem, '').parent} "
  158. f"(review from an interactive CLI session with {command})")
  159. return GateDecision(stage=True, message=(f"Staged for approval ({subsystem}.write_approval is on). "
  160. f"Not yet saved — {where}."))
  161. def evaluate_gate(subsystem: str, *, inline_summary: str = "", inline_detail: str = "") -> GateDecision:
  162. """Decide what to do with a pending write: gate off → allow; gate on + skills (any origin) or
  163. background → stage; gate on + memory + foreground → inline prompt when an interactive channel
  164. exists, else stage. The gate only ever delays a write, never silently refuses it; ``blocked``
  165. is produced only when the user actively denies the inline prompt."""
  166. if not write_approval_enabled(subsystem):
  167. return GateDecision(allow=True)
  168. # Skills are too big to review inline; a background write runs in a daemon thread with no user.
  169. if subsystem == SKILLS or current_origin() == "background_review":
  170. return _staged(subsystem)
  171. granted = _prompt_inline_memory_approval(inline_summary, inline_detail)
  172. if granted is None:
  173. return _staged(MEMORY)
  174. if granted:
  175. return GateDecision(allow=True)
  176. return GateDecision(blocked=True, message="Memory write denied by user. The change was not saved.")
  177. def _prompt_inline_memory_approval(summary: str, detail: str) -> Optional[bool]:
  178. """Prompt inline for a memory write: True approved, False denied, None → stage. Uses the per-thread
  179. CLI approval callback (``tools.terminal_tool.set_approval_callback``) directly, not
  180. ``prompt_dangerous_approval``: that wrapper falls back to ``input()`` (deadlock-prone under
  181. prompt_toolkit; silent deny in gateway sessions) and turns callback errors into a deny, whereas
  182. here a missing channel or failed prompt must stage instead.
  183. ``hermes chat -q`` (and so every kanban worker), cron and unattended platforms can register a callback too,
  184. but nobody answers it: stage at once instead of waiting the approval timeout. See #15216.
  185. """
  186. from tools.approval_context import _no_user_can_answer
  187. if _no_user_can_answer():
  188. return None
  189. try:
  190. from tools.terminal_tool import _get_approval_callback
  191. except Exception:
  192. return None
  193. callback = _get_approval_callback()
  194. if callback is None:
  195. return None
  196. header = summary.strip() or "Save to memory?"
  197. try:
  198. from tools.approval_prompt import callback_accepts
  199. extra = {"title": "Save to memory?"} if callback_accepts(callback, "title") else {}
  200. choice = callback(detail.strip() or header, f"Save to memory: {header}", allow_permanent=False, **extra)
  201. except Exception as e:
  202. logger.error("Inline memory approval prompt failed: %s", e)
  203. return None
  204. # unknown outcome → stage rather than drop
  205. return {"once": True, "session": True, "deny": False}.get(choice)
  206. # --- Skill-specific helpers (gist + diff for the review affordances) ---
  207. _GIST_TEMPLATES = {"write_file": "write {file_path} in '{name}'", "remove_file": "remove {file_path} from '{name}'",
  208. "delete": "delete skill '{name}'"}
  209. def skill_gist(action: str, name: str, *, content: str = "", file_path: str = "",
  210. old_string: str = "", new_string: str = "") -> str:
  211. """One-line heuristic gist (no model call) for a pending skill write: create/edit use
  212. the frontmatter ``description:``; patch/write_file describe the size of the change."""
  213. if action in {"create", "edit"} and content:
  214. desc = _frontmatter_description(content)
  215. size = f"{len(content) // 1024 + 1} KB" if len(content) >= 1024 else f"{len(content)} chars"
  216. return f"{'create' if action == 'create' else 'rewrite'} '{name}'{f' — {desc}' if desc else ''} ({size})"
  217. if action == "patch":
  218. removed = old_string.count("\n") + 1 if old_string else 0
  219. added = new_string.count("\n") + 1 if new_string else 0
  220. return f"patch '{name}' {file_path or 'SKILL.md'} (+{added}/-{removed} lines)"
  221. return _GIST_TEMPLATES.get(action, "{action} '{name}'").format(action=action, name=name, file_path=file_path)
  222. def _frontmatter_description(content: str) -> str:
  223. """Extract the ``description:`` value from SKILL.md YAML frontmatter (≤140 chars)."""
  224. m = re.search(r"^description:\s*(.+)$", content, re.MULTILINE)
  225. return m.group(1).strip().strip("'\"")[:140] if m else ""
  226. def _find_skill_path(name: str) -> Optional[Path]:
  227. """Directory of an installed skill, or None if unknown / lookup unavailable."""
  228. try:
  229. from tools.skill_manager_tool import _find_skill
  230. except Exception:
  231. return None
  232. # Only the import is guarded (as on main); a lookup failure propagates.
  233. found = _find_skill(name)
  234. return found["path"] if found else None
  235. def _staged_base(name: str, target_label: str, staged: Optional[dict[str, dict[str, str]]]) -> str:
  236. """What an op diffs against: the content earlier ops of the same batch left in this file,
  237. else the on-disk copy (empty for a file that does not exist yet)."""
  238. files = (staged or {}).get(name)
  239. if files and target_label in files:
  240. return files[target_label]
  241. skill_dir = _find_skill_path(name)
  242. if not skill_dir:
  243. return ""
  244. with suppress(Exception):
  245. p = skill_dir / target_label
  246. if p.exists():
  247. return p.read_text(encoding="utf-8-sig")
  248. return ""
  249. def skill_pending_diff(
  250. record: dict[str, Any], staged: Optional[dict[str, dict[str, str]]] = None
  251. ) -> str:
  252. """Full content (create) or unified diff vs. the base file (edit/patch/write_file),
  253. rendered by /skills diff <id> on surfaces that can show it. ``staged`` carries the file
  254. contents the earlier ops of a batch left behind, so op *i* diffs against ops 1..*i-1* and
  255. disk is read only for files no earlier op touched. A staged batch renders each op's diff
  256. under its gist header (single-op path below is unchanged)."""
  257. payload = record.get("payload", {})
  258. action = payload.get("action", "")
  259. name = payload.get("name", "")
  260. if action == "batch":
  261. return _batch_pending_diff(payload)
  262. if action == "create":
  263. return payload.get("content") or ""
  264. if action not in {"edit", "patch", "write_file"}:
  265. return {"remove_file": f"remove file: {payload.get('file_path')} from skill '{name}'",
  266. "delete": f"delete skill '{name}'"}.get(action, f"({action} on '{name}')")
  267. # patch/write_file target a file inside the skill; edit always targets SKILL.md.
  268. target_label = "SKILL.md" if action == "edit" else (payload.get("file_path") or "SKILL.md")
  269. current = _staged_base(name, target_label, staged)
  270. if action == "patch":
  271. old_s, new_s = payload.get("old_string") or "", payload.get("new_string") or ""
  272. if not current:
  273. new = f"(patch {old_s!r} → {new_s!r})"
  274. else:
  275. # Fold through the same matcher approve will run, so the preview can't
  276. # fabricate a result the approve path would reject (repeated anchor without
  277. # replace_all, whitespace-only anchor, escape drift, old_string == new_string).
  278. folded, patch_err = _fold_patch(current, old_s, new_s, payload.get("replace_all"))
  279. if patch_err:
  280. return f"(patch would fail: {patch_err})"
  281. new = folded
  282. else:
  283. new = payload.get("content" if action == "edit" else "file_content") or ""
  284. diff = difflib.unified_diff(current.splitlines(keepends=True), new.splitlines(keepends=True),
  285. fromfile=f"a/{target_label}", tofile=f"b/{target_label}")
  286. return "".join(diff) or "(no textual change)"
  287. def _fold_patch(base: str, old_string: str, new_string: str, replace_all: Any = False
  288. ) -> tuple[str, Optional[str]]:
  289. """Fold one patch op through ``fuzzy_find_and_replace`` — the SAME matcher the approve
  290. path runs (``_patch_skill`` / ``apply_skill_pending``) — so a previewed diff is exactly
  291. what an approval would commit, and a patch approval would reject (repeated anchor with
  292. ``replace_all`` unset, whitespace-only anchor, escape drift, ``old_string == new_string``)
  293. renders as an explicit failed-patch note instead of a fabricated folded result.
  294. Returns ``(folded_content, None)`` or ``(base, error)``; base is returned unchanged on
  295. error so the caller can still render the unchanged content, matching the engine's own
  296. ``(content, 0, None, error)`` contract. Local import: keeps write_approval importable
  297. without the tool chain (fuzzy_match is core-adjacent but guarded for safety anyway).
  298. """
  299. from tools.fuzzy_match import fuzzy_find_and_replace
  300. folded, match_count, _strategy, error = fuzzy_find_and_replace(
  301. base, old_string, str(new_string), bool(replace_all))
  302. if error or match_count == 0:
  303. return base, error or "Could not find a match for old_string in the file"
  304. return folded, None
  305. def _fold_staged(staged: dict[str, dict[str, str]], action: str, name: str,
  306. op: dict[str, Any]) -> None:
  307. """Record what one op leaves in the staged view the next op diffs against."""
  308. if not name:
  309. return
  310. if action == "delete":
  311. staged.pop(name, None)
  312. return
  313. label = "SKILL.md" if action == "edit" else (op.get("file_path") or "SKILL.md")
  314. files = staged.setdefault(name, {})
  315. if action in {"create", "edit"}:
  316. files["SKILL.md"] = op.get("content") or ""
  317. elif action == "write_file":
  318. files[label] = op.get("file_content") or ""
  319. elif action == "patch":
  320. base = _staged_base(name, label, staged)
  321. folded, patch_err = _fold_patch(base, op.get("old_string") or "",
  322. op.get("new_string") or "", op.get("replace_all"))
  323. if patch_err is None:
  324. files[label] = folded
  325. # On error the staged label keeps its prior content: approve would abort the batch
  326. # at this op, so nothing later in the preview should diff against a folded result
  327. # that will never be committed.
  328. elif action == "remove_file":
  329. files.pop(label, None)
  330. def _batch_pending_diff(payload: dict[str, Any]) -> str:
  331. """Per-op diffs for a staged ``batch`` payload (skill_manage operations[]). Ops apply in
  332. order, so each op reuses the single-op path above with the earlier ops' staged content as
  333. its base (disk only for files no earlier op touched) — a patch to a skill an earlier op
  334. created shows a real diff, which is the case this renderer exists for."""
  335. ops = [op for op in (payload.get("operations") or []) if isinstance(op, dict)]
  336. total = len(ops)
  337. staged: dict[str, dict[str, str]] = {}
  338. parts = []
  339. for i, op in enumerate(ops):
  340. op_action, op_name = op.get("action", ""), op.get("name") or ""
  341. gist = skill_gist(op_action, op_name, content=op.get("content") or "",
  342. file_path=op.get("file_path") or "",
  343. old_string=op.get("old_string") or "",
  344. new_string=op.get("new_string") or "")
  345. diff = skill_pending_diff({"payload": {**op, "name": op_name}}, staged)
  346. parts.append(f"## op {i + 1}/{total}: {gist}\n\n{diff}")
  347. _fold_staged(staged, op_action, op_name, op)
  348. return "\n\n".join(parts) or "(empty batch)"