@zhin.js/core 1.1.35 → 1.1.38

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.
Files changed (197) hide show
  1. package/README.md +79 -193
  2. package/lib/built/ai-outbound/index.d.ts +0 -1
  3. package/lib/built/ai-outbound/index.js +0 -1
  4. package/lib/built/ai-outbound/types.d.ts +0 -9
  5. package/lib/built/ai-trigger.d.ts +0 -5
  6. package/lib/built/ai-trigger.js +1 -27
  7. package/lib/built/common-adapter-tools.d.ts +0 -2
  8. package/lib/built/common-adapter-tools.js +0 -4
  9. package/lib/built/html-segment-fallback.d.ts +2 -5
  10. package/lib/built/html-segment-fallback.js +0 -15
  11. package/lib/built/interactive-segments/index.d.ts +0 -2
  12. package/lib/built/interactive-segments/index.js +0 -2
  13. package/lib/built/interactive-segments/keyboard-segment.d.ts +0 -1
  14. package/lib/built/interactive-segments/keyboard-segment.js +0 -1
  15. package/lib/built/interactive-segments/onebot-keyboard.d.ts +0 -1
  16. package/lib/built/interactive-segments/onebot-keyboard.js +0 -2
  17. package/lib/built/interactive-segments/resolve.d.ts +0 -1
  18. package/lib/built/interactive-segments/resolve.js +0 -1
  19. package/lib/built/interactive-segments/types.d.ts +0 -5
  20. package/lib/built/login-assist.d.ts +1 -8
  21. package/lib/built/message-enrich.d.ts +2 -8
  22. package/lib/built/message-enrich.js +3 -11
  23. package/lib/built/segment-contract/assert.js +2 -1
  24. package/lib/built/segment-contract/delivery.js +1 -0
  25. package/lib/built/segment-contract/index.d.ts +2 -2
  26. package/lib/built/segment-contract/index.js +1 -1
  27. package/lib/built/segment-contract/json-schema.d.ts +1 -1
  28. package/lib/built/segment-contract/json-schema.js +33 -2
  29. package/lib/built/segment-contract/preview.js +7 -0
  30. package/lib/built/segment-contract/types.d.ts +2 -2
  31. package/lib/built/segment-contract/validate.d.ts +43 -2
  32. package/lib/built/segment-contract/validate.js +37 -3
  33. package/lib/built/tool-access.d.ts +5 -0
  34. package/lib/built/tool-access.js +17 -0
  35. package/lib/built/user-interaction.js +0 -4
  36. package/lib/feature/handler.d.ts +1 -5
  37. package/lib/index.d.ts +4 -45
  38. package/lib/index.js +3 -39
  39. package/lib/message.d.ts +1 -2
  40. package/lib/models/system-log.d.ts +0 -2
  41. package/lib/models/system-log.js +1 -8
  42. package/lib/models/user.d.ts +0 -2
  43. package/lib/models/user.js +1 -7
  44. package/lib/notice.d.ts +1 -2
  45. package/lib/plugin-runtime/im/conversation-runtime.d.ts +19 -0
  46. package/lib/plugin-runtime/im/conversation-runtime.js +312 -0
  47. package/lib/plugin-runtime/im/endpoint-runtime.d.ts +79 -0
  48. package/lib/plugin-runtime/im/endpoint-runtime.js +162 -0
  49. package/lib/plugin-runtime/im/im-runtime.d.ts +13 -106
  50. package/lib/plugin-runtime/im/im-runtime.js +58 -1061
  51. package/lib/plugin-runtime/im/inbound-runtime.d.ts +31 -0
  52. package/lib/plugin-runtime/im/inbound-runtime.js +252 -0
  53. package/lib/plugin-runtime/im/index.d.ts +4 -2
  54. package/lib/plugin-runtime/im/index.js +2 -2
  55. package/lib/plugin-runtime/im/ingress-route.d.ts +10 -0
  56. package/lib/plugin-runtime/im/ingress-route.js +10 -0
  57. package/lib/plugin-runtime/im/interaction-runtime.d.ts +23 -0
  58. package/lib/plugin-runtime/im/interaction-runtime.js +181 -0
  59. package/lib/plugin-runtime/im/interactive-router.d.ts +17 -0
  60. package/lib/plugin-runtime/im/interactive-router.js +98 -0
  61. package/lib/plugin-runtime/im/message-bus.d.ts +3 -3
  62. package/lib/plugin-runtime/im/message-bus.js +3 -3
  63. package/lib/plugin-runtime/im/message-events.d.ts +26 -0
  64. package/lib/plugin-runtime/im/message-events.js +61 -0
  65. package/lib/plugin-runtime/im/outbound-delivery-runtime.d.ts +19 -0
  66. package/lib/plugin-runtime/im/outbound-delivery-runtime.js +165 -0
  67. package/lib/plugin-runtime/im/outbound-segments.d.ts +2 -3
  68. package/lib/plugin-runtime/im/outbound-segments.js +3 -4
  69. package/lib/plugin-runtime/im/runtime-middleware.d.ts +3 -0
  70. package/lib/plugin-runtime/im/runtime-middleware.js +13 -0
  71. package/lib/request.d.ts +1 -2
  72. package/lib/side-event/base.d.ts +1 -2
  73. package/lib/side-event/normalize.d.ts +1 -5
  74. package/lib/side-event/normalize.js +1 -11
  75. package/lib/system-event.d.ts +1 -2
  76. package/lib/types.d.ts +9 -116
  77. package/lib/utils.d.ts +51 -24
  78. package/lib/utils.js +11 -23
  79. package/package.json +18 -28
  80. package/lib/adapter.d.ts +0 -145
  81. package/lib/adapter.js +0 -377
  82. package/lib/built/adapter-process.d.ts +0 -58
  83. package/lib/built/adapter-process.js +0 -128
  84. package/lib/built/agent-preset.d.ts +0 -64
  85. package/lib/built/agent-preset.js +0 -79
  86. package/lib/built/ai-outbound/adapter-access.d.ts +0 -3
  87. package/lib/built/ai-outbound/adapter-access.js +0 -9
  88. package/lib/built/authorization.d.ts +0 -10
  89. package/lib/built/authorization.js +0 -76
  90. package/lib/built/command.d.ts +0 -72
  91. package/lib/built/command.js +0 -105
  92. package/lib/built/component.d.ts +0 -67
  93. package/lib/built/component.js +0 -97
  94. package/lib/built/config.d.ts +0 -98
  95. package/lib/built/config.js +0 -372
  96. package/lib/built/connect-endpoint-instance.d.ts +0 -17
  97. package/lib/built/connect-endpoint-instance.js +0 -42
  98. package/lib/built/database.d.ts +0 -68
  99. package/lib/built/database.js +0 -106
  100. package/lib/built/dispatcher.d.ts +0 -141
  101. package/lib/built/dispatcher.js +0 -383
  102. package/lib/built/endpoint-commands.d.ts +0 -3
  103. package/lib/built/endpoint-commands.js +0 -99
  104. package/lib/built/endpoint-lifecycle-service.d.ts +0 -28
  105. package/lib/built/endpoint-lifecycle-service.js +0 -242
  106. package/lib/built/endpoint-lifecycle.d.ts +0 -27
  107. package/lib/built/endpoint-lifecycle.js +0 -36
  108. package/lib/built/endpoint-manager.d.ts +0 -34
  109. package/lib/built/endpoint-manager.js +0 -1
  110. package/lib/built/html-renderer-loader.d.ts +0 -13
  111. package/lib/built/html-renderer-loader.js +0 -33
  112. package/lib/built/inbound-pipeline.d.ts +0 -37
  113. package/lib/built/inbound-pipeline.js +0 -63
  114. package/lib/built/inbound-runner.d.ts +0 -22
  115. package/lib/built/inbound-runner.js +0 -34
  116. package/lib/built/interactive-segment-contract.d.ts +0 -6
  117. package/lib/built/interactive-segment-contract.js +0 -9
  118. package/lib/built/interactive-segments/fallback-store.d.ts +0 -29
  119. package/lib/built/interactive-segments/fallback-store.js +0 -63
  120. package/lib/built/interactive-segments/handlers.d.ts +0 -16
  121. package/lib/built/interactive-segments/handlers.js +0 -74
  122. package/lib/built/introspection-format.d.ts +0 -10
  123. package/lib/built/introspection-format.js +0 -28
  124. package/lib/built/management-command-guard.d.ts +0 -15
  125. package/lib/built/management-command-guard.js +0 -25
  126. package/lib/built/message-filter.d.ts +0 -176
  127. package/lib/built/message-filter.js +0 -239
  128. package/lib/built/optional-peer-import.d.ts +0 -3
  129. package/lib/built/optional-peer-import.js +0 -33
  130. package/lib/built/outbound-media-contract.d.ts +0 -22
  131. package/lib/built/outbound-media-contract.js +0 -10
  132. package/lib/built/permission.d.ts +0 -51
  133. package/lib/built/permission.js +0 -99
  134. package/lib/built/permit-check.d.ts +0 -7
  135. package/lib/built/permit-check.js +0 -35
  136. package/lib/built/permit-parse.d.ts +0 -16
  137. package/lib/built/permit-parse.js +0 -32
  138. package/lib/built/platform-permit.d.ts +0 -20
  139. package/lib/built/platform-permit.js +0 -91
  140. package/lib/built/rich-segments/adapter-policies.d.ts +0 -9
  141. package/lib/built/rich-segments/adapter-policies.js +0 -27
  142. package/lib/built/rich-segments/base.d.ts +0 -11
  143. package/lib/built/rich-segments/base.js +0 -24
  144. package/lib/built/rich-segments/builtins.d.ts +0 -4
  145. package/lib/built/rich-segments/builtins.js +0 -40
  146. package/lib/built/rich-segments/capabilities.d.ts +0 -6
  147. package/lib/built/rich-segments/capabilities.js +0 -38
  148. package/lib/built/rich-segments/html-segment.d.ts +0 -15
  149. package/lib/built/rich-segments/html-segment.js +0 -62
  150. package/lib/built/rich-segments/index.d.ts +0 -13
  151. package/lib/built/rich-segments/index.js +0 -13
  152. package/lib/built/rich-segments/markdown-segment.d.ts +0 -14
  153. package/lib/built/rich-segments/markdown-segment.js +0 -58
  154. package/lib/built/rich-segments/qrcode-segment.d.ts +0 -18
  155. package/lib/built/rich-segments/qrcode-segment.js +0 -73
  156. package/lib/built/rich-segments/registry.d.ts +0 -16
  157. package/lib/built/rich-segments/registry.js +0 -52
  158. package/lib/built/rich-segments/resolve.d.ts +0 -5
  159. package/lib/built/rich-segments/resolve.js +0 -87
  160. package/lib/built/rich-segments/tts-segment.d.ts +0 -13
  161. package/lib/built/rich-segments/tts-segment.js +0 -51
  162. package/lib/built/rich-segments/types.d.ts +0 -79
  163. package/lib/built/rich-segments/types.js +0 -17
  164. package/lib/built/runtime-io.d.ts +0 -9
  165. package/lib/built/runtime-io.js +0 -67
  166. package/lib/built/schedule.d.ts +0 -54
  167. package/lib/built/schedule.js +0 -112
  168. package/lib/built/schema-endpoint-manager.d.ts +0 -17
  169. package/lib/built/schema-endpoint-manager.js +0 -73
  170. package/lib/built/schema-feature.d.ts +0 -77
  171. package/lib/built/schema-feature.js +0 -130
  172. package/lib/built/skill.d.ts +0 -120
  173. package/lib/built/skill.js +0 -151
  174. package/lib/built/speech-loader.d.ts +0 -14
  175. package/lib/built/speech-loader.js +0 -32
  176. package/lib/built/tool.d.ts +0 -151
  177. package/lib/built/tool.js +0 -388
  178. package/lib/command.d.ts +0 -50
  179. package/lib/command.js +0 -106
  180. package/lib/endpoint-capabilities.d.ts +0 -46
  181. package/lib/endpoint-capabilities.js +0 -55
  182. package/lib/endpoint.d.ts +0 -19
  183. package/lib/endpoint.js +0 -3
  184. package/lib/host-plugin-registry.d.ts +0 -8
  185. package/lib/host-plugin-registry.js +0 -12
  186. package/lib/plugin-context.d.ts +0 -27
  187. package/lib/plugin-context.js +0 -64
  188. package/lib/plugin-runtime/im/interactive.d.ts +0 -26
  189. package/lib/plugin-runtime/im/interactive.js +0 -46
  190. package/lib/plugin-runtime/im/service-tokens.d.ts +0 -18
  191. package/lib/plugin-runtime/im/service-tokens.js +0 -13
  192. package/lib/plugin.d.ts +0 -268
  193. package/lib/plugin.js +0 -583
  194. package/lib/schema-interaction.d.ts +0 -117
  195. package/lib/schema-interaction.js +0 -247
  196. package/lib/tool-zod.d.ts +0 -43
  197. package/lib/tool-zod.js +0 -184
