capt-hook 0.2.0__py3-none-any.whl

captain_hook/session.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import tempfile
+from collections.abc import Sequence
+from hashlib import sha256
+from pathlib import Path
+from typing import ClassVar, Generic, TypeVar, overload
+
+from loguru import logger
+from pydantic import BaseModel
+
+M = TypeVar("M", bound=BaseModel)
+
+
+def state_root() -> Path:
+    from captain_hook.settings import resolve_state_dir
+
+    return resolve_state_dir()
+
+
+def session_hash(transcript_path: str | Path) -> str:
+    return sha256(str(transcript_path).encode()).hexdigest()[:12]
+
+
+def ensure_session(transcript_path: str | Path) -> Path:
+    sd = state_root() / "hooks" / "sessions" / session_hash(transcript_path)
+    sd.mkdir(parents=True, exist_ok=True)
+    marker = sd / ".transcript_path"
+    if not marker.exists():
+        marker.write_text(str(transcript_path))
+    return sd
+
+
+def cleanup_stale() -> None:
+    sessions = state_root() / "hooks" / "sessions"
+    if not sessions.exists():
+        return
+    for sd in sessions.iterdir():
+        if not sd.is_dir():
+            continue
+        marker = sd / ".transcript_path"
+        if marker.exists() and not Path(marker.read_text().strip()).exists():
+            shutil.rmtree(sd, ignore_errors=True)
+
+
+class SessionSlot(Generic[M]):  # noqa: UP046
+    """A typed slot for reading/writing a single Pydantic model in a session directory."""
+
+    def __init__(self, session_dir: Path | None, model: type[M]) -> None:
+        self._model = model
+        self._path = (session_dir / f"{self.model_key(model)}.json") if session_dir else None
+
+    @staticmethod
+    def model_key(model: type[BaseModel]) -> str:
+        return re.sub(r"(?<!^)(?=[A-Z])", "_", model.__name__).lower()
+
+    @property
+    def path(self) -> Path | None:
+        return self._path
+
+    @overload
+    def get(self) -> M | None: ...
+    @overload
+    def get(self, default: M) -> M: ...
+    def get(self, default: M | None = None) -> M | None:
+        if not self._path or not self._path.exists():
+            return default
+        try:
+            return self._model.model_validate_json(self._path.read_text())
+        except Exception:
+            logger.bind(model=self._model.__name__, path=str(self._path)).opt(exception=True).warning(
+                "failed to read session state",
+            )
+            return default
+
+    def set(self, obj: M) -> None:
+        if not self._path:
+            return
+        try:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            tmp_fd, tmp_name = tempfile.mkstemp(
+                dir=self._path.parent,
+                suffix=".tmp",
+            )
+            try:
+                os.write(tmp_fd, obj.model_dump_json().encode())
+                os.close(tmp_fd)
+                os.replace(tmp_name, self._path)
+            except BaseException:
+                os.close(tmp_fd) if not os.get_inheritable(tmp_fd) else None
+                Path(tmp_name).unlink(missing_ok=True)
+                raise
+        except OSError:
+            logger.bind(path=str(self._path)).opt(exception=True).warning("failed to persist session state")
+
+    def delete(self) -> None:
+        if self._path:
+            self._path.unlink(missing_ok=True)
+
+
+class SessionStore:
+    """Class-keyed store providing typed ``SessionSlot`` access via ``store[ModelClass]``."""
+
+    TRACKED: ClassVar[list[type[BaseModel]]] = []
+
+    def __init__(self, session_dir: Path | None) -> None:
+        self._dir = session_dir
+
+    def __getitem__(self, model: type[M]) -> SessionSlot[M]:
+        return SessionSlot(self._dir, model)
+
+    def load(self, model: type[M]) -> M:
+        """Read ``model`` from its session slot, defaulting to a fresh ``model()``.
+
+        Args:
+            model: The Pydantic model class to read.
+
+        Returns:
+            The persisted instance, or a newly constructed ``model()`` when no
+            stored state exists for this session.
+        """
+        return self[model].get(model())
+
+    @classmethod
+    def track(cls, model: type[BaseModel]) -> None:
+        """Register ``model`` so it appears in ``tracked_models()`` and ``tracked_paths()``."""
+        if model not in cls.TRACKED:
+            cls.TRACKED.append(model)
+
+    @classmethod
+    def untrack(cls, model: type[BaseModel]) -> None:
+        """Reverse ``track`` — primarily for test isolation."""
+        if model in cls.TRACKED:
+            cls.TRACKED.remove(model)
+
+    @classmethod
+    def tracked_models(cls) -> Sequence[type[BaseModel]]:
+        """Return the registered tracked-state models as an immutable tuple."""
+        return tuple(cls.TRACKED)
+
+    def tracked_paths(self) -> dict[str, Path]:
+        """Return ``{ModelClass.__name__: Path}`` for every tracked model whose slot has a path."""
+        return {m.__name__: p for m in type(self).TRACKED if (p := self[m].path)}
+
+
+def session_state[T: BaseModel](cls: type[T]) -> type[T]:
+    """Decorator that registers a Pydantic model for collective ``SessionStore`` introspection.
+
+    Example:
+        >>> @session_state
+        ... class Snapshot(BaseModel):
+        ...     op_id: str
+    """
+    SessionStore.track(cls)
+    return cls

