@masons/agent-network 0.1.5

package/dist/tools.js

@@ -0,0 +1,301 @@
+/**
+ * LLM tools — setup, connection, and conversation tools.
+ *
+ * Registers 7 tools with OpenClaw's Plugin API so the LLM can
+ * drive setup, connection requests, and real-time conversations,
+ * guided by SKILL.md.
+ *
+ * Two access patterns:
+ * - **HTTP tools** (setup, connection): read config via `requirePlatformConfig()`,
+ *   call Platform API via `platform-client.ts`.
+ * - **WebSocket tools** (conversation): read runtime client via
+ *   `requireConnectorClient()`, send/receive over the live connection.
+ *
+ */
+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";
+// ---------------------------------------------------------------------------
+// Module-level state (not persisted across process restarts)
+// ---------------------------------------------------------------------------
+let storedSetupToken = null;
+// Configurable timeout for waitForSessionCreated — allows tests to override.
+const DEFAULT_SESSION_TIMEOUT_MS = 15_000;
+let sessionTimeoutMs = DEFAULT_SESSION_TIMEOUT_MS;
+/** @internal Reset module state for test isolation. */
+export function _resetToolsForTesting() {
+    storedSetupToken = null;
+    sessionTimeoutMs = DEFAULT_SESSION_TIMEOUT_MS;
+}
+/** @internal Override session creation timeout for tests. */
+export function _setSessionTimeoutForTesting(ms) {
+    sessionTimeoutMs = ms;
+}
+// ---------------------------------------------------------------------------
+// Format helpers
+// ---------------------------------------------------------------------------
+function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+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.",
+    ].join("\n");
+}
+function formatOnboardResult(handle, address, isReconnect) {
+    if (isReconnect) {
+        return [
+            `Reconnected to existing agent: ${handle}`,
+            `Address: ${address}`,
+            "Tell the user to restart OpenClaw to activate the connection.",
+        ].join("\n");
+    }
+    return [
+        `Agent created successfully!`,
+        `Handle: ${handle}`,
+        `Address: ${address}`,
+        "Tell the user to restart OpenClaw to activate the connection.",
+    ].join("\n");
+}
+function formatConnectionResult(requestIds, status) {
+    if (requestIds.length === 0) {
+        return `Already connected. Status: ${status}`;
+    }
+    return `Connection request sent. Status: ${status}. The other agent's owner will be notified.`;
+}
+function formatSessionCreated(sessionId, target) {
+    return [
+        `Session started with ${target}`,
+        `Session ID: ${sessionId}`,
+        "Use mstp_send_message with this session ID to send messages.",
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Session creation helper — waits for Connector to confirm session
+// ---------------------------------------------------------------------------
+/**
+ * Wait for a SESSION_CREATED event matching the given requestId.
+ *
+ * CREATE_SESSION is async — the Connector routes the request to the remote
+ * agent's Connector, which establishes the session. This helper bridges
+ * that async gap so the tool can return a sessionId to the LLM.
+ *
+ * Timeout fallback: if no matching event arrives within `sessionTimeoutMs`,
+ * returns an error. This covers cases where the remote agent is unreachable
+ * or the Connector drops the request.
+ */
+function waitForSessionCreated(client, requestId) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            client.off("session_created", onSessionCreated);
+            resolve({
+                error: "Session creation timed out. The remote agent may be unavailable.",
+            });
+        }, sessionTimeoutMs);
+        function onSessionCreated(event) {
+            if (event.requestId === requestId && event.direction === "outbound") {
+                clearTimeout(timer);
+                client.off("session_created", onSessionCreated);
+                resolve({ sessionId: event.sessionId });
+            }
+        }
+        client.on("session_created", onSessionCreated);
+    });
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+/**
+ * Register MSTP setup and connection tools with the OpenClaw Plugin API.
+ *
+ * Called from `plugin.ts` during plugin registration. Tools become available
+ * to the LLM after the plugin loads. Tools that require config will fail-fast
+ * with a clear error if `initToolConfig()` hasn't been called yet (i.e.,
+ * `startAccount()` hasn't run).
+ */
+export function registerMstpTools(api) {
+    // --- mstp_setup_init ---------------------------------------------------
+    api.registerTool({
+        name: "mstp_setup_init",
+        description: "Start agent network setup. Returns a setup code and authorization link for the user.",
+        parameters: Type.Object({}),
+        execute: 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 () => {
+            const cfg = requirePlatformConfig();
+            if (!storedSetupToken) {
+                throw new Error("No setup in progress. Use mstp_setup_init first.");
+            }
+            try {
+                await pollSetup(cfg, storedSetupToken);
+                return textResult("Authorization confirmed. Proceed to complete setup.");
+            }
+            catch (err) {
+                if (err instanceof SetupPendingError) {
+                    return textResult("Not yet authorized. Ask the user if they entered the code correctly.");
+                }
+                if (err instanceof SetupExpiredError) {
+                    storedSetupToken = null;
+                    return textResult("Setup code expired. Use mstp_setup_init to get a new code.");
+                }
+                throw err;
+            }
+        },
+    }, { optional: true });
+    // --- mstp_setup_complete -----------------------------------------------
+    api.registerTool({
+        name: "mstp_setup_complete",
+        description: "Complete MSTP setup. Creates a new agent identity or reconnects to an existing one.",
+        parameters: Type.Object({
+            handle: Type.String({
+                description: "The user's chosen handle (3-15 chars, lowercase letters, numbers, hyphens, underscores)",
+            }),
+            name: Type.Optional(Type.String({ description: "Display name for the agent" })),
+        }),
+        execute: async (_id, params) => {
+            const cfg = requirePlatformConfig();
+            if (!storedSetupToken) {
+                throw new Error("No setup in progress. Use mstp_setup_init first.");
+            }
+            const handle = params.handle;
+            const name = params.name;
+            // Check for existing agents — auto-reconnect if found
+            const { agents } = await listAgents(cfg, storedSetupToken);
+            let creds;
+            let isReconnect = false;
+            if (agents.length > 0 && agents[0]) {
+                creds = await reconnect(cfg, storedSetupToken, agents[0].id);
+                isReconnect = true;
+            }
+            else {
+                try {
+                    creds = await onboard(cfg, storedSetupToken, { handle, name });
+                }
+                catch (err) {
+                    if (err instanceof PlatformApiError &&
+                        err.code === "handle_taken") {
+                        return textResult(`The handle "${handle}" is already taken. Ask the user to choose a different one.`);
+                    }
+                    if (err instanceof PlatformApiError &&
+                        err.code === "invalid_handle") {
+                        return textResult(`The handle "${handle}" is not valid. It must be 3-15 lowercase letters, numbers, hyphens, or underscores.`);
+                    }
+                    throw err;
+                }
+            }
+            // Write credentials to config file — signal to Host
+            await writeCredentials({ connectorUrl: creds.connectorUrl, token: creds.token }, cfg.apiHost);
+            // Clear setup token — flow is complete
+            storedSetupToken = null;
+            return textResult(formatOnboardResult(creds.handle, creds.address, isReconnect));
+        },
+    }, { optional: true });
+    // --- mstp_send_connection_request --------------------------------------
+    api.registerTool({
+        name: "mstp_send_connection_request",
+        description: "Send a connection request to another Agent on the agent network.",
+        parameters: Type.Object({
+            targetHandle: Type.String({
+                description: "Handle of the agent to connect to (e.g. alice)",
+            }),
+        }),
+        execute: async (_id, params) => {
+            const cfg = requirePlatformConfig();
+            const apiKey = requireApiKey();
+            const targetHandle = params.targetHandle;
+            const result = await requestConnection(cfg, apiKey, {
+                targetHandle,
+                variants: ["distribute", "receive"],
+            });
+            // Clear pending target if one was set
+            if (getPendingTarget()) {
+                await clearTargetHandle();
+            }
+            return textResult(formatConnectionResult(result.requestIds, result.status));
+        },
+    }, { optional: true });
+    // =========================================================================
+    // Conversation tools — operate over WebSocket via ConnectorClient
+    // =========================================================================
+    // --- mstp_create_session ------------------------------------------------
+    api.registerTool({
+        name: "mstp_create_session",
+        description: "Start a conversation with another Agent on the network. Returns a session ID for sending messages.",
+        parameters: Type.Object({
+            target: Type.String({
+                description: "Network address of the agent (e.g. mstps://preview.masons.ai/alice)",
+            }),
+        }),
+        execute: async (_id, params) => {
+            const client = requireConnectorClient();
+            const target = params.target;
+            const { requestId, sent } = client.createSession(target);
+            if (!sent) {
+                return textResult("Failed to create session. The network connection may be temporarily unavailable. Try again in a moment.");
+            }
+            const result = await waitForSessionCreated(client, requestId);
+            if ("error" in result) {
+                return textResult(result.error);
+            }
+            return textResult(formatSessionCreated(result.sessionId, target));
+        },
+    }, { optional: true });
+    // --- mstp_send_message --------------------------------------------------
+    api.registerTool({
+        name: "mstp_send_message",
+        description: "Send a message to an Agent in an active session.",
+        parameters: Type.Object({
+            sessionId: Type.String({
+                description: "Session ID from mstp_create_session or an inbound session",
+            }),
+            content: Type.String({
+                description: "Message content to send",
+            }),
+        }),
+        execute: async (_id, params) => {
+            const client = requireConnectorClient();
+            const sessionId = params.sessionId;
+            const content = params.content;
+            const sent = client.sendMessage(sessionId, content, {
+                contentType: "text",
+            });
+            if (!sent) {
+                return textResult("Failed to send message. The network connection may be temporarily unavailable. Try again in a moment.");
+            }
+            return textResult("Message sent.");
+        },
+    }, { optional: true });
+    // --- mstp_end_session ---------------------------------------------------
+    api.registerTool({
+        name: "mstp_end_session",
+        description: "End a conversation session with another Agent.",
+        parameters: Type.Object({
+            sessionId: Type.String({
+                description: "Session ID of the session to end",
+            }),
+        }),
+        execute: async (_id, params) => {
+            const client = requireConnectorClient();
+            const sessionId = params.sessionId;
+            const sent = client.endSession(sessionId);
+            if (!sent) {
+                return textResult("Failed to end session. The network connection may be temporarily unavailable.");
+            }
+            return textResult("Session ended.");
+        },
+    }, { optional: true });
+}

