@charivo/core 0.22.0 → 0.24.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
@@ -200,12 +200,65 @@ interface LLMClient {
200
200
  /** Tool-calling variant; clients that support function calling implement this alongside call. */
201
201
  callWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
202
202
  }
203
+ /**
204
+ * Undoes a single `addToHistory` call. Idempotent: invoking it more than once
205
+ * changes nothing after the first call.
206
+ */
207
+ type HistoryRollback = () => void;
208
+ interface GenerateResponseOptions {
209
+ /**
210
+ * The caller has already placed the message in history via `addToHistory`
211
+ * and commits the reply itself, so the manager must perform no history
212
+ * writes for this call — no append, no reply commit, no rollback on
213
+ * failure. Character and message validation and prompt building are
214
+ * unchanged; the prompt still comes from history, which already holds the
215
+ * message.
216
+ */
217
+ callerOwnsHistory?: boolean;
218
+ /**
219
+ * Reports that this call has been superseded, so it should stop doing work
220
+ * on the caller's behalf. It is consulted before each new unit of tool work
221
+ * — before each tool call in a round, between a call's `tool:call` emission
222
+ * and its handler, and before each follow-up request — and on every
223
+ * projected emission, including repeated emissions from inside a single
224
+ * projector. Once it returns `true` the call starts nothing further and
225
+ * projects nothing further, then resolves with the latest response text.
226
+ *
227
+ * It does not govern history writes, and it aborts neither an in-flight
228
+ * request nor an already-running handler, so tool side effects are not
229
+ * rolled back. Note the resulting event split: `tool:call` records an
230
+ * attempted, dispatched call and can be the last event for a call whose
231
+ * handler was skipped, while `tool:result` and `tool:error` report a
232
+ * handler that actually ran.
233
+ */
234
+ isCancelled?: () => boolean;
235
+ }
203
236
  interface LLMManager {
204
237
  setCharacter(character: Character): void;
205
238
  getCharacter(): Character | null;
206
239
  clearHistory(): void;
207
240
  getHistory(): Message[];
208
- generateResponse(message: Message): Promise<string>;
241
+ /**
242
+ * Ensure `message` is present in this manager's history, synchronously —
243
+ * it appends and returns a handle, never a promise — and without emitting
244
+ * events or calling back into `Charivo`.
245
+ *
246
+ * A message this manager cannot store is rejected with a typed state error
247
+ * (`CharivoStateError`). The built-in manager mirrors each of its two write
248
+ * paths as they behave today: a `type: "user"` message needs non-empty
249
+ * string content, while a `type: "character"` message is stored exactly as
250
+ * produced, empty content included.
251
+ *
252
+ * Appends only when that exact object is not already present (reference
253
+ * identity, not id), then holds the configured history bound. The returned
254
+ * handle removes the message if it is still present and restores what *this*
255
+ * call evicted, but only when no other write has intervened. When nothing
256
+ * was appended — the object was already there — the call mutates nothing and
257
+ * returns a no-op handle, so it can neither delete the message nor
258
+ * invalidate an earlier handle.
259
+ */
260
+ addToHistory(message: Message): HistoryRollback;
261
+ generateResponse(message: Message, options?: GenerateResponseOptions): Promise<string>;
209
262
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
210
263
  registerTool?(tool: ToolRegistration): void;
211
264
  unregisterTool?(name: string): void;
@@ -337,6 +390,25 @@ type EventMap = {
337
390
  "message:received": {
338
391
  message: Message;
339
392
  };
393
+ /**
394
+ * An in-flight turn was superseded by a newer `userSay`. Emitted exactly
395
+ * once for every superseded turn, on the cascade path only — the realtime
396
+ * path keeps its own contract and never emits this. Supersession is the
397
+ * only cause, so the payload needs no cause discriminator, and the
398
+ * superseded `userSay` call still **resolves**.
399
+ *
400
+ * What the event reports is supersession. Retention is the separate
401
+ * guarantee: with an LLM manager and a character attached, the superseded
402
+ * turn's valid user message is already in history when this fires, ahead of
403
+ * the superseding turn's own message; with none attached it holds its queue
404
+ * position and is written by the next `userSay`. Input the manager refuses
405
+ * to store is announced here too but never stored, exactly as today.
406
+ *
407
+ * The `message:sent` carrying the same id always precedes this event.
408
+ */
409
+ "turn:cancelled": {
410
+ userMessageId: string;
411
+ };
340
412
  "character:speak": {
341
413
  character: Character;
342
414
  text: string;
@@ -601,6 +673,10 @@ declare class Charivo {
601
673
  private realtimeManager?;
602
674
  private character?;
603
675
  private isRealtimeMode;
676
+ private turnEpoch;
677
+ private activeTurn?;
678
+ private readonly turnQueue;
679
+ private messageSeq;
604
680
  constructor();
605
681
  /**
606
682
  * Attach a render manager to handle character visualization.
@@ -659,9 +735,37 @@ declare class Charivo {
659
735
  * Automatically propagates to all attached managers (LLM, Renderer).
660
736
  */
661
737
  setCharacter(character: Character): void;
738
+ /**
739
+ * Ids are for observability only, so a timestamp plus a per-instance
740
+ * counter is enough: same-millisecond turns no longer collide, which
741
+ * matters because turn:cancelled names its turn by user message id.
742
+ */
743
+ private nextMessageId;
744
+ /** A turn is live only while it is the newest one. */
745
+ private isStale;
746
+ private removeQueueEntry;
747
+ /**
748
+ * Head-first drain shared by both flushes, so history order is call order at
749
+ * any reentrancy depth. Both return immediately on an in-progress head.
750
+ *
751
+ * With `requester` null this is flush-superseded: it writes entries whose
752
+ * owner is no longer the active turn, stops at the first entry the active
753
+ * turn owns, and swallows rejections. With a requester it is flush-through:
754
+ * it writes older entries first, then the requester's own entry, recording
755
+ * that write's rollback handle and propagating a rejection of that entry
756
+ * alone.
757
+ */
758
+ private writeQueuedEntries;
759
+ /** Entry-block flush: drains the superseded backlog into the live manager. */
760
+ private flushSupersededEntries;
662
761
  /**
663
762
  * Process a user message and generate a character response.
664
763
  * Orchestrates the full conversation flow: rendering, LLM generation, and TTS playback.
764
+ *
765
+ * Latest-wins: a newer call supersedes the in-flight turn, which then
766
+ * resolves without performing any further turn-scoped effect or emitting
767
+ * any further turn-scoped event. Its user message is retained regardless of
768
+ * the phase the supersession lands in.
665
769
  */
666
770
  userSay(content: string): Promise<void>;
667
771
  /**
@@ -721,4 +825,4 @@ declare class Charivo {
721
825
  private finishDispose;
722
826
  }
723
827
 
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 };
828
+ 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
  }
@@ -650,76 +654,251 @@ var Charivo = class {
650
654
  this.realtimeManager.setCharacter(character);
651
655
  }
652
656
  }
657
+ /**
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.
661
+ */
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;
698
+ try {
699
+ const handle = manager.addToHistory(head.message);
700
+ this.removeQueueEntry(head);
701
+ if (isOwnEntry) {
702
+ head.turn.rollback = { manager, handle };
703
+ return;
704
+ }
705
+ } catch (error) {
706
+ this.removeQueueEntry(head);
707
+ if (isOwnEntry) {
708
+ throw error;
709
+ }
710
+ }
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
+ }
653
720
  /**
654
721
  * Process a user message and generate a character response.
655
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.
656
728
  */
657
729
  async userSay(content) {
658
730
  const userMessage = {
659
- id: Date.now().toString(),
731
+ id: this.nextMessageId(),
660
732
  content,
661
733
  timestamp: /* @__PURE__ */ new Date(),
662
734
  type: "user"
663
735
  };
664
- this.eventBus.emit("message:sent", { message: userMessage });
665
- if (this.renderManager) {
666
- try {
667
- await this.renderManager.render(userMessage);
668
- } catch (error) {
669
- 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
+ }
670
770
  }
671
- }
672
- if (this.llmManager && this.character) {
673
- const response = await this.llmManager.generateResponse(userMessage).catch(
674
- (error) => Promise.reject(
675
- toCharivoError(
676
- "provider",
677
- error,
678
- "Failed to generate a character response"
679
- )
680
- )
681
- );
682
- const characterMessage = {
683
- id: Date.now().toString() + "_response",
684
- content: response,
685
- timestamp: /* @__PURE__ */ new Date(),
686
- characterId: this.character.id,
687
- type: "character"
688
- };
689
- this.eventBus.emit("message:received", { message: characterMessage });
690
- this.eventBus.emit("character:speak", {
691
- character: this.character,
692
- text: response
693
- });
694
771
  if (this.renderManager) {
695
772
  try {
696
- await this.renderManager.render(characterMessage, this.character);
773
+ await this.renderManager.render(userMessage);
697
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();
698
810
  throw toCharivoError(
699
- "state",
811
+ "provider",
700
812
  error,
701
- "Failed to render character response"
813
+ "Failed to generate a character response"
702
814
  );
703
815
  }
704
- }
705
- 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
+ }
706
854
  try {
707
- this.eventBus.emit("tts:start", {
708
- text: response,
709
- characterId: this.character.id
710
- });
711
- const ttsOptions = this.character.voice ? {
712
- rate: this.character.voice.rate,
713
- pitch: this.character.voice.pitch,
714
- volume: this.character.voice.volume,
715
- voice: this.character.voice.voiceId
716
- } : void 0;
717
- await this.ttsManager.speak(response, ttsOptions);
718
- this.eventBus.emit("tts:end", { characterId: this.character.id });
855
+ generatingManager.addToHistory(characterMessage);
719
856
  } catch (error) {
720
- const typedError = toCharivoError("provider", error);
721
- 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;
722
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;
723
902
  }
724
903
  }
725
904
  }
@@ -869,6 +1048,7 @@ var Charivo = class {
869
1048
  this.renderManager = void 0;
870
1049
  this.character = void 0;
871
1050
  this.isRealtimeMode = false;
1051
+ this.turnQueue.length = 0;
872
1052
  this.eventBus.clear();
873
1053
  return this.finishDispose(firstError);
874
1054
  }