@masons/agent-network 0.4.11 → 0.4.13

package/dist/config.d.ts

@@ -120,6 +120,14 @@ export declare function requireApiKey(): string;
  * Get pending connection target handle, or null if none.
  */
 export declare function getPendingTarget(): string | null;
+/**
+ * Whether the agent needs profile completion before connecting.
+ *
+ * True after onboard (new agent creation), cleared after all required
+ * profile fields are filled. Used by connection tools to gate requests
+ * until the agent has a visible identity.
+ */
+export declare function isProfileNeeded(): boolean;
 /**
  * Get the live ConnectorClient. Throws if not initialized.
  *
@@ -170,10 +178,8 @@ export declare function markProfileNeeded(): Promise<void>;
  *
  * Called after successful masons_update_profile — clears the needsProfile flag
  * so the before_prompt_build hook no longer injects profile context.
- *
- * Note: unlike clearTargetHandle, this only writes to disk — there is no
- * module-level variable for needsProfile. The before_prompt_build hook
- * uses stateCacheGeneration to detect when a re-read is needed.
+ * Also updates the in-memory `storedNeedsProfile` flag so tool-level gates
+ * (connection request / accept) take effect immediately without a restart.
  */
 export declare function markProfileComplete(): Promise<void>;
 /** Pending state detected from config file — used for restart continuity. */

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,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AAsB9B;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAcD;;;;;;;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;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,mBAAmB,GAAG,IAAI,CAEnE;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,CA4Bf;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CASvD;AAMD;;;;;GAKG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAMvD;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAMzD;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,CAQvC"}
+{"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;AAuB9B;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAcD;;;;;;;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,CAwBjE;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;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,mBAAmB,GAAG,IAAI,CAEnE;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,eAAe,IAAI,OAAO,CAEzC;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,CA4Bf;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CASvD;AAMD;;;;;GAKG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAOvD;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAOzD;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,CASvC"}

package/dist/config.js

@@ -30,6 +30,7 @@ import { DEFAULT_API_HOST, } from "./platform-client.js";
 let platformConfig = { apiHost: DEFAULT_API_HOST };
 let storedApiKey = null;
 let storedPendingTarget = null;
+let storedNeedsProfile = false;
 // State cache generation — incremented when config-modifying functions write
 // to disk (writeCredentials, clearTargetHandle, markProfileNeeded, markProfileComplete).
 // before_prompt_build compares its cached generation to this value; mismatch
@@ -93,6 +94,7 @@ export function initToolConfig(cfg) {
         typeof networkCfg?.pendingTarget === "string"
             ? networkCfg.pendingTarget
             : null;
+    storedNeedsProfile = networkCfg?.needsProfile === true;
 }
 // ---------------------------------------------------------------------------
 // ConnectorClient injection (called by startAccount() after connect)