captain_hook/settings.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import os
+import types
+from pathlib import Path
+from typing import Any, get_type_hints
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+INFERRABLE_PRIMITIVES = (str, int, float, bool)
+
+DEFAULT_PLANNING_AGENTS = [
+    "Explore",
+    "Plan",
+    "general-purpose",
+    "explore",
+    "plan",
+    "web-analyzer",
+    "search-specialist",
+    "claude-code-guide",
+    "context-manager",
+    "sentry-error-debugger",
+    "logfire-trace-debugger",
+    "sentry:issue-summarizer",
+]
+
+DEFAULT_WAITING_TOOLS = [
+    "Monitor",
+    "TeamCreate",
+    "ScheduleWakeup",
+    "SendMessage",
+]
+
+DEFAULT_STATE_DIR = Path.home() / ".claude" / "state"
+DEFAULT_LOG_DIR = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "captain-hook" / "logs"
+
+
+def resolve_state_dir() -> Path:
+    return Path(os.environ.get("CAPTAIN_HOOK_STATE_DIR") or os.environ.get("CLAUDE_HOOKS_STATE_DIR") or DEFAULT_STATE_DIR)
+
+
+def resolve_log_dir() -> Path:
+    return Path(os.environ.get("CAPTAIN_HOOK_LOG_DIR") or DEFAULT_LOG_DIR)
+
+
+class HooksSettings(BaseSettings):
+    """Base settings class for hook configuration, backed by environment variables with ``HOOKS_`` prefix."""
+
+    model_config = SettingsConfigDict(env_prefix="HOOKS_")
+
+    planning_agents: list[str] = Field(default_factory=lambda: list(DEFAULT_PLANNING_AGENTS))
+    waiting_tools: list[str] = Field(default_factory=lambda: list(DEFAULT_WAITING_TOOLS))
+    state_dir: Path = Field(default_factory=resolve_state_dir)
+    log_dir: Path = Field(default_factory=resolve_log_dir)
+
+
+class AutoConf:
+    """Automatic settings builder that infers a ``HooksSettings`` subclass from a conf module's attributes."""
+
+    @staticmethod
+    def should_skip(name: str, val: Any) -> bool:
+        return name.startswith("_") or name.isupper() or callable(val) or isinstance(val, types.ModuleType)
+
+    @staticmethod
+    def find_settings_class(module: types.ModuleType) -> type[HooksSettings] | None:
+        for val in vars(module).values():
+            if isinstance(val, type) and issubclass(val, HooksSettings) and val is not HooksSettings:
+                return val
+        return None
+
+    @staticmethod
+    def build_settings(module: types.ModuleType, prefix: str = "HOOKS_") -> BaseSettings:
+        if settings_cls := AutoConf.find_settings_class(module):
+            return settings_cls()
+
+        try:
+            hints = get_type_hints(module)
+        except Exception:
+            hints = {}
+
+        candidates = sorted(
+            set(hints.keys()) | {k for k in vars(module) if not AutoConf.should_skip(k, getattr(module, k))}
+        )
+
+        fields: dict[str, tuple[type, Any]] = {}
+        for name in candidates:
+            val = getattr(module, name, None)
+            if AutoConf.should_skip(name, val):
+                continue
+            if val is None or isinstance(val, (dict, set)):
+                continue
+            match name in hints, isinstance(val, list):
+                case True, True:
+                    fields[name] = (hints[name], Field(default_factory=lambda v=val: list(v)))
+                case True, False:
+                    fields[name] = (hints[name], Field(default=val))
+                case False, True:
+                    fields[name] = (list, Field(default_factory=lambda v=val: list(v)))
+                case False, _ if isinstance(val, tuple):
+                    fields[name] = (tuple, Field(default_factory=lambda v=val: tuple(v)))
+                case False, _ if isinstance(val, INFERRABLE_PRIMITIVES):
+                    fields[name] = (type(val), Field(default=val))
+                case _:
+                    pass
+
+        return type(
+            "AutoSettings",
+            (HooksSettings,),
+            {
+                "__annotations__": {k: t for k, (t, _) in fields.items()},
+                "model_config": SettingsConfigDict(env_prefix=prefix),
+                **{k: fd for k, (_, fd) in fields.items()},
+            },
+        )()
+
+
+def build_settings(module: types.ModuleType, prefix: str = "HOOKS_") -> BaseSettings:
+    """Build a settings instance from a conf module, using an explicit ``HooksSettings`` subclass or auto-inferring fields."""
+    return AutoConf.build_settings(module, prefix)

