߲j3 dZddlZddlZddlmZmZddlmZmZm Z m Z ddl m Z dZ dZdZd Zd ed efd Zd edededed edzf dZGddeZy)a Abstract base class for pluggable context engines. A context engine decides when/how conversation context is compacted near the token limit, tracks usage, and may expose tools. ContextCompressor is the default; ``context.engine`` selects a plugin (``plugins/context_engine//``); one is active. Lifecycle: on_session_start() -> per API response update_from_response() -> per turn should_compress() / compress() -> on_session_end() at real session boundaries only (CLI exit, /reset, gateway expiry), never per-turn. N)ABCabstractmethod)AnyDictListOptional)redact_sensitive_textipiiz+ ...[memory provider context truncated]... memory_contextreturnct|jdd}t|tkr|S|dtt z|t dzS)zBPrepare provider context for a context-engine/LLM egress boundary.T)forceredact_url_credentialsN)r striplenMEMORY_CONTEXT_MAX_CHARS_MEMORY_CONTEXT_HEAD_CHARS!_MEMORY_CONTEXT_TRUNCATION_MARKER_MEMORY_CONTEXT_TAIL_CHARS)r sanitizeds 9/home/ubuntu/.hermes/hermes-agent/agent/context_engine.pysanitize_memory_contextrsT%n&:&:&ed?eddfd@Z-y)F ContextEnginez.Base class all context engines must implement.r cy)z,Short identifier (e.g. 'compressor', 'lcm').Nr selfs rnamezContextEngine.name3rrlast_prompt_tokenslast_completion_tokenslast_total_tokensthreshold_tokenscontext_lengthcompression_countg?threshold_percentprotect_first_nprotect_last_nTrusageNcy)a=Update tracked token usage after every LLM call. ``prompt_tokens``/``completion_tokens``/``total_tokens`` are always present; the canonical buckets (``input_tokens``, ``output_tokens``, ``cache_read_tokens``, ``cache_write_tokens``, ``reasoning_tokens``) are optional on older hosts. Nr )r+r9s rupdate_from_responsez"ContextEngine.update_from_responseKr-r prompt_tokenscy)z0Return True if compaction should fire this turn.Nr r+r<s rshould_compresszContextEngine.should_compressTr-rztuple[bool, str | None]c(|j|dfS)a Return ``(should_compress, reason)``. Engines with block reasons (summary-LLM cooldown, anti-thrashing guard) override this so callers can warn instead of silently skipping; the default keeps plugin engines from raising AttributeError. N)r?r>s rshould_compress_infoz"ContextEngine.should_compress_infoXs##M2D88rmessagescurrent_tokens focus_topicr r cy)uCompact ``messages`` into a valid OpenAI-format list that fits the budget. ``focus_topic`` comes from manual ``/compress `` (prioritise that topic); ``force`` asks to bypass an engine-owned cooldown; ``memory_context`` is provider text for the handoff prompt. Older engines may omit optional parameters — the host filters them by signature. Nr )r+rBrCrDr r s rcompresszContextEngine.compressar-rc |dfS)aMDeterministically trim old tool-result payloads without an LLM call. Runs on a low, cost-oriented trigger independent of ``should_compress`` so large-window engines reclaim re-sent tool output long before full compaction. Returns ``(messages, n_pruned)``; the default no-op keeps older engines safe. rr )r+rBrCs rprune_tool_results_onlyz%ContextEngine.prune_tool_results_onlyns{r)conversation_messagesincoming_message budget_tokensrequest_messagesrIrJrKcy)uOptionally *select* (replace) the context for THIS request, pre-generation. Runs on every provider request (also retries), independent of ``should_compress()``: ``compress()`` shrinks over-long context, this swaps in a different one (retrieval, topic routing, branch switching). Return ``None`` to leave the request unchanged. The returned list is request-only — it MUST NOT be treated as persisted transcript state (session DB history is untouched); unlike ``pre_llm_call`` it may replace the list. The host runs it before prompt cache-control and every request sanitizer, so a malformed replacement never reaches the provider and the default no-op keeps the request byte-identical; an engine that replaces the list changes its own cache prefix (breakpoints are re-derived on the selected list). ``request_messages`` is the assembled request (system prompt + history + ephemeral prefill); ``conversation_messages`` is the persisted history for reference only (do not mutate); ``budget_tokens`` is the model's context length or 0 if unknown. Nr )r+rLrIrJrKs rselect_contextzContextEngine.select_contextys(rkwargsc y)aObserve a finished turn (complement of ``select_context()``) to index/update routing state for the next request. Best-effort, not guaranteed: fires from the normal finalization seam only; some abnormal early returns (content-policy block, provider terminal failure) skip it. ``messages`` is a read-only shallow copy (return value ignored; never rely on transcript mutation). ``usage`` has the ``update_from_response`` shape and is ``None`` when no provider response was reached (interrupt). ``kwargs`` may include ``turn_id``, ``task_id``, ``api_call_count``, ``interrupted``, ``failed``, ``turn_exit_reason``. Nr )r+rBr9rOs ron_turn_completezContextEngine.on_turn_completesrcy)zOCheap rough check before the API call (no real token count yet); default skips.Fr r+rBs rshould_compress_preflightz'ContextEngine.should_compress_preflightsr rough_tokenscy)zTrue when preflight should trust recent real usage over the noisy rough estimate (avoids re-compacting after a compressed request already fit).Fr )r+rUs r$should_defer_preflight_to_real_usagez2ContextEngine.should_defer_preflight_to_real_usagesrrrrc "|jr|SdS)aBUser-visible status for automatic compaction, or ``None`` to suppress it. ``phase`` is the host call site (``"preflight"`` / ``"compress"``); ``context`` carries best-effort ``approx_tokens`` / ``threshold_tokens``. Warnings, errors and manual ``/compress`` are not governed by this hook. N)r)r+rrrs rrz5ContextEngine.get_automatic_compaction_status_messages#'"G"GQTQrcy)zPreflight guard for gateway ``/compress``: False reports "nothing to compress yet" without an LLM call (e.g. transcript entirely protected).Tr rSs rhas_content_to_compressz%ContextEngine.has_content_to_compresssr session_idc y)zVSession begins: load persisted state. kwargs may include hermes_home, platform, model.Nr )r+r[rOs ron_session_startzContextEngine.on_session_startr-rcy)uLReal session boundary (CLI exit, /reset, gateway expiry) — never per-turn.Nr )r+r[rBs ron_session_endzContextEngine.on_session_endr-rc<d|_d|_d|_d|_y)zO/new or /reset: reset per-session state (default: counters and token tracking).rN)r.r/r0r3r*s ron_session_resetzContextEngine.on_session_resets$#$&'#!"!"rcgS)z>Tool schemas this engine exposes to the agent (default: none).r r*s rget_tool_schemaszContextEngine.get_tool_schemass rr,argsc 6tjdd|iS)zHandle a call to one of this engine's tools; must return a JSON string. kwargs may include ``messages`` (live in-memory list).errorzUnknown context engine tool: )jsondumps)r+r,rdrOs rhandle_tool_callzContextEngine.handle_tool_calls zz7&CD6$JKLLrct|jd}||j|j|jrt d||jz dznd|j dS)z:Status dict with the standard fields run_agent.py expects.rd)r.r1r2 usage_percentr3)maxr.r1r2minr3)r+ last_prompts r get_statuszContextEngine.get_statussc$1115 "- $ 5 5"11RVReReSkD4G4G&G#&MNkl!%!7!7   rc,tj|S)alPer-agent instance of a plugin-registered engine (the plugin system holds ONE shared instance; every AIAgent gets its own so a child's update_model() cannot mutate the parent's). Override when the engine holds uncopyable state (locks, DB connections): return a fresh engine sharing the durable backend and copying only mutable budget state.)copydeepcopyr*s rclone_for_agentzContextEngine.clone_for_agents }}T""rmodelbase_urlapi_keyproviderapi_modec||_ddlm}t|ds|j|_||t |di|j ||_|j|_t||jz|_ y)u.Model switch / fallback: recompute threshold_tokens (override for more). Per-model threshold override (longest substring match), else the raw config percent — snapshotted ONCE so repeated switches fall back to the configured value, not the previous model's override. r)resolve_model_threshold_config_threshold_percentmodel_thresholdsN) r2agent.context_compressorr{hasattrr4r|r!_base_threshold_percentintr1)r+rur2rvrwrxryr{s r update_modelzContextEngine.update_modelsv-Dt89-1-C-CD *'> 74!3R8$:X:XZb(d$!%!=!= #NT5K5K$K Lr)N)NNF)r N)r r()rrrr).__name__ __module__ __qualname____doc__propertyrr#r,r.r__annotations__r/r0r1r2r3r4floatr6r8rboolrrr;r?rArrrFtuplerHrNrQrTrWrrZr]r_rarcrirprtrr rrr(r(0s8 ;c;; "#C#scNCs $u#OSNC.2$d1 $sCx. T  ?S?D??9#9AZ9NRVX  T#s(^,  >Fsm  c]  26  PS   d38n     LP T#s(^, >ADj  tDcN#S( ) hl+/a $T#s(^ 4PTUYZ]_bZbUcPdsCx.@C d38n , d38n)= d3PS8n gj os $tCH~2F4 R R.1 R>A R t RT#s(^0D e3eTe[[T#s(^8L[QU[#"$tCH~"6MSMS#XMSM  DcN  #SU,.MM*-M9<MLOMM&)M Mrr()rrrrgabcrrtypingrrrr agent.redactr rrrrr#rr&r(r rrrs #,,.!""$S!@C@C@ ( (s (UX (eh (mpswmw (JMCJMr