@masons/agent-network 0.4.16 → 0.4.17

package/dist/channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAsB9D,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,UAAU,oBAAoB,CAAC,CAAC;IAC9B,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAAC;IACvD,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC;IACpE,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;IACjE,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;CAC/D;AAED,UAAU,sBAAsB;IAC9B,EAAE,EAAE,OAAO,CAAC;CACb;AAED,UAAU,sBAAsB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,sBAAsB;IAC9B,YAAY,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC9C,QAAQ,CAAC,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACzE;AAED,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAsDD,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,YAAY,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,WAAW,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,UAAU,yBAAyB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,YAAY,EAAE,mBAAmB,CAAC;IAClC,MAAM,EAAE,oBAAoB,CAAC,mBAAmB,CAAC,CAAC;IAClD,QAAQ,EAAE,sBAAsB,CAAC;IACjC,OAAO,EAAE,qBAAqB,CAAC,mBAAmB,CAAC,CAAC;CACrD;AAkED,eAAO,MAAM,mBAAmB,EAAE,yBA6ajC,CAAC"}
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAsB9D,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,UAAU,oBAAoB,CAAC,CAAC;IAC9B,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAAC;IACvD,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC;IACpE,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;IACjE,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;CAC/D;AAED,UAAU,sBAAsB;IAC9B,EAAE,EAAE,OAAO,CAAC;CACb;AAED,UAAU,sBAAsB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,sBAAsB;IAC9B,YAAY,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC9C,QAAQ,CAAC,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACzE;AAED,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAsDD,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,YAAY,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,WAAW,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,UAAU,yBAAyB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,YAAY,EAAE,mBAAmB,CAAC;IAClC,MAAM,EAAE,oBAAoB,CAAC,mBAAmB,CAAC,CAAC;IAClD,QAAQ,EAAE,sBAAsB,CAAC;IACjC,OAAO,EAAE,qBAAqB,CAAC,mBAAmB,CAAC,CAAC;CACrD;AA+ND,eAAO,MAAM,mBAAmB,EAAE,yBAoNjC,CAAC"}

package/dist/channel.js

@@ -3,26 +3,18 @@ import createDebug from "debug";
 import { clearConnectorClient, clearConversationManager, extractNetworkConfig, initConnectorClient, initConversationManager, initToolConfig, requirePluginRuntime, } from "./config.js";
 import { ConnectorClient } from "./connector-client.js";
 import { ConversationManager } from "./conversation-manager.js";
-import { clearOwnerSessions, isOwnerSession, markOwnerSession, removeOwnerSession, setCurrentTurnIsOwner, } from "./owner-session-state.js";
+import { extractHandleFromAddress } from "./handle-utils.js";
+import { clearOwnerState, isOwnerAddress, markOwnerAddress, setCurrentTurnIsOwner, } from "./owner-session-state.js";
 import { setCurrentTurnSender } from "./turn-context.js";
 import { checkForUpdate } from "./update-check.js";
 const dbg = createDebug("agent-network:channel");
 // --- Sender identity ---
