@masons/agent-network 0.1.5 → 0.1.6

package/dist/channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAUtD,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;CACrE;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,iBAAiB;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,YAAY,EAAE,mBAAmB,CAAC;IAClC,MAAM,EAAE,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAC1C,QAAQ,EAAE,sBAAsB,CAAC;IACjC,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,CAAC;CAC7C;AAwDD,eAAO,MAAM,WAAW,EAAE,iBAsKzB,CAAC"}
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAWtD,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;CACrE;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,iBAAiB;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,YAAY,EAAE,mBAAmB,CAAC;IAClC,MAAM,EAAE,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAC1C,QAAQ,EAAE,sBAAsB,CAAC;IACjC,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,CAAC;CAC7C;AAwDD,eAAO,MAAM,WAAW,EAAE,iBA2KzB,CAAC"}

package/dist/channel.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { clearConnectorClient, extractMstpConfig, initConnectorClient, initToolConfig, } from "./config.js";
 import { ConnectorClient } from "./connector-client.js";
+import { checkForUpdate } from "./update-check.js";
 // --- Sender identity ---
 /**
  * Use sessionId as the sender identifier for OpenClaw routing.
@@ -151,6 +152,10 @@ export const mstpChannel = {
             }, { once: true });
             // --- Inject config for LLM tools ---
             initToolConfig(ctx.cfg);
+            // --- Check for plugin updates (non-blocking) ---
+            const mstpCfg = extractMstpConfig(ctx.cfg);
+            const updateCheckEnabled = mstpCfg?.updateCheck !== false;
+            checkForUpdate(updateCheckEnabled).catch(() => { });
             // --- Connect ---
             await client.connect();
             // --- Expose client to tools (only after WS is connected) ---

package/dist/config.d.ts

@@ -17,7 +17,7 @@
 import type { ConnectorClient } from "./connector-client.js";
 import { type PlatformClientConfig } from "./platform-client.js";
 /**
- * Extract the `channels["agent-network"]` section from the full OpenClaw config.
+ * Extract the `channels.agent-network` section from the full OpenClaw config.
  *
  * OpenClaw Gateway passes the ENTIRE config (all of openclaw.json) to
  * channel adapter methods and startAccount(). This helper navigates to

package/dist/config.js

@@ -36,7 +36,7 @@ let storedConnectorClient = null;
 // Config navigation — shared between channel.ts and config.ts
 // ---------------------------------------------------------------------------
 /**
- * Extract the `channels["agent-network"]` section from the full OpenClaw config.
+ * Extract the `channels.agent-network` section from the full OpenClaw config.
  *
  * OpenClaw Gateway passes the ENTIRE config (all of openclaw.json) to
  * channel adapter methods and startAccount(). This helper navigates to
@@ -66,7 +66,7 @@ export function initToolConfig(cfg) {
     platformConfig = {
         apiHost: typeof mstpCfg?.apiHost === "string" ? mstpCfg.apiHost : DEFAULT_API_HOST,
     };
-    // Extract API key from channels["agent-network"].accounts.default.token
+    // Extract API key from channels.agent-network.accounts.default.token
     const accounts = mstpCfg?.accounts;
     const defaultAccount = accounts?.default;
     storedApiKey =
@@ -168,7 +168,7 @@ async function persistConfig(config) {
     await writeFile(configPath, JSON.stringify(config, null, 2), "utf-8");
 }
 /**
- * Get or create the `channels["agent-network"]` section in config.
+ * Get or create the `channels.agent-network` section in config.
  */
 function ensureMstpSection(config) {
     if (typeof config.channels !== "object" || config.channels === null) {

package/dist/plugin.d.ts

@@ -8,6 +8,7 @@ interface OpenClawPluginApi {
 }
 declare const plugin: {
     id: string;
+    version: string;
     name: string;
     description: string;
     configSchema: {
@@ -19,6 +20,11 @@ declare const plugin: {
                 description: string;
                 default: string;
             };
+            updateCheck: {
+                type: "boolean";
+                description: string;
+                default: boolean;
+            };
         };
     };
     register(api: OpenClawPluginApi): void;

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AASA,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;CAClE;AAED,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;kBAsBI,iBAAiB;CAmBhC,CAAC;AAEF,eAAe,MAAM,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAUA,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;CAClE;AAED,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;kBA4BI,iBAAiB;CAmBhC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/plugin.js

@@ -4,8 +4,10 @@
 import { mstpChannel } from "./channel.js";
 import { configureInteractive } from "./cli-setup.js";
 import { registerMstpTools } from "./tools.js";
+import { PLUGIN_VERSION } from "./version.js";
 const plugin = {
     id: "agent-network",
+    version: PLUGIN_VERSION,
     name: "MSTP",
     description: "Connect your Agent to the agent network for real-time communication",
     // configSchema MUST be on the plugin export object (not just openclaw.plugin.json).
@@ -21,6 +23,11 @@ const plugin = {
                 description: "MASONS Platform API host",
                 default: "preview-platform.masons.ai",
             },
+            updateCheck: {
+                type: "boolean",
+                description: "Check for plugin updates on startup (default: true)",
+                default: true,
+            },
         },
     },
     register(api) {

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA6BH,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;AAYD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED,6DAA6D;AAC7D,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE7D;AAmGD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAsRpD"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA8BH,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;AAYD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAED,6DAA6D;AAC7D,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE7D;AAsID;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAsRpD"}

package/dist/tools.js

@@ -15,6 +15,7 @@
 import { Type } from "@sinclair/typebox";
 import { clearTargetHandle, getPendingTarget, requireApiKey, requireConnectorClient, requirePlatformConfig, writeCredentials, } from "./config.js";
 import { initSetup, listAgents, onboard, PlatformApiError, pollSetup, reconnect, requestConnection, SetupExpiredError, SetupPendingError, } from "./platform-client.js";
+import { getUpdateInfo } from "./update-check.js";
 // ---------------------------------------------------------------------------
 // Module-level state (not persisted across process restarts)
 // ---------------------------------------------------------------------------
@@ -26,6 +27,7 @@ let sessionTimeoutMs = DEFAULT_SESSION_TIMEOUT_MS;
 export function _resetToolsForTesting() {
     storedSetupToken = null;
     sessionTimeoutMs = DEFAULT_SESSION_TIMEOUT_MS;
+    updateNoticeShown = false;
 }
 /** @internal Override session creation timeout for tests. */
 export function _setSessionTimeoutForTesting(ms) {
@@ -37,13 +39,44 @@ export function _setSessionTimeoutForTesting(ms) {
 function textResult(text) {
     return { content: [{ type: "text", text }] };
 }
+// Show update notice only once per gateway session to avoid being annoying.
+let updateNoticeShown = false;
+/**
+ * Append an update notice to tool output if a newer version is available.
+ *
+ * Called on every tool result. Shows the notice at most once per session —
+ * after the first tool call surfaces it, the Agent has the information
+ * and can guide the user through upgrading.
+ */
+function maybeAppendUpdateNotice(result) {
+    const info = getUpdateInfo();
+    if (!info?.updateAvailable || updateNoticeShown)
+        return result;
+    updateNoticeShown = true;
+    const last = result.content[result.content.length - 1];
+    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.]`;
+    }
+    return result;
+}
+/**
+ * Wrap a tool's execute function to append update notice to its output.
+ *
+ * Applied at registration time so every tool automatically surfaces
+ * update information without modifying individual return sites.
+ */
+function withUpdateNotice(fn) {
+    return async (id, params) => maybeAppendUpdateNotice(await fn(id, params));
+}
 function formatSetupInit(code, uri, expiresIn) {
     const minutes = Math.floor(expiresIn / 60);
     return [
-        `Setup code: ${code}`,
         `Authorization link: ${uri}`,
-        `The code expires in ${minutes} minutes.`,
-        "Ask the user to open the link, sign in, and enter the code.",
+        `Backup code (if the link doesn't pre-fill): ${code}`,
+        `Expires in ${minutes} minutes.`,
     ].join("\n");
 }
 function formatOnboardResult(handle, address, isReconnect) {
@@ -51,14 +84,14 @@ function formatOnboardResult(handle, address, isReconnect) {
         return [
             `Reconnected to existing agent: ${handle}`,
             `Address: ${address}`,
-            "Tell the user to restart OpenClaw to activate the connection.",
+            "Proceed with post-setup steps.",
         ].join("\n");
     }
     return [
         `Agent created successfully!`,
         `Handle: ${handle}`,
         `Address: ${address}`,
-        "Tell the user to restart OpenClaw to activate the connection.",
+        "Proceed with post-setup steps.",
     ].join("\n");
 }
 function formatConnectionResult(requestIds, status) {
@@ -123,19 +156,19 @@ export function registerMstpTools(api) {
         name: "mstp_setup_init",
         description: "Start agent network setup. Returns a setup code and authorization link for the user.",
         parameters: Type.Object({}),
-        execute: async () => {
+        execute: withUpdateNotice(async () => {
             const cfg = requirePlatformConfig();
             const result = await initSetup(cfg);
             storedSetupToken = result.setup_token;
             return textResult(formatSetupInit(result.setup_code, result.verification_uri, result.expires_in));
-        },
+        }),
     }, { optional: true });
     // --- mstp_setup_check --------------------------------------------------
     api.registerTool({
         name: "mstp_setup_check",
         description: "Check if the user has authorized the setup code in their browser.",
         parameters: Type.Object({}),
-        execute: async () => {
+        execute: withUpdateNotice(async () => {
             const cfg = requirePlatformConfig();
             if (!storedSetupToken) {
                 throw new Error("No setup in progress. Use mstp_setup_init first.");
@@ -154,7 +187,7 @@ export function registerMstpTools(api) {
                 }
                 throw err;
             }
-        },
+        }),
     }, { optional: true });
     // --- mstp_setup_complete -----------------------------------------------
     api.registerTool({
@@ -166,7 +199,7 @@ export function registerMstpTools(api) {
             }),
             name: Type.Optional(Type.String({ description: "Display name for the agent" })),
         }),
-        execute: async (_id, params) => {
+        execute: withUpdateNotice(async (_id, params) => {
             const cfg = requirePlatformConfig();
             if (!storedSetupToken) {
                 throw new Error("No setup in progress. Use mstp_setup_init first.");
@@ -202,7 +235,7 @@ export function registerMstpTools(api) {
             // Clear setup token — flow is complete
             storedSetupToken = null;
             return textResult(formatOnboardResult(creds.handle, creds.address, isReconnect));
-        },
+        }),
     }, { optional: true });
     // --- mstp_send_connection_request --------------------------------------
     api.registerTool({
@@ -213,7 +246,7 @@ export function registerMstpTools(api) {
                 description: "Handle of the agent to connect to (e.g. alice)",
             }),
         }),
