@masons/agent-network 0.6.23 → 0.6.25

package/dist/handoff.js

@@ -15,6 +15,7 @@ export async function beginBridgeHandoff(options) {
         .toString("base64url");
     const apiBase = normalizeHttpBase(options.apiHost);
     let sessionId;
+    let ownerChoiceUrl;
     try {
         const initRes = await apiFetch(`${apiBase}/v1/cli-handoff/init`, {
             method: "POST",
@@ -24,25 +25,29 @@ export async function beginBridgeHandoff(options) {
             }),
         });
         if (!initRes.ok) {
-            throw new SetupFlowError(`Setup service rejected init (HTTP ${initRes.status}). Retry in a moment; if it persists, check that ${apiBase} is reachable and not behind a proxy that strips the request body.`);
+            throw new SetupFlowError(`Link service rejected init (HTTP ${initRes.status}). Retry in a moment; if it persists, check that ${apiBase} is reachable and not behind a proxy that strips the request body.`);
         }
         const initBody = (await initRes.json());
         if (typeof initBody.session_id !== "string" ||
             initBody.session_id.length === 0) {
-            throw new SetupFlowError("Setup service returned a malformed response (missing session_id). Retry; if it persists, this is a server-side bug worth reporting.");
+            throw new SetupFlowError("Link service returned a malformed response (missing session_id). Retry; if it persists, this is a server-side bug worth reporting.");
+        }
+        if (typeof initBody.owner_choice_url !== "string" ||
+            initBody.owner_choice_url.length === 0) {
+            throw new SetupFlowError("The Link service did not return a usable owner_choice_url in the init response (missing, empty, or not a string). Most likely this Services deployment predates the owner_choice_url contract (masons.ai#4320) — upgrade the server, or use a plugin release that predates the contract. This runtime does not compose that address itself.");
         }
         sessionId = initBody.session_id;
+        ownerChoiceUrl = initBody.owner_choice_url;
     }
     catch (err) {
         if (err instanceof SetupFlowError)
             throw err;
         const message = err instanceof Error ? err.message : "unknown error";
-        throw new SetupFlowError(`Could not reach the setup service at ${apiBase} (${message}). Retry in a moment.`);
+        throw new SetupFlowError(`Could not reach the Link service at ${apiBase} (${message}). Retry in a moment.`);
     }
