@masons/agent-network 0.6.19 → 0.6.21

package/dist/connector-client.js

@@ -5,6 +5,7 @@ import WebSocket from "ws";
 import { setEnvironmentContext } from "./environment-context.js";
 import { CURRENT_PROTOCOL_VERSION, isAddressedMessage, isCustodyPending, isDeliveryCursor, isDeliveryPending, isDeliverySkip, isDeliveryStatus, isRegisterAck, isSendAck, isStructuredError, REGISTER_ACK_TIMEOUT_MS, SEND_ACK_TIMEOUT_MS, } from "./types.js";
 import { PLUGIN_VERSION } from "./version.js";
+import { startWsHeartbeat, } from "./ws-heartbeat.js";
 const dbg = createDebug("agent-network:connector");
 const dbgMsg = createDebug("agent-network:connector:msg");
 const BACKOFF_INITIAL_MS = 1_000;
@@ -24,6 +25,23 @@ export class ConnectorError extends Error {
         this.to = to;
     }
 }
+export class SendOutcomeUnknownError extends Error {
+    code = "SEND_OUTCOME_UNKNOWN";
+    retryable = false;
+    attempts = 1;
+    messageId;
+    reason;
+    constructor(messageId, reason) {
+        const detail = reason === "ack_timeout"
+            ? "no SEND_ACK was observed before the acknowledgement deadline"
+            : "the connection closed before a SEND_ACK was observed";
+        super(`Send outcome unknown for message ${messageId}: ${detail}. ` +
+            "It may have been sent. Do not send it again as a new message.");
+        this.name = "SendOutcomeUnknownError";
+        this.messageId = messageId;
+        this.reason = reason;
+    }
+}
 export class ConnectorClient extends EventEmitter {
     url;
     token;
@@ -32,25 +50,32 @@ export class ConnectorClient extends EventEmitter {
     backoffMs = BACKOFF_INITIAL_MS;
     alreadyConnectedRetries = 0;
     reconnectTimer = null;
+    keepalive = null;
+    keepaliveOptions;
     registerResolve = null;
     registerReject = null;
     registerTimer = null;
+    registration = { state: "none" };
+    everDropped = false;
     lastKnownSeq;
     pendingSeqMessages = new Map();
     seenPayloadIds = new Set();
     seenPayloadIdOrder = [];
     pendingSends = new Map();
-    constructor(url, token) {
+    constructor(url, token, options = {}) {
         super();
         this.url = url;
         this.token = token;
+        this.keepaliveOptions = options.keepalive;
     }
     connect() {
         if (this.ws) {
             return Promise.reject(new Error("Already connecting or connected"));
         }
+        this.clearReconnectTimer();
         dbg("connecting to %s", this.url);
         this.intentionalClose = false;
+        this.everDropped = false;
         return this.doConnect();
     }
     disconnect() {
@@ -65,6 +90,17 @@ export class ConnectorClient extends EventEmitter {
             wsToClose.close(1000, "Client disconnect");
         }
     }
+    getChannelState() {
+        if (this.ws?.readyState === WebSocket.OPEN)
+            return "connected";
+        if (this.ws !== null || this.reconnectTimer !== null) {
+            return this.everDropped ? "reconnecting" : "connecting";
+        }
+        return "disconnected";
+    }
+    getRegistration() {
+        return this.registration;
+    }
     send(to, content, contentType = "text", metadata) {
         const messageId = randomUUID();
         const event = {
@@ -75,13 +111,29 @@ export class ConnectorClient extends EventEmitter {
             contentType,
             metadata,
         };
+        let serializedEvent;
+        try {
+            serializedEvent = JSON.stringify(event);
+        }
+        catch (err) {
+            return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+        }
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.pendingSends.delete(messageId);
-                reject(new Error("SEND_ACK timeout"));
+                reject(new SendOutcomeUnknownError(messageId, "ack_timeout"));
             }, SEND_ACK_TIMEOUT_MS);
             this.pendingSends.set(messageId, { resolve, reject, timer });
-            const sent = this.sendEvent(event);
+            let sent = false;
+            try {
+                sent = this.sendSerializedEvent(serializedEvent, event.event);
+            }
+            catch (err) {
+                clearTimeout(timer);
+                this.pendingSends.delete(messageId);
+                reject(err instanceof Error ? err : new Error(String(err)));
+                return;
+            }
             if (!sent) {
                 clearTimeout(timer);
                 this.pendingSends.delete(messageId);
@@ -120,18 +172,42 @@ export class ConnectorClient extends EventEmitter {
         return super.emit(event, ...args);
     }
     doConnect() {
+        if (this.ws) {
+            return Promise.reject(new Error("Already connecting or connected"));
+        }
         return new Promise((resolve, reject) => {
             this.registerResolve = resolve;
             this.registerReject = reject;
             const ws = new WebSocket(this.url, { handshakeTimeout: 10_000 });
             this.ws = ws;
             ws.on("open", () => {
+                if (this.ws !== ws) {
+                    ws.terminate();
+                    return;
+                }
+                this.keepalive = startWsHeartbeat(ws, {
+                    ...this.keepaliveOptions,
+                    onDead: () => {
+                        dbg("keepalive: silent Gateway socket terminated");
+                    },
+                    onPingError: (error) => {
+                        dbg("keepalive: ping failed: %s", error.message);
+                    },
+                });
                 this.sendRegister();
                 this.startRegisterTimeout();
             });
-            ws.on("message", this.handleMessage);
-            ws.on("close", this.handleClose);
-            ws.on("error", this.handleError);
+            ws.on("message", (data) => {
+                if (this.ws === ws)
+                    this.handleMessage(data);
+            });
+            ws.on("close", (code, reason) => {
+                this.handleClose(ws, code, reason);
+            });
+            ws.on("error", (error) => {
+                if (this.ws === ws)
+                    this.handleError(error);
+            });
         });
     }
     sendRegister() {
@@ -322,11 +398,13 @@ export class ConnectorClient extends EventEmitter {
             }
             this.backoffMs = BACKOFF_INITIAL_MS;
             this.alreadyConnectedRetries = 0;
+            this.registration = { state: "accepted" };
             this.resolveRegister();
             this.emit("connected");
         }
         else {
             const reason = ack.reason ?? "Unknown registration error";
+            this.registration = { state: "refused", reason };
             if (reason === "Unsupported protocol version") {
                 this.intentionalClose = true;
                 this.rejectRegister(new Error(reason));
@@ -342,28 +420,46 @@ export class ConnectorClient extends EventEmitter {
         }
     }
     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);
+            pending.resolve(structuredClone(ack));
+        }
+        try {
+            this.emit("send_ack", ack);
+        }
+        catch (err) {
+            console.error("[agent-network:connector-client] send_ack listener failed:", err);
         }
     }
     handleStructuredError(event) {
-        this.emit("structured_error", event);
         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;
             }
+            try {
+                this.emit("structured_error", event);
+            }
+            catch (err) {
+                console.error("[agent-network:connector-client] structured_error listener failed:", err);
+            }
+            return;
+        }
+        try {
+            this.emit("structured_error", event);
+        }
+        catch (err) {
+            console.error("[agent-network:connector-client] structured_error listener failed:", err);
         }
         this.emit("error", new Error(`[${event.code}] ${event.message}`));
     }
