oq'j dZddlmZddlZddlZddlmZmZmZm Z ddgZ e dZ d d Z Gd dee Z dS)uShared concurrency helpers for plugin authors. The most common plugin footgun is the lazy process-wide singleton: _client = None def get_client(): global _client if _client is not None: return _client _client = ExpensiveClient(...) # <-- TOCTOU: two threads both run this return _client When two threads call ``get_client()`` before the singleton is set, both pass the ``is not None`` guard, both run the expensive initialization, and the second write clobbers the first — leaking whatever resource the first client opened (connections, file handles, background threads). Multi-threaded agent sessions share one process (delegated tool calls, background workers, the self-improvement fork), so this race is reachable in practice. Rather than make every plugin author remember to hand-roll double-checked locking, this module gives them two thread-safe primitives: * :func:`lazy_singleton` — decorator for the zero-arg accessor case. * :class:`SingletonSlot` — manual slot for accessors that build different instances depending on a config/key argument. Both are import-light (stdlib ``threading`` only) so any plugin can import them without dragging in heavyweight host modules. ) annotationsN)CallableGenericOptionalTypeVarlazy_singleton SingletonSlotTfactoryCallable[[], T]returnctjgtjdfd }dfd }||_|S)aWrap a zero-argument factory into a thread-safe lazy singleton accessor. The wrapped callable returns the same instance on every call; the factory runs exactly once even under concurrent first calls, using double-checked locking. A ``.reset()`` attribute is attached for tests/teardown. Example:: @lazy_singleton def get_client(): return ExpensiveClient(load_config()) client = get_client() # built once, safe across threads get_client.reset() # drop the instance (next call rebuilds) Note: if the factory raises, no instance is cached and the next call retries (the lock is released either way). r r crdS5rdcdddS}||cdddS#1swxYwYdS)Nr)append)instanceboxr locks 9/home/ubuntu/.hermes/hermes-agent/plugins/plugin_utils.pyaccessorz lazy_singleton..accessorAs  q6M    1v        wyyH JJx                    s A AAANonecf5ddddS#1swxYwYdS)N)clear)rrsrresetzlazy_singleton..resetLsz    IIKKK                  s &**)r r r r) threadingLock functoolswrapsr)r rrrrs` @@rrr+s& >  DC_WHN Oc6eZdZdZdZddZdd Zdd Zdd Zd S)r u)Thread-safe lazy slot for accessors that take a build argument. Use this when the cached instance depends on a config/key passed to the accessor (so a bare zero-arg :func:`lazy_singleton` doesn't fit). The slot caches the first successfully-built instance and ignores the argument on subsequent calls — matching the established "first config wins" singleton semantics most plugins already rely on. Example:: _slot: SingletonSlot[Honcho] = SingletonSlot() def get_honcho_client(config=None): return _slot.get(lambda: Honcho(**resolve(config))) def reset_honcho_client(): _slot.reset() The factory runs at most once even under concurrent first calls. If the factory raises, nothing is cached and the next call retries. _lock_value_setr rcRtj|_d|_d|_dS)NF)rrr"r#r$selfs r__init__zSingletonSlot.__init__ms#^%% #'  rr r r c|jr|jS|j5|jr|jcdddS|}||_d|_|cdddS#1swxYwYdS)NT)r$r#r")r'r values rgetzSingletonSlot.getrs 9 ;  Z  y #{        GIIEDKDI                   sAAAA Optional[T]c"|jr|jndS)z?Return the cached instance without building it (None if unset).N)r$r#r&s rpeekzSingletonSlot.peeks"i1t{{T1rcb|j5d|_d|_ddddS#1swxYwYdS)z;Drop the cached instance so the next ``get()`` rebuilds it.NFr!r&s rrzSingletonSlot.resets| Z  DKDI                  s $((Nr)r r r r )r r,) __name__ __module__ __qualname____doc__ __slots__r(r+r.rrrr r Tsu,,I    2222r)r r r r )r3 __future__rrrtypingrrrr__all__r rr r5rrr9s>#"""""777777777777 _ - GCLL&&&&R33333GAJ33333r