@axiom-lattice/core 2.1.75 → 2.1.77

package/dist/index.d.ts

@@ -424,7 +424,6 @@ declare class SqlDatabaseManager {
     private static instance;
     private databases;
     private defaultDatabaseKeys;
-    private configStore;
     private constructor();
     /**
      * Get the singleton instance
@@ -447,14 +446,9 @@ declare class SqlDatabaseManager {
      * @param key - Database key to set as default
      */
     setDefaultDatabase(tenantId: string, key: string): void;
-    /**
-     * Set the configuration store for on-demand database loading
-     * @param store - The database configuration store
-     */
-    setConfigStore(store: _axiom_lattice_protocols.DatabaseConfigStore): void;
     /**
      * 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
@@ -914,11 +908,17 @@ declare class MetricsServerManager {
     private clients;
     private configs;
     private defaultServerKeys;
+    private _loadingPromise;
     private constructor();
     /**
      * Get the singleton instance
      */
     static getInstance(): MetricsServerManager;
+    /**
+     * Ensure configurations are loaded from the store lattice.
+     * Uses a promise-lock to prevent concurrent loads.
+     */
+    private _ensureLoaded;
     /**
      * Get or create tenant clients map
      */
@@ -945,13 +945,13 @@ declare class MetricsServerManager {
      * @param tenantId - Tenant identifier
      * @param key - Server key (optional, uses default if not provided)
      */
-    getClient(tenantId: string, key?: string): IMetricsServerClient;
+    getClient(tenantId: string, key?: string): Promise<IMetricsServerClient>;
     /**
      * Get metrics server configuration by key for a specific tenant
      * @param tenantId - Tenant identifier
      * @param key - Server key (optional, uses default if not provided)
      */
-    getConfig(tenantId: string, key?: string): MetricsServerConfig;
+    getConfig(tenantId: string, key?: string): Promise<MetricsServerConfig>;
     /**
      * Check if a metrics server is registered for a tenant
      * @param tenantId - Tenant identifier
@@ -962,11 +962,11 @@ declare class MetricsServerManager {
      * Get all registered metrics server keys with their types for a tenant
      * @param tenantId - Tenant identifier
      */
-    getServerKeys(tenantId: string): {
+    getServerKeys(tenantId: string): Promise<{
         key: string;
         type: MetricsServerType;
         name?: string;
-    }[];
+    }[]>;
     /**
      * Remove a metrics server for a tenant
      * @param tenantId - Tenant identifier
@@ -986,14 +986,6 @@ declare class MetricsServerManager {
      * @param tenantId - Tenant identifier
      */
     loadConfigsFromStore(store: _axiom_lattice_protocols.MetricsServerConfigStore, tenantId: string): Promise<void>;
-    /**
-     * 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
-     */
-    loadAllConfigsFromStore(store: _axiom_lattice_protocols.MetricsServerConfigStore): Promise<void>;
 }
 declare const metricsServerManager: MetricsServerManager;
 
@@ -2641,8 +2633,6 @@ interface IMessageQueueStore {
     removeMessage(messageId: string): Promise<boolean>;
     clearMessages(threadId: string): Promise<void>;
     markProcessing(messageId: string): Promise<void>;
-    markCompleted(messageId: string): Promise<void>;
-    clearCompletedMessages(threadId: string): Promise<void>;
     resetProcessingToPending(threadId: string): Promise<number>;
 }
 /**
@@ -2792,6 +2782,32 @@ declare const storeLatticeManager: StoreLatticeManager;
 declare const registerStoreLattice: <TStoreType extends StoreType>(key: string, type: TStoreType, store: StoreTypeMap[TStoreType]) => void;
 declare const getStoreLattice: <TStoreType extends StoreType>(key: string, type: TStoreType) => StoreLattice<TStoreType>;
 
+interface ConfigureStoresOptions {
+    autoDisposeStores?: boolean;
+    customStores?: Record<string, object>;
+}
+type Store = Partial<{
+    [K in StoreType]: StoreTypeMap[K];
+}> & {
+    schedule?: object;
+    checkpoint?: object;
+};
+/**
+ * Replace stores in the "default" lattice with the given implementations.
+ *
+ * Regular store keys (thread, assistant, etc.) are registered via StoreLatticeManager.
+ * Special keys:
+ *   - `schedule`: registered via ScheduleLatticeManager with default POSTGRES type
+ *   - `checkpoint`: registered via MemoryLatticeManager (PostgresSaver / any CheckpointSaver)
+ *
+ * For each store: initialize() is called if available, old "default" registration is removed,
+ * and the new store is registered. Stores with dispose() are tracked for cleanup.
+ *
+ * If `autoDisposeStores` is true, SIGINT/SIGTERM handlers call dispose() on exit.
+ * Always returns a dispose function for manual cleanup.
+ */
+declare function configureStores(stores: Store, options?: ConfigureStoresOptions): Promise<() => Promise<void>>;
+
 /**
  * InMemoryThreadStore
  *
@@ -3217,40 +3233,161 @@ declare class InMemoryUserTenantLinkStore implements UserTenantLinkStore {
 }
 
 /**
- * InMemoryChannelInstallationStore
+ * In-memory implementation of {@link ChannelInstallationStore}.
+ *
+ * Stores per-tenant channel installation configurations (Lark app credentials,
+ * Slack bot tokens, etc.). Each installation defines how a specific external
+ * app instance connects to Axiom Lattice, including fallback agent and
+ * `rejectWhenNoBinding` behavior.
  *
- * In-memory implementation of ChannelInstallationStore
- * Provides CRUD operations for channel installation data stored in memory
+ * @example
+ * ```ts
+ * import { InMemoryChannelInstallationStore } from "@axiom-lattice/core";
+ *
+ * const store = new InMemoryChannelInstallationStore();
+ * await store.createInstallation("tenant-a", "install-1", {
+ *   channel: "lark",
+ *   name: "Production Bot",
+ *   config: { appId: "cli_xxx", appSecret: "secret" },
+ *   fallbackAgentId: "agent-1",
+ *   rejectWhenNoBinding: false,
+ * });
+ * ```
+ *
+ * @see {@link ChannelInstallationStore} — Protocol interface
+ * @see {@link InMemoryBindingStore} — Companion binding store
  */
 
 declare class InMemoryChannelInstallationStore implements ChannelInstallationStore {
     private installations;
+    /**
+     * Retrieves a channel installation by its unique ID.
+     *
+     * @param installationId - The installation identifier
+     * @returns The {@link ChannelInstallation} or `null` if not found
+     */
     getInstallationById(installationId: string): Promise<ChannelInstallation | 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
+     */
     getInstallationsByTenant(tenantId: string, channel?: ChannelInstallationType): Promise<ChannelInstallation[]>;
+    /**
+     * 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}
+     */
     createInstallation(tenantId: string, installationId: string, data: CreateChannelInstallationRequest): Promise<ChannelInstallation>;
+    /**
+     * 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
+     */
     updateInstallation(tenantId: string, installationId: string, updates: UpdateChannelInstallationRequest): Promise<ChannelInstallation | null>;
+    /**
+     * 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
+     */
     deleteInstallation(tenantId: string, installationId: string): Promise<boolean>;
+    /**
+     * Clears all in-memory installations. Primarily used in tests.
+     */
     clear(): void;
 }
 
 /**
- * InMemoryBindingStore
+ * In-memory implementation of {@link BindingRegistry}.
+ *
+ * Stores sender-to-agent bindings that bridge external channel identities (Lark open_id,
+ * Slack userId, email address, etc.) to Axiom Lattice agents and threads.
+ *
+ * During `MessageRouter.dispatch()`, the router calls {@link resolve} to determine
+ * which agent should handle an inbound message. The binding also controls thread
+ * lifecycle via {@link Binding.threadMode}:
+ *
+ * - `"fixed"` — All messages from this sender reuse the same `threadId`.
+ * - `"per_conversation"` — Each conversation creates a new thread.
+ *
+ * @example
+ * ```ts
+ * import { InMemoryBindingStore, setBindingRegistry } from "@axiom-lattice/core";
+ *
+ * const store = new InMemoryBindingStore();
+ * setBindingRegistry(store);
+ *
+ * const binding = await store.create({
+ *   channel: "slack",
+ *   channelInstallationId: "install-1",
+ *   tenantId: "tenant-a",
+ *   senderId: "U12345",
+ *   agentId: "agent-1",
+ *   threadMode: "fixed",
+ * });
+ * ```
  *
- * In-memory implementation of BindingRegistry
- * Provides CRUD and resolve operations for sender-to-agent bindings
+ * @see {@link BindingRegistry} — Protocol interface
+ * @see {@link setBindingRegistry} — Global registration
+ * @see {@link manageBindingSchema} — Agent tool for dynamic binding management
  */
 
 declare class InMemoryBindingStore implements BindingRegistry {
     private bindings;
+    /**
+     * 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.
+     */
     resolve(params: {
         channel: string;
         senderId: string;
         channelInstallationId: string;
         tenantId: string;
     }): Promise<Binding | 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}.
+     */
     create(input: CreateBindingInput): Promise<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
+     */
     update(id: string, patch: Partial<Binding>): Promise<Binding>;
+    /**
+     * Deletes a binding by ID.
+     *
+     * @param id - Binding ID
+     */
     delete(id: string): Promise<void>;
+    /**
+     * Lists bindings filtered by tenant and optional channel/agent/installation.
+     *
+     * @param params - Filter and pagination parameters
+     * @returns Array of matching {@link Binding} objects
+     */
     list(params: {
         channel?: string;
         agentId?: string;
@@ -3259,10 +3396,25 @@ declare class InMemoryBindingStore implements BindingRegistry {
         limit?: number;
         offset?: number;
     }): Promise<Binding[]>;
+    /**
+     * Bulk-imports bindings.
+     *
+     * @param bindings - Array of {@link CreateBindingInput}
+     * @returns Array of created {@link Binding} objects
+     */
     import(bindings: CreateBindingInput[]): Promise<Binding[]>;
+    /**
+     * Exports all bindings for a tenant.
+     *
+     * @param params - Filter by tenantId
+     * @returns Array of {@link Binding} objects
+     */
     export(params: {
         tenantId: string;
     }): Promise<Binding[]>;
+    /**
+     * Clears all in-memory bindings. Primarily used in tests.
+     */
     clear(): void;
 }
 
@@ -3287,8 +3439,6 @@ declare class InMemoryThreadMessageQueueStore implements IMessageQueueStore {
     removeMessage(messageId: string): Promise<boolean>;
     clearMessages(threadId: string): Promise<void>;
     markProcessing(messageId: string): Promise<void>;
-    markCompleted(messageId: string): Promise<void>;
-    clearCompletedMessages(threadId: string): Promise<void>;
     resetProcessingToPending(threadId: string): Promise<number>;
 }
 
@@ -4252,7 +4402,42 @@ declare function buildSandboxMetadataEnv(config?: RunSandboxConfig): Record<stri
 
 declare function buildNamedVolumeName(prefix: "s" | "a" | "p", ...parts: Array<string | undefined>): string;
 
+/**
+ * Sets the global {@link BindingRegistry} instance used by the channel message router.
+ *
+ * The registry resolves which agent/thread should handle an inbound message from an
+ * external channel (Lark, Slack, Email, etc.). It is queried during
+ * `MessageRouter.dispatch()` to map a sender ID to a binding.
+ *
+ * @example
+ * ```ts
+ * import { configureStores, setBindingRegistry, getStoreLattice } from "@axiom-lattice/core";
+ * import { PostgreSQLBindingStore } from "@axiom-lattice/pg-stores";
+ *
+ * await configureStores({
+ *   channelBinding: new PostgreSQLBindingStore({ pool }),
+ * });
+ *
+ * const bindingStore = getStoreLattice("default", "channelBinding").store as BindingRegistry;
+ * setBindingRegistry(bindingStore);
+ * ```
+ *
+ * @param r - A {@link BindingRegistry} implementation (e.g. `InMemoryBindingStore` or `PostgreSQLBindingStore`)
+ * @see {@link getBindingRegistry}
+ * @see {@link InMemoryBindingStore}
+ */
 declare function setBindingRegistry(r: BindingRegistry): void;
+/**
+ * Returns the globally registered {@link BindingRegistry}.
+ *
+ * Must be called **after** {@link setBindingRegistry}. The registry is used by
+ * `MessageRouter.dispatch()` in `packages/gateway` to look up the agent binding
+ * for an incoming channel message.
+ *
+ * @returns The active {@link BindingRegistry} instance.
+ * @throws {Error} If the registry has not been initialized.
+ * @see {@link setBindingRegistry}
+ */
 declare function getBindingRegistry(): BindingRegistry;
 
 /**
@@ -5501,12 +5686,18 @@ declare class AgentManager {
     }, return_agent_state?: boolean): Promise<unknown>;
 }
 
+/** Execution state of a thread. */
 declare enum ThreadStatus {
     IDLE = "idle",
     BUSY = "busy",
     INTERRUPTED = "interrupted",
     ERROR = "error"
 }
+/**
+ * Snapshot of a thread's current state including queue and status.
+ *
+ * Used for recovery, monitoring, and external queries about thread health.
+ */
 interface ThreadState {
     threadId: string;
     assistantId: string;
@@ -5520,6 +5711,25 @@ interface ThreadState {
     pendingMessages: PendingMessage[];
     pendingCount: number;
 }
+/**
+ * Message payload passed to {@link Agent.addMessage}.
+ *
+ * Supports both a legacy single-message format (`input.message`) and a
+ * multi-message format (`input.messages[]` for mixed human/system messages).
+ *
+ * @example
+ * ```ts
+ * // Legacy single message
+ * await agent.addMessage({ input: { message: "Hello" } });
+ *
+ * // Multi-message format
+ * await agent.addMessage({
+ *   input: {
+ *     messages: [{ role: "human", content: "Hello" }, { role: "system", content: "Context" }]
+ *   }
+ * });
+ * ```
+ */
 interface QueueMessage {
     input: {
         message?: string;
@@ -5529,6 +5739,7 @@ interface QueueMessage {
     command?: CommandParams<any>;
     custom_run_config?: any;
 }
+/** Emitted when a thread transitions between {@link ThreadStatus} values. */
 interface ThreadStatusChangedEvent {
     type: "thread:status:changed";
     tenantId: string;
@@ -5543,7 +5754,26 @@ interface ThreadStatusChangedEvent {
         pendingCount?: number;
     };
 }
-type AgentLifecycleEventName = 'message:started' | 'message:completed' | 'message:interrupted' | 'message:failed' | 'thread:busy' | 'thread:idle' | 'queue:pending';
+/**
+ * Union of all lifecycle event names emitted by {@link Agent}.
+ *
+ * Used with {@link Agent.subscribe} / {@link Agent.subscribeOnce} to listen
+ * for agent state changes. Events are automatically namespaced as
+ * `{eventName}:{tenantId}:{threadId}`.
+ *
+ * | Event | Fires when |
+ * |-------|-----------|
+ * | `message:started` | An individual message begins processing |
+ * | `message:completed` | An individual message finishes processing |
+ * | `message:interrupted` | A message was interrupted (e.g. human approval) |
+ * | `message:failed` | A message execution threw an error |
+ * | `thread:busy` | The thread starts processing its queue |
+ * | `thread:idle` | The thread has no more pending messages |
+ * | `queue:pending` | A new message was added to the queue |
+ * | `reply:ready` | Agent execution finished, AI response is available |
+ */
+type AgentLifecycleEventName = 'message:started' | 'message:completed' | 'message:interrupted' | 'message:failed' | 'thread:busy' | 'thread:idle' | 'queue:pending' | 'reply:ready';
+/** Emitted when the agent starts processing a queued message. */
 interface MessageStartedEvent {
     type: 'message:started';
     messageId: string;
@@ -5551,6 +5781,12 @@ interface MessageStartedEvent {
     timestamp: Date;
     queueMode?: QueueMode;
 }
+/**
+ * Emitted when the agent finishes processing a queued message.
+ *
+ * The {@link state} field contains a LangGraph {@link StateSnapshot} which
+ * includes the full conversation history in `state.values.messages`.
+ */
 interface MessageCompletedEvent {
     type: 'message:completed';
     messageId: string;
@@ -5558,23 +5794,27 @@ interface MessageCompletedEvent {
     duration?: number;
     state?: any;
 }
+/** Emitted when message processing throws an unrecoverable error. */
 interface MessageFailedEvent {
     type: 'message:failed';
     messageId: string;
     error: string;
     timestamp: Date;
 }
+/** Emitted when the thread has drained its queue and returned to idle. */
 interface ThreadIdleEvent {
     type: 'thread:idle';
     timestamp: Date;
     pendingCount: number;
     state?: any;
 }
+/** Emitted when a thread transitions from idle to busy (queue processing started). */
 interface ThreadBusyEvent {
     type: 'thread:busy';
     timestamp: Date;
     messageId?: string;
 }
+/** Emitted when a message is enqueued but not yet processing. */
 interface QueuePendingEvent {
     type: 'queue:pending';
     messageId: string;
@@ -5584,6 +5824,12 @@ interface QueuePendingEvent {
     isHighPriority: boolean;
 }
 
+/**
+ * Parameters that uniquely identify an agent thread instance.
+ *
+ * Used by {@link AgentInstanceManager.getAgent} to create or retrieve
+ * the {@link Agent} instance for a given tenant/assistant/thread combination.
+ */
 interface AgentThreadInterface {
     assistant_id: string;
     thread_id: string;
@@ -5592,6 +5838,9 @@ interface AgentThreadInterface {
     project_id?: string;
     custom_run_config?: any;
 }
+/**
+ * Record of an async task tracked by the agent (e.g. sub-agent executions).
+ */
 interface AsyncTaskRecord {
     taskId: string;
     assistantId: string;
@@ -5600,6 +5849,42 @@ interface AsyncTaskRecord {
     createdAt: number;
     completedAt?: number;
 }
+/**
+ * Per-tenant agent thread instance with message queue, streaming, and lifecycle events.
+ *
+ * Each `Agent` instance is tied to a specific `(tenant_id, assistant_id, thread_id)`
+ * tuple. It wraps a LangGraph runnable and manages:
+ *
+ * - **Message queue** — Messages are enqueued via {@link addMessage} and processed
+ *   sequentially according to the thread's {@link QueueMode} (COLLECT, FOLLOWUP, STEER).
+ * - **Streaming** — Output chunks are buffered via {@link ChunkBuffer} and consumed
+ *   through {@link chunkStream}.
+ * - **Lifecycle events** — Emits namespaced events (`message:completed`, `reply:ready`,
+ *   `thread:idle`, etc.) via a global {@link EventBus}.
+ * - **Abort / Resume** — Supports graceful interruption and recovery after restart.
+ *
+ * Instances are created and managed by {@link AgentInstanceManager}. Do not
+ * construct directly — use `agentInstanceManager.getAgent(params)`.
+ *
+ * @example
+ * ```ts
+ * const agent = agentInstanceManager.getAgent({
+ *   assistant_id: "agent-1",
+ *   thread_id: "thread-abc",
+ *   tenant_id: "tenant-x",
+ * });
+ *
+ * // Subscribe to completion
+ * agent.subscribeOnce("message:completed", (evt) => {
+ *   console.log("Agent finished:", evt.state);
+ * });
+ *
+ * // Enqueue a message
+ * const result = await agent.addMessage({
+ *   input: { message: "Hello!" },
+ * });
+ * ```
+ */
 declare class Agent {
     private queueStore;
     private stateChecker;
@@ -5614,13 +5899,37 @@ declare class Agent {
     queueMode: ThreadQueueConfig;
     private isWaitingForQueueEnd;
     asyncTasks: AsyncTaskRecord[];
+    /**
+     * 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, tenant_id, workspace_id, project_id, custom_run_config, }: AgentThreadInterface);
     private getHumanPendingContent;
     /**
      * Initialize with message queue store
      */
     setQueueStore(store: IMessageQueueStore): void;
+    /**
+     * 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: MessageChunk): Promise<void>;
+    /**
+     * 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: string, stopTypes?: MessageChunkType[]): {
         [Symbol.asyncIterator]: () => AsyncGenerator<MessageChunk, void, unknown>;
     };
@@ -5638,22 +5947,50 @@ declare class Agent {
     private getQueueStore;
     private getDefaultQueueConfig;
     /**
-     * Set queue configuration for thread
+     * Override the thread's queue processing mode.
+     *
+     * @param config - Partial {@link ThreadQueueConfig} (e.g. `{ mode: QueueMode.FOLLOWUP }`)
      */
     setQueueConfig(config: Partial<ThreadQueueConfig>): Promise<void>;
     /**
-     * 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(): void;
     /**
-     * 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
+     * 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.
      *
-     * 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
+     * **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" } } },
+     * });
+     * ```
      */
     addMessage(queueMessage: QueueMessage, mode?: QueueMode): Promise<{
         queued: boolean;
@@ -5661,8 +5998,13 @@ declare class Agent {
         executed: boolean;
     }>;
     /**
-     * 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}.
      */
     startQueueProcessorIfNeeded(): Promise<void>;
     /**
@@ -5673,24 +6015,56 @@ declare class Agent {
      * Add reminder message for interrupted tasks
      */
     private addReminderMessage;
+    /**
+     * Returns a LangGraph StateSnapshot for this thread.
+     *
+     * Includes `state.values.messages` (full conversation history) and
+     * `state.tasks` / `state.next` (execution progress).
+     */
     getCurrentState(): Promise<_langchain_langgraph.StateSnapshot>;
+    /**
+     * 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`
+     */
     getCurrentMessages(): Promise<{
         id: string | undefined;
         role: _langchain_core_messages.MessageType;
         content: string | (langchain.ContentBlock | langchain.ContentBlock.Text)[];
     }[]>;
     get_draw_graph(): Promise<string>;
+    /**
+     * 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`
+     */
     getRunStatus(): Promise<ThreadStatus>;
     /**
-     * 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.
      */
     resumeTask(): Promise<void>;
     /**
-     * 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.
      */
     abort(): Promise<void>;
     /**
@@ -5698,25 +6072,59 @@ declare class Agent {
      */
     isAborted(): boolean;
     /**
-     * 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: AgentLifecycleEventName, callback: (data: any) => void): void;
     /**
-     * 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: AgentLifecycleEventName, callback: (data: any) => void): void;
     /**
-     * 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: AgentLifecycleEventName, callback: (data: any) => void): void;
     /**
      * Publish lifecycle event (internal use)
      */
     private publish;
+    /**
+     * 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: AsyncTaskRecord): void;
     getAsyncTasks(): AsyncTaskRecord[];
     getAsyncTask(taskId: string): AsyncTaskRecord | undefined;
+    /**
+     * Update the status of a tracked async task.
+     *
+     * Terminal states (`completed`, `failed`, `cancelled`) automatically
+     * set `completedAt` to the current timestamp.
+     */
     updateAsyncTaskStatus(taskId: string, status: AsyncTaskRecord['status']): void;
 }
 
@@ -5816,6 +6224,104 @@ declare function validateEncryptionKey(): void;
  */
 declare function clearEncryptionKeyCache(): void;
 
+/**
+ * Factory function type for creating custom middleware instances.
+ *
+ * Receives the raw `config` object from the database (excluding the `key` field)
+ * and returns a LangChain `AgentMiddleware` instance, either synchronously or asynchronously.
+ *
+ * @example
+ * ```ts
+ * const factory: CustomMiddlewareFactory = (config) =>
+ *   createMiddleware({
+ *     name: "MyMiddleware",
+ *     wrapModelCall: async (request, handler) => {
+ *       console.log(`[${config.logLevel}] Model call`);
+ *       return handler(request);
+ *     },
+ *   });
+ * ```
+ */
+type CustomMiddlewareFactory = (config: Record<string, any>) => Promise<AgentMiddleware> | AgentMiddleware;
+/**
+ * Global registry for external applications to register custom middleware factories.
+ *
+ * Applications write their own middleware (auth, audit, custom tools, etc.) without
+ * modifying core source code. Once registered, middleware can be enabled per-agent via
+ * the database config using `type: "custom"` in the agent's `graphDefinition.middleware` array.
+ *
+ * @example Register and use
+ * ```ts
+ * // 1. App startup — register a factory
+ * CustomMiddlewareRegistry.register("audit-logger", (config) =>
+ *   createMiddleware({
+ *     name: "AuditLogger",
+ *     wrapModelCall: async (r, h) => { console.log("audit:", config.level); return h(r); },
+ *   }),
+ * );
+ *
+ * // 2. Database config for an agent
+ * // {
+ * //   "id": "mw-001",
+ * //   "type": "custom",
+ * //   "enabled": true,
+ * //   "config": { "key": "audit-logger", "level": "debug" }
+ * // }
+ * ```
+ *
+ * @remarks
+ * - Register factories **before** building agents (typically at app startup).
+ * - Duplicate keys overwrite previous registrations.
+ * - Unregistered keys are skipped with a console warning at agent build time.
+ */
+declare class CustomMiddlewareRegistry {
+    private static factories;
+    /**
+     * 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: string, factory: CustomMiddlewareFactory): void;
+    /**
+     * 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: string): boolean;
+    /**
+     * Look up a factory by key.
+     *
+     * @param key - The factory key
+     * @returns The factory function, or `undefined` if not registered
+     */
+    static get(key: string): CustomMiddlewareFactory | undefined;
+    /**
+     * Check whether a factory is registered under the given key.
+     *
+     * @param key - The factory key to check
+     */
+    static has(key: string): boolean;
+    /**
+     * Get all currently registered factory keys.
+     *
+     * @returns Array of registered key strings
+     */
+    static list(): string[];
+}
+
 /**
  * Create middleware that provides widget rendering capabilities.
  *
@@ -5902,4 +6408,4 @@ interface UnknownToolHandlerConfig {
  */
 declare function createUnknownToolHandlerMiddleware(config?: UnknownToolHandlerConfig): AgentMiddleware;
 
-export { AGENT_TASK_EVENT, type AddMessageParams, Agent, type AgentClient, type AgentExecutor, AgentInstanceManager, type AgentLattice, AgentLatticeManager, type AgentLifecycleEventName, AgentManager, type AgentStreamExecutor, type AgentThreadInterface, BUILTIN_SKILLS, type BackendFactory, type BackendProtocol, type BufferStats, type Chunk, ChunkBuffer, ChunkBufferLatticeManager, type ColumnInfo, CompositeBackend, ConsoleLoggerClient, type CreateProcessingAgentParams, type CreateSandboxProviderConfig, type CronFields, CustomMetricsClient, type DatabaseConfig, type DatabaseType, DaytonaInstance, DaytonaProvider, type DaytonaProviderConfig, DefaultScheduleClient, E2BInstance, E2BProvider, type E2BProviderConfig, EMPTY_CONTENT_WARNING, type EditResult, type EmbeddingsLatticeInterface, EmbeddingsLatticeManager, type EnsureMicrosandboxInput, type FileData, type FileInfo, FileSystemSkillStore, type FileSystemSkillStoreOptions, FilesystemBackend, type FsEntry, type GrepMatch, type IMessageQueueStore, type IMetricsServerClient, type ISqlDatabase, InMemoryAssistantStore, InMemoryBindingStore, InMemoryChannelInstallationStore, InMemoryChunkBuffer, InMemoryDatabaseConfigStore, InMemoryMailboxStore, InMemoryTaskListStore, InMemoryTenantStore, InMemoryThreadMessageQueueStore, InMemoryThreadStore, InMemoryUserStore, InMemoryUserTenantLinkStore, LINE_NUMBER_WIDTH, type LangGraphStateChecker, type LoggerLattice, LoggerLatticeManager, MAX_LINE_LENGTH, type MailboxMessage, type MailboxStore, type McpLatticeInterface, McpLatticeManager, type McpServerInfo, MemoryBackend, MemoryLatticeManager, MemoryQueueClient, MemoryScheduleStorage, type MessageCompletedEvent, type MessageFailedEvent, type MessageStartedEvent, MessageType, MetricsServerManager, MicrosandboxRemoteInstance, MicrosandboxRemoteProvider, type MicrosandboxRemoteProviderClient, type MicrosandboxRemoteProviderConfig, MicrosandboxServiceClient, type MicrosandboxServiceClientConfig, type MicrosandboxShellExecInput, type ModelConfig, type ModelLatticeInterface, ModelLatticeManager, MysqlDatabase, type PendingMessage, PinoLoggerClient, PostgresDatabase, PrometheusClient, type QueryResult, type QueueLattice, QueueLatticeManager, QueueMode, type QueuePendingEvent, RemoteSandboxInstance, RemoteSandboxProvider, type RemoteSandboxProviderConfig, type RunSandboxConfig, type RuntimeModelConfig, type SandboxFileInfo, type SandboxFileService, SandboxFilesystem, type SandboxInstance, type SandboxIsolationLevel, SandboxLatticeManager, type SandboxManagerProtocol, type SandboxProvider, type SandboxShellService, SandboxSkillStore, type SandboxSkillStoreOptions, type SandboxVolumeDefinition, type ScheduleLattice, ScheduleLatticeManager, type SchedulerMiddlewareOptions, SemanticMetricsClient, type SkillLattice, SkillLatticeManager, type SkillMeta, type SkillResource, SqlDatabaseManager, type StateAndStore, StateBackend, StoreBackend, type StoreLattice, StoreLatticeManager, type StoreType, type StoreTypeMap, TOOL_RESULT_TOKEN_LIMIT, TRUNCATION_GUIDANCE, type TableInfo, type TableSchema, type TaskEvent, type TaskListStore, type TaskSpec, TaskStatus, type TaskUpdatable, TeamAgentGraphBuilder, type TeamConfig, type TeamMiddlewareOptions, type TeamTask, type TeammateSpec, type TeammateToolsOptions, type ThreadBuffer, type ThreadBufferConfig, type ThreadBusyEvent, type ThreadIdleEvent, type ThreadInfo, type ThreadQueueConfig, type ThreadState, ThreadStatus, type ThreadStatusChangedEvent, type ToolDefinition, type ToolLattice, ToolLatticeManager, type TopologyEdge, type UnknownToolHandlerConfig, type VectorStoreLatticeInterface, VectorStoreLatticeManager, VolumeFilesystem, type VolumeFsClient, type WriteResult, agentInstanceManager, agentLatticeManager, buildGrepResultsDict, buildNamedVolumeName, buildSandboxMetadataEnv, buildSkillFile, checkEmptyContent, clearEncryptionKeyCache, computeSandboxName, createAgentTeam, createExecuteSqlQueryTool, createFileData, createInfoSqlTool, createListMetricsDataSourcesTool, createListMetricsServersTool, createListTablesSqlTool, createModelSelectorMiddleware, createProcessingAgent, createQueryCheckerSqlTool, createQueryMetricDefinitionTool, createQueryMetricsListTool, createQuerySemanticMetricDataTool, createQuerySqlTool, createQueryTableDefinitionTool, createQueryTablesListTool, createSandboxProvider, createSchedulerMiddleware, createTeamMiddleware, createTeammateTools, createUnknownToolHandlerMiddleware, createWidgetMiddleware, decrypt, describeCronExpression, embeddingsLatticeManager, encrypt, ensureBuiltinAgentsForTenant, eventBus, eventBus as eventBusDefault, extractFetcherError, fileDataToString, formatContentWithLineNumbers, formatGrepMatches, formatGrepResults, formatReadResponse, getAgentClient, getAgentConfig, getAllAgentConfigs, getAllBuiltInSkillMetas, getAllToolDefinitions, getBindingRegistry, getBuiltInSkillContent, getBuiltInSkillMeta, getBuiltInSkillNames, getCheckpointSaver, getChunkBuffer, getEmbeddingsClient, getEmbeddingsLattice, getEncryptionKey, getLoggerLattice, getModelLattice, getNextCronTime, getQueueLattice, getSandBoxManager, getScheduleLattice, getStoreLattice, getToolClient, getToolDefinition, getToolLattice, getVectorStoreClient, getVectorStoreLattice, globSearchFiles, grepMatchesFromFiles, grepSearchFiles, hasChunkBuffer, isBuiltInSkill, isUsingDefaultKey, isValidCronExpression, isValidSandboxName, isValidSkillName, loggerLatticeManager, mcpManager, metricsServerManager, modelLatticeManager, normalizeSandboxName, parseCronExpression, parseSkillFrontmatter, performStringReplacement, queueLatticeManager, registerAgentLattice, registerAgentLatticeWithTenant, registerAgentLattices, registerCheckpointSaver, registerChunkBuffer, registerEmbeddingsLattice, registerExistingTool, registerLoggerLattice, registerModelLattice, registerQueueLattice, registerScheduleLattice, registerStoreLattice, registerTeammateAgent, registerToolLattice, registerVectorStoreLattice, sandboxLatticeManager, sanitizeToolCallId, scheduleLatticeManager, setBindingRegistry, skillLatticeManager, sqlDatabaseManager, storeLatticeManager, toolLatticeManager, truncateIfTooLong, unregisterTeammateAgent, updateFileData, validateAgentInput, validateEncryptionKey, validatePath, validateSkillName, validateToolInput, vectorStoreLatticeManager };
+export { AGENT_TASK_EVENT, type AddMessageParams, Agent, type AgentClient, type AgentExecutor, AgentInstanceManager, type AgentLattice, AgentLatticeManager, type AgentLifecycleEventName, AgentManager, type AgentStreamExecutor, type AgentThreadInterface, BUILTIN_SKILLS, type BackendFactory, type BackendProtocol, type BufferStats, type Chunk, ChunkBuffer, ChunkBufferLatticeManager, type ColumnInfo, CompositeBackend, ConsoleLoggerClient, type CreateProcessingAgentParams, type CreateSandboxProviderConfig, type CronFields, CustomMetricsClient, type CustomMiddlewareFactory, CustomMiddlewareRegistry, type DatabaseConfig, type DatabaseType, DaytonaInstance, DaytonaProvider, type DaytonaProviderConfig, DefaultScheduleClient, E2BInstance, E2BProvider, type E2BProviderConfig, EMPTY_CONTENT_WARNING, type EditResult, type EmbeddingsLatticeInterface, EmbeddingsLatticeManager, type EnsureMicrosandboxInput, type FileData, type FileInfo, FileSystemSkillStore, type FileSystemSkillStoreOptions, FilesystemBackend, type FsEntry, type GrepMatch, type IMessageQueueStore, type IMetricsServerClient, type ISqlDatabase, InMemoryAssistantStore, InMemoryBindingStore, InMemoryChannelInstallationStore, InMemoryChunkBuffer, InMemoryDatabaseConfigStore, InMemoryMailboxStore, InMemoryTaskListStore, InMemoryTenantStore, InMemoryThreadMessageQueueStore, InMemoryThreadStore, InMemoryUserStore, InMemoryUserTenantLinkStore, LINE_NUMBER_WIDTH, type LangGraphStateChecker, type LoggerLattice, LoggerLatticeManager, MAX_LINE_LENGTH, type MailboxMessage, type MailboxStore, type McpLatticeInterface, McpLatticeManager, type McpServerInfo, MemoryBackend, MemoryLatticeManager, MemoryQueueClient, MemoryScheduleStorage, type MessageCompletedEvent, type MessageFailedEvent, type MessageStartedEvent, MessageType, MetricsServerManager, MicrosandboxRemoteInstance, MicrosandboxRemoteProvider, type MicrosandboxRemoteProviderClient, type MicrosandboxRemoteProviderConfig, MicrosandboxServiceClient, type MicrosandboxServiceClientConfig, type MicrosandboxShellExecInput, type ModelConfig, type ModelLatticeInterface, ModelLatticeManager, MysqlDatabase, type PendingMessage, PinoLoggerClient, PostgresDatabase, PrometheusClient, type QueryResult, type QueueLattice, QueueLatticeManager, QueueMode, type QueuePendingEvent, RemoteSandboxInstance, RemoteSandboxProvider, type RemoteSandboxProviderConfig, type RunSandboxConfig, type RuntimeModelConfig, type SandboxFileInfo, type SandboxFileService, SandboxFilesystem, type SandboxInstance, type SandboxIsolationLevel, SandboxLatticeManager, type SandboxManagerProtocol, type SandboxProvider, type SandboxShellService, SandboxSkillStore, type SandboxSkillStoreOptions, type SandboxVolumeDefinition, type ScheduleLattice, ScheduleLatticeManager, type SchedulerMiddlewareOptions, SemanticMetricsClient, type SkillLattice, SkillLatticeManager, type SkillMeta, type SkillResource, SqlDatabaseManager, type StateAndStore, StateBackend, StoreBackend, type StoreLattice, StoreLatticeManager, type StoreType, type StoreTypeMap, TOOL_RESULT_TOKEN_LIMIT, TRUNCATION_GUIDANCE, type TableInfo, type TableSchema, type TaskEvent, type TaskListStore, type TaskSpec, TaskStatus, type TaskUpdatable, TeamAgentGraphBuilder, type TeamConfig, type TeamMiddlewareOptions, type TeamTask, type TeammateSpec, type TeammateToolsOptions, type ThreadBuffer, type ThreadBufferConfig, type ThreadBusyEvent, type ThreadIdleEvent, type ThreadInfo, type ThreadQueueConfig, type ThreadState, ThreadStatus, type ThreadStatusChangedEvent, type ToolDefinition, type ToolLattice, ToolLatticeManager, type TopologyEdge, type UnknownToolHandlerConfig, type VectorStoreLatticeInterface, VectorStoreLatticeManager, VolumeFilesystem, type VolumeFsClient, type WriteResult, agentInstanceManager, agentLatticeManager, buildGrepResultsDict, buildNamedVolumeName, buildSandboxMetadataEnv, buildSkillFile, checkEmptyContent, clearEncryptionKeyCache, computeSandboxName, configureStores, createAgentTeam, createExecuteSqlQueryTool, createFileData, createInfoSqlTool, createListMetricsDataSourcesTool, createListMetricsServersTool, createListTablesSqlTool, createModelSelectorMiddleware, createProcessingAgent, createQueryCheckerSqlTool, createQueryMetricDefinitionTool, createQueryMetricsListTool, createQuerySemanticMetricDataTool, createQuerySqlTool, createQueryTableDefinitionTool, createQueryTablesListTool, createSandboxProvider, createSchedulerMiddleware, createTeamMiddleware, createTeammateTools, createUnknownToolHandlerMiddleware, createWidgetMiddleware, decrypt, describeCronExpression, embeddingsLatticeManager, encrypt, ensureBuiltinAgentsForTenant, eventBus, eventBus as eventBusDefault, extractFetcherError, fileDataToString, formatContentWithLineNumbers, formatGrepMatches, formatGrepResults, formatReadResponse, getAgentClient, getAgentConfig, getAllAgentConfigs, getAllBuiltInSkillMetas, getAllToolDefinitions, getBindingRegistry, getBuiltInSkillContent, getBuiltInSkillMeta, getBuiltInSkillNames, getCheckpointSaver, getChunkBuffer, getEmbeddingsClient, getEmbeddingsLattice, getEncryptionKey, getLoggerLattice, getModelLattice, getNextCronTime, getQueueLattice, getSandBoxManager, getScheduleLattice, getStoreLattice, getToolClient, getToolDefinition, getToolLattice, getVectorStoreClient, getVectorStoreLattice, globSearchFiles, grepMatchesFromFiles, grepSearchFiles, hasChunkBuffer, isBuiltInSkill, isUsingDefaultKey, isValidCronExpression, isValidSandboxName, isValidSkillName, loggerLatticeManager, mcpManager, metricsServerManager, modelLatticeManager, normalizeSandboxName, parseCronExpression, parseSkillFrontmatter, performStringReplacement, queueLatticeManager, registerAgentLattice, registerAgentLatticeWithTenant, registerAgentLattices, registerCheckpointSaver, registerChunkBuffer, registerEmbeddingsLattice, registerExistingTool, registerLoggerLattice, registerModelLattice, registerQueueLattice, registerScheduleLattice, registerStoreLattice, registerTeammateAgent, registerToolLattice, registerVectorStoreLattice, sandboxLatticeManager, sanitizeToolCallId, scheduleLatticeManager, setBindingRegistry, skillLatticeManager, sqlDatabaseManager, storeLatticeManager, toolLatticeManager, truncateIfTooLong, unregisterTeammateAgent, updateFileData, validateAgentInput, validateEncryptionKey, validatePath, validateSkillName, validateToolInput, vectorStoreLatticeManager };