@masons/agent-network 0.5.14 → 0.5.16

package/dist/tools.js

@@ -1,81 +1,28 @@
-/**
- * LLM tools — setup, connection, profile, and conversation tools.
- *
- * Registers tools with OpenClaw's Plugin API so the LLM can
- * drive setup, profile completion, connection listing, connection
- * requests, request management, and real-time conversations,
- * guided by SKILL.md.
- *
- * Two access patterns:
- * - **HTTP tools** (setup, connection): read config via `requirePlatformConfig()`,
- *   call Platform API via `platform-client.ts`.
- * - **WebSocket tools** (conversation): use `requireConversationManager()` for
- *   identity-based messaging. Session management is fully transparent.
- *
- * Session Abstraction (#741):
- * - `masons_send_message(to, content)` — sends via ConversationManager
- * - `masons_end_conversation(contact)` — ends via ConversationManager
- * (Deprecated shims masons_create_session and masons_end_session have been removed.)
- */
-import { tmpdir } from "node:os";
 import { Type } from "@sinclair/typebox";
 import { getOwnerPassportAddress } from "./channel.js";
-import { clearTargetHandle, getDmScope, getOpenClawHome, getPendingTarget, isProfileNeeded, markProfileComplete, removeIdentityLinks, requireApiKey, requireConversationManager, requirePlatformConfig, writeIdentityLinks, } from "./config.js";
+import { clearTargetHandle, getDmScope, getPendingTarget, isProfileNeeded, markProfileComplete, removeIdentityLinks, requireApiKey, requireConversationManager, requirePlatformConfig, writeIdentityLinks, } from "./config.js";
 import { getOwnerHandle } from "./environment-context.js";
 import { ownerNotesQueue } from "./owner-notes.js";
-import { acceptRequest, declineRequest, getConnectionStatus, listConnections, listRequests, PlatformApiError, requestConnection, updateProfile, } from "./platform-client.js";
+import { acceptRequest, declineRequest, listConnections, listRequests, PlatformApiError, requestConnection, updateProfile, } from "./platform-client.js";
 import { sentMessageBuffer } from "./sent-message-buffer.js";
 import { getCurrentTurnChannelId, getCurrentTurnIsOwnerNonConsuming, } from "./turn-context.js";
-import { fetchLatestVersion, getPluginVersion, getUpdateInfo, } from "./update-check.js";
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-/** Accepted field names for masons_update_profile — reject anything else. */
+import { getLatestPublishedVersion, getPluginVersion, getUpdateInfo, } from "./update-check.js";
 const PROFILE_FIELDS = new Set(["name", "scope", "about", "audience"]);
-/** CLI command to update the plugin via OpenClaw. */
 const UPGRADE_CMD = "openclaw plugins update agent-network";
-/** Fallback: manual update via npm pack + in-place extract. Used when
- *  `openclaw plugins update` fails (integrity conflict, npm cache issue, etc.)
- *  while preserving credentials and node_modules.
- *  Placeholders `{version}`, `{home}`, and `{tmpdir}` are replaced at runtime. */
-const FALLBACK_UPGRADE_CMD = "npm pack @masons/agent-network@{version} --pack-destination {tmpdir} && " +
-    "tar xzf {tmpdir}/masons-agent-network-{version}.tgz --strip-components=1 -C {home}/extensions/agent-network/ && " +
-    "cd {home}/extensions/agent-network && npm install --omit=dev && " +
-    "rm -f {tmpdir}/masons-agent-network-{version}.tgz";
-/** CLI command to restart the gateway. */
 const GATEWAY_RESTART_CMD = "openclaw gateway restart";
-/** Simple semver regex — validates x.y.z before inserting into shell commands. */
+function reinstallCmd(version) {
+    return `openclaw plugins install @masons/agent-network@${version} --force`;
+}
 const SEMVER_RE = /^\d+\.\d+\.\d+$/;
-// ---------------------------------------------------------------------------
-// Module-level state (not persisted across process restarts)
-// ---------------------------------------------------------------------------
-/**
- * Tracks the version we already tried to upgrade to this session.
- * null = no attempt yet. Set to the target version string on the first
- * normal-path attempt. If the tool is called again while current version
- * still differs, the fallback path is returned instead.
- */
 let upgradeAttemptedVersion = null;
-/** @internal Reset module state for test isolation. */
 export function _resetToolsForTesting() {
     updateNoticeShown = false;
     upgradeAttemptedVersion = null;
 }
