@masons/agent-network 0.3.6 → 0.3.8

package/dist/channel.d.ts

@@ -32,22 +32,9 @@ interface ChannelGatewayContext<T = unknown> {
     cfg: Record<string, unknown>;
     accountId: string;
     account: T;
-    runtime: GatewayRuntime;
+    runtime: unknown;
     abortSignal: AbortSignal;
 }
-interface GatewayRuntime {
-    routeMessage(envelope: MessageEnvelope): void;
-}
-interface MessageEnvelope {
-    channelId: string;
-    messageId: string;
-    senderId: string;
-    senderName: string;
-    text: string;
-    timestamp: number;
-    isGroupMessage: boolean;
-    metadata?: Record<string, unknown>;
-}
 interface ChannelGatewayAdapter<T = unknown> {
     startAccount?(ctx: ChannelGatewayContext<T>): Promise<unknown>;
     stopAccount?(ctx: ChannelGatewayContext<T>): Promise<void>;

package/dist/channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAa9D,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,UAAU,oBAAoB,CAAC,CAAC;IAC9B,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAAC;IACvD,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC;IACpE,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;IACjE,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;CAC/D;AAED,UAAU,sBAAsB;IAC9B,EAAE,EAAE,OAAO,CAAC;CACb;AAED,UAAU,sBAAsB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,sBAAsB;IAC9B,YAAY,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC9C,QAAQ,CAAC,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACzE;AAED,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,cAAc,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,UAAU,cAAc;IACtB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;CAC/C;AAED,UAAU,eAAe;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,YAAY,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,WAAW,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,UAAU,yBAAyB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,YAAY,EAAE,mBAAmB,CAAC;IAClC,MAAM,EAAE,oBAAoB,CAAC,mBAAmB,CAAC,CAAC;IAClD,QAAQ,EAAE,sBAAsB,CAAC;IACjC,OAAO,EAAE,qBAAqB,CAAC,mBAAmB,CAAC,CAAC;CACrD;AAwDD,eAAO,MAAM,mBAAmB,EAAE,yBA4NjC,CAAC"}
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAa9D,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,UAAU,oBAAoB,CAAC,CAAC;IAC9B,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAAC;IACvD,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC;IACpE,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;IACjE,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;CAC/D;AAED,UAAU,sBAAsB;IAC9B,EAAE,EAAE,OAAO,CAAC;CACb;AAED,UAAU,sBAAsB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,sBAAsB;IAC9B,YAAY,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC9C,QAAQ,CAAC,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACzE;AAED,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAsDD,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,YAAY,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,WAAW,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,UAAU,yBAAyB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,YAAY,EAAE,mBAAmB,CAAC;IAClC,MAAM,EAAE,oBAAoB,CAAC,mBAAmB,CAAC,CAAC;IAClD,QAAQ,EAAE,sBAAsB,CAAC;IACjC,OAAO,EAAE,qBAAqB,CAAC,mBAAmB,CAAC,CAAC;CACrD;AAiED,eAAO,MAAM,mBAAmB,EAAE,yBAqWjC,CAAC"}

package/dist/channel.js

@@ -1,24 +1,31 @@
 import { randomUUID } from "node:crypto";
 import createDebug from "debug";
-import { clearConnectorClient, extractNetworkConfig, initConnectorClient, initToolConfig, } from "./config.js";
+import { clearConnectorClient, extractNetworkConfig, initConnectorClient, initToolConfig, requirePluginRuntime, } from "./config.js";
 import { ConnectorClient } from "./connector-client.js";
 import { checkForUpdate } from "./update-check.js";
 const dbg = createDebug("agent-network:channel");
 // --- Sender identity ---
 /**
- * Use sessionId as the sender identifier for OpenClaw routing.
+ * Derive a persistent sender identifier from the MSTP address.
  *
- * OpenClaw Gateway sets `ctx.recipient = senderId` when the LLM replies.
- * Our `sendText()` uses `ctx.recipient` as a sessionId to look up the
- * MSTP session. So senderId MUST equal sessionId for reply routing to work.
+ * Uses `metadata.from` (the remote agent's MSTP address, e.g.
+ * `mstps://masons.ai/alice`) as the conversation key. This ensures
+ * all messages from the same agent land in the same OpenClaw conversation,
+ * regardless of how many MSTP sessions are created.
  *
- * Each MSTP session maps to a separate OpenClaw conversation — correct
- * semantics since sessions are independent, ephemeral exchanges.
+ * Falls back to `sessionId` for direct MSTP clients that connect without
+ * a Connector (no `metadata.from`). These get ephemeral conversations.
  *
- * The remote Agent's MSTP address (from `metadata.from`) is preserved in
- * `senderName` and the envelope's `metadata` field — identity is not lost.
+ * The `activeSession` reverse index in AccountState maps the MSTP address
+ * back to the current sessionId for outbound routing (sendText, deliver).
+ *
+ * See: docs/openclaw/research/session-identity-mapping.md §5
  */
 function deriveSenderId(event) {
+    const from = event.metadata?.from;
+    if (typeof from === "string" && from.length > 0) {
+        return from;
+    }
     return event.sessionId;
 }
 /**
@@ -89,7 +96,7 @@ export const agentNetworkChannel = {
         isConfigured(account) {
             return account.connectorUrl !== "" && account.token !== "";
         },
-        isEnabled(account, cfg) {
+        isEnabled(_account, cfg) {
             const networkCfg = extractNetworkConfig(cfg);
             return networkCfg?.enabled !== false;
         },
@@ -97,68 +104,176 @@ export const agentNetworkChannel = {
     outbound: {
         deliveryMode: "direct",
         async sendText(ctx) {
-            // ctx.recipient = sessionId — Gateway echoes back the senderId from routeMessage
+            // ctx.recipient is now an MSTP address (senderId = address from deriveSenderId).
+            // Resolve to the active sessionId via the reverse index.
             const state = accounts.get(ctx.accountId);
-            if (!state?.sessions.has(ctx.recipient)) {
+            if (!state)
                 return { ok: false };
+            let sessionId = state.activeSession.get(ctx.recipient);
+            // Fallback: ctx.recipient might be a raw sessionId (direct MSTP client
+            // without metadata.from — deriveSenderId fell back to sessionId).
+            if (!sessionId && state.sessions.has(ctx.recipient)) {
+                sessionId = ctx.recipient;
             }
-            const sent = state.client.sendMessage(ctx.recipient, ctx.text, {
+            if (!sessionId || !state.sessions.has(sessionId)) {
+                return { ok: false };
+            }
+            const sent = state.client.sendMessage(sessionId, ctx.text, {
                 contentType: "text",
             });
-            dbg("sendText sessionId=%s contentLength=%d sent=%s", ctx.recipient, ctx.text.length, sent);
+            dbg("sendText recipient=%s sessionId=%s contentLength=%d sent=%s", ctx.recipient, sessionId, ctx.text.length, sent);
             return { ok: sent };
         },
     },
     gateway: {
         async startAccount(ctx) {
             dbg("starting account %s", ctx.accountId);
-            // Capability check: routeMessage is required for inbound message delivery.
-            // Older OpenClaw versions may not provide it on the gateway runtime.
-            if (typeof ctx.runtime.routeMessage !== "function") {
-                console.error("[agent-network] OpenClaw version too old — ctx.runtime.routeMessage is not available. " +
-                    "Inbound messages will not be delivered. Please upgrade OpenClaw.");
-            }
             const { connectorUrl, token } = ctx.account;
             const client = new ConnectorClient(connectorUrl, token);
             const state = {
                 client,
                 sessions: new Map(),
+                activeSession: new Map(),
             };
             accounts.set(ctx.accountId, state);
-            // --- Inbound message routing ---
-            client.on("message_received", (event) => {
+            // --- Inbound message routing (4-step channelRuntime dispatch) ---
+            // Replaces the non-existent routeMessage() API. Uses PluginRuntime
+            // captured in register() via config.ts module-level singleton.
+            // Reference: DingTalk plugin (github.com/soimy/openclaw-channel-dingtalk).
+            //
+            // Concurrency model: this handler is async but EventEmitter fires it
+            // synchronously per event. Multiple MESSAGE_RECEIVED on the same session
+            // produce concurrent dispatches — replies may arrive out of order.
+            // Acceptable for unstructured text conversation (Phase 1). If MSTP adds
+            // structured multi-step interactions, add a per-session dispatch queue.
+            client.on("message_received", async (event) => {
                 dbg("routing inbound message sessionId=%s contentLength=%d", event.sessionId, event.content.length);
-                const senderId = deriveSenderId(event);
-                const envelope = {
-                    channelId: "agent-network",
-                    messageId: `mstp:${event.sessionId}:${randomUUID()}`,
-                    senderId,
-                    senderName: deriveSenderName(event),
-                    text: event.content,
-                    timestamp: Date.now(),
-                    isGroupMessage: false,
-                    metadata: {
-                        ...event.metadata,
-                        contentType: event.contentType,
-                    },
-                };
-                if (typeof ctx.runtime.routeMessage !== "function") {
-                    dbg("routeMessage not available, dropping inbound message sessionId=%s", event.sessionId);
+                // --- Runtime guard ---
+                let runtime;
+                try {
+                    runtime = requirePluginRuntime();
+                }
+                catch {
+                    dbg("plugin runtime not available, dropping message sessionId=%s", event.sessionId);
                     return;
                 }
-                ctx.runtime.routeMessage(envelope);
+                // channel is required in our PluginRuntime type but may be absent
+                // at runtime on older OpenClaw versions (pre-2026.2.19).
+                if (!runtime.channel) {
+                    dbg("channelRuntime not available, dropping message sessionId=%s", event.sessionId);
+                    return;
+                }
+                // Resolve sender identity from session state, NOT from per-message metadata.
+                // metadata.from is reliably present on SESSION_CREATED (Connector sets it
+                // server-side) but NOT on MESSAGE_RECEIVED (per-message metadata is
+                // pass-through from the remote plugin, which doesn't include `from`).
+                // The session_created handler already stored the remoteAddress.
+                const sessionMeta = state.sessions.get(event.sessionId);
+                const senderId = sessionMeta?.remoteAddress ?? event.sessionId;
+                // Derive sender name from the resolved address, not per-message metadata.
+                // Build a synthetic event with the session's address for deriveSenderName.
+                const senderName = sessionMeta?.remoteAddress
+                    ? deriveSenderName({
+                        ...event,
+                        metadata: { ...event.metadata, from: sessionMeta.remoteAddress },
+                    })
+                    : deriveSenderName(event);
+                try {
+                    // Step 1 — Resolve agent route (await defensively — may be sync or async)
+                    const route = await runtime.channel.routing.resolveAgentRoute({
+                        cfg: ctx.cfg,
+                        channel: "agent-network",
+                        accountId: ctx.accountId,
+                        peer: { kind: "direct", id: senderId },
+                    });
+                    // Step 2 — Finalize inbound context (builds MsgContext for LLM pipeline)
+                    const msgCtx = runtime.channel.reply.finalizeInboundContext({
+                        Body: event.content,
+                        RawBody: event.content,
+                        CommandBody: event.content,
+                        From: senderId,
+                        To: senderId,
+                        SessionKey: route.sessionKey,
+                        AccountId: ctx.accountId,
+                        ChatType: "direct",
+                        SenderName: senderName,
+                        SenderId: senderId,
+                        Timestamp: Date.now(),
+                        Provider: "agent-network",
+                        Surface: "agent-network",
+                        MessageSid: `mstp:${event.sessionId}:${randomUUID()}`,
+                        CommandAuthorized: true,
+                        OriginatingChannel: "agent-network",
+                        OriginatingTo: senderId,
+                    });
+                    // Step 3 — Record inbound session
+                    const storePath = runtime.channel.session.resolveStorePath(undefined, { agentId: route.agentId });
+                    const sessionKey = typeof msgCtx.SessionKey === "string"
+                        ? msgCtx.SessionKey
+                        : route.sessionKey;
+                    await runtime.channel.session.recordInboundSession({
+                        storePath,
+                        sessionKey,
+                        ctx: msgCtx,
+                    });
+                    // Step 4 — Dispatch to LLM pipeline + deliver reply via callback
+                    await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+                        ctx: msgCtx,
+                        cfg: ctx.cfg,
+                        dispatcherOptions: {
+                            deliver: async (payload) => {
+                                const text = payload.text;
+                                if (!text)
+                                    return;
+                                // senderId is now an MSTP address. Resolve to sessionId.
+                                let deliverSessionId = state.activeSession.get(senderId);
+                                // Fallback: senderId might be a raw sessionId (direct client).
+                                if (!deliverSessionId && state.sessions.has(senderId)) {
+                                    deliverSessionId = senderId;
+                                }
+                                // Session may have ended while LLM was processing.
+                                if (!deliverSessionId || !state.sessions.has(deliverSessionId))
+                                    return;
+                                const sent = state.client.sendMessage(deliverSessionId, text, {
+                                    contentType: "text",
+                                });
+                                dbg("deliver reply address=%s sessionId=%s contentLength=%d sent=%s", senderId, deliverSessionId, text.length, sent);
+                            },
+                            onError: (err) => {
+                                console.error(`[agent-network:${ctx.accountId}] dispatch error:`, err);
+                            },
+                        },
+                    });
+                }
+                catch (err) {
+                    console.error(`[agent-network:${ctx.accountId}] inbound dispatch failed sessionId=${event.sessionId}:`, err);
+                }
             });
             // --- Session lifecycle ---
             client.on("session_created", (event) => {
                 dbg("session created sessionId=%s direction=%s", event.sessionId, event.direction);
                 const from = event.metadata?.from;
-                state.sessions.set(event.sessionId, {
-                    remoteAddress: typeof from === "string" && from.length > 0 ? from : null,
-                });
+                const remoteAddress = typeof from === "string" && from.length > 0 ? from : null;
+                state.sessions.set(event.sessionId, { remoteAddress });
+                // Update reverse index: this address is now reachable via this session.
+                // Last-write-wins: if a new session arrives from the same address,
+                // replies go to the newest session (same as XMPP resource binding).
+                if (remoteAddress) {
+                    state.activeSession.set(remoteAddress, event.sessionId);
+                }
             });
             client.on("session_ended", (event) => {
                 dbg("session ended sessionId=%s", event.sessionId);
+                const sessionMeta = state.sessions.get(event.sessionId);
                 state.sessions.delete(event.sessionId);
+                // Only clear reverse index if this session was the active one.
+                // If a newer session replaced it, the index already points elsewhere.
+                if (sessionMeta?.remoteAddress) {
+                    const currentActive = state.activeSession.get(sessionMeta.remoteAddress);
+                    if (currentActive === event.sessionId) {
+                        state.activeSession.delete(sessionMeta.remoteAddress);
+                    }
+                }
             });
             // --- Error handling ---
             // Must register before connect() — unhandled "error" events crash the process.
@@ -169,6 +284,7 @@ export const agentNetworkChannel = {
             client.on("disconnected", () => {
                 dbg("disconnected, cleared %d sessions", state.sessions.size);
                 state.sessions.clear();
+                state.activeSession.clear();
             });
             // --- Abort signal ---
             ctx.abortSignal.addEventListener("abort", () => {
@@ -207,6 +323,7 @@ export const agentNetworkChannel = {
                 state.client.removeAllListeners();
                 state.client.disconnect();
                 state.sessions.clear();
+                state.activeSession.clear();
                 accounts.delete(ctx.accountId);
             }
         },

package/dist/config.d.ts

@@ -49,6 +49,28 @@ export declare function initConnectorClient(client: ConnectorClient): void;
  * operating on a disconnected client.
  */
 export declare function clearConnectorClient(): void;
+/**
+ * Store the OpenClaw PluginRuntime for inbound message dispatch.
+ *
+ * Called by `register(api)` in plugin.ts — captures `api.runtime` which
+ * provides `runtime.channel.*` (routing, reply, session) used by the
+ * 4-step inbound dispatch flow in channel.ts.
+ *
+ * Idempotent: overwrites on re-call. Gateway may hot-reload plugins,
+ * calling `register()` again without a teardown counterpart.
+ */
+export declare function initPluginRuntime(runtime: unknown): void;
+/**
+ * Clear the stored PluginRuntime reference.
+ */
+export declare function clearPluginRuntime(): void;
+/**
+ * Get the stored PluginRuntime. Throws if not initialized.
+ *
+ * Callers cast the result to `PluginRuntime` (defined in channel.ts)
+ * at the usage site. Typed as `unknown` here to avoid circular imports.
+ */
+export declare function requirePluginRuntime(): unknown;
 /**
  * Get platform config. Always returns a valid config — defaults are set
  * at module load time, and overwritten by `initToolConfig()` when

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AAuB9B;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAMhC;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAsBjE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAOjE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAMD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,oBAAoB,CAE5D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,CAOxD;AAMD,+EAA+E;AAC/E,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAgDD,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,kBAAkB,EACzB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKrE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAQvD;AAMD;;;;;GAKG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKvD;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKzD;AAMD,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,cAAc,EAAE,OAAO,CAAC;IACxB,wDAAwD;IACxD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,4EAA4E;IAC5E,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,YAAY,CAAC,CA2BhE;AAMD,uDAAuD;AACvD,wBAAgB,gBAAgB,IAAI,IAAI,CAKvC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AA2B9B;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAMhC;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAsBjE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAOjE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAMD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAExD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAO9C;AAMD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,oBAAoB,CAE5D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,CAOxD;AAMD,+EAA+E;AAC/E,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAgDD,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,kBAAkB,EACzB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKrE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAQvD;AAMD;;;;;GAKG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKvD;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKzD;AAMD,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,cAAc,EAAE,OAAO,CAAC;IACxB,wDAAwD;IACxD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,4EAA4E;IAC5E,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,YAAY,CAAC,CA2BhE;AAMD,uDAAuD;AACvD,wBAAgB,gBAAgB,IAAI,IAAI,CAMvC"}

package/dist/config.js

@@ -32,6 +32,9 @@ let storedApiKey = null;
 let storedPendingTarget = null;
 // Runtime state (live connection — set by startAccount, cleared by stopAccount)
 let storedConnectorClient = null;
+// PluginRuntime state (set by register() in plugin.ts, used by channel.ts)
+// Typed as unknown to avoid circular imports — channel.ts casts to PluginRuntime.
+let storedPluginRuntime = null;
 // ---------------------------------------------------------------------------
 // Config navigation — shared between channel.ts and config.ts
 // ---------------------------------------------------------------------------
@@ -106,6 +109,40 @@ export function clearConnectorClient() {
     storedConnectorClient = null;
 }
 // ---------------------------------------------------------------------------
+// PluginRuntime injection (called by register() in plugin.ts)
+// ---------------------------------------------------------------------------
+/**
+ * Store the OpenClaw PluginRuntime for inbound message dispatch.
+ *
+ * Called by `register(api)` in plugin.ts — captures `api.runtime` which
+ * provides `runtime.channel.*` (routing, reply, session) used by the
+ * 4-step inbound dispatch flow in channel.ts.
+ *
+ * Idempotent: overwrites on re-call. Gateway may hot-reload plugins,
+ * calling `register()` again without a teardown counterpart.
+ */
+export function initPluginRuntime(runtime) {
+    storedPluginRuntime = runtime;
+}
+/**
+ * Clear the stored PluginRuntime reference.
+ */
+export function clearPluginRuntime() {
+    storedPluginRuntime = null;
+}
+/**
+ * Get the stored PluginRuntime. Throws if not initialized.
+ *
+ * Callers cast the result to `PluginRuntime` (defined in channel.ts)
+ * at the usage site. Typed as `unknown` here to avoid circular imports.
+ */
+export function requirePluginRuntime() {
+    if (storedPluginRuntime == null) {
+        throw new Error("Plugin runtime not initialized. register() must be called first.");
+    }
+    return storedPluginRuntime;
+}
+// ---------------------------------------------------------------------------
 // Guard functions (used by tools — fail-fast if not initialized)
 // ---------------------------------------------------------------------------
 /**
@@ -312,4 +349,5 @@ export function _resetForTesting() {
     storedApiKey = null;
     storedPendingTarget = null;
     storedConnectorClient = null;
+    storedPluginRuntime = null;
 }

package/dist/platform-client.d.ts

@@ -120,6 +120,10 @@ export interface ListConnectionsResponse {
         address: string;
     }>;
 }
+export interface ConnectionStatusResponse {
+    status: "connected" | "pending" | "not_connected";
+    canCreateSession: boolean;
+}
 /**
  * `POST /setup/init` — Start Device Code Flow.
  *
@@ -207,4 +211,13 @@ export declare function updateProfile(cfg: PlatformClientConfig, apiKey: string,
  * Returns name + MSTP address for each connected agent.
  */
 export declare function listConnections(cfg: PlatformClientConfig, apiKey: string): Promise<ListConnectionsResponse>;
+/**
+ * `GET /connections/status?target={handle}` — Check connection status.
+ *
+ * Requires API Key in Authorization header.
+ * Returns connection status and whether session creation is possible.
+ *
+ * Returns null if the request fails (advisory — caller should degrade gracefully).
+ */
+export declare function getConnectionStatus(cfg: PlatformClientConfig, apiKey: string, targetHandle: string): Promise<ConnectionStatusResponse | null>;
 //# sourceMappingURL=platform-client.d.ts.map

package/dist/platform-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"platform-client.d.ts","sourceRoot":"","sources":["../src/platform-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"platform-client.d.ts","sourceRoot":"","sources":["../src/platform-client.ts"],"names":[],"mappings":"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"}

package/dist/platform-client.js

@@ -247,3 +247,28 @@ export async function listConnections(cfg, apiKey) {
         return handleError(res);
     return (await res.json());
 }
+/**
+ * `GET /connections/status?target={handle}` — Check connection status.
+ *
+ * Requires API Key in Authorization header.
+ * Returns connection status and whether session creation is possible.
+ *
+ * Returns null if the request fails (advisory — caller should degrade gracefully).
+ */
+export async function getConnectionStatus(cfg, apiKey, targetHandle) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 3000);
+        const res = await fetch(`${baseUrl(cfg)}/connections/status?target=${encodeURIComponent(targetHandle)}`, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        if (!res.ok)
+            return null; // Advisory — degrade gracefully
+        return (await res.json());
+    }
+    catch {
+        return null; // Network error or timeout — degrade gracefully
+    }
+}

