Migrate synchronous SQLite APIs

Migrate synchronous SQLite SDK calls to the awaited or prepared replacements below. The final compatibility day is December 31, 2026 (2026-12-31). Removal ships in the first January 2027 stable release, without a Plugin SDK major version. This deprecation release retains the listed contracts; it does not remove them. See the removal timeline for the release and shipped-surface gates.

Start with the families your plugin uses. For direct Async replacements, keep the arguments and await the result. Factories that return adapters or prepared readers may remain synchronous: await the operations on the returned object as described below. A Promise-returning wrapper around a native database callback still runs that callback on the caller's thread; migrate the callback contract, not just its call site.

These changes preserve stored data, schemas, retention, and update behavior. Await a write before reading its result or publishing an external effect. Never retry a failed awaited operation through a deprecated synchronous path. Bundled plugins target the current host and do not need older-host fallbacks. External plugins should declare the host version that supplies the capabilities they use.

Session reads and inbound envelopes

Use session-store-runtime for session readers and channel-inbound for prepared envelope construction. The same method mapping applies to api.runtime.agent.session and channel runtime aliases.

// Beforeconst entry = api.runtime.agent.session.getSessionEntry(target);// Afterconst entry = await api.runtime.agent.session.getSessionEntryAsync(target);

The historical transcript-key resolver includes retained session_windows after a session resets. getSessionEntryByIdAsync(...).sessionKey is not a replacement for historical lookup. See the exact historical lookup contract.

Prepare the envelope builder once per inbound message. It returns a synchronous formatter yielding the body string; the older generic builder returned { storePath, body }. If the caller still needs a store path, resolve it from the same configured store and route through runtime.channel.session.resolveStorePath. For custom formatting, await readSessionUpdatedAtAsync once and pass that timestamp into the formatter instead of retaining a database-reading callback.

listSessionEntriesAsync returns a read-only metadata projection, not detached snapshots such as saved skill prompts. It does not take the synchronous listing's readOnly, snapshot-hydration, or source-capture options. Use getSessionEntryAsync for a full public entry. Keep authorization for transcript or metadata disclosure at the existing effect boundary. Memory statistics and archive readers remain on their existing documented or local subpaths; this migration does not make private host facades public.

For entry writes, replace opaque callbacks with owner preparation or an already-prepared patch:

// Before: a callback depends on the stored entry.await patchSessionEntry({ ...target, update: choosePatch });// After: preparation happens outside the transaction; the owner detects conflicts.await prepareSessionEntryPatch({ ...target, prepare: choosePatch });

See entry patch conflicts and authority when translating transaction-local callback behavior.

Auth profiles and provider readiness

Use the public provider-auth surface for profile stores and writes. Bundled plugins also use the private provider-auth-runtime surface for profile metadata and agent-sessions for AuthStorage and ModelRegistry. Existing agent-runtime and runtime modelAuth aliases follow the same mapping; prefer the focused public subpath when one exists.

// Beforeconst auth = AuthStorage.forAgent(agentDir, config);auth.set(providerId, credential);// Afterconst auth = await AuthStorage.forAgentAsync(agentDir, config);await auth.setAsync(providerId, credential);

Harnesses should consume the host-prepared params.authStorage. AuthStorage get, list, and has remain synchronous reads of its prepared view; login and getApiKey already return promises. Do not replace a newer whole auth store with a previously loaded snapshot: use updateAuthProfileStoreWithLock for owner-backed mutation.

Physical database-path displays are retired after 2026-12-31. External plugins should display provider/profile identifiers; there is no public async API for the selected database path. The private bundled-plugin helper AuthStorage.resolvePathForDisplayAsync preserves agent-local-versus-shared database selection, including locators for profiles that do not exist yet. Metadata helpers return profile/account identities and are not path substitutes.

Provider readiness hooks add an awaited callback:

// BeforeisConfigured: (context) => isProviderApiKeyConfigured(context),// After// Preserve synchronous SDK callers through 2026-12-31.isConfigured: (context) => isProviderApiKeyConfigured(context),isConfiguredAsync: async (context) => await isProviderApiKeyConfiguredAsync(context),

Use the hook's existing context and provider-specific inputs. The host awaits readiness and prefers the async hook; a failed async hook is not retried through the legacy one. A readiness result does not authorize later credential use. Keep the synchronous hooks required by the provider type through 2026-12-31. Bundled providers also retain synchronous hooks to support callers of the public synchronous SDK APIs until that date; ordinary runtime callers use async hooks. See auth and availability details.

Approval routing and command authorization

Direct resolvers return promises. Factories whose names end in Async below still return adapters synchronously; their routing and eligibility callbacks return promises and the host awaits them.

// Beforeconst auth = resolveCommandAuthorization(input);// Afterconst auth = await resolveCommandAuthorizationAsync(input); // Factory migration: construction itself stays synchronous.const adapter = createChannelApprovalNativeRuntimeAdapterAsync(options);

If one operation needs several routing decisions, prepare resolveApprovalRequestSessionDeliveryAsync once and pass its sessionDelivery to the helpers. Keep current approval, command execution, and delivery authority at their effect boundaries. See approval routing and import paths.

Conversation and native session bindings

Create current-host managers with createAccountScopedConversationBindingManagerV2 and register custom adapters with registerSessionBindingAdapterV2. The V2 manager factory remains synchronous and returns an async-only receiver.

// Beforeconst manager = createAccountScopedConversationBindingManager(options);const binding = manager.getByConversationId(conversationId);// Afterconst manager = createAccountScopedConversationBindingManagerV2(options);const binding = await manager.getByConversationIdAsync(conversationId);

