refactor: use transcript locator sdk helper

docs/plugins/sdk-migration.md

@@ -563,7 +563,7 @@ releases.
   | `plugin-sdk/reply-history` | Reply-history helpers | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
   | `plugin-sdk/reply-reference` | Reply reference planning | `createReplyReferencePlanner` |
   | `plugin-sdk/reply-chunking` | Reply chunk helpers | Text/markdown chunking helpers |
-  | `plugin-sdk/session-store-runtime` | Session row helpers | SQLite-backed session row, session-key, updated-at, and transcript path helpers |
+  | `plugin-sdk/session-store-runtime` | Session row helpers | SQLite-backed session row, session-key, updated-at, and transcript locator helpers |
   | `plugin-sdk/state-paths` | State path helpers | State and OAuth dir helpers |
   | `plugin-sdk/routing` | Routing/session-key helpers | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, session-key normalization helpers |
   | `plugin-sdk/status-helpers` | Channel status helpers | Channel/account status summary builders, runtime-state defaults, issue metadata helpers |

docs/plugins/sdk-subpaths.md

@@ -201,7 +201,7 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview)
     | `plugin-sdk/reply-history` | Shared short-window reply-history helpers and markers such as `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry`, and `clearHistoryEntriesIfEnabled` |
     | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
     | `plugin-sdk/reply-chunking` | Narrow text/markdown chunking helpers |
-    | `plugin-sdk/session-store-runtime` | SQLite-backed session row, session-key, updated-at, and transcript path helpers |
+    | `plugin-sdk/session-store-runtime` | SQLite-backed session row, session-key, updated-at, and transcript locator helpers |
     | `plugin-sdk/cron-store-runtime` | SQLite cron store key/load/save helpers |
     | `plugin-sdk/state-paths` | State/OAuth dir path helpers |
     | `plugin-sdk/routing` | Route/session-key/account binding helpers such as `resolveAgentRoute`, `buildAgentSessionKey`, and `resolveDefaultAgentBoundAccountId` |

extensions/telegram/src/bot-native-commands.session-meta.test.ts

@@ -53,7 +53,7 @@ const sessionMocks = vi.hoisted(() => {
       Object.entries(sessionStore.value).map(([sessionKey, entry]) => ({ sessionKey, entry })),
     ),
     recordSessionMetaFromInbound: vi.fn(),
-    resolveAndPersistSessionFile: vi.fn(),
+    resolveAndPersistSessionTranscriptLocator: vi.fn(),
     sessionStore,
   };
 });
@@ -160,7 +160,8 @@ vi.mock("openclaw/plugin-sdk/session-store-runtime", async () => {
     ...actual,
     getSessionEntry: sessionMocks.getSessionEntry,
     listSessionEntries: sessionMocks.listSessionEntries,
-    resolveAndPersistSessionFile: sessionMocks.resolveAndPersistSessionFile,
+    resolveAndPersistSessionTranscriptLocator:
+      sessionMocks.resolveAndPersistSessionTranscriptLocator,
   };
 });
 vi.mock("openclaw/plugin-sdk/command-auth-native", async () => {
@@ -483,19 +484,21 @@ describe("registerTelegramNativeCommands — session metadata", () => {
       })),
     );
     sessionMocks.recordSessionMetaFromInbound.mockClear().mockResolvedValue(undefined);
-    sessionMocks.resolveAndPersistSessionFile.mockClear().mockImplementation(async (params) => {
-      const sessionFile =
-        params.fallbackSessionFile ?? `/tmp/openclaw-sessions/${params.sessionId}.jsonl`;
-      return {
-        sessionFile,
-        sessionEntry: {
-          ...params.sessionEntry,
-          sessionId: params.sessionId,
-          sessionFile,
-          updatedAt: Date.now(),
-        },
-      };
-    });
+    sessionMocks.resolveAndPersistSessionTranscriptLocator
+      .mockClear()
+      .mockImplementation(async (params) => {
+        const transcriptLocator =
+          params.fallbackTranscriptLocator ?? `/tmp/openclaw-sessions/${params.sessionId}.jsonl`;
+        return {
+          transcriptLocator,
+          sessionEntry: {
+            ...params.sessionEntry,
+            sessionId: params.sessionId,
+            sessionFile: transcriptLocator,
+            updatedAt: Date.now(),
+          },
+        };
+      });
     pluginRuntimeMocks.executePluginCommand.mockClear().mockResolvedValue({ text: "ok" });
     pluginRuntimeMocks.matchPluginCommand.mockClear().mockReturnValue(null);
     replyMocks.dispatchReplyWithBufferedBlockDispatcher
