@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/README.md +48 -4
- package/dist/index.cjs +99 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +118 -19
- package/dist/index.d.ts +118 -19
- package/dist/index.js +98 -1
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
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
|
|
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?:
|
|
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:
|
|
326
|
+
registerTool(tool: ToolRegistration): void;
|
|
262
327
|
unregisterTool(name: string): void;
|
|
263
|
-
getRegisteredTools():
|
|
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
|
-
"
|
|
429
|
+
"avatar:expression": {
|
|
365
430
|
expressionId: string;
|
|
366
431
|
};
|
|
367
|
-
"
|
|
432
|
+
"avatar:motion": {
|
|
368
433
|
group: string;
|
|
369
434
|
index: number;
|
|
370
435
|
};
|
|
371
|
-
"
|
|
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
|
|
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
|
|
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?:
|
|
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:
|
|
326
|
+
registerTool(tool: ToolRegistration): void;
|
|
262
327
|
unregisterTool(name: string): void;
|
|
263
|
-
getRegisteredTools():
|
|
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
|
-
"
|
|
429
|
+
"avatar:expression": {
|
|
365
430
|
expressionId: string;
|
|
366
431
|
};
|
|
367
|
-
"
|
|
432
|
+
"avatar:motion": {
|
|
368
433
|
group: string;
|
|
369
434
|
index: number;
|
|
370
435
|
};
|
|
371
|
-
"
|
|
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
|
|
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
|