induscode 0.1.0__py3-none-any.whl

induscode/addons/host.py

@@ -0,0 +1,469 @@
+"""AddonHost — the assembly point that turns a directory of addon modules
+into a single wired runtime.
+
+This is the top of the addons subsystem: it composes the injectable
+:class:`ModuleLoader` (discovery + load), the per-addon :class:`AddonSurface`
+recorder, the :class:`EventDispatcher` (observe / transform / gate), and the
+:class:`InterceptorChain` (tool-boundary enter / exit) into one coherent
+host. Its job is purely *folding*: read every addon's recorded
+:class:`RegisteredManifest` back out and merge the four contribution streams
+into one shared registry, then build the dispatch + interception runtimes
+over the merged subscriptions and interceptors.
+
+The load pipeline, per discovered source:
+
+1. **Load.** Resolve the source path through the injected loader into an
+   :class:`AddonManifest`. A load failure is isolated into an
+   :class:`AddonFault` (``kind="load"``) and the source is skipped — one
+   broken addon never aborts the others.
+2. **Register.** Mint a fresh surface scoped to the addon's id and the
+   host's :class:`FrameworkHandles`, then invoke the addon's ``register``
+   against it. A raise is isolated as a ``register`` fault and the addon
+   contributes nothing.
+3. **Fold.** Read the surface's :class:`RegisteredManifest` and merge its
+   subscriptions / interceptors / commands / tools into the host's growing
+   registry. Registration order is preserved across addons, so the
+   dispatcher's middleware order and the chain's onion order equal load
+   order. A command or tool whose name is already claimed — by another addon
+   or by a reserved host action — is rejected as a ``conflict`` fault and
+   dropped; the first claimant wins.
+
+After :meth:`AddonHost.load_all` resolves, the host exposes (on the returned
+:class:`AddonSurfaceBundle`): the bound dispatcher over every addon's
+subscriptions, the interceptor chain over every addon's tool interceptors,
+the collected conflict-resolved commands/tools, and the loaded addon ids.
+:meth:`AddonHost.on_fault` is a single fault stream fanning out load /
+register / conflict faults plus the runtime handler faults the dispatcher and
+chain raise.
+
+The loader stays **injectable**: it defaults to the importlib-backed
+:func:`create_module_loader`, but a test injects a scripted fake that returns
+manifests with no real import and no disk — the host code only ever sees the
+:class:`ModuleLoader` Protocol.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from .contract import (
+    AddonCommand,
+    AddonDiscovery,
+    AddonFault,
+    AddonFaultListener,
+    AddonId,
+    AddonManifest,
+    AddonSource,
+    AddonTool,
+    EventDispatcher,
+    EventSubscription,
+    FrameworkHandles,
+    InterceptorChain,
+    ModuleLoader,
+    RegisteredManifest,
+    ToolInterceptor,
+    addon_fault,
+    addon_id,
+)
+from .dispatch import AddonEventDispatcher, AddonInterceptorChain
+from .loader import create_module_loader
+from .manifest import discover_sources
+from .surface import create_surface
+
+__all__ = [
+    "AddonHost",
+    "AddonRegistry",
+    "AddonSurfaceBundle",
+    "create_addon_host",
+]
+
+
+# ---------------------------------------------------------------------------
+# Reserved host action names
+# ---------------------------------------------------------------------------
+
+#: Slash-command names the host reserves for its own built-in actions, so an
+#: addon cannot shadow a core command by registering the same name.
+#:
+#: Data-sourced as a frozen set rather than scattered string checks: the
+#: conflict guard consults this set when folding an addon's commands, and a
+#: name in it is rejected with a ``conflict`` fault. Reserving a new core
+#: action is a one-line edit here.
+_RESERVED_ACTION_NAMES: frozenset[str] = frozenset(
+    {
+        "help",
+        "quit",
+        "exit",
+        "clear",
+        "model",
+        "compact",
+    }
+)
+
+
+async def _maybe_await(value: Any) -> Any:
+    """Resolve a ``register`` return that may be a plain value or an awaitable
+    — the Python analogue of TS ``await`` over ``void | Promise<void>``."""
+    if inspect.isawaitable(value):
+        return await value
+    return value
+
+
+# ---------------------------------------------------------------------------
+# Host registry & result
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AddonRegistry:
+    """The merged, conflict-resolved registry the host accumulates while
+    folding every addon's :class:`RegisteredManifest`.
+
+    One flat tuple per contribution stream, in load order. The host builds
+    the dispatch and interception runtimes from :attr:`subscriptions` and
+    :attr:`interceptors`; :attr:`commands` and :attr:`tools` are the
+    collected capabilities, already de-duped against earlier claimants and
+    the reserved set.
+    """
+
+    # Every addon's event subscriptions, in load (registration) order.
+    subscriptions: tuple[EventSubscription, ...]
+    # Every addon's tool interceptors, in load order.
+    interceptors: tuple[ToolInterceptor, ...]
+    # The collected, name-deduped slash commands.
+    commands: tuple[AddonCommand, ...]
+    # The collected, name-deduped contributed tools.
+    tools: tuple[AddonTool, ...]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AddonSurfaceBundle:
+    """The fully-wired addon runtime :meth:`AddonHost.load_all` produces.
+
+    Exposes the dispatch engine, the interceptor chain, the collected
+    capabilities, and the successfully-loaded addon ids (for
+    diagnostics/listing). Consumers wire :attr:`dispatch` into the agent's
+    event points, :attr:`interceptors` into the tool boundary, and surface
+    :attr:`commands` / :attr:`tools` into the session. Both runtimes are
+    wired to the originating host's single fault stream.
+    """
+
+    # The event dispatcher over every loaded addon's subscriptions.
+    dispatch: EventDispatcher
+    # The tool-boundary chain over every loaded addon's interceptors.
+    interceptors: InterceptorChain
+    # The collected, conflict-resolved slash commands.
+    commands: tuple[AddonCommand, ...]
+    # The collected, conflict-resolved contributed tools.
+    tools: tuple[AddonTool, ...]
+    # The ids of the addons that loaded and registered successfully, in order.
+    loaded: tuple[AddonId, ...]
+
+
+# ---------------------------------------------------------------------------
+# The host
+# ---------------------------------------------------------------------------
+
+
+class AddonHost:
+    """The addon host: discovers, loads, registers, and folds addons into a
+    single wired runtime.
+
+    Build one with :func:`create_addon_host` (defaults wire the live
+    runtime). Call :meth:`load_all` once with a workspace path (or pass a
+    full :class:`AddonDiscovery`) to populate the host, then read the
+    returned bundle's ``dispatch``, ``interceptors``, ``commands``, and
+    ``tools``. Faults raised during loading — and the runtime handler faults
+    the dispatcher/chain raise — fan out to :meth:`on_fault` listeners.
+
+    Every collaborator is injectable with a live default, so production code
+    constructs the host with nothing (or just ``handles``) and a test
+    overrides exactly the seam it needs — almost always ``loader`` with a
+    scripted fake.
+    """
+
+    def __init__(
+        self,
+        *,
+        loader: ModuleLoader | None = None,
+        handles: FrameworkHandles | None = None,
+        dispatcher: Callable[[Sequence[EventSubscription]], EventDispatcher] | None = None,
+        chain: Callable[[Sequence[ToolInterceptor]], InterceptorChain] | None = None,
+        reserved_actions: Iterable[str] | None = None,
+    ) -> None:
+        """
+        :param loader: the module loader turning a source path into an
+            :class:`AddonManifest`; defaults to the importlib-backed
+            :func:`create_module_loader` — a test injects a fake
+        :param handles: the framework handles threaded into every addon's
+            surface and command context; defaults to an empty bag (a
+            non-interactive run supplies fewer than an interactive TUI)
+        :param dispatcher: override how the :class:`EventDispatcher` is built
+            from the folded subscriptions; defaults to
+            :meth:`AddonEventDispatcher.from_subscriptions`
+        :param chain: override how the :class:`InterceptorChain` is built from
+            the folded interceptors; defaults to
+            :meth:`AddonInterceptorChain.from_interceptors`
+        :param reserved_actions: the reserved core action names addon commands
+            may not shadow; defaults to the host's frozen set
+        """
+        self._loader: ModuleLoader = loader if loader is not None else create_module_loader()
+        self._handles: FrameworkHandles = (
+            handles if handles is not None else FrameworkHandles()
+        )
+        self._build_dispatcher = (
+            dispatcher if dispatcher is not None else AddonEventDispatcher.from_subscriptions
+        )
+        self._build_chain = (
+            chain if chain is not None else AddonInterceptorChain.from_interceptors
+        )
+        # The reserved core action names addon commands may not shadow.
+        self._reserved: frozenset[str] = (
+            _RESERVED_ACTION_NAMES
+            if reserved_actions is None
+            else frozenset(reserved_actions)
+        )
+
+        # Live fault listeners, in registration order (dict = ordered set).
+        self._fault_listeners: dict[AddonFaultListener, None] = {}
+        # Accumulated subscriptions across every folded addon, in load order.
+        self._subscriptions: list[EventSubscription] = []
+        # Accumulated interceptors across every folded addon, in load order.
+        self._interceptors: list[ToolInterceptor] = []
+        # Accumulated, name-deduped commands.
+        self._commands: list[AddonCommand] = []
+        # Accumulated, name-deduped tools.
+        self._tools: list[AddonTool] = []
+        # The command names already claimed (reserved + earlier addon commands).
+        self._claimed_commands: set[str] = set(self._reserved)
+        # The tool names already claimed by earlier addons.
+        self._claimed_tools: set[str] = set()
+        # The ids of addons that loaded and registered successfully, in order.
+        self._loaded: list[AddonId] = []
+
+    def on_fault(self, listener: AddonFaultListener) -> Callable[[], None]:
+        """Register a listener for every :class:`AddonFault` the host raises —
+        load, register, and conflict faults during folding, plus the runtime
+        handler faults the built dispatcher and chain route. Returns an
+        idempotent unsubscribe.
+
+        Registering before :meth:`load_all` captures load-time faults; the
+        dispatcher and chain built by :meth:`load_all` are wired to this same
+        sink so a later dispatch fault reaches the same listeners.
+
+        :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 load_all(self, where: str | AddonDiscovery) -> AddonSurfaceBundle:
+        """Discover, load, register, and fold every addon under a directory
+        (or a full :class:`AddonDiscovery` config), then build and return the
+        wired runtime.
+
+        A bare string is treated as the workspace whose ``.indus/addons``
+        directory is scanned; an :class:`AddonDiscovery` is passed through to
+        :func:`discover_sources` unchanged. Each discovered source is loaded
+        through the injected loader and folded; failures are isolated into
+        faults. The returned :class:`AddonSurfaceBundle` exposes the dispatch
+        engine, the interceptor chain, and the collected capabilities — all
+        wired to this host's fault stream.
+
+        :param where: a workspace path, or a full discovery config
+        """
+        discovery = AddonDiscovery(workspace=where) if isinstance(where, str) else where
+        for source in discover_sources(discovery):
+            await self.load_one(source)
+        return self._bundle()
+
+    async def load_one(self, source: AddonSource) -> None:
+        """Load, register, and fold a single already-discovered
+        :class:`AddonSource`.
+
+        Public so a host can graft an explicitly-resolved addon (e.g. an
+        always-on bundled addon) without going through directory discovery.
+        Isolates load and register failures into faults and folds whatever
+        the addon recorded.
+
+        :param source: the discovered source (id + entry path)
+        """
+        module: AddonManifest
+        try:
+            module = await self._loader.load(source.path)
+        except Exception as cause:
+            self._report(
+                addon_fault(
+                    "load",
+                    f"Failed to load addon at {source.path}.",
+                    addon=source.id,
+                    cause=cause,
+                )
+            )
+            return
+
+        declared_id = getattr(module, "id", None)
+        ident = addon_id(declared_id) if isinstance(declared_id, str) else source.id
+        declared_version = getattr(module, "version", None)
+        version = declared_version if isinstance(declared_version, str) else None
+
+        surface = create_surface(ident, self._handles, version)
+        try:
+            await _maybe_await(module.register(surface))
+        except Exception as cause:
+            self._report(
+                addon_fault(
+                    "register",
+                    f'Addon "{ident}" threw during register().',
+                    addon=ident,
+                    cause=cause,
+                )
+            )
+            return
+
+        self._fold(ident, surface.manifest())
+        self._loaded.append(ident)
+
+    @property
+    def registry(self) -> AddonRegistry:
+        """The merged, conflict-resolved registry accumulated so far."""
+        return AddonRegistry(
+            subscriptions=tuple(self._subscriptions),
+            interceptors=tuple(self._interceptors),
+            commands=tuple(self._commands),
+            tools=tuple(self._tools),
+        )
+
+    def _bundle(self) -> AddonSurfaceBundle:
+        """Build the :class:`AddonSurfaceBundle` from the current accumulated
+        registry.
+
+        The dispatcher and chain are constructed via the injected factories
+        over the folded subscriptions/interceptors and wired to this host's
+        fault stream, so runtime handler faults reach the same listeners as
+        load-time faults.
+        """
+        dispatch = self._build_dispatcher(tuple(self._subscriptions))
+        interceptors = self._build_chain(tuple(self._interceptors))
+        self._wire_faults(dispatch)
+        self._wire_faults(interceptors)
+        return AddonSurfaceBundle(
+            dispatch=dispatch,
+            interceptors=interceptors,
+            commands=tuple(self._commands),
+            tools=tuple(self._tools),
+            loaded=tuple(self._loaded),
+        )
+
+    def _fold(self, addon: AddonId, manifest: RegisteredManifest) -> None:
+        """Fold one addon's recorded :class:`RegisteredManifest` into the host
+        registry.
+
+        Subscriptions and interceptors are appended unconditionally (order =
+        load order). Commands and tools are name-checked against the claimed
+        sets: a name already taken (by the reserved set or an earlier addon)
+        is rejected as a ``conflict`` fault and dropped, so the first
+        claimant wins.
+        """
+        self._subscriptions.extend(manifest.subscriptions)
+        self._interceptors.extend(manifest.interceptors)
+        for command in manifest.commands:
+            if command.name in self._claimed_commands:
+                self._report(
+                    addon_fault(
+                        "conflict",
+                        (
+                            f'Addon "{addon}" command "{command.name}" is a reserved action name.'
+                            if command.name in self._reserved
+                            else f'Addon "{addon}" command "{command.name}" conflicts with an already-registered command.'
+                        ),
+                        addon=addon,
+                    )
+                )
+                continue
+            self._claimed_commands.add(command.name)
+            self._commands.append(command)
+        for tool in manifest.tools:
+            if tool.name in self._claimed_tools:
+                self._report(
+                    addon_fault(
+                        "conflict",
+                        f'Addon "{addon}" tool "{tool.name}" conflicts with an already-registered tool.',
+                        addon=addon,
+                    )
+                )
+                continue
+            self._claimed_tools.add(tool.name)
+            self._tools.append(tool)
+
+    def _wire_faults(self, runtime: object) -> None:
+        """Forward a built runtime's fault stream into the host's listeners,
+        when the runtime exposes one.
+
+        The contract's :class:`EventDispatcher` always declares ``on_fault``;
+        the :class:`InterceptorChain` Protocol does not, though the default
+        :class:`AddonInterceptorChain` provides it. This probes for the
+        method so an injected dispatcher/chain that omits a fault stream is
+        simply not wired, rather than failing the host.
+        """
+        on_fault = getattr(runtime, "on_fault", None)
+        if callable(on_fault):
+            on_fault(self._report)
+
+    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
+
+
+# ---------------------------------------------------------------------------
+# Construction
+# ---------------------------------------------------------------------------
+
+
+def create_addon_host(
+    *,
+    loader: ModuleLoader | None = None,
+    handles: FrameworkHandles | None = None,
+    dispatcher: Callable[[Sequence[EventSubscription]], EventDispatcher] | None = None,
+    chain: Callable[[Sequence[ToolInterceptor]], InterceptorChain] | None = None,
+    reserved_actions: Iterable[str] | None = None,
+) -> AddonHost:
+    """Construct an :class:`AddonHost` with the given (all-optional)
+    dependencies.
+
+    The single sanctioned entry point: production code calls it with nothing
+    (or just ``handles``) and gets the importlib-backed loader and the
+    default dispatcher/chain factories; a test injects a fake
+    :class:`ModuleLoader` to exercise the full fold-and-wire pipeline with no
+    real import or disk.
+
+    :param loader: module loader override (defaults to importlib-backed)
+    :param handles: framework handles threaded into every addon surface
+    :param dispatcher: dispatcher factory override
+    :param chain: interceptor-chain factory override
+    :param reserved_actions: reserved core action names override
+    """
+    return AddonHost(
+        loader=loader,
+        handles=handles,
+        dispatcher=dispatcher,
+        chain=chain,
+        reserved_actions=reserved_actions,
+    )