fix(agents): deliver DM media completions directly when requester handoff fails

movefaster · claude · movefaster · commit 9487426f48d5 · 2026-06-19T11:13:09.000-07:00
Background image_generate completions were silently dropped when the requester session's captured origin had no deliverable channel: the MCP-bridged claude-cli runtime collapses it to the internal "webchat" channel, so deliveryTarget.deliver was false and every direct-delivery fallback no-op'd. Backfill the completion origin from the requester session's persisted delivery context (deliveryContextFromSession), and deliver generated media directly for DM targets when the requester-agent handoff fails, not only on session-write-lock errors.

Adds a regression test that supplies no deliverable origin in any param and asserts delivery routes to the backfilled target (negative-control verified: fails without the backfill). Full delivery suite: 102 passing.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/src/agents/subagent-announce-delivery.test.ts b/src/agents/subagent-announce-delivery.test.ts
@@ -1,6 +1,10 @@
 // Subagent announce delivery tests cover the last-mile routing used when child
 // runs report progress or completion back to the requester session.
 import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  useTempSessionsFixture,
+  writeSessionStoreForTest,
+} from "../config/sessions/test-helpers.js";
 import { OutboundDeliveryError } from "../infra/outbound/deliver-types.js";
 import {
   testing as sessionBindingServiceTesting,
@@ -4115,6 +4119,57 @@ describe("deliverSubagentAnnouncement completion delivery", () => {
     expect(sendMessage).not.toHaveBeenCalled();
   });
 
+  it("directly delivers DM media completions when the requester handoff fails", async () => {
+    // Companion to the Slack-channel case above. For a *direct-message* target a
+    // failed requester-agent handoff must NOT drop the user-requested media —
+    // regression test for background image_generate completions that were
+    // silently lost when the requester session could not be woken
+    // (no_active_run on the MCP-bridged CLI runtime), leaving the user with
+    // nothing until they pinged again.
+    const callGateway = vi.fn(async () => {
+      throw new Error("requester handoff exploded after dispatch");
+    }) as unknown as typeof runtimeCallGateway;
+    const sendMessage = createSendMessageMock();
+
+    const result = await deliverDiscordDirectMessageCompletion({
+      callGateway,
+      sendMessage,
+      sourceTool: "image_generate",
+      internalEvents: [
+        {
+          type: "task_completion",
+          source: "image_generation",
+          childSessionKey: "image_generate:task-dm-error",
+          childSessionId: "task-dm-error",
+          announceType: "image generation task",
+          taskLabel: "errored handoff dm image",
+          status: "ok",
+          statusLabel: "completed successfully",
+          result: "Generated 1 image.\nMEDIA:/tmp/generated-dm-error.png",
+          mediaUrls: ["/tmp/generated-dm-error.png"],
+          replyInstruction:
+            "Tell the user the image is ready and send it through the message tool.",
+        },
+      ],
+    });
+
+    expectRecordFields(result, {
+      delivered: true,
+      path: "direct",
+    });
+    expect(callGateway).toHaveBeenCalledTimes(1);
+    expect(sendMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        channel: "discord",
+        accountId: "acct-1",
+        to: "dm:U123",
+        content: "The generated image is ready.",
+        mediaUrls: ["/tmp/generated-dm-error.png"],
+        idempotencyKey: "announce-dm-fallback-empty:generated-media-direct",
+      }),
+    );
+  });
+
   it("runs inactive isolated cron media completions through the requester agent first", async () => {
     const callGateway = createGatewayMock({
       result: {
@@ -4811,3 +4866,95 @@ describe("deliverSubagentAnnouncement completion delivery", () => {
     });
   });
 });
+
+describe("deliverSubagentAnnouncement origin backfill from session store", () => {
+  // Scoped temp session store so we can seed the requester session's persisted
+  // delivery context (lastChannel/lastTo) without touching the real store.
+  const sessionsFixture = useTempSessionsFixture("openclaw-announce-backfill-");
+
+  it("backfills an empty completion origin from the requester session's stored delivery context", async () => {
+    // Regression test for the real background-task drop: the claude-cli /
+    // MCP-bridged runtime captures an EMPTY (or internal "webchat") completion
+    // origin, so the captured origin carries no deliverable channel. Without
+    // backfilling the requester session's persisted lastChannel/lastTo, the
+    // media completion has no external target and is silently dropped (the user
+    // gets nothing until they ping again).
+    //
+    // This test supplies NO deliverable origin in any param — completion/direct/
+    // session origins are all omitted. Delivery can therefore only succeed if
+    // deliveryContextFromSession(entry) rescues the Telegram target from the
+    // session store. Without the backfill the announce handoff returns no
+    // visible output and the result is a `visible_reply_missing` drop with no
+    // sendMessage call.
+    const requesterSessionKey = "agent:main:telegram:75597985";
+    writeSessionStoreForTest(sessionsFixture.storePath(), {
+      [requesterSessionKey]: {
+        sessionId: "requester-session-telegram",
+        lastChannel: "telegram",
+        lastTo: "75597985",
+        lastAccountId: "bot-1",
+      },
+    });
+
+    // Handoff succeeds (does not throw) but produces no visible output — the
+    // `private-final` case where the woken turn never calls the message tool.
+    const callGateway = createGatewayMock({ result: { payloads: [] } });
+    const sendMessage = createSendMessageMock();
+    testing.setDepsForTest({
+      callGateway,
+      getRequesterSessionActivity: () => ({
+        sessionId: "requester-session-telegram",
+        isActive: false,
+      }),
+      getRuntimeConfig: () => ({ session: { store: sessionsFixture.storePath() } }) as never,
+      sendMessage,
+    });
+
+    const result = await deliverSubagentAnnouncement({
+      requesterSessionKey,
+      targetRequesterSessionKey: requesterSessionKey,
+      triggerMessage: "child done",
+      steerMessage: "child done",
+      // Deliberately no requesterOrigin / requesterSessionOrigin /
+      // completionDirectOrigin / directOrigin: the session-store backfill is the
+      // only possible source of a deliverable Telegram target.
+      requesterIsSubagent: false,
+      expectsCompletionMessage: true,
+      bestEffortDeliver: true,
+      directIdempotencyKey: "announce-telegram-backfill",
+      sourceTool: "image_generate",
+      internalEvents: [
+        {
+          type: "task_completion",
+          source: "image_generation",
+          childSessionKey: "image_generate:task-backfill",
+          childSessionId: "task-backfill",
+          announceType: "image generation task",
+          taskLabel: "backfill origin image",
+          status: "ok",
+          statusLabel: "completed successfully",
+          result: "Generated 1 image.\nMEDIA:/tmp/generated-backfill.png",
+          mediaUrls: ["/tmp/generated-backfill.png"],
+          replyInstruction:
+            "Tell the user the image is ready and send it through the message tool.",
+        },
+      ],
+    });
+
+    expectRecordFields(result, {
+      delivered: true,
+      path: "direct",
+    });
+    // The Telegram target (channel/to/accountId) was resolved purely from the
+    // backfilled session entry — that is the behaviour under test.
+    expect(sendMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        channel: "telegram",
+        accountId: "bot-1",
+        to: "75597985",
+        mediaUrls: ["/tmp/generated-backfill.png"],
+        idempotencyKey: "announce-telegram-backfill:generated-media-direct",
+      }),
+    );
+  });
+});
diff --git a/src/agents/subagent-announce-delivery.ts b/src/agents/subagent-announce-delivery.ts
@@ -28,7 +28,11 @@ import {
 import { deriveSessionChatTypeFromKey } from "../sessions/session-chat-type-shared.js";
 import { isCronRunSessionKey, isCronSessionKey } from "../sessions/session-key-utils.js";
 import { isNonTerminalAgentRunStatus } from "../shared/agent-run-status.js";
-import { mergeDeliveryContext, normalizeDeliveryContext } from "../utils/delivery-context.js";
+import {
+  deliveryContextFromSession,
+  mergeDeliveryContext,
+  normalizeDeliveryContext,
+} from "../utils/delivery-context.js";
 import {
   INTERNAL_MESSAGE_CHANNEL,
   isDeliverableMessageChannel,
@@ -1228,19 +1232,29 @@ async function sendSubagentAnnounceDirectly(params: {
     // (channel, to, accountId) fall back to the originating session's
     // lastChannel / lastTo. Without this, a completion origin that carries a
     // channel but not a `to` would prevent external delivery.
+    const requesterEntry = loadRequesterSessionEntry(params.targetRequesterSessionKey).entry;
+    // Last-resort fallback: the requester session's persisted delivery context
+    // (lastChannel / lastTo / origin). This rescues completions whose captured
+    // origin never carried a deliverable channel — e.g. background tasks spawned
+    // from an MCP-bridged CLI runtime, where the tool context lacks the live
+    // inbound channel and the origin collapses to the internal "webchat" channel.
+    // Without this, the completion wake runs but the agent's reply is dropped.
+    const requesterStoredOrigin =
+      params.expectsCompletionMessage && !params.requesterIsSubagent
+        ? deliveryContextFromSession(requesterEntry)
+        : undefined;
     const externalCompletionDirectOrigin =
       stripNonDeliverableChannelForCompletionOrigin(completionDirectOrigin);
     const completionExternalFallbackOrigin = mergeDeliveryContext(
-      directOrigin,
-      requesterSessionOrigin,
+      mergeDeliveryContext(directOrigin, requesterSessionOrigin),
+      requesterStoredOrigin,
     );
     const effectiveDirectOrigin = params.expectsCompletionMessage
       ? mergeDeliveryContext(externalCompletionDirectOrigin, completionExternalFallbackOrigin)
       : directOrigin;
     const sessionOnlyOrigin = effectiveDirectOrigin?.channel
       ? effectiveDirectOrigin
-      : requesterSessionOrigin;
-    const requesterEntry = loadRequesterSessionEntry(params.targetRequesterSessionKey).entry;
+      : (requesterSessionOrigin ?? requesterStoredOrigin);
     const deliveryTarget = !params.requesterIsSubagent
       ? resolveExternalBestEffortDeliveryTarget({
           channel: effectiveDirectOrigin?.channel,
@@ -1476,14 +1490,31 @@ async function sendSubagentAnnounceDirectly(params: {
           return textDelivery;
         }
       }
+      // Generated media is the user-requested result, so when the
+      // requester-agent handoff fails we deliver it directly rather than
+      // dropping it — but only for cases where direct delivery is unambiguously
+      // correct:
+      //   * write-lock failures (any target): the lock is transient and the
+      //     media already exists, so a direct send is the safe recovery.
+      //   * direct-message targets (any non-permanent handoff failure): the user
+      //     asked for this media in a DM; there is no channel/threading context
+      //     that requires the requester agent to mediate. This is the path that
+      //     was silently dropping background image_generate completions when the
+      //     requester session could not be woken (e.g. no_active_run on the
+      //     MCP-bridged CLI runtime), leaving the user with nothing until they
+      //     pinged again.
+      // Channel/group completions intentionally fall through to the visible
+      // throw below so the requester run can re-deliver with proper context.
+      // tryGeneratedMediaDirectDelivery() no-ops when the session is genuinely
+      // active/wakeable or there is no deliverable target.
       if (
-        activeRequesterWakeFailed &&
         agentMediatedCompletion &&
         expectedMediaUrls.length > 0 &&
-        isSessionWriteLockAnnounceAgentError(err)
+        (isSessionWriteLockAnnounceAgentError(err) ||
+          isDirectMessageDeliveryTarget(deliveryTarget, canonicalRequesterSessionKey))
       ) {
         const generatedMediaDelivery = await tryGeneratedMediaDirectDelivery();
-        if (generatedMediaDelivery) {
+        if (generatedMediaDelivery?.delivered) {
           return generatedMediaDelivery;
         }
       }
