induscode 0.1.0__py3-none-any.whl

induscode/addons/dispatch/__init__.py

@@ -0,0 +1,43 @@
+"""Dispatch subsystem — public barrel.
+
+The unified hook + tool-interception runtime, written against the frozen
+``induscode.addons.contract`` surface:
+
+- :class:`AddonEventDispatcher` — the single fan-out / transform / veto
+  engine for the colon-named :data:`HookEvent` taxonomy. Folds every addon's
+  :class:`EventSubscription` records into one ordered middleware pass
+  (observe / transform / gate), short-circuits on the first veto, and derives
+  its reserved (gate-bearing) event set from a data table
+  (:data:`EVENT_TRAITS`) rather than a literal.
+- :class:`AddonInterceptorChain` — the composable tool-call boundary. Folds
+  every addon's :class:`ToolInterceptor` stages around one tool execution
+  (enter forward, exit reverse), rewriting args/results or blocking the call,
+  replacing the old tool wrapper plus before/after hook runner.
+
+Both isolate handler/stage faults into :class:`AddonFault` records routed to
+listeners so a misbehaving addon never crashes the agent loop. The
+:func:`subscription` and :func:`interceptor` helpers mint the contract's
+recorded shapes for hosts/tests that assemble them outside the full surface
+builder.
+"""
+
+from __future__ import annotations
+
+from .event_dispatcher import (
+    EVENT_TRAITS,
+    RESERVED_EVENTS,
+    AddonEventDispatcher,
+    EventTrait,
+    subscription,
+)
+from .tool_interceptor import AddonInterceptorChain, interceptor
+
+__all__ = [
+    "AddonEventDispatcher",
+    "AddonInterceptorChain",
+    "EVENT_TRAITS",
+    "EventTrait",
+    "RESERVED_EVENTS",
+    "interceptor",
+    "subscription",
+]

induscode/addons/dispatch/event_dispatcher.py