@@ -0,0 +1,312 @@
1
+ import { MemoryConversationEventStore, conversationRefKey, messageRefKey, } from '@zhin.js/im-contract';
2
+ import { assertCanonicalSegments } from '../../built/segment-contract/assert.js';
3
+ import { segmentsToPlainText } from '../../built/segment-contract/text.js';
4
+ /** Owns one ImRuntime's conversation fact store, projections, and consumer cursors. */
5
+ export class ConversationRuntime {
6
+ #events;
7
+ constructor(events = new MemoryConversationEventStore()) {
8
+ this.#events = events;
9
+ }
10
+ get reader() {
11
+ return this.#events;
12
+ }
13
+ replaceStore(events) {
14
+ this.#events = events;
15
+ }
16
+ async resolveLocal(reference) {
17
+ if (reference.kind !== 'message')
18
+ return undefined;
19
+ const message = await this.#events.getMessage(reference.message);
20
+ return message
21
+ ? Object.freeze({ status: 'resolved', reference, value: message })
22
+ : undefined;
23
+ }
24
+ async readContext(conversation, consumer, throughSequence, limit = 50, excludeMessageId) {
25
+ if (!Number.isSafeInteger(throughSequence) || throughSequence < 0) {
26
+ throw new TypeError('Conversation context throughSequence must be a non-negative integer');
27
+ }
28
+ const cursor = await this.#events.getCursor(consumer, conversation);
29
+ const events = await this.#events.listBetween(conversation, cursor, throughSequence, limit);
30
+ return Object.freeze({
31
+ blocks: aggregateConversationContext(events, excludeMessageId),
32
+ cursor: Math.max(cursor, throughSequence),
33
+ });
34
+ }
35
+ commitContext(conversation, consumer, cursor) {
36
+ return this.#events.commitCursor(consumer, conversation, cursor);
37
+ }
38
+ async recordIncoming(input, sender) {
39
+ if (!input.message?.id)
40
+ return undefined;
41
+ const timestamp = Date.now();
42
+ const appended = await this.#events.append(Object.freeze({
43
+ eventId: `message:${messageRefKey(input.message)}`,
44
+ conversation: input.conversation,
45
+ timestamp,
46
+ type: 'message.created',
47
+ message: Object.freeze({
48
+ ref: input.message,
49
+ ...(sender ? { actor: Object.freeze({
50
+ id: sender.id,
51
+ ...(sender.name ? { displayName: sender.name } : {}),
52
+ }) } : {}),
53
+ segments: Object.freeze(input.segments?.length
54
+ ? [...input.segments]
55
+ : [{ type: 'text', data: { text: input.content } }]),
56
+ timestamp,
57
+ ...(input.replyTo
58
+ ? { replyTo: Object.freeze({ conversation: input.conversation, id: input.replyTo.id }) }
59
+ : {}),
60
+ }),
61
+ }));
62
+ return appended.sequence;
63
+ }
64
+ async recordOutbound(request, receipt) {
65
+ if (receipt.status !== 'sent' || !receipt.message?.id)
66
+ return;
67
+ const timestamp = Date.now();
68
+ await this.#events.append(Object.freeze({
69
+ eventId: `message:${messageRefKey(receipt.message)}`,
70
+ conversation: request.conversation,
71
+ timestamp,
72
+ type: 'message.created',
73
+ message: Object.freeze({
74
+ ref: receipt.message,
75
+ segments: segmentsFromContent(request.content),
76
+ timestamp,
77
+ }),
78
+ }));
79
+ }
80
+ async recordNotice(notice) {
81
+ const event = conversationEventFromNotice(notice);
82
+ if (event)
83
+ await this.#events.append(event);
84
+ }
85
+ }
86
+ function conversationEventFromNotice(notice) {
87
+ const sceneType = notice.$scene_type;
88
+ const kind = sceneType === 'group' ? 'group'
89
+ : sceneType === 'channel' ? 'channel'
90
+ : sceneType === 'friend' || sceneType === 'private' ? 'private'
91
+ : undefined;
92
+ if (!kind || !notice.$scene_id || !notice.$id)
93
+ return undefined;
94
+ const conversation = Object.freeze({
95
+ endpoint: Object.freeze({ adapter: String(notice.$adapter), id: String(notice.$endpoint) }),
96
+ kind,
97
+ id: String(notice.$scene_id),
98
+ });
99
+ const actor = notice.$actor?.id
100
+ ? Object.freeze({
101
+ id: String(notice.$actor.id),
102
+ ...(notice.$actor.name ? { displayName: notice.$actor.name } : {}),
103
+ })
104
+ : undefined;
105
+ const target = notice.$target?.id
106
+ ? Object.freeze({
107
+ id: String(notice.$target.id),
108
+ ...(notice.$target.name ? { displayName: notice.$target.name } : {}),
109
+ })
110
+ : undefined;
111
+ const base = Object.freeze({
112
+ eventId: `notice:${conversationRefKey(conversation)}:${String(notice.$id)}`,
113
+ conversation,
114
+ timestamp: notice.$timestamp,
115
+ });
116
+ switch (notice.$sub_type) {
117
+ case 'member_increase':
118
+ case 'increase':
119
+ return target
120
+ ? Object.freeze({ ...base, type: 'member.joined', member: target, ...(actor ? { actor } : {}) })
121
+ : undefined;
122
+ case 'member_decrease':
123
+ return target
124
+ ? Object.freeze({
125
+ ...base,
126
+ type: 'member.left',
127
+ member: target,
128
+ ...(actor ? { actor } : {}),
129
+ reason: actor ? 'removed' : 'left',
130
+ })
131
+ : undefined;
132
+ case 'ban':
133
+ if (!target)
134
+ return undefined;
135
+ return notice.$duration_seconds === 0
136
+ ? Object.freeze({
137
+ ...base,
138
+ type: 'member.unmuted',
139
+ member: target,
140
+ ...(actor ? { actor } : {}),
141
+ })
142
+ : Object.freeze({
143
+ ...base,
144
+ type: 'member.muted',
145
+ member: target,
146
+ ...(actor ? { actor } : {}),
147
+ durationSeconds: notice.$duration_seconds ?? 0,
148
+ });
149
+ case 'admin_change':
150
+ return target && notice.$role && typeof notice.$enabled === 'boolean'
151
+ ? Object.freeze({
152
+ ...base,
153
+ type: 'member.role_changed',
154
+ member: target,
155
+ ...(actor ? { actor } : {}),
156
+ role: notice.$role,
157
+ enabled: notice.$enabled,
158
+ })
159
+ : undefined;
160
+ case 'recall':
161
+ return notice.$message_id
162
+ ? Object.freeze({
163
+ ...base,
164
+ type: 'message.recalled',
165
+ message: Object.freeze({ conversation, id: notice.$message_id }),
166
+ ...(actor ? { actor } : {}),
167
+ })
168
+ : undefined;
169
+ case 'emoji_reaction':
170
+ return notice.$message_id && notice.$reaction && notice.$operation
171
+ ? Object.freeze({
172
+ ...base,
173
+ type: 'message.reaction_changed',
174
+ message: Object.freeze({ conversation, id: notice.$message_id }),
175
+ ...(actor ? { actor } : {}),
176
+ reaction: notice.$reaction,
177
+ operation: notice.$operation,
178
+ })
179
+ : undefined;
180
+ case 'poke':
181
+ return Object.freeze({
182
+ ...base,
183
+ type: 'conversation.poked',
184
+ ...(actor ? { actor } : {}),
185
+ ...(target ? { target } : {}),
186
+ });
187
+ default:
188
+ return undefined;
189
+ }
190
+ }
191
+ function aggregateConversationContext(events, excludeMessageId) {
192
+ const ordinary = [];
193
+ const noisy = new Map();
194
+ for (const { sequence, event } of events) {
195
+ if (event.type === 'message.created') {
196
+ if (event.message.ref.id === excludeMessageId)
197
+ continue;
198
+ const text = describeConversationMessage(event.message);
199
+ if (!text)
200
+ continue;
201
+ ordinary.push(Object.freeze({
202
+ kind: 'conversation_event',
203
+ sequence,
204
+ eventType: event.type,
205
+ text,
206
+ }));
207
+ continue;
208
+ }
209
+ if (event.type === 'message.reaction_changed' || event.type === 'conversation.poked') {
210
+ const key = event.type === 'message.reaction_changed'
211
+ ? `${event.type}:${event.message.id}:${event.actor?.id ?? ''}:${event.reaction}:${event.operation}`
212
+ : `${event.type}:${event.actor?.id ?? ''}:${event.target?.id ?? ''}`;
213
+ const previous = noisy.get(key);
214
+ noisy.set(key, { sequence, event, count: (previous?.count ?? 0) + 1 });
215
+ continue;
216
+ }
217
+ ordinary.push(Object.freeze({
218
+ kind: 'conversation_event',
219
+ sequence,
220
+ eventType: event.type,
221
+ text: describeConversationEvent(event),
222
+ }));
223
+ }
224
+ for (const { sequence, event, count } of noisy.values()) {
225
+ ordinary.push(Object.freeze({
226
+ kind: 'conversation_event',
227
+ sequence,
228
+ eventType: event.type,
229
+ text: `${describeConversationEvent(event)}${count > 1 ? ` (${count} similar events.)` : ''}`,
230
+ }));
231
+ }
232
+ ordinary.sort((left, right) => left.sequence - right.sequence);
233
+ return Object.freeze(ordinary);
234
+ }
235
+ function describeConversationEvent(event) {
236
+ const actor = 'actor' in event && event.actor
237
+ ? `${event.actor.displayName ?? event.actor.id} (${event.actor.id})`
238
+ : undefined;
239
+ switch (event.type) {
240
+ case 'message.recalled':
241
+ return `${actor ?? 'Someone'} recalled message ${event.message.id}.`;
242
+ case 'message.reaction_changed':
243
+ return `${actor ?? 'Someone'} ${event.operation} reaction ${event.reaction} on message ${event.message.id}.`;
244
+ case 'conversation.poked':
245
+ return `${actor ?? 'Someone'} poked ${event.target ? `${event.target.displayName ?? event.target.id} (${event.target.id})` : 'someone'}.`;
246
+ case 'member.joined':
247
+ return `${event.member.displayName ?? event.member.id} (${event.member.id}) joined the conversation.`;
248
+ case 'member.left':
249
+ return `${event.member.displayName ?? event.member.id} (${event.member.id}) left the conversation (${event.reason ?? 'left'}).`;
250
+ case 'member.muted':
251
+ return `${event.member.displayName ?? event.member.id} (${event.member.id}) was muted for ${event.durationSeconds} seconds${actor ? ` by ${actor}` : ''}.`;
252
+ case 'member.unmuted':
253
+ return `${event.member.displayName ?? event.member.id} (${event.member.id}) was unmuted${actor ? ` by ${actor}` : ''}.`;
254
+ case 'member.role_changed':
255
+ return `${event.member.displayName ?? event.member.id} (${event.member.id}) role ${event.role} was ${event.enabled ? 'enabled' : 'disabled'}${actor ? ` by ${actor}` : ''}.`;
256
+ case 'message.created':
257
+ return '';
258
+ }
259
+ }
260
+ function describeConversationMessage(message) {
261
+ const actor = message.actor
262
+ ? `${message.actor.displayName ?? message.actor.id} (${message.actor.id})`
263
+ : undefined;
264
+ if (!actor)
265
+ return '';
266
+ const text = segmentsToPlainText(message.segments).trim();
267
+ const attachmentTypes = [...new Set(message.segments
268
+ .filter((segment) => segment.type !== 'text' && segment.type !== 'mention' && segment.type !== 'at')
269
+ .map((segment) => segment.type))];
270
+ const attachmentNote = attachmentTypes.length > 0
271
+ ? ` [message also contains ${attachmentTypes.join(', ')} data; inspect its reference before relying on that content]`
272
+ : '';
273
+ return `${actor}: ${text || '(no plain-text content)'}${attachmentNote}`;
274
+ }
275
+ function segmentsFromContent(content) {
276
+ if (Array.isArray(content)) {
277
+ try {
278
+ assertCanonicalSegments(content);
279
+ return Object.freeze([...content]);
280
+ }
281
+ catch {
282
+ // Fall through to a truthful text projection of non-canonical output.
283
+ }
284
+ }
285
+ return Object.freeze([{ type: 'text', data: Object.freeze({ text: flattenContent(content) }) }]);
286
+ }
287
+ function flattenContent(content) {
288
+ if (typeof content === 'string')
289
+ return content;
290
+ if (content == null)
291
+ return '';
292
+ if (Array.isArray(content))
293
+ return content.map((item) => flattenContent(item)).join('');
294
+ if (typeof content === 'object') {
295
+ const record = content;
296
+ const data = record.data;
297
+ if (typeof record.type === 'string') {
298
+ if (data && typeof data.text === 'string')
299
+ return data.text;
300
+ return `[${record.type}]`;
301
+ }
302
+ if (typeof record.text === 'string')
303
+ return record.text;
304
+ try {
305
+ return JSON.stringify(content) ?? '';
306
+ }
307
+ catch {
308
+ return String(content);
309
+ }
310
+ }
311
+ return String(content);
312
+ }
@@ -0,0 +1,79 @@
1
+ import { AdapterIndex, type AdapterEndpointPhase, type AdapterOperation, type EndpointManagement, type EndpointManagementCapability } from '@zhin.js/adapter';
2
+ import type { RuntimeSnapshot, SnapshotLease } from '@zhin.js/plugin-runtime';
3
+ import type { ConversationRef, DeliveryReceipt, EndpointCapabilities, MessageRef } from '@zhin.js/im-contract';
4
+ import type { ConversationAddress, SendRequest } from './contracts.js';
5
+ export interface EndpointRuntimeSummary {
6
+ readonly id: string;
7
+ readonly name: string;
8
+ readonly adapter: string;
9
+ readonly owner: string;
10
+ readonly connected: boolean;
11
+ readonly status: 'online' | 'offline';
12
+ readonly phase: AdapterEndpointPhase;
13
+ readonly operations: readonly AdapterOperation[];
14
+ readonly managementCapabilities: readonly EndpointManagementCapability[];
15
+ }
16
+ export type EndpointRuntimeDetail = Omit<EndpointRuntimeSummary, 'id' | 'owner'>;
17
+ export interface RuntimeEndpointSendInput {
18
+ readonly adapter: string;
19
+ readonly endpointKey: string;
20
+ readonly conversation: ConversationAddress;
21
+ readonly content: unknown;
22
+ }
23
+ export interface RuntimeEndpointReactionInput {
24
+ readonly adapter: string;
25
+ readonly endpointKey: string;
26
+ readonly message: MessageRef;
27
+ readonly emoji: string;
28
+ readonly sceneType?: string;
29
+ readonly channelId?: string;
30
+ }
31
+ export interface RuntimeEndpointRemoveReactionInput {
32
+ readonly adapter: string;
33
+ readonly endpointKey: string;
34
+ readonly message: MessageRef;
35
+ readonly reactionId: string;
36
+ }
37
+ export interface RuntimeEndpointMessageInput {
38
+ readonly adapter: string;
39
+ readonly endpointKey: string;
40
+ readonly message: MessageRef;
41
+ }
42
+ export interface RuntimeEndpointEditInput extends RuntimeEndpointMessageInput {
43
+ readonly content: unknown;
44
+ }
45
+ export interface RuntimeEndpointTypingInput {
46
+ readonly adapter: string;
47
+ readonly endpointKey: string;
48
+ readonly conversation: ConversationRef;
49
+ readonly active?: boolean;
50
+ }
51
+ interface EndpointRuntimeContext {
52
+ acquire(): SnapshotLease;
53
+ release(lease: SnapshotLease): void;
54
+ send(request: SendRequest, snapshot: RuntimeSnapshot): Promise<DeliveryReceipt>;
55
+ }
56
+ /** Owns generation-leased Endpoint discovery, control, management, and Console delivery. */
57
+ export declare class EndpointRuntime {
58
+ #private;
59
+ private readonly context;
60
+ constructor(context: EndpointRuntimeContext);
61
+ list(): readonly EndpointRuntimeSummary[];
62
+ capabilities(input: {
63
+ readonly adapter: string;
64
+ readonly endpointKey: string;
65
+ }): EndpointCapabilities | undefined;
66
+ get(adapter: string, endpointKey: string): EndpointRuntimeDetail | null;
67
+ send(input: RuntimeEndpointSendInput): Promise<{
68
+ messageId: string;
69
+ }>;
70
+ addReaction(input: RuntimeEndpointReactionInput): Promise<string | null>;
71
+ removeReaction(input: RuntimeEndpointRemoveReactionInput): Promise<void>;
72
+ recall(input: RuntimeEndpointMessageInput): Promise<void>;
73
+ edit(input: RuntimeEndpointEditInput): Promise<string | null>;
74
+ typing(input: RuntimeEndpointTypingInput): Promise<void>;
75
+ withManagement<T>(adapter: string, endpointKey: string, run: (management: EndpointManagement) => T | Promise<T>): Promise<T | null>;
76
+ }
77
+ export declare function requireAdapters(snapshot: RuntimeSnapshot): AdapterIndex;
78
+ export declare function adapterTypeName(packageName: string | undefined): string | undefined;
79
+ export {};
@@ -0,0 +1,162 @@
1
+ import { adapterFeatureId, isAdapterIndex, resolveEndpointManagement, } from '@zhin.js/adapter';
2
+ /** Owns generation-leased Endpoint discovery, control, management, and Console delivery. */
3
+ export class EndpointRuntime {
4
+ context;
5
+ constructor(context) {
6
+ this.context = context;
7
+ }
8
+ list() {
9
+ return this.#withLease((snapshot) => requireAdapters(snapshot).describe().map((row) => Object.freeze({
10
+ id: String(row.id),
11
+ name: row.name,
12
+ adapter: adapterTypeName(snapshot.tree.get(row.owner)?.packageName) ?? row.name,
13
+ owner: row.owner,
14
+ connected: row.connected,
15
+ status: row.status,
16
+ phase: row.phase,
17
+ operations: row.operations,
18
+ managementCapabilities: row.managementCapabilities,
19
+ })), Object.freeze([]));
20
+ }
21
+ capabilities(input) {
22
+ return this.#withLease((snapshot) => {
23
+ const index = requireAdapters(snapshot);
24
+ const id = index.resolve(input.adapter, input.endpointKey);
25
+ return id ? index.capabilities(id) : undefined;
26
+ }, undefined);
27
+ }
28
+ get(adapter, endpointKey) {
29
+ return this.#withLease((snapshot) => {
30
+ const index = requireAdapters(snapshot);
31
+ const id = index.resolve(adapter, endpointKey);
32
+ if (!id)
33
+ return null;
34
+ const row = index.describe().find((item) => item.id === id);
35
+ if (!row)
36
+ return null;
37
+ return Object.freeze({
38
+ name: row.name,
39
+ adapter: adapterTypeName(snapshot.tree.get(row.owner)?.packageName) ?? row.name,
40
+ connected: row.connected,
41
+ status: row.status,
42
+ phase: row.phase,
43
+ operations: row.operations,
44
+ managementCapabilities: row.managementCapabilities,
45
+ });
46
+ }, null);
47
+ }
48
+ async send(input) {
49
+ const lease = this.context.acquire();
50
+ try {
51
+ const index = requireAdapters(lease.value);
52
+ const resolved = index.resolve(input.adapter, input.endpointKey);
53
+ if (!resolved)
54
+ throw new Error('endpoint not found');
55
+ const requester = index.owner(resolved);
56
+ const conversation = {
57
+ endpoint: { id: String(resolved), adapter: String(requester) },
58
+ ...input.conversation,
59
+ };
60
+ const result = await this.context.send({
61
+ conversation,
62
+ requester,
63
+ content: normalizeConsoleContent(input.content),
64
+ }, lease.value);
65
+ return { messageId: result.message?.id ?? '' };
66
+ }
67
+ finally {
68
+ this.context.release(lease);
69
+ }
70
+ }
71
+ async addReaction(input) {
72
+ return this.#withControl(input.adapter, input.endpointKey, 'reaction', (control) => control.addReaction?.(input.message, input.emoji, {
73
+ sceneType: input.sceneType,
74
+ channelId: input.channelId,
75
+ }) ?? null, null);
76
+ }
77
+ async removeReaction(input) {
78
+ await this.#withControl(input.adapter, input.endpointKey, 'reaction', (control) => control.removeReaction?.(input.message, input.reactionId), undefined);
79
+ }
80
+ async recall(input) {
81
+ await this.#withControl(input.adapter, input.endpointKey, 'recall', (control) => control.recall?.(input.message), undefined);
82
+ }
83
+ async edit(input) {
84
+ return this.#withControl(input.adapter, input.endpointKey, 'edit', (control) => control.edit?.(input.message, input.content) ?? null, null);
85
+ }
86
+ async typing(input) {
87
+ await this.#withControl(input.adapter, input.endpointKey, 'typing', (control) => control.typing?.(input.conversation, input.active), undefined);
88
+ }
89
+ async withManagement(adapter, endpointKey, run) {
90
+ let lease;
91
+ try {
92
+ lease = this.context.acquire();
93
+ }
94
+ catch {
95
+ return null;
96
+ }
97
+ try {
98
+ const endpoint = requireAdapters(lease.value).connection(adapter, endpointKey);
99
+ if (!endpoint)
100
+ return null;
101
+ return await run(resolveEndpointManagement(endpoint) ?? Object.freeze({}));
102
+ }
103
+ finally {
104
+ this.context.release(lease);
105
+ }
106
+ }
107
+ async #withControl(adapter, endpointKey, operation, run, fallback) {
108
+ let lease;
109
+ try {
110
+ lease = this.context.acquire();
111
+ }
112
+ catch {
113
+ return fallback;
114
+ }
115
+ try {
116
+ const index = requireAdapters(lease.value);
117
+ const id = index.resolve(adapter, endpointKey);
118
+ const control = id ? index.control(id, operation) : undefined;
119
+ return control ? await run(control) : fallback;
120
+ }
121
+ finally {
122
+ this.context.release(lease);
123
+ }
124
+ }
125
+ #withLease(operation, fallback) {
126
+ let lease;
127
+ try {
128
+ lease = this.context.acquire();
129
+ }
130
+ catch {
131
+ return fallback;
132
+ }
133
+ try {
134
+ return operation(lease.value);
135
+ }
136
+ catch {
137
+ return fallback;
138
+ }
139
+ finally {
140
+ this.context.release(lease);
141
+ }
142
+ }
143
+ }
144
+ export function requireAdapters(snapshot) {
145
+ const projection = snapshot.projections.get(adapterFeatureId);
146
+ if (!isAdapterIndex(projection)) {
147
+ throw new Error('Adapter Feature projection is not installed');
148
+ }
149
+ return projection;
150
+ }
151
+ export function adapterTypeName(packageName) {
152
+ if (!packageName)
153
+ return undefined;
154
+ return packageName.replace(/^@[^/]+\/adapter-/, '');
155
+ }
156
+ function normalizeConsoleContent(content) {
157
+ if (typeof content === 'string')
158
+ return content;
159
+ if (Array.isArray(content))
160
+ return content;
161
+ return String(content);
162
+ }