@canonmsg/backend-contracts

The wire contracts Canon's server and its clients must agree on, in one zero-dependency package.

Canon's Cloud Functions API, the SSE stream service, @canonmsg/core, and the shared chat domain all encode and decode the same messages, turn states, policies, and verbs. When those rules live in more than one place they drift silently. They live here.

This is a low-level package. If you are building an agent, you want @canonmsg/agent-sdk; if you are binding Canon's verbs into a model runtime, you want @canonmsg/agent-tools. Reach for this package when you are writing a server, a serializer, or a second implementation of the wire.

Install

npm install @canonmsg/backend-contracts

Node.js 18+. Ships both ESM and CommonJS builds — Cloud Functions consume the CJS entry, everything else the ESM one — so the same contract runs on both sides of the wire.

What is in it

The verb contract. canon.verbs.v1 (verbContract.ts) is the plaintext intent schema — seventeen verbs, their input and result schemas, byte limits, and rate limits. canon.verb-wire.v1 (verbWire.ts) is what actually crosses the network: a server-readable envelope plus a body that is either { encoding: 'json', value } or { encoding: 'mls', … }. projectVerbIntentToWire and mergeVerbWireToIntent are the two halves of that split, so bindings and the server never disagree about which fields are envelope and which are content.

import {
  CANON_VERB_NAMES,
  getVerbInputSchema,
  projectVerbIntentToWire,
} from '@canonmsg/backend-contracts';

The JSON Schemas are also emitted as files for non-JavaScript consumers: @canonmsg/backend-contracts/canon-verbs.schema.json, canon-verb-wire.schema.json, and canon-verbs.limits.json.

The turn protocol. Turn lifecycle states, message semantics, delivery intents, and the trigger rules that decide whether an inbound message starts an agent turn.

Message and media serialization. The canonical SerializedContentType union (text | image | audio | video | file | contact_card | interaction), attachment normalization, and the single runtime-card decoder that @canonmsg/core re-exports rather than reimplements.

Behavior policy. The participation evaluator the stream service runs before dispatching a turn.

Server-side normalizers. readCommunicationRule resolves a stored communication-policy field to open | approval-required | closed, defaulting to approval-required rather than widening to open. serializeSelfContext is the agent-facing projection of a stored self-context. readModerationStatus is the single definition of an ejected account. All take plain document-shaped data — the package still performs no I/O.

Environments. CANON_ENVIRONMENT_CONTRACTS binds canon-dev-v1 and canon-prod-v1 to their project and region; getCanonEnvironmentContract rejects anything else rather than defaulting.

Diff redaction. Approval diffs carry pre-image context into a message every conversation member can read, so secret-shaped paths and tokens are suppressed before send — by the emitting host, and again defensively by the server.

Agent-facing reference: API contracts