@axiom-lattice/gateway 2.1.88 → 2.1.90

package/dist/index.d.mts

@@ -62,19 +62,81 @@ interface MessageContext {
 }
 type MessageMiddleware = (ctx: MessageContext, next: () => Promise<void>) => Promise<void>;
 
+/**
+ * Configuration for {@link MessageRouter}.
+ *
+ * @param middlewares - Ordered middleware chain executed before dispatch
+ * @param bindingRegistry - Resolves sender-to-agent bindings
+ * @param adapterRegistry - Registry of {@link ChannelAdapter} implementations
+ * @param installationStore - Persisted channel installation configs
+ */
 interface MessageRouterConfig {
     middlewares: MessageMiddleware[];
     bindingRegistry: BindingRegistry;
     adapterRegistry: ChannelAdapterRegistry;
     installationStore: ChannelInstallationStore;
 }
+/**
+ * Core message router for external channel integration.
+ *
+ * Receives normalized {@link InboundMessage} objects from channel adapters,
+ * resolves the target agent via {@link BindingRegistry}, manages thread
+ * lifecycle, and sends AI responses back to the channel via
+ * `ChannelAdapter.sendReply`.
+ *
+ * ## Reply flow
+ *
+ * The router uses a counter-based deduplication scheme on the internal
+ * {@link Agent.reply:ready} event:
+ *
+ * 1. Before `agent.addMessage()`, it subscribes to `reply:ready` on the agent.
+ * 2. Multiple concurrent dispatches on the same thread increment a counter;
+ *    only the first registers the `EventEmitter.once` listener.
+ * 3. When `reply:ready` fires, the callback extracts the last AI message from
+ *    the LangGraph state and sends it via `ChannelAdapter.sendReply`.
+ * 4. The counter is decremented; the subscription is only removed when the
+ *    counter reaches 0.
+ * 5. Stale subscriptions are cleaned up after a 1-hour timeout.
+ *
+ * The `replyTarget` is carried through by injecting `_replyTarget` into
+ * `custom_run_config` on {@link Agent.addMessage}, and retrieved from the
+ * `reply:ready` event payload.
+ *
+ * @see {@link ChannelAdapter.sendReply}
+ * @see {@link InboundMessage.replyTarget}
+ */
 declare class MessageRouter {
     private middlewares;
     private bindingRegistry;
     private adapterRegistry;
     private installationStore;
+    /**
+     * Tracks reply subscriptions per thread+channel to avoid duplicate
+     * `subscribeOnce` registrations and ensure proper cleanup.
+     *
+     * Key format: `{threadId}:{adapterChannel}:reply`
+     */
+    private _replySubs;
     constructor(config: MessageRouterConfig);
+    /**
+     * Register an additional middleware at the end of the chain.
+     *
+     * @param middleware - A {@link MessageMiddleware} function
+     */
     use(middleware: MessageMiddleware): void;
+    /**
+     * Dispatch an inbound channel message to the bound agent.
+     *
+     * Full pipeline: middleware chain → binding resolution → thread lifecycle
+     * → agent.addMessage() → (async) reply via {@link ChannelAdapter.sendReply}.
+     *
+     * If the message has a {@link InboundMessage.replyTarget}, the router subscribes
+     * to the agent's `reply:ready` event before enqueuing the message, and sends
+     * the AI response back to the channel when it arrives.
+     *
+     * @param message - Normalized inbound message from a channel adapter
+     * @returns {@link DispatchResult} with success status, bindingId, and threadId
+     */
     dispatch(message: InboundMessage): Promise<DispatchResult>;
     private runMiddlewares;
 }

package/dist/index.d.ts

@@ -62,19 +62,81 @@ interface MessageContext {
 }
 type MessageMiddleware = (ctx: MessageContext, next: () => Promise<void>) => Promise<void>;
 
+/**
+ * Configuration for {@link MessageRouter}.
+ *
+ * @param middlewares - Ordered middleware chain executed before dispatch
+ * @param bindingRegistry - Resolves sender-to-agent bindings
+ * @param adapterRegistry - Registry of {@link ChannelAdapter} implementations
+ * @param installationStore - Persisted channel installation configs
+ */
 interface MessageRouterConfig {
     middlewares: MessageMiddleware[];
     bindingRegistry: BindingRegistry;
     adapterRegistry: ChannelAdapterRegistry;
     installationStore: ChannelInstallationStore;
 }
+/**
+ * Core message router for external channel integration.
+ *
+ * Receives normalized {@link InboundMessage} objects from channel adapters,
+ * resolves the target agent via {@link BindingRegistry}, manages thread
+ * lifecycle, and sends AI responses back to the channel via
+ * `ChannelAdapter.sendReply`.
+ *
+ * ## Reply flow
+ *
+ * The router uses a counter-based deduplication scheme on the internal
+ * {@link Agent.reply:ready} event:
+ *
+ * 1. Before `agent.addMessage()`, it subscribes to `reply:ready` on the agent.
+ * 2. Multiple concurrent dispatches on the same thread increment a counter;
+ *    only the first registers the `EventEmitter.once` listener.
+ * 3. When `reply:ready` fires, the callback extracts the last AI message from
+ *    the LangGraph state and sends it via `ChannelAdapter.sendReply`.
+ * 4. The counter is decremented; the subscription is only removed when the
+ *    counter reaches 0.
+ * 5. Stale subscriptions are cleaned up after a 1-hour timeout.
+ *
+ * The `replyTarget` is carried through by injecting `_replyTarget` into
+ * `custom_run_config` on {@link Agent.addMessage}, and retrieved from the
+ * `reply:ready` event payload.
+ *
+ * @see {@link ChannelAdapter.sendReply}
+ * @see {@link InboundMessage.replyTarget}
+ */
 declare class MessageRouter {
     private middlewares;
     private bindingRegistry;
     private adapterRegistry;
     private installationStore;
+    /**
+     * Tracks reply subscriptions per thread+channel to avoid duplicate
+     * `subscribeOnce` registrations and ensure proper cleanup.
+     *
+     * Key format: `{threadId}:{adapterChannel}:reply`
+     */
+    private _replySubs;
     constructor(config: MessageRouterConfig);
+    /**
+     * Register an additional middleware at the end of the chain.
+     *
+     * @param middleware - A {@link MessageMiddleware} function
+     */
     use(middleware: MessageMiddleware): void;
+    /**
+     * Dispatch an inbound channel message to the bound agent.
+     *
+     * Full pipeline: middleware chain → binding resolution → thread lifecycle
+     * → agent.addMessage() → (async) reply via {@link ChannelAdapter.sendReply}.
+     *
+     * If the message has a {@link InboundMessage.replyTarget}, the router subscribes
+     * to the agent's `reply:ready` event before enqueuing the message, and sends
+     * the AI response back to the channel when it arrives.
+     *
+     * @param message - Normalized inbound message from a channel adapter
+     * @returns {@link DispatchResult} with success status, bindingId, and threadId
+     */
     dispatch(message: InboundMessage): Promise<DispatchResult>;
     private runMiddlewares;
 }