@zhin.js/core 1.1.54 → 1.1.56

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 (40) hide show
  1. package/lib/built/interaction-messages.d.ts +1 -1
  2. package/lib/index.d.ts +3 -0
  3. package/lib/index.js +1 -0
  4. package/lib/jsx/message-tags.d.ts +3 -3
  5. package/lib/jsx/message-tags.js +3 -0
  6. package/lib/plugin-runtime/im/captured-endpoint-operation.d.ts +5 -1
  7. package/lib/plugin-runtime/im/command-menu-navigation.d.ts +1 -1
  8. package/lib/plugin-runtime/im/command-menu-navigation.js +2 -1
  9. package/lib/plugin-runtime/im/contracts.d.ts +8 -1
  10. package/lib/plugin-runtime/im/contracts.js +20 -1
  11. package/lib/plugin-runtime/im/conversation-runtime.d.ts +2 -0
  12. package/lib/plugin-runtime/im/conversation-runtime.js +41 -4
  13. package/lib/plugin-runtime/im/endpoint-runtime.d.ts +4 -1
  14. package/lib/plugin-runtime/im/endpoint-runtime.js +38 -2
  15. package/lib/plugin-runtime/im/im-runtime.js +12 -4
  16. package/lib/plugin-runtime/im/inbound-runtime.d.ts +8 -1
  17. package/lib/plugin-runtime/im/inbound-runtime.js +1 -0
  18. package/lib/plugin-runtime/im/index.d.ts +2 -0
  19. package/lib/plugin-runtime/im/index.js +1 -0
  20. package/lib/plugin-runtime/im/message-dispatcher.js +2 -1
  21. package/lib/plugin-runtime/im/operation-resources.d.ts +15 -0
  22. package/lib/plugin-runtime/im/operation-resources.js +2 -0
  23. package/lib/plugin-runtime/im/outbound-delivery-runtime.d.ts +16 -2
  24. package/lib/plugin-runtime/im/outbound-delivery-runtime.js +49 -14
  25. package/lib/plugin-runtime/im/outbound-segments.d.ts +1 -1
  26. package/lib/plugin-runtime/im/outbound-segments.js +2 -20
  27. package/lib/plugin-runtime/im/progressive-reply.d.ts +52 -0
  28. package/lib/plugin-runtime/im/progressive-reply.js +495 -0
  29. package/lib/plugin-runtime/im/runtime-middleware.d.ts +2 -0
  30. package/lib/plugin-runtime/im/runtime-middleware.js +5 -0
  31. package/lib/side-event/index.d.ts +0 -1
  32. package/lib/side-event/index.js +0 -1
  33. package/lib/side-event/normalize.d.ts +0 -28
  34. package/lib/side-event/normalize.js +0 -100
  35. package/lib/side-event/scene-events.js +1 -1
  36. package/lib/side-event/types.d.ts +0 -6
  37. package/lib/side-event/types.js +1 -57
  38. package/package.json +15 -15
  39. package/lib/side-event/dispatch.d.ts +0 -15
  40. package/lib/side-event/dispatch.js +0 -168
@@ -35,13 +35,13 @@ export class OutboundDeliveryRuntime {
35
35
  this.context = context;
36
36
  this.#renderer = renderer;
37
37
  }
