@masons/agent-network 0.4.17 → 0.4.19

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;AAsB9D,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,yBAoNjC,CAAC"}
+{"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"}

package/dist/channel.js

@@ -3,6 +3,7 @@ import createDebug from "debug";
 import { clearConnectorClient, clearConversationManager, extractNetworkConfig, initConnectorClient, initConversationManager, initToolConfig, 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 { clearOwnerState, isOwnerAddress, markOwnerAddress, setCurrentTurnIsOwner, } from "./owner-session-state.js";
 import { setCurrentTurnSender } from "./turn-context.js";
@@ -283,9 +284,10 @@ export const agentNetworkChannel = {
                 dbg("delivery_pending → ACK sent count=%d upTo=%s", event.count, event.upTo);
             });
             // --- Disconnect ---
-            // On disconnect, all owner addresses are invalid — clear owner state.
+            // On disconnect, all session state is invalid — clear owner + environment.
             client.on("disconnected", () => {
                 clearOwnerState();
+                clearEnvironmentContext();
             });
             // --- Error handling ---
             // Must register before connect() — unhandled "error" events crash the process.

package/dist/config.d.ts

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

package/dist/config.d.ts.map

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

package/dist/config.js

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

package/dist/connector-client.d.ts.map

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

package/dist/connector-client.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
 import createDebug from "debug";
 import WebSocket from "ws";
+import { setEnvironmentContext } from "./environment-context.js";
 import { CURRENT_PROTOCOL_VERSION, isAddressedMessage, isDeliveryPending, isRegisterAck, isSendAck, isStructuredError, REGISTER_ACK_TIMEOUT_MS, SEND_ACK_TIMEOUT_MS, } from "./types.js";
 import { PLUGIN_VERSION } from "./version.js";
 const dbg = createDebug("agent-network:connector");