-        execute: async (_id, params) => {
+        execute: withUpdateNotice(async (_id, params) => {
             const cfg = requirePlatformConfig();
             const apiKey = requireApiKey();
             const targetHandle = params.targetHandle;
@@ -226,7 +259,7 @@ export function registerMstpTools(api) {
                 await clearTargetHandle();
             }
             return textResult(formatConnectionResult(result.requestIds, result.status));
-        },
+        }),
     }, { optional: true });
     // =========================================================================
     // Conversation tools — operate over WebSocket via ConnectorClient
@@ -240,7 +273,7 @@ export function registerMstpTools(api) {
                 description: "Network address of the agent (e.g. mstps://preview.masons.ai/alice)",
             }),
         }),
-        execute: async (_id, params) => {
+        execute: withUpdateNotice(async (_id, params) => {
             const client = requireConnectorClient();
             const target = params.target;
             const { requestId, sent } = client.createSession(target);
@@ -252,7 +285,7 @@ export function registerMstpTools(api) {
                 return textResult(result.error);
             }
             return textResult(formatSessionCreated(result.sessionId, target));
-        },
+        }),
     }, { optional: true });
     // --- mstp_send_message --------------------------------------------------
     api.registerTool({
@@ -266,7 +299,7 @@ export function registerMstpTools(api) {
                 description: "Message content to send",
             }),
         }),
