@canonmsg/backend-contracts 6.4.0 → 8.0.0

package/dist/cjs/verbSchemas.js

@@ -29,23 +29,11 @@
  *   endpoints validate against these schemas directly).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CANON_VERB_SCHEMA_REFS = exports.CANON_VERBS_JSON_SCHEMA = exports.VERB_SESSION_CONFIG_JSON_SCHEMA = exports.VERB_NATIVE_METADATA_JSON_SCHEMA = void 0;
+exports.CANON_VERB_SCHEMA_REFS = exports.CANON_VERBS_JSON_SCHEMA = exports.VERB_NATIVE_METADATA_JSON_SCHEMA = void 0;
 exports.getVerbInputSchema = getVerbInputSchema;
 exports.getVerbResultSchema = getVerbResultSchema;
 const verbContract_js_1 = require("./verbContract.js");
 const REF = (def) => ({ $ref: `#/$defs/${def}` });
-const groupInviteRequirementsDef = {
-    type: 'object',
-    description: 'Independent gates on a pending group invite. policyApproval is social '
-        + 'consent; ownerSessionSetup means the agent owner must choose the '
-        + 'runtime session configuration before membership is activated.',
-    required: ['policyApproval', 'ownerSessionSetup'],
-    additionalProperties: false,
-    properties: {
-        policyApproval: { type: 'boolean' },
-        ownerSessionSetup: { type: 'boolean' },
-    },
-};
 const selfContextDef = {
     type: 'object',
     description: 'Private note-to-self attached to a cross-conversation send. Visible only to the '
@@ -315,50 +303,6 @@ exports.VERB_NATIVE_METADATA_JSON_SCHEMA = {
         },
     },
 };
