@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/dist/index.d.cts CHANGED
@@ -37,25 +37,6 @@ interface Message {
37
37
  characterId?: string;
38
38
  type: "user" | "character" | "system";
39
39
  }
40
- interface Conversation {
41
- id: string;
42
- messages: Message[];
43
- characterId?: string;
44
- createdAt: Date;
45
- updatedAt: Date;
46
- }
47
- interface Plugin {
48
- id: string;
49
- name: string;
50
- version: string;
51
- enabled: boolean;
52
- }
53
- interface CharivoConfig {
54
- characters: Character[];
55
- plugins: Plugin[];
56
- llmProvider?: string;
57
- renderProvider?: string;
58
- }
59
40
  type RealtimeTransportKind = "webrtc" | "websocket";
60
41
  type RealtimeToolChoice = "auto" | "none" | "required";
61
42
  declare const OPENAI_REALTIME_ADAPTER = "openai-webrtc";
@@ -199,13 +180,20 @@ interface LLMProvider {
199
180
  /** Tool-calling variant; providers that support function calling implement this alongside generateResponse. */
200
181
  generateResponseWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
201
182
  }
183
+ /**
184
+ * Transport-level cancellation for a single `LLMClient` call. Implementations
185
+ * that do not support cancellation may ignore the field.
186
+ */
187
+ interface LLMCallOptions {
188
+ signal?: AbortSignal;
189
+ }
202
190
  interface LLMClient {
203
191
  call(messages: Array<{
204
192
  role: string;
205
193
  content: string;
206
- }>): Promise<string>;
194
+ }>, options?: LLMCallOptions): Promise<string>;
207
195
  /** Tool-calling variant; clients that support function calling implement this alongside call. */
208
- callWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
196
+ callWithTools?(messages: LLMMessage[], tools: ToolDefinition[], options?: LLMCallOptions): Promise<LLMToolResponse>;
209
197
  }
210
198
  /**
211
199
  * Undoes a single `addToHistory` call. Idempotent: invoking it more than once
@@ -231,14 +219,28 @@ interface GenerateResponseOptions {
231
219
  * projector. Once it returns `true` the call starts nothing further and
232
220
  * projects nothing further, then resolves with the latest response text.
233
221
  *
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.
222
+ * It does not govern history writes, and it does not abort an already-
223
+ * running handler, so tool side effects are not rolled back. Cancelling an
224
+ * in-flight request is `signal`'s job, not this predicate's - see `signal`
225
+ * below. Note the resulting event split: `tool:call` records an attempted,
226
+ * dispatched call and can be the last event for a call whose handler was
227
+ * skipped, while `tool:result` and `tool:error` report a handler that
228
+ * actually ran.
240
229
  */
241
230
  isCancelled?: () => boolean;
231
+ /**
232
+ * Cancellation for the in-flight LLM call, forwarded to the client as
233
+ * `LLMCallOptions.signal` on every `call`/`callWithTools` request this turn
234
+ * makes, tool rounds included. Distinct from `isCancelled`: `isCancelled`
235
+ * gates new work between steps and never aborts an in-flight request;
236
+ * `signal` is what aborts the request itself. Whether an abort actually
237
+ * cancels the transport depends on the client - clients that ignore
238
+ * `LLMCallOptions.signal` (allowed by the contract) run to completion
239
+ * regardless. A mid-request abort surfaces as a rejection, which a
240
+ * latest-wins caller swallows via its own stale-turn check rather than this
241
+ * manager doing anything special with it.
242
+ */
243
+ signal?: AbortSignal;
242
244
  }
