@masons/agent-network 0.3.9 → 0.4.1

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,35 +9,48 @@
  * 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, getOpenClawHome, 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";
+import { fetchLatestVersion, getPluginVersion, getUpdateInfo, } from "./update-check.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 /** Accepted field names for masons_update_profile — reject anything else. */
 const PROFILE_FIELDS = new Set(["name", "scope", "about", "audience"]);
+/** CLI command to update the plugin via OpenClaw. */
+const UPGRADE_CMD = "openclaw plugins update agent-network";
+/** Fallback: remove + fresh install. `{version}` is replaced at runtime. */
+const FALLBACK_UPGRADE_CMD = "rm -rf {home}/extensions/agent-network && openclaw plugins install @masons/agent-network@{version}";
+/** CLI command to restart the gateway. */
+const GATEWAY_RESTART_CMD = "openclaw gateway restart";
+/** Simple semver regex — validates x.y.z before inserting into shell commands. */
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
 // ---------------------------------------------------------------------------
 // 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;
+/**
+ * Tracks the version we already tried to upgrade to this session.
+ * null = no attempt yet. Set to the target version string on the first
+ * normal-path attempt. If the tool is called again while current version
+ * still differs, the fallback path is returned instead.
+ */
+let upgradeAttemptedVersion = null;
 /** @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;
+    upgradeAttemptedVersion = null;
 }
 // ---------------------------------------------------------------------------
 // Format helpers
@@ -63,9 +76,7 @@ function maybeAppendUpdateNotice(result) {
     if (last?.type === "text") {
         last.text +=
             `\n\n[Update available: v${info.latestVersion} (current: v${info.currentVersion}).` +
-                ` 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".]`;
+                ` Call \`masons_upgrade\` to update.]`;
     }
     return result;
 }
@@ -108,59 +119,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
 // ---------------------------------------------------------------------------
@@ -540,7 +498,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) {
@@ -600,31 +558,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();
@@ -640,59 +603,130 @@ 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 cm.send(to, content);
+            if (result.status === "sent") {
+                return textResult("Message sent.");
             }
-            const result = await waitForSessionCreated(client, requestId);
-            if ("error" in result) {
-                return textResult(result.error);
-            }
-            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 ---------------------------------------------------
+    // --- masons_upgrade -------------------------------------------------------
+    api.registerTool({
+        name: "masons_upgrade",
+        description: "Check for plugin updates and get upgrade instructions. Returns the exact command to run.",
+        parameters: Type.Object({}),
+        // NOT wrapped with withUpdateNotice — this tool IS the upgrade path.
+        // Wrapping would create a circular reference in the update notice text.
+        execute: async () => {
+            const currentVersion = getPluginVersion();
+            // 1. Determine latest version.
+            //    Normal path: use cached getUpdateInfo() (populated at startup).
+            //    Fallback path (upgradeAttemptedVersion set): bypass cache, fetch directly.
+            let latestVersion = null;
+            if (upgradeAttemptedVersion !== null) {
+                // Previous attempt didn't succeed — fetch directly to bypass stale cache.
+                latestVersion = await fetchLatestVersion();
+            }
+            else {
+                const info = getUpdateInfo();
+                if (info) {
+                    latestVersion = info.latestVersion;
+                }
+                else {
+                    // No cached info (startup check didn't run or failed) — fetch directly.
+                    latestVersion = await fetchLatestVersion();
+                }
+            }
+            // 2. Network error — can't determine latest version.
+            if (!latestVersion) {
+                return textResult("Could not check for updates (network issue). Try again later.");
+            }
+            // 3. Already up to date.
+            if (latestVersion === currentVersion) {
+                upgradeAttemptedVersion = null; // Reset on success
+                return textResult(`You're on the latest version (v${currentVersion}). No update needed.`);
+            }
+            // 4. Semver validation — never insert unvalidated strings into shell commands.
+            if (!SEMVER_RE.test(latestVersion)) {
+                return textResult(`Registry returned an unexpected version format: "${latestVersion}". Try again later.`);
+            }
+            // 5. Determine path: normal vs fallback.
+            const useFallback = upgradeAttemptedVersion === latestVersion;
+            if (useFallback) {
+                // Fallback path — previous normal-path attempt for this version didn't work.
+                upgradeAttemptedVersion = null; // Reset so next call starts fresh
+                const home = getOpenClawHome();
+                const fallbackCmd = FALLBACK_UPGRADE_CMD.replace("{home}", home).replace("{version}", latestVersion);
+                return textResult([
+                    `Update to v${latestVersion} — using alternative method (previous attempt may have failed).`,
+                    "",
+                    "Run this command using the exec tool:",
+                    fallbackCmd,
+                    "",
+                    `Then restart the gateway using the gateway tool.`,
+                    `If you cannot run commands, tell the user to run in Terminal:`,
+                    `${fallbackCmd} && ${GATEWAY_RESTART_CMD}`,
+                ].join("\n"));
+            }
+            // Normal path — first attempt for this version.
+            upgradeAttemptedVersion = latestVersion;
+            return textResult([
+                `Update available: v${currentVersion} → v${latestVersion}`,
+                "",
+                "Run this command using the exec tool:",
+                UPGRADE_CMD,
+                "",
+                "Then restart the gateway using the gateway tool.",
+                "If you cannot run commands, tell the user to run in Terminal:",
+                `${UPGRADE_CMD} && ${GATEWAY_RESTART_CMD}`,
+            ].join("\n"));
+        },
+    });
+    // =========================================================================
+    // 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.9";
+export declare const PLUGIN_VERSION = "0.4.1";
 //# 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.9";
+export const PLUGIN_VERSION = "0.4.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masons/agent-network",
-  "version": "0.3.9",
+  "version": "0.4.1",
   "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]"
 
@@ -281,23 +271,9 @@ Incoming messages from other agents appear automatically. Each includes:
 
 When a tool output mentions an update is available:
 
-**Say to user:** "A newer version of the agent network plugin is available (v[new] → v[current]). Want me to update?"
-
-**If they agree:**
-
-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`)
-
-**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.
+**Say to user:** "A newer version of the agent network plugin is available. Want me to update?"
 
-**Then:** If a reply is needed, call `masons_send_message` with the same session ID.
+**If they agree:** Call `masons_upgrade` and follow its instructions. It will tell you exactly what to run.
 
 ### Connection Status
 

package/skills/agent-network/references/maintenance.md

@@ -41,17 +41,10 @@ The user's agent identity, handle, and connections are preserved on the server
 
 ## Upgrade
 
-To update the plugin to a newer version:
-
-1. Use the `exec` tool to run: `openclaw plugins update agent-network`
-2. Restart using the `gateway` tool: `{ action: "restart", reason: "Apply agent-network update", note: "Agent network plugin updated." }`
-3. **Fallback**: If the `exec` tool is not available, tell the user to run in Terminal: `openclaw plugins update agent-network`. Then restart using the `gateway` tool.
-4. **Double fallback**: If neither `exec` nor `gateway` tool is available, tell the user to run in Terminal: `openclaw plugins update agent-network && openclaw gateway restart`
+Call `masons_upgrade` — it checks for updates and returns the exact command to run. Follow its instructions.
 
 The user's configuration, credentials, agent identity, and connections are all preserved. No setup needed — the new version picks up where the old one left off.
 
-Note: Use `plugins update` (with plugin ID `agent-network`), not `plugins install` (which may reject with "already exists").
-
 ## Reinstall
 
 To reinstall after a previous uninstall: