Skip to main content

Session Identity for Extension-Owned Storage

If your extension keeps its own records about a conversation (a per-user preference, a moderation flag, a billing counter) do not key those records on sessionKey. sessionKey is a config-shaped bucket id. For a direct peer, buildAgentPeerSessionKey (src/routing/session-key.ts) composes it from the sender plus session.dmScope, and from session.identityLinks only when that scope is not main. Group and channel keys are agent:<id>:<channel>:<group|channel>:<peer>. Neither setting is an input. resolve-route.ts passes those same builder inputs and still exposes the raw route peer. A dmScope change rebuckets direct peers only. Group and channel keys are unaffected. An identityLinks change rewrites a direct key only when dmScope is not main and the resolved linked peer id differs from the raw peer id after the builder lowercases both. An unlinked direct peer, a main-scope direct peer, and every group or channel peer keep the same key. Under identityLinks, a direct key segment can still be ambiguous: a linked sender’s canonical name is textually indistinguishable from an unlinked raw peer id that happens to equal it (#646). Stored group and channel peers remain the key segment. This limit does not change that rule, a route’s raw peerId, or the persisted actor snapshot. ADR 0081 makes actor identity (channel, accountId, peerKind, peerId, optional canonicalIdentity) a persisted, queryable fact instead. This guide covers the contract your extension should use instead of parsing sessionKey.

The keying contract (ADR 0081 D8)

Key your own tables on the raw tuple:
  • canonicalIdentity may be carried as an overlay on top of the tuple (for example, to group a linked sender’s rows together), but it never replaces the tuple as the primary key. It is undefined for an unlinked sender.
  • sessionKey is valid only as an opaque bucket id — pass it back to core APIs that expect a bucket id (readByKey, hook dispatch), never parse it to recover channel/account/peer.
  • The only code that parses a legacy sessionKey for identity is the backfill (src/config/sessions/ctx-identity-backfill.ts), which fills identity onto pre-ADR-0081 rows. No live consumer parses keys: since ADR 0081 mission 2, every live read and runtime path takes identity from the persisted session actor.

Gateway senders are devices

On the gateway surfaces (chat.send, sessions.steer, talk), the raw peer id of a turn is device:<deviceId> — the verified device that connected — not the app id. The app id (for example openclaw-user-client) is used only when the connection has no device block (Control UI with dangerouslyDisableDeviceAuth, a trusted proxy without a device block). Nothing changes about the tuple: device:<id> is the raw peerId, attributed through the turn’s channel by the existing precedence rules, and canonicalIdentity is set only when the operator linked the device in session.identityLinks. Key on the tuple as before; do not special-case the device: prefix — a lane-enabled agent denies turns it cannot attribute to a linked identity (WorkspaceLaneDeniedError; see Workspace Lanes). For a linked device (ADR 0104) the person is the sender name: ctx.senderName and the model’s Sender block resolve to the identityLinks key (Alice (device:…)), while senderId stays the raw device:<id> as provenance. The client’s display name (for example MentraOS glasses) is a Sender-block client field, never a person name. So: resolve people from ctx.runtimeIdentity.canonicalIdentity (or ctx.senderName for gateway turns); treat senderId as a credential id, never a person. System agent-turns (cron systemEvent/wake, nudge, work, announce) are never user turns. They report ctx.trigger of cron/heartbeat on run hooks, and their persisted entries carry entry.triggerSource of cron/heartbeat with entry.isAutomated: true on storage.afterAppend — including shared sessions such as agent:main:main. The reverse holds: a human chat.send into an existing cron or heartbeat session key is stamped user explicitly, so it persists as a person turn even inside an isolated cron session (a direct peer id that merely contains :cron: is also never cron). An entry without those markers on a non-system turn is a person’s turn; canonicalIdentity undefined then means an unknown person: fail closed.

Reading identity-scoped history

Your extension receives a ConversationReadQuery (ADR 0012), either injected into a context lifecycle hook (context.collect/project/prune) or fetched directly:
The legacy openclaw/plugin-sdk specifier still loads (ADR 2057). It is read-only and owner-scoped to agentId by construction — there is no parameter to read another agent’s sessions.

listSessionsByActor

Finds every session written by one raw (channel, accountId?, peerKind, peerId) tuple:
The accountId wildcard. Omitting accountId matches every account for that tuple, including rows whose account_id is NULL — it is a documented wildcard, not “no filter applied accidentally.” Passing an explicit accountId narrows to exactly that account and never matches a NULL account_id row. Most multi-account channel configurations should omit it unless they specifically need one account’s history. Coverage limit. listSessionsByActor requires channel. A row whose persisted channel is NULL is not returned by this query — there is no peer-only lookup, because a bare peer id can collide across channels. Such a row is still reachable through listSessionsByCanonicalIdentity (if canonical_identity was established) or through readByKey with its known sessionKey.

listSessionsByCanonicalIdentity

Finds every session for a linked sender, across every channel in their identityLinks entry — the case readByKey cannot cover (see “Non-claims” below):
This matches rows whose canonical_identity column already equals "alice", and rows whose direct-peer lookup keys match "alice"’s currently configured identityLinks peers — so a link added after a row was written still finds it. It does not return the session of an unlinked raw peer whose id merely equals "alice" (the #646 case) unless that row’s own metadata actually established the link. Configuration-derived links attribute direct peers only, never group or channel rows with colliding tokens. Link matching uses the resolver’s full-token trim-and-lowercase semantics, including opaque colons; it does not split tokens into invented channel/peer components. Private normalized lookup keys leave the stored raw facts and the public actor-query contract unchanged. Canonical references whose persisted channel is NULL omit channel instead of inventing a channel name.

listCompactions and loadLatestProjection

Both are derived-output reads over one session — session-level facts, not transcript entry ranges — with the same ownership scoping as every other session-id read (a session the scoped agent does not own throws StorageReadAccessError):
listCompactions reads the ctx_compaction_events table that compaction runs record; a session compacted before that table existed reports no events (callers that must see those fall back to transcript scans, as sessions.compaction.list does). Event-backed checkpoints have no transcript entry id, so only createdAt, tokensBefore and firstKeptEntryId are populated. loadLatestProjection returns undefined when nothing was ever persisted for that (sessionId, projectionType) pair. Both answers come from their own indexed tables, so neither touches the conversation log.

Limits

Both identity queries (listSessionsByActor, listSessionsByCanonicalIdentity) clamp limit through the same read-limit clamp every other store read uses: default 100, max 1000. A limit above 1000 is truncated to 1000 and logged as a warning. A non-numeric, zero, or negative limit falls back to 100 without a warning. Neither case is rejected. Page with the returned nextCursor until it is absent; pages are keyset-ordered on (updated_at, session_id) with no duplicates across pages. listCompactions clamps limit through the same clamp (same default and max). Both queries return { sessions: [] } when the configured runtime has no lossless conversation log (capabilities.losslessConversationLog === false) — check for an empty result, not an exception, when degrading gracefully on that backend.

Own your tables; core tables are off-limits

Store extension data in your own namespace, never in core session tables (ADR 0099, dev-docs/adr/0099-plugins-own-their-tables.md). Core owns every table its schema modules create: the ctx_* conversation tables plus the session-run, consumer-claim, task-run, task-budget, cron and verification tables. Your extension must not read, write, ALTER, index, attach triggers to, or otherwise reference any of them, in production code, tests or migrations. Columns a plugin adds to a core table are unsupported: any core migration or restore can drop them. Create and migrate your own tables instead:
  • Postgres: a dedicated schema named plugin_<id>, for example plugin_learning_core.
  • SQLite: tables prefixed plugin_<id>_.
Read conversation data through the plugin-sdk, never through the database: getConversationReadQuery (above) for history reads, and the storage.afterAppend hook for write-side events projected into your own tables. pnpm lint:extensions:no-core-tables (part of pnpm check) enforces the rule for bundled extensions. scripts/check-extension-core-table-access.ts derives the core table set from the same schema builders storage init composes, so new core tables are covered automatically, and it fails on any core table reference under extensions/ (.ts, .tsx, .js, .mjs, .cjs, .sql, .py). The script ALLOWLIST holds only test-harness hits with no plugin-sdk replacement yet; each entry names the finding that tracks its removal, and a hit in a production extension file is never allowlisted.

What this does not claim to fix (#646)

listSessionsByCanonicalIdentity and the persisted actor tuple fix stale attribution going forward: a row’s current identity snapshot now reflects the actor who most recently wrote it, and a dmScope/identityLinks change no longer detaches history written under the old shape. They do not separate a historical collision. If two different senders already shared one sessionKey before this change — under main/per-peer dmScope, or because an unlinked raw peer id happened to equal a linked canonical name — the messages those two senders wrote into that shared bucket stay recorded together under it. Only the row’s identity snapshot (its current channel/account_id/peer_kind/peer_id/canonical_identity columns) moves to the newest actor; the transcript already stored under that session_id is not re-split or re-attributed per message. Do not build a feature on the assumption that per-message attribution inside one legacy collided session is now available — it still isn’t.

Migrating off key parsing

A consumer that used to recover identity by parsing sessionKey should switch to the SDK fields and read queries above instead. For example, a hand-rolled parser like this (illustrative — based on the shape buildAgentPeerSessionKey produces, not a file this guide edits):
An inbound turn can expose its actual peer through runtimeIdentity even when isMainSession is true. ADR 0081 D3 keeps the persisted shared-main row peerless; it does not erase the current inbound actor from SDK lifecycle context. An actorless turn is distinguished by missing peerKind or peerId, not by the main-session flag. ResolvedAgentRoute also exposes peerKind, peerId, canonicalIdentity, and isMainSession when your extension resolves a route instead of receiving a hook context. peerId on that route is the raw constructor input: trimmed, not lowercased, and not replaced by an identityLinks canonical name. The session bucket is still built from that input plus dmScope. This guide does not change the route field or the bucket. That raw route id is not always the id you can query. On a surface-prefixed group or channel (slack:channel:…, slack:group:…, matrix:group:…), the exposed group id is the lowercased sliced id. The write seam persists that exposed id, and the turn’s runtimeIdentity.peerId publishes the same value. A bare group: / channel: marker still keeps the raw remainder, including case. That bare-marker case split is outside ADR 0081 D5 and is not the same id as the lowercased legacy key segment. For history older than the current turn, call listSessionsByActor / listSessionsByCanonicalIdentity with the matching turn’s runtimeIdentity tuple. Do not pass ResolvedAgentRoute.peerId, and do not recover the tuple by parsing sessionKey. For channel, pass the turn’s runtimeIdentity.channelId from an agent-turn hook such as before_agent_start; it follows the persisted actor channel (OriginatingChannel, then Provider, then Surface). On the inbound message_received hook, channelId prefers Surface over Provider, so it can differ from the persisted channel when OriginatingChannel is absent and Provider and Surface differ. Query from a turn hook when you need an exact match. Hook channelId values are lowercased, while the persisted actor channel keeps the raw case of the context field, so a channel that emits mixed-case context fields needs the persisted case. An account id may be the literal word direct, group, or channel. Each collides with a marker-shaped peer: agent:<id>:slack:direct:direct:<peer>, agent:<id>:slack:group:direct:<peer>, and agent:<id>:slack:channel:direct:<peer>. Do not parse those keys to decide account, peer kind, peer, or scope. The shared fact is channel slack only. Kind direct is shared only for the direct:direct shape. A mixed group or channel shape has no shared kind, so kind stays NULL. Account, peer, scope, and canonical identity stay NULL unless an independent account fact or an eligible raw sender establishes them. A raw human peer is used only when the resolved kind is direct and the existing channel provenance applies. A known group, channel, or absent kind never treats that human entry as the chat peer. Do not guess scope from a known kind or from a metadata account. Use the matching turn’s runtimeIdentity or the persisted tuple. A local working-tree gate now keeps that contract for all three markers: scripts/check-no-sessionkey-identity-parse.mjs, which runs as pnpm lint:sessions:no-sessionkey-identity-parse inside pnpm check and fails on code that recovers channel, account, peer kind/id, group, or user identity from sessionKey text. The gate scans this repository’s source tree only. It does not check third-party plugins, so never parse the key in yours.

Async safety

getConversationReadQuery and both identity queries are plain async functions — no blocking I/O, safe to call from a tool execute() or a hook handler. They do not block the gateway event loop. A listSessionsByCanonicalIdentity page executes one SQL statement containing at most three indexed UNION arms: persisted canonical_identity, normalized bare-peer lookup keys and normalized channel-scoped lookup keys. This is one database round trip per page, not one per configured link. SQL text and bind work still grow with the selected full-token link list. Avoid calling it in a tight loop over many identities in one turn; page with nextCursor rather than raising limit. Do not do this:
Do this instead: