@masons/agent-network 0.6.20 → 0.6.21

package/dist/channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACd,MAAM,kCAAkC,CAAC;AAa1C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAuD9D,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAEvD;AAOD,wBAAgB,2BAA2B,IAAI,OAAO,CAIrD;AAGD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE/D;AAeD,wBAAgB,sCAAsC,CACpD,oBAAoB,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,sBAAsB,CAAC,EACjF,MAAM,EAAE;IACN,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,GACA,MAAM,CAiBR;AAED,iBAAS,iCAAiC,CACxC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,gBAAgB,UAAQ,GACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA8CzB;AAED,eAAO,MAAM,4CAA4C,0CACtB,CAAC;AAokBpC,eAAO,MAAM,mBAAmB,EAAE,aAAa,CAAC,mBAAmB,CAuRlE,CAAC"}
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACd,MAAM,kCAAkC,CAAC;AAa1C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAwD9D,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAEvD;AAOD,wBAAgB,2BAA2B,IAAI,OAAO,CAIrD;AAGD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE/D;AAeD,wBAAgB,sCAAsC,CACpD,oBAAoB,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,sBAAsB,CAAC,EACjF,MAAM,EAAE;IACN,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,GACA,MAAM,CAiBR;AAED,iBAAS,iCAAiC,CACxC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,gBAAgB,UAAQ,GACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA8CzB;AAED,eAAO,MAAM,4CAA4C,0CACtB,CAAC;AAkkBpC,eAAO,MAAM,mBAAmB,EAAE,aAAa,CAAC,mBAAmB,CAkSlE,CAAC"}

package/dist/channel.js

@@ -1,8 +1,9 @@
 import { createHash, randomUUID } from "node:crypto";
 import createDebug from "debug";
 import { clearConnectorClient, clearConversationManager, extractNetworkConfig, getDmScope, initConnectorClient, initConversationManager, initToolConfig, isIdentityLinksConfigured, requirePlatformConfig, requirePluginRuntime, } from "./config.js";
-import { ConnectorClient } from "./connector-client.js";
+import { ConnectorClient, ConnectorError, SendOutcomeUnknownError, } from "./connector-client.js";
 import { ConversationManager } from "./conversation-manager.js";
+import { runWithConversationManagerContext } from "./conversation-manager-context.js";
 import { clearEnvironmentContext } from "./environment-context.js";
 import { extractHandleFromAddress } from "./handle-utils.js";
 import { clearOwnerState, isOwnerAddress, markOwnerAddress, setCurrentTurnIsOwner, setCurrentTurnOwnerSignal, } from "./owner-session-state.js";
@@ -10,7 +11,6 @@ import { ServicesRetainedRecipientConsumer, } from "./services-retained-recipien
 import { isServicesRetainedReplyContext, runWithServicesRetainedReplyContext, } from "./services-retained-reply-context.js";
 import { runWithServicesRetainedToolPolicy } from "./services-retained-tool-policy.js";
 import { createReplyTraceMetadata, ensureTraceMetadata, } from "./trace-metadata.js";
-import { setCurrentTurnSender, setCurrentTurnSenderAddress, } from "./turn-context.js";
 import { checkForUpdate } from "./update-check.js";
 const dbg = createDebug("agent-network:channel");
 const SERVICES_RETAINED_INBOX_PEER = "agent-network:services-retained-node-inbox";
@@ -115,34 +115,27 @@ function deriveSenderName(event) {
     if (visitorName && typeof visitorName === "string") {
         return visitorName;
     }
-    return extractHandleFromAddress(event.from);
+    return event.from;
 }
 function deriveNodeName(nodeRef, fromAddress) {
     if (nodeRef.displayName)
         return nodeRef.displayName;
     if (nodeRef.handle)
         return nodeRef.handle;
-    return extractHandleFromAddress(fromAddress);
+    return fromAddress;
 }
-const DEDUP_WINDOW_MS = 60_000;
-const recentMessages = new Map();
-function isDuplicate(from, content, sentAt) {
-    if (!sentAt)
-        return false;
-    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);
-    if (recentMessages.size > 200) {
-        for (const [k, ts] of recentMessages) {
-            if (now - ts > DEDUP_WINDOW_MS)
-                recentMessages.delete(k);
-        }
-    }
-    return false;
+function agentReadableAddressedBody(event) {
+    const facts = [
+        ...(event.messageId === undefined
+            ? []
+            : [`message_id=${JSON.stringify(event.messageId)}`]),
+        ...(event.sentAt === undefined
+            ? []
+            : [`sent_at=${JSON.stringify(event.sentAt)}`]),
+    ];
+    if (facts.length === 0)
+        return event.content;
+    return [`[MASONS message facts: ${facts.join("; ")}]`, event.content].join("\n\n");
 }
 async function handleAddressedMessage(event, conversationManager, client, ctx, options = {}) {
     const fromAddress = event.from;
@@ -155,11 +148,6 @@ async function handleAddressedMessage(event, conversationManager, client, ctx, o
             console.warn(`[agent-network:channel] invalid traceparent from=${fromAddress} traceId=${inboundTrace.traceId} spanName=receive`);
         }
     }
