indusagi-coding-agent 0.1.59 → 0.1.61

package/dist/types/addons/dispatch/event-dispatcher.d.ts

@@ -0,0 +1,140 @@
+/**
+ * EventDispatcher — the single fan-out / transform / veto engine for the unified
+ * colon-named event taxonomy.
+ *
+ * One {@link AddonEventDispatcher} replaces what were previously two parallel
+ * systems (a broad "emit lifecycle events" bus and a low-level "trigger mutation
+ * hooks" runner): every {@link 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 throw is isolated into an {@link 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 {@link DispatchOutcome.payload}. A
+ *                   transform that throws 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 {@link GateDecision}; the first
+ *                   `{ stop: true }` short-circuits the run and is surfaced as
+ *                   {@link DispatchOutcome.gate}. A gate that throws 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 {@link 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 construction by
+ * scanning a small {@link EventTrait} table keyed by {@link HookEvent}; an event
+ * with the `guards` trait is reserved. {@link 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.
+ */
+import type { AddonFaultListener, AddonId, DispatchOutcome, EventDispatcher, EventSubscription, HookEvent, HookHandler } from "../contract";
+/**
+ * The concrete {@link EventDispatcher}: one engine per session, fed the folded
+ * {@link EventSubscription}s of every loaded addon.
+ *
+ * Build one with {@link AddonEventDispatcher.from} over the host's collected
+ * subscriptions (registration order preserved), then call
+ * {@link AddonEventDispatcher.dispatch} per event. Handler faults are routed to
+ * {@link AddonEventDispatcher.onFault} listeners and never propagate into the
+ * agent loop.
+ */
+export declare class AddonEventDispatcher implements EventDispatcher {
+    /** Subscriptions grouped by event, each list in registration order. */
+    private readonly byEvent;
+    /** Live set of fault listeners, in registration order. */
+    private readonly faultListeners;
+    /**
+     * @param subscriptions every addon's recorded subscriptions, in the order the
+     *   host folded them (registration order = dispatch order)
+     */
+    constructor(subscriptions: readonly EventSubscription[]);
+    /**
+     * Build a dispatcher from a flat list of subscriptions.
+     *
+     * A thin alias for the constructor that reads well at the host's fold site:
+     * `AddonEventDispatcher.from(allSubscriptions)`.
+     *
+     * @param subscriptions the folded subscriptions across all addons
+     */
+    static from(subscriptions: readonly EventSubscription[]): AddonEventDispatcher;
+    /**
+     * 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.
+     */
+    get reserved(): ReadonlySet<HookEvent>;
+    /**
+     * 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 {@link DispatchOutcome} carries the final (possibly transformed)
+     * payload and, when a gate stopped the run, its decision. A handler that throws
+     * is isolated into an {@link 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 {@link DispatchOutcome.gate} for any event; the
+     * {@link 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
+     */
+    dispatch<TPayload>(event: HookEvent, payload: TPayload): Promise<DispatchOutcome<TPayload>>;
+    /** Whether any addon has subscribed to the given event. */
+    has(event: HookEvent): boolean;
+    /**
+     * Register a listener for per-handler {@link AddonFault}s.
+     *
+     * Returns an idempotent unsubscribe thunk; registering the same listener twice
+     * collapses to one slot.
+     *
+     * @param listener the fault sink
+     */
+    onFault(listener: AddonFaultListener): () => void;
+    /**
+     * Invoke one subscription's handler against the current payload, isolating any
+     * throw, and return a gate decision when the handler is a gate (otherwise
+     * `undefined`).
+     *
+     * `observe` returns nothing and the payload is left untouched; `transform`
+     * folds its return value in via `commit`; `gate` yields its decision. A throw
+     * from any kind is converted to an {@link AddonFault} routed to listeners and
+     * then swallowed — observe/transform continue with the prior payload, gate
+     * fails open (returns no veto).
+     */
+    private run;
+    /** Route a fault to every listener, guarding each listener against its own throw. */
+    private report;
+}
+/**
+ * Record one event subscription, stamping it with the owning addon — the shape
+ * the {@link 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
+ */
+export declare function subscription(addon: AddonId, event: HookEvent, handler: HookHandler): EventSubscription;

