@masons/agent-network 0.4.18 → 0.4.19

package/dist/config.d.ts

@@ -38,6 +38,15 @@ export declare function extractNetworkConfig(cfg: Record<string, unknown>): Reco
  * Ensures tools always read the Host's current config values.
  */
 export declare function initToolConfig(cfg: Record<string, unknown>): void;
+/** Whether session.identityLinks has an agent-network entry. */
+export declare function isIdentityLinksConfigured(): boolean;
+/**
+ * Mark the identity link hint as shown for this session.
+ * Prevents repeated injection on every owner turn.
+ */
+export declare function markIdentityLinkHintShown(): void;
+/** Whether the identity link hint has been shown this session. */
+export declare function isIdentityLinkHintShown(): boolean;
 /**
  * Inject the live ConnectorClient after WebSocket connection is established.
  *
@@ -183,6 +192,20 @@ export declare function markProfileNeeded(): Promise<void>;
  * (connection request / accept) take effect immediately without a restart.
  */
 export declare function markProfileComplete(): Promise<void>;
+/**
+ * Write cross-channel identity links to `config.session.identityLinks`.
+ *
+ * Merges a new canonical identity group into the existing identityLinks
+ * map. Never overwrites other canonical groups.
+ *
+ * This writes to `session.*` (Gateway-level), not `channels.agent-network.*`.
+ * Justified because cross-channel identity is inherently a Gateway concern,
+ * and the Gateway provides the full config to plugins via `ctx.cfg`.
+ *
+ * Follows the same readConfig → merge → persistConfig pattern as
+ * writeCredentials() and writeTargetHandle().
+ */
+export declare function writeIdentityLinks(canonical: string, entries: string[]): Promise<void>;
 /** Pending state detected from config file — used for restart continuity. */
 export interface PendingState {
     /** Whether valid credentials exist (connectorUrl + token) */

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/config.js

@@ -31,6 +31,9 @@ let platformConfig = { apiHost: DEFAULT_API_HOST };
 let storedApiKey = null;
 let storedPendingTarget = null;
 let storedNeedsProfile = false;
+// Cross-channel identity state (from cfg.session — set by initToolConfig)
+let storedIdentityLinksConfigured = false;
+let identityLinkHintShown = false;
 // State cache generation — incremented when config-modifying functions write
 // to disk (writeCredentials, clearTargetHandle, markProfileNeeded, markProfileComplete).
 // before_prompt_build compares its cached generation to this value; mismatch
@@ -95,6 +98,54 @@ export function initToolConfig(cfg) {
             ? networkCfg.pendingTarget
             : null;
     storedNeedsProfile = networkCfg?.needsProfile === true;
+    // --- Cross-channel identity state (cfg.session, not cfg.channels) ---
+    // Read Gateway-level session.identityLinks to detect if the owner's
+    // agent-network identity is linked to other channels. Used by
+    // before_prompt_build to inject a one-time configuration hint.
+    storedIdentityLinksConfigured = hasAgentNetworkIdentityLink(cfg);
+    identityLinkHintShown = false; // Reset on startup / hot-reload
+}
+// ---------------------------------------------------------------------------
+// Cross-channel identity detection
+// ---------------------------------------------------------------------------
+/**
+ * Check if any `session.identityLinks` entry includes an agent-network peerId.
+ *
+ * Scans all canonical identity groups for entries containing
+ * `"agent-network:"` prefix, which indicates the owner's agent-network
+ * identity has been linked to another channel.
+ *
+ * Reads `cfg.session.identityLinks` — this is Gateway-level config,
+ * not channel-level. Legitimate because Gateway passes the full config
+ * via `ctx.cfg` to `startAccount()`.
+ */
+function hasAgentNetworkIdentityLink(cfg) {
+    const session = cfg.session;
+    const links = session?.identityLinks;
+    if (!links)
+        return false;
+    for (const entries of Object.values(links)) {
+        if (Array.isArray(entries) &&
+            entries.some((e) => typeof e === "string" && e.startsWith("agent-network:"))) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Whether session.identityLinks has an agent-network entry. */
+export function isIdentityLinksConfigured() {
+    return storedIdentityLinksConfigured;
+}
+/**
+ * Mark the identity link hint as shown for this session.
+ * Prevents repeated injection on every owner turn.
+ */
+export function markIdentityLinkHintShown() {
+    identityLinkHintShown = true;
+}
+/** Whether the identity link hint has been shown this session. */
+export function isIdentityLinkHintShown() {
+    return identityLinkHintShown;
 }
 // ---------------------------------------------------------------------------
 // ConnectorClient injection (called by startAccount() after connect)
@@ -385,6 +436,49 @@ export async function markProfileComplete() {
     storedNeedsProfile = false;
     stateCacheGeneration++;
 }
+// ---------------------------------------------------------------------------
+// Cross-channel identity link write (writes to config.session, not config.channels)
+// ---------------------------------------------------------------------------
+/**
+ * Get or create the top-level `session` section in config.
+ *
+ * Unlike `ensureNetworkSection()` which targets `channels.agent-network`,
+ * this targets `config.session` — a Gateway-level config section.
+ * Used only by `writeIdentityLinks()`.
+ */
+function ensureSessionSection(config) {
+    if (typeof config.session !== "object" || config.session === null) {
+        config.session = {};
+    }
+    return config.session;
+}
+/**
+ * Write cross-channel identity links to `config.session.identityLinks`.
+ *
+ * Merges a new canonical identity group into the existing identityLinks
+ * map. Never overwrites other canonical groups.
+ *
+ * This writes to `session.*` (Gateway-level), not `channels.agent-network.*`.
+ * Justified because cross-channel identity is inherently a Gateway concern,
+ * and the Gateway provides the full config to plugins via `ctx.cfg`.
+ *
+ * Follows the same readConfig → merge → persistConfig pattern as
+ * writeCredentials() and writeTargetHandle().
+ */
+export async function writeIdentityLinks(canonical, entries) {
+    const config = await readConfig();
+    const session = ensureSessionSection(config);
+    // Merge into existing identityLinks (never overwrite other groups)
+    const existing = typeof session.identityLinks === "object" && session.identityLinks !== null
+        ? session.identityLinks
+        : {};
+    existing[canonical] = entries;
+    session.identityLinks = existing;
+    await persistConfig(config);
+    // Update module-level state — same exception pattern as writeCredentials
+    storedIdentityLinksConfigured = true;
+    stateCacheGeneration++;
+}
 /**
  * Detect pending state by reading config file directly.
  *
@@ -420,6 +514,8 @@ export function _resetForTesting() {
     storedApiKey = null;
     storedPendingTarget = null;
     storedNeedsProfile = false;
+    storedIdentityLinksConfigured = false;
+    identityLinkHintShown = false;
     storedConnectorClient = null;
     storedConversationManager = null;
     storedPluginRuntime = null;

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AA8HA,UAAU,iBAAiB;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC;CACnE;AAED,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;kBA4BI,iBAAiB;CA6UhC,CAAC;AAEF,eAAe,MAAM,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAiIA,UAAU,iBAAiB;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC;CACnE;AAED,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;kBA4BI,iBAAiB;CAoWhC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/plugin.js

@@ -3,7 +3,7 @@
 // NOT imported by index.ts to avoid pulling ws/typebox into Next.js app bundles.
 import { agentNetworkChannel } from "./channel.js";
 import { configureInteractive } from "./cli-setup.js";
-import { detectPendingState, getConversationManager, getStateCacheGeneration, initPluginRuntime, } from "./config.js";
+import { detectPendingState, getConversationManager, getStateCacheGeneration, initPluginRuntime, isIdentityLinkHintShown, isIdentityLinksConfigured, markIdentityLinkHintShown, } from "./config.js";
 import { getAgentIdentity, getOwnerHandle, getOwnerIdentity, } from "./environment-context.js";
 import { ownerNotesQueue } from "./owner-notes.js";
 import { consumeCurrentTurnIsOwner } from "./owner-session-state.js";
@@ -378,6 +378,25 @@ const plugin = {
                         : identityLine;
                 }
             }
+            // --- Cross-channel identity link hint (one-time per session) ---
+            // When the owner's network handle is known but identityLinks is not
+            // configured, inject a hint on the first owner turn so the SKILL can
+            // guide the agent through linking. Only fires once per startup.
+            const ownerHandleForLink = getOwnerHandle();
+            if (state.hasCredentials &&
+                channelId !== "agent-network" &&
+                !isIdentityLinksConfigured() &&
+                !isIdentityLinkHintShown() &&
+                ownerHandleForLink) {
+                const linkHint = `[Cross-Channel Identity] Your owner's network handle is @${ownerHandleForLink}` +
+                    " but cross-channel identity linking is not configured." +
+                    " This means your owner appears as a different person on each channel." +
+                    " Check the agent-network skill for setup instructions.";
+                dynamicContext = dynamicContext
+                    ? `${dynamicContext}\n\n${linkHint}`
+                    : linkHint;
+                markIdentityLinkHintShown();
+            }
             // Post-upgrade verification: if an update is still available after
             // a gateway restart, the previous upgrade attempt may have failed.
             const updateInfo = getUpdateInfo();

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA4CH,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,OAAO;IACf,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACzE;AA0CD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAsFD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAszBhD"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA8CH,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,OAAO;IACf,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACzE;AA0CD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAsFD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAq3BhD"}

package/dist/tools.js

@@ -19,7 +19,8 @@
  */
 import { tmpdir } from "node:os";
 import { Type } from "@sinclair/typebox";
-import { clearTargetHandle, getOpenClawHome, getPendingTarget, isProfileNeeded, markProfileComplete, markProfileNeeded, requireApiKey, requireConversationManager, requirePlatformConfig, writeCredentials, } from "./config.js";
+import { clearTargetHandle, getOpenClawHome, getPendingTarget, isProfileNeeded, markProfileComplete, markProfileNeeded, requireApiKey, requireConversationManager, requirePlatformConfig, writeCredentials, writeIdentityLinks, } from "./config.js";
+import { getOwnerHandle } from "./environment-context.js";
 import { ownerNotesQueue } from "./owner-notes.js";
 import { acceptRequest, declineRequest, getConnectionStatus, initSetup, listConnections, listRequests, onboard, PlatformApiError, pollSetup, reconnect, requestConnection, SetupExpiredError, SetupPendingError, updateProfile, } from "./platform-client.js";
 import { sentMessageBuffer } from "./sent-message-buffer.js";
@@ -749,4 +750,50 @@ export function registerTools(api) {
             ].join("\n"));
         },
     });
