handcode 0.3.0rc1__py3-none-any.whl

agentctl/kernel/gate.py

@@ -0,0 +1,391 @@
+"""The effect gate. Spec: `docs/0011` §3, `docs/0012` §3.2.
+
+The correctness core, and deliberately small. One rule dominates:
+
+    guard() MUST NEVER RAISE.
+
+Any internal failure becomes BLOCK — fail closed (`docs/0008` §6.5). A gate
+that crashes open is worse than no gate, because it creates false confidence.
+"""
+from __future__ import annotations
+
+import json
+import logging
+
+from .classify import Classifier
+from .reconcile.base import (
+    DID_NOT_LAND, INCONCLUSIVE, LANDED, SAFE_TO_RETRY, ProbeRegistry,
+)
+from .ledger.models import (
+    EffectClass,
+    EffectState,
+    GateDecision,
+    ToolCall,
+    Verdict,
+)
+from .ledger.store import LedgerStore, StaleFence
+
+log = logging.getLogger("agentctl.gate")
+
+
+class EffectGate:
+    """Decides whether a tool call may execute.
+
+    Seam-agnostic by design (`docs/0012` §3.2.1): it returns a decision, and
+    the binding acts on it. Seam B can honour BLOCK/ESCALATE; only Seam C can
+    honour SUBSTITUTE.
+    """
+
+    def __init__(
+        self,
+        store: LedgerStore,
+        classifier: Classifier | None = None,
+        probes: ProbeRegistry | None = None,
+        fence: int = 0,
+    ):
+        self.store = store
+        self.classifier = classifier or Classifier()
+        self.probes = probes if probes is not None else ProbeRegistry()
+        self.fence = fence
+
+    # ── the decision ───────────────────────────────────────────────────
+    def guard(self, call: ToolCall) -> GateDecision:
+        try:
+            return self._guard(call)
+        except StaleFence as exc:
+            # Not a bug in the gate: another process took this conversation
+            # over (`docs/0046`). Said as such, rather than as "gate error,
+            # failing closed: StaleFence(...)" -- accurate, and meaningless to
+            # the person reading it (`docs/0048`).
+            log.warning("superseded: %s", exc)
+            return GateDecision(
+                Verdict.BLOCK,
+                reason="another process has taken over this conversation, so "
+                       "this run may not start new actions; let the other "
+                       "run finish, or stop this one")
+        except Exception as exc:                       # noqa: BLE001
+            # Fail closed. Never let a gate bug become an unguarded effect.
+            log.exception("gate failure for %s", call.tool_call_id)
+            self._try_block(call.tool_call_id, f"gate error: {exc!r}")
+            return GateDecision(
+                Verdict.BLOCK, reason=f"gate error, failing closed: {exc!r}"
+            )
+
+    def _guard(self, call: ToolCall) -> GateDecision:
+        cls = self.classifier.classify(call)
+        rec = self.store.lookup(call.tool_call_id)
+
+        if rec is None and not cls.replay_safe:
+            # The id is model-minted, so a different model answering the same
+            # question produces a different one for the identical call
+            # (`docs/0023` §4). Before calling this a first sighting, ask
+            # whether this exact effect is already on record under another id.
+            twin = self.store.find_by_intent(call.conversation_id,
+                                             call.intent_hash())
+            if twin is not None:
+                log.info("matched %s to prior effect %s by intent hash",
+                         call.tool_call_id, twin.tool_call_id)
+                return self._decide_on(call, twin, cls, aliased=True)
+
+        # First sighting — the common case.
+        if rec is None:
+            self.store.write_intent(call, cls, self.fence, self._capture(call, cls))
+            return GateDecision(Verdict.EXECUTE, cls)
+
+        # Same id, different arguments. Substituting here would return the
+        # wrong observation, so refuse outright.
+        if rec.intent_hash != call.intent_hash():
+            return GateDecision(
+                Verdict.BLOCK, cls,
+                reason="tool_call_id reused with different arguments",
+            )
+        return self._decide_on(call, rec, cls)
+
+    def _decide_on(self, call: ToolCall, rec, cls: EffectClass,
+                   aliased: bool = False) -> GateDecision:
+        """Decide against a record, which may be under a different id."""
+        note = (f" (matched to {rec.tool_call_id} by intent hash)"
+                if aliased else "")
+
+        # OBSERVED reaches here only by its own id: the SDK re-driving the very
+        # action whose result it persisted. `find_by_intent` never aliases to
+        # one, because a re-minted twin of an observed call is the model's
+        # decision to repeat (`docs/0045`).
+        if rec.state in (EffectState.COMMITTED, EffectState.OBSERVED):
+            return GateDecision(Verdict.SUBSTITUTE, cls,
+                                observation=rec.observation,
+                                reason=f"already recorded{note}" if note else None,
+                                record_id=rec.tool_call_id)
+
+        if rec.state is EffectState.FAILED:
+            # Re-capture: the world may have moved since the failed attempt.
+            self.store.write_intent(call, cls, self.fence, self._capture(call, cls))
+            return GateDecision(Verdict.EXECUTE, cls)
+
+        if rec.state is EffectState.BLOCKED:
+            return GateDecision(
+                Verdict.BLOCK, cls,
+                reason=(rec.error or "previously blocked; awaiting human decision")
+                + note,
+            )
+
+        # rec.state is INTENT — the irreducible ambiguity (docs/0008 §6.5).
+        return self._resolve_ambiguous(call, rec, cls)
+
+    def _resolve_ambiguous(self, call, rec, cls: EffectClass) -> GateDecision:
+        """We cannot tell whether the effect landed. Decide by class.
+
+        Every ledger write here targets `rec.tool_call_id`, never
+        `call.tool_call_id`. Under intent-hash aliasing those differ, and
+        writing to the caller's id raises `IllegalTransition` -- which the
+        fail-closed wrapper then turns into a BLOCK, producing a correct
+        outcome by an incorrect route and stranding the record (`docs/0024`).
+        """
+        rid = rec.tool_call_id
+
+        if cls.replay_safe:
+            # Repeating is harmless, so the window does not matter.
+            return GateDecision(Verdict.EXECUTE, cls)
+
+        if cls is EffectClass.DESTRUCTIVE:
+            self.store.block(rid, "destructive effect, outcome unknown")
+            return GateDecision(
+                Verdict.ESCALATE, cls,
+                reason="destructive effect with unknown outcome; a human must decide",
+            )
+
+        # NON_IDEMPOTENT_WRITE / EXTERNAL: ask the world if it can answer.
+        probe = self.probes.for_call(call, self.classifier.probe_for(call))
+        verdict = INCONCLUSIVE
+        if probe is not None:
+            try:
+                verdict = probe.probe(call, rec)
+            except Exception:                           # noqa: BLE001
+                log.exception("probe %s raised", getattr(probe, "name", "?"))
+                verdict = INCONCLUSIVE
+
+            if verdict == LANDED and not self._sole_writer(rec):
+                # The probe reasoned from world state, but this call was not
+                # the only thing writing to that world. The change it saw may
+                # be a sibling's (`docs/0038` §3). Downgrade rather than
+                # attribute: a dropped effect recorded as COMMITTED is the one
+                # outcome this system exists to prevent.
+                log.warning("%s probe said LANDED, but a sibling effect "
+                            "committed inside the window; not attributing", probe.name)
+                verdict = INCONCLUSIVE
+
+            if verdict == LANDED:
+                self.store.reconcile(rid, verdict, landed=True)
+                return GateDecision(
+                    Verdict.SUBSTITUTE, cls, observation=rec.observation,
+                    reason=f"{probe.name} probe: the effect already landed",
+                    record_id=rid,
+                )
+            if verdict == DID_NOT_LAND:
+                self.store.reconcile(rid, verdict, landed=False)
+                self.store.write_intent(call, cls, self.fence,
+                                        self._capture(call, cls))
+                return GateDecision(
+                    Verdict.EXECUTE, cls,
+                    reason=f"{probe.name} probe: the effect did not land",
+                )
+            if verdict == SAFE_TO_RETRY:
+                # We cannot tell whether it landed, and we do not need to: the
+                # call carries an idempotency key, so the remote collapses a
+                # retry into the original effect (`docs/0020`).
+                self.store.reconcile(rid, verdict, landed=False)
+                self.store.write_intent(call, cls, self.fence,
+                                        self._capture(call, cls))
+                return GateDecision(
+                    Verdict.EXECUTE, cls,
+                    reason=(f"{probe.name} probe: outcome unknown, but the call "
+                            f"is idempotency-keyed so a retry is safe"),
+                )
+
+        # No probe, or inconclusive. Fail closed.
+        detail = ("no probe available" if probe is None
+                  else f"{probe.name} probe inconclusive")
+        reason = (f"cannot determine whether {call.tool_name} already "
+                  f"executed ({detail})")
+        self.store.block(rid, reason)
+        return GateDecision(Verdict.BLOCK, cls, reason=reason)
+
+    def _sole_writer(self, rec) -> bool:
+        """Was this call the only thing writing the world its probe just read?
+
+        A probe that reasons from world state — HEAD moved, so my commit
+        landed — is sound only under that assumption, and it is the probe's
+        own stated one. It holds across conversations. It does not hold inside
+        a batch, where a sibling can execute after this call was fingerprinted
+        (`docs/0038` §3).
+
+        Only effects that can change the world count; a read cannot. And when
+        the question cannot be answered, the answer is no: a world-state
+        verdict we cannot justify is exactly what must not be trusted.
+        """
+        try:
+            siblings = self.store.committed_since(
+                rec.conversation_id, rec.started_at, rec.tool_call_id)
+        except Exception:                               # noqa: BLE001
+            log.exception("could not check for concurrent effects on %s",
+                          rec.tool_call_id)
+            return False
+        return not any(not s.effect_class.replay_safe for s in siblings)
+
+    def recapture(self, call: ToolCall) -> None:
+        """Re-fingerprint the world for `call`, immediately before it runs.
+
+        Called from Seam C, the only seam that sees a call at its own execution
+        moment. Seam B decided for the whole batch; by the time this call is
+        actually about to execute, its siblings may already have changed the
+        world its probe will later reason about (`docs/0038` §3).
+
+        Never raises and never decides. A failure here costs a stale
+        fingerprint, which the probe reads as INCONCLUSIVE and the gate fails
+        closed on — the same direction as every other unknown in this system.
+        """
+        try:
+            cls = self.classifier.classify(call)
+            if cls.replay_safe:
+                return
+            self.store.refresh_pre_state(call.tool_call_id,
+                                         self._capture(call, cls))
+        except Exception:                               # noqa: BLE001
+            log.exception("recapture failed for %s", call.tool_call_id)
+
+    def _capture(self, call: ToolCall, cls: EffectClass) -> str | None:
+        """Fingerprint the world before acting, so a probe can compare later.
+
+        Only for classes that can reach the ambiguous branch -- there is no
+        point paying for it on a read.
+        """
+        if cls.replay_safe:
+            return None
+        probe = self.probes.for_call(call, self.classifier.probe_for(call))
+        if probe is None:
+            return None
+        try:
+            state = probe.capture(call)
+        except Exception:                               # noqa: BLE001
+            log.exception("probe %s capture raised", getattr(probe, "name", "?"))
+            return None
+        return json.dumps(state) if state else None
+
+    # ── post-execution bookkeeping ─────────────────────────────────────
+    def record_success(self, call: ToolCall, observation: bytes | None = None) -> None:
+        try:
+            self.store.commit(call.tool_call_id, observation)
+        except Exception:                               # noqa: BLE001
+            log.exception("could not commit %s", call.tool_call_id)
+
+    def record_failure(self, call: ToolCall, error: str) -> None:
+        try:
+            self.store.fail(call.tool_call_id, error)
+        except Exception:                               # noqa: BLE001
+            log.exception("could not record failure for %s", call.tool_call_id)
+
+    def record_success_by_id(self, tool_call_id: str, observation: bytes | None = None) -> None:
+        try:
+            self.store.commit(tool_call_id, observation)
+        except Exception:                               # noqa: BLE001
+            log.exception("could not commit %s", tool_call_id)
+
+    def record_failure_by_id(self, tool_call_id: str, error: str) -> None:
+        try:
+            self.store.fail(tool_call_id, error)
+        except Exception:                               # noqa: BLE001
+            log.exception("could not record failure for %s", tool_call_id)
+
+    def record_observation(self, tool_call_id: str,
+                           observation: bytes | None = None,
+                           error: str | None = None) -> None:
+        """The tool returned, and the harness has PERSISTED its result.
+
+        Only a caller that knows the result is durably in the conversation
+        history may use this -- Seam B qualifies because the SDK persists an
+        event before any caller callback runs (`docs/0042` §8.2). Otherwise
+        use `record_success` / `record_tool_error`, which assume nothing about
+        what the model has seen.
+
+        The record goes INTENT -> OBSERVED in one write, success or reported
+        failure alike. From then on an identical call is the model choosing to
+        repeat it, so `find_by_intent` stops aliasing to it (`docs/0045`).
+
+        One exception keeps the old shape: a replay-safe effect that reported
+        failure is FAILED. Repeating it is harmless, and FAILED already lets
+        the agent retry without a human.
+        """
+        try:
+            rec = self.store.lookup(tool_call_id)
+            if rec is None:
+                log.error("no record to deliver for %s", tool_call_id)
+                return
+            if error is not None and rec.effect_class.replay_safe:
+                self.store.fail(tool_call_id, error)
+            elif rec.state is EffectState.INTENT:
+                self.store.deliver(tool_call_id, observation, error)
+            elif rec.state is EffectState.COMMITTED:
+                self.store.observed(tool_call_id)
+            else:
+                log.warning("not delivering %s from state %s",
+                            tool_call_id, rec.state.value)
+        except Exception:                               # noqa: BLE001
+            # Leaves the record INTENT (or COMMITTED): the conservative side.
+            # A later identical call is then matched and probed or blocked,
+            # never silently repeated.
+            log.exception("could not record the observation for %s", tool_call_id)
+
+    def mark_observed(self, tool_call_id: str) -> None:
+        """A substituted result has reached the model. COMMITTED -> OBSERVED.
+
+        Without this an effect recovered after a crash stays COMMITTED, and
+        every later deliberate repeat of it is answered with the old output.
+        """
+        try:
+            rec = self.store.lookup(tool_call_id)
+            if rec is not None and rec.state is EffectState.COMMITTED:
+                self.store.observed(tool_call_id)
+        except Exception:                               # noqa: BLE001
+            log.exception("could not mark %s observed", tool_call_id)
+
+    def record_tool_error(self, tool_call_id: str, error: str,
+                          observation: bytes | None = None) -> None:
+        """The tool RAN and reported failure. That is a third thing.
+
+        Not `record_success`: committing a failed effect means a resume treats
+        work that never happened as done, and silently skips it. A real run
+        recorded five `exit=1` shell commands as COMMITTED (`docs/0031` §10).
+
+        Not `record_failure` either. `FAILED` means *provably did not land*,
+        and a non-zero exit is not proof of that — `echo x > a.txt && bad`
+        writes the file and exits 1. Asserting it did not land would be a lie
+        in the direction that permits a duplicate.
+
+        So it splits on whether repeating is safe, which is what the effect
+        class already encodes:
+
+            replay_safe   -> FAILED, and the agent may simply try again
+            everything    -> BLOCKED. Nobody knows whether it landed; that is
+            else             the definition of the ambiguous case, and
+                             `docs/0008` §6.5 says effect decisions fail closed.
+        """
+        rec = None
+        try:
+            rec = self.store.lookup(tool_call_id)
+        except Exception:                               # noqa: BLE001
+            log.exception("could not look up %s", tool_call_id)
+
+        if rec is not None and not rec.effect_class.replay_safe:
+            self._try_block(
+                tool_call_id,
+                f"the tool reported failure and this effect cannot be safely "
+                f"repeated, so whether it landed is unknown: {error[:300]}")
+            return
+        self.record_failure_by_id(tool_call_id, error)
+
+    def _try_block(self, tool_call_id: str, reason: str) -> None:
+        try:
+            if self.store.lookup(tool_call_id):
+                self.store.block(tool_call_id, reason)
+        except Exception:                               # noqa: BLE001
+            log.exception("could not block %s", tool_call_id)