38
- async deliver(request, snapshot) {
38
+ async deliver(request, snapshot, execution) {
39
39
  let rendering;
40
- const receipt = await this.#deliver(request, snapshot, value => { rendering = value; });
40
+ const receipt = await this.#deliver(request, snapshot, value => { rendering = value; }, execution);
41
41
  this.context.diagnostics?.delivery(snapshot.generation, request.conversation, receipt, rendering);
42
42
  return receipt;
43
43
  }
44
- async #deliver(request, snapshot, observeRendering) {
44
+ async #deliver(request, snapshot, observeRendering, execution) {
45
45
  const adapter = request.conversation.endpoint.id;
46
46
  const boundEndpoint = request[operationEndpoint];
47
47
  if (boundEndpoint && boundEndpoint.canonicalId !== adapter)
@@ -154,7 +154,8 @@ export class OutboundDeliveryRuntime {
154
154
  : Array.isArray(payload) && payload.every(isCanonicalSegment) ? payload : undefined;
155
155
  // Capture known canonical content before the endpoint can mutate it.
156
156
  // Inline rendering bytes and opaque extensions never become new history.
157
- const contentSources = canonicalContent?.map(snapshotHistorySource);
157
+ let contentSources = canonicalContent?.map(snapshotHistorySource);
158
+ let contentUnavailable = false;
158
159
  const payloadLength = Array.isArray(payload) ? payload.length : 1;
159
160
  try {
160
161
  const sendRequest = {
@@ -162,10 +163,25 @@ export class OutboundDeliveryRuntime {
162
163
  locale: resolveLocale(request.locale ?? projectLocale(snapshot)),
163
164
  payload,
164
165
  };
165
- const result = boundEndpoint
166
- ? await boundEndpoint.send(sendRequest)
167
- : await requireAdapters(snapshot).send(adapter, sendRequest);
168
- receipt = receiptFromEndpointResult(result, request.conversation, payloadLength);
166
+ if (execution) {
167
+ const transported = await execution.send(sendRequest);
168
+ if (transported.confirmedContent) {
169
+ contentSources = transported.confirmedContent.map(snapshotHistorySource);
170
+ // Explicit physical evidence must never fall back to the planned logical body.
171
+ contentUnavailable = !contentSources.length || contentSources.some(source => source === undefined);
172
+ }
173
+ if (transported.contentUnavailable) {
174
+ contentSources = undefined;
175
+ contentUnavailable = true;
176
+ }
177
+ receipt = transported.result === undefined ? suppressedDeliveryReceipt()
178
+ : receiptFromEndpointResult(transported.result, request.conversation, contentSources?.length ?? payloadLength);
179
+ }
180
+ else {
181
+ const result = boundEndpoint ? await boundEndpoint.send(sendRequest)
182
+ : await requireAdapters(snapshot).send(adapter, sendRequest);
183
+ receipt = receiptFromEndpointResult(result, request.conversation, payloadLength);
184
+ }
169
185
  }
170
186
  catch (error) {
171
187
  receipt = receiptFromEndpointError(error, true, request.conversation, payloadLength);
@@ -175,25 +191,36 @@ export class OutboundDeliveryRuntime {
175
191
  if (receipt.status !== 'sent' && !receipt.failure?.deliveryUnknown && !receipt.parts?.length)
176
192
  revokeButtons?.();
177
193
  for (const part of evidence.parts) {
194
+ execution?.confirmed(part.part, part.content);
178
195
  const partReceipt = { status: 'sent', ...(part.part.message ? { message: part.part.message } : {}),
179
196
  ...(part.part.outboundTextDigest ? { outboundTextDigest: part.part.outboundTextDigest } : {}) };
180
- if (part.part.message) {
181
- await this.context.record(request, partReceipt, part.content ?? (receipt.parts ? 'unavailable' : undefined));
197
+ const history = execution?.history() ?? 'create';
198
+ if (part.part.message && history !== 'skip') {
199
+ try {
200
+ const content = part.content ?? (contentUnavailable || receipt.parts ? 'unavailable' : undefined);
201
+ if (history === 'create')
202
+ await this.context.record(request, partReceipt, content);
203
+ else
204
+ await this.context.recordUpdate?.(request, partReceipt, history.revision, content);
205
+ }
206
+ catch (error) {
207
+ logger.warn(formatCompact({ op: 'outbound_history_failed', error: error instanceof Error ? error.message : String(error) }));
208
+ }
182
209
  }
183
210
  try {
184
- this.context.ledger?.(request.conversation, partReceipt, part.content ?? (receipt.parts ? undefined : payload));
211
+ this.context.ledger?.(request.conversation, partReceipt, part.content ?? (contentUnavailable || receipt.parts ? undefined : payload));
185
212
  }
186
213
  catch (error) {
187
214
  logger.warn(`outbound ledger write failed: ${error instanceof Error ? error.message : String(error)}`);
188
215
  }
189
- if (part.part.message)
216
+ if (part.part.message && history !== 'skip')
190
217
  this.context.publish({
191
218
  direction: 'outbound',
192
219
  rendering: projection.rendering,
193
220
  conversation: request.conversation,
194
221
  requester: request.requester,
195
222
  contentPreview: part.content ? previewMessageContent(part.content)
196
- : receipt.parts ? '[Message content unavailable; inspect its reference.]' : previewMessageContent(payload),
223
+ : contentUnavailable || receipt.parts ? '[Message content unavailable; inspect its reference.]' : previewMessageContent(payload),
197
224
  messageId: part.part.message.id,
198
225
  timestamp: Date.now(),
199
226
  });
@@ -258,7 +285,7 @@ function receiptFromEndpointResult(result, conversation, payloadLength) {
258
285
  message: Object.freeze({ conversation, id: result }),
259
286
  });
260
287
  }
261
- function receiptFromEndpointError(error, attempted = true, conversation, payloadLength) {
288
+ export function receiptFromEndpointError(error, attempted = true, conversation, payloadLength) {
262
289
  if (error instanceof EndpointDeliveryError) {
263
290
  const parts = attempted && conversation ? normalizeEndpointParts(error.parts, conversation, payloadLength) : [];
264
291
  // Disposition is transport evidence; an error code alone cannot override it.
@@ -309,6 +336,14 @@ function normalizeEndpointParts(parts, conversation, payloadLength) {
309
336
  }));
310
337
  }
311
338
  function snapshotHistorySource(segment) {
339
+ if (segment.type === 'markdown') {
340
+ const data = segment.data;
341
+ // The AI authoring contract has one closed Markdown shape. Core extensions remain opaque.
342
+ if (Object.keys(segment).length !== 2 || !Object.hasOwn(segment, 'type') || !Object.hasOwn(segment, 'data')
343
+ || Object.keys(data).length !== 1 || !Object.hasOwn(data, 'content') || typeof data.content !== 'string')
344
+ return undefined;
345
+ return { type: 'markdown', data: { content: data.content } };
346
+ }
312
347
  // Forward entries and opaque card/extensions have no bounded, simple content contract here.
313
348
  if (!isStrictCanonicalSegment(segment) || segment.type === 'forward')
314
349
  return undefined;
@@ -59,7 +59,7 @@ export declare function resolveOutboundMediaPolicy(adapter: CapabilityId, snapsh
59
59
  export declare function isOutboundSegment(value: unknown): value is OutboundSegment;
60
60
  /**
61
61
  * 解析端点的出站 interactive 策略:优先读 adapter definition 上声明的
62
- * `segments.interactive`,否则按平台名查内置表,未知平台回退 'text'。
62
+ * `segments.interactive`(ADR 0044:原生按钮由 adapter 自己声明,core 不认平台名),否则回退 'text'。
63
63
  */
64
64
  export declare function resolveOutboundInteractivePolicy(adapter: CapabilityId, snapshot: RuntimeSnapshot): InteractivePolicy;
65
65
  /** Read declared support from this operation's snapshot without requiring live admission. */
@@ -47,18 +47,9 @@ export function isOutboundSegment(value) {
47
47
  && !Array.isArray(value)
48
48
  && typeof value.type === 'string';
49
49
  }
50
- /**
51
- * 平台名 → 出站 interactive 策略(adapter 未声明 `segments.interactive` 时
52
- * 的内置来源):telegram / discord 端点自行把 keyboard 编码为原生按钮;
53
- * 其余平台默认 'text'(编号文本降级)。
54
- */
55
- const OUTBOUND_INTERACTIVE_POLICY_BY_ADAPTER = {
56
- telegram: 'native',
57
- discord: 'native',
58
- };
59
50
  /**
60
51
  * 解析端点的出站 interactive 策略:优先读 adapter definition 上声明的
61
- * `segments.interactive`,否则按平台名查内置表,未知平台回退 'text'。
52
+ * `segments.interactive`(ADR 0044:原生按钮由 adapter 自己声明,core 不认平台名),否则回退 'text'。
62
53
  */
63
54
  export function resolveOutboundInteractivePolicy(adapter, snapshot) {
64
55
  const slot = snapshot.capabilities.get(adapter)
@@ -66,10 +57,7 @@ export function resolveOutboundInteractivePolicy(adapter, snapshot) {
66
57
  const declared = readDeclaredInteractivePolicy(slot?.definition);
67
58
  if (declared)
68
59
  return declared;
69
- const packageName = slot ? snapshot.tree.get(slot.owner)?.packageName : undefined;
70
- const adapterType = adapterTypeName(packageName);
71
- return (adapterType ? OUTBOUND_INTERACTIVE_POLICY_BY_ADAPTER[adapterType] : undefined)
72
- ?? DEFAULT_INTERACTIVE_POLICY;
60
+ return DEFAULT_INTERACTIVE_POLICY;
73
61
  }
74
62
  /** Read declared support from this operation's snapshot without requiring live admission. */
75
63
  export function resolveOutboundSupportedSegments(adapter, snapshot) {
@@ -190,12 +178,6 @@ function baseSlotCapabilityId(adapter) {
190
178
  const tilde = adapter.indexOf('~');
191
179
  return (tilde === -1 ? adapter : adapter.slice(0, tilde));
192
180
  }
193
- /** `@zhin.js/adapter-icqq` → `icqq`;非 adapter 包名原样返回。 */
194
- function adapterTypeName(packageName) {
195
- if (!packageName)
196
- return undefined;
197
- return packageName.replace(/^@[^/]+\/adapter-/, '');
198
- }
199
181
  /**
200
182
  * Normalize a rendered outbound payload toward canonical wire segments:
201
183
  * - segment arrays stay arrays (html segments converted per element,
@@ -0,0 +1,52 @@
1
+ import { type EndpointStreaming, type EndpointChildLease, type EndpointStreamSource } from '@zhin.js/adapter';
2
+ import { type DeliveryReceipt, type MessageRef, type Segment } from '@zhin.js/im-contract';
3
+ import type { Locale } from '@zhin.js/plugin-runtime';
4
+ import type { SendContent } from './contracts.js';
5
+ import { type OutboundDeliveryExecution } from './outbound-delivery-runtime.js';
6
+ /** Host-owned keys identify content, independently of model-authored or platform identifiers. */
7
+ export interface ReplyStreamSnapshot {
8
+ readonly revision: number;
9
+ readonly messages: readonly {
10
+ readonly key: string;
11
+ readonly complete: boolean;
12
+ readonly segments: readonly {
13
+ readonly key: string;
14
+ readonly complete: boolean;
15
+ readonly value: Segment;
16
+ }[];
17
+ }[];
18
+ }
19
+ export interface OpenReplyStreamOptions {
20
+ readonly locale?: Locale;
21
+ readonly source?: EndpointStreamSource;
22
+ readonly maxBufferedBytes?: number;
23
+ /** Revalidate trusted reply admission immediately before every platform submission. */
24
+ readonly beforeSubmit?: () => void;
25
+ /** Resource authorization/materialization; this must not submit an external message. */
26
+ readonly prepare?: (segments: readonly Segment[], signal: AbortSignal) => Promise<readonly Segment[]>;
27
+ }
28
+ export interface ConfirmedReplyContent {
29
+ /** Stable physical container key; one logical message can produce several containers. */
30
+ readonly key: string;
31
+ readonly segments: readonly Segment[];
32
+ readonly message?: MessageRef;
33
+ }
34
+ export interface CoreReplyStream {
35
+ readonly minIntervalMs?: number;
36
+ readonly receipt: DeliveryReceipt;
37
+ readonly confirmed: readonly ConfirmedReplyContent[];
38
+ /** Coalesces replaceable candidates; does not allocate a Promise for every model token. */
39
+ update(snapshot: ReplyStreamSnapshot): void;
40
+ finish(snapshot: ReplyStreamSnapshot): Promise<DeliveryReceipt>;
41
+ cancel(): Promise<DeliveryReceipt>;
42
+ }
43
+ interface ProgressiveReplyContext {
44
+ readonly endpoint: EndpointChildLease;
45
+ readonly streaming: EndpointStreaming;
46
+ readonly options: OpenReplyStreamOptions;
47
+ readonly deliver: (content: SendContent, execution: OutboundDeliveryExecution) => Promise<DeliveryReceipt>;
48
+ readonly release: () => void;
49
+ }
50
+ /** One producer, one sending pump, and one replaceable candidate rather than a queue per token. */
51
+ export declare function createCoreReplyStream(context: ProgressiveReplyContext): CoreReplyStream;
52
+ export {};