@charivo/realtime 0.4.0 → 0.6.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.
Files changed (39) hide show
  1. package/README.md +20 -10
  2. package/dist/chunk-3K733UIP.mjs +58 -0
  3. package/dist/chunk-3K733UIP.mjs.map +1 -0
  4. package/dist/{chunk-DHNRDHST.mjs → chunk-WPZF3VXZ.mjs} +8 -5
  5. package/dist/chunk-WPZF3VXZ.mjs.map +1 -0
  6. package/dist/{chunk-PTFZ7CML.mjs → chunk-YLMDWMWQ.mjs} +23 -10
  7. package/dist/chunk-YLMDWMWQ.mjs.map +1 -0
  8. package/dist/{chunk-Y7JO2FFX.mjs → chunk-ZJZO4QYA.mjs} +7 -5
  9. package/dist/chunk-ZJZO4QYA.mjs.map +1 -0
  10. package/dist/index.d.mts +23 -17
  11. package/dist/index.d.ts +23 -17
  12. package/dist/index.js +129 -214
  13. package/dist/index.js.map +1 -1
  14. package/dist/index.mjs +128 -202
  15. package/dist/index.mjs.map +1 -1
  16. package/dist/openai/index.d.mts +1 -1
  17. package/dist/openai/index.d.ts +1 -1
  18. package/dist/openai/index.js +8 -5
  19. package/dist/openai/index.js.map +1 -1
  20. package/dist/openai/index.mjs +3 -3
  21. package/dist/openai-agents/index.d.mts +2 -1
  22. package/dist/openai-agents/index.d.ts +2 -1
  23. package/dist/openai-agents/index.js +22 -10
  24. package/dist/openai-agents/index.js.map +1 -1
  25. package/dist/openai-agents/index.mjs +3 -3
  26. package/dist/remote/index.d.mts +1 -1
  27. package/dist/remote/index.d.ts +1 -1
  28. package/dist/remote/index.js +58 -39
  29. package/dist/remote/index.js.map +1 -1
  30. package/dist/remote/index.mjs +37 -33
  31. package/dist/remote/index.mjs.map +1 -1
  32. package/dist/{types-bmYuc_Vs.d.mts → types-BRya38bF.d.mts} +3 -0
  33. package/dist/{types-bmYuc_Vs.d.ts → types-BRya38bF.d.ts} +3 -0
  34. package/package.json +2 -2
  35. package/dist/chunk-DHNRDHST.mjs.map +0 -1
  36. package/dist/chunk-PDODY2T7.mjs +0 -65
  37. package/dist/chunk-PDODY2T7.mjs.map +0 -1
  38. package/dist/chunk-PTFZ7CML.mjs.map +0 -1
  39. package/dist/chunk-Y7JO2FFX.mjs.map +0 -1
package/dist/index.mjs CHANGED
@@ -1,145 +1,7 @@
1
- import { SET_EXPRESSION_TOOL_DESCRIPTION, PLAY_MOTION_TOOL_DESCRIPTION, LOOK_AT_TOOL_DESCRIPTION, buildRealtimeSessionConfig } from './chunk-PDODY2T7.mjs';
2
- export { DEFAULT_REALTIME_AGENT_INSTRUCTIONS, buildRealtimeSessionConfig } from './chunk-PDODY2T7.mjs';
3
- import { subscribeBrowserLifecycle } from '@charivo/core';
1
+ import { buildRealtimeSessionConfig } from './chunk-3K733UIP.mjs';
2
+ export { DEFAULT_REALTIME_AGENT_INSTRUCTIONS, buildRealtimeSessionConfig } from './chunk-3K733UIP.mjs';
3
+ import { CharivoStateError, toCharivoError, subscribeBrowserLifecycle } from '@charivo/core';
4
4
 