-    if (options.servicesRetained === undefined &&
-        isDuplicate(fromAddress, event.content, event.sentAt)) {
-        dbg("duplicate message suppressed from=%s sentAt=%s", fromAddress, event.sentAt);
-        return true;
-    }
     const inboundCorrelationId = typeof metadata.correlation_id === "string"
         ? metadata.correlation_id
         : undefined;
@@ -204,11 +192,10 @@ async function handleAddressedMessage(event, conversationManager, client, ctx, o
         (nodeRef ? deriveNodeName(nodeRef, fromAddress) : deriveSenderName(event));
     const replyAddress = options.routableReplyAddress ??
         (options.servicesRetained ? undefined : fromAddress);
-    if (replyAddress && !conversationManager.getContactByAddress(replyAddress)) {
+    if (replyAddress &&
+        !conversationManager.refreshInboundPortrayal(contact, replyAddress)) {
         conversationManager.registerInbound(contact, replyAddress);
     }
-    setCurrentTurnSender(contact);
-    setCurrentTurnSenderAddress(replyAddress ?? null);
     let runtime;
     try {
         runtime = requirePluginRuntime();
@@ -247,7 +234,9 @@ async function handleAddressedMessage(event, conversationManager, client, ctx, o
             })
             : route.sessionKey;
         const msgCtx = runtime.channel.reply.finalizeInboundContext({
-            Body: event.content,
+            Body: options.servicesRetained === undefined
+                ? agentReadableAddressedBody(event)
+                : event.content,
             RawBody: event.content,
             CommandBody: event.content,
             From: senderId,
@@ -321,25 +310,39 @@ async function handleAddressedMessage(event, conversationManager, client, ctx, o
                             messageId: inboundMessageId,
                         });
                         const deliverResult = await conversationManager.send(replyAddress, text, replyTrace.metadata);
+                        dbg("deliver reply senderId=%s status=%s ackStatus=%s contentLength=%d traceId=%s originalTraceId=%s spanName=send", senderId, deliverResult.status, deliverResult.status === "sent"
+                            ? deliverResult.acknowledgementStatus
+                            : "(none)", text.length, replyTrace.traceId, replyTrace.originalTraceId ?? "(absent)");
                         if (deliverResult.status === "sent") {
                             replyRouted = true;
                         }
+                        else if (deliverResult.status === "unknown") {
+                            throw new SendOutcomeUnknownError(deliverResult.messageId, deliverResult.reason);
+                        }
                         else {
-                            console.warn(`[agent-network:${ctx.accountId}] reply send FAILED to=${senderId} code=${deliverResult.errorCode ?? "(none)"} error=${deliverResult.error ?? "(none)"}`);
+                            throw new ConnectorError(deliverResult.error ?? "Agent Network send failed", deliverResult.errorCode ?? "SEND_FAILED", replyAddress);
                         }
-                        dbg("deliver reply senderId=%s status=%s contentLength=%d traceId=%s originalTraceId=%s spanName=send", senderId, deliverResult.status, text.length, replyTrace.traceId, replyTrace.originalTraceId ?? "(absent)");
                     },
                     onError: (err) => {
                         dispatchError = err;
-                        console.error(`[agent-network:${ctx.accountId}] dispatch error:`, err);
+                        if (err instanceof SendOutcomeUnknownError) {
+                            console.warn(`[agent-network:${ctx.accountId}] reply send OUTCOME UNKNOWN to=${senderId} messageId=${err.messageId} reason=${err.reason}`);
+                        }
+                        else if (err instanceof ConnectorError) {
+                            console.warn(`[agent-network:${ctx.accountId}] reply send FAILED to=${senderId} code=${err.code} error=${err.message}`);
+                        }
+                        else {
+                            console.error(`[agent-network:${ctx.accountId}] dispatch error:`, err);
+                        }
                     },
                 },
             });
+            const dispatchInConversationManagerContext = () => runWithConversationManagerContext(conversationManager, dispatch);
             if (options.servicesRetained) {
-                await runWithServicesRetainedToolPolicy(runtimeSessionKey, () => runWithServicesRetainedReplyContext(dispatch));
+                await runWithServicesRetainedToolPolicy(runtimeSessionKey, () => runWithServicesRetainedReplyContext(dispatchInConversationManagerContext));
             }
             else {
-                await dispatch();
+                await dispatchInConversationManagerContext();
             }
             if (dispatchError)
                 throw dispatchError;