captain_hook/signals/__init__.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from captain_hook.signals.nlp import NlpSignal
+from captain_hook.types import Event, Signal, Signals
+
+if TYPE_CHECKING:
+    from captain_hook.events import BaseHookEvent
+
+TSignalPattern = Signal | NlpSignal
+
+
+def score_signals(patterns: Sequence[TSignalPattern], text: str) -> int:
+    from captain_hook.signals.nlp import nlp_scan
+
+    total = 0
+    for s in patterns:
+        match s:
+            case NlpSignal(clauses=clauses) if nlp_scan(clauses, text):
+                total += s.weight
+            case Signal() if re.search(s.pattern, text, s.flags):
+                total += s.weight
+            case _:
+                pass
+    return total
+
+
+def extract_signal_context(patterns: Sequence[TSignalPattern], text: str) -> list[str]:
+    from captain_hook.signals.nlp import nlp_scan
+
+    result: list[str] = []
+    for s in patterns:
+        match s:
+            case NlpSignal(clauses=clauses):
+                result.extend(nlp_scan(clauses, text))
+            case Signal():
+                result.extend(line for line in text.splitlines() if re.search(s.pattern, line, s.flags))
+    return result
+
+
+def transcript_texts(evt: BaseHookEvent, window: int) -> list[str]:
+    """Extract text from recent transcript messages for signal scoring.
+
+    For ``UserPromptSubmit`` events, returns just the user prompt.
+    Otherwise returns ``.text`` from the last ``window`` messages.
+    """
+    return (
+        [evt.user_prompt]
+        if evt.event == Event.UserPromptSubmit and evt.user_prompt
+        else [msg.text for msg in evt.ctx.t.recent(window).messages if msg.text]
+    )
+
+
+def cite_message(sig: Signals, triggering: list[str], message: str) -> str:
+    """Append trigger context to a message when signal matches are found."""
+    return (
+        f"{message}\n\nTriggered by: {'; '.join(context)}"
+        if (context := extract_signal_context(sig.patterns, "\n".join(triggering)))
+        else message
+    )
+
+
+def resolve_signals(signals: Sequence[Signal | NlpSignal] | Signals | None) -> Signals | None:
+    """Normalize signals input into a ``Signals`` bundle, or None.
+
+    A bare ``list[Signal]`` is wrapped with ``threshold=1`` (any single match triggers).
+    """
+    if signals is None:
+        return None
+    if isinstance(signals, Signals):
+        return signals
+    return Signals(patterns=list(signals), threshold=1)
+
+
+__all__ = [
+    "Signal",
+    "Signals",
+    "cite_message",
+    "extract_signal_context",
+    "resolve_signals",
+    "score_signals",
+    "transcript_texts",
+]