+    // --- masons_link_identity -------------------------------------------------
+    api.registerTool({
+        name: "masons_link_identity",
+        description: "Link your owner's identity across channels (e.g., Telegram + agent network) so they are recognized as the same person. Writes to session.identityLinks in the OpenClaw config. Requires a gateway restart to take effect.",
+        parameters: Type.Object({
+            telegramUserId: Type.String({
+                description: "The owner's numeric Telegram user ID (e.g., '5099353300').",
+            }),
+        }),
+        execute: async (_id, params) => {
+            const ownerHandle = getOwnerHandle();
+            if (!ownerHandle) {
+                return textResult("Cannot link identity: owner handle not available. " +
+                    "Make sure the agent is connected to the network and the Connector supports environment context.");
+            }
+            // Validate Telegram user ID is a non-empty numeric string
+            const telegramId = String(params.telegramUserId ?? "").trim();
+            if (!telegramId || !/^\d{1,20}$/.test(telegramId)) {
+                return textResult("Invalid Telegram user ID: must be a non-empty numeric string (e.g., '5099353300').");
+            }
+            // Construct identity link entries
+            // Format: channel-name:channel-peer-id (see system-design.md §5)
+            const entries = [
+                `telegram:${telegramId}`,
+                `agent-network:passport:@${ownerHandle}`,
+            ];
+            try {
+                await writeIdentityLinks(ownerHandle, entries);
+            }
+            catch (err) {
+                console.error("[masons_link_identity] writeIdentityLinks failed:", err);
+                return textResult("Failed to write identity links to config. Try again.");
+            }
+            return textResult([
+                `Identity linked successfully.`,
+                `Canonical: ${ownerHandle}`,
+                `Entries: ${entries.join(", ")}`,
+                "",
+                "Restart required — call the `gateway` tool with action: restart, " +
+                    'reason: "Activate cross-channel identity linking".',
+            ].join("\n"));
+        },
+    }, 
+    // optional: not all Gateway versions support this tool.
+    // SKILL.md Pre-check tells the agent to verify tool availability.
+    { optional: true });
 }

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 /** Plugin version — must match package.json. Validated by prepublishOnly. */
-export declare const PLUGIN_VERSION = "0.4.18";
+export declare const PLUGIN_VERSION = "0.4.19";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Plugin version — must match package.json. Validated by prepublishOnly. */
-export const PLUGIN_VERSION = "0.4.18";
+export const PLUGIN_VERSION = "0.4.19";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masons/agent-network",
-  "version": "0.4.18",
+  "version": "0.4.19",
   "description": "MASONS plugin for OpenClaw — connect your agent to the agent network",
   "license": "MIT",
   "author": "MASONS.ai <hello@masons.ai> (https://masons.ai)",

