@axiom-lattice/core 2.1.76 → 2.1.77

package/dist/index.js

@@ -42,6 +42,7 @@ __export(index_exports, {
   CompositeBackend: () => CompositeBackend,
   ConsoleLoggerClient: () => ConsoleLoggerClient,
   CustomMetricsClient: () => CustomMetricsClient,
+  CustomMiddlewareRegistry: () => CustomMiddlewareRegistry,
   DaytonaInstance: () => DaytonaInstance,
   DaytonaProvider: () => DaytonaProvider,
   DefaultScheduleClient: () => DefaultScheduleClient,
@@ -2691,14 +2692,35 @@ var InMemoryChannelInstallationStore = class {
   constructor() {
     this.installations = /* @__PURE__ */ new Map();
   }
+  /**
+   * Retrieves a channel installation by its unique ID.
+   *
+   * @param installationId - The installation identifier
+   * @returns The {@link ChannelInstallation} or `null` if not found
+   */
   async getInstallationById(installationId) {
     return this.installations.get(installationId) || null;
   }
+  /**
+   * Lists all channel installations for a tenant, optionally filtered by channel type.
+   *
+   * @param tenantId - Tenant identifier
+   * @param channel - Optional channel type filter (`"lark"`, `"email"`, `"slack"`)
+   * @returns Array of matching {@link ChannelInstallation} objects
+   */
   async getInstallationsByTenant(tenantId, channel) {
     return Array.from(this.installations.values()).filter(
       (inst) => inst.tenantId === tenantId && (!channel || inst.channel === channel)
     );
   }
+  /**
+   * Creates a new channel installation for a tenant.
+   *
+   * @param tenantId - Tenant identifier
+   * @param installationId - Unique installation ID (caller-defined)
+   * @param data - {@link CreateChannelInstallationRequest} containing channel type, name, config, and fallback settings
+   * @returns The created {@link ChannelInstallation}
+   */
   async createInstallation(tenantId, installationId, data) {
     const now = /* @__PURE__ */ new Date();
     const installation = {
@@ -2716,6 +2738,14 @@ var InMemoryChannelInstallationStore = class {
     this.installations.set(installationId, installation);
     return installation;
   }
+  /**
+   * Updates an existing channel installation. Config fields are shallow-merged.
+   *
+   * @param tenantId - Tenant identifier (used for isolation check)
+   * @param installationId - Installation ID to update
+   * @param updates - {@link UpdateChannelInstallationRequest} with fields to patch
+   * @returns The updated {@link ChannelInstallation} or `null` if not found or tenant mismatch
+   */
   async updateInstallation(tenantId, installationId, updates) {
     const existing = this.installations.get(installationId);
     if (!existing || existing.tenantId !== tenantId) return null;
@@ -2731,11 +2761,21 @@ var InMemoryChannelInstallationStore = class {
     this.installations.set(installationId, updated);
     return updated;
   }
+  /**
+   * Deletes a channel installation.
+   *
+   * @param tenantId - Tenant identifier (used for isolation check)
+   * @param installationId - Installation ID to delete
+   * @returns `true` if deleted, `false` if not found or tenant mismatch
+   */
   async deleteInstallation(tenantId, installationId) {
     const existing = this.installations.get(installationId);
     if (!existing || existing.tenantId !== tenantId) return false;
     return this.installations.delete(installationId);
   }
+  /**
+   * Clears all in-memory installations. Primarily used in tests.
+   */
   clear() {
     this.installations.clear();
   }
@@ -2747,6 +2787,16 @@ var InMemoryBindingStore = class {
   constructor() {
     this.bindings = /* @__PURE__ */ new Map();
   }
+  /**
+   * Resolves a binding for the given sender across a specific channel installation.
+   *
+   * Called by `MessageRouter.dispatch()` during inbound message processing.
+   * Matches on `channel + senderId + channelInstallationId + tenantId` and
+   * requires `enabled === true`.
+   *
+   * @param params - Resolution parameters
+   * @returns The matching {@link Binding} or `null` if none found.
+   */
   async resolve(params) {
     for (const binding of this.bindings.values()) {
       if (binding.channel === params.channel && binding.senderId === params.senderId && binding.channelInstallationId === params.channelInstallationId && binding.tenantId === params.tenantId && binding.enabled) {
@@ -2755,6 +2805,12 @@ var InMemoryBindingStore = class {
     }
     return null;
   }
+  /**
+   * Creates a new sender-to-agent binding.
+   *
+   * @param input - {@link CreateBindingInput} defining channel, sender, target agent, and thread mode.
+   * @returns The newly created {@link Binding}.
+   */
   async create(input) {
     const now = /* @__PURE__ */ new Date();
     const binding = {
@@ -2777,6 +2833,14 @@ var InMemoryBindingStore = class {
     this.bindings.set(binding.id, binding);
     return binding;
   }
+  /**
+   * Updates an existing binding (e.g. changing the target agent or thread mode).
+   *
+   * @param id - Binding ID
+   * @param patch - Partial {@link Binding} fields to update
+   * @returns The updated {@link Binding}
+   * @throws {Error} If the binding does not exist
+   */
   async update(id, patch) {
     const existing = this.bindings.get(id);
     if (!existing) throw new Error(`Binding ${id} not found`);
@@ -2788,9 +2852,20 @@ var InMemoryBindingStore = class {
     this.bindings.set(id, updated);
     return updated;
   }
+  /**
+   * Deletes a binding by ID.
+   *
+   * @param id - Binding ID
+   */
   async delete(id) {
     this.bindings.delete(id);
   }
+  /**
+   * Lists bindings filtered by tenant and optional channel/agent/installation.
+   *
+   * @param params - Filter and pagination parameters
+   * @returns Array of matching {@link Binding} objects
+   */
   async list(params) {
     let results = Array.from(this.bindings.values()).filter((b) => {
       if (b.tenantId !== params.tenantId) return false;
@@ -2803,6 +2878,12 @@ var InMemoryBindingStore = class {
     const limit = params.limit ?? 50;
     return results.slice(offset, offset + limit);
   }
+  /**
+   * Bulk-imports bindings.
+   *
+   * @param bindings - Array of {@link CreateBindingInput}
+   * @returns Array of created {@link Binding} objects
+   */
   async import(bindings) {
     const result = [];
     for (const input of bindings) {
@@ -2810,9 +2891,18 @@ var InMemoryBindingStore = class {
     }
     return result;
   }
+  /**
+   * Exports all bindings for a tenant.
+   *
+   * @param params - Filter by tenantId
+   * @returns Array of {@link Binding} objects
+   */
   async export(params) {
     return this.list({ tenantId: params.tenantId, limit: 1e4 });
   }
+  /**
+   * Clears all in-memory bindings. Primarily used in tests.
+   */
   clear() {
     this.bindings.clear();
   }
@@ -12113,6 +12203,14 @@ var ThreadStatus2 = /* @__PURE__ */ ((ThreadStatus3) => {
   return ThreadStatus3;
 })(ThreadStatus2 || {});
 var Agent = class {
+  /**
+   * Constructs an Agent instance.
+   *
+   * Prefer {@link AgentInstanceManager.getAgent} over direct construction — it
+   * ensures a single instance per thread.
+   *
+   * @param params - {@link AgentThreadInterface}
+   */
   constructor({
     assistant_id,
     thread_id,
@@ -12325,6 +12423,7 @@ var Agent = class {
               await this.queueStore?.removeMessage(p.id);
               const runStatus = await this.getRunStatus();
               const state = await this.getCurrentState();
+              const customRunConfig = p.custom_run_config ?? queueMessageData.custom_run_config;
               if (runStatus === "interrupted" /* INTERRUPTED */) {
                 this.publish("message:interrupted", {
                   type: "message:interrupted",
@@ -12349,6 +12448,12 @@ var Agent = class {
                   state
                 });
               }
+              this.publish("reply:ready", {
+                type: "reply:ready",
+                timestamp: /* @__PURE__ */ new Date(),
+                state,
+                customRunConfig
+              });
             } catch (error) {
               console.error(`STEER/Command message ${p.id} execution failed:`, error);
               this.addChunk({
@@ -12427,6 +12532,12 @@ var Agent = class {
                   });
                 }
               }
+              this.publish("reply:ready", {
+                type: "reply:ready",
+                timestamp: /* @__PURE__ */ new Date(),
+                state,
+                customRunConfig: remainingPendings[0]?.custom_run_config ?? firstQueueMessage?.custom_run_config
+              });
             } catch (error) {
               console.error(`COLLECT mode execution failed:`, error);
               for (const p of remainingPendings) {
@@ -12475,6 +12586,7 @@ var Agent = class {
                 await this.queueStore?.removeMessage(p.id);
                 const runStatus = await this.getRunStatus();
                 const state = await this.getCurrentState();
+                const customRunConfig = p.custom_run_config ?? queueMessageData.custom_run_config;
                 if (runStatus === "interrupted" /* INTERRUPTED */) {
                   this.publish("message:interrupted", {
                     type: "message:interrupted",
@@ -12499,6 +12611,12 @@ var Agent = class {
                     state
                   });
                 }
+                this.publish("reply:ready", {
+                  type: "reply:ready",
+                  timestamp: /* @__PURE__ */ new Date(),
+                  state,
+                  customRunConfig
+                });
               } catch (error) {
                 console.error(`FOLLOWUP mode message ${p.id} execution failed:`, error);
                 this.addChunk({
@@ -12541,9 +12659,25 @@ var Agent = class {
   setQueueStore(store) {
     this.queueStore = store;
   }
+  /**
+   * Push a chunk into the streaming buffer for this thread.
+   *
+   * Consumers read chunks via {@link chunkStream}.
+   *
+   * @param content - The message chunk to buffer
+   */
   addChunk(content) {
     return this.chunkBuffer.addChunk(this.thread_id, content);
   }
+  /**
+   * Returns an async iterator over new chunks since the given message ID.
+   *
+   * Used by SSE endpoints to stream agent output to clients in real time.
+   *
+   * @param message_id - The client message ID to start streaming from
+   * @param stopTypes - Optional chunk types that terminate the stream
+   * @returns An async iterable yielding {@link MessageChunk} objects
+   */
   chunkStream(message_id, stopTypes) {
     const stream = this.chunkBuffer.getNewChunksSinceContentIterator(
       this.thread_id,
@@ -12632,13 +12766,21 @@ var Agent = class {
     };
   }
   /**
-   * Set queue configuration for thread
+   * Override the thread's queue processing mode.
+   *
+   * @param config - Partial {@link ThreadQueueConfig} (e.g. `{ mode: QueueMode.FOLLOWUP }`)
    */
   async setQueueConfig(config) {
     this.queueMode = { ...this.queueMode, ...config };
   }
   /**
-   * Stop queue processor
+   * Abort any ongoing queue processing without clearing the queue.
+   *
+   * Used internally by STEER mode to interrupt the current execution so the
+   * steer message can be processed next. For a full abort that also clears
+   * pending messages, use {@link abort}.
+   *
+   * @see {@link abort}
    */
   stopQueueProcessor() {
     if (this.abortController) {
@@ -12647,14 +12789,34 @@ var Agent = class {
     }
   }
   /**
-   * Add message to queue
-   * All messages go to queue, processor auto-starts if not running
-   * STEER/Command messages are inserted at head of queue for immediate processing
-   * 
-   * Supports both legacy single message format and new messages[] format:
-   * - Legacy: input.message (single human message)
-   * - New: input.messages[] (array of mixed human/system messages)
-   * - When input.messages is provided, it takes precedence over input.message
+   * Enqueue a message for this thread.
+   *
+   * Messages are always queued; the queue processor starts automatically if idle.
+   * Returns immediately with the message ID — execution is asynchronous.
+   *
+   * **Queue modes** (via the optional `mode` param):
+   * - `COLLECT` (default) — Batch multiple pending messages into one agent call.
+   * - `FOLLOWUP` — Process messages one at a time in order.
+   * - `STEER` — High-priority, inserted at queue head, interrupts current processing.
+   *
+   * **Format**: Supports both `input.message` (legacy string) and `input.messages[]`
+   * (array of `{ role, content }` objects). The array form takes precedence.
+   *
+   * The `custom_run_config` field is round-tripped through the queue and emitted
+   * back in {@link ReplyReadyEvent}, enabling callers to attach routing metadata
+   * (e.g. `_replyTarget` for channel reply).
+   *
+   * @param queueMessage - The message to enqueue
+   * @param mode - Optional queue mode override (defaults to thread's current mode)
+   * @returns `{ queued: true, executed: false, messageId }` — execution happens asynchronously
+   *
+   * @example
+   * ```ts
+   * await agent.addMessage({
+   *   input: { message: "Hello" },
+   *   custom_run_config: { _replyTarget: { adapterChannel: "lark", rawTarget: { chatId: "xxx" } } },
+   * });
+   * ```
    */
   async addMessage(queueMessage, mode) {
     const useMode = mode ?? this.queueMode.mode;
@@ -12748,8 +12910,13 @@ var Agent = class {
     return { queued: true, executed: false, messageId };
   }
   /**
-   * Start queue processor if not already running
-   * Public method to allow external triggering (e.g., from recovery)
+   * Start the queue processor if it is not already running.
+   *
+   * Called automatically by {@link addMessage} and {@link resumeTask}.
+   * Safe to call externally — it is a no-op if processing is already active.
+   *
+   * Emits `thread:busy` before starting, and starts the {@link waitingForQueueEnd}
+   * loop with a fresh {@link AbortController}.
    */
   async startQueueProcessorIfNeeded() {
     const store = this.getQueueStore();
@@ -12797,6 +12964,12 @@ var Agent = class {
       type: "system"
     });
   }
+  /**
+   * Returns a LangGraph StateSnapshot for this thread.
+   *
+   * Includes `state.values.messages` (full conversation history) and
+   * `state.tasks` / `state.next` (execution progress).
+   */
   async getCurrentState() {
     const { runnable_agent } = await this.getLatticeClientAndRuntimeConfig();
     const state = await runnable_agent.getState({
@@ -12804,6 +12977,14 @@ var Agent = class {
     });
     return state;
   }
+  /**
+   * Returns the conversation history as normalized message objects.
+   *
+   * Filters to `human`, `ai`, and `tool` message types. Each entry has
+   * `{ id, role, content }` plus any LangChain kwargs.
+   *
+   * @returns Array of message objects with `id`, `role`, and `content`
+   */
   async getCurrentMessages() {
     const state = await this.getCurrentState();
     const messages = state.values.messages || [];
@@ -12826,6 +13007,14 @@ var Agent = class {
     const image = await drawableGraph.drawMermaid();
     return image;
   }
+  /**
+   * Determine the current thread execution status.
+   *
+   * Checks LangGraph's `state.tasks` for interrupts and `state.next` for
+   * pending steps.
+   *
+   * @returns {@link ThreadStatus} — `IDLE`, `BUSY`, or `INTERRUPTED`
+   */
   async getRunStatus() {
     const state = await this.getCurrentState();
     const isInterrupted = state.tasks?.some(
@@ -12840,9 +13029,14 @@ var Agent = class {
     return "idle" /* IDLE */;
   }
   /**
-   * Resume task processing after server restart
-   * Resets any stuck processing messages to pending and starts queue processing
-   * Note: Does not rely on LangGraph state as it may be stale after crash/restart
+   * Resume processing after a server restart.
+   *
+   * Resets any stuck "processing" messages back to "pending" and restarts the
+   * queue processor. Skips threads that are in `INTERRUPTED` state (the
+   * interruption was intentional).
+   *
+   * Called during gateway startup to recover threads that were mid-execution
+   * when the server went down.
    */
   async resumeTask() {
     try {
@@ -12864,9 +13058,14 @@ var Agent = class {
     await this.startQueueProcessorIfNeeded();
   }
   /**
-   * Abort the current agent execution
-   * This will cancel any ongoing invoke or stream operations
-   * and clear all queued messages (pending + processing)
+   * Fully abort all activity on this thread.
+   *
+   * Aborts any in-flight agent execution (via {@link AbortController}) and
+   * clears all pending and processing messages from the queue. Also marks
+   * the chunk buffer thread as aborted so streaming consumers can detect it.
+   *
+   * Unlike {@link stopQueueProcessor}, this is a destructive abort — the
+   * queue is drained.
    */
   async abort() {
     if (this.abortController) {
@@ -12884,22 +13083,44 @@ var Agent = class {
     return this.abortController?.signal.aborted ?? false;
   }
   /**
-   * Subscribe to lifecycle events for this agent/thread
-   * Events are automatically namespaced by tenantId and threadId
+   * Subscribe to a lifecycle event for this specific thread.
+   *
+   * Event names are namespaced as `{eventName}:{tenantId}:{threadId}` so
+   * listeners only receive events for this agent instance.
+   *
+   * @param eventName - One of {@link AgentLifecycleEventName}
+   * @param callback - Handler receiving the event data payload
+   *
+   * @example
+   * ```ts
+   * agent.subscribe("message:completed", (evt) => {
+   *   console.log("AI response:", evt.state?.values?.messages);
+   * });
+   * ```
    */
   subscribe(eventName, callback) {
     const namespacedEvent = `${eventName}:${this.tenant_id}:${this.thread_id}`;
     event_bus_default.subscribe(namespacedEvent, callback);
   }
   /**
-   * Unsubscribe from lifecycle events
+   * Remove a previously registered event listener.
+   *
+   * @param eventName - The event that was subscribed to
+   * @param callback - The same function reference used in {@link subscribe}
    */
   unsubscribe(eventName, callback) {
     const namespacedEvent = `${eventName}:${this.tenant_id}:${this.thread_id}`;
     event_bus_default.unsubscribe(namespacedEvent, callback);
   }
   /**
-   * Subscribe to lifecycle events once (auto-unsubscribe after first event)
+   * Subscribe to a lifecycle event once — the listener is removed after the
+   * first invocation.
+   *
+   * Ideal for one-shot async patterns (e.g. waiting for `reply:ready` before
+   * sending a channel reply).
+   *
+   * @param eventName - One of {@link AgentLifecycleEventName}
+   * @param callback - Handler receiving the event data payload
    */
   subscribeOnce(eventName, callback) {
     const namespacedEvent = `${eventName}:${this.tenant_id}:${this.thread_id}`;
@@ -12913,6 +13134,12 @@ var Agent = class {
     console.log(namespacedEvent);
     event_bus_default.publish(namespacedEvent, data);
   }
+  /**
+   * Track a sub-agent async task spawned by this agent.
+   *
+   * Tasks are monitored by the agent task consumer in `packages/gateway`
+   * and their status can be polled via {@link getAsyncTasks}.
+   */
   addAsyncTask(task) {
     this.asyncTasks.push(task);
   }
@@ -12922,6 +13149,12 @@ var Agent = class {
   getAsyncTask(taskId) {
     return this.asyncTasks.find((t) => t.taskId === taskId);
   }
+  /**
+   * Update the status of a tracked async task.
+   *
+   * Terminal states (`completed`, `failed`, `cancelled`) automatically
+   * set `completedAt` to the current timestamp.
+   */
   updateAsyncTaskStatus(taskId, status) {
     const task = this.getAsyncTask(taskId);
     if (!task) return;
@@ -13287,6 +13520,65 @@ function createSchedulerMiddleware(options = {}) {
   });
 }
 
+// src/agent_lattice/builders/CustomMiddlewareRegistry.ts
+var CustomMiddlewareRegistry = class {
+  /**
+   * Register a custom middleware factory under the given key.
+   *
+   * The key is referenced by `config.key` in the database middleware configuration.
+   * When an agent is built, the framework looks up this key and calls the factory
+   * with the remaining config fields.
+   *
+   * @param key - Unique identifier, referenced in database config as `config.key`
+   * @param factory - Function that receives config (minus `key`) and returns an AgentMiddleware
+   *
+   * @example
+   * ```ts
+   * CustomMiddlewareRegistry.register("my-logger", (config) =>
+   *   createMiddleware({ name: "Logger", beforeAgent: async () => { ... } }),
+   * );
+   * ```
+   */
+  static register(key, factory) {
+    this.factories.set(key, factory);
+  }
+  /**
+   * Remove a previously registered factory.
+   *
+   * @param key - The factory key to unregister
+   * @returns `true` if a factory was removed, `false` if the key was not found
+   */
+  static unregister(key) {
+    return this.factories.delete(key);
+  }
+  /**
+   * Look up a factory by key.
+   *
+   * @param key - The factory key
+   * @returns The factory function, or `undefined` if not registered
+   */
+  static get(key) {
+    return this.factories.get(key);
+  }
+  /**
+   * Check whether a factory is registered under the given key.
+   *
+   * @param key - The factory key to check
+   */
+  static has(key) {
+    return this.factories.has(key);
+  }
+  /**
+   * Get all currently registered factory keys.
+   *
+   * @returns Array of registered key strings
+   */
+  static list() {
+    return Array.from(this.factories.keys());
+  }
+};
+CustomMiddlewareRegistry.factories = /* @__PURE__ */ new Map();
+
 // src/agent_lattice/builders/commonMiddleware.ts
 async function createCommonMiddlewares(middlewareConfigs, filesystemBackend, fsIsExised) {
   const middlewares = [];
@@ -13363,6 +13655,21 @@ async function createCommonMiddlewares(middlewareConfigs, filesystemBackend, fsI
       case "scheduler":
         middlewares.push(createSchedulerMiddleware(config.config));
         break;
+      case "custom":
+        {
+          const customConfig = config.config;
+          const { key, ...rest } = customConfig;
+          const factory = CustomMiddlewareRegistry.get(key);
+          if (factory) {
+            const middleware = factory(rest);
+            middlewares.push(middleware instanceof Promise ? await middleware : middleware);
+          } else {
+            console.warn(
+              `[custom middleware] No factory registered for key "${key}". Use CustomMiddlewareRegistry.register("${key}", factory) before building the agent.`
+            );
+          }
+        }
+        break;
     }
   }
   return middlewares;
@@ -22708,6 +23015,7 @@ function clearEncryptionKeyCache() {
   CompositeBackend,
   ConsoleLoggerClient,
   CustomMetricsClient,
+  CustomMiddlewareRegistry,
   DaytonaInstance,
   DaytonaProvider,
   DefaultScheduleClient,