@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/dist/index.d.cts CHANGED
@@ -84,7 +84,6 @@ interface RealtimeSessionConfig {
84
84
  voice?: string;
85
85
  model?: string;
86
86
  instructions?: string;
87
- temperature?: number;
88
87
  maxTokens?: number;
89
88
  tools?: ToolDefinition[];
90
89
  toolChoice?: RealtimeToolChoice;
@@ -180,13 +179,20 @@ interface LLMProvider {
180
179
  /** Tool-calling variant; providers that support function calling implement this alongside generateResponse. */
181
180
  generateResponseWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
182
181
  }
182
+ /**
183
+ * Transport-level cancellation for a single `LLMClient` call. Implementations
184
+ * that do not support cancellation may ignore the field.
185
+ */
186
+ interface LLMCallOptions {
187
+ signal?: AbortSignal;
188
+ }
183
189
  interface LLMClient {
184
190
  call(messages: Array<{
185
191
  role: string;
186
192
  content: string;
187
- }>): Promise<string>;
193
+ }>, options?: LLMCallOptions): Promise<string>;
188
194
  /** Tool-calling variant; clients that support function calling implement this alongside call. */
189
- callWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
195
+ callWithTools?(messages: LLMMessage[], tools: ToolDefinition[], options?: LLMCallOptions): Promise<LLMToolResponse>;
190
196
  }
191
197
  /**
192
198
  * Undoes a single `addToHistory` call. Idempotent: invoking it more than once
@@ -212,14 +218,28 @@ interface GenerateResponseOptions {
212
218
  * projector. Once it returns `true` the call starts nothing further and
213
219
  * projects nothing further, then resolves with the latest response text.
214
220
  *
215
- * It does not govern history writes, and it aborts neither an in-flight
216
- * request nor an already-running handler, so tool side effects are not
217
- * rolled back. Note the resulting event split: `tool:call` records an
218
- * attempted, dispatched call and can be the last event for a call whose
219
- * handler was skipped, while `tool:result` and `tool:error` report a
220
- * handler that actually ran.
221
+ * It does not govern history writes, and it does not abort an already-
222
+ * running handler, so tool side effects are not rolled back. Cancelling an
223
+ * in-flight request is `signal`'s job, not this predicate's - see `signal`
224
+ * below. Note the resulting event split: `tool:call` records an attempted,
225
+ * dispatched call and can be the last event for a call whose handler was
226
+ * skipped, while `tool:result` and `tool:error` report a handler that
227
+ * actually ran.
221
228
  */
222
229
  isCancelled?: () => boolean;
230
+ /**
231
+ * Cancellation for the in-flight LLM call, forwarded to the client as
232
+ * `LLMCallOptions.signal` on every `call`/`callWithTools` request this turn
233
+ * makes, tool rounds included. Distinct from `isCancelled`: `isCancelled`
234
+ * gates new work between steps and never aborts an in-flight request;
235
+ * `signal` is what aborts the request itself. Whether an abort actually
236
+ * cancels the transport depends on the client - clients that ignore
237
+ * `LLMCallOptions.signal` (allowed by the contract) run to completion
238
+ * regardless. A mid-request abort surfaces as a rejection, which a
239
+ * latest-wins caller swallows via its own stale-turn check rather than this
240
+ * manager doing anything special with it.
241
+ */
242
+ signal?: AbortSignal;
223
243
  }