@@ -231,6 +232,9 @@ export class ConnectorClient extends EventEmitter {
             if (ack.protocolVersion !== CURRENT_PROTOCOL_VERSION) {
                 dbg("WARN: server negotiated protocolVersion=%d, expected=%d", ack.protocolVersion, CURRENT_PROTOCOL_VERSION);
             }
+            // Store agent + owner identity from enriched REGISTER_ACK (#969).
+            // Old Connectors omit these fields — setEnvironmentContext handles undefined.
+            setEnvironmentContext(ack.agent, ack.owner);
             this.backoffMs = BACKOFF_INITIAL_MS;
             this.alreadyConnectedRetries = 0;
             this.resolveRegister();

package/dist/environment-context.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Agent Environment Context — self-identity and owner identity.
+ *
+ * Populated from REGISTER_ACK when the Connector includes agent/owner fields
+ * (#969). Connection-scoped: cleared on disconnect, refreshed on reconnect.
+ *
+ * Module-level singleton — shared between connector-client.ts (write) and
+ * plugin.ts (read). Follows the same pattern as owner-session-state.ts.
+ *
+ * **Trust model**: Identity is Connector-asserted, not cryptographically
+ * verified. The Plugin trusts the Connector because they communicate over an
+ * authenticated WebSocket channel. A self-hosted Connector could assert
+ * arbitrary identity — this is the same trust level as the `from` field on
+ * MESSAGE_RECEIVED. Do not build security-critical logic on these values.
+ */
+export interface AgentIdentity {
+    handle: string;
+    name?: string;
+}
+export interface OwnerIdentity {
+    handle: string;
+    displayName?: string;
+}
+/**
+ * Store agent and owner identity from an enriched REGISTER_ACK.
+ *
+ * Either parameter may be undefined (old Connector, or agent without
+ * a bound owner). Undefined values leave the corresponding state as null.
+ */
+export declare function setEnvironmentContext(agent?: {
+    handle: string;
+    name?: string;
+}, owner?: {
+    handle: string;
+    displayName?: string;
+}): void;
+export declare function getAgentIdentity(): AgentIdentity | null;
+export declare function getOwnerIdentity(): OwnerIdentity | null;
+/** Convenience: get the owner's handle for interaction tagging. */
+export declare function getOwnerHandle(): string | null;
+/** Clear all environment context (connection lost — identity invalid). */
+export declare function clearEnvironmentContext(): void;
+/** @internal Reset module state for test isolation. */
+export declare function _resetForTesting(): void;
+//# sourceMappingURL=environment-context.d.ts.map

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

@@ -0,0 +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"}

package/dist/environment-context.js

@@ -0,0 +1,81 @@
+/**
+ * Agent Environment Context — self-identity and owner identity.
+ *
+ * Populated from REGISTER_ACK when the Connector includes agent/owner fields
+ * (#969). Connection-scoped: cleared on disconnect, refreshed on reconnect.
+ *
+ * Module-level singleton — shared between connector-client.ts (write) and
+ * plugin.ts (read). Follows the same pattern as owner-session-state.ts.
+ *
+ * **Trust model**: Identity is Connector-asserted, not cryptographically
+ * verified. The Plugin trusts the Connector because they communicate over an
+ * authenticated WebSocket channel. A self-hosted Connector could assert
+ * arbitrary identity — this is the same trust level as the `from` field on
+ * MESSAGE_RECEIVED. Do not build security-critical logic on these values.
+ */
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+let agentIdentity = null;
+let ownerIdentity = null;
+// ---------------------------------------------------------------------------
+// Write API (called from connector-client.ts on REGISTER_ACK)
+// ---------------------------------------------------------------------------
+/**
+ * Store agent and owner identity from an enriched REGISTER_ACK.
+ *
+ * Either parameter may be undefined (old Connector, or agent without
+ * a bound owner). Undefined values leave the corresponding state as null.
+ */
+export function setEnvironmentContext(agent, owner) {
+    // Defensive: validate handle is a string even though types say so.
+    // A malformed REGISTER_ACK from an untrusted Connector could send
+    // non-string values; guard prevents storing garbage in module state.
+    if (agent && typeof agent.handle === "string") {
+        const identity = { handle: agent.handle };
+        if (agent.name)
+            identity.name = agent.name;
+        agentIdentity = identity;
+    }
+    else {
+        agentIdentity = null;
+    }
+    if (owner && typeof owner.handle === "string") {
+        const identity = { handle: owner.handle };
+        if (owner.displayName)
+            identity.displayName = owner.displayName;
+        ownerIdentity = identity;
+    }
+    else {
+        ownerIdentity = null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Read API (called from plugin.ts in before_prompt_build)
+// ---------------------------------------------------------------------------
+export function getAgentIdentity() {
+    return agentIdentity;
+}
+export function getOwnerIdentity() {
+    return ownerIdentity;
+}
+/** Convenience: get the owner's handle for interaction tagging. */
+export function getOwnerHandle() {
+    return ownerIdentity?.handle ?? null;
+}
+// ---------------------------------------------------------------------------
+// Lifecycle
+// ---------------------------------------------------------------------------
+/** Clear all environment context (connection lost — identity invalid). */
+export function clearEnvironmentContext() {
+    agentIdentity = null;
+    ownerIdentity = null;
+}
+// ---------------------------------------------------------------------------
+// Test-only reset
+// ---------------------------------------------------------------------------
+/** @internal Reset module state for test isolation. */
+export function _resetForTesting() {
+    agentIdentity = null;
+    ownerIdentity = null;
+}

package/dist/plugin.d.ts.map

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

package/dist/plugin.js

@@ -3,7 +3,8 @@
 // NOT imported by index.ts to avoid pulling ws/typebox into Next.js app bundles.
 import { agentNetworkChannel } from "./channel.js";
 import { configureInteractive } from "./cli-setup.js";
-import { detectPendingState, getConversationManager, getStateCacheGeneration, initPluginRuntime, } from "./config.js";
+import { detectPendingState, getConversationManager, getStateCacheGeneration, initPluginRuntime, isIdentityLinkHintShown, isIdentityLinksConfigured, markIdentityLinkHintShown, } from "./config.js";
+import { getAgentIdentity, getOwnerHandle, getOwnerIdentity, } from "./environment-context.js";
 import { ownerNotesQueue } from "./owner-notes.js";
 import { consumeCurrentTurnIsOwner } from "./owner-session-state.js";
 import { sentMessageBuffer } from "./sent-message-buffer.js";
@@ -43,7 +44,7 @@ const MAX_INTERACTIONS = 5;
  *
  * Returns undefined if no interactions exist or CM is not available.
  */
-function buildInteractionContext(channelId, turnSender) {
+function buildInteractionContext(channelId, turnSender, ownerHandle) {
     const cm = getConversationManager();
     if (!cm)
         return undefined;
@@ -60,9 +61,12 @@ function buildInteractionContext(channelId, turnSender) {
         : "[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} — ${initiated} — last activity ${when}`;
+        return `• ${who}${ownerTag} — ${initiated} — last activity ${when}`;
     });
     const isNetworkTurn = channelId === "agent-network";
     if (isNetworkTurn && turnSender) {
@@ -298,7 +302,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);
+                        const interactionCtx = buildInteractionContext(channelId, turnSender, getOwnerHandle());
                         if (interactionCtx) {
                             dynamicContext += `\n\n${interactionCtx}`;
                         }
@@ -342,7 +346,7 @@ const plugin = {
                     }
                     // Append interaction space on owner turns too (#873).
                     // Gives the agent awareness of active network interactions.
-                    const interactionCtx = buildInteractionContext(channelId, null);
+                    const interactionCtx = buildInteractionContext(channelId, null, getOwnerHandle());
                     if (interactionCtx) {
                         dynamicContext = dynamicContext
                             ? `${dynamicContext}\n\n${interactionCtx}`
@@ -350,6 +354,49 @@ 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.
+            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;AA4CH,UAAU,WAAW;IACnB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,CACP,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,WAAW,CAAC,CAAC;CAC3B;AAED,UAAU,OAAO;IACf,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACzE;AA0CD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAsFD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAszBhD"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA8CH,UAAU,WAAW;IACnB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,CACP,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,WAAW,CAAC,CAAC;CAC3B;AAED,UAAU,OAAO;IACf,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACzE;AA0CD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAsFD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAq3BhD"}

package/dist/tools.js

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

package/dist/types.d.ts

@@ -32,6 +32,16 @@ export interface RegisterAckEvent {
     status: "ok" | "error";
     reason?: string;
     protocolVersion: number;
+    /** Agent identity — present when Connector supports environment context (#969). */
+    agent?: {
+        handle: string;
+        name?: string;
+    };
+    /** Owner identity — present when agent has a bound owner with a MASONS account. */
+    owner?: {
+        handle: string;
+        displayName?: string;
+    };
 }
 /**
  * Delivery confirmation for a sent message.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAC1C,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAC9C,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAQ1C,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qDAAqD;AACrD,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,cAAc,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,qDAAqD;AACrD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,QAAQ,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,iEAAiE;AACjE,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,cAAc,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAID,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,cAAc,CAAC;IACtB,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;CAC3C;AAED,gDAAgD;AAChD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,kBAAkB,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,6DAA6D;AAC7D,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,kBAAkB,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,mDAAmD;AACnD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD,MAAM,MAAM,sBAAsB,GAC9B,aAAa,GACb,kBAAkB,GAClB,oBAAoB,GACpB,yBAAyB,CAAC;AAE9B,MAAM,MAAM,sBAAsB,GAC9B,gBAAgB,GAChB,YAAY,GACZ,qBAAqB,GACrB,oBAAoB,GACpB,oBAAoB,CAAC;AAUzB,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,gBAAgB,CAErE;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,YAAY,CAM7D;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,OAAO,GACZ,IAAI,IAAI,qBAAqB,CAO/B;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,oBAAoB,CAO7E;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,oBAAoB,CAO7E"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

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.17";
+export declare const PLUGIN_VERSION = "0.4.19";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

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

package/package.json

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