@charivo/core 0.25.0 → 0.27.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`,
@@ -28,7 +32,9 @@ provider classes (`OpenAILLMProvider`, `OpenClawLLMProvider`,
28
32
  `OpenAITTSProvider`, `OpenAISTTProvider`, `OpenAIRealtimeProvider`) are
29
33
  the three exceptions, exported directly as concrete classes: `Charivo`
30
34
  owns the instance lifecycle (wiring managers, the event bus, and
31
- `dispose()`) so it isn't behind a factory; `CharivoError` is a taxonomy
35
+ `dispose()`), so although `createCharivo()` is the preferred way in, the
36
+ class stays exported for wiring that happens after construction;
37
+ `CharivoError` is a taxonomy
32
38
  checked via `isCharivoError`/`error.code`, not constructed; the
33
39
  OpenAI/OpenClaw providers are exported because consumers rely on
34
40
  `instanceof` checks and provider methods outside the narrow core
@@ -46,14 +52,14 @@ pnpm add @charivo/core
46
52
  ## Usage
47
53
 
48
54
  ```ts
49
- import { Charivo } from "@charivo/core";
50
-
51
- const charivo = new Charivo();
52
-
53
- charivo.setCharacter({
54
- id: "hiyori",
55
- name: "Hiyori",
56
- personality: "Cheerful and helpful assistant",
55
+ import { createCharivo } from "@charivo/core";
56
+
57
+ const charivo = createCharivo({
58
+ character: {
59
+ id: "hiyori",
60
+ name: "Hiyori",
61
+ personality: "Cheerful and helpful assistant",
62
+ },
57
63
  });
58
64
 
59
65
  charivo.on("message:received", ({ message }) => {
@@ -63,6 +69,28 @@ charivo.on("message:received", ({ message }) => {
63
69
 
64
70
  ## `Charivo`
65
71
 
72
+ `createCharivo(options)` builds an instance with its managers already attached.
73
+ Every option is optional:
74
+
75
+ ```ts
76
+ const charivo = createCharivo({
77
+ renderer: renderManager,
78
+ llm: llmManager,
79
+ tts: ttsManager,
80
+ stt: sttManager,
81
+ realtime: realtimeManager,
82
+ character,
83
+ });
84
+ ```
85
+
86
+ Each option also accepts `null`, treated the same as omitting it, so a manager
87
+ that resolves conditionally can be passed through without a fallback.
88
+
89
+ It is exactly `new Charivo()` plus the matching `attach*` calls followed by
90
+ `setCharacter()`, and it returns an ordinary `Charivo` — supply what you have
91
+ up front and keep attaching later, as when swapping a provider at runtime.
92
+ Constructing the class directly still works and is not deprecated.
93
+
66
94
  The `Charivo` instance wires managers together:
67
95
 
68
96
  - `attachRenderer(renderManager)`
@@ -72,8 +100,15 @@ The `Charivo` instance wires managers together:
72
100
  - `attachRealtime(realtimeManager)`
73
101
  - `detachLLM()`
74
102
  - `detachRenderer()`
103
+ - `getRenderManager()`
104
+ - `getLLMManager()`
105
+ - `getTTSManager()`
106
+ - `getSTTManager()`
107
+ - `getRealtimeManager()`
108
+ - `getCurrentCharacter()`
75
109
  - `setCharacter(character)`
76
110
  - `userSay(text)`
111
+ - `interrupt()`
77
112
  - `dispose()`
78
113
  - `clearHistory()`
79
114
  - `getHistory()`
@@ -99,14 +134,17 @@ the outcome of a tool handler that had already started: that handler's
99
134
  `tool:result`/`tool:error` still fires, because it reports work that genuinely
100
135
  happened, so `turn:cancelled` is not an event barrier. Projections still stop,
101
136
  and no new tool work or request starts.
102
- `turn:cancelled` (`{ userMessageId }`) fires exactly once for it, and
103
- supersession by a newer `userSay(text)` is its only cause. What the superseded
104
- turn leaves behind is its **user message**: it is retained no matter which
105
- phase the cancellation landed in, always ordered ahead of the superseding
106
- turn's own message, and from then on it is an ordinary history entry subject
107
- to normal `maxHistoryTurns` eviction. Input the LLM manager refuses to store —
108
- empty content, exactly as today — is never stored. The unspoken reply is
109
- 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.
110
148
 
111
149
  A reply reaches history only at the **presentation boundary**: after its own
112
150
  character message has rendered (immediately, when no renderer is attached) and
@@ -174,19 +212,36 @@ checkpoints, since only the manager can enforce them. That is also why
174
212
  `tool:call` records an *attempted, dispatched* call, and can be the last event
175
213
  for a call whose handler was skipped, while `tool:result`/`tool:error` report
176
214
  a handler that actually ran. The superseded turn's in-flight LLM request is
177
- abandoned but keeps running; request-level `AbortSignal` threading is a
178
- 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
179
221
  no guard interval either — a stray duplicate send is indistinguishable from a
180
222
  deliberate rapid correction, so debouncing belongs in the input layer.
181
223
 
182
- Nothing else cancels a turn: `setCharacter(...)`, `attachLLM(...)`,
183
- `detachLLM(...)`, `clearHistory()` and `dispose()` neither cancel an in-flight
184
- turn nor move the point at which a turn reads the manager or the character.
185
- Message validation is unchanged — `userSay("")` still emits `message:sent`,
186
- still runs the pre-turn stop and renders the user message, and still rejects
187
- with `CharivoStateError` from the LLM step (and still resolves when no manager
188
- and character are attached) — and an empty assistant reply is still stored,
189
- 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.
190
245
 
191
246
  The realtime path deliberately keeps the opposite contract:
192
247
  `RealtimeManager.sendMessage(...)` rejects while a response is in progress and
@@ -332,4 +387,24 @@ objects.
332
387
 
333
388
  The event bus isolates each listener: one that throws is reported via
334
389
  `console.error` and does not stop the listeners queued behind it, so `emit`
335
- 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
  */
@@ -936,6 +1069,18 @@ var Charivo = class {
936
1069
  getRenderManager() {
937
1070
  return this.renderManager;
938
1071
  }
1072
+ /**
1073
+ * Get the current TTS manager instance.
1074
+ */
1075
+ getTTSManager() {
1076
+ return this.ttsManager;
1077
+ }
1078
+ /**
1079
+ * Get the current LLM manager instance.
1080
+ */
1081
+ getLLMManager() {
1082
+ return this.llmManager;
1083
+ }
939
1084
  /**
940
1085
  * Attach a Realtime manager to handle real-time conversation.
941
1086
  * Automatically connects the event emitter and enables Realtime mode.
@@ -1060,6 +1205,28 @@ var Charivo = class {
1060
1205
  }
1061
1206
  }
1062
1207
  };
1208
+ function createCharivo(options = {}) {
1209
+ const charivo = new Charivo();
1210
+ if (options.renderer) {
1211
+ charivo.attachRenderer(options.renderer);
1212
+ }
1213
+ if (options.llm) {
1214
+ charivo.attachLLM(options.llm);
1215
+ }
1216
+ if (options.tts) {
1217
+ charivo.attachTTS(options.tts);
1218
+ }
1219
+ if (options.stt) {
1220
+ charivo.attachSTT(options.stt);
1221
+ }
1222
+ if (options.realtime) {
1223
+ charivo.attachRealtime(options.realtime);
1224
+ }
1225
+ if (options.character) {
1226
+ charivo.setCharacter(options.character);
1227
+ }
1228
+ return charivo;
1229
+ }
1063
1230
 
1064
1231
  exports.Charivo = Charivo;
1065
1232
  exports.CharivoDisposeError = CharivoDisposeError;
@@ -1068,12 +1235,15 @@ exports.CharivoProviderError = CharivoProviderError;
1068
1235
  exports.CharivoStateError = CharivoStateError;
1069
1236
  exports.CharivoTimeoutError = CharivoTimeoutError;
1070
1237
  exports.CharivoTransportError = CharivoTransportError;
1238
+ exports.DEFAULT_FETCH_TIMEOUT_MS = DEFAULT_FETCH_TIMEOUT_MS;
1071
1239
  exports.OPENAI_REALTIME_ADAPTER = OPENAI_REALTIME_ADAPTER;
1072
1240
  exports.OPENAI_REALTIME_AGENTS_ADAPTER = OPENAI_REALTIME_AGENTS_ADAPTER;
1073
1241
  exports.assertToolResultObject = assertToolResultObject;
1242
+ exports.createCharivo = createCharivo;
1074
1243
  exports.createLipSyncAnalyzer = createLipSyncAnalyzer;
1075
1244
  exports.createToolFailureOutput = createToolFailureOutput;
1076
1245
  exports.createToolRegistry = createToolRegistry;
1246
+ exports.fetchWithTimeout = fetchWithTimeout;
1077
1247
  exports.getErrorMessage = getErrorMessage;
1078
1248
  exports.isCharivoError = isCharivoError;
1079
1249
  exports.snapshotToolResult = snapshotToolResult;