224
244
  interface LLMManager {
225
245
  setCharacter(character: Character): void;
@@ -371,7 +391,27 @@ interface RealtimeManager {
371
391
  getRegisteredTools(): ToolDefinition[];
372
392
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
373
393
  }
374
- type EventMap = {
394
+ /**
395
+ * An interface (not a type alias) so third-party packages can extend it via
396
+ * declaration merging — a custom renderer or manager declares its own events
397
+ * without a core change:
398
+ *
399
+ * ```ts
400
+ * import "@charivo/core";
401
+ *
402
+ * declare module "@charivo/core" {
403
+ * interface EventMap {
404
+ * "vrm:blendshape": { name: string; weight: number };
405
+ * }
406
+ * }
407
+ * ```
408
+ *
409
+ * The `import` line matters: it makes the declaring file a module, so
410
+ * `declare module` *augments* the package. In a plain script or `.d.ts` with
411
+ * no top-level import/export, the same block *shadows* `@charivo/core`
412
+ * entirely and every other export vanishes from the compiler's view.
413
+ */
414
+ interface EventMap {
375
415
  "message:sent": {
376
416
  message: Message;
377
417
  };
@@ -379,18 +419,19 @@ type EventMap = {
379
419
  message: Message;
380
420
  };
381
421
  /**
382
- * An in-flight turn was superseded by a newer `userSay`. Emitted exactly
383
- * once for every superseded turn, on the cascade path only — the realtime
384
- * path keeps its own contract and never emits this. Supersession is the
385
- * only cause, so the payload needs no cause discriminator, and the
386
- * superseded `userSay` call still **resolves**.
422
+ * An in-flight turn was cancelled: either a newer `userSay` superseded it,
423
+ * or `interrupt()` cut it off. Emitted exactly once for every cancelled
424
+ * turn, on the cascade path only — the realtime path keeps its own contract
425
+ * and never emits this. The payload carries no cause discriminator, and the
426
+ * superseded or interrupted `userSay` call still **resolves**.
387
427
  *
388
- * What the event reports is supersession. Retention is the separate
389
- * guarantee: with an LLM manager and a character attached, the superseded
390
- * turn's valid user message is already in history when this fires, ahead of
391
- * the superseding turn's own message; with none attached it holds its queue
392
- * position and is written by the next `userSay`. Input the manager refuses
393
- * to store is announced here too but never stored, exactly as today.
428
+ * What the event reports is the cancellation. Retention is the separate
429
+ * guarantee: with an LLM manager and a character attached, the cancelled
430
+ * turn's valid user message is already in history when this fires — for a
431
+ * supersession, ahead of the superseding turn's own message; with none
432
+ * attached it holds its queue position and is written by the next `userSay`.
433
+ * Input the manager refuses to store is announced here too but never stored,
434
+ * exactly as today.
394
435
  *
395
436
  * The `message:sent` carrying the same id always precedes this event.
396
437
  */
@@ -502,7 +543,7 @@ type EventMap = {
502
543
  "llm:error": {
503
544
  error: Error;
504
545
  };
505
- };
546
+ }
506
547
  interface CharivoEventEmitter {
507
548
  emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
508
549
  }
@@ -652,6 +693,36 @@ interface ToolResultSnapshot {
652
693
  */
653
694
  declare function snapshotToolResult(result: Record<string, unknown>, toolName: string, toolLabel?: string): ToolResultSnapshot;
654
695
 
696
+ declare const DEFAULT_FETCH_TIMEOUT_MS = 30000;
697
+ interface FetchWithTimeoutOptions {
698
+ /** CharivoTimeoutError message when the internal timeout fires. */
699
+ timeoutMessage: string;
700
+ /** Fixed message for the default CharivoTransportError wrap of non-abort failures. */
701
+ failureMessage?: string;
702
+ timeoutMs?: number;
703
+ /** 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. */
704
+ signal?: AbortSignal;
705
+ /** Overrides the default transport wrap (server providers map to provider errors instead). */
706
+ mapError?: (error: unknown) => Error;
707
+ }
708
+ /**
709
+ * `init.signal` is typed `never` so callers cannot pass a signal directly —
710
+ * `options.signal` is the single cancellation channel, composed internally
711
+ * with the timeout's own controller.
712
+ *
713
+ * `consumeBody`, when given, is called with the resolved Response while
714
+ * cancellation is still wired up, so an external abort (or timeout) that
715
+ * lands during body consumption (e.g. `response.json()`) still aborts the
716
+ * underlying request instead of only being able to cancel up to the point
717
+ * headers arrive. Its rejection is classified the same way a `fetch()`
718
+ * rejection is for abort/timeout; any other rejection (e.g. an error the
719
+ * callback throws deliberately) passes through unchanged, matching how a
720
+ * caller used to handle the body itself outside this helper.
721
+ */
722
+ declare function fetchWithTimeout<T = Response>(input: RequestInfo | URL, init: Omit<RequestInit, "signal"> & {
723
+ signal?: never;
724
+ }, options: FetchWithTimeoutOptions, consumeBody?: (response: Response) => Promise<T>): Promise<T>;
725
+
655
726
  declare class Charivo {
656
727
  private eventBus;
657
728
  private llmManager?;
@@ -729,7 +800,7 @@ declare class Charivo {
729
800
  * matters because turn:cancelled names its turn by user message id.
730
801
  */
731
802
  private nextMessageId;
732
- /** A turn is live only while it is the newest one. */
803
+ /** A turn is live only while it still owns the current epoch. */
733
804
  private isStale;
734
805
  private removeQueueEntry;
735
806
  /**
@@ -753,9 +824,32 @@ declare class Charivo {
753
824
  * Latest-wins: a newer call supersedes the in-flight turn, which then
754
825
  * resolves without performing any further turn-scoped effect or emitting
755
826
  * any further turn-scoped event. Its user message is retained regardless of
756
- * the phase the supersession lands in.
827
+ * the phase the supersession lands in. Supersession also aborts the turn's
828
+ * LLM request through the turn's own `AbortSignal`, so a client that honors
829
+ * it stops waiting on the provider; one that ignores it settles late and
830
+ * the turn merely goes quiet once it resumes. {@link Charivo.interrupt}
831
+ * cancels an in-flight turn the same way, without a successor taking over.
757
832
  */
758
833
  userSay(content: string): Promise<void>;
834
+ /**
835
+ * Cut off the in-progress turn and its speech now.
836
+ *
837
+ * The cascade counterpart of `RealtimeManager.interrupt()`: the live turn's
838
+ * LLM request is aborted, the turn performs and emits nothing further, and
839
+ * the TTS manager it is speaking on is stopped — the exact manager it handed
840
+ * the reply to, which a mid-turn `attachTTS()` may since have replaced.
841
+ * Resolving means that stop has completed, so no audio from the interrupted
842
+ * turn starts afterwards. The interrupted `userSay()` **resolves**, and the
843
+ * turn is announced as `turn:cancelled`, exactly as a supersession is.
844
+ *
845
+ * Unlike the realtime version, which requires an active, connected session,
846
+ * this has no precondition: with no turn in flight it still stops the
847
+ * attached TTS manager, resolves, and emits nothing.
848
+ *
849
+ * Realtime mode is not covered — this does not delegate to the realtime
850
+ * manager. Use `getRealtimeManager()?.interrupt()` there.
851
+ */
852
+ interrupt(): Promise<void>;
759
853
  /**
760
854
  * Clear the conversation history from the LLM manager.
761
855
  */
@@ -850,4 +944,4 @@ interface CharivoOptions {
850
944
  */
851
945
  declare function createCharivo(options?: CharivoOptions): Charivo;
852
946
 
853
- 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, 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 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, getErrorMessage, isCharivoError, snapshotToolResult, subscribeBrowserLifecycle, toCharivoError, validateToolArguments, withToolTimeout };
947
+ 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
@@ -84,7 +84,6 @@ interface RealtimeSessionConfig {
84
84
  voice?: string;
85
85
  model?: string;
86
86
  instructions?: string;
87
- temperature?: number;
88
87
  maxTokens?: number;
89
88
  tools?: ToolDefinition[];
90
89
  toolChoice?: RealtimeToolChoice;
@@ -180,13 +179,20 @@ interface LLMProvider {
180
179
  /** Tool-calling variant; providers that support function calling implement this alongside generateResponse. */
181
180
  generateResponseWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
182
181
  }
182
+ /**
183
+ * Transport-level cancellation for a single `LLMClient` call. Implementations
184
+ * that do not support cancellation may ignore the field.
185
+ */
186
+ interface LLMCallOptions {
187
+ signal?: AbortSignal;
188
+ }
183
189
  interface LLMClient {
184
190
  call(messages: Array<{
185
191
  role: string;
186
192
  content: string;
187
- }>): Promise<string>;
193
+ }>, options?: LLMCallOptions): Promise<string>;
188
194
  /** Tool-calling variant; clients that support function calling implement this alongside call. */
189
- callWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
195
+ callWithTools?(messages: LLMMessage[], tools: ToolDefinition[], options?: LLMCallOptions): Promise<LLMToolResponse>;
190
196
  }
191
197
  /**
192
198
  * Undoes a single `addToHistory` call. Idempotent: invoking it more than once
@@ -212,14 +218,28 @@ interface GenerateResponseOptions {
212
218
  * projector. Once it returns `true` the call starts nothing further and
213
219
  * projects nothing further, then resolves with the latest response text.
214
220
  *
215
- * It does not govern history writes, and it aborts neither an in-flight
216
- * request nor an already-running handler, so tool side effects are not
217
- * rolled back. Note the resulting event split: `tool:call` records an
218
- * attempted, dispatched call and can be the last event for a call whose
219
- * handler was skipped, while `tool:result` and `tool:error` report a
220
- * handler that actually ran.
221
+ * It does not govern history writes, and it does not abort an already-
222
+ * running handler, so tool side effects are not rolled back. Cancelling an
223
+ * in-flight request is `signal`'s job, not this predicate's - see `signal`
224
+ * below. Note the resulting event split: `tool:call` records an attempted,
225
+ * dispatched call and can be the last event for a call whose handler was
226
+ * skipped, while `tool:result` and `tool:error` report a handler that
227
+ * actually ran.
221
228
  */
222
229
  isCancelled?: () => boolean;
230
+ /**
231
+ * Cancellation for the in-flight LLM call, forwarded to the client as
232
+ * `LLMCallOptions.signal` on every `call`/`callWithTools` request this turn
233
+ * makes, tool rounds included. Distinct from `isCancelled`: `isCancelled`
234
+ * gates new work between steps and never aborts an in-flight request;
235
+ * `signal` is what aborts the request itself. Whether an abort actually
236
+ * cancels the transport depends on the client - clients that ignore
237
+ * `LLMCallOptions.signal` (allowed by the contract) run to completion
238
+ * regardless. A mid-request abort surfaces as a rejection, which a
239
+ * latest-wins caller swallows via its own stale-turn check rather than this
240
+ * manager doing anything special with it.
241
+ */
242
+ signal?: AbortSignal;
223
243
  }
224
244
  interface LLMManager {
225
245
  setCharacter(character: Character): void;
@@ -371,7 +391,27 @@ interface RealtimeManager {
371
391
  getRegisteredTools(): ToolDefinition[];
372
392
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
373
393
  }
374
- type EventMap = {
394
+ /**
395
+ * An interface (not a type alias) so third-party packages can extend it via
396
+ * declaration merging — a custom renderer or manager declares its own events
397
+ * without a core change:
398
+ *
399
+ * ```ts
400
+ * import "@charivo/core";
401
+ *
402
+ * declare module "@charivo/core" {
403
+ * interface EventMap {
404
+ * "vrm:blendshape": { name: string; weight: number };
405
+ * }
406
+ * }
407
+ * ```
408
+ *
409
+ * The `import` line matters: it makes the declaring file a module, so
410
+ * `declare module` *augments* the package. In a plain script or `.d.ts` with
411
+ * no top-level import/export, the same block *shadows* `@charivo/core`
412
+ * entirely and every other export vanishes from the compiler's view.
413
+ */
414
+ interface EventMap {
375
415
  "message:sent": {
376
416
  message: Message;
377
417
  };
@@ -379,18 +419,19 @@ type EventMap = {
379
419
  message: Message;
380
420
  };
381
421
  /**
382
- * An in-flight turn was superseded by a newer `userSay`. Emitted exactly
383
- * once for every superseded turn, on the cascade path only — the realtime
384
- * path keeps its own contract and never emits this. Supersession is the
385
- * only cause, so the payload needs no cause discriminator, and the
386
- * superseded `userSay` call still **resolves**.
422
+ * An in-flight turn was cancelled: either a newer `userSay` superseded it,
423
+ * or `interrupt()` cut it off. Emitted exactly once for every cancelled
424
+ * turn, on the cascade path only — the realtime path keeps its own contract
425
+ * and never emits this. The payload carries no cause discriminator, and the
426
+ * superseded or interrupted `userSay` call still **resolves**.
387
427
  *
388
- * What the event reports is supersession. Retention is the separate
389
- * guarantee: with an LLM manager and a character attached, the superseded
390
- * turn's valid user message is already in history when this fires, ahead of
391
- * the superseding turn's own message; with none attached it holds its queue
392
- * position and is written by the next `userSay`. Input the manager refuses
393
- * to store is announced here too but never stored, exactly as today.
428
+ * What the event reports is the cancellation. Retention is the separate
429
+ * guarantee: with an LLM manager and a character attached, the cancelled
430
+ * turn's valid user message is already in history when this fires — for a
431
+ * supersession, ahead of the superseding turn's own message; with none
432
+ * attached it holds its queue position and is written by the next `userSay`.
433
+ * Input the manager refuses to store is announced here too but never stored,
434
+ * exactly as today.
394
435
  *
395
436
  * The `message:sent` carrying the same id always precedes this event.
396
437
  */
@@ -502,7 +543,7 @@ type EventMap = {
502
543
  "llm:error": {
503
544
  error: Error;
504
545
  };
505
- };
546
+ }
506
547
  interface CharivoEventEmitter {
507
548
  emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
508
549
  }
@@ -652,6 +693,36 @@ interface ToolResultSnapshot {
652
693
  */
653
694
  declare function snapshotToolResult(result: Record<string, unknown>, toolName: string, toolLabel?: string): ToolResultSnapshot;
654
695
 
696
+ declare const DEFAULT_FETCH_TIMEOUT_MS = 30000;
697
+ interface FetchWithTimeoutOptions {
698
+ /** CharivoTimeoutError message when the internal timeout fires. */
699
+ timeoutMessage: string;
700
+ /** Fixed message for the default CharivoTransportError wrap of non-abort failures. */
701
+ failureMessage?: string;
702
+ timeoutMs?: number;
703
+ /** 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. */
704
+ signal?: AbortSignal;
705
+ /** Overrides the default transport wrap (server providers map to provider errors instead). */
706
+ mapError?: (error: unknown) => Error;
707
+ }
708
+ /**
709
+ * `init.signal` is typed `never` so callers cannot pass a signal directly —
710
+ * `options.signal` is the single cancellation channel, composed internally
711
+ * with the timeout's own controller.
712
+ *
713
+ * `consumeBody`, when given, is called with the resolved Response while
714
+ * cancellation is still wired up, so an external abort (or timeout) that
715
+ * lands during body consumption (e.g. `response.json()`) still aborts the
716
+ * underlying request instead of only being able to cancel up to the point
717
+ * headers arrive. Its rejection is classified the same way a `fetch()`
718
+ * rejection is for abort/timeout; any other rejection (e.g. an error the
719
+ * callback throws deliberately) passes through unchanged, matching how a
720
+ * caller used to handle the body itself outside this helper.
721
+ */
722
+ declare function fetchWithTimeout<T = Response>(input: RequestInfo | URL, init: Omit<RequestInit, "signal"> & {
723
+ signal?: never;
724
+ }, options: FetchWithTimeoutOptions, consumeBody?: (response: Response) => Promise<T>): Promise<T>;
725
+
655
726
  declare class Charivo {
656
727
  private eventBus;
657
728
  private llmManager?;
@@ -729,7 +800,7 @@ declare class Charivo {
729
800
  * matters because turn:cancelled names its turn by user message id.
730
801
  */
731
802
  private nextMessageId;
732
- /** A turn is live only while it is the newest one. */
803
+ /** A turn is live only while it still owns the current epoch. */
733
804
  private isStale;
734
805
  private removeQueueEntry;
735
806
  /**
@@ -753,9 +824,32 @@ declare class Charivo {
753
824
  * Latest-wins: a newer call supersedes the in-flight turn, which then
754
825
  * resolves without performing any further turn-scoped effect or emitting
755
826
  * any further turn-scoped event. Its user message is retained regardless of
756
- * the phase the supersession lands in.
827
+ * the phase the supersession lands in. Supersession also aborts the turn's
828
+ * LLM request through the turn's own `AbortSignal`, so a client that honors
829
+ * it stops waiting on the provider; one that ignores it settles late and
830
+ * the turn merely goes quiet once it resumes. {@link Charivo.interrupt}
831
+ * cancels an in-flight turn the same way, without a successor taking over.
757
832
  */
758
833
  userSay(content: string): Promise<void>;
834
+ /**
835
+ * Cut off the in-progress turn and its speech now.
836
+ *
837
+ * The cascade counterpart of `RealtimeManager.interrupt()`: the live turn's
838
+ * LLM request is aborted, the turn performs and emits nothing further, and
839
+ * the TTS manager it is speaking on is stopped — the exact manager it handed
840
+ * the reply to, which a mid-turn `attachTTS()` may since have replaced.
841
+ * Resolving means that stop has completed, so no audio from the interrupted
842
+ * turn starts afterwards. The interrupted `userSay()` **resolves**, and the
843
+ * turn is announced as `turn:cancelled`, exactly as a supersession is.
844
+ *
845
+ * Unlike the realtime version, which requires an active, connected session,
846
+ * this has no precondition: with no turn in flight it still stops the
847
+ * attached TTS manager, resolves, and emits nothing.
848
+ *
849
+ * Realtime mode is not covered — this does not delegate to the realtime
850
+ * manager. Use `getRealtimeManager()?.interrupt()` there.
851
+ */
852
+ interrupt(): Promise<void>;
759
853
  /**
760
854
  * Clear the conversation history from the LLM manager.
761
855
  */
@@ -850,4 +944,4 @@ interface CharivoOptions {
850
944
  */
851
945
  declare function createCharivo(options?: CharivoOptions): Charivo;
852
946
 
853
- 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, 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 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, getErrorMessage, isCharivoError, snapshotToolResult, subscribeBrowserLifecycle, toCharivoError, validateToolArguments, withToolTimeout };
947
+ 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 };