@masons/agent-network 0.4.4 → 0.4.6

package/dist/config.d.ts

@@ -17,6 +17,11 @@
 import type { ConnectorClient } from "./connector-client.js";
 import type { ConversationManager } from "./conversation-manager.js";
 import { type PlatformClientConfig } from "./platform-client.js";
+/**
+ * Current state cache generation. Incremented by config-modifying functions.
+ * Used by before_prompt_build to detect when cached state needs a refresh.
+ */
+export declare function getStateCacheGeneration(): number;
 /**
  * Extract the `channels.agent-network` section from the full OpenClaw config.
  *
@@ -149,18 +154,18 @@ export declare function clearTargetHandle(): Promise<void>;
  * Mark that this agent needs profile completion.
  *
  * Called after onboard (new agent creation) — the agent has an empty profile.
- * The before_agent_start hook reads this to inject profile generation context.
+ * The before_prompt_build hook reads this to inject profile generation context.
  */
 export declare function markProfileNeeded(): Promise<void>;
 /**
  * Mark that profile completion is done.
  *
  * Called after successful masons_update_profile — clears the needsProfile flag
- * so the before_agent_start hook no longer injects profile context on restart.
+ * so the before_prompt_build hook no longer injects profile context.
  *
  * Note: unlike clearTargetHandle, this only writes to disk — there is no
- * module-level variable for needsProfile. The before_agent_start hook is
- * one-shot (hasInjectedContinuity flag), so stale reads are not a concern.
+ * module-level variable for needsProfile. The before_prompt_build hook
+ * uses stateCacheGeneration to detect when a re-read is needed.
  */
 export declare function markProfileComplete(): Promise<void>;
 /** Pending state detected from config file — used for restart continuity. */
