@masons/agent-network 0.4.18 → 0.4.20

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":"AAcA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAgC9D,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;AAsRD,eAAO,MAAM,mBAAmB,EAAE,yBAsNjC,CAAC"}

package/dist/channel.js

@@ -1,14 +1,19 @@
 import { randomUUID } from "node:crypto";
 import createDebug from "debug";
-import { clearConnectorClient, clearConversationManager, extractNetworkConfig, initConnectorClient, initConversationManager, initToolConfig, requirePluginRuntime, } from "./config.js";
+import { clearConnectorClient, clearConversationManager, extractNetworkConfig, getTelegramOwnerUserId, initConnectorClient, initConversationManager, initToolConfig, isIdentityLinksConfigured, requirePluginRuntime, writeIdentityLinks, } from "./config.js";
 import { ConnectorClient } from "./connector-client.js";
 import { ConversationManager } from "./conversation-manager.js";
-import { clearEnvironmentContext } from "./environment-context.js";
+import { clearEnvironmentContext, getOwnerHandle, } 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 auto-link: once per startAccount lifecycle idempotency
+// guard. Reset on startAccount(). isIdentityLinksConfigured() provides the
+// cross-restart idempotency (checks config file).
+let identityLinkAttempted = false;
 // --- Sender identity ---
 /**
  * Extract a human-readable name from the sender's metadata.
@@ -81,6 +86,53 @@ async function handleAddressedMessage(event, conversationManager, client, ctx) {
     // Connector includes is_owner in metadata for Passport visitors.
     if (event.metadata?.is_owner === true) {
         markOwnerAddress(fromAddress);
+        // --- Cross-channel identity auto-link (2026-03-26, #969) ---
+        // When owner visits Passport and identity is not yet linked,
+        // auto-configure session.identityLinks for session merge.
+        //
+        // Trust levels of data used here:
+        // - is_owner: cryptographically derived (Clerk JWT match) — triggers write
+        // - ownerHandle (from REGISTER_ACK): Connector-asserted — used only as
+        //   canonical group name, not for access decisions
+        // - telegramId (from cfg.channels.telegram.allowFrom): config-derived —
+        //   inferred owner in single-user setup, not crypto-verified
+        if (!isIdentityLinksConfigured() && !identityLinkAttempted) {
+            identityLinkAttempted = true;
+            const ownerHandle = getOwnerHandle();
+            const telegramId = getTelegramOwnerUserId();
+            if (ownerHandle && telegramId) {
+                // Scenario A: allowFrom has 1 ID — act-then-inform (Gmail undo).
+                // Notification is conditional on write success to avoid false positive.
+                const entries = [
+                    `telegram:${telegramId}`,
+                    `agent-network:${fromAddress}`,
+                ];
+                writeIdentityLinks(ownerHandle, entries)
+                    .then(() => {
+                    // TODO: i18n — notification language should match owner's locale
+                    ownerNotesQueue.enqueue({
+                        content: "你刚才在我的网页上跟我聊过。我已经准备好了跨渠道关联 — " +
+                            "重启后不管你从 Telegram 还是网页跟我对话，我都会记得之前聊过什么。" +
+                            "如果这不是你，告诉我撤销。",
+                        timestamp: Date.now(),
+                    });
+                    dbg("auto-linked owner identity: %s → telegram:%s + agent-network:%s", ownerHandle, telegramId, fromAddress);
+                })
+                    .catch((err) => {
+                    dbg("auto-link writeIdentityLinks failed: %O", err);
+                });
+            }
+            else if (ownerHandle) {
+                // Scenario B: cannot determine Telegram ID — notify owner.
+                // TODO: i18n — notification language should match owner's locale
+                ownerNotesQueue.enqueue({
+                    content: "你刚才在我的网页上跟我聊过。如果你想让我在 Telegram 和网页上" +
+                        "都能认出你、记住对话，告诉我你的 Telegram 用户 ID。",
+                    timestamp: Date.now(),
+                });
+                dbg("owner detected on Passport but no Telegram ID available");
+            }
+        }
     }
     setCurrentTurnIsOwner(isOwnerAddress(fromAddress));
     // Resolve contact from address. Register inbound conversation if new.
@@ -246,6 +298,7 @@ export const agentNetworkChannel = {
     gateway: {
         async startAccount(ctx) {
             dbg("starting account %s", ctx.accountId);
+            identityLinkAttempted = false; // Reset per-session idempotency guard
             // 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,6 +38,14 @@ 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` 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;
+/** Telegram owner user ID (only when allowFrom has exactly 1 entry). */
+export declare function getTelegramOwnerUserId(): string | null;
 /**
  * Inject the live ConnectorClient after WebSocket connection is established.
  *
@@ -183,6 +191,27 @@ 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>;
+/**
+ * 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

@@ -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 + cfg.channels.telegram — set by initToolConfig)
+let storedIdentityLinksConfigured = false;
+let storedTelegramOwnerUserId = null;
 // 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,95 @@ export function initToolConfig(cfg) {
             ? networkCfg.pendingTarget
             : null;
     storedNeedsProfile = networkCfg?.needsProfile === true;
+    // --- Cross-channel identity state (cfg.session, not cfg.channels) ---
+    // Decision: 2026-03-26, during cross-channel identity linking design (#969).
+    //
+    // Global Awareness (cross-channel, platform-gap workaround)
+    // Reads Gateway-level session.identityLinks to detect if the owner's
+    // agent-network identity is linked to other channels. Used by
+    // channel.ts auto-link logic and tools.
+    //
+    // 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);
+    storedTelegramOwnerUserId = extractTelegramOwnerUserId(cfg);
+}
+// ---------------------------------------------------------------------------
+// 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` 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;
+}
+/**
+ * Extract the owner's Telegram user ID from `cfg.channels.telegram.allowFrom`.
+ *
+ * Returns the ID only when `allowFrom` has exactly one entry (deterministic
+ * single-user case). Multi-user `allowFrom` returns null — cannot determine
+ * which ID is the owner.
+ *
+ * Trust level: config-derived (not cryptographically verified). Ownership is
+ * inferred from the single-user assumption (allowFrom has exactly 1 entry =
+ * that person is the owner by convention).
+ *
+ * Platform-gap workaround (2026-03-26, #969): reads another channel's config
+ * (cfg.channels.telegram) to infer the owner's Telegram ID. When OpenClaw
+ * provides a native "owner identifiers" API, this cross-channel read should
+ * be removed.
+ *
+ * Strips `telegram:` / `tg:` prefix if present (OpenClaw normalizes these).
+ */
+function extractTelegramOwnerUserId(cfg) {
+    const channels = cfg.channels;
+    if (!channels)
+        return null;
+    const telegram = channels.telegram;
+    if (!telegram)
+        return null;
+    const allowFrom = telegram.allowFrom;
+    if (!Array.isArray(allowFrom) || allowFrom.length !== 1)
+        return null;
+    const raw = String(allowFrom[0] ?? "")
+        .replace(/^(telegram|tg):/i, "")
+        .trim();
+    // Validate: must be numeric, 1-20 digits
+    if (/^\d{1,20}$/.test(raw))
+        return raw;
+    return null;
+}
+/** Telegram owner user ID (only when allowFrom has exactly 1 entry). */
+export function getTelegramOwnerUserId() {
+    return storedTelegramOwnerUserId;
 }
 // ---------------------------------------------------------------------------
 // ConnectorClient injection (called by startAccount() after connect)
