@masons/agent-network 0.6.22 → 0.6.24

package/dist/tools.js

@@ -1,16 +1,22 @@
 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";
 import { getOwnerHandle } from "./environment-context.js";
 import { classifyIdentityError, formatCanonicalNode, formatKindLabel, } from "./identity-format.js";
 import { ownerNotesQueue } from "./owner-notes.js";
-import { acceptRequest, declineRequest, getIdentity, listConnections, listRequests, PlatformApiError, PlatformNetworkError, requestConnection, updateProfile, } from "./platform-client.js";
+import { acceptRequest, getIdentity, ignoreRequest, isPackagedTombstone, listConnections, listRequests, PlatformApiError, PlatformNetworkError, requestConnection, updateProfile, withdrawRequest, } from "./platform-client.js";
 import { isServicesRetainedReplyContext } from "./services-retained-reply-context.js";
 import { getCurrentTurnChannelId, getCurrentTurnIsOwnerNonConsuming, getCurrentTurnOwnerSignal, } from "./turn-context.js";
 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`;
 }
@@ -47,11 +53,61 @@ function maybeAppendUpdateNotice(result) {
 function withUpdateNotice(fn) {
     return async (id, params) => maybeAppendUpdateNotice(await fn(id, params));
 }
-function formatConnectionResult(requestIds, status) {
-    if (requestIds.length === 0) {
-        return "Already connected or request already pending — no new request needed.";
+function counterpartyName(c) {
+    if (isPackagedTombstone(c)) {
+        return c.handle ? `@${c.handle}` : (c.mstpAddress ?? c.id);
+    }
+    return c.displayName ?? (c.handle ? `@${c.handle}` : c.mstpAddress);
+}
+function suppressionKey(item) {
+    const c = item.counterparty;
+    if (isPackagedTombstone(c))
+        return `tombstone:${c.mstpAddress ?? c.id}`;
+    const address = c.mstpAddress;
+    if (!address || address.endsWith("/"))
+        return null;
+    return address;
+}
+function collapseToCounterpartyGrain(items) {
+    const seen = new Set();
+    const rows = [];
+    for (const item of items) {
+        if (item.shadowed)
+            continue;
+        const key = suppressionKey(item);
+        if (key !== null) {
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+        }
+        rows.push(item);
+    }
+    return rows;
+}
+function directionLabel(status) {
+    if (status === "awaiting-your-decision")
+        return "incoming";
+    if (status === "awaiting-counterparty")
+        return "outgoing";
+    return "history";
+}
+function formatAlreadyResolved(status, act) {
+    const nothing = `Nothing to ${act} —`;
+    if (status == null) {
+        return `${nothing} this request is no longer pending.`;
     }
-    return `Connection request sent. Status: ${status}. The other agent's owner will be notified.`;
+    const terminal = status === "accepted" || status === "ignored" || status === "withdrawn";
+    return terminal
+        ? `${nothing} this request is already resolved as "${status}".`
+        : `${nothing} this request is not in a state you can ${act} (status: "${status}").`;
+}
+function formatVerb404(err, verbLabel) {
+    return err.code === "not_found"
+        ? "Request not found, or it is not addressable from your perspective. Use masons_list_requests to see current requests."
+        : `This Services deployment does not serve the ${verbLabel} endpoint. Nothing changed — the request is unchanged.`;
+}
+function quoteRejected(value) {
+    return `"${typeof value === "string" ? value : JSON.stringify(value)}"`;
 }
 const IDENTITY_NO_FALLBACK = "This is not an answer — do not assume any locally-cached handle or name is this Runtime's identity.";
 function formatIdentityError(err) {
@@ -63,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}`;
@@ -101,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();
@@ -132,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) {
@@ -164,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:",
         "",
@@ -177,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:",
@@ -202,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(),
@@ -239,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",
@@ -257,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.",
             })),
@@ -289,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: [
@@ -417,15 +481,20 @@ export function registerTools(api) {
             const targetHandle = params.targetHandle;
             let result;
             try {
-                result = await requestConnection(cfg, apiKey, {
-                    targetHandle,
-                    variants: ["distribute", "receive"],
-                });
+                result = await requestConnection(cfg, apiKey, targetHandle);
             }
             catch (err) {
                 if (err instanceof PlatformApiError) {
+                    if (err.status === 409 && err.code === "already_connected") {
+                        if (getPendingTarget()) {
+                            await clearTargetHandle();
+                        }
+                        return textResult(`Already connected with @${targetHandle} — no request needed. Use masons_send_message to reach them.`);
+                    }
                     if (err.status === 404) {
-                        return textResult(`Agent @${targetHandle} not found. Check the handle and try again.`);
+                        return textResult(err.code === "target_not_found"
+                            ? `Agent @${targetHandle} not found. Check the handle and try again.`
+                            : "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`.");
@@ -440,35 +509,73 @@ export function registerTools(api) {
             if (getPendingTarget()) {
                 await clearTargetHandle();
             }
-            return textResult(formatConnectionResult(result.requestIds, result.status));
+            const request = result.request;
+            if (request === null) {
+                return textResult("The network accepted the call but returned no request object — " +
+                    "the outcome is unknown; use masons_list_requests to check.");
+            }
+            const who = counterpartyName(request.counterparty);
+            if (request.status === "accepted") {
+                return textResult(`Connection established with ${who}. They had already requested a connection with you, so sending yours completed it — nothing is pending. You can now send messages using masons_send_message.`);
+            }
+            if (!result.created) {
+                return textResult(`A connection request to ${who} is already pending — no new request was sent.`);
+            }
+            return textResult(`Connection request sent to ${who}. Status: ${request.status}. The other agent's owner will be notified.`);
         }),
     });
     api.registerTool({
         name: "masons_list_requests",
-        description: "List connection requests — incoming from other agents, outgoing ones you sent, or all.",
+        description: "List connection requests — one entry per counterparty, keyed by the " +
+            "request ID every request tool takes. Shows what is awaiting your " +
+            "decision, what is awaiting theirs, and resolved history. Each entry " +
+            "is that counterparty's latest state; pass counterparty to see every " +
+            "row of one pair instead.",
         parameters: Type.Object({
-            status: Type.Optional(Type.String({
-                description: 'Filter by status: "pending" (default), "accepted", "declined", "withdrawn", or "all". ' +
-                    'Note: "declined" only ever matches requests YOU declined (incoming). ' +
-                    "A recipient's refusal of your outgoing request is never disclosed — " +
-                    'outgoing requests stay "pending" until accepted or withdrawn, so ' +
-                    'filtering outgoing by "declined" always returns empty.',
+            direction: Type.Optional(Type.Union([
+                Type.Literal("all"),
+                Type.Literal("incoming"),
+                Type.Literal("outgoing"),
+            ], {
+                description: '"all" (default) — both; "incoming" — awaiting YOUR decision; ' +
+                    '"outgoing" — awaiting the counterparty. Direction is derived ' +
+                    "from each request's status; it is not a state you can filter " +
+                    "the network by.",
             })),
-            direction: Type.Optional(Type.String({
-                description: '"incoming" (default) — requests from others; "outgoing" — requests you sent; "all" — both directions',
+            include_history: Type.Optional(Type.Boolean({
+                description: "Include resolved requests (accepted / ignored / withdrawn). " +
+                    "Default true — pass false for pending requests only.",
+            })),
+            counterparty: Type.Optional(Type.String({
+                description: "Handle of one agent — show the full per-pair history with " +
+                    "@handle — bypasses the one-row-per-counterparty collapse.",
             })),
         }),
         execute: withUpdateNotice(async (_id, params) => {
             const cfg = requirePlatformConfig();
             const apiKey = requireApiKey();
-            const status = params.status ?? "pending";
-            const direction = params.direction ?? "incoming";
+            const rawDirection = params.direction;
+            if (rawDirection !== undefined &&
+                rawDirection !== "all" &&
+                rawDirection !== "incoming" &&
+                rawDirection !== "outgoing") {
+                return textResult(`${quoteRejected(rawDirection)} is not a direction — use "all", "incoming", or "outgoing". Nothing was read.`);
+            }
+            const rawHistory = params.include_history;
+            if (rawHistory !== undefined && typeof rawHistory !== "boolean") {
+                return textResult(`${quoteRejected(rawHistory)} is not a boolean — include_history takes true or false. Nothing was read.`);
+            }
+            const direction = rawDirection ?? "all";
+            const includeHistory = rawHistory ?? true;
+            const rawCounterparty = params.counterparty;
+            const counterparty = typeof rawCounterparty === "string"
+                ? rawCounterparty.replace(/^@/, "").trim() || undefined
+                : undefined;
             let result;
             try {
                 result = await listRequests(cfg, apiKey, {
-                    status,
-                    direction,
                     limit: 100,
+                    ...(counterparty ? { counterparty } : {}),
                 });
             }
             catch (err) {
@@ -476,6 +583,9 @@ export function registerTools(api) {
                     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`.");
                     }
+                    if (err.status === 404) {
+                        return textResult("This Services deployment does not serve the packaged connection-request endpoint. Nothing was read.");
+                    }
                     return textResult(`Failed to list requests: ${err.message}`);
                 }
                 if (err instanceof PlatformNetworkError) {
@@ -483,53 +593,57 @@ export function registerTools(api) {
                 }
                 throw err;
             }
-            if (result.total === 0) {
-                const dirLabel = direction === "all"
-                    ? ""
-                    : direction === "outgoing"
-                        ? "outgoing "
-                        : "incoming ";
-                return textResult(`No ${dirLabel}${status === "all" ? "" : `${status} `}connection requests.`);
-            }
-            const lines = result.items.map((item) => {
-                const dir = item.direction ?? direction;
-                const node = dir === "outgoing" ? item.toNode : item.fromNode;
-                const otherName = node?.displayName || node?.handle || "unknown";
-                const otherHandle = node?.handle || "unknown";
-                const kindLabel = formatKindLabel(node?.kind);
-                const dirArrow = dir === "outgoing" ? "→" : "←";
-                const parts = [
-                    `• ${dirArrow} ${kindLabel}${otherName} (@${otherHandle})`,
-                    `  ID: ${item.id} | Variant: ${item.variant} | Status: ${item.status}`,
-                ];
-                if (item.matchmaking?.title) {
-                    parts.push(`  Why: ${item.matchmaking.title}`);
-                }
-                if (item.matchmaking?.benefit) {
-                    parts.push(`  Benefit: ${item.matchmaking.benefit}`);
-                }
-                if (item.matchmaking?.scenario) {
-                    parts.push(`  Context: ${item.matchmaking.scenario}`);
-                }
-                return parts.join("\n");
+            const filtered = result.items.filter((item) => {
+                const label = directionLabel(item.status);
+                if (label === "history")
+                    return includeHistory;
+                return direction === "all" || direction === label;
             });
-            const dirLabel = direction === "all"
-                ? ""
-                : direction === "outgoing"
-                    ? "outgoing "
-                    : "incoming ";
-            const suffix = direction === "incoming" || direction === "all"
-                ? "\n\nUse masons_accept_request or masons_decline_request with the ID to act on incoming requests."
+            const rows = counterparty
+                ? filtered
+                : collapseToCounterpartyGrain(filtered);
+            const scope = direction !== "all" &&
+                rows.every((item) => directionLabel(item.status) === direction)
+                ? `${direction} `
                 : "";
-            return textResult(`${result.total} ${dirLabel}${status === "all" ? "" : `${status} `}request(s):\n\n${lines.join("\n\n")}${suffix}`);
+            const withWho = counterparty ? ` with @${counterparty}` : "";
+            const moreLine = result.nextCursor !== null
+                ? "\n\nMore requests exist beyond this page — this is the most recent page, not the whole history."
+                : "";
+            if (rows.length === 0) {
+                return textResult(`No ${scope}${includeHistory ? "" : "pending "}connection requests${withWho}.${moreLine}`);
+            }
+            const lines = rows.map((item) => {
+                const node = item.counterparty;
+                const label = directionLabel(item.status);
+                const arrow = label === "incoming" ? "←" : label === "outgoing" ? "→" : "·";
+                const kindLabel = formatKindLabel(node.kind);
+                const handle = node.handle ? `@${node.handle}` : "no handle";
+                const shadowMark = item.shadowed ? " | shadowed" : "";
+                return [
+                    `• ${arrow} ${kindLabel}${counterpartyName(node)} (${handle})`,
+                    `  ID: ${item.id} | Status: ${item.status} | ${label}${shadowMark}`,
+                ].join("\n");
+            });
+            const hints = [];
+            if (rows.some((item) => item.status === "awaiting-your-decision")) {
+                hints.push("Use masons_accept_request or masons_ignore_request with the ID to act on requests awaiting your decision.");
+            }
+            if (rows.some((item) => item.status === "awaiting-counterparty")) {
+                hints.push("Use masons_withdraw_request with the ID to take back a request you sent.");
+            }
+            const suffix = hints.length > 0 ? `\n\n${hints.join("\n")}` : "";
+            return textResult(`${rows.length} ${scope}request(s)${withWho}:\n\n${lines.join("\n\n")}${suffix}${moreLine}`);
         }),
     });
     api.registerTool({
         name: "masons_accept_request",
-        description: "Accept an incoming connection request from another agent.",
+        description: "Accept a connection request awaiting your decision. Takes the ID " +
+            "masons_list_requests shows for that request; the whole request is " +
+            "resolved in one act.",
         parameters: Type.Object({
             requestId: Type.String({
-                description: "ID of the connection request to accept",
+                description: "ID of the connection request to accept, as shown by masons_list_requests",
             }),
         }),
         execute: withUpdateNotice(async (_id, params) => {
@@ -543,15 +657,57 @@ export function registerTools(api) {
             const requestId = params.requestId;
             try {
                 const result = await acceptRequest(cfg, apiKey, requestId);
-                const node = result.counterparty;
-                const who = node?.displayName || node?.handle || "that Node";
+                if (result.outcome === "already_resolved") {
+                    return textResult(formatAlreadyResolved(result.status, "accept"));
+                }
+                const node = result.request?.counterparty;
+                const who = node ? counterpartyName(node) : "that Node";
                 const handle = node?.handle ? ` (@${node.handle})` : "";
                 const kindLabel = formatKindLabel(node?.kind);
+                if (result.idempotent) {
+                    return textResult(`Already connected with ${kindLabel}${who}${handle} — you accepted this request earlier and nothing changed now. You can send messages using masons_send_message.`);
+                }
                 return textResult(`Connected with ${kindLabel}${who}${handle}! You can now send messages using masons_send_message.`);
             }
             catch (err) {
                 if (err instanceof PlatformApiError && err.status === 404) {
-                    return textResult("Request not found or already processed. Use masons_list_requests to see current requests.");
+                    return textResult(formatVerb404(err, "accept"));
+                }
+                if (err instanceof PlatformNetworkError) {
+                    return textResult(networkErrorText(err));
+                }
+                throw err;
+            }
+        }),
+    });
+    api.registerTool({
+        name: "masons_ignore_request",
+        description: "Set aside a connection request awaiting your decision. " +
+            "This resolves the whole request on your side, silently: the sender is " +
+            "not notified and sees no change — there is no refusal they can observe.",
+        parameters: Type.Object({
+            requestId: Type.String({
+                description: "ID of the connection request to set aside, as shown by masons_list_requests",
+            }),
+        }),
+        execute: withUpdateNotice(async (_id, params) => {
+            const cfg = requirePlatformConfig();
+            const apiKey = requireApiKey();
+            const requestId = params.requestId;
+            try {
+                const result = await ignoreRequest(cfg, apiKey, requestId);
+                if (result.outcome === "already_resolved") {
+                    return textResult(formatAlreadyResolved(result.status, "set aside"));
+                }
+                if (result.idempotent) {
+                    return textResult("This request was already set aside earlier; nothing changed.");
+                }
+                return textResult("Request set aside. The whole request is resolved on your side. " +
+                    "The sender is not notified and sees no change.");
+            }
+            catch (err) {
+                if (err instanceof PlatformApiError && err.status === 404) {
+                    return textResult(formatVerb404(err, "ignore"));
                 }
                 if (err instanceof PlatformNetworkError) {
                     return textResult(networkErrorText(err));
@@ -561,11 +717,14 @@ export function registerTools(api) {
         }),
     });
     api.registerTool({
-        name: "masons_decline_request",
-        description: "Decline an incoming connection request from another agent.",
+        name: "masons_withdraw_request",
+        description: "Withdraw a connection request YOU sent — one awaiting the counterparty. " +
+            "(masons_accept_request and masons_ignore_request act on requests " +
+            "awaiting your decision.) Takes the ID masons_list_requests shows for " +
+            "that request; the whole request is resolved in one act.",
         parameters: Type.Object({
             requestId: Type.String({
-                description: "ID of the connection request to decline",
+                description: "ID of the outgoing connection request to withdraw, as shown by masons_list_requests",
             }),
         }),
         execute: withUpdateNotice(async (_id, params) => {
@@ -573,12 +732,21 @@ export function registerTools(api) {
             const apiKey = requireApiKey();
             const requestId = params.requestId;
             try {
-                await declineRequest(cfg, apiKey, requestId);
-                return textResult("Request declined.");
+                const result = await withdrawRequest(cfg, apiKey, requestId);
+                if (result.outcome === "already_resolved") {
+                    return textResult(formatAlreadyResolved(result.status, "withdraw"));
+                }
+                if (result.idempotent) {
+                    return textResult("This request was already withdrawn earlier; nothing changed.");
+                }
+                return textResult("Request withdrawn. A new request to the same agent can be sent later. " +
+                    "If the recipient had not acted on it yet, the pending request " +
+                    "disappears from their view; if they had already set it aside, " +
+                    "nothing changes for them.");
             }
             catch (err) {
                 if (err instanceof PlatformApiError && err.status === 404) {
-                    return textResult("Request not found or already processed. Use masons_list_requests to see current requests.");
+                    return textResult(formatVerb404(err, "withdraw"));
                 }
                 if (err instanceof PlatformNetworkError) {
                     return textResult(networkErrorText(err));
@@ -727,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. " +