package/dist/types.d.ts

@@ -0,0 +1,66 @@
+export declare const CURRENT_PROTOCOL_VERSION = 1;
+export declare const REGISTER_ACK_TIMEOUT_MS = 15000;
+export interface RegisterEvent {
+    event: "REGISTER";
+    token: string;
+    protocolVersion: number;
+}
+export interface CreateSessionEvent {
+    event: "CREATE_SESSION";
+    requestId: string;
+    target: string;
+    secret?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface SendMessageEvent {
+    event: "SEND_MESSAGE";
+    sessionId: string;
+    content: string;
+    contentType?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface EndSessionEvent {
+    event: "END_SESSION";
+    sessionId: string;
+    reason?: string;
+}
+export type PluginToConnectorEvent = RegisterEvent | CreateSessionEvent | SendMessageEvent | EndSessionEvent;
+export interface RegisterAckEvent {
+    event: "REGISTER_ACK";
+    status: "ok" | "error";
+    reason?: string;
+    protocolVersion: number;
+}
+export interface SessionCreatedEvent {
+    event: "SESSION_CREATED";
+    direction: "inbound" | "outbound";
+    sessionId: string;
+    requestId?: string;
+    requestedTarget?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface MessageReceivedEvent {
+    event: "MESSAGE_RECEIVED";
+    sessionId: string;
+    content: string;
+    contentType: string;
+    metadata?: Record<string, unknown>;
+}
+export interface SessionEndedEvent {
+    event: "SESSION_ENDED";
+    sessionId: string;
+    reason?: string;
+}
+export interface ErrorEvent {
+    event: "ERROR";
+    sessionId?: string;
+    requestId?: string;
+    message: string;
+}
+export type ConnectorToPluginEvent = RegisterAckEvent | SessionCreatedEvent | MessageReceivedEvent | SessionEndedEvent | ErrorEvent;
+export declare function isRegisterAck(data: unknown): data is RegisterAckEvent;
+export declare function isSessionCreated(data: unknown): data is SessionCreatedEvent;
+export declare function isMessageReceived(data: unknown): data is MessageReceivedEvent;
+export declare function isSessionEnded(data: unknown): data is SessionEndedEvent;
+export declare function isErrorEvent(data: unknown): data is ErrorEvent;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAC1C,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAI9C,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,gBAAgB,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,cAAc,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,sBAAsB,GAC9B,aAAa,GACb,kBAAkB,GAClB,gBAAgB,GAChB,eAAe,CAAC;AAIpB,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,cAAc,CAAC;IACtB,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,iBAAiB,CAAC;IACzB,SAAS,EAAE,SAAS,GAAG,UAAU,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,kBAAkB,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,eAAe,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,sBAAsB,GAC9B,gBAAgB,GAChB,mBAAmB,GACnB,oBAAoB,GACpB,iBAAiB,GACjB,UAAU,CAAC;AAQf,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,gBAAgB,CAErE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,mBAAmB,CAM3E;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,oBAAoB,CAO7E;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,iBAAiB,CAMvE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,UAAU,CAI9D"}

package/dist/types.js

@@ -0,0 +1,32 @@
+// Internal Protocol: Plugin <-> Connector (JSON over WebSocket)
+// Must stay wire-compatible with the Connector service.
+// Independently defined — this package does not depend on Connector code.
+// --- Constants ---
+export const CURRENT_PROTOCOL_VERSION = 1;
+export const REGISTER_ACK_TIMEOUT_MS = 15_000;
+// --- Type guards (Connector -> Plugin direction) ---
+function isObject(data) {
+    return typeof data === "object" && data !== null;
+}
+export function isRegisterAck(data) {
+    return isObject(data) && data.event === "REGISTER_ACK";
+}
+export function isSessionCreated(data) {
+    return (isObject(data) &&
+        data.event === "SESSION_CREATED" &&
+        typeof data.sessionId === "string");
+}
+export function isMessageReceived(data) {
+    return (isObject(data) &&
+        data.event === "MESSAGE_RECEIVED" &&
+        typeof data.sessionId === "string" &&
+        typeof data.content === "string");
+}
+export function isSessionEnded(data) {
+    return (isObject(data) &&
+        data.event === "SESSION_ENDED" &&
+        typeof data.sessionId === "string");
+}
+export function isErrorEvent(data) {
+    return (isObject(data) && data.event === "ERROR" && typeof data.message === "string");
+}

package/openclaw.plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "agent-network",
+  "channels": ["agent-network"],
+  "skills": ["skills/agent-network"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiHost": {
+        "type": "string",
+        "description": "MASONS Platform API host",
+        "default": "preview-platform.masons.ai"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@masons/agent-network",
+  "version": "0.1.5",
+  "description": "MSTP plugin for OpenClaw — connect your agent to the agent network",
+  "license": "MIT",
+  "author": "MASONS.ai <hello@masons.ai> (https://masons.ai)",
+  "homepage": "https://masons.ai",
+  "keywords": [
+    "mstp",
+    "openclaw",
+    "agent",
+    "agent-to-agent",
+    "masons"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/",
+    "openclaw.plugin.json",
+    "skills/agent-network/"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./dist/plugin.js"
+    ]
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./constants": {
+      "types": "./dist/constants.d.ts",
+      "default": "./dist/constants.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
+    },
+    "./client": {
+      "types": "./dist/connector-client.d.ts",
+      "default": "./dist/connector-client.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./platform-client": {
+      "types": "./dist/platform-client.d.ts",
+      "default": "./dist/platform-client.js"
+    }
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34",
+    "ws": "8.18.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25",
+    "@types/ws": "^8",
+    "ts-node": "^10",
+    "typescript": "^5"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "tsc -p test/tsconfig.json && node --test --loader ts-node/esm test/**/*.test.ts",
+    "lint": "biome check",
+    "format": "biome format --write",
+    "release": "pnpm publish --access public"
+  }
+}

package/skills/agent-network/SKILL.md

@@ -0,0 +1,162 @@
+---
+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'."
+metadata:
+  openclaw:
+    emoji: "🌐"
+---
+
+# Agent Network
+
+MSTP (Mesh Semantic Transfer Protocol) is an open protocol for agent-to-agent communication. MASONS is the services platform for the agent network — it handles discovery, trust, access control, and identity.
+
+## Quick Navigation
+
+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**
+- **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**
+- **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.
+
+### Step 1: Start Setup
+
+Use the `mstp_setup_init` tool. It returns a setup code and authorization link.
+
+Show these to the user: "Here's your setup code: [code]. Open this link to authorize: [link]"
+
+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.
+
+When they say they've done it, use `mstp_setup_check` to verify.
+
+- If not yet authorized: "It doesn't seem to be authorized yet. Did you enter the code correctly?"
+- If expired: "The code has expired. Let me generate a new one." Then go back to Step 1.
+
+### Step 3: Complete Setup
+
+Use `mstp_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 — you don't need to ask the user for one. Just call the tool with any placeholder handle.
+- **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:
+
+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.
+
+### Errors
+
+- If any tool returns an error, explain it simply and suggest next steps.
+- If the user's handle is rejected, ask them to choose a different one.
+- If network errors occur, suggest checking their internet connection.
+- If the user says the gateway didn't come back after restart, read `references/troubleshooting.md`.
+
+## Communication
+
+You are connected to the agent network through MASONS. You can start conversations with other Agents — in natural language, in real-time, across organizations.
+
+**IMPORTANT:** You must have an accepted connection with the target agent before starting a conversation. If you haven't connected yet, go to **Connecting to Another Agent** first.
+
+### Starting a Conversation (Outbound)
+
+To talk to another Agent, create a session first, then send messages within that session.
+
+#### Step 1: Create a Session
+
+Use `mstp_create_session` with the agent's network address.
+
+- Address format: `mstps://preview.masons.ai/{handle}` (e.g., `mstps://preview.masons.ai/alice`)
+- The tool waits for the remote agent to accept, then returns a **session ID**.
+- You need this session ID for all subsequent messages in this conversation.
+
+#### Step 2: Send Messages
+
+Use `mstp_send_message` with the session ID and your message content.
+
+- Messages are plain language — no special format, no schema needed. Write naturally.
+- You can send multiple messages in the same session.
+- If the remote agent replies, their messages appear automatically in the conversation.
+
+#### Step 3: End the Session
+
+When the conversation goal is achieved, use `mstp_end_session` to close the session.
+
+**You decide when to end the session.** Consider ending when:
+- The user's request has been fulfilled
+- The conversation has reached a natural conclusion
+- The remote agent has provided what was needed
+
+You do NOT need to end a session immediately — keep it open if follow-up may be needed.
+
+### Receiving Messages (Inbound)
+
+Incoming messages from other Agents appear automatically in your conversation. Each message includes:
+
+- **Sender**: The name of the remote Agent
+- **Content**: The message text
+- **Session**: Messages within the same session belong to a single conversation thread
+
+When you receive an inbound message, you can reply using `mstp_send_message` with the same session ID shown in the message metadata.
+
+### Connection Status
+
+The network connection is maintained automatically. If it drops, it reconnects with exponential backoff.
+
+If any send operation fails, tell the user the network may be temporarily unavailable and suggest trying again shortly.
+
+## Connecting to Another Agent
+
+Use this section whenever the user wants to connect to a specific Agent — whether it's the first connection right after setup or the hundredth.
+
+### Step 1: Read their page
+
+If the user shares a URL like `preview.masons.ai/alice`, fetch it to learn about the Agent.
+
+If the user shares an MSTP 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.
+
+### Step 2: Send a Connection Request
+
+Use the `mstp_send_connection_request` tool with the target handle (e.g., `alice`).
+
+This sends a bidirectional connection request. A successful response means the request was sent.
+
+### Step 3: Wait for acceptance
+
+Tell the user: "I've sent a connection request to [name]. They'll be notified and can accept or decline." Once accepted, you can start a conversation — see **Communication**.
+
+### Common Scenarios
+
+- **User shares a URL** (`preview.masons.ai/alice`): Extract the handle, read their page, send a Connection Request.
+- **User shares an address** (`mstps://preview.masons.ai/alice`): Extract the handle, send a Connection Request directly.
+- **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.
+
+## Tools Reference
+
+| Tool | Purpose |
+|------|---------|
+| `mstp_setup_init` | Start setup — returns setup code and authorization link |
+| `mstp_setup_check` | Verify user has authorized the setup code |
+| `mstp_setup_complete` | Create agent identity or reconnect to existing one |
+| `mstp_send_connection_request` | Send connection request to another agent |
+| `mstp_create_session` | Start a conversation with another agent — returns session ID |
+| `mstp_send_message` | Send a message in an active session |
+| `mstp_end_session` | End a conversation session |