@@ -0,0 +1,348 @@
+"""EventDispatcher — the single fan-out / transform / veto engine for the
+unified colon-named event taxonomy.
+
+One :class:`AddonEventDispatcher` replaces what were previously two parallel
+systems (a broad "emit lifecycle events" bus and a low-level "trigger
+mutation hooks" runner): every :data:`HookEvent` flows through one ordered
+middleware pass, and an addon decides per-subscription whether it merely
+*observes* the payload, *transforms* it, or *gates* (vetoes) the flow. The
+three middleware kinds compose in one dispatch:
+
+- ``observe``   — fire-and-forget. The handler sees the live payload and
+  returns nothing. It cannot alter the value or stop the chain; a raise is
+  isolated into an :class:`AddonFault` and the run continues.
+- ``transform`` — the handler returns a replacement payload, which the
+  dispatcher threads into every later handler and ultimately back to the
+  caller as :attr:`DispatchOutcome.payload`. A transform that raises is
+  isolated and treated as a no-op (the prior payload is kept), so one bad
+  rewriter cannot drop the value.
+- ``gate``      — the handler returns a :class:`GateDecision`; the first
+  ``stop=True`` short-circuits the run and is surfaced as
+  :attr:`DispatchOutcome.gate`. A gate that raises is isolated and treated as
+  "no veto", so an erroring guard **fails open** rather than wedging the
+  agent.
+
+Ordering is registration order across every addon: subscriptions are appended
+to a per-event list as the host folds each :class:`RegisteredManifest` in,
+and a dispatch walks that list front-to-back. Because a gate stops the walk,
+a gate registered earlier wins over a transform registered later — the host
+controls precedence purely through load order, with no priority field to
+reconcile.
+
+Reserved (gate-bearing) events — the events that *guard* something the agent
+is about to do and therefore honor a veto — are **data-sourced**, not a
+hard-coded literal. The dispatcher derives the reserved set at import by
+scanning a small :class:`EventTrait` table keyed by :data:`HookEvent`; an
+event with the ``guards`` trait is reserved.
+:attr:`AddonEventDispatcher.reserved` exposes the derived set so callers (and
+tests) read the same source of truth the engine uses to decide whether a gate
+decision is meaningful for an event.
+
+The dispatcher is transport-agnostic: it knows nothing about the framework
+agent loop, the tool boundary, or how an event's payload is produced. Callers
+push events in; the dispatcher fans them out, folds transforms,
+short-circuits on a veto, and routes handler faults to listeners.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any, Mapping
+
+from ..contract import (
+    AddonFault,
+    AddonFaultListener,
+    AddonId,
+    DispatchOutcome,
+    EventSubscription,
+    GateDecision,
+    HookEvent,
+    HookHandler,
+    addon_fault,
+)
+
+__all__ = [
+    "AddonEventDispatcher",
+    "EVENT_TRAITS",
+    "EventTrait",
+    "RESERVED_EVENTS",
+    "subscription",
+]
+
+
+# ---------------------------------------------------------------------------
+# Event traits (data-sourced reserved set)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class EventTrait:
+    """The behavioral traits of a single :data:`HookEvent`, used to *derive*
+    facts about the taxonomy instead of restating them as standalone literals.
+
+    Today the only trait the engine consults is :attr:`guards`: whether the
+    event fronts an action the agent is about to take and therefore admits a
+    veto. The reserved (gate-bearing) set is computed from this table at
+    import, so adding or reclassifying an event is a one-row edit here —
+    never a second hand-maintained ``RESERVED`` constant to keep in sync.
+    """
+
+    #: Whether this event guards an imminent action and so honors a ``gate``
+    #: veto. ``True`` for events that straddle a side-effecting step the host
+    #: can refuse to take (run a tool, submit input, condense the transcript);
+    #: ``False`` for purely notificational lifecycle/transform events, where a
+    #: gate decision carries no action to stop.
+    guards: bool
+
+
+#: The trait table for every :data:`HookEvent`, in taxonomy order.
+#:
+#: The dispatcher reads this once to build its reserved set; nothing else
+#: encodes which events are gate-bearing. An event whose ``guards`` is True
+#: is one whose ``stop=True`` gate decision the host is expected to act on:
+#:
+#: - ``tool:before``    — guards a tool execution (block the call).
+#: - ``input:submit``   — guards user input entering the loop (drop the turn).
+#: - ``compact:before`` — guards condensing the transcript (refuse the compaction).
+#:
+#: Every other event is notificational or transform-only; a gate handler may
+#: still attach to it, but the engine reports its decision without treating
+#: the event as reserved.
+EVENT_TRAITS: Mapping[HookEvent, EventTrait] = MappingProxyType(
+    {
+        "session:start": EventTrait(guards=False),
+        "session:end": EventTrait(guards=False),
+        "turn:start": EventTrait(guards=False),
+        "turn:end": EventTrait(guards=False),
+        "tool:before": EventTrait(guards=True),
+        "tool:after": EventTrait(guards=False),
+        "chat:params": EventTrait(guards=False),
+        "chat:message": EventTrait(guards=False),
+        "shell:env": EventTrait(guards=False),
+        "input:submit": EventTrait(guards=True),
+        "context:build": EventTrait(guards=False),
+        "compact:build": EventTrait(guards=False),
+        "compact:before": EventTrait(guards=True),
+    }
+)
+
+#: The reserved (gate-bearing) events, derived from :data:`EVENT_TRAITS`.
+#:
+#: Computed once from the trait table — the single data source — rather than
+#: declared as its own literal set. Callers obtain it through
+#: :attr:`AddonEventDispatcher.reserved`; the engine consults the same set
+#: when deciding whether a gate decision is actionable for an event.
+RESERVED_EVENTS: frozenset[HookEvent] = frozenset(
+    event for event, trait in EVENT_TRAITS.items() if trait.guards
+)
+
+
+async def _maybe_await(value: Any) -> Any:
+    """Resolve a handler return that may be a plain value or an awaitable —
+    the Python analogue of TS ``await`` over ``T | Promise<T>``."""
+    if inspect.isawaitable(value):
+        return await value
+    return value
+
+
+# ---------------------------------------------------------------------------
+# Dispatcher
+# ---------------------------------------------------------------------------
+
+
+class AddonEventDispatcher:
+    """The concrete :class:`EventDispatcher`: one engine per session, fed the
+    folded :class:`EventSubscription` lists of every loaded addon.
+
+    Build one with :meth:`from_subscriptions` over the host's collected
+    subscriptions (registration order preserved), then call :meth:`dispatch`
+    per event. Handler faults are routed to :meth:`on_fault` listeners and
+    never propagate into the agent loop.
+    """
+
+    def __init__(self, subscriptions: Sequence[EventSubscription]) -> None:
+        """
+        :param subscriptions: every addon's recorded subscriptions, in the
+            order the host folded them (registration order = dispatch order)
+        """
+        # Subscriptions grouped by event, each list in registration order.
+        self._by_event: dict[HookEvent, tuple[EventSubscription, ...]] = _group_by_event(
+            subscriptions
+        )
+        # Live fault listeners, in registration order (dict = ordered set).
+        self._fault_listeners: dict[AddonFaultListener, None] = {}
+
+    @classmethod
+    def from_subscriptions(
+        cls, subscriptions: Sequence[EventSubscription]
+    ) -> AddonEventDispatcher:
+        """Build a dispatcher from a flat list of subscriptions.
+
+        A thin alias for the constructor that reads well at the host's fold
+        site (the TS static ``from``; renamed — ``from`` is a Python keyword).
+
+        :param subscriptions: the folded subscriptions across all addons
+        """
+        return cls(subscriptions)
+
+    @property
+    def reserved(self) -> frozenset[HookEvent]:
+        """The reserved (gate-bearing) event set, derived from the trait table.
+
+        Exposed so callers and tests share the engine's own source of truth
+        for which events honor a veto, rather than re-deriving it from a
+        literal.
+        """
+        return RESERVED_EVENTS
+
+    async def dispatch(self, event: HookEvent, payload: Any) -> DispatchOutcome:
+        """Run an event through its subscribed middleware and return the
+        outcome.
+
+        Walks the event's subscriptions in registration order: ``transform``
+        handlers fold the payload forward, ``observe`` handlers see the
+        current payload, and the first ``gate`` handler that returns
+        ``stop=True`` short-circuits the walk. The returned
+        :class:`DispatchOutcome` carries the final (possibly transformed)
+        payload and, when a gate stopped the run, its decision. A handler
+        that raises is isolated into an :class:`AddonFault` routed to
+        listeners; the run continues (or, for a gate, fails open).
+
+        A gate decision is reported regardless of whether the event is
+        reserved, so a caller may inspect :attr:`DispatchOutcome.gate` for
+        any event; the :attr:`reserved` set tells the host which events it is
+        *expected* to act on.
+
+        :param event: the event to dispatch
+        :param payload: the initial payload threaded through the chain
+        """
+        subscriptions = self._by_event.get(event)
+        if not subscriptions:
+            return DispatchOutcome(payload=payload)
+
+        current = payload
+        for sub in subscriptions:
+            gate, current = await self._run(event, sub, current)
+            if gate is not None and gate.stop:
+                return DispatchOutcome(payload=current, gate=gate)
+        return DispatchOutcome(payload=current)
+
+    def has(self, event: HookEvent) -> bool:
+        """Whether any addon has subscribed to the given event."""
+        return bool(self._by_event.get(event))
+
+    def on_fault(self, listener: AddonFaultListener) -> Callable[[], None]:
+        """Register a listener for per-handler :class:`AddonFault` reports.
+
+        Returns an idempotent unsubscribe thunk; registering the same
+        listener twice collapses to one slot.
+
+        :param listener: the fault sink
+        """
+        self._fault_listeners[listener] = None
+        active = True
+
+        def unsubscribe() -> None:
+            nonlocal active
+            if not active:
+                return
+            active = False
+            self._fault_listeners.pop(listener, None)
+
+        return unsubscribe
+
+    async def _run(
+        self,
+        event: HookEvent,
+        sub: EventSubscription,
+        payload: Any,
+    ) -> tuple[GateDecision | None, Any]:
+        """Invoke one subscription's handler against the current payload,
+        isolating any raise, and return ``(gate_decision, next_payload)``.
+
+        ``observe`` returns nothing and the payload is left untouched;
+        ``transform`` folds its return value in; ``gate`` yields its decision
+        (a non-:class:`GateDecision` return degrades to "no opinion"). A
+        raise from any kind is converted to an :class:`AddonFault` routed to
+        listeners and then swallowed — observe/transform continue with the
+        prior payload, gate fails open (returns no veto).
+        """
+        handler: HookHandler = sub.handler
+        try:
+            match handler.kind:
+                case "observe":
+                    await _maybe_await(handler.run(payload))
+                    return None, payload
+                case "transform":
+                    next_payload = await _maybe_await(handler.run(payload))
+                    return None, next_payload
+                case "gate":
+                    decision = await _maybe_await(handler.run(payload))
+                    if isinstance(decision, GateDecision):
+                        return decision, payload
+                    return None, payload
+        except Exception as cause:
+            self._report(
+                addon_fault(
+                    "handler",
+                    f'Handler for "{event}" threw during dispatch.',
+                    addon=sub.addon,
+                    cause=cause,
+                )
+            )
+            return None, payload
+        # Unknown handler kind (malformed duck): inert, payload untouched.
+        return None, payload
+
+    def _report(self, fault: AddonFault) -> None:
+        """Route a fault to every listener, guarding each listener against its
+        own raise."""
+        for listener in list(self._fault_listeners):
+            try:
+                listener(fault)
+            except Exception:
+                # A throwing fault listener must not break fan-out to the others.
+                pass
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _group_by_event(
+    subscriptions: Sequence[EventSubscription],
+) -> dict[HookEvent, tuple[EventSubscription, ...]]:
+    """Group a flat subscription list into per-event tuples, preserving the
+    input order within each event so dispatch order equals registration
+    order."""
+    grouped: dict[HookEvent, list[EventSubscription]] = {}
+    for sub in subscriptions:
+        grouped.setdefault(sub.event, []).append(sub)
+    return {event: tuple(subs) for event, subs in grouped.items()}
+
+
+# ---------------------------------------------------------------------------
+# Construction helpers
+# ---------------------------------------------------------------------------
+
+
+def subscription(
+    addon: AddonId,
+    event: HookEvent,
+    handler: HookHandler,
+) -> EventSubscription:
+    """Record one event subscription, stamping it with the owning addon — the
+    shape the :class:`AddonSurface` produces and the dispatcher consumes.
+
+    Small convenience for hosts/tests assembling subscriptions by hand
+    without going through the full surface builder.
+
+    :param addon: the addon the subscription is attributed to
+    :param event: the event being hooked
+    :param handler: the observe/transform/gate middleware
+    """
+    return EventSubscription(event=event, handler=handler, addon=addon)