@@ -385,6 +477,75 @@ 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++;
+}
+/**
+ * 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.
  *
@@ -420,6 +581,8 @@ export function _resetForTesting() {
     storedApiKey = null;
     storedPendingTarget = null;
     storedNeedsProfile = false;
+    storedIdentityLinksConfigured = false;
+    storedTelegramOwnerUserId = null;
     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":"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":"AAqHA,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;CAwUhC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/plugin.js

@@ -4,7 +4,7 @@
 import { agentNetworkChannel } from "./channel.js";
 import { configureInteractive } from "./cli-setup.js";
 import { detectPendingState, getConversationManager, getStateCacheGeneration, initPluginRuntime, } from "./config.js";
-import { getAgentIdentity, getOwnerHandle, getOwnerIdentity, } from "./environment-context.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";
@@ -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,7 +196,14 @@ 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 (2026-03-26) ---
+            "When your owner visits your Passport page, the plugin may automatically " +
+            "link their cross-channel identity based on verified authentication. " +
+            "This does not change who your owner is — it helps you recognize them " +
+            "across channels so conversations share context. " +
+            "If your owner asks about cross-channel identity, explain how it works. " +
+            "Use masons_link_identity to link or masons_unlink_identity to undo.";
         api.on("before_prompt_build", async (_event, ctx) => {
             const hookCtx = ctx;
             const channelId = hookCtx?.channelId;
@@ -302,7 +306,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 +350,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,25 +358,18 @@ 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.
+            // --- 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;

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,CA+6BhD"}

package/dist/tools.js

@@ -19,7 +19,7 @@
  */
 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, removeIdentityLinks, requireApiKey, requireConversationManager, requirePlatformConfig, writeCredentials, writeIdentityLinks, } from "./config.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 +749,90 @@ export function registerTools(api) {
             ].join("\n"));
         },
     });