@@ -383,8 +386,9 @@ function servicesRetainedBody(message) {
     const sender = servicesRetainedSenderName(message);
     const displayName = message.envelope.sender.display_name;
     const handle = message.envelope.sender.handle;
+    const sentAt = message.envelope.sent_at;
     return [
-        `[MASONS canonical message_ref=${JSON.stringify(message.envelope.message_ref)}; sender_display_name=${displayName === undefined ? "absent" : JSON.stringify(displayName)}; sender_handle=${handle === undefined ? "absent" : JSON.stringify(handle)}; sender_label=${JSON.stringify(sender)}; content_type=${JSON.stringify(message.contentType)}]`,
+        `[MASONS canonical message_ref=${JSON.stringify(message.envelope.message_ref)}; sent_at=${sentAt === undefined ? "absent" : JSON.stringify(sentAt)}; sender_display_name=${displayName === undefined ? "absent" : JSON.stringify(displayName)}; sender_handle=${handle === undefined ? "absent" : JSON.stringify(handle)}; sender_label=${JSON.stringify(sender)}; content_type=${JSON.stringify(message.contentType)}]`,
         message.envelope.content,
     ].join("\n\n");
 }
@@ -444,13 +448,19 @@ export const agentNetworkChannel = {
             }
             const state = ctx.accountId ? accounts.get(ctx.accountId) : undefined;
             if (!state)
-                return { channel: "agent-network", messageId: "" };
+                throw new Error("Agent Network account unavailable");
             const result = await state.conversationManager.send(ctx.to, ctx.text);
-            dbg("sendText to=%s status=%s contentLength=%d", ctx.to, result.status, ctx.text.length);
-            return {
-                channel: "agent-network",
-                messageId: `an:${randomUUID()}`,
-            };
+            dbg("sendText to=%s status=%s ackStatus=%s contentLength=%d", ctx.to, result.status, result.status === "sent" ? result.acknowledgementStatus : "(none)", ctx.text.length);
+            if (result.status === "sent") {
+                return { channel: "agent-network", messageId: result.messageId };
+            }
+            if (result.status === "unknown") {
+                throw new SendOutcomeUnknownError(result.messageId, result.reason);
+            }
+            if (result.errorCode) {
+                throw new ConnectorError(result.error ?? result.errorCode, result.errorCode, ctx.to);
+            }
+            throw new Error(result.error ?? "Agent Network send failed");
         },
     },
     gateway: {

package/dist/config.d.ts

@@ -18,9 +18,11 @@ export declare function clearPluginRuntime(): void;
 export declare function requirePluginRuntime(): unknown;
 export declare function requirePlatformConfig(): PlatformClientConfig;
 export declare function requireApiKey(): string;
+export declare function hasApiKey(): boolean;
 export declare function getPendingTarget(): string | null;
 export declare function isProfileNeeded(): boolean;
 export declare function requireConnectorClient(): ConnectorClient;
+export declare function getConnectorClient(): ConnectorClient | null;
 export interface NetworkCredentials {
     connectorUrl: string;
     token: string;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAoCjD,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAsBD,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAMhC;AAYD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAyCjE;AAuCD,wBAAgB,yBAAyB,IAAI,OAAO,CAEnD;AAWD,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAeD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAOjE;AAQD,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAYD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAE1E;AASD,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAKD,wBAAgB,0BAA0B,IAAI,mBAAmB,CAOhE;AASD,wBAAgB,sBAAsB,IAAI,mBAAmB,GAAG,IAAI,CAEnE;AAgBD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAExD;AAKD,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAQD,wBAAgB,oBAAoB,IAAI,OAAO,CAO9C;AAcD,wBAAgB,qBAAqB,IAAI,oBAAoB,CAE5D;AAKD,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAKD,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAEhD;AASD,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AASD,wBAAgB,sBAAsB,IAAI,eAAe,CAOxD;AAyBD,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAQD,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAW5E;AAoBD,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,kBAAkB,EACzB,OAAO,CAAC,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,EACnB,aAAa,CAAC,EAAE,MAAM,EACtB,gBAAgB,CAAC,EAAE,MAAM,IAAI,GAC5B,OAAO,CAAC,IAAI,CAAC,CA0Cf;AAUD,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrE;AASD,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CASvD;AAYD,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAOvD;AAUD,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAOzD;AAwCD,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,IAAI,CAAC,CAsBf;AAQD,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4B1E;AAOD,MAAM,WAAW,YAAY;IAE3B,cAAc,EAAE,OAAO,CAAC;IAExB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B,YAAY,EAAE,OAAO,CAAC;CACvB;AASD,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,YAAY,CAAC,CA2BhE;AAOD,wBAAgB,gBAAgB,IAAI,IAAI,CAWvC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/config.js

@@ -108,6 +108,9 @@ export function requireApiKey() {
     }
     return storedApiKey;
 }
+export function hasApiKey() {
+    return Boolean(storedApiKey);
+}
 export function getPendingTarget() {
     return storedPendingTarget;
 }
@@ -120,6 +123,9 @@ export function requireConnectorClient() {
     }
     return storedConnectorClient;
 }
