@masons/agent-network 0.4.16 → 0.4.17

package/dist/connector-client.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 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 { 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");
 const dbgMsg = createDebug("agent-network:connector:msg");
@@ -11,6 +11,21 @@ const BACKOFF_INITIAL_MS = 1_000;
 const BACKOFF_MAX_MS = 30_000;
 const ALREADY_CONNECTED_RETRY_MS = 2_000;
 const ALREADY_CONNECTED_MAX_RETRIES = 30;
+// --- Error class for structured errors ---
+/**
+ * Error with machine-readable `code` from Connector structured errors.
+ * Thrown by `send()` when the Connector responds with ERROR { code }.
+ */
+export class ConnectorError extends Error {
+    code;
+    to;
+    constructor(message, code, to) {
+        super(message);
+        this.name = "ConnectorError";
+        this.code = code;
+        this.to = to;
+    }
+}
 // --- ConnectorClient ---
 export class ConnectorClient extends EventEmitter {
     url;
@@ -23,6 +38,8 @@ export class ConnectorClient extends EventEmitter {
     registerResolve = null;
     registerReject = null;
     registerTimer = null;
+    /** Pending SEND_ACK correlation map for address-based sends. */
+    pendingSends = new Map();
     constructor(url, token) {
         super();
         this.url = url;
@@ -49,58 +66,54 @@ export class ConnectorClient extends EventEmitter {
             wsToClose.close(1000, "Client disconnect");
         }
     }
-    createSession(target, opts) {
-        const requestId = randomUUID();
-        const event = {
-            event: "CREATE_SESSION",
-            requestId,
-            target,
-            secret: opts?.secret,
-            metadata: opts?.metadata,
-        };
-        const sent = this.send(event);
-        dbg("createSession target=%s requestId=%s sent=%s", target, requestId, sent);
-        return { requestId, sent };
-    }
-    sendMessage(sessionId, content, opts) {
+    // --- Messaging ---
+    /**
+     * Send a message to a routable address. Returns a Promise that resolves
+     * with the SEND_ACK from the Connector, or rejects with a ConnectorError
+     * (structured error code) or a plain Error (timeout / disconnect).
+     *
+     * The messageId is generated internally and used for ACK correlation.
+     */
+    send(to, content, contentType = "text", metadata) {
+        const messageId = randomUUID();
         const event = {
             event: "SEND_MESSAGE",
-            sessionId,
+            messageId,
+            to,
             content,
-            contentType: opts?.contentType,
-            metadata: opts?.metadata,
-        };
-        const sent = this.send(event);
-        dbgMsg("sendMessage sessionId=%s contentLength=%d sent=%s", sessionId, content.length, sent);
-        return sent;
-    }
-    endSession(sessionId, reason) {
-        const event = {
-            event: "END_SESSION",
-            sessionId,
-            reason,
+            contentType,
+            metadata,
         };
-        const sent = this.send(event);
-        dbg("endSession sessionId=%s sent=%s", sessionId, sent);
-        return sent;
-    }
-    sendDeliveryAck(mailboxSessionId) {
-        const event = {
-            event: "DELIVERY_ACK",
-            mailboxSessionId,
-        };
-        const sent = this.send(event);
-        dbg("sendDeliveryAck mailboxSessionId=%s sent=%s", mailboxSessionId, sent);
-        return sent;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingSends.delete(messageId);
+                reject(new Error("SEND_ACK timeout"));
+            }, SEND_ACK_TIMEOUT_MS);
+            this.pendingSends.set(messageId, { resolve, reject, timer });
+            const sent = this.sendEvent(event);
+            if (!sent) {
+                clearTimeout(timer);
+                this.pendingSends.delete(messageId);
+                reject(new Error("WebSocket not connected"));
+            }
+        });
     }
