@axiom-lattice/gateway 2.1.88 → 2.1.89

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @axiom-lattice/gateway@2.1.88 build /home/runner/work/agentic/agentic/packages/gateway
+> @axiom-lattice/gateway@2.1.89 build /home/runner/work/agentic/agentic/packages/gateway
 > tsup src/index.ts --format cjs,esm --dts --clean --sourcemap
 
 CLI Building entry: src/index.ts
@@ -18,15 +18,15 @@
   You need to set the output format to "esm" for "import.meta" to work correctly.
 
 
-ESM dist/index.mjs               237.01 KB
+CJS dist/index.js     246.20 KB
+CJS dist/index.js.map 515.19 KB
+CJS ⚡️ Build success in 415ms
+ESM dist/index.mjs               241.30 KB
 ESM dist/sender-PX32VSHB.mjs     873.00 B
-ESM dist/index.mjs.map           504.85 KB
 ESM dist/sender-PX32VSHB.mjs.map 2.07 KB
-ESM ⚡️ Build success in 417ms
-CJS dist/index.js     241.90 KB
-CJS dist/index.js.map 506.42 KB
-CJS ⚡️ Build success in 418ms
+ESM dist/index.mjs.map           513.63 KB
+ESM ⚡️ Build success in 415ms
 DTS Build start
-DTS ⚡️ Build success in 13918ms
-DTS dist/index.d.ts  5.01 KB
-DTS dist/index.d.mts 5.01 KB
+DTS ⚡️ Build success in 14563ms
+DTS dist/index.d.ts  7.57 KB
+DTS dist/index.d.mts 7.57 KB

package/AGENTS.md

@@ -24,6 +24,12 @@ src/
     queue_service.ts       # Task queue (memory/redis)
     agent_task_consumer.ts # Queue consumer
     sandbox_service.ts     # Sandbox proxy
+  channels/         # External channel adapters (Lark, Slack, etc.)
+    lark/           # Lark (Feishu) adapter
+    registry.ts     # ChannelAdapterRegistry
+  router/           # Message routing
+    MessageRouter.ts # Inbound message dispatch + channel reply
+    MessageContext.ts # Request-scoped context
   schemas/index.ts  # Zod/Fastify schemas
   logger/Logger.ts  # Logger lattice integration
 ```
@@ -40,6 +46,62 @@ src/
 - **DB configs**: `routes/index.ts`, `controllers/database-configs.ts`
 - **Queue setup**: `services/queue_service.ts`, `services/agent_task_consumer.ts`
 - **Logger lattice**: `logger/Logger.ts`, integration in `index.ts`
+- **Channel message routing**: `router/MessageRouter.ts`, `channels/lark/`
+- **Channel reply mechanism**: `router/MessageRouter.ts#dispatch` (see below)
+
+## CHANNEL MESSAGE REPLY FLOW
+
+When an external channel (e.g. Lark) sends a message to a bound agent, the gateway
+routes the message and sends the AI response back to the channel. The flow:
+
+```
+1. Channel webhook → ChannelAdapter.receive(rawPayload)
+   → InboundMessage with replyTarget set
+
+2. MessageRouter.dispatch(inboundMessage)
+   → resolve binding → create/reuse thread
+   → subscribe to Agent 'reply:ready' event (before addMessage)
+   → agent.addMessage({ custom_run_config: { _replyTarget: replyTarget } })
+
+3. Agent queue processes the message
+   → agentStreamExecutor() runs the agent
+   → emits 'reply:ready' { state, customRunConfig }
+
+4. reply:ready callback fires
+   → extracts last AI message from state.values.messages
+   → calls ChannelAdapter.sendReply(replyTarget, { text }, installation)
+   → reply appears in the external channel
+```
+
+### Reply deduplication per thread
+
+`MessageRouter` uses a counter-based subscription (`_replySubs: Map<string, { count, timer }>`) to handle
+multiple concurrent dispatches on the same thread:
+
+- Each dispatch increments the counter, only the first registers the `subscribeOnce` listener.
+- When `reply:ready` fires, the callback decrements the counter. The subscription is removed
+  only when the counter reaches 0.
+- A 1-hour timeout cleans up stale subscriptions (e.g. agent aborted, sequence error).
+
+### Reply timing across QueueModes
+
+| Mode | `reply:ready` emitted | Reply behavior |
+|------|----------------------|----------------|
+| STEER | After each execution | 1 reply per message |
+| FOLLOWUP | After each execution | 1 reply per message |
+| COLLECT | After the batch (all per-message events first) | 1 reply for the entire batch |
+
+### Key logs for debugging
+
+| Event | Meaning |
+|-------|---------|
+| `dispatch:reply:subscribed` | First reply subscription for this thread |
+| `dispatch:reply:incremented` | Additional dispatch joined existing subscription |
+| `dispatch:reply:sending` | AI text extracted, about to call sendReply |
+| `dispatch:reply:sent` | Channel API responded OK |
+| `dispatch:reply:failed` | Channel API returned an error |
+| `dispatch:reply:empty` | Agent produced no output, skipping reply |
+| `dispatch:reply:timeout` | No reply:ready fired within 1h, subscription cleaned up |
 
 ## CONVENTIONS
 - Controllers export named handlers, consume from `services/`

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @axiom-lattice/gateway
 
+## 2.1.89
+
+### Patch Changes
+
+- 176bfe8: custom middleware, enhance messagerouter
+- Updated dependencies [176bfe8]
+  - @axiom-lattice/core@2.1.77
+  - @axiom-lattice/agent-eval@2.1.71
+  - @axiom-lattice/pg-stores@1.0.68
+
 ## 2.1.88
 
 ### Patch Changes

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;
 }

