fix(cron): route topic targets through channel plugins

steipete · web-flow · commit 917549190624 · 2026-05-23T13:52:06.000+01:00
Route cron announce topic target parsing through channel plugin target parsers instead of Telegram-specific cron core code. Keep supported Telegram topic forms in the Telegram plugin and document the channel-owned shorthand.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -63,6 +63,7 @@ Docs: https://docs.openclaw.ai
 - CLI/tasks: reject partially numeric `openclaw tasks audit --limit` values so audit limits must be real positive integers instead of accepting strings like `5abc`. (#84901) Thanks @jbetala7.
 - Status/diagnostics: bound deep Docker audit probes so `openclaw status --deep` reports slow container checks instead of hanging behind unbounded inspection. (#85476) Thanks @giodl73-repo.
 - Providers/Anthropic: migrate 1M context handling to GA-capable Claude 4.x models by sizing eligible models at 1M without the retired `context-1m-2025-08-07` beta, ignoring that retired beta in older configs, and preserving OAuth-required Anthropic beta headers. (#45613) Thanks @haoyu-haoyu.
+- Cron/Telegram: parse forum-topic delivery targets through the Telegram plugin instead of cron core, including `:topic:` and `:topicId` forms for announce delivery. Thanks @etticat.
 - Twitch: keep stale message-handler cleanup callbacks from removing newer handler registrations for the same account, preserving inbound message delivery after reconnects. Fixes #83888. (#85425) Thanks @alkor2000.
 - Memory/LanceDB: expose public memory artifacts through the active memory provider bridge so memory-wiki imports durable memory files, daily notes, dream reports, and event logs without depending on memory-core internals. Fixes #83604. (#85060) Thanks @brokemac79.
 - Crabbox: keep AWS hydration compatible with local Actions replay by inlining the hydrate workflow's Node/pnpm setup instead of invoking repo-local composite actions.
diff --git a/docs/automation/cron-jobs.md b/docs/automation/cron-jobs.md
@@ -167,7 +167,7 @@ Before an isolated cron run enters the agent runner, OpenClaw checks reachable l
 | `webhook`  | POST finished event payload to a URL                                |
 | `none`     | No runner fallback delivery                                         |
 
-Use `--announce --channel telegram --to "-1001234567890"` for channel delivery. For Telegram forum topics, use `-1001234567890:topic:123`; direct RPC/config callers may also pass `delivery.threadId` as a string or number. Slack/Discord/Mattermost targets should use explicit prefixes (`channel:<id>`, `user:<id>`). Matrix room IDs are case-sensitive; use the exact room ID or `room:!room:server` form from Matrix.
+Use `--announce --channel telegram --to "-1001234567890"` for channel delivery. For Telegram forum topics, use `-1001234567890:topic:123`; OpenClaw also accepts the Telegram-owned `-1001234567890:123` shorthand. Direct RPC/config callers may pass `delivery.threadId` as a string or number. Slack/Discord/Mattermost targets should use explicit prefixes (`channel:<id>`, `user:<id>`). Matrix room IDs are case-sensitive; use the exact room ID or `room:!room:server` form from Matrix.
 
 When announce delivery uses `channel: "last"` or omits `channel`, a provider-prefixed target such as `telegram:123` can select the channel before cron falls back to session history or a single configured channel. Only prefixes advertised by the loaded plugin are provider selectors. If `delivery.channel` is explicit, the target prefix must name the same provider; for example, `channel: "whatsapp"` with `to: "telegram:123"` is rejected instead of letting WhatsApp interpret the Telegram ID as a phone number. Target-kind and service prefixes such as `channel:<id>`, `user:<id>`, `imessage:<handle>`, and `sms:<number>` remain channel-owned target syntax, not provider selectors.
 
diff --git a/src/cron/isolated-agent/delivery-target.runtime.ts b/src/cron/isolated-agent/delivery-target.runtime.ts
@@ -1,3 +1,20 @@
+import type { ParsedChannelExplicitTarget } from "../../channels/plugins/target-parsing-loaded.js";
+import type { OpenClawConfig } from "../../config/types.openclaw.js";
+import { resolveOutboundChannelPlugin } from "../../infra/outbound/channel-resolution.js";
 export { getLoadedChannelPluginForRead } from "../../channels/plugins/registry-loaded-read.js";
 export { mapAllowFromEntries } from "../../plugin-sdk/channel-config-helpers.js";
 export { resolveFirstBoundAccountId } from "../../routing/bound-account-read.js";
+
+export function parseExplicitTargetForDelivery(params: {
+  cfg: OpenClawConfig;
+  channel: string;
+  rawTarget: string;
+}): ParsedChannelExplicitTarget | null {
+  return (
+    resolveOutboundChannelPlugin({
+      channel: params.channel,
+      cfg: params.cfg,
+      allowBootstrap: true,
+    })?.messaging?.parseExplicitTarget?.({ raw: params.rawTarget }) ?? null
+  );
+}
diff --git a/src/cron/isolated-agent/delivery-target.test.ts b/src/cron/isolated-agent/delivery-target.test.ts
@@ -917,6 +917,19 @@ describe("resolveDeliveryTarget", () => {
     expect(result.threadId).toBe(1008013);
   });
 
+  it("parses plugin-owned numeric topic shorthand into delivery threadId", async () => {
+    setMainSessionEntry(undefined);
+
+    const result = await resolveDeliveryTarget(makeCfg({ bindings: [] }), AGENT_ID, {
+      channel: "telegram",
+      to: "-100200300:77",
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.to).toBe("-100200300");
+    expect(result.threadId).toBe(77);
+  });
+
   it("prefers explicit telegram :topic: targets over session-derived threadId", async () => {
     setLastSessionEntry({
       sessionId: "sess-telegram-topic",
diff --git a/src/cron/isolated-agent/delivery-target.ts b/src/cron/isolated-agent/delivery-target.ts
@@ -1,4 +1,3 @@
-import { parseExplicitTargetForLoadedChannel } from "../../channels/plugins/target-parsing-loaded.js";
 import type { ChannelId } from "../../channels/plugins/types.public.js";
 import { resolveAgentMainSessionKey } from "../../config/sessions/main-session.js";
 import { resolveStorePath } from "../../config/sessions/paths.js";
@@ -9,7 +8,10 @@ import { formatErrorMessage } from "../../infra/errors.js";
 import { maybeResolveIdLikeTarget } from "../../infra/outbound/target-id-resolution.js";
 import { normalizeTargetForProvider } from "../../infra/outbound/target-normalization.js";
 import { tryResolveLoadedOutboundTarget } from "../../infra/outbound/targets-loaded.js";
-import { resolveSessionDeliveryTarget } from "../../infra/outbound/targets-session.js";
+import {
+  resolveSessionDeliveryTarget,
+  type ExplicitTargetParser,
+} from "../../infra/outbound/targets-session.js";
 import type { OutboundChannel } from "../../infra/outbound/targets.js";
 import { normalizeAccountId } from "../../routing/session-key.js";
 import { createLazyImportLoader } from "../../shared/lazy-promise.js";
@@ -64,6 +66,7 @@ async function resolveOutboundTargetWithRuntime(
 function normalizeTargetForThreadCarry(
   channel: Exclude<OutboundChannel, "none"> | undefined,
   to: string | undefined,
+  parseExplicitTarget: ExplicitTargetParser,
 ): string | undefined {
   if (!channel || !to) {
     return undefined;
@@ -74,7 +77,7 @@ function normalizeTargetForThreadCarry(
     if (!comparable) {
       return undefined;
     }
-    const parsed = parseExplicitTargetForLoadedChannel(channel, comparable);
+    const parsed = parseExplicitTarget(channel, comparable);
     const base = parsed?.to ?? comparable;
     return normalizeTargetForProvider(channel, base) ?? base;
   } catch {
@@ -86,15 +89,24 @@ function deliveryTargetsShareThreadRoute(params: {
   channel: Exclude<OutboundChannel, "none"> | undefined;
   to: string | undefined;
   lastTo: string | undefined;
+  parseExplicitTarget: ExplicitTargetParser;
 }): boolean {
   if (!params.to || !params.lastTo) {
     return false;
   }
   if (params.to === params.lastTo) {
     return true;
   }
-  const normalizedTo = normalizeTargetForThreadCarry(params.channel, params.to);
-  const normalizedLastTo = normalizeTargetForThreadCarry(params.channel, params.lastTo);
+  const normalizedTo = normalizeTargetForThreadCarry(
+    params.channel,
+    params.to,
+    params.parseExplicitTarget,
+  );
+  const normalizedLastTo = normalizeTargetForThreadCarry(
+    params.channel,
+    params.lastTo,
+    params.parseExplicitTarget,
+  );
   return Boolean(normalizedTo && normalizedLastTo && normalizedTo === normalizedLastTo);
 }
 
@@ -128,6 +140,13 @@ export async function resolveDeliveryTarget(
   const requestedChannel = typeof jobPayload.channel === "string" ? jobPayload.channel : "last";
   const explicitTo = typeof jobPayload.to === "string" ? jobPayload.to : undefined;
   const allowMismatchedLastTo = requestedChannel === "last";
+  const deliveryTargetRuntime = await loadDeliveryTargetRuntime();
+  const parseExplicitTarget: ExplicitTargetParser = (channel, rawTarget) =>
+    deliveryTargetRuntime.parseExplicitTargetForDelivery({
+      cfg,
+      channel,
+      rawTarget,
+    });
 
   const sessionCfg = cfg.session;
   const mainSessionKey = resolveAgentMainSessionKey({ cfg, agentId });
@@ -167,6 +186,7 @@ export async function resolveDeliveryTarget(
     explicitTo,
     explicitThreadId: jobPayload.threadId,
     allowMismatchedLastTo,
+    parseExplicitTarget,
   });
 
   let fallbackChannel: Exclude<OutboundChannel, "none"> | undefined;
@@ -197,6 +217,7 @@ export async function resolveDeliveryTarget(
         fallbackChannel,
         allowMismatchedLastTo,
         mode: preliminary.mode,
+        parseExplicitTarget,
       })
     : preliminary;
 
@@ -213,8 +234,11 @@ export async function resolveDeliveryTarget(
       : undefined;
   let accountId = explicitAccountId ?? resolved.accountId;
   if (!accountId && channel) {
-    const { resolveFirstBoundAccountId } = await loadDeliveryTargetRuntime();
-    accountId = resolveFirstBoundAccountId({ cfg, channelId: channel, agentId });
+    accountId = deliveryTargetRuntime.resolveFirstBoundAccountId({
+      cfg,
+      channelId: channel,
+      agentId,
+    });
   }
 
   // job.delivery.accountId takes highest precedence — explicitly set by the job author.
@@ -233,20 +257,11 @@ export async function resolveDeliveryTarget(
         channel,
         to: resolved.to,
         lastTo: resolved.lastTo,
+        parseExplicitTarget,
       }))
       ? resolved.threadId
       : undefined;
 
-  if (channel === "telegram" && typeof toCandidate === "string") {
-    const topicMatch = toCandidate.match(/:topic:(\d+)$/i);
-    if (topicMatch) {
-      if (jobPayload.threadId == null || jobPayload.threadId === "") {
-        threadId = Number(topicMatch[1]);
-      }
-      toCandidate = toCandidate.replace(/:topic:\d+$/i, "");
-    }
-  }
-
   if (!channel) {
     return {
       ok: false,
@@ -263,8 +278,7 @@ export async function resolveDeliveryTarget(
 
   let effectiveAllowFrom: string[] | undefined;
   if (mode === "implicit") {
-    const { getLoadedChannelPluginForRead, mapAllowFromEntries } =
-      await loadDeliveryTargetRuntime();
+    const { getLoadedChannelPluginForRead, mapAllowFromEntries } = deliveryTargetRuntime;
     const channelPlugin = getLoadedChannelPluginForRead(channel);
     const resolvedAccountId = normalizeAccountId(accountId);
     const configuredAllowFromRaw = channelPlugin?.config.resolveAllowFrom?.({
diff --git a/src/infra/outbound/targets-session.ts b/src/infra/outbound/targets-session.ts
@@ -1,10 +1,11 @@
-import {
-  parseExplicitTargetForLoadedChannel,
-  resolveRouteTargetForLoadedChannel,
-} from "../../channels/plugins/target-parsing-loaded.js";
+import { parseExplicitTargetForLoadedChannel } from "../../channels/plugins/target-parsing-loaded.js";
 import type { ChannelOutboundTargetMode } from "../../channels/plugins/types.public.js";
 import type { SessionEntry } from "../../config/sessions.js";
-import { channelRouteTargetsShareConversation } from "../../plugin-sdk/channel-route.js";
+import {
+  type ChannelRouteExplicitTargetParser,
+  channelRouteTargetsShareConversation,
+  resolveChannelRouteTargetWithParser,
+} from "../../plugin-sdk/channel-route.js";
 import { deliveryContextFromSession } from "../../utils/delivery-context.shared.js";
 import {
   isDeliverableMessageChannel,
@@ -30,10 +31,25 @@ export type SessionDeliveryTarget = {
   lastThreadId?: string | number;
 };
 
-function parseExplicitTargetWithPlugin(params: {
+export type ExplicitTargetParser = ChannelRouteExplicitTargetParser;
+
+function resolveParsedRouteTarget(params: {
+  channel: string;
+  rawTarget?: string | null;
+  fallbackThreadId?: string | number | null;
+  parseExplicitTarget?: ExplicitTargetParser;
+}) {
+  return resolveChannelRouteTargetWithParser({
+    ...params,
+    parseExplicitTarget: params.parseExplicitTarget ?? parseExplicitTargetForLoadedChannel,
+  });
+}
+
+function parseExplicitDeliveryTarget(params: {
   channel?: DeliverableMessageChannel;
   fallbackChannel?: DeliverableMessageChannel;
   raw?: string;
+  parseExplicitTarget?: ExplicitTargetParser;
 }) {
   const raw = params.raw?.trim();
   if (!raw) {
@@ -43,7 +59,7 @@ function parseExplicitTargetWithPlugin(params: {
   if (!provider) {
     return null;
   }
-  return parseExplicitTargetForLoadedChannel(provider, raw);
+  return (params.parseExplicitTarget ?? parseExplicitTargetForLoadedChannel)(provider, raw);
 }
 
 export function resolveSessionDeliveryTarget(params: {
@@ -64,25 +80,28 @@ export function resolveSessionDeliveryTarget(params: {
   turnSourceTo?: string;
   turnSourceAccountId?: string;
   turnSourceThreadId?: string | number;
+  parseExplicitTarget?: ExplicitTargetParser;
 }): SessionDeliveryTarget {
   const context = deliveryContextFromSession(params.entry);
   const sessionLastChannel =
     context?.channel && isDeliverableMessageChannel(context.channel) ? context.channel : undefined;
   const parsedSessionTarget = sessionLastChannel
-    ? resolveRouteTargetForLoadedChannel({
+    ? resolveParsedRouteTarget({
         channel: sessionLastChannel,
         rawTarget: context?.to,
         fallbackThreadId: context?.threadId,
+        parseExplicitTarget: params.parseExplicitTarget,
       })
     : null;
 
   const hasTurnSourceChannel = params.turnSourceChannel != null;
   const parsedTurnSourceTarget =
     hasTurnSourceChannel && params.turnSourceChannel
-      ? resolveRouteTargetForLoadedChannel({
+      ? resolveParsedRouteTarget({
           channel: params.turnSourceChannel,
           rawTarget: params.turnSourceTo,
           fallbackThreadId: params.turnSourceThreadId,
+          parseExplicitTarget: params.parseExplicitTarget,
         })
       : null;
   const hasTurnSourceThreadId = parsedTurnSourceTarget?.threadId != null;
@@ -131,10 +150,11 @@ export function resolveSessionDeliveryTarget(params: {
   }
 
   let explicitTo = rawExplicitTo;
-  const parsedExplicitTarget = parseExplicitTargetWithPlugin({
+  const parsedExplicitTarget = parseExplicitDeliveryTarget({
     channel,
     fallbackChannel: !channel ? lastChannel : undefined,
     raw: rawExplicitTo,
+    parseExplicitTarget: params.parseExplicitTarget,
   });
   if (parsedExplicitTarget?.to) {
     explicitTo = parsedExplicitTarget.to;
diff --git a/src/infra/outbound/targets.test-helpers.ts b/src/infra/outbound/targets.test-helpers.ts
@@ -62,8 +62,13 @@ function parseTelegramTargetForTest(raw: string): {
   const trimmed = raw.trim();
   const withoutPrefix = trimmed.replace(/^telegram:/i, "").trim();
   const topicMatch = withoutPrefix.match(/^(.*):topic:(\d+)$/i);
-  const chatId = topicMatch?.[1]?.trim() || withoutPrefix;
-  const messageThreadId = topicMatch?.[2] ? Number.parseInt(topicMatch[2], 10) : undefined;
+  const colonMatch = withoutPrefix.match(/^(-?\d+):(\d+)$/i);
+  const chatId = topicMatch?.[1]?.trim() || colonMatch?.[1] || withoutPrefix;
+  const messageThreadId = topicMatch?.[2]
+    ? Number.parseInt(topicMatch[2], 10)
+    : colonMatch?.[2]
+      ? Number.parseInt(colonMatch[2], 10)
+      : undefined;
   const numericId = chatId.startsWith("-") ? chatId.slice(1) : chatId;
   const chatType =
     /^\d+$/.test(numericId) && !chatId.startsWith("-100")
