@masons/agent-network 0.4.19 → 0.4.21

package/dist/channel.d.ts

@@ -1,4 +1,6 @@
 import type { AgentNetworkAccount } from "./config-schema.js";
+/** Get the stored owner Passport address (first is_owner visit). */
+export declare function getOwnerPassportAddress(): string | null;
 interface ChannelMeta {
     name: string;
     description: string;

package/dist/channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAuB9D,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,UAAU,oBAAoB,CAAC,CAAC;IAC9B,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAAC;IACvD,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC;IACpE,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;IACjE,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;CAC/D;AAED,UAAU,sBAAsB;IAC9B,EAAE,EAAE,OAAO,CAAC;CACb;AAED,UAAU,sBAAsB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,sBAAsB;IAC9B,YAAY,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC9C,QAAQ,CAAC,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACzE;AAED,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAsDD,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,YAAY,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,WAAW,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,UAAU,yBAAyB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,YAAY,EAAE,mBAAmB,CAAC;IAClC,MAAM,EAAE,oBAAoB,CAAC,mBAAmB,CAAC,CAAC;IAClD,QAAQ,EAAE,sBAAsB,CAAC;IACjC,OAAO,EAAE,qBAAqB,CAAC,mBAAmB,CAAC,CAAC;CACrD;AA+ND,eAAO,MAAM,mBAAmB,EAAE,yBAqNjC,CAAC"}
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AA2B9D,oEAAoE;AACpE,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAEvD;AAQD,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,UAAU,oBAAoB,CAAC,CAAC;IAC9B,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAAC;IACvD,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC;IACpE,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;IACjE,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;CAC/D;AAED,UAAU,sBAAsB;IAC9B,EAAE,EAAE,OAAO,CAAC;CACb;AAED,UAAU,sBAAsB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,sBAAsB;IAC9B,YAAY,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC9C,QAAQ,CAAC,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACzE;AAED,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAsDD,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,YAAY,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,WAAW,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,UAAU,yBAAyB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,YAAY,EAAE,mBAAmB,CAAC;IAClC,MAAM,EAAE,oBAAoB,CAAC,mBAAmB,CAAC,CAAC;IAClD,QAAQ,EAAE,sBAAsB,CAAC;IACjC,OAAO,EAAE,qBAAqB,CAAC,mBAAmB,CAAC,CAAC;CACrD;AA4PD,eAAO,MAAM,mBAAmB,EAAE,yBAwNjC,CAAC"}

package/dist/channel.js

@@ -1,14 +1,26 @@
 import { randomUUID } from "node:crypto";
 import createDebug from "debug";
-import { clearConnectorClient, clearConversationManager, extractNetworkConfig, initConnectorClient, initConversationManager, initToolConfig, requirePluginRuntime, } from "./config.js";
+import { clearConnectorClient, clearConversationManager, extractNetworkConfig, getDmScope, initConnectorClient, initConversationManager, initToolConfig, isIdentityLinksConfigured, requirePluginRuntime, } from "./config.js";
 import { ConnectorClient } from "./connector-client.js";
 import { ConversationManager } from "./conversation-manager.js";
 import { clearEnvironmentContext } from "./environment-context.js";
 import { extractHandleFromAddress } from "./handle-utils.js";
+import { ownerNotesQueue } from "./owner-notes.js";
 import { clearOwnerState, isOwnerAddress, markOwnerAddress, setCurrentTurnIsOwner, } from "./owner-session-state.js";
 import { setCurrentTurnSender } from "./turn-context.js";
 import { checkForUpdate } from "./update-check.js";
 const dbg = createDebug("agent-network:channel");
+// Cross-channel identity notification: once per startAccount lifecycle.
+// Reset on startAccount(). isIdentityLinksConfigured() provides the
+// cross-restart idempotency (checks config file).
+let notificationAttempted = false;
+// Owner's Passport address: recorded on first is_owner MESSAGE_RECEIVED.
+// Used by masons_link_identity tool to auto-include the Passport entry.
+let storedOwnerPassportAddress = null;
+/** Get the stored owner Passport address (first is_owner visit). */
+export function getOwnerPassportAddress() {
+    return storedOwnerPassportAddress;
+}
 // --- Sender identity ---
 /**
  * Extract a human-readable name from the sender's metadata.
@@ -81,6 +93,30 @@ async function handleAddressedMessage(event, conversationManager, client, ctx) {
     // Connector includes is_owner in metadata for Passport visitors.
     if (event.metadata?.is_owner === true) {
         markOwnerAddress(fromAddress);
+        // Record Passport address for tool auto-include (first visit only)
+        if (!storedOwnerPassportAddress) {
+            storedOwnerPassportAddress = fromAddress;
+            dbg("recorded owner Passport address: %s", fromAddress);
+        }
+        // --- dmScope-aware notification (2026-03-26, #986 redesign) ---
+        // Notify the owner about cross-channel identity linking availability.
+        // Notification is:
+        // - Skipped in "main" mode (linking has no effect — Gateway skips resolveLinkedPeerId)
+        // - Skipped if identityLinks already configured (already linked)
+        // - Sent once per startAccount lifecycle (in-memory idempotency)
+        // Content is channel-agnostic and language-neutral (semantic event, not identity claim).
+        if (getDmScope() !== "main" &&
+            !isIdentityLinksConfigured() &&
+            !notificationAttempted) {
+            notificationAttempted = true;
+            ownerNotesQueue.enqueue({
+                content: "Owner visited via Passport (verified). " +
+                    "Cross-channel identity linking is available but not configured. " +
+                    "The owner can link their identity across channels so conversations share context.",
+                timestamp: Date.now(),
+            });
+            dbg("queued identity linking notification (dmScope=%s)", getDmScope());
+        }
     }
     setCurrentTurnIsOwner(isOwnerAddress(fromAddress));
     // Resolve contact from address. Register inbound conversation if new.
@@ -246,6 +282,9 @@ export const agentNetworkChannel = {
     gateway: {
         async startAccount(ctx) {
             dbg("starting account %s", ctx.accountId);
+            // Reset per-session state
+            notificationAttempted = false;
+            storedOwnerPassportAddress = null;
             // Defensive: clear stale singletons from a previous cycle.
             // The abort handler intentionally leaves them alive for in-flight tool
             // calls (#935). Clean up here at cycle start so initConnectorClient()

package/dist/config.d.ts

@@ -38,15 +38,22 @@ 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. */
+/**
+ * Whether `session.identityLinks` contains at least one entry with the
+ * `agent-network:` channel prefix — indicating the owner's agent-network
+ * identity is linked to another channel.
+ */
 export declare function isIdentityLinksConfigured(): boolean;
 /**
- * Mark the identity link hint as shown for this session.
- * Prevents repeated injection on every owner turn.
+ * Current dmScope mode from Gateway config (`cfg.session.dmScope`).
+ *
+ * Determines how the plugin handles cross-channel identity:
+ * - "main" (default): all DMs share one session. Identity linking has no effect.
+ * - "per-peer": identity linking merges sessions across channels.
+ * - "per-channel-peer" / "per-account-channel-peer": identity linking normalizes
+ *   peerId but sessions stay separate per channel.
  */
-export declare function markIdentityLinkHintShown(): void;
-/** Whether the identity link hint has been shown this session. */
-export declare function isIdentityLinkHintShown(): boolean;
+export declare function getDmScope(): string;
 /**
  * Inject the live ConnectorClient after WebSocket connection is established.
  *
@@ -195,8 +202,13 @@ 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.
+ * **Entry-level additive merge** (2026-03-26, #986 redesign):
+ * New entries are merged INTO the existing canonical group, deduped,
+ * lowercase-normalized. Never overwrites other canonical groups, and
+ * never removes existing entries within the same group.
+ *
+ * This allows one-channel-at-a-time linking: first call adds Telegram,
+ * second call adds Feishu — without losing the Telegram entry.
  *
  * This writes to `session.*` (Gateway-level), not `channels.agent-network.*`.
  * Justified because cross-channel identity is inherently a Gateway concern,
@@ -206,6 +218,13 @@ export declare function markProfileComplete(): Promise<void>;
  * writeCredentials() and writeTargetHandle().
  */
 export declare function writeIdentityLinks(canonical: string, entries: string[]): Promise<void>;
+/**
+ * Remove a canonical identity group from `config.session.identityLinks`.
+ *
+ * Undo path for `writeIdentityLinks()`. Removes only the specified
+ * canonical key; other groups are preserved.
+ */
+export declare function removeIdentityLinks(canonical: 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

@@ -33,7 +33,12 @@ let storedPendingTarget = null;
 let storedNeedsProfile = false;
 // Cross-channel identity state (from cfg.session — set by initToolConfig)
 let storedIdentityLinksConfigured = false;
-let identityLinkHintShown = false;
+// dmScope from cfg.session.dmScope — determines notification + linking behavior.
+// "main" (default): all DMs share one session. Identity linking has no effect.
+// "per-peer": identity linking merges sessions across channels.
+// "per-channel-peer" / "per-account-channel-peer": identity linking normalizes
+//   peerId but sessions stay separate per channel.
+let storedDmScope = "main";
 // 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
@@ -99,11 +104,20 @@ export function initToolConfig(cfg) {
             : 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.
+    // Decision: 2026-03-26, during cross-channel identity linking design (#969, #986).
+    //
+    // Reads Gateway-level session config to detect:
+    // 1. Whether identityLinks already contains agent-network entries
+    // 2. The dmScope mode (determines notification + linking behavior)
+    //
+    // These are NOT agent-network-specific — any channel plugin would need
+    // similar capabilities. They live here because only one channel plugin
+    // exists today. When OpenClaw provides native cross-channel identity
+    // management, this should migrate.
     storedIdentityLinksConfigured = hasAgentNetworkIdentityLink(cfg);
-    identityLinkHintShown = false; // Reset on startup / hot-reload
+    const sessionCfg = cfg.session;
+    storedDmScope =
+        typeof sessionCfg?.dmScope === "string" ? sessionCfg.dmScope : "main";
 }
 // ---------------------------------------------------------------------------
 // Cross-channel identity detection
@@ -132,20 +146,25 @@ function hasAgentNetworkIdentityLink(cfg) {
     }
     return false;
 }
-/** Whether session.identityLinks has an agent-network entry. */
+/**
+ * Whether `session.identityLinks` contains at least one entry with the
+ * `agent-network:` channel prefix — indicating the owner's agent-network
+ * identity is linked to another channel.
+ */
 export function isIdentityLinksConfigured() {
     return storedIdentityLinksConfigured;
 }
 /**
- * Mark the identity link hint as shown for this session.
- * Prevents repeated injection on every owner turn.
+ * Current dmScope mode from Gateway config (`cfg.session.dmScope`).
+ *
+ * Determines how the plugin handles cross-channel identity:
+ * - "main" (default): all DMs share one session. Identity linking has no effect.
+ * - "per-peer": identity linking merges sessions across channels.
+ * - "per-channel-peer" / "per-account-channel-peer": identity linking normalizes
+ *   peerId but sessions stay separate per channel.
  */
-export function markIdentityLinkHintShown() {
-    identityLinkHintShown = true;
-}
-/** Whether the identity link hint has been shown this session. */
-export function isIdentityLinkHintShown() {
-    return identityLinkHintShown;
+export function getDmScope() {
+    return storedDmScope;
 }
 // ---------------------------------------------------------------------------
 // ConnectorClient injection (called by startAccount() after connect)
@@ -455,8 +474,13 @@ function ensureSessionSection(config) {
 /**
  * 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.
+ * **Entry-level additive merge** (2026-03-26, #986 redesign):
+ * New entries are merged INTO the existing canonical group, deduped,
+ * lowercase-normalized. Never overwrites other canonical groups, and
+ * never removes existing entries within the same group.
+ *
+ * This allows one-channel-at-a-time linking: first call adds Telegram,
+ * second call adds Feishu — without losing the Telegram entry.
  *
  * This writes to `session.*` (Gateway-level), not `channels.agent-network.*`.
  * Justified because cross-channel identity is inherently a Gateway concern,
@@ -472,13 +496,43 @@ export async function writeIdentityLinks(canonical, entries) {
     const existing = typeof session.identityLinks === "object" && session.identityLinks !== null
         ? session.identityLinks
         : {};
-    existing[canonical] = entries;
+    // Entry-level additive merge: combine new entries into existing group
+    const current = existing[canonical] ?? [];
+    const normalized = entries.map((e) => e.toLowerCase());
+    const merged = [...new Set([...current, ...normalized])];
+    existing[canonical] = merged;
     session.identityLinks = existing;
     await persistConfig(config);
     // Update module-level state — same exception pattern as writeCredentials
     storedIdentityLinksConfigured = true;
     stateCacheGeneration++;
 }
+/**
+ * Remove a canonical identity group from `config.session.identityLinks`.
+ *
+ * Undo path for `writeIdentityLinks()`. Removes only the specified
+ * canonical key; other groups are preserved.
+ */
+export async function removeIdentityLinks(canonical) {
+    const config = await readConfig();
+    const session = ensureSessionSection(config);
+    const existing = typeof session.identityLinks === "object" && session.identityLinks !== null
+        ? session.identityLinks
+        : {};
+    delete existing[canonical];
+    // If identityLinks is now empty, remove the key entirely
+    if (Object.keys(existing).length === 0) {
+        delete session.identityLinks;
+    }
+    else {
+        session.identityLinks = existing;
+    }
+    await persistConfig(config);
+    // Re-check if any agent-network links remain
+    storedIdentityLinksConfigured = Object.values(existing).some((entries) => Array.isArray(entries) &&
+        entries.some((e) => typeof e === "string" && e.startsWith("agent-network:")));
+    stateCacheGeneration++;
+}
 /**
  * Detect pending state by reading config file directly.
  *
@@ -515,7 +569,7 @@ export function _resetForTesting() {
     storedPendingTarget = null;
     storedNeedsProfile = false;
     storedIdentityLinksConfigured = false;
-    identityLinkHintShown = false;
+    storedDmScope = "main";
     storedConnectorClient = null;
     storedConversationManager = null;
     storedPluginRuntime = null;

package/dist/environment-context.d.ts

@@ -36,7 +36,7 @@ export declare function setEnvironmentContext(agent?: {
 }): void;
 export declare function getAgentIdentity(): AgentIdentity | null;
 export declare function getOwnerIdentity(): OwnerIdentity | null;
-/** Convenience: get the owner's handle for interaction tagging. */
+/** Convenience: get the owner's handle (used by auto-link in channel.ts). */
 export declare function getOwnerHandle(): string | null;
 /** Clear all environment context (connection lost — identity invalid). */
 export declare function clearEnvironmentContext(): void;

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

@@ -1 +1 @@
-{"version":3,"file":"environment-context.d.ts","sourceRoot":"","sources":["../src/environment-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAaD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,CAAC,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EACzC,KAAK,CAAC,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,IAAI,CAkBN;AAMD,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,IAAI,CAEvD;AAED,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,IAAI,CAEvD;AAED,mEAAmE;AACnE,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAE9C;AAMD,0EAA0E;AAC1E,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C;AAMD,uDAAuD;AACvD,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC"}
+{"version":3,"file":"environment-context.d.ts","sourceRoot":"","sources":["../src/environment-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAaD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,CAAC,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EACzC,KAAK,CAAC,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,IAAI,CAkBN;AAMD,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,IAAI,CAEvD;AAED,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,IAAI,CAEvD;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAE9C;AAMD,0EAA0E;AAC1E,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C;AAMD,uDAAuD;AACvD,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC"}

package/dist/environment-context.js

@@ -59,7 +59,7 @@ export function getAgentIdentity() {
 export function getOwnerIdentity() {
     return ownerIdentity;
 }
-/** Convenience: get the owner's handle for interaction tagging. */
+/** Convenience: get the owner's handle (used by auto-link in channel.ts). */
 export function getOwnerHandle() {
     return ownerIdentity?.handle ?? null;
 }

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AA0HA,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;CAsWhC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/plugin.js

@@ -3,13 +3,13 @@
 // 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, isIdentityLinkHintShown, isIdentityLinksConfigured, markIdentityLinkHintShown, } from "./config.js";
-import { getAgentIdentity, getOwnerHandle, getOwnerIdentity, } from "./environment-context.js";
+import { detectPendingState, getConversationManager, getDmScope, getStateCacheGeneration, initPluginRuntime, } from "./config.js";
+import { getAgentIdentity } from "./environment-context.js";
 import { ownerNotesQueue } from "./owner-notes.js";
 import { consumeCurrentTurnIsOwner } from "./owner-session-state.js";
 import { sentMessageBuffer } from "./sent-message-buffer.js";
 import { registerTools } from "./tools.js";
-import { consumeCurrentTurnSender } from "./turn-context.js";
+import { consumeCurrentTurnSender, setCurrentTurnChannelId, setCurrentTurnIsOwnerForTools, } from "./turn-context.js";
 import { getUpdateInfo } from "./update-check.js";
 import { PLUGIN_VERSION } from "./version.js";
 // ---------------------------------------------------------------------------
@@ -44,7 +44,7 @@ const MAX_INTERACTIONS = 5;
  *
  * Returns undefined if no interactions exist or CM is not available.
  */
-function buildInteractionContext(channelId, turnSender, ownerHandle) {
+function buildInteractionContext(channelId, turnSender) {
     const cm = getConversationManager();
     if (!cm)
         return undefined;
@@ -61,12 +61,9 @@ function buildInteractionContext(channelId, turnSender, ownerHandle) {
         : "[Active interactions]";
     const lines = sorted.map((c) => {
         const who = `@${c.contact}`;
-        // Tag owner interactions so the LLM knows which contact is the owner (#969).
-        const isOwner = !!ownerHandle && c.contact.toLowerCase() === ownerHandle.toLowerCase();
-        const ownerTag = isOwner ? " (your owner)" : "";
         const initiated = c.initiatedBy === "local" ? "you initiated" : "they initiated";
         const when = formatTimeAgo(c.lastMessageAt);
-        return `• ${who}${ownerTag} — ${initiated} — last activity ${when}`;
+        return `• ${who} — ${initiated} — last activity ${when}`;
     });
     const isNetworkTurn = channelId === "agent-network";
     if (isNetworkTurn && turnSender) {
@@ -199,10 +196,30 @@ const plugin = {
             "should you report to your owner via masons_note_for_owner? " +
             "Should you follow up with another agent via masons_send_message? " +
             "When the interaction is complete, call masons_end_conversation as your FINAL action — " +
-            "do not generate any text reply after ending.";
+            "do not generate any text reply after ending. " +
+            // --- Cross-channel identity linking knowledge removed from static TOOL_CONTEXT ---
+            // Moved to dynamicContext in before_prompt_build (#986 redesign).
+            // Reason: TOOL_CONTEXT is built in register() before startAccount() runs,
+            // so getDmScope() is not available. Linking knowledge is dmScope-conditional.
+            "";
         api.on("before_prompt_build", async (_event, ctx) => {
             const hookCtx = ctx;
             const channelId = hookCtx?.channelId;
+            // --- Consume per-turn flags unconditionally (#836, #873) ---
+            // MUST happen BEFORE any early return (config read timeout, etc.)
+            // to prevent stale state from leaking across turns. If not consumed,
+            // the value persists and is read on the NEXT turn, producing incorrect
+            // context or — critically — bypassing the access gate on identity tools.
+            const turnIsOwner = consumeCurrentTurnIsOwner();
+            const turnSender = consumeCurrentTurnSender();
+            // --- Store turn context for tool access gates (#986) ---
+            // Tools run AFTER before_prompt_build. The consumed flags above are gone
+            // by tool execution time. Store non-consuming copies so tools can check
+            // channelId and isOwner for access control (e.g., identity linking gate).
+            // These persist until the next before_prompt_build overwrites them.
+            // Assumption: OpenClaw processes turns sequentially per agent.
+            setCurrentTurnChannelId(channelId ?? null);
+            setCurrentTurnIsOwnerForTools(turnIsOwner);
             // --- Detect setup state (cached, re-read when config changes) ---
             const currentGeneration = getStateCacheGeneration();
             if (!cachedState || cachedGeneration !== currentGeneration) {
@@ -217,16 +234,11 @@ const plugin = {
                 catch {
                     // Config read failure — proceed without state-specific context.
                     // Will retry on next turn (cachedState stays null).
+                    // Per-turn flags were already consumed above — no stale state leak.
                     return {};
                 }
             }
             const state = cachedState;
-            // --- Consume per-turn flags unconditionally (#836, #873) ---
-            // Must consume on EVERY turn to prevent stale state from leaking across
-            // turns. If not consumed (e.g., agent is in setup flow), the value would
-            // persist and be read on the NEXT turn, producing incorrect context.
-            const turnIsOwner = consumeCurrentTurnIsOwner();
-            const turnSender = consumeCurrentTurnSender();
             // --- Build dynamic context based on setup state ---
             let dynamicContext;
             if (!state.hasCredentials) {
@@ -302,7 +314,7 @@ const plugin = {
                                 "your owner (Principal) will NOT see it. To report something to your owner, " +
                                 "call masons_note_for_owner.";
                         // Append interaction space snapshot if active interactions exist.
-                        const interactionCtx = buildInteractionContext(channelId, turnSender, getOwnerHandle());
+                        const interactionCtx = buildInteractionContext(channelId, turnSender);
                         if (interactionCtx) {
                             dynamicContext += `\n\n${interactionCtx}`;
                         }
@@ -346,7 +358,7 @@ const plugin = {
                     }
                     // Append interaction space on owner turns too (#873).
                     // Gives the agent awareness of active network interactions.
-                    const interactionCtx = buildInteractionContext(channelId, null, getOwnerHandle());
+                    const interactionCtx = buildInteractionContext(channelId, null);
                     if (interactionCtx) {
                         dynamicContext = dynamicContext
                             ? `${dynamicContext}\n\n${interactionCtx}`
@@ -354,49 +366,42 @@ const plugin = {
                     }
                 }
             }
-            // --- Identity preamble (#969) ---
-            // Inject agent + owner identity into dynamic context so the LLM knows
-            // who it is and who its owner is on the network. Goes into dynamicContext
-            // (not TOOL_CONTEXT) because identity is per-agent.
+            // --- dmScope-conditional linking knowledge (#986 redesign) ---
+            // Placed in dynamicContext (not static TOOL_CONTEXT) because getDmScope()
+            // is only available after startAccount() runs (initToolConfig reads cfg).
+            // TOOL_CONTEXT is built in register() before startAccount().
+            if (state.hasCredentials && !state.needsProfile && !state.pendingTarget) {
+                const dmScope = getDmScope();
+                if (dmScope !== "main") {
+                    const linkingKnowledge = "[Cross-Channel Identity] When your owner visits your Passport page, " +
+                        "the plugin detects them via verified authentication. " +
+                        "You can link their identity across channels so conversations share context. " +
+                        "Use masons_link_identity to link or masons_unlink_identity to undo. " +
+                        (dmScope === "per-peer"
+                            ? "After linking and gateway restart, conversations will merge across channels."
+                            : "After linking and gateway restart, identity will be normalized but conversations stay separate under current session configuration.");
+                    dynamicContext = dynamicContext
+                        ? `${dynamicContext}\n\n${linkingKnowledge}`
+                        : linkingKnowledge;
+                }
+            }
+            // --- Self-identity preamble (#969) ---
+            // Inject agent self-identity so the LLM knows who it is on the network.
+            // Owner identity is NOT injected here — agent rejected it as untrusted
+            // (0.4.18/0.4.19 case study). Owner recognition is handled via
+            // session.identityLinks at the Gateway config layer instead.
             if (state.hasCredentials) {
                 const envAgent = getAgentIdentity();
-                const envOwner = getOwnerIdentity();
                 if (envAgent) {
                     let identityLine = `[Identity] You are @${envAgent.handle}`;
                     if (envAgent.name)
                         identityLine += ` (${envAgent.name})`;
                     identityLine += " on the agent network.";
-                    if (envOwner) {
-                        identityLine += ` Your owner is @${envOwner.handle}`;
-                        if (envOwner.displayName) {
-                            identityLine += ` (${envOwner.displayName})`;
-                        }
-                        identityLine += ".";
-                    }
                     dynamicContext = dynamicContext
                         ? `${identityLine}\n\n${dynamicContext}`
                         : 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;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"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAqDH,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,CA88BhD"}

package/dist/tools.js

@@ -19,11 +19,13 @@
  */
 import { tmpdir } from "node:os";
 import { Type } from "@sinclair/typebox";
-import { clearTargetHandle, getOpenClawHome, getPendingTarget, isProfileNeeded, markProfileComplete, markProfileNeeded, requireApiKey, requireConversationManager, requirePlatformConfig, writeCredentials, writeIdentityLinks, } from "./config.js";
+import { getOwnerPassportAddress } from "./channel.js";
+import { clearTargetHandle, getDmScope, getOpenClawHome, getPendingTarget, isProfileNeeded, markProfileComplete, markProfileNeeded, removeIdentityLinks, 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";
+import { getCurrentTurnChannelId, getCurrentTurnIsOwnerNonConsuming, } from "./turn-context.js";
 import { fetchLatestVersion, getPluginVersion, getUpdateInfo, } from "./update-check.js";
 // ---------------------------------------------------------------------------
 // Constants
@@ -751,49 +753,109 @@ export function registerTools(api) {
         },
     });
     // --- 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 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.",
+        description: "Link your owner's identity on the current channel to their Passport identity. " +
+            "Provide only the current channel's entry in 'channel:peerId' format " +
+            "(e.g., 'telegram:5099353300', 'feishu:ou_abc123'). " +
+            "The canonical name and Passport entry are added automatically. " +
+            "Requires a gateway restart to take effect.",
         parameters: Type.Object({
-            telegramUserId: Type.String({
-                description: "The owner's numeric Telegram user ID (e.g., '5099353300').",
+            entry: Type.String({
+                description: "Current channel's identity entry in 'channel:peerId' format " +
+                    "(e.g., 'telegram:5099353300', 'feishu:ou_abc123').",
             }),
         }),
-        execute: async (_id, params) => {
+        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) {
+                return textResult("Identity linking is only available to the agent's owner.");
+            }
             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}`,
-            ];
+                return textResult("Not connected to the network. Cannot determine canonical identity.");
+            }
+            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) {
                 console.error("[masons_link_identity] writeIdentityLinks failed:", err);
                 return textResult("Failed to write identity links to config. Try again.");
             }
+            const dmScope = getDmScope();
+            const effectExplanation = dmScope === "per-peer"
+                ? "After restart, conversations will merge across linked channels."
+                : "After restart, identity will be normalized. Conversations stay separate under current session configuration (per-channel-peer). For full merge, change session.dmScope to per-peer.";
             return textResult([
-                `Identity linked successfully.`,
+                "Identity linked successfully.",
                 `Canonical: ${ownerHandle}`,
-                `Entries: ${entries.join(", ")}`,
+                `Entries added: ${entries.join(", ")}`,
+                "",
+                effectExplanation,
                 "",
                 "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 });
+    // --- 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.
+    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) {
+                return textResult("Identity unlinking is only available to the agent's owner.");
+            }
+            const ownerHandle = getOwnerHandle();
+            if (!ownerHandle) {
+                return textResult("Not connected to the network. Cannot determine canonical identity.");
+            }
+            try {
+                await removeIdentityLinks(ownerHandle);
+            }
+            catch (err) {
+                console.error("[masons_unlink_identity] removeIdentityLinks failed:", err);
+                return textResult("Failed to remove identity link from config. Try again.");
+            }
+            return textResult([
+                `Identity link for "${ownerHandle}" removed.`,
+                "",
+                "Restart required — call the `gateway` tool with action: restart, " +
+                    'reason: "Remove cross-channel identity linking".',
+            ].join("\n"));
+        }),
+    }, { optional: true });
 }

package/dist/turn-context.d.ts

@@ -22,9 +22,31 @@
  * 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;AAaH;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEjE;AAMD;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,GAAG,IAAI,CAIxD"}
+{"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"}

package/dist/turn-context.js

@@ -21,6 +21,10 @@
 // ---------------------------------------------------------------------------
 /** Contact handle of the sender for the current turn. null = unknown/unset. */
 let currentTurnSender = null;
+/** Channel ID for the current turn. null = unknown/unset. */
+let currentTurnChannelId = null;
+/** Whether the current turn was triggered by the owner. */
+let currentTurnIsOwner = false;
 // ---------------------------------------------------------------------------
 // Write API (called from channel.ts)
 // ---------------------------------------------------------------------------
@@ -32,6 +36,22 @@ let currentTurnSender = null;
 export function setCurrentTurnSender(contact) {
     currentTurnSender = contact;
 }
+/**
+ * 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 function setCurrentTurnChannelId(channelId) {
+    currentTurnChannelId = channelId;
+}
+/**
+ * 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 function setCurrentTurnIsOwnerForTools(value) {
+    currentTurnIsOwner = value;
+}
 // ---------------------------------------------------------------------------
 // Read API (called from plugin.ts)
 // ---------------------------------------------------------------------------
@@ -44,3 +64,17 @@ export function consumeCurrentTurnSender() {
     currentTurnSender = null;
     return value;
 }
+/**
+ * Get the channel ID for the current turn (non-consuming).
+ * Used by tool access gates to determine which channel triggered the turn.
+ */
+export function getCurrentTurnChannelId() {
+    return currentTurnChannelId;
+}
+/**
+ * Get the owner flag for the current turn (non-consuming).
+ * Used by tool access gates to enforce owner-only tools.
+ */
+export function getCurrentTurnIsOwnerNonConsuming() {
+    return currentTurnIsOwner;
+}

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.19";
+export declare const PLUGIN_VERSION = "0.4.21";
 //# 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.19";
+export const PLUGIN_VERSION = "0.4.21";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masons/agent-network",
-  "version": "0.4.19",
+  "version": "0.4.21",
   "description": "MASONS plugin for OpenClaw — connect your agent to the agent network",
   "license": "MIT",
   "author": "MASONS.ai <hello@masons.ai> (https://masons.ai)",
@@ -19,6 +19,15 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "tsc -p test/tsconfig.json && node --test --loader ts-node/esm test/**/*.test.ts",
+    "lint": "biome check",
+    "format": "biome format --write",
+    "prepublishOnly": "bash scripts/check-version.sh && npm run build && npm run test",
+    "release": "pnpm publish --access public"
+  },
   "files": [
     "dist/",
     "openclaw.plugin.json",
@@ -68,13 +77,5 @@
     "@types/ws": "^8",
     "ts-node": "^10",
     "typescript": "^5"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "tsc -p test/tsconfig.json && node --test --loader ts-node/esm test/**/*.test.ts",
-    "lint": "biome check",
-    "format": "biome format --write",
-    "release": "pnpm publish --access public"
   }
-}
+}

package/skills/agent-network/SKILL.md

@@ -52,7 +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**
+- **User asks about cross-channel identity or why they appear as different people on different channels** → 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
@@ -166,46 +166,55 @@ After Step 3, the tool will confirm all three fields are filled and clear `needs
 
 ## 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.
+Reference section — use when:
+- Your owner asks about cross-channel identity or why they appear as a different person on different channels
+- You received a notification about the owner visiting Passport and identity linking being available
+- Your owner asks to link or unlink identities
 
-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.
+**Background**: When the owner visits the Passport page, the plugin detects them via verified authentication (crypto, not guessing). If identity linking is not yet configured and the session mode allows it, you receive a notification on your owner's next turn. You can then guide the owner through linking their identity on the current channel.
 
-### Step 1: Get Telegram user ID
+**How it works**: Each channel has a different peer ID for the same person. Identity linking maps these IDs to a single canonical name, so the gateway treats them as one person. The canonical name and Passport entry are set automatically — the owner only needs to provide the current channel's 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."
+### Acknowledging the notification
 
-**Then:** Wait for the user to provide their Telegram user ID.
+When your context includes a notification about the owner visiting Passport:
 
-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.
+**Say to owner:** Explain that you detected their visit to your web page, and offer to link their identities so conversations share context across channels. Ask for their user ID on this channel (e.g., Telegram numeric ID).
 
-### Step 2: Confirm
+### Linking identities
 
-**Say to user:** "I'll link your identities so I recognize you across channels:
-- Telegram: `{telegram_id}`
-- Agent Network: `passport:@{handle}`
+**Pre-check:** If `masons_link_identity` is not in your tool list, STOP. The plugin may be outdated. Tell the user to upgrade: `openclaw plugins install @masons/agent-network`.
 
-This means our conversations on Telegram and the agent network will share context. OK?"
+**Then:** Once the owner provides their channel ID, call `masons_link_identity` with:
+- `entry`: `"channel:peerId"` (e.g., `"telegram:5099353300"`, `"feishu:ou_abc123"`)
 
-**Then:** Wait for confirmation.
+The canonical name and Passport entry are added automatically. One channel at a time — if the owner uses multiple channels, repeat for each.
 
-### Step 3: Link
+**Say to owner:** Relay the tool output (it explains the expected effect based on session configuration).
 
-**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 `gateway` with: `action: "restart"`, `delayMs: 2000`, `reason: "Activate cross-channel identity linking"`, `note: "Cross-channel identity linked."`
 
-**Then:** Call `masons_link_identity` with the Telegram user ID.
+**Fallback:** If the `gateway` tool is not available or fails:
+**Say to owner:** "I couldn't restart automatically. Please run in your terminal: `openclaw gateway restart`"
+
+### Unlinking identities
+
+**Say to owner:** "I'll remove the cross-channel link. After a restart, conversations on each channel will be separate again."
 
-**Say to user:** "Identity linked! I need to restart for this to take effect."
+**Then:** Call `masons_unlink_identity` (no parameters needed — it uses the canonical name automatically).
 
-**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."`
+**Then:** Call `gateway` with: `action: "restart"`, `delayMs: 2000`, `reason: "Remove cross-channel identity linking"`, `note: "Cross-channel identity unlinked."`
 
 **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`"
+**Say to owner:** "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`.
+- If `masons_link_identity` returns an error about invalid format, each entry must be `channel:peerId` (e.g., `telegram:5099353300`). Telegram IDs must be numeric.
+- If the owner doesn't know their channel user ID, suggest ways to find it (e.g., messaging `@userinfobot` on Telegram for Telegram IDs).
+- If the tool returns a write failure, suggest trying again.
+- If the tool says identity linking is only available to the owner, this is a security gate — only the owner can invoke this tool.
+- If the tool is missing from your tool list, suggest upgrading the plugin.
 
 ## Connect