package/dist/types/addons/dispatch/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Dispatch subsystem — public barrel.
+ *
+ * The unified hook + tool-interception runtime, written against the frozen
+ * {@link module:../contract} surface:
+ *
+ *   - {@link AddonEventDispatcher} — the single fan-out / transform / veto engine
+ *     for the colon-named {@link HookEvent} taxonomy. Folds every addon's
+ *     {@link EventSubscription}s 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 rather than a literal.
+ *   - {@link AddonInterceptorChain} — the composable tool-call boundary. Folds
+ *     every addon's {@link 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 {@link AddonFault}s routed to listeners
+ * so a misbehaving addon never crashes the agent loop. The `subscription` and
+ * `interceptor` helpers mint the contract's recorded shapes for hosts/tests that
+ * assemble them outside the full surface builder.
+ */
+export { AddonEventDispatcher, subscription } from "./event-dispatcher";
+export { AddonInterceptorChain, interceptor } from "./tool-interceptor";

package/dist/types/addons/dispatch/tool-interceptor.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 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
+ * {@link 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
+ *     `{ args }`), or block the call outright (return a {@link 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 {@link AgentTool}-style `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 {@link AgentToolResult}); the
+ *     rewritten result threads into the next (earlier-registered) stage's exit.
+ *
+ * Fault isolation: a throw from any `enter`/`exit` stage is converted to an
+ * {@link 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 {@link ToolExitContext.error}) and then
+ * re-thrown 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). {@link AddonInterceptorChain.matches} answers whether any stage
+ * applies to a tool, letting the host skip the pipeline entirely for tools no
+ * addon touches.
+ */
+import type { AddonFaultListener, AddonId, AgentToolResult, InterceptResult, InterceptorChain, ToolEnterContext, ToolInterceptor } from "../contract";
+/** The real tool invocation the chain folds around, called with the final args. */
+type Execute = (args: Readonly<Record<string, unknown>>) => Promise<AgentToolResult<unknown>>;
+/**
+ * The concrete {@link InterceptorChain}: an ordered set of {@link ToolInterceptor}
+ * stages folded around one tool execution.
+ *
+ * Build one with {@link AddonInterceptorChain.from} over the host's collected
+ * interceptors (registration order preserved). Per tool call, {@link 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 {@link onFault} listeners and never crash the call.
+ */
+export declare class AddonInterceptorChain implements InterceptorChain {
+    /** Every registered interceptor, in registration order. */
+    private readonly interceptors;
+    /** Live set of fault listeners, in registration order. */
+    private readonly faultListeners;
+    /**
+     * @param interceptors every addon's recorded interceptors, in the order the
+     *   host folded them (registration order = enter order; reverse = exit order)
+     */
+    constructor(interceptors: readonly ToolInterceptor[]);
+    /**
+     * Build a chain from a flat list of interceptors.
+     *
+     * A thin alias for the constructor that reads well at the host's fold site:
+     * `AddonInterceptorChain.from(allInterceptors)`.
+     *
+     * @param interceptors the folded interceptors across all addons
+     */
+    static from(interceptors: readonly ToolInterceptor[]): AddonInterceptorChain;
+    /**
+     * 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 }` and never calls `execute`. When no stage
+     * matches, `execute` runs directly with the original args.
+     *
+     * If the real tool throws, the error is offered to the matching `exit` stages;
+     * an exit stage may return a replacement result to recover, otherwise the error
+     * is re-thrown to the caller after the exit stages have observed it.
+     *
+     * @param ctx     the entering call context (tool, callId, initial args)
+     * @param execute the real tool invocation, called with the final args
+     */
+    run(ctx: ToolEnterContext, execute: Execute): Promise<InterceptResult>;
+    /** Whether any interceptor matches the given tool name. */
+    matches(tool: string): boolean;
+    /**
+     * Register a listener for per-stage {@link AddonFault}s.
+     *
+     * Returns an idempotent unsubscribe thunk; registering the same listener twice
+     * collapses to one slot.
+     *
+     * @param listener the fault sink
+     */
+    onFault(listener: AddonFaultListener): () => void;
+    /**
+     * Apply the matching stages' `enter` in forward order, folding args rewrites
+     * and short-circuiting on the first block. A stage that throws is isolated and
+     * skipped (the prior args are kept, no block).
+     */
+    private applyEnter;
+    /**
+     * 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 `undefined` (the caller keeps the original result/error). A
+     * stage that throws is isolated and skipped.
+     */
+    private applyExit;
+    /** Route a fault to every listener, guarding each listener against its own throw. */
+    private report;
+}
+/**
+ * Record one tool interceptor, stamping it with the matched tool and owning
+ * addon — the shape the {@link 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
+ */
+export declare function interceptor(addon: AddonId, match: string | "*", stage: Omit<ToolInterceptor, "match" | "addon">): ToolInterceptor;
+export {};

package/dist/types/addons/host.d.ts

@@ -0,0 +1,246 @@
+/**
+ * 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
+ * {@link ModuleLoader} (discovery + load), the per-addon {@link AddonSurface}
+ * recorder, the {@link EventDispatcher} (observe / transform / gate), and the
+ * {@link InterceptorChain} (tool-boundary enter / exit) into one coherent host.
+ * Its job is purely *folding*: read every addon's recorded
+ * {@link 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
+ *      {@link AddonManifest}. A load failure is isolated into an
+ *      {@link 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 {@link FrameworkHandles}, then invoke the addon's `register` against
+ *      it. A throw is isolated as a `register` fault and the addon contributes
+ *      nothing.
+ *   3. **Fold.** Read the surface's {@link 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 {@link AddonHost.loadAll} resolves, the host exposes:
+ *   - {@link AddonHost.dispatch} — the bound {@link EventDispatcher} over every
+ *     addon's subscriptions;
+ *   - {@link AddonHost.interceptors} — the {@link InterceptorChain} over every
+ *     addon's tool interceptors;
+ *   - {@link AddonHost.commands} / {@link AddonHost.tools} — the collected,
+ *     conflict-resolved capabilities;
+ *   - {@link AddonHost.onFault} — a single fault stream fanning out load /
+ *     register / conflict faults plus the runtime handler faults the dispatcher
+ *     and chain raise.
+ *
+ * The loader stays **injectable**: {@link AddonHostDeps.loader} defaults to the
+ * jiti-backed {@link createJitiLoader}, but a test injects a scripted fake that
+ * returns manifests with no real jiti and no disk — the host code only ever sees
+ * the {@link ModuleLoader} interface.
+ */
+import { type AddonCommand, type AddonDiscovery, type AddonFaultListener, type AddonId, type AddonSource, type AddonTool, type EventDispatcher, type EventSubscription, type FrameworkHandles, type InterceptorChain, type ModuleLoader, type ToolInterceptor } from "./contract";
+/**
+ * The injectable collaborators an {@link AddonHost} is built from.
+ *
+ * Every field is optional with a live default, so production code calls
+ * {@link createAddonHost} with nothing (or just {@link AddonHostDeps.handles})
+ * and a test overrides exactly the seam it needs — almost always
+ * {@link AddonHostDeps.loader} with a scripted fake.
+ */
+export interface AddonHostDeps {
+    /**
+     * The module loader turning a source path into an {@link AddonManifest}.
+     * Defaults to the jiti-backed {@link createJitiLoader}; a test injects a fake.
+     */
+    readonly loader?: ModuleLoader;
+    /**
+     * 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).
+     */
+    readonly handles?: FrameworkHandles;
+    /**
+     * Override how the {@link EventDispatcher} is built from the folded
+     * subscriptions. Defaults to {@link AddonEventDispatcher.from}; injectable so a
+     * test can substitute a custom dispatcher.
+     */
+    readonly dispatcher?: (subscriptions: readonly EventSubscription[]) => EventDispatcher;
+    /**
+     * Override how the {@link InterceptorChain} is built from the folded
+     * interceptors. Defaults to {@link AddonInterceptorChain.from}.
+     */
+    readonly chain?: (interceptors: readonly ToolInterceptor[]) => InterceptorChain;
+    /**
+     * The reserved core action names addon commands may not shadow. Defaults to
+     * {@link RESERVED_ACTION_NAMES}; injectable so a host with a different core
+     * command set can supply its own.
+     */
+    readonly reservedActions?: Iterable<string>;
+}
+/**
+ * The merged, conflict-resolved registry the host accumulates while folding
+ * every addon's {@link RegisteredManifest}.
+ *
+ * One flat list per contribution stream, in load order. The host builds the
+ * dispatch and interception runtimes from {@link AddonRegistry.subscriptions} and
+ * {@link AddonRegistry.interceptors}; {@link AddonRegistry.commands} and
+ * {@link AddonRegistry.tools} are the collected capabilities, already de-duped
+ * against earlier claimants and the reserved set.
+ */
+export interface AddonRegistry {
+    /** Every addon's event subscriptions, in load (registration) order. */
+    readonly subscriptions: readonly EventSubscription[];
+    /** Every addon's tool interceptors, in load order. */
+    readonly interceptors: readonly ToolInterceptor[];
+    /** The collected, name-deduped slash commands. */
+    readonly commands: readonly AddonCommand[];
+    /** The collected, name-deduped contributed tools. */
+    readonly tools: readonly AddonTool[];
+}
+/**
+ * The fully-wired addon runtime {@link AddonHost.loadAll} produces.
+ *
+ * Exposes the dispatch engine, the interceptor chain, the collected
+ * capabilities, the loaded source manifests (for diagnostics/listing), and a
+ * single fault stream. Consumers wire {@link dispatch} into the agent's event
+ * points, {@link interceptors} into the tool boundary, and surface
+ * {@link commands} / {@link tools} into the session.
+ */
+export interface AddonSurfaceBundle {
+    /** The event dispatcher over every loaded addon's subscriptions. */
+    readonly dispatch: EventDispatcher;
+    /** The tool-boundary chain over every loaded addon's interceptors. */
+    readonly interceptors: InterceptorChain;
+    /** The collected, conflict-resolved slash commands. */
+    readonly commands: readonly AddonCommand[];
+    /** The collected, conflict-resolved contributed tools. */
+    readonly tools: readonly AddonTool[];
+    /** The ids of the addons that loaded and registered successfully, in order. */
+    readonly loaded: readonly AddonId[];
+}
+/**
+ * The addon host: discovers, loads, registers, and folds addons into a single
+ * wired runtime.
+ *
+ * Build one with {@link createAddonHost} (defaults wire the live runtime). Call
+ * {@link loadAll} once with a discovery directory (or pass an explicit
+ * {@link AddonDiscovery}) to populate the host, then read {@link dispatch},
+ * {@link interceptors}, {@link commands}, and {@link tools}. Faults raised during
+ * loading — and the runtime handler faults the dispatcher/chain raise — fan out
+ * to {@link onFault} listeners.
+ */
+export declare class AddonHost {
+    /** Live set of fault listeners, in registration order. */
+    private readonly faultListeners;
+    /** The reserved core action names addon commands may not shadow. */
+    private readonly reserved;
+    /** Accumulated subscriptions across every folded addon, in load order. */
+    private readonly subscriptions;
+    /** Accumulated interceptors across every folded addon, in load order. */
+    private readonly interceptors;
+    /** Accumulated, name-deduped commands. */
+    private readonly commands;
+    /** Accumulated, name-deduped tools. */
+    private readonly tools;
+    /** The command names already claimed (reserved + earlier addon commands). */
+    private readonly claimedCommands;
+    /** The tool names already claimed by earlier addons. */
+    private readonly claimedTools;
+    /** The ids of addons that loaded and registered successfully, in order. */
+    private readonly loaded;
+    private readonly loader;
+    private readonly handles;
+    private readonly buildDispatcher;
+    private readonly buildChain;
+    /**
+     * @param deps the injectable collaborators (loader, handles, dispatcher/chain
+     *   factories, reserved action names) — each with a live default
+     */
+    constructor(deps?: AddonHostDeps);
+    /**
+     * Register a listener for every {@link 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 {@link loadAll} captures load-time faults; the dispatcher
+     * and chain built by {@link loadAll} are wired to this same sink so a later
+     * dispatch fault reaches the same listeners.
+     *
+     * @param listener the fault sink
+     */
+    onFault(listener: AddonFaultListener): () => void;
+    /**
+     * Discover, load, register, and fold every addon under a directory (or a full
+     * {@link AddonDiscovery} config), then build and return the wired runtime.
+     *
+     * A bare string is treated as the workspace whose `.indus/addons` directory is
+     * scanned; an {@link AddonDiscovery} is passed through to {@link discoverSources}
+     * unchanged. Each discovered source is loaded through the injected loader and
+     * folded; failures are isolated into faults. The returned
+     * {@link 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
+     */
+    loadAll(where: string | AddonDiscovery): Promise<AddonSurfaceBundle>;
+    /**
+     * Load, register, and fold a single already-discovered {@link 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)
+     */
+    loadOne(source: AddonSource): Promise<void>;
+    /**
+     * Build the {@link 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.
+     */
+    private bundle;
+    /** The merged, conflict-resolved registry accumulated so far. */
+    get registry(): AddonRegistry;
+    /**
+     * Fold one addon's recorded {@link 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.
+     */
+    private fold;
+    /**
+     * Forward a built runtime's fault stream into the host's listeners, when the
+     * runtime exposes one.
+     *
+     * The contract's {@link EventDispatcher} always declares `onFault`; the
+     * {@link InterceptorChain} interface does not, though the default
+     * {@link 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.
+     */
+    private wireFaults;
+    /** Route a fault to every listener, guarding each listener against its own throw. */
+    private report;
+}
+/**
+ * Construct an {@link AddonHost} with the given (all-optional) dependencies.
+ *
+ * The single sanctioned entry point: production code calls it with nothing (or
+ * just {@link AddonHostDeps.handles}) and gets the jiti-backed loader and the
+ * default dispatcher/chain factories; a test injects a fake {@link ModuleLoader}
+ * to exercise the full fold-and-wire pipeline with no real jiti or disk.
+ *
+ * @param deps the injectable collaborators (loader, handles, factories, reserved)
+ */
+export declare function createAddonHost(deps?: AddonHostDeps): AddonHost;

package/dist/types/addons/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Addons subsystem — public barrel.
+ *
+ * Re-exports the FROZEN third-party customization contract: the
+ * {@link AddonManifest} an addon module returns and the {@link AddonSurface} its
+ * `register` entry point receives, the colon-named {@link HookEvent} taxonomy
+ * with its observe/transform/gate {@link HookHandler} middleware and the
+ * {@link EventDispatcher} that runs them, the tool-boundary {@link ToolInterceptor}
+ * stages and the {@link InterceptorChain} pipeline that folds them around a tool
+ * execution, the capabilities an addon contributes ({@link AddonTool},
+ * {@link AddonCommand}), the injectable {@link ModuleLoader} + {@link AddonDiscovery}
+ * loading seam, and the typed {@link AddonFault}.
+ *
+ * Behavior modules (the jiti-backed sandbox loader, the capability registry, the
+ * surface builder, the event dispatcher, and the interceptor chain) are added to
+ * this barrel as they land; consumers import the addon surface from
+ * `src/addons` rather than reaching into individual modules.
+ */
+export type { BundledNamespace, AddonId, AddonManifest, RegisteredManifest, HookEvent, HookKind, GateDecision, HookHandler, EventSubscription, EventDispatcher, DispatchOutcome, ToolEnterContext, ToolExitContext, EnterOutcome, ExitOutcome, ToolInterceptor, InterceptorChain, InterceptResult, AddonTool, CommandContext, AddonCommand, FrameworkHandles, ExecOutcome, AddonSurface, ModuleLoader, AddonDiscovery, AddonSource, AddonFaultKind, AddonFault, AddonFaultListener, AgentMessage, AgentTool, AgentToolResult, ThinkingLevel, Model, Component, KeyId, TSchema, Static, } from "./contract";
+export { BUNDLED_NAMESPACES, ADDONS_DIR, ADDON_MANIFEST_FIELD, addonId, emptyManifest, addonFault, } from "./contract";
+/**
+ * Addon sandbox — the single jiti-backed {@link ModuleLoader}: bridges the
+ * framework {@link BUNDLED_NAMESPACES} into a loaded addon (virtual modules in a
+ * compiled binary, resolved aliases under Node) and turns a path into its
+ * {@link AddonManifest}. Injectable — tests supply a fake of the same interface.
+ */
+export { createJitiLoader, scrubInvisible, expandPath, resolvePath, type JitiLoaderOptions, } from "./sandbox";
+/**
+ * Addon discovery — scan a `.indus/addons` directory for entry modules and fold
+ * an {@link AddonDiscovery} config into id-stamped {@link AddonSource}s.
+ */
+export { discoverAddons, discoverSources } from "./manifest";
+/**
+ * Dispatch runtime — the unified {@link EventDispatcher} (observe / transform /
+ * gate) and the tool-boundary {@link InterceptorChain}, plus the `subscription`
+ * and `interceptor` minters for assembling their recorded shapes by hand.
+ */
+export { AddonEventDispatcher, AddonInterceptorChain, subscription, interceptor, } from "./dispatch/index";
+/**
+ * Addon surface — the per-addon recording {@link AddonSurface} the host hands to
+ * an addon's `register`; accumulates contributions and reads them back as a
+ * {@link RegisteredManifest}.
+ */
+export { createSurface } from "./surface";
+/**
+ * Addon host — the assembly point: discover + load (injectable loader), register
+ * each addon against a fresh surface, fold every {@link RegisteredManifest} into
+ * one registry, and wire the dispatch engine + interceptor chain + collected
+ * commands/tools.
+ */
+export { createAddonHost, AddonHost, type AddonHostDeps, type AddonRegistry, type AddonSurfaceBundle, } from "./host";

package/dist/types/addons/manifest.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Addon discovery — scanning a workspace for addon entry modules.
+ *
+ * Where {@link module:sandbox} answers "how do I load *this* path", this module
+ * answers "*which* paths are there to load". It walks the per-workspace
+ * {@link ADDONS_DIR} (`.indus/addons`) one level deep and yields the absolute
+ * entry-module paths a {@link ModuleLoader} will resolve. Three candidate shapes
+ * are recognised inside that directory:
+ *
+ *   1. **A bare module file** — `something.ts` / `.js` (and the ESM/TS variants)
+ *      sitting directly in the addons directory *is* its own entry.
+ *   2. **A package directory with a manifest field** — a subdirectory whose
+ *      `package.json` carries an {@link ADDON_MANIFEST_FIELD} (`indusAddon`)
+ *      pointing at the entry module relative to that subdirectory.
+ *   3. **A package directory with a conventional index** — a subdirectory with no
+ *      manifest field falls back to an `index.*` entry if one exists.
+ *
+ * Discovery is filesystem-only and never imports a module: it produces *paths*,
+ * leaving the actual jiti import to the loader. Hidden entries (dot-files and
+ * dot-directories) are skipped so editor and VCS detritus is never treated as an
+ * addon. The scan is resilient: a missing addons directory yields an empty list
+ * rather than an error, and an unreadable package directory is silently skipped.
+ *
+ * Two entry points are exposed:
+ *   - {@link discoverAddons} — the low-level "scan one directory, return paths".
+ *   - {@link discoverSources} — folds an {@link AddonDiscovery} config (workspace +
+ *     explicit paths) into a deduplicated, id-stamped {@link AddonSource} list the
+ *     host feeds to the loader.
+ */
+import { type AddonDiscovery, type AddonSource } from "./contract";
+/**
+ * Scan one addons directory and return the absolute entry-module paths it holds.
+ *
+ * Walks `dir` a single level deep, resolving each non-hidden child through
+ * {@link resolveTopLevelEntry}. The result is sorted by path for a stable,
+ * deterministic load order, and is empty when `dir` is missing or holds no
+ * recognised addon. This is the low-level primitive; {@link discoverSources}
+ * layers the config (workspace + explicit paths) and id-stamping on top.
+ *
+ * @param dir absolute path to an addons directory (typically `<workspace>/.indus/addons`)
+ */
+export declare function discoverAddons(dir: string): string[];
+/**
+ * Fold an {@link AddonDiscovery} config into the ordered, deduplicated list of
+ * {@link AddonSource}s the host hands to the loader.
+ *
+ * Concatenates, in this order: the entries discovered under the workspace's
+ * addons directory (when a `workspace` is given), then any {@link
+ * AddonDiscovery.explicitPaths} (resolved to absolute paths). Duplicate paths are
+ * collapsed — the first occurrence wins — and each surviving path is stamped with
+ * a derived {@link AddonId}. Discovery touches the filesystem only to enumerate;
+ * it never imports a module.
+ *
+ * @param discovery the discovery configuration (workspace, dir, explicit paths)
+ */
+export declare function discoverSources(discovery: AddonDiscovery): AddonSource[];