243
245
  interface LLMManager {
244
246
  setCharacter(character: Character): void;
@@ -390,7 +392,27 @@ interface RealtimeManager {
390
392
  getRegisteredTools(): ToolDefinition[];
391
393
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
392
394
  }
393
- type EventMap = {
395
+ /**
396
+ * An interface (not a type alias) so third-party packages can extend it via
397
+ * declaration merging — a custom renderer or manager declares its own events
398
+ * without a core change:
399
+ *
400
+ * ```ts
401
+ * import "@charivo/core";
402
+ *
403
+ * declare module "@charivo/core" {
404
+ * interface EventMap {
405
+ * "vrm:blendshape": { name: string; weight: number };
406
+ * }
407
+ * }
408
+ * ```
409
+ *
410
+ * The `import` line matters: it makes the declaring file a module, so
411
+ * `declare module` *augments* the package. In a plain script or `.d.ts` with
412
+ * no top-level import/export, the same block *shadows* `@charivo/core`
413
+ * entirely and every other export vanishes from the compiler's view.
414
+ */
415
+ interface EventMap {
394
416
  "message:sent": {
395
417
  message: Message;
396
418
  };
@@ -398,18 +420,19 @@ type EventMap = {
398
420
  message: Message;
399
421
  };
400
422
  /**
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**.
423
+ * An in-flight turn was cancelled: either a newer `userSay` superseded it,
424
+ * or `interrupt()` cut it off. Emitted exactly once for every cancelled
425
+ * turn, on the cascade path only — the realtime path keeps its own contract
426
+ * and never emits this. The payload carries no cause discriminator, and the
427
+ * superseded or interrupted `userSay` call still **resolves**.
406
428
  *
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.
429
+ * What the event reports is the cancellation. Retention is the separate
430
+ * guarantee: with an LLM manager and a character attached, the cancelled
431
+ * turn's valid user message is already in history when this fires — for a
432
+ * supersession, ahead of the superseding turn's own message; with none
433
+ * attached it holds its queue position and is written by the next `userSay`.
434
+ * Input the manager refuses to store is announced here too but never stored,
435
+ * exactly as today.
413
436
  *
414
437
  * The `message:sent` carrying the same id always precedes this event.
415
438
  */
@@ -521,7 +544,7 @@ type EventMap = {
521
544
  "llm:error": {
522
545
  error: Error;
523
546
  };
524
- };
547
+ }
525
548
  interface CharivoEventEmitter {
526
549
  emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
527
550
  }
@@ -671,6 +694,36 @@ interface ToolResultSnapshot {
671
694
  */
672
695
  declare function snapshotToolResult(result: Record<string, unknown>, toolName: string, toolLabel?: string): ToolResultSnapshot;
673
696
 
697
+ declare const DEFAULT_FETCH_TIMEOUT_MS = 30000;
698
+ interface FetchWithTimeoutOptions {
699
+ /** CharivoTimeoutError message when the internal timeout fires. */
700
+ timeoutMessage: string;
701
+ /** Fixed message for the default CharivoTransportError wrap of non-abort failures. */
702
+ failureMessage?: string;
703
+ timeoutMs?: number;
704
+ /** External cancellation. An abort observed from this signal (its exact reason, or an AbortError) is re-thrown as-is; a coincidental non-abort rejection racing it is still classified normally. */
705
+ signal?: AbortSignal;
706
+ /** Overrides the default transport wrap (server providers map to provider errors instead). */
707
+ mapError?: (error: unknown) => Error;
708
+ }
709
+ /**
710
+ * `init.signal` is typed `never` so callers cannot pass a signal directly —
711
+ * `options.signal` is the single cancellation channel, composed internally
712
+ * with the timeout's own controller.
713
+ *
714
+ * `consumeBody`, when given, is called with the resolved Response while
715
+ * cancellation is still wired up, so an external abort (or timeout) that
716
+ * lands during body consumption (e.g. `response.json()`) still aborts the
717
+ * underlying request instead of only being able to cancel up to the point
718
+ * headers arrive. Its rejection is classified the same way a `fetch()`
719
+ * rejection is for abort/timeout; any other rejection (e.g. an error the
720
+ * callback throws deliberately) passes through unchanged, matching how a
721
+ * caller used to handle the body itself outside this helper.
722
+ */
723
+ declare function fetchWithTimeout<T = Response>(input: RequestInfo | URL, init: Omit<RequestInit, "signal"> & {
724
+ signal?: never;
725
+ }, options: FetchWithTimeoutOptions, consumeBody?: (response: Response) => Promise<T>): Promise<T>;
726
+
674
727
  declare class Charivo {
675
728
  private eventBus;
676
729
  private llmManager?;
@@ -748,7 +801,7 @@ declare class Charivo {
748
801
  * matters because turn:cancelled names its turn by user message id.
749
802
  */
750
803
  private nextMessageId;
751
- /** A turn is live only while it is the newest one. */
804
+ /** A turn is live only while it still owns the current epoch. */
752
805
  private isStale;
753
806
  private removeQueueEntry;
754
807
  /**
@@ -772,9 +825,32 @@ declare class Charivo {
772
825
  * Latest-wins: a newer call supersedes the in-flight turn, which then
773
826
  * resolves without performing any further turn-scoped effect or emitting
774
827
  * any further turn-scoped event. Its user message is retained regardless of
775
- * the phase the supersession lands in.
828
+ * the phase the supersession lands in. Supersession also aborts the turn's
829
+ * LLM request through the turn's own `AbortSignal`, so a client that honors
830
+ * it stops waiting on the provider; one that ignores it settles late and
831
+ * the turn merely goes quiet once it resumes. {@link Charivo.interrupt}
832
+ * cancels an in-flight turn the same way, without a successor taking over.
776
833
  */
777
834
  userSay(content: string): Promise<void>;
835
+ /**
836
+ * Cut off the in-progress turn and its speech now.
837
+ *
838
+ * The cascade counterpart of `RealtimeManager.interrupt()`: the live turn's
839
+ * LLM request is aborted, the turn performs and emits nothing further, and
840
+ * the TTS manager it is speaking on is stopped — the exact manager it handed
841
+ * the reply to, which a mid-turn `attachTTS()` may since have replaced.
842
+ * Resolving means that stop has completed, so no audio from the interrupted
843
+ * turn starts afterwards. The interrupted `userSay()` **resolves**, and the
844
+ * turn is announced as `turn:cancelled`, exactly as a supersession is.
845
+ *
846
+ * Unlike the realtime version, which requires an active, connected session,
847
+ * this has no precondition: with no turn in flight it still stops the
848
+ * attached TTS manager, resolves, and emits nothing.
849
+ *
850
+ * Realtime mode is not covered — this does not delegate to the realtime
851
+ * manager. Use `getRealtimeManager()?.interrupt()` there.
852
+ */
853
+ interrupt(): Promise<void>;
778
854
  /**
779
855
  * Clear the conversation history from the LLM manager.
780
856
  */
@@ -795,6 +871,14 @@ declare class Charivo {
795
871
  * Get the current render manager instance.
796
872
  */
797
873
  getRenderManager(): RenderManager | undefined;
874
+ /**
875
+ * Get the current TTS manager instance.
876
+ */
877
+ getTTSManager(): TTSManager | undefined;
878
+ /**
879
+ * Get the current LLM manager instance.
880
+ */
881
+ getLLMManager(): LLMManager | undefined;
798
882
  /**
799
883
  * Attach a Realtime manager to handle real-time conversation.
800
884
  * Automatically connects the event emitter and enables Realtime mode.
@@ -831,5 +915,34 @@ declare class Charivo {
831
915
  dispose(): Promise<void>;
832
916
  private finishDispose;
833
917
  }
918
+ /**
919
+ * Managers and character to wire into a new {@link Charivo}.
920
+ *
921
+ * Every field is optional — an instance with no managers is valid, and each
922
+ * modality is attached only when supplied. `null` is accepted alongside
923
+ * `undefined` so callers can pass a manager they hold as nullable state (a
924
+ * React ref, a feature-flagged modality) without converting it first.
925
+ */
926
+ interface CharivoOptions {
927
+ llm?: LLMManager | null;
928
+ tts?: TTSManager | null;
929
+ stt?: STTManager | null;
930
+ realtime?: RealtimeManager | null;
931
+ renderer?: RenderManager | null;
932
+ character?: Character | null;
933
+ }
934
+ /**
935
+ * Create a Charivo instance with its managers already attached.
936
+ *
937
+ * Equivalent to `new Charivo()` followed by the matching `attach*` calls, then
938
+ * `setCharacter()`. The character is applied last so it reaches every
939
+ * character-aware manager supplied above it — the LLM, renderer, and realtime
940
+ * managers. Hand-wiring works in either order only because `attach*` re-applies
941
+ * an already-set character, and that coupling is easy to miss.
942
+ *
943
+ * Note that supplying `realtime` also enables realtime mode, exactly as
944
+ * `attachRealtime()` does.
945
+ */
946
+ declare function createCharivo(options?: CharivoOptions): Charivo;
834
947
 
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 };
948
+ export { type AvatarControlCatalog, type BrowserLifecycleCallbacks, type Character, Charivo, CharivoDisposeError, CharivoError, type CharivoErrorCode, type CharivoErrorKind, type CharivoErrorOptions, type CharivoEventBus, type CharivoEventEmitter, type CharivoOptions, CharivoProviderError, CharivoStateError, CharivoTimeoutError, CharivoTransportError, DEFAULT_FETCH_TIMEOUT_MS, type EventMap, type FetchWithTimeoutOptions, type GazeCoordinates, type GenerateResponseOptions, type HistoryRollback, type LLMAdapter, type LLMCallOptions, 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 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, createCharivo, createLipSyncAnalyzer, createToolFailureOutput, createToolRegistry, fetchWithTimeout, getErrorMessage, isCharivoError, snapshotToolResult, subscribeBrowserLifecycle, toCharivoError, validateToolArguments, withToolTimeout };
package/dist/index.d.ts CHANGED
@@ -37,25 +37,6 @@ interface Message {
37
37
  characterId?: string;
38
38
  type: "user" | "character" | "system";
39
39
  }
40
- interface Conversation {
41
- id: string;
42
- messages: Message[];
43
- characterId?: string;
44
- createdAt: Date;
45
- updatedAt: Date;
46
- }
47
- interface Plugin {
48
- id: string;
49
- name: string;
50
- version: string;
51
- enabled: boolean;
52
- }
53
- interface CharivoConfig {
54
- characters: Character[];
55
- plugins: Plugin[];
56
- llmProvider?: string;
57
- renderProvider?: string;
58
- }
59
40
  type RealtimeTransportKind = "webrtc" | "websocket";
60
41
  type RealtimeToolChoice = "auto" | "none" | "required";
61
42
  declare const OPENAI_REALTIME_ADAPTER = "openai-webrtc";
@@ -199,13 +180,20 @@ interface LLMProvider {
199
180
  /** Tool-calling variant; providers that support function calling implement this alongside generateResponse. */
200
181
  generateResponseWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
201
182
  }
183
+ /**
184
+ * Transport-level cancellation for a single `LLMClient` call. Implementations
185
+ * that do not support cancellation may ignore the field.
186
+ */
187
+ interface LLMCallOptions {
188
+ signal?: AbortSignal;
189
+ }
202
190
  interface LLMClient {
203
191
  call(messages: Array<{
204
192
  role: string;
205
193
  content: string;
206
- }>): Promise<string>;
194
+ }>, options?: LLMCallOptions): Promise<string>;
207
195
  /** Tool-calling variant; clients that support function calling implement this alongside call. */
208
- callWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
196
+ callWithTools?(messages: LLMMessage[], tools: ToolDefinition[], options?: LLMCallOptions): Promise<LLMToolResponse>;
209
197
  }
210
198
  /**
211
199
  * Undoes a single `addToHistory` call. Idempotent: invoking it more than once
@@ -231,14 +219,28 @@ interface GenerateResponseOptions {
231
219
  * projector. Once it returns `true` the call starts nothing further and
232
220
  * projects nothing further, then resolves with the latest response text.
233
221
  *
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.
222
+ * It does not govern history writes, and it does not abort an already-
223
+ * running handler, so tool side effects are not rolled back. Cancelling an
224
+ * in-flight request is `signal`'s job, not this predicate's - see `signal`
225
+ * below. Note the resulting event split: `tool:call` records an attempted,
226
+ * dispatched call and can be the last event for a call whose handler was
227
+ * skipped, while `tool:result` and `tool:error` report a handler that
228
+ * actually ran.
240
229
  */
241
230
  isCancelled?: () => boolean;
231
+ /**
232
+ * Cancellation for the in-flight LLM call, forwarded to the client as
233
+ * `LLMCallOptions.signal` on every `call`/`callWithTools` request this turn
234
+ * makes, tool rounds included. Distinct from `isCancelled`: `isCancelled`
235
+ * gates new work between steps and never aborts an in-flight request;
236
+ * `signal` is what aborts the request itself. Whether an abort actually
237
+ * cancels the transport depends on the client - clients that ignore
238
+ * `LLMCallOptions.signal` (allowed by the contract) run to completion
239
+ * regardless. A mid-request abort surfaces as a rejection, which a
240
+ * latest-wins caller swallows via its own stale-turn check rather than this
241
+ * manager doing anything special with it.
242
+ */
243
+ signal?: AbortSignal;
242
244
  }
243
245
  interface LLMManager {
244
246
  setCharacter(character: Character): void;
@@ -390,7 +392,27 @@ interface RealtimeManager {
390
392
  getRegisteredTools(): ToolDefinition[];
391
393
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
392
394
  }
393
- type EventMap = {
395
+ /**
396
+ * An interface (not a type alias) so third-party packages can extend it via
397
+ * declaration merging — a custom renderer or manager declares its own events
398
+ * without a core change:
399
+ *
400
+ * ```ts
401
+ * import "@charivo/core";
402
+ *
403
+ * declare module "@charivo/core" {
404
+ * interface EventMap {
405
+ * "vrm:blendshape": { name: string; weight: number };
406
+ * }
407
+ * }
408
+ * ```
409
+ *
410
+ * The `import` line matters: it makes the declaring file a module, so
411
+ * `declare module` *augments* the package. In a plain script or `.d.ts` with
412
+ * no top-level import/export, the same block *shadows* `@charivo/core`
413
+ * entirely and every other export vanishes from the compiler's view.
414
+ */
415
+ interface EventMap {
394
416
  "message:sent": {
395
417
  message: Message;
396
418
  };
@@ -398,18 +420,19 @@ type EventMap = {
398
420
  message: Message;
399
421
  };
400
422
  /**
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**.
423
+ * An in-flight turn was cancelled: either a newer `userSay` superseded it,
424
+ * or `interrupt()` cut it off. Emitted exactly once for every cancelled
425
+ * turn, on the cascade path only — the realtime path keeps its own contract
426
+ * and never emits this. The payload carries no cause discriminator, and the
427
+ * superseded or interrupted `userSay` call still **resolves**.
406
428
  *
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.
429
+ * What the event reports is the cancellation. Retention is the separate
430
+ * guarantee: with an LLM manager and a character attached, the cancelled
431
+ * turn's valid user message is already in history when this fires — for a
432
+ * supersession, ahead of the superseding turn's own message; with none
433
+ * attached it holds its queue position and is written by the next `userSay`.
434
+ * Input the manager refuses to store is announced here too but never stored,
435
+ * exactly as today.
413
436
  *
414
437
  * The `message:sent` carrying the same id always precedes this event.
415
438
  */
@@ -521,7 +544,7 @@ type EventMap = {
521
544
  "llm:error": {
522
545
  error: Error;
523
546
  };
524
- };
547
+ }
525
548
  interface CharivoEventEmitter {
526
549
  emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
527
550
  }
@@ -671,6 +694,36 @@ interface ToolResultSnapshot {
671
694
  */
672
695
  declare function snapshotToolResult(result: Record<string, unknown>, toolName: string, toolLabel?: string): ToolResultSnapshot;
673
696
 
697
+ declare const DEFAULT_FETCH_TIMEOUT_MS = 30000;
698
+ interface FetchWithTimeoutOptions {
699
+ /** CharivoTimeoutError message when the internal timeout fires. */
700
+ timeoutMessage: string;
701
+ /** Fixed message for the default CharivoTransportError wrap of non-abort failures. */
702
+ failureMessage?: string;
703
+ timeoutMs?: number;
704
+ /** External cancellation. An abort observed from this signal (its exact reason, or an AbortError) is re-thrown as-is; a coincidental non-abort rejection racing it is still classified normally. */
705
+ signal?: AbortSignal;
706
+ /** Overrides the default transport wrap (server providers map to provider errors instead). */
707
+ mapError?: (error: unknown) => Error;
708
+ }
709
+ /**
710
+ * `init.signal` is typed `never` so callers cannot pass a signal directly —
711
+ * `options.signal` is the single cancellation channel, composed internally
712
+ * with the timeout's own controller.
713
+ *
714
+ * `consumeBody`, when given, is called with the resolved Response while
715
+ * cancellation is still wired up, so an external abort (or timeout) that
716
+ * lands during body consumption (e.g. `response.json()`) still aborts the
717
+ * underlying request instead of only being able to cancel up to the point
718
+ * headers arrive. Its rejection is classified the same way a `fetch()`
719
+ * rejection is for abort/timeout; any other rejection (e.g. an error the
720
+ * callback throws deliberately) passes through unchanged, matching how a
721
+ * caller used to handle the body itself outside this helper.
722
+ */
723
+ declare function fetchWithTimeout<T = Response>(input: RequestInfo | URL, init: Omit<RequestInit, "signal"> & {
724
+ signal?: never;
725
+ }, options: FetchWithTimeoutOptions, consumeBody?: (response: Response) => Promise<T>): Promise<T>;
726
+
674
727
  declare class Charivo {
675
728
  private eventBus;
676
729
  private llmManager?;
@@ -748,7 +801,7 @@ declare class Charivo {
748
801
  * matters because turn:cancelled names its turn by user message id.
749
802
  */
750
803
  private nextMessageId;
751
- /** A turn is live only while it is the newest one. */
804
+ /** A turn is live only while it still owns the current epoch. */
752
805
  private isStale;
753
806
  private removeQueueEntry;
754
807
  /**
@@ -772,9 +825,32 @@ declare class Charivo {
772
825
  * Latest-wins: a newer call supersedes the in-flight turn, which then
773
826
  * resolves without performing any further turn-scoped effect or emitting
774
827
  * any further turn-scoped event. Its user message is retained regardless of
775
- * the phase the supersession lands in.
828
+ * the phase the supersession lands in. Supersession also aborts the turn's
829
+ * LLM request through the turn's own `AbortSignal`, so a client that honors
830
+ * it stops waiting on the provider; one that ignores it settles late and
831
+ * the turn merely goes quiet once it resumes. {@link Charivo.interrupt}
832
+ * cancels an in-flight turn the same way, without a successor taking over.
776
833
  */
777
834
  userSay(content: string): Promise<void>;
835
+ /**
836
+ * Cut off the in-progress turn and its speech now.
837
+ *
838
+ * The cascade counterpart of `RealtimeManager.interrupt()`: the live turn's
839
+ * LLM request is aborted, the turn performs and emits nothing further, and
840
+ * the TTS manager it is speaking on is stopped — the exact manager it handed
841
+ * the reply to, which a mid-turn `attachTTS()` may since have replaced.
842
+ * Resolving means that stop has completed, so no audio from the interrupted
843
+ * turn starts afterwards. The interrupted `userSay()` **resolves**, and the
844
+ * turn is announced as `turn:cancelled`, exactly as a supersession is.
845
+ *
846
+ * Unlike the realtime version, which requires an active, connected session,
847
+ * this has no precondition: with no turn in flight it still stops the
848
+ * attached TTS manager, resolves, and emits nothing.
849
+ *
850
+ * Realtime mode is not covered — this does not delegate to the realtime
851
+ * manager. Use `getRealtimeManager()?.interrupt()` there.
852
+ */
853
+ interrupt(): Promise<void>;
778
854
  /**
779
855
  * Clear the conversation history from the LLM manager.
780
856
  */
@@ -795,6 +871,14 @@ declare class Charivo {
795
871
  * Get the current render manager instance.
796
872
  */
797
873
  getRenderManager(): RenderManager | undefined;
874
+ /**
875
+ * Get the current TTS manager instance.
876
+ */
877
+ getTTSManager(): TTSManager | undefined;
878
+ /**
879
+ * Get the current LLM manager instance.
880
+ */
881
+ getLLMManager(): LLMManager | undefined;
798
882
  /**
799
883
  * Attach a Realtime manager to handle real-time conversation.
800
884
  * Automatically connects the event emitter and enables Realtime mode.
@@ -831,5 +915,34 @@ declare class Charivo {
831
915
  dispose(): Promise<void>;
832
916
  private finishDispose;
833
917
  }
918
+ /**
919
+ * Managers and character to wire into a new {@link Charivo}.
920
+ *
921
+ * Every field is optional — an instance with no managers is valid, and each
922
+ * modality is attached only when supplied. `null` is accepted alongside
923
+ * `undefined` so callers can pass a manager they hold as nullable state (a
924
+ * React ref, a feature-flagged modality) without converting it first.
925
+ */
926
+ interface CharivoOptions {
927
+ llm?: LLMManager | null;
928
+ tts?: TTSManager | null;
929
+ stt?: STTManager | null;
930
+ realtime?: RealtimeManager | null;
931
+ renderer?: RenderManager | null;
932
+ character?: Character | null;
933
+ }
934
+ /**
935
+ * Create a Charivo instance with its managers already attached.
936
+ *
937
+ * Equivalent to `new Charivo()` followed by the matching `attach*` calls, then
938
+ * `setCharacter()`. The character is applied last so it reaches every
939
+ * character-aware manager supplied above it — the LLM, renderer, and realtime
940
+ * managers. Hand-wiring works in either order only because `attach*` re-applies
941
+ * an already-set character, and that coupling is easy to miss.
942
+ *
943
+ * Note that supplying `realtime` also enables realtime mode, exactly as
944
+ * `attachRealtime()` does.
945
+ */
946
+ declare function createCharivo(options?: CharivoOptions): Charivo;
834
947
 
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 };
948
+ export { type AvatarControlCatalog, type BrowserLifecycleCallbacks, type Character, Charivo, CharivoDisposeError, CharivoError, type CharivoErrorCode, type CharivoErrorKind, type CharivoErrorOptions, type CharivoEventBus, type CharivoEventEmitter, type CharivoOptions, CharivoProviderError, CharivoStateError, CharivoTimeoutError, CharivoTransportError, DEFAULT_FETCH_TIMEOUT_MS, type EventMap, type FetchWithTimeoutOptions, type GazeCoordinates, type GenerateResponseOptions, type HistoryRollback, type LLMAdapter, type LLMCallOptions, 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 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, createCharivo, createLipSyncAnalyzer, createToolFailureOutput, createToolRegistry, fetchWithTimeout, getErrorMessage, isCharivoError, snapshotToolResult, subscribeBrowserLifecycle, toCharivoError, validateToolArguments, withToolTimeout };