libp2p-mesh 2026.6.2 → 2026.6.4

package/src/instance-router.ts

@@ -1,6 +1,8 @@
 import type {
   DeliveryAckPayload,
+  DeliveryTargetResult,
   InboundDeliveryAdapter,
+  InboundTargetConfig,
   InstanceAnnouncePayload,
   InstancePeerStore,
   InstanceRouter,
@@ -24,8 +26,19 @@ type PendingAck = {
 };
 
 type DeliveryCacheEntry = {
-  peerId: string;
-  payload: DeliveryAckPayload;
+  inFlight?: boolean;
+  payload?: DeliveryAckPayload;
+  promise?: Promise<DeliveryAckPayload>;
+};
+
+type InboundDeliveryState = {
+  timedOut: boolean;
+  currentTarget?: EffectiveInboundTarget;
+  results: DeliveryTargetResult[];
+};
+
+type InboundTimeoutController = {
+  stop: () => void;
 };
 
 const MAX_DELIVERY_CACHE_ENTRIES = 1000;
@@ -46,6 +59,85 @@ function summarizeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+type EffectiveInboundTarget = {
+  id?: string;
+  channel: string;
+  target: string;
+  valid: boolean;
+  error?: string;
+};
+
+const INVALID_INBOUND_TARGET_ERROR = "inbound target channel and target are required";
+
+function invalidInboundTarget(): EffectiveInboundTarget {
+  return {
+    channel: "",
+    target: "",
+    valid: false,
+    error: INVALID_INBOUND_TARGET_ERROR,
+  };
+}
+
+function displayTargetId(target: { id?: unknown }): string | undefined {
+  return typeof target.id === "string" ? target.id.trim() || undefined : undefined;
+}
+
+function normalizeConfiguredTarget(target: unknown): EffectiveInboundTarget {
+  if (!target || typeof target !== "object" || Array.isArray(target)) {
+    return invalidInboundTarget();
+  }
+
+  const configuredTarget = target as Partial<InboundTargetConfig>;
+  const channel =
+    typeof configuredTarget.channel === "string" ? configuredTarget.channel.trim() : "";
+  const destination =
+    typeof configuredTarget.target === "string" ? configuredTarget.target.trim() : "";
+  const normalized: EffectiveInboundTarget = {
+    id: displayTargetId(configuredTarget),
+    channel,
+    target: destination,
+    valid: Boolean(channel && destination),
+  };
+  if (!normalized.valid) {
+    normalized.error = INVALID_INBOUND_TARGET_ERROR;
+  }
+  return normalized;
+}
+
+function effectiveInboundTargets(config: MeshConfig): EffectiveInboundTarget[] {
+  if (Array.isArray(config.inboundTargets)) {
+    const seen = new Set<string>();
+    const targets: EffectiveInboundTarget[] = [];
+    for (const target of config.inboundTargets) {
+      const normalized = normalizeConfiguredTarget(target);
+      const key = `${normalized.channel}\0${normalized.target}`;
+      if (normalized.valid && seen.has(key)) {
+        continue;
+      }
+      if (normalized.valid) {
+        seen.add(key);
+      }
+      targets.push(normalized);
+    }
+    return targets;
+  }
+
+  if (!config.inboundChannel || !config.inboundTarget) {
+    return [];
+  }
+  return [
+    {
+      channel: config.inboundChannel,
+      target: config.inboundTarget,
+      valid: true,
+    },
+  ];
+}
+
+function firstAttemptedResult(results: DeliveryTargetResult[]): DeliveryTargetResult | undefined {
+  return results.find((result) => result.ok) ?? results[0];
+}
+
 export function createInstanceRouter(options: {
   mesh: MeshNetwork;
   store: InstancePeerStore;
@@ -60,7 +152,10 @@ export function createInstanceRouter(options: {
   const announcedPeers = new Set<string>();
   const pendingAcks = new Map<string, PendingAck>();
   const deliveryCache = new Map<string, DeliveryCacheEntry>();
+  const inboundTimeoutControllers = new Set<InboundTimeoutController>();
+  const activeAckSends = new Set<Promise<void>>();
   const unsubs: Array<() => void> = [];
+  let stopped = false;
 
   function localInstanceId(): string {
     const identity = mesh.getInstanceIdentity();
@@ -156,15 +251,213 @@ export function createInstanceRouter(options: {
   }
 
   async function sendAck(peerId: string, ack: DeliveryAckPayload): Promise<void> {
-    await mesh.sendStructuredMessage(peerId, {
+    if (stopped) {
+      return;
+    }
+
+    const send = mesh.sendStructuredMessage(peerId, {
       id: crypto.randomUUID(),
       type: "delivery-ack",
       to: peerId,
       payload: JSON.stringify(ack),
     });
+    activeAckSends.add(send);
+    try {
+      await send;
+    } finally {
+      activeAckSends.delete(send);
+    }
+  }
+
+  function deliveryCacheKey(payload: UserMessagePayload, msg: P2PMessage): string {
+    return [
+      payload.fromInstanceId,
+      msg.from,
+      payload.toInstanceId,
+      payload.messageId,
+    ].join("\0");
+  }
+
+  function buildAckFromDeliveryState(
+    messageId: string,
+    state: Pick<InboundDeliveryState, "results">,
+  ): DeliveryAckPayload {
+    const selected = firstAttemptedResult(state.results);
+    return {
+      ackFor: messageId,
+      ok: state.results.some((result) => result.ok),
+      inboundChannel: selected?.channel,
+      inboundTarget: selected?.target,
+      deliveredAt: Date.now(),
+      error: state.results.every((result) => !result.ok)
+        ? state.results.map((result) => result.error).filter(Boolean).join("; ") ||
+          "inbound delivery failed"
+        : undefined,
+      results: state.results,
+    };
+  }
+
+  async function deliverAndBuildAck(
+    payload: UserMessagePayload,
+    msg: P2PMessage,
+    state: InboundDeliveryState,
+  ): Promise<DeliveryAckPayload> {
+    const targets = effectiveInboundTargets(config);
+    if (targets.length === 0) {
+      return {
+        ackFor: payload.messageId,
+        ok: false,
+        deliveredAt: Date.now(),
+        error: "inbound delivery is not configured",
+        results: [],
+      };
+    }
+
+    const metadata = payload.metadata;
+    for (const target of targets) {
+      if (state.timedOut) {
+        break;
+      }
+
+      if (!target.valid) {
+        state.results.push({
+          id: target.id,
+          channel: target.channel,
+          target: target.target,
+          ok: false,
+          error: target.error ?? "inbound target channel and target are required",
+        });
+        continue;
+      }
+
+      state.currentTarget = target;
+      try {
+        const result = await delivery.deliver({
+          channel: target.channel,
+          target: target.target,
+          text: payload.text,
+          metadata: {
+            fromInstanceId: payload.fromInstanceId,
+            fromPeerId: msg.from,
+            p2pMessageId: payload.messageId,
+            allowAgentAutoReply: metadata?.allowAgentAutoReply === true,
+            replyToInstanceId: payload.fromInstanceId,
+            replyTool: "p2p_send_instance_message",
+          },
+        });
+        if (state.timedOut) {
+          break;
+        }
+        state.results.push({
+          id: target.id,
+          channel: result.channel,
+          target: result.target,
+          ok: result.ok,
+          error: result.error,
+        });
+      } catch (error) {
+        if (state.timedOut) {
+          break;
+        }
+        state.results.push({
+          id: target.id,
+          channel: target.channel,
+          target: target.target,
+          ok: false,
+          error: summarizeError(error),
+        });
+      } finally {
+        if (state.currentTarget === target) {
+          state.currentTarget = undefined;
+        }
+      }
+    }
+
+    return buildAckFromDeliveryState(payload.messageId, state);
+  }
+
+  function buildInboundTimeoutAck(
+    messageId: string,
+    state: InboundDeliveryState,
+  ): DeliveryAckPayload {
+    const error = `inbound delivery timeout after ${ackTimeoutMs}ms`;
+    const results = state.results.slice();
+    const currentTarget = state.currentTarget;
+    if (currentTarget) {
+      results.push({
+        id: currentTarget.id,
+        channel: currentTarget.channel,
+        target: currentTarget.target,
+        ok: false,
+        error: currentTarget.valid
+          ? error
+          : currentTarget.error ?? "inbound target channel and target are required",
+      });
+    }
+    const selected = firstAttemptedResult(results);
+    return {
+      ackFor: messageId,
+      ok: results.some((result) => result.ok),
+      inboundChannel: selected?.channel,
+      inboundTarget: selected?.target,
+      deliveredAt: Date.now(),
+      error,
+      results,
+    };
+  }
+
+  function withInboundDeliveryTimeout(
+    promise: Promise<DeliveryAckPayload>,
+    messageId: string,
+    state: InboundDeliveryState,
+  ): Promise<DeliveryAckPayload> {
+    return new Promise((resolve) => {
+      let settled = false;
+      const settle = (ack: DeliveryAckPayload): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        inboundTimeoutControllers.delete(controller);
+        resolve(ack);
+      };
+      const timer = setTimeout(() => {
+        state.timedOut = true;
+        settle(buildInboundTimeoutAck(messageId, state));
+      }, ackTimeoutMs);
+      const controller: InboundTimeoutController = {
+        stop() {
+          state.timedOut = true;
+          settle({
+            ackFor: messageId,
+            ok: false,
+            deliveredAt: Date.now(),
+            error: "instance router stopped",
+            results: state.results,
+          });
+        },
+      };
+      inboundTimeoutControllers.add(controller);
+
+      promise
+        .then((ack) => {
+          settle(ack);
+        })
+        .catch((error) => {
+          settle({
+            ackFor: messageId,
+            ok: false,
+            deliveredAt: Date.now(),
+            error: summarizeError(error),
+            results: [],
+          });
+        });
+    });
   }
 
   async function handleUserMessage(msg: P2PMessage): Promise<void> {
+    if (stopped) {
+      return;
+    }
     const payload = parsePayload<UserMessagePayload>(msg);
     if (
       !payload ||
@@ -183,6 +476,9 @@ export function createInstanceRouter(options: {
       return;
     }
     const senderRoute = await store.resolve(payload.fromInstanceId);
+    if (stopped) {
+      return;
+    }
     if (!senderRoute || senderRoute.peerId !== msg.from) {
       logger?.warn?.(
         `[libp2p-mesh] Ignoring user-message from ${msg.from}; instance ${payload.fromInstanceId} is not routed to that peer`,
@@ -198,57 +494,80 @@ export function createInstanceRouter(options: {
       return;
     }
 
-    const cached = deliveryCache.get(payload.messageId);
+    const cacheKey = deliveryCacheKey(payload, msg);
+    const cached = deliveryCache.get(cacheKey);
     if (cached) {
-      await sendAck(cached.peerId, cached.payload);
+      const ack = cached.payload ?? (await cached.promise);
+      if (!ack) {
+        throw new Error(`delivery cache entry for ${payload.messageId} has no ACK payload`);
+      }
+      if (stopped) {
+        return;
+      }
+      await sendAck(msg.from, ack);
       return;
     }
 
-    let ack: DeliveryAckPayload;
-    if (!config.inboundChannel || !config.inboundTarget) {
-      ack = {
+    if (pendingDeliveryCount() >= MAX_DELIVERY_CACHE_ENTRIES) {
+      const ack: DeliveryAckPayload = {
         ackFor: payload.messageId,
         ok: false,
-        inboundChannel: config.inboundChannel,
-        inboundTarget: config.inboundTarget,
-        deliveredAt: Date.now(),
-        error: "inbound delivery is not configured",
-      };
-    } else {
-      const metadata = payload.metadata;
-      const result = await delivery.deliver({
-        channel: config.inboundChannel,
-        target: config.inboundTarget,
-        text: payload.text,
-        metadata: {
-          fromInstanceId: payload.fromInstanceId,
-          fromPeerId: msg.from,
-          p2pMessageId: payload.messageId,
-          allowAgentAutoReply: metadata?.allowAgentAutoReply === true,
-          replyToInstanceId: payload.fromInstanceId,
-          replyTool: "p2p_send_instance_message",
-        },
-      });
-      ack = {
-        ackFor: payload.messageId,
-        ok: result.ok,
-        inboundChannel: result.channel,
-        inboundTarget: result.target,
         deliveredAt: Date.now(),
-        error: result.error,
+        error: `too many pending inbound deliveries (${MAX_DELIVERY_CACHE_ENTRIES})`,
+        results: [],
       };
+      deliveryCache.set(cacheKey, { payload: ack });
+      trimDeliveryCache(cacheKey);
+      if (stopped) {
+        return;
+      }
+      await sendAck(msg.from, ack);
+      return;
     }
 
-    deliveryCache.set(payload.messageId, { peerId: msg.from, payload: ack });
+    const deliveryState: InboundDeliveryState = {
+      timedOut: false,
+      results: [],
+    };
+    const deliveryPromise = Promise.resolve()
+      .then(() => deliverAndBuildAck(payload, msg, deliveryState))
+      .finally(() => {
+        const entry = deliveryCache.get(cacheKey);
+        if (entry) {
+          entry.inFlight = false;
+        }
+      });
+    const ackPromise = withInboundDeliveryTimeout(deliveryPromise, payload.messageId, deliveryState);
+    const cacheEntry: DeliveryCacheEntry = { inFlight: true, promise: ackPromise };
+    deliveryCache.set(cacheKey, cacheEntry);
     trimDeliveryCache();
+    const ack = await ackPromise;
+    if (stopped) {
+      return;
+    }
+    cacheEntry.payload = ack;
+    trimDeliveryCache();
+    if (stopped) {
+      return;
+    }
     await sendAck(msg.from, ack);
   }
 
-  function trimDeliveryCache(): void {
+  function pendingDeliveryCount(): number {
+    let count = 0;
+    for (const entry of deliveryCache.values()) {
+      if (entry.inFlight) count += 1;
+    }
+    return count;
+  }
+
+  function trimDeliveryCache(protectedKey?: string): void {
     while (deliveryCache.size > MAX_DELIVERY_CACHE_ENTRIES) {
-      const oldestKey = deliveryCache.keys().next().value as string | undefined;
-      if (!oldestKey) return;
-      deliveryCache.delete(oldestKey);
+      const settledKeys = Array.from(deliveryCache)
+        .filter(([key, entry]) => key !== protectedKey && entry.payload && !entry.inFlight)
+        .map(([key]) => key);
+      if (settledKeys.length === 0) return;
+      deliveryCache.delete(settledKeys[0]!);
     }
   }
 
@@ -293,6 +612,7 @@ export function createInstanceRouter(options: {
   }
 
   async function start(): Promise<void> {
+    stopped = false;
     unsubs.push(
       mesh.onMessage((msg) => {
         handleMessage(msg).catch((error) => {
@@ -316,10 +636,16 @@ export function createInstanceRouter(options: {
   }
 
   async function stop(): Promise<void> {
+    stopped = true;
     for (const unsub of unsubs.splice(0)) {
       unsub();
     }
 
+    for (const controller of Array.from(inboundTimeoutControllers)) {
+      controller.stop();
+    }
+    inboundTimeoutControllers.clear();
+
     for (const [messageId, pending] of pendingAcks) {
       clearTimeout(pending.timer);
       pending.resolve({
@@ -331,6 +657,9 @@ export function createInstanceRouter(options: {
     }
     pendingAcks.clear();
     deliveryCache.clear();
+
+    await Promise.allSettled([...activeAckSends]);
+    activeAckSends.clear();
   }
 
   async function listInstances() {
@@ -410,6 +739,8 @@ export function createInstanceRouter(options: {
       toPeerId: route.peerId,
       ackMessageId: ack.ackFor,
       inboundChannel: ack.inboundChannel,
+      inboundTarget: ack.inboundTarget,
+      deliveryResults: ack.results,
       error: ack.error,
     };
   }

package/src/plugin.ts

@@ -1,7 +1,7 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
 import { createLibp2pMeshChannel } from "./channel.js";
-import { handleP2PInbound } from "./inbound.js";
-import { createOpenClawCliInboundDelivery } from "./inbound-delivery.js";
+import { handleP2PInbound, type InboundHandlerDeps } from "./inbound.js";
+import { createOpenClawRuntimeInboundDelivery } from "./inbound-delivery.js";
 import { createInstancePeerStore } from "./instance-peer-store.js";
 import { createInstanceRouter } from "./instance-router.js";
 import { createMeshNetwork } from "./mesh.js";
@@ -18,7 +18,11 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
     logger: api.logger,
   });
   const store = createInstancePeerStore({ logger: api.logger });
-  const delivery = createOpenClawCliInboundDelivery({ logger: api.logger });
+  const delivery = createOpenClawRuntimeInboundDelivery({
+    config: api.config,
+    loadAdapter: api.runtime.channel.outbound.loadAdapter,
+    logger: api.logger,
+  });
   const router = createInstanceRouter({
     mesh,
     store,
@@ -27,6 +31,8 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
     logger: api.logger,
   });
 
+  const channel = createLibp2pMeshChannel(mesh);
+
   // 1. Register Service (manages libp2p node lifecycle)
   api.registerService({
     id: "libp2p-mesh",
@@ -38,7 +44,36 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
       await mesh.start();
       await router.start();
       unsubscribeInbound = mesh.onMessage((msg) => {
-        if (msg.type === "direct" || msg.type === "broadcast" || msg.type === "agent-sync") {
+        if (msg.type === "direct" || msg.type === "broadcast") {
+          const sendToChannel: InboundHandlerDeps["sendToChannel"] = async (_channelId, _target, text) => {
+            if (!config?.inboundChannel || !config?.inboundTarget) {
+              api.logger.warn?.(
+                "[libp2p-mesh] inboundChannel/inboundTarget not configured; direct message logged only.",
+              );
+              return;
+            }
+
+            const result = await delivery.deliver({
+              channel: config.inboundChannel,
+              target: config.inboundTarget,
+              text,
+              metadata: {
+                fromInstanceId: msg.instanceId ?? msg.from,
+                fromPeerId: msg.from,
+                p2pMessageId: msg.id,
+                allowAgentAutoReply: false,
+                replyToInstanceId: msg.instanceId ?? msg.from,
+                replyTool: "p2p_send_instance_message",
+              },
+            });
+            if (!result.ok) {
+              api.logger.error?.(
+                `[libp2p-mesh] Failed to forward direct message from ${msg.from}: ${result.error}`,
+              );
+            }
+          };
+          handleP2PInbound(msg, { logger: api.logger, sendToChannel });
+        } else if (msg.type === "agent-sync") {
           handleP2PInbound(msg, { logger: api.logger });
         }
       });
@@ -75,7 +110,7 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
 
   // 2. Register Channel (lightweight debugging surface)
   api.registerChannel({
-    plugin: createLibp2pMeshChannel(mesh) as ChannelPlugin,
+    plugin: channel as ChannelPlugin,
   });
 
   // 3. Register Agent Tools

package/src/types.ts

@@ -62,6 +62,20 @@ export interface UserMessagePayload {
   };
 }
 
+export interface InboundTargetConfig {
+  id?: string;
+  channel: string;
+  target: string;
+}
+
+export interface DeliveryTargetResult {
+  id?: string;
+  channel: string;
+  target: string;
+  ok: boolean;
+  error?: string;
+}
+
 export interface DeliveryAckPayload {
   ackFor: string;
   ok: boolean;
@@ -69,6 +83,7 @@ export interface DeliveryAckPayload {
   inboundTarget?: string;
   deliveredAt: number;
   error?: string;
+  results?: DeliveryTargetResult[];
 }
 
 export interface InstancePeerRecord {
@@ -138,6 +153,8 @@ export interface InstanceRouter {
     toPeerId: string;
     ackMessageId?: string;
     inboundChannel?: string;
+    inboundTarget?: string;
+    deliveryResults?: DeliveryTargetResult[];
     error?: string;
   }>;
 }
@@ -190,7 +207,8 @@ export interface MeshConfig {
   /**
    * Deprecated pre-2026.6 config keys kept so existing OpenClaw configs keep
    * validating after upgrade. Relay selection is now configured with
-   * `relayList`; inbound display uses `inboundChannel`/`inboundTarget`.
+   * `relayList`; inbound display uses `inboundChannel`/`inboundTarget`, or
+   * `inboundTargets` when multi-target inbound delivery is enabled.
    */
   relayChannel?: string;
   relayAccountId?: string;
@@ -207,6 +225,7 @@ export interface MeshConfig {
   announceAddrs?: string[];
   inboundChannel?: string;
   inboundTarget?: string;
+  inboundTargets?: InboundTargetConfig[];
   deliveryAckTimeoutMs?: number;
 }