@canonmsg/backend-contracts 8.4.0 → 8.5.0

package/dist/canon-verbs.schema.json

@@ -1427,7 +1427,6 @@
       "type": "object",
       "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; hard-denied members are skipped (see the result). A creator-only group is valid when at least one requested member has a 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"
       ],
       "additionalProperties": false,

package/dist/cjs/conversationMembership.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeConversationRole = normalizeConversationRole;
+exports.isConversationAdminRole = isConversationAdminRole;
+exports.readMembershipRevision = readMembershipRevision;
+exports.resolveConversationPolicyScope = resolveConversationPolicyScope;
+exports.buildConversationParticipantSummary = buildConversationParticipantSummary;
+exports.readConversationInvitationPolicy = readConversationInvitationPolicy;
+const communication_js_1 = require("./communication.js");
+/** `owner` is a read-only legacy spelling, never superior to another admin. */
+function normalizeConversationRole(value) {
+    return value === 'admin' || value === 'owner' ? 'admin' : value === 'member' ? 'member' : null;
+}
+function isConversationAdminRole(value) {
+    return normalizeConversationRole(value) === 'admin';
+}
+function readMembershipRevision(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+/** Behavioral scope follows the current roster, never the legacy shape label. */
+function resolveConversationPolicyScope(memberIdsOrCount) {
+    const count = Array.isArray(memberIdsOrCount)
+        ? new Set(memberIdsOrCount.filter((id) => typeof id === 'string' && id.length > 0)).size
+        : memberIdsOrCount;
+    if (typeof count !== 'number' || !Number.isSafeInteger(count))
+        return 'unknown';
+    return count === 2 ? 'direct' : count > 2 ? 'group' : 'unknown';
+}
+function buildConversationParticipantSummary(participants) {
+    const participantTypes = Object.fromEntries(participants.map(({ userId, userType }) => [userId, userType === 'ai_agent' ? 'ai_agent' : 'human']));
+    const types = Object.values(participantTypes);
+    const agentCount = types.filter((type) => type === 'ai_agent').length;
+    return {
+        participantTypes,
+        participantSummary: { humanCount: types.length - agentCount, agentCount, totalCount: types.length },
+        isAgentChat: agentCount > 0,
+    };
+}
+/** Legacy fields are compatibility inputs to one conservative invitation policy. */
+function readConversationInvitationPolicy(data) {
+    const inbound = (0, communication_js_1.readCommunicationRule)(data?.inboundPolicy);
+    const group = (0, communication_js_1.readCommunicationRule)(data?.groupJoinPolicy);
+    if (inbound === 'closed' || group === 'closed')
+        return 'closed';
+    if (inbound === 'approval-required' || group === 'approval-required')
+        return 'approval-required';
+    return 'open';
+}

package/dist/cjs/index.js

@@ -37,3 +37,4 @@ __exportStar(require("./selfContext.js"), exports);
 __exportStar(require("./replyAuthority.js"), exports);
 __exportStar(require("./runtimeDescriptor.js"), exports);
 __exportStar(require("./workSessions.js"), exports);
+__exportStar(require("./conversationMembership.js"), exports);

package/dist/cjs/verbSchemas.js

@@ -787,7 +787,7 @@ const create_group_input = {
         + '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'],
+    required: ['memberIds'],
     additionalProperties: false,
     properties: {
         name: { type: 'string', minLength: 1, maxLength: verbContract_js_1.VERB_LIMITS.groupNameChars },

package/dist/communication.d.ts

@@ -1,3 +1,4 @@
+import type { ListConversationsResult } from './verbContract.js';
 import type { DiscoverAgentsInput, DiscoverAgentsResult } from './agentDirectory.js';
 /** The deliberately small policy vocabulary for principal communication. */
 export type CommunicationRule = 'open' | 'approval-required' | 'closed';
@@ -20,14 +21,14 @@ export type CommunicateInput = ({
     text: string;
     messageId?: string;
 } | {
-    action: 'start_direct';
+    action: 'start_direct' | 'start_conversation';
     principalId: string;
     text: string;
     selection?: DirectConversationSelection;
     messageId?: string;
 } | {
-    action: 'create_group';
-    name: string;
+    action: 'create_group' | 'create_conversation';
+    name?: string;
     memberIds: string[];
 } | {
     action: 'forward_message';
@@ -42,12 +43,23 @@ export type CommunicateInput = ({
     text?: string;
     messageId?: string;
 } | {
-    action: 'manage_group_members';
+    action: 'manage_group_members' | 'manage_participants';
     conversationId: string;
     userId: string;
     operation: 'add' | 'remove';
+} | {
+    action: 'list_conversations';
+    limit?: number;
+} | {
+    action: 'leave_conversation';
+    conversationId: string;
 };
 export type CommunicateResult = ({
+    status: 'listed';
+} & ListConversationsResult) | {
+    status: 'left';
+    conversationId: string;
+} | ({
     status: 'discovered';
 } & DiscoverAgentsResult) | {
     status: 'messaged';

package/dist/conversationMembership.d.ts

@@ -0,0 +1,28 @@
+import { type CommunicationRule } from './communication.js';
+/** Shared social membership semantics; presentation and runtime ownership are separate. */
+export type ConversationRole = 'admin' | 'member';
+export type ConversationParticipantType = 'human' | 'ai_agent';
+export interface ConversationParticipantSummary {
+    humanCount: number;
+    agentCount: number;
+    totalCount: number;
+}
+/** `owner` is a read-only legacy spelling, never superior to another admin. */
+export declare function normalizeConversationRole(value: unknown): ConversationRole | null;
+export declare function isConversationAdminRole(value: unknown): boolean;
+export declare function readMembershipRevision(value: unknown): number;
+/** Behavioral scope follows the current roster, never the legacy shape label. */
+export declare function resolveConversationPolicyScope(memberIdsOrCount: unknown): 'direct' | 'group' | 'unknown';
+export declare function buildConversationParticipantSummary(participants: readonly {
+    userId: string;
+    userType: unknown;
+}[]): {
+    participantTypes: Record<string, ConversationParticipantType>;
+    participantSummary: ConversationParticipantSummary;
+    isAgentChat: boolean;
+};
+/** Legacy fields are compatibility inputs to one conservative invitation policy. */
+export declare function readConversationInvitationPolicy(data: {
+    inboundPolicy?: unknown;
+    groupJoinPolicy?: unknown;
+} | null | undefined): CommunicationRule;

package/dist/conversationMembership.js

@@ -0,0 +1,40 @@
+import { readCommunicationRule } from './communication.js';
+/** `owner` is a read-only legacy spelling, never superior to another admin. */
+export function normalizeConversationRole(value) {
+    return value === 'admin' || value === 'owner' ? 'admin' : value === 'member' ? 'member' : null;
+}
+export function isConversationAdminRole(value) {
+    return normalizeConversationRole(value) === 'admin';
+}
+export function readMembershipRevision(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+/** Behavioral scope follows the current roster, never the legacy shape label. */
+export function resolveConversationPolicyScope(memberIdsOrCount) {
+    const count = Array.isArray(memberIdsOrCount)
+        ? new Set(memberIdsOrCount.filter((id) => typeof id === 'string' && id.length > 0)).size
+        : memberIdsOrCount;
+    if (typeof count !== 'number' || !Number.isSafeInteger(count))
+        return 'unknown';
+    return count === 2 ? 'direct' : count > 2 ? 'group' : 'unknown';
+}
+export function buildConversationParticipantSummary(participants) {
+    const participantTypes = Object.fromEntries(participants.map(({ userId, userType }) => [userId, userType === 'ai_agent' ? 'ai_agent' : 'human']));
+    const types = Object.values(participantTypes);
+    const agentCount = types.filter((type) => type === 'ai_agent').length;
+    return {
+        participantTypes,
+        participantSummary: { humanCount: types.length - agentCount, agentCount, totalCount: types.length },
+        isAgentChat: agentCount > 0,
+    };
+}
+/** Legacy fields are compatibility inputs to one conservative invitation policy. */
+export function readConversationInvitationPolicy(data) {
+    const inbound = readCommunicationRule(data?.inboundPolicy);
+    const group = readCommunicationRule(data?.groupJoinPolicy);
+    if (inbound === 'closed' || group === 'closed')
+        return 'closed';
+    if (inbound === 'approval-required' || group === 'approval-required')
+        return 'approval-required';
+    return 'open';
+}

package/dist/index.d.ts

@@ -21,3 +21,4 @@ export * from './selfContext.js';
 export * from './replyAuthority.js';
 export * from './runtimeDescriptor.js';
 export * from './workSessions.js';
+export * from './conversationMembership.js';

package/dist/index.js

@@ -21,3 +21,4 @@ export * from './selfContext.js';
 export * from './replyAuthority.js';
 export * from './runtimeDescriptor.js';
 export * from './workSessions.js';
+export * from './conversationMembership.js';

package/dist/replyAuthority.d.ts

@@ -9,4 +9,6 @@ export interface AgentReplyAuthorityV1 {
     sourceMessageId: string;
     token: string;
     expiresAt: string;
+    /** Agent membership admission at issuance; absent/null only for legacy membership. */
+    admissionId?: string | null;
 }

package/dist/verbContract.d.ts

@@ -580,8 +580,8 @@ export interface ForwardResult {
     forwardedFrom?: unknown;
 }
 export interface CreateGroupInput {
-    /** Group name (authoring cap VERB_LIMITS.groupNameChars). */
-    name: string;
+    /** Optional conversation title (authoring cap VERB_LIMITS.groupNameChars). */
+    name?: string;
     /** Other members; the caller is added automatically. Cap
      * VERB_LIMITS.groupMembers including the creator. Each target's
      * groupJoinPolicy is enforced server-side. */
@@ -658,6 +658,17 @@ export interface VerbConversationSummary {
     name?: string | null;
     topic: string | null;
     memberIds: string[];
+    membershipModel?: 'unified';
+    membershipRevision?: number;
+    participantTypes?: Record<string, 'human' | 'ai_agent'>;
+    participantSummary?: {
+        humanCount: number;
+        agentCount: number;
+        totalCount: number;
+    };
+    runtimeSessionKind?: 'direct' | 'group';
+    admissionId?: string | null;
+    historyStartAt?: string | null;
     isAgentChat: boolean;
     hasUnread?: boolean;
     lastMessage: {

package/dist/verbSchemas.d.ts

@@ -1298,7 +1298,7 @@ export declare const CANON_VERBS_JSON_SCHEMA: {
         readonly create_group_input: {
             readonly type: "object";
             readonly description: string;
-            readonly required: readonly ["name", "memberIds"];
+            readonly required: readonly ["memberIds"];
             readonly additionalProperties: false;
             readonly properties: {
                 readonly name: {

package/dist/verbSchemas.js

@@ -782,7 +782,7 @@ const create_group_input = {
         + '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'],
+    required: ['memberIds'],
     additionalProperties: false,
     properties: {
         name: { type: 'string', minLength: 1, maxLength: VERB_LIMITS.groupNameChars },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "8.4.0",
+  "version": "8.5.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",