@canonmsg/backend-contracts 6.4.0 → 7.0.0

package/README.md

@@ -16,7 +16,7 @@ Node.js 18+. Ships both ESM and CommonJS builds — Cloud Functions consume the
 
 ## What is in it
 
-**The verb contract.** `canon.verbs.v1` (`verbContract.ts`) is the plaintext *intent* schema — eighteen 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.
+**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.
 
 ```ts
 import {

package/dist/canon-verb-wire.schema.json

@@ -33,7 +33,6 @@
         "list_contacts",
         "list_contact_requests",
         "list_conversations",
-        "cancel_contact_request",
         "no_reply"
       ]
     },
@@ -428,10 +427,6 @@
             "null"
           ]
         },
-        "sourceMessageId": {
-          "type": "string",
-          "minLength": 1
-        },
         "turnSemantics": {
           "enum": [
             "progress",
@@ -513,7 +508,6 @@
             "list_contacts",
             "list_contact_requests",
             "list_conversations",
-            "cancel_contact_request",
             "no_reply"
           ]
         },

package/dist/canon-verbs.schema.json

@@ -1767,26 +1767,11 @@
     "list_contact_requests_input": {
       "type": "object",
       "additionalProperties": false,
-      "properties": {
-        "direction": {
-          "enum": [
-            "inbound",
-            "outbound"
-          ]
-        },
-        "includeResolved": {
-          "type": "boolean"
-        },
-        "limit": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 100
-        }
-      }
+      "properties": {}
     },
     "list_contact_requests_result": {
       "type": "object",
-      "description": "Contact requests, newest first, capped at 100. Defaults to pending inbound; requesters use direction=outbound with includeResolved=true to recover lifecycle state. Items are SerializedContactRequest (backend-contracts contactRequest.ts).",
+      "description": "Pending inbound requests, newest first, capped at 100. Items are SerializedContactRequest (backend-contracts contactRequest.ts). Read-only awareness: approval routes to the owner; agents cannot approve/reject.",
       "required": [
         "requests"
       ],
@@ -1801,8 +1786,7 @@
               "requesterId",
               "targetId",
               "status",
-              "kind",
-              "phase"
+              "kind"
             ],
             "additionalProperties": true,
             "properties": {
@@ -1823,8 +1807,7 @@
                   "pending",
                   "approved",
                   "rejected",
-                  "expired",
-                  "cancelled"
+                  "expired"
                 ]
               },
               "kind": {
@@ -1833,17 +1816,6 @@
                   "group_invite"
                 ]
               },
-              "phase": {
-                "enum": [
-                  "awaiting_owner",
-                  "starting",
-                  "connected",
-                  "rejected",
-                  "expired",
-                  "cancelled",
-                  "failed"
-                ]
-              },
               "message": {
                 "type": [
                   "string",
@@ -1977,35 +1949,6 @@
         }
       }
     },
-    "cancel_contact_request_input": {
-      "type": "object",
-      "required": [
-        "requestId"
-      ],
-      "additionalProperties": false,
-      "properties": {
-        "requestId": {
-          "type": "string",
-          "pattern": "^[A-Za-z0-9_.:-]{1,160}$"
-        }
-      }
-    },
-    "cancel_contact_request_result": {
-      "type": "object",
-      "required": [
-        "status",
-        "requestId"
-      ],
-      "additionalProperties": true,
-      "properties": {
-        "status": {
-          "const": "cancelled"
-        },
-        "requestId": {
-          "type": "string"
-        }
-      }
-    },
     "no_reply_input": {
       "type": "object",
       "description": "End this turn without posting anything to the conversation. Nothing is rendered and no other member or agent is triggered.",

package/dist/cjs/communication.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCommunicationRule = readCommunicationRule;
+exports.parseDirectConversationSelection = parseDirectConversationSelection;
+/** Missing or invalid policy never widens access. */
+function readCommunicationRule(value) {
+    if (value === 'open' || value === 'approval-required' || value === 'closed') {
+        return value;
+    }
+    // Existing owner-only records have the same outsider-facing meaning as
+    // closed; the agent owner bypass remains a separate server-side rule.
+    if (value === 'owner-only')
+        return 'closed';
+    return 'approval-required';
+}
+function parseDirectConversationSelection(value) {
+    if (value == null)
+        return { mode: 'latest_or_new' };
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('selection must be an object');
+    }
+    const record = value;
+    if (record.mode === 'latest_or_new' || record.mode === 'new') {
+        return { mode: record.mode };
+    }
+    if (record.mode === 'specific') {
+        const conversationId = typeof record.conversationId === 'string'
+            ? record.conversationId.trim()
+            : '';
+        if (!conversationId)
+            throw new Error('selection.conversationId is required');
+        return { mode: 'specific', conversationId };
+    }
+    throw new Error('selection.mode is invalid');
+}

package/dist/cjs/contactRequest.js

@@ -1,29 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readContactRequestRequirements = readContactRequestRequirements;
 exports.readGroupInviteRequirements = readGroupInviteRequirements;
-exports.deriveContactRequestPhase = deriveContactRequestPhase;
 exports.serializeContactRequest = serializeContactRequest;
-function readContactRequestRequirements(value) {
+function readGroupInviteRequirements(value) {
     const record = isRecord(value) ? value : null;
     if (typeof record?.policyApproval !== 'boolean'
         || typeof record.ownerSessionSetup !== 'boolean') {
-        throw new TypeError('Invalid contact request requirements');
+        throw new TypeError('Invalid group invite requirements');
     }
     return {
         policyApproval: record.policyApproval,
         ownerSessionSetup: record.ownerSessionSetup,
     };
 }
-/** Backward-compatible parser retained for existing group invite clients. */
-function readGroupInviteRequirements(value) {
-    try {
-        return readContactRequestRequirements(value);
-    }
-    catch {
-        throw new TypeError('Invalid group invite requirements');
-    }
-}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -41,36 +30,12 @@ function normalizeStatus(value) {
     if (value === 'pending'
         || value === 'approved'
         || value === 'rejected'
-        || value === 'expired'
-        || value === 'cancelled') {
+        || value === 'expired') {
         return value;
     }
     return 'pending';
 }
-function deriveContactRequestPhase(data) {
-    const status = data.status;
-    const openingStatus = data.openingMessageStatus;
-    let phase;
-    if (status === 'cancelled')
-        phase = 'cancelled';
-    else if (status === 'rejected')
-        phase = 'rejected';
-    else if (status === 'expired')
-        phase = 'expired';
-    else if (status === 'delivery_failed' || openingStatus === 'failed')
-        phase = 'failed';
-    else if (status === 'approved')
-        phase = 'connected';
-    else if (status === 'delivery_pending'
-        || openingStatus === 'ready'
-        || openingStatus === 'delivering'
-        || openingStatus === 'retryable')
-        phase = 'starting';
-    else
-        phase = 'awaiting_owner';
-    return phase;
-}
-function serializeContactRequest(requestId, data, options = {}) {
+function serializeContactRequest(requestId, data) {
     if (typeof data.approverId !== 'string' || data.approverId.length === 0) {
         return null;
     }
@@ -127,34 +92,20 @@ function serializeContactRequest(requestId, data, options = {}) {
         message: null,
         status: normalizeStatus(data.status),
         kind: kindValue,
-        phase: deriveContactRequestPhase(data),
         createdAt: normalizeTimestamp(data.createdAt),
         resolvedAt: normalizeTimestamp(data.resolvedAt),
         expiresAt: normalizeTimestamp(data.expiresAt),
     };
-    if (groupContext || kindValue === 'dm') {
+    if (groupContext) {
         let requirements;
         try {
-            requirements = data.requirements === undefined && kindValue === 'dm'
-                ? { policyApproval: true, ownerSessionSetup: false }
-                : readContactRequestRequirements(data.requirements);
+            requirements = readGroupInviteRequirements(data.requirements);
         }
         catch {
             return null;
         }
-        payload.requirements = requirements;
-    }
-    if (groupContext)
         payload.groupContext = groupContext;
-    if (options.audience === 'requester') {
-        if (typeof data.sourceConversationId === 'string' && data.sourceConversationId.length > 0) {
-            payload.sourceConversationId = data.sourceConversationId;
-        }
-        if (payload.phase === 'connected'
-            && typeof data.openingMessageConversationId === 'string'
-            && data.openingMessageConversationId.length > 0) {
-            payload.conversationId = data.openingMessageConversationId;
-        }
+        payload.requirements = requirements;
     }
     if (data.targetUserType === 'ai_agent') {
         payload.targetOwnerId = data.targetOwnerId;

package/dist/cjs/index.js

@@ -29,6 +29,7 @@ __exportStar(require("./verbContract.js"), exports);
 __exportStar(require("./verbSchemas.js"), exports);
 __exportStar(require("./verbWire.js"), exports);
 __exportStar(require("./accessPolicy.js"), exports);
+__exportStar(require("./communication.js"), exports);
 __exportStar(require("./apiErrors.js"), exports);
 __exportStar(require("./firestoreValues.js"), exports);
 __exportStar(require("./moderation.js"), exports);

package/dist/cjs/verbContract.js

@@ -206,7 +206,6 @@ exports.CANON_VERB_NAMES = [
     'list_contacts',
     'list_contact_requests',
     'list_conversations',
-    'cancel_contact_request',
     'no_reply',
 ];
 exports.VERB_NATIVE_METADATA_KEYS = [

package/dist/cjs/verbSchemas.js

@@ -1004,17 +1004,13 @@ const list_contacts_result = {
 const list_contact_requests_input = {
     type: 'object',
     additionalProperties: false,
-    properties: {
-        direction: { enum: ['inbound', 'outbound'] },
-        includeResolved: { type: 'boolean' },
-        limit: { type: 'integer', minimum: 1, maximum: 100 },
-    },
+    properties: {},
 };
 const list_contact_requests_result = {
     type: 'object',
-    description: 'Contact requests, newest first, capped at 100. Defaults to pending inbound; '
-        + 'requesters use direction=outbound with includeResolved=true to recover lifecycle state. '
-        + 'Items are SerializedContactRequest (backend-contracts contactRequest.ts).',
+    description: 'Pending inbound requests, newest first, capped at 100. Items are '
+        + 'SerializedContactRequest (backend-contracts contactRequest.ts). Read-only awareness: '
+        + "approval routes to the owner; agents cannot approve/reject.",
     required: ['requests'],
     additionalProperties: true,
     properties: {
@@ -1022,26 +1018,15 @@ const list_contact_requests_result = {
             type: 'array',
             items: {
                 type: 'object',
-                required: ['id', 'requesterId', 'targetId', 'status', 'kind', 'phase'],
+                required: ['id', 'requesterId', 'targetId', 'status', 'kind'],
                 additionalProperties: true,
                 properties: {
                     id: { type: 'string' },
                     requesterId: { type: 'string' },
                     requesterName: { type: 'string' },
                     targetId: { type: 'string' },
-                    status: { enum: ['pending', 'approved', 'rejected', 'expired', 'cancelled'] },
+                    status: { enum: ['pending', 'approved', 'rejected', 'expired'] },
                     kind: { enum: ['dm', 'group_invite'] },
-                    phase: {
-                        enum: [
-                            'awaiting_owner',
-                            'starting',
-                            'connected',
-                            'rejected',
-                            'expired',
-                            'cancelled',
-                            'failed',
-                        ],
-                    },
                     message: { type: ['string', 'null'] },
                     createdAt: { type: ['string', 'null'] },
                     expiresAt: { type: ['string', 'null'] },
@@ -1050,23 +1035,6 @@ const list_contact_requests_result = {
         },
     },
 };
-const cancel_contact_request_input = {
-    type: 'object',
-    required: ['requestId'],
-    additionalProperties: false,
-    properties: {
-        requestId: { type: 'string', pattern: verbContract_js_1.VERB_ID_PATTERNS.runtimeId },
-    },
-};
-const cancel_contact_request_result = {
-    type: 'object',
-    required: ['status', 'requestId'],
-    additionalProperties: true,
-    properties: {
-        status: { const: 'cancelled' },
-        requestId: { type: 'string' },
-    },
-};
 const list_conversations_input = {
     type: 'object',
     additionalProperties: false,
@@ -1206,8 +1174,6 @@ exports.CANON_VERBS_JSON_SCHEMA = {
         list_contact_requests_result,
         list_conversations_input,
         list_conversations_result,
-        cancel_contact_request_input,
-        cancel_contact_request_result,
         no_reply_input,
         no_reply_result,
     },

package/dist/cjs/verbWire.js

@@ -118,7 +118,6 @@ exports.VERB_WIRE_ENVELOPE_FIELDS = {
     list_contacts: { required: [], optional: [] },
     list_contact_requests: { required: [], optional: [] },
     list_conversations: { required: [], optional: ['limit'] },
-    cancel_contact_request: { required: ['requestId'], optional: [] },
     no_reply: { required: [], optional: ['conversationId', 'messageId'] },
 };
 // ---------------------------------------------------------------------------
@@ -160,7 +159,6 @@ const wireTurnDef = {
     additionalProperties: false,
     properties: {
         turnId: { type: ['string', 'null'] },
-        sourceMessageId: { type: 'string', minLength: 1 },
         turnSemantics: { enum: ['progress', 'turn_complete', 'control'] },
         deliveryIntent: { enum: ['queue', 'interrupt', 'interleave', 'stop'] },
         replyBehavior: { enum: ['allow_auto_reply', 'suppress_auto_reply'] },
@@ -286,13 +284,7 @@ exports.CANON_VERB_WIRE_JSON_SCHEMA = {
 // ---------------------------------------------------------------------------
 // Intent <-> wire projection (json codec)
 // ---------------------------------------------------------------------------
-const TURN_KEYS = [
-    'turnId',
-    'sourceMessageId',
-    'turnSemantics',
-    'deliveryIntent',
-    'replyBehavior',
-];
+const TURN_KEYS = ['turnId', 'turnSemantics', 'deliveryIntent', 'replyBehavior'];
 function splitTurnMetadata(metadata) {
     if (!metadata || typeof metadata !== 'object')
         return { turn: undefined, rest: undefined };
@@ -477,25 +469,14 @@ function projectVerbIntentToWire(verb, intent, options) {
             envelope = compact({ conversationId: input.conversationId });
             break;
         }
-        case 'list_contacts': {
-            break;
-        }
+        case 'list_contacts':
         case 'list_contact_requests': {
-            value = compact({
-                direction: input.direction,
-                includeResolved: input.includeResolved,
-                limit: input.limit,
-            });
             break;
         }
         case 'list_conversations': {
             envelope = compact({ limit: input.limit });
             break;
         }
-        case 'cancel_contact_request': {
-            envelope = compact({ requestId: input.requestId });
-            break;
-        }
         case 'no_reply': {
             envelope = compact({ conversationId: input.conversationId, messageId: input.messageId });
             value = compact({ reason: input.reason });
@@ -634,17 +615,10 @@ function mergeVerbWireToIntent(request) {
         case 'leave_conversation':
             return compact({ conversationId: envelope.conversationId });
         case 'list_contacts':
-            return {};
         case 'list_contact_requests':
-            return compact({
-                direction: value.direction,
-                includeResolved: value.includeResolved,
-                limit: value.limit,
-            });
+            return {};
         case 'list_conversations':
             return compact({ limit: envelope.limit });
-        case 'cancel_contact_request':
-            return compact({ requestId: envelope.requestId });
         case 'no_reply':
             return compact({ conversationId: envelope.conversationId, messageId: envelope.messageId, reason: value.reason });
     }

package/dist/communication.d.ts

@@ -0,0 +1,91 @@
+/** The deliberately small policy vocabulary for principal communication. */
+export type CommunicationRule = 'open' | 'approval-required' | 'closed';
+/** Missing or invalid policy never widens access. */
+export declare function readCommunicationRule(value: unknown): CommunicationRule;
+/** Canon conversation selection is principal-neutral; a conversation is a runtime session boundary. */
+export type DirectConversationSelection = {
+    mode: 'latest_or_new';
+} | {
+    mode: 'new';
+} | {
+    mode: 'specific';
+    conversationId: string;
+};
+export type CommunicateInput = {
+    action: 'message_existing';
+    conversationId: string;
+    text: string;
+    messageId?: string;
+} | {
+    action: 'start_direct';
+    principalId: string;
+    text: string;
+    selection?: DirectConversationSelection;
+    messageId?: string;
+} | {
+    action: 'create_group';
+    name: string;
+    memberIds: string[];
+} | {
+    action: 'forward_message';
+    sourceConversationId: string;
+    targetConversationId: string;
+    messageId: string;
+    text?: string;
+};
+export type CommunicateResult = {
+    status: 'messaged';
+    conversationId: string;
+    messageId: string;
+    created?: boolean;
+    reused?: boolean;
+} | {
+    status: 'requested' | 'pending';
+    requestId: string;
+} | {
+    status: 'created';
+    conversationId: string;
+    added: string[];
+    pending: Array<{
+        userId: string;
+        requestId: string;
+        requirements: {
+            policyApproval: boolean;
+            ownerSessionSetup: boolean;
+        };
+    }>;
+    skipped: Array<{
+        userId: string;
+        reason: string;
+    }>;
+} | {
+    status: 'forwarded';
+    messageId: string;
+    targetConversationId: string;
+} | {
+    status: 'blocked' | 'unavailable';
+    reason: string;
+};
+/** Principal-neutral app/SDK command. Humans may open a composer before sending. */
+export interface StartDirectInput {
+    targetUserId: string;
+    opener?: {
+        text: string;
+        messageId?: string;
+    } | null;
+    selection?: DirectConversationSelection;
+}
+export type StartDirectResult = {
+    status: 'opened' | 'messaged';
+    conversationId: string;
+    messageId?: string;
+    created?: boolean;
+    reused?: boolean;
+} | {
+    status: 'requested' | 'pending';
+    requestId: string;
+} | {
+    status: 'blocked' | 'unavailable';
+    reason: string;
+};
+export declare function parseDirectConversationSelection(value: unknown): DirectConversationSelection;

package/dist/communication.js

@@ -0,0 +1,31 @@
+/** Missing or invalid policy never widens access. */
+export function readCommunicationRule(value) {
+    if (value === 'open' || value === 'approval-required' || value === 'closed') {
+        return value;
+    }
+    // Existing owner-only records have the same outsider-facing meaning as
+    // closed; the agent owner bypass remains a separate server-side rule.
+    if (value === 'owner-only')
+        return 'closed';
+    return 'approval-required';
+}
+export function parseDirectConversationSelection(value) {
+    if (value == null)
+        return { mode: 'latest_or_new' };
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('selection must be an object');
+    }
+    const record = value;
+    if (record.mode === 'latest_or_new' || record.mode === 'new') {
+        return { mode: record.mode };
+    }
+    if (record.mode === 'specific') {
+        const conversationId = typeof record.conversationId === 'string'
+            ? record.conversationId.trim()
+            : '';
+        if (!conversationId)
+            throw new Error('selection.conversationId is required');
+        return { mode: 'specific', conversationId };
+    }
+    throw new Error('selection.mode is invalid');
+}

package/dist/contactRequest.d.ts

@@ -1,18 +1,12 @@
-export type SerializedContactRequestStatus = 'pending' | 'approved' | 'rejected' | 'expired' | 'cancelled';
-export type ContactRequestLifecyclePhase = 'awaiting_owner' | 'starting' | 'connected' | 'rejected' | 'expired' | 'cancelled' | 'failed';
+export type SerializedContactRequestStatus = 'pending' | 'approved' | 'rejected' | 'expired';
 /**
- * Independent gates that must be satisfied before a pending contact request
- * can activate. DM introductions and group invites share this owner-review
- * vocabulary even though their activation pipelines remain separate.
+ * Independent gates that must be satisfied before a pending group invite can
+ * add its target.
  */
-export interface ContactRequestRequirements {
+export interface GroupInviteRequirements {
     policyApproval: boolean;
     ownerSessionSetup: boolean;
 }
-/** Backward-compatible name retained for existing group invite clients. */
-export type GroupInviteRequirements = ContactRequestRequirements;
-export declare function readContactRequestRequirements(value: unknown): ContactRequestRequirements;
-/** Backward-compatible parser retained for existing group invite clients. */
 export declare function readGroupInviteRequirements(value: unknown): GroupInviteRequirements;
 export interface SerializedContactRequest {
     id: string;
@@ -33,18 +27,10 @@ export interface SerializedContactRequest {
         conversationId: string;
         groupName: string | null;
     };
-    /** Present for group invites and setup/policy-aware DM introductions. */
-    requirements?: ContactRequestRequirements;
-    phase: ContactRequestLifecyclePhase;
-    /** Requester-only source lane for an opener-backed introduction. */
-    sourceConversationId?: string;
-    /** Requester-only destination, present after an opener-backed DM connects. */
-    conversationId?: string;
+    /** Present for group_invite payloads; omitted for DM requests. */
+    requirements?: GroupInviteRequirements;
     createdAt: string | null;
     resolvedAt?: string | null;
     expiresAt?: string | null;
 }
-export declare function deriveContactRequestPhase(data: Record<string, unknown>): ContactRequestLifecyclePhase;
-export declare function serializeContactRequest(requestId: string, data: Record<string, unknown>, options?: {
-    audience?: 'inbound' | 'requester';
-}): SerializedContactRequest | null;
+export declare function serializeContactRequest(requestId: string, data: Record<string, unknown>): SerializedContactRequest | null;

package/dist/contactRequest.js

@@ -1,23 +1,14 @@
-export function readContactRequestRequirements(value) {
+export function readGroupInviteRequirements(value) {
     const record = isRecord(value) ? value : null;
     if (typeof record?.policyApproval !== 'boolean'
         || typeof record.ownerSessionSetup !== 'boolean') {
-        throw new TypeError('Invalid contact request requirements');
+        throw new TypeError('Invalid group invite requirements');
     }
     return {
         policyApproval: record.policyApproval,
         ownerSessionSetup: record.ownerSessionSetup,
     };
 }
-/** Backward-compatible parser retained for existing group invite clients. */
-export function readGroupInviteRequirements(value) {
-    try {
-        return readContactRequestRequirements(value);
-    }
-    catch {
-        throw new TypeError('Invalid group invite requirements');
-    }
-}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -35,36 +26,12 @@ function normalizeStatus(value) {
     if (value === 'pending'
         || value === 'approved'
         || value === 'rejected'
-        || value === 'expired'
-        || value === 'cancelled') {
+        || value === 'expired') {
         return value;
     }
     return 'pending';
 }
-export function deriveContactRequestPhase(data) {
-    const status = data.status;
-    const openingStatus = data.openingMessageStatus;
-    let phase;
-    if (status === 'cancelled')
-        phase = 'cancelled';
-    else if (status === 'rejected')
-        phase = 'rejected';
-    else if (status === 'expired')
-        phase = 'expired';
-    else if (status === 'delivery_failed' || openingStatus === 'failed')
-        phase = 'failed';
-    else if (status === 'approved')
-        phase = 'connected';
-    else if (status === 'delivery_pending'
-        || openingStatus === 'ready'
-        || openingStatus === 'delivering'
-        || openingStatus === 'retryable')
-        phase = 'starting';
-    else
-        phase = 'awaiting_owner';
-    return phase;
-}
-export function serializeContactRequest(requestId, data, options = {}) {
+export function serializeContactRequest(requestId, data) {
     if (typeof data.approverId !== 'string' || data.approverId.length === 0) {
         return null;
     }
@@ -121,34 +88,20 @@ export function serializeContactRequest(requestId, data, options = {}) {
         message: null,
         status: normalizeStatus(data.status),
         kind: kindValue,
-        phase: deriveContactRequestPhase(data),
         createdAt: normalizeTimestamp(data.createdAt),
         resolvedAt: normalizeTimestamp(data.resolvedAt),
         expiresAt: normalizeTimestamp(data.expiresAt),
     };
-    if (groupContext || kindValue === 'dm') {
+    if (groupContext) {
         let requirements;
         try {
-            requirements = data.requirements === undefined && kindValue === 'dm'
-                ? { policyApproval: true, ownerSessionSetup: false }
-                : readContactRequestRequirements(data.requirements);
+            requirements = readGroupInviteRequirements(data.requirements);
         }
         catch {
             return null;
         }
-        payload.requirements = requirements;
-    }
-    if (groupContext)
         payload.groupContext = groupContext;
-    if (options.audience === 'requester') {
-        if (typeof data.sourceConversationId === 'string' && data.sourceConversationId.length > 0) {
-            payload.sourceConversationId = data.sourceConversationId;
-        }
-        if (payload.phase === 'connected'
-            && typeof data.openingMessageConversationId === 'string'
-            && data.openingMessageConversationId.length > 0) {
-            payload.conversationId = data.openingMessageConversationId;
-        }
+        payload.requirements = requirements;
     }
     if (data.targetUserType === 'ai_agent') {
         payload.targetOwnerId = data.targetOwnerId;

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export * from './verbContract.js';
 export * from './verbSchemas.js';
 export * from './verbWire.js';
 export * from './accessPolicy.js';
+export * from './communication.js';
 export * from './apiErrors.js';
 export * from './firestoreValues.js';
 export * from './moderation.js';

package/dist/index.js

@@ -13,6 +13,7 @@ export * from './verbContract.js';
 export * from './verbSchemas.js';
 export * from './verbWire.js';
 export * from './accessPolicy.js';
+export * from './communication.js';
 export * from './apiErrors.js';
 export * from './firestoreValues.js';
 export * from './moderation.js';

package/dist/verbContract.d.ts

@@ -42,7 +42,7 @@
  * `findVerbByteLimitViolations()` (or equivalent checks from the emitted
  * canon-verbs.limits.json) after schema validation.
  */
-import type { ContactRequestRequirements } from './contactRequest.js';
+import type { GroupInviteRequirements } from './contactRequest.js';
 /** Identifier for this contract document. */
 export declare const CANON_VERBS_SCHEMA_VERSION = "canon.verbs.v1";
 /** $id of the emitted JSON Schema bundle. */
@@ -184,7 +184,7 @@ export declare const VERB_RATE_LIMITS: {
 /** The one self-context type the platform accepts today. */
 export declare const SELF_CONTEXT_TYPE = "cross_session";
 /** Canonical verb names. */
-export declare const CANON_VERB_NAMES: readonly ["send_to", "request_input", "request_approval", "check_approval", "send_card", "request_card", "share_contact", "react", "forward", "create_group", "add_member", "remove_member", "leave_conversation", "list_contacts", "list_contact_requests", "list_conversations", "cancel_contact_request", "no_reply"];
+export declare const CANON_VERB_NAMES: readonly ["send_to", "request_input", "request_approval", "check_approval", "send_card", "request_card", "share_contact", "react", "forward", "create_group", "add_member", "remove_member", "leave_conversation", "list_contacts", "list_contact_requests", "list_conversations", "no_reply"];
 export type CanonVerbName = (typeof CANON_VERB_NAMES)[number];
 /** Private note-to-self attached to a cross-conversation send. */
 export interface VerbSelfContext {
@@ -268,7 +268,6 @@ export interface VerbMediaAttachment {
  */
 export interface VerbTurnMetadata {
     turnId?: string | null;
-    sourceMessageId?: string;
     turnSemantics?: 'progress' | 'turn_complete' | 'control';
     deliveryIntent?: 'queue' | 'interrupt' | 'interleave' | 'stop';
     replyBehavior?: 'allow_auto_reply' | 'suppress_auto_reply';
@@ -323,7 +322,7 @@ export type SendToResult = {
     selfContextId?: string;
     created?: boolean;
     reused?: boolean;
-    sessionSelection?: VerbSessionSelection['mode'];
+    sessionSelection?: string;
 } | {
     status: 'requested';
     requestId: string | null;
@@ -614,7 +613,7 @@ export interface CreateGroupInput {
 export interface PendingGroupInviteResult {
     userId: string;
     requestId: string;
-    requirements: ContactRequestRequirements;
+    requirements: GroupInviteRequirements;
 }
 export interface CreateGroupResult {
     status: 'created';
@@ -654,7 +653,7 @@ export type AddMemberResult = {
 } | {
     status: 'pending';
     requestId: string;
-    requirements: ContactRequestRequirements;
+    requirements: GroupInviteRequirements;
 };
 export interface RemoveMemberInput {
     conversationId: string;
@@ -681,26 +680,11 @@ export interface VerbContact {
 export interface ListContactsResult {
     contacts: VerbContact[];
 }
-export type ContactRequestListDirection = 'inbound' | 'outbound';
-export interface ListContactRequestsInput {
-    /** Defaults to inbound. Outbound is the reconnect/recovery surface. */
-    direction?: ContactRequestListDirection;
-    /** Include terminal and starting lifecycle states; default false. */
-    includeResolved?: boolean;
-    /** Newest-first result cap; default and maximum 100. */
-    limit?: number;
-}
-/** Items are SerializedContactRequest (contactRequest.ts), newest first, capped at 100. */
+export type ListContactRequestsInput = Record<string, never>;
+/** Items are SerializedContactRequest (contactRequest.ts) — pending inbound only, newest first, capped at 100. */
 export interface ListContactRequestsResult {
     requests: unknown[];
 }
-export interface CancelContactRequestInput {
-    requestId: string;
-}
-export interface CancelContactRequestResult {
-    status: 'cancelled';
-    requestId: string;
-}
 export interface ListConversationsInput {
     /** Optional client-side cap; the REST endpoint returns all memberships. */
     limit?: number;

package/dist/verbContract.js

@@ -200,7 +200,6 @@ export const CANON_VERB_NAMES = [
     'list_contacts',
     'list_contact_requests',
     'list_conversations',
-    'cancel_contact_request',
     'no_reply',
 ];
 export const VERB_NATIVE_METADATA_KEYS = [

package/dist/verbSchemas.d.ts

@@ -1615,19 +1615,7 @@ export declare const CANON_VERBS_JSON_SCHEMA: {
         readonly list_contact_requests_input: {
             readonly type: "object";
             readonly additionalProperties: false;
-            readonly properties: {
-                readonly direction: {
-                    readonly enum: readonly ["inbound", "outbound"];
-                };
-                readonly includeResolved: {
-                    readonly type: "boolean";
-                };
-                readonly limit: {
-                    readonly type: "integer";
-                    readonly minimum: 1;
-                    readonly maximum: 100;
-                };
-            };
+            readonly properties: {};
         };
         readonly list_contact_requests_result: {
             readonly type: "object";
@@ -1639,7 +1627,7 @@ export declare const CANON_VERBS_JSON_SCHEMA: {
                     readonly type: "array";
                     readonly items: {
                         readonly type: "object";
-                        readonly required: readonly ["id", "requesterId", "targetId", "status", "kind", "phase"];
+                        readonly required: readonly ["id", "requesterId", "targetId", "status", "kind"];
                         readonly additionalProperties: true;
                         readonly properties: {
                             readonly id: {
@@ -1655,14 +1643,11 @@ export declare const CANON_VERBS_JSON_SCHEMA: {
                                 readonly type: "string";
                             };
                             readonly status: {
-                                readonly enum: readonly ["pending", "approved", "rejected", "expired", "cancelled"];
+                                readonly enum: readonly ["pending", "approved", "rejected", "expired"];
                             };
                             readonly kind: {
                                 readonly enum: readonly ["dm", "group_invite"];
                             };
-                            readonly phase: {
-                                readonly enum: readonly ["awaiting_owner", "starting", "connected", "rejected", "expired", "cancelled", "failed"];
-                            };
                             readonly message: {
                                 readonly type: readonly ["string", "null"];
                             };
@@ -1756,30 +1741,6 @@ export declare const CANON_VERBS_JSON_SCHEMA: {
                 };
             };
         };
-        readonly cancel_contact_request_input: {
-            readonly type: "object";
-            readonly required: readonly ["requestId"];
-            readonly additionalProperties: false;
-            readonly properties: {
-                readonly requestId: {
-                    readonly type: "string";
-                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
-                };
-            };
-        };
-        readonly cancel_contact_request_result: {
-            readonly type: "object";
-            readonly required: readonly ["status", "requestId"];
-            readonly additionalProperties: true;
-            readonly properties: {
-                readonly status: {
-                    readonly const: "cancelled";
-                };
-                readonly requestId: {
-                    readonly type: "string";
-                };
-            };
-        };
         readonly no_reply_input: {
             readonly type: "object";
             readonly description: string;

package/dist/verbSchemas.js

@@ -999,17 +999,13 @@ const list_contacts_result = {
 const list_contact_requests_input = {
     type: 'object',
     additionalProperties: false,
-    properties: {
-        direction: { enum: ['inbound', 'outbound'] },
-        includeResolved: { type: 'boolean' },
-        limit: { type: 'integer', minimum: 1, maximum: 100 },
-    },
+    properties: {},
 };
 const list_contact_requests_result = {
     type: 'object',
-    description: 'Contact requests, newest first, capped at 100. Defaults to pending inbound; '
-        + 'requesters use direction=outbound with includeResolved=true to recover lifecycle state. '
-        + 'Items are SerializedContactRequest (backend-contracts contactRequest.ts).',
+    description: 'Pending inbound requests, newest first, capped at 100. Items are '
+        + 'SerializedContactRequest (backend-contracts contactRequest.ts). Read-only awareness: '
+        + "approval routes to the owner; agents cannot approve/reject.",
     required: ['requests'],
     additionalProperties: true,
     properties: {
@@ -1017,26 +1013,15 @@ const list_contact_requests_result = {
             type: 'array',
             items: {
                 type: 'object',
-                required: ['id', 'requesterId', 'targetId', 'status', 'kind', 'phase'],
+                required: ['id', 'requesterId', 'targetId', 'status', 'kind'],
                 additionalProperties: true,
                 properties: {
                     id: { type: 'string' },
                     requesterId: { type: 'string' },
                     requesterName: { type: 'string' },
                     targetId: { type: 'string' },
-                    status: { enum: ['pending', 'approved', 'rejected', 'expired', 'cancelled'] },
+                    status: { enum: ['pending', 'approved', 'rejected', 'expired'] },
                     kind: { enum: ['dm', 'group_invite'] },
-                    phase: {
-                        enum: [
-                            'awaiting_owner',
-                            'starting',
-                            'connected',
-                            'rejected',
-                            'expired',
-                            'cancelled',
-                            'failed',
-                        ],
-                    },
                     message: { type: ['string', 'null'] },
                     createdAt: { type: ['string', 'null'] },
                     expiresAt: { type: ['string', 'null'] },
@@ -1045,23 +1030,6 @@ const list_contact_requests_result = {
         },
     },
 };
-const cancel_contact_request_input = {
-    type: 'object',
-    required: ['requestId'],
-    additionalProperties: false,
-    properties: {
-        requestId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
-    },
-};
-const cancel_contact_request_result = {
-    type: 'object',
-    required: ['status', 'requestId'],
-    additionalProperties: true,
-    properties: {
-        status: { const: 'cancelled' },
-        requestId: { type: 'string' },
-    },
-};
 const list_conversations_input = {
     type: 'object',
     additionalProperties: false,
@@ -1201,8 +1169,6 @@ export const CANON_VERBS_JSON_SCHEMA = {
         list_contact_requests_result,
         list_conversations_input,
         list_conversations_result,
-        cancel_contact_request_input,
-        cancel_contact_request_result,
         no_reply_input,
         no_reply_result,
     },

package/dist/verbWire.d.ts

@@ -40,8 +40,6 @@ export type VerbWireBody = {
 /** Turn-protocol keys the server enforces on (subset of TurnMetadata). */
 export interface VerbWireTurn {
     turnId?: string | null;
-    /** Trusted message that initiated a host-bound owner turn. */
-    sourceMessageId?: string;
     turnSemantics?: 'progress' | 'turn_complete' | 'control';
     deliveryIntent?: 'queue' | 'interrupt' | 'interleave' | 'stop';
     replyBehavior?: 'allow_auto_reply' | 'suppress_auto_reply';
@@ -139,7 +137,7 @@ export declare const CANON_VERB_WIRE_JSON_SCHEMA: {
             readonly const: "canon.verb-wire.v1";
         };
         readonly verb: {
-            readonly enum: readonly ["send_to", "request_input", "request_approval", "check_approval", "send_card", "request_card", "share_contact", "react", "forward", "create_group", "add_member", "remove_member", "leave_conversation", "list_contacts", "list_contact_requests", "list_conversations", "cancel_contact_request", "no_reply"];
+            readonly enum: readonly ["send_to", "request_input", "request_approval", "check_approval", "send_card", "request_card", "share_contact", "react", "forward", "create_group", "add_member", "remove_member", "leave_conversation", "list_contacts", "list_contact_requests", "list_conversations", "no_reply"];
         };
         readonly envelope: {
             readonly $ref: "#/$defs/envelope";
@@ -466,10 +464,6 @@ export declare const CANON_VERB_WIRE_JSON_SCHEMA: {
                 readonly turnId: {
                     readonly type: readonly ["string", "null"];
                 };
-                readonly sourceMessageId: {
-                    readonly type: "string";
-                    readonly minLength: 1;
-                };
                 readonly turnSemantics: {
                     readonly enum: readonly ["progress", "turn_complete", "control"];
                 };
@@ -515,7 +509,7 @@ export declare const CANON_VERB_WIRE_JSON_SCHEMA: {
                     readonly const: "canon.verb-wire.v1";
                 };
                 readonly verb: {
-                    readonly enum: readonly ["send_to", "request_input", "request_approval", "check_approval", "send_card", "request_card", "share_contact", "react", "forward", "create_group", "add_member", "remove_member", "leave_conversation", "list_contacts", "list_contact_requests", "list_conversations", "cancel_contact_request", "no_reply"];
+                    readonly enum: readonly ["send_to", "request_input", "request_approval", "check_approval", "send_card", "request_card", "share_contact", "react", "forward", "create_group", "add_member", "remove_member", "leave_conversation", "list_contacts", "list_contact_requests", "list_conversations", "no_reply"];
                 };
                 readonly result: {
                     readonly $ref: "#/$defs/body";

package/dist/verbWire.js

@@ -112,7 +112,6 @@ export const VERB_WIRE_ENVELOPE_FIELDS = {
     list_contacts: { required: [], optional: [] },
     list_contact_requests: { required: [], optional: [] },
     list_conversations: { required: [], optional: ['limit'] },
-    cancel_contact_request: { required: ['requestId'], optional: [] },
     no_reply: { required: [], optional: ['conversationId', 'messageId'] },
 };
 // ---------------------------------------------------------------------------
@@ -154,7 +153,6 @@ const wireTurnDef = {
     additionalProperties: false,
     properties: {
         turnId: { type: ['string', 'null'] },
-        sourceMessageId: { type: 'string', minLength: 1 },
         turnSemantics: { enum: ['progress', 'turn_complete', 'control'] },
         deliveryIntent: { enum: ['queue', 'interrupt', 'interleave', 'stop'] },
         replyBehavior: { enum: ['allow_auto_reply', 'suppress_auto_reply'] },
@@ -280,13 +278,7 @@ export const CANON_VERB_WIRE_JSON_SCHEMA = {
 // ---------------------------------------------------------------------------
 // Intent <-> wire projection (json codec)
 // ---------------------------------------------------------------------------
-const TURN_KEYS = [
-    'turnId',
-    'sourceMessageId',
-    'turnSemantics',
-    'deliveryIntent',
-    'replyBehavior',
-];
+const TURN_KEYS = ['turnId', 'turnSemantics', 'deliveryIntent', 'replyBehavior'];
 function splitTurnMetadata(metadata) {
     if (!metadata || typeof metadata !== 'object')
         return { turn: undefined, rest: undefined };
@@ -471,25 +463,14 @@ export function projectVerbIntentToWire(verb, intent, options) {
             envelope = compact({ conversationId: input.conversationId });
             break;
         }
-        case 'list_contacts': {
-            break;
-        }
+        case 'list_contacts':
         case 'list_contact_requests': {
-            value = compact({
-                direction: input.direction,
-                includeResolved: input.includeResolved,
-                limit: input.limit,
-            });
             break;
         }
         case 'list_conversations': {
             envelope = compact({ limit: input.limit });
             break;
         }
-        case 'cancel_contact_request': {
-            envelope = compact({ requestId: input.requestId });
-            break;
-        }
         case 'no_reply': {
             envelope = compact({ conversationId: input.conversationId, messageId: input.messageId });
             value = compact({ reason: input.reason });
@@ -628,17 +609,10 @@ export function mergeVerbWireToIntent(request) {
         case 'leave_conversation':
             return compact({ conversationId: envelope.conversationId });
         case 'list_contacts':
-            return {};
         case 'list_contact_requests':
-            return compact({
-                direction: value.direction,
-                includeResolved: value.includeResolved,
-                limit: value.limit,
-            });
+            return {};
         case 'list_conversations':
             return compact({ limit: envelope.limit });
-        case 'cancel_contact_request':
-            return compact({ requestId: envelope.requestId });
         case 'no_reply':
             return compact({ conversationId: envelope.conversationId, messageId: envelope.messageId, reason: value.reason });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "6.4.0",
+  "version": "7.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.10.2",
+    "@canonmsg/rich-cards": "^0.10.3",
     "@types/node": "^22.0.0",
     "ajv": "^8.20.0",
     "typescript": "~5.7.0",