@charivo/core 0.16.0 → 0.17.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,12 +146,16 @@ interface RealtimeState {
119
146
  };
120
147
  lastError: Error | null;
121
148
  }
122
- interface RealtimeToolContext {
123
- character?: Character | null;
149
+ /** @deprecated Use ToolDefinition */
150
+ interface RealtimeTool extends ToolDefinition {
151
+ }
152
+ /** @deprecated Use ToolContext (note: context.state becomes optional in the neutral contract) */
153
+ interface RealtimeToolContext extends ToolContext {
124
154
  state: RealtimeState;
125
- callId?: string;
126
155
  }
156
+ /** @deprecated Use ToolHandler (note: context.state becomes optional in the neutral contract) */
127
157
  type RealtimeToolHandler = (args: Record<string, unknown>, context: RealtimeToolContext) => Promise<Record<string, unknown>>;
158
+ /** @deprecated Use ToolRegistration (note: context.state becomes optional in the neutral contract) */
128
159
  interface RealtimeToolRegistration {
129
160
  definition: RealtimeTool;
130
161
  handler: RealtimeToolHandler;
@@ -141,17 +172,48 @@ interface LLMAdapter {
141
172
  setCharacter(character: Character): void;
142
173
  clearHistory(): void;
143
174
  }
175
+ interface LLMToolCall {
176
+ id: string;
177
+ name: string;
178
+ /** JSON-decoded; the provider/client adapter parses the raw tool-call arguments before this contract is used. */
179
+ arguments: Record<string, unknown>;
180
+ }
181
+ /**
182
+ * Role-discriminated union so protocol-invalid combinations are unrepresentable
183
+ * for typed direct callers: unknown roles, tool turns without an ID, and tool
184
+ * calls on user turns cannot be expressed.
185
+ */
186
+ type LLMMessage = {
187
+ role: "system" | "user";
188
+ content: string;
189
+ } | {
190
+ role: "assistant";
191
+ content: string;
192
+ toolCalls?: LLMToolCall[];
193
+ } | {
194
+ role: "tool";
195
+ content: string;
196
+ toolCallId: string;
197
+ };
198
+ interface LLMToolResponse {
199
+ content: string;
200
+ toolCalls?: LLMToolCall[];
201
+ }
144
202
  interface LLMProvider {
145
203
  generateResponse(messages: Array<{
146
204
  role: string;
147
205
  content: string;
148
206
  }>): Promise<string>;
207
+ /** Tool-calling variant; providers that support function calling implement this alongside generateResponse. */
208
+ generateResponseWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
149
209
  }
150
210
  interface LLMClient {
151
211
  call(messages: Array<{
152
212
  role: string;
153
213
  content: string;
154
214
  }>): Promise<string>;
215
+ /** Tool-calling variant; clients that support function calling implement this alongside call. */
216
+ callWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
155
217
  }
156
218
  interface LLMManager {
157
219
  setCharacter(character: Character): void;
@@ -159,6 +221,24 @@ interface LLMManager {
159
221
  clearHistory(): void;
160
222
  getHistory(): Message[];
161
223
  generateResponse(message: Message): Promise<string>;
224
+ setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
225
+ registerTool?(tool: ToolRegistration): void;
226
+ unregisterTool?(name: string): void;
227
+ getRegisteredTools?(): ToolDefinition[];
228
+ /** System-prompt-level instructions injected only when tools are registered; pass null to clear. */
229
+ setToolInstructions?(instructions: string | null): void;
230
+ }
231
+ /**
232
+ * `LLMManager` with the tool-calling members required instead of optional.
233
+ * Third-party `LLMManager` implementations may omit tool support, but the
234
+ * built-in manager returned by `createLLMManager` always provides it.
235
+ */
236
+ interface LLMManagerWithTools extends LLMManager {
237
+ setEventEmitter(eventEmitter: CharivoEventEmitter): void;
238
+ registerTool(tool: ToolRegistration): void;
239
+ unregisterTool(name: string): void;
240
+ getRegisteredTools(): ToolDefinition[];
241
+ setToolInstructions(instructions: string | null): void;
162
242
  }
163
243
  interface Renderer {
164
244
  initialize(): Promise<void>;
@@ -260,7 +340,7 @@ interface RealtimeManager {
260
340
  interrupt(): Promise<void>;
261
341
  registerTool(tool: RealtimeToolRegistration): void;
262
342
  unregisterTool(name: string): void;
263
- getRegisteredTools(): RealtimeTool[];
343
+ getRegisteredTools(): ToolDefinition[];
264
344
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
265
345
  }
266
346
  type EventMap = {
@@ -361,14 +441,14 @@ type EventMap = {
361
441
  lastError: Error;
362
442
  };
363
443
  "realtime:usage": RealtimeUsageEvent;
364
- "realtime:expression": {
444
+ "avatar:expression": {
365
445
  expressionId: string;
366
446
  };
367
- "realtime:motion": {
447
+ "avatar:motion": {
368
448
  group: string;
369
449
  index: number;
370
450
  };
371
- "realtime:gaze": GazeCoordinates;
451
+ "avatar:gaze": GazeCoordinates;
372
452
  "realtime:text:delta": {
373
453
  text: string;
374
454
  };
@@ -462,6 +542,36 @@ interface LipSyncAnalyzer {
462
542
  }
463
543
  declare function createLipSyncAnalyzer(options: LipSyncAnalyzerOptions): LipSyncAnalyzer;
464
544
 
545
+ /**
546
+ * Shared tool validation: the single argument/result contract enforced before
547
+ * and after a tool handler runs, regardless of the modality that calls it.
548
+ *
549
+ * Errors here are plain `Error`, not a `CharivoErrorKind` variant, on purpose:
550
+ * this preserves message-string compatibility with the pre-move realtime
551
+ * validator, and no existing error kind fits schema validation.
552
+ */
553
+
554
+ /**
555
+ * Validates tool call arguments against a definition's parameter schema.
556
+ *
557
+ * Enforces only: required-key presence, `enum` membership, and each
558
+ * property's top-level `type`. Nested schemas, `additionalProperties`, and
559
+ * numeric-length constraints (`minLength`, `maximum`, etc.) are not
560
+ * validated. Throws a plain `Error` on the first violation found.
561
+ *
562
+ * @param toolLabel - Prefixes thrown messages (e.g. `${toolLabel} "name" ...`);
563
+ * callers use this to distinguish realtime tools from other modalities.
564
+ */
565
+ declare function validateToolArguments(definition: ToolDefinition, args: unknown, toolLabel?: string): void;
566
+ /**
567
+ * Tool handlers must resolve to a plain object; arrays and primitives are not
568
+ * serializable tool outputs. Throws a plain `Error` on violation.
569
+ *
570
+ * @param toolLabel - Prefixes the thrown message (e.g. `${toolLabel} "name" ...`);
571
+ * callers use this to distinguish realtime tools from other modalities.
572
+ */
573
+ declare function assertToolResultObject(result: unknown, toolName: string, toolLabel?: string): asserts result is Record<string, unknown>;
574
+
465
575
  declare class Charivo {
466
576
  private eventBus;
467
577
  private llmManager?;
@@ -520,6 +630,10 @@ declare class Charivo {
520
630
  * Connects the STT manager to the event bus for speech recognition event emission.
521
631
  */
522
632
  private connectSTTManagerEventEmitter;
633
+ /**
634
+ * Connects the LLM manager to the event bus for tool-call event emission.
635
+ */
636
+ private connectLLMManagerEventEmitter;
523
637
  /**
524
638
  * Set the character for this Charivo instance.
525
639
  * Automatically propagates to all attached managers (LLM, Renderer).
@@ -587,4 +701,4 @@ declare class Charivo {
587
701
  private finishDispose;
588
702
  }
589
703
 
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 };
704
+ 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 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, 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,12 +146,16 @@ interface RealtimeState {
119
146
  };
120
147
  lastError: Error | null;
121
148
  }
122
- interface RealtimeToolContext {
123
- character?: Character | null;
149
+ /** @deprecated Use ToolDefinition */
150
+ interface RealtimeTool extends ToolDefinition {
151
+ }
152
+ /** @deprecated Use ToolContext (note: context.state becomes optional in the neutral contract) */
153
+ interface RealtimeToolContext extends ToolContext {
124
154
  state: RealtimeState;
125
- callId?: string;
126
155
  }
156
+ /** @deprecated Use ToolHandler (note: context.state becomes optional in the neutral contract) */
127
157
  type RealtimeToolHandler = (args: Record<string, unknown>, context: RealtimeToolContext) => Promise<Record<string, unknown>>;
158
+ /** @deprecated Use ToolRegistration (note: context.state becomes optional in the neutral contract) */
128
159
  interface RealtimeToolRegistration {
129
160
  definition: RealtimeTool;
130
161
  handler: RealtimeToolHandler;
@@ -141,17 +172,48 @@ interface LLMAdapter {
141
172
  setCharacter(character: Character): void;
142
173
  clearHistory(): void;
143
174
  }
175
+ interface LLMToolCall {
176
+ id: string;
177
+ name: string;
178
+ /** JSON-decoded; the provider/client adapter parses the raw tool-call arguments before this contract is used. */
179
+ arguments: Record<string, unknown>;
180
+ }
181
+ /**
182
+ * Role-discriminated union so protocol-invalid combinations are unrepresentable
183
+ * for typed direct callers: unknown roles, tool turns without an ID, and tool
184
+ * calls on user turns cannot be expressed.
185
+ */
186
+ type LLMMessage = {
187
+ role: "system" | "user";
188
+ content: string;
189
+ } | {
190
+ role: "assistant";
191
+ content: string;
192
+ toolCalls?: LLMToolCall[];
193
+ } | {
194
+ role: "tool";
195
+ content: string;
196
+ toolCallId: string;
197
+ };
198
+ interface LLMToolResponse {
199
+ content: string;
200
+ toolCalls?: LLMToolCall[];
201
+ }
144
202
  interface LLMProvider {
145
203
  generateResponse(messages: Array<{
146
204
  role: string;
147
205
  content: string;
148
206
  }>): Promise<string>;
207
+ /** Tool-calling variant; providers that support function calling implement this alongside generateResponse. */
208
+ generateResponseWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
149
209
  }
150
210
  interface LLMClient {
151
211
  call(messages: Array<{
152
212
  role: string;
153
213
  content: string;
154
214
  }>): Promise<string>;
215
+ /** Tool-calling variant; clients that support function calling implement this alongside call. */
216
+ callWithTools?(messages: LLMMessage[], tools: ToolDefinition[]): Promise<LLMToolResponse>;
155
217
  }
156
218
  interface LLMManager {
157
219
  setCharacter(character: Character): void;
@@ -159,6 +221,24 @@ interface LLMManager {
159
221
  clearHistory(): void;
160
222
  getHistory(): Message[];
161
223
  generateResponse(message: Message): Promise<string>;
224
+ setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
225
+ registerTool?(tool: ToolRegistration): void;
226
+ unregisterTool?(name: string): void;
227
+ getRegisteredTools?(): ToolDefinition[];
228
+ /** System-prompt-level instructions injected only when tools are registered; pass null to clear. */
229
+ setToolInstructions?(instructions: string | null): void;
230
+ }
231
+ /**
232
+ * `LLMManager` with the tool-calling members required instead of optional.
233
+ * Third-party `LLMManager` implementations may omit tool support, but the
234
+ * built-in manager returned by `createLLMManager` always provides it.
235
+ */
236
+ interface LLMManagerWithTools extends LLMManager {
237
+ setEventEmitter(eventEmitter: CharivoEventEmitter): void;
238
+ registerTool(tool: ToolRegistration): void;
239
+ unregisterTool(name: string): void;
240
+ getRegisteredTools(): ToolDefinition[];
241
+ setToolInstructions(instructions: string | null): void;
162
242
  }
163
243
  interface Renderer {
164
244
  initialize(): Promise<void>;
@@ -260,7 +340,7 @@ interface RealtimeManager {
260
340
  interrupt(): Promise<void>;
261
341
  registerTool(tool: RealtimeToolRegistration): void;
262
342
  unregisterTool(name: string): void;
263
- getRegisteredTools(): RealtimeTool[];
343
+ getRegisteredTools(): ToolDefinition[];
264
344
  setEventEmitter?(eventEmitter: CharivoEventEmitter): void;
265
345
  }
266
346
  type EventMap = {
@@ -361,14 +441,14 @@ type EventMap = {
361
441
  lastError: Error;
362
442
  };
363
443
  "realtime:usage": RealtimeUsageEvent;
364
- "realtime:expression": {
444
+ "avatar:expression": {
365
445
  expressionId: string;
366
446
  };
367
- "realtime:motion": {
447
+ "avatar:motion": {
368
448
  group: string;
369
449
  index: number;
370
450
  };
371
- "realtime:gaze": GazeCoordinates;
451
+ "avatar:gaze": GazeCoordinates;
372
452
  "realtime:text:delta": {
373
453
  text: string;
374
454
  };
@@ -462,6 +542,36 @@ interface LipSyncAnalyzer {
462
542
  }
463
543
  declare function createLipSyncAnalyzer(options: LipSyncAnalyzerOptions): LipSyncAnalyzer;
464
544
 
545
+ /**
546
+ * Shared tool validation: the single argument/result contract enforced before
547
+ * and after a tool handler runs, regardless of the modality that calls it.
548
+ *
549
+ * Errors here are plain `Error`, not a `CharivoErrorKind` variant, on purpose:
550
+ * this preserves message-string compatibility with the pre-move realtime
551
+ * validator, and no existing error kind fits schema validation.
552
+ */
553
+
554
+ /**
555
+ * Validates tool call arguments against a definition's parameter schema.
556
+ *
557
+ * Enforces only: required-key presence, `enum` membership, and each
558
+ * property's top-level `type`. Nested schemas, `additionalProperties`, and
559
+ * numeric-length constraints (`minLength`, `maximum`, etc.) are not
560
+ * validated. Throws a plain `Error` on the first violation found.
561
+ *
562
+ * @param toolLabel - Prefixes thrown messages (e.g. `${toolLabel} "name" ...`);
563
+ * callers use this to distinguish realtime tools from other modalities.
564
+ */
565
+ declare function validateToolArguments(definition: ToolDefinition, args: unknown, toolLabel?: string): void;
566
+ /**
567
+ * Tool handlers must resolve to a plain object; arrays and primitives are not
568
+ * serializable tool outputs. Throws a plain `Error` on violation.
569
+ *
570
+ * @param toolLabel - Prefixes the thrown message (e.g. `${toolLabel} "name" ...`);
571
+ * callers use this to distinguish realtime tools from other modalities.
572
+ */
573
+ declare function assertToolResultObject(result: unknown, toolName: string, toolLabel?: string): asserts result is Record<string, unknown>;
574
+
465
575
  declare class Charivo {
466
576
  private eventBus;
467
577
  private llmManager?;
@@ -520,6 +630,10 @@ declare class Charivo {
520
630
  * Connects the STT manager to the event bus for speech recognition event emission.
521
631
  */
522
632
  private connectSTTManagerEventEmitter;
633
+ /**
634
+ * Connects the LLM manager to the event bus for tool-call event emission.
635
+ */
636
+ private connectLLMManagerEventEmitter;
523
637
  /**
524
638
  * Set the character for this Charivo instance.
525
639
  * Automatically propagates to all attached managers (LLM, Renderer).
@@ -587,4 +701,4 @@ declare class Charivo {
587
701
  private finishDispose;
588
702
  }
589
703
 
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 };
704
+ 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 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, 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