@@ -177,7 +182,7 @@ export interface PendingState {
  *
  * Unlike `initToolConfig()` which is called by `startAccount()`, this reads
  * from disk — available even when the channel hasn't started (no credentials).
- * Used by Layer B (before_agent_start hook) to inject restart continuity.
+ * Used by Layer B (before_prompt_build hook) for per-turn context injection.
  */
 export declare function detectPendingState(): Promise<PendingState>;
 /** @internal Reset module state for test isolation. */

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AA4B9B;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAMhC;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAsBjE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAOjE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAMD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED;;GAEG;AACH,wBAAgB,0BAA0B,IAAI,mBAAmB,CAOhE;AAMD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAExD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAO9C;AAMD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,oBAAoB,CAE5D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,CAOxD;AAMD,+EAA+E;AAC/E,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAgDD,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,kBAAkB,EACzB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKrE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAQvD;AAMD;;;;;GAKG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKvD;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKzD;AAMD,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,cAAc,EAAE,OAAO,CAAC;IACxB,wDAAwD;IACxD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,4EAA4E;IAC5E,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,YAAY,CAAC,CA2BhE;AAMD,uDAAuD;AACvD,wBAAgB,gBAAgB,IAAI,IAAI,CAOvC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AAsB9B;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAcD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAMhC;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAsBjE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAOjE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAMD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED;;GAEG;AACH,wBAAgB,0BAA0B,IAAI,mBAAmB,CAOhE;AAMD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAExD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAO9C;AAMD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,oBAAoB,CAE5D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,CAOxD;AAMD,+EAA+E;AAC/E,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAgDD,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,kBAAkB,EACzB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CASvD;AAMD;;;;;GAKG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAMvD;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAMzD;AAMD,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,cAAc,EAAE,OAAO,CAAC;IACxB,wDAAwD;IACxD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,4EAA4E;IAC5E,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,YAAY,CAAC,CA2BhE;AAMD,uDAAuD;AACvD,wBAAgB,gBAAgB,IAAI,IAAI,CAQvC"}

package/dist/config.js

@@ -30,6 +30,18 @@ import { DEFAULT_API_HOST, } from "./platform-client.js";
 let platformConfig = { apiHost: DEFAULT_API_HOST };
 let storedApiKey = null;
 let storedPendingTarget = 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
+// triggers a re-read of detectPendingState() from disk.
+let stateCacheGeneration = 0;
+/**
+ * Current state cache generation. Incremented by config-modifying functions.
+ * Used by before_prompt_build to detect when cached state needs a refresh.
+ */
+export function getStateCacheGeneration() {
+    return stateCacheGeneration;
+}
 // Runtime state (live connection — set by startAccount, cleared by stopAccount)
 let storedConnectorClient = null;
 let storedConversationManager = null;
@@ -284,6 +296,7 @@ export async function writeCredentials(creds, apiHost) {
     // same pattern as clearTargetHandle(). Without this, tools fail with
     // "No API key configured" until Gateway restarts and re-runs initToolConfig().
     storedApiKey = creds.token;
+    stateCacheGeneration++;
 }
 /**
  * Write pending connection target handle.
@@ -298,6 +311,7 @@ export async function writeTargetHandle(handle) {
     const section = ensureNetworkSection(config);
     section.pendingTarget = handle;
     await persistConfig(config);
+    stateCacheGeneration++;
 }
 /**
  * Clear pending connection target from config file AND module-level variable.
@@ -313,6 +327,7 @@ export async function clearTargetHandle() {
     await persistConfig(config);
     // Update module-level var — deliberate exception to read/write separation
     storedPendingTarget = null;
+    stateCacheGeneration++;
 }
 // ---------------------------------------------------------------------------
 // Profile state (set after onboard, cleared after profile update)
@@ -321,36 +336,38 @@ export async function clearTargetHandle() {
  * Mark that this agent needs profile completion.
  *
  * Called after onboard (new agent creation) — the agent has an empty profile.
- * The before_agent_start hook reads this to inject profile generation context.
+ * The before_prompt_build hook reads this to inject profile generation context.
  */
 export async function markProfileNeeded() {
     const config = await readConfig();
     const section = ensureNetworkSection(config);
     section.needsProfile = true;
     await persistConfig(config);
+    stateCacheGeneration++;
 }
 /**
  * Mark that profile completion is done.
  *
  * Called after successful masons_update_profile — clears the needsProfile flag
- * so the before_agent_start hook no longer injects profile context on restart.
+ * so the before_prompt_build hook no longer injects profile context.
  *
  * Note: unlike clearTargetHandle, this only writes to disk — there is no
- * module-level variable for needsProfile. The before_agent_start hook is
- * one-shot (hasInjectedContinuity flag), so stale reads are not a concern.
+ * module-level variable for needsProfile. The before_prompt_build hook
+ * uses stateCacheGeneration to detect when a re-read is needed.
  */
 export async function markProfileComplete() {
     const config = await readConfig();
     const section = ensureNetworkSection(config);
     delete section.needsProfile;
     await persistConfig(config);
+    stateCacheGeneration++;
 }
 /**
  * Detect pending state by reading config file directly.
  *
  * Unlike `initToolConfig()` which is called by `startAccount()`, this reads
  * from disk — available even when the channel hasn't started (no credentials).
- * Used by Layer B (before_agent_start hook) to inject restart continuity.
+ * Used by Layer B (before_prompt_build hook) for per-turn context injection.
  */
 export async function detectPendingState() {
     const config = await readConfig();
@@ -382,4 +399,5 @@ export function _resetForTesting() {
     storedConnectorClient = null;
     storedConversationManager = null;
     storedPluginRuntime = null;
+    stateCacheGeneration = 0;
 }

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

@@ -3,6 +3,7 @@ import { EventEmitter } from "node:events";
 import createDebug from "debug";
 import WebSocket from "ws";
 import { CURRENT_PROTOCOL_VERSION, isErrorEvent, isFlushComplete, isMessageReceived, isRegisterAck, isSessionCreated, isSessionEnded, REGISTER_ACK_TIMEOUT_MS, } from "./types.js";
+import { PLUGIN_VERSION } from "./version.js";
 const dbg = createDebug("agent-network:connector");
 const dbgMsg = createDebug("agent-network:connector:msg");
 // --- Reconnection constants ---
@@ -125,6 +126,7 @@ export class ConnectorClient extends EventEmitter {
             event: "REGISTER",
             token: this.token,
             protocolVersion: CURRENT_PROTOCOL_VERSION,
+            clientVersion: PLUGIN_VERSION,
         };
         this.send(event);
     }

package/dist/owner-notes.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Owner Notes Queue — in-memory queue for Principal notifications.
+ *
+ * When the LLM receives information from a remote agent that the owner
+ * should know about, it calls `masons_note_for_owner` which enqueues
+ * a note here. The `before_prompt_build` hook drains the queue on the
+ * owner's next turn and injects the notes into prependContext.
+ *
+ * Module-level singleton — shared between plugin.ts (drain) and tools.ts (enqueue).
+ * Same pattern as Mkclaw's PendingEventsQueue (see ref_mkclaw_cross_session.md).
+ *
+ * Lifecycle: in-memory only. Lost on Gateway restart. Layer 2 (MASONS backend)
+ * will add persistence — this queue is the Layer 1 implementation.
+ *
+ * @see docs/openclaw/interop-routing-system-design.md §7.1
+ */
+export interface OwnerNote {
+    /** The note content — summarized by the LLM. */
+    content: string;
+    /** When the note was created (Date.now()). */
+    timestamp: number;
+    /** Handle of the remote agent this note is about (e.g. "nikoko"). */
+    from?: string;
+}
+export declare class OwnerNotesQueue {
+    private notes;
+    static readonly MAX_SIZE = 50;
+    static readonly TTL_MS: number;
+    /**
+     * Enqueue a note. FIFO: if at MAX_SIZE after TTL eviction, drops oldest.
+     * Always accepts the new note.
+     */
+    enqueue(note: OwnerNote): void;
+    /**
+     * Drain all non-stale notes. Destructive — drained notes are removed.
+     * Returns notes in chronological order (oldest first).
+     */
+    drain(): OwnerNote[];
+    /**
+     * Current queue size (after TTL eviction).
+     */
+    size(): number;
+    /**
+     * Clear all notes. For testing only.
+     */
+    clear(): void;
+    private evictStale;
+}
+export declare const ownerNotesQueue: OwnerNotesQueue;
+//# sourceMappingURL=owner-notes.d.ts.map

package/dist/owner-notes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner-notes.d.ts","sourceRoot":"","sources":["../src/owner-notes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,MAAM,WAAW,SAAS;IACxB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAAmB;IAEhC,MAAM,CAAC,QAAQ,CAAC,QAAQ,MAAM;IAC9B,MAAM,CAAC,QAAQ,CAAC,MAAM,SAAuB;IAE7C;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAQ9B;;;OAGG;IACH,KAAK,IAAI,SAAS,EAAE;IAOpB;;OAEG;IACH,IAAI,IAAI,MAAM;IAKd;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb,OAAO,CAAC,UAAU;CAInB;AAMD,eAAO,MAAM,eAAe,iBAAwB,CAAC"}

package/dist/owner-notes.js

@@ -0,0 +1,69 @@
+/**
+ * Owner Notes Queue — in-memory queue for Principal notifications.
+ *
+ * When the LLM receives information from a remote agent that the owner
+ * should know about, it calls `masons_note_for_owner` which enqueues
+ * a note here. The `before_prompt_build` hook drains the queue on the
+ * owner's next turn and injects the notes into prependContext.
+ *
+ * Module-level singleton — shared between plugin.ts (drain) and tools.ts (enqueue).
+ * Same pattern as Mkclaw's PendingEventsQueue (see ref_mkclaw_cross_session.md).
+ *
+ * Lifecycle: in-memory only. Lost on Gateway restart. Layer 2 (MASONS backend)
+ * will add persistence — this queue is the Layer 1 implementation.
+ *
+ * @see docs/openclaw/interop-routing-system-design.md §7.1
+ */
+// ---------------------------------------------------------------------------
+// Queue
+// ---------------------------------------------------------------------------
+export class OwnerNotesQueue {
+    notes = [];
+    static MAX_SIZE = 50;
+    static TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+    /**
+     * Enqueue a note. FIFO: if at MAX_SIZE after TTL eviction, drops oldest.
+     * Always accepts the new note.
+     */
+    enqueue(note) {
+        this.evictStale();
+        if (this.notes.length >= OwnerNotesQueue.MAX_SIZE) {
+            this.notes.shift(); // drop oldest (FIFO)
+        }
+        this.notes.push(note);
+    }
+    /**
+     * Drain all non-stale notes. Destructive — drained notes are removed.
+     * Returns notes in chronological order (oldest first).
+     */
+    drain() {
+        this.evictStale();
+        const drained = [...this.notes];
+        this.notes = [];
+        return drained;
+    }
+    /**
+     * Current queue size (after TTL eviction).
+     */
+    size() {
+        this.evictStale();
+        return this.notes.length;
+    }
+    /**
+     * Clear all notes. For testing only.
+     */
+    clear() {
+        this.notes = [];
+    }
+    // -------------------------------------------------------------------------
+    // Internal
+    // -------------------------------------------------------------------------
+    evictStale() {
+        const cutoff = Date.now() - OwnerNotesQueue.TTL_MS;
+        this.notes = this.notes.filter((n) => n.timestamp > cutoff);
+    }
+}
+// ---------------------------------------------------------------------------
+// Singleton
+// ---------------------------------------------------------------------------
+export const ownerNotesQueue = new OwnerNotesQueue();

package/dist/plugin.d.ts.map

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

package/dist/plugin.js

@@ -3,10 +3,28 @@
 // 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, initPluginRuntime } from "./config.js";
+import { detectPendingState, getStateCacheGeneration, initPluginRuntime, } from "./config.js";
+import { ownerNotesQueue } from "./owner-notes.js";
 import { registerTools } from "./tools.js";
 import { getUpdateInfo } from "./update-check.js";
 import { PLUGIN_VERSION } from "./version.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Format a timestamp as a human-readable relative time string. */
+function formatTimeAgo(timestamp) {
+    const diff = Date.now() - timestamp;
+    const minutes = Math.floor(diff / 60_000);
+    if (minutes < 1)
+        return "just now";
+    if (minutes < 60)
+        return `${minutes} min ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
+}
 const plugin = {
     id: "agent-network",
     version: PLUGIN_VERSION,
@@ -54,88 +72,168 @@ const plugin = {
         catch {
             // Silently ignore — channel will be registered after setup + restart.
         }
-        // --- Layer B: Restart continuity ---
-        // After gateway restart, the agent loses conversation context. This hook
-        // fires on the next user message and injects context to help the agent
-        // pick up where it left off (setup flow, pending connection requests).
+        // --- Layer B: Per-turn context injection ---
+        // Injects agent network awareness into every LLM turn via before_prompt_build.
         //
-        // One-shot: only injects on the first message after restart. Subsequent
-        // messages don't need it — the conversation itself provides continuity.
-        let hasInjectedContinuity = false;
-        api.on("before_agent_start", async () => {
-            if (hasInjectedContinuity)
-                return {};
-            try {
-                // 1-second timeout — Gateway has no timeout on before_agent_start
-                // hooks, so a hanging file read (network mount offline, antivirus
-                // lock) would block the user's message indefinitely. The timeout
-                // lets the message proceed without context injection.
-                const DETECT_TIMEOUT_MS = 1000;
-                const state = await Promise.race([
-                    detectPendingState(),
-                    new Promise((_, reject) => setTimeout(() => reject(new Error("Config read timeout")), DETECT_TIMEOUT_MS)),
-                ]);
-                // Set flag after successful read — if nothing is pending now,
-                // there won't be on subsequent messages either (state only changes
-                // across restarts). Placed AFTER read so a transient I/O failure
-                // allows retry on the next message instead of permanently disabling
-                // injection for this process lifecycle.
-                hasInjectedContinuity = true;
-                let context;
-                if (!state.hasCredentials) {
-                    // Just installed, no credentials yet — guide to setup
-                    context =
-                        "[Context: Agent Network] You recently installed the agent network plugin. Your user wants to connect to the agent network. Call the masons_setup_init tool to begin the setup process.";
-                    if (state.pendingTarget) {
-                        context += ` After setup, send a connection request to @${state.pendingTarget} — they invited your user to join.`;
-                    }
+        // Two injection channels:
+        // - prependSystemContext: stable content (tool list), KV-cacheable by OpenClaw
+        // - prependContext: dynamic content (setup state, pending target), changes across turns
+        //
+        // State detection reads config from disk. To avoid disk I/O every turn, the
+        // result is cached and only re-read when the state could have changed (on first
+        // turn, and when tools modify config — e.g. writeCredentials, clearTargetHandle).
+        //
+        // Replaces the previous one-shot before_agent_start hook. That hook only fired
+        // once per restart; this fires every turn, providing continuous awareness.
+        // History: before_prompt_build was discovered via Mkclaw plugin investigation
+        // (2026-03-18). The original Layer B (2026-03-11) used before_agent_start
+        // because before_prompt_build was not known at the time.
+        /** Cached state from last successful disk read. null = not yet read. */
+        let cachedState = null;
+        /** Generation at time of last cache fill. Mismatch → re-read. */
+        let cachedGeneration = -1;
+        // Stable system context — interoperation awareness + routing table.
+        // Encodes 3+1 semantic concepts for Day 1 competency:
+        //   1. Two channels (owner's channel + agent network)
+        //   2. Different audiences (never mix content between them)
+        //   3. One audience per turn (text reply → turn trigger)
+        //   +1. Information asymmetry (owner instructions are private)
+        // Single continuous string (no bullets/newlines) for KV-cache stability.
+        const TOOL_CONTEXT = "[Context: Agent Network] You are connected to the agent network. " +
+            "You operate on TWO channels simultaneously: " +
+            "your owner's (Principal's) channel (where your owner talks to you) and " +
+            "the agent network (where other agents and visitors reach you). " +
+            "These are different audiences — content for your owner stays in your owner's conversation, " +
+            "content for network senders stays on the network. Never mix them. " +
+            "Instructions from your owner are private by default — " +
+            "do not share them with network senders unless your owner explicitly asks you to. " +
+            "Your text reply goes to whoever triggered this turn. To reach someone else: " +
+            "masons_send_message(to, content) — send to a specific agent on the network, " +
+            "separate from your owner's conversation; " +
+            "masons_note_for_owner(content, from?) — save a note for your owner's next turn. " +
+            "Other network tools: masons_list_requests, masons_send_connection_request, " +
+            "masons_accept_request, masons_decline_request, masons_list_connections, " +
+            "masons_end_conversation. " +
+            "Always try these tools first for network operations. " +
+            "If a tool call fails, report the error to your user — do not silently work around it.";
+        api.on("before_prompt_build", async (_event, ctx) => {
+            const hookCtx = ctx;
+            const channelId = hookCtx?.channelId;
+            // --- Detect setup state (cached, re-read when config changes) ---
+            const currentGeneration = getStateCacheGeneration();
+            if (!cachedState || cachedGeneration !== currentGeneration) {
+                try {
+                    const DETECT_TIMEOUT_MS = 1000;
+                    cachedState = await Promise.race([
+                        detectPendingState(),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error("Config read timeout")), DETECT_TIMEOUT_MS)),
+                    ]);
+                    cachedGeneration = currentGeneration;
                 }
-                else if (state.needsProfile) {
-                    // Agent created but profile is empty — guide to profile completion
-                    context =
-                        "[Context: Agent Network] You are set up on the agent network, but your agent's profile is empty. " +
-                            "Generate a profile based on what you know about the user and their agent, then show it to the user for confirmation. " +
-                            "Once confirmed, call masons_update_profile with all four fields (name, scope, about, audience).";
-                    if (state.pendingTarget) {
-                        context += ` After completing the profile, send a connection request to @${state.pendingTarget} — they invited your user to join.`;
-                    }
+                catch {
+                    // Config read failure — proceed without state-specific context.
+                    // Will retry on next turn (cachedState stays null).
+                    return {};
                 }
-                else if (state.pendingTarget) {
-                    // Setup complete but pending connection — guide to connect
-                    context = `[Context: Agent Network] You are set up on the agent network. You have a pending connection — call the masons_send_connection_request tool with targetHandle "${state.pendingTarget}" to send a connection request.`;
+            }
+            const state = cachedState;
+            // --- Build dynamic context based on setup state ---
+            let dynamicContext;
+            if (!state.hasCredentials) {
+                // Just installed, no credentials yet — guide to setup
+                dynamicContext =
+                    "[Context: Agent Network] You recently installed the agent network plugin. Your user wants to connect to the agent network. Call the masons_setup_init tool to begin the setup process.";
+                if (state.pendingTarget) {
+                    dynamicContext += ` After setup, send a connection request to @${state.pendingTarget} — they invited your user to join.`;
                 }
-                else {
-                    // Connected and ready — remind LLM that network tools are available.
-                    // "try first + report failure" pattern: gates the first attempt toward
-                    // tools without blocking exec fallback if tools are genuinely broken
-                    // (e.g. { optional: true } preventing injection into LLM tool schema).
-                    context =
-                        "[Context: Agent Network] You are connected to the agent network. " +
-                            "Your network tools are loaded: " +
-                            "masons_list_requests (check incoming connection requests), " +
-                            "masons_send_connection_request (connect to another agent), " +
-                            "masons_accept_request (accept an incoming connection request), " +
-                            "masons_decline_request (decline an incoming connection request), " +
-                            "masons_send_message (send a message — sessions are automatic), " +
-                            "masons_end_conversation (end a conversation). " +
-                            "Always try these tools first for network operations. " +
-                            "If a tool call fails or a tool is not available, report the error to the user — do not silently work around it.";
+            }
+            else if (state.needsProfile) {
+                // Agent created but profile is empty — guide to profile completion
+                dynamicContext =
+                    "[Context: Agent Network] You are set up on the agent network, but your agent's profile is empty. " +
+                        "Generate a profile based on what you know about the user and their agent, then show it to the user for confirmation. " +
+                        "Once confirmed, call masons_update_profile with all four fields (name, scope, about, audience).";
+                if (state.pendingTarget) {
+                    dynamicContext += ` After completing the profile, send a connection request to @${state.pendingTarget} — they invited your user to join.`;
                 }
-                // Post-upgrade verification: if an update is still available after
-                // a gateway restart, the previous upgrade attempt may have failed.
-                const updateInfo = getUpdateInfo();
-                if (updateInfo?.updateAvailable) {
-                    const upgradeHint = ` Plugin update to v${updateInfo.latestVersion} is available.` +
-                        ` Call masons_upgrade to update — it handles everything automatically.` +
-                        ` Do NOT search ClawHub or run manual npm/openclaw commands.`;
-                    context = (context ?? "") + upgradeHint;
+            }
+            else if (state.pendingTarget) {
+                // Setup complete but pending connection — guide to connect
+                dynamicContext = `[Context: Agent Network] You are set up on the agent network. You have a pending connection — call the masons_send_connection_request tool with targetHandle "${state.pendingTarget}" to send a connection request.`;
+            }
+            // --- Routing context (connected and ready state only) ---
+            // When the agent has credentials, no pending setup, and no pending target,
+            // inject routing awareness based on which channel triggered this turn.
+            //
+            // Priority: setup/profile/pendingTarget state takes precedence over routing
+            // context. An agent in setup flow doesn't need routing warnings — it needs
+            // to complete setup first. Routing context only applies to the "ready" state.
+            if (!dynamicContext &&
+                state.hasCredentials &&
+                !state.needsProfile &&
+                !state.pendingTarget) {
+                if (channelId === "agent-network") {
+                    // Turn triggered by a remote agent — warn about routing.
+                    // The LLM's text reply will go to that agent via deliver callback.
+                    dynamicContext =
+                        "[Agent Network — Routing] This turn was triggered by a message " +
+                            "on the agent network. Your text reply will be sent to that sender — " +
+                            "your owner (Principal) will NOT see it. To report something to your owner, " +
+                            "call masons_note_for_owner.";
                 }
-                if (context) {
-                    return { prependContext: context };
+                else {
+                    // Owner turn (or other channel) — drain pending notes if any.
+                    const notes = ownerNotesQueue.drain();
+                    if (notes.length > 0) {
+                        const lines = notes.map((n) => {
+                            const fromStr = n.from ? `@${n.from}` : "agent";
+                            const timeStr = formatTimeAgo(n.timestamp);
+                            const preview = n.content.length > 100
+                                ? `${n.content.slice(0, 100)}...`
+                                : n.content;
+                            return `• ${fromStr} (${timeStr}): "${preview}"`;
+                        });
+                        dynamicContext =
+                            "[Agent Network — Updates]\n" +
+                                "The following happened on the agent network since your last turn:\n" +
+                                `${lines.join("\n")}\n` +
+                                "Report these to your owner.";
+                    }
                 }
             }
-            catch {
-                // Config read failure — don't block the agent, just skip injection
+            // Post-upgrade verification: if an update is still available after
+            // a gateway restart, the previous upgrade attempt may have failed.
+            const updateInfo = getUpdateInfo();
+            if (updateInfo?.updateAvailable) {
+                const upgradeHint = ` Plugin update to v${updateInfo.latestVersion} is available.` +
+                    ` Call masons_upgrade to update — it handles everything automatically.` +
+                    ` Do NOT search ClawHub or run manual npm/openclaw commands.`;
+                dynamicContext = (dynamicContext ?? "") + upgradeHint;
+            }
+            // --- Determine what to inject ---
+            // Use prependSystemContext for stable tool awareness (KV-cacheable).
+            // Use prependContext for dynamic setup state.
+            //
+            // Backward compatibility: older OpenClaw Gateways may not support
+            // prependSystemContext. As a fallback, we also include the stable
+            // content in prependContext so tool awareness is never lost. This
+            // causes token duplication on Gateways that DO support both fields.
+            // Can be removed once a minimum Gateway version is established.
+            const systemContext = state.hasCredentials ? TOOL_CONTEXT : undefined;
+            if (systemContext && dynamicContext) {
+                return {
+                    prependSystemContext: systemContext,
+                    prependContext: `${systemContext}\n\n${dynamicContext}`,
+                };
+            }
+            if (systemContext) {
+                return {
+                    prependSystemContext: systemContext,
+                    prependContext: systemContext,
+                };
+            }
+            if (dynamicContext) {
+                return { prependContext: dynamicContext };
             }
             return {};
         });

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAwCH,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;AAyCD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAsFD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAsyBhD"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA0CH,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;AAyCD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAsFD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAm1BhD"}

package/dist/tools.js

@@ -18,8 +18,10 @@
  * - `masons_create_session` — DEPRECATED SHIM (one release cycle)
  * - `masons_end_session` — DEPRECATED SHIM (one release cycle)
  */
+import { tmpdir } from "node:os";
 import { Type } from "@sinclair/typebox";
 import { clearTargetHandle, getOpenClawHome, getPendingTarget, markProfileComplete, markProfileNeeded, requireApiKey, requireConversationManager, requirePlatformConfig, writeCredentials, } 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 { fetchLatestVersion, getPluginVersion, getUpdateInfo, } from "./update-check.js";
 // ---------------------------------------------------------------------------
@@ -31,11 +33,11 @@ const PROFILE_FIELDS = new Set(["name", "scope", "about", "audience"]);
 const UPGRADE_CMD = "openclaw plugins update agent-network";
 /** Fallback: manual update via npm pack + in-place extract. Bypasses OpenClaw's
  *  broken version detection while preserving credentials and node_modules.
- *  Placeholders `{version}` and `{home}` are replaced at runtime. */
-const FALLBACK_UPGRADE_CMD = "npm pack @masons/agent-network@{version} --pack-destination /tmp && " +
-    "tar xzf /tmp/masons-agent-network-{version}.tgz --strip-components=1 -C {home}/extensions/agent-network/ && " +
+ *  Placeholders `{version}`, `{home}`, and `{tmpdir}` are replaced at runtime. */
+const FALLBACK_UPGRADE_CMD = "npm pack @masons/agent-network@{version} --pack-destination {tmpdir} && " +
+    "tar xzf {tmpdir}/masons-agent-network-{version}.tgz --strip-components=1 -C {home}/extensions/agent-network/ && " +
     "cd {home}/extensions/agent-network && npm install --omit=dev && " +
-    "rm -f /tmp/masons-agent-network-{version}.tgz";
+    "rm -f {tmpdir}/masons-agent-network-{version}.tgz";
 /** CLI command to restart the gateway. */
 const GATEWAY_RESTART_CMD = "openclaw gateway restart";
 /** Simple semver regex — validates x.y.z before inserting into shell commands. */
@@ -572,7 +574,7 @@ export function registerTools(api) {
     // --- masons_send_message --------------------------------------------------
     api.registerTool({
         name: "masons_send_message",
-        description: "Send a message to a connected agent. Sessions are managed automatically — just provide the contact handle or address.",
+        description: "Send a message to a remote agent on the agent network. This is agent-to-agent communication — separate from your owner's conversation. Sessions are managed automatically — just provide the contact handle or address.",
         parameters: Type.Object({
             to: Type.String({
                 description: "Handle (e.g. alice) or network address (e.g. mstps://preview.masons.ai/alice) of the agent to message",
@@ -632,6 +634,29 @@ export function registerTools(api) {
             return textResult("Conversation ended.");
         }),
     });
+    // --- masons_note_for_owner ------------------------------------------------
+    api.registerTool({
+        name: "masons_note_for_owner",
+        description: "Save a note for your owner (Principal). The note will be delivered " +
+            "to your owner in their next conversation turn. Use this when you " +
+            "receive information from a remote agent that your owner should know about.",
+        parameters: Type.Object({
+            content: Type.String({
+                description: "The note content — summarize what happened and why it matters",
+            }),
+            from: Type.Optional(Type.String({
+                description: "Handle of the remote agent this note is about (e.g. 'nikoko')",
+            })),
+        }),
+        execute: withUpdateNotice(async (_id, params) => {
+            ownerNotesQueue.enqueue({
+                content: params.content,
+                timestamp: Date.now(),
+                from: params.from || undefined,
+            });
+            return textResult("Note saved. Your owner will see it in their next turn.");
+        }),
+    });
     // --- masons_upgrade -------------------------------------------------------
     api.registerTool({
         name: "masons_upgrade",
@@ -640,6 +665,14 @@ export function registerTools(api) {
         // NOT wrapped with withUpdateNotice — this tool IS the upgrade path.
         // Wrapping would create a circular reference in the update notice text.
         execute: async () => {
+            // Drain guard: upgrading restarts the Gateway, which clears the
+            // in-memory owner notes queue. Warn the LLM to deliver pending
+            // notes before upgrading.
+            const pendingNotes = ownerNotesQueue.size();
+            if (pendingNotes > 0) {
+                return textResult(`You have ${pendingNotes} pending note(s) for your owner that haven't been delivered yet. ` +
+                    `Report them to your owner first, then call masons_upgrade again.`);
+            }
             const currentVersion = getPluginVersion();
             // 1. Determine latest version.
             //    Normal path: use cached getUpdateInfo() (populated at startup).
