fix(telegram): migrate legacy cache sidecars

extensions/telegram/src/bot-info-cache.ts

@@ -1,9 +1,14 @@
+import os from "node:os";
+import path from "node:path";
+import { readJsonFileWithFallback } from "openclaw/plugin-sdk/json-store";
+import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
 import { normalizeTelegramBotInfo, type TelegramBotInfo } from "./bot-info.js";
 import { getTelegramRuntime } from "./runtime.js";
 import { fingerprintTelegramBotToken } from "./token-fingerprint.js";
 
-const STORE_NAMESPACE = "telegram.bot-info-cache";
-const STORE_MAX_ENTRIES = 128;
+const LEGACY_STORE_VERSION = 1;
+export const TELEGRAM_BOT_INFO_CACHE_NAMESPACE = "telegram.bot-info-cache";
+export const TELEGRAM_BOT_INFO_CACHE_MAX_ENTRIES = 128;
 export const TELEGRAM_BOT_INFO_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 
 type TelegramBotInfoCacheState = {
@@ -41,32 +46,59 @@ function fingerprintFromToken(botToken?: string): string | null {
   return fingerprintTelegramBotToken(trimmed);
 }
 
+export function resolveTelegramBotInfoCachePath(
+  accountId?: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const stateDir = resolveStateDir(env, os.homedir);
+  return path.join(stateDir, "telegram", `bot-info-${normalizeAccountId(accountId)}.json`);
+}
+
 function openBotInfoCacheStore(): TelegramBotInfoCacheStore {
   return (
     botInfoCacheStoreForTest ??
     getTelegramRuntime().state.openKeyedStore<TelegramBotInfoCacheState>({
-      namespace: STORE_NAMESPACE,
-      maxEntries: STORE_MAX_ENTRIES,
+      namespace: TELEGRAM_BOT_INFO_CACHE_NAMESPACE,
+      maxEntries: TELEGRAM_BOT_INFO_CACHE_MAX_ENTRIES,
       defaultTtlMs: TELEGRAM_BOT_INFO_CACHE_MAX_AGE_MS,
     })
   );
 }
 
-function parseCachedTelegramBotInfo(value: TelegramBotInfoCacheState | undefined) {
-  if (!value || Number.isNaN(Date.parse(value.fetchedAt))) {
+function parseCachedTelegramBotInfo(value: unknown) {
+  if (!value || typeof value !== "object") {
     return null;
   }
-  const botInfo = normalizeTelegramBotInfo(value.botInfo);
+  const state = value as Partial<TelegramBotInfoCacheState>;
+  if (
+    typeof state.tokenFingerprint !== "string" ||
+    typeof state.fetchedAt !== "string" ||
+    Number.isNaN(Date.parse(state.fetchedAt))
+  ) {
+    return null;
+  }
+  const botInfo = normalizeTelegramBotInfo(state.botInfo);
   if (!botInfo) {
     return null;
   }
   return {
-    tokenFingerprint: value.tokenFingerprint,
-    fetchedAt: value.fetchedAt,
+    tokenFingerprint: state.tokenFingerprint,
+    fetchedAt: state.fetchedAt,
     botInfo,
   };
 }
 
+function parseLegacyCachedTelegramBotInfo(value: unknown) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const state = value as { version?: unknown };
+  if (state.version !== LEGACY_STORE_VERSION) {
+    return null;
+  }
+  return parseCachedTelegramBotInfo(value);
+}
+
 export async function readCachedTelegramBotInfo(params: {
   accountId?: string;
   botToken?: string;
@@ -119,3 +151,15 @@ export function setTelegramBotInfoCacheStoreForTest(
 ): void {
   botInfoCacheStoreForTest = store;
 }
+
+export async function listTelegramLegacyBotInfoCacheEntries(params: {
+  accountId?: string;
+  persistedPath: string;
+}): Promise<Array<{ key: string; value: TelegramBotInfoCacheState }>> {
+  const { value } = await readJsonFileWithFallback<unknown>(params.persistedPath, null);
+  const parsed = parseLegacyCachedTelegramBotInfo(value);
+  if (!parsed) {
+    return [];
+  }
+  return [{ key: normalizeAccountId(params.accountId), value: parsed }];
+}

extensions/telegram/src/state-migrations.test.ts

@@ -5,8 +5,14 @@ import type { Message } from "grammy/types";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
 import { resolveStorePath } from "openclaw/plugin-sdk/session-store-runtime";
 import { describe, expect, it } from "vitest";
+import { resolveTelegramBotInfoCachePath } from "./bot-info-cache.js";
 import { resolveTelegramMessageCachePath } from "./message-cache.js";
 import { detectTelegramLegacyStateMigrations } from "./state-migrations.js";
+import {
+  resolveTopicNameCacheNamespace,
+  resolveTopicNameCachePath,
+  resolveTopicNameCacheScope,
+} from "./topic-name-cache.js";
 
 type PersistedCacheEntry = {
   key: string;
@@ -31,6 +37,74 @@ function persistedCacheEntry(messageId: number, text: string): PersistedCacheEnt
 }
 
 describe("telegram state migrations", () => {
+  it("detects legacy bot-info cache import", async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "openclaw-telegram-state-migration-"));
+    const env = { ...process.env, OPENCLAW_STATE_DIR: dir };
+    const persistedPath = resolveTelegramBotInfoCachePath("ops", env);
+    try {
+      await mkdir(path.dirname(persistedPath), { recursive: true });
+      await writeFile(
+        persistedPath,
+        JSON.stringify({
+          version: 1,
+          tokenFingerprint: "token:fingerprint",
+          fetchedAt: "2026-05-24T11:00:00.000Z",
+          botInfo: {
+            id: 123456,
+            is_bot: true,
+            first_name: "OpenClaw",
+            username: "openclaw_bot",
+          },
+        }),
+      );
+
+      const cfg = {
+        channels: {
+          telegram: {
+            accounts: {
+              ops: {
+                botToken: "123456:secret",
+              },
+            },
+          },
+        },
+      } as OpenClawConfig;
+      const plans = await detectTelegramLegacyStateMigrations({ cfg, env });
+      const botInfoPlan = plans.find(
+        (plan) =>
+          plan.kind === "plugin-state-import" && plan.label === "Telegram startup bot info cache",
+      );
+
+      expect(botInfoPlan).toMatchObject({
+        kind: "plugin-state-import",
+        sourcePath: persistedPath,
+        targetPath: "plugin state:telegram.bot-info-cache",
+        pluginId: "telegram",
+        namespace: "telegram.bot-info-cache",
+        scopeKey: "",
+      });
+      if (!botInfoPlan || botInfoPlan.kind !== "plugin-state-import") {
+        throw new Error("expected Telegram bot-info plugin-state import plan");
+      }
+
+      const entries = await botInfoPlan.readEntries();
+      expect(entries).toHaveLength(1);
+      expect(entries[0]).toMatchObject({
+        key: "ops",
+        value: {
+          tokenFingerprint: "token:fingerprint",
+          fetchedAt: "2026-05-24T11:00:00.000Z",
+          botInfo: {
+            id: 123456,
+            username: "openclaw_bot",
+          },
+        },
+      });
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
   it("detects legacy message-cache import for the runtime sidecar path", async () => {
     const dir = await mkdtemp(path.join(os.tmpdir(), "openclaw-telegram-state-migration-"));
     const env = { ...process.env, OPENCLAW_STATE_DIR: dir };
@@ -73,4 +147,62 @@ describe("telegram state migrations", () => {
       await rm(dir, { recursive: true, force: true });
     }
   });
+
+  it("detects legacy topic-name cache import for the runtime sidecar path", async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "openclaw-telegram-state-migration-"));
+    const env = { ...process.env, OPENCLAW_STATE_DIR: dir };
+    const storePath = resolveStorePath(undefined, { env });
+    const persistedPath = resolveTopicNameCachePath(storePath);
+    const namespace = resolveTopicNameCacheNamespace(resolveTopicNameCacheScope(storePath));
+    try {
+      await mkdir(path.dirname(persistedPath), { recursive: true });
+      await writeFile(
+        persistedPath,
+        JSON.stringify({
+          "7:42": {
+            name: "Deployments",
+            iconColor: 0x6fb9f0,
+            updatedAt: 1736380000,
+          },
+        }),
+      );
+
+      const cfg = {
+        agents: {
+          list: [{ id: "ops", default: true }],
+        },
+      } as OpenClawConfig;
+      const plans = await detectTelegramLegacyStateMigrations({ cfg, env });
+      const topicNamePlan = plans.find(
+        (plan) =>
+          plan.kind === "plugin-state-import" && plan.label === "Telegram forum topic-name cache",
+      );
+
+      expect(topicNamePlan).toMatchObject({
+        kind: "plugin-state-import",
+        sourcePath: persistedPath,
+        targetPath: `plugin state:${namespace}`,
+        pluginId: "telegram",
+        namespace,
+        scopeKey: "",
+      });
+      if (!topicNamePlan || topicNamePlan.kind !== "plugin-state-import") {
+        throw new Error("expected Telegram topic-name plugin-state import plan");
+      }
+
+      const entries = await topicNamePlan.readEntries();
+      expect(entries).toStrictEqual([
+        {
+          key: "7:42",
+          value: {
+            name: "Deployments",
+            iconColor: 0x6fb9f0,
+            updatedAt: 1736380000,
+          },
+        },
+      ]);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
 });

extensions/telegram/src/state-migrations.ts

@@ -4,7 +4,13 @@ import { resolveChannelAllowFromPath } from "openclaw/plugin-sdk/channel-pairing
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
 import { statRegularFileSync } from "openclaw/plugin-sdk/security-runtime";
 import { resolveStorePath } from "openclaw/plugin-sdk/session-store-runtime";
-import { resolveDefaultTelegramAccountId } from "./account-selection.js";
+import { listTelegramAccountIds, resolveDefaultTelegramAccountId } from "./account-selection.js";
+import {
+  listTelegramLegacyBotInfoCacheEntries,
+  resolveTelegramBotInfoCachePath,
+  TELEGRAM_BOT_INFO_CACHE_MAX_ENTRIES,
+  TELEGRAM_BOT_INFO_CACHE_NAMESPACE,
+} from "./bot-info-cache.js";
 import {
   listTelegramLegacyMessageCacheEntries,
   resolveTelegramMessageCachePath,
@@ -12,6 +18,13 @@ import {
   TELEGRAM_MESSAGE_CACHE_PERSISTENT_MAX_MESSAGES,
   TELEGRAM_MESSAGE_CACHE_PERSISTENT_NAMESPACE,
 } from "./message-cache.js";
+import {
+  listTelegramLegacyTopicNameCacheEntries,
+  resolveTopicNameCacheNamespace,
+  resolveTopicNameCachePath,
+  resolveTopicNameCacheScope,
+  TELEGRAM_TOPIC_NAME_CACHE_MAX_ENTRIES,
+} from "./topic-name-cache.js";
 
 function fileExists(pathValue: string): boolean {
   try {
@@ -69,6 +82,73 @@ function detectTelegramMessageCacheLegacyStateMigration(params: {
   });
 }
 
+function detectTelegramBotInfoCacheLegacyStateMigration(params: {
+  cfg: OpenClawConfig;
+  env: NodeJS.ProcessEnv;
+}): ChannelLegacyStateMigrationPlan[] {
+  return listTelegramAccountIds(params.cfg).flatMap((accountId) => {
+    const persistedPath = resolveTelegramBotInfoCachePath(accountId, params.env);
+    if (!fileExists(persistedPath)) {
+      return [];
+    }
+    return {
+      kind: "plugin-state-import",
+      label: "Telegram startup bot info cache",
+      sourcePath: persistedPath,
+      targetPath: `plugin state:${TELEGRAM_BOT_INFO_CACHE_NAMESPACE}`,
+      pluginId: "telegram",
+      namespace: TELEGRAM_BOT_INFO_CACHE_NAMESPACE,
+      maxEntries: TELEGRAM_BOT_INFO_CACHE_MAX_ENTRIES,
+      scopeKey: "",
+      cleanupSource: "rename",
+      preview: `- Telegram startup bot info cache: ${persistedPath} → plugin state (${TELEGRAM_BOT_INFO_CACHE_NAMESPACE})`,
+      readEntries: () => {
+        return listTelegramLegacyBotInfoCacheEntries({
+          accountId,
+          persistedPath,
+        });
+      },
+    };
+  });
+}
+
+function detectTelegramTopicNameCacheLegacyStateMigration(params: {
+  cfg: OpenClawConfig;
+  env: NodeJS.ProcessEnv;
+  stateDir?: string;
+}): ChannelLegacyStateMigrationPlan[] {
+  const storePath = resolveStorePath(params.cfg.session?.store, { env: params.env });
+  const runtimePersistedPath = resolveTopicNameCachePath(storePath);
+  const legacyStorePath = resolveLegacySessionStorePath(params);
+  const legacyPersistedPath = resolveTopicNameCachePath(legacyStorePath);
+  const scope = resolveTopicNameCacheScope(storePath);
+  const namespace = resolveTopicNameCacheNamespace(scope);
+  const sourcePaths = Array.from(new Set([runtimePersistedPath, legacyPersistedPath]));
+  return sourcePaths.flatMap((persistedPath) => {
+    if (!fileExists(persistedPath)) {
+      return [];
+    }
+    return {
+      kind: "plugin-state-import",
+      label: "Telegram forum topic-name cache",
+      sourcePath: persistedPath,
+      targetPath: `plugin state:${namespace}`,
+      pluginId: "telegram",
+      namespace,
+      maxEntries: TELEGRAM_TOPIC_NAME_CACHE_MAX_ENTRIES,
+      scopeKey: "",
+      cleanupSource: "rename",
+      preview: `- Telegram forum topic-name cache: ${persistedPath} → plugin state (${namespace})`,
+      readEntries: () => {
+        return listTelegramLegacyTopicNameCacheEntries({
+          persistedPath,
+          maxEntries: TELEGRAM_TOPIC_NAME_CACHE_MAX_ENTRIES,
+        });
+      },
+    };
+  });
+}
+
 export async function detectTelegramLegacyStateMigrations(params: {
   cfg: OpenClawConfig;
   env: NodeJS.ProcessEnv;
@@ -88,6 +168,8 @@ export async function detectTelegramLegacyStateMigrations(params: {
       });
     }
   }
+  plans.push(...detectTelegramBotInfoCacheLegacyStateMigration(params));
   plans.push(...detectTelegramMessageCacheLegacyStateMigration(params));
+  plans.push(...detectTelegramTopicNameCacheLegacyStateMigration(params));
   return plans;
 }

extensions/telegram/src/topic-name-cache.ts

@@ -1,7 +1,8 @@
 import { createHash } from "node:crypto";
+import { readJsonFileWithFallback } from "openclaw/plugin-sdk/json-store";
 import { getTelegramRuntime } from "./runtime.js";
 
-const MAX_ENTRIES = 2_048;
+export const TELEGRAM_TOPIC_NAME_CACHE_MAX_ENTRIES = 2_048;
 const STORE_NAMESPACE_PREFIX = "telegram.topic-name-cache";
 const TOPIC_NAME_CACHE_STATE_KEY = Symbol.for("openclaw.telegramTopicNameCacheState");
 const DEFAULT_TOPIC_NAME_CACHE_SCOPE = "default";
@@ -70,22 +71,30 @@ function namespaceForScope(scope: string): string {
   return `${STORE_NAMESPACE_PREFIX}.${hash}`;
 }
 
+export function resolveTopicNameCachePath(storePath: string): string {
+  return `${storePath}.telegram-topic-names.json`;
+}
+
 export function resolveTopicNameCacheScope(storePath: string): string {
   return storePath;
 }
 
+export function resolveTopicNameCacheNamespace(scope: string): string {
+  return namespaceForScope(scope);
+}
+
 function openTopicNamePersistentStore(namespace: string): TopicNamePersistentStore {
   return (
     topicNameStoreFactoryForTest?.(namespace) ??
     getTelegramRuntime().state.openKeyedStore<TopicEntry>({
       namespace,
-      maxEntries: MAX_ENTRIES,
+      maxEntries: TELEGRAM_TOPIC_NAME_CACHE_MAX_ENTRIES,
     })
   );
 }
 
 function evictOldest(store: TopicNameStore): string | undefined {
-  if (store.size <= MAX_ENTRIES) {
+  if (store.size <= TELEGRAM_TOPIC_NAME_CACHE_MAX_ENTRIES) {
     return undefined;
   }
   let oldestKey: string | undefined;
@@ -221,6 +230,21 @@ export async function getTopicEntry(
   return (await getTopicStore(scope)).get(cacheKey(chatId, threadId));
 }
 
+export async function listTelegramLegacyTopicNameCacheEntries(params: {
+  persistedPath: string;
+  maxEntries?: number;
+}): Promise<Array<{ key: string; value: TopicEntry }>> {
+  const { value } = await readJsonFileWithFallback<Record<string, unknown>>(
+    params.persistedPath,
+    {},
+  );
+  return Object.entries(value)
+    .filter((entry): entry is [string, TopicEntry] => isTopicEntry(entry[1]))
+    .toSorted(([, left], [, right]) => right.updatedAt - left.updatedAt)
+    .slice(0, params.maxEntries ?? TELEGRAM_TOPIC_NAME_CACHE_MAX_ENTRIES)
+    .map(([key, entry]) => ({ key, value: entry }));
+}
+
 export async function clearTopicNameCache(): Promise<void> {
   const state = getTopicNameCacheState();
   await Promise.all(

src/commands/doctor-state-migrations.test.ts

@@ -619,7 +619,9 @@ describe("doctor legacy state migrations", () => {
   it("imports plugin-state legacy plans through doctor", async () => {
     const root = await makeTempRoot();
     const sourcePath = path.join(root, "legacy-cache.json");
+    const globalSourcePath = path.join(root, "legacy-global-cache.json");
     fs.writeFileSync(sourcePath, "legacy", "utf-8");
+    fs.writeFileSync(globalSourcePath, "global", "utf-8");
     mockedChannelMigrationPlans.plans = [
       {
         kind: "plugin-state-import",
@@ -637,6 +639,18 @@ describe("doctor legacy state migrations", () => {
           { key: "overflow", value: { body: "overflow" } },
         ],
       },
+      {
+        kind: "plugin-state-import",
+        label: "Test global cache",
+        sourcePath: globalSourcePath,
+        targetPath: "plugin state:test.global-cache",
+        pluginId: "telegram",
+        namespace: "test.global-cache",
+        maxEntries: 4,
+        scopeKey: "",
+        cleanupSource: "rename",
+        readEntries: () => [{ key: "default", value: { body: "global" } }],
+      },
     ];
 
     await withStateDir(root, async () => {
@@ -657,11 +671,17 @@ describe("doctor legacy state migrations", () => {
 
     expect(result.warnings).toStrictEqual([]);
     expect(result.changes).toContain("Migrated 2 Test prompt-context cache entries → plugin state");
+    expect(result.changes).toContain("Migrated 1 Test global cache entry → plugin state");
     expect(result.changes).toContain(
       `Archived Test prompt-context cache legacy source → ${sourcePath}.migrated`,
     );
+    expect(result.changes).toContain(
+      `Archived Test global cache legacy source → ${globalSourcePath}.migrated`,
+    );
     expect(fs.existsSync(sourcePath)).toBe(false);
     expect(fs.existsSync(`${sourcePath}.migrated`)).toBe(true);
+    expect(fs.existsSync(globalSourcePath)).toBe(false);
+    expect(fs.existsSync(`${globalSourcePath}.migrated`)).toBe(true);
 
     await withStateDir(root, async () => {
       const store = createPluginStateKeyedStore<{ body: string }>("telegram", {
@@ -677,6 +697,17 @@ describe("doctor legacy state migrations", () => {
         "scope:old": "old",
         "scope:overflow": "overflow",
       });
+
+      const globalStore = createPluginStateKeyedStore<{ body: string }>("telegram", {
+        namespace: "test.global-cache",
+        maxEntries: 4,
+      });
+      const globalValuesByKey = new Map(
+        (await globalStore.entries()).map(({ key, value }) => [key, value.body]),
+      );
+      expect(Object.fromEntries(globalValuesByKey)).toEqual({
+        default: "global",
+      });
     });
   });
 

src/infra/state-migrations.ts

@@ -122,6 +122,10 @@ function buildLegacyMigrationPreview(plan: ChannelLegacyStateMigrationPlan): str
   return `- ${plan.label}: ${plan.sourcePath} → ${plan.targetPath}`;
 }
 
+function resolvePluginStateImportTargetKey(scopeKey: string, key: string): string {
+  return scopeKey ? `${scopeKey}:${key}` : key;
+}
+
 async function withPluginStateImportEnv<T>(
   plan: Extract<ChannelLegacyStateMigrationPlan, { kind: "plugin-state-import" }>,
   run: () => Promise<T>,
@@ -168,7 +172,7 @@ async function runLegacyMigrationPlans(
         const entries = await plan.readEntries();
         let imported = 0;
         for (const entry of entries) {
-          const targetKey = `${plan.scopeKey}:${entry.key}`;
+          const targetKey = resolvePluginStateImportTargetKey(plan.scopeKey, entry.key);
           if (existingKeys.has(targetKey)) {
             continue;
           }
@@ -191,7 +195,9 @@ async function runLegacyMigrationPlans(
         }
         const allEntriesCovered =
           entries.length > 0 &&
-          entries.every(({ key }) => existingKeys.has(`${plan.scopeKey}:${key}`));
+          entries.every(({ key }) =>
+            existingKeys.has(resolvePluginStateImportTargetKey(plan.scopeKey, key)),
+          );
         if (allEntriesCovered && plan.cleanupSource === "rename" && fileExists(plan.sourcePath)) {
           const archivedPath = `${plan.sourcePath}.migrated`;
           if (fileExists(archivedPath)) {