-    sendTypingStart(sessionId) {
-        const sent = this.send({ event: "TYPING_START", sessionId });
-        dbg("sendTypingStart sessionId=%s sent=%s", sessionId, sent);
+    /**
+     * Send a typing indicator to a routable address.
+     */
+    sendTyping(to, isTyping) {
+        const event = { event: "TYPING", to, isTyping };
+        const sent = this.sendEvent(event);
+        dbg("sendTyping to=%s isTyping=%s sent=%s", to, isTyping, sent);
         return sent;
     }
-    sendTypingStop(sessionId) {
-        const sent = this.send({ event: "TYPING_STOP", sessionId });
-        dbg("sendTypingStop sessionId=%s sent=%s", sessionId, sent);
+    /**
+     * Acknowledge delivery of stored messages up to a timestamp.
+     */
+    ackDelivery(upTo) {
+        const event = { event: "DELIVERY_ACK", upTo };
+        const sent = this.sendEvent(event);
+        dbg("ackDelivery upTo=%s sent=%s", upTo, sent);
         return sent;
     }
     on(event, listener) {
@@ -138,7 +151,7 @@ export class ConnectorClient extends EventEmitter {
             protocolVersion: CURRENT_PROTOCOL_VERSION,
             clientVersion: PLUGIN_VERSION,
         };
-        this.send(event);
+        this.sendEvent(event);
     }
     startRegisterTimeout() {
         this.registerTimer = setTimeout(() => {
@@ -178,40 +191,46 @@ export class ConnectorClient extends EventEmitter {
             this.emit("error", new Error("Received non-JSON message from Connector"));
             return;
         }
+        // REGISTER_ACK is version-agnostic — always handled first
         if (isRegisterAck(parsed)) {
             this.handleRegisterAck(parsed);
             return;
         }
-        if (isSessionCreated(parsed)) {
-            dbg("SESSION_CREATED sessionId=%s direction=%s", parsed.sessionId, parsed.direction);
-            this.handleSessionCreated(parsed);
+        this.dispatchAddressed(parsed);
+    };
+    /** Dispatch inbound address-based events. */
+    dispatchAddressed(parsed) {
+        if (isSendAck(parsed)) {
+            dbg("SEND_ACK messageId=%s status=%s", parsed.messageId, parsed.status);
+            this.handleSendAck(parsed);
             return;
         }
-        if (isMessageReceived(parsed)) {
-            dbgMsg("MESSAGE_RECEIVED sessionId=%s contentLength=%d", parsed.sessionId, parsed.content.length);
+        if (isAddressedMessage(parsed)) {
+            dbgMsg("MESSAGE_RECEIVED from=%s contentLength=%d", parsed.from, parsed.content.length);
             this.emit("message_received", parsed);
             return;
         }
-        if (isSessionEnded(parsed)) {
-            dbg("SESSION_ENDED sessionId=%s", parsed.sessionId);
-            this.emit("session_ended", parsed);
+        if (isDeliveryPending(parsed)) {
+            dbg("DELIVERY_PENDING count=%d upTo=%s", parsed.count, parsed.upTo);
+            this.emit("delivery_pending", parsed);
             return;
         }
-        if (isFlushComplete(parsed)) {
-            dbg("FLUSH_COMPLETE mailboxSessionId=%s messageCount=%d", parsed.mailboxSessionId, parsed.messageCount);
-            this.emit("flush_complete", parsed);
-            return;
-        }
-        if (isErrorEvent(parsed)) {
-            dbg("ERROR message=%s", parsed.message);
-            this.handleErrorEvent(parsed);
+        if (isStructuredError(parsed)) {
+            dbg("ERROR code=%s message=%s", parsed.code, parsed.message);
+            this.handleStructuredError(parsed);
             return;
         }
         // Unknown event type — silently ignore (forward compatibility)
-    };
+    }
     handleRegisterAck(ack) {
-        dbg("REGISTER_ACK status=%s", ack.status);
+        dbg("REGISTER_ACK status=%s protocolVersion=%d", ack.status, ack.protocolVersion);
         if (ack.status === "ok") {
+            // Defensive: verify the negotiated version matches what we requested.
+            // Current Connector rejects unsupported versions outright (no downgrade),
+            // so this check is future-proofing against silent protocol desync.
+            if (ack.protocolVersion !== CURRENT_PROTOCOL_VERSION) {
+                dbg("WARN: server negotiated protocolVersion=%d, expected=%d", ack.protocolVersion, CURRENT_PROTOCOL_VERSION);
+            }
             this.backoffMs = BACKOFF_INITIAL_MS;
             this.alreadyConnectedRetries = 0;
             this.resolveRegister();
@@ -235,17 +254,38 @@ export class ConnectorClient extends EventEmitter {
             this.ws?.close(4001, reason);
         }
     }
-    handleSessionCreated(event) {
-        this.emit("session_created", event);
+    // --- Address-based handlers ---
+    /**
+     * Resolve the pending send promise matching this SEND_ACK.
+     * Also emits `send_ack` for listeners that want to observe all ACKs.
+     */
+    handleSendAck(ack) {
+        this.emit("send_ack", ack);
+        const pending = this.pendingSends.get(ack.messageId);
+        if (pending) {
+            clearTimeout(pending.timer);
+            this.pendingSends.delete(ack.messageId);
+            pending.resolve(ack);
+        }
     }
-    handleErrorEvent(event) {
-        // (1) Route by sessionId — session-scoped error
-        if (event.sessionId) {
-            this.emit("session_error", event.sessionId, event.message);
-            return;
+    /**
+     * Structured ERROR: message-scoped errors reject pending sends,
+     * connection-scoped errors emit generic event.
+     */
+    handleStructuredError(event) {
+        this.emit("structured_error", event);
+        // Message-scoped: reject the pending send for this messageId
+        if (event.messageId) {
+            const pending = this.pendingSends.get(event.messageId);
+            if (pending) {
+                clearTimeout(pending.timer);
+                this.pendingSends.delete(event.messageId);
+                pending.reject(new ConnectorError(event.message, event.code, event.to));
+                return;
+            }
         }
-        // (2) Global error (includes requestId-only errors from failed CREATE_SESSION)
-        this.emit("error", new Error(event.message));
+        // Connection-scoped: emit generic error
+        this.emit("error", new Error(`[${event.code}] ${event.message}`));
     }
     // --- Connection close ---
     handleClose = () => {
@@ -320,9 +360,16 @@ export class ConnectorClient extends EventEmitter {
             clearTimeout(this.registerTimer);
             this.registerTimer = null;
         }
+        // Reject all pending address-based sends on disconnect
+        for (const [, pending] of this.pendingSends) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error("Connection closed"));
+        }
+        this.pendingSends.clear();
     }
-    // --- Helpers ---
-    send(event) {
+    // --- Wire helpers ---
+    /** Send an event over the WebSocket. */
+    sendEvent(event) {
         if (this.ws?.readyState === WebSocket.OPEN) {
             this.ws.send(JSON.stringify(event));
             return true;

package/dist/conversation-manager.d.ts

@@ -2,20 +2,21 @@
  * Conversation Manager — maps contacts to conversations.
  *
  * Owns the identity-based API that the Tool Interface and Inbound Dispatcher
- * call. Internally delegates session management to SessionLifecycle.
+ * call. Sends messages directly to routable addresses via ConnectorClient.send().
  *
- * Contact resolution: handle -> `mstps://${connectorHost}/${handle}`
- * Internal key: MSTP address (same as SessionLifecycle).
- * One session per contact, last-write-wins (D2).
- * In-memory only, no persistence (D3).
+ * 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/openclaw/session-abstraction-system-design.md §4.1
+ * @see docs/connector/gateway-v2-consumer-adaptation-plan.md PR 2
  */
-import type { ConnectorClient } from "./connector-client.js";
-import { SessionLifecycle } from "./session-lifecycle.js";
+import { type ConnectorClient } from "./connector-client.js";
 export interface SendResult {
     status: "sent" | "failed";
     error?: string;
+    /** Machine-readable error code from Connector (when status === "failed"). */
+    errorCode?: string;
 }
 export interface ConversationEntry {
     contact: string;
@@ -31,37 +32,37 @@ export interface ConversationSummary {
     initiatedBy: "local" | "remote";
 }
 export declare class ConversationManager {
-    readonly sessionLifecycle: SessionLifecycle;
     private readonly client;
     private readonly connectorHost;
-    /** Conversations keyed by MSTP address */
+    /** Conversations keyed by routable address */
     private readonly conversations;
     constructor(client: ConnectorClient, connectorHost: string);
     /**
-     * Send a message to a contact. Session management is transparent.
-     * Creates a session automatically if none exists (D1 — sync-but-transparent).
+     * Send a message to a contact. Sends directly to the resolved address —
+     * no session management needed.
      *
-     * @param contact - Handle or MSTP address of the target agent.
+     * 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.
      */
     send(contact: string, content: string): Promise<SendResult>;
     /**
-     * Register an inbound session (remote agent initiated).
-     * Called by the channel adapter on SESSION_CREATED with direction=inbound.
-     */
-    registerInbound(sessionId: string, contact: string, address: string): void;
-    /**
-     * Resolve a sessionId to a contact handle.
-     * Used by the inbound dispatcher to derive sender identity from a message event.
+     * Register an inbound conversation (remote agent or visitor initiated).
+     * Called by the channel adapter when a message arrives from a new address.
      */
-    getContactBySessionId(sessionId: string): string | undefined;
+    registerInbound(contact: string, address: string): void;
     /**
-     * Resolve a sessionId to an MSTP address.
-     * Used by the channel adapter for reverse lookup.
+     * Resolve a routable address to a contact handle.
+     * Used by the inbound dispatcher to derive sender identity from MESSAGE_RECEIVED.from.
      */
-    getAddressBySessionId(sessionId: string): string | undefined;
+    getContactByAddress(address: string): string | 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(): ConversationSummary[];
     /**
@@ -74,25 +75,31 @@ export declare class ConversationManager {
     hasConversation(contact: string): boolean;
     /**
      * End the conversation with a contact.
-     * Closes the active session if one exists.
+     * Removes the conversation entry. No END_SESSION needed — the Connector
+     * manages connection lifecycle (idle timeout).
      */
     endConversation(contact: string): void;
     /**
-     * Resolve a contact (handle or MSTP address) to an MSTP address.
+     * Resolve a contact (handle, MSTP address, or passport address) to a
+     * routable address.
      *
      * Resolution order:
-     * 1. If `contact` is already an MSTP address (starts with mstps:// or mstp://),
-     *    return it as-is.
-     * 2. If `contact` is already a key in the conversations map (e.g., a sessionId
-     *    used as fallback address for direct MSTP clients), return it as-is.
-     * 3. Otherwise construct: `mstps://${connectorHost}/${handle}`.
+     * 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: string): string;
     /**
-     * Extract handle from an MSTP address.
-     * `mstps://preview.masons.ai/alice` -> `alice`
+     * Extract a display-friendly handle from any address scheme.
+     * Delegates to shared utility — single source of truth.
      */
     extractHandle(address: string): string;
+    private ensureConversationEntry;
     /** @internal Reset for test isolation. */
     _resetForTesting(): void;
 }

package/dist/conversation-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conversation-manager.d.ts","sourceRoot":"","sources":["../src/conversation-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAQ1D,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,OAAO,GAAG,QAAQ,CAAC;CACjC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,OAAO,GAAG,QAAQ,CAAC;CACjC;AAMD,qBAAa,mBAAmB;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAwC;gBAE1D,MAAM,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM;IAU1D;;;;;;OAMG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAgDjE;;;OAGG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAyB1E;;;OAGG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAQ5D;;;OAGG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI5D;;OAEG;IACH,iBAAiB,IAAI,mBAAmB,EAAE;IAe1C;;;;;;OAMG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAKzC;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAkBtC;;;;;;;;;OASG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAYvC;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAUtC,0CAA0C;IAC1C,gBAAgB,IAAI,IAAI;CAIzB"}
+{"version":3,"file":"conversation-manager.d.ts","sourceRoot":"","sources":["../src/conversation-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,KAAK,eAAe,EAAkB,MAAM,uBAAuB,CAAC;AAS7E,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,OAAO,GAAG,QAAQ,CAAC;CACjC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,OAAO,GAAG,QAAQ,CAAC;CACjC;AAwBD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAwC;gBAE1D,MAAM,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM;IAS1D;;;;;;;;;;OAUG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IA0CjE;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAKvD;;;OAGG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAaxD;;;;OAIG;IACH,iBAAiB,IAAI,mBAAmB,EAAE;IAc1C;;;;;;OAMG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAKzC;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAUtC;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAoBvC;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAQtC,OAAO,CAAC,uBAAuB;IAwB/B,0CAA0C;IAC1C,gBAAgB,IAAI,IAAI;CAGzB"}