libp2p-mesh 2026.6.3 → 2026.6.4

package/dist/src/inbound.js

@@ -1,6 +1,6 @@
 import { verifyInstanceSignature } from "./instance-id.js";
 export function handleP2PInbound(msg, deps) {
-    const { logger } = deps;
+    const { logger, sendToChannel } = deps;
     const instanceTag = msg.instanceId ? ` [instance: ${msg.instanceId}]` : "";
     const signedTag = msg.signature ? " [signed]" : "";
     // Verify signature if present
@@ -28,8 +28,15 @@ export function handleP2PInbound(msg, deps) {
     }
     if (msg.type === "broadcast") {
         logger?.info?.(`[libp2p-mesh] Broadcast from ${msg.from}${instanceTag}${signedTag} on topic ${msg.topic ?? "(none)"}: ${msg.payload}`);
+        return;
     }
-    else {
-        logger?.info?.(`[libp2p-mesh] Direct message from ${msg.from}${instanceTag}${signedTag}: ${msg.payload}`);
+    // Direct message — log and forward to local channel
+    logger?.info?.(`[libp2p-mesh] Direct message from ${msg.from}${instanceTag}${signedTag}: ${msg.payload}`);
+    if (!sendToChannel || !msg.payload) {
+        return;
     }
+    const text = `[来自 ${msg.from}]\n${msg.payload}`;
+    sendToChannel("libp2p-mesh", msg.from, text).catch((err) => {
+        logger?.error?.(`[libp2p-mesh] Failed to forward direct message from ${msg.from}: ${err}`);
+    });
 }

package/dist/src/instance-router.js

@@ -13,6 +13,67 @@ function isNonEmptyString(value) {
 function summarizeError(error) {
     return error instanceof Error ? error.message : String(error);
 }
+const INVALID_INBOUND_TARGET_ERROR = "inbound target channel and target are required";
+function invalidInboundTarget() {
+    return {
+        channel: "",
+        target: "",
+        valid: false,
+        error: INVALID_INBOUND_TARGET_ERROR,
+    };
+}
+function displayTargetId(target) {
+    return typeof target.id === "string" ? target.id.trim() || undefined : undefined;
+}
+function normalizeConfiguredTarget(target) {
+    if (!target || typeof target !== "object" || Array.isArray(target)) {
+        return invalidInboundTarget();
+    }
+    const configuredTarget = target;
+    const channel = typeof configuredTarget.channel === "string" ? configuredTarget.channel.trim() : "";
+    const destination = typeof configuredTarget.target === "string" ? configuredTarget.target.trim() : "";
+    const normalized = {
+        id: displayTargetId(configuredTarget),
+        channel,
+        target: destination,
+        valid: Boolean(channel && destination),
+    };
+    if (!normalized.valid) {
+        normalized.error = INVALID_INBOUND_TARGET_ERROR;
+    }
+    return normalized;
+}
+function effectiveInboundTargets(config) {
+    if (Array.isArray(config.inboundTargets)) {
+        const seen = new Set();
+        const targets = [];
+        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) {
+    return results.find((result) => result.ok) ?? results[0];
+}
 export function createInstanceRouter(options) {
     const { mesh, store, delivery } = options;
     const config = options.config ?? {};
@@ -21,7 +82,10 @@ export function createInstanceRouter(options) {
     const announcedPeers = new Set();
     const pendingAcks = new Map();
     const deliveryCache = new Map();
+    const inboundTimeoutControllers = new Set();
+    const activeAckSends = new Set();
     const unsubs = [];
+    let stopped = false;
     function localInstanceId() {
         const identity = mesh.getInstanceIdentity();
         if (!identity) {
@@ -95,14 +159,191 @@ export function createInstanceRouter(options) {
         }
     }
     async function sendAck(peerId, ack) {
-        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, msg) {
+        return [
+            payload.fromInstanceId,
+            msg.from,
+            payload.toInstanceId,
+            payload.messageId,
+        ].join("\0");
+    }
+    function buildAckFromDeliveryState(messageId, state) {
+        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, msg, state) {
+        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, state) {
+        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, messageId, state) {
+        return new Promise((resolve) => {
+            let settled = false;
+            const settle = (ack) => {
+                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 = {
+                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) {
+        if (stopped) {
+            return;
+        }
         const payload = parsePayload(msg);
         if (!payload ||
             !isNonEmptyString(payload.messageId) ||
@@ -117,6 +358,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`);
             return;
@@ -126,56 +370,78 @@ export function createInstanceRouter(options) {
             logger?.warn?.(`[libp2p-mesh] Ignoring user-message for ${payload.toInstanceId}; local instance is ${localId}`);
             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;
-        if (!config.inboundChannel || !config.inboundTarget) {
-            ack = {
+        if (pendingDeliveryCount() >= MAX_DELIVERY_CACHE_ENTRIES) {
+            const ack = {
                 ackFor: payload.messageId,
                 ok: false,
-                inboundChannel: config.inboundChannel,
-                inboundTarget: config.inboundTarget,
                 deliveredAt: Date.now(),
-                error: "inbound delivery is not configured",
+                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;
         }
-        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,
-            };
+        const deliveryState = {
+            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 = { inFlight: true, promise: ackPromise };
+        deliveryCache.set(cacheKey, cacheEntry);
+        trimDeliveryCache();
+        const ack = await ackPromise;
+        if (stopped) {
+            return;
         }
-        deliveryCache.set(payload.messageId, { peerId: msg.from, payload: ack });
+        cacheEntry.payload = ack;
         trimDeliveryCache();
+        if (stopped) {
+            return;
+        }
         await sendAck(msg.from, ack);
     }
-    function trimDeliveryCache() {
+    function pendingDeliveryCount() {
+        let count = 0;
+        for (const entry of deliveryCache.values()) {
+            if (entry.inFlight)
+                count += 1;
+        }
+        return count;
+    }
+    function trimDeliveryCache(protectedKey) {
         while (deliveryCache.size > MAX_DELIVERY_CACHE_ENTRIES) {
-            const oldestKey = deliveryCache.keys().next().value;
-            if (!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(oldestKey);
+            deliveryCache.delete(settledKeys[0]);
         }
     }
     function handleAck(msg) {
@@ -211,6 +477,7 @@ export function createInstanceRouter(options) {
         }
     }
     async function start() {
+        stopped = false;
         unsubs.push(mesh.onMessage((msg) => {
             handleMessage(msg).catch((error) => {
                 logger?.error?.(`[libp2p-mesh] Instance router message error: ${summarizeError(error)}`);
@@ -224,9 +491,14 @@ export function createInstanceRouter(options) {
         await announceToConnectedPeers();
     }
     async function stop() {
+        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({
@@ -238,6 +510,8 @@ export function createInstanceRouter(options) {
         }
         pendingAcks.clear();
         deliveryCache.clear();
+        await Promise.allSettled([...activeAckSends]);
+        activeAckSends.clear();
     }
     async function listInstances() {
         return store.list();
@@ -311,6 +585,8 @@ export function createInstanceRouter(options) {
             toPeerId: route.peerId,
             ackMessageId: ack.ackFor,
             inboundChannel: ack.inboundChannel,
+            inboundTarget: ack.inboundTarget,
+            deliveryResults: ack.results,
             error: ack.error,
         };
     }

package/dist/src/plugin.js

@@ -26,6 +26,7 @@ export function registerLibp2pMesh(api) {
         config,
         logger: api.logger,
     });
+    const channel = createLibp2pMeshChannel(mesh);
     // 1. Register Service (manages libp2p node lifecycle)
     api.registerService({
         id: "libp2p-mesh",
@@ -37,7 +38,32 @@ export function registerLibp2pMesh(api) {
             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 = 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 });
                 }
             });
@@ -69,7 +95,7 @@ export function registerLibp2pMesh(api) {
     });
     // 2. Register Channel (lightweight debugging surface)
     api.registerChannel({
-        plugin: createLibp2pMeshChannel(mesh),
+        plugin: channel,
     });
     // 3. Register Agent Tools
     const tools = buildP2PTools(mesh, router);

package/dist/src/types.d.ts

@@ -51,6 +51,18 @@ export interface UserMessagePayload {
         replyTool: "p2p_send_instance_message";
     };
 }
+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;
@@ -58,6 +70,7 @@ export interface DeliveryAckPayload {
     inboundTarget?: string;
     deliveredAt: number;
     error?: string;
+    results?: DeliveryTargetResult[];
 }
 export interface InstancePeerRecord {
     instanceId: string;
@@ -120,6 +133,8 @@ export interface InstanceRouter {
         toPeerId: string;
         ackMessageId?: string;
         inboundChannel?: string;
+        inboundTarget?: string;
+        deliveryResults?: DeliveryTargetResult[];
         error?: string;
     }>;
 }
@@ -165,7 +180,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;
@@ -182,6 +198,7 @@ export interface MeshConfig {
     announceAddrs?: string[];
     inboundChannel?: string;
     inboundTarget?: string;
+    inboundTargets?: InboundTargetConfig[];
     deliveryAckTimeoutMs?: number;
 }
 export interface NATTraversalStatus {

package/dist/src/wizard.d.ts

@@ -0,0 +1,22 @@
+export interface PromptChoice {
+    label: string;
+    value: string;
+    hint?: string;
+}
+export interface WizardPrompter {
+    question(prompt: string, defaultValue?: string): Promise<string>;
+    confirm(prompt: string, defaultValue?: boolean): Promise<boolean>;
+    select(prompt: string, choices: PromptChoice[]): Promise<string>;
+    multiline(prompt: string, helpText?: string): Promise<string[]>;
+    displayBox(title: string, lines: string[]): void;
+    displaySuccess(message: string): void;
+    displayError(message: string): void;
+    displayWarning(message: string): void;
+    close(): void;
+}
+export declare function validateMultiaddr(raw: string): string | null;
+export declare function createReadlinePrompter(): WizardPrompter;
+export declare function runSetupWizard(prompter: WizardPrompter, currentConfig: Record<string, unknown>, availableChannels: string[]): Promise<Record<string, unknown>>;
+export declare class WizardCancelledError extends Error {
+    constructor();
+}