5
- // src/tools.ts
6
- var MIN_GAZE = -1;
7
- var MAX_GAZE = 1;
8
- var SET_EXPRESSION_TOOL_NAME = "setExpression";
9
- var PLAY_MOTION_TOOL_NAME = "playMotion";
10
- var LOOK_AT_TOOL_NAME = "lookAt";
11
- var AVATAR_CONTROL_TOOL_NAMES = [
12
- SET_EXPRESSION_TOOL_NAME,
13
- PLAY_MOTION_TOOL_NAME,
14
- LOOK_AT_TOOL_NAME
15
- ];
16
- function createAvatarControlTools(catalog) {
17
- const tools = [];
18
- if (catalog.expressions.length > 0) {
19
- const expressionValues = [...catalog.expressions];
20
- tools.push({
21
- definition: {
22
- type: "function",
23
- name: SET_EXPRESSION_TOOL_NAME,
24
- description: SET_EXPRESSION_TOOL_DESCRIPTION,
25
- parameters: {
26
- type: "object",
27
- properties: {
28
- expressionId: {
29
- type: "string",
30
- description: "Expression ID from the loaded Live2D model.",
31
- enum: expressionValues
32
- }
33
- },
34
- required: ["expressionId"]
35
- }
36
- },
37
- async handler(args) {
38
- const expressionId = args.expressionId;
39
- if (typeof expressionId !== "string" || !expressionValues.includes(expressionId)) {
40
- throw new Error(
41
- 'setExpression requires a valid "expressionId" from the model catalog'
42
- );
43
- }
44
- return {
45
- success: true,
46
- expressionId
47
- };
48
- }
49
- });
50
- }
51
- const motionGroups = Object.keys(catalog.motions);
52
- if (motionGroups.length > 0) {
53
- tools.push({
54
- definition: {
55
- type: "function",
56
- name: PLAY_MOTION_TOOL_NAME,
57
- description: PLAY_MOTION_TOOL_DESCRIPTION,
58
- parameters: {
59
- type: "object",
60
- properties: {
61
- group: {
62
- type: "string",
63
- description: "Motion group from the loaded Live2D model.",
64
- enum: motionGroups
65
- },
66
- index: {
67
- type: "number",
68
- description: "Zero-based motion index within the selected motion group."
69
- }
70
- },
71
- required: ["group", "index"]
72
- }
73
- },
74
- async handler(args) {
75
- const group = args.group;
76
- const index = args.index;
77
- if (typeof group !== "string" || !motionGroups.includes(group)) {
78
- throw new Error(
79
- 'playMotion requires a valid "group" from the model catalog'
80
- );
81
- }
82
- if (!Number.isInteger(index)) {
83
- throw new Error('playMotion requires an integer "index"');
84
- }
85
- const count = catalog.motions[group] ?? 0;
86
- const motionIndex = index;
87
- if (motionIndex < 0 || motionIndex >= count) {
88
- throw new Error(
89
- `playMotion index ${String(motionIndex)} is out of range for group "${group}"`
90
- );
91
- }
92
- return {
93
- success: true,
94
- group,
95
- index: motionIndex
96
- };
97
- }
98
- });
99
- }
100
- tools.push({
101
- definition: {
102
- type: "function",
103
- name: LOOK_AT_TOOL_NAME,
104
- description: LOOK_AT_TOOL_DESCRIPTION,
105
- parameters: {
106
- type: "object",
107
- properties: {
108
- x: {
109
- type: "number",
110
- description: "Normalized horizontal gaze target. -1 looks left, 0 is center, 1 looks right."
111
- },
112
- y: {
113
- type: "number",
114
- description: "Normalized vertical gaze target. -1 looks down, 0 is center, 1 looks up."
115
- }
116
- },
117
- required: ["x", "y"]
118
- }
119
- },
120
- async handler(args) {
121
- const x = args.x;
122
- const y = args.y;
123
- if (typeof x !== "number" || Number.isNaN(x)) {
124
- throw new Error('lookAt requires a numeric "x"');
125
- }
126
- if (typeof y !== "number" || Number.isNaN(y)) {
127
- throw new Error('lookAt requires a numeric "y"');
128
- }
129
- return {
130
- success: true,
131
- x: clamp(x, MIN_GAZE, MAX_GAZE),
132
- y: clamp(y, MIN_GAZE, MAX_GAZE)
133
- };
134
- }
135
- });
136
- return tools;
137
- }
138
- function clamp(value, min, max) {
139
- return Math.max(min, Math.min(max, value));
140
- }
141
-
142
- // src/realtime-manager.ts
143
5
  var DEFAULT_TOOL_TIMEOUT_MS = 1e4;
144
6
  var RECONNECT_DELAYS_MS = [500, 1e3, 2e3, 4e3, 5e3];