package/dist/plugin.d.ts

@@ -1,4 +1,5 @@
 interface OpenClawPluginApi {
+    runtime: unknown;
     registerChannel(opts: {
         plugin: unknown;
     }): void;

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAWA,UAAU,iBAAiB;IACzB,eAAe,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC;CACnE;AAED,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;kBA4BI,iBAAiB;CAuGhC,CAAC;AAEF,eAAe,MAAM,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAWA,UAAU,iBAAiB;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC;CACnE;AAED,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;kBA4BI,iBAAiB;CA4GhC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/plugin.js

@@ -3,7 +3,7 @@
 // NOT imported by index.ts to avoid pulling ws/typebox into Next.js app bundles.
 import { agentNetworkChannel } from "./channel.js";
 import { configureInteractive } from "./cli-setup.js";
-import { detectPendingState } from "./config.js";
+import { detectPendingState, initPluginRuntime } from "./config.js";
 import { registerTools } from "./tools.js";
 import { PLUGIN_VERSION } from "./version.js";
 const plugin = {
@@ -32,6 +32,10 @@ const plugin = {
         },
     },
     register(api) {
+        // Capture runtime for inbound message dispatch (Pathway 1: module-level singleton).
+        // api.runtime is the full PluginRuntime (includes .channel for routing/reply/session).
+        // Idempotent — Gateway may hot-reload, calling register() again.
+        initPluginRuntime(api.runtime);
         // Register tools FIRST — they must be available even when the channel
         // has no credentials yet (setup flow needs these tools to GET credentials).
         registerTools(api);

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAoCH,UAAU,WAAW;IACnB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,CACP,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,WAAW,CAAC,CAAC;CAC3B;AAED,UAAU,OAAO;IACf,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACzE;AAmBD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAED,6DAA6D;AAC7D,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE7D;AAuID;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CA6pBhD"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAqCH,UAAU,WAAW;IACnB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,CACP,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,WAAW,CAAC,CAAC;CAC3B;AAED,UAAU,OAAO;IACf,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACzE;AAmBD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAED,6DAA6D;AAC7D,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE7D;AAuJD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAurBhD"}

package/dist/tools.js

@@ -15,7 +15,7 @@
  */
 import { Type } from "@sinclair/typebox";
 import { clearTargetHandle, getPendingTarget, markProfileComplete, markProfileNeeded, requireApiKey, requireConnectorClient, requirePlatformConfig, writeCredentials, } from "./config.js";
-import { acceptRequest, declineRequest, initSetup, listConnections, listRequests, onboard, PlatformApiError, pollSetup, reconnect, requestConnection, SetupExpiredError, SetupPendingError, updateProfile, } from "./platform-client.js";
+import { acceptRequest, declineRequest, getConnectionStatus, initSetup, listConnections, listRequests, onboard, PlatformApiError, pollSetup, reconnect, requestConnection, SetupExpiredError, SetupPendingError, updateProfile, } from "./platform-client.js";
 import { getUpdateInfo } from "./update-check.js";
 // ---------------------------------------------------------------------------
 // Constants
@@ -131,19 +131,33 @@ function formatSessionCreated(sessionId, target) {
 function waitForSessionCreated(client, requestId) {
     return new Promise((resolve) => {
         const timer = setTimeout(() => {
-            client.off("session_created", onSessionCreated);
+            cleanup();
             resolve({
                 error: "Session creation timed out. The remote agent may be unavailable.",
             });
         }, sessionTimeoutMs);
+        function cleanup() {
+            clearTimeout(timer);
+            client.off("session_created", onSessionCreated);
+            client.off("error", onError);
+        }
         function onSessionCreated(event) {
             if (event.requestId === requestId && event.direction === "outbound") {
-                clearTimeout(timer);
-                client.off("session_created", onSessionCreated);
+                cleanup();
                 resolve({ sessionId: event.sessionId });
             }
         }
+        // Listen for ERROR events from the Connector (e.g., access control rejection).
+        // The Connector sends { event: "ERROR", requestId, message } as a global error
+        // when CREATE_SESSION is rejected.
+        function onError(err) {
+            // ConnectorClient emits Error objects with the server message as err.message.
+            // Match by checking if the error message is actionable (not a generic WS error).
+            cleanup();
+            resolve({ error: err.message });
+        }
         client.on("session_created", onSessionCreated);
+        client.on("error", onError);
     });
 }
 // ---------------------------------------------------------------------------
@@ -603,6 +617,28 @@ export function registerTools(api) {
         execute: withUpdateNotice(async (_id, params) => {
             const client = requireConnectorClient();
             const target = params.target;
+            // --- Pre-flight: check connection status (advisory, not gate) ---
+            // If the check fails (network error, API down), proceed anyway —
+            // the Connector gate (Layer 2) is the authoritative enforcement.
+            try {
+                const handle = target
+                    .replace(/^mstps?:\/\/[^/]+\//, "")
+                    .replace(/\/+$/, "");
+                if (handle) {
+                    const cfg = requirePlatformConfig();
+                    const apiKey = requireApiKey();
+                    const status = await getConnectionStatus(cfg, apiKey, handle);
+                    if (status && !status.canCreateSession) {
+                        if (status.status === "pending") {
+                            return textResult(`Connection request to @${handle} is pending. Wait for the other agent to accept your request.`);
+                        }
+                        return textResult(`You are not connected to @${handle}. Send a connection request first using masons_send_connection_request.`);
+                    }
+                }
+            }
+            catch {
+                // Advisory check failed — proceed to Connector gate
+            }
             const { requestId, sent } = client.createSession(target);
             if (!sent) {
                 return textResult("Failed to create session. The network connection may be temporarily unavailable. Try again in a moment.");

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 /** Plugin version — must match package.json. Validated by prepublishOnly. */
-export declare const PLUGIN_VERSION = "0.3.6";
+export declare const PLUGIN_VERSION = "0.3.8";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Plugin version — must match package.json. Validated by prepublishOnly. */
-export const PLUGIN_VERSION = "0.3.6";
+export const PLUGIN_VERSION = "0.3.8";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masons/agent-network",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "MASONS plugin for OpenClaw — connect your agent to the agent network",
   "license": "MIT",
   "author": "MASONS.ai <hello@masons.ai> (https://masons.ai)",