induscode 0.1.0__py3-none-any.whl

induscode/addons/dispatch/tool_interceptor.py

@@ -0,0 +1,349 @@
+"""ToolInterceptor pipeline — the composable tool-call boundary.
+
+This module is the runtime for the per-tool interception path. It replaces
+the old two-part arrangement — a nested wrapper that re-bound a tool's
+``execute`` plus a separate before/after hook runner — with one ordered
+pipeline of :class:`ToolInterceptor` stages folded around a single tool
+execution.
+
+The shape of a stage is ``enter`` (before the tool) and ``exit`` (after it),
+either optional. The chain applies them as a reduce:
+
+- **enter, forward.** Each matching stage's ``enter`` runs in registration
+  order. A stage may inspect the call, rewrite the decoded ``args`` (return
+  an :class:`ArgsRewrite`), or block the call outright (return a
+  :class:`GateDecision` with ``stop=True``). A block short-circuits: no later
+  ``enter`` runs, the real tool never executes, and the chain resolves with
+  ``blocked`` set.
+- **execute, once.** With the final (possibly rewritten) args, the chain
+  invokes the real ``execute`` exactly once.
+- **exit, reverse.** Each matching stage's ``exit`` runs in *reverse*
+  registration order, so the stage that entered first exits last — it wraps
+  the outermost layer around the call (classic onion ordering). A stage may
+  rewrite the result (return a replacement :class:`AgentToolResult`); the
+  rewritten result threads into the next (earlier-registered) stage's exit.
+
+Fault isolation: a raise from any ``enter``/``exit`` stage is converted to an
+:class:`AddonFault` routed to listeners and then treated as a no-op for that
+stage — enter keeps the prior args (and does not block), exit keeps the prior
+result. A stage's bug therefore degrades to "this stage did nothing" rather
+than crashing the tool call. An error *from the real tool* is not swallowed:
+it is offered to the ``exit`` stages (via :attr:`ToolExitContext.error`) and
+then re-raised so the agent loop sees it, unless an exit stage produced a
+replacement result (a deliberate recovery).
+
+Matching: a stage's ``match`` is either an exact wire-facing tool name or
+``"*"`` (every tool). :meth:`AddonInterceptorChain.matches` answers whether
+any stage applies to a tool, letting the host skip the pipeline entirely for
+tools no addon touches.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any
+
+from ..contract import (
+    AddonFault,
+    AddonFaultListener,
+    AddonId,
+    AgentToolResult,
+    ArgsRewrite,
+    ExecuteFn,
+    GateDecision,
+    InterceptResult,
+    InterceptorStage,
+    ToolEnterContext,
+    ToolExitContext,
+    ToolInterceptor,
+    addon_fault,
+)
+
+__all__ = [
+    "AddonInterceptorChain",
+    "interceptor",
+]
+
+
+async def _maybe_await(value: Any) -> Any:
+    """Resolve a stage 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
+
+
+# ---------------------------------------------------------------------------
+# Interceptor chain
+# ---------------------------------------------------------------------------
+
+
+class AddonInterceptorChain:
+    """The concrete :class:`InterceptorChain`: an ordered set of
+    :class:`ToolInterceptor` stages folded around one tool execution.
+
+    Build one with :meth:`from_interceptors` over the host's collected
+    interceptors (registration order preserved). Per tool call, :meth:`run`
+    selects the matching stages, applies their ``enter`` forward (honoring an
+    early block), executes the tool, then applies their ``exit`` in reverse.
+    Stage faults are routed to :meth:`on_fault` listeners and never crash the
+    call.
+    """
+
+    def __init__(self, interceptors: Sequence[ToolInterceptor]) -> None:
+        """
+        :param interceptors: every addon's recorded interceptors, in the order
+            the host folded them (registration order = enter order; reverse =
+            exit order)
+        """
+        # Every registered interceptor, in registration order.
+        self._interceptors: tuple[ToolInterceptor, ...] = tuple(interceptors)
+        # Live fault listeners, in registration order (dict = ordered set).
+        self._fault_listeners: dict[AddonFaultListener, None] = {}
+
+    @classmethod
+    def from_interceptors(
+        cls, interceptors: Sequence[ToolInterceptor]
+    ) -> AddonInterceptorChain:
+        """Build a chain from a flat list of interceptors.
+
+        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 interceptors: the folded interceptors across all addons
+        """
+        return cls(interceptors)
+
+    async def run(self, ctx: ToolEnterContext, execute: ExecuteFn) -> InterceptResult:
+        """Run a tool's execution through the interceptor pipeline.
+
+        Selects the stages whose ``match`` admits ``ctx.tool``, applies their
+        ``enter`` forward (rewriting args or short-circuiting on a block),
+        invokes ``execute`` once with the final args, then applies their
+        ``exit`` in reverse. A blocked enter resolves with ``blocked`` set
+        and never calls ``execute``. When no stage matches, ``execute`` runs
+        directly with the original args.
+
+        If the real tool raises, the error is offered to the matching
+        ``exit`` stages; an exit stage may return a replacement result to
+        recover, otherwise the error is re-raised to the caller after the
+        exit stages have observed it.
+
+        :param ctx: the entering call context (tool, call_id, initial args)
+        :param execute: the real tool invocation, called with the final args
+        """
+        matching = [
+            stage for stage in self._interceptors if _matches_tool(stage.match, ctx.tool)
+        ]
+        if len(matching) == 0:
+            return InterceptResult(result=await execute(ctx.args))
+
+        args, blocked = await self._apply_enter(ctx, matching)
+        if blocked is not None:
+            return InterceptResult(blocked=blocked)
+
+        exec_ctx = ToolEnterContext(tool=ctx.tool, call_id=ctx.call_id, args=args)
+        result: AgentToolResult | None = None
+        error: object | None = None
+        try:
+            result = await execute(exec_ctx.args)
+        except Exception as cause:
+            error = cause
+
+        exited = await self._apply_exit(exec_ctx, matching, result, error)
+        if exited is not None:
+            return InterceptResult(result=exited)
+        if error is not None:
+            # No exit stage recovered the failure — surface it to the agent loop.
+            raise error  # type: ignore[misc]
+        # A matched call always produces a result here (execute resolved, no error).
+        return InterceptResult(result=result)
+
+    def matches(self, tool: str) -> bool:
+        """Whether any interceptor matches the given tool name."""
+        return any(_matches_tool(stage.match, tool) for stage in self._interceptors)
+
+    def on_fault(self, listener: AddonFaultListener) -> Callable[[], None]:
+        """Register a listener for per-stage :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 _apply_enter(
+        self,
+        ctx: ToolEnterContext,
+        stages: Sequence[ToolInterceptor],
+    ) -> tuple[Mapping[str, Any], GateDecision | None]:
+        """Apply the matching stages' ``enter`` in forward order, folding args
+        rewrites and short-circuiting on the first block. A stage that raises
+        is isolated and skipped (the prior args are kept, no block)."""
+        args = ctx.args
+        for stage in stages:
+            if stage.enter is None:
+                continue
+            here = ToolEnterContext(tool=ctx.tool, call_id=ctx.call_id, args=args)
+            try:
+                outcome = await _maybe_await(stage.enter(here))
+            except Exception as cause:
+                self._report(
+                    addon_fault(
+                        "handler",
+                        f'Interceptor enter for "{ctx.tool}" threw.',
+                        addon=stage.addon,
+                        cause=cause,
+                    )
+                )
+                continue
+            blocked, rewritten = _read_enter(outcome)
+            if blocked is not None:
+                return args, blocked
+            if rewritten is not None:
+                args = rewritten
+        return args, None
+
+    async def _apply_exit(
+        self,
+        ctx: ToolEnterContext,
+        stages: Sequence[ToolInterceptor],
+        result: AgentToolResult | None,
+        error: object | None,
+    ) -> AgentToolResult | None:
+        """Apply the matching stages' ``exit`` in reverse order, folding
+        result rewrites. Returns the rewritten result when any stage produced
+        one (or recovered an error), otherwise ``None`` (the caller keeps the
+        original result/error). A stage that raises is isolated and skipped."""
+        current = result
+        rewritten = False
+        for stage in reversed(stages):
+            if stage.exit is None:
+                continue
+            exit_ctx = _build_exit_context(ctx, current, error)
+            try:
+                outcome = await _maybe_await(stage.exit(exit_ctx))
+            except Exception as cause:
+                self._report(
+                    addon_fault(
+                        "handler",
+                        f'Interceptor exit for "{ctx.tool}" threw.',
+                        addon=stage.addon,
+                        cause=cause,
+                    )
+                )
+                continue
+            if outcome is not None:
+                current = outcome
+                rewritten = True
+        return current if rewritten else None
+
+    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
+
+
+# ---------------------------------------------------------------------------
+# Outcome reading
+# ---------------------------------------------------------------------------
+
+
+def _read_enter(
+    outcome: object,
+) -> tuple[GateDecision | None, Mapping[str, Any] | None]:
+    """Interpret an enter outcome into a normalized
+    ``(blocked, replacement_args)`` verdict — a block decision, a replacement
+    args mapping, or neither (continue unchanged).
+
+    Distinguishes the two contract shapes by type — a :class:`GateDecision`
+    carries ``stop``, an :class:`ArgsRewrite` carries ``args`` — and, for TS
+    structural-guard parity, also tolerates a plain mapping carrying a bool
+    ``stop`` key (gate) or a mapping-valued ``args`` key (rewrite). Anything
+    else is treated as "leave unchanged".
+    """
+    if outcome is None:
+        return None, None
+    if isinstance(outcome, GateDecision):
+        return (outcome if outcome.stop else None), None
+    if isinstance(outcome, ArgsRewrite):
+        return None, outcome.args
+    if isinstance(outcome, Mapping):
+        stop = outcome.get("stop")
+        if isinstance(stop, bool):
+            if not stop:
+                return None, None
+            raw_reason = outcome.get("reason")
+            reason = raw_reason if isinstance(raw_reason, str) else None
+            return GateDecision(stop=True, reason=reason), None
+        args = outcome.get("args")
+        if isinstance(args, Mapping):
+            return None, args
+    return None, None
+
+
+def _build_exit_context(
+    ctx: ToolEnterContext,
+    result: AgentToolResult | None,
+    error: object | None,
+) -> ToolExitContext:
+    """Build the :class:`ToolExitContext` handed to an exit stage from the
+    entering context plus the current result/error. Only sets ``result`` when
+    present and ``error`` when present, matching the contract's "one of"
+    shape."""
+    if error is not None:
+        return ToolExitContext(tool=ctx.tool, call_id=ctx.call_id, error=error)
+    return ToolExitContext(tool=ctx.tool, call_id=ctx.call_id, result=result)
+
+
+# ---------------------------------------------------------------------------
+# Matching
+# ---------------------------------------------------------------------------
+
+
+def _matches_tool(match: str, tool: str) -> bool:
+    """Whether an interceptor's ``match`` (an exact name or ``"*"``) admits a
+    tool."""
+    return match == "*" or match == tool
+
+
+# ---------------------------------------------------------------------------
+# Construction helpers
+# ---------------------------------------------------------------------------
+
+
+def interceptor(
+    addon: AddonId,
+    match: str,
+    stage: InterceptorStage,
+) -> ToolInterceptor:
+    """Record one tool interceptor, stamping it with the matched tool and
+    owning addon — the shape the :class:`AddonSurface` produces and the chain
+    consumes.
+
+    Small convenience for hosts/tests assembling interceptors by hand without
+    going through the full surface builder. The supplied ``stage`` carries
+    only the enter/exit hooks; ``match`` and ``addon`` are filled here.
+
+    :param addon: the addon the interceptor is attributed to
+    :param match: the tool name to intercept, or ``"*"`` for every tool
+    :param stage: the enter/exit hooks
+    """
+    return ToolInterceptor(match=match, addon=addon, enter=stage.enter, exit=stage.exit)