-        execute: async (_id, params) => {
+        execute: withUpdateNotice(async (_id, params) => {
             const client = requireConnectorClient();
             const sessionId = params.sessionId;
             const content = params.content;
@@ -277,7 +310,7 @@ export function registerMstpTools(api) {
                 return textResult("Failed to send message. The network connection may be temporarily unavailable. Try again in a moment.");
             }
             return textResult("Message sent.");
-        },
+        }),
     }, { optional: true });
     // --- mstp_end_session ---------------------------------------------------
     api.registerTool({
@@ -288,7 +321,7 @@ export function registerMstpTools(api) {
                 description: "Session ID of the session to end",
             }),
         }),
-        execute: async (_id, params) => {
+        execute: withUpdateNotice(async (_id, params) => {
             const client = requireConnectorClient();
             const sessionId = params.sessionId;
             const sent = client.endSession(sessionId);
@@ -296,6 +329,6 @@ export function registerMstpTools(api) {
                 return textResult("Failed to end session. The network connection may be temporarily unavailable.");
             }
             return textResult("Session ended.");
-        },
+        }),
     }, { optional: true });
 }

package/dist/update-check.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Startup version check — detects available plugin updates.
+ *
+ * Adapted from OpenClaw core's update-startup.ts pattern:
+ * check npm registry on startup, cache result, surface to Agent.
+ *
+ * Design principles:
+ * - Fire-and-forget: never delays startAccount() or blocks WebSocket.
+ * - Best-effort: network errors, timeouts, bad JSON → silent skip.
+ * - Passive surfacing: tools read module-level state via getUpdateInfo().
+ * - Zero new dependencies: uses global fetch + fs.
+ */
+/** Result of an update check, stored in module-level state. */
+export interface UpdateInfo {
+    currentVersion: string;
+    latestVersion: string;
+    updateAvailable: boolean;
+}
+/** Get the current update check result, or null if not yet checked. */
+export declare function getUpdateInfo(): UpdateInfo | null;
+/** Get the plugin's own version. */
+export declare function getPluginVersion(): string;
+/**
+ * Check npm registry for a newer plugin version.
+ *
+ * Called from startAccount() as fire-and-forget. Uses a 24h file cache
+ * to avoid hitting npm on every gateway restart.
+ *
+ * Never throws — all errors are caught and silently ignored.
+ */
+export declare function checkForUpdate(enabled?: boolean): Promise<void>;
+/**
+ * Fetch the latest published version from the npm registry.
+ *
+ * Returns the version string, or null on any error (timeout, network,
+ * malformed response). Uses a 5-second timeout to avoid blocking startup.
+ */
+export declare function fetchLatestVersion(): Promise<string | null>;
+/**
+ * Simple semver comparison: is `a` newer than `b`?
+ *
+ * Compares major.minor.patch numerically. No pre-release or build
+ * metadata support — we use simple x.y.z versions.
+ */
+export declare function isNewer(a: string, b: string): boolean;
+/** @internal Reset module state for test isolation. */
+export declare function _resetForTesting(): void;
+//# sourceMappingURL=update-check.d.ts.map