Channel-specific setter names remain on their existing local channel surfaces. They do not create new cross-plugin imports. Custom adapters own their storage and must implement the V2 asynchronous and current-owner contracts.

Native harnesses must migrate ownership, not just rename a getter:

For new harness code, follow native session lineage: await resolvePreparedNativeSessionBinding or retainNativeSessionGenerationAuthority, consume the owned capture, and call release() in finally. Keep the owner alive through effects and terminal cleanup. A cold or invalidated cached binding cannot substitute for current owner authority.

Keyed state

Use api.runtime.state.openKeyedStoreV2, or the lazy createPluginStateKeyedStoreV2 factory from plugin-state-store-runtime when providing an explicit plugin owner. These factories return immediately; their methods perform the worker operations.

// Beforeconst store = api.runtime.state.openSyncKeyedStore(options);store.register("item", value);const stored = store.lookup("item");// Afterconst store = api.runtime.state.openKeyedStoreV2(options);await store.register("item", value);const stored = await store.lookup("item");

V1 callback methods already return promises, but their opaque JavaScript callbacks still execute in a native host transaction. Do not replace an atomic update with an unconditional lookup and write:

// Beforeawait legacyStore.update("counter", (value) => (value ?? 0) + 1);// Afterconst observed = await store.observe("counter");const result = await store.compareAndApply("counter", observed.comparison, {  operation: "update",  action: "set",  value: (observed.value ?? 0) + 1,});if (result.status === "conflict") {  // Recompute from a new observation or report the conflict to the caller.}

For deleteIf, evaluate the predicate from an observation, then conditionally apply { operation: "delete", action: "delete" } with that observation's comparison. A conflict means no requested mutation committed. Do not replay an unknown write or a callback with external side effects. See keyed-state migration for multi-key conditions and worker operations. Ordinary V1 data-only methods are not the callback removal target.

SessionManager, extension persistence, and replay

Use agent-sessions for manager APIs. Every persistence method below must settle before reading the resulting view or publishing a dependent effect.

// Beforeconst manager = SessionManager.open(target);const id = manager.appendCustomEntry("checkpoint", { stage: "ready" });// Afterconst manager = await SessionManager.openAsync(target);const id = await manager.appendCustomEntryAsync("checkpoint", { stage: "ready" });

Use ExtensionActionsV2, ExtensionRuntimeV2, and bindCoreAsync to supply awaited extension actions. The original action/runtime types and bindCore are not removed merely because they can host legacy actions. SQL-free prepared view getters, inMemory(), and fromEntries() remain synchronous. See session persistence and provider replay for completion semantics and types.

Transcript write callbacks, readers, and catalogs

// Beforeawait withSessionTranscriptWriteLock(target, async (writer) => {  await writer.appendMessage({ message, prepareMessageAfterIdempotencyCheck: prepareSync });});// Afterawait withSessionTranscriptWrite(target, async (writer) => {  await writer.appendMessage({    message,    preparation: { prepareMessage: prepareAsync, source: sourceAuthority },  });});

Preparation runs after duplicate detection and outside the database transaction. Return undefined to suppress a fresh append; a duplicate keeps its stored bytes and skips preparation. Keep externally visible side effects out of preparation. The new write scope does not promise the old callback's native transaction view or roll back already committed appends. See locked transcript preparation.

Reply, observer, and harness preparation

// BeforesessionObserver.handleEvent(event);// Afterawait sessionObserver.handleEventAsync(event);

onPreparedAgentRunStart must still return completion ownership synchronously; prepare transcript facts before invoking it. Awaited policy preparation is not permission to execute or disclose later. Preserve the host's current authority immediately before the effect. See reply authority and observer visibility.

Account services, runtime config, workspace, and TTS

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

Bundled plugins can call private prepareTtsPreferences once per turn and pass that result to the supported prepared overloads. Those SQL-free synchronous overloads are not deprecated. External plugins use the public runtime method above. See the public TTS preparation recipe.

Debug proxy capture and raw SQLite

// Beforeconst store = acquireDebugProxyCaptureStore(options);// Afterconst lease = await acquireDebugProxyCaptureStoreAsync(options);try {  // Await capture operations on lease.store.} finally {  await lease.release();}

The following sqlite-runtime operations have no mechanical async SQL wrapper. Use openOpenClawAgentSqliteWorkerStoreV2 and serializable owner commands for ordinary runtime storage. Move the native implementation into the paired worker backend using sqlite-worker-runtime:

// Before: awaiting admission does not move this callback off the host.await withOpenClawAgentDatabaseWrite(options, ({ db }) => updateRows(db, input));// After: updateRows and its transaction belong to the paired worker backend.await store.execute({ type: "updateRows", input }, owner.assertCurrent);

Preserve explicit read-only inspection, offline Doctor/CLI maintenance custody, and supported worker-local primitives. Do not treat them as permission for writable native handles in Gateway handlers. See worker store construction, cleanup, and missing-store semantics.

Verify the migration

Exercise one read after an awaited in-process write for each migrated owner. For conditional state updates, prove that a competing write produces a conflict instead of being lost. Check callback completion and release resources in finally. Confirm that the migrated flow emits no synchronous SQLite deprecation warning and that errors propagate without a legacy retry.

This guide covers the synchronous SQLite removal window. Unrelated aliases, active compatibility records, prepared SQL-free overloads, and private/internal implementation kernels retain their own contracts. Removing the public adapters in January does not authorize removing live security checks or changing stored data.