-    const handoffUrl = `${options.idpBaseUrl}/console/handoff?session=${encodeURIComponent(sessionId)}`;
     return {
         sessionId,
-        handoffUrl,
+        handoffUrl: verifyOwnerChoiceUrl(ownerChoiceUrl, options.idpBaseUrl, options.idpBaseUrlIsDefault ?? false),
         apiBase,
         privateKey,
         expiresAt: Date.now() + HANDOFF_TIMEOUT_MS,
@@ -50,20 +55,58 @@ export async function beginBridgeHandoff(options) {
 }
 export async function completeBridgeHandoff(session) {
     const envelope = await pollForCompletion(session.apiBase, session.sessionId, session.expiresAt);
+    return readBridgeEnvelope(session, envelope);
+}
+export async function collectBridgeHandoffOnce(session) {
+    assertHandoffDeadlineActive(session.expiresAt);
+    const res = await apiFetch(pollUrl(session.apiBase, session.sessionId), {
+        method: "GET",
+    });
+    if (res.status === 404)
+        return { outcome: "gone" };
+    if (!res.ok)
+        return { outcome: "pending" };
+    let body;
+    try {
+        body = (await res.json());
+    }
+    catch (err) {
+        return { outcome: "spoiled", error: unreadableDelivery(err) };
+    }
+    if (body.status !== "completed" || !body.payload)
+        return { outcome: "pending" };
+    try {
+        return {
+            outcome: "delivered",
+            handoff: readBridgeEnvelope(session, body.payload),
+        };
+    }
+    catch (err) {
+        return {
+            outcome: "spoiled",
+            error: err instanceof SetupFlowError ? err : unreadableDelivery(err),
+        };
+    }
+}
+function unreadableDelivery(err) {
+    const detail = err instanceof Error ? err.message : "unknown error";
+    return new SetupFlowError(`The handoff bridge released this Link's runtime key but the response could not be read (${detail}), so the key was lost with it.`);
+}
+function readBridgeEnvelope(session, envelope) {
     let payload;
     try {
         payload = decryptBridgeEnvelope(session.privateKey, envelope);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : "unknown error";
-        throw new SetupFlowError(`Handoff received but could not be decrypted (${message}). The link may have been tampered with — re-run setup. If it keeps failing, your network may be inserting a TLS-terminating proxy that mangled the ciphertext.`);
+        throw new SetupFlowError(`Handoff received but could not be decrypted (${message}). The link may have been tampered with — re-run Link. If it keeps failing, your network may be inserting a TLS-terminating proxy that mangled the ciphertext.`);
     }
     assertHandoffDeadlineActive(session.expiresAt);
     if (typeof payload.token !== "string" ||
         !RUNTIME_KEY_PATTERN.test(payload.token) ||
         typeof payload.agent?.handle !== "string" ||
         typeof payload.agent?.agentId !== "string") {
-        throw new SetupFlowError("Handoff payload did not match the expected shape. Re-run setup; if it keeps happening, this is a server-side bug worth reporting.");
+        throw new SetupFlowError("Handoff payload did not match the expected shape. Re-run Link; if it keeps happening, this is a server-side bug worth reporting.");
     }
     return {
         token: payload.token,
@@ -76,12 +119,15 @@ export async function completeBridgeHandoff(session) {
         },
     };
 }
+function pollUrl(apiBase, sessionId) {
+    return `${apiBase}/v1/cli-handoff/${encodeURIComponent(sessionId)}/poll`;
+}
 async function pollForCompletion(apiBase, sessionId, expiresAt) {
     let lastNetworkError;
     while (Date.now() < expiresAt) {
         let res;
         try {
-            res = await apiFetch(`${apiBase}/v1/cli-handoff/${encodeURIComponent(sessionId)}/poll`, { method: "GET" });
+            res = await apiFetch(pollUrl(apiBase, sessionId), { method: "GET" });
         }
         catch (err) {
             if (err instanceof PlatformNetworkError) {
@@ -94,7 +140,7 @@ async function pollForCompletion(apiBase, sessionId, expiresAt) {
         if (Date.now() >= expiresAt)
             break;
         if (res.status === 404) {
-            throw new SetupFlowError("Handoff session expired before the runtime key was delivered. Re-run setup.");
+            throw new SetupFlowError("Handoff session expired before the runtime key was delivered. Re-run Link.");
         }
         if (!res.ok) {
             await sleepBeforeNextPoll(expiresAt);
@@ -109,8 +155,8 @@ async function pollForCompletion(apiBase, sessionId, expiresAt) {
         await sleepBeforeNextPoll(expiresAt);
     }
     throw new SetupFlowError(lastNetworkError
-        ? `Handoff timed out before the runtime key was delivered; the last poll could not reach ${apiBase} (${lastNetworkError.message}). Re-run setup; if you're behind a proxy that blocks long-running fetches, retry on a different network.`
-        : "Handoff timed out before the runtime key was delivered. Re-run setup; if you're behind a proxy that blocks long-running fetches, retry on a different network.");
+        ? `Handoff timed out before the runtime key was delivered; the last poll could not reach ${apiBase} (${lastNetworkError.message}). Re-run Link; if you're behind a proxy that blocks long-running fetches, retry on a different network.`
+        : "Handoff timed out before the runtime key was delivered. Re-run Link; if you're behind a proxy that blocks long-running fetches, retry on a different network.");
 }
 async function sleepBeforeNextPoll(expiresAt) {
     const remainingMs = expiresAt - Date.now();
@@ -144,6 +190,34 @@ function decryptBridgeEnvelope(privateKey, envelope) {
     ]);
     return JSON.parse(plaintext.toString("utf-8"));
 }
+function verifyOwnerChoiceUrl(ownerChoiceUrl, idpBaseUrl, idpBaseUrlIsDefault) {
+    const configured = parseAbsoluteUrl(idpBaseUrl);
+    if (!configured) {
+        throw new SetupFlowError("This Runtime's identity provider (idpBaseUrl) is not an absolute http(s) URL, so the owner-choice address the Link service named cannot be verified. Set idpBaseUrl for this channel to an absolute http(s) URL and re-run Link.");
+    }
+    const named = parseAbsoluteUrl(ownerChoiceUrl);
+    if (!named) {
+        throw new SetupFlowError("The Link service named an owner-choice address that is not a valid absolute URL; refusing to direct the owner's browser to it. Retry; if it persists, this is a server-side bug worth reporting.");
+    }
+    if (named.protocol !== "http:" && named.protocol !== "https:") {
+        throw new SetupFlowError(`The Link service named an owner-choice address using the "${named.protocol}" scheme, which is not an address a browser can be sent to; refusing it. Retry; if it persists, this is a server-side bug worth reporting.`);
+    }
+    if (named.origin !== configured.origin) {
+        const anchor = idpBaseUrlIsDefault
+            ? "the built-in default identity provider (idpBaseUrl is not set)"
+            : "your configured identity provider (idpBaseUrl)";
+        throw new SetupFlowError(`The Link service named an owner-choice address on ${named.origin}, which is not ${anchor}: ${configured.origin}. Refusing to direct the owner's browser there. If your deployment's identity provider genuinely moved, update idpBaseUrl for this channel. If you did not expect this, do not change configuration — the server may be misdirecting your sign-in; report it.`);
+    }
+    return named.href;
+}
+function parseAbsoluteUrl(value) {
+    try {
+        return new URL(value);
+    }
+    catch {
+        return null;
+    }
+}
 function normalizeHttpBase(apiHost) {
     const trimmed = apiHost.replace(/\/+$/, "");
     if (/^https?:\/\//.test(trimmed))

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAUrE,OAAO,EACL,kCAAkC,EAEnC,MAAM,oCAAoC,CAAC;AA8D5C,wBAAgB,uBAAuB,CACrC,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,iBAAiB,EAAE,MAAM,GAAG,IAAI,EAChC,mBAAmB,GAAE,mBAAmB,GAAG,IAA+B,GACzE,MAAM,GAAG,SAAS,CA6EpB;AAKD,UAAU,iBAAiB;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,YAAY,CACV,IAAI,EAAE,OAAO,EACb,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3C,IAAI,CAAC;IACR,yBAAyB,CAAC,MAAM,EAAE;QAChC,EAAE,EAAE,MAAM,CAAC;QACX,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,OAAO,kCAAkC,CAAC;KACrD,GAAG,IAAI,CAAC;IACT,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC;CACnE;AAqCD,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAaI,iBAAiB;CAoahC,CAAC;AAEF,eAAe,MAAM,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAUrE,OAAO,EACL,kCAAkC,EAEnC,MAAM,oCAAoC,CAAC;AA8D5C,wBAAgB,uBAAuB,CACrC,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,iBAAiB,EAAE,MAAM,GAAG,IAAI,EAChC,mBAAmB,GAAE,mBAAmB,GAAG,IAA+B,GACzE,MAAM,GAAG,SAAS,CA6EpB;AAKD,UAAU,iBAAiB;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,YAAY,CACV,IAAI,EAAE,OAAO,EACb,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3C,IAAI,CAAC;IACR,yBAAyB,CAAC,MAAM,EAAE;QAChC,EAAE,EAAE,MAAM,CAAC;QACX,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,OAAO,kCAAkC,CAAC;KACrD,GAAG,IAAI,CAAC;IACT,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC;CACnE;AAqCD,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAaI,iBAAiB;CAsahC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/plugin.js

@@ -194,19 +194,21 @@ const plugin = {
             if (!state.hasCredentials) {
                 dynamicContext =
                     "[Context: Agent Network] You recently installed the agent network plugin " +
-                        "but it is not yet authorized. If your current channel sender is the verified " +
-                        "OpenClaw owner, call masons_setup to generate a MASONS handoff URL here. " +
-                        "If owner authority is unavailable, tell your user to run this terminal fallback: " +
-                        "`openclaw channels login --channel agent-network`. Browser sign-in handles " +
-                        "agent selection or creation. After setup completes, OpenClaw will reload and " +
+                        "but it is not yet authorized. Link finishes in this conversation: if your " +
+                        "current channel sender is the verified OpenClaw owner, call masons_link to " +
+                        "generate a MASONS handoff URL here. If owner authority is unavailable here, " +
+                        "ask the owner to start Link from a channel their OpenClaw is configured for; " +
+                        "only as a last resort, `openclaw channels login --channel agent-network` in a " +
+                        "terminal. Browser sign-in handles " +
+                        "agent selection or creation. After the Link completes, OpenClaw will reload and " +
                         "the agent network tools will become available.";
                 if (state.pendingTarget) {
-                    dynamicContext += ` After setup, send a connection request to ${state.pendingTarget} — they invited your user to join.`;
+                    dynamicContext += ` After the Link completes, send a connection request to ${state.pendingTarget} — they invited your user to join.`;
                 }
             }
             else if (state.needsProfile) {
                 dynamicContext =
-                    "[Context: Agent Network] You are set up on the agent network, but your agent's profile is empty. " +
+                    "[Context: Agent Network] You are linked to 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). " +
                         "Without a profile, other agents can't see who you are — " +
@@ -216,7 +218,7 @@ const plugin = {
                 }
             }
             else if (state.pendingTarget) {
-                dynamicContext = `[Context: Agent Network] You are set up on the agent network. You have a pending connection — call the masons_send_connection_request tool with targetHandle "${state.pendingTarget}" to send a connection request.`;
+                dynamicContext = `[Context: Agent Network] You are linked to the agent network. You have a pending connection — call the masons_send_connection_request tool with targetHandle "${state.pendingTarget}" to send a connection request.`;
             }
             if (!dynamicContext &&
                 state.hasCredentials &&

package/dist/tools.d.ts

@@ -1,3 +1,4 @@
+import { type ChannelSetupResult } from "./channel-setup.js";
 interface ToolContent {
     content: Array<{
         type: "text";
@@ -25,6 +26,8 @@ interface ToolApi {
     }): void;
 }
 export declare function _resetToolsForTesting(): void;
+export declare function ownerRefusalText(reason: "known-non-owner" | "ambiguous"): string;
+export declare function formatChannelSetupResult(result: ChannelSetupResult): string;
 export declare function registerTools(api: ToolApi): void;
 export {};
 //# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAmFA,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,WAAW;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,KAAK,WAAW,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,cAAc,GAAG,IAAI,GAAG,SAAS,CAAC;AAE3E,UAAU,OAAO;IACf,YAAY,CACV,IAAI,EAAE,cAAc,GAAG,WAAW,EAWlC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAC7D,IAAI,CAAC;CACT;AAoDD,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAodD,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAqlChD"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAuBA,OAAO,EAEL,KAAK,kBAAkB,EAGxB,MAAM,oBAAoB,CAAC;AAuD5B,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,WAAW;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,KAAK,WAAW,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,cAAc,GAAG,IAAI,GAAG,SAAS,CAAC;AAE3E,UAAU,OAAO;IACf,YAAY,CACV,IAAI,EAAE,cAAc,GAAG,WAAW,EAWlC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAC7D,IAAI,CAAC;CACT;AAkED,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AA6XD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,iBAAiB,GAAG,WAAW,GACtC,MAAM,CAqBR;AAGD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAoC3E;AAyBD,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAmoChD"}

package/dist/tools.js

@@ -1,6 +1,7 @@
 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 { _resetChannelSetupForTesting, getDefaultChannelSetupOptions, startOrGetChannelSetup, } from "./channel-setup.js";
 import { clearTargetHandle, extractNetworkConfig, getConnectorClient, getDmScope, getPendingTarget, hasApiKey, isProfileNeeded, markProfileComplete, removeIdentityLinks, requireApiKey, requireConversationManager, requirePlatformConfig, writeIdentityLinks, } from "./config.js";
 import { getOwnerHandle } from "./environment-context.js";
 import { classifyIdentityError, formatCanonicalNode, formatKindLabel, } from "./identity-format.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,37 +222,20 @@ function toRecord(value) {
 function stringValue(value) {
     return typeof value === "string" && value.length > 0 ? value : undefined;
 }
-function terminalSetupInstructions() {
-    return [
-        "Run this in the terminal where OpenClaw is installed:",
-        "",
-        "  openclaw channels login --channel agent-network",
-        "",
-        "It will:",
-        "  1. Display a MASONS handoff URL.",
-        "  2. Open it in your browser and sign in.",
-        "  3. Pick an existing agent or create a new one.",
-        "  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.",
-    ].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,53 +243,69 @@ 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.",
+            "This Link is still open, so asking me again returns this same URL, not a new one — open the one above.",
             "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`.',
+            "This result stands until the owner asks to start over: to re-link or change Node, call masons_link with start_over: true.",
         ].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.",
             "",
-            terminalSetupInstructions(),
+            LINK_RETRY_GUIDANCE,
         ].join("\n");
     }
     return [
-        result.message ?? "Agent Network setup failed.",
-        "Ask again to retry, or use the terminal fallback:",
+        result.message ?? "Agent Network Link failed.",
         "",
-        terminalSetupInstructions(),
+        LINK_RETRY_GUIDANCE,
     ].join("\n");
 }
+const LINK_RETRY_GUIDANCE = [
+    "Call masons_link again in this conversation and I will issue a fresh Link URL — the whole flow finishes here.",
+    "Last resort, only if that keeps failing: the owner can run `openclaw channels login --channel agent-network` in a terminal.",
+].join("\n");
 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. After a",
+            "Link has completed in this process, pass start_over: true to re-link",
+            "or link a different Node; a plain call re-reports the completed one.",
+            "To check on a Link in progress (after the owner opens the URL), call",
+            "with NO arguments — start_over would discard the pending Link and",
+            "issue a fresh URL instead of confirming the one the owner completed.",
+            "",
+            "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,16 +314,23 @@ 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.",
             })),
+            start_over: Type.Optional(Type.Boolean({
+                description: "Discard whatever this Runtime is holding — a Link still in " +
+                    "progress, or a Link that already completed — and issue a fresh " +
+                    "Link URL. After a completed Link, pass start_over: true to " +
+                    "re-link or link a different Node; without it a repeat call " +
+                    "re-reports the completed result instead of starting again.",
+            })),
         }),
         execute: async (_id, params) => {
             const authority = resolveSetupAuthority();
@@ -326,27 +340,23 @@ export function registerTools(api) {
             const invitedBy = typeof params.invitedBy === "string" && params.invitedBy.length > 0
                 ? params.invitedBy
                 : undefined;
-            const existing = consumeChannelSetupStatus();
             let result;
             try {
-                result = existing
-                    ? existing
-                    : await startOrGetChannelSetup({
-                        ...getSetupOptionsFromToolContext(ctx),
-                        invitedBy,
-                    });
+                result = await startOrGetChannelSetup({
+                    ...getSetupOptionsFromToolContext(ctx),
+                    invitedBy,
+                    startOver: params.start_over === true,
+                });
             }
             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: [
@@ -402,7 +412,7 @@ export function registerTools(api) {
             catch (err) {
                 if (err instanceof PlatformApiError) {
                     if (err.status === 401) {
-                        return textResult("Authentication failed. The runtime key may be invalid. Ask the user to run `openclaw channels login --channel agent-network`.");
+                        return textResult("Authentication failed. The runtime key may be invalid. Ask the owner to re-link here: call masons_link with start_over: true.");
                     }
                     if (err.status === 422) {
                         return textResult(`Validation error: ${err.message}`);
@@ -483,7 +493,7 @@ export function registerTools(api) {
                             : "This Services deployment does not serve the connection-request endpoint. Nothing was sent.");
                     }
                     if (err.status === 401) {
-                        return textResult("Authentication failed. The runtime key may be invalid. Ask the user to run `openclaw channels login --channel agent-network`.");
+                        return textResult("Authentication failed. The runtime key may be invalid. Ask the owner to re-link here: call masons_link with start_over: true.");
                     }
                     return textResult(`Connection request failed: ${err.message}`);
                 }
@@ -567,7 +577,7 @@ export function registerTools(api) {
             catch (err) {
                 if (err instanceof PlatformApiError) {
                     if (err.status === 401) {
-                        return textResult("Authentication failed. The runtime key may be invalid. Ask the user to run `openclaw channels login --channel agent-network`.");
+                        return textResult("Authentication failed. The runtime key may be invalid. Ask the owner to re-link here: call masons_link with start_over: true.");
                     }
                     if (err.status === 404) {
                         return textResult("This Services deployment does not serve the packaged connection-request endpoint. Nothing was read.");
@@ -755,7 +765,7 @@ export function registerTools(api) {
             catch (err) {
                 if (err instanceof PlatformApiError) {
                     if (err.status === 401) {
-                        return textResult("Authentication failed. The runtime key may be invalid. Ask the user to run `openclaw channels login --channel agent-network`.");
+                        return textResult("Authentication failed. The runtime key may be invalid. Ask the owner to re-link here: call masons_link with start_over: true.");
                     }
                     return textResult(`Failed to list connections: ${err.message}`);
                 }
@@ -881,36 +891,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.25";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

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

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.25",
   "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)",