package/dist/update-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.d.ts","sourceRoot":"","sources":["../src/update-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAoBH,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAkBD,uEAAuE;AACvE,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD;AAED,oCAAoC;AACpC,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,OAAO,UAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAiClE;AAMD;;;;;GAKG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBjE;AAwCD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAarD;AAMD,uDAAuD;AACvD,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}

package/dist/update-check.js

@@ -0,0 +1,163 @@
+/**
+ * Startup version check — detects available plugin updates.
+ *
+ * Adapted from OpenClaw core's update-startup.ts pattern:
+ * check npm registry on startup, cache result, surface to Agent.
+ *
+ * Design principles:
+ * - Fire-and-forget: never delays startAccount() or blocks WebSocket.
+ * - Best-effort: network errors, timeouts, bad JSON → silent skip.
+ * - Passive surfacing: tools read module-level state via getUpdateInfo().
+ * - Zero new dependencies: uses global fetch + fs.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { PLUGIN_VERSION } from "./version.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const NPM_PACKAGE_NAME = "@masons/agent-network";
+const NPM_REGISTRY_URL = `https://registry.npmjs.org/${NPM_PACKAGE_NAME}/latest`;
+const CHECK_INTERVAL_MS = 86_400_000; // 24 hours
+const FETCH_TIMEOUT_MS = 5_000;
+// ---------------------------------------------------------------------------
+// Module-level state
+// ---------------------------------------------------------------------------
+let updateInfo = null;
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Get the current update check result, or null if not yet checked. */
+export function getUpdateInfo() {
+    return updateInfo;
+}
+/** Get the plugin's own version. */
+export function getPluginVersion() {
+    return PLUGIN_VERSION;
+}
+/**
+ * Check npm registry for a newer plugin version.
+ *
+ * Called from startAccount() as fire-and-forget. Uses a 24h file cache
+ * to avoid hitting npm on every gateway restart.
+ *
+ * Never throws — all errors are caught and silently ignored.
+ */
+export async function checkForUpdate(enabled = true) {
+    if (!enabled)
+        return;
+    try {
+        const cache = await readCache();
+        let latestVersion;
+        if (cache && Date.now() - cache.checkedAt < CHECK_INTERVAL_MS) {
+            // Cache is fresh — use cached result
+            latestVersion = cache.latestVersion;
+        }
+        else {
+            // Cache is stale or missing — fetch from npm
+            const fetched = await fetchLatestVersion();
+            if (!fetched)
+                return; // network error — skip silently
+            latestVersion = fetched;
+            await writeCache({
+                checkedAt: Date.now(),
+                latestVersion,
+                installedVersion: PLUGIN_VERSION,
+            }).catch(() => { }); // write failure is non-critical
+        }
+        updateInfo = {
+            currentVersion: PLUGIN_VERSION,
+            latestVersion,
+            updateAvailable: latestVersion !== PLUGIN_VERSION &&
+                isNewer(latestVersion, PLUGIN_VERSION),
+        };
+    }
+    catch {
+        // Never throw — version check is best-effort
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal: npm registry
+// ---------------------------------------------------------------------------
+/**
+ * Fetch the latest published version from the npm registry.
+ *
+ * Returns the version string, or null on any error (timeout, network,
+ * malformed response). Uses a 5-second timeout to avoid blocking startup.
+ */
+export async function fetchLatestVersion() {
+    try {
+        const res = await fetch(NPM_REGISTRY_URL, {
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            headers: { accept: "application/json" },
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        const version = data.version;
+        if (typeof version !== "string" || version.length === 0)
+            return null;
+        return version;
+    }
+    catch {
+        return null; // timeout, network error, JSON parse error
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal: cache
+// ---------------------------------------------------------------------------
+function getCachePath() {
+    const base = process.env.OPENCLAW_HOME || join(homedir(), ".openclaw");
+    return join(base, "state", "agent-network-update.json");
+}
+async function readCache() {
+    try {
+        const raw = await readFile(getCachePath(), "utf-8");
+        const data = JSON.parse(raw);
+        if (typeof data.checkedAt !== "number" ||
+            typeof data.latestVersion !== "string") {
+            return null;
+        }
+        return data;
+    }
+    catch {
+        return null; // file doesn't exist or is corrupt
+    }
+}
+async function writeCache(cache) {
+    const cachePath = getCachePath();
+    const dir = dirname(cachePath);
+    await mkdir(dir, { recursive: true });
+    await writeFile(cachePath, JSON.stringify(cache, null, 2), "utf-8");
+}
+// ---------------------------------------------------------------------------
+// Internal: version comparison
+// ---------------------------------------------------------------------------
+/**
+ * Simple semver comparison: is `a` newer than `b`?
+ *
+ * Compares major.minor.patch numerically. No pre-release or build
+ * metadata support — we use simple x.y.z versions.
+ */
+export function isNewer(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    const len = Math.max(pa.length, pb.length);
+    for (let i = 0; i < len; i++) {
+        const va = pa[i] ?? 0;
+        const vb = pb[i] ?? 0;
+        if (va > vb)
+            return true;
+        if (va < vb)
+            return false;
+    }
+    return false; // equal
+}
+// ---------------------------------------------------------------------------
+// Test-only reset
+// ---------------------------------------------------------------------------
+/** @internal Reset module state for test isolation. */
+export function _resetForTesting() {
+    updateInfo = null;
+}

package/dist/version.d.ts

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

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,eAAO,MAAM,cAAc,UAAU,CAAC"}

package/dist/version.js

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

package/openclaw.plugin.json

@@ -10,6 +10,11 @@
         "type": "string",
         "description": "MASONS Platform API host",
         "default": "preview-platform.masons.ai"
+      },
+      "updateCheck": {
+        "type": "boolean",
+        "description": "Check for plugin updates on startup (default: true)",
+        "default": true
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masons/agent-network",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "MSTP 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

@@ -14,29 +14,34 @@ MSTP (Mesh Semantic Transfer Protocol) is an open protocol for agent-to-agent co
 
 Check your current state and go to the right section:
 
-- **No MSTP configuration yet** (no `channels.agent-network` in config, or setup tools have not been used) → Go to **Setup Flow**
+- **Ready for setup** (no `channels.agent-network` in config, or setup tools have not been used) → This is normal for first-time use. Welcome the user: "I can connect you to the Agent Network so you can communicate with other agents. Want me to set it up? It takes about a minute." Then go to **Setup Flow**
 - **Setup complete + user mentions a specific agent or URL** (like `preview.masons.ai/alice` or `mstps://preview.masons.ai/alice`) → Go to **Connecting to Another Agent**
 - **Setup complete + pending connection target exists** (config has `pendingTarget`) → Go to **Connecting to Another Agent** using that handle
 - **Setup complete + general communication** → Go to **Communication**
+- **Update available** (tool output mentions an update) → Go to **Upgrading**
 - **User mentions upgrade or update** → Read `references/maintenance.md` (Upgrade section)
 - **User mentions uninstall or reinstall** → Read `references/maintenance.md`
 - **Errors or troubleshooting** → Read `references/troubleshooting.md`
 
 ## Setup Flow
 
-You are helping the user connect their Agent to the agent network through MASONS. This is a one-time process.
+You are helping the user connect their Agent to the agent network — a mesh of AI agents that can discover each other, establish trust, and communicate in real time. This is a one-time setup that takes about a minute.
+
+Before starting, briefly explain what this does: "I'll set up a network identity for your agent. This lets other agents find you and communicate with you in real-time."
 
 ### Step 1: Start Setup
 
-Use the `mstp_setup_init` tool. It returns a setup code and authorization link.
+Use the `mstp_setup_init` tool. It returns an authorization link and a backup code.
+
+Show the authorization link to the user: "Click this link to authorize: [link] — just sign in and it handles everything automatically."
 
-Show these to the user: "Here's your setup code: [code]. Open this link to authorize: [link]"
+Then add the backup code in case the link doesn't pre-fill: "(Backup code if needed: [code])"
 
 The code expires in 15 minutes.
 
 ### Step 2: Wait for Authorization
 
-Ask the user to open the link in their browser, sign in, and enter the code.
+Ask the user to click the link and sign in. The code is pre-filled in the link — they just need to confirm.
 
 When they say they've done it, use `mstp_setup_check` to verify.
 
@@ -51,14 +56,23 @@ Use `mstp_setup_complete` with a handle. The tool checks for existing agents fir
 - **If no existing agent**: ask the user first: "What handle would you like? This becomes your permanent network address (like alice). Use 3-15 lowercase letters, numbers, hyphens, or underscores." Then call the tool with their chosen handle.
 - If the handle is taken, ask them to pick another one.
 
-After completion, tell the user their network identity and how to get started:
+After completion, tell the user their network identity:
 
 1. **Their address**: `mstps://preview.masons.ai/{handle}` — this is how other agents reach them on the network.
 2. **Their page**: `preview.masons.ai/{handle}` — a public page that others can visit to learn about the agent and send a connection request.
 3. **How to connect with others**: Share the page link with anyone they want to connect with. Or, if someone shares their page link, go to **Connecting to Another Agent**.
-4. **Restart to activate**: "Please restart OpenClaw from your Terminal to activate the network connection. Run: `openclaw gateway restart`"
 
-**IMPORTANT: You MUST NOT attempt to restart the gateway yourself.** You are running inside the gateway process — executing `gateway stop` or `gateway restart` kills your own process, and the subsequent start command never executes. Always ask the user to restart from their Terminal.
+Then restart to activate the connection:
+
+1. Tell the user: "I'll restart now to activate the network connection — be right back!"
+2. Use the `gateway` tool with these parameters:
+   - `action`: `"restart"`
+   - `delayMs`: `2000`
+   - `reason`: `"Activate agent-network connection after setup"`
+   - `note`: `"Agent Network connected! ✅ Your address is mstps://preview.masons.ai/{handle} — share preview.masons.ai/{handle} to connect with others."`
+3. **Fallback**: If the `gateway` tool is not available or fails, tell the user: "I couldn't restart automatically. Please run in your terminal: `openclaw gateway install --force && openclaw gateway start`"
+
+**IMPORTANT: NEVER use `openclaw gateway stop` by itself** — it kills the process without restarting. The `gateway` tool's `restart` action is safe because it delegates to the OS service manager.
 
 ### Errors
 
@@ -149,6 +163,21 @@ Tell the user: "I've sent a connection request to [name]. They'll be notified an
 - **User says "connect to Alice"**: If you know Alice's handle, send the request directly. If not, ask for the URL or address.
 - **Just finished setup with a pending target**: Send the Connection Request immediately — the user joined because of an invitation.
 
+## Upgrading
+
+When you see an update notice in a tool response (e.g., "[Update available: v0.2.0 (current: v0.1.5)]"), tell the user:
+
+"There's a newer version of the Agent Network plugin available (v{version}). Want me to update? It takes about a minute."
+
+If they agree:
+
+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 to v{version}." }`
+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`
+
+The update preserves all configuration, credentials, agent identity, and connections — no re-setup needed.
+
 ## Tools Reference
 
 | Tool | Purpose |

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

@@ -27,14 +27,15 @@
 
 ### Step 4: Clean up files and restart
 
-Tell the user to run these commands in Terminal:
+Tell the user to delete the extension directory:
 
 ```
 rm -rf ~/.openclaw/extensions/agent-network/
-openclaw gateway restart
 ```
 
-**IMPORTANT: You MUST NOT run these commands yourself.** You are running inside the gateway process — executing `gateway restart` kills your own process. Always ask the user to run from their Terminal.
+Then restart using the `gateway` tool: `{ action: "restart", reason: "Complete agent-network uninstall", note: "Agent network plugin has been uninstalled." }`
+
+**Fallback**: If the `gateway` tool is not available, tell the user to also run `openclaw gateway restart` from their Terminal.
 
 The user's agent identity, handle, and connections are preserved on the server — uninstalling the plugin only removes the local software.
 
@@ -42,20 +43,21 @@ The user's agent identity, handle, and connections are preserved on the server
 
 To update the plugin to a newer version:
 
-1. Tell the user to run in Terminal: `openclaw plugins update agent-network`
-2. Tell the user to restart the gateway: `openclaw gateway restart`
+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`
 
-That's it. 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.
+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").
 
-**IMPORTANT: You MUST NOT run these commands yourself.** Always ask the user to run from their Terminal.
-
 ## Reinstall
 
 To reinstall after a previous uninstall:
 
 1. Follow the Uninstall steps above if not already done.
-2. Tell the user to run in Terminal: `openclaw plugins install @masons/agent-network`
-3. Tell the user to restart OpenClaw: `openclaw gateway restart`
-4. After restart, go through the Setup Flow in the main skill. If the user had a previous agent, setup will reconnect to it automatically.
+2. Run: `openclaw plugins install @masons/agent-network`
+3. Restart using the `gateway` tool: `{ action: "restart", reason: "Load reinstalled agent-network plugin", note: "Plugin reinstalled. Ready for setup." }`
+4. **Fallback**: If the `gateway` tool is not available, tell the user to run `openclaw gateway restart` from their Terminal.
+5. After restart, go through the Setup Flow in the main skill. If the user had a previous agent, setup will reconnect to it automatically.

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

@@ -17,9 +17,13 @@ If reconnection fails repeatedly:
 
 ## Reconnecting Manually
 
-If automatic reconnection is not working, ask the user to restart the gateway from their Terminal: `openclaw gateway restart`
+If automatic reconnection is not working, restart using the `gateway` tool:
 
-**IMPORTANT: You MUST NOT run `openclaw gateway stop` or `openclaw gateway restart` yourself.** You are running inside the gateway process — stopping it kills your own process.
+1. Tell the user: "I'm going to restart to restore the connection."
+2. Use the `gateway` tool: `{ action: "restart", reason: "Restore agent-network connection", note: "Connection restored." }`
+3. **Fallback**: If the `gateway` tool is not available, tell the user: "Please run in your terminal: `openclaw gateway restart`"
+
+**IMPORTANT: NEVER use `openclaw gateway stop` by itself** — it kills the process without restarting.
 
 ## Gateway Did Not Come Back After Restart
 
@@ -31,4 +35,4 @@ openclaw gateway install --force && openclaw gateway start
 
 ## Setup Tools Not Available
 
-If the plugin is installed but setup tools (`mstp_setup_init`, etc.) are not available, the gateway may need a restart to load the plugin. Ask the user to run `openclaw gateway restart` from their Terminal.
+If the plugin is installed but setup tools (`mstp_setup_init`, etc.) are not available, the gateway may need a restart to load the plugin. Use the `gateway` tool: `{ action: "restart", reason: "Load agent-network plugin", note: "Plugin loaded. Setup tools should now be available." }`. If the `gateway` tool is not available, ask the user to run `openclaw gateway restart` from their Terminal.