145
7
  var RealtimeManagerImpl = class {
@@ -233,7 +95,7 @@ var RealtimeManagerImpl = class {
233
95
  }
234
96
  async startSession(config) {
235
97
  if (this.state.session.status === "active" || this.state.session.status === "starting" || this.refreshInFlight || this.reconnectInFlight) {
236
- throw new Error("Realtime session already active");
98
+ throw new CharivoStateError("Realtime session already active");
237
99
  }
238
100
  this.sessionBaseConfig = this.resolveNextSessionBaseConfig(config);
239
101
  const sessionConfig = this.buildEffectiveSessionConfig();
@@ -259,10 +121,9 @@ var RealtimeManagerImpl = class {
259
121
  void this.requestWakeLock();
260
122
  this.emitSessionStart("user");
261
123
  } catch (error) {
262
- this.finalizeFailedSession(
263
- error instanceof Error ? error : new Error(String(error))
264
- );
265
- throw error;
124
+ const typedError = toCharivoError("transport", error);
125
+ this.finalizeFailedSession(typedError);
126
+ throw typedError;
266
127
  }
267
128
  }
268
129
  updateSession(config) {
@@ -303,41 +164,45 @@ var RealtimeManagerImpl = class {
303
164
  } catch {
304
165
  }
305
166
  if (this.state.session.status === "active") {
306
- await this.performStopSession();
167
+ await this.performStopSession().catch((error) => {
168
+ throw toCharivoError("transport", error);
169
+ });
307
170
  }
308
171
  return;
309
172
  }
310
173
  if (this.state.session.status !== "active") {
311
174
  return;
312
175
  }
313
- await this.performStopSession();
176
+ await this.performStopSession().catch((error) => {
177
+ throw toCharivoError("transport", error);
178
+ });
314
179
  }
315
180
  async sendMessage(text) {
316
181
  if (this.state.session.status !== "active") {
317
- throw new Error("Realtime session not active");
182
+ throw new CharivoStateError("Realtime session not active");
318
183
  }
319
184
  if (this.state.connection !== "connected") {
320
- throw new Error("Realtime session is reconnecting");
185
+ throw new CharivoStateError("Realtime session is reconnecting");
321
186
  }
322
- await this.client.sendText(text);
187
+ await this.client.sendText(text).catch((error) => Promise.reject(toCharivoError("transport", error)));
323
188
  }
324
189
  async sendAudioChunk(audio) {
325
190
  if (this.state.session.status !== "active") {
326
- throw new Error("Realtime session not active");
191
+ throw new CharivoStateError("Realtime session not active");
327
192
  }
328
193
  if (this.state.connection !== "connected") {
329
- throw new Error("Realtime session is reconnecting");
194
+ throw new CharivoStateError("Realtime session is reconnecting");
330
195
  }
331
- await this.client.sendAudio(audio);
196
+ await this.client.sendAudio(audio).catch((error) => Promise.reject(toCharivoError("transport", error)));
332
197
  }
