docs: deprecate legacy session file helpers (#97494)

* docs: deprecate legacy session file helpers

* docs: update sdk deprecation budgets

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,

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";

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,