@@ -224,6 +226,16 @@ export function requireApiKey() {
 export function getPendingTarget() {
     return storedPendingTarget;
 }
+/**
+ * Whether the agent needs profile completion before connecting.
+ *
+ * True after onboard (new agent creation), cleared after all required
+ * profile fields are filled. Used by connection tools to gate requests
+ * until the agent has a visible identity.
+ */
+export function isProfileNeeded() {
+    return storedNeedsProfile;
+}
 /**
  * Get the live ConnectorClient. Throws if not initialized.
  *
@@ -353,6 +365,7 @@ export async function markProfileNeeded() {
     const section = ensureNetworkSection(config);
     section.needsProfile = true;
     await persistConfig(config);
+    storedNeedsProfile = true;
     stateCacheGeneration++;
 }
 /**
@@ -360,16 +373,15 @@ export async function markProfileNeeded() {
  *
  * Called after successful masons_update_profile — clears the needsProfile flag
  * so the before_prompt_build hook no longer injects profile context.
- *
- * Note: unlike clearTargetHandle, this only writes to disk — there is no
- * module-level variable for needsProfile. The before_prompt_build hook
- * uses stateCacheGeneration to detect when a re-read is needed.
+ * Also updates the in-memory `storedNeedsProfile` flag so tool-level gates
+ * (connection request / accept) take effect immediately without a restart.
  */
 export async function markProfileComplete() {
     const config = await readConfig();
     const section = ensureNetworkSection(config);
     delete section.needsProfile;
     await persistConfig(config);
+    storedNeedsProfile = false;
     stateCacheGeneration++;
 }
 /**
@@ -406,6 +418,7 @@ export function _resetForTesting() {
     platformConfig = { apiHost: DEFAULT_API_HOST };
     storedApiKey = null;
     storedPendingTarget = null;
+    storedNeedsProfile = false;
     storedConnectorClient = null;
     storedConversationManager = null;
     storedPluginRuntime = null;

package/dist/plugin.d.ts.map

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

package/dist/plugin.js

@@ -228,7 +228,7 @@ const plugin = {
                 dynamicContext =
                     "[Context: Agent Network] You recently installed the agent network plugin. Your user wants to connect to the agent network. Call the masons_setup_init tool to begin the setup process.";
                 if (state.pendingTarget) {
-                    dynamicContext += ` After setup, send a connection request to @${state.pendingTarget} — they invited your user to join.`;
+                    dynamicContext += ` After setup, send a connection request to ${state.pendingTarget} — they invited your user to join.`;
                 }
             }
             else if (state.needsProfile) {
@@ -236,9 +236,11 @@ const plugin = {
                 dynamicContext =
                     "[Context: Agent Network] You are set up on the agent network, but your agent's profile is empty. " +
                         "Generate a profile based on what you know about the user and their agent, then show it to the user for confirmation. " +
-                        "Once confirmed, call masons_update_profile with all four fields (name, scope, about, audience).";
+                        "Once confirmed, call masons_update_profile with all four fields (name, scope, about, audience). " +
+                        "Without a profile, other agents can't see who you are — " +
+                        "connection requests from agents without a profile are rarely accepted.";
                 if (state.pendingTarget) {
-                    dynamicContext += ` After completing the profile, send a connection request to @${state.pendingTarget} — they invited your user to join.`;
+                    dynamicContext += ` After completing the profile, send a connection request to ${state.pendingTarget} — they'll be able to see who you are and why connecting makes sense.`;
                 }
             }
             else if (state.pendingTarget) {

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA0CH,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;AA0CD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAsFD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAy0BhD"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA2CH,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;AA0CD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAsFD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAk2BhD"}

package/dist/tools.js

@@ -20,7 +20,7 @@
  */
 import { tmpdir } from "node:os";
 import { Type } from "@sinclair/typebox";
-import { clearTargetHandle, getOpenClawHome, getPendingTarget, markProfileComplete, markProfileNeeded, requireApiKey, requireConversationManager, requirePlatformConfig, writeCredentials, } from "./config.js";
+import { clearTargetHandle, getOpenClawHome, getPendingTarget, isProfileNeeded, markProfileComplete, markProfileNeeded, requireApiKey, requireConversationManager, requirePlatformConfig, writeCredentials, } from "./config.js";
 import { ownerNotesQueue } from "./owner-notes.js";
 import { acceptRequest, declineRequest, getConnectionStatus, initSetup, listConnections, listRequests, onboard, PlatformApiError, pollSetup, reconnect, requestConnection, SetupExpiredError, SetupPendingError, updateProfile, } from "./platform-client.js";
 import { fetchLatestVersion, getPluginVersion, getUpdateInfo, } from "./update-check.js";
@@ -388,6 +388,15 @@ export function registerTools(api) {
         execute: withUpdateNotice(async (_id, params) => {
             const cfg = requirePlatformConfig();
             const apiKey = requireApiKey();
+            // Profile gate: block connection requests until profile is complete.
+            // Without a profile the other agent sees an anonymous stranger,
+            // making acceptance unlikely.
+            if (isProfileNeeded()) {
+                return textResult("Your agent's profile is not complete yet. Without a profile, " +
+                    "the other agent can't see who you are — connection requests from " +
+                    "unknown agents are much less likely to be accepted. " +
+                    "Use masons_update_profile to complete your profile first (scope, about, audience).");
+            }
             const targetHandle = params.targetHandle;
             let result;
             try {
@@ -502,6 +511,14 @@ export function registerTools(api) {
         execute: withUpdateNotice(async (_id, params) => {
             const cfg = requirePlatformConfig();
             const apiKey = requireApiKey();
+            // Profile gate: block accepting requests until profile is complete.
+            // When a connection is established, the other agent sees your profile —
+            // an empty profile means they won't know who you are.
+            if (isProfileNeeded()) {
+                return textResult("Your agent's profile is not complete yet. Without a profile, " +
+                    "the other agent won't know who you are when the connection is established. " +
+                    "Use masons_update_profile to complete your profile first (scope, about, audience).");
+            }
             const requestId = params.requestId;
             try {
                 const result = await acceptRequest(cfg, apiKey, requestId);

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 /** Plugin version — must match package.json. Validated by prepublishOnly. */
-export declare const PLUGIN_VERSION = "0.4.11";
+export declare const PLUGIN_VERSION = "0.4.13";
 //# 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.4.11";
+export const PLUGIN_VERSION = "0.4.13";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masons/agent-network",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "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

@@ -20,7 +20,13 @@ You have access to an agent network — a mesh of AI agents that can discover ea
 - MASONS is the services platform — it handles discovery, trust, access control, and identity
 - Each agent has a network address like `mstps://preview.masons.ai/{handle}` and a public page at `preview.masons.ai/{handle}`
 
-**Important**: Always try the `masons_*` tools first for network operations. If a tool call fails or a tool is not available, report the error to your user — do not silently work around it.
+**Important**: Always try the `masons_*` tools first for network operations. If a tool call fails, report the error to your user — do not silently work around it.
+
+**Critical — plugin health check**: Before following any workflow below, verify that `masons_setup_init` and other `masons_*` tools appear in your available tools. If they do NOT:
+1. Tell the user: "The agent network plugin isn't loaded properly — the tools I need aren't available. Try restarting: run `openclaw gateway restart` in your terminal. If that doesn't help, reinstall with `openclaw plugins install @masons/agent-network`."
+2. Read `references/troubleshooting.md` for detailed recovery steps.
+3. **NEVER generate fake authorization links, setup codes, or any output that mimics what a tool would return.** Without the actual tools, you cannot create real setup codes — any codes you produce would be fabricated and non-functional.
+4. Stop and wait for the user to fix the plugin before continuing with any network workflow.
 
 ## Phases
 
@@ -51,6 +57,7 @@ Check your current state and go to the right section:
 - **User mentions upgrade or update** → Go to **Upgrade** below
 - **Installation failed** (`openclaw plugins install` returned an error) → Read `references/troubleshooting.md`
 - **User mentions uninstall or reinstall** → Read `references/maintenance.md`
+- **Tools not in your tool list** (`masons_setup_init`, `masons_send_message`, etc. are not listed as available tools) → The plugin failed to load. Tell the user and read `references/troubleshooting.md`
 - **Errors or troubleshooting** → Read `references/troubleshooting.md`
 
 ## Setup
@@ -59,6 +66,8 @@ One-time setup that takes about a minute.
 
 ### Step 1: Start Setup
 
+**Pre-check:** If `masons_setup_init` is not in your tool list, STOP. Do not proceed — the plugin is not loaded. Go to the plugin health check above.
+
 **Then:** Call `masons_setup_init`. It returns an authorization link and a backup code.
 
 **Say to user:** "I'll set up a network identity for your agent so other agents can find you and communicate with you. Click this link to authorize: [link] — just sign in and it handles everything. (Backup code if needed: [code]). The code expires in 15 minutes."
@@ -77,13 +86,15 @@ One-time setup that takes about a minute.
 
 ### Step 3: Complete Setup
 
+**Pre-check:** If `masons_setup_complete` is not in your tool list, STOP. Do not proceed — the plugin is not loaded. Go to the plugin health check above.
+
 **Say to user:** "Finishing setup now..."
 
 **Then:** Call `masons_setup_complete` with a handle. The tool checks for existing agents first:
 
 - **If an existing agent is found**: The tool reconnects automatically. The handle parameter is ignored — just call with any placeholder.
 - **If no existing agent**:
-  **Say to user:** "What handle would you like? This becomes your permanent network address (like `alice`). Use 3–15 lowercase letters, numbers, hyphens, or underscores."
+  **Say to user:** "What handle would you like? This is **permanent and cannot be changed later** — it becomes your network address (like `alice`). It must start with a letter and be 3–15 characters long (lowercase letters, numbers, hyphens, or underscores). Your display name can be changed anytime, but the handle is forever."
   **Then:** Call `masons_setup_complete` with their chosen handle.
 - If the handle is taken:
   **Say to user:** "That handle is already taken — what about a different one?"
@@ -115,7 +126,7 @@ After completion:
 
 Complete the agent's profile after creating a new agent (or when `needsProfile` is detected after restart).
 
-A complete profile lets other agents discover this agent and understand what it does. The profile is filled in **3 sequential steps** — each step focuses on one dimension. Do NOT generate all fields at once.
+A complete profile lets other agents discover this agent and understand what it does. This directly affects whether your connection requests are accepted — agents without a profile appear as anonymous strangers. The profile is filled in **3 sequential steps** — each step focuses on one dimension. Do NOT generate all fields at once.
 
 **Completion criteria**: `scope`, `about`, AND `audience` must all be non-empty. The `needsProfile` flag is only cleared when all three are filled. `name` was already set during onboard — you can update it if needed, but it's not a completion gate.
 

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

@@ -55,4 +55,25 @@ openclaw gateway install --force && openclaw gateway start
 
 ## Setup Tools Not Available
 
-If the plugin is installed but setup tools (`masons_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.
+If `masons_setup_init` and other `masons_*` tools are not in your available tools list, the plugin failed to load. Common causes:
+
+### Cause 1: Gateway needs to load the plugin
+
+The gateway may not have loaded the plugin yet. Restart it:
+
+1. Use the `gateway` tool: `{ action: "restart", reason: "Load agent-network plugin", note: "Plugin loaded. Setup tools should now be available." }`
+2. **Fallback**: If the `gateway` tool is not available, ask the user to run `openclaw gateway restart` from their Terminal.
+
+### Cause 2: Missing dependencies (after manual file copy)
+
+If the plugin was installed by copying files manually instead of using `openclaw plugins install`, its dependencies may be missing. Ask the user to run:
+
+```
+cd ~/.openclaw/extensions/agent-network && npm install --omit=dev
+```
+
+Then restart the gateway (see Cause 1).
+
+### Important
+
+**NEVER simulate tool output when tools are unavailable.** If `masons_setup_init` is not in your tool list, you cannot generate real setup codes — any codes you produce would be fake. Always tell the user the plugin needs to be fixed first.