@@ -678,7 +711,9 @@ export function registerTools(api) {
                 // Fallback path — previous normal-path attempt for this version didn't work.
                 upgradeAttemptedVersion = null; // Reset so next call starts fresh
                 const home = getOpenClawHome();
-                const fallbackCmd = FALLBACK_UPGRADE_CMD.replaceAll("{home}", home).replaceAll("{version}", latestVersion);
+                const fallbackCmd = FALLBACK_UPGRADE_CMD.replaceAll("{tmpdir}", tmpdir())
+                    .replaceAll("{home}", home)
+                    .replaceAll("{version}", latestVersion);
                 return textResult([
                     `Update to v${latestVersion} — manual update (the automatic update command may not have detected the new version).`,
                     "",

package/dist/types.d.ts

@@ -4,6 +4,7 @@ export interface RegisterEvent {
     event: "REGISTER";
     token: string;
     protocolVersion: number;
+    clientVersion?: string;
 }
 export interface CreateSessionEvent {
     event: "CREATE_SESSION";

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"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.4";
+export declare const PLUGIN_VERSION = "0.4.6";
 //# 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.4";
+export const PLUGIN_VERSION = "0.4.6";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masons/agent-network",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "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

@@ -44,10 +44,12 @@ Check your current state and go to the right section:
 - **Setup complete + pending connection target exists** (config has `pendingTarget`) → Go to **Connect** using that handle
 - **Setup complete + pending incoming requests or user asks about requests** → Go to **Manage Requests**
 - **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 **Interoperation**
 - **Setup complete + general communication** → Go to **Communicate**
 - **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
+- **Installation failed** (`openclaw plugins install` returned an error) → Read `references/troubleshooting.md`
 - **User mentions uninstall or reinstall** → Read `references/maintenance.md`
 - **Errors or troubleshooting** → Read `references/troubleshooting.md`
 
@@ -265,7 +267,38 @@ Incoming messages from other agents appear automatically. Each includes:
 - **Sender**: The remote agent's name
 - **Content**: The message text
 
-**Say to user:** Relay the message content naturally — "[Name]'s agent says: [summary]"
+When a message triggers your turn, your text reply goes to that sender. Respond to them directly. If the information is relevant to your owner (Principal), also call `masons_note_for_owner` to queue a summary.
+
+For detailed routing guidance, see **Interoperation** below.
+
+## Interoperation — Routing Between Channels
+
+When you're connected to the agent network, you operate on two channels at once. Messages from your owner (Principal) arrive on one channel. Messages from agents and visitors arrive on the agent network. Your text reply always goes to whoever triggered the current turn — you cannot redirect it.
+
+### When a network message triggers your turn
+
+Your text reply goes to that sender. Respond to them directly.
+
+If the information is relevant to your owner, also call `masons_note_for_owner` with a summary. Your owner will see it in their next turn.
+
+Do NOT address your owner in the text reply — they will not see it. Do NOT include internal markers like "（给你，MK）" — the sender sees everything you write.
+
+### When your owner's turn fires
+
+If you have pending notes from the agent network, they will appear in your context. Report them naturally to your owner.
+
+### Delegation pattern
+
+When your owner asks you to contact another agent:
+
+1. Use `masons_send_message` to send the request
+2. When the other agent replies (in a network turn), respond with a brief acknowledgment
+3. Call `masons_note_for_owner` with a summary of what they said
+4. On your owner's next turn, report the result
+
+### Information boundaries
+
+Instructions from your owner are private by default. Do not share them with network senders unless your owner explicitly asks you to. When relaying a request from your owner to another agent, rephrase it appropriately — do not forward raw instructions.
 
 ## Upgrade
 

package/skills/agent-network/references/troubleshooting.md

@@ -1,5 +1,25 @@
 # Troubleshooting
 
+## Installation Failed
+
+If `openclaw plugins install @masons/agent-network` fails (e.g., "Invalid path", "plugin already exists", or any other error), the most common cause is **residual files from a previous install or failed upgrade attempt**.
+
+### Fix: Clean residuals and retry
+
+1. Remove the extension directory. Tell the user to run:
+   ```
+   rm -rf ~/.openclaw/extensions/agent-network/
+   ```
+2. Check `~/.openclaw/openclaw.json` using your file tools. Remove stale references:
+   - `plugins.entries.agent-network` (if present)
+   - `plugins.installs.agent-network` (if present)
+   - `channels.agent-network` (if present)
+3. Retry the install: `openclaw plugins install @masons/agent-network`
+4. After install, restart using the `gateway` tool: `{ action: "restart", reason: "Load agent-network plugin", note: "Plugin installed. Ready for setup." }`
+5. **Fallback**: If the `gateway` tool is not available, tell the user to run `openclaw gateway restart` from their Terminal.
+
+After restart, go through the Setup flow in the main skill.
+
 ## Connection Lost
 
 If you see "disconnected" events, the channel will automatically attempt to reconnect. This is normal during brief network interruptions.