Contract tests

Contract tests (plugin and channel shape)

Contract tests verify that every registered plugin and channel conforms to its interface contract. They iterate over all discovered plugins and run a suite of shape and behavior assertions. The default pnpm test unit lane intentionally skips these shared seam and smoke files; run the contract commands explicitly when you touch shared channel or provider surfaces.

Commands

• All contracts: pnpm test:contracts
• Channel contracts only: pnpm test:contracts:channels
• Provider contracts only: pnpm test:contracts:plugins

Channel contracts

Located in src/channels/plugins/contracts/*.contract.test.ts. Current top-level categories:

• channel-catalog - bundled/registry channel catalog entry metadata
• plugin (registry-backed, sharded) - basic plugin registration shape
• surfaces-only (registry-backed, sharded) - per-surface shape checks for actions, setup, status, outbound, messaging, threading, directory, and gateway
• session-binding (registry-backed) - session binding behavior
• outbound-payload - message payload structure and normalization
• group-policy (fallback) - default group policy enforcement per channel
• threading (registry-backed, sharded) - thread id handling
• directory (registry-backed, sharded) - directory/roster API
• registry and plugins-core.* - channel plugin registry, loader, and config-write authorization internals

Inbound dispatch-capture and outbound-payload harness helpers used by these suites are exposed internally through src/plugin-sdk/channel-contract-testing.ts (npm-excluded, not a public SDK subpath); there is no standalone inbound.contract.test.ts file in this directory.

Provider contracts

Located in src/plugins/contracts/*.contract.test.ts. Current categories include:

• shape - plugin manifest, API, and runtime export shape
• plugin-registration (+ parallel) - manifest registration cases
• package-manifest - package manifest requirements
• loader - plugin loader setup/teardown behavior
• registry - plugin contract registry contents and lookup
• providers - shared provider behavior across bundled providers, plus web-search providers
• auth-choice - auth choice metadata and setup behavior
• provider-catalog-deprecation - deprecated provider catalog metadata
• wizard.choice-resolution, wizard.model-picker, wizard.setup-options - provider setup wizard contracts
• embedding-provider, memory-embedding-provider, web-fetch-provider, tts - capability-specific provider contracts
• session-actions, session-attachments, session-entry-projection - plugin-owned session state contracts
• scheduled-turns - plugin scheduled turn metadata and timestamp bounds
• host-hooks, run-context-lifecycle, runtime-import-side-effects, runtime-seams - plugin host/runtime lifecycle and import-boundary contracts
• extension-runtime-dependencies - runtime dependency placement for extensions

When to run

• After changing plugin-sdk exports or subpaths
• After adding or modifying a channel or provider plugin
• After refactoring plugin registration or discovery

Contract tests run in CI and do not require real API keys.