-// Identity resolution uses session state (remoteAddress from SESSION_CREATED),
-// not per-message metadata. See the message_received handler for details.
-// See: docs/openclaw/research/session-identity-mapping.md §5
 /**
  * Extract a human-readable name from the sender's metadata.
  *
- * Resolution order (account-level identity first, then address):
+ * Resolution order:
  * 1. `metadata.visitor_name` — display name for Passport browser visitors
- *    (resolved by Connector from user_info.displayName)
- * 2. `metadata.from` — MSTP address for agent-to-agent connections
- *    (e.g. `mstps://preview.masons.ai/alice` → "alice")
- * 3. Fallback: "Unknown" for direct MSTP clients without metadata
- *
- * Design: Channel determines routing, Account determines identity.
- * See: interop-routing-system-design.md §3 "Channel vs Account".
+ * 2. `event.from` — extract handle from routable address
  */
 function deriveSenderName(event) {
     // Account-level identity: Passport visitor with resolved display name
@@ -30,14 +22,8 @@ function deriveSenderName(event) {
     if (visitorName && typeof visitorName === "string") {
         return visitorName;
     }
-    // MSTP address: extract handle from agent address
-    const from = event.metadata?.from;
-    if (from && typeof from === "string") {
-        const trimmed = from.replace(/\/+$/, "");
-        const parts = trimmed.split("/");
-        return parts[parts.length - 1] || from;
-    }
-    return "Unknown";
+    // Extract handle from `from` address
+    return extractHandleFromAddress(event.from);
 }
 /**
  * Extract the Connector host from a connectorUrl.
@@ -53,6 +39,140 @@ function extractConnectorHost(connectorUrl) {
         return connectorUrl.replace(/^wss?:\/\//, "").replace(/\/.*$/, "");
     }
 }
+// --- Duplicate message protection for at-least-once delivery ---
+// Short-window dedup: stored messages re-delivered on reconnect are
+// suppressed if the same (from, content, sentAt) was seen within 60 seconds.
+const DEDUP_WINDOW_MS = 60_000;
+const recentMessages = new Map(); // key → timestamp
+function isDuplicate(from, content, sentAt) {
+    if (!sentAt)
+        return false; // only dedup stored messages (have sentAt)
+    const key = `${from}\0${content}\0${sentAt}`;
+    const now = Date.now();
+    const seen = recentMessages.get(key);
+    if (seen && now - seen < DEDUP_WINDOW_MS) {
+        return true;
+    }
+    recentMessages.set(key, now);
+    // Lazy cleanup: remove expired entries when map grows large
+    if (recentMessages.size > 200) {
+        for (const [k, ts] of recentMessages) {
+            if (now - ts > DEDUP_WINDOW_MS)
+                recentMessages.delete(k);
+        }
+    }
+    return false;
+}
+// --- Message dispatch helpers ---
+/**
+ * Handle an address-based MESSAGE_RECEIVED { from, content, metadata }.
+ * This is the primary path for the address-based protocol.
+ */
+async function handleAddressedMessage(event, conversationManager, client, ctx) {
+    const fromAddress = event.from;
+    dbg("routing inbound message from=%s contentLength=%d", fromAddress, event.content.length);
+    // Duplicate protection for at-least-once re-delivery (stored messages).
+    if (isDuplicate(fromAddress, event.content, event.sentAt)) {
+        dbg("duplicate message suppressed from=%s sentAt=%s", fromAddress, event.sentAt);
+        return;
+    }
+    // Owner detection: first-message-sets, subsequent-inherits.
+    // Connector includes is_owner in metadata for Passport visitors.
+    if (event.metadata?.is_owner === true) {
+        markOwnerAddress(fromAddress);
+    }
+    setCurrentTurnIsOwner(isOwnerAddress(fromAddress));
+    // Resolve contact from address. Register inbound conversation if new.
+    const contact = deriveSenderName(event);
+    if (!conversationManager.getContactByAddress(fromAddress)) {
+        conversationManager.registerInbound(contact, fromAddress);
+    }
+    setCurrentTurnSender(conversationManager.getContactByAddress(fromAddress) ?? null);
+    // Runtime guard
+    let runtime;
+    try {
+        runtime = requirePluginRuntime();
+    }
+    catch {
+        dbg("plugin runtime not available, dropping message from=%s", fromAddress);
+        return;
+    }
+    if (!runtime.channel) {
+        dbg("channelRuntime not available, dropping message from=%s", fromAddress);
+        return;
+    }
+    // senderId for OpenClaw routing: use the routable address
+    const senderId = fromAddress;
+    const senderName = contact;
+    try {
+        const route = await runtime.channel.routing.resolveAgentRoute({
+            cfg: ctx.cfg,
+            channel: "agent-network",
+            accountId: ctx.accountId,
+            peer: { kind: "direct", id: senderId },
+        });
+        const msgCtx = runtime.channel.reply.finalizeInboundContext({
+            Body: event.content,
+            RawBody: event.content,
+            CommandBody: event.content,
+            From: senderId,
+            To: senderId,
+            SessionKey: route.sessionKey,
+            AccountId: ctx.accountId,
+            ChatType: "direct",
+            SenderName: senderName,
+            SenderId: senderId,
+            Timestamp: event.sentAt ? new Date(event.sentAt).getTime() : Date.now(),
+            Provider: "agent-network",
+            Surface: "agent-network",
+            MessageSid: `an:${extractHandleFromAddress(fromAddress)}:${randomUUID()}`,
+            CommandAuthorized: true,
+            OriginatingChannel: "agent-network",
+            OriginatingTo: senderId,
+        });
+        const storePath = runtime.channel.session.resolveStorePath(undefined, {
+            agentId: route.agentId,
+        });
+        const sessionKey = typeof msgCtx.SessionKey === "string"
+            ? msgCtx.SessionKey
+            : route.sessionKey;
+        await runtime.channel.session.recordInboundSession({
+            storePath,
+            sessionKey,
+            ctx: msgCtx,
+        });
+        // Typing: address-based
+        client.sendTyping(fromAddress, true);
+        try {
+            await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+                ctx: msgCtx,
+                cfg: ctx.cfg,
+                dispatcherOptions: {
+                    deliver: async (payload) => {
+                        const text = payload.text;
+                        if (!text)
+                            return;
+                        if (!conversationManager.hasConversation(senderId)) {
+                            dbg("deliver suppressed: conversation ended senderId=%s len=%d", senderId, text.length);
+                            return;
+                        }
+                        const deliverResult = await conversationManager.send(senderId, text);
+                        dbg("deliver reply senderId=%s status=%s contentLength=%d", senderId, deliverResult.status, text.length);
+                    },
+                    onError: (err) => {
+                        console.error(`[agent-network:${ctx.accountId}] dispatch error:`, err);
+                    },
+                },
+            });
+        }
+        finally {
+            client.sendTyping(fromAddress, false);
+        }
+    }
+    catch (err) {
+        console.error(`[agent-network:${ctx.accountId}] inbound dispatch failed from=${fromAddress}:`, err);
+    }
+}
 const accounts = new Map();
 // --- Channel Plugin ---
 export const agentNetworkChannel = {
@@ -112,8 +232,8 @@ export const agentNetworkChannel = {
     outbound: {
         deliveryMode: "direct",
         async sendText(ctx) {
-            // ctx.recipient is the MSTP address or sessionId fallback (senderId from inbound dispatch).
-            // ConversationManager.send() handles session management transparently.
+            // ctx.recipient is the routable address (senderId from inbound dispatch).
+            // ConversationManager.send() handles address resolution transparently.
             const state = accounts.get(ctx.accountId);
             if (!state)
                 return { ok: false };
@@ -151,182 +271,21 @@ export const agentNetworkChannel = {
             // Acceptable for unstructured text conversation (Phase 1). If MSTP adds
             // structured multi-step interactions, add a per-session dispatch queue.
             client.on("message_received", async (event) => {
-                dbg("routing inbound message sessionId=%s contentLength=%d", event.sessionId, event.content.length);
-                // --- Per-turn context (#836, #873) ---
-                // Set BEFORE dispatch so before_prompt_build can read these synchronously.
-                setCurrentTurnIsOwner(isOwnerSession(event.sessionId));
-                // Sender identity: resolve sessionId → contact handle using
-                // the closure-scoped conversationManager (NOT imported from config.ts).
-                setCurrentTurnSender(conversationManager.getContactBySessionId(event.sessionId) ?? null);
-                // --- Runtime guard ---
-                let runtime;
-                try {
-                    runtime = requirePluginRuntime();
-                }
-                catch {
-                    dbg("plugin runtime not available, dropping message sessionId=%s", event.sessionId);
-                    return;
-                }
-                // channel is required in our PluginRuntime type but may be absent
-                // at runtime on older OpenClaw versions (pre-2026.2.19).
-                if (!runtime.channel) {
-                    dbg("channelRuntime not available, dropping message sessionId=%s", event.sessionId);
-                    return;
-                }
-                // Resolve sender identity via ConversationManager.
-                // The session_created handler registered the inbound session with
-                // the ConversationManager, so we can look up the contact handle.
-                const senderAddress = conversationManager.getAddressBySessionId(event.sessionId);
-                // Determine if the address is a real MSTP address or a sessionId fallback.
-                const isRealAddress = typeof senderAddress === "string" &&
-                    (senderAddress.startsWith("mstps://") ||
-                        senderAddress.startsWith("mstp://"));
-                // senderId for OpenClaw routing: use MSTP address if available,
-                // fall back to sessionId for unknown sessions / direct MSTP clients.
-                const senderId = isRealAddress ? senderAddress : event.sessionId;
-                // Derive sender name.
-                // - MSTP agents: extract handle from address.
-                // - Passport visitors / direct clients: use the contact name stored
-                //   in ConversationManager at session_created time (which read
-                //   visitor_name from session metadata). Per-message metadata does
-                //   NOT carry session-level fields like visitor_name, so we must
-                //   use the stored value. Falls back to deriveSenderName → "Unknown".
-                const senderName = isRealAddress
-                    ? deriveSenderName({
-                        ...event,
-                        metadata: { ...event.metadata, from: senderAddress },
-                    })
-                    : (conversationManager.getContactBySessionId(event.sessionId) ??
-                        deriveSenderName(event));
-                try {
-                    // Step 1 — Resolve agent route (await defensively — may be sync or async)
-                    const route = await runtime.channel.routing.resolveAgentRoute({
-                        cfg: ctx.cfg,
-                        channel: "agent-network",
-                        accountId: ctx.accountId,
-                        peer: { kind: "direct", id: senderId },
-                    });
-                    // Step 2 — Finalize inbound context (builds MsgContext for LLM pipeline)
-                    const msgCtx = runtime.channel.reply.finalizeInboundContext({
-                        Body: event.content,
-                        RawBody: event.content,
-                        CommandBody: event.content,
-                        From: senderId,
-                        To: senderId,
-                        SessionKey: route.sessionKey,
-                        AccountId: ctx.accountId,
-                        ChatType: "direct",
-                        SenderName: senderName,
-                        SenderId: senderId,
-                        Timestamp: Date.now(),
-                        Provider: "agent-network",
-                        Surface: "agent-network",
-                        MessageSid: `mstp:${event.sessionId}:${randomUUID()}`,
-                        CommandAuthorized: true,
-                        OriginatingChannel: "agent-network",
-                        OriginatingTo: senderId,
-                    });
-                    // Step 3 — Record inbound session
-                    const storePath = runtime.channel.session.resolveStorePath(undefined, { agentId: route.agentId });
-                    const sessionKey = typeof msgCtx.SessionKey === "string"
-                        ? msgCtx.SessionKey
-                        : route.sessionKey;
-                    await runtime.channel.session.recordInboundSession({
-                        storePath,
-                        sessionKey,
-                        ctx: msgCtx,
-                    });
-                    // Step 4 — Dispatch to LLM pipeline + deliver reply via callback
-                    // Signal typing start — agent is composing a reply.
-                    // Wrapped in try/finally so typing stop fires even on dispatch error.
-                    // Without this, a failed dispatch leaves a stale "typing..." for 30s.
-                    client.sendTypingStart(event.sessionId);
-                    try {
-                        await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-                            ctx: msgCtx,
-                            cfg: ctx.cfg,
-                            dispatcherOptions: {
-                                deliver: async (payload) => {
-                                    const text = payload.text;
-                                    if (!text)
-                                        return;
-                                    // Guard: if conversation was ended during this dispatch
-                                    // (LLM called masons_end_conversation mid-turn), suppress
-                                    // straggler text to prevent auto-creating a new session.
-                                    // endConversation() deletes the conversation entry — its
-                                    // absence is the signal. Normal inbound replies always
-                                    // have an entry (registerInbound creates it before dispatch).
-                                    if (!conversationManager.hasConversation(senderId)) {
-                                        dbg("deliver suppressed: conversation ended senderId=%s len=%d", senderId, text.length);
-                                        return;
-                                    }
-                                    const deliverResult = await conversationManager.send(senderId, text);
-                                    dbg("deliver reply senderId=%s status=%s contentLength=%d", senderId, deliverResult.status, text.length);
-                                },
-                                onError: (err) => {
-                                    console.error(`[agent-network:${ctx.accountId}] dispatch error:`, err);
-                                },
-                            },
-                        });
-                    }
-                    finally {
-                        // Signal typing stop — dispatch complete (explicit stop, layer 1).
-                        // Also implicitly cleared by Connector on SEND_MESSAGE (layer 2).
-                        client.sendTypingStop(event.sessionId);
-                    }
-                }
-                catch (err) {
-                    console.error(`[agent-network:${ctx.accountId}] inbound dispatch failed sessionId=${event.sessionId}:`, err);
-                }
-            });
-            // --- Inbound session registration ---
-            // When a remote agent creates a session (direction=inbound),
-            // register it with the ConversationManager.
-            client.on("session_created", (event) => {
-                dbg("session created sessionId=%s direction=%s", event.sessionId, event.direction);
-                if (event.direction === "inbound") {
-                    // --- Owner identity binding (#836) ---
-                    // Connector sets `is_owner: true` when visitor_user_id === agent.userId.
-                    // Track this session so message_received can set the per-turn flag.
-                    if (event.metadata?.is_owner === true) {
-                        markOwnerSession(event.sessionId);
-                        dbg("owner session detected sessionId=%s", event.sessionId);
-                    }
-                    const from = event.metadata?.from;
-                    const remoteAddress = typeof from === "string" && from.length > 0 ? from : null;
-                    if (remoteAddress) {
-                        const contact = deriveSenderName(event);
-                        conversationManager.registerInbound(event.sessionId, contact, remoteAddress);
-                    }
-                    else {
-                        // No MSTP address — Passport visitor or direct MSTP client.
-                        // Use visitor_name from session metadata (account-level identity
-                        // resolved by Connector) if available, else sessionId fallback.
-                        const contact = deriveSenderName(event);
-                        conversationManager.registerInbound(event.sessionId, contact, event.sessionId);
-                    }
-                }
-                // Outbound sessions are handled by SessionLifecycle internally
-                // (matched by requestId in the createSession flow).
-            });
-            // --- Mailbox delivery ACK ---
-            // "received" semantics — ACK immediately on FLUSH_COMPLETE,
-            // don't wait for LLM processing. This tells Connector it's safe
-            // to delete the flushed entries from MongoDB.
-            client.on("flush_complete", (event) => {
-                client.sendDeliveryAck(event.mailboxSessionId);
-                dbg("flush_complete → ACK sent mailboxSessionId=%s", event.mailboxSessionId);
+                if (!("from" in event))
+                    return; // address-based only
+                await handleAddressedMessage(event, conversationManager, client, ctx);
             });
-            // --- Session ended + disconnect ---
-            // SessionLifecycle handles session state transitions (session_ended, disconnected)
-            // via its own event subscriptions. No CM calls needed here.
-            // Owner session cleanup (#836): remove from ownerSessionIds on session_ended.
-            client.on("session_ended", (event) => {
-                removeOwnerSession(event.sessionId);
+            // --- Delivery ACK ---
+            // ACK immediately on DELIVERY_PENDING — tells Connector it's safe
+            // to delete delivered stored messages.
+            client.on("delivery_pending", (event) => {
+                client.ackDelivery(event.upTo);
+                dbg("delivery_pending → ACK sent count=%d upTo=%s", event.count, event.upTo);
             });
-            // On disconnect, all sessions are invalid — clear owner state.
+            // --- Disconnect ---
+            // On disconnect, all owner addresses are invalid — clear owner state.
             client.on("disconnected", () => {
-                clearOwnerSessions();
+                clearOwnerState();
             });
             // --- Error handling ---
             // Must register before connect() — unhandled "error" events crash the process.

package/dist/connector-client.d.ts

@@ -1,11 +1,19 @@
 import { EventEmitter } from "node:events";
-import { type FlushCompleteEvent, type MessageReceivedEvent, type SessionCreatedEvent, type SessionEndedEvent } from "./types.js";
+import { type AddressedMessageEvent, type DeliveryPendingEvent, type SendAckEvent, type StructuredErrorEvent } from "./types.js";
+/**
+ * Error with machine-readable `code` from Connector structured errors.
+ * Thrown by `send()` when the Connector responds with ERROR { code }.
+ */
+export declare class ConnectorError extends Error {
+    readonly code: string;
+    readonly to?: string;
+    constructor(message: string, code: string, to?: string);
+}
 type ConnectorClientEvents = {
-    session_created: (event: SessionCreatedEvent) => void;
-    message_received: (event: MessageReceivedEvent) => void;
-    session_ended: (event: SessionEndedEvent) => void;
-    flush_complete: (event: FlushCompleteEvent) => void;
-    session_error: (sessionId: string, message: string) => void;
+    message_received: (event: AddressedMessageEvent) => void;
+    send_ack: (event: SendAckEvent) => void;
+    delivery_pending: (event: DeliveryPendingEvent) => void;
+    structured_error: (event: StructuredErrorEvent) => void;
     error: (error: Error) => void;
     connected: () => void;
     disconnected: () => void;
@@ -21,24 +29,27 @@ export declare class ConnectorClient extends EventEmitter {
     private registerResolve;
     private registerReject;
     private registerTimer;
+    /** Pending SEND_ACK correlation map for address-based sends. */
+    private pendingSends;
     constructor(url: string, token: string);
     connect(): Promise<void>;
     disconnect(): void;
-    createSession(target: string, opts?: {
-        secret?: string;
-        metadata?: Record<string, unknown>;
-    }): {
-        requestId: string;
-        sent: boolean;
-    };
-    sendMessage(sessionId: string, content: string, opts?: {
-        contentType?: string;
-        metadata?: Record<string, unknown>;
-    }): boolean;
-    endSession(sessionId: string, reason?: string): boolean;
-    sendDeliveryAck(mailboxSessionId: string): boolean;
-    sendTypingStart(sessionId: string): boolean;
-    sendTypingStop(sessionId: string): boolean;
+    /**
+     * 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: string, content: string, contentType?: string, metadata?: Record<string, unknown>): Promise<SendAckEvent>;
+    /**
+     * Send a typing indicator to a routable address.
+     */
+    sendTyping(to: string, isTyping: boolean): boolean;
+    /**
+     * Acknowledge delivery of stored messages up to a timestamp.
+     */
+    ackDelivery(upTo: string): boolean;
     on<K extends keyof ConnectorClientEvents>(event: K, listener: ConnectorClientEvents[K]): this;
     on(event: string | symbol, listener: (...args: unknown[]) => void): this;
     once<K extends keyof ConnectorClientEvents>(event: K, listener: ConnectorClientEvents[K]): this;
@@ -53,9 +64,19 @@ export declare class ConnectorClient extends EventEmitter {
     private resolveRegister;
     private rejectRegister;
     private handleMessage;
+    /** Dispatch inbound address-based events. */
+    private dispatchAddressed;
     private handleRegisterAck;
-    private handleSessionCreated;
-    private handleErrorEvent;
+    /**
+     * Resolve the pending send promise matching this SEND_ACK.
+     * Also emits `send_ack` for listeners that want to observe all ACKs.
+     */
+    private handleSendAck;
+    /**
+     * Structured ERROR: message-scoped errors reject pending sends,
+     * connection-scoped errors emit generic event.
+     */
+    private handleStructuredError;
     private handleClose;
     private handleError;
     private scheduleReconnect;
@@ -63,7 +84,8 @@ export declare class ConnectorClient extends EventEmitter {
     private nextExponentialBackoff;
     private clearReconnectTimer;
     private cleanupConnection;
-    private send;
+    /** Send an event over the WebSocket. */
+    private sendEvent;
 }
 export {};
 //# sourceMappingURL=connector-client.d.ts.map

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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"}