> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Session identity keying

# 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:

```typescript theme={"dark"}
type ExtensionRecordKey = {
  channel: string;
  accountId?: string;
  peerKind: "direct" | "group" | "channel"; // matches core's ChatType
  peerId: string;
};
```

* `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](https://docs.wednesdayai.dev/next/developers/concepts/workspace-lanes.md#linking-gateway-devices)).

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:

```typescript theme={"dark"}
import { getConversationReadQuery } from "wednesdayai/plugin-sdk";

const query = getConversationReadQuery({ agentId });
```

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:

```typescript theme={"dark"}
const { sessions, nextCursor } = await query.listSessionsByActor({
  channel: "telegram",
  peerKind: "direct",
  peerId: "123456",
  limit: 100, // optional; default 100, max 1000 — see "Limits" below
});
```

**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):

```typescript theme={"dark"}
const { sessions } = await query.listSessionsByCanonicalIdentity({
  canonicalIdentity: "alice",
  limit: 100,
});
```

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`):

```typescript theme={"dark"}
// Recorded compaction events for a session, newest first, on the (session_id, compaction_seq)
// index — no transcript scan. `beforeCompactionSeq` pages strictly older rows.
const events = await query.listCompactions({ sessionId, limit: 100 });
for (const event of events) {
  event.payload.result; // { summary, tokensBefore, firstKeptEntryId }
}

// The latest saved `context.project` payload (or any other projection type) for a session.
const projection = await query.loadLatestProjection({
  sessionId,
  projectionType: "context.project",
});
```

`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):

```typescript theme={"dark"}
// Before: parses the key's positional segments to guess channel/account/peer.
function inferPeerFromSessionKey(sessionKey: string) {
  const parts = sessionKey.split(":"); // agent:<id>:<channel>:[<account>:]direct:<peer>
  // ...shape-sniffing, ambiguous under identityLinks (#646), breaks on a dmScope change
}
```

```typescript theme={"dark"}
import type { OpenClawPluginApi } from "wednesdayai/plugin-sdk";

// After: use the persisted/SDK-exposed tuple instead of the key text.
export default function register(api: OpenClawPluginApi): void {
  api.on("before_agent_start", async (_event, ctx) => {
    const identity = ctx.runtimeIdentity;
    if (!identity) {
      return;
    }
    const { peerKind, peerId, accountId, canonicalIdentity } = identity;
    if (!peerKind || !peerId) {
      // The SDK fields are optional because non-inbound lifecycle paths may not have an actor.
      return;
    }
  });
}
```

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:**

```typescript theme={"dark"}
// ❌ parses sessionKey for identity instead of using the persisted tuple / read queries
const peerId = ctx.sessionKey.split(":").pop();
```

**Do this instead:**

```typescript theme={"dark"}
// ✅ read the current actor from the injected runtime identity
const identity = ctx.runtimeIdentity;
if (!identity) {
  return;
}
const { peerId, peerKind, accountId, canonicalIdentity } = identity;
if (!peerKind || !peerId) {
  return;
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.