Versioned kernel contracts
The kernel exposes six versioned contracts. Each contract id names one public surface an extension builds against, versioned asmajor.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
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.
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?)andBusWorkDispatcherOptions.backend.release(workId, opts?)accept{ availableAt?: Date }: the released item returns topendingand is not claimable beforeavailableAt. Withoutopts, release behaves exactly as before.- Optional
claimDispatched(topic, consumerId, leaseMs)onBackboneand the bus-work backend claims only consumer-dispatchedagent.turnitems (Postgres only; absent elsewhere). - Session-run recovery modes gain
"lease"(visible throughPluginRuntime.sessions): runs executed by the runner consumer, which startup recovery skips because work-lease reclaim owns them.
Version semantics
Contract versions aremajor.minor strings. The policy is:
- Breaking (requires a major bump): removing an entry, adding a required member to an
implementedtype, changing a signature or type shape, or flipping a direction. - Additive (requires only a minor bump): new optional members, new members on a
providedtype, 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 byliteralRuns/shapeHashon digest-stored entries, or by the elided shape of a short text).
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).
Declaring what your plugin needs
The optionalcontracts 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):
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 providecontracts.<id> "<v>" is not a valid "major.minor" versionrequires <id> contract <M>.x (>= <v>), but host provides <host>requires <id> contract >= <v>, but host provides <host>
- At install:
src/plugins/install.tsrefuses the install with the error codeVERSION_INCOMPATIBLEand the messageplugin "<id>" is not compatible with this host: <reason>. Upgrade WednesdayAI and retry.An invalid version string is prefixed withinvalid contract version in <manifest>:. A malformedcontractsfield (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 messageinvalid contracts field in <manifest>: <error>.<manifest>is the filename actually read:wednesdayai.plugin.json, or the legacyopenclaw.plugin.jsonwhen that is the only file present. - At load:
src/plugins/manifest-registry.tsdrops the plugin and records an error diagnostic with the internal codePLUGIN_CONTRACT_INCOMPATIBLE(orPLUGIN_MANIFEST_INVALIDwhen the manifest fails to parse — including a malformedcontractsfield — or the declared version is not a validmajor.minorstring) and the messageplugin "<id>" <reason>. Config validation (src/config/validation.ts) turns every error-level manifest diagnostic into a config error atplugins.entries.<id>, soconfig validate,plugins listand 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.
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.
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— hooktimeoutMs, when set, is greater than 0.
checkDeliveryConformance):
delivery.mode.known—deliveryModeisdirect,gatewayorhybrid.delivery.direct.handlers— non-gateway delivery provides bothsendTextandsendMedia(otherwisecreatePluginHandlerreturns 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 validtextChunkLimitdoes not scale the probe allocation.delivery.send-text.result— the optional sendText probe resolves to a result object with a non-emptymessageIdand the adapter’s ownchannel.
checkIngressConformance):
ingress.sender.identity— sender identity fields passvalidateSenderIdentity.ingress.body.strings—Body,BodyForAgentandBodyForCommandsare strings.ingress.group.conversation-label— group/channel context carries a conversation label (ConversationLabelor fields that derive one).
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(aliaswednesdayai/plugin-sdk), and- its exported
./plugin-sdk/*subpaths, for examplewednesdayai/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-searchandwednesdayai/plugin-sdk/provider-media-understanding, and wednesdayai/plugin-sdk/testingfrom test files only. Importing it from production code is forbidden because the jiti manifest entrypoint never loads it in production. The legacyopenclaw/plugin-sdkspecifier and its subpaths still load (ADR 2057).
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:
relative-outside-package— a relative import leaves the extension package (test files may still deep-importsrc/when their file is in the documented allowlist).core-internal-package-path— aopenclaw/...orwednesdayai/...import that is not one of the allowed plugin-sdk subpaths above.testing-subpath-in-production—wednesdayai/plugin-sdk/testingimported from a production file instead of a test file.stale-allowlist-entry— an allowlist entry whose file no longer deep-importssrc/, so the exception can be deleted.
Lazy imports
Plugins load from TypeScript source through jiti, which hands a second concurrentimport() 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:
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 ofcreateLazyRuntimeModule(() => import(...)).top-level-await— anawaitorfor awaitoutside any function.
Changing a contract
To change a public contract surface:- Edit the type.
- Run
pnpm contracts:updateto regeneratesrc/plugin-sdk/contract-surface.json. - Bump the version constant in
src/plugins/contract-versions.ts: minor bump for additive-only changes, major bump for breaking changes. - Commit the updated
src/plugin-sdk/contract-surface.jsonwith 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.jsondoes not match the generated snapshot. Fix: runpnpm contracts:updateand 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@deprecatedalias (see Renaming and removing).payload.untyped— a member newly typed as an openRecord<string, unknown>(see 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 asha256: 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:- Add the new name.
- Keep the old name with a
/** @deprecated Use <new> */marker and ship the whole change as a minor bump. - Wait one release cycle so a released snapshot carries the deprecated alias.
- Remove the old name with a major bump.
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.