-    handleClose = (code, reason) => {
+    handleClose(ws, code, reason) {
+        if (this.ws !== ws)
+            return;
         const reasonStr = reason
             ? typeof reason === "string"
                 ? reason
@@ -371,11 +467,13 @@ export class ConnectorClient extends EventEmitter {
             : "";
         dbg("connection closed code=%s reason=%s intentional=%s", code ?? "?", reasonStr, this.intentionalClose);
         const wasRegistering = this.registerReject !== null;
+        this.everDropped = true;
         this.cleanupConnection();
         const replacedByNewRuntime = code === REPLACED_BY_NEW_RUNTIME_CODE &&
             reasonStr === REPLACED_BY_NEW_RUNTIME_REASON;
         if (replacedByNewRuntime) {
             this.intentionalClose = true;
+            this.registration = { state: "replaced" };
             const msg = "This agent was claimed by another Runtime " +
                 "(this Runtime disconnected). " +
                 "Re-run `openclaw channels login --channel agent-network` " +
@@ -396,17 +494,21 @@ export class ConnectorClient extends EventEmitter {
         if (!this.intentionalClose) {
             this.scheduleReconnect();
         }
-    };
+    }
     handleError = (err) => {
         dbg("websocket error: %s", err.message);
         this.emit("error", err);
     };
     scheduleReconnect() {
+        if (this.intentionalClose || this.ws)
+            return;
         this.clearReconnectTimer();
         const delay = this.calculateBackoff();
         dbg("reconnecting in %dms", Math.round(delay));
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
+            if (this.intentionalClose || this.ws)
+                return;
             this.doConnect().catch(() => {
             });
         }, delay);
@@ -434,28 +536,33 @@ export class ConnectorClient extends EventEmitter {
         }
     }
     cleanupConnection() {
+        this.registration = { state: "none" };
+        if (this.keepalive) {
+            this.keepalive.stop();
+            this.keepalive = null;
+        }
         if (this.ws) {
-            this.ws.off("message", this.handleMessage);
-            this.ws.off("close", this.handleClose);
-            this.ws.off("error", this.handleError);
             this.ws = null;
         }
         if (this.registerTimer) {
             clearTimeout(this.registerTimer);
             this.registerTimer = null;
         }
-        for (const [, pending] of this.pendingSends) {
+        for (const [messageId, pending] of this.pendingSends) {
             clearTimeout(pending.timer);
-            pending.reject(new Error("Connection closed"));
+            pending.reject(new SendOutcomeUnknownError(messageId, "connection_closed"));
         }
         this.pendingSends.clear();
     }
     sendEvent(event) {
+        return this.sendSerializedEvent(JSON.stringify(event), event.event);
+    }
+    sendSerializedEvent(serializedEvent, eventName) {
         if (this.ws?.readyState === WebSocket.OPEN) {
-            this.ws.send(JSON.stringify(event));
+            this.ws.send(serializedEvent);
             return true;
         }
-        dbg("send failed: ws not open event=%s", event.event);
+        dbg("send failed: ws not open event=%s", eventName);
         return false;
     }
 }

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

@@ -0,0 +1,4 @@
+import type { ConversationManager } from "./conversation-manager.js";
+export declare function runWithConversationManagerContext<T>(manager: ConversationManager, callback: () => T): T;
+export declare function getInvocationConversationManager(): ConversationManager | null;
+//# sourceMappingURL=conversation-manager-context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-manager-context.d.ts","sourceRoot":"","sources":["../src/conversation-manager-context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAIrE,wBAAgB,iCAAiC,CAAC,CAAC,EACjD,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,MAAM,CAAC,GAChB,CAAC,CAEH;AAED,wBAAgB,gCAAgC,IAAI,mBAAmB,GAAG,IAAI,CAE7E"}

package/dist/conversation-manager-context.js

@@ -0,0 +1,8 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const conversationManagerContext = new AsyncLocalStorage();
+export function runWithConversationManagerContext(manager, callback) {
+    return conversationManagerContext.run(manager, callback);
+}
+export function getInvocationConversationManager() {
+    return conversationManagerContext.getStore() ?? null;
+}

package/dist/conversation-manager.d.ts

@@ -1,9 +1,25 @@
-import { type ConnectorClient } from "./connector-client.js";
-export interface SendResult {
-    status: "sent" | "failed";
+import { type ConnectorClient, type SendOutcomeUnknownReason } from "./connector-client.js";
+import { type SentMessage } from "./sent-message-buffer.js";
+import type { SendAckEvent } from "./types.js";
+export type SendResult = {
+    status: "sent";
+    messageId: string;
+    acknowledgementStatus: string;
+    messageRef?: string;
+    addressedTarget?: NonNullable<SendAckEvent["addressedTarget"]>;
+} | {
+    status: "unknown";
+    messageId: string;
+    attempts: 1;
+    retryable: false;
+    reason: SendOutcomeUnknownReason;
+    error: string;
+    errorCode: "SEND_OUTCOME_UNKNOWN";
+} | {
+    status: "failed";
     error?: string;
     errorCode?: string;
-}
+};
 export interface ConversationEntry {
     contact: string;
     address: string;
@@ -28,11 +44,16 @@ export interface InboundEnvelope {
 export declare const REPLY_CORRELATION_MAX_AGE_MS: number;
 export declare class ConversationManager {
     private readonly client;
+    private readonly sentMessageBuffer;
     private readonly conversations;
+    private readonly conversationAliases;
     private readonly pendingOutreach;
     constructor(client: ConnectorClient);
+    recordOutboundContext(peerAddress: string, content: string): void;
+    getRecentOutboundContext(peerAddress: string): SentMessage[];
     send(contact: string, content: string, metadata?: Record<string, unknown>): Promise<SendResult>;
     registerInbound(contact: string, address: string): void;
+    refreshInboundPortrayal(contact: string, address: string): boolean;
     recordInboundEnvelope(address: string, envelope: Omit<InboundEnvelope, "receivedAt">): void;
     getContactByAddress(address: string): string | undefined;
     listConversations(): ConversationSummary[];
@@ -42,6 +63,10 @@ export declare class ConversationManager {
     resolveAddress(contact: string): string;
     private resolveContactForSend;
     extractHandle(address: string): string;
+    private resolveConversationAlias;
+    private recordConversationAlias;
+    private deleteConversationAliases;
+    private fileResolvedConversation;
     private ensureConversationEntry;
     _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":"AAiBA,OAAO,EAAE,KAAK,eAAe,EAAkB,MAAM,uBAAuB,CAAC;AAa7E,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,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;IAchC,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;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;AAuBD,MAAM,WAAW,eAAe;IAE9B,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AASD,eAAO,MAAM,4BAA4B,QAAc,CAAC;AA0CxD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAGzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAwC;IAiBtE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;gBAEzC,MAAM,EAAE,eAAe;IAsB7B,IAAI,CACR,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,UAAU,CAAC;IA0HtB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAYvD,qBAAqB,CACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,YAAY,CAAC,GAC5C,IAAI;IAmBP,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAkBxD,iBAAiB,IAAI,mBAAmB,EAAE;IAwB1C,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAiBzC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAoCzC,wBAAwB,IAAI,IAAI;IAuChC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAwBvC,OAAO,CAAC,qBAAqB;IAuC7B,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAQtC,OAAO,CAAC,uBAAuB;IAiC/B,gBAAgB,IAAI,IAAI;CAGzB"}
+{"version":3,"file":"conversation-manager.d.ts","sourceRoot":"","sources":["../src/conversation-manager.ts"],"names":[],"mappings":"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"}

package/dist/conversation-manager.js

@@ -1,6 +1,7 @@
 import createDebug from "debug";
-import { ConnectorError } from "./connector-client.js";
+import { ConnectorError, SendOutcomeUnknownError, } from "./connector-client.js";
 import { extractHandleFromAddress } from "./handle-utils.js";
+import { SentMessageBuffer } from "./sent-message-buffer.js";
 import { createReplyTraceMetadata, ensureTraceMetadata, } from "./trace-metadata.js";
 const dbg = createDebug("agent-network:conversation-manager");
 export const REPLY_CORRELATION_MAX_AGE_MS = 10 * 60_000;
@@ -19,17 +20,68 @@ function normalizeHandleContact(contact) {
     return contact.startsWith("@") ? contact.slice(1) : contact;
 }
 function isRoutableAddress(value) {
-    return (value.startsWith("mstps://") ||
-        value.startsWith("mstp://") ||
-        value.startsWith("passport:"));
+    return /^mstps?:\/\//i.test(value) || value.startsWith("passport:");
+}
+function isAddressedTargetAddress(value) {
+    for (let index = 0; index < value.length; index++) {
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit <= 0x1f || codeUnit === 0x7f)
+            return false;
+    }
+    if (!/^mstps?:\/\//i.test(value)) {
+        return false;
+    }
+    try {
+        const parsed = new URL(value);
+        return ((parsed.protocol === "mstp:" || parsed.protocol === "mstps:") &&
+            parsed.hostname.length > 0);
+    }
+    catch {
+        return false;
+    }
+}
+function isCanonicalResolvedNodeAddress(value) {
+    return /^mstps?:\/\/[a-z0-9.-]+(?::[0-9]+)?\/[a-z][a-z0-9_-]{2,14}$/.test(value);
+}
+function normalizedAddressedTarget(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const candidate = value;
+    if (typeof candidate.address !== "string" ||
+        candidate.address.length === 0 ||
+        (candidate.basis !== "resolved" && candidate.basis !== "forwarded")) {
+        return undefined;
+    }
+    const validAddress = candidate.basis === "resolved"
+        ? isCanonicalResolvedNodeAddress(candidate.address)
+        : isAddressedTargetAddress(candidate.address);
+    if (!validAddress) {
+        return undefined;
+    }
+    return {
+        address: candidate.address,
+        basis: candidate.basis,
+    };
+}
+function normalizedMessageRef(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
 }
 export class ConversationManager {
     client;
+    sentMessageBuffer = new SentMessageBuffer();
     conversations = new Map();
+    conversationAliases = new Map();
     pendingOutreach = new Set();
     constructor(client) {
         this.client = client;
     }
+    recordOutboundContext(peerAddress, content) {
+        this.sentMessageBuffer.record(peerAddress, content);
+    }
+    getRecentOutboundContext(peerAddress) {
+        return this.sentMessageBuffer.getRecent(peerAddress);
+    }
     async send(contact, content, metadata) {
         const resolution = this.resolveContactForSend(contact);
         if (resolution.ambiguous) {
@@ -74,16 +126,45 @@ export class ConversationManager {
         }
         try {
             const ack = await this.client.send(address, content, "text", wireMetadata);
-            if (isRoutableAddress(address)) {
+            const addressedTarget = normalizedAddressedTarget(ack.addressedTarget);
+            const messageRef = normalizedMessageRef(ack.messageRef);
+            const resolvedAddress = addressedTarget?.basis === "resolved"
+                ? addressedTarget.address
+                : undefined;
+            if (resolvedAddress !== undefined) {
+                if (!isRoutableAddress(address)) {
+                    this.pendingOutreach.delete(normalizeHandleContact(address).toLowerCase());
+                }
+                this.fileResolvedConversation(address, resolvedAddress);
+            }
+            else if (isRoutableAddress(address)) {
                 this.ensureConversationEntry(this.extractHandle(address), address, "local");
             }
             else {
                 this.pendingOutreach.add(address.toLowerCase());
             }
             dbg("send contact=%s address=%s status=%s traceId=%s spanName=send", contact, address, ack.status, sendTraceId);
-            return { status: "sent" };
+            return {
+                status: "sent",
+                messageId: ack.messageId,
+                acknowledgementStatus: ack.status,
+                ...(messageRef !== undefined && { messageRef }),
+                ...(addressedTarget !== undefined && { addressedTarget }),
+            };
         }
         catch (err) {
+            if (err instanceof SendOutcomeUnknownError) {
+                dbg("send outcome unknown contact=%s messageId=%s reason=%s", contact, err.messageId, err.reason);
+                return {
+                    status: "unknown",
+                    messageId: err.messageId,
+                    attempts: err.attempts,
+                    retryable: err.retryable,
+                    reason: err.reason,
+                    error: err.message,
+                    errorCode: err.code,
+                };
+            }
             if (err instanceof ConnectorError) {
                 const message = formatErrorMessage(err.code, err.to ?? contact);
                 dbg("send failed contact=%s code=%s message=%s", contact, err.code, message);
@@ -98,8 +179,16 @@ export class ConversationManager {
         this.ensureConversationEntry(contact, address, "remote");
         dbg("registerInbound contact=%s address=%s", contact, address);
     }
+    refreshInboundPortrayal(contact, address) {
+        const entry = this.conversations.get(this.resolveConversationAlias(address));
+        if (!entry)
+            return false;
+        entry.contact = contact;
+        dbg("refreshInboundPortrayal contact=%s address=%s", contact, address);
+        return true;
+    }
     recordInboundEnvelope(address, envelope) {
-        const entry = this.conversations.get(address);
+        const entry = this.conversations.get(this.resolveConversationAlias(address));
         if (!entry) {
             dbg("recordInboundEnvelope no entry, skipped address=%s", address);
             return;
@@ -108,7 +197,7 @@ export class ConversationManager {
         dbg("recordInboundEnvelope address=%s messageId=%s correlationId=%s", address, envelope.messageId ?? "(absent)", envelope.correlationId ?? "(absent)");
     }
     getContactByAddress(address) {
-        const entry = this.conversations.get(address);
+        const entry = this.conversations.get(this.resolveConversationAlias(address));
         if (entry)
             return entry.contact;
         for (const [, e] of this.conversations) {
@@ -155,6 +244,7 @@ export class ConversationManager {
         for (const [address, entry] of this.conversations) {
             if (entry.ended) {
                 this.conversations.delete(address);
+                this.deleteConversationAliases(address);
                 count++;
             }
         }
@@ -167,7 +257,10 @@ export class ConversationManager {
     }
     resolveContactForSend(contact) {
         if (isRoutableAddress(contact)) {
-            return { address: contact, ambiguous: false };
+            return {
+                address: this.resolveConversationAlias(contact),
+                ambiguous: false,
+            };
         }
         const normalizedContact = normalizeHandleContact(contact);
         if (this.conversations.has(normalizedContact)) {
@@ -194,22 +287,77 @@ export class ConversationManager {
     extractHandle(address) {
         return extractHandleFromAddress(address);
     }
+    resolveConversationAlias(address) {
+        return this.conversationAliases.get(address) ?? address;
+    }
+    recordConversationAlias(aliasAddress, canonicalAddress) {
+        if (aliasAddress === canonicalAddress)
+            return;
+        this.conversationAliases.delete(canonicalAddress);
+        for (const [alias, target] of this.conversationAliases) {
+            if (target === aliasAddress) {
+                this.conversationAliases.set(alias, canonicalAddress);
+            }
+        }
+        this.conversationAliases.set(aliasAddress, canonicalAddress);
+    }
+    deleteConversationAliases(canonicalAddress) {
+        for (const [alias, target] of this.conversationAliases) {
+            if (target === canonicalAddress)
+                this.conversationAliases.delete(alias);
+        }
+    }
+    fileResolvedConversation(sentAddress, resolvedAddress) {
+        const prior = sentAddress !== resolvedAddress && isRoutableAddress(sentAddress)
+            ? this.conversations.get(sentAddress)
+            : undefined;
+        const canonical = this.conversations.get(resolvedAddress);
+        if (prior)
+            this.conversations.delete(sentAddress);
+        if (sentAddress !== resolvedAddress && isRoutableAddress(sentAddress)) {
+            this.recordConversationAlias(sentAddress, resolvedAddress);
+        }
+        if (!canonical && prior) {
+            this.conversations.set(resolvedAddress, {
+                ...prior,
+                address: resolvedAddress,
+                lastMessageAt: Date.now(),
+                ended: false,
+            });
+            return;
+        }
+        if (canonical) {
+            canonical.lastMessageAt = Date.now();
+            canonical.ended = false;
+            if (prior?.initiatedBy === "local")
+                canonical.initiatedBy = "local";
+            if (prior?.inboundEnvelope &&
+                (!canonical.inboundEnvelope ||
+                    prior.inboundEnvelope.receivedAt >
+                        canonical.inboundEnvelope.receivedAt)) {
+                canonical.inboundEnvelope = prior.inboundEnvelope;
+            }
+            return;
+        }
+        this.ensureConversationEntry(this.extractHandle(resolvedAddress), resolvedAddress, "local");
+    }
     ensureConversationEntry(contact, address, initiatedBy) {
-        if (!this.conversations.has(address)) {
-            const outreachKey = extractHandleFromAddress(address).toLowerCase();
+        const canonicalAddress = this.resolveConversationAlias(address);
+        if (!this.conversations.has(canonicalAddress)) {
+            const outreachKey = extractHandleFromAddress(canonicalAddress).toLowerCase();
             let origin = initiatedBy;
             if (origin === "remote" && this.pendingOutreach.delete(outreachKey)) {
                 origin = "local";
             }
-            this.conversations.set(address, {
+            this.conversations.set(canonicalAddress, {
                 contact,
-                address,
+                address: canonicalAddress,
                 lastMessageAt: Date.now(),
                 initiatedBy: origin,
             });
         }
         else {
-            const entry = this.conversations.get(address);
+            const entry = this.conversations.get(canonicalAddress);
             if (entry) {
                 entry.lastMessageAt = Date.now();
                 entry.ended = false;
@@ -218,5 +366,6 @@ export class ConversationManager {
     }
     _resetForTesting() {
         this.conversations.clear();
+        this.conversationAliases.clear();
     }
 }

package/dist/handoff-deadline.d.ts

@@ -0,0 +1,4 @@
+export declare class SetupFlowError extends Error {
+}
+export declare function assertHandoffDeadlineActive(expiresAt: number): void;
+//# sourceMappingURL=handoff-deadline.d.ts.map

package/dist/handoff-deadline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-deadline.d.ts","sourceRoot":"","sources":["../src/handoff-deadline.ts"],"names":[],"mappings":"AAAA,qBAAa,cAAe,SAAQ,KAAK;CAAG;AAG5C,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAMnE"}

package/dist/handoff-deadline.js

@@ -0,0 +1,7 @@
+export class SetupFlowError extends Error {
+}
+export function assertHandoffDeadlineActive(expiresAt) {
+    if (Date.now() >= expiresAt) {
+        throw new SetupFlowError("Handoff session expired before the runtime key was delivered. Re-run setup.");
+    }
+}