@canonmsg/backend-contracts 4.0.0 → 5.0.0

package/README.md

@@ -0,0 +1,41 @@
+# @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`](https://www.npmjs.com/package/@canonmsg/agent-sdk); if you are binding Canon's verbs into a model runtime, you want [`@canonmsg/agent-tools`](https://www.npmjs.com/package/@canonmsg/agent-tools). Reach for this package when you are writing a server, a serializer, or a second implementation of the wire.
+
+## Install
+
+```sh
+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 — sixteen 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.
+
+```ts
+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 and contact requests.** The participation evaluator the stream service runs before dispatching a turn, and the contact-request serializer both sides validate against.
+
+**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](https://canonmail.com/agents/contracts)

package/dist/agentBehaviorPolicy.js

@@ -52,16 +52,9 @@ function resolveGroupMentionRequirement(input) {
         && typeof input.requireMentionForGroupReplies !== 'boolean') {
         throw new Error('requireMentionForGroupReplies must be a boolean');
     }
-    if (input.requireMentionForGroupAgentReplies !== undefined
-        && typeof input.requireMentionForGroupAgentReplies !== 'boolean') {
-        throw new Error('requireMentionForGroupAgentReplies must be a boolean');
-    }
     if (typeof input.requireMentionForGroupReplies === 'boolean') {
         return input.requireMentionForGroupReplies;
     }
-    if (typeof input.requireMentionForGroupAgentReplies === 'boolean') {
-        return input.requireMentionForGroupAgentReplies;
-    }
     return undefined;
 }
 export function parseAgentBehaviorSettings(raw) {
@@ -104,9 +97,7 @@ export function normalizeStoredAgentBehaviorPolicy(raw) {
             : {}),
         ...(typeof raw.requireMentionForGroupReplies === 'boolean'
             ? { requireMentionForGroupReplies: raw.requireMentionForGroupReplies }
-            : typeof raw.requireMentionForGroupAgentReplies === 'boolean'
-                ? { requireMentionForGroupReplies: raw.requireMentionForGroupAgentReplies }
-                : {}),
+            : {}),
         ...(typeof raw.maxConsecutiveAgentTurns === 'number' || raw.maxConsecutiveAgentTurns === null
             ? { maxConsecutiveAgentTurns: raw.maxConsecutiveAgentTurns }
             : {}),

package/dist/canon-verbs.schema.json

