@charivo/core 0.26.0 → 0.28.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/README.md CHANGED
@@ -14,6 +14,10 @@ It exports:
14
14
  - `createLipSyncAnalyzer`: the shared audio-analysis utility the TTS manager
15
15
  and realtime clients use to compute mouth-open RMS and emit
16
16
  `tts:lipsync:update`
17
+ - `fetchWithTimeout` (with `DEFAULT_FETCH_TIMEOUT_MS`): the shared `fetch`
18
+ wrapper that enforces a timeout, layers an optional external `AbortSignal`
19
+ on top, and classifies the failure into the `CharivoError` taxonomy; the
20
+ llm/tts/stt/realtime/server remotes share it
17
21
  - modality-neutral tool contracts (`ToolDefinition`, `ToolRegistration`, ...)
18
22
  plus the validation and execution helpers (`validateToolArguments`,
19
23
  `assertToolResultObject`, `createToolRegistry`, `withToolTimeout`,
@@ -104,6 +108,7 @@ The `Charivo` instance wires managers together:
104
108
  - `getCurrentCharacter()`
105
109
  - `setCharacter(character)`
106
110
  - `userSay(text)`
111
+ - `interrupt()`
107
112
  - `dispose()`
108
113
  - `clearHistory()`
109
114
  - `getHistory()`
@@ -129,14 +134,17 @@ the outcome of a tool handler that had already started: that handler's
129
134
  `tool:result`/`tool:error` still fires, because it reports work that genuinely
130
135
  happened, so `turn:cancelled` is not an event barrier. Projections still stop,
131
136
  and no new tool work or request starts.
132
- `turn:cancelled` (`{ userMessageId }`) fires exactly once for it, and
133
- supersession by a newer `userSay(text)` is its only cause. What the superseded
134
- turn leaves behind is its **user message**: it is retained no matter which
135
- phase the cancellation landed in, always ordered ahead of the superseding
136
- turn's own message, and from then on it is an ordinary history entry subject
137
- to normal `maxHistoryTurns` eviction. Input the LLM manager refuses to store —
138
- empty content, exactly as today — is never stored. The unspoken reply is
139
- dropped.
137
+ `turn:cancelled` (`{ userMessageId }`) fires exactly once for it. Supersession
138
+ by a newer `userSay(text)` is one cause; `interrupt()` (below) is the only
139
+ other one. What the superseded turn leaves behind is its **user message**: it
140
+ is retained no matter which phase the cancellation landed in — ordered ahead
141
+ of the superseding turn's own message when a newer `userSay(text)` caused the
142
+ cancellation; `interrupt()` has no superseding message to order against, so
143
+ its retained message either enters history immediately (when an LLM manager
144
+ and character are attached) or ahead of whichever `userSay(text)` call flushes
145
+ it next — and from then on it is an ordinary history entry subject to normal
146
+ `maxHistoryTurns` eviction. Input the LLM manager refuses to store — empty
147
+ content, exactly as today — is never stored. The unspoken reply is dropped.
140
148
 
141
149
  A reply reaches history only at the **presentation boundary**: after its own
142
150
  character message has rendered (immediately, when no renderer is attached) and
@@ -204,19 +212,36 @@ checkpoints, since only the manager can enforce them. That is also why
204
212
  `tool:call` records an *attempted, dispatched* call, and can be the last event
205
213
  for a call whose handler was skipped, while `tool:result`/`tool:error` report
206
214
  a handler that actually ran. The superseded turn's in-flight LLM request is
207
- abandoned but keeps running; request-level `AbortSignal` threading is a
208
- follow-up. There is
215
+ aborted: `Charivo` passes the turn's `AbortSignal` as
216
+ `GenerateResponseOptions.signal`, and the built-in `@charivo/llm` manager
217
+ forwards it to the client as `LLMCallOptions.signal` on every request the turn
218
+ makes, tool rounds included. A client that ignores the optional `signal`
219
+ simply keeps the old keep-running behavior — its request settles late, and the
220
+ stale-turn check swallows the result either way. There is
209
221
  no guard interval either — a stray duplicate send is indistinguishable from a
210
222
  deliberate rapid correction, so debouncing belongs in the input layer.
211
223
 
212
- Nothing else cancels a turn: `setCharacter(...)`, `attachLLM(...)`,
213
- `detachLLM(...)`, `clearHistory()` and `dispose()` neither cancel an in-flight
214
- turn nor move the point at which a turn reads the manager or the character.
215
- Message validation is unchanged — `userSay("")` still emits `message:sent`,
216
- still runs the pre-turn stop and renders the user message, and still rejects
217
- with `CharivoStateError` from the LLM step (and still resolves when no manager
218
- and character are attached) — and an empty assistant reply is still stored,
219
- presented, and spoken exactly as before.
224
+ Besides `interrupt()` (below), nothing else cancels a turn: `setCharacter(...)`,
225
+ `attachLLM(...)`, `detachLLM(...)`, `clearHistory()` and `dispose()` neither
226
+ cancel an in-flight turn nor move the point at which a turn reads the manager
227
+ or the character. Message validation is unchanged — `userSay("")` still emits
228
+ `message:sent`, still runs the pre-turn stop and renders the user message, and
229
+ still rejects with `CharivoStateError` from the LLM step (and still resolves
230
+ when no manager and character are attached) — and an empty assistant reply is
231
+ still stored, presented, and spoken exactly as before.
232
+
233
+ `interrupt()` cuts off the in-progress turn and its speech now: it aborts the
234
+ live turn's LLM request through the same `AbortSignal` supersession uses, then
235
+ stops the TTS manager that turn is actually speaking on — the manager it
236
+ handed the reply to, which a mid-turn `attachTTS()` may have since replaced,
237
+ or, if the turn hasn't reached that step yet, whichever manager is currently
238
+ attached. It has no precondition: unlike `RealtimeManager.interrupt()`, which
239
+ requires an active, connected session, calling it with no turn in flight is
240
+ still idle-safe — it stops the attached TTS manager, resolves, and emits
241
+ nothing. The interrupted `userSay(text)` call **resolves**, and the turn is
242
+ announced via `turn:cancelled`, exactly as a supersession is. This is
243
+ cascade-only: it does not delegate to the realtime manager, so a realtime app
244
+ uses `getRealtimeManager()?.interrupt()` instead.
220
245
 
221
246
  The realtime path deliberately keeps the opposite contract:
222
247
  `RealtimeManager.sendMessage(...)` rejects while a response is in progress and
@@ -362,4 +387,24 @@ objects.
362
387
 
363
388
  The event bus isolates each listener: one that throws is reported via
364
389
  `console.error` and does not stop the listeners queued behind it, so `emit`
365
- never throws into its caller.
390
+ never throws into its caller. Each `emit` dispatches to a snapshot of the
391
+ listener list, so a listener removed mid-emit (its own `off`, or a
392
+ `disconnect()` that removes several) still fires for that emit; the removal
393
+ applies from the next one.
394
+
395
+ `EventMap` is an interface, so a package can carry its own events through the
396
+ bus by augmenting it — no core change needed:
397
+
398
+ ```ts
399
+ import "@charivo/core";
400
+
401
+ declare module "@charivo/core" {
402
+ interface EventMap {
403
+ "vrm:blendshape": { name: string; weight: number };
404
+ }
405
+ }
406
+ ```
407
+
408
+ Keep the `import` line: it makes the declaring file a module, so the block
409
+ augments the package. In a standalone `.d.ts` without it, the same block
410
+ shadows `@charivo/core` and every other export disappears.
package/dist/index.cjs CHANGED
@@ -2,13 +2,18 @@
2
2
 
3
3
  // src/bus.ts
4
4
  var EventBus = class {
5
- listeners = {};
5
+ // Object.create(null), not {}: EventMap is open to declaration merging, so
6
+ // an augmented event may be named after an Object.prototype member
7
+ // ("constructor", "toString", ...). On a prototype-backed store those keys
8
+ // inherit a truthy value, so `??=` skips the array init and on()/emit()
9
+ // throw. A null-prototype store has no inherited keys.
10
+ listeners = /* @__PURE__ */ Object.create(null);
6
11
  on(event, listener) {
7
12
  this.listeners[event] ??= [];
8
13
  this.listeners[event].push(listener);
9
14
  }
10
15
  emit(event, data) {
11
- this.listeners[event]?.forEach((listener) => {
16
+ [...this.listeners[event] ?? []].forEach((listener) => {
12
17
  try {
13
18
  listener(data);
14
19
  } catch (error) {
@@ -30,7 +35,7 @@ var EventBus = class {
30
35
  }
31
36
  }
32
37
  clear() {
33
- this.listeners = {};
38
+ this.listeners = /* @__PURE__ */ Object.create(null);
34
39
  }
35
40
  };
36
41
 
@@ -527,6 +532,83 @@ function snapshotToolResult(result, toolName, toolLabel = "Tool") {
527
532
  return { serialized, snapshot: parsed };
528
533
  }
529
534
 
535
+ // src/fetch-with-timeout.ts
536
+ var DEFAULT_FETCH_TIMEOUT_MS = 3e4;
537
+ function isAbortError(error) {
538
+ return error instanceof DOMException && error.name === "AbortError" || error instanceof Error && error.name === "AbortError";
539
+ }
540
+ function fetchWithTimeout(input, init, options, consumeBody) {
541
+ const {
542
+ timeoutMessage,
543
+ failureMessage = "Request failed",
544
+ timeoutMs = DEFAULT_FETCH_TIMEOUT_MS,
545
+ signal,
546
+ mapError
547
+ } = options;
548
+ const controller = new AbortController();
549
+ let abortSource = null;
550
+ const onExternalAbort = () => {
551
+ if (abortSource === null) {
552
+ abortSource = "external";
553
+ }
554
+ controller.abort(signal.reason);
555
+ };
556
+ if (signal?.aborted) {
557
+ abortSource = "external";
558
+ controller.abort(signal.reason);
559
+ } else {
560
+ signal?.addEventListener("abort", onExternalAbort);
561
+ }
562
+ const timeoutId = setTimeout(() => {
563
+ if (abortSource === null) {
564
+ abortSource = "timeout";
565
+ }
566
+ controller.abort();
567
+ }, timeoutMs);
568
+ const cleanup = () => {
569
+ clearTimeout(timeoutId);
570
+ signal?.removeEventListener("abort", onExternalAbort);
571
+ };
572
+ const classifyAbort = (error) => {
573
+ if (abortSource === "external" && (error === signal?.reason || isAbortError(error))) {
574
+ return { matched: true, value: error };
575
+ }
576
+ if (abortSource === "timeout" && isAbortError(error)) {
577
+ return {
578
+ matched: true,
579
+ value: new CharivoTimeoutError(timeoutMessage, { cause: error })
580
+ };
581
+ }
582
+ return { matched: false };
583
+ };
584
+ return fetch(input, { ...init, signal: controller.signal }).then(
585
+ (response) => {
586
+ if (!consumeBody) {
587
+ cleanup();
588
+ return response;
589
+ }
590
+ return Promise.resolve().then(() => consumeBody(response)).then(
591
+ (result) => {
592
+ cleanup();
593
+ return result;
594
+ },
595
+ (error) => {
596
+ cleanup();
597
+ const classified = classifyAbort(error);
598
+ throw classified.matched ? classified.value : error;
599
+ }
600
+ );
601
+ },
602
+ (error) => {
603
+ cleanup();
604
+ const classified = classifyAbort(error);
605
+ throw classified.matched ? classified.value : mapError?.(error) ?? new CharivoTransportError(failureMessage, {
606
+ cause: error instanceof Error ? error : void 0
607
+ });
608
+ }
609
+ );
610
+ }
611
+
530
612
  // src/index.ts
531
613
  var Charivo = class {
532
614
  eventBus;
@@ -665,7 +747,7 @@ var Charivo = class {
665
747
  this.messageSeq += 1;
666
748
  return `${Date.now()}-${this.messageSeq}`;
667
749
  }
668
- /** A turn is live only while it is the newest one. */
750
+ /** A turn is live only while it still owns the current epoch. */
669
751
  isStale(turn) {
670
752
  return this.turnEpoch !== turn.epoch;
671
753
  }
@@ -726,7 +808,11 @@ var Charivo = class {
726
808
  * Latest-wins: a newer call supersedes the in-flight turn, which then
727
809
  * resolves without performing any further turn-scoped effect or emitting
728
810
  * any further turn-scoped event. Its user message is retained regardless of
729
- * the phase the supersession lands in.
811
+ * the phase the supersession lands in. Supersession also aborts the turn's
812
+ * LLM request through the turn's own `AbortSignal`, so a client that honors
813
+ * it stops waiting on the provider; one that ignores it settles late and
814
+ * the turn merely goes quiet once it resumes. {@link Charivo.interrupt}
815
+ * cancels an in-flight turn the same way, without a successor taking over.
730
816
  */
731
817
  async userSay(content) {
732
818
  const userMessage = {
@@ -739,7 +825,8 @@ var Charivo = class {
739
825
  this.turnEpoch += 1;
740
826
  const turn = {
741
827
  epoch: this.turnEpoch,
742
- userMessageId: userMessage.id
828
+ userMessageId: userMessage.id,
829
+ abortController: new AbortController()
743
830
  };
744
831
  const superseded = this.activeTurn;
745
832
  this.activeTurn = turn;
@@ -749,6 +836,7 @@ var Charivo = class {
749
836
  this.eventBus.emit("message:sent", { message: userMessage });
750
837
  this.flushSupersededEntries();
751
838
  if (superseded) {
839
+ superseded.abortController.abort();
752
840
  this.eventBus.emit("turn:cancelled", {
753
841
  userMessageId: superseded.userMessageId
754
842
  });
@@ -802,7 +890,8 @@ var Charivo = class {
802
890
  }
803
891
  response = await generatingManager.generateResponse(userMessage, {
804
892
  callerOwnsHistory: true,
805
- isCancelled: () => this.isStale(turn)
893
+ isCancelled: () => this.isStale(turn),
894
+ signal: turn.abortController.signal
806
895
  });
807
896
  } catch (error) {
808
897
  if (this.isStale(turn)) {
@@ -869,6 +958,7 @@ var Charivo = class {
869
958
  return;
870
959
  }
871
960
  if (this.ttsManager) {
961
+ const speakingManager = this.ttsManager;
872
962
  try {
873
963
  this.eventBus.emit("tts:start", {
874
964
  text: response,
@@ -883,7 +973,8 @@ var Charivo = class {
883
973
  volume: this.character.voice.volume,
884
974
  voice: this.character.voice.voiceId
885
975
  } : void 0;
886
- await this.ttsManager.speak(response, ttsOptions);
976
+ turn.speakingTTSManager = speakingManager;
977
+ await speakingManager.speak(response, ttsOptions);
887
978
  if (this.isStale(turn)) {
888
979
  return;
889
980
  }
@@ -904,6 +995,48 @@ var Charivo = class {
904
995
  }
905
996
  }
906
997
  }
998
+ /**
999
+ * Cut off the in-progress turn and its speech now.
1000
+ *
1001
+ * The cascade counterpart of `RealtimeManager.interrupt()`: the live turn's
1002
+ * LLM request is aborted, the turn performs and emits nothing further, and
1003
+ * the TTS manager it is speaking on is stopped — the exact manager it handed
1004
+ * the reply to, which a mid-turn `attachTTS()` may since have replaced.
1005
+ * Resolving means that stop has completed, so no audio from the interrupted
1006
+ * turn starts afterwards. The interrupted `userSay()` **resolves**, and the
1007
+ * turn is announced as `turn:cancelled`, exactly as a supersession is.
1008
+ *
1009
+ * Unlike the realtime version, which requires an active, connected session,
1010
+ * this has no precondition: with no turn in flight it still stops the
1011
+ * attached TTS manager, resolves, and emits nothing.
1012
+ *
1013
+ * Realtime mode is not covered — this does not delegate to the realtime
1014
+ * manager. Use `getRealtimeManager()?.interrupt()` there.
1015
+ */
1016
+ async interrupt() {
1017
+ const interrupted = this.activeTurn;
1018
+ if (interrupted) {
1019
+ this.turnEpoch += 1;
1020
+ this.activeTurn = void 0;
1021
+ this.flushSupersededEntries();
1022
+ interrupted.abortController.abort();
1023
+ this.eventBus.emit("turn:cancelled", {
1024
+ userMessageId: interrupted.userMessageId
1025
+ });
1026
+ }
1027
+ const stopTarget = interrupted?.speakingTTSManager ?? this.ttsManager;
1028
+ if (stopTarget) {
1029
+ try {
1030
+ await stopTarget.stop();
1031
+ } catch (error) {
1032
+ throw toCharivoError(
1033
+ "provider",
1034
+ error,
1035
+ "Failed to stop TTS during interrupt"
1036
+ );
1037
+ }
1038
+ }
1039
+ }
907
1040
  /**
908
1041
  * Clear the conversation history from the LLM manager.
909
1042
  */
@@ -1102,6 +1235,7 @@ exports.CharivoProviderError = CharivoProviderError;
1102
1235
  exports.CharivoStateError = CharivoStateError;
1103
1236
  exports.CharivoTimeoutError = CharivoTimeoutError;
1104
1237
  exports.CharivoTransportError = CharivoTransportError;
1238
+ exports.DEFAULT_FETCH_TIMEOUT_MS = DEFAULT_FETCH_TIMEOUT_MS;
1105
1239
  exports.OPENAI_REALTIME_ADAPTER = OPENAI_REALTIME_ADAPTER;
1106
1240
  exports.OPENAI_REALTIME_AGENTS_ADAPTER = OPENAI_REALTIME_AGENTS_ADAPTER;
1107
1241
  exports.assertToolResultObject = assertToolResultObject;
@@ -1109,6 +1243,7 @@ exports.createCharivo = createCharivo;
1109
1243
  exports.createLipSyncAnalyzer = createLipSyncAnalyzer;
1110
1244
  exports.createToolFailureOutput = createToolFailureOutput;
1111
1245
  exports.createToolRegistry = createToolRegistry;
1246
+ exports.fetchWithTimeout = fetchWithTimeout;
1112
1247
  exports.getErrorMessage = getErrorMessage;
1113
1248
  exports.isCharivoError = isCharivoError;
1114
1249
  exports.snapshotToolResult = snapshotToolResult;