fix(telegram): cron and heartbeat messages land in wrong chat instead of target topic (#19367)

Merged via /review-pr -> /prepare-pr -> /merge-pr.

Prepared head SHA: bf02bbf9ce
Co-authored-by: Lukavyi <1013690+Lukavyi@users.noreply.github.com>
Co-authored-by: obviyus <22031114+obviyus@users.noreply.github.com>
Reviewed-by: @obviyus

src/infra/heartbeat-runner.returns-default-unset.test.ts

@@ -305,6 +305,46 @@ describe("resolveHeartbeatDeliveryTarget", () => {
     });
   });
 
+  it("keeps explicit telegram targets", () => {
+    const cfg: OpenClawConfig = {
+      agents: { defaults: { heartbeat: { target: "telegram", to: "123" } } },
+    };
+    expect(resolveHeartbeatDeliveryTarget({ cfg, entry: baseEntry })).toEqual({
+      channel: "telegram",
+      to: "123",
+      accountId: undefined,
+      lastChannel: undefined,
+      lastAccountId: undefined,
+    });
+  });
+
+  it("parses threadId from :topic: suffix in heartbeat to", () => {
+    const cfg: OpenClawConfig = {
+      agents: {
+        defaults: {
+          heartbeat: { target: "telegram", to: "-100111:topic:42" },
+        },
+      },
+    };
+    const result = resolveHeartbeatDeliveryTarget({ cfg, entry: baseEntry });
+    expect(result.channel).toBe("telegram");
+    expect(result.to).toBe("-100111");
+    expect(result.threadId).toBe(42);
+  });
+
+  it("heartbeat to without :topic: has no threadId", () => {
+    const cfg: OpenClawConfig = {
+      agents: {
+        defaults: {
+          heartbeat: { target: "telegram", to: "-100111" },
+        },
+      },
+    };
+    const result = resolveHeartbeatDeliveryTarget({ cfg, entry: baseEntry });
+    expect(result.to).toBe("-100111");
+    expect(result.threadId).toBeUndefined();
+  });
+
   it("uses explicit heartbeat accountId when provided", () => {
     const cfg: OpenClawConfig = {
       agents: {

src/infra/heartbeat-runner.ts

@@ -637,6 +637,7 @@ export async function runHeartbeatOnce(opts: {
       channel: delivery.channel,
       to: delivery.to,
       accountId: delivery.accountId,
+      threadId: delivery.threadId,
       payloads: [{ text: heartbeatOkText }],
       agentId,
       deps: opts.deps,
@@ -832,6 +833,7 @@ export async function runHeartbeatOnce(opts: {
       to: delivery.to,
       accountId: deliveryAccountId,
       agentId,
+      threadId: delivery.threadId,
       payloads: [
         ...reasoningPayloads,
         ...(shouldSkipMain

src/infra/outbound/outbound.test.ts

@@ -1000,6 +1000,7 @@ describe("resolveSessionDeliveryTarget", () => {
       to: "+1555",
       accountId: "acct-1",
       threadId: undefined,
+      threadIdExplicit: false,
       mode: "implicit",
       lastChannel: "whatsapp",
       lastTo: "+1555",
@@ -1024,6 +1025,7 @@ describe("resolveSessionDeliveryTarget", () => {
       to: undefined,
       accountId: undefined,
       threadId: undefined,
+      threadIdExplicit: false,
       mode: "implicit",
       lastChannel: "whatsapp",
       lastTo: "+1555",
@@ -1049,6 +1051,7 @@ describe("resolveSessionDeliveryTarget", () => {
       to: "+1555",
       accountId: undefined,
       threadId: undefined,
+      threadIdExplicit: false,
       mode: "implicit",
       lastChannel: "whatsapp",
       lastTo: "+1555",
@@ -1074,6 +1077,7 @@ describe("resolveSessionDeliveryTarget", () => {
       to: undefined,
       accountId: undefined,
       threadId: undefined,
+      threadIdExplicit: false,
       mode: "implicit",
       lastChannel: "whatsapp",
       lastTo: "+1555",

src/infra/outbound/targets.test.ts

@@ -0,0 +1,220 @@
+import { describe, expect, it } from "vitest";
+import { resolveSessionDeliveryTarget } from "./targets.js";
+
+describe("resolveSessionDeliveryTarget", () => {
+  it("derives implicit delivery from the last route", () => {
+    const resolved = resolveSessionDeliveryTarget({
+      entry: {
+        sessionId: "sess-1",
+        updatedAt: 1,
+        lastChannel: " whatsapp ",
+        lastTo: " +1555 ",
+        lastAccountId: " acct-1 ",
+      },
+      requestedChannel: "last",
+    });
+
+    expect(resolved).toEqual({
+      channel: "whatsapp",
+      to: "+1555",
+      accountId: "acct-1",
+      threadId: undefined,
+      threadIdExplicit: false,
+      mode: "implicit",
+      lastChannel: "whatsapp",
+      lastTo: "+1555",
+      lastAccountId: "acct-1",
+      lastThreadId: undefined,
+    });
+  });
+
+  it("prefers explicit targets without reusing lastTo", () => {
+    const resolved = resolveSessionDeliveryTarget({
+      entry: {
+        sessionId: "sess-2",
+        updatedAt: 1,
+        lastChannel: "whatsapp",
+        lastTo: "+1555",
+      },
+      requestedChannel: "telegram",
+    });
+
+    expect(resolved).toEqual({
+      channel: "telegram",
+      to: undefined,
+      accountId: undefined,
+      threadId: undefined,
+      threadIdExplicit: false,
+      mode: "implicit",
+      lastChannel: "whatsapp",
+      lastTo: "+1555",
+      lastAccountId: undefined,
+      lastThreadId: undefined,
+    });
+  });
+
+  it("allows mismatched lastTo when configured", () => {
+    const resolved = resolveSessionDeliveryTarget({
+      entry: {
+        sessionId: "sess-3",
+        updatedAt: 1,
+        lastChannel: "whatsapp",
+        lastTo: "+1555",
+      },
+      requestedChannel: "telegram",
+      allowMismatchedLastTo: true,
+    });
+
+    expect(resolved).toEqual({
+      channel: "telegram",
+      to: "+1555",
+      accountId: undefined,
+      threadId: undefined,
+      threadIdExplicit: false,
+      mode: "implicit",
+      lastChannel: "whatsapp",
+      lastTo: "+1555",
+      lastAccountId: undefined,
+      lastThreadId: undefined,
+    });
+  });
+
+  it("passes through explicitThreadId when provided", () => {
+    const resolved = resolveSessionDeliveryTarget({
+      entry: {
+        sessionId: "sess-thread",
+        updatedAt: 1,
+        lastChannel: "telegram",
+        lastTo: "-100123",
+        lastThreadId: 999,
+      },
+      requestedChannel: "last",
+      explicitThreadId: 42,
+    });
+
+    expect(resolved.threadId).toBe(42);
+    expect(resolved.channel).toBe("telegram");
+    expect(resolved.to).toBe("-100123");
+  });
+
+  it("uses session lastThreadId when no explicitThreadId", () => {
+    const resolved = resolveSessionDeliveryTarget({
+      entry: {
+        sessionId: "sess-thread-2",
+        updatedAt: 1,
+        lastChannel: "telegram",
+        lastTo: "-100123",
+        lastThreadId: 999,
+      },
+      requestedChannel: "last",
+    });
+
+    expect(resolved.threadId).toBe(999);
+  });
+
+  it("falls back to a provided channel when requested is unsupported", () => {
+    const resolved = resolveSessionDeliveryTarget({
+      entry: {
+        sessionId: "sess-4",
+        updatedAt: 1,
+        lastChannel: "whatsapp",
+        lastTo: "+1555",
+      },
+      requestedChannel: "webchat",
+      fallbackChannel: "slack",
+    });
+
+    expect(resolved).toEqual({
+      channel: "slack",
+      to: undefined,
+      accountId: undefined,
+      threadId: undefined,
+      threadIdExplicit: false,
+      mode: "implicit",
+      lastChannel: "whatsapp",
+      lastTo: "+1555",
+      lastAccountId: undefined,
+      lastThreadId: undefined,
+    });
+  });
+
+  it("parses :topic:NNN from explicitTo into threadId", () => {
+    const resolved = resolveSessionDeliveryTarget({
+      entry: {
+        sessionId: "sess-topic",
+        updatedAt: 1,
+        lastChannel: "telegram",
+        lastTo: "63448508",
+      },
+      requestedChannel: "last",
+      explicitTo: "63448508:topic:1008013",
+    });
+
+    expect(resolved.to).toBe("63448508");
+    expect(resolved.threadId).toBe(1008013);
+  });
+
+  it("parses :topic:NNN even when lastTo is absent", () => {
+    const resolved = resolveSessionDeliveryTarget({
+      entry: {
+        sessionId: "sess-no-last",
+        updatedAt: 1,
+        lastChannel: "telegram",
+      },
+      requestedChannel: "last",
+      explicitTo: "63448508:topic:1008013",
+    });
+
+    expect(resolved.to).toBe("63448508");
+    expect(resolved.threadId).toBe(1008013);
+  });
+
+  it("skips :topic: parsing for non-telegram channels", () => {
+    const resolved = resolveSessionDeliveryTarget({
+      entry: {
+        sessionId: "sess-slack",
+        updatedAt: 1,
+        lastChannel: "slack",
+        lastTo: "C12345",
+      },
+      requestedChannel: "last",
+      explicitTo: "C12345:topic:999",
+    });
+
+    expect(resolved.to).toBe("C12345:topic:999");
+    expect(resolved.threadId).toBeUndefined();
+  });
+
+  it("skips :topic: parsing when channel is explicitly non-telegram even if lastChannel was telegram", () => {
+    const resolved = resolveSessionDeliveryTarget({
+      entry: {
+        sessionId: "sess-cross",
+        updatedAt: 1,
+        lastChannel: "telegram",
+        lastTo: "63448508",
+      },
+      requestedChannel: "slack",
+      explicitTo: "C12345:topic:999",
+    });
+
+    expect(resolved.to).toBe("C12345:topic:999");
+    expect(resolved.threadId).toBeUndefined();
+  });
+
+  it("explicitThreadId takes priority over :topic: parsed value", () => {
+    const resolved = resolveSessionDeliveryTarget({
+      entry: {
+        sessionId: "sess-priority",
+        updatedAt: 1,
+        lastChannel: "telegram",
+        lastTo: "63448508",
+      },
+      requestedChannel: "last",
+      explicitTo: "63448508:topic:1008013",
+      explicitThreadId: 42,
+    });
+
+    expect(resolved.threadId).toBe(42);
+    expect(resolved.to).toBe("63448508");
+  });
+});

src/infra/outbound/targets.ts

@@ -5,6 +5,7 @@ import type { OpenClawConfig } from "../../config/config.js";
 import type { SessionEntry } from "../../config/sessions.js";
 import type { AgentDefaultsConfig } from "../../config/types.agent-defaults.js";
 import { normalizeAccountId } from "../../routing/session-key.js";
+import { parseTelegramTarget } from "../../telegram/targets.js";
 import { deliveryContextFromSession } from "../../utils/delivery-context.js";
 import type {
   DeliverableMessageChannel,
@@ -26,6 +27,7 @@ export type OutboundTarget = {
   to?: string;
   reason?: string;
   accountId?: string;
+  threadId?: string | number;
   lastChannel?: DeliverableMessageChannel;
   lastAccountId?: string;
 };
@@ -43,6 +45,8 @@ export type SessionDeliveryTarget = {
   to?: string;
   accountId?: string;
   threadId?: string | number;
+  /** Whether threadId came from an explicit source (config/param/:topic: parsing) vs session history. */
+  threadIdExplicit?: boolean;
   mode: ChannelOutboundTargetMode;
   lastChannel?: DeliverableMessageChannel;
   lastTo?: string;
@@ -75,20 +79,33 @@ export function resolveSessionDeliveryTarget(params: {
         ? requested
         : undefined;
 
-  const explicitTo =
+  const rawExplicitTo =
     typeof params.explicitTo === "string" && params.explicitTo.trim()
       ? params.explicitTo.trim()
       : undefined;
-  const explicitThreadId =
-    params.explicitThreadId != null && params.explicitThreadId !== ""
-      ? params.explicitThreadId
-      : undefined;
 
   let channel = requestedChannel === "last" ? lastChannel : requestedChannel;
   if (!channel && params.fallbackChannel && isDeliverableMessageChannel(params.fallbackChannel)) {
     channel = params.fallbackChannel;
   }
 
+  // Parse :topic:NNN from explicitTo (Telegram topic syntax).
+  // Only applies when we positively know the channel is Telegram.
+  // When channel is unknown, the downstream send path (resolveTelegramSession)
+  // handles :topic: parsing independently.
+  const isTelegramContext = channel === "telegram" || (!channel && lastChannel === "telegram");
+  let explicitTo = rawExplicitTo;
+  let parsedThreadId: number | undefined;
+  if (isTelegramContext && rawExplicitTo && rawExplicitTo.includes(":topic:")) {
+    const parsed = parseTelegramTarget(rawExplicitTo);
+    explicitTo = parsed.chatId;
+    parsedThreadId = parsed.messageThreadId;
+  }
+  const explicitThreadId =
+    params.explicitThreadId != null && params.explicitThreadId !== ""
+      ? params.explicitThreadId
+      : parsedThreadId;
+
   let to = explicitTo;
   if (!to && lastTo) {
     if (channel && channel === lastChannel) {
@@ -102,11 +119,13 @@ export function resolveSessionDeliveryTarget(params: {
   const threadId = channel && channel === lastChannel ? lastThreadId : undefined;
   const mode = params.mode ?? (explicitTo ? "explicit" : "implicit");
 
+  const resolvedThreadId = explicitThreadId ?? threadId;
   return {
     channel,
     to,
     accountId,
-    threadId: explicitThreadId ?? threadId,
+    threadId: resolvedThreadId,
+    threadIdExplicit: resolvedThreadId != null && explicitThreadId != null,
     mode,
     lastChannel,
     lastTo,
@@ -281,6 +300,7 @@ export function resolveHeartbeatDeliveryTarget(params: {
     to: resolved.to,
     reason,
     accountId: effectiveAccountId,
+    threadId: resolvedTarget.threadId,
     lastChannel: resolvedTarget.lastChannel,
     lastAccountId: resolvedTarget.lastAccountId,
   };