@@ -153,7 +153,7 @@
     },
     "messageOptions": {
       "type": "object",
-      "description": "Message composition options (mirrors POST /messages/send). Deliberately absent: contact_card contentType (use share_contact) and forwarded/forwardedFrom (forwarding stays host/REST-mediated; /messages/forward is not a v1 verb).",
+      "description": "Message composition options (mirrors POST /messages/send). Deliberately absent: contact_card contentType (use share_contact) and forwarded/forwardedFrom (forwarding has its own verb — use forward, not send_to).",
       "additionalProperties": false,
       "properties": {
         "messageId": {
@@ -661,7 +661,7 @@
       }
     },
     "send_to_result": {
-      "description": "Canonical outcome vocabulary. Legacy binding drift documented in CANON_VERB_BINDINGS (hermes 'opened' -> messaged without messageId; hermes 'denied' -> blocked).",
+      "description": "Canonical outcome vocabulary. Legacy binding drift documented in docs/design/verb-bindings.md (hermes 'opened' -> messaged without messageId; hermes 'denied' -> blocked).",
       "oneOf": [
         {
           "type": "object",

package/dist/cjs/agentBehaviorPolicy.js

@@ -62,16 +62,9 @@ function resolveGroupMentionRequirement(input) {
         && typeof input.requireMentionForGroupReplies !== 'boolean') {
         throw new Error('requireMentionForGroupReplies must be a boolean');
     }
-    if (input.requireMentionForGroupAgentReplies !== undefined
-        && typeof input.requireMentionForGroupAgentReplies !== 'boolean') {
-        throw new Error('requireMentionForGroupAgentReplies must be a boolean');
-    }
     if (typeof input.requireMentionForGroupReplies === 'boolean') {
         return input.requireMentionForGroupReplies;
     }
-    if (typeof input.requireMentionForGroupAgentReplies === 'boolean') {
-        return input.requireMentionForGroupAgentReplies;
-    }
     return undefined;
 }
 function parseAgentBehaviorSettings(raw) {
@@ -114,9 +107,7 @@ function normalizeStoredAgentBehaviorPolicy(raw) {
             : {}),
         ...(typeof raw.requireMentionForGroupReplies === 'boolean'
             ? { requireMentionForGroupReplies: raw.requireMentionForGroupReplies }
-            : typeof raw.requireMentionForGroupAgentReplies === 'boolean'
-                ? { requireMentionForGroupReplies: raw.requireMentionForGroupAgentReplies }
-                : {}),
+            : {}),
         ...(typeof raw.maxConsecutiveAgentTurns === 'number' || raw.maxConsecutiveAgentTurns === null
             ? { maxConsecutiveAgentTurns: raw.maxConsecutiveAgentTurns }
             : {}),

package/dist/cjs/runtimeCardStorage.js

@@ -5,9 +5,6 @@ function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 function decodeStoredRuntimeCard(input) {
-    if (isRecord(input.runtimeCard)) {
-        return input.runtimeCard;
-    }
     if (typeof input.runtimeCardJson !== 'string' || !input.runtimeCardJson.trim()) {
         return undefined;
     }

package/dist/cjs/verbContract.js

@@ -23,8 +23,9 @@
  *
  * Scope note: this module DESCRIBES the contract (canonical shapes + the
  * server-enforced limits, with enforcement sites cited). Enforcement itself
- * stays where it runs today — functions/src. Server-side verb endpoints that
- * validate against these schemas are a planned follow-up.
+ * stays where it runs today — functions/src. The server-side verb endpoint that
+ * validates against these schemas is live: POST /agent/verbs/:verb
+ * (functions/src/index.ts, functions/src/api/agentVerbs.ts).
  *
  * Normativity: the JSON Schemas in `verbSchemas.ts` (and the emitted
  * canon-verbs.schema.json) are the normative contract. The TypeScript types

package/dist/cjs/verbSchemas.js

@@ -125,7 +125,7 @@ const messageOptionsDef = {
     type: 'object',
     description: 'Message composition options (mirrors POST /messages/send). Deliberately absent: '
         + 'contact_card contentType (use share_contact) and forwarded/forwardedFrom '
-        + '(forwarding stays host/REST-mediated; /messages/forward is not a v1 verb).',
+        + '(forwarding has its own verb — use forward, not send_to).',
     additionalProperties: false,
     properties: {
         messageId: REF('messageId'),
@@ -404,7 +404,7 @@ const send_to_input = {
     dependentRequired: { selfContext: ['sourceConversationId'] },
 };
 const send_to_result = {
-    description: 'Canonical outcome vocabulary. Legacy binding drift documented in CANON_VERB_BINDINGS '
+    description: 'Canonical outcome vocabulary. Legacy binding drift documented in docs/design/verb-bindings.md '
         + "(hermes 'opened' -> messaged without messageId; hermes 'denied' -> blocked).",
     oneOf: [
         {

package/dist/runtimeCardStorage.d.ts

@@ -1,4 +1,3 @@
 export declare function decodeStoredRuntimeCard(input: {
-    runtimeCard?: unknown;
     runtimeCardJson?: unknown;
 }): Record<string, unknown> | undefined;

package/dist/runtimeCardStorage.js

@@ -2,9 +2,6 @@ function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 export function decodeStoredRuntimeCard(input) {
-    if (isRecord(input.runtimeCard)) {
-        return input.runtimeCard;
-    }
     if (typeof input.runtimeCardJson !== 'string' || !input.runtimeCardJson.trim()) {
         return undefined;
     }

package/dist/verbContract.d.ts

@@ -22,8 +22,9 @@
  *
  * Scope note: this module DESCRIBES the contract (canonical shapes + the
  * server-enforced limits, with enforcement sites cited). Enforcement itself
- * stays where it runs today — functions/src. Server-side verb endpoints that
- * validate against these schemas are a planned follow-up.
+ * stays where it runs today — functions/src. The server-side verb endpoint that
+ * validates against these schemas is live: POST /agent/verbs/:verb
+ * (functions/src/index.ts, functions/src/api/agentVerbs.ts).
  *
  * Normativity: the JSON Schemas in `verbSchemas.ts` (and the emitted
  * canon-verbs.schema.json) are the normative contract. The TypeScript types

package/dist/verbContract.js

@@ -22,8 +22,9 @@
  *
  * Scope note: this module DESCRIBES the contract (canonical shapes + the
  * server-enforced limits, with enforcement sites cited). Enforcement itself
- * stays where it runs today — functions/src. Server-side verb endpoints that
- * validate against these schemas are a planned follow-up.
+ * stays where it runs today — functions/src. The server-side verb endpoint that
+ * validates against these schemas is live: POST /agent/verbs/:verb
+ * (functions/src/index.ts, functions/src/api/agentVerbs.ts).
  *
  * Normativity: the JSON Schemas in `verbSchemas.ts` (and the emitted
  * canon-verbs.schema.json) are the normative contract. The TypeScript types

package/dist/verbSchemas.js

@@ -120,7 +120,7 @@ const messageOptionsDef = {
     type: 'object',
     description: 'Message composition options (mirrors POST /messages/send). Deliberately absent: '
         + 'contact_card contentType (use share_contact) and forwarded/forwardedFrom '
-        + '(forwarding stays host/REST-mediated; /messages/forward is not a v1 verb).',
+        + '(forwarding has its own verb — use forward, not send_to).',
     additionalProperties: false,
     properties: {
         messageId: REF('messageId'),
@@ -399,7 +399,7 @@ const send_to_input = {
     dependentRequired: { selfContext: ['sourceConversationId'] },
 };
 const send_to_result = {
-    description: 'Canonical outcome vocabulary. Legacy binding drift documented in CANON_VERB_BINDINGS '
+    description: 'Canonical outcome vocabulary. Legacy binding drift documented in docs/design/verb-bindings.md '
         + "(hermes 'opened' -> messaged without messageId; hermes 'denied' -> blocked).",
     oneOf: [
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -43,7 +43,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@canonmsg/rich-cards": "^0.8.5",
+    "@canonmsg/rich-cards": "^0.8.7",
     "@types/node": "^22.0.0",
     "ajv": "^8.20.0",
     "typescript": "~5.7.0",