@scotthuang/agent-knock-knock 0.12.13 → 0.12.14

package/dist/src/callback-outbox-service.js

@@ -1,37 +1,180 @@
 import { createHash, randomUUID } from "node:crypto";
-import { applyMessageToConversation, createMessage, effectiveTurnStatus, executorForConversation, extractStructuredMessage, isTerminalBridgeCallbackSupersedeStatus, isTerminalDispatchOwnerReleasedStatus, isTurnPhaseStatus, isWaitingForAgentStatus, normalizeLegacyCallbackStatus, parseMessageJson, turnIdForConversation } from "./protocol.js";
-import { beginCallbackRetryPolicy, reduceCallbackRetryPolicy } from "./callback-outbox-policy.js";
-import { createCallbackOutboxSettlement } from "./callback-outbox-settlement.js";
+import { applyMessageToConversation, createMessage, effectiveTurnStatus, executorForConversation, extractStructuredMessage, isTerminalBridgeCallbackSupersedeStatus, isTerminalDispatchOwnerReleasedStatus, isTurnPhaseStatus, isWaitingForAgentStatus, normalizeLegacyCallbackStatus, parseMessageJson, sessionIdForConversation, turnIdForConversation } from "./protocol.js";
+import { beginCallbackRetryPolicy, reduceCallbackRetryPolicy, supersedeCallbackNotificationDelivery } from "./callback-outbox-policy.js";
+import { callbackOutboxEvent, callbackOutboxField, createCallbackOutboxSettlement } from "./callback-outbox-settlement.js";
 import { canonicalJson } from "./canonical-json.js";
+import { callbackRouteFingerprint } from "./callback-route-authority.js";
+import { createCallbackEnvelope, parseCallbackAttemptOutcome, resolveCallbackRoute as resolveHostCallbackRoute } from "./callback-transport.js";
 import { isRecord, nonBlankString as stringValue } from "./value-guards.js";
+function supersedeNotificationForLifecycleMessage(conversation, message, now) {
+    return message.type === "done" || message.type === "error"
+        ? supersedeCallbackNotificationDelivery(conversation, {
+            at: now.toISOString(),
+            reason: `superseded_by_${message.type}_callback`
+        })
+        : conversation;
+}
 export function resolveCallbackGatewayRoute(...candidates) {
+    let gatewayUrl;
     for (const candidate of candidates) {
+        gatewayUrl ??= stringValue(candidate.gatewayUrl);
         const token = stringValue(candidate.token);
         if (!token || token === "<token>") {
             continue;
         }
         return {
-            gatewayUrl: stringValue(candidate.gatewayUrl),
+            gatewayUrl: stringValue(candidate.gatewayUrl) ?? gatewayUrl,
             token
         };
     }
     return {
-        gatewayUrl: undefined,
+        gatewayUrl,
         token: undefined
     };
 }
