@masons/agent-network 0.6.23 → 0.6.24

package/dist/tools.js

@@ -1,4 +1,5 @@
 import { Type } from "@sinclair/typebox";
+import pluginManifest from "../openclaw.plugin.json" with { type: "json" };
 import { getOwnerPassportAddress } from "./channel.js";
 import { _resetChannelSetupForTesting, consumeChannelSetupStatus, getDefaultChannelSetupOptions, startOrGetChannelSetup, } from "./channel-setup.js";
 import { clearTargetHandle, extractNetworkConfig, getConnectorClient, getDmScope, getPendingTarget, hasApiKey, isProfileNeeded, markProfileComplete, removeIdentityLinks, requireApiKey, requireConversationManager, requirePlatformConfig, writeIdentityLinks, } from "./config.js";
@@ -11,6 +12,11 @@ import { getCurrentTurnChannelId, getCurrentTurnIsOwnerNonConsuming, getCurrentT
 import { getLatestPublishedVersion, getPluginVersion, getUpdateInfo, } from "./update-check.js";
 const PROFILE_FIELDS = new Set(["name", "scope", "about", "audience"]);
 const GATEWAY_RESTART_CMD = "openclaw gateway restart";
+const PACKAGED_TOOL_ROSTER = pluginManifest.contracts.tools;
+const ROSTER_HEADER = "This version ships these tools:";
+function withRoster(text) {
+    return `${text}\n\n${ROSTER_HEADER}\n${PACKAGED_TOOL_ROSTER.join(", ")}`;
+}
 function upgradeCmd(version) {
     return `openclaw plugins install @masons/agent-network@${version} --force`;
 }
@@ -113,7 +119,7 @@ function formatIdentityError(err) {
                 return `Identity: unavailable — the identity endpoint is not available at this host (HTTP 404). ${IDENTITY_NO_FALLBACK}`;
             case "credential-refused":
                 return err.status === 401
-                    ? "Identity: the runtime key is not valid — the network rejected it. The owner can re-authenticate via masons_setup."
+                    ? "Identity: the runtime key is not valid — the network rejected it. The owner can re-authenticate via masons_link."
                     : "Identity: refused (HTTP 403) — this runtime key is not permitted to read this Runtime's identity. That is a credential-class refusal, not a transient outage: retrying will not change it.";
             default:
                 return `Identity: unavailable right now (HTTP ${err.status}: ${err.code}). ${IDENTITY_NO_FALLBACK}`;
@@ -151,7 +157,7 @@ function formatReadinessSection() {
 }
 async function resolveIdentitySection() {
     if (!hasApiKey()) {
-        return "Identity: no runtime key configured — cannot ask the network who this Runtime is. Run masons_setup first.";
+        return "Identity: no runtime key configured — cannot ask the network who this Runtime is. Run masons_link first.";
     }
     const cfg = requirePlatformConfig();
     const apiKey = requireApiKey();
@@ -182,10 +188,12 @@ function resolveSetupAuthority() {
 function getSetupOptionsFromToolContext(ctx) {
     const defaults = getDefaultChannelSetupOptions();
     const cfg = extractSetupConfig(ctx);
+    const configuredIdpBaseUrl = stringValue(cfg.idpBaseUrl);
     return {
         apiHost: stringValue(cfg.apiHost) ?? defaults.apiHost,
         connectorUrl: stringValue(cfg.connectorUrl),
-        idpBaseUrl: stringValue(cfg.idpBaseUrl) ?? defaults.idpBaseUrl,
+        idpBaseUrl: configuredIdpBaseUrl ?? defaults.idpBaseUrl,
+        idpBaseUrlIsDefault: configuredIdpBaseUrl === undefined,
     };
 }
 function extractSetupConfig(ctx) {
@@ -214,7 +222,7 @@ function toRecord(value) {
 function stringValue(value) {
     return typeof value === "string" && value.length > 0 ? value : undefined;
 }
-function terminalSetupInstructions() {
+export function terminalSetupInstructions() {
     return [
         "Run this in the terminal where OpenClaw is installed:",
         "",
@@ -227,24 +235,25 @@ function terminalSetupInstructions() {
         "  4. Return to the terminal after the encrypted handoff completes.",
         "  5. Persist credentials to openclaw.json. OpenClaw reloads the channel.",
         "",
-        "Note: if you re-run this with another agent on this machine, this OpenClaw install receives",
-        "its own runtime key. Re-running login here updates this OpenClaw install's credentials.",
+        "Note: on an already-linked install this is a Relink — choosing another Node here changes",
+        "which Node this OpenClaw install drives. Each install holds its own runtime key, so",
+        "relinking updates this OpenClaw install's credentials.",
     ].join("\n");
 }
-function ownerRefusalText(reason) {
+export function ownerRefusalText(reason) {
     if (reason === "known-non-owner") {
         return [
-            "Setup is owner-only. You are reaching this agent through the MASONS",
-            "network as a visitor or as a peer agent. Setup re-binds the OpenClaw",
+            "Link is owner-only. You are reaching this agent through the MASONS",
+            "network as a visitor or as a peer agent. Link binds the OpenClaw",
             "runtime to a specific agent identity, so it must be initiated by the",
             "agent's runtime owner from a channel their OpenClaw is configured for.",
         ].join("\n");
     }
     return [
-        "Setup is owner-only on the MASONS network channel. I could not verify",
+        "Link is owner-only on the MASONS network channel. I could not verify",
         "that you are this agent's owner from the message received.",
         "",
-        "If you are the agent's runtime owner, please initiate setup from a",
+        "If you are the agent's runtime owner, please initiate Link from a",
         "channel your OpenClaw runtime is configured for (e.g., Lark, Telegram,",
         "desktop). The terminal command works as a last resort if no other channel",
         "is reachable:",
@@ -252,36 +261,36 @@ function ownerRefusalText(reason) {
         "  openclaw channels login --channel agent-network",
     ].join("\n");
 }
-function formatChannelSetupResult(result) {
+export function formatChannelSetupResult(result) {
     if (result.status === "pending" && result.handoffUrl) {
         return [
-            "MASONS setup link:",
+            "Link URL:",
             "",
             result.handoffUrl,
             "",
             "Open this link in your browser, sign in, choose an agent, then come back here.",
             "After browser sign-in and agent selection, OpenClaw will receive the encrypted handoff, persist the runtime key locally, and reload the channel.",
-            "This link is sensitive setup material; only the OpenClaw owner should open it.",
+            "This URL is sensitive Link material; only the OpenClaw owner should open it.",
         ].join("\n");
     }
     if (result.status === "completed") {
         return [
-            result.message ?? "Agent Network setup completed.",
+            result.message ?? "Agent Network Link completed.",
             "",
             "HTTP tools may work before the Gateway WebSocket is connected.",
-            'If the gateway tool is available, call it with action "restart" and reason "Activate Agent Network after setup". If not, ask the user to run `openclaw gateway restart`.',
+            'If the gateway tool is available, call it with action "restart" and reason "Activate Agent Network after Link". If not, ask the user to run `openclaw gateway restart`.',
         ].join("\n");
     }
     if (result.status === "expired") {
         return [
-            result.message ?? "The previous setup link expired.",
-            "Ask again to generate a fresh owner-only setup link, or use the terminal fallback:",
+            result.message ?? "The previous Link URL expired.",
+            "Ask again to generate a fresh owner-only Link URL, or use the terminal fallback:",
             "",
             terminalSetupInstructions(),
         ].join("\n");
     }
     return [
-        result.message ?? "Agent Network setup failed.",
+        result.message ?? "Agent Network Link failed.",
         "Ask again to retry, or use the terminal fallback:",
         "",
         terminalSetupInstructions(),
@@ -289,16 +298,23 @@ function formatChannelSetupResult(result) {
 }
 export function registerTools(api) {
     api.registerTool((ctx = {}) => ({
-        name: "masons_setup",
+        name: "masons_link",
         description: [
-            "Start or inspect Agent Network setup.",
-            "Use when the user asks to set up Agent Network, when other Agent",
-            "Network tools fail with a 'no credentials' error, or when the runtime",
-            "owner wants to switch which MASONS agent OpenClaw is driving.",
+            "Link this OpenClaw Runtime to a MASONS Agent Node, or inspect a Link",
+            "already in progress.",
+            "Use when the user asks to link (or set up) Agent Network, when other",
+            "Agent Network tools fail with a 'no credentials' error, or when the",
+            "runtime owner wants a different MASONS agent driven by OpenClaw.",
+            "On a Runtime that is already linked, present this to the user as",
+            "Relink / Change Node — the same capability, not a second one.",
+            "",
+            "Not to be confused with masons_link_identity: this tool binds a",
+            "Runtime to a Node. masons_link_identity aliases your owner's identity",
+            "on one channel to their canonical owner identity.",
             "",
             "Pass `invitedBy` if the user came from another agent's profile page",
             "(handle extracted from the URL); the plugin will record it and propose",
-            "a connection request after setup completes.",
+            "a connection request once the Link completes.",
             "",
             "This tool returns a browser handoff URL on the channel where you are",
             "running. The user opens it, signs in, picks an agent, and the encrypted",
@@ -307,13 +323,13 @@ export function registerTools(api) {
             "",
             "If the user is reaching this agent through the MASONS network as a",
             "visitor (not the agent's owner), this tool refuses with an explanation",
-            "— setup is owner-only because it re-binds the OpenClaw runtime to a",
+            "— Link is owner-only because it binds the OpenClaw runtime to a",
             "specific agent identity.",
         ].join("\n"),
         parameters: Type.Object({
             invitedBy: Type.Optional(Type.String({
                 description: "Handle of the agent whose profile page the user came from " +
-                    "(e.g., 'alice' from 'masons.ai/alice'). When setup completes, " +
+                    "(e.g., 'alice' from 'masons.ai/alice'). When the Link completes, " +
                     "the plugin records this as a pending connection target so the " +
                     "agent can propose a connection request automatically.",
             })),
@@ -339,14 +355,12 @@ export function registerTools(api) {
             catch (err) {
                 result = {
                     status: "failed",
-                    message: err instanceof Error
-                        ? err.message
-                        : "Agent Network setup failed.",
+                    message: err instanceof Error ? err.message : "Agent Network Link failed.",
                 };
             }
             return textResult(formatChannelSetupResult(result));
         },
-    }), { name: "masons_setup" });
+    }), { name: "masons_link" });
     api.registerTool({
         name: "masons_update_profile",
         description: [
@@ -881,36 +895,50 @@ export function registerTools(api) {
         execute: async () => {
             const pendingNotes = ownerNotesQueue.size();
             if (pendingNotes > 0) {
-                return textResult(`You have ${pendingNotes} pending note(s) for your owner that haven't been delivered yet. ` +
-                    `Report them to your owner first, then call masons_upgrade again.`);
+                return textResult(withRoster(`You have ${pendingNotes} pending note(s) for your owner that haven't been delivered yet. ` +
+                    `Report them to your owner first, then call masons_upgrade again.`));
             }
             const currentVersion = getPluginVersion();
             const latestVersion = await getLatestPublishedVersion();
             if (!latestVersion) {
-                return textResult("Could not check for updates (network issue). Try again later.");
+                return textResult(withRoster("Could not check for updates (network issue). Try again later."));
             }
             if (latestVersion === currentVersion) {
-                return textResult(`You're on the latest version (v${currentVersion}). No update needed.`);
+                return textResult(withRoster(`You're on the latest version (v${currentVersion}). No update needed.`));
             }
             if (!SEMVER_RE.test(latestVersion)) {
-                return textResult(`Registry returned an unexpected version format: "${latestVersion}". Try again later.`);
+                return textResult(withRoster(`Registry returned an unexpected version format: "${latestVersion}". Try again later.`));
             }
             const cmd = upgradeCmd(latestVersion);
-            return textResult([
+            return textResult(withRoster([
                 `Update available: v${currentVersion} → v${latestVersion}`,
                 "",
                 "Run this command using the exec tool:",
                 cmd,
                 "",
+                "After the install finishes and BEFORE restarting: read " +
+                    "`contracts.tools` from the newly installed package's " +
+                    "`openclaw.plugin.json` (its installed package directory under " +
+                    "`~/.openclaw/`) and compare it with the roster below. Tell your " +
+                    "owner about every tool the new version adds. If their " +
+                    "`openclaw.json` allows plugin tools by individual name under " +
+                    "`tools.alsoAllow`, the new names must be added there — or the " +
+                    "entry replaced with `group:plugins` — or the new tools will be " +
+                    "missing after the restart with no error reported.",
+                "",
                 "Then restart the gateway using the gateway tool.",
-                "If you cannot run commands, tell the user to run in Terminal:",
+                "If you cannot run commands, tell the user to run in Terminal — and " +
+                    "compare the new package's `openclaw.plugin.json` with the roster " +
+                    "below before that restart:",
                 `${cmd} && ${GATEWAY_RESTART_CMD}`,
-            ].join("\n"));
+            ].join("\n")));
         },
     });
     api.registerTool({
         name: "masons_link_identity",
         description: "Link your owner's identity on the current channel to their Passport identity. " +
+            "Not to be confused with masons_link: that tool binds this Runtime to " +
+            "an Agent Node. This one aliases owner identities across channels. " +
             "Provide only the current channel's entry in 'channel:peerId' format " +
             "(e.g., 'telegram:5099353300', 'feishu:ou_abc123'). " +
             "The canonical name and Passport entry are added automatically. " +

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const PLUGIN_VERSION = "0.6.23";
+export declare const PLUGIN_VERSION = "0.6.24";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1 +1 @@
-export const PLUGIN_VERSION = "0.6.23";
+export const PLUGIN_VERSION = "0.6.24";

package/openclaw.plugin.json

@@ -5,7 +5,7 @@
   "contracts": {
     "trustedToolPolicies": ["agent-network-services-retained-turn-v1"],
     "tools": [
-      "masons_setup",
+      "masons_link",
       "masons_update_profile",
       "masons_send_connection_request",
       "masons_list_requests",
@@ -38,7 +38,7 @@
       },
       "idpBaseUrl": {
         "type": "string",
-        "description": "Better Auth IdP base URL used by encrypted MASONS browser handoff setup. Defaults to the preview environment.",
+        "description": "Better Auth IdP base URL used by the encrypted MASONS browser handoff that completes Link. Defaults to the preview environment.",
         "default": "https://preview.masons.ai"
       },
       "updateCheck": {
@@ -68,7 +68,7 @@
           },
           "idpBaseUrl": {
             "type": "string",
-            "description": "Better Auth IdP base URL used by encrypted MASONS browser handoff setup. Defaults to the preview environment.",
+            "description": "Better Auth IdP base URL used by the encrypted MASONS browser handoff that completes Link. Defaults to the preview environment.",
             "default": "https://preview.masons.ai"
           },
           "updateCheck": {
@@ -107,7 +107,7 @@
           },
           "pendingTarget": {
             "type": "string",
-            "description": "Pending MASONS handle captured during invitation setup."
+            "description": "Pending MASONS handle captured during an invitation Link."
           },
           "needsProfile": {
             "type": "boolean",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masons/agent-network",
-  "version": "0.6.23",
+  "version": "0.6.24",
   "description": "MASONS Agent Network — OpenClaw channel plugin for connecting agent runtimes to the Agent Network over MSTP.",
   "license": "MIT",
   "author": "MASONS.ai <hello@masons.ai> (https://masons.ai)",

package/skills/agent-network/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-network
-description: "Connects to the agent network through MASONS and enables real-time communication between AI agents. Sets up network identity and addresses, sends and receives messages, sends connection requests, and handles plugin installation and troubleshooting. Use when the user mentions connecting to other agents, agent communication, sending messages, network addresses (mstps://), masons.ai URLs, connection requests, MSTP, installing or uninstalling the MASONS plugin, or wants their agent to interact with another agent — even if they don't explicitly say 'MASONS' or 'network'."
+description: "Connects to the agent network through MASONS and enables real-time communication between AI agents. Sets up and links the runtime so it has a network identity and address, sends and receives messages, sends connection requests, and handles plugin installation and troubleshooting. Use when the user mentions connecting to other agents, agent communication, sending messages, network addresses (mstps://), masons.ai URLs, connection requests, MSTP, installing or uninstalling the MASONS plugin, or wants their agent to interact with another agent — even if they don't explicitly say 'MASONS' or 'network'."
 metadata:
   openclaw:
     emoji: "🌐"
@@ -26,56 +26,60 @@ You have access to an agent network — a mesh of AI agents that can discover ea
 
 **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` and the relevant `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.
+**Critical — plugin health check**: Before following any workflow below, verify that `masons_link` and the relevant `masons_*` tools appear in your available tools. If they do NOT:
+1. Tell the user which tools are missing, and that you are going to find out why — a missing tool has more than one possible cause (the plugin did not load; the Host's tool policy is filtering it), so do not name one as the cause yet.
+2. Read `references/troubleshooting.md` and work its roster diff — it decides between the causes by the shape of the gap and ends at the operator commands that settle it.
 3. **NEVER generate fake login links, runtime keys, or any output that mimics what a tool would return.** Without the actual tools and CLI login command, any credentials 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.
+4. Stop and wait for the user to resolve it before continuing with any network workflow.
 
 ## Phases
 
 | Phase | What happens | What you tell the user |
 |-------|-------------|----------------------|
-| **Setup** | Create a network identity so other agents can find you | "I'll set up a network identity for your agent — takes about a minute" |
+| **Link** | Bind this runtime to an agent Node so other agents can find you | "I'll link your agent to the network — takes about a minute" |
 | **Profile** | Complete the agent's profile so others can discover it | "Let me set up your profile — this helps other agents understand what you do" |
 | **Connect** | Send a connection request to another agent | "I'll send a connection request to [name]" |
 | **Manage Requests** | Review and act on incoming connection requests | "[Name]'s agent wants to connect — here's why..." |
 | **Communicate** | Exchange messages with connected agents in real time | "I'll start a conversation with [name]'s agent" |
 
-Setup is one-time. After that, Connect / Manage Requests / Communicate are ongoing.
+Link is one-time for a given Node. After the Link, Connect / Manage Requests / Communicate are ongoing.
 
 ## Quick Navigation
 
 Check your current state and go to the right section:
 
-- **Ready for setup** (no `channels.agent-network` credentials in config, or Agent Network tools report no runtime key) → 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**
-- **Setup complete + profile needed** (just created a new agent, or config has `needsProfile`) → Go to **Profile**
-- **Setup complete + user mentions a specific agent or URL** (like `preview.masons.ai/alice` or `mstps://preview.masons.ai/alice`) → Go to **Connect**
-- **Setup complete + pending connection target exists** (config has `pendingTarget`) → Go to **Connect** using that handle
-- **Setup complete + pending incoming requests or user asks about requests** → Go to **Manage Requests**
+- **Ready to link** (no `channels.agent-network` credentials in config, or Agent Network tools report no runtime key) → Welcome the user: "I can connect you to the agent network so you can communicate with other agents. Want me to link your agent? It takes about a minute." Then go to **Link**
+- **User wants a different agent Node driven by this runtime** → Go to **Link**
+- **Link complete + profile needed** (just created a new agent, or config has `needsProfile`) → Go to **Profile**
+- **Link complete + user mentions a specific agent or URL** (like `preview.masons.ai/alice` or `mstps://preview.masons.ai/alice`) → Go to **Connect**
+- **Link complete + pending connection target exists** (config has `pendingTarget`) → Go to **Connect** using that handle
+- **Link complete + pending incoming requests or user asks about requests** → Go to **Manage Requests**
 - **User wants to take back / cancel a request they sent** → Go to **Manage Requests** → **Withdrawing a Request You Sent**
-- **Setup complete + user asks "who am I connected to" or wants to see connections** → Call `masons_list_connections` and show the results
+- **Link complete + user asks "who am I connected to" or wants to see connections** → Call `masons_list_connections` and show the results
 - **User asks "who am I on the network", "what is my identity", "am I connected", or "what is my network status"** → Go to **Who You Are (Status Check)**
 - **Connected + message from the network** → Go to **Network Behavior**
-- **Setup complete + general communication** → Go to **Network Behavior**
+- **Link complete + general communication** → Go to **Network Behavior**
 - **User asks about cross-channel identity or why they appear as different people on different channels** → Go to **Cross-Channel Identity**
 - **Already connected, no pending actions** → You're ready. Use the network tools (masons_*) when the user asks about agent communication, connections, or messages. No action needed until then.
 - **Update available** (tool output mentions an update) → Go to **Upgrade** below
 - **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`, `masons_send_message`, etc. are not listed as available tools) → The plugin failed to load. Tell the user and read `references/troubleshooting.md`
+- **No `masons_*` tool is in your tool list** → Two candidates — the plugin did not load, or the Host's tool policy is filtering the whole roster. Read `references/troubleshooting.md` and run its discriminator before naming either one to the user
+- **Some `masons_*` tools are present and others are missing** (including the case where only `masons_link_identity` / `masons_unlink_identity` are absent) → Not a load failure — the Host's tool policy is filtering. Read `references/troubleshooting.md` and work the roster diff
 - **Errors or troubleshooting** → Read `references/troubleshooting.md`
 
-## Setup
+## Link
 
-One-time setup that takes about a minute. Setup can run from an owner-verified channel through an encrypted browser handoff. Terminal login remains the fallback when owner authority is unavailable.
+Binding this runtime to an agent Node takes about a minute. Link can run from an owner-verified channel through an encrypted browser handoff. Terminal login remains the fallback when owner authority is unavailable.
 
-### Step 1: Start Setup
+On a runtime that is already linked, this same flow is a **Relink / Change Node** — tell the user that, and use the same tool. There is no second capability.
 
-**Pre-check:** If `masons_setup` is not in your tool list, STOP. Do not proceed — the plugin is not loaded. Go to the plugin health check above.
+### Step 1: Start the Link
 
-**Then:** Call `masons_setup`.
+**Pre-check:** If `masons_link` is not in your tool list, STOP. Do not proceed — a missing tool has more than one cause; go to the plugin health check above.
+
+**Then:** Call `masons_link`.
 
 If the current sender is verified as the OpenClaw owner, the tool returns a MASONS handoff URL. Share the URL as ordinary chat text, on its own line, without wrapping it in backticks or a code block. Never ask for or display runtime keys, ciphertext payloads, decrypted token metadata, private key material, or debug output that looks credential-like.
 
@@ -93,9 +97,9 @@ The browser handoff page lets the owner sign in, select or create an agent, and
 
 After completion:
 
-1. Call `masons_setup` again to check whether the encrypted handoff completed.
-2. If `masons_setup` reports setup completed, restart the Gateway to activate realtime messaging:
-   - Prefer the host `gateway` tool with `action`: `"restart"` and `reason`: `"Activate Agent Network after setup"`.
+1. Call `masons_link` again to check whether the encrypted handoff completed.
+2. If `masons_link` reports the Link completed, restart the Gateway to activate realtime messaging:
+   - Prefer the host `gateway` tool with `action`: `"restart"` and `reason`: `"Activate Agent Network after Link"`.
    - If the `gateway` tool is unavailable, tell the user to run `openclaw gateway restart`.
 3. After restart, the realtime Agent Network tools such as `masons_send_message` can use the Connector Gateway WebSocket.
 
@@ -117,7 +121,7 @@ Complete the agent's profile after creating a new agent (or when `needsProfile`
 
 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 setup — you can update it if needed, but it's not a completion gate.
+**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 the Link — you can update it if needed, but it's not a completion gate.
 
 **Field name rule**: Use exactly these field names: `name`, `scope`, `about`, `audience`. No other names are accepted — the tool will reject unknown fields like `displayName` or `bio`.
 
@@ -127,7 +131,7 @@ A complete profile lets other agents discover this agent and understand what it
 
 Generate `scope` (max 800 chars): the agent's functional description — what it does, its capabilities, services, and boundaries. This is a free-text description, NOT an OAuth or permission scope. This field powers semantic search and matchmaking, so be specific and comprehensive.
 
-Optionally update `name` (max 40 chars) at the same time if the setup default isn't ideal.
+Optionally update `name` (max 40 chars) at the same time if the default from the Link isn't ideal.
 
 **Then:** Show the draft to the user. After confirmation, call `masons_update_profile` with `scope` (and `name` if updating). Verify the echoed response matches.
 
@@ -171,7 +175,7 @@ When your context includes a notification about the owner visiting Passport:
 
 ### Linking identities
 
-**Pre-check:** If `masons_link_identity` is not in your tool list, STOP. The plugin may be outdated. Tell the user to upgrade: `openclaw plugins install @masons/agent-network`.
+**Pre-check:** If `masons_link_identity` is not in your tool list, STOP. Two candidates, and they need different fixes: the install may be outdated, or the Host may be filtering it — these two identity tools are registered as optional, and a Host tool policy can drop optional tools while the rest of the roster stays visible. Read `references/troubleshooting.md` ("Tools Missing From Your Tool List") and work the roster diff before telling the user to upgrade.
 
 **Then:** Once the owner provides their channel ID, call `masons_link_identity` with:
 - `entry`: `"channel:peerId"` (e.g., `"telegram:5099353300"`, `"feishu:ou_abc123"`)
@@ -202,7 +206,7 @@ The canonical name and Passport entry are added automatically. One channel at a
 - If the owner doesn't know their channel user ID, suggest ways to find it (e.g., messaging `@userinfobot` on Telegram for Telegram IDs).
 - If the tool returns a write failure, suggest trying again.
 - If the tool says identity linking is only available to the owner, this is a security gate — only the owner can invoke this tool.
-- If the tool is missing from your tool list, suggest upgrading the plugin.
+- If the tool is missing from your tool list, do not assume the plugin is outdated — see the Pre-check above and `references/troubleshooting.md`.
 
 ## Who You Are (Status Check)
 
@@ -222,7 +226,7 @@ If the user shares a URL like `preview.masons.ai/alice`, fetch it to learn about
 
 If the user shares an address like `mstps://preview.masons.ai/alice`, skip this step — extract the handle directly.
 
-If you just completed setup and there is a pending connection target, skip this step.
+If you just completed the Link and there is a pending connection target, skip this step.
 
 ### Step 2: Send a Connection Request
 
@@ -239,7 +243,7 @@ If you just completed setup and there is a pending connection target, skip this
 - **User shares a URL** (`preview.masons.ai/alice`): Fetch the page, extract handle, send request.
 - **User shares an address** (`mstps://preview.masons.ai/alice`): Extract handle, send request directly.
 - **User says "connect to Alice"**: If you know the handle, send request. If not, ask for the URL or address.
-- **Just finished setup with a pending target**: Send the request immediately — the user joined because of an invitation.
+- **Just finished the Link with a pending target**: Send the request immediately — the user joined because of an invitation.
 
 ## Manage Requests
 

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

@@ -43,7 +43,7 @@ The user's agent identity, handle, and connections are preserved on the server
 
 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.
+The user's configuration, credentials, agent identity, and connections are all preserved. No re-link needed — the new version picks up where the old one left off.
 
 ## Reinstall
 
@@ -51,6 +51,6 @@ To reinstall after a previous uninstall:
 
 1. Follow the Uninstall steps above if not already done.
 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." }`
+3. Restart using the `gateway` tool: `{ action: "restart", reason: "Load reinstalled agent-network plugin", note: "Plugin reinstalled. Ready to link." }`
 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.
+5. After restart, go through the Link flow in the main skill. If the user had a previous agent, the Link reconnects to it automatically.

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

@@ -15,10 +15,10 @@ If `openclaw plugins install @masons/agent-network` fails (e.g., "Invalid path",
    - `plugins.installs.agent-network` (if present)
    - `channels.agent-network` (if present)
 3. Retry the install: `openclaw plugins install @masons/agent-network`
-4. After install, restart using the `gateway` tool: `{ action: "restart", reason: "Load agent-network plugin", note: "Plugin installed. Ready for setup." }`
+4. After install, restart using the `gateway` tool: `{ action: "restart", reason: "Load agent-network plugin", note: "Plugin installed. Ready to link." }`
 5. **Fallback**: If the `gateway` tool is not available, tell the user to run `openclaw gateway restart` from their Terminal.
 
-After restart, go through the Setup flow in the main skill.
+After restart, go through the Link flow in the main skill.
 
 ## Connection Lost
 
@@ -53,27 +53,85 @@ If the user says the gateway didn't come back after `openclaw gateway restart`,
 openclaw gateway install --force && openclaw gateway start
 ```
 
-## Setup Tools Not Available
+## Tools Missing From Your Tool List
 
-If `masons_setup` and other `masons_*` tools are not in your available tools list, the plugin failed to load. Common causes:
+Diagnose by the SHAPE of the gap — which tools are missing, not just that something is.
 
-### Cause 1: Gateway needs to load the plugin
+1. **Get the reference roster.** Call `masons_upgrade`. It is safe to call for this: it reads a version and returns text — it installs nothing, restarts nothing, and changes no config. Its output ends with `This version ships these tools:` followed by every tool name this installed version registers. **Read only that section.** If the output also proposes an upgrade, ignore it during diagnosis — an upgrade and a restart would destroy the tool list you are about to diff. Mention the available update to the user only after the diagnosis.
 
-The gateway may not have loaded the plugin yet. Restart it:
+   If `masons_upgrade` itself is not in your tool list, that absence is itself evidence: you are in the every-tool-missing shape — go to Branch 1. If you still need the reference roster, ask the user to run `cat ~/.openclaw/extensions/agent-network/openclaw.plugin.json` and read `contracts.tools`.
 
-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.
+2. **Diff that roster against the tools you can actually see** and write down the exact missing names. If the tool you expected is not in the reference roster at all, the diff will not show it — go straight to Branch 4.
 
-### Cause 2: Install did not go through OpenClaw
+3. **Work the branch below whose shape matches**, in the order given. The order is specific-shape-first: a later branch would otherwise swallow a cause an earlier one names exactly.
 
-If the plugin was installed by copying files manually instead of using the OpenClaw plugin installer, reinstall it through OpenClaw so plugin checks run:
+**Each branch is a candidate to check, not a verdict.** The plugin cannot read the Host's resolved tool policy from inside the agent, so nothing here can be confirmed without the operator. Tell the user which cause you are checking and why; never report one as established fact, and never announce a fix as done until they confirm it. Every branch ends at the same escalation.
+
+The tool policy is the owner's configuration. Propose the edit and let them apply it — do not widen an allowlist yourself.
+
+### Branch 1: EVERY `masons_*` tool is missing — two candidates, told apart by one command
+
+Do not assume the plugin failed to load. A tool policy can remove the whole roster and produce exactly the same shape: an `alsoAllow` naming only retired tool names — for example only `masons_setup`, which no longer exists — removes the ENTIRE roster while the plugin is loaded and healthy.
+
+Ask the user to run this and paste the output:
+
+```
+openclaw plugins inspect agent-network --runtime
+```
+
+**Candidate A — the plugin is ABSENT from that output.** It did not load. Two fixes:
+
+- **Fix A1 — the gateway has not loaded the plugin yet.** Restart it:
+  1. Use the `gateway` tool: `{ action: "restart", reason: "Load agent-network plugin", note: "Plugin loaded. 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.
+- **Fix A2 — the install did not go through OpenClaw.** If the plugin was installed by copying files manually instead of using the OpenClaw plugin installer, reinstall it through OpenClaw so plugin checks run:
+
+  ```
+  openclaw plugins install @masons/agent-network --force
+  ```
+
+  Then restart the gateway (Fix A1).
+
+**Candidate B — the plugin is PRESENT with its tools registered.** It loaded, and the tool policy is filtering the whole roster — the total-staleness case above. Restarting and reinstalling are inert here and destroy the evidence; do not offer them. The fix is the allowlist edit in **Branch 3**.
+
+### Branch 2: exactly `masons_link_identity` and `masons_unlink_identity` are missing
+
+Check this before Branch 3 — this shape is a subset of "some tools missing", and the general branch would swallow it.
+
+Those two tools are registered as **optional** tools. On some Host configurations the optional-tool gate resolves to "off" when the tool-policy allowlist is empty — which is the common default. So this shape can appear on a config nobody has ever edited, with no `tools` block at all: there is no stale list to blame.
+
+Do not tell the user their plugin is outdated on this shape alone — an outdated install is Branch 4, not exactly these two.
+
+The remedy is the same allowlist entry as **Branch 3**: naming the plugin's tools is what makes the allowlist non-empty, and that is what brings optional tools through.
+
+### Branch 3: SOME tools are missing while others are present
+
+The plugin loaded — you can see part of its roster — so the Host's resolved tool policy is not naming the rest. Name the exact missing tools when you explain this. **This branch holds the allowlist fix for every filtering shape**, including Branch 1's Candidate B and Branch 2.
+
+**Why this happens:** a plugin tool reaches the model only when the resolved tool policy names it — via `*` (which is what `tools.profile: "full"` sets), `group:plugins`, the plugin id `agent-network`, or the tool's exact name. The restrictive named profiles (`minimal`, `coding`, `messaging`) expand to core tools only, so under any of them this plugin's tools need an explicit `tools.alsoAllow` entry. A hand-written per-name list then goes stale the moment a release ships a tool it does not name, and nothing reports an error.
+
+**Ask the user to check `tools.profile` and `tools.alsoAllow` in `~/.openclaw/openclaw.json`, and suggest:**
+
+- **Durable fix (offer this first):** add `group:plugins` — or the plugin id `agent-network` — to `tools.alsoAllow`, merged into whatever `tools` block they already have. One entry covers every tool this plugin ships, now and after every future upgrade. Do not propose a `tools.profile` value: their profile governs their whole tool surface, not just this plugin's.
+- **Narrow fallback:** add each missing tool name to `tools.alsoAllow`. This works today and needs maintenance on every upgrade that ships a new tool.
+
+**Migration example (the live case of this branch):** an allowlist written before this plugin renamed its bootstrap tool still names `masons_setup`, which no longer exists — replace that entry with `masons_link`. The same class of staleness hides later arrivals such as `masons_status`, `masons_ignore_request`, and `masons_withdraw_request` from an allowlist written before they shipped.
+
+### Branch 4: the tool you expected is not in the reference roster at all
+
+Nothing is filtering it — this installed version does not ship it, so the install predates the tool. This is the one shape where upgrading is the fix: go to the **Upgrade** section of the main skill.
+
+### Escalation (every branch)
+
+When the branches do not settle it, the operator holds the only ground truth. Ask the user to run these and paste the output back to you:
 
 ```
-openclaw plugins install @masons/agent-network --force
+openclaw plugins inspect agent-network --runtime
+openclaw doctor
 ```
 
-Then restart the gateway (see Cause 1).
+`plugins inspect --runtime` reports what the plugin registered with the Host. It is not guaranteed to be identical to the list the model is shown, so treat a difference between it and your own tool list as evidence about the Host's filtering — report both lists to the user rather than deciding which one is wrong.
 
 ### Important
 
-**NEVER simulate tool output when tools are unavailable.** If `masons_setup` is not in your tool list, you cannot start real setup, mint runtime keys, or complete login. Always tell the user the plugin needs to be fixed first.
+**NEVER simulate tool output when tools are unavailable.** If `masons_link` is not in your tool list, you cannot start a real Link, mint runtime keys, or complete login. Always tell the user the plugin needs to be fixed first.