@canonmsg/backend-contracts 1.3.0 → 1.4.0

package/dist/agentBehaviorPolicy.js

@@ -206,9 +206,6 @@ export function appendParticipationHistoryMessage(snapshot, message, limit = PAR
 export function evaluateParticipationPolicy(policy, input) {
     const consecutiveAgentTurns = Math.max(input.consecutiveAgentTurns ?? (input.senderType === 'ai_agent' ? 1 : 0), input.senderType === 'ai_agent' ? 1 : 0);
     const currentAgentStreakStartedByHuman = input.currentAgentStreakStartedByHuman === true;
-    if (input.isOwner) {
-        return { allow: true, reason: 'owner messages always pass through' };
-    }
     if (input.conversationType === 'group'
         && policy.participation.requireMentionForGroupReplies
         && !input.mentionedAgent) {
@@ -217,6 +214,9 @@ export function evaluateParticipationPolicy(policy, input) {
             reason: 'group replies require a direct mention',
         };
     }
+    if (input.isOwner) {
+        return { allow: true, reason: 'owner messages pass through outside mention-required group turns' };
+    }
     if (input.senderType !== 'ai_agent') {
         return { allow: true, reason: 'latest sender is human' };
     }

package/dist/cjs/agentBehaviorPolicy.js

@@ -216,9 +216,6 @@ function appendParticipationHistoryMessage(snapshot, message, limit = exports.PA
 function evaluateParticipationPolicy(policy, input) {
     const consecutiveAgentTurns = Math.max(input.consecutiveAgentTurns ?? (input.senderType === 'ai_agent' ? 1 : 0), input.senderType === 'ai_agent' ? 1 : 0);
     const currentAgentStreakStartedByHuman = input.currentAgentStreakStartedByHuman === true;
-    if (input.isOwner) {
-        return { allow: true, reason: 'owner messages always pass through' };
-    }
     if (input.conversationType === 'group'
         && policy.participation.requireMentionForGroupReplies
         && !input.mentionedAgent) {
@@ -227,6 +224,9 @@ function evaluateParticipationPolicy(policy, input) {
             reason: 'group replies require a direct mention',
         };
     }
+    if (input.isOwner) {
+        return { allow: true, reason: 'owner messages pass through outside mention-required group turns' };
+    }
     if (input.senderType !== 'ai_agent') {
         return { allow: true, reason: 'latest sender is human' };
     }

package/dist/cjs/turnProtocol.js

@@ -11,6 +11,17 @@ exports.shouldTriggerAgentTurn = shouldTriggerAgentTurn;
 exports.normalizeRuntimeTurnState = normalizeRuntimeTurnState;
 exports.ACTIVE_TURN_STALE_THRESHOLD_MS = 30 * 60 * 1000;
 exports.WAITING_INPUT_STALE_THRESHOLD_MS = 12 * 60 * 60 * 1000;
+const TURN_SEMANTICS = [
+    'progress',
+    'turn_complete',
+    'control',
+];
+const DELIVERY_INTENTS = [
+    'queue',
+    'interrupt',
+    'interleave',
+    'stop',
+];
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -29,21 +40,40 @@ function isHiddenRuntimeCardMetadata(metadata) {
 function normalizeTurnMetadata(metadata) {
     if (!isRecord(metadata))
         return null;
-    const turnSemantics = metadata.turnSemantics === 'progress'
-        || metadata.turnSemantics === 'turn_complete'
-        || metadata.turnSemantics === 'control'
+    const turnId = typeof metadata.turnId === 'string' && metadata.turnId.trim()
+        ? metadata.turnId.trim()
+        : null;
+    const turnSemantics = TURN_SEMANTICS.includes(metadata.turnSemantics)
         ? metadata.turnSemantics
         : undefined;
-    const replyBehavior = metadata.replyBehavior === 'allow_auto_reply'
-        || metadata.replyBehavior === 'suppress_auto_reply'
+    const deliveryIntent = DELIVERY_INTENTS.includes(metadata.deliveryIntent)
+        ? metadata.deliveryIntent
+        : undefined;
+    const replyBehavior = metadata.replyBehavior === 'allow_auto_reply' || metadata.replyBehavior === 'suppress_auto_reply'
         ? metadata.replyBehavior
         : undefined;
-    if (!turnSemantics && !replyBehavior) {
+    const inboundDisposition = metadata.inboundDisposition === 'queued'
+        || metadata.inboundDisposition === 'accepted_now'
+        || metadata.inboundDisposition === 'interleaved'
+        || metadata.inboundDisposition === 'trigger_suppressed'
+        || metadata.inboundDisposition === 'rejected'
+        || metadata.inboundDisposition === 'cancelled'
+        ? metadata.inboundDisposition
+        : undefined;
+    const requestedTurnMode = typeof metadata.requestedTurnMode === 'string'
+        && /^[A-Za-z0-9_.:-]{1,80}$/.test(metadata.requestedTurnMode.trim())
+        ? metadata.requestedTurnMode.trim()
+        : undefined;
+    if (!turnId && !turnSemantics && !deliveryIntent && !replyBehavior && !inboundDisposition && !requestedTurnMode) {
         return null;
     }
     return {
+        ...(turnId ? { turnId } : {}),
         ...(turnSemantics ? { turnSemantics } : {}),
+        ...(deliveryIntent ? { deliveryIntent } : {}),
         ...(replyBehavior ? { replyBehavior } : {}),
+        ...(inboundDisposition ? { inboundDisposition } : {}),
+        ...(requestedTurnMode ? { requestedTurnMode } : {}),
     };
 }
 function isTurnOpen(turnState) {
@@ -95,12 +125,33 @@ function shouldTriggerAgentTurn(input) {
     const semantics = resolveTurnMessageSemantics(input);
     const turnMetadata = normalizeTurnMetadata(input.metadata);
     if (turnMetadata?.replyBehavior === 'suppress_auto_reply') {
-        return { allow: false, semantics };
+        return {
+            allow: false,
+            semantics,
+            reason: 'metadata explicitly suppresses auto-reply',
+        };
     }
     if (input.senderType === 'human') {
-        return { allow: true, semantics };
+        return {
+            allow: true,
+            semantics,
+            reason: 'human messages always remain triggerable',
+        };
+    }
+    if (semantics === 'progress') {
+        return {
+            allow: false,
+            semantics,
+            reason: turnMetadata?.turnSemantics === 'progress'
+                ? 'non-final agent progress does not trigger other agents'
+                : 'agent messages require explicit turn_complete semantics',
+        };
     }
-    return { allow: semantics !== 'progress', semantics };
+    return {
+        allow: true,
+        semantics,
+        reason: 'agent message is treated as turn-complete',
+    };
 }
 function normalizeRuntimeTurnState(value) {
     if (!isRecord(value))

package/dist/turnProtocol.d.ts

@@ -1,9 +1,20 @@
 export type SenderType = 'human' | 'ai_agent';
 export type TurnLifecycleState = 'idle' | 'thinking' | 'streaming' | 'tool' | 'waiting_input' | 'completed' | 'interrupted';
 export type TurnMessageSemantics = 'progress' | 'turn_complete' | 'control';
+export type DeliveryIntent = 'queue' | 'interrupt' | 'interleave' | 'stop';
+export type InboundDisposition = 'queued' | 'accepted_now' | 'interleaved' | 'trigger_suppressed' | 'rejected' | 'cancelled';
 export interface TurnMetadata {
+    turnId?: string | null;
     turnSemantics?: TurnMessageSemantics;
+    deliveryIntent?: DeliveryIntent;
     replyBehavior?: 'allow_auto_reply' | 'suppress_auto_reply';
+    inboundDisposition?: InboundDisposition;
+    requestedTurnMode?: string;
+}
+export interface TriggerDecision {
+    allow: boolean;
+    semantics: TurnMessageSemantics;
+    reason: string;
 }
 export interface TurnStateLike {
     state: TurnLifecycleState;
@@ -28,8 +39,5 @@ export declare function shouldPromoteConversationMessage(input: {
 export declare function shouldTriggerAgentTurn(input: {
     senderType: SenderType;
     metadata?: unknown;
-}): {
-    allow: boolean;
-    semantics: TurnMessageSemantics;
-};
+}): TriggerDecision;
 export declare function normalizeRuntimeTurnState(value: unknown): TurnStateLike | null;

package/dist/turnProtocol.js

@@ -1,5 +1,16 @@
 export const ACTIVE_TURN_STALE_THRESHOLD_MS = 30 * 60 * 1000;
 export const WAITING_INPUT_STALE_THRESHOLD_MS = 12 * 60 * 60 * 1000;
+const TURN_SEMANTICS = [
+    'progress',
+    'turn_complete',
+    'control',
+];
+const DELIVERY_INTENTS = [
+    'queue',
+    'interrupt',
+    'interleave',
+    'stop',
+];
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -18,21 +29,40 @@ function isHiddenRuntimeCardMetadata(metadata) {
 export function normalizeTurnMetadata(metadata) {
     if (!isRecord(metadata))
         return null;
-    const turnSemantics = metadata.turnSemantics === 'progress'
-        || metadata.turnSemantics === 'turn_complete'
-        || metadata.turnSemantics === 'control'
+    const turnId = typeof metadata.turnId === 'string' && metadata.turnId.trim()
+        ? metadata.turnId.trim()
+        : null;
+    const turnSemantics = TURN_SEMANTICS.includes(metadata.turnSemantics)
         ? metadata.turnSemantics
         : undefined;
-    const replyBehavior = metadata.replyBehavior === 'allow_auto_reply'
-        || metadata.replyBehavior === 'suppress_auto_reply'
+    const deliveryIntent = DELIVERY_INTENTS.includes(metadata.deliveryIntent)
+        ? metadata.deliveryIntent
+        : undefined;
+    const replyBehavior = metadata.replyBehavior === 'allow_auto_reply' || metadata.replyBehavior === 'suppress_auto_reply'
         ? metadata.replyBehavior
         : undefined;
-    if (!turnSemantics && !replyBehavior) {
+    const inboundDisposition = metadata.inboundDisposition === 'queued'
+        || metadata.inboundDisposition === 'accepted_now'
+        || metadata.inboundDisposition === 'interleaved'
+        || metadata.inboundDisposition === 'trigger_suppressed'
+        || metadata.inboundDisposition === 'rejected'
+        || metadata.inboundDisposition === 'cancelled'
+        ? metadata.inboundDisposition
+        : undefined;
+    const requestedTurnMode = typeof metadata.requestedTurnMode === 'string'
+        && /^[A-Za-z0-9_.:-]{1,80}$/.test(metadata.requestedTurnMode.trim())
+        ? metadata.requestedTurnMode.trim()
+        : undefined;
+    if (!turnId && !turnSemantics && !deliveryIntent && !replyBehavior && !inboundDisposition && !requestedTurnMode) {
         return null;
     }
     return {
+        ...(turnId ? { turnId } : {}),
         ...(turnSemantics ? { turnSemantics } : {}),
+        ...(deliveryIntent ? { deliveryIntent } : {}),
         ...(replyBehavior ? { replyBehavior } : {}),
+        ...(inboundDisposition ? { inboundDisposition } : {}),
+        ...(requestedTurnMode ? { requestedTurnMode } : {}),
     };
 }
 export function isTurnOpen(turnState) {
@@ -84,12 +114,33 @@ export function shouldTriggerAgentTurn(input) {
     const semantics = resolveTurnMessageSemantics(input);
     const turnMetadata = normalizeTurnMetadata(input.metadata);
     if (turnMetadata?.replyBehavior === 'suppress_auto_reply') {
-        return { allow: false, semantics };
+        return {
+            allow: false,
+            semantics,
+            reason: 'metadata explicitly suppresses auto-reply',
+        };
     }
     if (input.senderType === 'human') {
-        return { allow: true, semantics };
+        return {
+            allow: true,
+            semantics,
+            reason: 'human messages always remain triggerable',
+        };
+    }
+    if (semantics === 'progress') {
+        return {
+            allow: false,
+            semantics,
+            reason: turnMetadata?.turnSemantics === 'progress'
+                ? 'non-final agent progress does not trigger other agents'
+                : 'agent messages require explicit turn_complete semantics',
+        };
     }
-    return { allow: semantics !== 'progress', semantics };
+    return {
+        allow: true,
+        semantics,
+        reason: 'agent message is treated as turn-complete',
+    };
 }
 export function normalizeRuntimeTurnState(value) {
     if (!isRecord(value))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -42,7 +42,7 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typescript": "~5.7.0",
-    "vitest": "^3.0.0"
+    "vitest": "^4.1.8"
   },
   "license": "MIT"
 }