@zhin.js/core 1.1.52 → 1.1.54

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 (34) hide show
  1. package/README.md +13 -26
  2. package/lib/built/login-assist.d.ts +12 -3
  3. package/lib/built/login-assist.js +32 -26
  4. package/lib/feature/handler.d.ts +12 -2
  5. package/lib/feature/handler.js +2 -1
  6. package/lib/index.d.ts +3 -1
  7. package/lib/index.js +2 -0
  8. package/lib/plugin-runtime/im/captured-endpoint-operation.d.ts +30 -0
  9. package/lib/plugin-runtime/im/captured-endpoint-operation.js +1 -0
  10. package/lib/plugin-runtime/im/command-menu-navigation.d.ts +8 -1
  11. package/lib/plugin-runtime/im/command-menu-navigation.js +3 -3
  12. package/lib/plugin-runtime/im/contracts.d.ts +69 -48
  13. package/lib/plugin-runtime/im/contracts.js +65 -58
  14. package/lib/plugin-runtime/im/conversation-runtime.d.ts +2 -2
  15. package/lib/plugin-runtime/im/conversation-runtime.js +11 -4
  16. package/lib/plugin-runtime/im/endpoint-runtime.d.ts +9 -14
  17. package/lib/plugin-runtime/im/endpoint-runtime.js +156 -40
  18. package/lib/plugin-runtime/im/group-rule-violation.d.ts +5 -0
  19. package/lib/plugin-runtime/im/im-runtime.d.ts +3 -0
  20. package/lib/plugin-runtime/im/im-runtime.js +30 -5
  21. package/lib/plugin-runtime/im/inbound-runtime.d.ts +2 -0
  22. package/lib/plugin-runtime/im/inbound-runtime.js +138 -33
  23. package/lib/plugin-runtime/im/index.d.ts +1 -1
  24. package/lib/plugin-runtime/im/interaction-operation.d.ts +5 -1
  25. package/lib/plugin-runtime/im/interaction-runtime.d.ts +12 -2
  26. package/lib/plugin-runtime/im/interaction-runtime.js +50 -35
  27. package/lib/plugin-runtime/im/message-dispatcher.js +2 -2
  28. package/lib/plugin-runtime/im/operation-endpoint.d.ts +6 -0
  29. package/lib/plugin-runtime/im/operation-endpoint.js +2 -0
  30. package/lib/plugin-runtime/im/outbound-delivery-runtime.d.ts +2 -2
  31. package/lib/plugin-runtime/im/outbound-delivery-runtime.js +151 -38
  32. package/lib/plugin-runtime/im/outbound-renderer.d.ts +12 -3
  33. package/lib/plugin-runtime/im/outbound-renderer.js +20 -13
  34. package/package.json +14 -14
@@ -1,4 +1,4 @@
1
- import { createToken, generationAdmissionBinder, } from '@zhin.js/plugin-runtime';
1
+ import { OwnerOperation, createToken, generationAdmissionBinder, } from '@zhin.js/plugin-runtime';
2
2
  import { AsyncLocalStorage } from 'node:async_hooks';
3
3
  import { PermissionHost, permissionHostToken } from '@zhin.js/permission';
4
4
  import { CommandExecutionBudget, commandExecutionAdmissionToken } from '@zhin.js/command/internal/execution';
@@ -55,7 +55,7 @@ export class ImRuntime {
55
55
  this.#outbound = new OutboundDeliveryRuntime({
56
56
  diagnostics: this.#messageDiagnostics,
57
57
  ledger: (conversation, receipt, payload) => ledger.record(conversation, receipt, payload),
58
- record: (request, receipt) => this.#conversations.recordOutbound(request, receipt),
58
+ record: (request, receipt, canonicalContent) => this.#conversations.recordOutbound(request, receipt, canonicalContent),
59
59
  rememberFallback: (conversation, generation, map) => this.#interactions.rememberFallback(conversation, generation, map),
60
60
  publish: (event) => this.#messageEventStream.publish(event),
61
61
  prepareButtons: (request, snapshot) => this.#interactions.prepareButtons(request, snapshot),
@@ -65,6 +65,7 @@ export class ImRuntime {
65
65
  runCommandOperation: (controller, operation) => this.#commandOperation.run(controller, operation),
66
66
  diagnostics: this.#messageDiagnostics,
67
67
  interactions: this.#interactions,
68
+ captureOperation: input => this.endpoints.captureOperation(input),
68
69
  inboundClaim: options.inboundClaim,
69
70
  originClassifier,
70
71
  deduper,
@@ -83,6 +84,7 @@ export class ImRuntime {
83
84
  }, options.commandPrefix);
84
85
  this.endpoints = new EndpointRuntime({
85
86
  acquire: () => this.#acquire(),
87
+ retain: () => this.#retainSnapshot(),
86
88
  release: (lease) => this.#release(lease),
87
89
  send: (request, snapshot) => this.#deliver(request, snapshot),
88
90
  });
@@ -160,13 +162,26 @@ export class ImRuntime {
160
162
  self.#release(lease);
161
163
  }
162
164
  };
