@masons/agent-network 0.6.14 → 0.6.16

package/dist/conversation-manager.js

@@ -18,13 +18,17 @@ function formatErrorMessage(code, to) {
 function normalizeHandleContact(contact) {
     return contact.startsWith("@") ? contact.slice(1) : contact;
 }
+function isRoutableAddress(value) {
+    return (value.startsWith("mstps://") ||
+        value.startsWith("mstp://") ||
+        value.startsWith("passport:"));
+}
 export class ConversationManager {
     client;
-    mstpAuthority;
     conversations = new Map();
-    constructor(client, mstpAuthority) {
+    pendingOutreach = new Set();
+    constructor(client) {
         this.client = client;
-        this.mstpAuthority = mstpAuthority;
     }
     async send(contact, content, metadata) {
         const resolution = this.resolveContactForSend(contact);
@@ -70,7 +74,12 @@ export class ConversationManager {
         }
         try {
             const ack = await this.client.send(address, content, "text", wireMetadata);
-            this.ensureConversationEntry(this.extractHandle(address), address, "local");
+            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" };
         }
@@ -157,9 +166,7 @@ export class ConversationManager {
         return this.resolveContactForSend(contact).address;
     }
     resolveContactForSend(contact) {
-        if (contact.startsWith("mstps://") ||
-            contact.startsWith("mstp://") ||
-            contact.startsWith("passport:")) {
+        if (isRoutableAddress(contact)) {
             return { address: contact, ambiguous: false };
         }
         const normalizedContact = normalizeHandleContact(contact);
@@ -168,10 +175,9 @@ export class ConversationManager {
         }
         let first;
         let ambiguous = false;
-        for (const [addr, entry] of this.conversations) {
-            if (entry.contact !== normalizedContact &&
-                extractHandleFromAddress(addr).toLowerCase() !==
-                    normalizedContact.toLowerCase()) {
+        for (const addr of this.conversations.keys()) {
+            if (extractHandleFromAddress(addr).toLowerCase() !==
+                normalizedContact.toLowerCase()) {
                 continue;
             }
             if (first === undefined) {
@@ -183,21 +189,23 @@ export class ConversationManager {
         }
         if (first !== undefined)
             return { address: first, ambiguous };
-        return {
-            address: `mstps://${this.mstpAuthority}/${normalizedContact}`,
-            ambiguous: false,
-        };
+        return { address: normalizedContact, ambiguous: false };
     }
     extractHandle(address) {
         return extractHandleFromAddress(address);
     }
     ensureConversationEntry(contact, address, initiatedBy) {
         if (!this.conversations.has(address)) {
+            const outreachKey = extractHandleFromAddress(address).toLowerCase();
+            let origin = initiatedBy;
+            if (origin === "remote" && this.pendingOutreach.delete(outreachKey)) {
+                origin = "local";
+            }
             this.conversations.set(address, {
                 contact,
                 address,
                 lastMessageAt: Date.now(),
-                initiatedBy,
+                initiatedBy: origin,
             });
         }
         else {

package/dist/plugin.d.ts

@@ -1,3 +1,4 @@
+export declare function buildInteractionContext(channelId: string | undefined, turnSender: string | null, turnSenderAddress: string | null, turnReplyRoute?: "routable" | "unavailable" | null): string | undefined;
 interface OpenClawPluginApi {
     runtime: unknown;
     registerChannel(opts: {

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAqJA,UAAU,iBAAiB;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,YAAY,CACV,IAAI,EAAE,OAAO,EACb,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3C,IAAI,CAAC;IACR,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC;CACnE;AAED,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAaI,iBAAiB;CAmYhC,CAAC;AAEF,eAAe,MAAM,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAsFA,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,iBAAiB,EAAE,MAAM,GAAG,IAAI,EAChC,cAAc,GAAE,UAAU,GAAG,aAAa,GAAG,IAAW,GACvD,MAAM,GAAG,SAAS,CA+EpB;AAKD,UAAU,iBAAiB;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,YAAY,CACV,IAAI,EAAE,OAAO,EACb,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3C,IAAI,CAAC;IACR,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC;CACnE;AAED,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAaI,iBAAiB;CA2YhC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/plugin.js

@@ -7,7 +7,7 @@ import { ownerNotesQueue } from "./owner-notes.js";
 import { consumeCurrentTurnIsOwner, consumeCurrentTurnOwnerSignal, } from "./owner-session-state.js";
 import { sentMessageBuffer } from "./sent-message-buffer.js";
 import { registerTools } from "./tools.js";
-import { consumeCurrentTurnSender, setCurrentTurnChannelId, setCurrentTurnIsOwnerForTools, setCurrentTurnOwnerSignalForTools, } from "./turn-context.js";
+import { consumeCurrentTurnReplyRoute, consumeCurrentTurnSender, consumeCurrentTurnSenderAddress, setCurrentTurnChannelId, setCurrentTurnIsOwnerForTools, setCurrentTurnOwnerSignalForTools, } from "./turn-context.js";
 import { getUpdateInfo } from "./update-check.js";
 import { PLUGIN_VERSION } from "./version.js";
 function formatTimeAgo(timestamp) {
@@ -38,7 +38,7 @@ function drainAndFormatNotes(reportInstruction) {
         reportInstruction);
 }
 const MAX_INTERACTIONS = 5;
-function buildInteractionContext(channelId, turnSender) {
+export function buildInteractionContext(channelId, turnSender, turnSenderAddress, turnReplyRoute = null) {
     const cm = getConversationManager();
     if (!cm)
         return undefined;
@@ -53,20 +53,27 @@ function buildInteractionContext(channelId, turnSender) {
         ? `[Active interactions (showing ${sorted.length} of ${conversations.length})]`
         : "[Active interactions]";
     const lines = sorted.map((c) => {
-        const who = `@${c.contact}`;
+        const who = c.contact === c.address ? c.address : `${c.contact} (${c.address})`;
         const initiated = c.initiatedBy === "local" ? "you initiated" : "they initiated";
         const when = formatTimeAgo(c.lastMessageAt);
         return `• ${who} — ${initiated} — last activity ${when}`;
     });
     const isNetworkTurn = channelId === "agent-network";
     if (isNetworkTurn && turnSender) {
-        const senderConvo = conversations.find((c) => c.contact === turnSender);
+        const senderConvo = turnSenderAddress
+            ? conversations.find((c) => c.address === turnSenderAddress)
+            : undefined;
         const initiated = senderConvo?.initiatedBy === "local"
             ? "You initiated this interaction."
             : "They initiated this interaction.";
+        const from = turnSenderAddress && turnSenderAddress !== turnSender
+            ? `${turnSender} (${turnSenderAddress})`
+            : turnSender;
         return (`${header}\n${lines.join("\n")}\n` +
-            `[This turn] From @${turnSender}. ${initiated}\n` +
-            "Your text reply goes to this sender. " +
+            `[This turn] From ${from}. ${initiated}\n` +
+            (turnReplyRoute === "unavailable"
+                ? "No reply route is available for this message. "
+                : "Your text reply goes to this sender. ") +
             "To report to your owner: masons_note_for_owner.");
     }
     if (isNetworkTurn) {
@@ -137,6 +144,8 @@ const plugin = {
             const turnIsOwner = consumeCurrentTurnIsOwner();
             const turnOwnerSignal = consumeCurrentTurnOwnerSignal();
             const turnSender = consumeCurrentTurnSender();
+            const turnSenderAddress = consumeCurrentTurnSenderAddress();
+            const turnReplyRoute = consumeCurrentTurnReplyRoute();
             setCurrentTurnChannelId(channelId ?? null);
             setCurrentTurnIsOwnerForTools(turnIsOwner);
             setCurrentTurnOwnerSignalForTools(turnOwnerSignal);
@@ -203,11 +212,15 @@ const plugin = {
                     }
                     else {
                         dynamicContext =
-                            "[Agent Network — Routing] This turn was triggered by a message " +
-                                "on the agent network. Your text reply will be sent to that sender — " +
-                                "your owner (Principal) will NOT see it. To report something to your owner, " +
-                                "call masons_note_for_owner.";
-                        const interactionCtx = buildInteractionContext(channelId, turnSender);
+                            turnReplyRoute === "unavailable"
+                                ? "[Agent Network — Services-retained message] This canonical message carries no reply address. " +
+                                    "A plain text reply will NOT be routed to its sender. Do not infer or fabricate an address or Session. " +
+                                    "Treat the message as inbound information; to report something to your owner, call masons_note_for_owner."
+                                : "[Agent Network — Routing] This turn was triggered by a message " +
+                                    "on the agent network. Your text reply will be sent to that sender — " +
+                                    "your owner (Principal) will NOT see it. To report something to your owner, " +
+                                    "call masons_note_for_owner.";
+                        const interactionCtx = buildInteractionContext(channelId, turnSender, turnSenderAddress, turnReplyRoute);
                         if (interactionCtx) {
                             dynamicContext += `\n\n${interactionCtx}`;
                         }
@@ -221,7 +234,7 @@ const plugin = {
                                     return `• (${formatTimeAgo(m.timestamp)}): "${preview}"`;
                                 });
                                 dynamicContext +=
-                                    `\n\n[Your recent messages to @${turnSender}]\n` +
+                                    `\n\n[Your recent messages to ${turnSender}]\n` +
                                         lines.join("\n");
                             }
                         }
@@ -242,7 +255,7 @@ const plugin = {
                             ? `${dynamicContext}\n\n${nudge}`
                             : nudge;
                     }
-                    const interactionCtx = buildInteractionContext(channelId, null);
+                    const interactionCtx = buildInteractionContext(channelId, null, null);
                     if (interactionCtx) {
                         dynamicContext = dynamicContext
                             ? `${dynamicContext}\n\n${interactionCtx}`

package/dist/services-retained-recipient.d.ts

@@ -0,0 +1,58 @@
+import { type RuntimeExactTargetPresentationEnvelopeV1 } from "./_vendor/runtime-adapter-client/index.js";
+export interface ServicesRetainedRecipientPresentation {
+    contentType: string;
+    envelope: RuntimeExactTargetPresentationEnvelopeV1;
+}
+export interface ServicesRetainedRecipientLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string, error?: unknown): void;
+}
+export interface ServicesRetainedRecipientOptions {
+    apiHost: string;
+    runtimeKey: string;
+    present: (message: ServicesRetainedRecipientPresentation) => Promise<boolean>;
+    logger: ServicesRetainedRecipientLogger;
+    endpointNonce?: string;
+    retryDelayMs?: number;
+    minimumHeartbeatDelayMs?: number;
+    fetch?: typeof fetch;
+}
+export declare class ServicesRetainedRecipientConsumer {
+    private readonly clientConfig;
+    private readonly runtimeKey;
+    private readonly present;
+    private readonly logger;
+    private readonly endpointNonce;
+    private readonly retryDelayMs;
+    private readonly minimumHeartbeatDelayMs;
+    private endpoint;
+    private presentedOffer;
+    private acquirePermanentlyBlocked;
+    private consumptionPermanentlyBlocked;
+    private consecutiveHeartbeatNotFound;
+    private stopped;
+    private activationPromise;
+    private drainPromise;
+    private drainRequested;
+    private activationRetryTimer;
+    private drainRetryTimer;
+    private heartbeatTimer;
+    private stopPromise;
+    constructor(options: ServicesRetainedRecipientOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    requestDrain(): Promise<void>;
+    private activate;
+    private drain;
+    private consumePresentedOffer;
+    private scheduleHeartbeat;
+    private heartbeat;
+    private recoverEndpoint;
+    private scheduleActivationRetry;
+    private scheduleDrainRetry;
+    private clearActivationRetryTimer;
+    private clearDrainRetryTimer;
+    private clearHeartbeatTimer;
+}
+//# sourceMappingURL=services-retained-recipient.d.ts.map

package/dist/services-retained-recipient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"services-retained-recipient.d.ts","sourceRoot":"","sources":["../src/services-retained-recipient.ts"],"names":[],"mappings":"AACA,OAAO,EAML,KAAK,wCAAwC,EAI9C,MAAM,2CAA2C,CAAC;AAKnD,MAAM,WAAW,qCAAqC;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,wCAAwC,CAAC;CACpD;AAED,MAAM,WAAW,+BAA+B;IAC9C,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/C;AAED,MAAM,WAAW,gCAAgC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,CAAC,OAAO,EAAE,qCAAqC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9E,MAAM,EAAE,+BAA+B,CAAC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAaD,qBAAa,iCAAiC;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAC1D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8C;IACtE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAS;IAEjD,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,yBAAyB,CAAS;IAC1C,OAAO,CAAC,6BAA6B,CAAS;IAC9C,OAAO,CAAC,4BAA4B,CAAK;IACzC,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,iBAAiB,CAA8B;IACvD,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,oBAAoB,CAA8C;IAC1E,OAAO,CAAC,eAAe,CAA8C;IACrE,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,WAAW,CAA8B;gBAErC,OAAO,EAAE,gCAAgC;IAc/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiCrB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;YAerB,QAAQ;YAoDR,KAAK;YA0EL,qBAAqB;IAwDnC,OAAO,CAAC,iBAAiB;YAcX,SAAS;IAgCvB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,uBAAuB;IAS/B,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,yBAAyB;IAKjC,OAAO,CAAC,oBAAoB;IAK5B,OAAO,CAAC,mBAAmB;CAI5B"}

package/dist/services-retained-recipient.js

@@ -0,0 +1,324 @@
+import { randomUUID } from "node:crypto";
+import { acquireServicesRetainedNodeRecipientMessage, consumeServicesRetainedNodeRecipientMessage, heartbeatRuntimeEndpoint, RuntimeAdapterApiError, registerRuntimeEndpoint, unregisterRuntimeEndpoint, } from "./_vendor/runtime-adapter-client/index.js";
+const RETRY_DELAY_MS = 5_000;
+const MIN_HEARTBEAT_DELAY_MS = 1_000;
+export class ServicesRetainedRecipientConsumer {
+    clientConfig;
+    runtimeKey;
+    present;
+    logger;
+    endpointNonce;
+    retryDelayMs;
+    minimumHeartbeatDelayMs;
+    endpoint = null;
+    presentedOffer = null;
+    acquirePermanentlyBlocked = false;
+    consumptionPermanentlyBlocked = false;
+    consecutiveHeartbeatNotFound = 0;
+    stopped = true;
+    activationPromise = null;
+    drainPromise = null;
+    drainRequested = false;
+    activationRetryTimer = null;
+    drainRetryTimer = null;
+    heartbeatTimer = null;
+    stopPromise = null;
+    constructor(options) {
+        this.clientConfig = {
+            apiHost: options.apiHost,
+            ...(options.fetch && { fetch: options.fetch }),
+        };
+        this.runtimeKey = options.runtimeKey;
+        this.present = options.present;
+        this.logger = options.logger;
+        this.endpointNonce = options.endpointNonce ?? randomUUID();
+        this.retryDelayMs = options.retryDelayMs ?? RETRY_DELAY_MS;
+        this.minimumHeartbeatDelayMs =
+            options.minimumHeartbeatDelayMs ?? MIN_HEARTBEAT_DELAY_MS;
+    }
+    async start() {
+        if (!this.stopped)
+            return this.activationPromise ?? Promise.resolve();
+        const pendingStop = this.stopPromise;
+        if (pendingStop)
+            await pendingStop;
+        if (!this.stopped)
+            return this.activationPromise ?? Promise.resolve();
+        this.stopped = false;
+        await this.activate();
+    }
+    async stop() {
+        if (this.stopPromise)
+            return this.stopPromise;
+        this.stopped = true;
+        this.drainRequested = false;
+        this.clearActivationRetryTimer();
+        this.clearDrainRetryTimer();
+        this.clearHeartbeatTimer();
+        const endpoint = this.endpoint;
+        this.endpoint = null;
+        this.stopPromise = (async () => {
+            await this.activationPromise?.catch(() => undefined);
+            await this.drainPromise?.catch(() => undefined);
+            if (!endpoint)
+                return;
+            try {
+                await unregisterRuntimeEndpoint(this.clientConfig, this.runtimeKey, endpoint.id);
+            }
+            catch (error) {
+                this.logger.warn(`failed to withdraw Services-retained endpoint ${endpoint.id}: ${errorText(error)}`);
+            }
+        })().finally(() => {
+            this.stopPromise = null;
+            this.presentedOffer = null;
+            this.acquirePermanentlyBlocked = false;
+            this.consumptionPermanentlyBlocked = false;
+        });
+        return this.stopPromise;
+    }
+    async requestDrain() {
+        if (this.stopped)
+            return;
+        this.drainRequested = true;
+        if (!this.endpoint) {
+            await this.activate();
+            return;
+        }
+        if (this.drainPromise)
+            return this.drainPromise;
+        this.drainPromise = this.drain().finally(() => {
+            this.drainPromise = null;
+            if (this.drainRequested && !this.stopped)
+                void this.requestDrain();
+        });
+        return this.drainPromise;
+    }
+    async activate() {
+        if (this.stopped || this.endpoint)
+            return;
+        if (this.activationPromise)
+            return this.activationPromise;
+        this.activationPromise = (async () => {
+            try {
+                const response = await registerRuntimeEndpoint(this.clientConfig, this.runtimeKey, {
+                    runtime_kind: "openclaw",
+                    endpoint_nonce: this.endpointNonce,
+                    display_label: "OpenClaw",
+                    runtime_capabilities: ["node_recipient_admission_v1"],
+                    node_recipient_admission_contract_id: "target-node-recipient-services-retained-v1",
+                });
+                if (this.stopped) {
+                    await unregisterRuntimeEndpoint(this.clientConfig, this.runtimeKey, response.endpoint_id).catch(() => undefined);
+                    return;
+                }
+                this.endpoint = {
+                    id: response.endpoint_id,
+                    nonce: this.endpointNonce,
+                    heartbeatAfterSeconds: response.heartbeat_after_seconds,
+                };
+                this.consecutiveHeartbeatNotFound = 0;
+                this.acquirePermanentlyBlocked = false;
+                this.clearActivationRetryTimer();
+                this.logger.info(`Services-retained recipient active endpoint=${response.endpoint_id}`);
+                this.scheduleHeartbeat();
+                this.drainRequested = true;
+            }
+            catch (error) {
+                this.logger.error("Services-retained recipient declaration failed; live Connector participation remains available", error);
+                this.scheduleActivationRetry();
+            }
+        })().finally(() => {
+            this.activationPromise = null;
+        });
+        await this.activationPromise;
+        if (this.endpoint && this.drainRequested)
+            await this.requestDrain();
+    }
+    async drain() {
+        while (!this.stopped && this.endpoint) {
+            this.drainRequested = false;
+            const endpoint = this.endpoint;
+            if (this.presentedOffer) {
+                if (this.consumptionPermanentlyBlocked)
+                    return;
+                if (!(await this.consumePresentedOffer(endpoint)))
+                    return;
+                continue;
+            }
+            if (this.acquirePermanentlyBlocked)
+                return;
+            let acquired;
+            try {
+                acquired = await acquireServicesRetainedNodeRecipientMessage(this.clientConfig, this.runtimeKey, {
+                    endpoint_id: endpoint.id,
+                    endpoint_nonce: endpoint.nonce,
+                });
+            }
+            catch (error) {
+                this.logger.error("Services-retained acquire failed", error);
+                this.scheduleDrainRetry();
+                return;
+            }
+            if (this.stopped || this.endpoint !== endpoint)
+                return;
+            if (acquired.status === "empty")
+                return;
+            if (acquired.status === "rejected") {
+                this.logger.warn(`Services-retained acquire rejected reason=${acquired.reason} retryable=${String(acquired.retryable)}`);
+                if (acquired.reason === "endpoint_unavailable") {
+                    this.recoverEndpoint(endpoint);
+                }
+                else {
+                    this.acquirePermanentlyBlocked = true;
+                    this.logger.error(`Services-retained acquire stopped on permanent provider rejection reason=${acquired.reason}`);
+                }
+                return;
+            }
+            let presented = false;
+            try {
+                presented = await this.present({
+                    contentType: acquired.content_type,
+                    envelope: acquired.envelope,
+                });
+            }
+            catch (error) {
+                this.logger.error(`OpenClaw inbound presentation failed message_ref=${acquired.message_ref}`, error);
+            }
+            if (!presented) {
+                this.scheduleDrainRetry();
+                return;
+            }
+            this.presentedOffer = {
+                messageRef: acquired.message_ref,
+                offerRef: acquired.offer_ref,
+            };
+            this.consumptionPermanentlyBlocked = false;
+            if (!(await this.consumePresentedOffer(endpoint)))
+                return;
+        }
+    }
+    async consumePresentedOffer(endpoint) {
+        const offer = this.presentedOffer;
+        if (!offer)
+            return true;
+        const outcome = await consumeServicesRetainedNodeRecipientMessage(this.clientConfig, this.runtimeKey, {
+            type: "runtime_node_recipient_message_consumption",
+            version: 1,
+            endpoint_id: endpoint.id,
+            endpoint_nonce: endpoint.nonce,
+            message_ref: offer.messageRef,
+            offer_ref: offer.offerRef,
+        });
+        if (outcome.ok) {
+            this.logger.info(`Services-retained message consumed message_ref=${offer.messageRef} status=${outcome.status}`);
+            this.presentedOffer = null;
+            this.consumptionPermanentlyBlocked = false;
+            this.drainRequested = true;
+            return true;
+        }
+        const reason = "providerStatus" in outcome ? outcome.reason : undefined;
+        this.logger.warn(`Services-retained consumption failed message_ref=${offer.messageRef} terminal=${String(outcome.terminal)}${reason ? ` reason=${reason}` : ""}`);
+        if (reason === "endpoint_unavailable") {
+            this.recoverEndpoint(endpoint);
+            return false;
+        }
+        if (reason === "processing_conflict" || !outcome.terminal) {
+            this.scheduleDrainRetry();
+            return false;
+        }
+        if (reason === "message_terminal") {
+            this.presentedOffer = null;
+            this.consumptionPermanentlyBlocked = false;
+            this.drainRequested = true;
+            return true;
+        }
+        this.consumptionPermanentlyBlocked = true;
+        this.logger.error(`Services-retained consumption stopped on permanent rejection message_ref=${offer.messageRef}${reason ? ` reason=${reason}` : ""}`);
+        return false;
+    }
+    scheduleHeartbeat() {
+        this.clearHeartbeatTimer();
+        if (this.stopped || !this.endpoint)
+            return;
+        const delay = Math.max(this.minimumHeartbeatDelayMs, this.endpoint.heartbeatAfterSeconds * 1_000);
+        this.heartbeatTimer = setTimeout(() => {
+            this.heartbeatTimer = null;
+            void this.heartbeat();
+        }, delay);
+        this.heartbeatTimer.unref?.();
+    }
+    async heartbeat() {
+        const endpoint = this.endpoint;
+        if (this.stopped || !endpoint)
+            return;
+        try {
+            await heartbeatRuntimeEndpoint(this.clientConfig, this.runtimeKey, endpoint.id);
+            this.consecutiveHeartbeatNotFound = 0;
+            void this.requestDrain();
+        }
+        catch (error) {
+            this.logger.warn(`Services-retained endpoint heartbeat failed endpoint=${endpoint.id}: ${errorText(error)}`);
+            if (error instanceof RuntimeAdapterApiError &&
+                error.status === 404 &&
+                error.code === "not_found") {
+                this.consecutiveHeartbeatNotFound++;
+                if (this.consecutiveHeartbeatNotFound >= 2) {
+                    this.recoverEndpoint(endpoint);
+                }
+            }
+            else {
+                this.consecutiveHeartbeatNotFound = 0;
+            }
+        }
+        finally {
+            if (this.endpoint === endpoint)
+                this.scheduleHeartbeat();
+        }
+    }
+    recoverEndpoint(endpoint) {
+        if (this.stopped || this.endpoint !== endpoint)
+            return;
+        this.endpoint = null;
+        this.acquirePermanentlyBlocked = false;
+        this.consumptionPermanentlyBlocked = false;
+        this.consecutiveHeartbeatNotFound = 0;
+        this.clearHeartbeatTimer();
+        this.scheduleActivationRetry();
+    }
+    scheduleActivationRetry() {
+        if (this.stopped || this.activationRetryTimer)
+            return;
+        this.activationRetryTimer = setTimeout(() => {
+            this.activationRetryTimer = null;
+            void this.activate();
+        }, this.retryDelayMs);
+        this.activationRetryTimer.unref?.();
+    }
+    scheduleDrainRetry() {
+        if (this.stopped || this.drainRetryTimer)
+            return;
+        this.drainRetryTimer = setTimeout(() => {
+            this.drainRetryTimer = null;
+            void this.requestDrain();
+        }, this.retryDelayMs);
+        this.drainRetryTimer.unref?.();
+    }
+    clearActivationRetryTimer() {
+        if (this.activationRetryTimer)
+            clearTimeout(this.activationRetryTimer);
+        this.activationRetryTimer = null;
+    }
+    clearDrainRetryTimer() {
+        if (this.drainRetryTimer)
+            clearTimeout(this.drainRetryTimer);
+        this.drainRetryTimer = null;
+    }
+    clearHeartbeatTimer() {
+        if (this.heartbeatTimer)
+            clearTimeout(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+    }
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/turn-context.d.ts

@@ -1,9 +1,13 @@
 import type { OwnerSignal } from "./owner-session-state.js";
 export declare function setCurrentTurnSender(contact: string | null): void;
+export declare function setCurrentTurnSenderAddress(address: string | null): void;
+export declare function setCurrentTurnReplyRoute(route: "routable" | "unavailable"): void;
 export declare function setCurrentTurnChannelId(channelId: string | null): void;
 export declare function setCurrentTurnIsOwnerForTools(value: boolean): void;
 export declare function setCurrentTurnOwnerSignalForTools(signal: OwnerSignal): void;
 export declare function consumeCurrentTurnSender(): string | null;
+export declare function consumeCurrentTurnSenderAddress(): string | null;
+export declare function consumeCurrentTurnReplyRoute(): "routable" | "unavailable" | null;
 export declare function getCurrentTurnChannelId(): string | null;
 export declare function getCurrentTurnIsOwnerNonConsuming(): boolean;
 export declare function getCurrentTurnOwnerSignal(): OwnerSignal;

package/dist/turn-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"turn-context.d.ts","sourceRoot":"","sources":["../src/turn-context.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAwC5D,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEjE;AAOD,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEtE;AAOD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAElE;AAUD,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAE3E;AAUD,wBAAgB,wBAAwB,IAAI,MAAM,GAAG,IAAI,CAIxD;AAMD,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAEvD;AAMD,wBAAgB,iCAAiC,IAAI,OAAO,CAE3D;AAOD,wBAAgB,yBAAyB,IAAI,WAAW,CAEvD"}
+{"version":3,"file":"turn-context.d.ts","sourceRoot":"","sources":["../src/turn-context.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AA0C5D,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEjE;AAUD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAExE;AAGD,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,UAAU,GAAG,aAAa,GAChC,IAAI,CAEN;AAOD,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEtE;AAOD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAElE;AAUD,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAE3E;AAUD,wBAAgB,wBAAwB,IAAI,MAAM,GAAG,IAAI,CAIxD;AAGD,wBAAgB,+BAA+B,IAAI,MAAM,GAAG,IAAI,CAI/D;AAGD,wBAAgB,4BAA4B,IACxC,UAAU,GACV,aAAa,GACb,IAAI,CAIP;AAMD,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAEvD;AAMD,wBAAgB,iCAAiC,IAAI,OAAO,CAE3D;AAOD,wBAAgB,yBAAyB,IAAI,WAAW,CAEvD"}

package/dist/turn-context.js

@@ -1,10 +1,18 @@
 let currentTurnSender = null;
+let currentTurnSenderAddress = null;
+let currentTurnReplyRoute = null;
 let currentTurnChannelId = null;
 let currentTurnIsOwner = false;
 let currentTurnOwnerSignalForTools = null;
 export function setCurrentTurnSender(contact) {
     currentTurnSender = contact;
 }
+export function setCurrentTurnSenderAddress(address) {
+    currentTurnSenderAddress = address;
+}
+export function setCurrentTurnReplyRoute(route) {
+    currentTurnReplyRoute = route;
+}
 export function setCurrentTurnChannelId(channelId) {
     currentTurnChannelId = channelId;
 }
@@ -19,6 +27,16 @@ export function consumeCurrentTurnSender() {
     currentTurnSender = null;
     return value;
 }
+export function consumeCurrentTurnSenderAddress() {
+    const value = currentTurnSenderAddress;
+    currentTurnSenderAddress = null;
+    return value;
+}
+export function consumeCurrentTurnReplyRoute() {
+    const value = currentTurnReplyRoute;
+    currentTurnReplyRoute = null;
+    return value;
+}
 export function getCurrentTurnChannelId() {
     return currentTurnChannelId;
 }