@axiom-lattice/core 2.1.76 → 2.1.78

package/dist/index.js

@@ -42,6 +42,7 @@ __export(index_exports, {
   CompositeBackend: () => CompositeBackend,
   ConsoleLoggerClient: () => ConsoleLoggerClient,
   CustomMetricsClient: () => CustomMetricsClient,
+  CustomMiddlewareRegistry: () => CustomMiddlewareRegistry,
   DaytonaInstance: () => DaytonaInstance,
   DaytonaProvider: () => DaytonaProvider,
   DefaultScheduleClient: () => DefaultScheduleClient,
@@ -51,7 +52,8 @@ __export(index_exports, {
   EmbeddingsLatticeManager: () => EmbeddingsLatticeManager,
   FileSystemSkillStore: () => FileSystemSkillStore,
   FilesystemBackend: () => FilesystemBackend,
-  HumanMessage: () => import_messages5.HumanMessage,
+  HumanMessage: () => import_messages6.HumanMessage,
+  InMemoryA2AApiKeyStore: () => InMemoryA2AApiKeyStore,
   InMemoryAssistantStore: () => InMemoryAssistantStore,
   InMemoryBindingStore: () => InMemoryBindingStore,
   InMemoryChannelInstallationStore: () => InMemoryChannelInstallationStore,
@@ -1893,6 +1895,7 @@ var InMemoryProjectStore = class {
       workspaceId,
       name: data.name,
       description: data.description,
+      config: data.config,
       createdAt: now,
       updatedAt: now
     };
@@ -1900,6 +1903,13 @@ var InMemoryProjectStore = class {
     this.projects.set(key, project);
     return project;
   }
+  /**
+   * Update an existing project
+   *
+   * @remarks
+   * - The `config` field uses **replace** semantics: if provided, it completely
+   *   overwrites the existing config. To preserve the current config, omit this field.
+   */
   async updateProject(tenantId, id, updates) {
     const key = this.getKey(tenantId, id);
     const existing = this.projects.get(key);
@@ -2691,14 +2701,35 @@ var InMemoryChannelInstallationStore = class {
   constructor() {
     this.installations = /* @__PURE__ */ new Map();
   }
+  /**
+   * Retrieves a channel installation by its unique ID.
+   *
+   * @param installationId - The installation identifier
+   * @returns The {@link ChannelInstallation} or `null` if not found
+   */
   async getInstallationById(installationId) {
     return this.installations.get(installationId) || null;
   }
+  /**
+   * Lists all channel installations for a tenant, optionally filtered by channel type.
+   *
+   * @param tenantId - Tenant identifier
+   * @param channel - Optional channel type filter (`"lark"`, `"email"`, `"slack"`)
+   * @returns Array of matching {@link ChannelInstallation} objects
+   */
   async getInstallationsByTenant(tenantId, channel) {
     return Array.from(this.installations.values()).filter(
       (inst) => inst.tenantId === tenantId && (!channel || inst.channel === channel)
     );
   }
+  /**
+   * Creates a new channel installation for a tenant.
+   *
+   * @param tenantId - Tenant identifier
+   * @param installationId - Unique installation ID (caller-defined)
+   * @param data - {@link CreateChannelInstallationRequest} containing channel type, name, config, and fallback settings
+   * @returns The created {@link ChannelInstallation}
+   */
   async createInstallation(tenantId, installationId, data) {
     const now = /* @__PURE__ */ new Date();
     const installation = {
@@ -2716,6 +2747,14 @@ var InMemoryChannelInstallationStore = class {
     this.installations.set(installationId, installation);
     return installation;
   }
+  /**
+   * Updates an existing channel installation. Config fields are shallow-merged.
+   *
+   * @param tenantId - Tenant identifier (used for isolation check)
+   * @param installationId - Installation ID to update
+   * @param updates - {@link UpdateChannelInstallationRequest} with fields to patch
+   * @returns The updated {@link ChannelInstallation} or `null` if not found or tenant mismatch
+   */
   async updateInstallation(tenantId, installationId, updates) {
     const existing = this.installations.get(installationId);
     if (!existing || existing.tenantId !== tenantId) return null;
@@ -2731,11 +2770,21 @@ var InMemoryChannelInstallationStore = class {
     this.installations.set(installationId, updated);
     return updated;
   }
+  /**
+   * Deletes a channel installation.
+   *
+   * @param tenantId - Tenant identifier (used for isolation check)
+   * @param installationId - Installation ID to delete
+   * @returns `true` if deleted, `false` if not found or tenant mismatch
+   */
   async deleteInstallation(tenantId, installationId) {
     const existing = this.installations.get(installationId);
     if (!existing || existing.tenantId !== tenantId) return false;
     return this.installations.delete(installationId);
   }
+  /**
+   * Clears all in-memory installations. Primarily used in tests.
+   */
   clear() {
     this.installations.clear();
   }
@@ -2747,6 +2796,16 @@ var InMemoryBindingStore = class {
   constructor() {
     this.bindings = /* @__PURE__ */ new Map();
   }
+  /**
+   * Resolves a binding for the given sender across a specific channel installation.
+   *
+   * Called by `MessageRouter.dispatch()` during inbound message processing.
+   * Matches on `channel + senderId + channelInstallationId + tenantId` and
+   * requires `enabled === true`.
+   *
+   * @param params - Resolution parameters
+   * @returns The matching {@link Binding} or `null` if none found.
+   */
   async resolve(params) {
     for (const binding of this.bindings.values()) {
       if (binding.channel === params.channel && binding.senderId === params.senderId && binding.channelInstallationId === params.channelInstallationId && binding.tenantId === params.tenantId && binding.enabled) {
@@ -2755,6 +2814,12 @@ var InMemoryBindingStore = class {
     }
     return null;
   }
+  /**
+   * Creates a new sender-to-agent binding.
+   *
+   * @param input - {@link CreateBindingInput} defining channel, sender, target agent, and thread mode.
+   * @returns The newly created {@link Binding}.
+   */
   async create(input) {
     const now = /* @__PURE__ */ new Date();
     const binding = {
@@ -2777,6 +2842,14 @@ var InMemoryBindingStore = class {
     this.bindings.set(binding.id, binding);
     return binding;
   }
+  /**
+   * Updates an existing binding (e.g. changing the target agent or thread mode).
+   *
+   * @param id - Binding ID
+   * @param patch - Partial {@link Binding} fields to update
+   * @returns The updated {@link Binding}
+   * @throws {Error} If the binding does not exist
+   */
   async update(id, patch) {
     const existing = this.bindings.get(id);
     if (!existing) throw new Error(`Binding ${id} not found`);
@@ -2788,9 +2861,20 @@ var InMemoryBindingStore = class {
     this.bindings.set(id, updated);
     return updated;
   }
+  /**
+   * Deletes a binding by ID.
+   *
+   * @param id - Binding ID
+   */
   async delete(id) {
     this.bindings.delete(id);
   }
+  /**
+   * Lists bindings filtered by tenant and optional channel/agent/installation.
+   *
+   * @param params - Filter and pagination parameters
+   * @returns Array of matching {@link Binding} objects
+   */
   async list(params) {
     let results = Array.from(this.bindings.values()).filter((b) => {
       if (b.tenantId !== params.tenantId) return false;
@@ -2803,6 +2887,12 @@ var InMemoryBindingStore = class {
     const limit = params.limit ?? 50;
     return results.slice(offset, offset + limit);
   }
+  /**
+   * Bulk-imports bindings.
+   *
+   * @param bindings - Array of {@link CreateBindingInput}
+   * @returns Array of created {@link Binding} objects
+   */
   async import(bindings) {
     const result = [];
     for (const input of bindings) {
@@ -2810,14 +2900,104 @@ 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();
   }
 };
 
+// src/store_lattice/InMemoryA2AApiKeyStore.ts
+var import_crypto2 = require("crypto");
+function generateApiKey() {
+  return `a2a_${(0, import_crypto2.randomUUID)().replace(/-/g, "")}`;
+}
+var InMemoryA2AApiKeyStore = class {
+  constructor() {
+    this.keys = /* @__PURE__ */ new Map();
+  }
+  async findByKey(key) {
+    for (const record of this.keys.values()) {
+      if (record.key === key && record.enabled) return record;
+    }
+    return null;
+  }
+  async list(params) {
+    let records = Array.from(this.keys.values());
+    if (params.tenantId) {
+      records = records.filter((r) => r.tenantId === params.tenantId);
+    }
+    const offset = params.offset || 0;
+    const limit = params.limit;
+    records = records.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+    return limit ? records.slice(offset, offset + limit) : records.slice(offset);
+  }
+  async create(input) {
+    const now = /* @__PURE__ */ new Date();
+    const record = {
+      id: (0, import_crypto2.randomUUID)(),
+      key: generateApiKey(),
+      tenantId: input.tenantId,
+      projectId: input.projectId,
+      workspaceId: input.workspaceId,
+      label: input.label,
+      enabled: true,
+      createdAt: now,
+      updatedAt: now
+    };
+    this.keys.set(record.id, record);
+    return record;
+  }
+  async disable(id) {
+    const record = this.keys.get(id);
+    if (!record) throw new Error(`A2A API key not found: ${id}`);
+    const updated = { ...record, enabled: false, updatedAt: /* @__PURE__ */ new Date() };
+    this.keys.set(id, updated);
+    return updated;
+  }
+  async enable(id) {
+    const record = this.keys.get(id);
+    if (!record) throw new Error(`A2A API key not found: ${id}`);
+    const updated = { ...record, enabled: true, updatedAt: /* @__PURE__ */ new Date() };
+    this.keys.set(id, updated);
+    return updated;
+  }
+  async rotate(id) {
+    const record = this.keys.get(id);
+    if (!record) throw new Error(`A2A API key not found: ${id}`);
+    const updated = { ...record, key: generateApiKey(), updatedAt: /* @__PURE__ */ new Date() };
+    this.keys.set(id, updated);
+    return updated;
+  }
+  async delete(id) {
+    this.keys.delete(id);
+  }
+  async loadIntoMap() {
+    const map = /* @__PURE__ */ new Map();
+    for (const record of this.keys.values()) {
+      if (record.enabled) {
+        map.set(record.key, {
+          key: record.key,
+          tenantId: record.tenantId,
+          projectId: record.projectId,
+          workspaceId: record.workspaceId
+        });
+      }
+    }
+    return map;
+  }
+};
+
 // src/store_lattice/StoreLatticeManager.ts
 var StoreLatticeManager = class _StoreLatticeManager extends BaseLatticeManager {
   /**
@@ -2992,6 +3172,12 @@ storeLatticeManager.registerLattice(
   "channelBinding",
   defaultChannelBindingStore
 );
+var defaultA2AApiKeyStore = new InMemoryA2AApiKeyStore();
+storeLatticeManager.registerLattice(
+  "default",
+  "a2aApiKey",
+  defaultA2AApiKeyStore
+);
 
 // src/tool_lattice/manage_binding/index.ts
 function getInstallationStore() {
@@ -7079,7 +7265,7 @@ var createBrowserGetInfoTool = ({ vmIsolation }) => {
 };
 
 // src/index.ts
-var import_messages5 = require("@langchain/core/messages");
+var import_messages6 = require("@langchain/core/messages");
 
 // src/agent_lattice/types.ts
 var import_protocols = require("@axiom-lattice/protocols");
@@ -12113,6 +12299,14 @@ var ThreadStatus2 = /* @__PURE__ */ ((ThreadStatus3) => {
   return ThreadStatus3;
 })(ThreadStatus2 || {});
 var Agent = class {
+  /**
+   * Constructs an Agent instance.
+   *
+   * Prefer {@link AgentInstanceManager.getAgent} over direct construction — it
+   * ensures a single instance per thread.
+   *
+   * @param params - {@link AgentThreadInterface}
+   */
   constructor({
     assistant_id,
     thread_id,
@@ -12325,6 +12519,7 @@ var Agent = class {
               await this.queueStore?.removeMessage(p.id);
               const runStatus = await this.getRunStatus();
               const state = await this.getCurrentState();
+              const customRunConfig = p.custom_run_config ?? queueMessageData.custom_run_config;
               if (runStatus === "interrupted" /* INTERRUPTED */) {
                 this.publish("message:interrupted", {
                   type: "message:interrupted",
@@ -12349,6 +12544,12 @@ var Agent = class {
                   state
                 });
               }
+              this.publish("reply:ready", {
+                type: "reply:ready",
+                timestamp: /* @__PURE__ */ new Date(),
+                state,
+                customRunConfig
+              });
             } catch (error) {
               console.error(`STEER/Command message ${p.id} execution failed:`, error);
               this.addChunk({
@@ -12427,6 +12628,12 @@ var Agent = class {
                   });
                 }
               }
+              this.publish("reply:ready", {
+                type: "reply:ready",
+                timestamp: /* @__PURE__ */ new Date(),
+                state,
+                customRunConfig: remainingPendings[0]?.custom_run_config ?? firstQueueMessage?.custom_run_config
+              });
             } catch (error) {
               console.error(`COLLECT mode execution failed:`, error);
               for (const p of remainingPendings) {
@@ -12475,6 +12682,7 @@ var Agent = class {
                 await this.queueStore?.removeMessage(p.id);
                 const runStatus = await this.getRunStatus();
                 const state = await this.getCurrentState();
+                const customRunConfig = p.custom_run_config ?? queueMessageData.custom_run_config;
                 if (runStatus === "interrupted" /* INTERRUPTED */) {
                   this.publish("message:interrupted", {
                     type: "message:interrupted",
@@ -12499,6 +12707,12 @@ var Agent = class {
                     state
                   });
                 }
+                this.publish("reply:ready", {
+                  type: "reply:ready",
+                  timestamp: /* @__PURE__ */ new Date(),
+                  state,
+                  customRunConfig
+                });
               } catch (error) {
                 console.error(`FOLLOWUP mode message ${p.id} execution failed:`, error);
                 this.addChunk({
@@ -12541,9 +12755,25 @@ var Agent = class {
   setQueueStore(store) {
     this.queueStore = store;
   }
+  /**
+   * Push a chunk into the streaming buffer for this thread.
+   *
+   * Consumers read chunks via {@link chunkStream}.
+   *
+   * @param content - The message chunk to buffer
+   */
   addChunk(content) {
     return this.chunkBuffer.addChunk(this.thread_id, content);
   }
+  /**
+   * Returns an async iterator over new chunks since the given message ID.
+   *
+   * Used by SSE endpoints to stream agent output to clients in real time.
+   *
+   * @param message_id - The client message ID to start streaming from
+   * @param stopTypes - Optional chunk types that terminate the stream
+   * @returns An async iterable yielding {@link MessageChunk} objects
+   */
   chunkStream(message_id, stopTypes) {
     const stream = this.chunkBuffer.getNewChunksSinceContentIterator(
       this.thread_id,
@@ -12632,13 +12862,21 @@ var Agent = class {
     };
   }
   /**
-   * Set queue configuration for thread
+   * Override the thread's queue processing mode.
+   *
+   * @param config - Partial {@link ThreadQueueConfig} (e.g. `{ mode: QueueMode.FOLLOWUP }`)
    */
   async setQueueConfig(config) {
     this.queueMode = { ...this.queueMode, ...config };
   }
   /**
-   * Stop queue processor
+   * Abort any ongoing queue processing without clearing the queue.
+   *
+   * Used internally by STEER mode to interrupt the current execution so the
+   * steer message can be processed next. For a full abort that also clears
+   * pending messages, use {@link abort}.
+   *
+   * @see {@link abort}
    */
   stopQueueProcessor() {
     if (this.abortController) {
@@ -12647,14 +12885,34 @@ var Agent = class {
     }
   }
   /**
-   * Add message to queue
-   * All messages go to queue, processor auto-starts if not running
-   * STEER/Command messages are inserted at head of queue for immediate processing
-   * 
-   * Supports both legacy single message format and new messages[] format:
-   * - Legacy: input.message (single human message)
-   * - New: input.messages[] (array of mixed human/system messages)
-   * - When input.messages is provided, it takes precedence over input.message
+   * Enqueue a message for this thread.
+   *
+   * Messages are always queued; the queue processor starts automatically if idle.
+   * Returns immediately with the message ID — execution is asynchronous.
+   *
+   * **Queue modes** (via the optional `mode` param):
+   * - `COLLECT` (default) — Batch multiple pending messages into one agent call.
+   * - `FOLLOWUP` — Process messages one at a time in order.
+   * - `STEER` — High-priority, inserted at queue head, interrupts current processing.
+   *
+   * **Format**: Supports both `input.message` (legacy string) and `input.messages[]`
+   * (array of `{ role, content }` objects). The array form takes precedence.
+   *
+   * The `custom_run_config` field is round-tripped through the queue and emitted
+   * back in {@link ReplyReadyEvent}, enabling callers to attach routing metadata
+   * (e.g. `_replyTarget` for channel reply).
+   *
+   * @param queueMessage - The message to enqueue
+   * @param mode - Optional queue mode override (defaults to thread's current mode)
+   * @returns `{ queued: true, executed: false, messageId }` — execution happens asynchronously
+   *
+   * @example
+   * ```ts
+   * await agent.addMessage({
+   *   input: { message: "Hello" },
+   *   custom_run_config: { _replyTarget: { adapterChannel: "lark", rawTarget: { chatId: "xxx" } } },
+   * });
+   * ```
    */
   async addMessage(queueMessage, mode) {
     const useMode = mode ?? this.queueMode.mode;
@@ -12748,8 +13006,13 @@ var Agent = class {
     return { queued: true, executed: false, messageId };
   }
   /**
-   * Start queue processor if not already running
-   * Public method to allow external triggering (e.g., from recovery)
+   * Start the queue processor if it is not already running.
+   *
+   * Called automatically by {@link addMessage} and {@link resumeTask}.
+   * Safe to call externally — it is a no-op if processing is already active.
+   *
+   * Emits `thread:busy` before starting, and starts the {@link waitingForQueueEnd}
+   * loop with a fresh {@link AbortController}.
    */
   async startQueueProcessorIfNeeded() {
     const store = this.getQueueStore();
@@ -12797,6 +13060,12 @@ var Agent = class {
       type: "system"
     });
   }
+  /**
+   * Returns a LangGraph StateSnapshot for this thread.
+   *
+   * Includes `state.values.messages` (full conversation history) and
+   * `state.tasks` / `state.next` (execution progress).
+   */
   async getCurrentState() {
     const { runnable_agent } = await this.getLatticeClientAndRuntimeConfig();
     const state = await runnable_agent.getState({
@@ -12804,6 +13073,14 @@ var Agent = class {
     });
     return state;
   }
+  /**
+   * Returns the conversation history as normalized message objects.
+   *
+   * Filters to `human`, `ai`, and `tool` message types. Each entry has
+   * `{ id, role, content }` plus any LangChain kwargs.
+   *
+   * @returns Array of message objects with `id`, `role`, and `content`
+   */
   async getCurrentMessages() {
     const state = await this.getCurrentState();
     const messages = state.values.messages || [];
@@ -12826,6 +13103,14 @@ var Agent = class {
     const image = await drawableGraph.drawMermaid();
     return image;
   }
+  /**
+   * Determine the current thread execution status.
+   *
+   * Checks LangGraph's `state.tasks` for interrupts and `state.next` for
+   * pending steps.
+   *
+   * @returns {@link ThreadStatus} — `IDLE`, `BUSY`, or `INTERRUPTED`
+   */
   async getRunStatus() {
     const state = await this.getCurrentState();
     const isInterrupted = state.tasks?.some(
@@ -12840,9 +13125,14 @@ var Agent = class {
     return "idle" /* IDLE */;
   }
   /**
-   * Resume task processing after server restart
-   * Resets any stuck processing messages to pending and starts queue processing
-   * Note: Does not rely on LangGraph state as it may be stale after crash/restart
+   * Resume processing after a server restart.
+   *
+   * Resets any stuck "processing" messages back to "pending" and restarts the
+   * queue processor. Skips threads that are in `INTERRUPTED` state (the
+   * interruption was intentional).
+   *
+   * Called during gateway startup to recover threads that were mid-execution
+   * when the server went down.
    */
   async resumeTask() {
     try {
@@ -12864,9 +13154,14 @@ var Agent = class {
     await this.startQueueProcessorIfNeeded();
   }
   /**
-   * Abort the current agent execution
-   * This will cancel any ongoing invoke or stream operations
-   * and clear all queued messages (pending + processing)
+   * Fully abort all activity on this thread.
+   *
+   * Aborts any in-flight agent execution (via {@link AbortController}) and
+   * clears all pending and processing messages from the queue. Also marks
+   * the chunk buffer thread as aborted so streaming consumers can detect it.
+   *
+   * Unlike {@link stopQueueProcessor}, this is a destructive abort — the
+   * queue is drained.
    */
   async abort() {
     if (this.abortController) {
@@ -12884,22 +13179,44 @@ var Agent = class {
     return this.abortController?.signal.aborted ?? false;
   }
   /**
-   * Subscribe to lifecycle events for this agent/thread
-   * Events are automatically namespaced by tenantId and threadId
+   * Subscribe to a lifecycle event for this specific thread.
+   *
+   * Event names are namespaced as `{eventName}:{tenantId}:{threadId}` so
+   * listeners only receive events for this agent instance.
+   *
+   * @param eventName - One of {@link AgentLifecycleEventName}
+   * @param callback - Handler receiving the event data payload
+   *
+   * @example
+   * ```ts
+   * agent.subscribe("message:completed", (evt) => {
+   *   console.log("AI response:", evt.state?.values?.messages);
+   * });
+   * ```
    */
   subscribe(eventName, callback) {
     const namespacedEvent = `${eventName}:${this.tenant_id}:${this.thread_id}`;
     event_bus_default.subscribe(namespacedEvent, callback);
   }
   /**
-   * Unsubscribe from lifecycle events
+   * Remove a previously registered event listener.
+   *
+   * @param eventName - The event that was subscribed to
+   * @param callback - The same function reference used in {@link subscribe}
    */
   unsubscribe(eventName, callback) {
     const namespacedEvent = `${eventName}:${this.tenant_id}:${this.thread_id}`;
     event_bus_default.unsubscribe(namespacedEvent, callback);
   }
   /**
-   * Subscribe to lifecycle events once (auto-unsubscribe after first event)
+   * Subscribe to a lifecycle event once — the listener is removed after the
+   * first invocation.
+   *
+   * Ideal for one-shot async patterns (e.g. waiting for `reply:ready` before
+   * sending a channel reply).
+   *
+   * @param eventName - One of {@link AgentLifecycleEventName}
+   * @param callback - Handler receiving the event data payload
    */
   subscribeOnce(eventName, callback) {
     const namespacedEvent = `${eventName}:${this.tenant_id}:${this.thread_id}`;
@@ -12913,6 +13230,12 @@ var Agent = class {
     console.log(namespacedEvent);
     event_bus_default.publish(namespacedEvent, data);
   }
+  /**
+   * Track a sub-agent async task spawned by this agent.
+   *
+   * Tasks are monitored by the agent task consumer in `packages/gateway`
+   * and their status can be polled via {@link getAsyncTasks}.
+   */
   addAsyncTask(task) {
     this.asyncTasks.push(task);
   }
@@ -12922,6 +13245,12 @@ var Agent = class {
   getAsyncTask(taskId) {
     return this.asyncTasks.find((t) => t.taskId === taskId);
   }
+  /**
+   * Update the status of a tracked async task.
+   *
+   * Terminal states (`completed`, `failed`, `cancelled`) automatically
+   * set `completedAt` to the current timestamp.
+   */
   updateAsyncTaskStatus(taskId, status) {
     const task = this.getAsyncTask(taskId);
     if (!task) return;
@@ -13287,6 +13616,65 @@ function createSchedulerMiddleware(options = {}) {
   });
 }
 
+// src/agent_lattice/builders/CustomMiddlewareRegistry.ts
+var CustomMiddlewareRegistry = class {
+  /**
+   * Register a custom middleware factory under the given key.
+   *
+   * The key is referenced by `config.key` in the database middleware configuration.
+   * When an agent is built, the framework looks up this key and calls the factory
+   * with the remaining config fields.
+   *
+   * @param key - Unique identifier, referenced in database config as `config.key`
+   * @param factory - Function that receives config (minus `key`) and returns an AgentMiddleware
+   *
+   * @example
+   * ```ts
+   * CustomMiddlewareRegistry.register("my-logger", (config) =>
+   *   createMiddleware({ name: "Logger", beforeAgent: async () => { ... } }),
+   * );
+   * ```
+   */
+  static register(key, factory) {
+    this.factories.set(key, factory);
+  }
+  /**
+   * Remove a previously registered factory.
+   *
+   * @param key - The factory key to unregister
+   * @returns `true` if a factory was removed, `false` if the key was not found
+   */
+  static unregister(key) {
+    return this.factories.delete(key);
+  }
+  /**
+   * Look up a factory by key.
+   *
+   * @param key - The factory key
+   * @returns The factory function, or `undefined` if not registered
+   */
+  static get(key) {
+    return this.factories.get(key);
+  }
+  /**
+   * Check whether a factory is registered under the given key.
+   *
+   * @param key - The factory key to check
+   */
+  static has(key) {
+    return this.factories.has(key);
+  }
+  /**
+   * Get all currently registered factory keys.
+   *
+   * @returns Array of registered key strings
+   */
+  static list() {
+    return Array.from(this.factories.keys());
+  }
+};
+CustomMiddlewareRegistry.factories = /* @__PURE__ */ new Map();
+
 // src/agent_lattice/builders/commonMiddleware.ts
 async function createCommonMiddlewares(middlewareConfigs, filesystemBackend, fsIsExised) {
   const middlewares = [];
@@ -13363,6 +13751,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;
@@ -17969,6 +18372,227 @@ var ProcessingAgentGraphBuilder = class {
   }
 };
 
+// src/agent_lattice/builders/RemoteAgentGraphBuilder.ts
+var import_langgraph14 = require("@langchain/langgraph");
+var import_messages5 = require("@langchain/core/messages");
+
+// src/services/a2a-client.ts
+var import_uuid4 = require("uuid");
+var A2ARemoteError = class extends Error {
+  constructor(message, statusCode, body) {
+    super(message);
+    this.statusCode = statusCode;
+    this.body = body;
+    this.name = "A2ARemoteError";
+  }
+};
+var A2ARemoteClient = class {
+  constructor(config) {
+    this.config = config;
+    this.jsonRpcUrl = null;
+    this.card = null;
+  }
+  // ── Resolution ───────────────────────────────────────────────────────────
+  /**
+   * Fetch the agent card and resolve the JSON-RPC endpoint.
+   */
+  async resolve() {
+    if (this.card) return this.card;
+    const resp = await fetch(this.config.agentCardUrl, {
+      signal: AbortSignal.timeout(this.config.timeout ?? 3e4)
+    });
+    if (!resp.ok) {
+      throw new A2ARemoteError(
+        `Failed to fetch agent card: HTTP ${resp.status}`,
+        resp.status
+      );
+    }
+    this.card = await resp.json();
+    const card = this.card;
+    const jsonRpc = card.additionalInterfaces?.find(
+      (i) => i.transport === "JSONRPC"
+    );
+    this.jsonRpcUrl = jsonRpc?.url ?? card.url;
+    return this.card;
+  }
+  // ── Execute ──────────────────────────────────────────────────────────────
+  /**
+   * Send a text prompt to the remote A2A agent and return the response.
+   *
+   * Supports SSE streaming (parses status-update events) and falls back
+   * to polling the task status for non-streaming agents.
+   */
+  async sendMessage(text) {
+    await this.resolve();
+    const taskId = (0, import_uuid4.v4)();
+    const body = JSON.stringify({
+      jsonrpc: "2.0",
+      method: "tasks/send",
+      params: {
+        id: taskId,
+        message: {
+          role: "user",
+          parts: [{ kind: "text", text }]
+        }
+      },
+      id: taskId
+    });
+    const headers = {
+      "Content-Type": "application/json",
+      "Accept": "text/event-stream"
+    };
+    if (this.config.apiKey) {
+      headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+    }
+    const resp = await fetch(this.jsonRpcUrl, {
+      method: "POST",
+      headers,
+      body,
+      signal: AbortSignal.timeout(this.config.timeout ?? 3e5)
+    });
+    if (!resp.ok) {
+      const text2 = await resp.text().catch(() => "");
+      throw new A2ARemoteError(
+        `A2A request failed: HTTP ${resp.status}`,
+        resp.status,
+        text2
+      );
+    }
+    const contentType = resp.headers.get("content-type") ?? "";
+    if (contentType.includes("text/event-stream")) {
+      return this.parseSSE(resp);
+    }
+    const json = await resp.json();
+    return this.extractArtifactText(json);
+  }
+  // ── SSE Parsing ──────────────────────────────────────────────────────────
+  async parseSSE(resp) {
+    if (!resp.body) {
+      throw new A2ARemoteError("Empty response body");
+    }
+    const reader = resp.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer2 = "";
+    let accumulatedText = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer2 += decoder.decode(value, { stream: true });
+        const lines = buffer2.split("\n");
+        buffer2 = lines.pop() ?? "";
+        for (const line of lines) {
+          if (line.startsWith("data: ")) {
+            const data = line.slice(6).trim();
+            if (!data) continue;
+            try {
+              const event = JSON.parse(data);
+              this.handleSSEEvent(event, (t) => {
+                accumulatedText += t;
+              });
+            } catch {
+            }
+          }
+        }
+      }
+      if (buffer2.startsWith("data: ")) {
+        const data = buffer2.slice(6).trim();
+        if (data) {
+          try {
+            const event = JSON.parse(data);
+            this.handleSSEEvent(event, (t) => {
+              accumulatedText += t;
+            });
+          } catch {
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    return accumulatedText;
+  }
+  handleSSEEvent(event, onText) {
+    const e = event;
+    const messageParts = e.status?.message?.parts;
+    if (messageParts) {
+      for (const part of messageParts) {
+        if (part.text) onText(part.text);
+      }
+    }
+  }
+  // ── Artifact Extraction ──────────────────────────────────────────────────
+  extractArtifactText(task) {
+    const artifacts = task.artifacts ?? [];
+    return artifacts.flatMap((a) => a.parts ?? []).filter((p) => p.text).map((p) => p.text).join("\n");
+  }
+};
+
+// src/agent_lattice/builders/RemoteAgentGraphBuilder.ts
+var import_protocols9 = require("@axiom-lattice/protocols");
+var RemoteAgentGraphBuilder = class {
+  async build(agentLattice, params) {
+    if (agentLattice.config.type !== import_protocols9.AgentType.A2A_REMOTE) {
+      throw new Error(
+        `RemoteAgentGraphBuilder received wrong agent type: ${agentLattice.config.type}`
+      );
+    }
+    const config = agentLattice.config;
+    const client = new A2ARemoteClient({
+      agentCardUrl: config.agentCardUrl,
+      apiKey: config.apiKey,
+      timeout: config.timeout
+    });
+    await client.resolve();
+    const remoteCallNode = async (state) => {
+      const messages = state.messages ?? [];
+      const text = extractLastHumanMessage(messages);
+      if (!text) {
+        return {
+          messages: [
+            new import_messages5.AIMessage("No text input provided to remote agent.")
+          ]
+        };
+      }
+      try {
+        const fullPrompt = params.prompt ? `${params.prompt}
+
+User request:
+${text}` : text;
+        const response = await client.sendMessage(fullPrompt);
+        return {
+          messages: [new import_messages5.AIMessage(response)]
+        };
+      } catch (error) {
+        const msg = error.message ?? String(error);
+        return {
+          messages: [
+            new import_messages5.AIMessage(`Remote A2A agent error: ${msg}`)
+          ]
+        };
+      }
+    };
+    const workflow = new import_langgraph14.StateGraph(import_langgraph14.MessagesAnnotation).addNode("remote_call", remoteCallNode).addEdge("__start__", "remote_call").addEdge("remote_call", "__end__");
+    return workflow.compile();
+  }
+};
+function extractLastHumanMessage(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg._getType() === "human") {
+      const content = msg.content;
+      if (typeof content === "string") return content;
+      if (Array.isArray(content)) {
+        return content.filter(
+          (c) => typeof c === "object" && c !== null && c.type === "text"
+        ).map((c) => c.text).join("\n");
+      }
+      return String(content);
+    }
+  }
+  return "";
+}
+
 // src/agent_lattice/builders/AgentGraphBuilderFactory.ts
 var AgentGraphBuilderFactory = class _AgentGraphBuilderFactory {
   constructor() {
@@ -17992,6 +18616,7 @@ var AgentGraphBuilderFactory = class _AgentGraphBuilderFactory {
     this.builders.set(import_protocols.AgentType.DEEP_AGENT, new DeepAgentGraphBuilder());
     this.builders.set(import_protocols.AgentType.TEAM, new TeamAgentGraphBuilder());
     this.builders.set(import_protocols.AgentType.PROCESSING, new ProcessingAgentGraphBuilder());
+    this.builders.set(import_protocols.AgentType.A2A_REMOTE, new RemoteAgentGraphBuilder());
   }
   /**
    * 注册自定义Builder
@@ -18018,7 +18643,7 @@ var AgentGraphBuilderFactory = class _AgentGraphBuilderFactory {
 };
 
 // src/agent_lattice/builders/AgentParamsBuilder.ts
-var import_protocols9 = require("@axiom-lattice/protocols");
+var import_protocols10 = require("@axiom-lattice/protocols");
 var AgentParamsBuilder = class {
   /**
    * constructor
@@ -18036,8 +18661,8 @@ var AgentParamsBuilder = class {
    * @returns Agent build parameters
    */
   async buildParams(agentLattice, options) {
-    const skills = (0, import_protocols9.isDeepAgentConfig)(agentLattice.config) || (0, import_protocols9.isProcessingAgentConfig)(agentLattice.config) ? agentLattice.config.skillCategories : void 0;
-    const toolKeys = options?.overrideTools || (0, import_protocols9.getToolsFromConfig)(agentLattice.config);
+    const skills = (0, import_protocols10.isDeepAgentConfig)(agentLattice.config) || (0, import_protocols10.isProcessingAgentConfig)(agentLattice.config) ? agentLattice.config.skillCategories : void 0;
+    const toolKeys = options?.overrideTools || (0, import_protocols10.getToolsFromConfig)(agentLattice.config);
     const tools = toolKeys.map((toolKey) => {
       const toolLattice = toolLatticeManager.getToolLattice(toolKey);
       if (!toolLattice) {
@@ -18054,7 +18679,7 @@ var AgentParamsBuilder = class {
     if (!model) {
       throw new Error(`Model "${modelKey}" does not exist`);
     }
-    const subAgentKeys = (0, import_protocols9.getSubAgentsFromConfig)(agentLattice.config);
+    const subAgentKeys = (0, import_protocols10.getSubAgentsFromConfig)(agentLattice.config);
     const subAgents = await Promise.all(subAgentKeys.map(async (agentKey) => {
       const subAgentLattice = await this.getAgentLatticeFunc(agentKey);
       if (!subAgentLattice) {
@@ -18067,7 +18692,7 @@ var AgentParamsBuilder = class {
       };
     }));
     let internalSubAgents = [];
-    if ((0, import_protocols9.isDeepAgentConfig)(agentLattice.config) || (0, import_protocols9.isProcessingAgentConfig)(agentLattice.config)) {
+    if ((0, import_protocols10.isDeepAgentConfig)(agentLattice.config) || (0, import_protocols10.isProcessingAgentConfig)(agentLattice.config)) {
       internalSubAgents = agentLattice.config.internalSubAgents?.map((i) => ({
         key: i.key,
         config: i
@@ -18663,8 +19288,8 @@ ${body}` : `${frontmatter}
 
 // src/agent_lattice/agentArchitectTools.ts
 var import_zod53 = __toESM(require("zod"));
-var import_uuid4 = require("uuid");
-var import_protocols10 = require("@axiom-lattice/protocols");
+var import_uuid5 = require("uuid");
+var import_protocols11 = require("@axiom-lattice/protocols");
 function getTenantId(exeConfig) {
   const runConfig = exeConfig?.configurable?.runConfig || {};
   return runConfig.tenantId || "default";
@@ -18772,7 +19397,7 @@ registerToolLattice(
         key: id,
         name: input.name,
         description: input.description || "",
-        type: input.type === "deep_agent" ? import_protocols10.AgentType.DEEP_AGENT : import_protocols10.AgentType.REACT,
+        type: input.type === "deep_agent" ? import_protocols11.AgentType.DEEP_AGENT : import_protocols11.AgentType.REACT,
         prompt: input.prompt,
         ...input.tools && input.tools.length > 0 ? { tools: input.tools } : {},
         ...input.middleware && input.middleware.length > 0 ? { middleware: input.middleware } : {},
@@ -18861,7 +19486,7 @@ registerToolLattice(
         key: id,
         name: input.name,
         description: input.description || "",
-        type: import_protocols10.AgentType.PROCESSING,
+        type: import_protocols11.AgentType.PROCESSING,
         prompt: input.prompt,
         ...input.tools && input.tools.length > 0 ? { tools: input.tools } : {},
         middleware,
@@ -18929,7 +19554,7 @@ registerToolLattice(
         return JSON.stringify({ error: `Agent '${input.id}' not found` });
       }
       const existingConfig = existing.graphDefinition || {};
-      if (existingConfig.type !== import_protocols10.AgentType.PROCESSING) {
+      if (existingConfig.type !== import_protocols11.AgentType.PROCESSING) {
         return JSON.stringify({ error: `Agent '${input.id}' is not a PROCESSING agent (type: ${existingConfig.type})` });
       }
       const normalize = (s) => s.toLowerCase().replace(/[_\-\s]/g, "");
@@ -19137,7 +19762,7 @@ registerToolLattice(
       if (!existing) {
         return JSON.stringify({ error: `Agent '${id}' not found` });
       }
-      const threadId = (0, import_uuid4.v4)();
+      const threadId = (0, import_uuid5.v4)();
       const agent = new Agent({
         tenant_id: tenantId,
         assistant_id: id,
@@ -19161,7 +19786,7 @@ registerToolLattice(
 );
 
 // src/agent_lattice/agentArchitectConfig.ts
-var import_protocols12 = require("@axiom-lattice/protocols");
+var import_protocols13 = require("@axiom-lattice/protocols");
 
 // src/agent_lattice/agentArchitectPrompt.ts
 var AGENT_ARCHITECT_PROMPT = `# Agent Architect
@@ -19801,7 +20426,7 @@ Updates a PROCESSING agent's topology edges, name, prompt, or sub-agents. Unlike
 `;
 
 // src/agent_lattice/agentReviewerConfig.ts
-var import_protocols11 = require("@axiom-lattice/protocols");
+var import_protocols12 = require("@axiom-lattice/protocols");
 
 // src/agent_lattice/agentReviewerPrompt.ts
 var AGENT_REVIEWER_PROMPT = `# Agent Reviewer
@@ -19864,7 +20489,7 @@ var agentReviewerConfig = {
   key: AGENT_REVIEWER_KEY,
   name: "Agent Reviewer",
   description: "Review and test AI agents. Use this agent to check agent configurations for correctness and to test agents by invoking them with realistic messages.",
-  type: import_protocols11.AgentType.REACT,
+  type: import_protocols12.AgentType.REACT,
   prompt: AGENT_REVIEWER_PROMPT,
   tools: [
     "invoke_agent",
@@ -19890,7 +20515,7 @@ var agentArchitectConfig = {
   key: AGENT_ARCHITECT_KEY,
   name: "Agent Architect",
   description: "Design and manage AI agents through natural language conversation. Use this agent when you want to create a new agent, modify an existing agent, or manage your agent collection (list, view, update, delete).",
-  type: import_protocols12.AgentType.DEEP_AGENT,
+  type: import_protocols13.AgentType.DEEP_AGENT,
   prompt: AGENT_ARCHITECT_PROMPT,
   tools: [
     "list_agents",
@@ -20556,7 +21181,7 @@ var getVectorStoreLattice = (key) => vectorStoreLatticeManager.getVectorStoreLat
 var getVectorStoreClient = (key) => vectorStoreLatticeManager.getVectorStoreClient(key);
 
 // src/logger_lattice/LoggerLatticeManager.ts
-var import_protocols13 = require("@axiom-lattice/protocols");
+var import_protocols14 = require("@axiom-lattice/protocols");
 
 // src/logger_lattice/PinoLoggerClient.ts
 var import_pino = __toESM(require("pino"));
@@ -20778,11 +21403,11 @@ var LoggerLatticeManager = class _LoggerLatticeManager extends BaseLatticeManage
     if (client) {
       loggerClient = client;
     } else {
-      if (config.type === import_protocols13.LoggerType.PINO) {
+      if (config.type === import_protocols14.LoggerType.PINO) {
         loggerClient = new PinoLoggerClient(config);
-      } else if (config.type === import_protocols13.LoggerType.CONSOLE) {
+      } else if (config.type === import_protocols14.LoggerType.CONSOLE) {
         loggerClient = new ConsoleLoggerClient(config);
-      } else if (config.type === import_protocols13.LoggerType.CUSTOM) {
+      } else if (config.type === import_protocols14.LoggerType.CUSTOM) {
         throw new Error(
           `Custom logger client must be provided. Please pass the client to registerLattice.`
         );
@@ -22632,7 +23257,7 @@ function createSandboxProvider(config) {
 var Protocols = __toESM(require("@axiom-lattice/protocols"));
 
 // src/util/encryption.ts
-var import_crypto2 = require("crypto");
+var import_crypto3 = require("crypto");
 var ALGORITHM = "aes-256-gcm";
 var IV_LENGTH = 16;
 var SALT_LENGTH = 32;
@@ -22645,7 +23270,7 @@ function getEncryptionKey() {
     return cachedKey;
   }
   const key = process.env.LATTICE_ENCRYPTION_KEY || DEFAULT_ENCRYPTION_KEY;
-  cachedKey = (0, import_crypto2.pbkdf2Sync)(key, "lattice-encryption-salt", ITERATIONS, 32, "sha256");
+  cachedKey = (0, import_crypto3.pbkdf2Sync)(key, "lattice-encryption-salt", ITERATIONS, 32, "sha256");
   if (!keyValidated) {
     keyValidated = true;
     validateEncryptionKey();
@@ -22654,10 +23279,10 @@ function getEncryptionKey() {
 }
 function encrypt(plaintext, key) {
   const actualKey = key || getEncryptionKey();
-  const salt = (0, import_crypto2.randomBytes)(SALT_LENGTH);
-  const iv = (0, import_crypto2.randomBytes)(IV_LENGTH);
-  const derivedKey = (0, import_crypto2.pbkdf2Sync)(actualKey, salt, ITERATIONS, 32, "sha256");
-  const cipher = (0, import_crypto2.createCipheriv)(ALGORITHM, derivedKey, iv);
+  const salt = (0, import_crypto3.randomBytes)(SALT_LENGTH);
+  const iv = (0, import_crypto3.randomBytes)(IV_LENGTH);
+  const derivedKey = (0, import_crypto3.pbkdf2Sync)(actualKey, salt, ITERATIONS, 32, "sha256");
+  const cipher = (0, import_crypto3.createCipheriv)(ALGORITHM, derivedKey, iv);
   const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
   const authTag = cipher.getAuthTag();
   return Buffer.concat([salt, iv, encrypted, authTag]).toString("base64");
@@ -22669,8 +23294,8 @@ function decrypt(encrypted, key) {
   const iv = data.subarray(SALT_LENGTH, SALT_LENGTH + IV_LENGTH);
   const authTag = data.subarray(-16);
   const ciphertext = data.subarray(SALT_LENGTH + IV_LENGTH, -16);
-  const derivedKey = (0, import_crypto2.pbkdf2Sync)(actualKey, salt, ITERATIONS, 32, "sha256");
-  const decipher = (0, import_crypto2.createDecipheriv)(ALGORITHM, derivedKey, iv);
+  const derivedKey = (0, import_crypto3.pbkdf2Sync)(actualKey, salt, ITERATIONS, 32, "sha256");
+  const decipher = (0, import_crypto3.createDecipheriv)(ALGORITHM, derivedKey, iv);
   decipher.setAuthTag(authTag);
   return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
 }
@@ -22708,6 +23333,7 @@ function clearEncryptionKeyCache() {
   CompositeBackend,
   ConsoleLoggerClient,
   CustomMetricsClient,
+  CustomMiddlewareRegistry,
   DaytonaInstance,
   DaytonaProvider,
   DefaultScheduleClient,
@@ -22718,6 +23344,7 @@ function clearEncryptionKeyCache() {
   FileSystemSkillStore,
   FilesystemBackend,
   HumanMessage,
+  InMemoryA2AApiKeyStore,
   InMemoryAssistantStore,
   InMemoryBindingStore,
   InMemoryChannelInstallationStore,