@masons/agent-network 0.5.14 → 0.5.16

package/dist/conversation-manager.js

@@ -1,23 +1,7 @@
-/**
- * Conversation Manager — maps contacts to conversations.
- *
- * Owns the identity-based API that the Tool Interface and Inbound Dispatcher
- * call. Sends messages directly to routable addresses via ConnectorClient.send().
- *
- * Contact resolution: handle → `mstps://${connectorHost}/${handle}`
- * Address schemes: MSTP (`mstps://`), handle (bare), passport (`passport:@`)
- * Internal key: routable address.
- * One conversation per contact, in-memory only (D3).
- *
- * @see docs/connector/gateway-v2-consumer-adaptation-plan.md PR 2
- */
 import createDebug from "debug";
 import { ConnectorError } from "./connector-client.js";
 import { extractHandleFromAddress } from "./handle-utils.js";
 const dbg = createDebug("agent-network:conversation-manager");
-// ---------------------------------------------------------------------------
-// Error code → tool result mapping
-// ---------------------------------------------------------------------------
 const ERROR_MESSAGES = {
     ADDRESS_NOT_FOUND: "Cannot find agent '{to}'. Check the handle.",
     ACCESS_DENIED: "No connection to '{to}'. Send a connection request first.",
@@ -29,50 +13,19 @@ function formatErrorMessage(code, to) {
     const template = ERROR_MESSAGES[code] ?? `Send failed: ${code}`;
     return to ? template.replace(/\{to\}/g, to) : template;
 }
-// ---------------------------------------------------------------------------
-// ConversationManager
-// ---------------------------------------------------------------------------
 export class ConversationManager {
     client;
     connectorHost;
-    /** Conversations keyed by routable address */
     conversations = new Map();
     constructor(client, connectorHost) {
         this.client = client;
         this.connectorHost = connectorHost;
     }
-    // -------------------------------------------------------------------------
-    // Public API — identity-based
-    // -------------------------------------------------------------------------
-    /**
-     * Send a message to a contact. Sends directly to the resolved address —
-     * no session management needed.
-     *
-     * Returns a structured result with status and optional error.
-     * ConnectorError codes (ADDRESS_NOT_FOUND, ACCESS_DENIED, etc.) are
-     * mapped to human-readable messages for LLM tool results.
-     *
-     * @param contact - Handle, MSTP address, or passport address of the target.
-     * @param content - Message content to send.
-     */
     async send(contact, content) {
         const address = this.resolveAddress(contact);
-        // Ensure conversation entry exists
-        if (!this.conversations.has(address)) {
-            this.conversations.set(address, {
-                contact: this.extractHandle(address),
-                address,
-                lastMessageAt: Date.now(),
-                initiatedBy: "local",
-            });
-        }
         try {
             const ack = await this.client.send(address, content, "text");
-            // Update lastMessageAt
-            const entry = this.conversations.get(address);
-            if (entry) {
-                entry.lastMessageAt = Date.now();
-            }
+            this.ensureConversationEntry(this.extractHandle(address), address, "local");
             dbg("send contact=%s address=%s status=%s", contact, address, ack.status);
             return { status: "sent" };
         }
@@ -87,35 +40,20 @@ export class ConversationManager {
             return { status: "failed", error: message };
         }
     }
-    /**
-     * Register an inbound conversation (remote agent or visitor initiated).
-     * Called by the channel adapter when a message arrives from a new address.
-     */
     registerInbound(contact, address) {
         this.ensureConversationEntry(contact, address, "remote");
         dbg("registerInbound contact=%s address=%s", contact, address);
     }
-    /**
-     * Resolve a routable address to a contact handle.
-     * Used by the inbound dispatcher to derive sender identity from MESSAGE_RECEIVED.from.
-     */
     getContactByAddress(address) {
         const entry = this.conversations.get(address);
         if (entry)
             return entry.contact;
-        // Try resolving — the address might be a full MSTP address while conversations
-        // are keyed by a different form. Extract handle as fallback.
         for (const [, e] of this.conversations) {
             if (e.address === address)
                 return e.contact;
         }
         return undefined;
     }
-    /**
-     * List all conversations with metadata.
-     * `active` is always true for address-based protocol — there is no session
-     * lifecycle. Conversations persist until explicitly ended or Plugin restarts.
-     */
     listConversations() {
         const result = [];
         for (const [, entry] of this.conversations) {
@@ -129,32 +67,10 @@ export class ConversationManager {
         }
         return result;
     }
-    /**
-     * Check if a conversation entry exists for a contact.
-     *
-     * Returns true for entries that are marked `ended` but not yet committed —
-     * this allows the deliver callback to flush buffered text from the same
-     * dispatch cycle as end_conversation (#999).
-     *
-     * Straggler text from *subsequent* dispatch cycles is still suppressed
-     * because `commitEndedConversations()` removes entries between cycles.
-     */
     hasConversation(contact) {
         const address = this.resolveAddress(contact);
         return this.conversations.has(address);
     }
-    /**
-     * Mark the conversation with a contact as ended (deferred deletion).
-     *
-     * The entry is NOT removed immediately — it is flagged `ended` and stays
-     * in the Map until `commitEndedConversations()` is called after the
-     * current dispatch cycle completes. This prevents the "last-message-
-     * before-close" race where the dispatcher executes end_conversation
-     * before flushing buffered text (#999).
-     *
-     * No END_SESSION needed — the Connector manages connection lifecycle
-     * (idle timeout).
-     */
     endConversation(contact) {
         const address = this.resolveAddress(contact);
         const entry = this.conversations.get(address);
@@ -166,19 +82,6 @@ export class ConversationManager {
             dbg("endConversation (no-op) contact=%s address=%s", contact, address);
         }
     }
-    /**
-     * Remove all conversations marked as `ended`.
-     *
-     * Call this after the dispatch cycle completes (in the `finally` block
-     * of `handleAddressedMessage`). Deferred deletion ensures that text
-     * buffered in the same dispatch cycle as end_conversation is delivered
-     * before the entry disappears.
-     *
-     * Pattern: React 18 batched updates / Qt `deleteLater()` — mutations
-     * during a dispatch cycle are committed only when the cycle ends.
-     *
-     * @see https://github.com/MASONS-ai/masons.ai/issues/999
-     */
     commitEndedConversations() {
         let count = 0;
         for (const [address, entry] of this.conversations) {
@@ -191,23 +94,6 @@ export class ConversationManager {
             dbg("commitEndedConversations removed=%d", count);
         }
     }
-    // -------------------------------------------------------------------------
-    // Contact resolution
-    // -------------------------------------------------------------------------
-    /**
-     * Resolve a contact (handle, MSTP address, or passport address) to a
-     * routable address.
-     *
-     * Resolution order:
-     * 1. MSTP address (starts with mstps:// or mstp://) → return as-is.
-     * 2. Passport address (starts with passport:) → return as-is (already routable).
-     * 3. Already a key in the conversations map → return as-is.
-     * 4. Reverse lookup: if any existing conversation has this handle as its
-     *    contact, use that conversation's address. This ensures replies to a
-     *    cross-Connector sender route to the sender's original address, not to
-     *    a locally-constructed address.
-     * 5. Otherwise treat as handle → construct `mstps://${connectorHost}/${handle}`.
-     */
     resolveAddress(contact) {
         if (contact.startsWith("mstps://") || contact.startsWith("mstp://")) {
             return contact;
@@ -218,26 +104,15 @@ export class ConversationManager {
         if (this.conversations.has(contact)) {
             return contact;
         }
-        // Reverse lookup: handle → existing conversation address.
-        // Handles the case where inbound arrived from a remote Connector
-        // (e.g., "mstps://remote-host/mason") but the LLM replies using
-        // the bare handle "mason".
         for (const [addr, entry] of this.conversations) {
             if (entry.contact === contact)
                 return addr;
         }
         return `mstps://${this.connectorHost}/${contact}`;
     }
-    /**
-     * Extract a display-friendly handle from any address scheme.
-     * Delegates to shared utility — single source of truth.
-     */
     extractHandle(address) {
         return extractHandleFromAddress(address);
     }
-    // -------------------------------------------------------------------------
-    // Internal
-    // -------------------------------------------------------------------------
     ensureConversationEntry(contact, address, initiatedBy) {
         if (!this.conversations.has(address)) {
             this.conversations.set(address, {
@@ -251,14 +126,10 @@ export class ConversationManager {
             const entry = this.conversations.get(address);
             if (entry) {
                 entry.lastMessageAt = Date.now();
-                entry.ended = false; // Clear deferred deletion on re-registration
+                entry.ended = false;
             }
         }
     }
-    // -------------------------------------------------------------------------
-    // Test helpers
-    // -------------------------------------------------------------------------
-    /** @internal Reset for test isolation. */
     _resetForTesting() {
         this.conversations.clear();
     }

package/dist/environment-context.d.ts

@@ -1,18 +1,3 @@
-/**
- * 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;
@@ -21,12 +6,6 @@ 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;
@@ -36,10 +15,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 (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;
-/** @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

@@ -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,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"}
+{"version":3,"file":"environment-context.d.ts","sourceRoot":"","sources":["../src/environment-context.ts"],"names":[],"mappings":"AAoBA,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;AAmBD,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;AAGD,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAE9C;AAOD,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C;AAOD,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC"}

package/dist/environment-context.js

@@ -1,36 +1,6 @@
-/**
- * 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)
@@ -50,31 +20,19 @@ export function setEnvironmentContext(agent, owner) {
         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 (used by auto-link in channel.ts). */
 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/handle-utils.d.ts

@@ -1,16 +1,2 @@
-/**
- * Shared handle extraction utility.
- *
- * Used by ConversationManager (contact resolution) and Channel (sender name derivation).
- * Single source of truth for address → display handle mapping.
- */
-/**
- * Extract a display-friendly handle from any address scheme.
- *
- * - `mstps://preview.masons.ai/alice` → `alice`
- * - `passport:@luomingke` → `luomingke`
- * - `passport:user_abc` → `user_abc`
- * - `mason` → `mason` (bare handle passthrough)
- */
 export declare function extractHandleFromAddress(address: string): string;
 //# sourceMappingURL=handle-utils.d.ts.map

package/dist/handle-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handle-utils.d.ts","sourceRoot":"","sources":["../src/handle-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAUhE"}
+{"version":3,"file":"handle-utils.d.ts","sourceRoot":"","sources":["../src/handle-utils.ts"],"names":[],"mappings":"AAeA,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAUhE"}

package/dist/handle-utils.js

@@ -1,17 +1,3 @@
-/**
- * Shared handle extraction utility.
- *
- * Used by ConversationManager (contact resolution) and Channel (sender name derivation).
- * Single source of truth for address → display handle mapping.
- */
-/**
- * Extract a display-friendly handle from any address scheme.
- *
- * - `mstps://preview.masons.ai/alice` → `alice`
- * - `passport:@luomingke` → `luomingke`
- * - `passport:user_abc` → `user_abc`
- * - `mason` → `mason` (bare handle passthrough)
- */
 export function extractHandleFromAddress(address) {
     if (address.startsWith("passport:@")) {
         return address.slice("passport:@".length);

package/dist/index.js

@@ -1,10 +1 @@
-// Main entry point for @masons/agent-network.
-//
-// This file MUST NOT import modules that depend on Node.js-only packages (ws,
-// etc.) because some consumers import from here in Next.js builds that include
-// client bundles.
-//
-// The OpenClaw Plugin entry is in ./plugin.ts (loaded via openclaw.extensions).
-// The ConnectorClient and protocol types are available via dedicated sub-exports.
-// --- Shared constants ---
 export { AUTHORIZED_TOKEN_TTL_MS, SETUP_CODE_CHARSET, SETUP_CODE_LENGTH, SETUP_CODE_TTL_MS, } from "./constants.js";

package/dist/owner-notes.d.ts

@@ -1,48 +1,15 @@
-/**
- * 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;
 }

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

@@ -1 +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"}
+{"version":3,"file":"owner-notes.d.ts","sourceRoot":"","sources":["../src/owner-notes.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,SAAS;IAExB,OAAO,EAAE,MAAM,CAAC;IAEhB,SAAS,EAAE,MAAM,CAAC;IAElB,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;IAM7C,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAY9B,KAAK,IAAI,SAAS,EAAE;IAUpB,IAAI,IAAI,MAAM;IAQd,KAAK,IAAI,IAAI;IAQb,OAAO,CAAC,UAAU;CAInB;AAMD,eAAO,MAAM,eAAe,iBAAwB,CAAC"}

package/dist/owner-notes.js

@@ -1,69 +1,30 @@
-/**
- * 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.
-     */
+    static TTL_MS = 24 * 60 * 60 * 1000;
     enqueue(note) {
         this.evictStale();
         if (this.notes.length >= OwnerNotesQueue.MAX_SIZE) {
-            this.notes.shift(); // drop oldest (FIFO)
+            this.notes.shift();
         }
         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/owner-session-state.d.ts

@@ -1,32 +1,6 @@
-/**
- * Owner Identity State — tracks which addresses belong to the agent's owner.
- *
- * When the Connector detects that a Passport visitor is the agent's owner
- * (deterministic userId comparison, #836), it includes `is_owner: true` in
- * MESSAGE_RECEIVED metadata. This module maintains the Plugin-side state:
- *
- * - `ownerAddresses`: Set of routable addresses where the visitor is the owner.
- *   Populated on first MESSAGE_RECEIVED with is_owner=true, cleared on disconnect.
- *
- * - `currentTurnIsOwner`: Per-turn flag set in the message_received handler
- *   and read in before_prompt_build. Reset after each read to avoid stale state.
- *
- * Module-level singleton — shared between channel.ts (write) and plugin.ts (read).
- */
-/** Mark an address as belonging to the owner. */
 export declare function markOwnerAddress(address: string): void;
-/** Check if an address belongs to the owner. */
 export declare function isOwnerAddress(address: string): boolean;
-/** Clear all owner state (connection lost — all addresses invalid). */
 export declare function clearOwnerState(): void;
-/**
- * Set the per-turn owner flag. Called in message_received before dispatch.
- * The flag is consumed (read + reset) by before_prompt_build.
- */
 export declare function setCurrentTurnIsOwner(value: boolean): void;
-/**
- * Consume the per-turn owner flag. Returns the value and resets to false.
- * Consuming prevents stale state from leaking into subsequent turns.
- */
 export declare function consumeCurrentTurnIsOwner(): boolean;
 //# sourceMappingURL=owner-session-state.d.ts.map

package/dist/owner-session-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"owner-session-state.d.ts","sourceRoot":"","sources":["../src/owner-session-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAgBH,iDAAiD;AACjD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEtD;AAED,gDAAgD;AAChD,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,uEAAuE;AACvE,wBAAgB,eAAe,IAAI,IAAI,CAGtC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE1D;AAMD;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,OAAO,CAInD"}
+{"version":3,"file":"owner-session-state.d.ts","sourceRoot":"","sources":["../src/owner-session-state.ts"],"names":[],"mappings":"AA+BA,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEtD;AAGD,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvD;AAGD,wBAAgB,eAAe,IAAI,IAAI,CAGtC;AAMD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE1D;AAUD,wBAAgB,yBAAyB,IAAI,OAAO,CAInD"}

package/dist/owner-session-state.js

@@ -1,55 +1,18 @@
-/**
- * Owner Identity State — tracks which addresses belong to the agent's owner.
- *
- * When the Connector detects that a Passport visitor is the agent's owner
- * (deterministic userId comparison, #836), it includes `is_owner: true` in
- * MESSAGE_RECEIVED metadata. This module maintains the Plugin-side state:
- *
- * - `ownerAddresses`: Set of routable addresses where the visitor is the owner.
- *   Populated on first MESSAGE_RECEIVED with is_owner=true, cleared on disconnect.
- *
- * - `currentTurnIsOwner`: Per-turn flag set in the message_received handler
- *   and read in before_prompt_build. Reset after each read to avoid stale state.
- *
- * Module-level singleton — shared between channel.ts (write) and plugin.ts (read).
- */
-// ---------------------------------------------------------------------------
-// State
-// ---------------------------------------------------------------------------
-/** Routable addresses where the visitor has been identified as the owner. */
 const ownerAddresses = new Set();
-/** Whether the current LLM turn was triggered by an owner. */
 let currentTurnIsOwner = false;
-// ---------------------------------------------------------------------------
-// Write API (called from channel.ts)
-// ---------------------------------------------------------------------------
-/** Mark an address as belonging to the owner. */
 export function markOwnerAddress(address) {
     ownerAddresses.add(address);
 }
-/** Check if an address belongs to the owner. */
 export function isOwnerAddress(address) {
     return ownerAddresses.has(address);
 }
-/** Clear all owner state (connection lost — all addresses invalid). */
 export function clearOwnerState() {
     ownerAddresses.clear();
     currentTurnIsOwner = false;
 }
-/**
- * Set the per-turn owner flag. Called in message_received before dispatch.
- * The flag is consumed (read + reset) by before_prompt_build.
- */
 export function setCurrentTurnIsOwner(value) {
     currentTurnIsOwner = value;
 }
-// ---------------------------------------------------------------------------
-// Read API (called from plugin.ts)
-// ---------------------------------------------------------------------------
-/**
- * Consume the per-turn owner flag. Returns the value and resets to false.
- * Consuming prevents stale state from leaking into subsequent turns.
- */
 export function consumeCurrentTurnIsOwner() {
     const value = currentTurnIsOwner;
     currentTurnIsOwner = false;