@@ -1197,11 +1200,11 @@ describe("registerTelegramNativeCommands — session metadata", () => {
       createTelegramTopicCommandContext({ match: "bind --cwd /tmp/work", threadId: 42 }),
     );
 
-    expect(sessionMocks.resolveAndPersistSessionFile).toHaveBeenCalledWith(
+    expect(sessionMocks.resolveAndPersistSessionTranscriptLocator).toHaveBeenCalledWith(
       expect.objectContaining({
         sessionId: "sess-topic",
         sessionKey: "agent:main:telegram:group:-1001234567890:topic:42",
-        fallbackSessionFile: "sqlite-transcript://main/sess-topic-topic-42.jsonl",
+        fallbackTranscriptLocator: "sqlite-transcript://main/sess-topic-topic-42.jsonl",
       }),
     );
     expect(pluginRuntimeMocks.executePluginCommand).toHaveBeenCalledWith(

extensions/telegram/src/bot-native-commands.ts

@@ -42,7 +42,7 @@ import {
   createSqliteSessionTranscriptLocator,
   getSessionEntry,
   listSessionEntries,
-  resolveAndPersistSessionFile,
+  resolveAndPersistSessionTranscriptLocator,
   resolveSessionRowEntry,
 } from "openclaw/plugin-sdk/session-store-runtime";
 import {
@@ -168,7 +168,7 @@ function resolveTelegramProgressPlaceholder(command: {
   return text ? text : null;
 }
 
-async function resolveTelegramCommandSessionFile(params: {
+async function resolveTelegramCommandTranscriptLocator(params: {
   cfg: OpenClawConfig;
   agentId: string;
   sessionKey: string;
@@ -185,19 +185,19 @@ async function resolveTelegramCommandSessionFile(params: {
       sessionKey,
     });
     const sessionId = resolved.existing?.sessionId?.trim() || randomUUID();
-    const fallbackSessionFile = createSqliteSessionTranscriptLocator({
+    const fallbackTranscriptLocator = createSqliteSessionTranscriptLocator({
       sessionId,
       agentId: params.agentId,
       topicId: params.threadId,
     });
-    const persisted = await resolveAndPersistSessionFile({
+    const persisted = await resolveAndPersistSessionTranscriptLocator({
       sessionId,
       sessionKey: resolved.normalizedKey,
       sessionEntry: resolved.existing,
       agentId: params.agentId,
-      fallbackSessionFile,
+      fallbackTranscriptLocator,
     });
-    return { sessionId, sessionFile: persisted.sessionFile };
+    return { sessionId, sessionFile: persisted.transcriptLocator };
   } catch {
     return {};
   }
@@ -1332,7 +1332,7 @@ export const registerTelegramNativeCommands = ({
           } catch {}
         }
 
-        const sessionFileContext = await resolveTelegramCommandSessionFile({
+        const sessionFileContext = await resolveTelegramCommandTranscriptLocator({
           cfg: runtimeCfg,
           agentId: route.agentId,
           sessionKey: route.sessionKey,

src/auto-reply/reply/commands-export-common.ts

@@ -57,7 +57,7 @@ export function resolveExportCommandSessionTarget(
     return { agentId: targetAgentId, entry, sessionFile };
   } catch (err) {
     return {
-      text: `❌ Failed to resolve session file: ${formatErrorMessage(err)}`,
+      text: `❌ Failed to resolve session transcript: ${formatErrorMessage(err)}`,
     };
   }
 }

src/commands/export-trajectory.ts

@@ -102,7 +102,7 @@ export async function exportTrajectoryCommand(
       sessionId: entry.sessionId,
     });
   } catch (error) {
-    runtime.error(`Failed to resolve session file: ${formatErrorMessage(error)}`);
+    runtime.error(`Failed to resolve session transcript: ${formatErrorMessage(error)}`);
     runtime.exit(1);
     return;
   }