-// ---------------------------------------------------------------------------
-// Format helpers
-// ---------------------------------------------------------------------------
 function textResult(text) {
     return { content: [{ type: "text", text }] };
 }
-// Show update notice only once per gateway session to avoid being annoying.
 let updateNoticeShown = false;
-/**
- * Append an update notice to tool output if a newer version is available.
- *
- * Called on every tool result. Shows the notice at most once per session —
- * after the first tool call surfaces it, the Agent has the information
- * and can guide the user through upgrading.
- */
 function maybeAppendUpdateNotice(result) {
     const info = getUpdateInfo();
     if (!info?.updateAvailable || updateNoticeShown)
@@ -89,28 +36,9 @@ function maybeAppendUpdateNotice(result) {
     }
     return result;
 }
-/**
- * Wrap a tool's execute function to append update notice to its output.
- *
- * Applied at registration time so every tool automatically surfaces
- * update information without modifying individual return sites.
- */
 function withUpdateNotice(fn) {
     return async (id, params) => maybeAppendUpdateNotice(await fn(id, params));
 }
-/**
- * Format a Node kind discriminator as a prefix label for list rendering.
- *
- * Returns:
- *   - "[Human Node] " when kind === "user"
- *   - "[Agent Node] " when kind === "agent"
- *   - "[Node:<kind>] " for future / unknown kinds (forward-compat per
- *     `docs/concepts/human-node-capability-obligations.md § 5` — never
- *     suppress, never crash)
- *   - "" (empty) when kind is absent — preserves backward-compatible
- *     rendering against Connector versions that have not adopted NodeRef
- *     projection.
- */
 function formatKindLabel(kind) {
     if (!kind)
         return "";
@@ -126,42 +54,18 @@ function formatConnectionResult(requestIds, status) {
     }
     return `Connection request sent. Status: ${status}. The other agent's owner will be notified.`;
 }
-// ---------------------------------------------------------------------------
-// Tool registration
-// ---------------------------------------------------------------------------
-/**
- * Register agent network tools with the OpenClaw Plugin API.
- *
- * Called from `plugin.ts` during plugin registration. Tools become available
- * to the LLM after the plugin loads. Tools that require config will fail-fast
- * with a clear error if `initToolConfig()` hasn't been called yet (i.e.,
- * `startAccount()` hasn't run).
- */
 export function registerTools(api) {
-    // --- masons_setup ---------------------------------------------------------
-    // Lightweight nudge for the no-credentials state (#1264). The legacy
-    // `masons_setup_init / check / complete` trio (removed in 0.5.0) ran the
-    // device flow inside the LLM; that's not viable for an OAuth Device
-    // Authorization Grant flow which requires terminal I/O (the user enters a
-    // user_code in their browser, returns to the terminal to pick or create
-    // an agent). This tool's only job is to surface the CLI command and let
-    // the user run it.
-    //
-    // Layer B's `before_prompt_build` hook in plugin.ts already injects this
-    // guidance for the no-credentials state — this tool is here so the LLM
-    // can reach it explicitly when the user asks "how do I set this up?"
-    // (e.g., as a fallback after a failed tool call surfaces "no credentials").
     api.registerTool({
         name: "masons_setup",
         description: [
             "Returns instructions for connecting OpenClaw to the agent network.",
             "Use when the user asks how to set up Agent Network, when other Agent",
-            "Network tools fail with a 'no credentials' / 'no API key' error, or",
+            "Network tools fail with a 'no credentials' / 'no runtime key' error, or",
             "when the user wants to switch which agent OpenClaw is driving.",
             "",
             "This tool does NOT perform setup itself — it surfaces the terminal",
-            "command. The user must run it from their shell because the device",
-            "authorization flow requires browser interaction and terminal prompts.",
+            "command. The user must run it from their shell because login requires",
+            "a browser handoff.",
         ].join("\n"),
         parameters: Type.Object({}),
         execute: async () => ({
@@ -174,21 +78,21 @@ export function registerTools(api) {
                         "  openclaw channels login --channel agent-network",
                         "",
                         "It will:",
-                        "  1. Display a short setup code and a verification URL.",
-                        "  2. Open the URL in your browser, sign in to MASONS, approve.",
-                        "  3. Return to the terminal — pick an existing agent or create a new one.",
-                        "  4. Persist credentials to openclaw.json. OpenClaw reloads the channel.",
+                        "  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 (single-Runtime semantic): if you re-run this with another",
-                        "agent on a different machine, that agent's API key is rotated and",
-                        "any previously-connected OpenClaw is disconnected. Only one",
-                        "Runtime drives an agent at a time.",
+                        "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"),
                 },
             ],
         }),
     });
