PL jndZddlmZddlZddlZddlZddlZddlmZm Z m Z m Z ej e ZdZdZdZd#d Zdddddd$dZd%dZ d&d'd!Zgd"ZdS)(u7Background memory/skill review — fork the agent to evaluate the turn. After every turn, ``AIAgent.run_conversation`` may call :func:`spawn_background_review` to fire off a daemon thread that replays the conversation snapshot in a forked :class:`AIAgent` and asks itself "should any skill/memory be saved or updated?". Writes go straight to the memory + skill stores. Main conversation and prompt cache are never touched. The fork inherits the parent's live runtime (provider, model, base_url, credentials, cached system prompt) so it hits the same prefix cache and uses the same auth. It runs with a tool whitelist limited to memory and skill management tools; everything else is denied at runtime. See the ``hermes-agent-dev`` skill (``references/self-improvement-loop.md``) for invariants and PR review criteria. ) annotationsN)AnyDictListOptionaluReview the conversation above and consider saving to memory if appropriate. Focus on: 1. Has the user revealed things about themselves — their persona, desires, preferences, or personal details worth remembering? 2. Has the user expressed expectations about how you should behave, their work style, or ways they want you to operate? If something stands out, save it using the memory tool. If nothing is worth saving, just say 'Nothing to save.' and stop.uReview the conversation above and update the skill library. Be ACTIVE — most sessions produce at least one skill update, even if small. A pass that does nothing is a missed learning opportunity, not a neutral outcome. Target shape of the library: CLASS-LEVEL skills, each with a rich SKILL.md and a `references/` directory for session-specific detail. Not a long flat list of narrow one-session-one-skill entries. This shapes HOW you update, not WHETHER you update. Signals to look for (any one of these warrants action): • User corrected your style, tone, format, legibility, or verbosity. Frustration signals like 'stop doing X', 'this is too verbose', 'don't format like this', 'why are you explaining', 'just give me the answer', 'you always do Y and I hate it', or an explicit 'remember this' are FIRST-CLASS skill signals, not just memory signals. Update the relevant skill(s) to embed the preference so the next session starts already knowing. • User corrected your workflow, approach, or sequence of steps. Encode the correction as a pitfall or explicit step in the skill that governs that class of task. • Non-trivial technique, fix, workaround, debugging path, or tool-usage pattern emerged that a future session would benefit from. Capture it. • A skill that got loaded or consulted this session turned out to be wrong, missing a step, or outdated. Patch it NOW. Preference order — prefer the earliest action that fits, but do pick one when a signal above fired: 1. UPDATE A CURRENTLY-LOADED SKILL. Look back through the conversation for skills the user loaded via /skill-name or you read via skill_view. If any of them covers the territory of the new learning, PATCH that one first. It is the skill that was in play, so it's the right one to extend. 2. UPDATE AN EXISTING UMBRELLA (via skills_list + skill_view). If no loaded skill fits but an existing class-level skill does, patch it. Add a subsection, a pitfall, or broaden a trigger. 3. ADD A SUPPORT FILE under an existing umbrella. Skills can be packaged with three kinds of support files — use the right directory per kind: • `references/.md` — session-specific detail (error transcripts, reproduction recipes, provider quirks) AND condensed knowledge banks: quoted research, API docs, external authoritative excerpts, or domain notes you found while working on the problem. Write it concise and for the value of the task, not as a full mirror of upstream docs. • `templates/.` — starter files meant to be copied and modified (boilerplate configs, scaffolding, a known-good example the agent can `reproduce with modifications`). • `scripts/.` — statically re-runnable actions the skill can invoke directly (verification scripts, fixture generators, deterministic probes, anything the agent should run rather than hand-type each time). Add support files via skill_manage action=write_file with file_path starting 'references/', 'templates/', or 'scripts/'. The umbrella's SKILL.md should gain a one-line pointer to any new support file so future agents know it exists. 4. CREATE A NEW CLASS-LEVEL UMBRELLA SKILL when no existing skill covers the class. The name MUST be at the class level. The name MUST NOT be a specific PR number, error string, feature codename, library-alone name, or 'fix-X / debug-Y / audit-Z-today' session artifact. If the proposed name only makes sense for today's task, it's wrong — fall back to (1), (2), or (3). User-preference embedding (important): when the user expressed a style/format/workflow preference, the update belongs in the SKILL.md body, not just in memory. Memory captures 'who the user is and what the current situation and state of your operations are'; skills capture 'how to do this class of task for this user'. When they complain about how you handled a task, the skill that governs that task needs to carry the lesson. If you notice two existing skills that overlap, note it in your reply — the background curator handles consolidation at scale. Do NOT capture (these become persistent self-imposed constraints that bite you later when the environment changes): • Environment-dependent failures: missing binaries, fresh-install errors, post-migration path mismatches, 'command not found', unconfigured credentials, uninstalled packages. The user can fix these — they are not durable rules. • Negative claims about tools or features ('browser tools do not work', 'X tool is broken', 'cannot use Y from execute_code'). These harden into refusals the agent cites against itself for months after the actual problem was fixed. • Session-specific transient errors that resolved before the conversation ended. If retrying worked, the lesson is the retry pattern, not the original failure. • One-off task narratives. A user asking 'summarize today's market' or 'analyze this PR' is not a class of work that warrants a skill. If a tool failed because of setup state, capture the FIX (install command, config step, env var to set) under an existing setup or troubleshooting skill — never 'this tool does not work' as a standalone constraint. 'Nothing to save.' is a real option but should NOT be the default. If the session ran smoothly with no corrections and produced no new technique, just say 'Nothing to save.' and stop. Otherwise, act.uReview the conversation above and update two things: **Memory**: who the user is. Did the user reveal persona, desires, preferences, personal details, or expectations about how you should behave? Save facts about the user and durable preferences with the memory tool. **Skills**: how to do this class of task. Be ACTIVE — most sessions produce at least one skill update. A pass that does nothing is a missed learning opportunity, not a neutral outcome. Target shape of the skill library: CLASS-LEVEL skills with a rich SKILL.md and a `references/` directory for session-specific detail. Not a long flat list of narrow one-session-one-skill entries. Signals that warrant a skill update (any one is enough): • User corrected your style, tone, format, legibility, verbosity, or approach. Frustration is a FIRST-CLASS skill signal, not just a memory signal. 'stop doing X', 'don't format like this', 'I hate when you Y' — embed the lesson in the skill that governs that task so the next session starts fixed. • Non-trivial technique, fix, workaround, or debugging path emerged. • A skill that was loaded or consulted turned out wrong, missing, or outdated — patch it now. Preference order for skills — pick the earliest that fits: 1. UPDATE A CURRENTLY-LOADED SKILL. Check what skills were loaded via /skill-name or skill_view in the conversation. If one of them covers the learning, PATCH it first. It was in play; it's the right place. 2. UPDATE AN EXISTING UMBRELLA (skills_list + skill_view to find the right one). Patch it. 3. ADD A SUPPORT FILE under an existing umbrella via skill_manage action=write_file. Three kinds: `references/.md` for session-specific detail OR condensed knowledge banks (quoted research, API docs excerpts, domain notes) written concise and task-focused; `templates/.` for starter files meant to be copied and modified; `scripts/.` for statically re-runnable actions (verification, fixture generators, probes). Add a one-line pointer in SKILL.md so future agents find them. 4. CREATE A NEW CLASS-LEVEL UMBRELLA when nothing exists. Name at the class level — NOT a PR number, error string, codename, library-alone name, or 'fix-X / debug-Y' session artifact. If the name only fits today's task, fall back to (1), (2), or (3). User-preference embedding: when the user complains about how you handled a task, update the skill that governs that task — memory alone isn't enough. Memory says 'who the user is and what the current situation and state of your operations are'; skills say 'how to do this class of task for this user'. Both should carry user-preference lessons when relevant. If you notice overlapping existing skills, mention it — the background curator handles consolidation. Do NOT capture as skills (these become persistent self-imposed constraints that bite you later when the environment changes): • Environment-dependent failures: missing binaries, fresh-install errors, post-migration path mismatches, 'command not found', unconfigured credentials, uninstalled packages. The user can fix these — they are not durable rules. • Negative claims about tools or features ('browser tools do not work', 'X tool is broken', 'cannot use Y from execute_code'). These harden into refusals the agent cites against itself for months after the actual problem was fixed. • Session-specific transient errors that resolved before the conversation ended. If retrying worked, the lesson is the retry pattern, not the original failure. • One-off task narratives. A user asking 'summarize today's market' or 'analyze this PR' is not a class of work that warrants a skill. If a tool failed because of setup state, capture the FIX (install command, config step, env var to set) under an existing setup or troubleshooting skill — never 'this tool does not work' as a standalone constraint. Act on whichever of the two dimensions has real signal. If genuinely nothing stands out on either, say 'Nothing to save.' and stop — but don't reach for that conclusion as a default.review_messages List[Dict]prior_snapshotreturn List[str]c>t}t}|pgD]}t|tr|ddkr1|d}|r||^|d}t|t r||g}|pgD]V}t|tr|ddkr2|d}|r||vrN|s/|d} t| t r| |vr t j|dd} n#t jtf$rYwxYwt| tr| ds| dd} | d d} d | vr| | Id | vr| | vd | vs| rBd | vr,| dkrdn | dkrdn| } | | dd| vr,| dkrdn | dkrdn| } | | dd| vsd| vr*| dkrdn | dkrdn| } | | dX|S)a3Build the human-facing action summary for a background review pass. Walks the review agent's session messages and collects "successful tool action" descriptions to surface to the user (e.g. "Memory updated"). Tool messages already present in ``prior_snapshot`` are skipped so we don't re-surface stale results from the prior conversation that the review agent inherited via ``conversation_history`` (issue #14944). Matching is by ``tool_call_id`` when available, with a content-equality fallback for tool messages that lack one. roletool tool_call_idcontentz{}successmessagetargetcreatedupdatedaddedaddmemoryMemoryuserz User profilez updatedz Entry addedremovedreplaced) set isinstancedictgetrstrjsonloadsJSONDecodeError TypeErrorlowerappend)rr existing_tool_call_idsexisting_tool_contentspriortcidractionsmsg content_strdatarrlabels ;/home/kuhnn/.hermes/hermes-agent/agent/background_review.py#summarize_background_review_actionsr4sk!UU UU%2 4 4%&& %))F*;*;v*E*E yy((  4 " & &t , , , ,ii **G'3'' 4&**7333G$"//#t$$ 6(A(A ww~&&  D222  ''),,K+s++  ?U0U0U :cggi6677DD$i0    H $%% TXXi-@-@  ((9b))(B''   ' ' NN7 # # # # '--// ) ) NN7 # # # #   ' 'F 'u 7O7O &( 2 2HH&TZJZJZ`fE NNe--- . . . . g % % &( 2 2HH&TZJZJZ`fE NNe--- . . . . '--// ) )Z7==??-J-J &( 2 2HH&TZJZJZ`fE NNe--- . . . Ns(E..FF) write_originexecution_contexttask_idragentrr5 Optional[str]r6r7rDict[str, Any]c|pt|dd|pt|dd|jpd|jpd|jptjdddd }|r||d <|r||d <d |DS) z?Build provenance metadata for external memory-provider mirrors._memory_write_originassistant_tool_memory_write_context foregroundrHERMES_SESSION_SOURCEclir)r5r6 session_idparent_session_idplatform tool_namer7rc"i|] \}}|dv || S)>Nr).0kvs r3 z/build_memory_write_metadata..2s( E E ETQ*1D1DAq1D1D1D)getattrrB_parent_session_idrDosenvironr"items)r8r5r6r7rmetadatas r3build_memory_write_metadatarSs%`7MO_(`(`  Eu5|DD&,""5;NTbjnn5Le&T&T  H&%0#/ E EX^^-- E E EErLmessages_snapshotpromptr#Nonec ddlm}ddlm}d} ||n#t$rYnwxYwd}g} t t jdd5}tj |5tj |5| } | d pd} | d krd } ||j d d |j|j| | dpd| dpdt!|dd|jd  }d|_d|_|j|_|j|_|j|_d|_d|_d |_|j|_|j|_|j|_ddlm} ddlm} m } d| ddgd D}| |d |!|dz|| n#| wxYw |"n#t$rYnwxYw |#n#t$rYnwxYwtIt!|dg}d}dddn #1swxYwYdddn #1swxYwYdddn #1swxYwYtK||}|rnd&tN(|}|)d||j*}|r |d |n#t$rYnwxYwnH#t$r;}tV,d!||-d"|Yd}~nd}~wwxYw| t t jdd5}tj |5tj |5 |"n#t$rYnwxYw |#n#t$rYnwxYwdddn #1swxYwYdddn #1swxYwYdddn #1swxYwYn#t$rYnwxYw |ddS#t$rYdSwxYw#| t t jdd5}tj |5tj |5 |"n#t$rYnwxYw |#n#t$rYnwxYwdddn #1swxYwYdddn #1swxYwYdddn #1swxYwYn#t$rYnwxYw |dw#t$rYwwxYwxYw)#a"Worker function executed in the background-review daemon thread. Spawns a forked ``AIAgent`` inheriting the parent's runtime, runs the review prompt, and surfaces a compact action summary back to the user via ``agent._safe_print`` and ``agent.background_review_callback``. r)AIAgent)set_approval_callbackc>td||dS)Nz8Background review auto-denied dangerous command: %s (%s)deny)loggerwarning)command descriptionkwargss r3_bg_review_auto_denyz3_run_review_in_thread.._bg_review_auto_denyIs' F [   vrLNwzutf-8)encodingapi_modecodex_app_servercodex_responsesTbase_urlapi_key_credential_pool) modelmax_iterations quiet_moderDproviderrdrhricredential_poolrC skip_memorybackground_review)get_tool_definitions)set_thread_tool_whitelistclear_thread_tool_whitelistc*h|]}|ddS)functionnamerG)rHts r3 z(_run_review_in_thread..s1   * f%   rLrskills)enabled_toolsetsrmz`Background review denied non-whitelisted tool: {tool_name}. Only memory/skill tools are allowed.) deny_msg_fmtuu You can only call memory and skill management tools. Other tools will be denied at runtime — do not attempt them.) user_messageconversation_history_session_messagesu · u 💾 Self-improvement review: u💾 Self-improvement review: z)Background memory/skill review failed: %szbackground review). run_agentrXtools.terminal_toolrY ExceptionopenrOdevnull contextlibredirect_stdoutredirect_stderr_current_main_runtimer"rkrDrnrMrBr<r> _memory_store_memory_enabled_user_profile_enabled_memory_nudge_interval_skill_nudge_intervalsuppress_status_output_cached_system_prompt session_start model_toolsrrhermes_cli.pluginsrsrtrun_conversationshutdown_memory_providercloselistr4joinr!fromkeys _safe_printbackground_review_callbackr\r]_emit_auxiliary_failure)r8rTrUrX_set_approval_callbackra review_agentr_devnull_parent_runtime_parent_api_moderrrsrtreview_whitelistr.summary_bg_cbe_fns r3_run_review_in_threadr5s "!!!!!SSSSSS  34444      L"$O~ "*cG 4 4 4E   ' 1 1E E  ' 1 1E E $99;;O.22:>>F$  #555#4 #7k!)(,,Z88@D'++I66>$ '/A4 H H"'"2    L1DL -1DL .).)> *;.,+----++----  557777     ""$$$$    "7<9Lb#Q#QRROLKE E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E Z6      kk$--"8"899G   <7<<   5F FBBB!D >>>BAFFF %%&91========>  # "*cG<<< /44  /44  $==????$$**,,,,$                                                   " "4 ( ( ( ( (    DD '  # "*cG<<< /44  /44  $==????$$**,,,,$                                                   " "4 ( ( ( (    D s  **LJ #I28D6I/G I G I$G98I9 H IH I HI H, )I+H, ,#I I2I I2"I #I2& J 2I6 6J 9I6 :J = L J  LJ A#L5LL LLLLQ( M1MQ(MQ( P9<P-P&O?(N=<O?= O O? O O?O#"O?# O0 -O?/O0 0O?3 P?P PP P P-P P-P P-! P9-P11P94P15P99 QQ Q Q%$Q%(U2,UT9T" 2T 4S T S T S T S/ .T / S< 9T ;S< <T ? T" TT" TT"  T9"T& &T9)T& *T9- U9T= =UT= UU2 UU2UU2 U"!U2" U/,U2.U//U2F review_memorybool review_skillsc|r|rtdtn/|rtdtntdtdfd }|fS)a%Build the review thread target and prompt for a background review. Returns a ``(target, prompt)`` tuple. The caller (``AIAgent._spawn_background_review``) owns the actual ``threading.Thread`` construction so test-level patches of ``run_agent.threading.Thread`` keep working. _COMBINED_REVIEW_PROMPT_MEMORY_REVIEW_PROMPT_SKILL_REVIEW_PROMPTr rVc*tdS)N)r)r8rTrUsr3_targetz/spawn_background_review_thread.._target-se%6?????rL)r rV)rMrrr)r8rTrrrrUs`` @r3spawn_background_review_threadrsNN 9;RSS N 79NOO 68LMM@@@@@@@@ F?rL)rrrrr4rS)rr r r r r ) r8rr5r9r6r9r7r9rr9r r:)r8rrTr rUr#r rV)FF)r8rrTr rrrr)__doc__ __future__rrr$loggingrOtypingrrrr getLogger__name__r\rrrr4rSrr__all__rGrLr3rs:$#"""""  ,,,,,,,,,,,,  8 $ $H\BHE\<<<<D#''+!"& FFFFFF6____J  8   rL