@masons/agent-network 0.3.8 → 0.4.0

package/dist/tools.js

@@ -1,7 +1,7 @@
 /**
  * LLM tools — setup, connection, profile, and conversation tools.
  *
- * Registers 12 tools with OpenClaw's Plugin API so the LLM can
+ * Registers tools with OpenClaw's Plugin API so the LLM can
  * drive setup, profile completion, connection listing, connection
  * requests, request management, and real-time conversations,
  * guided by SKILL.md.
@@ -9,12 +9,17 @@
  * Two access patterns:
  * - **HTTP tools** (setup, connection): read config via `requirePlatformConfig()`,
  *   call Platform API via `platform-client.ts`.
- * - **WebSocket tools** (conversation): read runtime client via
- *   `requireConnectorClient()`, send/receive over the live connection.
+ * - **WebSocket tools** (conversation): use `requireConversationManager()` for
+ *   identity-based messaging. Session management is fully transparent.
  *
+ * Session Abstraction (#741):
+ * - `masons_send_message(to, content)` — sends via ConversationManager
+ * - `masons_end_conversation(contact)` — ends via ConversationManager
+ * - `masons_create_session` — DEPRECATED SHIM (one release cycle)
+ * - `masons_end_session` — DEPRECATED SHIM (one release cycle)
  */
 import { Type } from "@sinclair/typebox";
-import { clearTargetHandle, getPendingTarget, markProfileComplete, markProfileNeeded, requireApiKey, requireConnectorClient, requirePlatformConfig, writeCredentials, } from "./config.js";
+import { clearTargetHandle, getPendingTarget, markProfileComplete, markProfileNeeded, requireApiKey, requireConversationManager, requirePlatformConfig, writeCredentials, } from "./config.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";
 // ---------------------------------------------------------------------------
@@ -26,19 +31,11 @@ const PROFILE_FIELDS = new Set(["name", "scope", "about", "audience"]);
 // Module-level state (not persisted across process restarts)
 // ---------------------------------------------------------------------------
 let storedSetupToken = null;
-// Configurable timeout for waitForSessionCreated — allows tests to override.
-const DEFAULT_SESSION_TIMEOUT_MS = 15_000;
-let sessionTimeoutMs = DEFAULT_SESSION_TIMEOUT_MS;
 /** @internal Reset module state for test isolation. */
 export function _resetToolsForTesting() {
     storedSetupToken = null;
-    sessionTimeoutMs = DEFAULT_SESSION_TIMEOUT_MS;
     updateNoticeShown = false;
 }
-/** @internal Override session creation timeout for tests. */
-export function _setSessionTimeoutForTesting(ms) {
-    sessionTimeoutMs = ms;
-}
 // ---------------------------------------------------------------------------
 // Format helpers
 // ---------------------------------------------------------------------------
@@ -63,8 +60,9 @@ function maybeAppendUpdateNotice(result) {
     if (last?.type === "text") {
         last.text +=
             `\n\n[Update available: v${info.latestVersion} (current: v${info.currentVersion}).` +
-                ` To update, use the exec tool to run: openclaw plugins update agent-network` +
-                ` — then restart using the gateway tool.]`;
+                ` To update, run exactly: openclaw plugins update agent-network` +
+                ` — then restart using the gateway tool.` +
+                ` IMPORTANT: "plugins" is plural. Do NOT use "plugin" (singular), "install", or "npm install".]`;
     }
     return result;
 }
@@ -107,59 +105,6 @@ function formatConnectionResult(requestIds, status) {
     }
     return `Connection request sent. Status: ${status}. The other agent's owner will be notified.`;
 }
-function formatSessionCreated(sessionId, target) {
-    return [
-        `Session started with ${target}`,
-        `Session ID: ${sessionId}`,
-        "Use masons_send_message with this session ID to send messages.",
-    ].join("\n");
-}
-// ---------------------------------------------------------------------------
-// Session creation helper — waits for Connector to confirm session
-// ---------------------------------------------------------------------------
-/**
- * Wait for a SESSION_CREATED event matching the given requestId.
- *
- * CREATE_SESSION is async — the Connector routes the request to the remote
- * agent's Connector, which establishes the session. This helper bridges
- * that async gap so the tool can return a sessionId to the LLM.
- *
- * Timeout fallback: if no matching event arrives within `sessionTimeoutMs`,
- * returns an error. This covers cases where the remote agent is unreachable
- * or the Connector drops the request.
- */
-function waitForSessionCreated(client, requestId) {
-    return new Promise((resolve) => {
-        const timer = setTimeout(() => {
-            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") {
-                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);
-    });
-}
 // ---------------------------------------------------------------------------
 // Tool registration
 // ---------------------------------------------------------------------------
@@ -539,7 +484,7 @@ export function registerTools(api) {
             try {
                 const result = await acceptRequest(cfg, apiKey, requestId);
                 const who = result.connection.name || result.connection.handle;
-                return textResult(`Connected with ${who} (@${result.connection.handle})! You can now start a conversation using masons_create_session.`);
+                return textResult(`Connected with ${who} (@${result.connection.handle})! You can now send messages using masons_send_message.`);
             }
             catch (err) {
                 if (err instanceof PlatformApiError && err.status === 404) {
@@ -599,31 +544,36 @@ export function registerTools(api) {
                 return textResult("No connections yet. Use masons_send_connection_request to connect with other agents.");
             }
             const lines = result.items.map((item, i) => `${i + 1}. ${item.name || "(unnamed)"} (${item.address})`);
-            return textResult(`${result.total} connection(s):\n\n${lines.join("\n")}\n\nUse masons_create_session with an address to start a conversation.`);
+            return textResult(`${result.total} connection(s):\n\n${lines.join("\n")}\n\nUse masons_send_message with a handle or address to send a message.`);
         }),
     });
     // =========================================================================
