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

# Versioned Kernel Contracts

# Versioned kernel contracts

The kernel exposes six versioned contracts. Each contract id names one public surface an
extension builds against, versioned as `major.minor` by a constant in
`src/plugins/contract-versions.ts`. Versions are compiled into the host, so they are reliable
even when the host version string is not. All ids, constants and the compat checker are
re-exported from `wednesdayai/plugin-sdk`.

## Versioned contracts

| Contract | Constant | Current version | Root types | You implement |
| - | - | - | - | - |
| `sdk` | `SDK_CONTRACT_VERSION` | `2.52` | The public `wednesdayai/plugin-sdk` barrel and its declared subpaths | nothing — core provides all of it |
| `plugin` | `PLUGIN_CONTRACT_VERSION` | `2.13` | `OpenClawPluginApi`, `OpenClawPluginDefinition` (`src/plugins/types.ts`), `PluginManifest` (`src/plugins/manifest.ts`), `PluginRuntime` (`src/plugins/runtime/types.ts`), `ChannelPlugin` (`src/channels/plugins/types.plugin.ts`), `ChannelCapabilities` and `ChannelMeta` (`src/channels/plugins/types.core.ts`) | `OpenClawPluginDefinition`, `PluginManifest`, `ChannelPlugin`, `ChannelCapabilities`, `ChannelMeta` |
| `hooks` | `HOOKS_CONTRACT_VERSION` | `1.4` | Every `PluginHook*` type in `src/plugins/types.ts` | the `PluginHook*Result` payloads your handlers return |
| `ingress` | `INGRESS_CONTRACT_VERSION` | `1.9` | `MsgContext` (`src/auto-reply/templating.ts`), `InboundUserContext` (`src/auto-reply/reply/inbound-meta.ts`), `PluginRuntimeChannel` (`src/plugins/runtime/types-channel.ts`), `ChannelGatewayAdapter` and `ChannelGatewayContext` (`src/channels/plugins/types.ts`) | `MsgContext`, `ChannelGatewayAdapter` |
| `delivery` | `DELIVERY_CONTRACT_VERSION` | `1.0` | `ChannelOutboundAdapter`, `ChannelOutboundContext`, `ChannelPollContext` and `ChannelPollResult` (`src/channels/plugins/types.ts`), `ChannelOutboundPayloadContext` (`src/channels/plugins/types.adapters.ts`), `OutboundDeliveryResult` (`src/infra/outbound/deliver.ts`) | `ChannelOutboundAdapter`, `ChannelPollResult`, `OutboundDeliveryResult` |
| `gateway` | `GATEWAY_CONTRACT_VERSION` | `3.28` | Every exported wire type in `src/gateway/protocol/schema/types.ts`, plus the `ProtocolSchemas` registry (`src/gateway/protocol/schema/protocol-schemas.ts`) | request `*Params` payloads and `RequestFrame` |

Each root type carries a direction, and the snapshot records it per entry:

* `provided` — core hands the type to you, so core may add members to it freely without
  breaking you.
* `implemented` — you implement or construct the type, so a new required member or a changed
  signature in core would break your implementation.

The exact per-type split lives in `scripts/contract-surface/roots.ts`.

The `gateway` contract is special: its major equals `PROTOCOL_VERSION` in
`src/gateway/protocol/schema/protocol-schemas.ts`, because the wire protocol between clients and
the gateway is observable outside the plugin boundary.

### Delayed release and consumer-dispatched claims (sdk 2.36, plugin 2.8)

For deployment roles (ADR 1168, `dev-docs/adr/1168-postgres-multi-writer-mechanism.md`), the
bus-work surfaces gained two additive members:

* `Backbone.release(workId, opts?)` and `BusWorkDispatcherOptions.backend.release(workId, opts?)`
  accept `{ availableAt?: Date }`: the released item returns to `pending` and is not claimable
  before `availableAt`. Without `opts`, release behaves exactly as before.
* Optional `claimDispatched(topic, consumerId, leaseMs)` on `Backbone` and the bus-work backend
  claims only consumer-dispatched `agent.turn` items (Postgres only; absent elsewhere).
* Session-run recovery modes gain `"lease"` (visible through `PluginRuntime.sessions`): runs
  executed by the runner consumer, which startup recovery skips because work-lease reclaim owns
  them.

### Channel connecting flag (sdk 2.39, plugin 2.9)

`ChannelAccountSnapshot` and a channel's `status.defaultRuntime` gain optional
`connecting?: boolean`. A channel sets it while a connection handshake is in progress;
`wednesdayai channels status` then prints `connecting` for a running account instead of
`disconnected`. Without the flag, a running account that is not connected still prints
`disconnected`, with the `lastDisconnect` code or reason when one is recorded.

