@charivo/core 0.26.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/README.md +64 -19
- package/dist/index.cjs +143 -8
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +119 -24
- package/dist/index.d.ts +119 -24
- package/dist/index.js +142 -9
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -180,13 +180,20 @@ interface LLMProvider {
|
|
|
180
180
|
/** Tool-calling variant; providers that support function calling implement this alongside generateResponse. */
|
|
181
181
|
generateResponseWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
|
|
182
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
|
+
}
|
|
183
190
|
interface LLMClient {
|
|
184
191
|
call(messages: Array<{
|
|
185
192
|
role: string;
|
|
186
193
|
content: string;
|
|
187
|
-
}
|
|
194
|
+
}>, options?: LLMCallOptions): Promise<string>;
|
|
188
195
|
/** Tool-calling variant; clients that support function calling implement this alongside call. */
|
|
189
|
-
callWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
|
|
196
|
+
callWithTools?(messages: LLMMessage[], tools: ToolDefinition[], options?: LLMCallOptions): Promise<LLMToolResponse>;
|
|
190
197
|
}
|
|
191
198
|
/**
|
|
192
199
|
* Undoes a single `addToHistory` call. Idempotent: invoking it more than once
|
|
@@ -212,14 +219,28 @@ interface GenerateResponseOptions {
|
|
|
212
219
|
* projector. Once it returns `true` the call starts nothing further and
|
|
213
220
|
* projects nothing further, then resolves with the latest response text.
|
|
214
221
|
*
|
|
215
|
-
* It does not govern history writes, and it
|
|
216
|
-
*
|
|
217
|
-
*
|
|
218
|
-
*
|
|
219
|
-
*
|
|
220
|
-
* handler that
|
|
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.
|
|
221
229
|
*/
|
|
222
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;
|
|
223
244
|
}
|
|
224
245
|
interface LLMManager {
|
|
225
246
|
setCharacter(character: Character): void;
|
|
@@ -371,7 +392,27 @@ interface RealtimeManager {
|
|
|
371
392
|
getRegisteredTools(): ToolDefinition[];
|
|
372
393
|
setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
|
|
373
394
|
}
|
|
374
|
-
|
|
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 {
|
|
375
416
|
"message:sent": {
|
|
376
417
|
message: Message;
|
|
377
418
|
};
|
|
@@ -379,18 +420,19 @@ type EventMap = {
|
|
|
379
420
|
message: Message;
|
|
380
421
|
};
|
|
381
422
|
/**
|
|
382
|
-
* An in-flight turn was
|
|
383
|
-
*
|
|
384
|
-
*
|
|
385
|
-
*
|
|
386
|
-
* 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**.
|
|
387
428
|
*
|
|
388
|
-
* What the event reports is
|
|
389
|
-
* guarantee: with an LLM manager and a character attached, the
|
|
390
|
-
* turn's valid user message is already in history when this fires
|
|
391
|
-
* the superseding turn's own message; with none
|
|
392
|
-
* position and is written by the next `userSay`.
|
|
393
|
-
* to store is announced here too but never stored,
|
|
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.
|
|
394
436
|
*
|
|
395
437
|
* The `message:sent` carrying the same id always precedes this event.
|
|
396
438
|
*/
|
|
@@ -502,7 +544,7 @@ type EventMap = {
|
|
|
502
544
|
"llm:error": {
|
|
503
545
|
error: Error;
|
|
504
546
|
};
|
|
505
|
-
}
|
|
547
|
+
}
|
|
506
548
|
interface CharivoEventEmitter {
|
|
507
549
|
emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
|
|
508
550
|
}
|
|
@@ -652,6 +694,36 @@ interface ToolResultSnapshot {
|
|
|
652
694
|
*/
|
|
653
695
|
declare function snapshotToolResult(result: Record<string, unknown>, toolName: string, toolLabel?: string): ToolResultSnapshot;
|
|
654
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
|
+
|
|
655
727
|
declare class Charivo {
|
|
656
728
|
private eventBus;
|
|
657
729
|
private llmManager?;
|
|
@@ -729,7 +801,7 @@ declare class Charivo {
|
|
|
729
801
|
* matters because turn:cancelled names its turn by user message id.
|
|
730
802
|
*/
|
|
731
803
|
private nextMessageId;
|
|
732
|
-
/** A turn is live only while it
|
|
804
|
+
/** A turn is live only while it still owns the current epoch. */
|
|
733
805
|
private isStale;
|
|
734
806
|
private removeQueueEntry;
|
|
735
807
|
/**
|
|
@@ -753,9 +825,32 @@ declare class Charivo {
|
|
|
753
825
|
* Latest-wins: a newer call supersedes the in-flight turn, which then
|
|
754
826
|
* resolves without performing any further turn-scoped effect or emitting
|
|
755
827
|
* any further turn-scoped event. Its user message is retained regardless of
|
|
756
|
-
* 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.
|
|
757
833
|
*/
|
|
758
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>;
|
|
759
854
|
/**
|
|
760
855
|
* Clear the conversation history from the LLM manager.
|
|
761
856
|
*/
|
|
@@ -850,4 +945,4 @@ interface CharivoOptions {
|
|
|
850
945
|
*/
|
|
851
946
|
declare function createCharivo(options?: CharivoOptions): Charivo;
|
|
852
947
|
|
|
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 };
|
|
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
|
@@ -180,13 +180,20 @@ interface LLMProvider {
|
|
|
180
180
|
/** Tool-calling variant; providers that support function calling implement this alongside generateResponse. */
|
|
181
181
|
generateResponseWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
|
|
182
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
|
+
}
|
|
183
190
|
interface LLMClient {
|
|
184
191
|
call(messages: Array<{
|
|
185
192
|
role: string;
|
|
186
193
|
content: string;
|
|
187
|
-
}
|
|
194
|
+
}>, options?: LLMCallOptions): Promise<string>;
|
|
188
195
|
/** Tool-calling variant; clients that support function calling implement this alongside call. */
|
|
189
|
-
callWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
|
|
196
|
+
callWithTools?(messages: LLMMessage[], tools: ToolDefinition[], options?: LLMCallOptions): Promise<LLMToolResponse>;
|
|
190
197
|
}
|
|
191
198
|
/**
|
|
192
199
|
* Undoes a single `addToHistory` call. Idempotent: invoking it more than once
|
|
@@ -212,14 +219,28 @@ interface GenerateResponseOptions {
|
|
|
212
219
|
* projector. Once it returns `true` the call starts nothing further and
|
|
213
220
|
* projects nothing further, then resolves with the latest response text.
|
|
214
221
|
*
|
|
215
|
-
* It does not govern history writes, and it
|
|
216
|
-
*
|
|
217
|
-
*
|
|
218
|
-
*
|
|
219
|
-
*
|
|
220
|
-
* handler that
|
|
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.
|
|
221
229
|
*/
|
|
222
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;
|
|
223
244
|
}
|
|
224
245
|
interface LLMManager {
|
|
225
246
|
setCharacter(character: Character): void;
|
|
@@ -371,7 +392,27 @@ interface RealtimeManager {
|
|
|
371
392
|
getRegisteredTools(): ToolDefinition[];
|
|
372
393
|
setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
|
|
373
394
|
}
|
|
374
|
-
|
|
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 {
|
|
375
416
|
"message:sent": {
|
|
376
417
|
message: Message;
|
|
377
418
|
};
|
|
@@ -379,18 +420,19 @@ type EventMap = {
|
|
|
379
420
|
message: Message;
|
|
380
421
|
};
|
|
381
422
|
/**
|
|
382
|
-
* An in-flight turn was
|
|
383
|
-
*
|
|
384
|
-
*
|
|
385
|
-
*
|
|
386
|
-
* 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**.
|
|
387
428
|
*
|
|
388
|
-
* What the event reports is
|
|
389
|
-
* guarantee: with an LLM manager and a character attached, the
|
|
390
|
-
* turn's valid user message is already in history when this fires
|
|
391
|
-
* the superseding turn's own message; with none
|
|
392
|
-
* position and is written by the next `userSay`.
|
|
393
|
-
* to store is announced here too but never stored,
|
|
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.
|
|
394
436
|
*
|
|
395
437
|
* The `message:sent` carrying the same id always precedes this event.
|
|
396
438
|
*/
|
|
@@ -502,7 +544,7 @@ type EventMap = {
|
|
|
502
544
|
"llm:error": {
|
|
503
545
|
error: Error;
|
|
504
546
|
};
|
|
505
|
-
}
|
|
547
|
+
}
|
|
506
548
|
interface CharivoEventEmitter {
|
|
507
549
|
emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
|
|
508
550
|
}
|
|
@@ -652,6 +694,36 @@ interface ToolResultSnapshot {
|
|
|
652
694
|
*/
|
|
653
695
|
declare function snapshotToolResult(result: Record<string, unknown>, toolName: string, toolLabel?: string): ToolResultSnapshot;
|
|
654
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
|
+
|
|
655
727
|
declare class Charivo {
|
|
656
728
|
private eventBus;
|
|
657
729
|
private llmManager?;
|
|
@@ -729,7 +801,7 @@ declare class Charivo {
|
|
|
729
801
|
* matters because turn:cancelled names its turn by user message id.
|
|
730
802
|
*/
|
|
731
803
|
private nextMessageId;
|
|
732
|
-
/** A turn is live only while it
|
|
804
|
+
/** A turn is live only while it still owns the current epoch. */
|
|
733
805
|
private isStale;
|
|
734
806
|
private removeQueueEntry;
|
|
735
807
|
/**
|
|
@@ -753,9 +825,32 @@ declare class Charivo {
|
|
|
753
825
|
* Latest-wins: a newer call supersedes the in-flight turn, which then
|
|
754
826
|
* resolves without performing any further turn-scoped effect or emitting
|
|
755
827
|
* any further turn-scoped event. Its user message is retained regardless of
|
|
756
|
-
* 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.
|
|
757
833
|
*/
|
|
758
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>;
|
|
759
854
|
/**
|
|
760
855
|
* Clear the conversation history from the LLM manager.
|
|
761
856
|
*/
|
|
@@ -850,4 +945,4 @@ interface CharivoOptions {
|
|
|
850
945
|
*/
|
|
851
946
|
declare function createCharivo(options?: CharivoOptions): Charivo;
|
|
852
947
|
|
|
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 };
|
|
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.js
CHANGED
|
@@ -1,12 +1,17 @@
|
|
|
1
1
|
// src/bus.ts
|
|
2
2
|
var EventBus = class {
|
|
3
|
-
|
|
3
|
+
// Object.create(null), not {}: EventMap is open to declaration merging, so
|
|
4
|
+
// an augmented event may be named after an Object.prototype member
|
|
5
|
+
// ("constructor", "toString", ...). On a prototype-backed store those keys
|
|
6
|
+
// inherit a truthy value, so `??=` skips the array init and on()/emit()
|
|
7
|
+
// throw. A null-prototype store has no inherited keys.
|
|
8
|
+
listeners = /* @__PURE__ */ Object.create(null);
|
|
4
9
|
on(event, listener) {
|
|
5
10
|
this.listeners[event] ??= [];
|
|
6
11
|
this.listeners[event].push(listener);
|
|
7
12
|
}
|
|
8
13
|
emit(event, data) {
|
|
9
|
-
this.listeners[event]
|
|
14
|
+
[...this.listeners[event] ?? []].forEach((listener) => {
|
|
10
15
|
try {
|
|
11
16
|
listener(data);
|
|
12
17
|
} catch (error) {
|
|
@@ -28,7 +33,7 @@ var EventBus = class {
|
|
|
28
33
|
}
|
|
29
34
|
}
|
|
30
35
|
clear() {
|
|
31
|
-
this.listeners =
|
|
36
|
+
this.listeners = /* @__PURE__ */ Object.create(null);
|
|
32
37
|
}
|
|
33
38
|
};
|
|
34
39
|
|
|
@@ -525,6 +530,83 @@ function snapshotToolResult(result, toolName, toolLabel = "Tool") {
|
|
|
525
530
|
return { serialized, snapshot: parsed };
|
|
526
531
|
}
|
|
527
532
|
|
|
533
|
+
// src/fetch-with-timeout.ts
|
|
534
|
+
var DEFAULT_FETCH_TIMEOUT_MS = 3e4;
|
|
535
|
+
function isAbortError(error) {
|
|
536
|
+
return error instanceof DOMException && error.name === "AbortError" || error instanceof Error && error.name === "AbortError";
|
|
537
|
+
}
|
|
538
|
+
function fetchWithTimeout(input, init, options, consumeBody) {
|
|
539
|
+
const {
|
|
540
|
+
timeoutMessage,
|
|
541
|
+
failureMessage = "Request failed",
|
|
542
|
+
timeoutMs = DEFAULT_FETCH_TIMEOUT_MS,
|
|
543
|
+
signal,
|
|
544
|
+
mapError
|
|
545
|
+
} = options;
|
|
546
|
+
const controller = new AbortController();
|
|
547
|
+
let abortSource = null;
|
|
548
|
+
const onExternalAbort = () => {
|
|
549
|
+
if (abortSource === null) {
|
|
550
|
+
abortSource = "external";
|
|
551
|
+
}
|
|
552
|
+
controller.abort(signal.reason);
|
|
553
|
+
};
|
|
554
|
+
if (signal?.aborted) {
|
|
555
|
+
abortSource = "external";
|
|
556
|
+
controller.abort(signal.reason);
|
|
557
|
+
} else {
|
|
558
|
+
signal?.addEventListener("abort", onExternalAbort);
|
|
559
|
+
}
|
|
560
|
+
const timeoutId = setTimeout(() => {
|
|
561
|
+
if (abortSource === null) {
|
|
562
|
+
abortSource = "timeout";
|
|
563
|
+
}
|
|
564
|
+
controller.abort();
|
|
565
|
+
}, timeoutMs);
|
|
566
|
+
const cleanup = () => {
|
|
567
|
+
clearTimeout(timeoutId);
|
|
568
|
+
signal?.removeEventListener("abort", onExternalAbort);
|
|
569
|
+
};
|
|
570
|
+
const classifyAbort = (error) => {
|
|
571
|
+
if (abortSource === "external" && (error === signal?.reason || isAbortError(error))) {
|
|
572
|
+
return { matched: true, value: error };
|
|
573
|
+
}
|
|
574
|
+
if (abortSource === "timeout" && isAbortError(error)) {
|
|
575
|
+
return {
|
|
576
|
+
matched: true,
|
|
577
|
+
value: new CharivoTimeoutError(timeoutMessage, { cause: error })
|
|
578
|
+
};
|
|
579
|
+
}
|
|
580
|
+
return { matched: false };
|
|
581
|
+
};
|
|
582
|
+
return fetch(input, { ...init, signal: controller.signal }).then(
|
|
583
|
+
(response) => {
|
|
584
|
+
if (!consumeBody) {
|
|
585
|
+
cleanup();
|
|
586
|
+
return response;
|
|
587
|
+
}
|
|
588
|
+
return Promise.resolve().then(() => consumeBody(response)).then(
|
|
589
|
+
(result) => {
|
|
590
|
+
cleanup();
|
|
591
|
+
return result;
|
|
592
|
+
},
|
|
593
|
+
(error) => {
|
|
594
|
+
cleanup();
|
|
595
|
+
const classified = classifyAbort(error);
|
|
596
|
+
throw classified.matched ? classified.value : error;
|
|
597
|
+
}
|
|
598
|
+
);
|
|
599
|
+
},
|
|
600
|
+
(error) => {
|
|
601
|
+
cleanup();
|
|
602
|
+
const classified = classifyAbort(error);
|
|
603
|
+
throw classified.matched ? classified.value : mapError?.(error) ?? new CharivoTransportError(failureMessage, {
|
|
604
|
+
cause: error instanceof Error ? error : void 0
|
|
605
|
+
});
|
|
606
|
+
}
|
|
607
|
+
);
|
|
608
|
+
}
|
|
609
|
+
|
|
528
610
|
// src/index.ts
|
|
529
611
|
var Charivo = class {
|
|
530
612
|
eventBus;
|
|
@@ -663,7 +745,7 @@ var Charivo = class {
|
|
|
663
745
|
this.messageSeq += 1;
|
|
664
746
|
return `${Date.now()}-${this.messageSeq}`;
|
|
665
747
|
}
|
|
666
|
-
/** A turn is live only while it
|
|
748
|
+
/** A turn is live only while it still owns the current epoch. */
|
|
667
749
|
isStale(turn) {
|
|
668
750
|
return this.turnEpoch !== turn.epoch;
|
|
669
751
|
}
|
|
@@ -724,7 +806,11 @@ var Charivo = class {
|
|
|
724
806
|
* Latest-wins: a newer call supersedes the in-flight turn, which then
|
|
725
807
|
* resolves without performing any further turn-scoped effect or emitting
|
|
726
808
|
* any further turn-scoped event. Its user message is retained regardless of
|
|
727
|
-
* the phase the supersession lands in.
|
|
809
|
+
* the phase the supersession lands in. Supersession also aborts the turn's
|
|
810
|
+
* LLM request through the turn's own `AbortSignal`, so a client that honors
|
|
811
|
+
* it stops waiting on the provider; one that ignores it settles late and
|
|
812
|
+
* the turn merely goes quiet once it resumes. {@link Charivo.interrupt}
|
|
813
|
+
* cancels an in-flight turn the same way, without a successor taking over.
|
|
728
814
|
*/
|
|
729
815
|
async userSay(content) {
|
|
730
816
|
const userMessage = {
|
|
@@ -737,7 +823,8 @@ var Charivo = class {
|
|
|
737
823
|
this.turnEpoch += 1;
|
|
738
824
|
const turn = {
|
|
739
825
|
epoch: this.turnEpoch,
|
|
740
|
-
userMessageId: userMessage.id
|
|
826
|
+
userMessageId: userMessage.id,
|
|
827
|
+
abortController: new AbortController()
|
|
741
828
|
};
|
|
742
829
|
const superseded = this.activeTurn;
|
|
743
830
|
this.activeTurn = turn;
|
|
@@ -747,6 +834,7 @@ var Charivo = class {
|
|
|
747
834
|
this.eventBus.emit("message:sent", { message: userMessage });
|
|
748
835
|
this.flushSupersededEntries();
|
|
749
836
|
if (superseded) {
|
|
837
|
+
superseded.abortController.abort();
|
|
750
838
|
this.eventBus.emit("turn:cancelled", {
|
|
751
839
|
userMessageId: superseded.userMessageId
|
|
752
840
|
});
|
|
@@ -800,7 +888,8 @@ var Charivo = class {
|
|
|
800
888
|
}
|
|
801
889
|
response = await generatingManager.generateResponse(userMessage, {
|
|
802
890
|
callerOwnsHistory: true,
|
|
803
|
-
isCancelled: () => this.isStale(turn)
|
|
891
|
+
isCancelled: () => this.isStale(turn),
|
|
892
|
+
signal: turn.abortController.signal
|
|
804
893
|
});
|
|
805
894
|
} catch (error) {
|
|
806
895
|
if (this.isStale(turn)) {
|
|
@@ -867,6 +956,7 @@ var Charivo = class {
|
|
|
867
956
|
return;
|
|
868
957
|
}
|
|
869
958
|
if (this.ttsManager) {
|
|
959
|
+
const speakingManager = this.ttsManager;
|
|
870
960
|
try {
|
|
871
961
|
this.eventBus.emit("tts:start", {
|
|
872
962
|
text: response,
|
|
@@ -881,7 +971,8 @@ var Charivo = class {
|
|
|
881
971
|
volume: this.character.voice.volume,
|
|
882
972
|
voice: this.character.voice.voiceId
|
|
883
973
|
} : void 0;
|
|
884
|
-
|
|
974
|
+
turn.speakingTTSManager = speakingManager;
|
|
975
|
+
await speakingManager.speak(response, ttsOptions);
|
|
885
976
|
if (this.isStale(turn)) {
|
|
886
977
|
return;
|
|
887
978
|
}
|
|
@@ -902,6 +993,48 @@ var Charivo = class {
|
|
|
902
993
|
}
|
|
903
994
|
}
|
|
904
995
|
}
|
|
996
|
+
/**
|
|
997
|
+
* Cut off the in-progress turn and its speech now.
|
|
998
|
+
*
|
|
999
|
+
* The cascade counterpart of `RealtimeManager.interrupt()`: the live turn's
|
|
1000
|
+
* LLM request is aborted, the turn performs and emits nothing further, and
|
|
1001
|
+
* the TTS manager it is speaking on is stopped — the exact manager it handed
|
|
1002
|
+
* the reply to, which a mid-turn `attachTTS()` may since have replaced.
|
|
1003
|
+
* Resolving means that stop has completed, so no audio from the interrupted
|
|
1004
|
+
* turn starts afterwards. The interrupted `userSay()` **resolves**, and the
|
|
1005
|
+
* turn is announced as `turn:cancelled`, exactly as a supersession is.
|
|
1006
|
+
*
|
|
1007
|
+
* Unlike the realtime version, which requires an active, connected session,
|
|
1008
|
+
* this has no precondition: with no turn in flight it still stops the
|
|
1009
|
+
* attached TTS manager, resolves, and emits nothing.
|
|
1010
|
+
*
|
|
1011
|
+
* Realtime mode is not covered — this does not delegate to the realtime
|
|
1012
|
+
* manager. Use `getRealtimeManager()?.interrupt()` there.
|
|
1013
|
+
*/
|
|
1014
|
+
async interrupt() {
|
|
1015
|
+
const interrupted = this.activeTurn;
|
|
1016
|
+
if (interrupted) {
|
|
1017
|
+
this.turnEpoch += 1;
|
|
1018
|
+
this.activeTurn = void 0;
|
|
1019
|
+
this.flushSupersededEntries();
|
|
1020
|
+
interrupted.abortController.abort();
|
|
1021
|
+
this.eventBus.emit("turn:cancelled", {
|
|
1022
|
+
userMessageId: interrupted.userMessageId
|
|
1023
|
+
});
|
|
1024
|
+
}
|
|
1025
|
+
const stopTarget = interrupted?.speakingTTSManager ?? this.ttsManager;
|
|
1026
|
+
if (stopTarget) {
|
|
1027
|
+
try {
|
|
1028
|
+
await stopTarget.stop();
|
|
1029
|
+
} catch (error) {
|
|
1030
|
+
throw toCharivoError(
|
|
1031
|
+
"provider",
|
|
1032
|
+
error,
|
|
1033
|
+
"Failed to stop TTS during interrupt"
|
|
1034
|
+
);
|
|
1035
|
+
}
|
|
1036
|
+
}
|
|
1037
|
+
}
|
|
905
1038
|
/**
|
|
906
1039
|
* Clear the conversation history from the LLM manager.
|
|
907
1040
|
*/
|
|
@@ -1093,6 +1226,6 @@ function createCharivo(options = {}) {
|
|
|
1093
1226
|
return charivo;
|
|
1094
1227
|
}
|
|
1095
1228
|
|
|
1096
|
-
export { Charivo, CharivoDisposeError, CharivoError, CharivoProviderError, CharivoStateError, CharivoTimeoutError, CharivoTransportError, OPENAI_REALTIME_ADAPTER, OPENAI_REALTIME_AGENTS_ADAPTER, assertToolResultObject, createCharivo, createLipSyncAnalyzer, createToolFailureOutput, createToolRegistry, getErrorMessage, isCharivoError, snapshotToolResult, subscribeBrowserLifecycle, toCharivoError, validateToolArguments, withToolTimeout };
|
|
1229
|
+
export { Charivo, CharivoDisposeError, CharivoError, CharivoProviderError, CharivoStateError, CharivoTimeoutError, CharivoTransportError, DEFAULT_FETCH_TIMEOUT_MS, OPENAI_REALTIME_ADAPTER, OPENAI_REALTIME_AGENTS_ADAPTER, assertToolResultObject, createCharivo, createLipSyncAnalyzer, createToolFailureOutput, createToolRegistry, fetchWithTimeout, getErrorMessage, isCharivoError, snapshotToolResult, subscribeBrowserLifecycle, toCharivoError, validateToolArguments, withToolTimeout };
|
|
1097
1230
|
//# sourceMappingURL=index.js.map
|
|
1098
1231
|
//# sourceMappingURL=index.js.map
|