docs: deprecate legacy session file helpers (#97494)

jalehman · web-flow · commit b5e91790630e · 2026-06-28T07:33:34.000-07:00
* docs: deprecate legacy session file helpers

* docs: update sdk deprecation budgets
diff --git a/docs/plugins/sdk-runtime.md b/docs/plugins/sdk-runtime.md
@@ -131,11 +131,9 @@ two-party event loops that do not go through the shared inbound reply runner.
     await api.runtime.agent.ensureAgentWorkspace(cfg);
 
     // Run an embedded agent turn
-    const agentDir = api.runtime.agent.resolveAgentDir(cfg);
     const result = await api.runtime.agent.runEmbeddedAgent({
       sessionId: "my-plugin:task-1",
       runId: crypto.randomUUID(),
-      sessionFile: path.join(agentDir, "sessions", "my-plugin-task-1.jsonl"),
       workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg),
       prompt: "Summarize the latest changes",
       timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg),
@@ -166,9 +164,9 @@ two-party event loops that do not go through the shared inbound reply runner.
 
     Prefer `getSessionEntry(...)`, `listSessionEntries(...)`, `patchSessionEntry(...)`, or `upsertSessionEntry(...)` for session workflows. These helpers address sessions by agent/session identity so plugins do not depend on the legacy `sessions.json` storage shape. Use `preserveActivity: true` for metadata-only patches that should not refresh session activity, and `replaceEntry: true` only when the callback returns a complete entry and deleted fields must stay deleted.
 
-    For transcript reads and writes, import `openclaw/plugin-sdk/session-transcript-runtime` and use `resolveSessionTranscriptIdentity(...)`, `resolveSessionTranscriptTarget(...)`, `readSessionTranscriptEvents(...)`, `appendSessionTranscriptMessageByIdentity(...)`, `publishSessionTranscriptUpdateByIdentity(...)`, or `withSessionTranscriptWriteLock(...)` with `{ agentId, sessionKey, sessionId }`. These APIs let plugins identify a transcript, read its events, append messages, publish updates, and run related operations under the same transcript write lock. Pass `sessionFile` only when adapting code that already receives an active transcript artifact and needs each helper to operate on that same artifact.
+    For transcript reads and writes, import `openclaw/plugin-sdk/session-transcript-runtime` and use `resolveSessionTranscriptIdentity(...)`, `resolveSessionTranscriptTarget(...)`, `readSessionTranscriptEvents(...)`, `appendSessionTranscriptMessageByIdentity(...)`, `publishSessionTranscriptUpdateByIdentity(...)`, or `withSessionTranscriptWriteLock(...)` with `{ agentId, sessionKey, sessionId }`. These APIs let plugins identify a transcript, read its events, append messages, publish updates, and run related operations under the same transcript write lock. Passing `sessionFile`, using `resolveSessionTranscriptLegacyFileTarget(...)`, or importing low-level `appendSessionTranscriptMessage(...)` / `emitSessionTranscriptUpdate(...)` from `openclaw/plugin-sdk/agent-harness-runtime` is deprecated; those paths exist only for legacy code that already receives an active transcript artifact.
 
-    `loadSessionStore(...)`, `saveSessionStore(...)`, `updateSessionStore(...)`, and `resolveSessionFilePath(...)` are compatibility helpers for plugins that still intentionally depend on the legacy whole-store or transcript-file shape. New plugin code must not use those helpers, and existing callers should migrate to entry helpers.
+    `loadSessionStore(...)`, `saveSessionStore(...)`, `updateSessionStore(...)`, `resolveSessionFilePath(...)`, and `resolveAndPersistSessionFile(...)` are deprecated compatibility helpers for plugins that still intentionally depend on the legacy whole-store or transcript-file shape. New plugin code must not use those helpers, and existing callers should migrate to entry helpers and transcript identity helpers.
 
   </Accordion>
   <Accordion title="api.runtime.agent.defaults">
diff --git a/scripts/plugin-sdk-surface-report.mjs b/scripts/plugin-sdk-surface-report.mjs
@@ -164,7 +164,7 @@ const defaultPublicDeprecatedExportsByEntrypointBudget = Object.freeze({
   "channel-policy": 8,
   "channel-route": 5,
   "session-store-runtime": 1,
-  "session-transcript-runtime": 1,
+  "session-transcript-runtime": 2,
   "group-access": 13,
   "media-generation-runtime-shared": 3,
   "music-generation-core": 20,
@@ -206,7 +206,7 @@ try {
     publicFunctionExports: readBudgetEnv("OPENCLAW_PLUGIN_SDK_MAX_PUBLIC_FUNCTION_EXPORTS", 5214),
     publicDeprecatedExports: readBudgetEnv(
       "OPENCLAW_PLUGIN_SDK_MAX_PUBLIC_DEPRECATED_EXPORTS",
-      3247,
+      3249,
     ),
     publicWildcardReexports: readBudgetEnv(
       "OPENCLAW_PLUGIN_SDK_MAX_PUBLIC_WILDCARD_REEXPORTS",
diff --git a/src/plugin-sdk/agent-harness-runtime.ts b/src/plugin-sdk/agent-harness-runtime.ts
@@ -286,7 +286,17 @@ export {
   resolveSessionWriteLockOptions,
   type SessionWriteLockAcquireTimeoutConfig,
 } from "../agents/session-write-lock.js";
+/**
+ * @deprecated Use appendSessionTranscriptMessageByIdentity from
+ * openclaw/plugin-sdk/session-transcript-runtime so transcript writes target a
+ * session identity instead of an active JSONL transcript file.
+ */
 export { appendSessionTranscriptMessage } from "../config/sessions/transcript-append.js";
+/**
+ * @deprecated Use publishSessionTranscriptUpdateByIdentity from
+ * openclaw/plugin-sdk/session-transcript-runtime so transcript updates target
+ * a session identity instead of an active JSONL transcript file.
+ */
 export { emitSessionTranscriptUpdate } from "../sessions/transcript-events.js";
 export {
   consumeAdjustedParamsForToolCall,
diff --git a/src/plugin-sdk/config-runtime.ts b/src/plugin-sdk/config-runtime.ts
@@ -151,8 +151,18 @@ export type {
 export {
   clearSessionStoreCacheForTest,
   recordSessionMetaFromInbound,
+  /**
+   * @deprecated Use patchSessionEntry/upsertSessionEntry for writes. This
+   * whole-store helper is kept only during the transition before SQLite
+   * migration. Callers must migrate away from writing sessions.json directly.
+   */
   saveSessionStore,
   updateLastRoute,
+  /**
+   * @deprecated Use patchSessionEntry/upsertSessionEntry for writes. This
+   * whole-store helper is kept only during the transition before SQLite
+   * migration. Callers must migrate away from updating sessions.json directly.
+   */
   updateSessionStore,
   resolveSessionStoreEntry,
 } from "../config/sessions/store.js";
diff --git a/src/plugin-sdk/session-transcript-runtime.ts b/src/plugin-sdk/session-transcript-runtime.ts
@@ -60,11 +60,13 @@ export type SessionTranscriptTarget = SessionTranscriptIdentity & {
   targetKind: "active-session-file" | "runtime-session";
 };
 
+/**
+ * @deprecated Use SessionTranscriptTarget with `{ agentId, sessionKey,
+ * sessionId }`. Active transcript file targets are transitional only and will
+ * be removed with the SQLite session/transcript storage flip.
+ */
 export type SessionTranscriptLegacyFileTarget = SessionTranscriptTarget & {
-  /**
-   * Deprecated transitional file target for callers that still pass active
-   * transcript files to plugin command handlers.
-   */
+  /** Deprecated transitional file path for active transcript artifact callers. */
   sessionFile: string;
 };
 
@@ -124,8 +126,9 @@ export async function resolveSessionTranscriptTarget(
 }
 
 /**
- * Resolves and persists the current file-backed target for legacy plugin
- * command calls that still require `sessionFile`.
+ * @deprecated Use resolveSessionTranscriptTarget with `{ agentId, sessionKey,
+ * sessionId }`. This persists an active transcript file target only for legacy
+ * plugin command calls that still require `sessionFile`.
  */
 export async function resolveSessionTranscriptLegacyFileTarget(
   params: SessionTranscriptTargetParams,