### Host bridge device settings (sdk 2.40)

`packages/host-bridge` gains `HostSettingsEntry`, `SettingsOpen`, `WEB_FEATURE_SETTINGS_MENU`,
an optional `HostDescribe.settings` list, optional `HostDescribeRequest.features`, and the
web → host `settings.open` message. The envelope stays `v: 1`. The change is additive only.

### Role-scoped device socket revocation (sdk 2.41)

`GatewayRequestHandlerOptions.context` gains optional
`revokeDeviceRoleConnections(deviceId, role, reason)`. It works like `revokeDeviceConnections`
but suspends and then closes only the device's live connections that hold `role`.
`device.token.revoke` uses it, so revoking a token closes the sockets that token authenticated
(#2282). The change is additive only.

### Channel account mode (sdk 2.42)

`resolveChannelAccountMode(cfg, channel, accountId?)` and the `ChannelAccountMode` type
(`"channel" | "inbox"`) are exported. An account resolves to
`channels.<ch>.accounts.<id>.mode ?? channels.<ch>.mode ?? "channel"`; only `whatsapp`,
`bluebubbles`, and `discord` can resolve to `"inbox"` (ADR 2572).

### Device accessories (gateway 3.20, sdk 2.43)

A signed-in WednesdayAI app device manages the credential-less accessories vouched for by its own
record (plan C2 of `docs/plans/app-login-accessory-scopes.md`, ADR 2242 D4):

* New methods `device.accessory.attach` / `device.accessory.detach` / `device.accessory.list`
  (all own-device, `operator.write` / `operator.write` / `operator.read`, app-profile callers
  only), with new `ProtocolSchemas` entries `DeviceAccessory*Params` / `DeviceAccessory*Result`.
* The request frame gains optional `accessoryId` (`RequestFrame.accessoryId`), so
  `GatewayRequestHandlerOptions.req` carries it; a tagged request is clamped to the accessory's
  gateway-owned profile after the method-scope check (the clamp only narrows). The change is
  additive only.
* A tag admits only the explicit allowlist `ACCESSORY_TAGGABLE_METHODS` (in
  `src/shared/accessory-profiles.ts`): `node.invoke`, `node.event`, `node.invoke.result`,
  `chat.send`, `chat.abort`, `chat.history`, `exec.approval.resolve`, `device.self`. Everything
  else tagged is refused `accessory_method_denied` before any scope check.
* Refusal reasons (all `INVALID_REQUEST`, in `error.details.reason`): `accessory_forbidden` (the
  caller is not a signed-in app device — includes device-less connections), `accessory_kind_unknown`,
  `accessory_id_invalid`, `accessory_limit` (9th accessory), `accessory_not_attached` (unknown or
  detached tag), `accessory_method_denied` (method not on the taggable allowlist),
  `accessory_scope_denied` (the kind's profile does not grant the method's required operator
  scope), `accessory_command_denied` (`node.invoke` command outside the kind's `commands` grants).
  One further reason travels as `UNAVAILABLE`, not `INVALID_REQUEST`: `accessory_busy` (the
  device's accessory state is locked by a concurrent connect or mutation; retry).
* A tagged request that passes the clamp runs its handler with a request-local client view whose
  `connect.scopes` hold every accessory-profile scope the connection satisfies under the
  implication rules (never a scope outside the profile); the view's connect delegates to the
  original connection for person-scope state, so a live suspension or unlink applies to tagged
  requests too. The socket's client object is never mutated.
* The tag is attribution plus a ceiling on the accessory's own direct requests — not an isolation
  boundary against the app or the person's agent: an agent turn started by a tagged `chat.send`
  runs under the person's tool policy and exec approvals like any untagged app request. For audit
  and approval display, a run started by a tagged `chat.send` carries `accessoryId` and `kind` in
  its `chat` events' optional `origin` (next to `deviceId`/`clientId`).

### App sign-in requirement (gateway 3.21, plugin 2.10, sdk 2.44)

C4 of `docs/plans/app-login-accessory-scopes.md` (ADR 2242 D4). All changes are additive:

* `GATEWAY_CLIENT_IDS` gains `WEDNESDAYAI_MOBILE: "wednesdayai-mobile"` and
  `WEDNESDAYAI_DESKTOP: "wednesdayai-desktop"`, both mapped to the app bootstrap profile (the
  same object as the deprecated `wednesdayai-glass-node`). `ConnectParams.client`'s id enum and
  its expanded surfaces therefore widen.
* `PluginRuntime.identity.issueEnrollment` accepts `profile: "wednesdayai-mobile"` and
  `"wednesdayai-desktop"`, minting the app bootstrap profile like `wednesdayai-glass-node`.
* The identity-oidc plugin config gains `appSignIn` (`"required" | "optional"`, default
  `"optional"`) and `appSessionMaxAgeDays` (optional positive integer); `GET
  /plugins/identity-oidc/providers` returns the resolved `appSignIn` and, when set,
  `appSessionMaxAgeDays`.
* Connect refusal detail codes `app_sign_in_required` and `app_sign_in_expired`
  (`src/gateway/protocol/connect-error-details.ts`) for an app device connecting without a
  person, or with a pairing older than `appSessionMaxAgeDays`.

### Your devices (gateway 3.22)

A person reads and removes their own devices from any of their own devices (plan C5 of
`docs/plans/app-login-accessory-scopes.md`, ADR 2600):

* New methods `identity.devices.list` (`operator.read`, narrow-admitted via
  `operator.sessions.read`) and `identity.devices.remove` (`operator.write`, narrow-admitted via
  `operator.sessions.write`), with new `ProtocolSchemas` entries
  `IdentityDevicesListParams`/`Result`, `IdentityDevicesRemoveParams`/`Result` and the shared
  `IdentityDeviceEntry` row. Additive only; no existing payload changed.
* `identity.devices.list` returns the paired devices whose stored `ownerPerson` is the caller's
  person — device id, optional display/client/platform/family fields, `lastActiveAtMs`,
  `approvedAtMs`, `companionOf`, `current`, and the vouched accessories
  (`accessoryId`, `kind`, `model?`). No tokens, public keys or scopes cross the wire.
* `identity.devices.remove` runs the guarded owned-removal cascade: one conditional store
  mutation re-checks owner, row revision and token fingerprint under the store lock and removes
  the parent, its companion grants and its companion rows in that transaction (the captured
  companion ids drive the socket closes). `identity_device_not_owned` is the uniform refusal for
  another person's device, for an unknown id and for a re-enrollment between the read and the
  write, and `identity_person_required` refuses a caller with no person.

### Session-storage Postgres connect timeout (sdk 2.45)

`OpenClawConfig.session.storage` gained the optional `postgres.connectionTimeoutMs` key (#2520).
It is a `provided` config member, so the change is additive.

### Channel account failed state (sdk 2.46, plugin 2.11)

A channel's `gateway.startAccount` may resolve with `ChannelAccountStartResult`
(`{ accountFailure: { reason, code?, remediation? } }`). `ChannelAccountStartResult` and
`ChannelAccountFailure` are exported from `wednesdayai/plugin-sdk`. The channel manager then sets
`ChannelAccountSnapshot.failure` (`reason`, `code`, `remediation`, `at`) and `lastError`, skips
the backoff restart, and the health monitor does not restart the account. The account starts
again only when its resolved config changes, when it resolves disabled or unconfigured, or when
the gateway restarts. `wednesdayai channels status` prints `failed (code N)` and a warning, and
`wednesdayai doctor` lists the same warning. `status.defaultRuntime` gains optional `failure`.
The change is additive only: channels that never return `accountFailure` behave as before.

### Alert mutes and preview dedupe (gateway 3.23, plugin 2.12)

A person can mute their own alert pushes per kind, per inbox source, or per inbox source and
account, from the app (device settings C4, ADR 2242 D2):

* New gateway methods `push.mute.get` (`operator.read`, `{}`) and `push.mute.set`
  (`operator.write`) return `{ mutes }`, the person's full sorted mute list after the change.
  `push.mute.set` is one idempotent toggle (`{ kind, source?, accountId?, muted }`), not a
  snapshot replace, so concurrent devices do not overwrite each other.
* A mute matches an alert when the kind is equal and the optional `source` and `accountId`
  match exactly. `"chat.final"` mutes reply alerts; `"inbox"` with a `source` mutes that inbox
  source, with `accountId` one account. Approvals are never muted.
* `RuntimePushAlertInput` (plugin 2.12) gains optional `source` and `accountId`, so inbox
  plugins pass the emitting account and the person's mutes apply to them. Additive only.
* Refusals carry `error.details.reason`: `push_mute_person_required` (the connection resolves no
  person), `push_mute_invalid` (bad or inconsistent `source`/`accountId`), `push_mute_limit`
  (more than 64 mutes per person).
* Superseded in plugin 2.13: dedupe is by event id, not preview text (see below).

### Alert event dedupe (plugin 2.13)

* `RuntimePushAlertInput` gains optional `eventId`, a stable id of the event the alert is for
  (the inbox plugin passes its row id, the percent-encoded `source:accountId:sourceId`; reply
  alerts use the run id). Additive only.
* A repeat with the same `eventId` is pushed to a device at most once per kind every 10 minutes
  (`PERSON_ALERT_EVENT_DEDUPE_MS`). Identical text never suppresses a distinct event; only the
  30-second per-collapse-key rate limit (`PERSON_ALERT_MIN_INTERVAL_MS`) applies.
  Without `eventId` nothing is deduped. Approvals are never deduped. Only digests are kept in
  memory.
* Replaces the gateway 3.23 / plugin 2.12 preview-text dedupe, which dropped the second of two
  different mails sharing a subject.

### Inbox classification provenance (gateway 3.27, sdk 2.49)

Inbox classification is live-only by default, and history is opt-in per account (ADR 2637,
`dev-docs/adr/2637-inbox-classify-history-opt-in.md`):

* `InboxItemDto` gains optional `categorySource`, `categorySignal`, `classifyState`
  (`pending` | `skipped-history` | `done`), `classifiedAt` and `classifyModel`. They are
  optional, so the change is additive: older gateways omit them, and readers treat an absent
  field as `null`.
* `OpenClawConfig.inbox.classify` gains optional `history` (`InboxClassifyHistoryConfig`):
  `default` and `accounts` (keyed `"<source>:<accountId>"` or `"<source>"`), each a policy
  `{ mode: "live" | "window" | "all", days? }`. It is a `provided` config member, so the change
  is additive.

### People seam (sdk 2.51)

A process-scoped seam between the people-graph plugin and the inbox plugin, which never import
each other (`src/plugin-sdk/people.ts`):

* `registerPeopleResolver` / `getPeopleResolver` with the `PeopleResolver` type: people-graph
  registers it; inbox calls `resolveSenders` and `resolveEmails` for display names and
  `recordInboxItems` / `recordCalendarEvents` for touch points.
* `registerPeopleHistorySource` / `getPeopleHistorySource` with `PeopleHistorySource`: inbox
  registers read-only paging over its own history, so people-graph backfills never read inbox
  tables (ADR 0099).
* Each register returns an unregister that removes only its own registration. All additive.

### System-origin chat provenance (gateway 3.28, sdk 2.52)

* `ChatEvent` gains optional `trigger: "heartbeat" | "cron" | "subagent" | "acp"`, the run's system
  origin. It is optional, so the change is additive: user runs and older gateways omit it.
* New subpath `wednesdayai/plugin-sdk/reply-sentinels`: the client-safe sentinel rules
  (`REPLY_SENTINEL_TOKENS`, `isSilentReplyText`, `isSilentReplyLeadFragment`,
  `stripEdgeSentinelLines` and siblings).

## Version semantics

Contract versions are `major.minor` strings. The policy is:

* **Breaking** (requires a major bump): removing an entry, adding a required member to an
  `implemented` type, changing a signature or type shape, or flipping a direction.
* **Additive** (requires only a minor bump): new optional members, new members on a `provided`
  type, new required members beneath a newly added optional member (omitting the optional parent
  omits them), new deprecation markers, and pure string-literal union widening — a union that
  gains literals while its literal-elided shape stays unchanged — in either direction (proved by
  `literalRuns`/`shapeHash` on digest-stored entries, or by the elided shape of a short text).

A type-text difference that vanishes under member-order canonicalization is **no change at all**:
the checker's print order for spread and inferred object types follows symbol allocation, not the
contract, so order-only permutations emit no change line. Member order that is semantic is never
canonicalized: bare call/construct signatures and same-name overload groups keep authored order.

Three refinements keep the classifier honest. First, adding members to a `provided` type
changes the parent's recorded shape text, and that parent change is classified as additive
as long as every new entry beneath it is absorbable — a new `provided` member (always
additive, required or not) or an optional one. The same holds one step removed: a
`provided` entry whose text only embeds the grown type by reference (the registry entry
`ProtocolSchemas.AgentSummary`, a flattened member like `AgentsListResult.agents`) is
additive while every addition in the whole contract is absorbable, and breaking otherwise.
Second, the sdk barrel records each export's whole printed type as one entry with no member
entries beneath it, so a member added inside a barrel type changes the barrel entry's text
with nothing in the sdk contract to explain it. A `provided` barrel text change
(`plugin-sdk#MsgContext`) therefore defers to that type's member subtree in the contract
that enumerates it (ingress for `MsgContext` and `InboundUserContext`): additive while the
subtree has diffs and every one of them is additive, breaking otherwise. Kernel version
constants (`plugin-sdk#GATEWAY_CONTRACT_VERSION` and siblings) are exempt
from type-text comparison: their literal changes exactly when a contract version is bumped,
and the per-contract rules already police that bump. Type text is also only compared when
both snapshots were produced by the same text algorithm (the snapshot's `typeTextVersion`);
an algorithm change is a notice with per-contract counts, like a TypeScript bump, never a
breaking change by itself.

Optional members can also hide inside one entry's text. A leaf entry with no keys recorded beneath
it whose type is an inline object (`ConnectParams.auth`) classifies additive in either direction
when the only difference is new optional properties; a union of object arms, a retyped, removed or
newly required property stays breaking. The registry check applies the same rule one level down:
a nested object property that only gained optional properties, with every other keyword
unchanged, is an optional addition.

A breaking change without a major bump fails CI (see [Changing a contract](#changing-a-contract)).

## Declaring what your plugin needs

The optional `contracts` field in `wednesdayai.plugin.json` maps contract ids to the minimum
`major.minor` version your plugin requires (the legacy `openclaw.plugin.json` filename still
loads):

```json theme={"dark"}
{
  "id": "voice-call",
  "configSchema": {},
  "contracts": {
    "plugin": "1.0",
    "hooks": "1.0",
    "ingress": "1.0",
    "delivery": "1.0"
  }
}
```

The field is parsed in `src/plugins/manifest.ts` and checked in
`src/plugins/contract-versions.ts` (`checkPluginContractCompat`). The compat rule is: same
major, and the host minor must be greater than or equal to the required minor. A plugin that
declares nothing is always compatible; a plugin can require a subset of the contracts.
Entries whose value is an array of strings (upstream capability-ownership lists such as
`contracts.tools`) are accepted and ignored for kernel contract versioning; an array holding any
non-string is rejected.

When the check fails, the host refuses the plugin with one of these reasons, taken verbatim
from `checkPluginContractCompat`:

* `requires kernel contract "<id>", which this host does not provide`
* `contracts.<id> "<v>" is not a valid "major.minor" version`
* `requires <id> contract <M>.x (>= <v>), but host provides <host>`
* `requires <id> contract >= <v>, but host provides <host>`

Where the check runs:

* **At install**: `src/plugins/install.ts` refuses the install with the error code
  `VERSION_INCOMPATIBLE` and the message `plugin "<id>" is not compatible with this host: <reason>. Upgrade WednesdayAI and retry.` An invalid version string is prefixed with
  `invalid contract version in <manifest>:`. A malformed `contracts` field (not a map
  whose values are version strings or arrays of strings) is rejected the same way — and before any files are copied — with
  the message `invalid contracts field in <manifest>: <error>`. `<manifest>` is the filename
  actually read: `wednesdayai.plugin.json`, or the legacy `openclaw.plugin.json` when that is
  the only file present.
* **At load**: `src/plugins/manifest-registry.ts` drops the plugin and records an error
  diagnostic with the internal code `PLUGIN_CONTRACT_INCOMPATIBLE` (or `PLUGIN_MANIFEST_INVALID`
  when the manifest fails to parse — including a malformed `contracts` field — or the declared
  version is not a valid `major.minor` string) and the message `plugin "<id>" <reason>`.
  Config validation (`src/config/validation.ts`) turns every error-level manifest diagnostic into
  a config error at `plugins.entries.<id>`, so `config validate`, `plugins list` and Gateway
  startup fail until the plugin is removed or upgraded — the same behaviour as the existing
  minimum-host-version check. The check runs in dev builds too, because contract versions are
  compiled into the host.

See [Plugin manifest](https://docs.wednesdayai.dev/next/developers/plugins/manifest.md) for the rest of the manifest shape.

## Conformance suite

`src/plugin-sdk/conformance.ts`, `conformance-delivery.ts` and `conformance-ingress.ts` ship
framework-free checkers through `wednesdayai/plugin-sdk/testing`. Each checker returns a report of rule violations;
`assertConformance` throws a typed `ConformanceError` when any report has violations, so
extension tests never need to import a test framework to run the checks.

```ts theme={"dark"}
import {
  assertConformance,
  checkDeliveryConformance,
  checkExtensionConformance,
  checkIngressConformance,
} from "wednesdayai/plugin-sdk/testing";

const reports = [
  ...(await checkExtensionConformance({
    dir: "test/fixtures/plugins/conformance-reference",
    pluginId: "conformance-reference",
  })),
  await checkDeliveryConformance(channelPlugin.outbound, { subject: "my outbound" }),
  checkIngressConformance(buildInboundContext("hello"), { subject: "my inbound" }),
];
assertConformance(reports);
```

`checkExtensionConformance` loads the plugin through the real plugin loader and runs the plugin,
hooks and delivery checks; `checkDeliveryConformance` and `checkIngressConformance` can also be
called directly on an adapter or a `MsgContext`. Two properties of `checkExtensionConformance`
matter for test suites: calls are serialised through a module-level promise chain (the inspecting
load activates process-global plugin state, so overlapping loads would restore over each
other), and after the load the checker restores the pre-call state — registry, hook runner,
plugin APIs, speech and voice providers, internal-hook handlers, plugin commands and the
task-pass buffer — so other plugins' commands and registrations survive the check.

Rule ids, grouped by checker:

Plugin and hooks (`checkExtensionConformance`, which includes `checkHooksConformance`):

* `plugin.load.loaded` — the plugin module actually loaded into the registry. When the plugin
  fails to load, this is the only check reported.
* `plugin.register.no-diagnostics` — no warn or error diagnostic is attributed to the plugin.
  Discovery, manifest parsing, config validation and registration all count, not only
  registration.
* `hooks.handler.function` — every registered hook handler is a function.
* `hooks.priority.finite` — hook priority, when set, is a finite number.
* `hooks.timeout.positive` — hook `timeoutMs`, when set, is greater than 0.

Delivery (`checkDeliveryConformance`):

* `delivery.mode.known` — `deliveryMode` is `direct`, `gateway` or `hybrid`.
* `delivery.direct.handlers` — non-gateway delivery provides both `sendText` and `sendMedia`
  (otherwise `createPluginHandler` returns null and delivery throws at send time).
* `delivery.text-chunk-limit.positive` — `textChunkLimit`, when set, is a positive integer.
* `delivery.chunker.bounded` — a chunker returns a non-empty chunk array at the adapter's own
  limit (default 4000) without throwing. The probe text is capped independently of the declared
  limit (\~8000 chars), so a huge valid `textChunkLimit` does not scale the probe allocation.
* `delivery.send-text.result` — the optional sendText probe resolves to a result object with a
  non-empty `messageId` and the adapter's own `channel`.

Ingress (`checkIngressConformance`):

* `ingress.sender.identity` — sender identity fields pass `validateSenderIdentity`.
* `ingress.body.strings` — `Body`, `BodyForAgent` and `BodyForCommands` are strings.
* `ingress.group.conversation-label` — group/channel context carries a conversation label
  (`ConversationLabel` or fields that derive one).

These checks are not sandboxed: the checkers execute the adapter's own code in-process, with
neither a sandbox nor a timeout. `delivery.chunker.bounded` calls the adapter's chunker twice,
and the optional `deliveryProbe` makes the `delivery.send-text.result` check call the adapter's
real send path — with a credential-bearing config, that sends a real message. Run the send-text
probe only against an in-memory or sandbox adapter.

`test/fixtures/plugins/conformance-reference/` is the reference implementation: a minimal
in-memory channel plugin that imports only from `wednesdayai/plugin-sdk` and passes every check.
For an extension-side example, see `extensions/telegram/src/outbound.conformance.test.ts`.

## Private imports

An extension may import core only through the plugin-sdk surface:

* `wednesdayai/plugin-sdk` (alias `wednesdayai/plugin-sdk`), and
* its exported `./plugin-sdk/*` subpaths, for example `wednesdayai/plugin-sdk/account-id`,
  `wednesdayai/plugin-sdk/keyed-async-queue`, `wednesdayai/plugin-sdk/process-scoped-map`,
  `wednesdayai/plugin-sdk/lazy-runtime`, `wednesdayai/plugin-sdk/escape-regexp`,
  `wednesdayai/plugin-sdk/control-ui`,
  `wednesdayai/plugin-sdk/provider-web-search` and
  `wednesdayai/plugin-sdk/provider-media-understanding`, and
* `wednesdayai/plugin-sdk/testing` from test files only. Importing it from production code is
  forbidden because the jiti manifest entrypoint never loads it in production.
  The legacy `openclaw/plugin-sdk` specifier and its subpaths still load (ADR 2057).

The bare package root `openclaw` and `openclaw/cli-entry` appear in the root `package.json`
`exports` map, but they are not part of the allowed plugin surface; importing either one from an
extension is a violation. A "test file" here means a file whose name ends in `.test.ts`,
`.test.tsx`, `.test-harness.ts`, `.shared-test.ts`, `.test-utils.ts` or `.e2e-harness.ts`, or any
file inside a `__tests__` directory.

Deep relative imports into `src/` resolve inside the monorepo but crash in the installed
package, which ships `dist/` only. The gate is
`pnpm lint:extensions:no-private-imports` (`scripts/check-extension-imports.ts`), part of
`pnpm check`. Violations print one line each:

```text theme={"dark"}
<file>:<line>: <rule>: "<specifier>" -> <target>
```

Rule ids:

* `relative-outside-package` — a relative import leaves the extension package (test files may
  still deep-import `src/` when their file is in the documented allowlist).
* `core-internal-package-path` — a `openclaw/...` or `wednesdayai/...` import that is not one of
  the allowed plugin-sdk subpaths above.
* `testing-subpath-in-production` — `wednesdayai/plugin-sdk/testing` imported from a production
  file instead of a test file.
* `stale-allowlist-entry` — an allowlist entry whose file no longer deep-imports `src/`, so the
  exception can be deleted.

## Lazy imports

Plugins load from TypeScript source through jiti, which hands a second concurrent `import()` of
a module that is still evaluating a partially initialized copy. Calling into it throws
`ReferenceError: Cannot access '<name>' before initialization`. Wrap every relative dynamic
import in a module-level loader from `wednesdayai/plugin-sdk/lazy-runtime`:

```ts theme={"dark"}
import { createLazyRuntimeModule } from "wednesdayai/plugin-sdk/lazy-runtime";

const loadSend = createLazyRuntimeModule(() => import("./send.js"));

export async function send(text: string) {
  return (await loadSend()).sendMessage(text);
}
```

The loader caches the module, retries after a failed load, and runs one first load at a time
per process. Never use top-level `await` in a plugin module: a module that awaited a loader while
it was being evaluated would wait on itself.

The gate is `pnpm lint:extensions:no-bare-lazy-import`
(`scripts/check-extension-lazy-imports.ts`), part of `pnpm check`. Rule ids:

* `bare-relative-dynamic-import` — a `./` or `../` `import()` that is not the direct argument of
  `createLazyRuntimeModule(() => import(...))`.
* `top-level-await` — an `await` or `for await` outside any function.

Test files are exempt.

## Changing a contract

To change a public contract surface:

1. Edit the type.
2. Run `pnpm contracts:update` to regenerate `src/plugin-sdk/contract-surface.json`.
3. Bump the version constant in `src/plugins/contract-versions.ts`: minor bump for additive-only
   changes, major bump for breaking changes.
4. Commit the updated `src/plugin-sdk/contract-surface.json` with your change.

`pnpm lint:contracts:surface` (`scripts/check-contract-surface.ts`) inside `pnpm check` diffs the
committed snapshot against the merge base with the PR base branch (the first parent on a push
build) and the latest release tag — true only because the CI `check` job checks out full history
(`fetch-depth: 0`); do not reduce that checkout depth, or the gate silently degrades to a
base-tip comparison. The script accepts only `--update` and `--base-ref <ref>`: a missing
`--base-ref` value, or a value that is itself a flag, and any unknown argument are a usage
error, never a silent fallback to the default base. It fails CI with:

* `snapshot.stale` — `src/plugin-sdk/contract-surface.json` does not match the generated
  snapshot. Fix: run `pnpm contracts:update` and commit the result.
* `base.unresolved` — the base snapshot cannot be read at all. The check fails rather than
  passing silently; a base branch that simply does not carry the snapshot yet is only a notice.
* `version.bump-required` — the surface changed but the contract version constant did not.
  Fix: bump the constant (minor for additive changes).
* `version.major-bump-required` — the change is breaking but the constant kept its major.
  Fix: bump the major.
* `version.decreased` — the constant went down relative to the base branch's snapshot. Fix:
  restore or correctly bump the version.
* `contract.removed` — a contract id disappeared from the snapshot. Fix: reinstate it or record
  the removal with a major bump and a released `@deprecated` alias
  (see [Renaming and removing](#renaming-and-removing)).
* `payload.untyped` — a member newly typed as an open `Record<string, unknown>` (see
  [What the snapshot tracks](#what-the-snapshot-tracks)).

### What the snapshot tracks

The snapshot is deliberately shallow: per entry it records only its presence, whether it is
optional, its direction, its deprecation marker, and the entry's printed type text, with two
exceptions: an anonymous object property that gets flattened into dotted child entries records a
marker instead of its own text (its children carry the shape), and a non-enumerable type text
longer than 240 characters is stored as a `sha256:` digest (an enumerable one is flattened
instead; see below). A digest-stored entry whose text contains string literals also records them
as `literalRuns` — the sorted vocabulary per literal run, in position order — plus `shapeHash`, a
digest of the text with every literal run replaced by a placeholder, so the diff can prove a pure
vocabulary append without the digest pre-image (runs compare positionally, so one union narrowing
while another grows is still breaking). Four positions never count as vocabulary, in short texts or
recorded evidence: template-literal text (quoted fragments there are static content, not union
members); the argument lists of `Record`, `Pick`, `Omit`, and `Exclude` (key and subtraction
sets, where a growing union adds or removes properties); a literal carrying the array postfix
(the `"b"[]` arm of `"a" | "b"[]` is its own alternative, not another run member); and
conditional-type operands (`T extends "a" ? …` — the inline form of `Exclude`). Edits in those
positions flip the elided shape and keep the conservative classification. For generic interfaces, classes and type aliases
the declaration's type-parameter list — constraints and defaults included — is appended to the
recorded text (`Box<T> { value: T; } <T>`), because the printed type alone drops them; this
closes the generic-type-alias known limit in ADR 0117. A member whose type is a named object type
declared in this repository (an alias or interface outside `node_modules`, not a class, not a root)
is flattened into dotted child entries like an anonymous object, so removing a member inside it
demands a major bump of the contract that references it. Types from dependencies and the
TypeScript library (`Date`, arrays) stay nominal, and so does any type whose declaration carries
the JSDoc tag `@contractNominal <reason>`: `OpenClawConfig` does, because config keys are
versioned by the config schema and the `sdk` contract tracks the `OpenClawConfig` export itself.
The test-only `wednesdayai/plugin-sdk/testing` subpath is deliberately excluded from the `sdk`
contract.

A member typed as an open record (`Record<string, unknown>`, `{ [key: string]: unknown }` or an
alias of either) is recorded with `untyped: true`, because its keys cannot be diffed. Typing a
new member that way fails the check with `payload.untyped`. Fix: give it a typed shape, or tag the
property `/** @openPayload <reason> */` when its keys are deliberately opaque. Open records that
already existed are listed in a grandfathered notice on every run.

When an entry's printed text is opaque (past the 240-char digest cap) but the shape behind it is
enumerable, the generator records that shape as dotted per-member entries and marks the parent
with a stable marker (`object`, or `object <config>` such as `object $strict` for a zod object
schema, so a strictness change diffs) — for provided object-shaped types and for zod object schemas
(the config keys under `TtsConfigSchema` and friends), where member optionality comes from the
zod `ZodOptional`/`ZodDefault` wrappers and nested `ZodObject` shapes flatten to the same depth
cap as anonymous types. Introducing that recording changed the emitted type text, so it shipped
with a `typeTextVersion` bump: snapshots recorded before it are not compared text for text (the
notice reports the skip). Entry keys, optionality, deprecation and direction are still compared,
so removals and optionality regressions stay breaking. A same-key retype or signature change is
not detected on the run that crosses the version bump.

Zod library types are recorded by their resolved class name plus authored type arguments, wherever
they appear: `ZodEnum<{ allowlist: "allowlist"; open: "open"; }>`,
`(schema: ZodType<unknown, unknown>): …`. zod's derived `*Internals` arguments and the class's own
methods are left out. A zod release that only changes the library's API, or how it aliases
`ZodTypeAny`, is therefore not a contract change, while an authored change such as a new enum
option still diffs. This recording shipped with `typeTextVersion` 8.

## Renaming and removing

Config keys, CLI flags and SDK exports are never removed immediately; the same discipline
applies to kernel contract entries. The flow:

1. Add the new name.
2. Keep the old name with a `/** @deprecated Use <new> */` marker and ship the whole change as a
   minor bump.
3. Wait one release cycle so a released snapshot carries the deprecated alias.
4. Remove the old name with a major bump.

CI enforces the alias requirement through `deprecation.alias-release-required`: a removed entry
must have shipped `@deprecated` in the latest release tag's snapshot, otherwise the removal is
rejected. Two key shapes are exempt because nobody authors them and so nobody can deprecate
them: hook-name literal entries (`PluginHookName|"message_received"`, including dotted literals
like `PluginHookName|"context.collect"`) and generated union-constituent keys
(`<Root>|kind="a".member`, `<Root>|m:<digest>.member`, `<Root>|v:<digest>`, `<Root>|<n>.member`),
whose prefix changes whenever that constituent's shape changes. Both still require the major bump
when an entry disappears, and ordinary payload properties are never exempt.

See the general policy in [Release](https://docs.wednesdayai.dev/next/developers/contributing/release.md#deprecation-policy).


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