@canonmsg/backend-contracts 6.3.0 → 6.4.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 — 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.
+**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.
 
 ```ts
 import {

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

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

package/dist/canon-verbs.schema.json

@@ -1767,11 +1767,26 @@
     "list_contact_requests_input": {
       "type": "object",
       "additionalProperties": false,
-      "properties": {}
+      "properties": {
+        "direction": {
+          "enum": [
+            "inbound",
+            "outbound"
+          ]
+        },
+        "includeResolved": {
+          "type": "boolean"
+        },
+        "limit": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100
+        }
+      }
     },
     "list_contact_requests_result": {
       "type": "object",
-      "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.",
+      "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).",
       "required": [
         "requests"
       ],
@@ -1786,7 +1801,8 @@
               "requesterId",
               "targetId",
               "status",
-              "kind"
+              "kind",
+              "phase"
             ],
             "additionalProperties": true,
             "properties": {
@@ -1807,7 +1823,8 @@
                   "pending",
                   "approved",
                   "rejected",
-                  "expired"
+                  "expired",
+                  "cancelled"
                 ]
               },
               "kind": {
@@ -1816,6 +1833,17 @@
                   "group_invite"
                 ]
               },
+              "phase": {
+                "enum": [
+                  "awaiting_owner",
+                  "starting",
+                  "connected",
+                  "rejected",
+                  "expired",
+                  "cancelled",
+                  "failed"
+                ]
+              },
               "message": {
                 "type": [
                   "string",
@@ -1949,6 +1977,35 @@
         }
       }
     },
+    "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/contactRequest.js

@@ -1,18 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.readContactRequestRequirements = readContactRequestRequirements;
 exports.readGroupInviteRequirements = readGroupInviteRequirements;
+exports.deriveContactRequestPhase = deriveContactRequestPhase;
 exports.serializeContactRequest = serializeContactRequest;
-function readGroupInviteRequirements(value) {
+function readContactRequestRequirements(value) {
     const record = isRecord(value) ? value : null;
     if (typeof record?.policyApproval !== 'boolean'
         || typeof record.ownerSessionSetup !== 'boolean') {
-        throw new TypeError('Invalid group invite requirements');
+        throw new TypeError('Invalid contact request 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);
 }
@@ -30,12 +41,36 @@ function normalizeStatus(value) {
     if (value === 'pending'
         || value === 'approved'
         || value === 'rejected'
-        || value === 'expired') {
+        || value === 'expired'
+        || value === 'cancelled') {
         return value;
     }
     return 'pending';
 }
-function serializeContactRequest(requestId, data) {
+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 = {}) {
     if (typeof data.approverId !== 'string' || data.approverId.length === 0) {
         return null;
     }
@@ -92,21 +127,35 @@ function serializeContactRequest(requestId, data) {
         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) {
+    if (groupContext || kindValue === 'dm') {
         let requirements;
         try {
-            requirements = readGroupInviteRequirements(data.requirements);
+            requirements = data.requirements === undefined && kindValue === 'dm'
+                ? { policyApproval: true, ownerSessionSetup: false }
+                : readContactRequestRequirements(data.requirements);
         }
         catch {
             return null;
         }
-        payload.groupContext = groupContext;
         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;
+        }
+    }
     if (data.targetUserType === 'ai_agent') {
         payload.targetOwnerId = data.targetOwnerId;
     }

package/dist/cjs/verbContract.js

@@ -206,6 +206,7 @@ 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,13 +1004,17 @@ const list_contacts_result = {
 const list_contact_requests_input = {
     type: 'object',
     additionalProperties: false,
-    properties: {},
+    properties: {
+        direction: { enum: ['inbound', 'outbound'] },
+        includeResolved: { type: 'boolean' },
+        limit: { type: 'integer', minimum: 1, maximum: 100 },
+    },
 };
 const list_contact_requests_result = {
     type: 'object',
-    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.",
+    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).',
     required: ['requests'],
     additionalProperties: true,
     properties: {
@@ -1018,15 +1022,26 @@ const list_contact_requests_result = {
             type: 'array',
             items: {
                 type: 'object',
-                required: ['id', 'requesterId', 'targetId', 'status', 'kind'],
+                required: ['id', 'requesterId', 'targetId', 'status', 'kind', 'phase'],
                 additionalProperties: true,
                 properties: {
                     id: { type: 'string' },
                     requesterId: { type: 'string' },
                     requesterName: { type: 'string' },
                     targetId: { type: 'string' },
-                    status: { enum: ['pending', 'approved', 'rejected', 'expired'] },
+                    status: { enum: ['pending', 'approved', 'rejected', 'expired', 'cancelled'] },
                     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'] },
@@ -1035,6 +1050,23 @@ 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,
@@ -1174,6 +1206,8 @@ 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,6 +118,7 @@ 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'] },
 };
 // ---------------------------------------------------------------------------
@@ -159,6 +160,7 @@ 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'] },
@@ -284,7 +286,13 @@ exports.CANON_VERB_WIRE_JSON_SCHEMA = {
 // ---------------------------------------------------------------------------
 // Intent <-> wire projection (json codec)
 // ---------------------------------------------------------------------------
-const TURN_KEYS = ['turnId', 'turnSemantics', 'deliveryIntent', 'replyBehavior'];
+const TURN_KEYS = [
+    'turnId',
+    'sourceMessageId',
+    'turnSemantics',
+    'deliveryIntent',
+    'replyBehavior',
+];
 function splitTurnMetadata(metadata) {
     if (!metadata || typeof metadata !== 'object')
         return { turn: undefined, rest: undefined };
@@ -469,14 +477,25 @@ function projectVerbIntentToWire(verb, intent, options) {
             envelope = compact({ conversationId: input.conversationId });
             break;
         }
-        case 'list_contacts':
+        case 'list_contacts': {
+            break;
+        }
         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 });
@@ -615,10 +634,17 @@ function mergeVerbWireToIntent(request) {
         case 'leave_conversation':
             return compact({ conversationId: envelope.conversationId });
         case 'list_contacts':
-        case 'list_contact_requests':
             return {};
+        case 'list_contact_requests':
+            return compact({
+                direction: value.direction,
+                includeResolved: value.includeResolved,
+                limit: value.limit,
+            });
         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/contactRequest.d.ts

@@ -1,12 +1,18 @@
-export type SerializedContactRequestStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+export type SerializedContactRequestStatus = 'pending' | 'approved' | 'rejected' | 'expired' | 'cancelled';
+export type ContactRequestLifecyclePhase = 'awaiting_owner' | 'starting' | 'connected' | 'rejected' | 'expired' | 'cancelled' | 'failed';
 /**
- * Independent gates that must be satisfied before a pending group invite can
- * add its target.
+ * 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.
  */
-export interface GroupInviteRequirements {
+export interface ContactRequestRequirements {
     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;
@@ -27,10 +33,18 @@ export interface SerializedContactRequest {
         conversationId: string;
         groupName: string | null;
     };
-    /** Present for group_invite payloads; omitted for DM requests. */
-    requirements?: GroupInviteRequirements;
+    /** 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;
     createdAt: string | null;
     resolvedAt?: string | null;
     expiresAt?: string | null;
 }
-export declare function serializeContactRequest(requestId: string, data: Record<string, unknown>): SerializedContactRequest | 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;

package/dist/contactRequest.js

@@ -1,14 +1,23 @@
-export function readGroupInviteRequirements(value) {
+export function readContactRequestRequirements(value) {
     const record = isRecord(value) ? value : null;
     if (typeof record?.policyApproval !== 'boolean'
         || typeof record.ownerSessionSetup !== 'boolean') {
-        throw new TypeError('Invalid group invite requirements');
+        throw new TypeError('Invalid contact request 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);
 }
@@ -26,12 +35,36 @@ function normalizeStatus(value) {
     if (value === 'pending'
         || value === 'approved'
         || value === 'rejected'
-        || value === 'expired') {
+        || value === 'expired'
+        || value === 'cancelled') {
         return value;
     }
     return 'pending';
 }
-export function serializeContactRequest(requestId, data) {
+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 = {}) {
     if (typeof data.approverId !== 'string' || data.approverId.length === 0) {
         return null;
     }
@@ -88,21 +121,35 @@ export function serializeContactRequest(requestId, data) {
         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) {
+    if (groupContext || kindValue === 'dm') {
         let requirements;
         try {
-            requirements = readGroupInviteRequirements(data.requirements);
+            requirements = data.requirements === undefined && kindValue === 'dm'
+                ? { policyApproval: true, ownerSessionSetup: false }
+                : readContactRequestRequirements(data.requirements);
         }
         catch {
             return null;
         }
-        payload.groupContext = groupContext;
         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;
+        }
+    }
     if (data.targetUserType === 'ai_agent') {
         payload.targetOwnerId = data.targetOwnerId;
     }

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 { GroupInviteRequirements } from './contactRequest.js';
+import type { ContactRequestRequirements } 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", "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", "cancel_contact_request", "no_reply"];
 export type CanonVerbName = (typeof CANON_VERB_NAMES)[number];
 /** Private note-to-self attached to a cross-conversation send. */
 export interface VerbSelfContext {
@@ -268,6 +268,7 @@ 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';
@@ -322,7 +323,7 @@ export type SendToResult = {
     selfContextId?: string;
     created?: boolean;
     reused?: boolean;
-    sessionSelection?: string;
+    sessionSelection?: VerbSessionSelection['mode'];
 } | {
     status: 'requested';
     requestId: string | null;
@@ -613,7 +614,7 @@ export interface CreateGroupInput {
 export interface PendingGroupInviteResult {
     userId: string;
     requestId: string;
-    requirements: GroupInviteRequirements;
+    requirements: ContactRequestRequirements;
 }
 export interface CreateGroupResult {
     status: 'created';
@@ -653,7 +654,7 @@ export type AddMemberResult = {
 } | {
     status: 'pending';
     requestId: string;
-    requirements: GroupInviteRequirements;
+    requirements: ContactRequestRequirements;
 };
 export interface RemoveMemberInput {
     conversationId: string;
@@ -680,11 +681,26 @@ export interface VerbContact {
 export interface ListContactsResult {
     contacts: VerbContact[];
 }
-export type ListContactRequestsInput = Record<string, never>;
-/** Items are SerializedContactRequest (contactRequest.ts) — pending inbound only, newest first, capped at 100. */
+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 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,6 +200,7 @@ 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,7 +1615,19 @@ export declare const CANON_VERBS_JSON_SCHEMA: {
         readonly list_contact_requests_input: {
             readonly type: "object";
             readonly additionalProperties: false;
-            readonly properties: {};
+            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 list_contact_requests_result: {
             readonly type: "object";
@@ -1627,7 +1639,7 @@ export declare const CANON_VERBS_JSON_SCHEMA: {
                     readonly type: "array";
                     readonly items: {
                         readonly type: "object";
-                        readonly required: readonly ["id", "requesterId", "targetId", "status", "kind"];
+                        readonly required: readonly ["id", "requesterId", "targetId", "status", "kind", "phase"];
                         readonly additionalProperties: true;
                         readonly properties: {
                             readonly id: {
@@ -1643,11 +1655,14 @@ export declare const CANON_VERBS_JSON_SCHEMA: {
                                 readonly type: "string";
                             };
                             readonly status: {
-                                readonly enum: readonly ["pending", "approved", "rejected", "expired"];
+                                readonly enum: readonly ["pending", "approved", "rejected", "expired", "cancelled"];
                             };
                             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"];
                             };
@@ -1741,6 +1756,30 @@ 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,13 +999,17 @@ const list_contacts_result = {
 const list_contact_requests_input = {
     type: 'object',
     additionalProperties: false,
-    properties: {},
+    properties: {
+        direction: { enum: ['inbound', 'outbound'] },
+        includeResolved: { type: 'boolean' },
+        limit: { type: 'integer', minimum: 1, maximum: 100 },
+    },
 };
 const list_contact_requests_result = {
     type: 'object',
-    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.",
+    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).',
     required: ['requests'],
     additionalProperties: true,
     properties: {
@@ -1013,15 +1017,26 @@ const list_contact_requests_result = {
             type: 'array',
             items: {
                 type: 'object',
-                required: ['id', 'requesterId', 'targetId', 'status', 'kind'],
+                required: ['id', 'requesterId', 'targetId', 'status', 'kind', 'phase'],
                 additionalProperties: true,
                 properties: {
                     id: { type: 'string' },
                     requesterId: { type: 'string' },
                     requesterName: { type: 'string' },
                     targetId: { type: 'string' },
-                    status: { enum: ['pending', 'approved', 'rejected', 'expired'] },
+                    status: { enum: ['pending', 'approved', 'rejected', 'expired', 'cancelled'] },
                     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'] },
@@ -1030,6 +1045,23 @@ 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,
@@ -1169,6 +1201,8 @@ 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,6 +40,8 @@ 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';
@@ -137,7 +139,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", "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", "cancel_contact_request", "no_reply"];
         };
         readonly envelope: {
             readonly $ref: "#/$defs/envelope";
@@ -464,6 +466,10 @@ 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"];
                 };
@@ -509,7 +515,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", "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", "cancel_contact_request", "no_reply"];
                 };
                 readonly result: {
                     readonly $ref: "#/$defs/body";

package/dist/verbWire.js

@@ -112,6 +112,7 @@ 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'] },
 };
 // ---------------------------------------------------------------------------
@@ -153,6 +154,7 @@ 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'] },
@@ -278,7 +280,13 @@ export const CANON_VERB_WIRE_JSON_SCHEMA = {
 // ---------------------------------------------------------------------------
 // Intent <-> wire projection (json codec)
 // ---------------------------------------------------------------------------
-const TURN_KEYS = ['turnId', 'turnSemantics', 'deliveryIntent', 'replyBehavior'];
+const TURN_KEYS = [
+    'turnId',
+    'sourceMessageId',
+    'turnSemantics',
+    'deliveryIntent',
+    'replyBehavior',
+];
 function splitTurnMetadata(metadata) {
     if (!metadata || typeof metadata !== 'object')
         return { turn: undefined, rest: undefined };
@@ -463,14 +471,25 @@ export function projectVerbIntentToWire(verb, intent, options) {
             envelope = compact({ conversationId: input.conversationId });
             break;
         }
-        case 'list_contacts':
+        case 'list_contacts': {
+            break;
+        }
         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 });
@@ -609,10 +628,17 @@ export function mergeVerbWireToIntent(request) {
         case 'leave_conversation':
             return compact({ conversationId: envelope.conversationId });
         case 'list_contacts':
-        case 'list_contact_requests':
             return {};
+        case 'list_contact_requests':
+            return compact({
+                direction: value.direction,
+                includeResolved: value.includeResolved,
+                limit: value.limit,
+            });
         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.3.0",
+  "version": "6.4.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",