diff --git a/docs/plugins/sdk-runtime.md b/docs/plugins/sdk-runtime.md index 23ca19c41c3..4b7fde276a5 100644 --- 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. diff --git a/scripts/plugin-sdk-surface-report.mjs b/scripts/plugin-sdk-surface-report.mjs index 924d74ada0c..f610adee383 100644 --- 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 index 58922e399c5..bf79912788b 100644 --- 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 index 44b823d7829..c291d57a16f 100644 --- 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 index 396aeef9496..f37113c59e3 100644 --- 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,