,jUdZddlmZddlZddlZddlZddlZddlmZddl m Z m Z m Z ddl mZejeZdaded <ed d hZejd ZeZdMdZdNdZeGddZdZdZdZded<dZ eGddZ!dOdPd!Z"dd"dQd(Z# dOdRd-Z$e%d.d/d0d1d2d3d4d5d d67 e%d8d9d8d9d2d3d d6:e%d;dd=d>d2d3d d6:e%d4d5dd?d2d3d4d5d d67 e%dd?dd?dd?dd@Ae%dd?dBdCd2d3dd?d dd@D dEZ&dFedG<dSdHZ'dSdIZ(dTdKZ)dUdLZ*dS)VuOCredits tracking for Nous inference API responses. Parses x-nous-credits-* (and optional x-nous-tool-pool-*) headers from inference responses into a validated CreditsState dataclass. Provides depletion detection (paid_access), subscription-cap used_fraction, and warn-once schema-version gating. This is the hardened parser used by all live consumers (run_agent, tui_gateway) — not a dev-only shim. Header schema (x-nous-credits-* family): x-nous-credits-version contract/schema version x-nous-credits-remaining-micros total remaining balance (micros) x-nous-credits-remaining-usd same, formatted USD string x-nous-credits-subscription-micros subscription balance (SIGNED; may be negative/debt) x-nous-credits-subscription-usd same, formatted USD string x-nous-credits-subscription-limit-micros subscription cap (PAIRED/optional) x-nous-credits-subscription-limit-usd same, formatted USD string (PAIRED/optional) x-nous-credits-rollover-micros rolled-over balance (micros) x-nous-credits-purchased-micros purchased balance (micros) x-nous-credits-purchased-usd same, formatted USD string x-nous-credits-denominator-kind "subscription_cap" | "none" x-nous-credits-paid-access "true" | "false" (STRING!) x-nous-credits-disabled-reason reason string (header omitted when null) x-nous-credits-as-of-ms server-side timestamp (ms epoch) Tool-pool headers use a SEPARATE prefix: x-nous-tool-pool-micros tool-pool balance (micros) x-nous-tool-pool-gated-off "true" | "false" (STRING!) Money is handled as micros ints only; *_usd values are preserved verbatim as the raw strings the server sent (never re-parsed to float). ) annotationsN) dataclass)AnyMappingOptional)is_truthy_valueFbool_version_warning_emittedsubscription_capnonez^-?\d+\.\d{2}$valuerreturnc|tS tt|S#ttf$r tcYSwxYw)u;Parse a header value to an exact int (money-safe). The contract guarantees every ``*_micros`` field is an integer string — we parse with ``int()`` directly, NOT ``int(float(...))``, to avoid float- precision loss above 2**53 that would silently corrupt large money values. Returns the parsed int, or ``_SENTINEL`` if the value is not a valid integer string (including float-shaped strings like "1.5"). The sentinel lets callers detect the failure and return None from the overall parse (fail-hard-on-bad- input, not silently coerce). ) _SENTINELintstr TypeError ValueErrorr s :/home/ubuntu/.hermes/hermes-agent/agent/credits_tracker.py _safe_intr>sR }3u:: z "s'AA Optional[str]cX|dStt|S)zCReturn True iff value is a non-None string matching ^-?\d+\.\d{2}$.NF)r _USD_REmatchrs r _validate_usdrSs& }u  e$$ % %%cpeZdZUdZdZded<dZded<dZded<dZded <dZ ded <d Z d ed <d Z ded<dZ ded<dZ ded<dZded<dZded<dZded<dZded<dZded<d Zded<dZded<dZded<dZded <ed'd"Zed(d#Zed'd$Zed)d&Zd S)* CreditsStatezAFull credits state parsed from x-nous-credits-* response headers.rrversionremaining_microsr remaining_usdsubscription_microssubscription_usdN Optional[int]subscription_limit_microsrsubscription_limit_usdrollover_microspurchased_micros purchased_usdtool_pool_microsFr tool_pool_gated_offr denominator_kindT paid_accessdisabled_reasonas_of_msfloat captured_at from_headerrc|jdkSNr)r4selfs rhas_datazCreditsState.has_datats!##rcd|jstdStj|jz S)Ninf)r:r3timer4r8s r age_secondszCreditsState.age_secondsxs,} << y{{T---rc|j S)uTrue when the account has lost paid access. Keyed off ``paid_access == False`` ONLY — never ``remaining_micros == 0``, which would give a false positive whenever the balance is zero but access is still live (e.g. subscription renewal pending). )r/r8s rdepletedzCreditsState.depleted~s###rOptional[float]ct|jtsdS|jdkrdS|j|jz }t dt d||jz S)uFraction of the subscription cap consumed, in [0.0, 1.0]. Computable only when ``subscription_limit_micros`` is a truthy (non-zero, non-None) int. Guarded on the LIMIT FIELD, not ``denominator_kind`` — the limit field is the real denominator; ``denominator_kind`` is metadata. Returns None when there is no computable denominator (no limit, or limit==0). Nrr2?) isinstancer'rr$maxmin)r9useds r used_fractionzCreditsState.used_fractionsc$8#>> 4  )Q . .4-0HH3C(F!FGGHHHrrr )rr3)rrA)__name__ __module__ __qualname____doc__r __annotations__r!r#r$r%r'r(r)r*r+r,r-r.r/r0r1r4r5propertyr:r>r@rHrrrr]sKKGM     /33333,00000OM %%%%%"""""K%)O))))HKK $$$X$...X. $$$X$ I I IX I I Irrstickyi@))g?info2)g?warnK)g?rTZz"tuple[tuple[float, str, int], ...]CREDITS_USAGE_BANDSz credits.usagecdeZdZUdZded<dZded<dZded<dZd ed <dZd ed <dZ d ed <dS) AgentNoticeuA structured, driver-agnostic out-of-band notice. The agent fires these via ``AIAgent.notice_callback`` (and clears them via ``notice_clear_callback``); each driver renders it its own way — the TUI as a status-bar override, the CLI as a console line, etc. v1 credits notices are all ``kind="sticky"``; ``kind``/``ttl_ms`` are kept fully expressive so a future config/slash-command can switch them to TTL without touching the policy (a single default seam — see L4). rtextrRlevelrQkindNr&ttl_msrkeyid) rJrKrLrMrNr[r\r]r^r_rPrrrYrYs|IIIED F    CBrrYr"modelrbase_urlcL|sdS|drdS|sdS ddlm}m}|d}|dr|dd d}||}|sdS|||S#t $rYdSwxYw) uReturn True when *model* is a Nous free-tier model, using ONLY local data. Two signals, both zero-network: 1. The ``:free`` suffix — the canonical Nous free SKU marker (e.g. ``nvidia/nemotron-3-ultra:free``). Free by construction on the API side (spend is forced to 0 for ``:free`` ids). 2. A peek into the in-process pricing cache in ``hermes_cli.models`` (populated when the model picker fetched ``/v1/models`` pricing for *base_url*). PEEK ONLY — a cache miss never triggers a fetch. This is CLI/TUI-session best-effort: gateway sessions never run the picker's pricing fetch, so suppression there rests entirely on the ``:free`` suffix (which all Nous free SKUs carry). Fail-open to False (the depleted notice still shows) on any error: wrongly showing the warning is recoverable noise; wrongly hiding it on a paid model would mask a real billing block. Fz:freeTr)_is_model_free_pricing_cache/z/v1N)endswithhermes_cli.modelsrcrdrstripget Exception)r`rarcrdr^pricings ris_free_tier_modelrms& u ~~gt uDDDDDDDD ooc"" <<   'crc(//#&&C $$S)) 5~eW--- uusA&B B B#"B#) model_is_freestatelatchdictrn#tuple[list[AgentNotice], list[str]]c 6g}g}|j}tdd}| ||krd|d<|d}d}|tD]} || dkr| }|jdkrd}|jdko|duo|dko |jdk} |j } |d} |r|dr|d nd} | | krt |vr4|t |t | r|j pd }|d }|t|d krd ndd| d|d|tt t | t | |d<| rOd|vrK|td|j ddtdd| dn0d|vr,| s*|d|d| o| }|rFd|vrB|tddtdd| dn_d|vr[|sY|d|d| s-|tdddtdd||fS)uReconcile credits notices against the latch. Mutates ``latch`` IN PLACE. latch = {"active": set[str], "seen_below_90": bool, "usage_band": Optional[int]}. ``model_is_free``: True when the session's active model is a Nous free-tier model (see :func:`is_free_tier_model`). Suppresses the ``credits.depleted`` notice — a depleted account on a free model can keep inferencing, so the error banner is noise (and confuses free-tier users who never had credits). Suppression does NOT emit the "restored" success notice; that fires only on a genuine ``paid_access`` flip back to True. Returns ``(to_show: list[AgentNotice], to_clear: list[str])``. Caller emits to_clear FIRST, then to_show. Pure function — no I/O, no agent/run_agent imports. rNT seen_below_90activer rC usage_band?rTu⚠u•z Credits u % used · $z cap)rZr[r\r^r_zcredits.grant_spentu• Grant spent · $z top-up leftrRzcredits.depletedu2✕ Credit access paused · run /credits to top uperroru✓ Credit access restoredsuccessttlzcredits.restored)rZr[r\r]r^r_)rHrWr*r.r/rjCREDITS_USAGE_KEYappenddiscardr(rYCREDITS_NOTICE_KINDaddr+CREDITS_RESTORED_TTL_MS)rorprnto_showto_clearuf _lowest_bandru current_bandband grant_cond depleted_cond shown_band target_band_cap_usd_level show_depleteds revaluate_credits_noticesrs|,"$GH  B 'q)!,L ~"|++!%o 8_F6:L ~' $ $DT!W}}#  !!  "44 ' dN ' #I '  "Q &  ))M <((J&2Xu_7MX,q//TXKj   & & OO- . . . NN, - - -  "3:sH!!_F NN%+v%5%5EE5qq;qqckqqq ,)(     JJ( ) ) ))l .+699 ME,?MMM()(         ()))) & ( ( (-...,--- "7-&7M+699 I(&%         %&&&& v % %m %*+++)***  NN5#2*)     X rheadersMapping[str, str]providerOptional[CreditsState]c td|DsdSd|Dd}|dSt|}|turdS|dkr,|dkr$t sdat d|dSd7fd }d7fd }|d}|turdS|d}|turdS|d}|turdS|d} | turdSd} | d} n"t| } | tus| dkrdS| } |d} | turdSdd}t|sdSdd}t|sdSdd}t|sdSd}d}d}d}|9|7t|}|turdS|dkrdSt|sdS|}|}dd}|tvrdSdvr9d }|dvrdS|dk}nd}d vr9d  }|dvrdS|dk}nd!}d"}td8id#|d$|d%|d&|d'|d(|d)|d*|d+| d,|d-| d.|d/|d0|d1|d2| d3tj d4dS#t$r t d5d6YdSwxYw)9a-Parse x-nous-credits-* (and x-nous-tool-pool-*) headers into a CreditsState. Returns None (miss) on ANY of: - No ``x-nous-credits-version`` header present. - Version != 1 (> 1 also emits a one-time logger.warning). - Any ``*_micros`` field is non-integer, or negative for a non-subscription field. - Any ``*_usd`` field doesn't match ``^-?\d+\.\d{2}$``. - ``denominator_kind`` is not in {"subscription_cap", "none"}. - ``paid_access`` / ``tool_pool_gated_off`` is not exactly "true"/"false". - ``as_of_ms`` is not a valid integer. - Any unexpected exception. Fail-open on the subscription_limit pair: a half-pair (only -micros or only -usd present) is treated as both-absent; the overall parse STILL SUCCEEDS but with subscription_limit_micros/usd both None. c3FK|]}|dkVdS)x-nous-credits-versionNlower).0ks r z(parse_credits_headers..s0JJQ17799 88JJJJJJrNc>i|]\}}||SrPr)rrvs r z)parse_credits_headers..s&<<._req_nonnegsD++c""CC..Ci  Qww  Jrcp|}t|}|turtS|S)Nrrs r_req_intz'parse_credits_headers.._req_ints5++c""CC..Ci  Jrzx-nous-credits-remaining-microsz"x-nous-credits-subscription-microszx-nous-credits-rollover-microszx-nous-credits-purchased-microszx-nous-tool-pool-microsrzx-nous-credits-as-of-mszx-nous-credits-remaining-usdr"zx-nous-credits-subscription-usdzx-nous-credits-purchased-usdz(x-nous-credits-subscription-limit-microsz%x-nous-credits-subscription-limit-usdzx-nous-credits-denominator-kindr zx-nous-credits-paid-access)truefalserzx-nous-tool-pool-gated-offFzx-nous-credits-disabled-reasonr r!r#r$r%r'r(r)r*r+r,r-r.r/r0r1r4r5u9credits ▸ parse_credits_headers raised (fail-open miss)exc_info)r^rrrrP)anyitemsrjrrr loggerwarningr_VALID_DENOMINATOR_KINDSstriprrr=rkdebug)rr version_raw version_valrrr!r$r)r*_tp_rawr,_tp_valr1r#r%r+sub_limit_micros_rawsub_limit_usd_rawr'r(lmr.pa_rawr/tpgo_rawr-r0rs @rparse_credits_headersrs,g JJ'JJJJJ 4=%L:%%L: A L:L: L:1#L:4L: =L: A.L::&M$#M$iz30.34iz18.00i-1z20.00i Kz12.34T) r!r#r$r%r'r(r*r+r.r/iz10.00)r!r#r$r%r'r(r.r/i@KLz5.00iz2.000.00out_of_credits)r!r#r$r%r*r+r/r0iz-5.00) r!r#r$r%r'r(r*r+r.r/r0)healthy sub_50pct sub_75pct sub_90pctgrant_exhaustedr@debtzdict[str, dict] _DEV_FIXTURESctttjdsdStjdd}|sdS|}tjj|vsd|vrc t|dd5}|}dddn #1swxYwYn#t$rYdSwxYwt| }|sdSd d d |}tdi|d tj d S)ubReturn a fixture CreditsState for HERMES_DEV_CREDITS_FIXTURE, or None. The env value is a state name, OR a path to a file whose contents are a state name (re-read each call → flip states live without a restart). Unknown name / "clear" / "none" / unset → None (normal behaviour). Throwaway test scaffolding. Hard prod-leak guard: a fixture applies ONLY when the dev flag HERMES_DEV_CREDITS is also on, so a stray HERMES_DEV_CREDITS_FIXTURE (leaked into a shell profile, a container env, a launch plist, …) can never surface fabricated balances/notices on a real account. HERMES_DEV_CREDITSNHERMES_DEV_CREDITS_FIXTUREr"rerzutf-8)encodingryr)r r+T)r5r4rP)rosenvironrjrpathsepopenreadOSErrorrrrr=)rnamefhspecmergeds rdev_fixture_credits_staters| 2:>>*>?? @ @t *..5r : : @ @ B BC t D w{cSCZZ c3111 )Rwwyy(( ) ) ) ) ) ) ) ) ) ) ) ) ) ) )   44    TZZ\\ * *D t V < ._to_micross76@3PU,6W6W^3uWy011222]^ ^rcFt|ttfr|dndS)Nz.2fr")rDrr3rs r_to_usdz,_credits_state_from_account.._to_usds((2'C<'H'HPg###b Prmonthly_creditsrpaid_service_accesstotal_usable_creditssubscription_credits_remainingpurchased_credits_remainingrollover_creditsr r TF) r!r#r$r%r'r(r*r+r)r.r/r5r4u/credits ▸ seed account→state mapping failedr) getattrrDrr3rr r=rkrr)rR_acc_subrr_monthly_has_cap_paids r_credits_state_from_accountrs t7>>t^T22 _ _ _ Q Q Q 4!2D99he 55F(Q,3T::'Z6Ld(S(STT!''$0F"M"MNN * 749Y[_+`+` a a$WWT3SUY%Z%Z[[>F&Pjj&:&:&:D8@#J778#4#4#4d'Z6SUY(Z(Z[[!''$0Mt"T"TUU&Jwt5G'N'NOO3;G//!+E4!8!8Bd       FQU VVVttsE5E88&F"!F"Nonec ||_t|dd |j|_t|dd}t |t r |jd|d<t|dd}t|r |dSdS)uInstall a seed CreditsState on the agent and fire the notice policy once. Sets _credits_state, latches session-start remaining, and primes the crossing gate (the cold-start snapshot IS the first observation, so a session that opens already in a band warns immediately — the live header path keeps true crossing semantics), then emits. Safe to call from a worker thread: emit already runs off-thread in the TUI build path._credits_session_start_microsN_credits_latchTrt_emit_credits_notices)_credits_staterr!rrDrqrHcallable)agentro_latchemits r_hydrate_seed_staters!Eu5t<<D.3.D+ U,d 3 3F&$'E$7$C"& 514 8 8D~~ rc tdddkrdStdddSd} t}n#t$rd}YnwxYw|t|dSddl}dfd }||d d dS#t$r tddYdSwxYw)u}Hydrate agent._credits_state from /api/oauth/account (or a dev fixture) and fire the notice policy, so depletion / usage-band warnings show at session OPEN. Shared by (a) the TUI/desktop agent build (fires at "ready", before any message) and (b) the first-turn conversation setup (fallback for plain CLI / when the build path didn't seed). Idempotent: a second call is a no-op once a seed or a real header has already populated _credits_state. Returns True if it seeded this call, False otherwise (not nous / already seeded / fail-open error). Never raises — credits must never block session startup. rr"nousFrNTrrrc ddlm}|d}tdddSt|}|t |dSdS#t $r t ddYdSwxYw)Nr)get_nous_portal_account_infoT) force_freshru2credits ▸ session-start seed (background) failedr)hermes_cli.nous_accountrrrrrkrr)rrRrors r_bg_seedz/seed_credits_at_session_start.._bg_seeds bPPPPPP33EEE5"2D99EF3D99$'u55555%$ b b b Q\` aaaaaa bs#A !A &A76A7z credits-seed)targetrdaemonu1credits ▸ session-start seed failed (fail-open)rrr) rrrkr threadingThreadstartrr)rfixturerrs` rseed_credits_at_session_startrs0) 5*b ) )V 3 35 5*D 1 1 =5 /11GG   GGG    w / / /4  b b b b b b ~dKKQQSSSt   HSW XXXuu sABBB?B A B AB%4B&CC)r rrr)r rrr )r")r`rrarrr )rorrprqrnr rrr)rrrrrr)rrrrI)+rM __future__rloggingrrer= dataclassesrtypingrrrutilsr getLoggerrJrr rN frozensetrcompilerobjectrrrrrrrWr}rYrmrrrqrrrrrrPrrrs@#""""" !!!!!!))))))))))!!!!!!  8 $ $"'&&&&%9&8&%ABB "*& ' ' FHH *&&&& 8I8I8I8I8I8I8I 8I@; $   ,'''''b KKKKKKf}}}}}\t#7&",W#7+ #7&",W+  "&%",W+  "&%",W+  t#7",W#7+ &&+;  D&&",W&+(    O/"/" ////d!M!M!M!MH&&&&R&555555r