߲j7"UdZddlmZddlZddlZddlZddlZddlZddlm Z m Z ddl m Z m Z ddlmZmZmZmZmZmZddlmZddlmZej2eZd ZGd d Ze d_d Zd`d ZdadZ dbdZ!dcdZ"dZ#dZ$dZ%dZ&dddZ'dedfdZ(dedgdZ) dh didZ*djdZ+dedkdZ,dldZ-dmdZ.dndZ/dodpdZ0dZ1d e1zd!zZ2d"Z3d#Z4d$e3zd%ze4zd&zZ5d'e1zd(ze3zd)ze4zd*zZ6dqd+Z7d,d-d.d/Z8d0e9d1<drd2Z:dsd3Z;dtd4Zdvd7Z?dwd8Z@dxd9ZA dy dzd:ZBddddd; d{d<ZCd=ZDd|d>ZEd}d?ZFd~d@ZGddAZHdBZIddCZJdeddDZKdbdEZLddFZM de ddGZNdHZOddIZP dedJdK ddLZQdMZRddNZSddOZT d ddPZUe GdQdRZVdbdSZW d ddTZXddUZY d ddVZZdWdXdYdYdZZ[ d dd[Z\gd\Z]dd]l^m_Z_ de dd^Z`y)u)Background memory/skill review — fork the agent to evaluate the turn. After every turn ``AIAgent.run_conversation`` may spawn a daemon thread that replays the conversation snapshot in a forked :class:`AIAgent` and asks "should any skill/memory be saved or updated?". Writes go straight to the memory + skill stores; the main conversation and prompt cache are never touched. The fork inherits the parent's live runtime (provider, model, credentials, cached system prompt) so it hits the same prefix cache, and runs under a dispatch-side tool whitelist.) annotationsN)contextmanagersuppress) dataclassfield)AnyDictIteratorListOptionalTuple)resolve_prompt_cache_scope_safe)thread_scoped_silenceg@c0eZdZdZddZddZd dZd dZy) _BackgroundReviewRunz9Per-review cancellation and request-completion handshake.ctj|_tj|_tj|_d|_dx|_|_y)NF) threadingEventcancel_requested request_doneLock_lock _review_agent_request_finished_cancel_dispatchedselfs Latch request completion once; the caller publishes the event.NF)TNT)rrrrs rmark_request_finishedz*_BackgroundReviewRun.mark_request_finished6sJ ZZ %%  :D 6D "D$6    s ==ANreturnNone)r#rr+bool)r+r)r+r-)__name__ __module__ __qualname____doc__rr$r'r)r rrrsCA&r rc#jKt||d}|dy|5ddddy#1swYyxYww)zF``with`` over a lock attribute that may be absent (direct test stubs).N)getattr)agentattrlocks r_optional_lockr8?s; 5$ %D |   s3' 303c>t} t|dd}|tjx}|_|5t|dd}|$|j j s dddy||_ddd|S#1swY|SxYw#ttf$rYywxYw)zCInstall a unique run token on the parent before ``Thread.start()``._background_review_lockN_background_review_run) rr4rrr:rr"r;AttributeError TypeError)r5runr7currents rprepare_background_review_runr@Js  C u7> <3<>>3C CD50  /e%=tDG"7+?+?+F+F+H / /,/E (  / J / J I &s:,B +A=#B ,A=3B =BB B BBc||jsyt|d5t|dd|urd|_ddd|jj y#1swY$xYw)zGPublish one run's request exit without clearing a successor (ABA-safe).Nr:r;)r)r8r4r;rr&)r5r>s rfinish_background_review_runrB[sc {#335 8 90 52D 9S @+/E (000s AA#cdfd } tj|ddjy#t$rtj ddYywxYw) zRequest abort off-thread so a wedged abort hook cannot stall the live turn (the bounded ``request_done`` wait in the canceller relies on this returning fast).cv ddlm}|ddy#t$rtj ddYywxYw) Nr)request_hard_interruptzsuperseded by a new live turnzbackground review superseded) tool_reasonz;Failed to cancel in-flight background review for a new turnTexc_info)agent.interrupt_compatrE Exceptionloggerdebug)rEr#s r _interruptz0_interrupt_background_review.._interrupthsB g E "=Ki  g LLVaeL f gs  88Tzbg-review-cancel)targetdaemonnamez5Failed to start background-review cancellation threadrGNr*)rThreadstartrJrKrL)r#rMs` r_interrupt_background_reviewrSesNg] 4>PQWWY ] LW[ \]s&0 AAc8t|d5t|dd}t|dd}dddn|j}| t||y|jj t stjdt yy#1swYixYw)uCancel the current review and await its request-phase acknowledgement. Foreground priority: past the bounded deadline, warn and let the live turn proceed — self-improvement work must never block a user-facing turn. Foreground priority is preserved: if the review does not acknowledge within the bounded deadline, a warning is logged and the live turn proceeds anyway. See #84423. r:r;N_background_review_agent)timeoutzeBackground review did not acknowledge cancellation within %.1fs; proceeding with foreground live turn) r8r4r'rSrwait)_BACKGROUND_REVIEW_CANCEL_TIMEOUT_SECONDSrKwarning)r5r> legacy_agentr#s r&cancel_background_review_for_live_turnr[xs 8 9He5t<u&@$G H$'; ``(enabled, task_cfg)``. Fail-open (``enabled=True``) so a broken config never silently disables reviews — but WARN so the cost is visible.rrhis_truthy_valueenabledTdefaultzVFailed to read background_review.enabled; leaving automatic review enabled (fail-open)rG) rjriutilsrrfrarJrKrY)rirres rload_background_review_settingsrsi :)/12txx 2DA4GG  )  Rx s69$A A c |j}|jdxsd}|j|j|jdxsd|jdxsd|dk(rdn|t |ddt t |dixsit |d dt |d dt t |d gxsgd d }t| fddD\}}}}|r-|dk7r(|r&||jxsdk(r||jxsdk(r|S ddlm } | ||||} | jdxs|| jdxs|ddD cic]} | | j| c} t | jdxsit | jdxsgddScc} w#t$r} t|||| |cYd} ~ Sd} ~ wwxYw)a[Resolve provider/model/credentials for the review fork. Default (auto / unset / same as parent): the parent's live runtime with ``routed=False`` (codex_app_server -> codex_responses downgrade applied). When ``auxiliary.background_review.{provider,model}`` names a different concrete model, resolve that runtime and set ``routed=True``.api_modeNapi_keybase_urlcodex_app_servercodex_responses_credential_poolrequest_overrides max_tokens acp_commandacp_argsF) providermodelrrrcredential_poolrrcommandargsroutedc3xK|]1}tj|djxsd3yw)N)strrastrip).0keyres r z*_resolve_review_runtime..s7>36DHHS" $$&.$.>s7:)rrrrautorr)resolve_runtime_provider) requested target_modelexplicit_api_keyexplicit_base_urlrr)rr)rrrrrrT)rrr) _current_main_runtimerarrr4rblistrlhermes_cli.runtime_providerrrJ_warn_review_routing_fallback)r5rkparent_runtimeparent_api_modeparent task_provider task_model task_base_url task_api_keyrrpreres @r_resolve_review_runtimers 002N$((4<ONNU[[!%%i08DnFXFXYcFdFlhl)8:f>:M:}l mv5*%...B/J5;;CTRT4U H %#*)]  z*;mbffWoFcYc +lmCsBFF3Km "&bff-@&A&GR!H-2.$   m %e]JJ s2AF4F/-AF4/F44 G=G GGc dd|d|dt|jdd|jd|jd }tj d|t |d d ry d |_t |d d }t|r!tt5||d d d y y #1swYy xYw)a"The configured review route could not be resolved, so the fork runs on the main model. That was a debug-level line nobody saw (#116055): the misrouted model never ran and nothing said so. User-visible notice once per agent (same rail as the reasoning_effort notice); log every time.u*⚠ auxiliary.background_review.provider='z ' (model 'z') could not be resolved: ru. — background reviews run on the main model /z9 instead. Run 'hermes doctor' to check auxiliary routing.%s_warned_bg_review_routingFNT _emit_warning) r splitlinesrrrKrYr4rcallablerrJ)r5rrerrormessageemits rrrs 5]O:j\ZZ**,Q/00^ >> !EKK=(a c  NN4!u159&*E# 5/4 0D~ i   M    s  B&&B/ct|dd}|| t|ndfD]!}t|dd}||t|cSy)uWhether a fork inheriting ``agent``'s runtime could act at all: an agent-as-provider client shim declaring ``SUPPORTS_HERMES_TOOL_CALLS = False`` (instance or class) is skipped — the fork would be a guaranteed no-op that still pays a full spawn. Silence means capable.clientNSUPPORTS_HERMES_TOOL_CALLST)r4typer-)r5r candidate supporteds r_parent_can_emit_tool_callsrsZUHd +Ff.@d6ldK# I'CTJ  Y%: ? "# r c|jd}t|trdjd|D}t|tr|j SdS)Ncontent c3bK|]'}t|ts|jdd)yw)textrNr`rbra)rbs rrz_msg_text..)s$I1Z45HQUU62&Is//r)rar`rjoinrr)mcs r _msg_textr&sH iA!T HHII I"1c*177922r c(t|xsg}t||kDrE|| d}t|dtr|dj ddk(sn|dz }t||kDrE|Sg}|dt| D]}t|ts|j dt |j dd}}|dk(r|r|jd |dd _|d k(se|j d rj|d Dcgc]8}t|ts|j d xsij dd:} }|jddj| d|s|jd|ddddj|z} d| dg|zScc}w)aCompact replay for the routed (different-model) path only: keep the recent ``tail`` messages verbatim (extended so the kept run never starts on a tool result) and collapse older turns into one synthetic user-role digest, preserving role alternation.Nrroletoolrp ruserzUSER: i, assistant tool_callsfunctionrP?zASSISTANT[tools: , ]z ASSISTANT: u[Earlier conversation digest — older turns summarised to bound the review's cold-write cost on the routed aux model. Recent turns follow verbatim below.] )rr) rlenr`rbrarreplaceappendr) messages_snapshottailmsgskeeplinesrrrtcnamesdigests r_digest_historyr-s !'R (D d)d TEF|47D)d1gkk&.AV.K    d)d   E +CI:  9!T" UU6]IaL$8$8s$Cd 6>d LL6$t*. / [ uu\"OPQ]wblmoqubv"&&,277Dww 051A0B!DE {4:,78 9 $&*ii&6 7  / 04 77xs 3F 'FuTWO distinct stores — pick the right one for each fact: • USER.md (memory tool, target='user'): who the user is — persona, preferences, communication and work style, personal details they revealed, and expectations about how you should behave. • MEMORY.md (memory tool, target='memory'): facts about the ENVIRONMENT you operate in — tool quirks, project conventions, config gotchas, paths and endpoints that matter. One fact goes to ONE store, never both — writing it to both bloats both files until they hit their size limits and crowds out the facts that matter; misrouting it puts it where the next session won't look. If the tool schema lists only one target, that store is the only one enabled — use it and skip the other. zXReview the conversation above and consider saving to memory if appropriate. Memory has zIf something stands out, save it once, in the right store, using the memory tool with the matching target. If nothing is worth saving, just say 'Nothing to save.' and stop.uHWhat a skill IS: the instructions for doing a class of task the most efficient and correct way, to THIS user's specifications — the procedure, the tools and commands that work, the order, the user's preferences for how the result should look, and the pitfalls that cost time. A future session should be able to follow it and produce what the user wants on the first try. Everything below is about writing that well: • Procedure first: the steps in the order they are done, with the concrete commands, tool calls, and decision points. Lessons and pitfalls attach to the step they affect. • A pitfall is a generalizable rule + one clause of WHY (the mechanism), imperative. 'Grep the test tree for the SYMBOL before widening a helper signature — hand-rolled mocks reimplement the old shape and fail on a shard you did not run.' Not a narrative of what happened this session. • No PR/issue numbers, dates, ticket IDs, or quoted user text as content — the rule must stand without the incident behind it. Keep a short quote ONLY when the quote itself is the clearest statement of the rule. • The same lesson learned twice is ONE rule. Before adding, search the skill (and its references/) for the rule already stated; strengthen or clarify it rather than appending a second copy. • Not a duplicate of what the environment already teaches: repo AGENTS.md files, tool schema descriptions, and other always-loaded context. A skill carries the WORKFLOW and the pitfalls; it does not restate the codebase map or a tool's parameter list. • Always-on rules (standing user preferences, gates that apply to every instance of the task) live in SKILL.md itself, whole. references/ is for depth that is only needed sometimes: a decision table, a recipe, a domain note — each file topical and reusable, never '-.md'. Prefer extending an existing references/ file over creating one; a skill with dozens of one-off references is the failure shape, not the goal. • Fix the skill in place when it is wrong: edit the sentence that misled, do not append 'UPDATE: actually...' underneath it. u (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. • Unresolved failures: if the session ended WITHOUT actually finding a working method — you tried several things, none worked, and told the user to check manually — do NOT write those attempts up as a 'reliable workflow' or 'recommended approach'. That presents an untested sequence of failures as validated guidance a future session will trust and repeat. Either say 'Nothing to save', or, only if you are independently confident of a real working alternative (not something you are merely guessing might work), capture ONLY that alternative — never the dead ends, and never dressed up as best practice. 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. 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 SKILL.md of always-on rules and a small `references/` set of topical depth. Not a flat list of narrow one-session skills, and not an umbrella hoarding a references/ file per session. This shapes HOW you update, not WHETHER you update. uSignals 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 (re-load it with skill_view during this review — see Read-before-write below). It is the skill that was in play, so it's the right one to extend — but only if it is curator-managed. Bundled, hub, pinned, and user-owned skills are off-limits to you no matter how relevant (see Protected skills below); for those, fall through to the next option. 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` — topical depth needed only sometimes: a decision table, a reproduction recipe, provider quirks, condensed domain notes or API excerpts. Name it by TOPIC and extend an existing file when one covers the topic; do not create a per-session or per-incident file, and do not paste error transcripts — distill them to the rule. • `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). Read-before-write (ENFORCED — skill_manage refuses otherwise): before you patch or edit an existing skill's SKILL.md, call skill_view(name) for that skill during this review. Before you overwrite or remove an EXISTING supporting file, call skill_view(name, file_path=...) for that exact file. Content quoted earlier in the conversation transcript does NOT count — the guard requires a fresh load within this review, and your write must be based on what skill_view just returned. Creating a brand-new skill or adding a NEW supporting file needs no prior read. If a write is refused with a read-before-write error, call skill_view for the named target once and retry the write once; do not loop. 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. Protected skills (DO NOT edit these): • Bundled skills (shipped with Hermes, e.g. 'hermes-agent'). • Hub-installed skills (installed via 'hermes skills install'). • Skills in skills.external_dirs (externally owned). • PINNED skills (marked via 'hermes curator pin'). You are an autonomous no-user-present actor, so pin blocks your writes too — content updates included. Only the user, in a foreground session, can change a pinned skill. • USER-OWNED skills — anything not curator-managed. A skill the user hand-wrote, installed by URL, or asked a foreground agent to create is theirs, not yours; your writes to it WILL be refused. This includes skills that were loaded or consulted this session: being in play does not make one yours to edit. If such a skill is wrong or outdated, say so in your reply and recommend 'hermes curator adopt ' — do not try to patch it. If the only skills that need updating are protected, say 'Nothing to save.' and stop. Do NOT capturez'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.zBReview the conversation above and update two things: **Memory**: u**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 SKILL.md of always-on rules and a small `references/` set of topical depth — not narrow one-session skills, and not an umbrella hoarding a references/ file per session. uSignals 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 (re-load it with skill_view during this review — see Read-before-write below). It was in play; it's the right place — provided it is curator-managed. Protected and user-owned skills are off-limits however relevant; fall through when one of those is the best fit. 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 topical depth (decision tables, recipes, quirks, condensed domain notes) — extend an existing topical file before creating one, never a per-session file; `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). Read-before-write (ENFORCED — skill_manage refuses otherwise): before patching or editing an existing skill's SKILL.md, call skill_view(name) during this review; before overwriting or removing an EXISTING supporting file, call skill_view(name, file_path=...) for that exact file. Content quoted earlier in the transcript does NOT count — base the write on what skill_view just returned. New skills and NEW supporting files need no prior read. On a read-before-write refusal: view the named target once, retry the write once, do not loop. User-preference embedding: when the user complains about how you handled a task, update the skill that governs that task rather than memory. 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'. A user-preference lesson lives in exactly ONE place: the skill that governs the task when one exists, USER.md only for cross-cutting preferences no skill owns — never both. Duplicating it is how a memory file ends up restating SKILL.md until both hit their size limits. If you notice overlapping existing skills, mention it — the background curator handles consolidation. Protected skills (DO NOT edit these): • Bundled skills (shipped with Hermes, e.g. 'hermes-agent'). • Hub-installed skills (installed via 'hermes skills install'). • Skills in skills.external_dirs (externally owned). • PINNED skills (marked via 'hermes curator pin'). Pin blocks autonomous writes entirely — content updates included — because no user is present to consent. Only a foreground session can change one. • USER-OWNED skills — anything not curator-managed (hand-written, URL-installed, or created by a foreground agent at the user's request). Your writes to these WILL be refused, including to skills loaded or consulted this session. If one is wrong, say so in your reply and recommend 'hermes curator adopt ' instead. If the only skills that need updating are protected, say 'Nothing to save.' and stop. Do NOT capture as skillsuAct 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.c6|d|t||kDrdzSdzS)Nu…r)r)rlimits r_previewr:s& >2 >>r )u➕rx)u✏️rr)u➖old_text<)addrremovezDict[str, Tuple[str, str, int]]_MEMORY_OP_FORMATSctj|xsd\}}}|r|j|xsdnd}|r|d|dt||SdS)zMVerbose line for one memory add/replace/remove, or None when no preview text.)NrrrrN)rrar)labelactionfieldsglyph field_namerrs r_memory_op_linerDs[155f=NE:u+06::j ! 'RbD9=eWAeWAhtU34 5G4Gr c|jdd}|jdd}|jd}t|tr|ni}|jddxs|jdd}|jddxs|jdd}|d k(r|s|rd ||fD\} } d |d | d | dSdddj|} | r|jdrd |d| d|dS|rd|Sd|S)NrrrP_changeold old_stringnew new_stringpatchc3TK|] }t|djdd"yw)PrrN)rrrts rrz&_verbose_skill_line..Ts##i1HQO$;$;D#$F#is&(u 📝 Skill 'z ' patched: "u" → ""created rewritten)createedit description' z: u📝 zSkill )rar`rb) datadetailrr skill_name change_rawchangerr old_preview new_previewverbs r_verbose_skill_linerKs ZZ" %FFB'J)$J!+J!=:2FE2&F&**\2*FJE2&F&**\2*FJ jJ#iQ[]gPh#i [j\{m9[MY[\\ 5 9 9& AD  =)j\D6F=4I3JKK 'U7) >vfX->>r c B|jd}t|trP|rN|Dcgc]0}t|tst ||jdd|2}}|Dcgc]}|s| c}St ||jdd|xs|dgScc}wcc}w)N operationsrr updated)rar`rrbr)rr ops_rawoprlines r_verbose_memory_linesr\sjj&G'4 WLSlbWabdfjWkx( parsed call arguments for notify tools. Result JSON only says "Entry added"; the call arguments carry action, target and content previews. Restricting to notify tools keeps helper tools from surfacing as memory work just because they succeeded.r skill_managerrrrrPrid arguments{}r)rr) r&r`rbrarjsonloadsJSONDecodeErrorr=_CALL_DETAIL_DEFAULTS) review_messages notify_toolsall_tool_call_ids call_detailsmsgrfnfn_nametcidrkrs r_collect_review_call_detailsr,ls`n-L UL$"#t$;(F '',+1r Bb$' B'-2BffVR(G66$%D1E 1EEcd|xsgDS)Nc3lK|],}t|ts|jddk(s)|.yw)rrNr)rrs rrz!_tool_messages..s) Y!At)<vRXAXA Ys 444r2)messagess r_tool_messagesr0s Yx~2 YYr ctt|}|Dchc]}|jds|d}}|Dchc]9}|jdrt|jdts5|d;}}||fScc}wcc}w)zN``(tool_call_ids, contents)`` of tool messages already in the parent snapshot. tool_call_idr)rr0rar`r)prior_snapshotpriorsridscontentss r_prior_tool_keysr7s .0 1F&, Fn0E1^  FC F&,pAEE.4IjYZY^Y^_hYiknNo) pHp = GpsBBBB4Bc|jdr*|jdr|jdr|dgSgS|jdd}|jddxs|jdd}|jddk(}|rd|vrd d d d d dd}|jd}|jdrt|tsgSg}|D]} t| tr| jddur'|j| jd} | sJ| jds\| jdr d| ddnd} |j d| dd| | |S|j |s!d vsdvs|rt fddDr|gS|s|sgS|rdnddd j||} |r|rt|||gSt| |St fd!d"Dxs|xrd#v} | r| d$gSgS)%zVSummary line(s) for one successful notify-tool result (``[]`` when nothing to report).stagedproposal_stagedrrrNrrresultsrpatchedrwrittenremoveddeleted)rrr write_file remove_filedeleteoperations_appliedsuccessTrrP file_pathz ()zSkill 'rupdatedc3&K|]}|v ywNr2)rwordlowers rrz _action_lines..s)fD$%-)f)r<r?r=SkillMemoryz User profile)rrc3&K|]}|v ywrIr2)rr+rKs rrz _action_lines..s NQa5j NrL)addedreplacedr>appliedrr) rar`rrbrrKanyrr)r r verboserrNis_skillverbsr;rresultrpathrhitrKs @r _action_linesrZs) xx%)HH->$?DHHYDWY _]__hhy"%G XXh # ?vzz(B'?Fzz&!^3HI%%y+(iY((9%xx,-Z5NI GFfd+vzz)/DD/P99VZZ12D 6*6 no actions; ``on`` -> generic "Memory updated"/tool messages; ``verbose`` -> content previews from the tool-call arguments. See #14944. onoffrTr2rrrD)rrKr7r,r0rar`rr r!r=rbextendrZ) r#r3notification_modemoderTexisting_tool_call_idsexisting_tool_contentsr%r&actionsr'r*r s r#summarize_background_review_actionsrds<  (D ) / / 1D u} iG5En5U22&B?&S#|Go.Sww~& --2CT`H`  *C 0S^G]5]  ::cggi67D $%TXXi-@ }T<+;+;D+A+GRQRS N$$i0   s%DD21D2) write_originexecution_contexttask_idr2c R|xs t|dd|xs t|dd|jxsd|jxsd|jxs tj j ddd|xsd |xsd d }|jDcic] \}}|d vs ||c}}Scc}}w) z?Build provenance metadata for external memory-provider mirrors._memory_write_originassistant_tool_memory_write_context foregroundrHERMES_SESSION_SOURCEclirN)rerf session_idparent_session_idplatform tool_namergr2>Nr)r4ro_parent_session_idrqosenvironraitems)r5rerfrgr2metadatar+vs rbuild_memory_write_metadatarys %`7MO_(`.g'%AXZf2g&&,""55;NNTbjjnn5Le&T?d$, H&^^- ETQ*1DAqD EE Es B#B#) input_tokens output_tokenscache_read_tokenscache_write_tokensreasoning_tokens api_callsc idDcic]}|t||dc}tDcic] }|tt|d|dxsd"c}dt|ddiScc}wcc}w)zASnapshot in-memory usage counters from a review fork (pre-close).)rrrNsession_restimated_cost_usdsession_estimated_cost_usd)r4_USAGE_COUNTERSrq)r#rs r_snapshot_review_usagers| <] ^S3 c40 0 ^ P_ `3GLHSE*:A>C!D D `  gl4PRVW  ^ `s A%A#c  t|dd}t|dd}tDcic]!}|t|j|xsd#}}||rt |j sy|j |fd|jd|jd|jd|jd |jd d |ycc}w#t$r }tjd |Yd}~yd}~wwxYw) uHRecord a fork's usage against the parent session (best-effort, never raises). The fork has ``_session_db = None`` so conversation_loop's DB-gated accounting never sees its calls; route them through the aux-accounting chokepoint, which writes only ``session_model_usage`` — never the transcript or ``sessions`` row. _session_dbNrorr_rrrrr)rerbilling_providerbilling_base_urlrapi_call_countz8Background review usage recording failed (non-fatal): %s) r4rrqrarSvaluesrecord_auxiliary_usagepoprJrKrL) parent_agentusage session_dbrorcountsrs r_record_review_usage_to_parentrs T\=$? \<> ;JKC#s599S>.Q//KK  Zs6==?7K ) ))  0 '8J"YYz2UYYzEZ$yy)=>!::k2  7=  L T OQRSSTs/"C&C C*A%CC C>C99C>cB|xsgDcgc]F}t|jjdjjH}}t d|D}t d|D}dj dd|fd|ffDxsdScc}w) uEMap a review action summary to ``none`` / ``skill`` / ``memory`` / ``skill+memory``. Prefix-based on the formats :func:`summarize_background_review_actions` emits (``Skill …``, ``📝 Skill …``, ``Memory …``, ``User profile …``), so a free-text line like ``Skipped: no skill worth saving`` stays ``none``.u📝c3>K|]}|jdyw)skillN startswithrs rrz*_classify_review_result..s:aALL):c3>K|]}|jdyw))rz user profileNrrs rrz*_classify_review_result..sN!Q\\"<=Nr+c3,K|] \}}|s |ywrIr2)rkindrYs rrz*_classify_review_result.. s`YT3\_D`s rrnone)rlstrip removeprefixrKrSr)rcrlowers has_skill has_memorys r_classify_review_resultrs X_Wdbd eVc&k  "//7>>@FFH eF e:6::INvNNJ 88`GY+?(JAW*X` ` jdjjfsA BcHtjdgfddD|y)zHEmit a per-fork completion line so cost is visible where it is incurred.zZBackground review complete: thread=bg-review calls=%d in=%d out=%d cache_read=%d result=%sc3ZK|]"}tj|xsd$yw)rN)rqra)rr+rs rrz)_log_review_completion..(s# nQ#eiila ns(+)rrzr{r|N)rKinfo)rrWs` r_log_review_completionr#s/ KK " o*m n  r )providers_allowedproviders_ignoredproviders_order provider_sortprovider_require_parametersprovider_data_collectionc t|ddt|dddtDcic]}t||dx}s||c}}tjt|ddxsgx}r||d<|Scc}w)arAIAgent kwargs that keep a SAME-model fork's request bytes identical to the parent's. Only for the un-routed path: on a different model the cache is cold anyway, and the parent's reasoning-effort vocabulary may be invalid for the routed provider (OpenRouter forwards ``reasoning.effort`` unclamped; codex_responses passes ``max``/``ultra`` through unmapped).reasoning_configNephemeral_system_prompt)rrprefill_messages)r4_PROVIDER_PIN_ATTRScopydeepcopy)r5r6valkwargsparent_prefills r_same_model_parity_kwargsr6s$E+=tD#*52KT#R  "5 \tUY@Z9Z9Z49 \ Fwu6H$'O'USUVV~V%3!" M ]s A.A.c\tt|jdxsdj}|r t |ddryd|_d|d}t |d d}t |r tt5||dddtjd |y#1swY xYw) a One-shot user-visible notice: ``auxiliary.background_review.reasoning_effort`` is IGNORED on the same-model path (#104116). The fork inherits the parent's ``reasoning_config`` verbatim so its request bytes keep the parent's prompt-cache prefix (#30532: a diverged ``thinking`` field on the fork-birth request re-created a large share of the cache); the no-op used to be silent, so a user who set the key saw no feedback at all. Gated on the parent so a nudge-per-turn session warns once, not per fork.reasoning_effortr"_warned_bg_review_reasoning_effortFNTu2⚠ auxiliary.background_review.reasoning_effort='a,' has no effect while the review runs on the main model: the fork inherits the conversation's reasoning effort to keep the parent's prompt-cache prefix (see memory docs, same-model review reasoning). Route the review elsewhere via auxiliary.background_review.provider/model to use a different effort.rr) rrlrarr4rrrrJrKrY)r5rkeffortrrs r_warn_ignored_reasoning_effortrJs/9==>PQWUW X ^ ^ `F WU$H%P/3E, aeNNz0B0TennFF:&BFF:4F4N$66)$,HYAZVV$78>BUZUeUe#E+=tD$U,?FW[F"&&&,!,/|"&&#S)bm "Y-"&&.:NB O  /67 M1: :* G%/!" Mr ictjt|ddxsg|_|jDchc] }|dd c}|_t |_ycc}w)uSame-model fork: advertise the parent's exact tools[] (its last outbound payload — an empty list included) so the request prefix matches byte-for-byte, then freeze the snapshot generation. Dispatch stays behind the review whitelist; advertising is not permission.toolsNrrP)rrr4rvalid_tool_names _FROZEN_TOOL_SNAPSHOT_GENERATION_tool_snapshot_generation)r#r5rs r_inherit_parent_tool_surfacersT wugt'D'JKLJVJ\J\$]$T*%5f%=$]L!-ML*%^sAr_)rec ddlm}t||}t|j d}|s|dk(r t |||dit |||||}|x|_|_|j|_ |j|_ |j|_ dx|_ |_ dx|_x|_|_d|_d|_|j&|_|sW|j(|_|j*|_t-|}|r||_|j1|_t5||t7|t9|||_|||fS) uLConstruct a detached AIAgent fork with warm prompt-cache parity (shared with ``/btw``): same runtime/credentials as the parent, byte-identical system prompt / tools[] / reasoning config on the same-model path, shared session_id for prefix warmth, full persistence detachment (no state.db writes, rotation, or external memory providers; in-place-only compaction). Returns ``(fork_agent, runtime_dict, routed)``; ``routed`` means a different model (cache cold — replay a digest). The caller owns registration, whitelisting, running, usage attribution and teardown.r)AIAgentrr_TFNr2) run_agentrrr-rarrrirk _memory_store_memory_enabled_user_profile_enabled_memory_nudge_interval_skill_nudge_interval_skip_mcp_refresh_persist_disabledsuppress_status_output_end_session_on_closerro_cached_system_prompt session_startr_inherited_cache_scope_conversation_root_id_cached_conversation_rootrrr~) r5rkrrer_rt_routedr#inherited_scopes rbuild_cache_parity_forkrs\" "% 2C3778$%G |'::&uh7^.uc7NT\]^LMYYL% (J!&!4!4L#(#8#8L ).)D)DL&OPPL',*LmqpL"p\%ClFi).L&#L#..L -2-H-H *%*%8%8 ":%@ 2AL /271L1L1N .$\59\*/IS_.`L+ g %%r c 2tjd||y)zNon-interactive approval: dangerous-command guards resolve to "deny" instead of input(), which would deadlock against the parent's TUI.z8Background review auto-denied dangerous command: %s (%s)deny)rKrY)rrrs r_bg_review_auto_denyr s NNMwXcd r chddlm}tt5||dddy#1swYyxYw)Nr)set_approval_callback)tools.terminal_toolrrrJ)callbackrs r_set_thread_approval_callbackrs*9 ) (h'(((s (1c|yt|dr4t|d5|r||_n|j|urd|_dddt|drlt|d5|r|jj |n8t t t5|jj|ddddddyy#1swYxYw#1swYxYw#1swYyxYw)upAdd (``register=True``) or remove the fork on the PARENT's tracking slots: ``_background_review_agent`` (direct pointer the next live turn interrupts) and ``_active_children`` (interrupt() fan-out). Removal is identity-scoped and idempotent; both are best-effort for direct test stubs — the prepared run token is the live-turn cancellation authority.NrUr:_active_children_active_children_lock) hasattrr8rUrrrr|r<r)r5r#registers r_track_review_forkrs u01 E#< = 61=.//<?15.  6 u() E#: ; @&&--l;j.9@**11,?@  @ @*  6 6@@  @ @s/ B=3CC +C=C C CCcddlm}|jxs |j}|r|rddgndg}||dDchc] }|dd }}|d d hz}t } t |j d g} t| tr?| D chc]4} t| ts| js%| j6}} ||z|fScc}wcc} w#t$rtjd d Y3wxYw)u``(whitelist, configured_extra_tools)`` for the review fork — DISPATCH-side only, so the advertised ``tools[]`` stays byte-identical to the parent's (prompt-cache parity).r)get_tool_definitionsrskillsT)rrrrP read_file search_files extra_toolsz*background_review extra_tools parse failedrG) model_toolsrrrr&rlrar`rrrrJrKrL) r#rk review_memoryr memory_onreview_toolsetsr whitelistconfigured_extra_tools extra_rawrPs r_review_tool_whitelistr 2s  1,,R 0R0RI.7Mx*PXzO0DVerv0wx1:v&xIx+~..I$#&%R28<@@PRS i &?H%stJW[]`Lafjfpfpfrdjjl%s "%s - -/E EE;y4&t R AD QRs5C /C C C1CCC C98C9cXeZdZUdZdZded<eeZded<ee Z ded <y) _ReviewForkStatezSMutable hand-off between the fork phase and the outer worker's error/cleanup paths.Nrr#)default_factory List[Dict]r#Dict[str, Any] review_usage) r.r/r0r1r#__annotations__rrr#rbrr2r rrr]s-]L#"'"=OZ=#(#>L.>r rcltt5|jdddy#1swYyxYw)zThe fork shares the foreground session ID: close() / shutdown_memory_provider() are session-bound (close() kills that session's terminal processes), so release only clients.N)rrJrelease_clients)r#s r_release_fork_clientsrfs- ) '$$&'''s*3ct||t\|_}} ||j_t ||jdddlm} m} t|j||\} } djt| }| rd|dnd }| rd |dnd }d | vrd nd }d | vrd nd}| | d|zdz|zdztt5ddl m}|ddd ||j|jr6|jj!|dz|zdz|z| r t#|n|| |jD|j$j't)|jt+||j$t ||jdt-||t/t1|jdg|_t5|jd|_y#1swYxYw#| |jD|j$j't)|jt+||j$t ||jdt-||wxYw)aFork phase (inside thread-scoped silence): build the fork, run the prompt under the tool whitelist, snapshot its messages/usage, release its clients. Partial progress lands on ``st`` so the caller's error path still sees usage and the fork to clean up. ``explicit`` (/refine) keeps the ``background_review`` origin (curator/skill guards still apply) but marks the fork attended, so the unattended-only memory delete gate leaves the full operation set available.)rTrr)set_thread_tool_whitelistclear_thread_tool_whitelistrz& Configured extra tools also allowed: .ru8 Exception — these configured tools are also allowed: rz and memory for notes (add only)zmemory and skill zskill zBackground review denied non-whitelisted tool: {tool_name}. Allowed here: skill_view/skills_list/read_file/search_files to read, skill_manage(action='patch'|...) to change skillsz Do not retry {tool_name}.) deny_msg_fmt)#_reset_background_review_read_marksNz You can only call uPmanagement tools. Other tools will be denied at runtime — do not attempt them.) user_messageconversation_historyF_session_messages)r_REVIEW_MAX_ITERATIONSr#_review_attendedrhermes_cli.pluginsrrr rsortedrrJtools.skill_manager_guardsrr$run_conversationrrrrrrBrr4r#r)r5rpromptrk review_runstrexplicitrrrrreview_whitelistr  extra_list deny_extra prompt_extramemory_phrase_denymemory_phrase_promptrs r_run_review_forkr1msl%< x(>%@!BOS''/BOO$uboo=Y/EbooW_an/o,,6"89:JKa9*QGgiJ_uMj\YZ[{}L@HK[?[;ac2:>N2N.T\ @! !$' '*4 47S S ) .R+-.8  !9!9"//!J OO , ,558LL::1G;>A=I;cdjtj|}|jd||jr-t t 5|j d|dddyy#1swYyxYw)Nu · u 💾 Self-improvement review: u💾 Self-improvement review: )rrbfromkeys _safe_printbackground_review_callbackrrJ)r5rcsummarys r_publish_review_summaryr7szkk$--01G 8 BC '' i  Y  , ,/MgY-W X Y Y( Y Ys A33A<c |'|jjr t||yttt |sHt ||jds-tjdt|ddtdyt} t5t||||||||ddd t|j|t|dd}t#|j$t'||r t)||t-||j.d t|||j.@t1t 5t5t3|j.ddddddtdy#1swYxYw#t $r"} tjd | g}Yd} ~ d} ~ wwxYw#t $rU} tjd | |j$rt#|j$d |j+d | Yd} ~ d} ~ wwxYw#1swYxYw#1swYxYw#t-||j.d t|||j.Zt1t 5t5t3|j.dddn #1swYnxYwdddn #1swYnxYwtdwxYw)aCDaemon-thread worker: build the fork, run the prompt, surface the action summary via ``agent._safe_print`` / ``background_review_callback``. ``review_run`` (from :func:`prepare_background_review_run`) cancelled before the first provider call aborts without entering ``run_conversation()``. See #84423. NrzBackground review skipped: provider %r cannot emit Hermes tool calls, so the review fork could not write memories or skills. Set auxiliary.background_review.{provider,model} to route the review to a normal model.rrmemory_notificationsr\)r_zsummarize_background_review_actions returned partial results after exception (treating as empty); suppressing AttributeError that previously aborted the entire review (#59437): %sz)Background memory/skill review failed: %srzbackground reviewFr)rr"rBrrrrrarKrYr4rrr1rdr#rJrrrr7_emit_auxiliary_failurerr#rr) r5rr'rkr(rr*r)rcrs r_run_review_in_threadr;sv*"="="D"D"F$UJ7!"67 'u -6MeU]6^6b6bck6l b E:s +  &d+  B4,# $ r U$5vxUWYfhp q r :""$5")%1G"NG r0G0PQ  #E7 3 5"//EB$UJ7 ?? &)$ 7&;&= 7%boo6 7 7 &d+Y r r$  NNI   G  >BAF ?? "2??G < %%&91== > 7 7 7 7 5"//EB$UJ7 ?? &)$ 7&;&= 7%boo6 7 7 7 7 7 7 &d+s G!F 4G=#F -G H0H$-H0 FG GF;6G;GG H! A HH<H!!H<$H- )H00H9._target's $fxJ'( r<rrGrdry)Pathc| ddlm}||jddSt \}}|S#t$rtj ddYywxYw)uReturn whether automatic post-turn background review may spawn. Controlled by ``auxiliary.background_review.enabled`` (default ``true``). Explicit ``/refine`` (``focus`` set) bypasses this gate — same contract as zeroing the nudge intervals, which stops automatic forks but leaves manual refine working (issue #87250). Prefer :func:`load_background_review_settings` at the spawn call site so the task block is not re-read on the same turn. rrrTrz[Failed to interpret background_review.enabled; leaving automatic review enabled (fail-open)rG)rrrarJrKrYr)rkrr_s ris_background_review_enabledrK;sj  -"8<< #:DI I12JGQ N  NN7     s2 AA)r5rr6rr+zIterator[None])r5rr+Optional[_BackgroundReviewRun])r5rr>rLr+r,)r#rr+r,)r5rr+r,)rcrr+rrI)rkOptional[Dict[str, Any]]r+r)r#rr+rq)NN)rkrMr#rr+z Optional[int])r+ztuple[bool, Dict[str, Any]])r5rrkrMr+r) r5rrrrrrrJr+r,)r5rr+r-)rr r+r))rrrrqr+r)rrrrqr+r)rrrrrzDict[str, str]r+ Optional[str])r r r r rrr+r)rrr r r+ List[str])r#rr+zTuple[set, dict])r/rr+zIterator[Dict])r3rr+Tuple[set, set])r r r r rTr-r+rP)r\)r#rr3rr_rr+rP) r5rrerOrfrOrgrOr2rOr+r)r#rr+r)rrrrr+r,)rcrPr+r)rrrWrr+r,)r5rr+r)r5rrkrMr+r,)rkrMr+rM) r5rrrrr-rrqrkrMr+r)r#rr5rr+r,) r5rrkrMrrqrerr+z Tuple[Any, Dict[str, Any], bool])rrr+r,)r5rr#rrr-r+r,)F)r#rrkrMrr-r+rQr?)r5rrrr'rrkrMr(rLr)rrr-r*r-r+r,)r5rrcrPr+r,)NNFF)r5rrrr'rrkrMr(rLrr-r*r-r+r,)FFNNNF)r5rrrrr-rEr-rFrOrkrMr(rLr*r-)rkrMr+r-)ar1 __future__rrrloggingrtr contextlibrr dataclassesrrtypingrr r r r r agent.prompt_cache_scoperagent.thread_scoped_outputr getLoggerr.rKrXrr8r@rBrSr[r!rtrvrrrfrlrxr~rrrrrr_MEMORY_ROUTING_BLOCKr=_LESSON_LAYER_BLOCK_DO_NOT_CAPTURE_BLOCKr>r<rrrrrrr"r,r0r7rZrdryrrrrrrrrrrrrrrrrrr rrr1r7r;rCrG__all__pathlibrHrKr2r rr_sT#  /(==D<   8 $,/)!!H"]& < '!%$+!2 kDH *& *=@ * *"&R& 38N T)*YY/>,4 !4 4HO^-_O-`aRn*+336II4<x"7y<7zd{>dF? #/IUl73 H?"\ +>Z$/PW[""1;"PS""L26Z^!F F!.FJWF F1>FF$ T*k ("0K>(<@ 8DR<$1 N6:G&+G& G&2G&NQG&G&&G&Z(@0RW(F(F!9(FJN(F(FV ?? ?']b= =#-=7:=F^=.=4D=UY== =@Y]a27Q, Q,#-Q,7:Q,&Q,;YQ,Q,,0Q, Q,l,B(5' *.& r