Skip to content

Commit 16d684f

Browse files
jalehmanjalehman
committed
docs: clarify session-store deprecation notices
1 parent 278c1f9 commit 16d684f

6 files changed

Lines changed: 53 additions & 30 deletions

File tree

‎docs/plugins/sdk-runtime.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,7 @@ two-party event loops that do not go through the shared inbound reply runner.
166166

167167
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.
168168

169-
`loadSessionStore(...)`, `saveSessionStore(...)`, `updateSessionStore(...)`, and `resolveSessionFilePath(...)` remain deprecated compatibility exports for plugins that still intentionally depend on the legacy whole-store or transcript-file shape. New plugin code should avoid those helpers; the deprecation window ends at the SQLite storage flip, and these file-shaped APIs are removed then.
169+
`loadSessionStore(...)`, `saveSessionStore(...)`, `updateSessionStore(...)`, and `resolveSessionFilePath(...)` are kept only during the transition before SQLite migration 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 must migrate to entry helpers before the SQLite storage flip.
170170

171171
</Accordion>
172172
<Accordion title="api.runtime.agent.defaults">

‎docs/plugins/sdk-subpaths.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -247,7 +247,7 @@ usage endpoint failed or returned no usable usage data.
247247
| `plugin-sdk/reply-history` | Shared short-window reply-history helpers. New message-turn code should use `createChannelHistoryWindow`; lower-level map helpers remain deprecated compatibility exports only |
248248
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
249249
| `plugin-sdk/reply-chunking` | Narrow text/markdown chunking helpers |
250-
| `plugin-sdk/session-store-runtime` | Session workflow helpers (`getSessionEntry`, `listSessionEntries`, `patchSessionEntry`, `upsertSessionEntry`), legacy session store path/session-key helpers, updated-at reads, and deprecated whole-store/file-path compatibility helpers |
250+
| `plugin-sdk/session-store-runtime` | Session workflow helpers (`getSessionEntry`, `listSessionEntries`, `patchSessionEntry`, `upsertSessionEntry`), legacy session store path/session-key helpers, updated-at reads, and transition-only whole-store/file-path compatibility helpers |
251251
| `plugin-sdk/sqlite-runtime` | Focused SQLite agent-schema, path, and transaction helpers for first-party runtime |
252252
| `plugin-sdk/cron-store-runtime` | Cron store path/load/save helpers |
253253
| `plugin-sdk/state-paths` | State/OAuth dir path helpers |

