@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/README.md +56 -4
- package/dist/index.cjs +99 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +124 -10
- package/dist/index.d.ts +124 -10
- 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,12 +146,16 @@ interface RealtimeState {
|
|
|
119
146
|
};
|
|
120
147
|
lastError: Error | null;
|
|
121
148
|
}
|
|
122
|
-
|
|
123
|
-
|
|
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():
|
|
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
|
-
"
|
|
444
|
+
"avatar:expression": {
|
|
365
445
|
expressionId: string;
|
|
366
446
|
};
|
|
367
|
-
"
|
|
447
|
+
"avatar:motion": {
|
|
368
448
|
group: string;
|
|
369
449
|
index: number;
|
|
370
450
|
};
|
|
371
|
-
"
|
|
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
|
|
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,12 +146,16 @@ interface RealtimeState {
|
|
|
119
146
|
};
|
|
120
147
|
lastError: Error | null;
|
|
121
148
|
}
|
|
122
|
-
|
|
123
|
-
|
|
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():
|
|
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
|
-
"
|
|
444
|
+
"avatar:expression": {
|
|
365
445
|
expressionId: string;
|
|
366
446
|
};
|
|
367
|
-
"
|
|
447
|
+
"avatar:motion": {
|
|
368
448
|
group: string;
|
|
369
449
|
index: number;
|
|
370
450
|
};
|
|
371
|
-
"
|
|
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
|