@axiom-lattice/gateway 2.1.87 → 2.1.89

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @axiom-lattice/gateway@2.1.87 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
@@ -11,22 +11,22 @@
 ESM Build start
 [warn] ▲ [WARNING] "import.meta" is not available with the "cjs" output format and will be empty [empty-import-meta]
 
-    src/index.ts:178:33:
-      178 │ const __filename = fileURLToPath(import.meta.url);
+    src/index.ts:175:33:
+      175 │ const __filename = fileURLToPath(import.meta.url);
           ╵                                  ~~~~~~~~~~~
 
   You need to set the output format to "esm" for "import.meta" to work correctly.
 
 
-CJS dist/index.js     242.46 KB
-CJS dist/index.js.map 507.89 KB
-CJS ⚡️ Build success in 387ms
-ESM dist/index.mjs               237.76 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/sender-PX32VSHB.mjs.map 2.07 KB
-ESM dist/index.mjs.map           506.38 KB
-ESM ⚡️ Build success in 391ms
+ESM dist/index.mjs.map           513.63 KB
+ESM ⚡️ Build success in 415ms
 DTS Build start
-DTS ⚡️ Build success in 13983ms
-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,27 @@
 # @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
+
+- 6ff5bd5: fix issue
+- Updated dependencies [6ff5bd5]
+  - @axiom-lattice/agent-eval@2.1.70
+  - @axiom-lattice/core@2.1.76
+  - @axiom-lattice/pg-stores@1.0.67
+  - @axiom-lattice/protocols@2.1.39
+  - @axiom-lattice/queue-redis@1.0.38
+
 ## 2.1.87
 
 ### Patch Changes

package/README.md

@@ -1,125 +1,68 @@
-# Lattice Gateway
+# @axiom-lattice/gateway
 
-这是 Lattice 项目的 API 网关服务，提供了基于 Fastify 的 HTTP API 接口，用于与 Lattice Core 交互。
+Fastify-based HTTP API gateway exposing REST endpoints for agent execution, thread management, and configuration.
 
-## 功能特点
+## Store Consumption
 
-- 基于 Fastify 的 HTTP API
-- 代理调用服务
-- 流式响应支持
-- 事件总线
-- 队列服务（基于 QueueLattice）
-- 日志服务（基于 LoggerLattice，支持自定义配置）
+The gateway reads all stores from `StoreLatticeManager` at startup — no manual wiring needed.
+Register stores via `configureStores` **before** calling `startAsHttpEndpoint()`:
 
-## 安装
-
-```bash
-pnpm install
-```
-
-## 启动服务
-
-```bash
-# 开发环境
-pnpm dev
-
-# 生产环境
-pnpm build
-pnpm start
-```
-
-## API 接口
-
-### Configuration API
-
-The gateway supports dynamic configuration updates via JSON. You can update environment variables at runtime without restarting the server.
+```typescript
+import { configureStores } from "@axiom-lattice/core";
+import { createPgStoreConfig } from "@axiom-lattice/pg-stores";
+import { LatticeGateway } from "@axiom-lattice/gateway";
 
-#### Get Configuration
+const stores = createPgStoreConfig(process.env.DATABASE_URL);
+await configureStores({ ...stores });
 
-```bash
-GET /api/config
+// Gateway picks up stores from StoreLatticeManager automatically
+LatticeGateway.startAsHttpEndpoint({ port: 4001 });
 ```
 
-Returns the current configuration (sensitive values are masked).
+### How it works
 
-#### Update Configuration
+The gateway internally calls `getStoreLattice("default", type)` for each store it needs:
 
-```bash
-PUT /api/config
-Content-Type: application/json
+- **`channelBinding`** — used by `MessageRouter` for sender-to-agent binding resolution
+- **`channelInstallation`** — used for channel instance lookup
+- **`database`** — `SqlDatabaseManager` reads configs lazily on first query
+- **`metrics`** — `MetricsServerManager` loads configs on first access
+- **All other stores** — consumed by controllers via `getStoreLattice("default", type)`
 
-{
-  "config": {
-    "port": 4001,
-    "queueServiceType": "redis",
-    "redisUrl": "redis://localhost:6379",
-    "redisPassword": "your-password",
-    "queueName": "tasks"
-  }
-}
-```
-
-**Note**: When updating `queueServiceType`, the queue service will be automatically reconfigured.
+No `setConfigStore()` or `loadConfigsFromStore()` calls needed — each manager reads directly from `StoreLatticeManager`.
 
-**Example**:
+## Quick Start
 
 ```typescript
-// Update configuration from frontend
-const response = await fetch("http://localhost:4001/api/config", {
-  method: "PUT",
-  headers: {
-    "Content-Type": "application/json",
-  },
-  body: JSON.stringify({
-    config: {
-      queueServiceType: "redis",
-      redisUrl: "redis://localhost:6379",
-      redisPassword: "your-password",
-    },
-  }),
-});
+import { LatticeGateway } from "@axiom-lattice/gateway";
 
-const result = await response.json();
-console.log(result); // { success: true, message: "Configuration updated successfully", data: {...} }
+LatticeGateway.startAsHttpEndpoint({
+  port: 4001,
+  queueServiceConfig: { type: "memory", defaultStartPollingQueue: true },
+});
 ```
 
-### 代理调用
-
-- `POST /api/v1/run`: 运行代理
-- `POST /api/v1/run/stream`: 流式运行代理
-- `GET /api/v1/run/:thread_id`: 获取运行状态
-- `GET /api/v1/run/:thread_id/messages`: 获取消息历史
-
-## Logger 配置
-
-Gateway 使用 Logger Lattice 进行日志管理，支持自定义日志配置。详细说明请参考 [LOGGER_CONFIG.md](./LOGGER_CONFIG.md)。
-
-### 快速开始
+## Logger Configuration
 
 ```typescript
 import { LatticeGateway } from "@axiom-lattice/gateway";
 import { LoggerType } from "@axiom-lattice/protocols";
 
-// 使用默认配置
-LatticeGateway.startAsHttpEndpoint({
-  port: 4001,
-});
-
-// 自定义日志配置
 LatticeGateway.startAsHttpEndpoint({
   port: 4001,
   loggerConfig: {
-    file: "./logs/my-app/gateway",
+    name: "default",
+    type: LoggerType.PINO,
     serviceName: "my-service",
   },
 });
 ```
 
-## 目录结构
+## API Endpoints
 
-- `src/config/`: 配置文件
-- `src/controllers/`: 控制器
-- `src/routes/`: 路由定义
-- `src/services/`: 服务实现
-- `src/types/`: 类型定义
-- `LOGGER_CONFIG.md`: Logger 配置详细文档
+- `POST /api/v1/run` — Execute agent
+- `POST /api/v1/run/stream` — Stream agent execution
+- `GET /api/v1/run/:thread_id` — Get run status
+- `GET /api/v1/run/:thread_id/messages` — Get message history
+- `GET /api/config` — Get gateway configuration
+- `PUT /api/config` — Update gateway configuration

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