+    // --- masons_link_identity -------------------------------------------------
+    // Generalized interface: accepts any canonical name and entries.
+    // Not locked to owner or Telegram — any cross-channel identity can be linked.
+    // See system-design.md §4C for design rationale.
+    api.registerTool({
+        name: "masons_link_identity",
+        description: "Link a person's identity across channels so they are recognized as the same person. " +
+            "Each entry is in 'channel:peerId' format (e.g., 'telegram:5099353300', " +
+            "'agent-network:passport:@luomingke'). Requires a gateway restart to take effect.",
+        parameters: Type.Object({
+            canonical: Type.String({
+                description: "Identity group name — all entries under this name are treated as the same person.",
+            }),
+            entries: Type.Array(Type.String(), {
+                description: "Array of 'channel:peerId' entries to link (at least 2).",
+                minItems: 2,
+            }),
+        }),
+        execute: async (_id, params) => {
+            const canonical = String(params.canonical ?? "").trim();
+            if (!canonical) {
+                return textResult("Canonical name must be non-empty.");
+            }
+            const entries = params.entries;
+            if (!Array.isArray(entries) || entries.length < 2) {
+                return textResult("At least 2 entries are required to link identities.");
+            }
+            // Validate each entry has channel:peerId format
+            const validated = [];
+            for (const entry of entries) {
+                const str = String(entry).trim();
+                if (!str.includes(":")) {
+                    return textResult(`Invalid entry "${str}": must be in 'channel:peerId' format.`);
+                }
+                validated.push(str);
+            }
+            try {
+                await writeIdentityLinks(canonical, validated);
+            }
+            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: ${canonical}`,
+                `Entries: ${validated.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.
+    { optional: true });
+    // --- masons_unlink_identity -----------------------------------------------
+    // Undo path: removes a canonical identity group from session.identityLinks.
+    api.registerTool({
+        name: "masons_unlink_identity",
+        description: "Remove a cross-channel identity link. Reverses masons_link_identity. " +
+            "Requires a gateway restart to take effect.",
+        parameters: Type.Object({
+            canonical: Type.String({
+                description: "The canonical identity group name to remove.",
+            }),
+        }),
+        execute: async (_id, params) => {
+            const canonical = String(params.canonical ?? "").trim();
+            if (!canonical) {
+                return textResult("Canonical name must be non-empty.");
+            }
+            try {
+                await removeIdentityLinks(canonical);
+            }
+            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 "${canonical}" removed.`,
+                "",
+                "Restart required — call the `gateway` tool with action: restart, " +
+                    'reason: "Remove cross-channel identity linking".',
+            ].join("\n"));
+        },
+    }, { 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.20";
 //# 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.20";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masons/agent-network",
-  "version": "0.4.18",
+  "version": "0.4.20",
   "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**
+- **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
@@ -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
+
+Reference section — use when your owner asks about cross-channel identity, why they appear as a different person on different channels, or wants to link/unlink identities.
+
+**Background**: When the owner visits the Passport page, the plugin may automatically link their cross-channel identity based on verified authentication. The owner receives a notification about this on their next Telegram turn. If the automatic linking didn't happen (e.g., multiple Telegram users configured), the owner may need to provide their Telegram user ID manually.
+
+### Linking identities
+
+**Pre-check:** If `masons_link_identity` is not in your tool list, STOP. Do not proceed — the plugin may be outdated. Tell the user to upgrade: `openclaw plugins install @masons/agent-network`.
+
+**Say to user:** "I can link your identities across channels so our conversations share context. I'll need a name for the link (your handle works) and your Telegram user ID — a numeric ID like `5099353300`. If you don't know it, message `@userinfobot` on Telegram."
+
+**Then:** Once the owner provides both, call `masons_link_identity` with:
+- `canonical`: the name they provided
+- `entries`: `["telegram:{their_id}", "agent-network:passport:@{their_handle}"]`
+
+Note: the `passport:@handle` part is the full peer ID as the Connector addresses it — keep it as one piece, do not split.
+
+**Say to user:** "Linked! I'll restart now so it takes effect — after that, I'll remember our conversations regardless of which channel you use."
+
+**Then:** Call `gateway` with: `action: "restart"`, `delayMs: 2000`, `reason: "Activate cross-channel identity linking"`, `note: "Cross-channel identity linked. Owner recognized across channels."`
+
+**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`"
+
+### Unlinking identities
+
+**Say to user:** "I'll remove the cross-channel link. After a restart, conversations on each channel will be separate again."
+
+**Then:** Call `masons_unlink_identity` with the canonical name.
+
+**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`"
+
+### Errors
+
+- If `masons_link_identity` returns an error about invalid entries, check the format: each entry must be `channel:peerId` (e.g., `telegram:5099353300`). Telegram IDs must be numeric.
+- If the owner doesn't know their Telegram user ID, suggest messaging `@userinfobot` on Telegram.
+- If the tool returns a write failure, suggest trying again.
+- If the tool is missing from your tool list, suggest upgrading the plugin.
+
 ## Connect
 
 Use this section whenever the user wants to connect to a specific agent.