induscode 0.1.0__py3-none-any.whl

induscode/addons/contract.py

@@ -0,0 +1,923 @@
+"""Addons contract — the FROZEN type surface of the third-party customization
+layer.
+
+This module is the single typed seam between the coding-agent *product* and
+code that does not ship with it: locally-authored Python modules that graft
+tools, slash commands, lifecycle observers, and tool-boundary interceptors
+onto a running session. It declares *only* shapes plus a handful of tiny
+inert helpers (a brand minter, a fault factory, and a pure empty-manifest
+constructor) — no I/O, no module loading, no dispatch. Every later addons
+module (the importlib-backed loader, the discovery walk, the surface builder,
+the event dispatcher, and the interceptor chain) is written against the names
+declared here, so the file is intentionally small, append-mostly, and stable.
+
+Design stance (ported from TS ``src/addons/contract.ts``) — three deliberate
+divergences from the prevailing "factory writes into per-addon Maps" pattern:
+
+1. **Return-a-manifest registration.** An addon module's ``register`` is
+   handed an :class:`AddonSurface` and *records* its intent — subscriptions,
+   interceptors, commands, tools — but the registration calls do not mutate
+   any global runtime. The host reads the recorded :class:`RegisteredManifest`
+   back out and folds it into one shared registry. Registration is a pure
+   description of capability, not a side effect on the agent.
+
+2. **One unified event model.** Lifecycle observation, payload
+   transformation, and veto are a single :class:`EventDispatcher` of
+   colon-named :data:`HookEvent` values, each carrying a :data:`HookHandler`
+   of one of three middleware kinds — ``observe`` (fire-and-forget),
+   ``transform`` (returns a replacement payload), ``gate`` (returns a stop
+   decision). There is no second parallel "hooks" system; the dotted
+   vocabulary is replaced by colon names (``tool:before``, ``chat:params``,
+   ``shell:env``, …).
+
+3. **A tool-boundary pipeline.** The per-tool interception path is an
+   ordered :class:`InterceptorChain` of :class:`ToolInterceptor` stages with
+   ``enter``/``exit`` hooks, applied as a reduce (enter forward, exit
+   reverse) — not a nested-if tool wrapper.
+
+The module loader is **injectable** (:class:`ModuleLoader`): the default is
+importlib-backed (see ``loader.py``), but a test injects a scripted fake that
+returns an :class:`AddonManifest` with no real import and no disk access.
+
+Port note — the jiti / virtual-module machinery is DROPPED
+----------------------------------------------------------
+The TS layer needed jiti (a TypeScript-on-the-fly importer) plus a
+virtual-module/alias bridge so an addon's ``import "indusagi/agent"`` could
+resolve inside a compiled single-file binary. Python addons are plain ``.py``
+files and the ``indusagi`` framework is an installed package, so a plain
+``import indusagi.agent`` simply works — no sandbox, no namespace bridge.
+:data:`BUNDLED_NAMESPACES` is therefore **vestigial**: it is kept (renamed to
+Python dotted module names, with ``@sinclair/typebox`` dropped — schemas are
+plain JSON-schema mappings here) purely for parity and introspection; no
+loader machinery consumes it.
+
+Framework anchors (all from the ``indusagi`` package — the sibling rebuilt
+framework this app targets):
+
+- :class:`AgentTool`, :class:`AgentToolResult`, ``ThinkingLevel`` ← ``indusagi.agent``
+- ``AgentMessage``, :class:`Model` ← ``indusagi.ai`` (note: ``AgentMessage``
+  lives in ``indusagi.ai``, not ``.agent`` — plan §5.9)
+- :class:`Component`, ``KeyId`` ← ``indusagi.tui``
+
+The contract never re-declares these; it composes them. The TS ``TSchema`` /
+``Static`` re-exports collapse to the plain JSON-schema :data:`Schema` alias
+(``Static`` is a compile-time computation with no Python analogue).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, ClassVar, Literal, NewType, Protocol, TypeAlias
+
+from indusagi.agent import AgentTool, AgentToolResult, ThinkingLevel
+from indusagi.ai import AgentMessage, Model
+from indusagi.tui import Component, KeyId
+
+__all__ = [
+    "ADDONS_DIR",
+    "AddonCommand",
+    "AddonDiscovery",
+    "AddonFault",
+    "AddonFaultKind",
+    "AddonFaultListener",
+    "AddonId",
+    "AddonManifest",
+    "AddonSource",
+    "AddonSurface",
+    "AddonTool",
+    "AgentMessage",
+    "AgentTool",
+    "AgentToolResult",
+    "ArgsRewrite",
+    "BUNDLED_NAMESPACES",
+    "BundledNamespace",
+    "CommandContext",
+    "CommandRun",
+    "CommandSpec",
+    "Component",
+    "DispatchOutcome",
+    "EnterFn",
+    "EnterOutcome",
+    "EventDispatcher",
+    "EventSubscription",
+    "ExecOutcome",
+    "ExecuteFn",
+    "ExitFn",
+    "ExitOutcome",
+    "FrameworkHandles",
+    "GateDecision",
+    "GateHandler",
+    "HookEvent",
+    "HookHandler",
+    "HookKind",
+    "InterceptResult",
+    "InterceptorChain",
+    "InterceptorStage",
+    "KeyId",
+    "Model",
+    "ModuleLoader",
+    "ObserveHandler",
+    "RegisteredManifest",
+    "Schema",
+    "ThinkingLevel",
+    "ToolEnterContext",
+    "ToolExitContext",
+    "ToolInterceptor",
+    "TransformHandler",
+    "addon_fault",
+    "addon_id",
+    "empty_manifest",
+]
+
+
+# ---------------------------------------------------------------------------
+# Schema stand-in (TypeBox collapses to plain JSON-schema mappings)
+# ---------------------------------------------------------------------------
+
+#: A JSON-schema parameter shape — the Python stand-in for TypeBox
+#: ``TSchema``. The framework's tools carry their parameter schemas as plain
+#: mappings; the addons layer threads them but never interprets them.
+Schema: TypeAlias = Mapping[str, Any]
+
+
+# ---------------------------------------------------------------------------
+# Bundled-namespace bridge identity (vestigial in Python — see module note)
+# ---------------------------------------------------------------------------
+
+#: The module specifiers an addon may import that the host guarantees are
+#: importable. In TS these had to be *bridged* into a compiled binary via
+#: jiti virtual modules; in Python they are ordinary installed packages and
+#: ``import indusagi.agent`` just works, so this type is parity vocabulary
+#: only. ``@sinclair/typebox`` is dropped (schemas are plain mappings).
+BundledNamespace: TypeAlias = Literal[
+    "indusagi.agent",
+    "indusagi.ai",
+    "indusagi.tui",
+]
+
+#: The frozen list of :data:`BundledNamespace` specifiers, in a stable order.
+#:
+#: **Vestigial** in the Python port: no loader machinery consumes it (there is
+#: no virtual-module bridge to build). Kept so diagnostics/introspection and
+#: the TS lineage share one source of truth for "what an addon may rely on".
+BUNDLED_NAMESPACES: tuple[BundledNamespace, ...] = (
+    "indusagi.agent",
+    "indusagi.ai",
+    "indusagi.tui",
+)
+
+
+# ---------------------------------------------------------------------------
+# Addon identity & manifest
+# ---------------------------------------------------------------------------
+
+#: String-branded stable identifier for a loaded addon.
+#:
+#: Derived from the addon's declared ``id`` (or its source path when absent);
+#: branded so an arbitrary string cannot be passed where a vetted addon id is
+#: required. Mint one with :func:`addon_id`.
+AddonId = NewType("AddonId", str)
+
+
+def addon_id(raw: str) -> AddonId:
+    """Brand a raw string as an :data:`AddonId`. The single sanctioned minter."""
+    return AddonId(raw)
+
+
+class AddonManifest(Protocol):
+    """What an addon module provides (or whose ``register`` the host invokes)
+    — the top-level shape the :class:`ModuleLoader` resolves.
+
+    An addon is a plain object (or the module itself), not a class hierarchy:
+    it declares its identity and a single ``register`` entry point.
+    ``register`` receives an :class:`AddonSurface` and uses it to *record* the
+    addon's contributions; the host then reads those contributions back as a
+    :class:`RegisteredManifest`. The addon never reaches into global agent
+    state — its only channel is the surface it is handed.
+
+    Two optional attributes are duck-read by the host (``getattr``, tolerant
+    of absence — a Python ``Protocol`` cannot express optional members):
+
+    - ``id`` — stable string identifier; when omitted the host derives one
+      from the source path. Used for de-duplication, error attribution, and
+      conflict diagnostics.
+    - ``version`` — optional semantic version string, surfaced in
+      diagnostics and listings.
+    """
+
+    def register(self, surface: AddonSurface) -> None | Awaitable[None]:
+        """The addon's single entry point.
+
+        Invoked once at load time with a fresh :class:`AddonSurface`.
+        Synchronous or async; it records subscriptions / interceptors /
+        commands / tools onto the surface and returns nothing. Raising here is
+        captured as an :class:`AddonFault` and never crashes the host.
+
+        :param surface: the registration API scoped to this addon
+        """
+        ...
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RegisteredManifest:
+    """The contributions an addon recorded through its :class:`AddonSurface`,
+    read back by the host after ``register`` runs — the return value of
+    registration, not a mutation of shared state.
+
+    This is the declarative result the host folds into its single capability
+    registry: the event subscriptions, the tool interceptors, the slash
+    commands, and the tools the addon contributed. Each entry carries enough
+    provenance (:data:`AddonId`) to attribute a later failure back to its
+    origin addon. Frozen, with tuple fields, so a read-back snapshot cannot be
+    mutated by a stray later surface call (the TS ``Object.freeze`` parity).
+    """
+
+    # The addon these contributions belong to.
+    addon: AddonId
+    # Optional version copied from the addon manifest.
+    version: str | None = None
+    # Event subscriptions the addon registered via AddonSurface.on.
+    subscriptions: tuple[EventSubscription, ...] = ()
+    # Tool interceptors the addon registered via AddonSurface.intercept_tool.
+    interceptors: tuple[ToolInterceptor, ...] = ()
+    # Slash commands the addon registered via AddonSurface.add_command.
+    commands: tuple[AddonCommand, ...] = ()
+    # Tools the addon registered via AddonSurface.add_tool.
+    tools: tuple[AddonTool, ...] = ()
+
+
+def empty_manifest(addon: AddonId, version: str | None = None) -> RegisteredManifest:
+    """An immutable, empty :class:`RegisteredManifest` for a given addon — the
+    seed an accumulating surface starts from, and a safe value to fold for an
+    addon that registered nothing.
+
+    :param addon: the addon this empty manifest is attributed to
+    :param version: optional version to carry through
+    """
+    return RegisteredManifest(addon=addon, version=version)
+
+
+# ---------------------------------------------------------------------------
+# Event taxonomy & handlers
+# ---------------------------------------------------------------------------
+
+#: The colon-named event vocabulary an addon can hook.
+#:
+#: One unified taxonomy replaces the split between broad lifecycle events and
+#: low-level mutation hooks. Names are colon-segmented (``scope:phase``)
+#: rather than dot-segmented, and a single event can be observed,
+#: transformed, or gated depending on the handler kind an addon attaches:
+#:
+#: - ``session:start`` / ``session:end`` — a session opened / closed.
+#: - ``turn:start`` / ``turn:end``       — an assistant turn began / settled.
+#: - ``tool:before`` / ``tool:after``    — straddle a single tool execution.
+#: - ``chat:params``                     — the model request options are being built.
+#: - ``chat:message``                    — an assistant message was assembled.
+#: - ``shell:env``                       — the environment for a shell action is being prepared.
+#: - ``input:submit``                    — user input is entering the loop (transform/gate).
+#: - ``context:build``                   — the message context is being assembled for the model.
+#: - ``compact:build``                   — the condensed summary is being built.
+#: - ``compact:before``                  — the transcript is about to be condensed (gate).
+HookEvent: TypeAlias = Literal[
+    "session:start",
+    "session:end",
+    "turn:start",
+    "turn:end",
+    "tool:before",
+    "tool:after",
+    "chat:params",
+    "chat:message",
+    "shell:env",
+    "input:submit",
+    "context:build",
+    "compact:build",
+    "compact:before",
+]
+
+#: The three middleware kinds a hook handler can be.
+#:
+#: - ``observe``   — fire-and-forget: inspect the payload, return nothing.
+#:   Cannot alter or veto; errors are isolated and never affect the flow.
+#: - ``transform`` — return a replacement payload that the dispatcher threads
+#:   into the next handler (and ultimately back to the agent).
+#: - ``gate``      — return a :class:`GateDecision`; ``stop=True``
+#:   short-circuits the event (vetoing a tool call, a compaction, a turn).
+HookKind: TypeAlias = Literal["observe", "transform", "gate"]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class GateDecision:
+    """A veto/short-circuit decision returned by a ``gate`` handler.
+
+    ``stop=False`` (or an omitted return) lets the flow continue;
+    ``stop=True`` halts it, with the optional ``reason`` surfaced to the
+    user/logs. Replaces the scattered ``cancel``/``block``/``reason`` result
+    fields with one shape.
+    """
+
+    # Whether to halt the gated flow.
+    stop: bool
+    # Human-readable explanation when ``stop`` is True.
+    reason: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ObserveHandler:
+    """A fire-and-forget hook handler: ``run`` inspects the payload and
+    returns nothing (sync or async). It cannot alter the value or stop the
+    chain; a raise is isolated into an :class:`AddonFault` and the run
+    continues."""
+
+    run: Callable[[Any], None | Awaitable[None]]
+    #: Discriminant tag — the middleware contract ``run`` honors.
+    kind: ClassVar[Literal["observe"]] = "observe"
+
+
+@dataclass(frozen=True, slots=True)
+class TransformHandler:
+    """A payload-rewriting hook handler: ``run`` returns a (possibly new)
+    payload of the same shape, which the dispatcher threads into every later
+    handler. A raise is isolated and treated as a no-op (the prior payload is
+    kept)."""
+
+    run: Callable[[Any], Any | Awaitable[Any]]
+    #: Discriminant tag — the middleware contract ``run`` honors.
+    kind: ClassVar[Literal["transform"]] = "transform"
+
+
+@dataclass(frozen=True, slots=True)
+class GateHandler:
+    """A vetoing hook handler: ``run`` returns a :class:`GateDecision` (or
+    ``None`` for "no opinion"). The first ``stop=True`` short-circuits the
+    dispatch. A raise is isolated and the gate fails **open** (no veto)."""
+
+    run: Callable[[Any], GateDecision | None | Awaitable[GateDecision | None]]
+    #: Discriminant tag — the middleware contract ``run`` honors.
+    kind: ClassVar[Literal["gate"]] = "gate"
+
+
+#: The discriminated handler an addon attaches to a :data:`HookEvent`. The
+#: TS tagged union ``{ kind, run }`` ports as three frozen dataclasses with
+#: ``ClassVar`` literal tags; the dispatcher matches on ``handler.kind``.
+HookHandler: TypeAlias = ObserveHandler | TransformHandler | GateHandler
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class EventSubscription:
+    """One recorded subscription: the event an addon hooked, the handler it
+    attached, and the addon it came from.
+
+    Produced by :meth:`AddonSurface.on` and collected into
+    :attr:`RegisteredManifest.subscriptions`. The :class:`EventDispatcher`
+    folds all subscriptions for an event into an ordered middleware run.
+    """
+
+    # The event this subscription is bound to.
+    event: HookEvent
+    # The middleware handler invoked when the event fires.
+    handler: HookHandler
+    # The addon that registered this subscription, for error attribution.
+    addon: AddonId
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DispatchOutcome:
+    """The result of dispatching one event through the :class:`EventDispatcher`.
+
+    ``payload`` is the value after every ``transform`` handler has run
+    (identical to the input when none transformed it). ``gate``, when present,
+    is the first stopping :class:`GateDecision` a ``gate`` handler returned;
+    consumers treat ``gate.stop == True`` as a veto of whatever the event
+    guards.
+    """
+
+    # The payload after all transform middleware ran.
+    payload: Any
+    # The stopping gate decision, if any handler vetoed the flow.
+    gate: GateDecision | None = None
+
+
+class EventDispatcher(Protocol):
+    """The fan-out / transform / veto engine that runs an event's
+    :class:`EventSubscription` list in order.
+
+    Unifies what were previously separate "emit events" and "trigger hooks"
+    systems into one surface. Dispatching an event threads its payload through
+    every matching handler: ``observe`` handlers see it untouched,
+    ``transform`` handlers replace it, and a ``gate`` handler can stop the
+    chain. Errors from any handler are isolated into an :class:`AddonFault`
+    routed to listeners — never propagated into the agent loop.
+    """
+
+    async def dispatch(self, event: HookEvent, payload: Any) -> DispatchOutcome:
+        """Run an event through its subscribed middleware and return the
+        outcome. Order is registration order across all addons.
+
+        :param event: the event to dispatch
+        :param payload: the initial payload threaded through the chain
+        """
+        ...
+
+    def has(self, event: HookEvent) -> bool:
+        """Whether any addon has subscribed to the given event."""
+        ...
+
+    def on_fault(self, listener: AddonFaultListener) -> Callable[[], None]:
+        """Register a listener for per-handler :class:`AddonFault` reports.
+        Returns an unsubscribe."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Tool-boundary interceptors
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ToolEnterContext:
+    """The arguments a tool is about to be invoked with, passed to a
+    :class:`ToolInterceptor` ``enter`` stage so it can inspect or rewrite
+    them.
+
+    ``args`` is the decoded parameter mapping the agent built for this call;
+    a stage may return a replacement (or a :class:`GateDecision` to block the
+    call outright). Field names are this layer's own — not the framework's
+    tool-call schema.
+    """
+
+    # Wire-facing name of the tool being invoked.
+    tool: str
+    # Stable id correlating this enter with its matching exit.
+    call_id: str
+    # The decoded parameter mapping the tool will execute against.
+    args: Mapping[str, Any]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ToolExitContext:
+    """The result a tool produced (or the error it raised), passed to a
+    :class:`ToolInterceptor` ``exit`` stage so it can inspect or rewrite the
+    outcome.
+
+    Carries the framework :class:`AgentToolResult` on success; on failure
+    ``error`` is set and ``result`` is ``None``. An exit stage may return a
+    replacement result (e.g. to redact, annotate, or recover) which the chain
+    threads onward.
+    """
+
+    # Wire-facing name of the tool that ran.
+    tool: str
+    # Stable id correlating this exit with its enter.
+    call_id: str
+    # The result the tool produced, when it succeeded.
+    result: AgentToolResult | None = None
+    # The error the tool raised, when it failed.
+    error: object | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ArgsRewrite:
+    """An ``enter`` outcome that replaces the tool's decoded arguments.
+
+    The Python name for the TS anonymous ``{ args }`` shape: returning one
+    from an enter stage threads ``args`` into later stages and the real
+    execute.
+    """
+
+    # The replacement decoded parameter mapping.
+    args: Mapping[str, Any]
+
+
+#: What a :class:`ToolInterceptor` ``enter`` stage may return.
+#:
+#: - ``None`` — leave the args unchanged, continue the chain.
+#: - an :class:`ArgsRewrite` — replace the arguments.
+#: - a :class:`GateDecision` with ``stop=True`` — block the tool call.
+#:
+#: The chain also tolerates plain mappings carrying ``stop`` / ``args`` keys,
+#: mirroring the TS structural guards.
+EnterOutcome: TypeAlias = "None | ArgsRewrite | GateDecision"
+
+#: What a :class:`ToolInterceptor` ``exit`` stage may return.
+#:
+#: - ``None`` — leave the outcome unchanged, continue the chain.
+#: - a replacement :class:`AgentToolResult` — rewrite the tool's result.
+ExitOutcome: TypeAlias = "AgentToolResult | None"
+
+#: Pre-execution stage callback: inspect/rewrite args or block the call.
+EnterFn: TypeAlias = Callable[[ToolEnterContext], "EnterOutcome | Awaitable[EnterOutcome]"]
+
+#: Post-execution stage callback: inspect/rewrite the result.
+ExitFn: TypeAlias = Callable[[ToolExitContext], "ExitOutcome | Awaitable[ExitOutcome]"]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class InterceptorStage:
+    """The enter/exit pair an addon supplies to
+    :meth:`AddonSurface.intercept_tool` — the TS
+    ``Omit<ToolInterceptor, "match" | "addon">`` shape. The surface fills the
+    ``match`` and ``addon`` provenance fields around it.
+    """
+
+    # Pre-execution stage: inspect/rewrite args or block the call.
+    enter: EnterFn | None = None
+    # Post-execution stage: inspect/rewrite the result.
+    exit: ExitFn | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ToolInterceptor:
+    """A single stage in the tool-boundary :class:`InterceptorChain`.
+
+    Replaces the nested before/after wrapper with a composable stage that
+    straddles tool execution: ``enter`` runs before the tool (may rewrite args
+    or block), ``exit`` runs after (may rewrite the result). Either may be
+    omitted. The chain applies ``enter`` stages forward and ``exit`` stages in
+    reverse, so an addon loaded first wraps the outermost layer. Provenance is
+    carried for attribution.
+    """
+
+    # Which tools this interceptor applies to: an exact name, or "*" for all.
+    match: str
+    # The addon that registered this interceptor, for error attribution.
+    addon: AddonId
+    # Pre-execution stage: inspect/rewrite args or block the call.
+    enter: EnterFn | None = None
+    # Post-execution stage: inspect/rewrite the result.
+    exit: ExitFn | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class InterceptResult:
+    """The outcome of running a tool through the :class:`InterceptorChain`.
+
+    On a normal run ``result`` holds the (possibly rewritten) tool result.
+    When an ``enter`` stage blocked the call, ``blocked`` carries the
+    :class:`GateDecision` and ``result`` is ``None`` — the tool never
+    executed.
+    """
+
+    # The final tool result, when the call was allowed to run.
+    result: AgentToolResult | None = None
+    # The blocking decision, when an enter stage vetoed the call.
+    blocked: GateDecision | None = None
+
+
+#: The real tool invocation the chain folds around, called with the final args.
+ExecuteFn: TypeAlias = Callable[[Mapping[str, Any]], Awaitable[AgentToolResult]]
+
+
+class InterceptorChain(Protocol):
+    """The ordered pipeline that threads a single tool execution through every
+    matching :class:`ToolInterceptor`.
+
+    This is the tool-boundary integration point: it folds the registered
+    interceptors around the real tool ``execute``, running ``enter`` stages
+    forward (honoring an early block), executing the tool, then running
+    ``exit`` stages in reverse. It replaces both the old tool wrapper and the
+    dotted before/after hook trigger with one reduce.
+    """
+
+    async def run(self, ctx: ToolEnterContext, execute: ExecuteFn) -> InterceptResult:
+        """Run a tool's execution through the interceptor pipeline.
+
+        Applies matching ``enter`` stages (rewriting args, or
+        short-circuiting on a block), invokes ``execute`` with the final args,
+        then applies matching ``exit`` stages in reverse. A blocked enter
+        resolves without calling ``execute``.
+
+        :param ctx: the entering call context (tool, call_id, initial args)
+        :param execute: the real tool invocation, called with the final args
+        """
+        ...
+
+    def matches(self, tool: str) -> bool:
+        """Whether any interceptor matches the given tool name."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Capabilities an addon contributes
+# ---------------------------------------------------------------------------
+
+#: A tool an addon contributes to the session.
+#:
+#: Deliberately an alias of the framework :class:`AgentTool` rather than a
+#: fresh descriptor: the agent loop consumes ``AgentTool`` objects directly,
+#: so an addon's job is to *supply* one, not to wrap it. (The TS generics over
+#: ``TSchema``/details erase — the Python Protocol is structural and
+#: ungeneric, so heterogeneous addon tools already coexist in one tuple.)
+AddonTool: TypeAlias = AgentTool
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ExecOutcome:
+    """The captured outcome of a :attr:`FrameworkHandles.exec` invocation.
+
+    A small, framework-agnostic shape: the process's standard streams and
+    exit code, so an addon can branch on success without parsing a richer
+    result.
+    """
+
+    # Captured standard output.
+    stdout: str
+    # Captured standard error.
+    stderr: str
+    # Process exit code (0 on success), or None if terminated by signal.
+    code: int | None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class FrameworkHandles:
+    """The bag of framework handles an addon may reach through — exposed on
+    the :class:`AddonSurface` and threaded into a :class:`CommandContext`.
+
+    These are the controlled callbacks an addon uses to act on the session
+    (instead of importing and mutating agent internals). Every handle is
+    optional: a print/JSON run mode supplies fewer than an interactive TUI.
+    The shapes are intentionally minimal — richer wiring is the host's
+    concern, not the contract's.
+    """
+
+    # Inject an assistant-visible message into the active turn.
+    send_message: Callable[[str], None | Awaitable[None]] | None = None
+    # Switch the active model by canonical id.
+    set_model: Callable[[str], None | Awaitable[None]] | None = None
+    # Adjust the reasoning-effort level for subsequent turns.
+    set_thinking: Callable[[ThinkingLevel], None] | None = None
+    # Render an ephemeral TUI component (absent outside interactive mode).
+    render: Callable[[Component], None] | None = None
+    # Run a shell command and resolve its captured output.
+    exec: Callable[[str], Awaitable[ExecOutcome]] | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CommandContext:
+    """Where a slash :class:`AddonCommand` runs and what it can reach.
+
+    Handed to a command handler at invocation time: the parsed argument
+    string, the workspace root, and a small set of framework handles (so the
+    command can send a message, switch the model, or drive the TUI) without
+    the addon holding global state. Optional handles are absent in
+    non-interactive run modes.
+    """
+
+    # The raw argument string following the command name.
+    args: str
+    # Absolute working directory the session is scoped to.
+    cwd: str
+    # Framework handles the command may use (model switch, message send, TUI).
+    handles: FrameworkHandles
+
+
+#: A command's entry point — runs against a :class:`CommandContext` and
+#: returns nothing (sync or async). Deliberately a DIFFERENT shape from the
+#: console's ``SlashCommand`` (which returns a ``SlashOutcome``): addon
+#: commands describe an effect, not a console state transition.
+CommandRun: TypeAlias = Callable[[CommandContext], None | Awaitable[None]]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CommandSpec:
+    """The definition an addon supplies to :meth:`AddonSurface.add_command` —
+    the TS ``Omit<AddonCommand, "name" | "addon">`` shape. The surface fills
+    the ``name`` and ``addon`` provenance fields around it.
+    """
+
+    # One-line description for the command palette / help listing.
+    summary: str
+    # Execute the command against its invocation context.
+    run: CommandRun
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AddonCommand:
+    """A slash command an addon contributes.
+
+    The model never calls a command — the user does, by name. ``name`` is the
+    invocation token (without a leading slash), ``summary`` lines it in help,
+    and ``run`` executes it against a :class:`CommandContext`. Provenance is
+    carried for conflict diagnostics when two addons claim the same name.
+    """
+
+    # Invocation token (no leading slash), unique across loaded addons.
+    name: str
+    # One-line description for the command palette / help listing.
+    summary: str
+    # The addon that registered this command, for conflict attribution.
+    addon: AddonId
+    # Execute the command against its invocation context.
+    run: CommandRun
+
+
+# ---------------------------------------------------------------------------
+# The addon registration surface
+# ---------------------------------------------------------------------------
+
+
+class AddonSurface(Protocol):
+    """The registration API a single addon receives in its
+    :meth:`AddonManifest.register` entry point.
+
+    Each method *records* a contribution rather than mutating global agent
+    state: the host hands a fresh surface to each addon, the addon calls
+    these to describe what it wants, and the host reads the accumulated
+    :class:`RegisteredManifest` back out via :meth:`manifest`. Read-only
+    access to framework handles is provided through :attr:`handles` for the
+    rare case an addon must act at registration time.
+    """
+
+    @property
+    def id(self) -> AddonId:
+        """The id of the addon this surface is scoped to."""
+        ...
+
+    @property
+    def handles(self) -> FrameworkHandles:
+        """Read-only access to the framework handles an addon may act through
+        at registration time. The same shape is threaded into command
+        contexts."""
+        ...
+
+    def on(self, event: HookEvent, handler: HookHandler) -> None:
+        """Subscribe a :data:`HookHandler` to a colon-named :data:`HookEvent`.
+
+        The handler's ``kind`` selects whether it observes, transforms, or
+        gates the event. Records an :class:`EventSubscription`.
+
+        :param event: the event to hook
+        :param handler: the observe/transform/gate middleware
+        """
+        ...
+
+    def intercept_tool(self, name: str, stage: InterceptorStage) -> None:
+        """Register a :class:`ToolInterceptor` for the tool-boundary pipeline.
+
+        :param name: the tool name to intercept, or ``"*"`` for every tool
+        :param stage: the enter/exit stage (its ``match``/``addon`` are
+            filled by the surface)
+        """
+        ...
+
+    def add_command(self, name: str, spec: CommandSpec) -> None:
+        """Register a slash command.
+
+        :param name: invocation token (no leading slash)
+        :param spec: the command definition (its ``name``/``addon`` are
+            filled by the surface)
+        """
+        ...
+
+    def add_tool(self, card: AddonTool) -> None:
+        """Register an LLM-callable tool.
+
+        :param card: the framework :data:`AddonTool` to add to the session's deck
+        """
+        ...
+
+    def manifest(self) -> RegisteredManifest:
+        """The accumulated :class:`RegisteredManifest` of everything recorded
+        so far.
+
+        The host reads this after ``register`` settles to fold the addon's
+        contributions into its single registry. Recording-then-returning, not
+        mutating-global-state, is the whole point of the surface.
+        """
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Module loading & discovery
+# ---------------------------------------------------------------------------
+
+
+class ModuleLoader(Protocol):
+    """The injectable seam that turns a source path into an
+    :class:`AddonManifest`.
+
+    The default implementation is importlib-backed (``loader.py``): it
+    spec-loads the ``.py`` entry module and accepts a module-level
+    ``register`` or a ``manifest``/``default`` object exposing one. A test
+    injects a fake that returns a scripted manifest with no real import and
+    no filesystem — the host code never assumes a concrete loader, only this
+    interface.
+    """
+
+    async def load(self, path: str) -> AddonManifest:
+        """Resolve and load the addon module at ``path``, returning its
+        :class:`AddonManifest`.
+
+        Implementations isolate import failures and surface them as a raised
+        exception (the host converts the raise into an :class:`AddonFault`).
+
+        :param path: absolute path to the addon's entry module
+        """
+        ...
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AddonDiscovery:
+    """Configuration for discovering addon source modules.
+
+    Discovery walks a set of roots — by default the per-workspace
+    ``.indus/addons`` directory — plus any explicitly configured paths,
+    yielding the entry modules the :class:`ModuleLoader` will load. The
+    directory name and fields are this app's own vocabulary.
+    """
+
+    # The workspace root whose `.indus/addons` directory is scanned. When
+    # None, only `explicit_paths` are used.
+    workspace: str | None = None
+    # The directory (relative to `workspace`) addons are discovered in.
+    # Defaults to ADDONS_DIR.
+    dir: str | None = None
+    # Additional absolute paths to addon entry modules, loaded as-is.
+    explicit_paths: Sequence[str] | None = None
+
+
+#: The default per-workspace directory addons are discovered in, relative to
+#: the workspace root. This app's own vocabulary — kept verbatim from the TS
+#: lineage (``.indus``, *not* ``.indusagi``/``.pindusagi``).
+ADDONS_DIR = ".indus/addons"
+
+# Port note: the TS ``ADDON_MANIFEST_FIELD`` (``"indusAddon"`` in a package
+# directory's package.json) is DROPPED with the Node packaging machinery. The
+# locked Python convention (plan §3) recognises exactly two shapes under the
+# addons dir: bare ``*.py`` files and directories holding an ``__init__.py``.
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AddonSource:
+    """One discovered addon source the loader will resolve.
+
+    Produced by discovery and consumed by the :class:`ModuleLoader`: the
+    absolute entry ``path`` and a stable :data:`AddonId` derived for it (from
+    the declared id or the path). Distinct from the loaded
+    :class:`AddonManifest` — a source is "where", a manifest is "what".
+    """
+
+    # Stable id assigned to this source for attribution and de-duplication.
+    id: AddonId
+    # Absolute path to the addon's entry module.
+    path: str
+
+
+# ---------------------------------------------------------------------------
+# Faults
+# ---------------------------------------------------------------------------
+
+#: The closed set of failure categories the addon system can surface.
+#:
+#: - ``load``     — resolving/importing an addon module failed.
+#: - ``register`` — an addon's ``register`` entry point raised.
+#: - ``handler``  — an event handler or interceptor stage raised at runtime.
+#: - ``command``  — a slash command handler raised.
+#: - ``conflict`` — two addons claimed the same command name (or tool id).
+AddonFaultKind: TypeAlias = Literal["load", "register", "handler", "command", "conflict"]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AddonFault:
+    """A typed, discriminated failure raised by the addon system.
+
+    ``kind`` selects the category; ``message`` is a human-readable summary;
+    ``addon`` (when known) attributes it to the originating addon; the
+    optional ``cause`` carries the underlying error for logging without
+    forcing consumers to parse the message. Construct one with
+    :func:`addon_fault`.
+
+    Port note: faults are *routed to listeners*, never raised, so the shape
+    stays a frozen record (not an ``Exception`` subclass) exactly as in TS.
+    """
+
+    # Failure category — the discriminant consumers switch on.
+    kind: AddonFaultKind
+    # Human-readable, single-line summary of what went wrong.
+    message: str
+    # The addon the fault is attributed to, when known.
+    addon: AddonId | None = None
+    # Underlying error or structured detail, if any.
+    cause: object | None = None
+
+
+#: A subscriber for :class:`AddonFault` reports routed off the dispatcher/host.
+AddonFaultListener: TypeAlias = Callable[[AddonFault], None]
+
+
+def addon_fault(
+    kind: AddonFaultKind,
+    message: str,
+    *,
+    addon: AddonId | None = None,
+    cause: object | None = None,
+) -> AddonFault:
+    """Construct an :class:`AddonFault`. The single sanctioned minter, so the
+    shape stays uniform across every producer.
+
+    :param kind: the failure category
+    :param message: a human-readable, single-line summary
+    :param addon: optional originating-addon provenance
+    :param cause: optional underlying error or structured detail
+    """
+    return AddonFault(kind=kind, message=message, addon=addon, cause=cause)