333
198
  async interrupt() {
334
199
  if (this.state.session.status !== "active") {
335
- throw new Error("Realtime session not active");
200
+ throw new CharivoStateError("Realtime session not active");
336
201
  }
337
202
  if (this.state.connection !== "connected") {
338
- throw new Error("Realtime session is reconnecting");
203
+ throw new CharivoStateError("Realtime session is reconnecting");
339
204
  }
340
- await this.client.interrupt();
205
+ await this.client.interrupt().catch((error) => Promise.reject(toCharivoError("transport", error)));
341
206
  this.state = {
342
207
  ...this.state,
343
208
  response: {
@@ -411,6 +276,7 @@ var RealtimeManagerImpl = class {
411
276
  return;
412
277
  }
413
278
  const text = event.text || this.state.response.text;
279
+ this.emitUsageEvent(event);
414
280
  this.state = {
415
281
  ...this.state,
416
282
  response: {
@@ -485,14 +351,22 @@ var RealtimeManagerImpl = class {
485
351
  return;
486
352
  }
487
353
  try {
354
+ this.log("debug", "Realtime tool execution started", {
355
+ name: event.name,
356
+ callId: event.callId
357
+ });
488
358
  const output = await this.runToolHandler(tool, event);
489
359
  await this.client.sendToolResult(event.callId, output);
490
- this.postProcessToolResult(event.name, output);
491
360
  this.eventEmitter?.emit("realtime:tool:result", {
492
361
  name: event.name,
493
362
  output,
494
363
  callId: event.callId
495
364
  });
365
+ this.projectToolResult(event.name, output, event.callId);
366
+ this.log("info", "Realtime tool execution succeeded", {
367
+ name: event.name,
368
+ callId: event.callId
369
+ });
496
370
  } catch (error) {
497
371
  await this.handleToolExecutionFailure(
498
372
  event.name,
@@ -531,39 +405,33 @@ var RealtimeManagerImpl = class {
531
405
  );
532
406
  }
533
407
  }
534
- postProcessToolResult(name, output) {
535
- switch (name) {
536
- case SET_EXPRESSION_TOOL_NAME: {
537
- const expressionId = output.expressionId;
538
- if (typeof expressionId === "string") {
539
- this.eventEmitter?.emit("realtime:expression", { expressionId });
540
- }
541
- return;
542
- }
543
- case PLAY_MOTION_TOOL_NAME: {
544
- const group = output.group;
545
- const index = output.index;
546
- if (typeof group === "string" && Number.isInteger(index)) {
547
- const motionIndex = index;
548
- this.eventEmitter?.emit("realtime:motion", {
549
- group,
550
- index: motionIndex
551
- });
552
- }
553
- return;
554
- }
555
- case LOOK_AT_TOOL_NAME: {
556
- const coords = readGazeCoordinates(output);
557
- if (coords) {
558
- this.eventEmitter?.emit("realtime:gaze", coords);
559
- }
560
- return;
408
+ projectToolResult(name, output, callId) {
409
+ for (const projector of this.options.resultProjectors ?? []) {
410
+ try {
411
+ projector({
412
+ name,
413
+ output,
414
+ callId,
415
+ emit: (event, payload) => {
416
+ this.eventEmitter?.emit(event, payload);
417
+ }
418
+ });
419
+ } catch (error) {
420
+ const projectorError = error instanceof Error ? error : new Error(String(error));
421
+ this.log("warn", "Realtime result projector failed", {
422
+ name,
423
+ callId,
424
+ error: projectorError.message
425
+ });
561
426
  }
562
- default:
563
- return;
564
427
  }
565
428
  }
566
429
  emitToolError(name, error, callId) {
430
+ this.log("warn", "Realtime tool execution failed", {
431
+ name,
432
+ callId,
433
+ error: error.message
434
+ });
567
435
  this.eventEmitter?.emit("realtime:tool:error", {
568
436
  name,
569
437
  error,
@@ -611,6 +479,10 @@ var RealtimeManagerImpl = class {
611
479
  };
612
480
  }
613
481
  this.emitState();
482
+ this.log("warn", "Realtime reconnect started", {
483
+ cause,
484
+ connection: this.state.connection
485
+ });
614
486
  this.reconnectInFlight = this.runReconnectLoop(reconnectToken, cause).catch((reconnectError) => {
615
487
  this.finalizeFailedSession(reconnectError);
616
488
  }).finally(() => {
@@ -631,6 +503,11 @@ var RealtimeManagerImpl = class {
631
503
  delayMs,
632
504
  cause
633
505
  });
506
+ this.log("info", "Realtime reconnect attempt", {
507
+ attempt,
508
+ delayMs,
509
+ cause
510
+ });
634
511
  await delay(delayMs);
635
512
  if (!this.isReconnectTokenActive(reconnectToken)) {
636
513
  return;
@@ -659,6 +536,11 @@ var RealtimeManagerImpl = class {
659
536
  totalMs: Date.now() - startedAt,
660
537
  cause
661
538
  });
539
+ this.log("info", "Realtime reconnect succeeded", {
540
+ attempts: attempt,
541
+ totalMs: Date.now() - startedAt,
542
+ cause
543
+ });
662
544
  return;
663
545
  } catch (error) {
664
546
  lastError = error instanceof Error ? error : new Error(String(error));
@@ -679,6 +561,12 @@ var RealtimeManagerImpl = class {
679
561
  cause,
680
562
  lastError
681
563
  });
564
+ this.log("error", "Realtime reconnect exhausted", {
565
+ attempts: RECONNECT_DELAYS_MS.length,
566
+ totalMs: Date.now() - startedAt,
567
+ cause,
568
+ error: lastError.message
569
+ });
682
570
  throw lastError;
683
571
  }
684
572
  cancelReconnectLoop() {
@@ -695,14 +583,19 @@ var RealtimeManagerImpl = class {
695
583
  });
696
584
  }
697
585
  applyError(error, connection) {
586
+ const typedError = toCharivoError("transport", error);
698
587
  this.emitAudioEnd();
699
588
  this.state = {
700
589
  ...this.state,
701
590
  connection,
702
- lastError: error
591
+ lastError: typedError
703
592
  };
704
- this.eventEmitter?.emit("realtime:error", { error });
593
+ this.eventEmitter?.emit("realtime:error", { error: typedError });
705
594
  this.emitState();
595
+ this.log("error", "Realtime transport error surfaced", {
596
+ connection,
597
+ error: typedError.message
598
+ });
706
599
  }
707
600
  emitAudioStart() {
708
601
  if (this.isAudioPlaybackActive) {
@@ -848,32 +741,52 @@ var RealtimeManagerImpl = class {
848
741
  lastError: null
849
742
  };
850
743
  this.emitState();
744
+ this.log("debug", "Realtime session patch started", {
745
+ voice: sessionConfig.voice,
746
+ model: sessionConfig.model
747
+ });
851
748
  try {
852
749
  await this.client.updateSession(sessionConfig);
853
750
  if (this.stopRequestedDuringRefresh) {
854
751
  return;
855
752
  }
856
753
  this.commitPatchedSession(sessionConfig);
754
+ this.log("info", "Realtime session patch succeeded", {
755
+ voice: sessionConfig.voice,
756
+ model: sessionConfig.model
757
+ });
857
758
  } catch (error) {
858
759
  const refreshError = error instanceof Error ? error : new Error(String(error));
760
+ const typedRefreshError = toCharivoError("transport", refreshError);
859
761
  if (this.isRecoveringConnection) {
860
- throw refreshError;
762
+ throw typedRefreshError;
861
763
  }
862
- if (this.state.lastError !== refreshError) {
863
- this.applyError(refreshError, "connected");
764
+ if (this.state.lastError !== typedRefreshError && this.state.lastError?.cause !== refreshError) {
765
+ this.applyError(typedRefreshError, "connected");
864
766
  }
865
- throw refreshError;
767
+ this.log("error", "Realtime session patch failed", {
768
+ error: typedRefreshError.message
769
+ });
770
+ throw typedRefreshError;
866
771
  } finally {
867
772
  this.isRefreshingSession = false;
868
773
  }
869
774
  }
870
775
  emitSessionStart(reason, state = this.getState()) {
776
+ this.log("info", "Realtime session started", {
777
+ reason,
778
+ connection: state.connection
779
+ });
871
780
  this.eventEmitter?.emit("realtime:session:start", {
872
781
  state,
873
782
  reason
874
783
  });
875
784
  }
876
785
  emitSessionEnd(reason, state = this.getState()) {
786
+ this.log("info", "Realtime session ended", {
787
+ reason,
788
+ connection: state.connection
789
+ });
877
790
  this.eventEmitter?.emit("realtime:session:end", {
878
791
  state,
879
792
  reason
@@ -901,6 +814,9 @@ var RealtimeManagerImpl = class {
901
814
  };
902
815
  this.eventEmitter?.emit("realtime:error", { error });
903
816
  this.emitState();
817
+ this.log("error", "Realtime session failed", {
818
+ error: error.message
819
+ });
904
820
  }
905
821
  finalizeStoppedSession(emitSessionEnd, reason) {
906
822
  this.cancelReconnectLoop();
@@ -927,15 +843,25 @@ var RealtimeManagerImpl = class {
927
843
  this.emitSessionEnd(reason);
928
844
  }
929
845
  }
930
- };
931
- function readGazeCoordinates(output) {
932
- const x = output.x;
933
- const y = output.y;
934
- if (typeof x !== "number" || typeof y !== "number") {
935
- return null;
846
+ emitUsageEvent(event) {
847
+ if (!event.usage) {
848
+ return;
849
+ }
850
+ const payload = {
851
+ usage: event.usage,
852
+ model: event.model,
853
+ responseId: event.responseId
854
+ };
855
+ this.eventEmitter?.emit("realtime:usage", payload);
856
+ this.log("debug", "Realtime usage reported", {
857
+ model: event.model,
858
+ responseId: event.responseId
859
+ });
936
860
  }
937
- return { x, y };
938
- }
861
+ log(level, message, context) {
862
+ this.options.logger?.[level]?.(message, context);
863
+ }
864
+ };
939
865
  function createRealtimeManager(client, options) {
940
866
  return new RealtimeManagerImpl(client, options);
941
867
  }
@@ -1000,6 +926,6 @@ function delay(ms) {
1000
926
  });
1001
927
  }
1002
928
 
1003
- export { AVATAR_CONTROL_TOOL_NAMES, LOOK_AT_TOOL_NAME, PLAY_MOTION_TOOL_NAME, RealtimeManagerImpl, SET_EXPRESSION_TOOL_NAME, createAvatarControlTools, createRealtimeManager };
929
+ export { RealtimeManagerImpl, createRealtimeManager };
1004
930
  //# sourceMappingURL=index.mjs.map
1005
931
  //# sourceMappingURL=index.mjs.map