@charivo/core 0.23.0 → 0.25.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/dist/index.d.ts CHANGED
@@ -9,6 +9,13 @@ interface GazeCoordinates {
9
9
  interface AvatarControlCatalog {
10
10
  expressions: string[];
11
11
  motions: Record<string, number>;
12
+ /**
13
+ * Optional semantic descriptions for each expression.
14
+ * Keys should correspond to IDs in the `expressions` array.
15
+ * Entries whose key is not present in `expressions` are ignored by consumers.
16
+ * When omitted or empty, no semantic hints are provided (preserving today's behavior).
17
+ */
18
+ expressionDescriptions?: Record<string, string>;
12
19
  }
13
20
  interface Character {
14
21
  id: string;
@@ -200,12 +207,65 @@ interface LLMClient {
200
207
  /** Tool-calling variant; clients that support function calling implement this alongside call. */
201
208
  callWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
202
209
  }
210
+ /**
211
+ * Undoes a single `addToHistory` call. Idempotent: invoking it more than once
212
+ * changes nothing after the first call.
213
+ */
214
+ type HistoryRollback = () => void;
215
+ interface GenerateResponseOptions {
216
+ /**
217
+ * The caller has already placed the message in history via `addToHistory`
218
+ * and commits the reply itself, so the manager must perform no history
219
+ * writes for this call — no append, no reply commit, no rollback on
220
+ * failure. Character and message validation and prompt building are
221
+ * unchanged; the prompt still comes from history, which already holds the
222
+ * message.
223
+ */
224
+ callerOwnsHistory?: boolean;
225
+ /**
226
+ * Reports that this call has been superseded, so it should stop doing work
227
+ * on the caller's behalf. It is consulted before each new unit of tool work
228
+ * — before each tool call in a round, between a call's `tool:call` emission
229
+ * and its handler, and before each follow-up request — and on every
230
+ * projected emission, including repeated emissions from inside a single
231
+ * projector. Once it returns `true` the call starts nothing further and
232
+ * projects nothing further, then resolves with the latest response text.
233
+ *
234
+ * It does not govern history writes, and it aborts neither an in-flight
235
+ * request nor an already-running handler, so tool side effects are not
236
+ * rolled back. Note the resulting event split: `tool:call` records an
237
+ * attempted, dispatched call and can be the last event for a call whose
238
+ * handler was skipped, while `tool:result` and `tool:error` report a
239
+ * handler that actually ran.
240
+ */
241
+ isCancelled?: () => boolean;
242
+ }
203
243
  interface LLMManager {
204
244
  setCharacter(character: Character): void;
205
245
  getCharacter(): Character | null;
206
246
  clearHistory(): void;
207
247
  getHistory(): Message[];
208
- generateResponse(message: Message): Promise<string>;
248
+ /**
249
+ * Ensure `message` is present in this manager's history, synchronously —
250
+ * it appends and returns a handle, never a promise — and without emitting
251
+ * events or calling back into `Charivo`.
252
+ *
253
+ * A message this manager cannot store is rejected with a typed state error
254
+ * (`CharivoStateError`). The built-in manager mirrors each of its two write
255
+ * paths as they behave today: a `type: "user"` message needs non-empty
256
+ * string content, while a `type: "character"` message is stored exactly as
257
+ * produced, empty content included.
258
+ *
259
+ * Appends only when that exact object is not already present (reference
260
+ * identity, not id), then holds the configured history bound. The returned
261
+ * handle removes the message if it is still present and restores what *this*
262
+ * call evicted, but only when no other write has intervened. When nothing
263
+ * was appended — the object was already there — the call mutates nothing and
264
+ * returns a no-op handle, so it can neither delete the message nor
265
+ * invalidate an earlier handle.
266
+ */
267
+ addToHistory(message: Message): HistoryRollback;
268
+ generateResponse(message: Message, options?: GenerateResponseOptions): Promise<string>;
209
269
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
210
270
  registerTool?(tool: ToolRegistration): void;
211
271
  unregisterTool?(name: string): void;
@@ -337,6 +397,25 @@ type EventMap = {
337
397
  "message:received": {
338
398
  message: Message;
339
399
  };
400
+ /**
401
+ * An in-flight turn was superseded by a newer `userSay`. Emitted exactly
402
+ * once for every superseded turn, on the cascade path only — the realtime
403
+ * path keeps its own contract and never emits this. Supersession is the
404
+ * only cause, so the payload needs no cause discriminator, and the
405
+ * superseded `userSay` call still **resolves**.
406
+ *
407
+ * What the event reports is supersession. Retention is the separate
408
+ * guarantee: with an LLM manager and a character attached, the superseded
409
+ * turn's valid user message is already in history when this fires, ahead of
410
+ * the superseding turn's own message; with none attached it holds its queue
411
+ * position and is written by the next `userSay`. Input the manager refuses
412
+ * to store is announced here too but never stored, exactly as today.
413
+ *
414
+ * The `message:sent` carrying the same id always precedes this event.
415
+ */
416
+ "turn:cancelled": {
417
+ userMessageId: string;
418
+ };
340
419
  "character:speak": {
341
420
  character: Character;
342
421
  text: string;
@@ -601,6 +680,10 @@ declare class Charivo {
601
680
  private realtimeManager?;
602
681
  private character?;
603
682
  private isRealtimeMode;
683
+ private turnEpoch;
684
+ private activeTurn?;
685
+ private readonly turnQueue;
686
+ private messageSeq;
604
687
  constructor();
605
688
  /**
606
689
  * Attach a render manager to handle character visualization.
@@ -659,9 +742,37 @@ declare class Charivo {
659
742
  * Automatically propagates to all attached managers (LLM, Renderer).
660
743
  */
661
744
  setCharacter(character: Character): void;
745
+ /**
746
+ * Ids are for observability only, so a timestamp plus a per-instance
747
+ * counter is enough: same-millisecond turns no longer collide, which
748
+ * matters because turn:cancelled names its turn by user message id.
749
+ */
750
+ private nextMessageId;
751
+ /** A turn is live only while it is the newest one. */
752
+ private isStale;
753
+ private removeQueueEntry;
754
+ /**
755
+ * Head-first drain shared by both flushes, so history order is call order at
756
+ * any reentrancy depth. Both return immediately on an in-progress head.
757
+ *
758
+ * With `requester` null this is flush-superseded: it writes entries whose
759
+ * owner is no longer the active turn, stops at the first entry the active
760
+ * turn owns, and swallows rejections. With a requester it is flush-through:
761
+ * it writes older entries first, then the requester's own entry, recording
762
+ * that write's rollback handle and propagating a rejection of that entry
763
+ * alone.
764
+ */
765
+ private writeQueuedEntries;
766
+ /** Entry-block flush: drains the superseded backlog into the live manager. */
767
+ private flushSupersededEntries;
662
768
  /**
663
769
  * Process a user message and generate a character response.
664
770
  * Orchestrates the full conversation flow: rendering, LLM generation, and TTS playback.
771
+ *
772
+ * Latest-wins: a newer call supersedes the in-flight turn, which then
773
+ * resolves without performing any further turn-scoped effect or emitting
774
+ * any further turn-scoped event. Its user message is retained regardless of
775
+ * the phase the supersession lands in.
665
776
  */
666
777
  userSay(content: string): Promise<void>;
667
778
  /**
@@ -721,4 +832,4 @@ declare class Charivo {
721
832
  private finishDispose;
722
833
  }
723
834
 
724
- export { type AvatarControlCatalog, type BrowserLifecycleCallbacks, type Character, Charivo, type CharivoConfig, CharivoDisposeError, CharivoError, type CharivoErrorCode, type CharivoErrorKind, type CharivoErrorOptions, type CharivoEventBus, type CharivoEventEmitter, CharivoProviderError, CharivoStateError, CharivoTimeoutError, CharivoTransportError, type Conversation, type EventMap, type GazeCoordinates, type LLMAdapter, type LLMClient, type LLMManager, type LLMManagerWithTools, type LLMMessage, type LLMProvider, type LLMToolCall, type LLMToolResponse, type LipSyncAnalyzer, type LipSyncAnalyzerOptions, type Message, type MotionSelection, OPENAI_REALTIME_ADAPTER, OPENAI_REALTIME_AGENTS_ADAPTER, type Plugin, type RealtimeConnectionState, type RealtimeManager, type RealtimeProvider, type RealtimeReconnectCause, type RealtimeResponseStatus, type RealtimeSessionBootstrap, type RealtimeSessionConfig, type RealtimeSessionRequest, type RealtimeSessionStatus, type RealtimeSessionTransitionReason, type RealtimeState, type RealtimeToolChoice, type RealtimeTransportKind, type RealtimeUsageEvent, type RenderManager, type Renderer, type STTManager, type STTOptions, type STTProvider, type STTTranscriber, type TTSManager, type TTSOptions, type TTSPlaybackMode, type TTSPlayer, type TTSProvider, type ToolContext, type ToolDefinition, type ToolHandler, type ToolRegistration, type ToolRegistry, type ToolResultProjector, type ToolResultProjectorContext, type ToolResultSnapshot, assertToolResultObject, createLipSyncAnalyzer, createToolFailureOutput, createToolRegistry, getErrorMessage, isCharivoError, snapshotToolResult, subscribeBrowserLifecycle, toCharivoError, validateToolArguments, withToolTimeout };
835
+ export { type AvatarControlCatalog, type BrowserLifecycleCallbacks, type Character, Charivo, type CharivoConfig, CharivoDisposeError, CharivoError, type CharivoErrorCode, type CharivoErrorKind, type CharivoErrorOptions, type CharivoEventBus, type CharivoEventEmitter, CharivoProviderError, CharivoStateError, CharivoTimeoutError, CharivoTransportError, type Conversation, type EventMap, type GazeCoordinates, type GenerateResponseOptions, type HistoryRollback, type LLMAdapter, type LLMClient, type LLMManager, type LLMManagerWithTools, type LLMMessage, type LLMProvider, type LLMToolCall, type LLMToolResponse, type LipSyncAnalyzer, type LipSyncAnalyzerOptions, type Message, type MotionSelection, OPENAI_REALTIME_ADAPTER, OPENAI_REALTIME_AGENTS_ADAPTER, type Plugin, type RealtimeConnectionState, type RealtimeManager, type RealtimeProvider, type RealtimeReconnectCause, type RealtimeResponseStatus, type RealtimeSessionBootstrap, type RealtimeSessionConfig, type RealtimeSessionRequest, type RealtimeSessionStatus, type RealtimeSessionTransitionReason, type RealtimeState, type RealtimeToolChoice, type RealtimeTransportKind, type RealtimeUsageEvent, type RenderManager, type Renderer, type STTManager, type STTOptions, type STTProvider, type STTTranscriber, type TTSManager, type TTSOptions, type TTSPlaybackMode, type TTSPlayer, type TTSProvider, type ToolContext, type ToolDefinition, type ToolHandler, type ToolRegistration, type ToolRegistry, type ToolResultProjector, type ToolResultProjectorContext, type ToolResultSnapshot, assertToolResultObject, createLipSyncAnalyzer, createToolFailureOutput, createToolRegistry, getErrorMessage, isCharivoError, snapshotToolResult, subscribeBrowserLifecycle, toCharivoError, validateToolArguments, withToolTimeout };
package/dist/index.js CHANGED
@@ -535,6 +535,10 @@ var Charivo = class {
535
535
  realtimeManager;
536
536
  character;
537
537
  isRealtimeMode = false;
538
+ turnEpoch = 0;
539
+ activeTurn;
540
+ turnQueue = [];
541
+ messageSeq = 0;
538
542
  constructor() {
539
543
  this.eventBus = new EventBus();
540
544
  }
@@ -651,83 +655,250 @@ var Charivo = class {
651
655
  }
652
656
  }
653
657
  /**
654
- * Process a user message and generate a character response.
655
- * Orchestrates the full conversation flow: rendering, LLM generation, and TTS playback.
658
+ * Ids are for observability only, so a timestamp plus a per-instance
659
+ * counter is enough: same-millisecond turns no longer collide, which
660
+ * matters because turn:cancelled names its turn by user message id.
656
661
  */
657
- async userSay(content) {
658
- if (this.ttsManager) {
662
+ nextMessageId() {
663
+ this.messageSeq += 1;
664
+ return `${Date.now()}-${this.messageSeq}`;
665
+ }
666
+ /** A turn is live only while it is the newest one. */
667
+ isStale(turn) {
668
+ return this.turnEpoch !== turn.epoch;
669
+ }
670
+ removeQueueEntry(entry) {
671
+ const index = this.turnQueue.indexOf(entry);
672
+ if (index !== -1) {
673
+ this.turnQueue.splice(index, 1);
674
+ }
675
+ }
676
+ /**
677
+ * Head-first drain shared by both flushes, so history order is call order at
678
+ * any reentrancy depth. Both return immediately on an in-progress head.
679
+ *
680
+ * With `requester` null this is flush-superseded: it writes entries whose
681
+ * owner is no longer the active turn, stops at the first entry the active
682
+ * turn owns, and swallows rejections. With a requester it is flush-through:
683
+ * it writes older entries first, then the requester's own entry, recording
684
+ * that write's rollback handle and propagating a rejection of that entry
685
+ * alone.
686
+ */
687
+ writeQueuedEntries(manager, requester) {
688
+ while (this.turnQueue.length > 0) {
689
+ const head = this.turnQueue[0];
690
+ if (head.inProgress) {
691
+ return;
692
+ }
693
+ const isOwnEntry = head.turn === requester;
694
+ if (!isOwnEntry && head.turn === this.activeTurn) {
695
+ return;
696
+ }
697
+ head.inProgress = true;
659
698
  try {
660
- await this.ttsManager.stop();
699
+ const handle = manager.addToHistory(head.message);
700
+ this.removeQueueEntry(head);
701
+ if (isOwnEntry) {
702
+ head.turn.rollback = { manager, handle };
703
+ return;
704
+ }
661
705
  } catch (error) {
662
- const typedError = toCharivoError("provider", error);
663
- this.eventBus.emit("tts:error", { error: typedError });
706
+ this.removeQueueEntry(head);
707
+ if (isOwnEntry) {
708
+ throw error;
709
+ }
664
710
  }
665
711
  }
712
+ }
713
+ /** Entry-block flush: drains the superseded backlog into the live manager. */
714
+ flushSupersededEntries() {
715
+ if (!this.llmManager || !this.character) {
716
+ return;
717
+ }
718
+ this.writeQueuedEntries(this.llmManager, null);
719
+ }
720
+ /**
721
+ * Process a user message and generate a character response.
722
+ * Orchestrates the full conversation flow: rendering, LLM generation, and TTS playback.
723
+ *
724
+ * Latest-wins: a newer call supersedes the in-flight turn, which then
725
+ * resolves without performing any further turn-scoped effect or emitting
726
+ * any further turn-scoped event. Its user message is retained regardless of
727
+ * the phase the supersession lands in.
728
+ */
729
+ async userSay(content) {
666
730
  const userMessage = {
667
- id: Date.now().toString(),
731
+ id: this.nextMessageId(),
668
732
  content,
669
733
  timestamp: /* @__PURE__ */ new Date(),
670
734
  type: "user"
671
735
  };
672
- this.eventBus.emit("message:sent", { message: userMessage });
673
- if (this.renderManager) {
674
- try {
675
- await this.renderManager.render(userMessage);
676
- } catch (error) {
677
- throw toCharivoError("state", error, "Failed to render user message");
736
+ const entryTTSManager = this.ttsManager;
737
+ this.turnEpoch += 1;
738
+ const turn = {
739
+ epoch: this.turnEpoch,
740
+ userMessageId: userMessage.id
741
+ };
742
+ const superseded = this.activeTurn;
743
+ this.activeTurn = turn;
744
+ const entry = { message: userMessage, turn, inProgress: false };
745
+ this.turnQueue.push(entry);
746
+ try {
747
+ this.eventBus.emit("message:sent", { message: userMessage });
748
+ this.flushSupersededEntries();
749
+ if (superseded) {
750
+ this.eventBus.emit("turn:cancelled", {
751
+ userMessageId: superseded.userMessageId
752
+ });
753
+ }
754
+ if (this.isStale(turn)) {
755
+ return;
756
+ }
757
+ if (entryTTSManager) {
758
+ try {
759
+ await entryTTSManager.stop();
760
+ } catch (error) {
761
+ if (this.isStale(turn)) {
762
+ return;
763
+ }
764
+ const typedError = toCharivoError("provider", error);
765
+ this.eventBus.emit("tts:error", { error: typedError });
766
+ }
767
+ if (this.isStale(turn)) {
768
+ return;
769
+ }
678
770
  }
679
- }
680
- if (this.llmManager && this.character) {
681
- const response = await this.llmManager.generateResponse(userMessage).catch(
682
- (error) => Promise.reject(
683
- toCharivoError(
684
- "provider",
685
- error,
686
- "Failed to generate a character response"
687
- )
688
- )
689
- );
690
- const characterMessage = {
691
- id: Date.now().toString() + "_response",
692
- content: response,
693
- timestamp: /* @__PURE__ */ new Date(),
694
- characterId: this.character.id,
695
- type: "character"
696
- };
697
- this.eventBus.emit("message:received", { message: characterMessage });
698
- this.eventBus.emit("character:speak", {
699
- character: this.character,
700
- text: response
701
- });
702
771
  if (this.renderManager) {
703
772
  try {
704
- await this.renderManager.render(characterMessage, this.character);
773
+ await this.renderManager.render(userMessage);
705
774
  } catch (error) {
775
+ if (this.isStale(turn)) {
776
+ return;
777
+ }
778
+ throw toCharivoError("state", error, "Failed to render user message");
779
+ }
780
+ if (this.isStale(turn)) {
781
+ return;
782
+ }
783
+ }
784
+ if (this.llmManager && this.character) {
785
+ const generatingManager = this.llmManager;
786
+ let response;
787
+ try {
788
+ for (; ; ) {
789
+ this.writeQueuedEntries(generatingManager, turn);
790
+ if (!this.turnQueue.includes(entry)) {
791
+ break;
792
+ }
793
+ await Promise.resolve();
794
+ if (this.isStale(turn)) {
795
+ return;
796
+ }
797
+ }
798
+ if (this.isStale(turn)) {
799
+ return;
800
+ }
801
+ response = await generatingManager.generateResponse(userMessage, {
802
+ callerOwnsHistory: true,
803
+ isCancelled: () => this.isStale(turn)
804
+ });
805
+ } catch (error) {
806
+ if (this.isStale(turn)) {
807
+ return;
808
+ }
809
+ turn.rollback?.handle();
706
810
  throw toCharivoError(
707
- "state",
811
+ "provider",
708
812
  error,
709
- "Failed to render character response"
813
+ "Failed to generate a character response"
710
814
  );
711
815
  }
712
- }
713
- if (this.ttsManager) {
816
+ if (this.isStale(turn)) {
817
+ return;
818
+ }
819
+ const characterMessage = {
820
+ id: this.nextMessageId() + "_response",
821
+ content: response,
822
+ timestamp: /* @__PURE__ */ new Date(),
823
+ characterId: this.character.id,
824
+ type: "character"
825
+ };
826
+ this.eventBus.emit("message:received", { message: characterMessage });
827
+ if (this.isStale(turn)) {
828
+ return;
829
+ }
830
+ this.eventBus.emit("character:speak", {
831
+ character: this.character,
832
+ text: response
833
+ });
834
+ if (this.isStale(turn)) {
835
+ return;
836
+ }
837
+ if (this.renderManager) {
838
+ try {
839
+ await this.renderManager.render(characterMessage, this.character);
840
+ } catch (error) {
841
+ if (this.isStale(turn)) {
842
+ return;
843
+ }
844
+ throw toCharivoError(
845
+ "state",
846
+ error,
847
+ "Failed to render character response"
848
+ );
849
+ }
850
+ if (this.isStale(turn)) {
851
+ return;
852
+ }
853
+ }
714
854
  try {
715
- this.eventBus.emit("tts:start", {
716
- text: response,
717
- characterId: this.character.id
718
- });
719
- const ttsOptions = this.character.voice ? {
720
- rate: this.character.voice.rate,
721
- pitch: this.character.voice.pitch,
722
- volume: this.character.voice.volume,
723
- voice: this.character.voice.voiceId
724
- } : void 0;
725
- await this.ttsManager.speak(response, ttsOptions);
726
- this.eventBus.emit("tts:end", { characterId: this.character.id });
855
+ generatingManager.addToHistory(characterMessage);
727
856
  } catch (error) {
728
- const typedError = toCharivoError("provider", error);
729
- this.eventBus.emit("tts:error", { error: typedError });
857
+ if (this.isStale(turn)) {
858
+ return;
859
+ }
860
+ throw toCharivoError(
861
+ "provider",
862
+ error,
863
+ "Failed to generate a character response"
864
+ );
865
+ }
866
+ if (this.isStale(turn)) {
867
+ return;
730
868
  }
869
+ if (this.ttsManager) {
870
+ try {
871
+ this.eventBus.emit("tts:start", {
872
+ text: response,
873
+ characterId: this.character.id
874
+ });
875
+ if (this.isStale(turn)) {
876
+ return;
877
+ }
878
+ const ttsOptions = this.character.voice ? {
879
+ rate: this.character.voice.rate,
880
+ pitch: this.character.voice.pitch,
881
+ volume: this.character.voice.volume,
882
+ voice: this.character.voice.voiceId
883
+ } : void 0;
884
+ await this.ttsManager.speak(response, ttsOptions);
885
+ if (this.isStale(turn)) {
886
+ return;
887
+ }
888
+ this.eventBus.emit("tts:end", { characterId: this.character.id });
889
+ } catch (error) {
890
+ if (this.isStale(turn)) {
891
+ return;
892
+ }
893
+ const typedError = toCharivoError("provider", error);
894
+ this.eventBus.emit("tts:error", { error: typedError });
895
+ }
896
+ }
897
+ }
898
+ } finally {
899
+ if (!this.isStale(turn)) {
900
+ this.removeQueueEntry(entry);
901
+ this.activeTurn = void 0;
731
902
  }
732
903
  }
733
904
  }
@@ -877,6 +1048,7 @@ var Charivo = class {
877
1048
  this.renderManager = void 0;
878
1049
  this.character = void 0;
879
1050
  this.isRealtimeMode = false;
1051
+ this.turnQueue.length = 0;
880
1052
  this.eventBus.clear();
881
1053
  return this.finishDispose(firstError);
882
1054
  }