+export function getConnectorClient() {
+    return storedConnectorClient;
+}
 function ensureNetworkSection(config) {
     if (typeof config.channels !== "object" || config.channels === null) {
         config.channels = {};

package/dist/connector-client.d.ts

@@ -1,14 +1,24 @@
 import { EventEmitter } from "node:events";
-import { type AddressedMessageEvent, type CustodyPendingEvent, type DeliveryPendingEvent, type DeliveryStatusEvent, type SendAckEvent, type StructuredErrorEvent } from "./types.js";
+import { type AddressedMessageEvent, type CustodyPendingEvent, type DeliveryPendingEvent, type DeliveryStatusEvent, type ObservedSendAckEvent, type StructuredErrorEvent } from "./types.js";
+import { type WsHeartbeatOptions } from "./ws-heartbeat.js";
 export declare class ConnectorError extends Error {
     readonly code: string;
     readonly to?: string;
     constructor(message: string, code: string, to?: string);
 }
+export type SendOutcomeUnknownReason = "ack_timeout" | "connection_closed";
+export declare class SendOutcomeUnknownError extends Error {
+    readonly code: "SEND_OUTCOME_UNKNOWN";
+    readonly retryable: false;
+    readonly attempts: 1;
+    readonly messageId: string;
+    readonly reason: SendOutcomeUnknownReason;
+    constructor(messageId: string, reason: SendOutcomeUnknownReason);
+}
 type ConnectorClientEvents = {
     message_received: (event: AddressedMessageEvent) => void;
     custody_pending: (event: CustodyPendingEvent) => void;
-    send_ack: (event: SendAckEvent) => void;
+    send_ack: (event: ObservedSendAckEvent) => void;
     delivery_pending: (event: DeliveryPendingEvent) => void;
     delivery_status: (event: DeliveryStatusEvent) => void;
     structured_error: (event: StructuredErrorEvent) => void;
@@ -16,6 +26,20 @@ type ConnectorClientEvents = {
     connected: () => void;
     disconnected: () => void;
 };
+export interface ConnectorClientOptions {
+    keepalive?: Pick<WsHeartbeatOptions, "intervalMs" | "probeTimeoutMs" | "missesBeforeDisconnect">;
+}
+export type ChannelState = "connecting" | "connected" | "reconnecting" | "disconnected";
+export type RegistrationOutcome = {
+    state: "accepted";
+} | {
+    state: "refused";
+    reason: string;
+} | {
+    state: "replaced";
+} | {
+    state: "none";
+};
 export declare class ConnectorClient extends EventEmitter {
     private readonly url;
     private readonly token;
@@ -24,18 +48,24 @@ export declare class ConnectorClient extends EventEmitter {
     private backoffMs;
     private alreadyConnectedRetries;
     private reconnectTimer;
+    private keepalive;
+    private readonly keepaliveOptions;
     private registerResolve;
     private registerReject;
     private registerTimer;
+    private registration;
+    private everDropped;
     private lastKnownSeq;
     private readonly pendingSeqMessages;
     private readonly seenPayloadIds;
     private readonly seenPayloadIdOrder;
     private pendingSends;
-    constructor(url: string, token: string);
+    constructor(url: string, token: string, options?: ConnectorClientOptions);
     connect(): Promise<void>;
     disconnect(): void;
-    send(to: string, content: string, contentType?: string, metadata?: Record<string, unknown>): Promise<SendAckEvent>;
+    getChannelState(): ChannelState;
+    getRegistration(): RegistrationOutcome;
+    send(to: string, content: string, contentType?: string, metadata?: Record<string, unknown>): Promise<ObservedSendAckEvent>;
     sendTyping(to: string, isTyping: boolean): boolean;
     ackDelivery(upToSeq: number): boolean;
     requestGapFill(sinceSeq: number): boolean;
@@ -70,6 +100,7 @@ export declare class ConnectorClient extends EventEmitter {
     private clearReconnectTimer;
     private cleanupConnection;
     private sendEvent;
+    private sendSerializedEvent;
 }
 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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"}

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