@canonmsg/backend-contracts 1.3.1 → 1.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cjs/turnProtocol.js +60 -9
- package/dist/turnProtocol.d.ts +12 -4
- package/dist/turnProtocol.js +60 -9
- package/package.json +1 -1
package/dist/cjs/turnProtocol.js
CHANGED
|
@@ -11,6 +11,17 @@ exports.shouldTriggerAgentTurn = shouldTriggerAgentTurn;
|
|
|
11
11
|
exports.normalizeRuntimeTurnState = normalizeRuntimeTurnState;
|
|
12
12
|
exports.ACTIVE_TURN_STALE_THRESHOLD_MS = 30 * 60 * 1000;
|
|
13
13
|
exports.WAITING_INPUT_STALE_THRESHOLD_MS = 12 * 60 * 60 * 1000;
|
|
14
|
+
const TURN_SEMANTICS = [
|
|
15
|
+
'progress',
|
|
16
|
+
'turn_complete',
|
|
17
|
+
'control',
|
|
18
|
+
];
|
|
19
|
+
const DELIVERY_INTENTS = [
|
|
20
|
+
'queue',
|
|
21
|
+
'interrupt',
|
|
22
|
+
'interleave',
|
|
23
|
+
'stop',
|
|
24
|
+
];
|
|
14
25
|
function isRecord(value) {
|
|
15
26
|
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
16
27
|
}
|
|
@@ -29,21 +40,40 @@ function isHiddenRuntimeCardMetadata(metadata) {
|
|
|
29
40
|
function normalizeTurnMetadata(metadata) {
|
|
30
41
|
if (!isRecord(metadata))
|
|
31
42
|
return null;
|
|
32
|
-
const
|
|
33
|
-
|
|
34
|
-
|
|
43
|
+
const turnId = typeof metadata.turnId === 'string' && metadata.turnId.trim()
|
|
44
|
+
? metadata.turnId.trim()
|
|
45
|
+
: null;
|
|
46
|
+
const turnSemantics = TURN_SEMANTICS.includes(metadata.turnSemantics)
|
|
35
47
|
? metadata.turnSemantics
|
|
36
48
|
: undefined;
|
|
37
|
-
const
|
|
38
|
-
|
|
49
|
+
const deliveryIntent = DELIVERY_INTENTS.includes(metadata.deliveryIntent)
|
|
50
|
+
? metadata.deliveryIntent
|
|
51
|
+
: undefined;
|
|
52
|
+
const replyBehavior = metadata.replyBehavior === 'allow_auto_reply' || metadata.replyBehavior === 'suppress_auto_reply'
|
|
39
53
|
? metadata.replyBehavior
|
|
40
54
|
: undefined;
|
|
41
|
-
|
|
55
|
+
const inboundDisposition = metadata.inboundDisposition === 'queued'
|
|
56
|
+
|| metadata.inboundDisposition === 'accepted_now'
|
|
57
|
+
|| metadata.inboundDisposition === 'interleaved'
|
|
58
|
+
|| metadata.inboundDisposition === 'trigger_suppressed'
|
|
59
|
+
|| metadata.inboundDisposition === 'rejected'
|
|
60
|
+
|| metadata.inboundDisposition === 'cancelled'
|
|
61
|
+
? metadata.inboundDisposition
|
|
62
|
+
: undefined;
|
|
63
|
+
const requestedTurnMode = typeof metadata.requestedTurnMode === 'string'
|
|
64
|
+
&& /^[A-Za-z0-9_.:-]{1,80}$/.test(metadata.requestedTurnMode.trim())
|
|
65
|
+
? metadata.requestedTurnMode.trim()
|
|
66
|
+
: undefined;
|
|
67
|
+
if (!turnId && !turnSemantics && !deliveryIntent && !replyBehavior && !inboundDisposition && !requestedTurnMode) {
|
|
42
68
|
return null;
|
|
43
69
|
}
|
|
44
70
|
return {
|
|
71
|
+
...(turnId ? { turnId } : {}),
|
|
45
72
|
...(turnSemantics ? { turnSemantics } : {}),
|
|
73
|
+
...(deliveryIntent ? { deliveryIntent } : {}),
|
|
46
74
|
...(replyBehavior ? { replyBehavior } : {}),
|
|
75
|
+
...(inboundDisposition ? { inboundDisposition } : {}),
|
|
76
|
+
...(requestedTurnMode ? { requestedTurnMode } : {}),
|
|
47
77
|
};
|
|
48
78
|
}
|
|
49
79
|
function isTurnOpen(turnState) {
|
|
@@ -95,12 +125,33 @@ function shouldTriggerAgentTurn(input) {
|
|
|
95
125
|
const semantics = resolveTurnMessageSemantics(input);
|
|
96
126
|
const turnMetadata = normalizeTurnMetadata(input.metadata);
|
|
97
127
|
if (turnMetadata?.replyBehavior === 'suppress_auto_reply') {
|
|
98
|
-
return {
|
|
128
|
+
return {
|
|
129
|
+
allow: false,
|
|
130
|
+
semantics,
|
|
131
|
+
reason: 'metadata explicitly suppresses auto-reply',
|
|
132
|
+
};
|
|
99
133
|
}
|
|
100
134
|
if (input.senderType === 'human') {
|
|
101
|
-
return {
|
|
135
|
+
return {
|
|
136
|
+
allow: true,
|
|
137
|
+
semantics,
|
|
138
|
+
reason: 'human messages always remain triggerable',
|
|
139
|
+
};
|
|
140
|
+
}
|
|
141
|
+
if (semantics === 'progress') {
|
|
142
|
+
return {
|
|
143
|
+
allow: false,
|
|
144
|
+
semantics,
|
|
145
|
+
reason: turnMetadata?.turnSemantics === 'progress'
|
|
146
|
+
? 'non-final agent progress does not trigger other agents'
|
|
147
|
+
: 'agent messages require explicit turn_complete semantics',
|
|
148
|
+
};
|
|
102
149
|
}
|
|
103
|
-
return {
|
|
150
|
+
return {
|
|
151
|
+
allow: true,
|
|
152
|
+
semantics,
|
|
153
|
+
reason: 'agent message is treated as turn-complete',
|
|
154
|
+
};
|
|
104
155
|
}
|
|
105
156
|
function normalizeRuntimeTurnState(value) {
|
|
106
157
|
if (!isRecord(value))
|
package/dist/turnProtocol.d.ts
CHANGED
|
@@ -1,9 +1,20 @@
|
|
|
1
1
|
export type SenderType = 'human' | 'ai_agent';
|
|
2
2
|
export type TurnLifecycleState = 'idle' | 'thinking' | 'streaming' | 'tool' | 'waiting_input' | 'completed' | 'interrupted';
|
|
3
3
|
export type TurnMessageSemantics = 'progress' | 'turn_complete' | 'control';
|
|
4
|
+
export type DeliveryIntent = 'queue' | 'interrupt' | 'interleave' | 'stop';
|
|
5
|
+
export type InboundDisposition = 'queued' | 'accepted_now' | 'interleaved' | 'trigger_suppressed' | 'rejected' | 'cancelled';
|
|
4
6
|
export interface TurnMetadata {
|
|
7
|
+
turnId?: string | null;
|
|
5
8
|
turnSemantics?: TurnMessageSemantics;
|
|
9
|
+
deliveryIntent?: DeliveryIntent;
|
|
6
10
|
replyBehavior?: 'allow_auto_reply' | 'suppress_auto_reply';
|
|
11
|
+
inboundDisposition?: InboundDisposition;
|
|
12
|
+
requestedTurnMode?: string;
|
|
13
|
+
}
|
|
14
|
+
export interface TriggerDecision {
|
|
15
|
+
allow: boolean;
|
|
16
|
+
semantics: TurnMessageSemantics;
|
|
17
|
+
reason: string;
|
|
7
18
|
}
|
|
8
19
|
export interface TurnStateLike {
|
|
9
20
|
state: TurnLifecycleState;
|
|
@@ -28,8 +39,5 @@ export declare function shouldPromoteConversationMessage(input: {
|
|
|
28
39
|
export declare function shouldTriggerAgentTurn(input: {
|
|
29
40
|
senderType: SenderType;
|
|
30
41
|
metadata?: unknown;
|
|
31
|
-
}):
|
|
32
|
-
allow: boolean;
|
|
33
|
-
semantics: TurnMessageSemantics;
|
|
34
|
-
};
|
|
42
|
+
}): TriggerDecision;
|
|
35
43
|
export declare function normalizeRuntimeTurnState(value: unknown): TurnStateLike | null;
|
package/dist/turnProtocol.js
CHANGED
|
@@ -1,5 +1,16 @@
|
|
|
1
1
|
export const ACTIVE_TURN_STALE_THRESHOLD_MS = 30 * 60 * 1000;
|
|
2
2
|
export const WAITING_INPUT_STALE_THRESHOLD_MS = 12 * 60 * 60 * 1000;
|
|
3
|
+
const TURN_SEMANTICS = [
|
|
4
|
+
'progress',
|
|
5
|
+
'turn_complete',
|
|
6
|
+
'control',
|
|
7
|
+
];
|
|
8
|
+
const DELIVERY_INTENTS = [
|
|
9
|
+
'queue',
|
|
10
|
+
'interrupt',
|
|
11
|
+
'interleave',
|
|
12
|
+
'stop',
|
|
13
|
+
];
|
|
3
14
|
function isRecord(value) {
|
|
4
15
|
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
5
16
|
}
|
|
@@ -18,21 +29,40 @@ function isHiddenRuntimeCardMetadata(metadata) {
|
|
|
18
29
|
export function normalizeTurnMetadata(metadata) {
|
|
19
30
|
if (!isRecord(metadata))
|
|
20
31
|
return null;
|
|
21
|
-
const
|
|
22
|
-
|
|
23
|
-
|
|
32
|
+
const turnId = typeof metadata.turnId === 'string' && metadata.turnId.trim()
|
|
33
|
+
? metadata.turnId.trim()
|
|
34
|
+
: null;
|
|
35
|
+
const turnSemantics = TURN_SEMANTICS.includes(metadata.turnSemantics)
|
|
24
36
|
? metadata.turnSemantics
|
|
25
37
|
: undefined;
|
|
26
|
-
const
|
|
27
|
-
|
|
38
|
+
const deliveryIntent = DELIVERY_INTENTS.includes(metadata.deliveryIntent)
|
|
39
|
+
? metadata.deliveryIntent
|
|
40
|
+
: undefined;
|
|
41
|
+
const replyBehavior = metadata.replyBehavior === 'allow_auto_reply' || metadata.replyBehavior === 'suppress_auto_reply'
|
|
28
42
|
? metadata.replyBehavior
|
|
29
43
|
: undefined;
|
|
30
|
-
|
|
44
|
+
const inboundDisposition = metadata.inboundDisposition === 'queued'
|
|
45
|
+
|| metadata.inboundDisposition === 'accepted_now'
|
|
46
|
+
|| metadata.inboundDisposition === 'interleaved'
|
|
47
|
+
|| metadata.inboundDisposition === 'trigger_suppressed'
|
|
48
|
+
|| metadata.inboundDisposition === 'rejected'
|
|
49
|
+
|| metadata.inboundDisposition === 'cancelled'
|
|
50
|
+
? metadata.inboundDisposition
|
|
51
|
+
: undefined;
|
|
52
|
+
const requestedTurnMode = typeof metadata.requestedTurnMode === 'string'
|
|
53
|
+
&& /^[A-Za-z0-9_.:-]{1,80}$/.test(metadata.requestedTurnMode.trim())
|
|
54
|
+
? metadata.requestedTurnMode.trim()
|
|
55
|
+
: undefined;
|
|
56
|
+
if (!turnId && !turnSemantics && !deliveryIntent && !replyBehavior && !inboundDisposition && !requestedTurnMode) {
|
|
31
57
|
return null;
|
|
32
58
|
}
|
|
33
59
|
return {
|
|
60
|
+
...(turnId ? { turnId } : {}),
|
|
34
61
|
...(turnSemantics ? { turnSemantics } : {}),
|
|
62
|
+
...(deliveryIntent ? { deliveryIntent } : {}),
|
|
35
63
|
...(replyBehavior ? { replyBehavior } : {}),
|
|
64
|
+
...(inboundDisposition ? { inboundDisposition } : {}),
|
|
65
|
+
...(requestedTurnMode ? { requestedTurnMode } : {}),
|
|
36
66
|
};
|
|
37
67
|
}
|
|
38
68
|
export function isTurnOpen(turnState) {
|
|
@@ -84,12 +114,33 @@ export function shouldTriggerAgentTurn(input) {
|
|
|
84
114
|
const semantics = resolveTurnMessageSemantics(input);
|
|
85
115
|
const turnMetadata = normalizeTurnMetadata(input.metadata);
|
|
86
116
|
if (turnMetadata?.replyBehavior === 'suppress_auto_reply') {
|
|
87
|
-
return {
|
|
117
|
+
return {
|
|
118
|
+
allow: false,
|
|
119
|
+
semantics,
|
|
120
|
+
reason: 'metadata explicitly suppresses auto-reply',
|
|
121
|
+
};
|
|
88
122
|
}
|
|
89
123
|
if (input.senderType === 'human') {
|
|
90
|
-
return {
|
|
124
|
+
return {
|
|
125
|
+
allow: true,
|
|
126
|
+
semantics,
|
|
127
|
+
reason: 'human messages always remain triggerable',
|
|
128
|
+
};
|
|
129
|
+
}
|
|
130
|
+
if (semantics === 'progress') {
|
|
131
|
+
return {
|
|
132
|
+
allow: false,
|
|
133
|
+
semantics,
|
|
134
|
+
reason: turnMetadata?.turnSemantics === 'progress'
|
|
135
|
+
? 'non-final agent progress does not trigger other agents'
|
|
136
|
+
: 'agent messages require explicit turn_complete semantics',
|
|
137
|
+
};
|
|
91
138
|
}
|
|
92
|
-
return {
|
|
139
|
+
return {
|
|
140
|
+
allow: true,
|
|
141
|
+
semantics,
|
|
142
|
+
reason: 'agent message is treated as turn-complete',
|
|
143
|
+
};
|
|
93
144
|
}
|
|
94
145
|
export function normalizeRuntimeTurnState(value) {
|
|
95
146
|
if (!isRecord(value))
|