|+jKPdZddlmZddlZddlZddlZddlZddlZddlm Z ddl m Z m Z m Z mZddlmZejeZdZdZeefZd Zd9dZd:dZd;dZddZd?dZd@d ZdAd!Z dBd"Z!Gd#d$Z"d%d%d&dCd)Z#dBd*Z$dDd-Z%d%d%d%d%d.dEd5Z&dFd6Z'dGd8Z(dS)Hu}Write-approval gate + pending store for memory and skill writes. Background ---------- The agent writes to two persistent stores that survive across sessions: * **memory** — MEMORY.md / USER.md, small (~200 char) declarative entries * **skills** — SKILL.md + supporting files, potentially huge (10-100 KB) Both stores are written from two origins: * **foreground** — a normal agent turn (user is present / chatting) * **background_review** — the self-improvement review fork that runs after a turn and autonomously decides what to save (the source of the "wrong assumptions" users complained about) This module lets the user gate those writes per-subsystem with a boolean ``write_approval``: * ``false`` (default) — write freely (the pre-gate behaviour) * ``true`` — require approval: do not commit the write; either prompt inline (memory, interactive CLI only) or **stage** it to a pending store and surface it for the user to approve or reject out-of-band The size asymmetry between memory and skills is real and unavoidable: a memory entry can be reviewed inline in a chat bubble; a 100 KB SKILL.md cannot. So the gate stages BOTH to disk, but review affordances differ by subsystem (see ``hermes_cli`` slash handlers): memory shows full content, skills show metadata + a one-line gist + a ``diff`` escape hatch (CLI/dashboard/file). Staging is mandatory for background-origin writes (a daemon thread cannot block on an interactive prompt) and for gateway sessions (no inline prompt channel — review happens via ``/memory pending``). Foreground CLI memory writes prompt inline via the dangerous-command approval callback; skill writes always stage (too big to eyeball mid-loop). Pending records live under ``/pending/{memory,skills}/.json`` so they survive process restarts and can be reviewed from CLI, gateway, or the web dashboard. ) annotationsN)Path)AnyDictListOptionalget_hermes_homememoryskillswrite_approval subsystemstrreturnboolc|tvrdS ddlm}m}|}|||td}n#t $rYdSwxYwt |S)u'Return whether the approval gate is enabled for ``subsystem``. Reads ``.write_approval`` from config.yaml. Defaults to ``False`` (gate off — writes flow freely) for any unset / invalid value so existing installs keep their current behaviour until the user opts in. Fr) load_configcfg_get)default) _SUBSYSTEMShermes_cli.configrr CONFIG_KEY Exception_normalize_enabled)rrrcfgraws 3/usr/local/lib/hermes-agent/tools/write_approval.pywrite_approval_enabledrJs ##u::::::::kmmgc9j%@@@ uu c " ""s&4 AAvaluerct|tr|St|tr(|dvSdS)aCoerce a config value to a bool. Default (unknown) is False (gate off). Accepts real bools and the usual truthy/falsey strings. YAML 1.1 parses bare ``on``/``off``/``yes``/``no`` as bools already, so the string branch is mostly for hand-edited configs. >1onyestrueapproveenabledF) isinstancerrstriplower)rs rrr\sS% %Y{{}}""$$(XXX 5rc*tdz |z S)Npendingr )rs r _pending_dirr-ns   y (9 44r*payloadDict[str, Any]summaryorigincFtjjdd}|||dd|pd|pdt j|d} t |}|dd||d z }|d }| tj |d d dtj ||n5#t$r(} td|| dYd} ~ nd} ~ wwxYw|S)uOPersist a pending write and return a short record describing it. Args: subsystem: ``memory`` or ``skills``. payload: the exact kwargs needed to replay the write when approved (e.g. ``{"action": "add", "target": "user", "content": "..."}`` for memory, or the full ``skill_manage`` kwargs for skills). summary: a one-line human-readable description shown in pending lists. For skills this is the LLM/heuristic gist; for memory it can be the entry text itself. origin: ``foreground`` or ``background_review`` — recorded for audit. Returns a dict with ``id`` and metadata. Best-effort: on disk failure it logs and still returns a record (the write is simply lost, which is the safe failure for an approval gate — nothing is silently committed). Naction foreground)idrr4r0r1 created_atr.T)parentsexist_ok.jsonz .json.tmpF) ensure_asciiindentutf-8encodingz$Failed to stage pending %s write: %s)exc_info)uuiduuid4hexgetr(timer-mkdir with_suffix write_textjsondumpsosreplacerloggererror) rr.r0r1pidrecorddpathtmpes r stage_writerWrsA$ *,, 2A2 C++h++Mr((**(LikkFZ  # # t,,,c=== {++ tz&uQGGGRYZZZ 3 ZZZ ;YTX YYYYYYYYZ Ms'BC,, D6DDList[Dict[str, Any]]ct|}|sgSg}|dD]i} |t j|d?#t$rt d|YfwxYw| d|S)z;Return all pending records for ``subsystem``, oldest first.*.jsonr?r@z&Skipping unreadable pending record: %sc.|ddS)Nr8r)rF)rs rzlist_pending..squu\155r*)key) r-existsglobappendrKloads read_textrrOwarningsort)rrSrecordsps r list_pendingrhsYA 88:: $&G VVH  HH H NN4:akk7k&C&CDD E E E E H H H NNCQ G G G G G H LL55L666 Ns;A<<%B$#B$ pending_idOptional[Dict[str, Any]]ct||dz }|sdS tj|dS#t $rYdSwxYw)z.Return a single pending record by id, or None.r;Nr?r@)r-r_rKrbrcr)rrirTs r get_pendingrlsw  " " %9%9%9 9D ;;==tz$..'.::;;; tts'A A#"A#ct||dz } |r|dSn4#t$r'}td|||Yd}~nd}~wwxYwdS)z4Delete a pending record. Returns True if it existed.r;Tz#Failed to discard pending %s/%s: %sNF)r-r_unlinkrrOrP)rrirTrVs rdiscard_pendingros  " " %9%9%9 9DV ;;==  KKMMM4  VVV :IzSTUUUUUUUUV 5s(A A3 A..A3intct|}|sdS td|dDS#t$rYdSwxYw)z9Cheap count of pending records (for notification badges).rc3K|]}dVdS)N).0_s r z pending_count..s"//1//////r*rZ)r-r_sumr`r)rrSs r pending_countrystYA 88::q//affX..////// qqs+A A! A!cF ddlm}|S#t$rYdSwxYw)a=Return the active write origin: ``foreground`` or ``background_review``. Reuses the skill-provenance ContextVar, which the background review fork already sets (see ``agent.background_review`` / ``AIAgent._spawn_background_review``). Foreground agent turns leave it at the default ``foreground``. rget_current_write_originr6)tools.skill_provenancer|rr{s rcurrent_originr~sJCCCCCC''))) ||s   c&tdkS)Nbackground_review)r~rtr*r is_backgroundrs   2 22r*c(eZdZdZdZddddddZdS) GateDecisionuResult of evaluating the write gate for a single write attempt. Exactly one of the boolean flags is True: * ``allow`` — proceed with the real write (gate off, or an inline approval was granted). * ``blocked`` — refuse the write (the user denied an inline approval prompt). ``message`` explains why; surface it to the agent. * ``stage`` — do not write; the caller should stage the payload via ``stage_write`` (gate on, and no inline prompt is available — gateway, background review, script, or any skill write). ``message`` is the user-facing "staged for approval" note. allowblockedstagemessageFr5c>||_||_||_||_dS)Nr)selfrrrrs r__init__zGateDecision.__init__s"    r*N)__name__ __module__ __qualname____doc__ __slots__rrtr*rrrsG  9I %uE2r*rr5)inline_summary inline_detailrrctt|stdSt}|tks|r'|tkrdnd}tdd|d|dSt r9t ||}|durtdS|d urtdd Stdd S) uDecide what to do with a pending write for ``subsystem``. Args: subsystem: ``memory`` or ``skills``. inline_summary: short description used as the inline approval prompt header (memory foreground path only). inline_detail: full content shown in the inline prompt (memory entries are small; skills never take the inline path). Decision matrix: gate off (default) → allow (writes flow freely) gate on, memory + interactive CLI → inline approve/deny prompt gate on, memory + gateway/script/bg → stage gate on, skills (any origin) → stage (too big to review inline) Note: there is no config-driven "blocked" outcome — the gate only ever delays a write for approval, never silently refuses it. ``blocked`` is still produced when the user *actively denies* an inline prompt. T)rz/skills pendingz/memory pendingzStaged for approval (u6.write_approval is on). Not yet saved — review with .)rrFz6Memory write denied by user. The change was not saved.)rruaStaged for approval (memory.write_approval is on). Not yet saved — review with /memory pending.)rrrSKILLS_interactive_approval_available_prompt_inline_memory_approval)rrr backgroundwheregranteds r evaluate_gaters* ") , ,($''''JFj%.&%8%8!!>O: ::16:::    '((0OO d??d+++ + e  P   =   r*cJ ddlm}|duS#t$rYdSwxYw)uTrue when a foreground memory write can be approved inline. Inline prompting requires a per-thread approval callback registered by the interactive CLI (``tools.terminal_tool.set_approval_callback``). Every other surface stages instead: * **Gateway/API sessions** — the dangerous-command ``/approve`` round-trip lives in the pending-approval queue (``submit_pending`` + ``_await_gateway_decision``), which ``prompt_dangerous_approval`` never reaches; trying to prompt from a gateway session would hit the ``input()`` fallback and silently deny. Staging gives the user a real review affordance (``/memory pending``) instead. * Scripts, cron, and background threads — no user present. r_get_approval_callbackNF)tools.terminal_toolrrrs rrr;sO>>>>>>%%''t33 uus  ""detailOptional[bool]c` ddlm}n#t$rYdSwxYw|}|dS|pd}|}d|}|r|n|} |||d}n3#t$r&} td| Yd} ~ dSd} ~ wwxYw|d vrd S|d krdSdS) uoPrompt the user inline to approve a memory write. Returns True (approved), False (denied), or None (no interactive prompt available / prompt failed → caller should stage instead). Reuses the per-thread CLI approval callback registered for dangerous commands (``tools.terminal_tool.set_approval_callback``). The callback is invoked directly — NOT via ``prompt_dangerous_approval`` — because that wrapper falls back to ``input()`` (deadlock-prone under prompt_toolkit, see #15216) and converts callback errors into a silent deny; here a failed prompt must stage the write instead. rrNzSave to memory?zSave to memory: F)allow_permanentz(Inline memory approval prompt failed: %s>oncesessionTdeny)rrrr(rOrP) r0rrcallbackheaderbody descriptioncommandchoicerVs rrrQs>>>>>>> tt&%''Ht ]]__ 1 1F <<>>D-V--K&ddG ';FFF  ?CCCttttt$$$t u 4s$ A-- B7BB)content file_path old_string new_stringr4namerrrrc |dvrs|rqt|}t|dkrt|dzdzdnt|d}|dkrdnd}|r|d|d |d |d S|d|d |d S|d krK|pd} |r|ddznd} |r|ddznd} d|d| d| d| d S|dkr d|d|dS|dkr d|d|dS|dkrd|dS|d|dS)ugBuild a one-line human gist for a pending skill write. Heuristic, no model call — the gist surfaces enough to decide approve/reject in a chat bubble, while the full diff stays behind /skills diff (CLI/ dashboard/file). For create/edit it pulls the frontmatter ``description:``; for patch/write_file it describes the size of the change. >editcreateirsz KBz charsrrewritez 'u' — z ()z' (patchSKILL.md rzpatch 'z' z (+z/-z lines) write_filezwrite z in '' remove_filezremove z from 'deletedelete skill ')_frontmatter_descriptionlencount) r4rrrrrdescsizeverbtargetremovedaddeds r skill_gistrs####'0036w<<43G3G#g,,$&*////PST[P\P\MdMdMd!X--xx9  :99d99$99$999 9**$**4**** (j0:A*""4((1,,.8?   &&**aEEEEEEEEWEEEE / ////// 22242222 '''''     r*cddl}|d||j}|sdS|dd}|ddS)zBExtract the ``description:`` value from SKILL.md YAML frontmatter.rNz^description:\s*(.+)$r5rsz'")research MULTILINEgroupr()rrmrs rrrsg III *GR\BBA r 771::     # #E * *D :r*rRchddl}|di}|dd}|dd}|dkr|dpdS dd lm}n#t$rd}YnwxYwd}d }|||}|rz|d } |d kr| d z } n(|d vr|dpd } | | z } | }n| d z } | r| d}n#t$rd}YnwxYw|d kr|dpd} n|dkrP|dpd} |dpd}|r|| |nd| d|d} nU|dkr|dpd} n7|dkrd|dd|dS|dkrd|dSd|d |d!S|| d"#| d"#d$|d%|&}d |}|pd'S)(aFBuild a full unified diff (or full content) for a staged skill write. Used by /skills diff on a surface that can render it (CLI pager, web dashboard, or by opening the pending JSON file). For create this is the new file content; for edit/patch it is a unified diff against the current on-disk skill. rNr.r4r5rrr) _find_skillrrTr>rrrr?r@rrrz(patch u → rr file_contentrz remove file: z from skill 'rrr(z on 'z')T)keependsza/zb/)fromfiletofilez(no textual change)) difflibrFtools.skill_manager_toolrrr_rcrN unified_diff splitlinesjoin)rRrr.r4rrcurrent target_labelfoundbasergrelnewold_snew_sdifftexts rskill_pending_diffrsNNNjjB''G [[2 & &F ;;vr " "D  I&&,"-8888888  GL D!!  =D:%222kk+..<*3J" :% 88::<kk7k;;G    kk)$$* 7   L))/R L))/R/6^gooeU+++<^e<^<^TY<^<^<^ <  kk.))/R = Mw{{;77MMdMMMM 8  '''''(6((((((   D)) %%$l$$"L""   D 774==D  (((s$%A,, A;:A;*C99 DD)rrrr)rrrr)rrrr) rrr.r/r0rr1rrr/)rrrrX)rrrirrrj)rrrirrr)rrrrp)rr)rr)rrrrrrrr)r0rrrrr)r4rrrrrrrrrrrrr)rrrr)rRr/rr))r __future__rrKloggingrMrGrCpathlibrtypingrrrrhermes_constantsr getLoggerrrOMEMORYrrrrrr-rWrhrlroryr~rrrrrrrrrtr*rrsl''R#"""""  ,,,,,,,,,,,,,,,,,,  8 $ $  v  ####$    $5555%%%%P            3333.<>');;;;;;|,,,,,f:< "b!#      >@)@)@)@)@)@)r*