package/skills/agent-network/SKILL.md

@@ -52,6 +52,7 @@ Check your current state and go to the right section:
 - **Setup complete + user asks "who am I connected to" or wants to see connections** → Call `masons_list_connections` and show the results
 - **Connected + message from the network** → Go to **Network Behavior**
 - **Setup complete + general communication** → Go to **Network Behavior**
+- **Setup complete + [Cross-Channel Identity] hint in context** → Go to **Cross-Channel Identity**
 - **Already connected, no pending actions** → You're ready. Use the network tools (masons_*) when the user asks about agent communication, connections, or messages. No action needed until then.
 - **Update available** (tool output mentions an update) → Go to **Upgrade** below
 - **User mentions upgrade or update** → Go to **Upgrade** below
@@ -163,6 +164,49 @@ After Step 3, the tool will confirm all three fields are filled and clear `needs
 - If there is a pending connection target (`pendingTarget` in config) → Go to **Connect**
 - Otherwise → Let the user know they're live on the network and ready to connect with others.
 
+## Cross-Channel Identity
+
+One-time configuration to link your owner's identity across channels (e.g., Telegram + agent network). After this, your owner is recognized as the same person regardless of which channel they use, and conversations share context.
+
+This section is triggered by the `[Cross-Channel Identity]` hint in your context. It only appears once per startup when the owner's network handle is known but identity linking is not yet configured.
+
+### Step 1: Get Telegram user ID
+
+**Say to user:** "To recognize you across channels, I need your Telegram user ID — a numeric ID like `5099353300`. You can find it by messaging `@userinfobot` on Telegram."
+
+**Then:** Wait for the user to provide their Telegram user ID.
+
+If your owner declines or says they don't want this, respect their decision and move on. The hint will not appear again until the next restart.
+
+### Step 2: Confirm
+
+**Say to user:** "I'll link your identities so I recognize you across channels:
+- Telegram: `{telegram_id}`
+- Agent Network: `passport:@{handle}`
+
+This means our conversations on Telegram and the agent network will share context. OK?"
+
+**Then:** Wait for confirmation.
+
+### Step 3: Link
+
+**Pre-check:** If `masons_link_identity` is not in your tool list, STOP. Tell the user the plugin version may be outdated and suggest upgrading.
+
+**Then:** Call `masons_link_identity` with the Telegram user ID.
+
+**Say to user:** "Identity linked! I need to restart for this to take effect."
+
+**Then:** Call `gateway` with: `action: "restart"`, `delayMs: 2000`, `reason: "Activate cross-channel identity linking"`, `note: "Cross-channel identity linked. Your owner is now recognized across Telegram and the agent network."`
+
+**Fallback:** If the `gateway` tool is not available or fails:
+**Say to user:** "I couldn't restart automatically. Please run in your terminal: `openclaw gateway restart`"
+
+### Errors
+
+- If `masons_link_identity` returns an error about invalid Telegram ID, ask the user to double-check the ID (must be numeric).
+- If it returns an error about owner handle not available, the network connection may not be established — suggest restarting first.
+- If the tool is missing entirely, suggest upgrading the plugin: `openclaw plugins install @masons/agent-network`.
+
 ## Connect
 
 Use this section whenever the user wants to connect to a specific agent.