165
+ const runWithReceipt = (receive, gate) => self.runWithSnapshotView(async () => {
166
+ const lease = self.#acquire();
167
+ return receive(Object.freeze({ receive: event => {
168
+ if (!lease.active)
169
+ throw new Error('Endpoint receipt scope has ended');
170
+ lease.stopSignal.throwIfAborted();
171
+ return self.#operationSnapshot.run(lease, () => self.#inbound.receive(event, gate));
172
+ } }));
173
+ });
163
174
  const gateway = {
164
- receive: (event) => self.#inbound.receive(event),
175
+ run: runWithReceipt,
176
+ receive: event => self.runWithSnapshotView(() => self.#inbound.receive(event)),
165
177
  resolveLocale,
166
178
  [generationAdmissionBinder](gate) {
179
+ const owner = new OwnerOperation(gate, 'Endpoint ingress');
180
+ const run = (receive) => owner.run(() => runWithReceipt(receive, gate));
167
181
  return Object.freeze({
168
- receive: async (event) => gate.enter(() => self.#inbound.receive(event, gate)),
169
- resolveLocale: async (endpoint, senderId) => gate.enter(() => resolveLocale(endpoint, senderId)),
182
+ run,
183
+ receive: event => run(() => self.#inbound.receive(event, gate)),
184
+ resolveLocale: (endpoint, senderId) => run(() => resolveLocale(endpoint, senderId)),
170
185
  });
171
186
  },
172
187
  };
@@ -194,6 +209,10 @@ export class ImRuntime {
194
209
  createInteraction(message, bind) {
195
210
  return this.#inbound.createInteraction(message, bind);
196
211
  }
212
+ /** Reads a prompt within the caller's current generation lease; answering uses the original IM ingress. */
213
+ readPendingInteraction(conversation, subjectId, generation) {
214
+ return this.#interactions.readPendingInteraction(conversation, subjectId, generation);
215
+ }
197
216
  async send(request) {
198
217
  const lease = this.#acquire();
199
218
  try {
@@ -260,6 +279,12 @@ export class ImRuntime {
260
279
  selfIds: Object.freeze([...new Set(selfIds)]),
261
280
  }));
262
281
  }
282
+ #retainSnapshot() {
283
+ if (!this.#snapshots)
284
+ throw new Error('ImRuntime is not attached to a Root');
285
+ const inherited = this.#operationSnapshot.getStore();
286
+ return inherited?.active ? this.#snapshots.retain(inherited) : this.#snapshots.acquire();
287
+ }
263
288
  #acquire() {
264
289
  const inherited = this.#operationSnapshot.getStore();
265
290
  if (inherited?.active)
@@ -1,3 +1,4 @@
1
+ import type { CaptureEndpointOperationInput, CapturedEndpointOperation } from './captured-endpoint-operation.js';
1
2
  import type { GenerationAdmissionGate, RuntimeSnapshot, SnapshotLease } from '@zhin.js/plugin-runtime';
2
3
  import type { EndpointEvent, PeerRegistry } from '@zhin.js/adapter';
3
4
  import type { DeliveryReceipt } from '@zhin.js/im-contract';
@@ -17,6 +18,7 @@ interface InboundRuntimeContext {
17
18
  runCommandOperation?<T>(controller: CommandOperationController, operation: () => T): T;
18
19
  readonly diagnostics?: RuntimeMessageDiagnostics;
19
20
  readonly interactions: InboundInteractionPort;
21
+ captureOperation(input: CaptureEndpointOperationInput): CapturedEndpointOperation;
20
22
  readonly inboundClaim?: (message: Message) => boolean | Promise<boolean>;
21
23
  /** Trusted origin classifier. Absent: messages carry no origin (legacy behavior). */
22
24
  readonly originClassifier?: InboundOriginClassifier;
@@ -1,6 +1,7 @@
1
+ import { operationEndpoint } from './operation-endpoint.js';
1
2
  import { isMiddlewareIndex, middlewareFeatureId } from '@zhin.js/middleware';
2
3
  import { isHandlerIndex, handlerFeatureId } from '../../feature/handler.js';
3
- import { bindOperationInput } from '@zhin.js/feature-kit';
4
+ import { bindOperationInput, operationInputBinding } from '@zhin.js/feature-kit';
4
5
  import { formatCompact, getLogger, truncatePreview } from '@zhin.js/logger';
5
6
  import { RuntimeNotice } from '../../notice.js';
6
7
  import { RuntimeRequest } from '../../request.js';
@@ -44,7 +45,7 @@ export class InboundRuntime {
44
45
  return this.#receiveSideEvent(event);
45
46
  }
46
47
  }
47
- #routeInput(conversation, senderId, input, adapters, generation) {
48
+ #routeInput({ conversation, senderId, input, adapters, generation }) {
48
49
  const mentionTargets = (input.segments ?? [])
49
50
  .map((segment) => readMentionSegmentTarget(segment))
50
51
  .filter((target) => target !== '' && target !== 'all');
@@ -80,6 +81,7 @@ export class InboundRuntime {
80
81
  const lease = this.context.acquire();
81
82
  let active = true;
82
83
  let commandOperation;
84
+ let endpointLease;
83
85
  try {
84
86
  const adapter = source.endpoint.id;
85
87
  this.context.diagnostics?.begin(lease.value.generation, {
@@ -88,9 +90,16 @@ export class InboundRuntime {
88
90
  }, source.payload.message?.id);
89
91
  const adapters = requireAdapters(lease.value);
90
92
  const requester = adapters.owner(adapter);
93
+ endpointLease = adapters.acquireInbound(adapter, source.client);
94
+ const boundEndpoint = endpointLease;
95
+ const adapterInstance = adapters.adapterForEndpoint(adapter);
96
+ if (!adapterInstance)
97
+ throw new Error('Inbound Endpoint has no owning Adapter');
98
+ const operationSignal = AbortSignal.any([lease.stopSignal, boundEndpoint.signal]);
91
99
  // Routing identity belongs to the bound Endpoint, never to a protocol
92
100
  // normalizer's payload or a Plugin owner inferred from a CapabilityId.
93
101
  const conversation = Object.freeze({ ...source.payload.conversation,
102
+ ...(source.payload.conversation.parent ? { parent: Object.freeze({ ...source.payload.conversation.parent }) } : {}),
94
103
  endpoint: Object.freeze({ id: source.endpoint.id, adapter: adapters.clientAdapter(adapter) }),
95
104
  });
96
105
  const input = Object.freeze({ ...source.payload, conversation,
@@ -151,7 +160,7 @@ export class InboundRuntime {
151
160
  const deduper = this.context.deduper;
152
161
  if (typeof roomMembership.route === 'function' && typeof deduper.arbitrate === 'function') {
153
162
  const route = roomMembership.route.bind(roomMembership);
154
- const routeInput = this.#routeInput(conversation, senderId, input, adapters, lease.value.generation);
163
+ const routeInput = this.#routeInput({ conversation, senderId, input, adapters, generation: lease.value.generation });
155
164
  const verdict = deduper.arbitrate(conversation, senderId, input.message?.id, () => {
156
165
  try {
157
166
  const decision = route(routeInput);
@@ -236,11 +245,13 @@ export class InboundRuntime {
236
245
  const operationReply = (content, replyRequester = requester, targetConversation) => {
237
246
  if (!active)
238
247
  throw new Error('Message reply scope has ended');
248
+ boundEndpoint.assertActive();
239
249
  const effectiveConversation = targetConversation
240
250
  ? { ...targetConversation, endpoint: conversation.endpoint }
241
251
  : conversation;
242
252
  const deliver = () => this.context.deliver({
243
253
  conversation: effectiveConversation,
254
+ [operationEndpoint]: boundEndpoint,
244
255
  requester: replyRequester,
245
256
  locale,
246
257
  content,
@@ -261,19 +272,77 @@ export class InboundRuntime {
261
272
  };
262
273
  commandOperation = this.context.commandExecution?.openOperation({
263
274
  snapshot: lease.value, conversation, senderId: enrichedSender?.id,
264
- retirementSignal: lease.retirementSignal, reply: (owner, text) => operationReply(text, owner),
275
+ retirementSignal: operationSignal, reply: (owner, text) => operationReply(text, owner),
265
276
  });
266
277
  const execute = async () => {
267
- const message = new RuntimeMessage(conversation, input.content, lease.value.generation, operationReply, enrichedSender, Object.freeze({ ...input.metadata }), input.segments ? Object.freeze([...input.segments]) : undefined, input.message, input.endpointId, mentioned, input.replyTo, () => {
268
- if (!active)
269
- throw new Error('Message Client scope has ended');
270
- return source.client;
271
- }, source.endpoint.adapter, { snapshot: lease.value, locale,
272
- resolveCommands: (message) => this.#dispatcher.commandEnvironment(message, lease.value),
273
- retirementSignal: lease.retirementSignal, registerOperationView: commandOperation?.bind, assertActive: () => {
278
+ const segments = input.segments ? Object.freeze([...input.segments]) : undefined;
279
+ const platformRoles = input.sender?.roles?.filter(role => role !== 'master' && role !== 'trusted' && role !== 'user');
280
+ const authorizationRoles = enrichedSender?.roles?.filter(role => role === 'master' || role === 'trusted' || role === 'user');
281
+ const message = new RuntimeMessage({
282
+ conversation,
283
+ content: input.content,
284
+ sender: enrichedSender,
285
+ metadata: Object.freeze({ ...input.metadata }),
286
+ segments,
287
+ message: input.message,
288
+ endpointId: input.endpointId,
289
+ mentioned,
290
+ replyTo: input.replyTo,
291
+ }, {
292
+ generation: lease.value.generation,
293
+ reply: operationReply,
294
+ client: () => {
295
+ if (!active)
296
+ throw new Error('Message Client scope has ended');
297
+ boundEndpoint.assertActive();
298
+ return source.client;
299
+ },
300
+ clientAdapter: adapters.clientAdapter(adapter),
301
+ snapshot: lease.value,
302
+ signal: operationSignal,
303
+ session: {
304
+ adapter: adapterInstance,
305
+ endpoint: boundEndpoint.endpoint,
306
+ adapterName: adapters.clientAdapter(adapter),
307
+ scene: conversation,
308
+ event: input.event,
309
+ signal: operationSignal,
310
+ ...(enrichedSender
311
+ ? {
312
+ sender: Object.freeze({
313
+ id: enrichedSender.id,
314
+ ...(enrichedSender.name !== undefined ? { name: enrichedSender.name } : {}),
315
+ ...(platformRoles ? { platformRoles: Object.freeze(platformRoles) } : {}),
316
+ ...(authorizationRoles
317
+ ? { authorizationRoles: Object.freeze(authorizationRoles) }
318
+ : {}),
319
+ }),
320
+ }
321
+ : {}),
322
+ message: Object.freeze({
323
+ text: input.content,
324
+ receivedAt,
325
+ ...(input.message ? { id: input.message.id, ref: input.message } : {}),
326
+ ...(segments ? { segments } : {}),
327
+ ...(input.platformSentAt !== undefined ? { platformSentAt: input.platformSentAt } : {}),
328
+ ...(mentioned !== undefined ? { mentioned } : {}),
329
+ ...(input.replyTo ? { replyTo: Object.freeze({ ...input.replyTo }) } : {}),
330
+ }),
331
+ },
332
+ captureInteraction: owner => this.context.captureOperation({ target: conversation,
333
+ client: source.client, requester: owner, signal: boundEndpoint.signal }),
334
+ registerOperationView: commandOperation?.bind,
335
+ assertActive: () => {
274
336
  if (!active)
275
337
  throw new Error('Message author binding scope has ended');
276
- }, ...(origin ? { origin } : {}) });
338
+ boundEndpoint.assertActive();
339
+ },
340
+ ...(origin ? { origin } : {}),
341
+ presentation: {
342
+ locale,
343
+ resolveCommands: (message) => this.#dispatcher.commandEnvironment(message, lease.value),
344
+ },
345
+ });
277
346
  const conversationSequence = await this.context.recordIncoming(input, enrichedSender);
278
347
  let result = Object.freeze({ matched: false });
279
348
  let reply;
@@ -352,11 +421,11 @@ export class InboundRuntime {
352
421
  }
353
422
  }
354
423
  this.context.diagnostics?.step('handlers', 'started');
355
- await this.#runHandlers(lease, 'message.receive', [
356
- withEndpointEventPayload(source, message),
357
- ]);
424
+ await this.#runHandlers({ lease, event: 'message.receive', args: [
425
+ withEndpointEventPayload(source, message),
426
+ ], signal: operationSignal });
358
427
  this.context.diagnostics?.step('handlers', 'completed');
359
- const interactive = await this.#dispatchInteractive(message, requester, admission, lease.value);
428
+ const interactive = await this.#dispatchInteractive({ message, requester, admission, snapshot: lease.value });
360
429
  if (interactive)
361
430
  this.context.diagnostics?.route('interaction');
362
431
  const dispatched = interactive ? undefined : await this.#dispatcher.dispatchWithReply(message, lease.value, interactionFactory, (stage, status) => this.context.diagnostics?.step(stage, status));
@@ -437,28 +506,48 @@ export class InboundRuntime {
437
506
  }
438
507
  finally {
439
508
  active = false;
440
- this.context.release(lease);
509
+ try {
510
+ endpointLease?.release();
511
+ }
512
+ finally {
513
+ this.context.release(lease);
514
+ }
441
515
  }
442
516
  }
443
517
  }
444
518
  async #receiveCanonicalEndpointEvent(source) {
445
519
  const lease = this.context.acquire();
446
520
  let active = true;
521
+ let endpointLease;
447
522
  try {
523
+ const adapters = requireAdapters(lease.value);
524
+ endpointLease = adapters.acquireInbound(source.endpoint.id, source.client);
525
+ const captured = endpointLease;
526
+ const operationSignal = AbortSignal.any([lease.stopSignal, captured.signal]);
527
+ const assertActive = () => {
528
+ if (!active)
529
+ throw new Error('Endpoint event context expired with its generation operation');
530
+ // A held Root callback may drain across Root retirement; a retired child may not.
531
+ captured.assertActive();
532
+ };
448
533
  const context = {
449
534
  endpoint: {
450
535
  id: source.endpoint.id,
451
- adapter: requireAdapters(lease.value).clientAdapter(source.endpoint.id),
536
+ adapter: adapters.clientAdapter(source.endpoint.id),
452
537
  },
453
538
  generation: lease.value.generation,
454
539
  client: () => {
455
- if (!active)
456
- throw new Error('Endpoint event Client context expired with its generation operation');
540
+ assertActive();
457
541
  return source.client;
458
542
  },
459
543
  };
460
544
  const dispatch = async (payload) => {
461
- await this.#runHandlers(lease, source.name, [withEndpointEventPayload(source, payload)]);
545
+ await this.#runHandlers({ lease, event: source.name, args: [withEndpointEventPayload(source, payload)], signal: operationSignal,
546
+ captureInteraction: (owner, conversation) => {
547
+ assertActive();
548
+ return this.context.captureOperation({ target: conversation, client: source.client, requester: owner, signal: captured.signal });
549
+ },
550
+ });
462
551
  };
463
552
  if (source.payload.type !== source.name.split('.')[0]) {
464
553
  throw new TypeError('Endpoint event payload type does not match its gateway event');
@@ -481,7 +570,7 @@ export class InboundRuntime {
481
570
  finally {
482
571
  await recording;
483
572
  }
484
- });
573
+ }, assertActive);
485
574
  break;
486
575
  case 'system':
487
576
  await dispatch(new RuntimeSystemEvent(source.payload, context));
@@ -490,25 +579,38 @@ export class InboundRuntime {
490
579
  }
491
580
  finally {
492
581
  active = false;
493
- this.context.release(lease);
582
+ try {
583
+ endpointLease?.release();
584
+ }
585
+ finally {
586
+ this.context.release(lease);
587
+ }
494
588
  }
495
589
  }
496
590
  async #receiveSideEvent(event) {
497
591
  const lease = this.context.acquire();
592
+ let endpointLease;
498
593
  try {
499
- await this.#runHandlers(lease, event.name, [event]);
594
+ endpointLease = requireAdapters(lease.value).acquireInbound(event.endpoint.id, event.client);
595
+ const signal = AbortSignal.any([lease.stopSignal, endpointLease.signal]);
596
+ await this.#runHandlers({ lease, event: event.name, args: [event], signal });
500
597
  }
501
598
  finally {
502
- this.context.release(lease);
599
+ try {
600
+ endpointLease?.release();
601
+ }
602
+ finally {
603
+ this.context.release(lease);
604
+ }
503
605
  }
504
606
  }
505
- async #runHandlers(lease, event, args) {
607
+ async #runHandlers({ lease, event, args, signal = lease.stopSignal, captureInteraction }) {
506
608
  const snapshot = lease.value;
507
609
  const index = handlers(snapshot);
508
610
  if (!index)
509
611
  return;
510
612
  const options = {
511
- snapshot,
613
+ snapshot, signal,
512
614
  resolveInteraction: (name, interactionArgs, owner) => {
513
615
  const eventContext = interactionArgs[0];
514
616
  const payload = eventContext?.payload;
@@ -517,14 +619,16 @@ export class InboundRuntime {
517
619
  }
518
620
  if (name === 'notice.receive'
519
621
  || name === 'request.receive') {
520
- return this.#createInteractionForSideEvent(payload, snapshot, owner, lease.retirementSignal);
622
+ return this.#createInteractionForSideEvent({ payload: payload, snapshot, requester: owner, signal,
623
+ ...(captureInteraction ? { retain: () => captureInteraction(owner, payload.conversation) } : {}),
624
+ });
521
625
  }
522
626
  return undefined;
523
627
  },
524
628
  };
525
629
  await index.dispatch(event, args, options);
526
630
  }
527
- #createInteractionForSideEvent(payload, snapshot, requester, retirementSignal) {
631
+ #createInteractionForSideEvent({ payload, snapshot, requester, signal, retain }) {
528
632
  const conversation = payload.conversation;
529
633
  if (!conversation)
530
634
  return undefined;
@@ -539,9 +643,9 @@ export class InboundRuntime {
539
643
  content,
540
644
  }, snapshot),
541
645
  });
