@canonmsg/backend-contracts 2.1.0 → 2.3.0

package/dist/verbWire.js

@@ -0,0 +1,628 @@
+/**
+ * Canon verb WIRE contract — `canon.verb-wire.v1`.
+ *
+ * The verb INTENT contract (`canon.verbs.v1`, verbContract.ts) is the
+ * plaintext semantic input used locally by tools, MCP, SDK, and adapters. It
+ * is NOT the remote wire schema. What crosses the network is this contract:
+ * an authenticated public ENVELOPE (the routing/policy metadata the server
+ * may read, authorize, and enforce on) plus a BODY that is either plaintext
+ * JSON (temporary/plaintext conversations) or MLS ciphertext (encrypted
+ * conversations). See docs/design/e2ee-mls.md §1-2.
+ *
+ *   one developer-facing API  ≠  one plaintext wire schema
+ *
+ * Server endpoints (/agent/verbs/*) implement THIS contract with the `json`
+ * codec initially; MLS lands later as a codec swap, not an API change. In
+ * `json` mode the server may additionally read `body.value` to execute
+ * legacy behavior (validation, snapshot building); in `mls` mode the
+ * envelope is everything it will ever see.
+ *
+ * The intent→wire projection (and its inverse, used by the server executor
+ * in json mode) is defined here so every binding and the server agree on
+ * exactly which intent fields are envelope (server-visible) vs body
+ * (content). The split follows the 2026-07-12 plaintext audit: closed
+ * enums, ids, deadlines, and turn-protocol keys are envelope; free text,
+ * cards, prompts, questions, tool names/summaries, details, diffs, and
+ * self-contexts are body.
+ */
+import { CANON_VERB_NAMES, VERB_ID_PATTERNS, VERB_LIMITS, } from './verbContract.js';
+export const CANON_VERB_WIRE_SCHEMA_VERSION = 'canon.verb-wire.v1';
+export const CANON_VERB_WIRE_SCHEMA_ID = 'https://canonmsg.com/schemas/canon.verb-wire.v1.json';
+// ---------------------------------------------------------------------------
+// Which envelope fields each verb uses (documentation + validation aid)
+// ---------------------------------------------------------------------------
+export const VERB_WIRE_ENVELOPE_FIELDS = {
+    send_to: {
+        required: [],
+        optional: [
+            'conversationId',
+            'targetUserId',
+            'canonContactId',
+            'sourceConversationId',
+            'sessionSelection',
+            'sessionConfig',
+            'idempotencyKey',
+            'replyTo',
+            'replyToPosition',
+            'mentions',
+            'turn',
+        ],
+    },
+    request_input: {
+        required: ['conversationId'],
+        optional: ['requestId', 'kind', 'sensitive', 'responseUserId', 'expiresAt', 'native', 'turn'],
+    },
+    request_approval: {
+        required: ['conversationId'],
+        optional: [
+            'requestId',
+            'mode',
+            'riskLevel',
+            'risk',
+            'category',
+            'allowSessionRule',
+            'responseUserId',
+            'expiresAt',
+            'native',
+            'runtimeId',
+            'turn',
+        ],
+    },
+    check_approval: {
+        required: ['requestId'],
+        optional: ['conversationId'],
+    },
+    send_card: {
+        required: ['conversationId'],
+        optional: ['requestId', 'native', 'runtimeId', 'turn'],
+    },
+    request_card: {
+        required: ['conversationId'],
+        optional: ['requestId', 'responseUserId', 'expiresAt', 'native', 'runtimeId', 'turn'],
+    },
+    share_contact: {
+        required: ['conversationId', 'contactUserId'],
+        optional: ['idempotencyKey'],
+    },
+    react: {
+        required: ['conversationId', 'messageId'],
+        optional: [],
+    },
+    forward: {
+        required: ['sourceConversationId', 'conversationId', 'messageId'],
+        optional: [],
+    },
+    create_group: {
+        required: ['memberIds'],
+        optional: [],
+    },
+    add_member: {
+        required: ['conversationId', 'targetUserId'],
+        optional: [],
+    },
+    remove_member: {
+        required: ['conversationId', 'targetUserId'],
+        optional: [],
+    },
+    leave_conversation: {
+        required: ['conversationId'],
+        optional: [],
+    },
+    list_contacts: { required: [], optional: [] },
+    list_contact_requests: { required: [], optional: [] },
+    list_conversations: { required: [], optional: ['limit'] },
+};
+// ---------------------------------------------------------------------------
+// JSON Schema
+// ---------------------------------------------------------------------------
+const wireBodyDef = {
+    description: 'The verb body: plaintext JSON for temporary/plaintext conversations, MLS '
+        + 'ciphertext for encrypted ones. In json mode the server may read value to '
+        + 'execute legacy behavior; in mls mode it is opaque.',
+    oneOf: [
+        {
+            type: 'object',
+            required: ['encoding', 'value'],
+            additionalProperties: false,
+            properties: {
+                encoding: { const: 'json' },
+                value: { type: 'object' },
+            },
+        },
+        {
+            type: 'object',
+            required: ['encoding', 'epoch', 'ciphertext', 'aadHash'],
+            additionalProperties: false,
+            properties: {
+                encoding: { const: 'mls' },
+                epoch: { type: 'integer', minimum: 0 },
+                ciphertext: { type: 'string', minLength: 1 },
+                aadHash: {
+                    type: 'string',
+                    minLength: 1,
+                    description: 'Hash binding the envelope (AAD) to the ciphertext.',
+                },
+            },
+        },
+    ],
+};
+const wireTurnDef = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        turnId: { type: ['string', 'null'] },
+        turnSemantics: { enum: ['progress', 'turn_complete', 'control'] },
+        deliveryIntent: { enum: ['queue', 'interrupt', 'interleave', 'stop'] },
+        replyBehavior: { enum: ['allow_auto_reply', 'suppress_auto_reply'] },
+    },
+};
+const wireEnvelopeDef = {
+    type: 'object',
+    description: 'Authenticated public envelope: routing/policy metadata only, never '
+        + 'content. Per-verb field discipline: VERB_WIRE_ENVELOPE_FIELDS.',
+    additionalProperties: false,
+    properties: {
+        conversationId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+        targetUserId: { type: 'string', minLength: 1 },
+        canonContactId: { type: 'string', minLength: 1 },
+        sourceConversationId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+        contactUserId: { type: 'string', minLength: 1 },
+        requestId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+        responseUserId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+        expiresAt: { type: 'integer', minimum: 0 },
+        mode: { enum: ['blocking', 'detached'] },
+        kind: { enum: ['clarify', 'sudo', 'secret'] },
+        sensitive: { type: 'boolean' },
+        allowSessionRule: { type: 'boolean' },
+        riskLevel: { enum: ['normal', 'destructive'] },
+        risk: { enum: ['low', 'normal', 'high', 'destructive'] },
+        category: {
+            enum: ['command', 'file', 'network', 'browser', 'mcp', 'plugin', 'canon', 'tool'],
+        },
+        sessionSelection: {
+            oneOf: [
+                {
+                    type: 'object',
+                    required: ['mode'],
+                    additionalProperties: false,
+                    properties: { mode: { enum: ['new', 'continue_latest', 'continue_or_create'] } },
+                },
+                {
+                    type: 'object',
+                    required: ['mode', 'conversationId'],
+                    additionalProperties: false,
+                    properties: {
+                        mode: { const: 'specific' },
+                        conversationId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+                    },
+                },
+            ],
+        },
+        sessionConfig: { type: ['object', 'null'] },
+        idempotencyKey: {
+            type: 'string',
+            pattern: VERB_ID_PATTERNS.runtimeId,
+            not: { pattern: '^(\\.{1,2}|__.*__)$' },
+        },
+        messageId: { type: 'string', minLength: 1 },
+        replyTo: { type: 'string' },
+        replyToPosition: { type: 'integer' },
+        mentions: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Plaintext by decision D3 (routing + mention-piercing pushes).',
+        },
+        memberIds: {
+            type: 'array',
+            items: { type: 'string' },
+            minItems: 1,
+            description: 'Group-membership routing ids (create_group). Plaintext like mentions '
+                + '(D3 rationale) but a distinct field — membership operations must not '
+                + 'overload the mention slot.',
+        },
+        turn: { $ref: '#/$defs/turn' },
+        native: { type: 'object' },
+        runtimeId: { type: 'string', maxLength: VERB_LIMITS.turnIdChars },
+        limit: { type: 'integer', minimum: 1 },
+    },
+};
+export const CANON_VERB_WIRE_JSON_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: CANON_VERB_WIRE_SCHEMA_ID,
+    title: 'Canon Verb Wire v1',
+    description: 'The remote wire contract for agent verbs: authenticated envelope + '
+        + 'json-or-mls body. The semantic intent contract (canon.verbs.v1) is '
+        + 'local; this is what crosses the network.',
+    type: 'object',
+    required: ['wire', 'verb', 'envelope', 'body'],
+    additionalProperties: false,
+    properties: {
+        wire: { const: CANON_VERB_WIRE_SCHEMA_VERSION },
+        verb: { enum: [...CANON_VERB_NAMES] },
+        envelope: { $ref: '#/$defs/envelope' },
+        body: { $ref: '#/$defs/body' },
+    },
+    $defs: {
+        body: wireBodyDef,
+        envelope: wireEnvelopeDef,
+        turn: wireTurnDef,
+        accepted: {
+            type: 'object',
+            required: ['status', 'requestId'],
+            additionalProperties: true,
+            properties: {
+                status: { const: 'accepted' },
+                requestId: { type: 'string' },
+                expiresAt: { type: 'integer' },
+                messageId: { type: 'string' },
+                responseUserId: { type: 'string' },
+                interactive: { type: 'boolean' },
+            },
+        },
+        response: {
+            type: 'object',
+            required: ['wire', 'verb', 'result'],
+            additionalProperties: true,
+            properties: {
+                wire: { const: CANON_VERB_WIRE_SCHEMA_VERSION },
+                verb: { enum: [...CANON_VERB_NAMES] },
+                result: { $ref: '#/$defs/body' },
+            },
+        },
+    },
+};
+// ---------------------------------------------------------------------------
+// Intent <-> wire projection (json codec)
+// ---------------------------------------------------------------------------
+const TURN_KEYS = ['turnId', 'turnSemantics', 'deliveryIntent', 'replyBehavior'];
+function splitTurnMetadata(metadata) {
+    if (!metadata || typeof metadata !== 'object')
+        return { turn: undefined, rest: undefined };
+    const turn = {};
+    const rest = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        if (TURN_KEYS.includes(key))
+            turn[key] = value;
+        else
+            rest[key] = value;
+    }
+    return {
+        turn: Object.keys(turn).length ? turn : undefined,
+        rest: Object.keys(rest).length ? rest : undefined,
+    };
+}
+function compact(record) {
+    const out = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/**
+ * Resolve a relative deadline to the absolute epoch-ms the wire carries.
+ * Deterministic: callers pass `now` (the runtime library uses Date.now()).
+ */
+function resolveExpiresAt(intent, now) {
+    if (typeof intent.expiresAt === 'number')
+        return intent.expiresAt;
+    if (typeof intent.timeoutMs === 'number')
+        return now + intent.timeoutMs;
+    return undefined;
+}
+/**
+ * Project a plaintext verb intent (canon.verbs.v1 input) into its wire form
+ * with the `json` codec: envelope = the routing/policy fields the server may
+ * see; body.value = the content fields (what MLS later encrypts).
+ *
+ * The inverse is mergeVerbWireToIntent; round-tripping normalizes deadlines
+ * to absolute expiresAt but is otherwise lossless.
+ */
+export function projectVerbIntentToWire(verb, intent, options) {
+    const input = intent;
+    let envelope = {};
+    let value = {};
+    switch (verb) {
+        case 'send_to': {
+            const messageOptions = (input.messageOptions ?? {});
+            const { turn, rest } = splitTurnMetadata(messageOptions.metadata);
+            envelope = compact({
+                conversationId: input.targetConversationId,
+                targetUserId: input.targetUserId,
+                canonContactId: input.canonContactId,
+                sourceConversationId: input.sourceConversationId,
+                sessionSelection: input.sessionSelection,
+                sessionConfig: input.sessionConfig,
+                idempotencyKey: messageOptions.messageId,
+                replyTo: messageOptions.replyTo,
+                replyToPosition: messageOptions.replyToPosition,
+                mentions: messageOptions.mentions,
+                turn,
+            });
+            const contentOptions = compact({
+                contentType: messageOptions.contentType,
+                attachments: messageOptions.attachments,
+                metadata: rest,
+            });
+            value = compact({
+                text: input.text,
+                selfContext: input.selfContext,
+                requestMessage: input.requestMessage,
+                messageOptions: Object.keys(contentOptions).length ? contentOptions : undefined,
+            });
+            break;
+        }
+        case 'request_input': {
+            envelope = compact({
+                conversationId: input.conversationId,
+                requestId: input.inputId,
+                kind: input.kind,
+                sensitive: input.sensitive,
+                responseUserId: input.responseUserId,
+                expiresAt: resolveExpiresAt(input, options.now),
+                native: input.native,
+                turn: input.turnId !== undefined ? { turnId: input.turnId } : undefined,
+            });
+            value = compact({
+                title: input.title,
+                prompt: input.prompt,
+                choices: input.choices,
+                questions: input.questions,
+                secretName: input.secretName,
+            });
+            break;
+        }
+        case 'request_approval': {
+            envelope = compact({
+                conversationId: input.conversationId,
+                requestId: input.approvalId,
+                mode: input.mode,
+                riskLevel: input.riskLevel,
+                risk: input.risk,
+                category: input.category,
+                allowSessionRule: input.allowSessionRule,
+                responseUserId: input.responseUserId,
+                expiresAt: resolveExpiresAt(input, options.now),
+                native: input.native,
+                runtimeId: input.runtimeId,
+                turn: input.turnId !== undefined ? { turnId: input.turnId } : undefined,
+            });
+            value = compact({
+                toolName: input.toolName,
+                toolSummary: input.toolSummary,
+                details: input.details,
+                diff: input.diff,
+            });
+            break;
+        }
+        case 'check_approval': {
+            envelope = compact({
+                requestId: input.approvalId,
+                conversationId: input.conversationId,
+            });
+            break;
+        }
+        case 'send_card':
+        case 'request_card': {
+            envelope = compact({
+                conversationId: input.conversationId,
+                requestId: input.cardId,
+                responseUserId: verb === 'request_card' ? input.responseUserId : undefined,
+                expiresAt: verb === 'request_card' ? resolveExpiresAt(input, options.now) : undefined,
+                native: input.native,
+                runtimeId: input.runtimeId,
+                turn: input.turnId !== undefined ? { turnId: input.turnId } : undefined,
+            });
+            value = compact({ card: input.card });
+            break;
+        }
+        case 'share_contact': {
+            envelope = compact({
+                conversationId: input.conversationId,
+                contactUserId: input.contactUserId,
+                idempotencyKey: input.messageId,
+            });
+            value = compact({ text: input.text });
+            break;
+        }
+        case 'react': {
+            envelope = compact({
+                conversationId: input.conversationId,
+                messageId: input.messageId,
+            });
+            value = compact({ emoji: input.emoji });
+            break;
+        }
+        case 'forward': {
+            envelope = compact({
+                sourceConversationId: input.sourceConversationId,
+                conversationId: input.targetConversationId,
+                messageId: input.messageId,
+            });
+            value = compact({ text: input.text });
+            break;
+        }
+        case 'create_group': {
+            envelope = compact({ memberIds: input.memberIds });
+            value = compact({ name: input.name });
+            break;
+        }
+        case 'add_member':
+        case 'remove_member': {
+            envelope = compact({
+                conversationId: input.conversationId,
+                targetUserId: input.userId,
+            });
+            break;
+        }
+        case 'leave_conversation': {
+            envelope = compact({ conversationId: input.conversationId });
+            break;
+        }
+        case 'list_contacts':
+        case 'list_contact_requests': {
+            break;
+        }
+        case 'list_conversations': {
+            envelope = compact({ limit: input.limit });
+            break;
+        }
+    }
+    return {
+        wire: CANON_VERB_WIRE_SCHEMA_VERSION,
+        verb,
+        envelope,
+        body: { encoding: 'json', value },
+    };
+}
+/**
+ * Reconstruct the plaintext verb intent from a json-codec wire request — the
+ * server executor's half of the seam. Throws if the body is not json.
+ */
+export function mergeVerbWireToIntent(request) {
+    if (request.body.encoding !== 'json') {
+        throw new Error(`cannot merge encoding '${request.body.encoding}' to a plaintext intent — mls bodies are opaque to the server`);
+    }
+    const envelope = request.envelope;
+    const value = request.body.value;
+    switch (request.verb) {
+        case 'send_to': {
+            const contentOptions = (value.messageOptions ?? {});
+            const metadata = compact({
+                ...(contentOptions.metadata ?? {}),
+                ...(envelope.turn ?? {}),
+            });
+            const messageOptions = compact({
+                messageId: envelope.idempotencyKey,
+                contentType: contentOptions.contentType,
+                attachments: contentOptions.attachments,
+                mentions: envelope.mentions,
+                replyTo: envelope.replyTo,
+                replyToPosition: envelope.replyToPosition,
+                metadata: Object.keys(metadata).length ? metadata : undefined,
+            });
+            return compact({
+                targetConversationId: envelope.conversationId,
+                targetUserId: envelope.targetUserId,
+                canonContactId: envelope.canonContactId,
+                sourceConversationId: envelope.sourceConversationId,
+                sessionSelection: envelope.sessionSelection,
+                sessionConfig: envelope.sessionConfig,
+                text: value.text,
+                selfContext: value.selfContext,
+                requestMessage: value.requestMessage,
+                messageOptions: Object.keys(messageOptions).length ? messageOptions : undefined,
+            });
+        }
+        case 'request_input':
+            return compact({
+                conversationId: envelope.conversationId,
+                inputId: envelope.requestId,
+                kind: envelope.kind,
+                sensitive: envelope.sensitive,
+                responseUserId: envelope.responseUserId,
+                expiresAt: envelope.expiresAt,
+                native: envelope.native,
+                turnId: envelope.turn?.turnId ?? undefined,
+                title: value.title,
+                prompt: value.prompt,
+                choices: value.choices,
+                questions: value.questions,
+                secretName: value.secretName,
+            });
+        case 'request_approval':
+            return compact({
+                conversationId: envelope.conversationId,
+                approvalId: envelope.requestId,
+                mode: envelope.mode,
+                riskLevel: envelope.riskLevel,
+                risk: envelope.risk,
+                category: envelope.category,
+                allowSessionRule: envelope.allowSessionRule,
+                responseUserId: envelope.responseUserId,
+                expiresAt: envelope.expiresAt,
+                native: envelope.native,
+                runtimeId: envelope.runtimeId,
+                turnId: envelope.turn?.turnId ?? undefined,
+                toolName: value.toolName,
+                toolSummary: value.toolSummary,
+                details: value.details,
+                diff: value.diff,
+            });
+        case 'check_approval':
+            return compact({
+                approvalId: envelope.requestId,
+                conversationId: envelope.conversationId,
+            });
+        case 'send_card':
+        case 'request_card':
+            return compact({
+                conversationId: envelope.conversationId,
+                cardId: envelope.requestId,
+                responseUserId: envelope.responseUserId,
+                expiresAt: envelope.expiresAt,
+                native: envelope.native,
+                runtimeId: envelope.runtimeId,
+                turnId: envelope.turn?.turnId ?? undefined,
+                card: value.card,
+            });
+        case 'share_contact':
+            return compact({
+                conversationId: envelope.conversationId,
+                contactUserId: envelope.contactUserId,
+                messageId: envelope.idempotencyKey,
+                text: value.text,
+            });
+        case 'react':
+            return compact({
+                conversationId: envelope.conversationId,
+                messageId: envelope.messageId,
+                emoji: value.emoji,
+            });
+        case 'forward':
+            return compact({
+                sourceConversationId: envelope.sourceConversationId,
+                targetConversationId: envelope.conversationId,
+                messageId: envelope.messageId,
+                text: value.text,
+            });
+        case 'create_group':
+            return compact({
+                name: value.name,
+                memberIds: envelope.memberIds,
+            });
+        case 'add_member':
+        case 'remove_member':
+            return compact({
+                conversationId: envelope.conversationId,
+                userId: envelope.targetUserId,
+            });
+        case 'leave_conversation':
+            return compact({ conversationId: envelope.conversationId });
+        case 'list_contacts':
+        case 'list_contact_requests':
+            return {};
+        case 'list_conversations':
+            return compact({ limit: envelope.limit });
+    }
+}
+/**
+ * Envelope discipline check: no field outside the verb's allowed set, all
+ * required fields present. Schema validation catches shape; this catches
+ * per-verb field misuse (a strict-envelope server rejects on it).
+ */
+export function findVerbWireEnvelopeViolations(verb, envelope) {
+    const spec = VERB_WIRE_ENVELOPE_FIELDS[verb];
+    const allowed = new Set([...spec.required, ...spec.optional]);
+    const violations = [];
+    for (const key of Object.keys(envelope)) {
+        if (!allowed.has(key))
+            violations.push(`envelope.${key} is not used by verb '${verb}'`);
+    }
+    for (const key of spec.required) {
+        if (envelope[key] === undefined) {
+            violations.push(`envelope.${key} is required for verb '${verb}'`);
+        }
+    }
+    return violations;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -10,13 +10,16 @@
       "import": "./dist/index.js",
       "require": "./dist/cjs/index.js",
       "types": "./dist/index.d.ts"
-    }
+    },
+    "./canon-verbs.schema.json": "./dist/canon-verbs.schema.json",
+    "./canon-verbs.limits.json": "./dist/canon-verbs.limits.json",
+    "./canon-verb-wire.schema.json": "./dist/canon-verb-wire.schema.json"
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').mkdirSync('dist/cjs',{recursive:true}); require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({type:'commonjs'}))\"",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').mkdirSync('dist/cjs',{recursive:true}); require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({type:'commonjs'}))\" && node scripts/emit-verb-schemas.mjs",
     "dev": "tsc -p tsconfig.json --watch",
     "test": "vitest run",
     "prepack": "npm run build"
@@ -40,7 +43,9 @@
     "access": "public"
   },
   "devDependencies": {
+    "@canonmsg/rich-cards": "^0.8.2",
     "@types/node": "^22.0.0",
+    "ajv": "^8.20.0",
     "typescript": "~5.7.0",
     "vitest": "^4.1.8"
   },