package/dist/index.js

@@ -6689,14 +6689,39 @@ var BindingNotFoundError = class extends Error {
 };
 var MessageRouter = class {
   constructor(config) {
+    /**
+     * Tracks reply subscriptions per thread+channel to avoid duplicate
+     * `subscribeOnce` registrations and ensure proper cleanup.
+     *
+     * Key format: `{threadId}:{adapterChannel}:reply`
+     */
+    this._replySubs = /* @__PURE__ */ new Map();
     this.middlewares = [...config.middlewares];
     this.bindingRegistry = config.bindingRegistry;
     this.adapterRegistry = config.adapterRegistry;
     this.installationStore = config.installationStore;
   }
+  /**
+   * Register an additional middleware at the end of the chain.
+   *
+   * @param middleware - A {@link MessageMiddleware} function
+   */
   use(middleware) {
     this.middlewares.push(middleware);
   }
+  /**
+   * 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
+   */
   async dispatch(message) {
     const ctx = {
       inboundMessage: message,
@@ -6843,32 +6868,96 @@ var MessageRouter = class {
           workspace_id: ctx.binding.workspaceId || "",
           project_id: ctx.binding.projectId || ""
         });
-        const addResult = await agent.addMessage({
-          input: { message: message.content.text },
-          custom_run_config: message.content.metadata || {}
-        });
-        console.log({
-          event: "dispatch:complete",
-          agentId: ctx.binding.agentId,
-          threadId,
-          messageId: addResult?.messageId,
-          result: JSON.stringify(addResult)
-        }, "Agent dispatch complete \u2014 messageId = " + (addResult?.messageId || "N/A"));
         if (message.replyTarget) {
+          const replySubKey = `${threadId}:${message.replyTarget.adapterChannel}:reply`;
           const adapter = this.adapterRegistry.get(message.replyTarget.adapterChannel);
           if (adapter) {
             const installation = await this.installationStore.getInstallationById(
               message.channelInstallationId
             );
             if (installation) {
-              await adapter.sendReply(
-                message.replyTarget,
-                { text: ctx.result || "" },
-                installation
-              );
+              const existing = this._replySubs.get(replySubKey);
+              if (!existing || existing.count === 0) {
+                const timer = setTimeout(() => {
+                  const entry = this._replySubs.get(replySubKey);
+                  if (entry) {
+                    this._replySubs.delete(replySubKey);
+                    console.warn({
+                      event: "dispatch:reply:timeout",
+                      threadId,
+                      channel: message.replyTarget.adapterChannel
+                    }, "Reply subscription timed out \u2014 no reply:ready fired within 1h");
+                  }
+                }, 36e5);
+                this._replySubs.set(replySubKey, { count: 1, timer });
+                console.log({
+                  event: "dispatch:reply:subscribed",
+                  threadId,
+                  channel: message.replyTarget.adapterChannel,
+                  senderId: message.sender.id
+                }, "Subscribed to reply:ready for thread");
+                agent.subscribeOnce("reply:ready", (data) => {
+                  const messages = data.state?.values?.messages;
+                  const lastAI = messages?.filter((m) => m.type === "ai" || m.getType?.() === "ai").pop();
+                  const replyText = lastAI?.content ?? "";
+                  const entry = this._replySubs.get(replySubKey);
+                  if (entry) {
+                    entry.count--;
+                    if (entry.count <= 0) {
+                      clearTimeout(entry.timer);
+                      this._replySubs.delete(replySubKey);
+                    }
+                  }
+                  if (replyText) {
+                    console.log({
+                      event: "dispatch:reply:sending",
+                      threadId,
+                      channel: message.replyTarget.adapterChannel,
+                      replyLength: replyText.length
+                    }, "Sending channel reply");
+                    adapter.sendReply(message.replyTarget, { text: replyText }, installation).then(() => {
+                      console.log({
+                        event: "dispatch:reply:sent",
+                        threadId,
+                        channel: message.replyTarget.adapterChannel
+                      }, "Channel reply sent successfully");
+                    }).catch((err) => console.error({
+                      event: "dispatch:reply:failed",
+                      threadId,
+                      channel: message.replyTarget.adapterChannel,
+                      error: err instanceof Error ? err.message : String(err)
+                    }, "Failed to send channel reply"));
+                  } else {
+                    console.warn({
+                      event: "dispatch:reply:empty",
+                      threadId,
+                      channel: message.replyTarget.adapterChannel
+                    }, "Agent produced no text output \u2014 skipping reply");
+                  }
+                });
+              } else {
+                existing.count++;
+                console.log({
+                  event: "dispatch:reply:incremented",
+                  threadId,
+                  channel: message.replyTarget.adapterChannel,
+                  count: existing.count
+                }, "Incremented reply counter for thread (already subscribed)");
+              }
             }
           }
         }
+        const addResult = await agent.addMessage({
+          input: { message: message.content.text },
+          custom_run_config: message.replyTarget ? { ...message.content.metadata || {}, _replyTarget: message.replyTarget } : message.content.metadata || {}
+        });
+        console.log({
+          event: "dispatch:complete",
+          agentId: ctx.binding.agentId,
+          threadId,
+          messageId: addResult?.messageId,
+          result: JSON.stringify(addResult)
+        }, "Agent dispatch complete \u2014 messageId = " + (addResult?.messageId || "N/A"));
       });
       return {
         success: true,