542
- return this.context.interactions.create(source, undefined, { snapshot, owner: requester, retirementSignal });
646
+ return this.context.interactions.create(source, undefined, { snapshot, owner: requester, signal, retain });
543
647
  }
544
- async #dispatchInteractive(message, requester, admission, snapshot) {
648
+ async #dispatchInteractive({ message, requester, admission, snapshot }) {
545
649
  const handled = await this.context.interactions.dispatch(message, admission, snapshot);
546
650
  return handled
547
651
  ? Object.freeze({ matched: true, command: 'interactive', owner: requester })
@@ -564,13 +668,13 @@ function resolveRoomMembership(snapshot) {
564
668
  function interactionResult(requester) {
565
669
  return Object.freeze({ matched: true, command: 'interaction', owner: requester });
566
670
  }
567
- async function withRequestActionScope(request, dispatch) {
671
+ async function withRequestActionScope(request, dispatch, assertOperation) {
568
672
  let active = true;
569
673
  const actions = new Set();
570
674
  const run = (action) => {
571
675
  if (!active)
572
676
  throw new Error('Request action port expired with its generation operation');
573
- const operation = Promise.resolve().then(action);
677
+ const operation = Promise.resolve().then(() => { assertOperation(); return action(); });
574
678
  actions.add(operation);
575
679
  void operation.then(() => actions.delete(operation), () => actions.delete(operation));
576
680
  return operation;
@@ -597,5 +701,6 @@ function withEndpointEventPayload(source, payload) {
597
701
  payload,
598
702
  endpoint: source.endpoint,
599
703
  client: source.client,
704
+ [operationInputBinding]: (owner, snapshot) => withEndpointEventPayload(source, bindOperationInput(payload, owner, snapshot)),
600
705
  });
601
706
  }
@@ -1,6 +1,6 @@
1
1
  export * from './contracts.js';
2
2
  export { EndpointRuntime } from './endpoint-runtime.js';
3
- export type { EndpointRuntimeDetail, EndpointRuntimeSummary, RuntimeEndpointEditInput, RuntimeEndpointMessageInput, RuntimeEndpointReactionInput, RuntimeEndpointRemoveReactionInput, RuntimeEndpointSendInput, RuntimeEndpointTypingInput, } from './endpoint-runtime.js';
3
+ export type { CaptureEndpointOperationInput, CapturedEndpointOperation, EndpointRuntimeDetail, EndpointRuntimeSummary, RuntimeEndpointEditInput, RuntimeEndpointMessageInput, RuntimeEndpointReactionInput, RuntimeEndpointRemoveReactionInput, RuntimeEndpointSendInput, RuntimeEndpointTypingInput, } from './endpoint-runtime.js';
4
4
  export * from './ingress-route.js';
5
5
  export { isMessageOrigin, roomMembershipToken } from './inbound-origin.js';
6
6
  export type { MessageOrigin, RoomInboundRouteInput, RoomMembershipPort, RoomRouteDecision, } from './inbound-origin.js';
@@ -1,8 +1,12 @@
1
+ import type { CapturedEndpointOperation } from './captured-endpoint-operation.js';
1
2
  import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
2
3
  /** Core-only trusted operation binding; never read from message metadata. */
3
4
  export declare const interactionOperationScope: unique symbol;
4
5
  export interface InteractionOperationScope {
5
6
  readonly snapshot: RuntimeSnapshot;
6
7
  readonly owner: PluginId;
7
- readonly retirementSignal?: AbortSignal;
8
+ /** Explicit stop/source/caller lifetime; not an HMR replacement notification. */
9
+ readonly signal?: AbortSignal;
10
+ /** Pin one actual source Client and independently owned snapshot until the question settles. */
11
+ readonly retain?: () => CapturedEndpointOperation;
8
12
  }
@@ -1,12 +1,20 @@
1
- import { type Locale } from '@zhin.js/plugin-runtime';
1
+ import { type RuntimeSnapshot, type Locale } from '@zhin.js/plugin-runtime';
2
2
  import { type ConversationRef, type DeliveryReceipt, type MessageRef } from '@zhin.js/im-contract';
3
3
  import type { UserInteraction } from '@zhin.js/interaction';
4
- import { type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
5
4
  import { type Message, type MessageSenderRef, type SendContent, type SendRequest } from './contracts.js';
6
5
  import { type InteractionOperationScope } from './interaction-operation.js';
7
6
  import { RuntimeInteractiveRouter } from './interactive-router.js';
8
7
  import type { Segment } from '../../built/segment-contract/types.js';
9
8
  import { type JsxButtonBatch } from './jsx-button-registry.js';
9
+ /** A live conversational prompt; its callbacks still require the original subject and generation. */
10
+ export interface PendingUserInteraction {
11
+ readonly id: string;
12
+ readonly generation: number;
13
+ readonly conversation: ConversationRef;
14
+ readonly subjectId: string;
15
+ readonly expiresAt: number;
16
+ readonly segments: SendContent;
17
+ }
10
18
  export interface UserInteractionSource {
11
19
  readonly locale?: Locale;
12
20
  readonly generation?: number;
@@ -34,6 +42,8 @@ export declare class RuntimeInteractionCoordinator<Admission = never> {
34
42
  readonly content: string;
35
43
  readonly segments?: readonly Segment[];
36
44
  }): boolean;
45
+ /** Read-only current prompt; never re-delivers, renews its deadline or accepts an answer. */
46
+ readPendingInteraction(conversation: ConversationRef, subjectId: string, generation: number): PendingUserInteraction | undefined;
37
47
  createForMessage(message: Message, bind?: {
38
48
  readonly subjectId: string;
39
49
  }): UserInteraction | undefined;