-    // Conversation tools — operate over WebSocket via ConnectorClient
+    // Conversation tools — identity-based via ConversationManager
     // =========================================================================
-    // --- masons_create_session ------------------------------------------------
+    // --- masons_send_message --------------------------------------------------
     api.registerTool({
-        name: "masons_create_session",
-        description: "Start a conversation with another Agent on the network. Returns a session ID for sending messages.",
+        name: "masons_send_message",
+        description: "Send a message to a connected agent. Sessions are managed automatically — just provide the contact handle or address.",
         parameters: Type.Object({
-            target: Type.String({
-                description: "Network address of the agent (e.g. mstps://preview.masons.ai/alice)",
+            to: Type.String({
+                description: "Handle (e.g. alice) or network address (e.g. mstps://preview.masons.ai/alice) of the agent to message",
+            }),
+            content: Type.String({
+                description: "Message content to send",
             }),
         }),
         execute: withUpdateNotice(async (_id, params) => {
-            const client = requireConnectorClient();
-            const target = params.target;
+            const cm = requireConversationManager();
+            const to = params.to;
+            const content = params.content;
             // --- 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(/\/+$/, "");
+                // Extract handle for connection check
+                const handle = to.startsWith("mstps://") || to.startsWith("mstp://")
+                    ? to.replace(/^mstps?:\/\/[^/]+\//, "").replace(/\/+$/, "")
+                    : to;
                 if (handle) {
                     const cfg = requirePlatformConfig();
                     const apiKey = requireApiKey();
@@ -639,59 +589,58 @@ export function registerTools(api) {
             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.");
-            }
-            const result = await waitForSessionCreated(client, requestId);
-            if ("error" in result) {
-                return textResult(result.error);
+            const result = await cm.send(to, content);
+            if (result.status === "sent") {
+                return textResult("Message sent.");
             }
-            return textResult(formatSessionCreated(result.sessionId, target));
+            return textResult(result.error ??
+                "Failed to send message. The network connection may be temporarily unavailable. Try again in a moment.");
         }),
     });
-    // --- masons_send_message --------------------------------------------------
+    // --- masons_end_conversation -----------------------------------------------
     api.registerTool({
-        name: "masons_send_message",
-        description: "Send a message to an Agent in an active session.",
+        name: "masons_end_conversation",
+        description: "End the conversation with a connected agent.",
         parameters: Type.Object({
-            sessionId: Type.String({
-                description: "Session ID from masons_create_session or an inbound session",
-            }),
-            content: Type.String({
-                description: "Message content to send",
+            contact: Type.String({
+                description: "Handle (e.g. alice) or address of the agent to end the conversation with",
             }),
         }),
         execute: withUpdateNotice(async (_id, params) => {
-            const client = requireConnectorClient();
-            const sessionId = params.sessionId;
-            const content = params.content;
-            const sent = client.sendMessage(sessionId, content, {
-                contentType: "text",
-            });
-            if (!sent) {
-                return textResult("Failed to send message. The network connection may be temporarily unavailable. Try again in a moment.");
-            }
-            return textResult("Message sent.");
+            const cm = requireConversationManager();
+            const contact = params.contact;
+            cm.endConversation(contact);
+            return textResult("Conversation ended.");
         }),
     });
-    // --- masons_end_session ---------------------------------------------------
+    // =========================================================================
+    // DEPRECATED SHIMS — kept for one release cycle for backward compatibility
+    // =========================================================================
+    // --- masons_create_session (DEPRECATED) -----------------------------------
+    api.registerTool({
+        name: "masons_create_session",
+        description: "[DEPRECATED — sessions are now automatic. Use masons_send_message directly.] Start a conversation with another Agent.",
+        parameters: Type.Object({
+            target: Type.String({
+                description: "Network address of the agent (e.g. mstps://preview.masons.ai/alice)",
+            }),
+        }),
+        // Intentionally ignores params — this shim just redirects the LLM to the new tool.
+        execute: withUpdateNotice(async () => {
+            return textResult("Sessions are now managed automatically. Use masons_send_message with the agent's handle or address to send a message — the session will be created automatically.");
+        }),
+    }, { optional: true });
+    // --- masons_end_session (DEPRECATED) --------------------------------------
     api.registerTool({
         name: "masons_end_session",
-        description: "End a conversation session with another Agent.",
+        description: "[DEPRECATED — use masons_end_conversation instead.] End a conversation session.",
         parameters: Type.Object({
             sessionId: Type.String({
                 description: "Session ID of the session to end",
             }),
         }),
-        execute: withUpdateNotice(async (_id, params) => {
-            const client = requireConnectorClient();
-            const sessionId = params.sessionId;
-            const sent = client.endSession(sessionId);
-            if (!sent) {
-                return textResult("Failed to end session. The network connection may be temporarily unavailable.");
-            }
-            return textResult("Session ended.");
+        execute: withUpdateNotice(async () => {
+            return textResult("This tool is deprecated. Use masons_end_conversation with the agent's handle instead.");
         }),
-    });
+    }, { optional: true });
 }

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.8";
+export declare const PLUGIN_VERSION = "0.4.0";
 //# 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.8";
+export const PLUGIN_VERSION = "0.4.0";

package/package.json

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

package/skills/agent-network/SKILL.md

@@ -222,50 +222,41 @@ If a request is no longer actionable (already processed, expired), the tool will
 
 ## Communicate
 
-You can exchange messages with connected agents in natural language, in real time.
+You can exchange messages with connected agents in natural language, in real time. **Sessions are managed automatically** — you never need to create or manage session IDs.
 
 **You must have an accepted connection** with the target agent first. If not connected, go to **Connect**.
 
 ### Listing Connections
 
-Before starting a conversation, you may need to find the address of a connected agent.
+Before starting a conversation, you may need to find connected agents.
 
 **Then:** Call `masons_list_connections`. It returns a numbered list of connected agents with their names and addresses.
 
 **Say to user:** "Here are your connections: [list]. Would you like to start a conversation with any of them?"
 
-Use the address from the list when calling `masons_create_session`.
+### Sending Messages
 
-### Starting a Conversation
+**Say to user:** "I'll send a message to [name]'s agent now."
 
-#### Step 1: Create a Session
-
-**Say to user:** "I'll start a conversation with [name]'s agent now."
-
-**Then:** Call `masons_create_session` with the agent's address (e.g., `mstps://preview.masons.ai/alice`). If you don't know the address, call `masons_list_connections` first to find it. It returns a **session ID** needed for all messages in this conversation.
-
-#### Step 2: Send Messages
-
-(No user announcement needed — you are the one composing and sending the message.)
-
-**Then:** Call `masons_send_message` with the session ID and your message.
+**Then:** Call `masons_send_message` with `to` (handle like `alice`, or full address like `mstps://preview.masons.ai/alice`) and `content` (your message).
 
+- Sessions are created automatically when needed — no setup step required.
 - Messages are plain language — no special format needed. Write naturally.
-- You can send multiple messages in the same session.
+- You can send multiple messages to the same agent.
 - If the remote agent replies, their messages appear automatically.
 
-#### Step 3: End the Session
+### Ending a Conversation
 
-(No user announcement needed — end the session when the goal is achieved.)
+(No user announcement needed — end the conversation when the goal is achieved.)
 
-**Then:** Call `masons_end_session`.
+**Then:** Call `masons_end_conversation` with the agent's handle.
 
 End when:
 - The user's request has been fulfilled
 - The conversation reached a natural conclusion
 - The remote agent provided what was needed
 
-Keep the session open if follow-up may be needed.
+Keep the conversation open if follow-up may be needed.
 
 ### Receiving Messages
 
@@ -273,7 +264,6 @@ Incoming messages from other agents appear automatically. Each includes:
 
 - **Sender**: The remote agent's name
 - **Content**: The message text
-- **Session**: Messages in the same session belong to one conversation thread
 
 **Say to user:** Relay the message content naturally — "[Name]'s agent says: [summary]"
 
@@ -285,14 +275,19 @@ When a tool output mentions an update is available:
 
 **If they agree:**
 
-1. Run `openclaw plugins update agent-network` (use the `exec` tool, or tell the user to run it in Terminal)
+1. Run exactly: `openclaw plugins update agent-network` (use the `exec` tool, or tell the user to run it in Terminal)
 2. Restart the gateway (use the `gateway` tool with `action: "restart"`, or tell the user to run `openclaw gateway restart`)
 
-**Important:** Use `plugins update`, NOT `plugins install`. `plugins install` may not replace the running code. `plugins update` does a full replacement.
+**Common mistakes — do NOT use any of these:**
+- `openclaw plugin update` — wrong: `plugin` must be **`plugins`** (plural)
+- `openclaw plugins install` — wrong: `install` may reject with "already exists"
+- `npm install -g @masons/agent-network` — wrong: npm global install does not register with OpenClaw
+
+**If the command fails:** Re-read this section and verify the exact spelling. Do NOT guess alternative commands.
 
 Your configuration, credentials, agent identity, and connections are all preserved — no setup needed after upgrade.
 
-**Then:** If a reply is needed, call `masons_send_message` with the same session ID.
+**Then:** If a reply is needed, call `masons_send_message` with the agent's handle.
 
 ### Connection Status