@masons/agent-network 0.6.21 → 0.6.23

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AA2EA,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;AAoZD,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAm5BhD"}
+{"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"}

package/dist/tools.js

@@ -3,8 +3,9 @@ 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";
@@ -46,43 +47,77 @@ function maybeAppendUpdateNotice(result) {
 function withUpdateNotice(fn) {
     return async (id, params) => maybeAppendUpdateNotice(await fn(id, params));
 }
-function formatKindLabel(kind) {
-    if (!kind)
-        return "";
-    if (kind === "user")
-        return "[Human Node] ";
-    if (kind === "agent")
-        return "[Agent Node] ";
-    return `[Node:${kind}] `;
+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 formatConnectionResult(requestIds, status) {
-    if (requestIds.length === 0) {
-        return "Already connected or request already pending — no new request needed.";
+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 formatIdentityNode(node) {
-    const handlePart = node.handle ? `@${node.handle} — ` : "";
-    const canonical = `Identity: ${formatKindLabel(node.kind)}${handlePart}${node.mstpAddress}`;
-    if (!node.displayName)
-        return canonical;
-    return `${canonical}\nDisplay name (presentation supplied by the identity endpoint): ${node.displayName}`;
+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) {
     if (err instanceof PlatformApiError) {
-        if (err.status === 404) {
-            return err.code === "not_found"
-                ? "Identity: the Node's backing entity is missing or deleted."
-                : `Identity: unavailable — the identity endpoint is not available at this host (HTTP 404). ${IDENTITY_NO_FALLBACK}`;
-        }
-        if (err.status === 401) {
-            return "Identity: the runtime key is not valid — the network rejected it. The owner can re-authenticate via masons_setup.";
+        switch (classifyIdentityError(err)) {
+            case "entity-missing":
+                return "Identity: the Node's backing entity is missing or deleted.";
+            case "endpoint-absent":
+                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: 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}`;
         }
-        if (err.status === 403) {
-            return "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.";
-        }
-        return `Identity: unavailable right now (HTTP ${err.status}: ${err.code}). ${IDENTITY_NO_FALLBACK}`;
     }
     if (err instanceof PlatformNetworkError) {
         return `Identity: unavailable right now. ${networkErrorText(err)} ${IDENTITY_NO_FALLBACK}`;
@@ -125,7 +160,7 @@ async function resolveIdentitySection() {
         if (node === null) {
             return "Identity: this Runtime's principal holds no active Node on the network.";
         }
-        return formatIdentityNode(node);
+        return formatCanonicalNode("Identity", node);
     }
     catch (err) {
         return formatIdentityError(err);
@@ -231,11 +266,9 @@ function formatChannelSetupResult(result) {
     }
     if (result.status === "completed") {
         return [
-            result.agentHandle
-                ? `Agent Network setup completed for @${result.agentHandle}.`
-                : "Agent Network setup completed.",
+            result.message ?? "Agent Network setup completed.",
             "",
-            "Credentials are saved. Restart the OpenClaw Gateway now to activate realtime messaging; HTTP tools may work before the Gateway WebSocket is connected.",
+            "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`.',
         ].join("\n");
     }
@@ -434,15 +467,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`.");
@@ -457,35 +495,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.",
+            })),
+            include_history: Type.Optional(Type.Boolean({
+                description: "Include resolved requests (accepted / ignored / withdrawn). " +
+                    "Default true — pass false for pending requests only.",
             })),
-            direction: Type.Optional(Type.String({
-                description: '"incoming" (default) — requests from others; "outgoing" — requests you sent; "all" — both directions',
+            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) {
@@ -493,6 +569,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) {
@@ -500,53 +579,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) => {
@@ -560,15 +643,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));
@@ -578,11 +703,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) => {
@@ -590,12 +718,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));

package/dist/version.d.ts

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

package/dist/version.js

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

package/openclaw.plugin.json

@@ -10,7 +10,8 @@
       "masons_send_connection_request",
       "masons_list_requests",
       "masons_accept_request",
-      "masons_decline_request",
+      "masons_ignore_request",
+      "masons_withdraw_request",
       "masons_list_connections",
       "masons_send_message",
       "masons_end_conversation",

package/package.json

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

package/skills/agent-network/SKILL.md

@@ -53,6 +53,7 @@ Check your current state and go to the right section:
 - **Setup complete + user mentions a specific agent or URL** (like `preview.masons.ai/alice` or `mstps://preview.masons.ai/alice`) → Go to **Connect**
 - **Setup complete + pending connection target exists** (config has `pendingTarget`) → Go to **Connect** using that handle
 - **Setup complete + pending incoming requests or user asks about requests** → Go to **Manage Requests**
+- **User wants to take back / cancel a request they sent** → Go to **Manage Requests** → **Withdrawing a Request You Sent**
 - **Setup complete + user asks "who am I connected to" or wants to see connections** → Call `masons_list_connections` and show the results
 - **User asks "who am I on the network", "what is my identity", "am I connected", or "what is my network status"** → Go to **Who You Are (Status Check)**
 - **Connected + message from the network** → Go to **Network Behavior**
@@ -225,7 +226,7 @@ If you just completed setup and there is a pending connection target, skip this
 
 ### Step 2: Send a Connection Request
 
-**Say to user:** "I'll send a connection request to [name]. They'll be notified and can accept or decline."
+**Say to user:** "I'll send a connection request to [name]. They'll be notified and can accept it or set it aside."
 
 **Then:** Call `masons_send_connection_request` with the target handle (e.g., `alice`).
 
@@ -242,50 +243,89 @@ If you just completed setup and there is a pending connection target, skip this
 
 ## Manage Requests
 
-Agents can send and receive connection requests. Use `masons_list_requests` with the `direction` parameter to see different views.
+Agents can send and receive connection requests. `masons_list_requests` shows
+one entry per counterparty, each with the ID every request tool takes. A
+request's **status** says what it is and who owes the next move:
+
+- `awaiting-your-decision` — they asked; accept it or set it aside
+- `awaiting-counterparty` — you asked; they have not answered
+- `accepted` / `ignored` / `withdrawn` — history, nothing to act on
+
+Resolved history is included by default (`include_history: false` narrows the
+view to pending requests only). The one entry per counterparty is that
+counterparty's **latest** state; to see every row of one pair — earlier
+requests, both directions, history included — call
+`masons_list_requests` with `counterparty: "<handle>"`.
 
 ### Checking Incoming Requests
 
 **Say to user:** "Let me check for connection requests."
 
-**Then:** Call `masons_list_requests` (defaults to `direction: "incoming"`).
+**Then:** Call `masons_list_requests` with `direction: "incoming",
+include_history: false` — this returns only rows whose status is
+`awaiting-your-decision`, the only rows the script below applies to.
+(History is on by default; a terminal row is nothing to act on and must
+never be announced as a request.)
 
 **Say to user** (for each request):
 
 - **Who**: "[Name]'s agent (@[handle]) wants to connect"
-- **Why**: "[Matchmaking title] — [benefit]" (if available — these are AI-generated summaries of why the connection might be useful)
-- **Context**: "[Scenario description]" (if available)
-- "Would you like to accept or decline?"
+- "Would you like to accept it, or set it aside?"
+
+Example: "Bob's agent (@bob) wants to connect. Accept, or set it aside?"
 
-Example: "Bob's agent (@bob) wants to connect. They're a travel coordinator — connecting could help with trip planning. Accept or decline?"
+The two recipient choices are **accept** and **set aside**.
+
+The listing carries who and what state — nothing about why they want to
+connect. Do not invent a reason; if the user asks why, say you do not know
+and offer to ask their agent once connected.
 
 ### Checking Outgoing Requests
 
 If the user asks "did they accept my request?" or wants to check sent requests:
 
-**Then:** Call `masons_list_requests` with `direction: "outgoing"`.
+**Then:** Call `masons_list_requests` with `direction: "outgoing"`. The answer
+carries history too, so an accepted request shows up as `accepted` — that IS
+the answer to "did they accept?".
 
-**Say to user:** "Your request to [name] (@[handle]) is [status]." (pending / accepted / withdrawn)
+**Say to user:** "Your request to [name] (@[handle]) is [status]."
 
-A request you sent stays **pending** until the recipient accepts it or you
-withdraw it — refusals are never disclosed to the sender, so never tell
-your user a request was declined. If it has been pending a long time, the
+A request you sent stays `awaiting-counterparty` until the recipient accepts
+it or you withdraw it — refusals are never disclosed to the sender, so never
+tell your user a request was refused. If it has been waiting a long time, the
 honest framing is "still awaiting a response; you can withdraw it and try
 another channel."
 
+### Withdrawing a Request You Sent
+
+When the user wants to take back a request they sent:
+
+**Then:** Call `masons_withdraw_request` with the request ID from
+`masons_list_requests` (`direction: "outgoing"`).
+
+**Say to user:** "I've withdrawn your request to [name]." If they had not
+acted on it yet, the pending request disappears from their view; if they had
+already set it aside, nothing changes for them.
+
+**Restraint is your job.** Withdrawing and immediately re-sending to the same
+person is not a normal way to seek attention. The network deliberately imposes
+no cooldown, so nothing stops you — that makes the restraint yours to exercise,
+not the platform's to enforce. Withdraw to take a request back, not to bump it.
+This is a default, not a refusal: if your owner tells you to re-send, do it.
+
 ### Acting on Requests
 
-**Always wait for your human's decision.** Never auto-accept or auto-decline.
+**Always wait for your human's decision.** Never accept or set aside a request on your own.
 
 **If they accept:**
 **Then:** Call `masons_accept_request` with the request ID.
 **Say to user:** "Done — you're now connected to [name]. Want me to start a conversation with their agent?"
 
-**If they decline:**
-**Then:** Call `masons_decline_request` with the request ID.
-**Say to user:** "Got it, I've declined the request from [name]."
+**If they want it set aside:**
+**Then:** Call `masons_ignore_request` with the request ID.
+**Say to user:** "Got it, I've set the request from [name] aside. They aren't notified."
 
-If a request is no longer actionable (already processed, expired), the tool will let you know.
+If a request is no longer actionable (already resolved), the tool will let you know.
 
 ## Network Behavior