@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 +64 -19
- package/dist/index.cjs +143 -8
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +119 -25
- package/dist/index.d.ts +119 -25
- package/dist/index.js +142 -9
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
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
|
|
133
|
-
|
|
134
|
-
turn leaves behind is its **user message**: it
|
|
135
|
-
phase the cancellation landed in
|
|
136
|
-
turn's own message
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
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
|
-
|
|
208
|
-
|
|
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
|
-
|
|
213
|
-
`detachLLM(...)`, `clearHistory()` and `dispose()` neither
|
|
214
|
-
turn nor move the point at which a turn reads the manager
|
|
215
|
-
Message validation is unchanged — `userSay("")` still emits
|
|
216
|
-
still runs the pre-turn stop and renders the user message, and
|
|
217
|
-
with `CharivoStateError` from the LLM step (and still resolves
|
|
218
|
-
and character are attached) — and an empty assistant reply is
|
|
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
|
-
|
|
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]
|
|
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
|
|
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
|
-
|
|
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;
|