`gj xdZddlmZddlZddlZddlmZmZmZm Z ddgZ e dZ d dZ Gd dee Z y) 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 SingletonSlotTctjgtjdfd }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). crdS5rdcdddS}j||cdddS#1swYyxYw)Nr)append)instanceboxfactorylocks G/root/.hermes/venv/lib/python3.12/site-packages/plugins/plugin_utils.pyaccessorz lazy_singleton..accessorAsS q6M  1v  yH JJx     s ??AcT5jdddy#1swYyxYw)N)clear)rrsrresetzlazy_singleton..resetLs$   IIK   s')returnr rNone) threadingLock functoolswrapsr)rrrrrs` @@rrr+sD& >> DC__WHN Oc4eZdZdZdZddZd dZd dZddZy) 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_setcRtj|_d|_d|_y)NF)rrr!r"r#selfs r__init__zSingletonSlot.__init__ms^^% #'  rc|jr |jS|j5|jr|jcdddS|}||_d|_|cdddS#1swYyxYw)NT)r#r"r!)r&rvalues rgetzSingletonSlot.getrsc 99;;  ZZ yy{{  IEDKDI    sA'A''A0c6|jr |jSdS)z?Return the cached instance without building it (None if unset).N)r#r"r%s rpeekzSingletonSlot.peeks"iit{{1T1rcb|j5d|_d|_dddy#1swYyxYw)z;Drop the cached instance so the next ``get()`` rebuilds it.NFr r%s rrzSingletonSlot.resets, ZZ DKDI   s%.Nr)rCallable[[], T]rr )rz Optional[T]) __name__ __module__ __qualname____doc__ __slots__r'r*r,rrrr r Ts",,I 2r)rr.rr.)r2 __future__rrrtypingrrrr__all__r rr r4rrr8sD>#77 _ - CL&R3GAJ3r