-    // --- masons_update_profile ------------------------------------------------
     api.registerTool({
         name: "masons_update_profile",
         description: [
@@ -217,8 +121,6 @@ export function registerTools(api) {
             })),
         }),
         execute: withUpdateNotice(async (_id, params) => {
-            // Guard: reject unknown field names immediately so the LLM
-            // sees an actionable error and can self-correct.
             const unknownFields = Object.keys(params).filter((k) => !PROFILE_FIELDS.has(k));
             if (unknownFields.length > 0) {
                 return textResult(`Unknown field(s): ${unknownFields.join(", ")}. ` +
@@ -246,7 +148,7 @@ export function registerTools(api) {
             catch (err) {
                 if (err instanceof PlatformApiError) {
                     if (err.status === 401) {
-                        return textResult("Authentication failed. The API key may be invalid. Ask the user to re-authorize at masons.ai/device.");
+                        return textResult("Authentication failed. The runtime key may be invalid. Ask the user to run `openclaw channels login --channel agent-network`.");
                     }
                     if (err.status === 422) {
                         return textResult(`Validation error: ${err.message}`);
@@ -254,15 +156,12 @@ export function registerTools(api) {
                 }
                 throw err;
             }
-            // Completion gate: scope + about + audience must ALL be non-empty.
-            // name is set during onboard — not a completion gate.
             if (result.profile) {
                 const { scope, about, audience } = result.profile;
                 const profileComplete = scope.length > 0 && about.length > 0 && audience.length > 0;
                 if (profileComplete) {
                     await markProfileComplete();
                 }
-                // Echo saved values for LLM verification
                 const lines = [
                     "Profile updated successfully. Current profile:",
                     `• name: ${result.profile.name}`,
@@ -285,14 +184,12 @@ export function registerTools(api) {
                 }
                 return textResult(lines.join("\n"));
             }
-            // Backward compat: old Platform without profile in response
             if (profileFields.scope && profileFields.scope.length > 0) {
                 await markProfileComplete();
             }
             return textResult("Profile updated successfully. The agent's identity is now visible on the network.");
         }),
     });
-    // --- masons_send_connection_request --------------------------------------
     api.registerTool({
         name: "masons_send_connection_request",
         description: "Send a connection request to another Agent on the agent network.",
@@ -304,9 +201,6 @@ export function registerTools(api) {
         execute: withUpdateNotice(async (_id, params) => {
             const cfg = requirePlatformConfig();
             const apiKey = requireApiKey();
-            // Profile gate: block connection requests until profile is complete.
-            // Without a profile the other agent sees an anonymous stranger,
-            // making acceptance unlikely.
             if (isProfileNeeded()) {
                 return textResult("Your agent's profile is not complete yet. Without a profile, " +
                     "the other agent can't see who you are — connection requests from " +
@@ -327,20 +221,18 @@ export function registerTools(api) {
                         return textResult(`Agent @${targetHandle} not found. Check the handle and try again.`);
                     }
                     if (err.status === 401) {
-                        return textResult("Authentication failed. The API key may be invalid. Ask the user to re-authorize at masons.ai/device.");
+                        return textResult("Authentication failed. The runtime key may be invalid. Ask the user to run `openclaw channels login --channel agent-network`.");
                     }
                     return textResult(`Connection request failed: ${err.message}`);
                 }
                 throw err;
             }
-            // Clear pending target if one was set
             if (getPendingTarget()) {
                 await clearTargetHandle();
             }
             return textResult(formatConnectionResult(result.requestIds, result.status));
         }),
     });
-    // --- masons_list_requests --------------------------------------------------
     api.registerTool({
         name: "masons_list_requests",
         description: "List connection requests — incoming from other agents, outgoing ones you sent, or all.",
@@ -368,7 +260,7 @@ export function registerTools(api) {
             catch (err) {
                 if (err instanceof PlatformApiError) {
                     if (err.status === 401) {
-                        return textResult("Authentication failed. The API key may be invalid. Ask the user to re-authorize at masons.ai/device.");
+                        return textResult("Authentication failed. The runtime key may be invalid. Ask the user to run `openclaw channels login --channel agent-network`.");
                     }
                     return textResult(`Failed to list requests: ${err.message}`);
                 }
@@ -384,24 +276,9 @@ export function registerTools(api) {
             }
             const lines = result.items.map((item) => {
                 const dir = item.direction ?? direction;
-                // For incoming: sender NodeRef is in `fromNode` (since #1450 Phase 1).
-                // For outgoing: target NodeRef is in `toNode`. Both may be null when
-                // the Connector ran NodeRef enrichment but the entity record was
-                // missing. Back-compat fallback: `fromAgent` / `toAgent` carry just
-                // `{ handle, name }` from older Connector versions or the back-compat
-                // shape #1450 still emits.
                 const node = dir === "outgoing" ? item.toNode : item.fromNode;
-                const compat = dir === "outgoing" ? item.toAgent : item.fromAgent;
-                // Display fallback chain per `human-node-capability-obligations.md § 2`:
-                // NodeRef.displayName → NodeRef.handle → back-compat name → handle → "unknown".
-                const otherName = node?.displayName ||
-                    node?.handle ||
-                    compat?.name ||
-                    compat?.handle ||
-                    "unknown";
-                const otherHandle = node?.handle || compat?.handle || "unknown";
-                // Kind discriminator: surface "Human Node" / "Agent Node" / future kinds
-                // when the Connector projects `kind` per the same doc § 5 forward-compat.
+                const otherName = node?.displayName || node?.handle || "unknown";
+                const otherHandle = node?.handle || "unknown";
                 const kindLabel = formatKindLabel(node?.kind);
                 const dirArrow = dir === "outgoing" ? "→" : "←";
                 const parts = [
@@ -430,7 +307,6 @@ export function registerTools(api) {
             return textResult(`${result.total} ${dirLabel}${status === "all" ? "" : `${status} `}request(s):\n\n${lines.join("\n\n")}${suffix}`);
         }),
     });
-    // --- masons_accept_request ------------------------------------------------
     api.registerTool({
         name: "masons_accept_request",
         description: "Accept an incoming connection request from another agent.",
@@ -442,9 +318,6 @@ export function registerTools(api) {
         execute: withUpdateNotice(async (_id, params) => {
             const cfg = requirePlatformConfig();
             const apiKey = requireApiKey();
-            // Profile gate: block accepting requests until profile is complete.
-            // When a connection is established, the other agent sees your profile —
-            // an empty profile means they won't know who you are.
             if (isProfileNeeded()) {
                 return textResult("Your agent's profile is not complete yet. Without a profile, " +
                     "the other agent won't know who you are when the connection is established. " +
@@ -453,17 +326,11 @@ export function registerTools(api) {
             const requestId = params.requestId;
             try {
                 const result = await acceptRequest(cfg, apiKey, requestId);
-                // Prefer NodeRef on `counterparty` (since #1450 Phase 1); fall
-                // back to legacy `connection.{name, handle}` for older Connector
-                // versions or when enrichment returned null.
                 const node = result.counterparty;
-                const who = node?.displayName ||
-                    node?.handle ||
-                    result.connection.name ||
-                    result.connection.handle;
-                const handle = node?.handle || result.connection.handle;
+                const who = node?.displayName || node?.handle || "that Node";
+                const handle = node?.handle ? ` (@${node.handle})` : "";
                 const kindLabel = formatKindLabel(node?.kind);
-                return textResult(`Connected with ${kindLabel}${who} (@${handle})! You can now 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) {
@@ -473,7 +340,6 @@ export function registerTools(api) {
             }
         }),
     });
-    // --- masons_decline_request -----------------------------------------------
     api.registerTool({
         name: "masons_decline_request",
         description: "Decline an incoming connection request from another agent.",
@@ -498,7 +364,6 @@ export function registerTools(api) {
             }
         }),
     });
-    // --- masons_list_connections -----------------------------------------------
     api.registerTool({
         name: "masons_list_connections",
         description: "List your established connections on the agent network. Returns the name and address of each connected agent.",
@@ -513,7 +378,7 @@ export function registerTools(api) {
             catch (err) {
                 if (err instanceof PlatformApiError) {
                     if (err.status === 401) {
-                        return textResult("Authentication failed. The API key may be invalid. Ask the user to re-authorize at masons.ai/device.");
+                        return textResult("Authentication failed. The runtime key may be invalid. Ask the user to run `openclaw channels login --channel agent-network`.");
                     }
                     return textResult(`Failed to list connections: ${err.message}`);
                 }
@@ -522,22 +387,16 @@ export function registerTools(api) {
             if (result.total === 0) {
                 return textResult("No connections yet. Use masons_send_connection_request to connect with other agents.");
             }
-            const lines = result.items.map((item, i) => {
-                // NodeRef on `counterparty` (since #1450 Phase 1); falls back to
-                // legacy `name + address` for older Connector versions.
+            const lines = result.connections.map((item, i) => {
                 const node = item.counterparty;
-                const displayName = node?.displayName || node?.handle || item.name || "(unnamed)";
-                const address = node?.mstpAddress || item.address;
+                const displayName = node.displayName || node.handle || "(unnamed)";
+                const address = node.mstpAddress;
                 const kindLabel = formatKindLabel(node?.kind);
                 return `${i + 1}. ${kindLabel}${displayName} (${address})`;
             });
             return textResult(`${result.total} connection(s):\n\n${lines.join("\n")}\n\nUse masons_send_message with a handle or address to send a message.`);
         }),
     });
-    // =========================================================================
-    // Conversation tools — identity-based via ConversationManager
-    // =========================================================================
-    // --- masons_send_message --------------------------------------------------
     api.registerTool({
         name: "masons_send_message",
         description: "Send a message to a remote agent on the agent network. This is agent-to-agent communication — separate from your owner's conversation. Sessions are managed automatically — just provide the contact handle or address.",
@@ -553,33 +412,11 @@ export function registerTools(api) {
             const cm = requireConversationManager();
             const to = params.to;
             const content = params.content;
-            // Extract handle once — shared by pre-flight check and sent message buffer.
             const handle = to.startsWith("mstps://") || to.startsWith("mstp://")
                 ? to.replace(/^mstps?:\/\/[^/]+\//, "").replace(/\/+$/, "")
                 : to;
-            // --- Pre-flight: check connection status (advisory, not gate) ---
-            // If the check fails (network error, API down), proceed anyway —
-            // the Connector gate (Layer 2) is the authoritative enforcement.
-            try {
-                if (handle) {
-                    const cfg = requirePlatformConfig();
-                    const apiKey = requireApiKey();
-                    const status = await getConnectionStatus(cfg, apiKey, handle);
-                    if (status && !status.canCreateSession) {
-                        if (status.status === "pending") {
-                            return textResult(`Connection request to @${handle} is pending. Wait for the other agent to accept your request.`);
-                        }
-                        return textResult(`You are not connected to @${handle}. Send a connection request first using masons_send_connection_request.`);
-                    }
-                }
-            }
-            catch {
-                // Advisory check failed — proceed to Connector gate
-            }
             const result = await cm.send(to, content);
             if (result.status === "sent") {
-                // Record in sent message buffer so the agent-network session has
-                // context when the remote agent replies (cross-session bridge, #918).
                 sentMessageBuffer.record(handle, content);
                 return textResult("Message sent.");
             }
@@ -587,7 +424,6 @@ export function registerTools(api) {
                 "Failed to send message. The network connection may be temporarily unavailable. Try again in a moment.");
         }),
     });
-    // --- masons_end_conversation -----------------------------------------------
     api.registerTool({
         name: "masons_end_conversation",
         description: "End the conversation with a connected agent. This immediately closes the session — do not send any text reply after calling this tool.",
@@ -603,7 +439,6 @@ export function registerTools(api) {
             return textResult("Conversation ended.");
         }),
     });
-    // --- masons_note_for_owner ------------------------------------------------
     api.registerTool({
         name: "masons_note_for_owner",
         description: "Save a note for your owner (Principal). The note will be delivered " +
@@ -626,54 +461,34 @@ export function registerTools(api) {
             return textResult("Note saved. Your owner will see it in their next turn.");
         }),
     });
-    // --- masons_upgrade -------------------------------------------------------
     api.registerTool({
         name: "masons_upgrade",
         description: "Check for and install plugin updates via `openclaw plugins update`. Do not use ClawHub (it distributes skills, not plugins).",
         parameters: Type.Object({}),
-        // NOT wrapped with withUpdateNotice — this tool IS the upgrade path.
-        // Wrapping would create a circular reference in the update notice text.
         execute: async () => {
-            // Drain guard: upgrading restarts the Gateway, which clears the
-            // in-memory owner notes queue. Warn the LLM to deliver pending
-            // notes before upgrading.
             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.`);
             }
             const currentVersion = getPluginVersion();
-            // 1. Determine latest version.
-            //    Always fetch directly from npm — this is an explicit upgrade
-            //    command, not a passive check. The 24h startup cache
-            //    (checkForUpdate / getUpdateInfo) is for the withUpdateNotice
-            //    passive hint only. An explicit "upgrade" must see the real
-            //    latest version, even if it was published minutes ago.
-            const latestVersion = await fetchLatestVersion();
-            // 2. Network error — can't determine latest version.
+            const latestVersion = await getLatestPublishedVersion();
             if (!latestVersion) {
                 return textResult("Could not check for updates (network issue). Try again later.");
             }
-            // 3. Already up to date.
             if (latestVersion === currentVersion) {
-                upgradeAttemptedVersion = null; // Reset on success
+                upgradeAttemptedVersion = null;
                 return textResult(`You're on the latest version (v${currentVersion}). No update needed.`);
             }
-            // 4. Semver validation — never insert unvalidated strings into shell commands.
             if (!SEMVER_RE.test(latestVersion)) {
                 return textResult(`Registry returned an unexpected version format: "${latestVersion}". Try again later.`);
             }
-            // 5. Determine path: normal vs fallback.
             const useFallback = upgradeAttemptedVersion === latestVersion;
             if (useFallback) {
-                // Fallback path — previous normal-path attempt for this version didn't work.
-                upgradeAttemptedVersion = null; // Reset so next call starts fresh
-                const home = getOpenClawHome();
-                const fallbackCmd = FALLBACK_UPGRADE_CMD.replaceAll("{tmpdir}", tmpdir())
-                    .replaceAll("{home}", home)
-                    .replaceAll("{version}", latestVersion);
+                upgradeAttemptedVersion = null;
+                const fallbackCmd = reinstallCmd(latestVersion);
                 return textResult([
-                    `Update to v${latestVersion} — manual update (the automatic update command may not have detected the new version).`,
+                    `Update to v${latestVersion} — reinstall through OpenClaw (the normal update command may not have detected the new version).`,
                     "",
                     "Run this command using the exec tool:",
                     fallbackCmd,
@@ -683,7 +498,6 @@ export function registerTools(api) {
                     `${fallbackCmd} && ${GATEWAY_RESTART_CMD}`,
                 ].join("\n"));
             }
-            // Normal path — first attempt for this version.
             upgradeAttemptedVersion = latestVersion;
             return textResult([
                 `Update available: v${currentVersion} → v${latestVersion}`,
@@ -697,11 +511,6 @@ export function registerTools(api) {
             ].join("\n"));
         },
     });
-    // --- masons_link_identity -------------------------------------------------
-    // Simplified interface (#986 redesign): LLM provides only the current
-    // channel's entry. Canonical is auto-generated from getOwnerHandle().
-    // Passport entry is auto-included from storedOwnerPassportAddress.
-    // Access gate: deterministic owner-only check prevents prompt injection.
     api.registerTool({
         name: "masons_link_identity",
         description: "Link your owner's identity on the current channel to their Passport identity. " +
@@ -716,9 +525,6 @@ export function registerTools(api) {
             }),
         }),
         execute: withUpdateNotice(async (_id, params) => {
-            // --- Access gate (deterministic) ---
-            // Only the owner on an agent-network turn can invoke this tool.
-            // Prevents prompt injection from visitors or remote agents.
             const hookChannelId = getCurrentTurnChannelId();
             const turnIsOwner = getCurrentTurnIsOwnerNonConsuming();
             if (hookChannelId === "agent-network" && !turnIsOwner) {
@@ -731,20 +537,16 @@ export function registerTools(api) {
             const entry = String(params.entry ?? "")
                 .trim()
                 .toLowerCase();
-            // Validate channel:peerId format — split on first colon only,
-            // both parts must be non-empty (e.g., "telegram:5099353300").
             const colonIdx = entry.indexOf(":");
             if (colonIdx < 1 || colonIdx === entry.length - 1) {
                 return textResult("Invalid format. Use 'channel:peerId' (e.g., 'telegram:5099353300').");
             }
-            // Build entries: user-provided entry + auto-include Passport entry
             const entries = [entry];
             const passportAddr = getOwnerPassportAddress();
             if (passportAddr) {
                 entries.push(`agent-network:${passportAddr}`);
             }
             try {
-                // writeIdentityLinks does entry-level additive merge
                 await writeIdentityLinks(ownerHandle, entries);
             }
             catch (err) {
@@ -766,19 +568,13 @@ export function registerTools(api) {
                     'reason: "Activate cross-channel identity linking".',
             ].join("\n"));
         }),
-    }, 
-    // optional: not all Gateway versions support this tool.
-    { optional: true });
-    // --- masons_unlink_identity -----------------------------------------------
-    // Undo path: removes the owner's canonical identity group from session.identityLinks.
-    // Access gate: same owner-only check as masons_link_identity.
+    }, { optional: true });
     api.registerTool({
         name: "masons_unlink_identity",
         description: "Remove your owner's cross-channel identity link. Reverses masons_link_identity. " +
             "Requires a gateway restart to take effect.",
         parameters: Type.Object({}),
         execute: withUpdateNotice(async () => {
-            // --- Access gate (deterministic) ---
             const hookChannelId = getCurrentTurnChannelId();
             const turnIsOwner = getCurrentTurnIsOwnerNonConsuming();
             if (hookChannelId === "agent-network" && !turnIsOwner) {

package/dist/turn-context.d.ts

@@ -1,52 +1,7 @@
-/**
- * Turn Context — per-turn metadata captured during inbound message dispatch.
- *
- * Tracks the sender identity for the current LLM turn. Set in channel.ts
- * message_received handler (using the closure-scoped ConversationManager),
- * consumed by before_prompt_build in plugin.ts to inject interaction context.
- *
- * Follows the same consume-on-read pattern as owner-session-state.ts:
- * - Written BEFORE dispatch (so before_prompt_build can read it synchronously)
- * - Consumed (read + reset) to prevent stale state across turns
- *
- * Race condition caveat: if two inbound messages arrive on different sessions
- * near-simultaneously, the sender may reflect the wrong session. Acceptable
- * for Phase 1 — OpenClaw processes turns sequentially per agent. Same caveat
- * as owner-session-state.ts currentTurnIsOwner.
- *
- * Module-level singleton — shared between channel.ts (write) and plugin.ts (read).
- */
-/**
- * Set the sender identity for the current turn.
- * Called in message_received before dispatch, using the closure-scoped
- * ConversationManager to resolve sessionId → contact handle.
- */
 export declare function setCurrentTurnSender(contact: string | null): void;
-/**
- * Set the channel ID for the current turn.
- * Called in before_prompt_build — the hook provides channelId.
- * Persists through tool execution within the same turn.
- */
 export declare function setCurrentTurnChannelId(channelId: string | null): void;
-/**
- * Set the owner flag for the current turn (non-consuming copy).
- * Called in before_prompt_build after consuming from owner-session-state.
- * This copy persists through tool execution within the same turn.
- */
 export declare function setCurrentTurnIsOwnerForTools(value: boolean): void;
-/**
- * Consume the per-turn sender identity. Returns the value and resets to null.
- * Consuming prevents stale state from leaking into subsequent turns.
- */
 export declare function consumeCurrentTurnSender(): string | null;
-/**
- * Get the channel ID for the current turn (non-consuming).
- * Used by tool access gates to determine which channel triggered the turn.
- */
 export declare function getCurrentTurnChannelId(): string | null;
-/**
- * Get the owner flag for the current turn (non-consuming).
- * Used by tool access gates to enforce owner-only tools.
- */
 export declare function getCurrentTurnIsOwnerNonConsuming(): boolean;
 //# sourceMappingURL=turn-context.d.ts.map

package/dist/turn-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"turn-context.d.ts","sourceRoot":"","sources":["../src/turn-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAmBH;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEjE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAElE;AAMD;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,GAAG,IAAI,CAIxD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAEvD;AAED;;;GAGG;AACH,wBAAgB,iCAAiC,IAAI,OAAO,CAE3D"}
+{"version":3,"file":"turn-context.d.ts","sourceRoot":"","sources":["../src/turn-context.ts"],"names":[],"mappings":"AAyCA,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEjE;AAOD,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEtE;AAOD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAElE;AAUD,wBAAgB,wBAAwB,IAAI,MAAM,GAAG,IAAI,CAIxD;AAMD,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAEvD;AAMD,wBAAgB,iCAAiC,IAAI,OAAO,CAE3D"}