Awaited transcript and TTS helpers

Historical transcript keys

Use resolveTranscriptSessionKeyBySessionIdAsync from openclaw/plugin-sdk/session-store-runtime to find the session key that owns an exact transcript identity:

import { resolveTranscriptSessionKeyBySessionIdAsync } from "openclaw/plugin-sdk/session-store-runtime"; const sessionKey = await resolveTranscriptSessionKeyBySessionIdAsync({  agentId,  sessionId,  storePath,});

It returns Promise<string | undefined> and accepts the same agentId, env, sessionId, and storePath fields as the synchronous helper. Pass storePath when the transcript belongs to a configured or shared store. An absent database or unknown identity returns undefined without creating a database.

The lookup includes retained historical transcript windows after the current session has reset to a new identity. getSessionEntryByIdAsync reads current session entries and is not a substitute for this historical lookup. The helper resolves ownership; callers still enforce their existing authorization before disclosing transcript contents.

The synchronous resolveTranscriptSessionKeyBySessionId remains available as a deprecated adapter. Calls emit a bounded warning directing authors to the awaited replacement.

TTS prompts

For one prompt, await the public api.runtime.tts.buildSystemPromptHintAsync method. Older hosts may lack this additive capability; report an upgrade requirement rather than falling back to a synchronous database read:

const prepareHint = api.runtime.tts.buildSystemPromptHintAsync;if (!prepareHint) {  throw new Error("Update OpenClaw to use async TTS prompt preparation.");} const hint = await prepareHint(config, agentId, {  messageToolOnly: true,});

The result remains string | undefined: disabled TTS produces no hint. The helper prepares the machine-owned preference path through the state owner and preserves explicit configuration and OPENCLAW_TTS_PREFS precedence.

The openclaw/plugin-sdk/tts-runtime subpath is private to bundled plugins. Bundled code that needs several TTS helpers in one turn can prepare once and pass the result to each call. Its synchronous overloads with required preparedTtsPreferences remain supported:

import {  buildTtsSystemPromptHint,  prepareTtsPreferences,  resolveTtsConfig,  resolveTtsPrefsPath,} from "openclaw/plugin-sdk/tts-runtime"; const preparedTtsPreferences = await prepareTtsPreferences();const prefsPath = resolveTtsPrefsPath(resolveTtsConfig(config, agentId), preparedTtsPreferences);const hint = buildTtsSystemPromptHint(config, agentId, {  messageToolOnly: true,  preparedTtsPreferences,});

PreparedTtsPreferences is a private readonly type. Treat the returned value as a turn-scoped preparation and obtain a new one for the next turn. It retains the selected machine path, while preference-file contents are read when each helper runs. A committed in-process path change is visible to the next preparation.

The unprepared synchronous overloads of resolveTtsPrefsPath and buildTtsSystemPromptHint retain their existing return values and behavior but are deprecated. Use their awaited replacements, or supply the preparation above, to avoid synchronous state-database reads and deprecation warnings.

Removal timing

These deprecated adapters remain supported through 2026-12-31, the final compatibility day. Removal ships in the first January 2027 stable release, without a Plugin SDK major version. The prepared SQL-free TTS overloads remain supported. See the complete SQLite migration guide and removal timeline.