+function resolveManagedCallbackRoute(input) {
+    if (input.inheritedDelivery) {
+        return resolveHostCallbackRoute(callbackRouteFieldCandidate(input.inheritedDelivery, "callback_route"), legacyCallbackRouteCandidate({
+            gatewayMethod: input.inheritedDelivery.gateway_method,
+            gatewaySession: input.inheritedDelivery.gateway_session ??
+                input.conversation.gateway_session ??
+                input.conversation.openclaw_session,
+            openclawBin: input.inheritedDelivery.openclaw_bin ??
+                input.conversation.openclaw_bin,
+            gatewayUrl: input.inheritedDelivery.gateway_url ??
+                input.conversation.gateway_url
+        }));
+    }
+    return resolveHostCallbackRoute(callbackRouteFieldCandidate(input.options, "callbackRoute"), callbackRouteFieldCandidate(input.conversation, "callback_route"), legacyCallbackRouteCandidate({
+        gatewayMethod: input.options.gatewayMethod ??
+            input.conversation.gateway_method,
+        gatewaySession: input.options.gatewaySession ??
+            input.options.openclawSession ?? input.conversation.gateway_session ??
+            input.conversation.openclaw_session,
+        openclawBin: input.options.openclawBin ?? input.conversation.openclaw_bin,
+        gatewayUrl: input.options.gatewayUrl ?? input.conversation.gateway_url
+    }), legacyCallbackRouteCandidate({
+        gatewayMethod: input.conversation.gateway_method,
+        gatewaySession: input.conversation.gateway_session ??
+            input.conversation.openclaw_session,
+        openclawBin: input.conversation.openclaw_bin,
+        gatewayUrl: input.conversation.gateway_url
+    }));
+}
+function callbackRouteFieldCandidate(container, field) {
+    return Object.hasOwn(container, field)
+        ? { callbackRoute: container[field] }
+        : {};
+}
+function resolvedDeliveryOptions(input) {
+    if (!input.inheritedDelivery) {
+        return {
+            ...input.options,
+            ...(input.callbackRoute ? { callbackRoute: input.callbackRoute } : {}),
+            gatewayMethod: input.options.gatewayMethod ??
+                input.conversation.gateway_method,
+            gatewaySession: input.options.gatewaySession ??
+                input.options.openclawSession ?? input.conversation.gateway_session ??
+                input.conversation.openclaw_session,
+            openclawSession: input.options.openclawSession ??
+                input.conversation.openclaw_session,
+            openclawBin: input.options.openclawBin ?? input.conversation.openclaw_bin,
+            gatewayUrl: input.options.gatewayUrl ?? input.conversation.gateway_url
+        };
+    }
+    const { callbackRoute: _ignoredCurrentRoute, ...currentOptions } = input.options;
+    return {
+        ...currentOptions,
+        ...(input.callbackRoute ? { callbackRoute: input.callbackRoute } : {}),
+        gatewayMethod: stringValue(input.inheritedDelivery.gateway_method),
+        gatewaySession: stringValue(input.inheritedDelivery.gateway_session) ??
+            input.conversation.gateway_session ??
+            input.conversation.openclaw_session,
+        openclawSession: input.conversation.openclaw_session,
+        openclawBin: stringValue(input.inheritedDelivery.openclaw_bin) ??
+            input.conversation.openclaw_bin,
+        gatewayUrl: stringValue(input.inheritedDelivery.gateway_url) ??
+            input.conversation.gateway_url
+    };
+}
+function legacyCallbackRouteCandidate(input) {
+    return stringValue(input.gatewayMethod)
+        ? {
+            legacyOpenClaw: {
+                controllerSessionId: input.gatewaySession,
+                gatewayMethod: input.gatewayMethod,
+                openclawBin: input.openclawBin,
+                gatewayUrl: input.gatewayUrl
+            }
+        }
+        : {};
+}
+function createManagedCallbackEnvelope(route, conversation, message) {
+    return createCallbackEnvelope({
+        route,
+        source: {
+            kind: "managed_turn",
+            session_id: sessionIdForConversation(conversation),
+            turn_id: turnIdForConversation(conversation),
+            conversation_id: conversation.conversation_id
+        },
+        event: {
+            id: message.id,
+            type: message.type,
+            body: message.body,
+            requires_response: message.requires_response,
+            metadata: message.metadata
+        }
+    });
+}
+function assertImmutableCallbackTransport(inheritedDelivery, route, envelope, messageId) {
+    if (!inheritedDelivery)
+        return;
+    if (inheritedDelivery.callback_route !== undefined &&
+        canonicalJson(inheritedDelivery.callback_route) !== canonicalJson(route)) {
+        throw new Error(`callback message ${messageId} conflicts with its persisted immutable route`);
+    }
+    if (inheritedDelivery.callback_envelope !== undefined &&
+        canonicalJson(inheritedDelivery.callback_envelope) !== canonicalJson(envelope)) {
+        throw new Error(`callback message ${messageId} conflicts with its persisted immutable envelope`);
+    }
+}
+function assertDispatchCallbackRouteAuthority(conversation, route) {
+    const takeover = isRecord(conversation.native_session_takeover)
+        ? conversation.native_session_takeover
+        : undefined;
+    const submission = isRecord(takeover?.terminal_bridge_submission)
+        ? takeover.terminal_bridge_submission
+        : undefined;
+    if (!submission ||
+        !Object.hasOwn(submission, "callback_route_fingerprint")) {
+        // Records from before the route-fingerprint field remain readable.
+        return;
+    }
+    const authority = submission.callback_route_fingerprint;
+    const matches = authority === null
+        ? route === undefined
+        : stringValue(authority) !== undefined && route !== undefined &&
+            callbackRouteFingerprint(route) === authority;
+    if (!matches) {
+        throw new Error("callback route conflicts with immutable terminal dispatch authority");
+    }
+}
 export function createCallbackOutboxService(ports) {
     const settlement = createCallbackOutboxSettlement({
         state: {
+            withWriter: ports.state.withWriter,
             withStateTransaction: ports.state.withTransaction,
+            storeDirForStatePath: ports.state.storeDirForStatePath,
             load: ports.state.load,
             save: ports.state.save,
             append: ports.state.append
         },
         retryMonitor: {
-            start: ({ statePath }) => ports.retry.startMonitor({
+            start: ({ statePath, callbackOutboxLane }) => ports.retry.startMonitor({
                 statePath,
-                delayMs: ports.retry.delaysMs[0]
+                delayMs: ports.retry.delaysMs[0],
+                callbackOutboxLane
             })
         },
         clock: { now: ports.runtime.now, nowMs: ports.runtime.nowMs },
@@ -44,6 +187,8 @@ export function createCallbackOutboxService(ports) {
             ? options.conversationOverride
             : ports.state.load(options.statePath);
         const conversation = normalizeLegacyCallbackStatus(loadedConversation);
+        const callbackOutboxLane = options.callbackOutboxLane ?? "lifecycle";
+        const callbackOutbox = callbackOutboxField(callbackOutboxLane);
         const storeDir = ports.state.storeDirForStatePath(options.statePath);
         ports.authority.assertNoDeferredTransfer({
             storeDir,
@@ -51,10 +196,6 @@ export function createCallbackOutboxService(ports) {
             action: "prepare callback for"
         });
         const executor = executorForConversation(conversation);
-        const persistedGatewayRoute = resolveCallbackGatewayRoute({
-            gatewayUrl: options.gatewayUrl,
-            token: options.token
-        });
         const message = options.retryPending === true ||
             options.preserveMessageId === true
             ? parseMessageJson(messageInput)
@@ -68,8 +209,8 @@ export function createCallbackOutboxService(ports) {
             throw new Error(`message.conversation_id ${message.conversation_id} does not match conversation ${conversation.conversation_id}`);
         }
         const existingEvents = ports.state.readEvents(logPath);
-        const callbackDelivery = isRecord(conversation.callback_delivery)
-            ? conversation.callback_delivery
+        const callbackDelivery = isRecord(conversation[callbackOutbox])
+            ? conversation[callbackOutbox]
             : undefined;
         const persistedDeliveryMessage = isRecord(callbackDelivery?.message)
             ? callbackDelivery.message
@@ -83,6 +224,26 @@ export function createCallbackOutboxService(ports) {
         const inheritedDelivery = sameDeliveryMessage
             ? callbackDelivery
             : undefined;
+        const callbackRoute = resolveManagedCallbackRoute({
+            options,
+            conversation,
+            inheritedDelivery
+        });
+        assertDispatchCallbackRouteAuthority(conversation, callbackRoute);
+        const deliveryOptions = resolvedDeliveryOptions({
+            options,
+            conversation,
+            inheritedDelivery,
+            callbackRoute
+        });
+        const persistedGatewayRoute = resolveCallbackGatewayRoute({
+            gatewayUrl: deliveryOptions.gatewayUrl,
+            token: deliveryOptions.token
+        });
+        const callbackEnvelope = callbackRoute
+            ? createManagedCallbackEnvelope(callbackRoute, conversation, message)
+            : undefined;
+        assertImmutableCallbackTransport(inheritedDelivery, callbackRoute, callbackEnvelope, message.id);
         const retryingPending = options.retryPending === true &&
             sameDeliveryMessage &&
             callbackRetryDisposition(ports, inheritedDelivery).state === "retryable";
@@ -141,7 +302,9 @@ export function createCallbackOutboxService(ports) {
             const deliveryAttemptId = randomUUID();
             let nextConversation = retryingPending
                 ? conversation
-                : applyMessageToConversation(conversation, message);
+                : callbackOutboxLane === "notification"
+                    ? conversation
+                    : applyMessageToConversation(supersedeNotificationForLifecycleMessage(conversation, message, ports.runtime.now()), message);
             if (closeTerminalBridgeOnDone) {
                 const closedAt = ports.runtime.now().toISOString();
                 nextConversation = {
@@ -166,7 +329,8 @@ export function createCallbackOutboxService(ports) {
                 deliveryAttempt <= ports.retry.delaysMs.length
                 ? ports.retry.startMonitor({
                     statePath: options.statePath,
-                    delayMs: retryDelayMs
+                    delayMs: retryDelayMs,
+                    callbackOutboxLane
                 })
                 : undefined;
             if (!retryingPending &&
@@ -178,7 +342,7 @@ export function createCallbackOutboxService(ports) {
                 const now = ports.runtime.now().toISOString();
                 nextConversation = {
                     ...nextConversation,
-                    callback_delivery: {
+                    [callbackOutbox]: {
                         status: "pending",
                         message,
                         attempts: deliveryAttempt,
@@ -188,17 +352,20 @@ export function createCallbackOutboxService(ports) {
                         created_at: stringValue(inheritedDelivery?.created_at) ?? now,
                         last_attempt_at: now,
                         updated_at: now,
-                        gateway_method: options.gatewayMethod,
-                        gateway_session: options.gatewaySession ??
-                            options.openclawSession ?? conversation.openclaw_session,
+                        gateway_method: deliveryOptions.gatewayMethod,
+                        gateway_session: deliveryOptions.gatewaySession ??
+                            deliveryOptions.openclawSession ?? conversation.openclaw_session,
                         gateway_url: persistedGatewayRoute.gatewayUrl,
-                        openclaw_bin: options.openclawBin ?? conversation.openclaw_bin,
+                        openclaw_bin: deliveryOptions.openclawBin ??
+                            conversation.openclaw_bin,
                         close_terminal_bridge_on_done: closeTerminalBridgeOnDone,
                         track_delivery: true,
                         final_status: finalStatus,
                         preserve_conversation_status: true,
                         kind: stringValue(options.callbackDeliveryKind) ??
                             stringValue(inheritedDelivery?.kind),
+                        ...(callbackRoute ? { callback_route: callbackRoute } : {}),
+                        ...(callbackEnvelope ? { callback_envelope: callbackEnvelope } : {}),
                         ...(callbackWatchdog
                             ? {
                                 retry_monitor_pid: callbackWatchdog.pid ?? null,
@@ -210,9 +377,7 @@ export function createCallbackOutboxService(ports) {
                 ports.state.append(logPath, {
                     ts: now,
                     conversation_id: conversation.conversation_id,
-                    event: retryingPending
-                        ? "callback_delivery_retry_started"
-                        : "callback_delivery_pending",
+                    event: callbackOutboxEvent(callbackOutboxLane, retryingPending ? "retry_started" : "pending"),
                     message_id: message.id,
                     attempt: deliveryAttempt
                 });
@@ -220,11 +385,13 @@ export function createCallbackOutboxService(ports) {
                     ports.state.append(logPath, {
                         ts: ports.runtime.now().toISOString(),
                         conversation_id: conversation.conversation_id,
-                        event: "callback_retry_monitor_launched",
+                        event: callbackOutboxLane === "notification"
+                            ? "callback_notification_retry_monitor_launched"
+                            : "callback_retry_monitor_launched",
                         message_id: message.id,
                         pid: callbackWatchdog.pid ?? null,
-                        next_attempt_at: isRecord(nextConversation.callback_delivery)
-                            ? nextConversation.callback_delivery.next_attempt_at
+                        next_attempt_at: isRecord(nextConversation[callbackOutbox])
+                            ? nextConversation[callbackOutbox].next_attempt_at
                             : undefined
                     });
                 }
@@ -256,13 +423,16 @@ export function createCallbackOutboxService(ports) {
             }
             return {
                 outcome: "deliver",
-                options,
+                options: deliveryOptions,
                 statePath: options.statePath,
                 logPath,
                 conversation: nextConversation,
                 message,
                 deliveryAttempt,
-                deliveryAttemptId
+                deliveryAttemptId,
+                callbackOutboxLane,
+                ...(callbackRoute ? { callbackRoute } : {}),
+                callbackEnvelope
             };
         }
         return persistPreparation();
@@ -276,15 +446,30 @@ export function createCallbackOutboxService(ports) {
                 message: prepared.message
             };
         }
-        ports.state.assertWriterCompatible(ports.state.storeDirForStatePath(prepared.statePath));
+        const transportConversation = beginPreparedCallbackTransport(ports, prepared);
+        if (!transportConversation) {
+            return {
+                delivered: false,
+                duplicate: true,
+                conversation: ports.state.load(prepared.statePath),
+                message: prepared.message
+            };
+        }
         let acceptedDelivery;
+        let delivery;
         try {
-            const delivery = ports.delivery.deliver({
+            delivery = ports.delivery.deliver({
                 options: prepared.options,
                 statePath: prepared.statePath,
                 logPath: prepared.logPath,
                 conversation: prepared.conversation,
                 message: prepared.message,
+                attempt: {
+                    number: prepared.deliveryAttempt,
+                    id: prepared.deliveryAttemptId
+                },
+                route: prepared.callbackRoute,
+                envelope: prepared.callbackEnvelope,
                 onProgress: (progress) => {
                     settlement.persistDeliveryProgress(prepared, progress);
                 },
@@ -292,16 +477,6 @@ export function createCallbackOutboxService(ports) {
                     acceptedDelivery = accepted;
                 }
             });
-            return {
-                delivered: true,
-                duplicate: false,
-                conversation: settlement.settleDelivery(prepared, {
-                    delivered: true,
-                    delivery
-                }),
-                message: prepared.message,
-                delivery: delivery.kind
-            };
         }
         catch (error) {
             if (acceptedDelivery) {
@@ -329,8 +504,9 @@ export function createCallbackOutboxService(ports) {
                 delivered: false,
                 error
             });
-            const settledDelivery = isRecord(settled.callback_delivery)
-                ? settled.callback_delivery
+            const settledOutbox = callbackOutboxField(prepared.callbackOutboxLane);
+            const settledDelivery = isRecord(settled[settledOutbox])
+                ? settled[settledOutbox]
                 : undefined;
             if (settledDelivery?.status === "delivered") {
                 return {
@@ -343,6 +519,45 @@ export function createCallbackOutboxService(ports) {
             }
             throw error;
         }
+        const attemptOutcome = delivery.attempt_outcome === undefined
+            ? undefined
+            : parseCallbackAttemptOutcome(delivery.attempt_outcome);
+        if (attemptOutcome && attemptOutcome.disposition !== "accepted") {
+            const error = new Error(stringValue(attemptOutcome.evidence?.error_message) ??
+                `callback transport ${attemptOutcome.disposition}: ` +
+                    attemptOutcome.error_code);
+            const settled = settlement.settleDelivery(prepared, {
+                delivered: false,
+                delivery,
+                outcome: attemptOutcome,
+                error
+            });
+            const settledOutbox = callbackOutboxField(prepared.callbackOutboxLane);
+            const settledDelivery = isRecord(settled[settledOutbox])
+                ? settled[settledOutbox]
+                : undefined;
+            if (settledDelivery?.status === "delivered") {
+                return {
+                    delivered: true,
+                    duplicate: false,
+                    conversation: settled,
+                    message: prepared.message,
+                    delivery: delivery.kind
+                };
+            }
+            throw error;
+        }
+        return {
+            delivered: true,
+            duplicate: false,
+            conversation: settlement.settleDelivery(prepared, {
+                delivered: true,
+                delivery,
+                outcome: attemptOutcome
+            }),
+            message: prepared.message,
+            delivery: delivery.kind
+        };
     }
     return {
         prepare,
@@ -352,10 +567,42 @@ export function createCallbackOutboxService(ports) {
         retry: (input) => retryCallback(ports, settlement, input),
         retryDisposition: (delivery) => callbackRetryDisposition(ports, delivery),
         prepareApprovalNotification: (input) => prepareApprovalNotification(prepare, input),
+        prepareStallNotification: (input) => prepareStallNotification(prepare, input),
         prepareTerminalCompletion: (input) => prepareTerminalCompletion(ports, prepare, input)
     };
 }
+function beginPreparedCallbackTransport(ports, prepared) {
+    const storeDir = ports.state.storeDirForStatePath(prepared.statePath);
+    return ports.state.withWriter(storeDir, () => ports.state.withTransaction(prepared.statePath, () => {
+        const current = ports.state.load(prepared.statePath);
+        const field = callbackOutboxField(prepared.callbackOutboxLane);
+        const delivery = isRecord(current[field]) ? current[field] : undefined;
+        const message = isRecord(delivery?.message) ? delivery.message : undefined;
+        if (delivery?.status !== "pending" ||
+            message?.id !== prepared.message.id ||
+            Number(delivery.attempts) !== prepared.deliveryAttempt ||
+            stringValue(delivery.attempt_id) !== prepared.deliveryAttemptId ||
+            delivery.transport_started_at !== undefined) {
+            return undefined;
+        }
+        const now = ports.runtime.now().toISOString();
+        const started = {
+            ...current,
+            [field]: {
+                ...delivery,
+                transport_started_at: now,
+                updated_at: now
+            }
+        };
+        ports.state.save(prepared.statePath, started);
+        return started;
+    }));
+}
 function prepareApprovalNotification(prepare, input) {
+    const callbackRoute = resolveManagedCallbackRoute({
+        options: input.options,
+        conversation: input.conversation
+    });
     const identity = terminalApprovalCallbackIdentity(input.conversation);
     const callbackMessage = createMessage({
         conversation: input.conversation,
@@ -368,7 +615,7 @@ function prepareApprovalNotification(prepare, input) {
         metadata: input.metadata,
         now: identity.now
     });
-    if (!input.conversation.gateway_method) {
+    if (!callbackRoute) {
         return {
             callbackMessage,
             delivered: false
@@ -379,6 +626,7 @@ function prepareApprovalNotification(prepare, input) {
         prepared: prepare({
             options: {
                 ...input.options,
+                ...(callbackRoute ? { callbackRoute } : {}),
                 statePath: input.statePath,
                 log: input.logPath,
                 messageJson: JSON.stringify(callbackMessage),
@@ -386,9 +634,7 @@ function prepareApprovalNotification(prepare, input) {
                 gatewaySession: input.conversation.gateway_session,
                 openclawSession: input.conversation.openclaw_session,
                 openclawBin: input.conversation.openclaw_bin,
-                gatewayUrl: stringValue(input.conversation.gateway_token)
-                    ? input.conversation.gateway_url
-                    : undefined,
+                gatewayUrl: input.conversation.gateway_url,
                 token: stringValue(input.conversation.gateway_token),
                 preserveMessageId: true,
                 callbackDeliveryKind: "approval_notification",
@@ -399,6 +645,41 @@ function prepareApprovalNotification(prepare, input) {
         })
     };
 }
+function prepareStallNotification(prepare, input) {
+    const callbackRoute = resolveManagedCallbackRoute({
+        options: input.options,
+        conversation: input.conversation
+    });
+    if (!callbackRoute) {
+        return {
+            callbackMessage: input.message,
+            delivered: false
+        };
+    }
+    return {
+        callbackMessage: input.message,
+        prepared: prepare({
+            options: {
+                ...input.options,
+                callbackRoute,
+                callbackOutboxLane: "notification",
+                statePath: input.statePath,
+                log: input.logPath,
+                messageJson: JSON.stringify(input.message),
+                gatewayMethod: input.conversation.gateway_method,
+                gatewaySession: input.conversation.gateway_session,
+                openclawSession: input.conversation.openclaw_session,
+                openclawBin: input.conversation.openclaw_bin,
+                gatewayUrl: input.conversation.gateway_url,
+                token: stringValue(input.conversation.gateway_token),
+                preserveMessageId: true,
+                callbackDeliveryKind: "stall_notification",
+                conversationOverride: input.conversation
+            },
+            logPath: input.logPath
+        })
+    };
+}
 function terminalApprovalCallbackIdentity(conversation) {
     const nativeTakeover = isRecord(conversation.native_session_takeover)
         ? conversation.native_session_takeover
@@ -464,7 +745,8 @@ function prepareTerminalCompletion(ports, prepare, input) {
         completionFingerprint,
         outcome: completionOutcome
     });
-    const transaction = ports.state.withTransaction(input.statePath, () => {
+    const storeDir = ports.state.storeDirForStatePath(input.statePath);
+    const transaction = ports.state.withWriter(storeDir, () => ports.state.withTransaction(input.statePath, () => {
         const claim = claimTerminalCompletion(ports, {
             statePath: input.statePath,
             logPath: input.logPath,
@@ -523,9 +805,14 @@ function prepareTerminalCompletion(ports, prepare, input) {
             }),
             id: callbackMessageId
         };
+        const callbackRoute = resolveManagedCallbackRoute({
+            options: input.options,
+            conversation: claim.conversation
+        });
         const prepared = prepare({
             options: {
                 ...input.options,
+                ...(callbackRoute ? { callbackRoute } : {}),
                 statePath: input.statePath,
                 log: input.logPath,
                 closeTerminalBridgeOnDone: false,
@@ -537,11 +824,9 @@ function prepareTerminalCompletion(ports, prepare, input) {
                 gatewaySession: claim.conversation.gateway_session,
                 openclawSession: claim.conversation.openclaw_session,
                 openclawBin: claim.conversation.openclaw_bin,
-                gatewayUrl: stringValue(claim.conversation.gateway_token)
-                    ? claim.conversation.gateway_url
-                    : undefined,
+                gatewayUrl: claim.conversation.gateway_url,
                 token: stringValue(claim.conversation.gateway_token),
-                recordOnly: !stringValue(claim.conversation.gateway_method)
+                recordOnly: !callbackRoute
             },
             logPath: input.logPath
         });
@@ -554,7 +839,7 @@ function prepareTerminalCompletion(ports, prepare, input) {
             prepared,
             callbackMessageId
         };
-    });
+    }));
     if (!transaction.claimed) {
         return transaction;
     }
@@ -654,8 +939,10 @@ function claimTerminalCompletion(ports, input) {
     };
 }
 function retryCallback(ports, settlement, { options, conversation, statePath, logPath }) {
-    const callbackDelivery = isRecord(conversation.callback_delivery)
-        ? conversation.callback_delivery
+    const callbackOutboxLane = options.callbackOutboxLane ?? "lifecycle";
+    const callbackOutbox = callbackOutboxField(callbackOutboxLane);
+    const callbackDelivery = isRecord(conversation[callbackOutbox])
+        ? conversation[callbackOutbox]
         : undefined;
     const legacyStatusError = stringValue(conversation.legacy_callback_status_error);
     if (legacyStatusError) {
@@ -670,7 +957,8 @@ function retryCallback(ports, settlement, { options, conversation, statePath, lo
             expectedMessageId: isRecord(callbackDelivery?.message)
                 ? stringValue(callbackDelivery.message.id)
                 : undefined,
-            reason: "manual_retry_observed_accepted_transport"
+            reason: "manual_retry_observed_accepted_transport",
+            callbackOutboxLane
         });
         if (!recovered) {
             throw new Error(`cannot retry callback for ${conversation.conversation_id}; ` +
@@ -698,10 +986,16 @@ function retryCallback(ports, settlement, { options, conversation, statePath, lo
         gatewayUrl: conversation.gateway_url,
         token: conversation.gateway_token
     });
+    const callbackRoute = resolveManagedCallbackRoute({
+        options,
+        conversation,
+        inheritedDelivery: callbackDelivery
+    });
     return {
         kind: "retried",
         result: ports.delivery.runTransaction({
             ...options,
+            ...(callbackRoute ? { callbackRoute } : {}),
             statePath,
             messageJson: JSON.stringify(callbackDelivery.message),
             gatewayMethod: stringValue(callbackDelivery.gateway_method) ??
@@ -714,6 +1008,7 @@ function retryCallback(ports, settlement, { options, conversation, statePath, lo
             gatewayUrl: gatewayRoute.gatewayUrl,
             token: gatewayRoute.token,
             closeTerminalBridgeOnDone: callbackDelivery.close_terminal_bridge_on_done === true,
+            callbackOutboxLane,
             retryPending: true
         })
     };
@@ -760,13 +1055,24 @@ function rejectManualRetryDisposition(conversation, disposition) {
         throw new Error(`cannot retry callback for ${conversation.conversation_id}; callback ` +
             `delivery retries are exhausted after attempt ${disposition.attempt}`);
     }
+    if (disposition.state === "uncertain") {
+        throw new Error(`cannot retry callback for ${conversation.conversation_id}; callback ` +
+            `attempt ${disposition.attempt} has an uncertain transport outcome ` +
+            `(${disposition.reason}) and must not be blindly repeated`);
+    }
+    if (disposition.state === "permanent_failure") {
+        throw new Error(`cannot retry callback for ${conversation.conversation_id}; callback ` +
+            `attempt ${disposition.attempt} failed permanently ` +
+            `(${disposition.reason})`);
+    }
     if (disposition.state !== "retryable") {
         throw new Error(`cannot retry callback for ${conversation.conversation_id}; ` +
             disposition.reason);
     }
 }
-function reconcileCallbackDelivery(ports, settlement, { statePath, logPath, delayMs }) {
-    return ports.state.withTransaction(statePath, () => {
+function reconcileCallbackDelivery(ports, settlement, { statePath, logPath, delayMs, callbackOutboxLane = "lifecycle" }) {
+    const storeDir = ports.state.storeDirForStatePath(statePath);
+    return ports.state.withWriter(storeDir, () => ports.state.withTransaction(statePath, () => {
         const conversation = ports.state.load(statePath);
         const legacyStatusError = stringValue(conversation.legacy_callback_status_error);
         if (legacyStatusError) {
@@ -778,8 +1084,9 @@ function reconcileCallbackDelivery(ports, settlement, { statePath, logPath, dela
                 diagnostic: legacyStatusError
             };
         }
-        const callbackDelivery = isRecord(conversation.callback_delivery)
-            ? conversation.callback_delivery
+        const callbackOutbox = callbackOutboxField(callbackOutboxLane);
+        const callbackDelivery = isRecord(conversation[callbackOutbox])
+            ? conversation[callbackOutbox]
             : undefined;
         if (!["pending", "failed"].includes(String(callbackDelivery?.status ?? ""))) {
             return { handled: false };
@@ -798,7 +1105,7 @@ function reconcileCallbackDelivery(ports, settlement, { statePath, logPath, dela
                 handled: true,
                 conversationId,
                 status: "skipped",
-                reason: "callback_delivery_metadata_missing"
+                reason: callbackOutboxEvent(callbackOutboxLane, "metadata_missing")
             };
         }
         const disposition = callbackRetryDisposition(ports, callbackDelivery);
@@ -808,15 +1115,16 @@ function reconcileCallbackDelivery(ports, settlement, { statePath, logPath, dela
                 statePath,
                 logPath,
                 expectedMessageId: stringValue(callbackDelivery.message.id),
-                reason: "startup_reconciliation_observed_accepted_transport"
+                reason: "startup_reconciliation_observed_accepted_transport",
+                callbackOutboxLane
             });
             return {
                 handled: true,
                 conversationId,
                 status: settled ? "recovered" : "skipped",
                 reason: settled
-                    ? "callback_delivery_accepted_recovered"
-                    : "callback_delivery_changed_before_recovery"
+                    ? callbackOutboxEvent(callbackOutboxLane, "accepted_recovered")
+                    : callbackOutboxEvent(callbackOutboxLane, "changed_before_recovery")
             };
         }
         if (disposition.state === "in_flight") {
@@ -824,7 +1132,7 @@ function reconcileCallbackDelivery(ports, settlement, { statePath, logPath, dela
                 handled: true,
                 conversationId,
                 status: "already_running",
-                reason: "callback_delivery_attempt_in_flight",
+                reason: callbackOutboxEvent(callbackOutboxLane, "attempt_in_flight"),
                 attempt: disposition.attempt,
                 attemptPid: disposition.attempt_pid,
                 leaseExpiresAt: disposition.lease_expires_at,
@@ -836,7 +1144,7 @@ function reconcileCallbackDelivery(ports, settlement, { statePath, logPath, dela
                 handled: true,
                 conversationId,
                 status: "skipped",
-                reason: "callback_delivery_retries_exhausted"
+                reason: callbackOutboxEvent(callbackOutboxLane, "retries_exhausted")
             };
         }
         if (disposition.state !== "retryable") {
@@ -852,12 +1160,16 @@ function reconcileCallbackDelivery(ports, settlement, { statePath, logPath, dela
             configuredDelayMs >= 0
             ? configuredDelayMs
             : ports.retry.delaysMs[Math.max(0, attempts - 1)];
-        const retryMonitor = ports.retry.startMonitor({ statePath, delayMs: retryDelayMs });
+        const retryMonitor = ports.retry.startMonitor({
+            statePath,
+            delayMs: retryDelayMs,
+            callbackOutboxLane
+        });
         const launchedAt = ports.runtime.now().toISOString();
         const nextAttemptAt = new Date(ports.runtime.nowMs() + retryDelayMs).toISOString();
         ports.state.save(statePath, {
             ...conversation,
-            callback_delivery: {
+            [callbackOutbox]: {
                 ...callbackDelivery,
                 retry_monitor_pid: retryMonitor.pid ?? null,
                 next_attempt_at: nextAttemptAt,
@@ -867,7 +1179,9 @@ function reconcileCallbackDelivery(ports, settlement, { statePath, logPath, dela
         ports.state.append(logPath, {
             ts: launchedAt,
             conversation_id: conversationId,
-            event: "callback_retry_monitor_launched",
+            event: callbackOutboxLane === "notification"
+                ? "callback_notification_retry_monitor_launched"
+                : "callback_retry_monitor_launched",
             message_id: callbackDelivery.message.id,
             pid: retryMonitor.pid ?? null,
             next_attempt_at: nextAttemptAt,
@@ -877,23 +1191,23 @@ function reconcileCallbackDelivery(ports, settlement, { statePath, logPath, dela
             handled: true,
             conversationId,
             status: "launched",
-            reason: "callback_delivery_reconciliation",
+            reason: callbackOutboxEvent(callbackOutboxLane, "reconciliation"),
             monitorPid: retryMonitor.pid
         };
-    });
+    }));
 }
-function runCallbackRetryMonitor(ports, settlement, { statePath, initialDelayMs }) {
+function runCallbackRetryMonitor(ports, settlement, { statePath, initialDelayMs, callbackOutboxLane = "lifecycle" }) {
     const configuredDelayMs = Number(initialDelayMs);
     ports.runtime.sleepSync(Math.max(0, Number.isFinite(configuredDelayMs)
         ? configuredDelayMs
         : ports.retry.delaysMs[0]));
     while (true) {
-        const observed = observeCallbackRetryMonitor(ports, statePath);
+        const observed = observeCallbackRetryMonitor(ports, statePath, callbackOutboxLane);
         if (observed.kind === "stop") {
             return;
         }
         if (observed.kind === "accepted") {
-            settleRetryMonitorAcceptance(ports, settlement, statePath, observed.messageId);
+            settleRetryMonitorAcceptance(ports, settlement, statePath, observed.messageId, callbackOutboxLane);
             return;
         }
         if (observed.kind === "in_flight") {
@@ -901,15 +1215,15 @@ function runCallbackRetryMonitor(ports, settlement, { statePath, initialDelayMs
             continue;
         }
         try {
-            ports.delivery.runTransaction(retryMonitorDeliveryOptions(statePath, observed));
+            ports.delivery.runTransaction(retryMonitorDeliveryOptions(statePath, observed, callbackOutboxLane));
             return;
         }
         catch {
             // The failed attempt is persisted before the next bounded retry.
         }
-        const latest = observeCallbackRetryMonitor(ports, statePath);
+        const latest = observeCallbackRetryMonitor(ports, statePath, callbackOutboxLane);
         if (latest.kind === "accepted") {
-            settleRetryMonitorAcceptance(ports, settlement, statePath, latest.messageId);
+            settleRetryMonitorAcceptance(ports, settlement, statePath, latest.messageId, callbackOutboxLane);
             return;
         }
         if (latest.kind !== "retryable" ||
@@ -920,13 +1234,14 @@ function runCallbackRetryMonitor(ports, settlement, { statePath, initialDelayMs
         ports.runtime.sleepSync(ports.retry.delaysMs[Math.max(0, latest.attempts - 1)]);
     }
 }
-function observeCallbackRetryMonitor(ports, statePath) {
+function observeCallbackRetryMonitor(ports, statePath, callbackOutboxLane) {
     const conversation = ports.state.load(statePath);
     if (stringValue(conversation.legacy_callback_status_error)) {
         return { kind: "stop" };
     }
-    const delivery = isRecord(conversation.callback_delivery)
-        ? conversation.callback_delivery
+    const callbackOutbox = callbackOutboxField(callbackOutboxLane);
+    const delivery = isRecord(conversation[callbackOutbox])
+        ? conversation[callbackOutbox]
         : undefined;
     if (!delivery ||
         !isRecord(delivery.message) ||
@@ -953,7 +1268,7 @@ function observeCallbackRetryMonitor(ports, statePath) {
         attempts: Number(delivery.attempts ?? 0)
     };
 }
-function retryMonitorDeliveryOptions(statePath, observed) {
+function retryMonitorDeliveryOptions(statePath, observed, callbackOutboxLane) {
     const { conversation, delivery } = observed;
     const gatewayRoute = resolveCallbackGatewayRoute({
         gatewayUrl: delivery.gateway_url,
@@ -962,8 +1277,14 @@ function retryMonitorDeliveryOptions(statePath, observed) {
         gatewayUrl: conversation.gateway_url,
         token: conversation.gateway_token
     });
+    const callbackRoute = resolveManagedCallbackRoute({
+        options: { statePath },
+        conversation,
+        inheritedDelivery: delivery
+    });
     return {
         statePath,
+        ...(callbackRoute ? { callbackRoute } : {}),
         messageJson: JSON.stringify(delivery.message),
         gatewayMethod: stringValue(delivery.gateway_method) ??
             conversation.gateway_method,
@@ -974,16 +1295,18 @@ function retryMonitorDeliveryOptions(statePath, observed) {
         gatewayUrl: gatewayRoute.gatewayUrl,
         token: gatewayRoute.token,
         closeTerminalBridgeOnDone: delivery.close_terminal_bridge_on_done === true,
+        callbackOutboxLane,
         retryPending: true,
         disableCallbackRetry: true
     };
 }
-function settleRetryMonitorAcceptance(ports, settlement, statePath, expectedMessageId) {
+function settleRetryMonitorAcceptance(ports, settlement, statePath, expectedMessageId, callbackOutboxLane) {
     settlement.settleAccepted({
         statePath,
         logPath: ports.state.logPathForStatePath(statePath),
         expectedMessageId,
-        reason: "retry_monitor_observed_accepted_transport"
+        reason: "retry_monitor_observed_accepted_transport",
+        callbackOutboxLane
     });
 }
 function requiredMessageJson(value) {
@@ -1008,6 +1331,14 @@ function rejectNonRetryableDelivery(disposition) {
     if (disposition.state === "exhausted") {
         throw new Error(`callback retries are exhausted after attempt ${disposition.attempt}`);
     }
+    if (disposition.state === "uncertain") {
+        throw new Error(`callback attempt ${disposition.attempt} has an uncertain transport ` +
+            `outcome (${disposition.reason}) and must not be blindly repeated`);
+    }
+    if (disposition.state === "permanent_failure") {
+        throw new Error(`callback attempt ${disposition.attempt} failed permanently ` +
+            `(${disposition.reason})`);
+    }
     throw new Error(disposition.state === "unavailable"
         ? disposition.reason
         : "callback delivery is not retryable");