@axiom-lattice/core 2.1.75 → 2.1.77

package/dist/index.mjs

@@ -2319,24 +2319,6 @@ var InMemoryThreadMessageQueueStore = class {
       }
     }
   }
-  async markCompleted(messageId) {
-    for (const messages of this.messages.values()) {
-      const message = messages.find((msg) => msg.id === messageId);
-      if (message) {
-        message.status = "completed";
-        return;
-      }
-    }
-  }
-  async clearCompletedMessages(threadId) {
-    const messages = this.messages.get(threadId);
-    if (messages) {
-      const filtered = messages.filter(
-        (msg) => msg.status !== "completed"
-      );
-      this.messages.set(threadId, filtered);
-    }
-  }
   async resetProcessingToPending(threadId) {
     const messages = this.messages.get(threadId);
     if (!messages) {
@@ -2481,14 +2463,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 = {
@@ -2506,6 +2509,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;
@@ -2521,11 +2532,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();
   }
@@ -2537,6 +2558,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) {
@@ -2545,6 +2576,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 = {
@@ -2567,6 +2604,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`);
@@ -2578,9 +2623,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;
@@ -2593,6 +2649,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) {
@@ -2600,9 +2662,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();
   }
@@ -3225,7 +3296,6 @@ var SqlDatabaseManager = class _SqlDatabaseManager {
   constructor() {
     this.databases = /* @__PURE__ */ new Map();
     this.defaultDatabaseKeys = /* @__PURE__ */ new Map();
-    this.configStore = null;
   }
   /**
    * Get the singleton instance
@@ -3285,16 +3355,9 @@ var SqlDatabaseManager = class _SqlDatabaseManager {
     }
     this.defaultDatabaseKeys.set(tenantId, key);
   }
-  /**
-   * Set the configuration store for on-demand database loading
-   * @param store - The database configuration store
-   */
-  setConfigStore(store) {
-    this.configStore = store;
-  }
   /**
    * Get a database by key for a specific tenant
-   * If database is not registered and configStore is set, will try to load from store
+   * If database is not registered, tries to load from the store lattice
    * @param tenantId - Tenant identifier (required)
    * @param key - Database key (optional, uses default if not provided)
    * @returns ISqlDatabase instance
@@ -3312,8 +3375,10 @@ var SqlDatabaseManager = class _SqlDatabaseManager {
         return database;
       }
     }
-    if (this.configStore) {
-      const configEntry = await this.configStore.getConfigByKey(tenantId, dbKey);
+    try {
+      const { store } = getStoreLattice("default", "database");
+      const configStore = store;
+      const configEntry = await configStore.getConfigByKey(tenantId, dbKey);
       if (configEntry) {
         this.registerDatabase(tenantId, dbKey, configEntry.config);
         if (!this.defaultDatabaseKeys.has(tenantId)) {
@@ -3327,6 +3392,7 @@ var SqlDatabaseManager = class _SqlDatabaseManager {
           }
         }
       }
+    } catch {
     }
     if (!tenantDbs) {
       throw new Error(`No databases registered for tenant '${tenantId}'`);
@@ -4436,6 +4502,7 @@ var MetricsServerManager = class _MetricsServerManager {
     this.clients = /* @__PURE__ */ new Map();
     this.configs = /* @__PURE__ */ new Map();
     this.defaultServerKeys = /* @__PURE__ */ new Map();
+    this._loadingPromise = null;
   }
   /**
    * Get the singleton instance
@@ -4446,6 +4513,32 @@ var MetricsServerManager = class _MetricsServerManager {
     }
     return _MetricsServerManager.instance;
   }
+  /**
+   * Ensure configurations are loaded from the store lattice.
+   * Uses a promise-lock to prevent concurrent loads.
+   */
+  async _ensureLoaded() {
+    if (this.clients.size > 0) {
+      return;
+    }
+    if (this._loadingPromise) {
+      return this._loadingPromise;
+    }
+    this._loadingPromise = (async () => {
+      try {
+        const { store } = getStoreLattice("default", "metrics");
+        const configStore = store;
+        const configs = await configStore.getAllConfigsWithoutTenant();
+        for (const entry of configs) {
+          const tenantId = entry.tenantId || "default";
+          this.registerServer(tenantId, entry.key, entry.config);
+        }
+      } finally {
+        this._loadingPromise = null;
+      }
+    })();
+    return this._loadingPromise;
+  }
   /**
    * Get or create tenant clients map
    */
@@ -4514,7 +4607,8 @@ var MetricsServerManager = class _MetricsServerManager {
    * @param tenantId - Tenant identifier
    * @param key - Server key (optional, uses default if not provided)
    */
-  getClient(tenantId, key) {
+  async getClient(tenantId, key) {
+    await this._ensureLoaded();
     const tenantClients = this.clients.get(tenantId);
     if (!tenantClients) {
       throw new Error(`No metrics servers registered for tenant '${tenantId}'`);
@@ -4534,7 +4628,8 @@ var MetricsServerManager = class _MetricsServerManager {
    * @param tenantId - Tenant identifier
    * @param key - Server key (optional, uses default if not provided)
    */
-  getConfig(tenantId, key) {
+  async getConfig(tenantId, key) {
+    await this._ensureLoaded();
     const tenantConfigs = this.configs.get(tenantId);
     if (!tenantConfigs) {
       throw new Error(`No metrics servers registered for tenant '${tenantId}'`);
@@ -4562,7 +4657,8 @@ var MetricsServerManager = class _MetricsServerManager {
    * Get all registered metrics server keys with their types for a tenant
    * @param tenantId - Tenant identifier
    */
-  getServerKeys(tenantId) {
+  async getServerKeys(tenantId) {
+    await this._ensureLoaded();
     const tenantConfigs = this.configs.get(tenantId);
     if (!tenantConfigs) {
       return [];
@@ -4629,20 +4725,6 @@ var MetricsServerManager = class _MetricsServerManager {
       this.registerServer(tenantId, entry.key, entry.config);
     }
   }
-  /**
-   * Load all metrics server configurations from a store
-   * across all tenants and register them with this manager
-   *
-   * @param store - The metrics server configuration store
-   * @deprecated Use loadConfigsFromStore with specific tenant instead
-   */
-  async loadAllConfigsFromStore(store) {
-    const configs = await store.getAllConfigsWithoutTenant();
-    for (const entry of configs) {
-      const tenantId = entry.tenantId || "default";
-      this.registerServer(tenantId, entry.key, entry.config);
-    }
-  }
 };
 var metricsServerManager = MetricsServerManager.getInstance();
 
@@ -4661,7 +4743,7 @@ ${serverKeys.map(
     async (_input, _exeConfig) => {
       try {
         const tenantId = getTenantIdFromConfig2(_exeConfig, getTenantId2);
-        const servers = metricsServerManager.getServerKeys(tenantId);
+        const servers = await metricsServerManager.getServerKeys(tenantId);
         if (servers.length === 0) {
           return "No metrics servers registered.";
         }
@@ -4700,7 +4782,7 @@ ${serverKeys.map(
         const tenantId = getTenantIdFromConfig2(_exeConfig, getTenantId2);
         let effectiveServerKeys = serverKeys;
         if (connectAll) {
-          effectiveServerKeys = metricsServerManager.getServerKeys(tenantId).map((s) => s.key);
+          effectiveServerKeys = (await metricsServerManager.getServerKeys(tenantId)).map((s) => s.key);
         }
         const filteredServerKeys = filterServerKeysByTenant(effectiveServerKeys, tenantId);
         const runConfig = _exeConfig?.configurable?.runConfig || {};
@@ -4723,12 +4805,12 @@ To view all available data sources, please clear the current selection or reopen
         const allDataSources = [];
         for (const serverKey of filteredServerKeys) {
           try {
-            const config = metricsServerManager.getConfig(tenantId, serverKey);
+            const config = await metricsServerManager.getConfig(tenantId, serverKey);
             if (config.type !== "semantic") {
               console.warn(`Server "${serverKey}" is not a semantic metrics server, skipping.`);
               continue;
             }
-            const client = metricsServerManager.getClient(tenantId, serverKey);
+            const client = await metricsServerManager.getClient(tenantId, serverKey);
             const dataSources = await client.getDataSources();
             const selectedIds = config.selectedDataSources || [];
             const filteredDataSources = selectedIds.length > 0 ? dataSources.filter((ds) => selectedIds.includes(String(ds.id))) : dataSources;
@@ -4819,7 +4901,7 @@ ${serverKeys.map(
         const tenantId = getTenantIdFromConfig2(_exeConfig, getTenantId2);
         let effectiveServerKeys = serverKeys;
         if (connectAll) {
-          effectiveServerKeys = metricsServerManager.getServerKeys(tenantId).map((s) => s.key);
+          effectiveServerKeys = (await metricsServerManager.getServerKeys(tenantId)).map((s) => s.key);
         }
         const filteredServerKeys = filterServerKeysByTenant(effectiveServerKeys, tenantId);
         const runConfig = _exeConfig?.configurable?.runConfig || {};
@@ -4831,11 +4913,11 @@ ${serverKeys.map(
         if (!filteredServerKeys.includes(serverKey)) {
           return `Error: serverKey "${serverKey}" is not available for tenant "${tenantId}". Available servers: [${filteredServerKeys.join(", ")}]`;
         }
-        const config = metricsServerManager.getConfig(tenantId, serverKey);
+        const config = await metricsServerManager.getConfig(tenantId, serverKey);
         if (config.type !== "semantic") {
           return `Error: Server "${serverKey}" is not a semantic metrics server. This tool only works with semantic servers.`;
         }
-        const client = metricsServerManager.getClient(tenantId, serverKey);
+        const client = await metricsServerManager.getClient(tenantId, serverKey);
         const targetDatasourceIds = datasourceIds && datasourceIds.length > 0 ? datasourceIds : metricsDataSource?.datasourceId ? [metricsDataSource.datasourceId] : client.getSelectedDataSources();
         if (targetDatasourceIds.length === 0) {
           return `Error: No data sources specified and no default data sources configured for server "${serverKey}".`;
@@ -4977,7 +5059,7 @@ ${serverKeys.map(
         const tenantId = getTenantIdFromConfig2(_exeConfig, getTenantId2);
         let effectiveServerKeys = serverKeys;
         if (connectAll) {
-          effectiveServerKeys = metricsServerManager.getServerKeys(tenantId).map((s) => s.key);
+          effectiveServerKeys = (await metricsServerManager.getServerKeys(tenantId)).map((s) => s.key);
         }
         const filteredServerKeys = filterServerKeysByTenant(effectiveServerKeys, tenantId);
         const runConfig = _exeConfig?.configurable?.runConfig || {};
@@ -4993,11 +5075,11 @@ ${serverKeys.map(
         if (!metricName) {
           return "Error: metricName parameter is required.";
         }
-        const config = metricsServerManager.getConfig(tenantId, serverKey);
+        const config = await metricsServerManager.getConfig(tenantId, serverKey);
         if (config.type !== "semantic") {
           return `Error: Server "${serverKey}" is not a semantic metrics server. This tool only works with semantic servers.`;
         }
-        const client = metricsServerManager.getClient(tenantId, serverKey);
+        const client = await metricsServerManager.getClient(tenantId, serverKey);
         const targetDatasourceIds = datasourceId ? [datasourceId] : client.getSelectedDataSources();
         if (targetDatasourceIds.length === 0) {
           return `Error: No datasourceId specified and no default data sources configured for server "${serverKey}".`;
@@ -5213,7 +5295,7 @@ ${serverKeys.map(
         const tenantId = getTenantIdFromConfig2(_exeConfig, getTenantId2);
         let effectiveServerKeys = serverKeys;
         if (connectAll) {
-          effectiveServerKeys = metricsServerManager.getServerKeys(tenantId).map((s) => s.key);
+          effectiveServerKeys = (await metricsServerManager.getServerKeys(tenantId)).map((s) => s.key);
         }
         const filteredServerKeys = filterServerKeysByTenant(effectiveServerKeys, tenantId);
         const runConfig = _exeConfig?.configurable?.runConfig || {};
@@ -5232,11 +5314,11 @@ ${serverKeys.map(
         if (!metrics || metrics.length === 0) {
           return "Error: metrics parameter is required (at least one metric name).";
         }
-        const config = metricsServerManager.getConfig(tenantId, serverKey);
+        const config = await metricsServerManager.getConfig(tenantId, serverKey);
         if (config.type !== "semantic") {
           return `Error: Server "${serverKey}" is not a semantic metrics server. This tool only works with semantic servers.`;
         }
-        const client = metricsServerManager.getClient(tenantId, serverKey);
+        const client = await metricsServerManager.getClient(tenantId, serverKey);
         const semanticFilters = (filters || []).map((f) => ({
           dimension: f.dimension,
           operator: f.operator,
@@ -5294,7 +5376,7 @@ ${serverKeys.map(
         const tenantId = getTenantIdFromConfig2(_exeConfig, getTenantId2);
         let effectiveServerKeys = serverKeys;
         if (connectAll) {
-          effectiveServerKeys = metricsServerManager.getServerKeys(tenantId).map((s) => s.key);
+          effectiveServerKeys = (await metricsServerManager.getServerKeys(tenantId)).map((s) => s.key);
         }
         const filteredServerKeys = filterServerKeysByTenant(effectiveServerKeys, tenantId);
         const runConfig = _exeConfig?.configurable?.runConfig || {};
@@ -5306,11 +5388,11 @@ ${serverKeys.map(
         if (!filteredServerKeys.includes(serverKey)) {
           return `Error: serverKey "${serverKey}" is not available for tenant "${tenantId}". Available servers: [${filteredServerKeys.join(", ")}]`;
         }
-        const config = metricsServerManager.getConfig(tenantId, serverKey);
+        const config = await metricsServerManager.getConfig(tenantId, serverKey);
         if (config.type !== "semantic") {
           return `Error: Server "${serverKey}" is not a semantic metrics server. This tool only works with semantic servers.`;
         }
-        const client = metricsServerManager.getClient(tenantId, serverKey);
+        const client = await metricsServerManager.getClient(tenantId, serverKey);
         const targetDatasourceIds = datasourceIds && datasourceIds.length > 0 ? datasourceIds : metricsDataSource?.datasourceId ? [metricsDataSource.datasourceId] : client.getSelectedDataSources();
         if (targetDatasourceIds.length === 0) {
           return `Error: No data sources specified and no default data sources configured for server "${serverKey}".`;
@@ -5399,7 +5481,7 @@ ${serverKeys.map(
         const tenantId = getTenantIdFromConfig2(_exeConfig, getTenantId2);
         let effectiveServerKeys = serverKeys;
         if (connectAll) {
-          effectiveServerKeys = metricsServerManager.getServerKeys(tenantId).map((s) => s.key);
+          effectiveServerKeys = (await metricsServerManager.getServerKeys(tenantId)).map((s) => s.key);
         }
         const filteredServerKeys = filterServerKeysByTenant(effectiveServerKeys, tenantId);
         const runConfig = _exeConfig?.configurable?.runConfig || {};
@@ -5415,11 +5497,11 @@ ${serverKeys.map(
         if (!tableName) {
           return "Error: tableName parameter is required.";
         }
-        const config = metricsServerManager.getConfig(tenantId, serverKey);
+        const config = await metricsServerManager.getConfig(tenantId, serverKey);
         if (config.type !== "semantic") {
           return `Error: Server "${serverKey}" is not a semantic metrics server. This tool only works with semantic servers.`;
         }
-        const client = metricsServerManager.getClient(tenantId, serverKey);
+        const client = await metricsServerManager.getClient(tenantId, serverKey);
         const targetDatasourceIds = datasourceId ? [datasourceId] : client.getSelectedDataSources();
         if (targetDatasourceIds.length === 0) {
           return `Error: No datasourceId specified and no default data sources configured for server "${serverKey}".`;
@@ -5539,7 +5621,7 @@ ${serverKeys.map(
         const tenantId = getTenantIdFromConfig2(_exeConfig, getTenantId2);
         let effectiveServerKeys = serverKeys;
         if (connectAll) {
-          effectiveServerKeys = metricsServerManager.getServerKeys(tenantId).map((s) => s.key);
+          effectiveServerKeys = (await metricsServerManager.getServerKeys(tenantId)).map((s) => s.key);
         }
         const filteredServerKeys = filterServerKeysByTenant(effectiveServerKeys, tenantId);
         const runConfig = _exeConfig?.configurable?.runConfig || {};
@@ -5558,11 +5640,11 @@ ${serverKeys.map(
         if (!customSql || customSql.trim().length === 0) {
           return "Error: customSql parameter is required and cannot be empty.";
         }
-        const config = metricsServerManager.getConfig(tenantId, serverKey);
+        const config = await metricsServerManager.getConfig(tenantId, serverKey);
         if (config.type !== "semantic") {
           return `Error: Server "${serverKey}" is not a semantic metrics server. This tool only works with semantic servers.`;
         }
-        const client = metricsServerManager.getClient(tenantId, serverKey);
+        const client = await metricsServerManager.getClient(tenantId, serverKey);
         const result = await client.executeSqlQuery({
           datasourceId,
           customSql,
@@ -11913,6 +11995,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,
@@ -12122,9 +12212,10 @@ var Agent = class {
                 command: p.command,
                 custom_run_config: p.custom_run_config ?? queueMessageData.custom_run_config
               }, signal);
-              await this.queueStore?.markCompleted(p.id);
+              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",
@@ -12149,6 +12240,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({
@@ -12164,7 +12261,8 @@ var Agent = class {
                 error: error instanceof Error ? error.message : String(error),
                 timestamp: /* @__PURE__ */ new Date()
               });
-              throw error;
+              await this.queueStore?.removeMessage(p.id);
+              continue;
             }
           }
         }
@@ -12200,7 +12298,7 @@ var Agent = class {
               const runStatus = await this.getRunStatus();
               const state = await this.getCurrentState();
               for (const p of remainingPendings) {
-                await this.queueStore?.markCompleted(p.id);
+                await this.queueStore?.removeMessage(p.id);
                 if (runStatus === "interrupted" /* INTERRUPTED */) {
                   this.publish("message:interrupted", {
                     type: "message:interrupted",
@@ -12226,6 +12324,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) {
@@ -12242,8 +12346,8 @@ var Agent = class {
                   error: error instanceof Error ? error.message : String(error),
                   timestamp: /* @__PURE__ */ new Date()
                 });
+                await this.queueStore?.removeMessage(p.id);
               }
-              throw error;
             }
           } else if (this.queueMode.mode === "followup" /* FOLLOWUP */) {
             for (const p of remainingPendings) {
@@ -12271,9 +12375,10 @@ var Agent = class {
                   input,
                   custom_run_config: p.custom_run_config ?? queueMessageData.custom_run_config
                 }, signal);
-                await this.queueStore?.markCompleted(p.id);
+                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",
@@ -12298,6 +12403,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({
@@ -12313,7 +12424,8 @@ var Agent = class {
                   error: error instanceof Error ? error.message : String(error),
                   timestamp: /* @__PURE__ */ new Date()
                 });
-                throw error;
+                await this.queueStore?.removeMessage(p.id);
+                continue;
               }
             }
           }
@@ -12339,9 +12451,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,
@@ -12430,13 +12558,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) {
@@ -12445,14 +12581,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;
@@ -12546,8 +12702,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();
@@ -12595,6 +12756,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({
@@ -12602,6 +12769,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 || [];
@@ -12624,6 +12799,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(
@@ -12638,9 +12821,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 {
@@ -12662,9 +12850,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) {
@@ -12682,22 +12875,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}`;
@@ -12711,6 +12926,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);
   }
@@ -12720,6 +12941,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;
@@ -13085,6 +13312,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 = [];
@@ -13161,6 +13447,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;
@@ -17934,6 +18235,75 @@ function mergeAgentConfig(parent, child) {
   return merged;
 }
 
+// src/store_lattice/configureStores.ts
+var _disposables = [];
+var _cleanupRegistered = false;
+function registerSignalCleanup() {
+  if (_cleanupRegistered) return;
+  _cleanupRegistered = true;
+  for (const sig of ["SIGINT", "SIGTERM"]) {
+    process.once(sig, async () => {
+      for (const s of _disposables) {
+        if (s.dispose) await s.dispose();
+      }
+    });
+  }
+}
+async function initAndRegister(store, localDisposables) {
+  const initStore = store;
+  if (typeof initStore.initialize === "function" && initStore.initialize.length === 0) {
+    await initStore.initialize();
+  }
+  const dispStore = store;
+  if (typeof dispStore.dispose === "function") {
+    localDisposables.push(dispStore);
+  }
+}
+async function configureStores(stores, options = {}) {
+  const localDisposables = [];
+  const { schedule, checkpoint, ...regularStores } = stores;
+  for (const [type, store] of Object.entries(regularStores)) {
+    await initAndRegister(store, localDisposables);
+    if (storeLatticeManager.hasLattice("default", type)) {
+      storeLatticeManager.removeLattice("default", type);
+    }
+    storeLatticeManager.registerLattice("default", type, store);
+  }
+  if (schedule !== void 0) {
+    await initAndRegister(schedule, localDisposables);
+    const scheduleConfig = {
+      name: "Default Scheduler",
+      description: "Auto-configured schedule storage",
+      type: "postgres",
+      storage: schedule
+    };
+    registerScheduleLattice("default", scheduleConfig);
+  }
+  if (checkpoint !== void 0) {
+    MemoryLatticeManager.getInstance().removeCheckpointSaver("default");
+    registerCheckpointSaver("default", checkpoint);
+  }
+  if (options.customStores) {
+    for (const [type, store] of Object.entries(options.customStores)) {
+      await initAndRegister(store, localDisposables);
+      const t = type;
+      if (storeLatticeManager.hasLattice("default", t)) {
+        storeLatticeManager.removeLattice("default", t);
+      }
+      storeLatticeManager.registerLattice("default", t, store);
+    }
+  }
+  if (options.autoDisposeStores) {
+    registerSignalCleanup();
+    _disposables.push(...localDisposables);
+  }
+  return async () => {
+    for (const s of localDisposables.reverse()) {
+      if (s.dispose) await s.dispose();
+    }
+  };
+}
+
 // src/store_lattice/SandboxSkillStore.ts
 function parseFrontmatter2(content) {
   const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/;
@@ -22468,6 +22838,7 @@ export {
   CompositeBackend,
   ConsoleLoggerClient,
   CustomMetricsClient,
+  CustomMiddlewareRegistry,
   DaytonaInstance,
   DaytonaProvider,
   DefaultScheduleClient,
@@ -22541,6 +22912,7 @@ export {
   checkEmptyContent,
   clearEncryptionKeyCache,
   computeSandboxName,
+  configureStores,
   createAgentTeam,
   createExecuteSqlQueryTool,
   createFileData,