‎src/plugin-sdk/config-runtime.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,9 @@ export {
1616

1717
/**
1818
* @deprecated Use getSessionEntry/listSessionEntries for reads and
19-
* patchSessionEntry/upsertSessionEntry for writes. Whole-store helpers keep
20-
* the legacy mutable sessions.json shape and are compatibility escape hatches.
19+
* patchSessionEntry/upsertSessionEntry for writes. This whole-store helper is
20+
* kept only during the transition before SQLite migration. Callers must
21+
* migrate away from reading sessions.json directly.
2122
*/
2223
export const loadSessionStore = loadSessionStoreImpl;
2324

‎src/plugin-sdk/session-store-runtime.ts‎

Lines changed: 23 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,8 @@ type UpsertSessionEntryParams = SessionStoreReadParams & {
6161
};
6262

6363
function toSessionAccessScope(params: SessionStoreReadParams): SessionAccessScope {
64-
// Preserve the public SDK object-parameter shape while hiding internal seam
65-
// options such as borrowed reads from exported plugin types.
64+
// Maintainer note: keep this adapter narrow so plugin callers retain the
65+
// object-parameter API while internal accessor-only options stay private.
6666
return {
6767
sessionKey: params.sessionKey,
6868
...(params.agentId !== undefined ? { agentId: params.agentId } : {}),
@@ -76,17 +76,18 @@ function toSessionAccessScope(params: SessionStoreReadParams): SessionAccessScop
7676

7777
/**
7878
* @deprecated Use getSessionEntry/listSessionEntries for reads and
79-
* patchSessionEntry/upsertSessionEntry for writes. Whole-store helpers keep
80-
* the legacy mutable sessions.json shape only for pre-SQLite compatibility.
79+
* patchSessionEntry/upsertSessionEntry for writes. This whole-store helper is
80+
* kept only during the transition before SQLite migration. Callers must
81+
* migrate away from reading sessions.json directly.
8182
*/
8283
export const loadSessionStore = loadSessionStoreImpl;
8384

84-
/** Loads one session entry through the accessor seam. */
85+
/** Loads one session entry by agent/session identity. */
8586
export function getSessionEntry(params: SessionStoreReadParams): SessionEntry | undefined {
8687
return loadSessionEntry(toSessionAccessScope(params));
8788
}
8889

89-
/** Lists session entries through the accessor seam. */
90+
/** Lists session entries for one agent. */
9091
export function listSessionEntries(
9192
params: SessionStoreListParams = {},
9293
): SessionStoreEntrySummary[] {
@@ -100,7 +101,7 @@ export function listSessionEntries(
100101
});
101102
}
102103

103-
/** Patches one session entry through the accessor seam. */
104+
/** Patches one session entry by agent/session identity. */
104105
export async function patchSessionEntry(
105106
params: PatchSessionEntryParams,
106107
): Promise<SessionEntry | null> {
@@ -112,12 +113,12 @@ export async function patchSessionEntry(
112113
});
113114
}
114115

115-
/** Reads a session activity timestamp through the accessor seam. */
116+
/** Reads the last activity timestamp for one session entry. */
116117
export function readSessionUpdatedAt(params: ReadSessionUpdatedAtParams): number | undefined {
117118
return readAccessorSessionUpdatedAt(toSessionAccessScope(params));
118119
}
119120

120-
/** Updates an existing session entry through the accessor seam. */
121+
/** Updates an existing session entry by store path and session key. */
121122
export async function updateSessionStoreEntry(
122123
params: UpdateSessionStoreEntryParams,
123124
): Promise<SessionEntry | null> {
@@ -135,7 +136,7 @@ export async function updateSessionStoreEntry(
135136
);
136137
}
137138

138-
/** Replaces or creates one session entry through the accessor seam. */
139+
/** Replaces or creates one session entry by agent/session identity. */
139140
export async function upsertSessionEntry(params: UpsertSessionEntryParams): Promise<void> {
140141
await replaceSessionEntry(toSessionAccessScope(params), params.entry);
141142
}
@@ -144,14 +145,16 @@ export { resolveSessionStoreEntry } from "../config/sessions/store-entry.js";
144145
export { resolveSessionTranscriptPathInDir, resolveStorePath } from "../config/sessions/paths.js";
145146
/**
146147
* @deprecated Use getSessionEntry to read session metadata by agent/session
147-
* identity instead of resolving transcript file paths. This file-shaped API is
148-
* a deprecated pre-SQLite compatibility adapter, not a runtime storage path.
148+
* identity instead of resolving transcript file paths. This file-path helper
149+
* is kept only during the transition before SQLite migration. Callers must
150+
* migrate away from resolving transcript file paths directly.
149151
*/
150152
export { resolveSessionFilePath } from "../config/sessions/paths.js";
151153
/**
152154
* @deprecated Use patchSessionEntry/upsertSessionEntry to persist session
153-
* metadata by agent/session identity. This file-shaped API is a deprecated
154-
* pre-SQLite compatibility adapter, not a runtime storage path.
155+
* metadata by agent/session identity. This file-path helper is kept only during
156+
* the transition before SQLite migration. Callers must migrate away from
157+
* persisting transcript file paths directly.
155158
*/
156159
export { resolveAndPersistSessionFile } from "../config/sessions/session-file.js";
157160
export { readLatestAssistantTextFromSessionTranscript } from "../config/sessions/transcript.js";
@@ -164,14 +167,14 @@ export {
164167
updateLastRoute,
165168
} from "../config/sessions/store.js";
166169
/**
167-
* @deprecated Use patchSessionEntry/upsertSessionEntry for storage-neutral
168-
* writes. Keep this whole-store adapter as one compatibility operation: the
169-
* file backend owns the sessions.json writer, and a future SQLite bridge must
170-
* diff before/after store shapes, apply changed/deleted rows in one write
171-
* transaction, then publish updates after commit. Do not route this through
172-
* independent per-entry accessors or make it a permanent storage path.
170+
* @deprecated Use patchSessionEntry/upsertSessionEntry for writes. These
171+
* whole-store helpers are kept only during the transition before SQLite
172+
* migration. Callers must migrate away from reading or writing sessions.json.
173173
*/
174174
export { saveSessionStore, updateSessionStore } from "../config/sessions/store.js";
175+
// Maintainer note: keep saveSessionStore/updateSessionStore grouped as one
176+
// compatibility operation. A SQLite bridge must diff before/after store shapes,
177+
// apply changed/deleted rows in one write transaction, and publish after commit.
175178
export {
176179
evaluateSessionFreshness,
177180
resolveChannelResetConfig,

‎src/plugins/runtime/runtime-agent.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -130,8 +130,8 @@ async function patchSessionEntry(
130130
async function updateSessionStoreEntry(
131131
params: RuntimeSessionStoreEntryUpdateParams,
132132
): Promise<SessionEntry | null> {
133-
// Preserve the plugin runtime's object-parameter API while routing the
134-
// mutation through the storage-neutral session accessor seam.
133+
// Maintainer note: keep the legacy object-parameter API here, but route
134+
// mutations through the session accessor boundary.
135135
return await updateSessionEntry(
136136
{
137137
sessionKey: params.sessionKey,
@@ -147,8 +147,8 @@ async function updateSessionStoreEntry(
147147
}
148148

149149
async function upsertSessionEntry(params: RuntimeUpsertSessionEntryParams): Promise<void> {
150-
// The public runtime helper historically replaced the full entry. Use the
151-
// replace seam so removed fields do not survive as merge leftovers.
150+
// Maintainer note: this compatibility helper has full-entry replacement
151+
// semantics, so removed fields must not survive as merge leftovers.
152152
await replaceSessionEntry(toSessionAccessScope(params), params.entry);
153153
}
154154

‎src/plugins/runtime/types-core.ts‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -251,15 +251,34 @@ export type PluginRuntimeCore = {
251251
upsertSessionEntry: (params: RuntimeUpsertSessionEntryParams) => Promise<void>;
252252
/**
253253
* @deprecated Use getSessionEntry/listSessionEntries for reads and
254-
* patchSessionEntry/upsertSessionEntry for writes. This keeps the legacy
255-
* mutable whole-store compatibility shape.
254+
* patchSessionEntry/upsertSessionEntry for writes. This whole-store
255+
* helper is kept only during the transition before SQLite migration.
256+
* Callers must migrate away from reading sessions.json directly.
256257
*/
257258
loadSessionStore: typeof import("../../config/sessions/store-load.js").loadSessionStore;
259+
/**
260+
* @deprecated Use patchSessionEntry/upsertSessionEntry for writes. This
261+
* whole-store helper is kept only during the transition before SQLite
262+
* migration. Callers must migrate away from writing sessions.json
263+
* directly.
264+
*/
258265
saveSessionStore: import("../../config/sessions/runtime-types.js").SaveSessionStore;
266+
/**
267+
* @deprecated Use patchSessionEntry/upsertSessionEntry for writes. This
268+
* whole-store helper is kept only during the transition before SQLite
269+
* migration. Callers must migrate away from updating sessions.json
270+
* directly.
271+
*/
259272
updateSessionStore: typeof import("../../config/sessions/store.js").updateSessionStore;
260273
updateSessionStoreEntry: (
261274
params: RuntimeSessionStoreEntryUpdateParams,
262275
) => Promise<RuntimeSessionEntry | null>;
276+
/**
277+
* @deprecated Use getSessionEntry to read session metadata by
278+
* agent/session identity. This file-path helper is kept only during the
279+
* transition before SQLite migration. Callers must migrate away from
280+
* resolving transcript file paths directly.
281+
*/
263282
resolveSessionFilePath: typeof import("../../config/sessions/paths.js").resolveSessionFilePath;
264283
};
265284
};

0 commit comments

Comments
 (0)