@charivo/core 0.16.0 → 0.18.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
@@ -53,16 +53,43 @@ type RealtimeTransportKind = "webrtc" | "websocket";
53
53
  type RealtimeToolChoice = "auto" | "none" | "required";
54
54
  declare const OPENAI_REALTIME_ADAPTER = "openai-webrtc";
55
55
  declare const OPENAI_REALTIME_AGENTS_ADAPTER = "openai-agents-webrtc";
56
- interface RealtimeTool {
56
+ interface ToolDefinition {
57
57
  type: "function";
58
58
  name: string;
59
59
  description: string;
60
+ /**
61
+ * JSON Schema-shaped. `validateToolArguments` only enforces required-key
62
+ * presence, enum membership, and each property's top-level `type`; nested
63
+ * schemas, `additionalProperties`, and numeric-length constraints are not
64
+ * validated.
65
+ */
60
66
  parameters: {
61
67
  type: "object";
62
68
  properties: Record<string, unknown>;
63
69
  required?: string[];
64
70
  };
65
71
  }
72
+ interface ToolContext {
73
+ character?: Character | null;
74
+ callId?: string;
75
+ /** Present only for realtime sessions. */
76
+ state?: RealtimeState;
77
+ }
78
+ /** Must resolve to a plain object; arrays and primitives are rejected by the runners. */
79
+ type ToolHandler = (args: Record<string, unknown>, context: ToolContext) => Promise<Record<string, unknown>>;
80
+ interface ToolRegistration {
81
+ definition: ToolDefinition;
82
+ handler: ToolHandler;
83
+ /** Timeout in ms; falls back to the manager default when omitted. */
84
+ timeoutMs?: number;
85
+ }
86
+ interface ToolResultProjectorContext {
87
+ name: string;
88
+ output: Record<string, unknown>;
89
+ callId?: string;
90
+ emit<K extends keyof EventMap>(event: K, payload: EventMap[K]): void;
91
+ }
92
+ type ToolResultProjector = (context: ToolResultProjectorContext) => void;
66
93
  interface RealtimeSessionConfig {
67
94
  provider?: string;
68
95
  transport?: RealtimeTransportKind;
@@ -71,7 +98,7 @@ interface RealtimeSessionConfig {
71
98
  instructions?: string;
72
99
  temperature?: number;
73
100
  maxTokens?: number;
74
- tools?: RealtimeTool[];
101
+ tools?: ToolDefinition[];
75
102
  toolChoice?: RealtimeToolChoice;
76
103
  inputAudioTranscription?: {
77
104
  model?: string;
@@ -119,17 +146,6 @@ interface RealtimeState {
119
146
  };
120
147
  lastError: Error | null;
121
148
  }
122
- interface RealtimeToolContext {
123
- character?: Character | null;
124
- state: RealtimeState;
125
- callId?: string;
126
- }
127
- type RealtimeToolHandler = (args: Record<string, unknown>, context: RealtimeToolContext) => Promise<Record<string, unknown>>;
128
- interface RealtimeToolRegistration {
129
- definition: RealtimeTool;
130
- handler: RealtimeToolHandler;
131
- timeoutMs?: number;
132
- }
133
149
  interface RealtimeUsageEvent {
134
150
  usage: Record<string, unknown>;
135
151
  model?: string;
@@ -141,17 +157,48 @@ interface LLMAdapter {
141
157
  setCharacter(character: Character): void;
142
158
  clearHistory(): void;
143
159
  }
160
+ interface LLMToolCall {
161
+ id: string;
162
+ name: string;
163
+ /** JSON-decoded; the provider/client adapter parses the raw tool-call arguments before this contract is used. */
164
+ arguments: Record<string, unknown>;
165
+ }
166
+ /**
167
+ * Role-discriminated union so protocol-invalid combinations are unrepresentable
168
+ * for typed direct callers: unknown roles, tool turns without an ID, and tool
169
+ * calls on user turns cannot be expressed.
170
+ */
171
+ type LLMMessage = {
172
+ role: "system" | "user";
173
+ content: string;
174
+ } | {
175
+ role: "assistant";
176
+ content: string;
177
+ toolCalls?: LLMToolCall[];
178
+ } | {
179
+ role: "tool";
180
+ content: string;
181
+ toolCallId: string;
182
+ };
183
+ interface LLMToolResponse {
184
+ content: string;
185
+ toolCalls?: LLMToolCall[];
186
+ }
144
187
  interface LLMProvider {
145
188
  generateResponse(messages: Array<{
146
189
  role: string;
147
190
  content: string;
148
191
  }>): Promise<string>;
192
+ /** Tool-calling variant; providers that support function calling implement this alongside generateResponse. */
193
+ generateResponseWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
149
194
  }
150
195
  interface LLMClient {
151
196
  call(messages: Array<{
152
197
  role: string;
153
198
  content: string;
154
199
  }>): Promise<string>;
200
+ /** Tool-calling variant; clients that support function calling implement this alongside call. */
201
+ callWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
155
202
  }
156
203
  interface LLMManager {
157
204
  setCharacter(character: Character): void;
@@ -159,6 +206,24 @@ interface LLMManager {
159
206
  clearHistory(): void;
160
207
  getHistory(): Message[];
161
208
  generateResponse(message: Message): Promise<string>;
209
+ setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
210
+ registerTool?(tool: ToolRegistration): void;
211
+ unregisterTool?(name: string): void;
212
+ getRegisteredTools?(): ToolDefinition[];
213
+ /** System-prompt-level instructions injected only when tools are registered; pass null to clear. */
214
+ setToolInstructions?(instructions: string | null): void;
215
+ }
216
+ /**
217
+ * `LLMManager` with the tool-calling members required instead of optional.
218
+ * Third-party `LLMManager` implementations may omit tool support, but the
219
+ * built-in manager returned by `createLLMManager` always provides it.
220
+ */
221
+ interface LLMManagerWithTools extends LLMManager {
222
+ setEventEmitter(eventEmitter: CharivoEventEmitter): void;
223
+ registerTool(tool: ToolRegistration): void;
224
+ unregisterTool(name: string): void;
225
+ getRegisteredTools(): ToolDefinition[];
226
+ setToolInstructions(instructions: string | null): void;
162
227
  }
163
228
  interface Renderer {
164
229
  initialize(): Promise<void>;
@@ -258,9 +323,9 @@ interface RealtimeManager {
258
323
  sendMessage(text: string): Promise<void>;
259
324
  sendAudioChunk(audio: ArrayBuffer): Promise<void>;
260
325
  interrupt(): Promise<void>;
261
- registerTool(tool: RealtimeToolRegistration): void;
326
+ registerTool(tool: ToolRegistration): void;
262
327
  unregisterTool(name: string): void;
263
- getRegisteredTools(): RealtimeTool[];
328
+ getRegisteredTools(): ToolDefinition[];
264
329
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
265
330
  }
266
331
  type EventMap = {
@@ -361,14 +426,14 @@ type EventMap = {
361
426
  lastError: Error;
362
427
  };
363
428
  "realtime:usage": RealtimeUsageEvent;
364
- "realtime:expression": {
429
+ "avatar:expression": {
365
430
  expressionId: string;
366
431
  };
367
- "realtime:motion": {
432
+ "avatar:motion": {
368
433
  group: string;
369
434
  index: number;
370
435
  };
371
- "realtime:gaze": GazeCoordinates;
436
+ "avatar:gaze": GazeCoordinates;
372
437
  "realtime:text:delta": {
373
438
  text: string;
374
439
  };
@@ -462,6 +527,36 @@ interface LipSyncAnalyzer {
462
527
  }
463
528
  declare function createLipSyncAnalyzer(options: LipSyncAnalyzerOptions): LipSyncAnalyzer;
464
529
 
530
+ /**
531
+ * Shared tool validation: the single argument/result contract enforced before
532
+ * and after a tool handler runs, regardless of the modality that calls it.
533
+ *
534
+ * Errors here are plain `Error`, not a `CharivoErrorKind` variant, on purpose:
535
+ * this preserves message-string compatibility with the pre-move realtime
536
+ * validator, and no existing error kind fits schema validation.
537
+ */
538
+
539
+ /**
540
+ * Validates tool call arguments against a definition's parameter schema.
541
+ *
542
+ * Enforces only: required-key presence, `enum` membership, and each
543
+ * property's top-level `type`. Nested schemas, `additionalProperties`, and
544
+ * numeric-length constraints (`minLength`, `maximum`, etc.) are not
545
+ * validated. Throws a plain `Error` on the first violation found.
546
+ *
547
+ * @param toolLabel - Prefixes thrown messages (e.g. `${toolLabel} "name" ...`);
548
+ * callers use this to distinguish realtime tools from other modalities.
549
+ */
550
+ declare function validateToolArguments(definition: ToolDefinition, args: unknown, toolLabel?: string): void;
551
+ /**
552
+ * Tool handlers must resolve to a plain object; arrays and primitives are not
553
+ * serializable tool outputs. Throws a plain `Error` on violation.
554
+ *
555
+ * @param toolLabel - Prefixes the thrown message (e.g. `${toolLabel} "name" ...`);
556
+ * callers use this to distinguish realtime tools from other modalities.
557
+ */
558
+ declare function assertToolResultObject(result: unknown, toolName: string, toolLabel?: string): asserts result is Record<string, unknown>;
559
+
465
560
  declare class Charivo {
466
561
  private eventBus;
467
562
  private llmManager?;
@@ -520,6 +615,10 @@ declare class Charivo {
520
615
  * Connects the STT manager to the event bus for speech recognition event emission.
521
616
  */
522
617
  private connectSTTManagerEventEmitter;
618
+ /**
619
+ * Connects the LLM manager to the event bus for tool-call event emission.
620
+ */
621
+ private connectLLMManagerEventEmitter;
523
622
  /**
524
623
  * Set the character for this Charivo instance.
525
624
  * Automatically propagates to all attached managers (LLM, Renderer).
@@ -587,4 +686,4 @@ declare class Charivo {
587
686
  private finishDispose;
588
687
  }
589
688
 
590
- 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, EventBus, type EventMap, type GazeCoordinates, type LLMAdapter, type LLMClient, type LLMManager, type LLMProvider, 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 RealtimeTool, type RealtimeToolChoice, type RealtimeToolContext, type RealtimeToolHandler, type RealtimeToolRegistration, 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, createLipSyncAnalyzer, getErrorMessage, isCharivoError, subscribeBrowserLifecycle, toCharivoError };
689
+ 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, EventBus, type EventMap, type GazeCoordinates, type LLMAdapter, type LLMClient, type LLMManager, type LLMManagerWithTools, type LLMMessage, type LLMProvider, type LLMToolCall, type LLMToolResponse, type LipSyncAnalyzer, type LipSyncAnalyzerOptions, type Message, type MotionSelection, OPENAI_REALTIME_ADAPTER, OPENAI_REALTIME_AGENTS_ADAPTER, type Plugin, type RealtimeConnectionState, type RealtimeManager, type RealtimeProvider, type RealtimeReconnectCause, type RealtimeResponseStatus, type RealtimeSessionBootstrap, type RealtimeSessionConfig, type RealtimeSessionRequest, type RealtimeSessionStatus, type RealtimeSessionTransitionReason, type RealtimeState, type RealtimeToolChoice, type RealtimeTransportKind, type RealtimeUsageEvent, type RenderManager, type Renderer, type STTManager, type STTOptions, type STTProvider, type STTTranscriber, type TTSManager, type TTSOptions, type TTSPlaybackMode, type TTSPlayer, type TTSProvider, type ToolContext, type ToolDefinition, type ToolHandler, type ToolRegistration, type ToolResultProjector, type ToolResultProjectorContext, assertToolResultObject, createLipSyncAnalyzer, getErrorMessage, isCharivoError, subscribeBrowserLifecycle, toCharivoError, validateToolArguments };
package/dist/index.d.ts CHANGED
@@ -53,16 +53,43 @@ type RealtimeTransportKind = "webrtc" | "websocket";
53
53
  type RealtimeToolChoice = "auto" | "none" | "required";
54
54
  declare const OPENAI_REALTIME_ADAPTER = "openai-webrtc";
55
55
  declare const OPENAI_REALTIME_AGENTS_ADAPTER = "openai-agents-webrtc";
56
- interface RealtimeTool {
56
+ interface ToolDefinition {
57
57
  type: "function";
58
58
  name: string;
59
59
  description: string;
60
+ /**
61
+ * JSON Schema-shaped. `validateToolArguments` only enforces required-key
62
+ * presence, enum membership, and each property's top-level `type`; nested
63
+ * schemas, `additionalProperties`, and numeric-length constraints are not
64
+ * validated.
65
+ */
60
66
  parameters: {
61
67
  type: "object";
62
68
  properties: Record<string, unknown>;
63
69
  required?: string[];
64
70
  };
65
71
  }
72
+ interface ToolContext {
73
+ character?: Character | null;
74
+ callId?: string;
75
+ /** Present only for realtime sessions. */
76
+ state?: RealtimeState;
77
+ }
78
+ /** Must resolve to a plain object; arrays and primitives are rejected by the runners. */
79
+ type ToolHandler = (args: Record<string, unknown>, context: ToolContext) => Promise<Record<string, unknown>>;
80
+ interface ToolRegistration {
81
+ definition: ToolDefinition;
82
+ handler: ToolHandler;
83
+ /** Timeout in ms; falls back to the manager default when omitted. */
84
+ timeoutMs?: number;
85
+ }
86
+ interface ToolResultProjectorContext {
87
+ name: string;
88
+ output: Record<string, unknown>;
89
+ callId?: string;
90
+ emit<K extends keyof EventMap>(event: K, payload: EventMap[K]): void;
91
+ }
92
+ type ToolResultProjector = (context: ToolResultProjectorContext) => void;
66
93
  interface RealtimeSessionConfig {
67
94
  provider?: string;
68
95
  transport?: RealtimeTransportKind;
@@ -71,7 +98,7 @@ interface RealtimeSessionConfig {
71
98
  instructions?: string;
72
99
  temperature?: number;
73
100
  maxTokens?: number;
74
- tools?: RealtimeTool[];
101
+ tools?: ToolDefinition[];
75
102
  toolChoice?: RealtimeToolChoice;
76
103
  inputAudioTranscription?: {
77
104
  model?: string;
@@ -119,17 +146,6 @@ interface RealtimeState {
119
146
  };
120
147
  lastError: Error | null;
121
148
  }
122
- interface RealtimeToolContext {
123
- character?: Character | null;
124
- state: RealtimeState;
125
- callId?: string;
126
- }
127
- type RealtimeToolHandler = (args: Record<string, unknown>, context: RealtimeToolContext) => Promise<Record<string, unknown>>;
128
- interface RealtimeToolRegistration {
129
- definition: RealtimeTool;
130
- handler: RealtimeToolHandler;
131
- timeoutMs?: number;
132
- }
133
149
  interface RealtimeUsageEvent {
134
150
  usage: Record<string, unknown>;
135
151
  model?: string;
@@ -141,17 +157,48 @@ interface LLMAdapter {
141
157
  setCharacter(character: Character): void;
142
158
  clearHistory(): void;
143
159
  }
160
+ interface LLMToolCall {
161
+ id: string;
162
+ name: string;
163
+ /** JSON-decoded; the provider/client adapter parses the raw tool-call arguments before this contract is used. */
164
+ arguments: Record<string, unknown>;
165
+ }
166
+ /**
167
+ * Role-discriminated union so protocol-invalid combinations are unrepresentable
168
+ * for typed direct callers: unknown roles, tool turns without an ID, and tool
169
+ * calls on user turns cannot be expressed.
170
+ */
171
+ type LLMMessage = {
172
+ role: "system" | "user";
173
+ content: string;
174
+ } | {
175
+ role: "assistant";
176
+ content: string;
177
+ toolCalls?: LLMToolCall[];
178
+ } | {
179
+ role: "tool";
180
+ content: string;
181
+ toolCallId: string;
182
+ };
183
+ interface LLMToolResponse {
184
+ content: string;
185
+ toolCalls?: LLMToolCall[];
186
+ }
144
187
  interface LLMProvider {
145
188
  generateResponse(messages: Array<{
146
189
  role: string;
147
190
  content: string;
148
191
  }>): Promise<string>;
192
+ /** Tool-calling variant; providers that support function calling implement this alongside generateResponse. */
193
+ generateResponseWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
149
194
  }
150
195
  interface LLMClient {
151
196
  call(messages: Array<{
152
197
  role: string;
153
198
  content: string;
154
199
  }>): Promise<string>;
200
+ /** Tool-calling variant; clients that support function calling implement this alongside call. */
201
+ callWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
155
202
  }
156
203
  interface LLMManager {
157
204
  setCharacter(character: Character): void;
@@ -159,6 +206,24 @@ interface LLMManager {
159
206
  clearHistory(): void;
160
207
  getHistory(): Message[];
161
208
  generateResponse(message: Message): Promise<string>;
209
+ setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
210
+ registerTool?(tool: ToolRegistration): void;
211
+ unregisterTool?(name: string): void;
212
+ getRegisteredTools?(): ToolDefinition[];
213
+ /** System-prompt-level instructions injected only when tools are registered; pass null to clear. */
214
+ setToolInstructions?(instructions: string | null): void;
215
+ }
216
+ /**
217
+ * `LLMManager` with the tool-calling members required instead of optional.
218
+ * Third-party `LLMManager` implementations may omit tool support, but the
219
+ * built-in manager returned by `createLLMManager` always provides it.
220
+ */
221
+ interface LLMManagerWithTools extends LLMManager {
222
+ setEventEmitter(eventEmitter: CharivoEventEmitter): void;
223
+ registerTool(tool: ToolRegistration): void;
224
+ unregisterTool(name: string): void;
225
+ getRegisteredTools(): ToolDefinition[];
226
+ setToolInstructions(instructions: string | null): void;
162
227
  }
163
228
  interface Renderer {
164
229
  initialize(): Promise<void>;
@@ -258,9 +323,9 @@ interface RealtimeManager {
258
323
  sendMessage(text: string): Promise<void>;
259
324
  sendAudioChunk(audio: ArrayBuffer): Promise<void>;
260
325
  interrupt(): Promise<void>;
261
- registerTool(tool: RealtimeToolRegistration): void;
326
+ registerTool(tool: ToolRegistration): void;
262
327
  unregisterTool(name: string): void;
263
- getRegisteredTools(): RealtimeTool[];
328
+ getRegisteredTools(): ToolDefinition[];
264
329
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
265
330
  }
266
331
  type EventMap = {
@@ -361,14 +426,14 @@ type EventMap = {
361
426
  lastError: Error;
362
427
  };
363
428
  "realtime:usage": RealtimeUsageEvent;
364
- "realtime:expression": {
429
+ "avatar:expression": {
365
430
  expressionId: string;
366
431
  };
367
- "realtime:motion": {
432
+ "avatar:motion": {
368
433
  group: string;
369
434
  index: number;
370
435
  };
371
- "realtime:gaze": GazeCoordinates;
436
+ "avatar:gaze": GazeCoordinates;
372
437
  "realtime:text:delta": {
373
438
  text: string;
374
439
  };
@@ -462,6 +527,36 @@ interface LipSyncAnalyzer {
462
527
  }
463
528
  declare function createLipSyncAnalyzer(options: LipSyncAnalyzerOptions): LipSyncAnalyzer;
464
529
 
530
+ /**
531
+ * Shared tool validation: the single argument/result contract enforced before
532
+ * and after a tool handler runs, regardless of the modality that calls it.
533
+ *
534
+ * Errors here are plain `Error`, not a `CharivoErrorKind` variant, on purpose:
535
+ * this preserves message-string compatibility with the pre-move realtime
536
+ * validator, and no existing error kind fits schema validation.
537
+ */
538
+
539
+ /**
540
+ * Validates tool call arguments against a definition's parameter schema.
541
+ *
542
+ * Enforces only: required-key presence, `enum` membership, and each
543
+ * property's top-level `type`. Nested schemas, `additionalProperties`, and
544
+ * numeric-length constraints (`minLength`, `maximum`, etc.) are not
545
+ * validated. Throws a plain `Error` on the first violation found.
546
+ *
547
+ * @param toolLabel - Prefixes thrown messages (e.g. `${toolLabel} "name" ...`);
548
+ * callers use this to distinguish realtime tools from other modalities.
549
+ */
550
+ declare function validateToolArguments(definition: ToolDefinition, args: unknown, toolLabel?: string): void;
551
+ /**
552
+ * Tool handlers must resolve to a plain object; arrays and primitives are not
553
+ * serializable tool outputs. Throws a plain `Error` on violation.
554
+ *
555
+ * @param toolLabel - Prefixes the thrown message (e.g. `${toolLabel} "name" ...`);
556
+ * callers use this to distinguish realtime tools from other modalities.
557
+ */
558
+ declare function assertToolResultObject(result: unknown, toolName: string, toolLabel?: string): asserts result is Record<string, unknown>;
559
+
465
560
  declare class Charivo {
466
561
  private eventBus;
467
562
  private llmManager?;
@@ -520,6 +615,10 @@ declare class Charivo {
520
615
  * Connects the STT manager to the event bus for speech recognition event emission.
521
616
  */
522
617
  private connectSTTManagerEventEmitter;
618
+ /**
619
+ * Connects the LLM manager to the event bus for tool-call event emission.
620
+ */
621
+ private connectLLMManagerEventEmitter;
523
622
  /**
524
623
  * Set the character for this Charivo instance.
525
624
  * Automatically propagates to all attached managers (LLM, Renderer).
@@ -587,4 +686,4 @@ declare class Charivo {
587
686
  private finishDispose;
588
687
  }
589
688
 
590
- 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, EventBus, type EventMap, type GazeCoordinates, type LLMAdapter, type LLMClient, type LLMManager, type LLMProvider, 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 RealtimeTool, type RealtimeToolChoice, type RealtimeToolContext, type RealtimeToolHandler, type RealtimeToolRegistration, 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, createLipSyncAnalyzer, getErrorMessage, isCharivoError, subscribeBrowserLifecycle, toCharivoError };
689
+ 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, EventBus, type EventMap, type GazeCoordinates, type LLMAdapter, type LLMClient, type LLMManager, type LLMManagerWithTools, type LLMMessage, type LLMProvider, type LLMToolCall, type LLMToolResponse, type LipSyncAnalyzer, type LipSyncAnalyzerOptions, type Message, type MotionSelection, OPENAI_REALTIME_ADAPTER, OPENAI_REALTIME_AGENTS_ADAPTER, type Plugin, type RealtimeConnectionState, type RealtimeManager, type RealtimeProvider, type RealtimeReconnectCause, type RealtimeResponseStatus, type RealtimeSessionBootstrap, type RealtimeSessionConfig, type RealtimeSessionRequest, type RealtimeSessionStatus, type RealtimeSessionTransitionReason, type RealtimeState, type RealtimeToolChoice, type RealtimeTransportKind, type RealtimeUsageEvent, type RenderManager, type Renderer, type STTManager, type STTOptions, type STTProvider, type STTTranscriber, type TTSManager, type TTSOptions, type TTSPlaybackMode, type TTSPlayer, type TTSProvider, type ToolContext, type ToolDefinition, type ToolHandler, type ToolRegistration, type ToolResultProjector, type ToolResultProjectorContext, assertToolResultObject, createLipSyncAnalyzer, getErrorMessage, isCharivoError, subscribeBrowserLifecycle, toCharivoError, validateToolArguments };
package/dist/index.js CHANGED
@@ -341,6 +341,94 @@ function createLipSyncAnalyzer(options) {
341
341
  return new LipSyncAnalyzerImpl(options);
342
342
  }
343
343
 
344
+ // src/tool-validation.ts
345
+ function validateToolArguments(definition, args, toolLabel = "Tool") {
346
+ if (!isRecord(args) || Array.isArray(args)) {
347
+ throw new Error(
348
+ `${toolLabel} "${definition.name}" arguments failed schema validation: arguments must be an object`
349
+ );
350
+ }
351
+ const { parameters } = definition;
352
+ const required = parameters.required ?? [];
353
+ for (const propertyName of required) {
354
+ if (!hasOwnProperty(args, propertyName)) {
355
+ throw new Error(
356
+ `${toolLabel} "${definition.name}" arguments failed schema validation: missing required property "${propertyName}"`
357
+ );
358
+ }
359
+ }
360
+ for (const [propertyName, schema] of Object.entries(parameters.properties)) {
361
+ if (!hasOwnProperty(args, propertyName) || !isRecord(schema)) {
362
+ continue;
363
+ }
364
+ validateToolArgumentValue(
365
+ definition.name,
366
+ propertyName,
367
+ args[propertyName],
368
+ schema,
369
+ toolLabel
370
+ );
371
+ }
372
+ }
373
+ function assertToolResultObject(result, toolName, toolLabel = "Tool") {
374
+ if (!isRecord(result) || Array.isArray(result)) {
375
+ throw new Error(`${toolLabel} "${toolName}" must return an object`);
376
+ }
377
+ }
378
+ function validateToolArgumentValue(toolName, propertyName, value, schema, toolLabel) {
379
+ const enumValues = schema.enum;
380
+ if (Array.isArray(enumValues) && !enumValues.some((item) => Object.is(item, value))) {
381
+ throw new Error(
382
+ `${toolLabel} "${toolName}" arguments failed schema validation: property "${propertyName}" must be one of ${formatEnumValues(enumValues)}`
383
+ );
384
+ }
385
+ const expectedType = schema.type;
386
+ if (typeof expectedType !== "string") {
387
+ return;
388
+ }
389
+ if (!isSupportedSchemaType(expectedType)) {
390
+ throw new Error(
391
+ `${toolLabel} "${toolName}" arguments failed schema validation: property "${propertyName}" uses unsupported schema type "${expectedType}"`
392
+ );
393
+ }
394
+ if (!matchesSchemaType(value, expectedType)) {
395
+ throw new Error(
396
+ `${toolLabel} "${toolName}" arguments failed schema validation: property "${propertyName}" must be ${expectedType}`
397
+ );
398
+ }
399
+ }
400
+ function matchesSchemaType(value, expectedType) {
401
+ switch (expectedType) {
402
+ case "string":
403
+ return typeof value === "string";
404
+ case "number":
405
+ return typeof value === "number" && Number.isFinite(value);
406
+ case "integer":
407
+ return typeof value === "number" && Number.isInteger(value);
408
+ case "boolean":
409
+ return typeof value === "boolean";
410
+ case "object":
411
+ return isRecord(value) && !Array.isArray(value);
412
+ case "array":
413
+ return Array.isArray(value);
414
+ case "null":
415
+ return value === null;
416
+ }
417
+ return false;
418
+ }
419
+ function isSupportedSchemaType(expectedType) {
420
+ return expectedType === "string" || expectedType === "number" || expectedType === "integer" || expectedType === "boolean" || expectedType === "object" || expectedType === "array" || expectedType === "null";
421
+ }
422
+ function formatEnumValues(values) {
423
+ return values.map((value) => JSON.stringify(value)).join(", ");
424
+ }
425
+ function hasOwnProperty(record, propertyName) {
426
+ return Object.prototype.hasOwnProperty.call(record, propertyName);
427
+ }
428
+ function isRecord(value) {
429
+ return typeof value === "object" && value !== null;
430
+ }
431
+
344
432
  // src/index.ts
345
433
  var Charivo = class {
346
434
  eventBus;
@@ -380,6 +468,7 @@ var Charivo = class {
380
468
  */
381
469
  attachLLM(manager) {
382
470
  this.llmManager = manager;
471
+ this.connectLLMManagerEventEmitter(manager);
383
472
  if (this.character) {
384
473
  manager.setCharacter(this.character);
385
474
  }
@@ -441,6 +530,14 @@ var Charivo = class {
441
530
  manager.setEventEmitter(this.eventBus);
442
531
  }
443
532
  }
533
+ /**
534
+ * Connects the LLM manager to the event bus for tool-call event emission.
535
+ */
536
+ connectLLMManagerEventEmitter(manager) {
537
+ if (manager.setEventEmitter) {
538
+ manager.setEventEmitter(this.eventBus);
539
+ }
540
+ }
444
541
  /**
445
542
  * Set the character for this Charivo instance.
446
543
  * Automatically propagates to all attached managers (LLM, Renderer).
@@ -686,6 +783,6 @@ var Charivo = class {
686
783
  }
687
784
  };
688
785
 
689
- export { Charivo, CharivoDisposeError, CharivoError, CharivoProviderError, CharivoStateError, CharivoTimeoutError, CharivoTransportError, EventBus, OPENAI_REALTIME_ADAPTER, OPENAI_REALTIME_AGENTS_ADAPTER, createLipSyncAnalyzer, getErrorMessage, isCharivoError, subscribeBrowserLifecycle, toCharivoError };
786
+ export { Charivo, CharivoDisposeError, CharivoError, CharivoProviderError, CharivoStateError, CharivoTimeoutError, CharivoTransportError, EventBus, OPENAI_REALTIME_ADAPTER, OPENAI_REALTIME_AGENTS_ADAPTER, assertToolResultObject, createLipSyncAnalyzer, getErrorMessage, isCharivoError, subscribeBrowserLifecycle, toCharivoError, validateToolArguments };
690
787
  //# sourceMappingURL=index.js.map
691
788
  //# sourceMappingURL=index.js.map