agentctl/kernel/hook.py

@@ -0,0 +1,229 @@
+"""Seam A — the LiteLLM request hook. Spec: `docs/0012` §3.4.
+
+Runs inside the LiteLLM proxy, before the request reaches a provider. It is
+the only seam that is harness-independent: anything speaking the
+OpenAI-compatible format — OpenHands, Claude Code, Aider, Cline — passes
+through it (`docs/0013` §5).
+
+What it does:
+
+1. **Turn-atomic routing** — an endpoint may change between turns and never
+   within one. A message list ending in unresolved tool calls is pinned to the
+   deployment that opened the turn (`docs/0010` §7.3). Model families mint
+   `tool_call_id` differently, and the effect ledger is keyed on it, so a
+   mid-turn switch could make a committed effect invisible.
+2. **Attribution** — stamps a turn-scoped trace id. The SDK already sends a
+   conversation-scoped `x-litellm-session-id` (`docs/0015` §5); this adds the
+   turn.
+3. **Telemetry** — records cost, tokens, cache hits and the chosen deployment.
+
+Two things it deliberately does *not* do: decide anything about effects (that
+is the gate's job at Seams B and C), and depend on the control plane being
+reachable. It reads local state only.
+
+**This module holds only the logic.** The LiteLLM binding lives in
+`agentctl.adapters.litellm.hook` — the kernel must not import a data plane any
+more than it imports a harness (`docs/0008` R6), and `tests/test_boundaries.py`
+enforces that. `docs/0012` §1 originally placed the whole hook here; the split
+is recorded in `docs/0021` §7.
+
+**Seam A is best-effort and must be verified live.** LiteLLM has an open bug
+where `async_pre_call_hook` is bypassed on the Anthropic `/v1/messages`
+endpoint (#27518) and never fires for `/mcp/` tool calls (#25011) — silently,
+in both cases. `docs/0021` asserts it actually fires rather than assuming.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import time
+from pathlib import Path
+from typing import Any
+
+log = logging.getLogger("agentctl.hook")
+
+
+def ends_with_unresolved_tool_calls(messages: list[dict] | None) -> bool:
+    """Is the conversation mid-turn — awaiting tool results?
+
+    True when the last assistant message asked for tools and no matching tool
+    results follow it. Switching endpoints here is the hazard in `docs/0010`
+    §7.3.
+    """
+    if not messages:
+        return False
+
+    pending: set[str] = set()
+    for m in messages:
+        if not isinstance(m, dict):
+            continue
+        role = m.get("role")
+        if role == "assistant":
+            calls = m.get("tool_calls") or []
+            # A fresh assistant turn supersedes anything left dangling.
+            pending = {c.get("id") for c in calls if isinstance(c, dict) and c.get("id")}
+        elif role == "tool":
+            pending.discard(m.get("tool_call_id"))
+        elif role == "user":
+            # A user message means the turn was abandoned, not continued.
+            pending.clear()
+    return bool(pending)
+
+
+def turn_signature(messages: list[dict] | None) -> str | None:
+    """Identify the turn: the id of its first outstanding tool call."""
+    if not messages:
+        return None
+    for m in reversed(messages):
+        if isinstance(m, dict) and m.get("role") == "assistant":
+            calls = m.get("tool_calls") or []
+            ids = sorted(c.get("id") for c in calls
+                         if isinstance(c, dict) and c.get("id"))
+            return ids[0] if ids else None
+    return None
+
+
+class TurnAffinity:
+    """Remembers which deployment opened each turn. Local, in-memory.
+
+    Deliberately not shared state: `docs/0008` R2 says the hot path must not
+    depend on anything that can be unreachable. Losing this map costs a pinning
+    opportunity, never correctness.
+    """
+
+    def __init__(self, ttl_s: float = 900.0):
+        self._pins: dict[str, tuple[str, float]] = {}
+        self.ttl_s = ttl_s
+
+    def remember(self, turn: str | None, deployment: str | None) -> None:
+        if turn and deployment:
+            self._pins[turn] = (deployment, time.time())
+
+    def pinned(self, turn: str | None) -> str | None:
+        if not turn:
+            return None
+        hit = self._pins.get(turn)
+        if not hit:
+            return None
+        deployment, at = hit
+        if time.time() - at > self.ttl_s:
+            self._pins.pop(turn, None)
+            return None
+        return deployment
+
+    def __len__(self) -> int:
+        return len(self._pins)
+
+
+class RequestHook:
+    """Seam A. Subclasses LiteLLM's CustomLogger when it is importable.
+
+    Written so the logic is testable without the proxy: every method takes
+    plain dicts.
+    """
+
+    def __init__(self, telemetry_path: str | Path | None = None,
+                 affinity: TurnAffinity | None = None):
+        self.affinity = affinity or TurnAffinity()
+        self.telemetry_path = Path(telemetry_path) if telemetry_path else None
+        self.calls: list[dict] = []          # live-fire evidence for M1
+        self.records: list[dict] = []
+
+    # ── pre-call ───────────────────────────────────────────────────────
+    def apply(self, data: dict) -> dict:
+        """Mutate an outbound request. The testable core of the hook."""
+        messages = data.get("messages") or []
+        meta = data.setdefault("metadata", {})
+
+        turn = turn_signature(messages)
+        mid_turn = ends_with_unresolved_tool_calls(messages)
+
+        if mid_turn:
+            # THE RULE: the turn is the atomic unit of routing.
+            if (pin := self.affinity.pinned(turn)):
+                data["model"] = pin
+                meta["agentctl_pinned"] = pin
+            meta["agentctl_mid_turn"] = True
+        else:
+            self.affinity.remember(turn, data.get("model"))
+            meta["agentctl_mid_turn"] = False
+
+        # Where the proxy ACTUALLY puts it (`docs/0042` I-09, `docs/0048`).
+        # OpenHands sends the conversation id as the `x-litellm-session-id`
+        # header, and the proxy maps it to `litellm_session_id` and
+        # `metadata.session_id` -- captured from a real pre-call `data` dict,
+        # not assumed. `extra_headers` is a CLIENT-side kwarg that never
+        # reaches the proxy, so reading it alone gave `unknown:` on every live
+        # record (23/23, then 10/10). It stays last, for a direct caller.
+        conv = (meta.get("conversation_id")
+                or data.get("litellm_session_id")
+                or meta.get("session_id")
+                or (data.get("extra_headers") or {}).get("x-litellm-session-id")
+                or "unknown")
+        meta["agentctl_trace_id"] = f"{conv}:{turn or 'turn0'}"
+
+        self.calls.append({
+            "model": data.get("model"),
+            "n_messages": len(messages),
+            "mid_turn": mid_turn,
+            "turn": turn,
+            "trace_id": meta["agentctl_trace_id"],
+            "ts": time.time(),
+        })
+        self._flush()
+        return data
+
+    # ── post-call ──────────────────────────────────────────────────────
+    def record(self, kwargs: dict, response: Any,
+               start: float | None = None, end: float | None = None) -> dict:
+        """Extract the telemetry the cost ledger will need (M5)."""
+        usage = _get(response, "usage") or {}
+        details = _get(usage, "prompt_tokens_details") or {}
+        # WHERE THE METADATA ACTUALLY IS (docs/0021 §4). Anything the
+        # pre-call hook writes into data["metadata"] arrives on the logging
+        # callback under litellm_params.metadata, NOT kwargs["metadata"],
+        # which is empty. Reading only the obvious place yields trace_id=None
+        # and silently breaks cost attribution.
+        meta = kwargs.get("metadata") or {}
+        nested = (kwargs.get("litellm_params") or {}).get("metadata") or {}
+        trace = (meta.get("agentctl_trace_id")
+                 or nested.get("agentctl_trace_id")
+                 or (nested.get("requester_metadata") or {}).get("agentctl_trace_id"))
+        info = (kwargs.get("litellm_params") or {}).get("model_info") or {}
+        rec = {
+            "model": kwargs.get("model"),
+            "deployment": info.get("id"),
+            # The generated config's own claim (`model_info.free`). The cost
+            # ledger's third state reads it (`docs/0042` I-10).
+            "free": info.get("free"),
+            "trace_id": trace,
+            "prompt_tokens": _get(usage, "prompt_tokens"),
+            "completion_tokens": _get(usage, "completion_tokens"),
+            "cached_tokens": _get(details, "cached_tokens"),
+            "cost": kwargs.get("response_cost"),
+            "latency_s": (end - start) if (start and end) else None,
+            "ts": time.time(),
+        }
+        self.records.append(rec)
+        self._flush()
+        return rec
+
+    def _flush(self) -> None:
+        """Evidence on disk, so a subprocess proxy can be inspected."""
+        if self.telemetry_path is None:
+            return
+        try:
+            self.telemetry_path.parent.mkdir(parents=True, exist_ok=True)
+            self.telemetry_path.write_text(
+                json.dumps({"calls": self.calls, "records": self.records},
+                           indent=2, default=str), encoding="utf-8")
+        except Exception:                               # noqa: BLE001
+            log.exception("could not write hook telemetry")
+
+
+def _get(obj: Any, key: str, default=None):
+    if obj is None:
+        return default
+    if isinstance(obj, dict):
+        return obj.get(key, default)
+    return getattr(obj, key, default)