@masons/agent-network 0.3.8 → 0.4.0

package/dist/channel.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAc9D,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;AAqDD,eAAO,MAAM,mBAAmB,EAAE,yBA4VjC,CAAC"}

package/dist/channel.js

@@ -1,33 +1,14 @@
 import { randomUUID } from "node:crypto";
 import createDebug from "debug";
-import { clearConnectorClient, extractNetworkConfig, initConnectorClient, initToolConfig, requirePluginRuntime, } from "./config.js";
+import { clearConnectorClient, clearConversationManager, extractNetworkConfig, initConnectorClient, initConversationManager, initToolConfig, requirePluginRuntime, } from "./config.js";
 import { ConnectorClient } from "./connector-client.js";
+import { ConversationManager } from "./conversation-manager.js";
 import { checkForUpdate } from "./update-check.js";
 const dbg = createDebug("agent-network:channel");
 // --- Sender identity ---
-/**
- * Derive a persistent sender identifier from the MSTP address.
- *
- * 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.
- *
- * Falls back to `sessionId` for direct MSTP clients that connect without
- * a Connector (no `metadata.from`). These get ephemeral conversations.
- *
- * 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;
-}
+// Identity resolution uses session state (remoteAddress from SESSION_CREATED),
+// not per-message metadata. See the message_received handler for details.
+// See: docs/openclaw/research/session-identity-mapping.md §5
 /**
  * Extract a human-readable name from the remote Agent's MSTP address.
  *
@@ -45,6 +26,20 @@ function deriveSenderName(event) {
     const parts = trimmed.split("/");
     return parts[parts.length - 1] || from;
 }
+/**
+ * Extract the Connector host from a connectorUrl.
+ * `wss://preview.masons.ai/gw` -> `preview.masons.ai`
+ */
+function extractConnectorHost(connectorUrl) {
+    try {
+        const url = new URL(connectorUrl);
+        return url.hostname;
+    }
+    catch {
+        // Fallback: strip protocol and path
+        return connectorUrl.replace(/^wss?:\/\//, "").replace(/\/.*$/, "");
+    }
+}
 const accounts = new Map();
 // --- Channel Plugin ---
 export const agentNetworkChannel = {
@@ -104,25 +99,14 @@ export const agentNetworkChannel = {
     outbound: {
         deliveryMode: "direct",
         async sendText(ctx) {
-            // ctx.recipient is now an MSTP address (senderId = address from deriveSenderId).
-            // Resolve to the active sessionId via the reverse index.
+            // ctx.recipient is the MSTP address or sessionId fallback (senderId from inbound dispatch).
+            // ConversationManager.send() handles session management transparently.
             const state = accounts.get(ctx.accountId);
             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;
-            }
-            if (!sessionId || !state.sessions.has(sessionId)) {
-                return { ok: false };
-            }
-            const sent = state.client.sendMessage(sessionId, ctx.text, {
-                contentType: "text",
-            });
-            dbg("sendText recipient=%s sessionId=%s contentLength=%d sent=%s", ctx.recipient, sessionId, ctx.text.length, sent);
-            return { ok: sent };
+            const result = await state.conversationManager.send(ctx.recipient, ctx.text);
+            dbg("sendText recipient=%s status=%s contentLength=%d", ctx.recipient, result.status, ctx.text.length);
+            return { ok: result.status === "sent" };
         },
     },
     gateway: {
@@ -130,10 +114,11 @@ export const agentNetworkChannel = {
             dbg("starting account %s", ctx.accountId);
             const { connectorUrl, token } = ctx.account;
             const client = new ConnectorClient(connectorUrl, token);
+            const connectorHost = extractConnectorHost(connectorUrl);
+            const conversationManager = new ConversationManager(client, connectorHost);
             const state = {
                 client,
-                sessions: new Map(),
-                activeSession: new Map(),
+                conversationManager,
             };
             accounts.set(ctx.accountId, state);
             // --- Inbound message routing (4-step channelRuntime dispatch) ---
@@ -163,19 +148,22 @@ export const agentNetworkChannel = {
                     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
+                // Resolve sender identity via ConversationManager.
+                // The session_created handler registered the inbound session with
+                // the ConversationManager, so we can look up the contact handle.
+                const senderAddress = conversationManager.getAddressBySessionId(event.sessionId);
+                // Determine if the address is a real MSTP address or a sessionId fallback.
+                const isRealAddress = typeof senderAddress === "string" &&
+                    (senderAddress.startsWith("mstps://") ||
+                        senderAddress.startsWith("mstp://"));
+                // senderId for OpenClaw routing: use MSTP address if available,
+                // fall back to sessionId for unknown sessions / direct MSTP clients.
+                const senderId = isRealAddress ? senderAddress : event.sessionId;
+                // Derive sender name from the MSTP address, or "Unknown Agent" for fallback.
+                const senderName = isRealAddress
                     ? deriveSenderName({
                         ...event,
-                        metadata: { ...event.metadata, from: sessionMeta.remoteAddress },
+                        metadata: { ...event.metadata, from: senderAddress },
                     })
                     : deriveSenderName(event);
                 try {
@@ -225,19 +213,11 @@ export const agentNetworkChannel = {
                                 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);
+                                // Use ConversationManager to send the reply.
+                                // Pass the MSTP address (senderId) directly so the CM
+                                // can match the registered conversation entry.
+                                const deliverResult = await conversationManager.send(senderId, text);
+                                dbg("deliver reply senderId=%s status=%s contentLength=%d", senderId, deliverResult.status, text.length);
                             },
                             onError: (err) => {
                                 console.error(`[agent-network:${ctx.accountId}] dispatch error:`, err);
@@ -249,45 +229,37 @@ export const agentNetworkChannel = {
                     console.error(`[agent-network:${ctx.accountId}] inbound dispatch failed sessionId=${event.sessionId}:`, err);
                 }
             });
-            // --- Session lifecycle ---
+            // --- Inbound session registration ---
+            // When a remote agent creates a session (direction=inbound),
+            // register it with the ConversationManager.
             client.on("session_created", (event) => {
                 dbg("session created sessionId=%s direction=%s", event.sessionId, event.direction);
-                const from = event.metadata?.from;
-                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);
+                if (event.direction === "inbound") {
+                    const from = event.metadata?.from;
+                    const remoteAddress = typeof from === "string" && from.length > 0 ? from : null;
+                    if (remoteAddress) {
+                        const contact = deriveSenderName(event);
+                        conversationManager.registerInbound(event.sessionId, contact, remoteAddress);
+                    }
+                    else {
+                        // No address metadata — register with sessionId as fallback
+                        conversationManager.registerInbound(event.sessionId, event.sessionId, event.sessionId);
                     }
                 }
+                // Outbound sessions are handled by SessionLifecycle internally
+                // (matched by requestId in the createSession flow).
             });
+            // --- Session ended + disconnect ---
+            // SessionLifecycle handles session state transitions (session_ended, disconnected)
+            // via its own event subscriptions. No CM calls needed here.
             // --- Error handling ---
             // Must register before connect() — unhandled "error" events crash the process.
             client.on("error", (err) => {
                 console.error(`[agent-network:${ctx.accountId}]`, err.message);
             });
-            // --- Disconnect cleanup ---
-            client.on("disconnected", () => {
-                dbg("disconnected, cleared %d sessions", state.sessions.size);
-                state.sessions.clear();
-                state.activeSession.clear();
-            });
             // --- Abort signal ---
             ctx.abortSignal.addEventListener("abort", () => {
+                clearConversationManager();
                 clearConnectorClient(); // idempotent — stopAccount() may also call
                 client.disconnect();
             }, { once: true });
@@ -300,8 +272,9 @@ export const agentNetworkChannel = {
             // --- Connect ---
             await client.connect();
             dbg("connected account=%s", ctx.accountId);
-            // --- Expose client to tools (only after WS is connected) ---
+            // --- Expose client and conversation manager to tools (only after WS is connected) ---
             initConnectorClient(client);
+            initConversationManager(conversationManager);
             // Park the Promise — DO NOT resolve/return.
             // Resolution signals "account stopped" to OpenClaw's orchestrator,
             // triggering auto-restart with exponential backoff (crash-loop).
@@ -319,11 +292,10 @@ export const agentNetworkChannel = {
             dbg("stopping account %s", ctx.accountId);
             const state = accounts.get(ctx.accountId);
             if (state) {
+                clearConversationManager();
                 clearConnectorClient();
                 state.client.removeAllListeners();
                 state.client.disconnect();
-                state.sessions.clear();
-                state.activeSession.clear();
                 accounts.delete(ctx.accountId);
             }
         },

package/dist/config.d.ts

@@ -15,6 +15,7 @@
  *
  */
 import type { ConnectorClient } from "./connector-client.js";
+import type { ConversationManager } from "./conversation-manager.js";
 import { type PlatformClientConfig } from "./platform-client.js";
 /**
  * Extract the `channels.agent-network` section from the full OpenClaw config.
@@ -49,6 +50,24 @@ export declare function initConnectorClient(client: ConnectorClient): void;
  * operating on a disconnected client.
  */
 export declare function clearConnectorClient(): void;
+/**
+ * Inject the live ConversationManager after WebSocket connection is established.
+ *
+ * Called by `startAccount()` AFTER `client.connect()` resolves — ensures
+ * tools always get a manager backed by a connected client.
+ */
+export declare function initConversationManager(manager: ConversationManager): void;
+/**
+ * Clear the stored ConversationManager reference.
+ *
+ * Called by `stopAccount()` before disconnecting — prevents tools from
+ * operating on a stale manager.
+ */
+export declare function clearConversationManager(): void;
+/**
+ * Get the live ConversationManager. Throws if not initialized.
+ */
+export declare function requireConversationManager(): ConversationManager;
 /**
  * Store the OpenClaw PluginRuntime for inbound message dispatch.
  *

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;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"}
+{"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,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AA4B9B;;;;;;;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;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED;;GAEG;AACH,wBAAgB,0BAA0B,IAAI,mBAAmB,CAOhE;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,CAOvC"}

package/dist/config.js

@@ -32,6 +32,7 @@ let storedApiKey = null;
 let storedPendingTarget = null;
 // Runtime state (live connection — set by startAccount, cleared by stopAccount)
 let storedConnectorClient = null;
+let storedConversationManager = 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;
@@ -109,6 +110,36 @@ export function clearConnectorClient() {
     storedConnectorClient = null;
 }
 // ---------------------------------------------------------------------------
+// ConversationManager injection (called by startAccount() after connect)
+// ---------------------------------------------------------------------------
+/**
+ * Inject the live ConversationManager after WebSocket connection is established.
+ *
+ * Called by `startAccount()` AFTER `client.connect()` resolves — ensures
+ * tools always get a manager backed by a connected client.
+ */
+export function initConversationManager(manager) {
+    storedConversationManager = manager;
+}
+/**
+ * Clear the stored ConversationManager reference.
+ *
+ * Called by `stopAccount()` before disconnecting — prevents tools from
+ * operating on a stale manager.
+ */
+export function clearConversationManager() {
+    storedConversationManager = null;
+}
+/**
+ * Get the live ConversationManager. Throws if not initialized.
+ */
+export function requireConversationManager() {
+    if (!storedConversationManager) {
+        throw new Error("Not connected to the agent network. Wait for the connection to be established.");
+    }
+    return storedConversationManager;
+}
+// ---------------------------------------------------------------------------
 // PluginRuntime injection (called by register() in plugin.ts)
 // ---------------------------------------------------------------------------
 /**
@@ -349,5 +380,6 @@ export function _resetForTesting() {
     storedApiKey = null;
     storedPendingTarget = null;
     storedConnectorClient = null;
+    storedConversationManager = null;
     storedPluginRuntime = null;
 }

package/dist/conversation-manager.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Conversation Manager — maps contacts to conversations.
+ *
+ * Owns the identity-based API that the Tool Interface and Inbound Dispatcher
+ * call. Internally delegates session management to SessionLifecycle.
+ *
+ * Contact resolution: handle -> `mstps://${connectorHost}/${handle}`
+ * Internal key: MSTP address (same as SessionLifecycle).
+ * One session per contact, last-write-wins (D2).
+ * In-memory only, no persistence (D3).
+ *
+ * @see docs/openclaw/session-abstraction-system-design.md §4.1
+ */
+import type { ConnectorClient } from "./connector-client.js";
+import { SessionLifecycle } from "./session-lifecycle.js";
+export interface SendResult {
+    status: "sent" | "failed";
+    error?: string;
+}
+export interface ConversationEntry {
+    contact: string;
+    address: string;
+    lastMessageAt: number;
+    initiatedBy: "local" | "remote";
+}
+export interface ConversationSummary {
+    contact: string;
+    address: string;
+    active: boolean;
+    lastMessageAt: number;
+    initiatedBy: "local" | "remote";
+}
+export declare class ConversationManager {
+    readonly sessionLifecycle: SessionLifecycle;
+    private readonly client;
+    private readonly connectorHost;
+    /** Conversations keyed by MSTP address */
+    private readonly conversations;
+    constructor(client: ConnectorClient, connectorHost: string);
+    /**
+     * Send a message to a contact. Session management is transparent.
+     * Creates a session automatically if none exists (D1 — sync-but-transparent).
+     *
+     * @param contact - Handle or MSTP address of the target agent.
+     * @param content - Message content to send.
+     */
+    send(contact: string, content: string): Promise<SendResult>;
+    /**
+     * Register an inbound session (remote agent initiated).
+     * Called by the channel adapter on SESSION_CREATED with direction=inbound.
+     */
+    registerInbound(sessionId: string, contact: string, address: string): void;
+    /**
+     * Resolve a sessionId to a contact handle.
+     * Used by the inbound dispatcher to derive sender identity from a message event.
+     */
+    getContactBySessionId(sessionId: string): string | undefined;
+    /**
+     * Resolve a sessionId to an MSTP address.
+     * Used by the channel adapter for reverse lookup.
+     */
+    getAddressBySessionId(sessionId: string): string | undefined;
+    /**
+     * List all conversations with metadata.
+     */
+    listConversations(): ConversationSummary[];
+    /**
+     * End the conversation with a contact.
+     * Closes the active session if one exists.
+     */
+    endConversation(contact: string): void;
+    /**
+     * Resolve a contact (handle or MSTP address) to an MSTP address.
+     *
+     * Resolution order:
+     * 1. If `contact` is already an MSTP address (starts with mstps:// or mstp://),
+     *    return it as-is.
+     * 2. If `contact` is already a key in the conversations map (e.g., a sessionId
+     *    used as fallback address for direct MSTP clients), return it as-is.
+     * 3. Otherwise construct: `mstps://${connectorHost}/${handle}`.
+     */
+    resolveAddress(contact: string): string;
+    /**
+     * Extract handle from an MSTP address.
+     * `mstps://preview.masons.ai/alice` -> `alice`
+     */
+    extractHandle(address: string): string;
+    /** @internal Reset for test isolation. */
+    _resetForTesting(): void;
+}
+//# sourceMappingURL=conversation-manager.d.ts.map

package/dist/conversation-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-manager.d.ts","sourceRoot":"","sources":["../src/conversation-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAQ1D,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,OAAO,GAAG,QAAQ,CAAC;CACjC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,OAAO,GAAG,QAAQ,CAAC;CACjC;AAMD,qBAAa,mBAAmB;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAwC;gBAE1D,MAAM,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM;IAU1D;;;;;;OAMG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAgDjE;;;OAGG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAyB1E;;;OAGG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAQ5D;;;OAGG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI5D;;OAEG;IACH,iBAAiB,IAAI,mBAAmB,EAAE;IAe1C;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAkBtC;;;;;;;;;OASG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAYvC;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAUtC,0CAA0C;IAC1C,gBAAgB,IAAI,IAAI;CAIzB"}

package/dist/conversation-manager.js

@@ -0,0 +1,189 @@
+/**
+ * Conversation Manager — maps contacts to conversations.
+ *
+ * Owns the identity-based API that the Tool Interface and Inbound Dispatcher
+ * call. Internally delegates session management to SessionLifecycle.
+ *
+ * Contact resolution: handle -> `mstps://${connectorHost}/${handle}`
+ * Internal key: MSTP address (same as SessionLifecycle).
+ * One session per contact, last-write-wins (D2).
+ * In-memory only, no persistence (D3).
+ *
+ * @see docs/openclaw/session-abstraction-system-design.md §4.1
+ */
+import createDebug from "debug";
+import { SessionLifecycle } from "./session-lifecycle.js";
+const dbg = createDebug("agent-network:conversation-manager");
+// ---------------------------------------------------------------------------
+// ConversationManager
+// ---------------------------------------------------------------------------
+export class ConversationManager {
+    sessionLifecycle;
+    client;
+    connectorHost;
+    /** Conversations keyed by MSTP address */
+    conversations = new Map();
+    constructor(client, connectorHost) {
+        this.client = client;
+        this.connectorHost = connectorHost;
+        this.sessionLifecycle = new SessionLifecycle(client);
+    }
+    // -------------------------------------------------------------------------
+    // Public API — identity-based
+    // -------------------------------------------------------------------------
+    /**
+     * Send a message to a contact. Session management is transparent.
+     * Creates a session automatically if none exists (D1 — sync-but-transparent).
+     *
+     * @param contact - Handle or MSTP address of the target agent.
+     * @param content - Message content to send.
+     */
+    async send(contact, content) {
+        const address = this.resolveAddress(contact);
+        // Ensure conversation entry exists
+        if (!this.conversations.has(address)) {
+            this.conversations.set(address, {
+                contact: this.extractHandle(address),
+                address,
+                lastMessageAt: Date.now(),
+                initiatedBy: "local",
+            });
+        }
+        try {
+            const sessionId = await this.sessionLifecycle.ensureSession(address);
+            const sent = this.client.sendMessage(sessionId, content, {
+                contentType: "text",
+            });
+            if (!sent) {
+                return {
+                    status: "failed",
+                    error: "Failed to send message. The network connection may be temporarily unavailable.",
+                };
+            }
+            // Update lastMessageAt
+            const entry = this.conversations.get(address);
+            if (entry) {
+                entry.lastMessageAt = Date.now();
+            }
+            dbg("send contact=%s address=%s sessionId=%s", contact, address, sessionId);
+            return { status: "sent" };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "Unknown error";
+            dbg("send failed contact=%s error=%s", contact, message);
+            return { status: "failed", error: message };
+        }
+    }
+    /**
+     * Register an inbound session (remote agent initiated).
+     * Called by the channel adapter on SESSION_CREATED with direction=inbound.
+     */
+    registerInbound(sessionId, contact, address) {
+        this.sessionLifecycle.registerInbound(sessionId, address);
+        if (!this.conversations.has(address)) {
+            this.conversations.set(address, {
+                contact,
+                address,
+                lastMessageAt: Date.now(),
+                initiatedBy: "remote",
+            });
+        }
+        else {
+            const entry = this.conversations.get(address);
+            if (entry) {
+                entry.lastMessageAt = Date.now();
+            }
+        }
+        dbg("registerInbound sessionId=%s contact=%s address=%s", sessionId, contact, address);
+    }
+    /**
+     * Resolve a sessionId to a contact handle.
+     * Used by the inbound dispatcher to derive sender identity from a message event.
+     */
+    getContactBySessionId(sessionId) {
+        const address = this.sessionLifecycle.getAddressBySessionId(sessionId);
+        if (!address)
+            return undefined;
+        const entry = this.conversations.get(address);
+        return entry?.contact;
+    }
+    /**
+     * Resolve a sessionId to an MSTP address.
+     * Used by the channel adapter for reverse lookup.
+     */
+    getAddressBySessionId(sessionId) {
+        return this.sessionLifecycle.getAddressBySessionId(sessionId);
+    }
+    /**
+     * List all conversations with metadata.
+     */
+    listConversations() {
+        const result = [];
+        for (const [address, entry] of this.conversations) {
+            const sessionId = this.sessionLifecycle.getSession(address);
+            result.push({
+                contact: entry.contact,
+                address: entry.address,
+                active: sessionId !== null,
+                lastMessageAt: entry.lastMessageAt,
+                initiatedBy: entry.initiatedBy,
+            });
+        }
+        return result;
+    }
+    /**
+     * End the conversation with a contact.
+     * Closes the active session if one exists.
+     */
+    endConversation(contact) {
+        const address = this.resolveAddress(contact);
+        this.sessionLifecycle.closeSession(address);
+        this.conversations.delete(address);
+        dbg("endConversation contact=%s address=%s", contact, address);
+    }
+    // NOTE: handleDisconnected() and handleSessionEnded() are NOT needed here.
+    // SessionLifecycle owns session state transitions via its own event subscriptions
+    // (session_ended, disconnected). Conversations persist across both events —
+    // sessions are recreated transparently on the next send().
+    // -------------------------------------------------------------------------
+    // Contact resolution
+    // -------------------------------------------------------------------------
+    /**
+     * Resolve a contact (handle or MSTP address) to an MSTP address.
+     *
+     * Resolution order:
+     * 1. If `contact` is already an MSTP address (starts with mstps:// or mstp://),
+     *    return it as-is.
+     * 2. If `contact` is already a key in the conversations map (e.g., a sessionId
+     *    used as fallback address for direct MSTP clients), return it as-is.
+     * 3. Otherwise construct: `mstps://${connectorHost}/${handle}`.
+     */
+    resolveAddress(contact) {
+        if (contact.startsWith("mstps://") || contact.startsWith("mstp://")) {
+            return contact;
+        }
+        // Check if the contact string is already a registered conversation key
+        // (handles the fallback case where sessionId is used as address).
+        if (this.conversations.has(contact)) {
+            return contact;
+        }
+        return `mstps://${this.connectorHost}/${contact}`;
+    }
+    /**
+     * Extract handle from an MSTP address.
+     * `mstps://preview.masons.ai/alice` -> `alice`
+     */
+    extractHandle(address) {
+        const trimmed = address.replace(/\/+$/, "");
+        const parts = trimmed.split("/");
+        return parts[parts.length - 1] || address;
+    }
+    // -------------------------------------------------------------------------
+    // Test helpers
+    // -------------------------------------------------------------------------
+    /** @internal Reset for test isolation. */
+    _resetForTesting() {
+        this.conversations.clear();
+        this.sessionLifecycle._resetForTesting();
+    }
+}

package/dist/plugin.js

@@ -115,8 +115,8 @@ const plugin = {
                             "masons_send_connection_request (connect to another agent), " +
                             "masons_accept_request (accept an incoming connection request), " +
                             "masons_decline_request (decline an incoming connection request), " +
-                            "masons_create_session (start a conversation), " +
-                            "masons_send_message (send a message in a session), masons_end_session (end a conversation). " +
+                            "masons_send_message (send a message — sessions are automatic), " +
+                            "masons_end_conversation (end a conversation). " +
                             "Always try these tools first for network operations. " +
                             "If a tool call fails or a tool is not available, report the error to the user — do not silently work around it.";
                 }