-const sessionConfigValueDef = {
-    type: 'string',
-    pattern: verbContract_js_1.VERB_ID_PATTERNS.runtimeOptionValue,
-    maxLength: verbContract_js_1.VERB_LIMITS.sessionConfigValueChars,
-};
-exports.VERB_SESSION_CONFIG_JSON_SCHEMA = {
-    type: 'object',
-    description: 'Typed setup policy for an agent target. Values are stable runtime-advertised '
-        + 'option ids and are validated against the target descriptor before session creation; '
-        + 'labels, prompts, workspace paths, and arbitrary fields are not permitted.',
-    additionalProperties: false,
-    properties: {
-        model: sessionConfigValueDef,
-        permissionMode: sessionConfigValueDef,
-        effort: sessionConfigValueDef,
-        workspaceId: {
-            type: 'string',
-            pattern: verbContract_js_1.VERB_ID_PATTERNS.workspaceOptionId,
-            maxLength: verbContract_js_1.VERB_LIMITS.sessionConfigValueChars,
-        },
-        executionMode: { enum: ['worktree', 'locked'] },
-        runtimeControlValues: {
-            type: 'object',
-            maxProperties: verbContract_js_1.VERB_LIMITS.sessionConfigValues,
-            propertyNames: {
-                pattern: verbContract_js_1.VERB_ID_PATTERNS.runtimeControlId,
-                not: {
-                    enum: [
-                        'model',
-                        'workspace',
-                        'executionMode',
-                        'permissionMode',
-                        'effort',
-                        'interrupt',
-                        'runtimeControlValues',
-                        'updatedAt',
-                        'updatedBy',
-                    ],
-                },
-            },
-            additionalProperties: sessionConfigValueDef,
-        },
-    },
-};
 const timeoutFields = (maxMs, ceilingNote) => ({
     timeoutMs: {
         type: 'integer',
@@ -388,7 +332,7 @@ const send_to_input = {
         + 'sends -> admission resolve + create + send (the core reachOut composite). User '
         + 'targets resolve admission first: open targets get the message, approval-required '
         + 'targets get a contact request (send deferred and auto-fulfilled on approval), '
-        + "owner-only targets surface as status 'unavailable' with reason owner-only.",
+        + "closed targets surface as status 'unavailable' with reason closed.",
     additionalProperties: false,
     properties: {
         targetConversationId: { type: 'string', pattern: verbContract_js_1.VERB_ID_PATTERNS.runtimeId },
@@ -412,11 +356,6 @@ const send_to_input = {
                 + `truncate to ${verbContract_js_1.VERB_LIMITS.contactRequestNoteChars} chars.`,
         },
         sessionSelection: REF('sessionSelection'),
-        sessionConfig: {
-            oneOf: [REF('sessionConfig'), { type: 'null' }],
-            description: 'Coding-agent session setup (model/permissionMode/effort/workspaceId/executionMode); '
-                + 'only applied to agent targets, stripped for humans.',
-        },
         messageOptions: REF('messageOptions'),
     },
     oneOf: [
@@ -843,11 +782,9 @@ const create_group_input = {
     description: "Create a group conversation. Each target's groupJoinPolicy is enforced "
         + 'server-side with staged admission: directly-addable members join at '
         + 'creation, approval-required members become pending group_invite '
-        + 'requests; agents needing explicit group-session setup become pending '
-        + 'owner requests; hard-denied members are skipped (see the result). A '
+        + 'requests; hard-denied members are skipped (see the result). A '
         + 'creator-only group is valid when at least one requested member has a '
-        + 'pending invite. A creator that itself requires setup cannot create '
-        + 'groups (403 CREATE_GROUP_CREATOR_SETUP_REQUIRED). Under MLS, membership '
+        + 'pending invite. Under MLS, membership '
         + 'changes are Add/Remove proposals + Commit — a group operation is a '
         + 'cryptographic state change, not a codec swap.',
     required: ['name', 'memberIds'],
@@ -866,8 +803,8 @@ const create_group_input = {
 const create_group_result = {
     type: 'object',
     description: 'Staged admission: the group exists with the directly-added members; '
-        + '`pending` lists group_invite requests awaiting policy approval, owner '
-        + 'session setup, or both; `skipped` lists hard-denied targets.',
+        + '`pending` lists group_invite requests awaiting policy approval; '
+        + '`skipped` lists hard-denied targets.',
     required: ['status', 'conversationId', 'added', 'pending', 'skipped'],
     additionalProperties: true,
     properties: {
@@ -881,12 +818,11 @@ const create_group_result = {
             type: 'array',
             items: {
                 type: 'object',
-                required: ['userId', 'requestId', 'requirements'],
+                required: ['userId', 'requestId'],
                 additionalProperties: true,
                 properties: {
                     userId: { type: 'string' },
                     requestId: { type: 'string' },
-                    requirements: REF('groupInviteRequirements'),
                 },
             },
         },
@@ -906,8 +842,8 @@ const create_group_result = {
 };
 const add_member_input = {
     type: 'object',
-    description: 'A target needing policy approval and/or explicit owner session setup '
-        + 'yields one pending group_invite. Under MLS an add is an Add proposal '
+    description: 'A target needing policy approval yields one pending group_invite. '
+        + 'Under MLS an add is an Add proposal '
         + '+ Commit (new epoch), not a server-side membership write — the verb '
         + 'semantics are stable, the mechanism is not.',
     required: ['conversationId', 'userId'],
@@ -918,8 +854,7 @@ const add_member_input = {
     },
 };
 const add_member_result = {
-    description: 'Targets needing policy approval and/or owner session setup yield one '
-        + 'pending group_invite routed to the target or agent owner.',
+    description: 'Targets needing policy approval yield an exact pending group invite.',
     oneOf: [
         {
             type: 'object',
@@ -929,12 +864,11 @@ const add_member_result = {
         },
         {
             type: 'object',
-            required: ['status', 'requestId', 'requirements'],
+            required: ['status', 'requestId'],
             additionalProperties: true,
             properties: {
                 status: { const: 'pending' },
                 requestId: { type: 'string' },
-                requirements: REF('groupInviteRequirements'),
             },
         },
     ],
@@ -1001,72 +935,6 @@ 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 },
-    },
-};
-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).',
-    required: ['requests'],
-    additionalProperties: true,
-    properties: {
-        requests: {
-            type: 'array',
-            items: {
-                type: 'object',
-                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', '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'] },
-                },
-            },
-        },
-    },
-};
-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,
@@ -1160,7 +1028,6 @@ exports.CANON_VERBS_JSON_SCHEMA = {
         + 'deliberately NOT verbs — they stay host-mediated.',
     $defs: {
         messageId: messageIdDef,
-        groupInviteRequirements: groupInviteRequirementsDef,
         selfContext: selfContextDef,
         sessionSelection: sessionSelectionDef,
         mediaAttachment: mediaAttachmentDef,
@@ -1173,7 +1040,6 @@ exports.CANON_VERBS_JSON_SCHEMA = {
         sessionRule: sessionRuleDef,
         runtimeCard: runtimeCardDef,
         native: exports.VERB_NATIVE_METADATA_JSON_SCHEMA,
-        sessionConfig: exports.VERB_SESSION_CONFIG_JSON_SCHEMA,
         send_to_input,
         send_to_result,
         request_input_input,
@@ -1202,12 +1068,8 @@ exports.CANON_VERBS_JSON_SCHEMA = {
         leave_conversation_result,
         list_contacts_input,
         list_contacts_result,
-        list_contact_requests_input,
-        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

@@ -47,7 +47,6 @@ exports.VERB_WIRE_ENVELOPE_FIELDS = {
             'canonContactId',
             'sourceConversationId',
             'sessionSelection',
-            'sessionConfig',
             'idempotencyKey',
             'replyTo',
             'replyToPosition',
@@ -116,9 +115,7 @@ exports.VERB_WIRE_ENVELOPE_FIELDS = {
         optional: [],
     },
     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 +157,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'] },
@@ -208,9 +204,6 @@ const wireEnvelopeDef = {
                 },
             ],
         },
-        sessionConfig: {
-            oneOf: [verbSchemas_js_1.VERB_SESSION_CONFIG_JSON_SCHEMA, { type: 'null' }],
-        },
         idempotencyKey: {
             type: 'string',
             pattern: verbContract_js_1.VERB_ID_PATTERNS.runtimeId,
@@ -286,13 +279,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 };
@@ -350,7 +337,6 @@ function projectVerbIntentToWire(verb, intent, options) {
                 canonContactId: input.canonContactId,
                 sourceConversationId: input.sourceConversationId,
                 sessionSelection: input.sessionSelection,
-                sessionConfig: input.sessionConfig,
                 idempotencyKey: messageOptions.messageId,
                 replyTo: messageOptions.replyTo,
                 replyToPosition: messageOptions.replyToPosition,
@@ -480,22 +466,10 @@ function projectVerbIntentToWire(verb, intent, options) {
         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 });
@@ -541,7 +515,6 @@ function mergeVerbWireToIntent(request) {
                 canonContactId: envelope.canonContactId,
                 sourceConversationId: envelope.sourceConversationId,
                 sessionSelection: envelope.sessionSelection,
-                sessionConfig: envelope.sessionConfig,
                 text: value.text,
                 selfContext: value.selfContext,
                 requestMessage: value.requestMessage,
@@ -635,16 +608,8 @@ function mergeVerbWireToIntent(request) {
             return compact({ conversationId: envelope.conversationId });
         case 'list_contacts':
             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/communication.d.ts

@@ -0,0 +1,109 @@
+/** 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;
+} | {
+    action: 'share_contact';
+    conversationId: string;
+    contactUserId: string;
+    text?: string;
+    messageId?: string;
+} | {
+    action: 'manage_group_members';
+    conversationId: string;
+    userId: string;
+    operation: 'add' | 'remove';
+};
+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;
+    }>;
+    skipped: Array<{
+        userId: string;
+        reason: string;
+    }>;
+} | {
+    status: 'forwarded';
+    messageId: string;
+    targetConversationId: string;
+} | {
+    status: 'shared';
+    conversationId: string;
+    messageId: string;
+} | {
+    status: 'added' | 'removed';
+    conversationId: string;
+    userId: string;
+} | {
+    status: 'approval_required';
+    reason: 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,27 @@
+/** Missing or invalid policy never widens access. */
+export function readCommunicationRule(value) {
+    if (value === 'open' || value === 'approval-required' || value === 'closed') {
+        return value;
+    }
+    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/firestoreValues.d.ts

@@ -3,7 +3,7 @@ export declare function normalizeStoredString(value: unknown): string | null;
 /**
  * Firestore Timestamp-like -> ISO 8601, or null. Accepts only objects exposing
  * `toDate()`. A raw `Date` is deliberately NOT accepted: that matches both call
- * sites this replaced. `message.ts` and `contactRequest.ts` keep their own
+ * sites this replaced. `message.ts` keeps its own
  * Date-tolerant normalizers — a different contract, not this one.
  */
 export declare function firestoreTimestampToISOString(value: unknown): string | null;

package/dist/firestoreValues.js

@@ -10,7 +10,7 @@ export function normalizeStoredString(value) {
 /**
  * Firestore Timestamp-like -> ISO 8601, or null. Accepts only objects exposing
  * `toDate()`. A raw `Date` is deliberately NOT accepted: that matches both call
- * sites this replaced. `message.ts` and `contactRequest.ts` keep their own
+ * sites this replaced. `message.ts` keeps its own
  * Date-tolerant normalizers — a different contract, not this one.
  */
 export function firestoreTimestampToISOString(value) {

package/dist/index.d.ts

@@ -8,12 +8,12 @@ export * from './runtimeCardStorage.js';
 export * from './turnProtocol.js';
 export * from './agentBehaviorPolicy.js';
 export * from './agentSearch.js';
-export * from './contactRequest.js';
 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';
 export * from './selfContext.js';
+export * from './replyAuthority.js';

package/dist/index.js

@@ -8,12 +8,12 @@ export * from './runtimeCardStorage.js';
 export * from './turnProtocol.js';
 export * from './agentBehaviorPolicy.js';
 export * from './agentSearch.js';
-export * from './contactRequest.js';
 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';
 export * from './selfContext.js';
+export * from './replyAuthority.js';

package/dist/replyAuthority.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Opaque, server-issued authority for one agent reply to one inbound message.
+ *
+ * The stream delivers this beside the triggering message. Runtimes keep it out
+ * of model-visible schemas and return it only on the ordinary reply path.
+ */
+export interface AgentReplyAuthorityV1 {
+    schema: 'canon.agent-reply-authority.v1';
+    sourceMessageId: string;
+    token: string;
+    expiresAt: string;
+}

package/dist/replyAuthority.js

@@ -0,0 +1 @@
+export {};