captain_hook/signals/nlp.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import functools
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from spacy.tokens import Doc, Span, Token
+
+__all__ = ["Clause", "NlpSignal", "Phrase", "dep_related", "nlp_scan"]
+
+
+@dataclass(frozen=True, slots=True, init=False)
+class Phrase:
+    lemmas: tuple[str, ...]
+
+    def __init__(self, *terms: str) -> None:
+        object.__setattr__(self, "lemmas", tuple(t.lower() for t in terms))
+
+    @classmethod
+    def expand(cls, *terms: str, pos: str = "n") -> Phrase:
+        from captain_hook.state import RESOURCES
+
+        return cls(
+            *{
+                lemma.replace("_", " ")
+                for term in terms
+                for ss in RESOURCES.wn.synsets(term, pos=pos)
+                for lemma in ss.lemmas()
+            }
+            | {t.lower() for t in terms}
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Clause:
+    noun: Phrase
+    verb: Phrase | None = None
+    adj: Phrase | None = None
+    negated: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.verb and not self.adj and not self.negated and not any(" " in lemma for lemma in self.noun.lemmas):
+            raise ValueError("Clause needs verb, adj, negated, or a compound noun phrase")
+
+
+@dataclass(frozen=True, kw_only=True)
+class NlpSignal:
+    clauses: Sequence[Clause]
+    weight: int = 1
+
+
+@functools.lru_cache
+def parse(text: str) -> Doc:
+    from captain_hook.state import RESOURCES
+
+    return RESOURCES.spacy(text)
+
+
+def ancestors(tok: Token, max_hops: int) -> set[Token]:
+    result = {tok}
+    node = tok
+    for _ in range(max_hops):
+        if node == node.head:
+            break
+        result.add(node := node.head)
+    return result
+
+
+def dep_related(a: Token, b: Token, max_hops: int = 3) -> bool:
+    return bool(ancestors(a, max_hops) & ancestors(b, max_hops))
+
+
+def find_lemma_matches(phrase: Phrase, sent: Span, pos: set[str]) -> list[Token]:
+    return [
+        tok
+        for lemma in phrase.lemmas
+        if (parts := lemma.split())
+        for tok in sent
+        if tok.pos_ in pos
+        and tok.lemma_.lower() == parts[-1]
+        and (
+            len(parts) == 1
+            or all(m in {c.lemma_.lower() for c in tok.children if c.dep_ == "compound"} for m in parts[:-1])
+        )
+    ]
+
+
+def match_clause(clause: Clause, sent: Span) -> bool:
+    return any(
+        (not clause.verb or any(dep_related(nt, v) for v in find_lemma_matches(clause.verb, sent, {"VERB"})))
+        and (
+            not clause.adj
+            or any(dep_related(nt, a) for a in find_lemma_matches(clause.adj, sent, {"ADJ", "ADV", "PART"}))
+        )
+        and (not clause.negated or any(t.dep_ == "neg" and dep_related(nt, t) for t in sent))
+        for nt in find_lemma_matches(clause.noun, sent, {"NOUN", "PROPN"})
+    )
+
+
+def nlp_scan(clauses: Sequence[Clause], text: str) -> list[str]:
+    if not text.strip():
+        return []
+    return [sent.text.strip() for sent in parse(text).sents if any(match_clause(clause, sent) for clause in clauses)]

captain_hook/state.py

@@ -0,0 +1,221 @@
+"""Hook fire-count and primitive echo-suppression state, plus shared NLP resources (spaCy, WordNet)."""
+from __future__ import annotations
+
+import inspect
+import os
+import re
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from functools import cached_property
+from hashlib import sha256
+from pathlib import Path
+from typing import TYPE_CHECKING, TypeVar
+
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+    from types import FrameType, ModuleType
+
+    import spacy
+
+    from captain_hook.events import BaseHookEvent
+    from captain_hook.types import Signals
+
+FRAMEWORK_DIR = str(Path(__file__).resolve().parent)
+CACHE_ROOT = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "captain-hook"
+SPACY_MODEL = "en_core_web_sm"
+
+
+class NlpResources:
+    @cached_property
+    def spacy(self) -> spacy.language.Language:
+        import spacy
+
+        from captain_hook.util.model_cache import cached_pipeline
+
+        if spacy.util.is_package(SPACY_MODEL):
+            return spacy.load(SPACY_MODEL)
+        # We refuse to auto-download from a live hook: it's a ~100MB silent fetch behind
+        # the agent's back. If a previous run / explicit install already populated the
+        # cache, use that; otherwise, raise with an actionable install hint.
+        if cached := cached_pipeline():
+            return spacy.load(cached)
+        raise RuntimeError(
+            f"spaCy model {SPACY_MODEL!r} is not installed. "
+            f"Install it explicitly before running hooks that use NLP signals: "
+            f"`python -m spacy download {SPACY_MODEL}` "
+            f"or `python -c \"from captain_hook.util.model_cache import ensure_spacy_model; ensure_spacy_model()\"`."
+        )
+
+    @cached_property
+    def wn(self) -> ModuleType:
+        import wn
+
+        if not wn.lexicons(lexicon="oewn:2025"):
+            wn.download("oewn:2025", progress_handler=None)
+        return wn
+
+
+RESOURCES = NlpResources()
+
+
+class HookState(BaseModel):
+    """Per-hook persistent state tracked across events in a session (currently just ``fire_count`` for ``max_fires``)."""
+
+    fire_count: int = 0
+
+
+# ECHO_WINDOW: number of subsequent transcript messages after a nudge fires during which we
+# suppress restating the same idea. Tuned for "the agent reads our nudge and the next ~5
+# assistant messages reference the same concept".
+# ECHO_THRESHOLD: fraction of content lemmas in a candidate text that must overlap with the
+# nudge's lemmas to count as an echo. 0.4 = "if 40%+ of the meaningful words match, the
+# agent is parroting".
+# ECHO_MIN_OVERLAP: absolute minimum overlap to count, so short messages don't pass the
+# fractional threshold trivially (e.g. a 2-token message would otherwise hit 0.5).
+ECHO_WINDOW = 5
+ECHO_THRESHOLD = 0.4
+ECHO_MIN_OVERLAP = 2
+
+
+class PrimitiveState(BaseModel):
+    """Per-primitive state for nudges/gates: last fire index, consumed-signal hashes, and echo-window lemmas."""
+
+    last_fired_at: int = 0
+    consumed: set[str] = Field(default_factory=set)
+    echo_lemmas: set[str] = Field(default_factory=set)
+    echo_window_end: int = 0
+
+    @staticmethod
+    def content_lemmas(text: str) -> set[str]:
+        return {
+            tok.lemma_.lower()
+            for tok in RESOURCES.spacy(text)
+            if tok.pos_ in {"NOUN", "VERB", "ADJ"} and not tok.is_stop and len(tok.lemma_) > 2
+        }
+
+    def is_echo(self, text: str) -> bool:
+        return bool(
+            self.echo_lemmas
+            and (text_lemmas := self.content_lemmas(text))
+            and len(overlap := text_lemmas & self.echo_lemmas) >= ECHO_MIN_OVERLAP
+            and len(overlap) / len(text_lemmas) >= ECHO_THRESHOLD
+        )
+
+    def consume_echoes(self, texts: list[str], transcript_len: int) -> None:
+        if not self.echo_lemmas or transcript_len >= self.echo_window_end:
+            return
+
+        for text in texts:
+            if (h := text_hash(text)) not in self.consumed and self.is_echo(text):
+                self.consumed.add(h)
+
+    def seed_echo_window(self, triggering_texts: list[str], message: str, transcript_len: int) -> None:
+        self.echo_lemmas = self.content_lemmas(" ".join(triggering_texts)) | self.content_lemmas(message)
+        self.echo_window_end = transcript_len + ECHO_WINDOW
+
+    def match_signals(self, sig: Signals, texts: list[str]) -> list[str] | None:
+        from captain_hook.signals import score_signals
+
+        contributing_hashes = [
+            h
+            for text in texts
+            if (h := text_hash(text)) not in self.consumed and score_signals(sig.patterns, text) >= sig.threshold
+        ]
+        if not contributing_hashes:
+            return None
+        self.consumed.update(contributing_hashes)
+        return [t for t in texts if text_hash(t) in set(contributing_hashes)]
+
+
+def text_hash(text: str) -> str:
+    return sha256(text.encode()).hexdigest()[:16]
+
+
+def package_aware_stem(p: Path) -> str:
+    if (
+        p.name != "__init__.py"
+        and not str(p).startswith(FRAMEWORK_DIR)
+        and (init := p.parent / "__init__.py").exists()
+        and init.stat().st_size > 0
+    ):
+        return f"{p.parent.name}.{p.stem}"
+    return p.stem
+
+
+def caller_stem() -> str:
+    frame: FrameType | None = inspect.currentframe()
+    if frame:
+        frame = frame.f_back
+    while frame and frame.f_code.co_filename.startswith(FRAMEWORK_DIR):
+        frame = frame.f_back
+    return package_aware_stem(Path(frame.f_code.co_filename)) if frame else "unknown"
+
+
+def hook_name(prefix: str, label: str | None, message: str) -> str:
+    suffix = re.sub(r"[^a-z0-9]+", "_", label.lower()).strip("_") if label else sha256(message.encode()).hexdigest()[:8]
+    return f"{caller_stem()}:{prefix}_{suffix}"
+
+
+def record_fire(evt: BaseHookEvent) -> None:
+    ps = evt.ctx.s[PrimitiveState].get(PrimitiveState())
+    ps.last_fired_at = len(evt.ctx.t)
+    evt.ctx.s[PrimitiveState].set(ps)
+
+
+def fired_this_turn(evt: BaseHookEvent) -> bool:
+    return (ps := evt.ctx.s[PrimitiveState].get()) is not None and ps.last_fired_at > evt.ctx.turn.start_idx
+
+
+from captain_hook.session import SessionStore  # noqa: E402
+
+
+@dataclass
+class EchoTracker:
+    window: int = ECHO_WINDOW
+    threshold: float = ECHO_THRESHOLD
+    min_overlap: int = ECHO_MIN_OVERLAP
+
+    def saw(self, text: str, *, evt: BaseHookEvent) -> bool:
+        ps = evt.ctx.s[PrimitiveState].get()
+        return (
+            ps is not None
+            and bool(ps.echo_lemmas)
+            and len(evt.ctx.t) < ps.echo_window_end
+            and ps.is_echo(text)
+        )
+
+    def record(self, text: str, triggering: Iterable[str], *, evt: BaseHookEvent) -> None:
+        ps = evt.ctx.s[PrimitiveState].get(PrimitiveState())
+        ps.echo_lemmas = PrimitiveState.content_lemmas(" ".join(triggering)) | PrimitiveState.content_lemmas(text)
+        ps.echo_window_end = len(evt.ctx.t) + self.window
+        evt.ctx.s[PrimitiveState].set(ps)
+
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def workflow_state(name: str) -> Callable[[type[T]], type[T]]:
+    def wrap(cls: type[T]) -> type[T]:
+        cls.__workflow_name__ = name  # type: ignore[attr-defined]
+        SessionStore.track(cls)
+
+        def load(inner_cls: type[T], evt: BaseHookEvent) -> T:
+            return evt.ctx.s.load(inner_cls)
+
+        def save(self: T, evt: BaseHookEvent) -> None:
+            evt.ctx.s[type(self)].set(self)
+
+        def reset(inner_cls: type[T], evt: BaseHookEvent) -> None:
+            evt.ctx.s[inner_cls].delete()
+
+        cls.load = classmethod(load)  # type: ignore[attr-defined]
+        cls.save = save  # type: ignore[attr-defined]
+        cls.reset = classmethod(reset)  # type: ignore[attr-defined]
+        return cls
+
+    return wrap
+
+
+SessionStore.track(HookState)
+SessionStore.track(PrimitiveState)