@pollen-robotics/reachy-mini-sdk 1.13.0-dev.0.main.e4f3403 → 1.13.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 (64) hide show
  1. package/APP_CREATION_GUIDE.md +1 -1
  2. package/dist/animation/safe-return.d.ts +6 -4
  3. package/dist/animation/safe-return.d.ts.map +1 -1
  4. package/dist/animation/safe-return.js +12 -4
  5. package/dist/animation/safe-return.js.map +1 -1
  6. package/dist/lib/app-dx.test.d.ts +2 -0
  7. package/dist/lib/app-dx.test.d.ts.map +1 -0
  8. package/dist/lib/app-dx.test.js +100 -0
  9. package/dist/lib/app-dx.test.js.map +1 -0
  10. package/dist/lib/central-timeouts.test.d.ts +2 -0
  11. package/dist/lib/central-timeouts.test.d.ts.map +1 -0
  12. package/dist/lib/central-timeouts.test.js +101 -0
  13. package/dist/lib/central-timeouts.test.js.map +1 -0
  14. package/dist/lib/dial-races.test.d.ts +2 -0
  15. package/dist/lib/dial-races.test.d.ts.map +1 -0
  16. package/dist/lib/dial-races.test.js +215 -0
  17. package/dist/lib/dial-races.test.js.map +1 -0
  18. package/dist/lib/end-session-id.test.d.ts +2 -0
  19. package/dist/lib/end-session-id.test.d.ts.map +1 -0
  20. package/dist/lib/end-session-id.test.js +113 -0
  21. package/dist/lib/end-session-id.test.js.map +1 -0
  22. package/dist/lib/ice-grace.test.js +1 -0
  23. package/dist/lib/ice-grace.test.js.map +1 -1
  24. package/dist/lib/math.d.ts +3 -2
  25. package/dist/lib/math.d.ts.map +1 -1
  26. package/dist/lib/math.js +6 -2
  27. package/dist/lib/math.js.map +1 -1
  28. package/dist/lib/peer-link-liveness.test.d.ts +2 -0
  29. package/dist/lib/peer-link-liveness.test.d.ts.map +1 -0
  30. package/dist/lib/peer-link-liveness.test.js +97 -0
  31. package/dist/lib/peer-link-liveness.test.js.map +1 -0
  32. package/dist/lib/pending-replies.d.ts +3 -1
  33. package/dist/lib/pending-replies.d.ts.map +1 -1
  34. package/dist/lib/pending-replies.js.map +1 -1
  35. package/dist/lib/reachy-mini.d.ts +99 -1
  36. package/dist/lib/reachy-mini.d.ts.map +1 -1
  37. package/dist/lib/reachy-mini.js +491 -26
  38. package/dist/lib/reachy-mini.js.map +1 -1
  39. package/dist/lib/redial.test.js +59 -0
  40. package/dist/lib/redial.test.js.map +1 -1
  41. package/dist/lib/session-supervisor.d.ts +10 -0
  42. package/dist/lib/session-supervisor.d.ts.map +1 -1
  43. package/dist/lib/session-supervisor.js +12 -1
  44. package/dist/lib/session-supervisor.js.map +1 -1
  45. package/dist/lib/signaling-stall.test.d.ts +2 -0
  46. package/dist/lib/signaling-stall.test.d.ts.map +1 -0
  47. package/dist/lib/signaling-stall.test.js +64 -0
  48. package/dist/lib/signaling-stall.test.js.map +1 -0
  49. package/dist/lib/types.d.ts +50 -3
  50. package/dist/lib/types.d.ts.map +1 -1
  51. package/dist/lib/version.d.ts +1 -1
  52. package/dist/lib/version.d.ts.map +1 -1
  53. package/dist/lib/version.js +1 -1
  54. package/dist/lib/version.js.map +1 -1
  55. package/dist/reachy-mini-sdk.d.ts +1 -1
  56. package/dist/reachy-mini-sdk.d.ts.map +1 -1
  57. package/dist/reachy-mini-sdk.js.map +1 -1
  58. package/host/dist/chunks/{centralRest-K3a9U_Sk.js → centralRest-DR0Wx46x.js} +752 -508
  59. package/host/dist/chunks/{index-B79tSfbK.js → index-B14lPGN5.js} +1 -1
  60. package/host/dist/chunks/{mountHost-CMP4uYnZ.js → mountHost-CEY42tfj.js} +1 -1
  61. package/host/dist/entry/auto.js +2 -2
  62. package/host/dist/entry/embed.js +2 -2
  63. package/host/dist/index.js +3 -3
  64. package/package.json +1 -1
@@ -32,6 +32,44 @@ const log = createLogger('sdk');
32
32
  * flip it back and forth.
33
33
  */
34
34
  const POSE_STREAM_FRESH_MS = 750;
35
+ /**
36
+ * A streaming peer link counts as live when the robot was heard from this
37
+ * recently (it answers the ~500 ms state poll). Past it, a reason-less
38
+ * endSession from central is believed again.
39
+ */
40
+ const PEER_LINK_LIVE_MS = 2500;
41
+ /** How many closed session ids to remember, to ignore their late endSession. */
42
+ const RETIRED_SESSIONS_MAX = 8;
43
+ /**
44
+ * Central pings an idle signaling stream every 30 s. Silence well past that
45
+ * means the stream stalled without closing (seen after a phone screen lock or
46
+ * a network drop): it would never deliver again while our POSTs still go out,
47
+ * so every startSession times out unanswered. Abort it and reconnect instead.
48
+ */
49
+ const SIGNALING_STALL_MS = 75_000;
50
+ /** A stall timer this late means a frozen page; re-judge after the grace. */
51
+ const SIGNALING_FROZEN_SLACK_MS = 15_000;
52
+ const SIGNALING_FROZEN_GRACE_MS = 5_000;
53
+ /**
54
+ * Every call to central is bounded: a path that stalls without failing
55
+ * (lossy Wi-Fi, a half-dead connection) would otherwise hang a re-dial,
56
+ * a session start or a stop for as long as the browser's TCP timeout.
57
+ * `/send` and the robot list get CENTRAL_REQUEST_TIMEOUT_MS; opening the
58
+ * event stream gets SIGNALING_OPEN_TIMEOUT_MS for the response, then
59
+ * SIGNALING_WELCOME_TIMEOUT_MS for central's `welcome`.
60
+ */
61
+ const CENTRAL_REQUEST_TIMEOUT_MS = 10_000;
62
+ const SIGNALING_OPEN_TIMEOUT_MS = 15_000;
63
+ const SIGNALING_WELCOME_TIMEOUT_MS = 15_000;
64
+ /**
65
+ * A robot's stable identity across central re-registrations (its peer id
66
+ * changes each time): `install_id`, else `hardware_id`. Never the name,
67
+ * which users often leave at the default and share across robots.
68
+ */
69
+ function robotIdentity(r) {
70
+ const meta = r?.meta;
71
+ return meta?.install_id ?? meta?.hardware_id ?? null;
72
+ }
35
73
  /**
36
74
  * Upper bound on how long `ensureAwake()` waits for the wake trajectory to
37
75
  * complete. The emote itself takes ~2-3 s on hardware; the extra headroom
@@ -73,14 +111,32 @@ export class ReachyMini extends EventTarget {
73
111
  _tokenExpires = null;
74
112
  // ─── Signaling ───────────────────────────────────────────────────────
75
113
  _sseAbortController = null;
114
+ /** The open in flight (fetch → welcome): a second open joins it. */
115
+ _signalingOpening = null;
116
+ _signalingOpeningController = null;
76
117
  // ─── WebRTC ──────────────────────────────────────────────────────────
77
118
  _pc = null;
78
119
  _dc = null;
79
120
  _sessionId = null;
121
+ /** Our session after central dropped it while the peer link lived on. */
122
+ _staleSessionId = null;
123
+ /** Sessions we closed: a late endSession for one must not end the next. */
124
+ _retiredSessionIds = new Set();
80
125
  _selectedRobotId = null;
81
126
  _pendingRemoteIce = [];
82
127
  // ─── Audio ───────────────────────────────────────────────────────────
83
128
  _micStream = null;
129
+ _robotAudioTrack = null;
130
+ _outgoingAudioTrack = null;
131
+ /** Context driving the silent placeholder track; closed with it. */
132
+ _micCtx = null;
133
+ /** Robot dialed last and its stable identity (see `_redialTargetResolver`). */
134
+ _dialedRobotId = null;
135
+ _dialedRobotIdentity = null;
136
+ /** Signaling (SSE) dropped while streaming; reconnecting in the background. */
137
+ _signalingDown = false;
138
+ _signalingRetryTimer = null;
139
+ _signalingRetryAttempt = 0;
84
140
  _micMuted = true;
85
141
  _audioMuted = true;
86
142
  _micSupported = false;
@@ -133,7 +189,7 @@ export class ReachyMini extends EventTarget {
133
189
  hasPc: () => !!this._pc,
134
190
  isStreaming: () => this._state === 'streaming',
135
191
  isMidSetup: () => !!(this._sessionResolve || this._sessionReject),
136
- isSignalingDown: () => this._state === 'disconnected',
192
+ isSignalingDown: () => this._state === 'disconnected' || this._signalingDown,
137
193
  selectedRobotId: () => this._selectedRobotId,
138
194
  rejectPendingSession: (err) => {
139
195
  if (!this._sessionReject)
@@ -148,6 +204,7 @@ export class ReachyMini extends EventTarget {
148
204
  // The private dial skips the public startSession()'s
149
205
  // cancelRedial, so the loop's own attempts don't cancel it.
150
206
  dial: (robotId) => this._startSessionInternal(robotId),
207
+ redialTargetResolver: (robotId) => this._redialTargetResolver(robotId),
151
208
  teardownForRedial: () => this._teardownForRedial(),
152
209
  nudgeState: () => { this.requestState(); },
153
210
  emit: (name, detail) => this._emit(name, detail),
@@ -171,6 +228,12 @@ export class ReachyMini extends EventTarget {
171
228
  * use — never capture it across ticks.
172
229
  */
173
230
  get peerConnection() { return this._pc; }
231
+ /**
232
+ * The robot's microphone as a live audio track, or `null` until the
233
+ * session's audio arrives (see the `audioTrack` event). Feed it to Web
234
+ * Audio, `MediaRecorder` or `SpeechRecognition.start(track)`.
235
+ */
236
+ get robotAudioTrack() { return this._robotAudioTrack; }
174
237
  /**
175
238
  * Build version of this SDK (npm package `version`), injected from
176
239
  * package.json at build time. This is the JS SDK's OWN version and is
@@ -283,20 +346,58 @@ export class ReachyMini extends EventTarget {
283
346
  this._token = token;
284
347
  if (!this._token)
285
348
  throw new Error('No token — call authenticate() first or pass a token');
349
+ return this._openSignaling();
350
+ }
351
+ /**
352
+ * Open the signaling SSE stream and resolve on central's `welcome`.
353
+ * Shared by `connect()` and the background reconnect that runs while a
354
+ * session keeps streaming without signaling (see `signalingLost`).
355
+ */
356
+ _openSignaling() {
357
+ // Two opens at once (an app reconnect racing the supervisor's) would
358
+ // run two streams, each handling every message: join the first.
359
+ // Never join an open that was aborted on purpose (disconnect(), a
360
+ // dropped background retry): it is about to reject, and the caller
361
+ // asked for a fresh connection.
362
+ if (this._signalingOpening && !this._signalingOpeningController?.signal.aborted) {
363
+ return this._signalingOpening;
364
+ }
365
+ const opening = this._openSignalingOnce().finally(() => {
366
+ if (this._signalingOpening === opening) {
367
+ this._signalingOpening = null;
368
+ this._signalingOpeningController = null;
369
+ }
370
+ });
371
+ this._signalingOpening = opening;
372
+ return opening;
373
+ }
374
+ async _openSignalingOnce() {
286
375
  this._sseAbortController = new AbortController();
376
+ this._signalingOpeningController = this._sseAbortController;
377
+ const openController = this._sseAbortController;
378
+ let openTimedOut = false;
379
+ const openTimer = setTimeout(() => {
380
+ openTimedOut = true;
381
+ openController.abort();
382
+ }, SIGNALING_OPEN_TIMEOUT_MS);
287
383
  let res;
288
384
  try {
289
385
  res = await fetch(`${this._signalingUrl}/events`, {
290
- signal: this._sseAbortController.signal,
386
+ signal: openController.signal,
291
387
  headers: { 'Authorization': `Bearer ${this._token}` },
292
388
  });
293
389
  }
294
390
  catch (e) {
295
- this._sseAbortController = null;
296
- throw e;
391
+ if (this._sseAbortController === openController)
392
+ this._sseAbortController = null;
393
+ throw openTimedOut ? new Error('signaling: no answer from central') : e;
394
+ }
395
+ finally {
396
+ clearTimeout(openTimer);
297
397
  }
298
398
  if (!res.ok) {
299
- this._sseAbortController = null;
399
+ if (this._sseAbortController === openController)
400
+ this._sseAbortController = null;
300
401
  throw new Error(`HTTP ${res.status}`);
301
402
  }
302
403
  return new Promise((resolve, reject) => {
@@ -304,12 +405,45 @@ export class ReachyMini extends EventTarget {
304
405
  const reader = res.body.getReader();
305
406
  const decoder = new TextDecoder();
306
407
  let buffer = '';
408
+ const controller = openController;
409
+ // Central greets every stream at once: no welcome means a stream
410
+ // that will never work, and connect() must not wait on it.
411
+ let welcomeTimedOut = false;
412
+ const welcomeTimer = setTimeout(() => {
413
+ if (welcomed)
414
+ return;
415
+ welcomeTimedOut = true;
416
+ log.warn('signaling: no welcome from central; aborting the stream');
417
+ controller?.abort();
418
+ }, SIGNALING_WELCOME_TIMEOUT_MS);
419
+ let stallTimer = null;
420
+ const armStallTimer = (delayMs = SIGNALING_STALL_MS) => {
421
+ if (stallTimer !== null)
422
+ clearTimeout(stallTimer);
423
+ const armedAt = Date.now();
424
+ stallTimer = setTimeout(() => {
425
+ // Fired far later than asked: the page was frozen (screen
426
+ // lock, background tab), and bytes buffered meanwhile have
427
+ // not been read yet. Give them a moment before judging.
428
+ // While timers stay heavily throttled (hidden tab) this can
429
+ // re-arm repeatedly; a dead stream is then aborted within
430
+ // the grace once the page runs normally again.
431
+ if (Date.now() - armedAt > delayMs + SIGNALING_FROZEN_SLACK_MS) {
432
+ armStallTimer(SIGNALING_FROZEN_GRACE_MS);
433
+ return;
434
+ }
435
+ log.warn('signaling stream silent for too long; reconnecting');
436
+ controller?.abort();
437
+ }, delayMs);
438
+ };
307
439
  const readLoop = async () => {
308
440
  try {
441
+ armStallTimer();
309
442
  while (true) {
310
443
  const { done, value } = await reader.read();
311
444
  if (done)
312
445
  break;
446
+ armStallTimer();
313
447
  buffer += decoder.decode(value, { stream: true });
314
448
  const lines = buffer.split('\n');
315
449
  buffer = lines.pop() ?? '';
@@ -320,13 +454,26 @@ export class ReachyMini extends EventTarget {
320
454
  const msg = JSON.parse(line.slice(5).trim());
321
455
  if (!welcomed && msg.type === 'welcome' && msg.peerId) {
322
456
  welcomed = true;
323
- this._state = 'connected';
457
+ clearTimeout(welcomeTimer);
458
+ // A background reconnect lands mid-session:
459
+ // the session state is left alone.
460
+ const restoring = this._state !== 'disconnected';
461
+ if (!restoring)
462
+ this._state = 'connected';
463
+ this._signalingDown = false;
464
+ this._signalingRetryAttempt = 0;
324
465
  await this._sendToServer({
325
466
  type: 'setPeerStatus',
326
467
  roles: ['listener'],
327
468
  meta: { name: this._appName },
328
469
  });
329
- this._emit('connected', { peerId: msg.peerId });
470
+ if (restoring) {
471
+ log.info('signaling restored while streaming');
472
+ this._emit('signalingRestored', { peerId: msg.peerId });
473
+ }
474
+ else {
475
+ this._emit('connected', { peerId: msg.peerId });
476
+ }
330
477
  resolve();
331
478
  }
332
479
  this._handleSignalingMessage(msg);
@@ -340,11 +487,29 @@ export class ReachyMini extends EventTarget {
340
487
  this._emit('error', { source: 'signaling', error: e });
341
488
  }
342
489
  if (!welcomed) {
343
- reject(e);
490
+ reject(welcomeTimedOut ? new Error('signaling: no welcome from central') : e);
344
491
  return;
345
492
  }
346
493
  }
347
- if (this._state !== 'disconnected') {
494
+ finally {
495
+ clearTimeout(welcomeTimer);
496
+ if (stallTimer !== null)
497
+ clearTimeout(stallTimer);
498
+ }
499
+ if (this._state === 'streaming') {
500
+ // Signaling is only needed to SET UP a session: a live
501
+ // one is peer-to-peer. Keep it, reconnect in the
502
+ // background (same token: central's reconnect grace
503
+ // keeps our peer id).
504
+ this._sseAbortController = null;
505
+ if (!this._signalingDown) {
506
+ this._signalingDown = true;
507
+ log.warn('signaling lost while streaming; keeping the session');
508
+ this._emit('signalingLost', { reason: 'SSE closed' });
509
+ }
510
+ this._scheduleSignalingRetry();
511
+ }
512
+ else if (this._state !== 'disconnected') {
348
513
  this._state = 'disconnected';
349
514
  this._emit('disconnected', { reason: 'SSE closed' });
350
515
  }
@@ -427,9 +592,12 @@ export class ReachyMini extends EventTarget {
427
592
  }
428
593
  }
429
594
  async _fetchOwnedRobots({ filterBusy = true } = {}) {
595
+ const controller = new AbortController();
596
+ const timer = setTimeout(() => controller.abort(), CENTRAL_REQUEST_TIMEOUT_MS);
430
597
  try {
431
598
  const res = await fetch(`${this._signalingUrl}/api/robot-status`, {
432
599
  headers: { 'Authorization': `Bearer ${this._token}` },
600
+ signal: controller.signal,
433
601
  });
434
602
  if (!res.ok)
435
603
  throw new Error(`HTTP ${res.status}`);
@@ -461,6 +629,9 @@ export class ReachyMini extends EventTarget {
461
629
  lastSeenAgeSeconds: null,
462
630
  }));
463
631
  }
632
+ finally {
633
+ clearTimeout(timer);
634
+ }
464
635
  }
465
636
  _waitForRobotInList(robotId, timeoutMs) {
466
637
  if (this._robots?.find((r) => r.id === robotId))
@@ -492,6 +663,22 @@ export class ReachyMini extends EventTarget {
492
663
  if (this._state !== 'connected')
493
664
  throw new Error('Not connected');
494
665
  this._selectedRobotId = robotId;
666
+ // Remember who this is while it is surely listed (see
667
+ // `_redialTargetResolver`). Kept across redial attempts that dial
668
+ // the same robot under a fresh id.
669
+ const dialedIdentity = robotIdentity(this._robots.find((r) => r.id === robotId));
670
+ if (dialedIdentity)
671
+ this._dialedRobotIdentity = dialedIdentity;
672
+ else if (this._dialedRobotId !== robotId)
673
+ this._dialedRobotIdentity = null;
674
+ this._dialedRobotId = robotId;
675
+ // A new dial owns no session id until central's reply: anything
676
+ // left over from an earlier attempt is retired, so its late
677
+ // endSession cannot end this one, nor make us drop this one's own.
678
+ this._retireSession(this._sessionId);
679
+ this._sessionId = null;
680
+ this._retireSession(this._staleSessionId);
681
+ this._staleSessionId = null;
495
682
  this._iceConnected = false;
496
683
  this._dcOpen = false;
497
684
  this._micSupported = false;
@@ -514,7 +701,11 @@ export class ReachyMini extends EventTarget {
514
701
  const Ctx = w.AudioContext ?? w.webkitAudioContext;
515
702
  if (!Ctx)
516
703
  throw new Error('AudioContext not supported');
704
+ // A dial can follow a teardown that skipped the release
705
+ // (e.g. a rejected attempt): never keep two contexts alive.
706
+ this._releaseMicPlaceholder();
517
707
  const ctx = new Ctx();
708
+ this._micCtx = ctx;
518
709
  const dst = ctx.createMediaStreamDestination();
519
710
  const osc = ctx.createOscillator();
520
711
  const gain = ctx.createGain();
@@ -554,6 +745,10 @@ export class ReachyMini extends EventTarget {
554
745
  catch { /* ignore */ }
555
746
  this._emit('videoTrack', { track: e.track, stream: e.streams[0] });
556
747
  }
748
+ else if (e.track.kind === 'audio') {
749
+ this._robotAudioTrack = e.track;
750
+ this._emit('audioTrack', { track: e.track, stream: e.streams[0] });
751
+ }
557
752
  };
558
753
  this._pc.onicecandidate = async (e) => {
559
754
  if (e.candidate && this._sessionId) {
@@ -635,14 +830,61 @@ export class ReachyMini extends EventTarget {
635
830
  if (msg)
636
831
  this._handleRobotMessage(msg);
637
832
  };
833
+ // The robot ending the session closes the channel in an
834
+ // orderly way while ICE is still up: that, not central's
835
+ // signaling, is how a live session learns it is over. A dead
836
+ // network doesn't close it (ICE fails first and the
837
+ // supervisor re-dials), nor does our own teardown (the
838
+ // channel is no longer `this._dc` by then).
839
+ ch.onclose = () => {
840
+ if (this._dc !== ch || this._state !== 'streaming')
841
+ return;
842
+ const ice = this._pc?.iceConnectionState;
843
+ if (ice !== 'connected' && ice !== 'completed')
844
+ return;
845
+ log.info('robot closed the session');
846
+ this._endedByRobot('remote_end', null);
847
+ };
638
848
  };
849
+ const dialPc = this._pc;
639
850
  this._sendToServer({ type: 'startSession', peerId: robotId }).then((r) => {
851
+ if (this._pc !== dialPc) {
852
+ // This dial was abandoned (stopped, rejected, re-dialed)
853
+ // before central answered: the reply is not the current
854
+ // dial's. Retire its id and free the robot-side slot.
855
+ if (r?.sessionId) {
856
+ // Should a stray frame have made it current, drop it too.
857
+ if (this._sessionId === r.sessionId)
858
+ this._sessionId = null;
859
+ this._retireSession(r.sessionId);
860
+ void this._sendToServer({ type: 'endSession', sessionId: r.sessionId, reason: 'client_stop' });
861
+ }
862
+ return;
863
+ }
640
864
  if (r?.type === 'sessionRejected') {
641
865
  this._failSessionRejected(r);
642
866
  return;
643
867
  }
644
- if (r?.sessionId)
868
+ if (r?.sessionId) {
645
869
  this._sessionId = r.sessionId;
870
+ return;
871
+ }
872
+ // Central never took the request (unreachable, timed out,
873
+ // refused): no offer will come, so fail this dial now rather
874
+ // than leave it to the caller's timeout. Only if it is still
875
+ // the pending dial.
876
+ if (r === null && this._sessionReject) {
877
+ const sessionId = this._closeTransport(new Error('Could not reach central to start the session'));
878
+ // Central may have taken it anyway (reply lost, SSE gave
879
+ // us the id): release the robot-side slot.
880
+ if (sessionId) {
881
+ void this._sendToServer({ type: 'endSession', sessionId, reason: 'client_stop' });
882
+ }
883
+ }
884
+ else if (r?.type === 'error' && this._sessionReject) {
885
+ // e.g. "Producer not found": the robot re-registered.
886
+ this._closeTransport(new Error(`Central refused the session: ${r.message ?? 'error'}`));
887
+ }
646
888
  });
647
889
  });
648
890
  }
@@ -679,10 +921,8 @@ export class ReachyMini extends EventTarget {
679
921
  clearInterval(this._latencyMonitorId);
680
922
  this._latencyMonitorId = null;
681
923
  }
682
- if (this._micStream) {
683
- this._micStream.getTracks().forEach((t) => t.stop());
684
- this._micStream = null;
685
- }
924
+ this._releaseMicPlaceholder();
925
+ this._robotAudioTrack = null;
686
926
  this._micMuted = true;
687
927
  this._micSupported = false;
688
928
  if (this._pc) {
@@ -697,8 +937,36 @@ export class ReachyMini extends EventTarget {
697
937
  this._dcOpen = false;
698
938
  const sessionId = this._sessionId;
699
939
  this._sessionId = null;
940
+ this._retireSession(sessionId);
941
+ this._retireSession(this._staleSessionId);
942
+ this._staleSessionId = null;
700
943
  return sessionId;
701
944
  }
945
+ _retireSession(sessionId) {
946
+ if (!sessionId)
947
+ return;
948
+ this._retiredSessionIds.add(sessionId);
949
+ // Only recent ones matter: drop the oldest beyond a handful.
950
+ if (this._retiredSessionIds.size > RETIRED_SESSIONS_MAX) {
951
+ const oldest = this._retiredSessionIds.values().next().value;
952
+ if (oldest !== undefined)
953
+ this._retiredSessionIds.delete(oldest);
954
+ }
955
+ }
956
+ /**
957
+ * Whether an endSession is about another session than ours: one we
958
+ * already closed (a re-dial's old session, ended late by the robot as
959
+ * superseded), or any id but the current one. With no id known yet
960
+ * (startSession in flight) it is ours: rejections arrive that way.
961
+ */
962
+ _isOtherSession(sessionId) {
963
+ if (!sessionId)
964
+ return false;
965
+ if (this._retiredSessionIds.has(sessionId))
966
+ return true;
967
+ const current = this._sessionId ?? this._staleSessionId;
968
+ return current !== null && sessionId !== current;
969
+ }
702
970
  _failSessionRejected(msg) {
703
971
  const err = new Error(msg.reason === 'robot_busy'
704
972
  ? `Robot is busy: "${msg.activeApp || 'another app'}" is already connected`
@@ -721,15 +989,20 @@ export class ReachyMini extends EventTarget {
721
989
  this._supervisor.cancelRedial();
722
990
  this._logSubscribers.clear();
723
991
  this._updateProgressSubscribers.clear();
992
+ this._outgoingAudioTrack = null;
724
993
  const sessionId = this._closeTransport(new Error('Session stopped'));
725
994
  if (sessionId) {
726
- await this._sendToServer({ type: 'endSession', sessionId });
995
+ // A reason marks a deliberate hang-up: the robot ends the session
996
+ // on it, whereas a reason-less endSession (central's own
997
+ // eviction) is advisory while the peer link is live.
998
+ await this._sendToServer({ type: 'endSession', sessionId, reason: 'client_stop' });
727
999
  }
728
1000
  const wasStreaming = this._state === 'streaming';
729
1001
  if (wasStreaming) {
730
1002
  this._state = 'connected';
731
1003
  this._emit('sessionStopped', { reason: 'user' });
732
1004
  }
1005
+ this._dropToDisconnectedIfSignalingDown();
733
1006
  }
734
1007
  disconnect() {
735
1008
  this._supervisor.cancelRedial();
@@ -739,9 +1012,12 @@ export class ReachyMini extends EventTarget {
739
1012
  }
740
1013
  this._logSubscribers.clear();
741
1014
  this._updateProgressSubscribers.clear();
1015
+ this._outgoingAudioTrack = null;
1016
+ this._clearSignalingRetry();
1017
+ this._signalingDown = false;
742
1018
  const sessionId = this._closeTransport(new Error('Disconnected'));
743
1019
  if (sessionId && this._token) {
744
- void this._sendToServer({ type: 'endSession', sessionId });
1020
+ void this._sendToServer({ type: 'endSession', sessionId, reason: 'client_disconnect' });
745
1021
  }
746
1022
  this._robots = [];
747
1023
  this._state = 'disconnected';
@@ -778,6 +1054,41 @@ export class ReachyMini extends EventTarget {
778
1054
  * armed, and a late signaling reply could otherwise settle them
779
1055
  * against a closed pc).
780
1056
  */
1057
+ /**
1058
+ * Resolver for the redial loop. Matches on the robot's stable
1059
+ * identity (`install_id`, else `hardware_id`; never the name, which
1060
+ * users often leave at the default and share across robots). A
1061
+ * listed robot with that identity under a NEW id is the same robot,
1062
+ * re-registered; otherwise keep dialing the original id.
1063
+ */
1064
+ _redialTargetResolver(robotId) {
1065
+ // Prefer the identity recorded when the session was dialed: by the
1066
+ // time a redial starts, central may already have dropped the old
1067
+ // entry from the list (it evicts a robot whose signaling went
1068
+ // silent), leaving nothing to match against.
1069
+ const key = (this._dialedRobotId === robotId ? this._dialedRobotIdentity : null)
1070
+ ?? robotIdentity(this._robots.find((r) => r.id === robotId));
1071
+ if (!key)
1072
+ return () => robotId;
1073
+ return () => this._robots.find((r) => r.id !== robotId && robotIdentity(r) === key)?.id ?? robotId;
1074
+ }
1075
+ /**
1076
+ * Stop the placeholder sender track AND close its AudioContext.
1077
+ * Stopping the track alone left the context (and its oscillator)
1078
+ * running: one leaked context per dial, and browsers cap open audio
1079
+ * outputs (Chromium: 10 per page), so after a few re-dials every
1080
+ * new AudioContext in the host app fails silently.
1081
+ */
1082
+ _releaseMicPlaceholder() {
1083
+ if (this._micStream) {
1084
+ this._micStream.getTracks().forEach((t) => t.stop());
1085
+ this._micStream = null;
1086
+ }
1087
+ const ctx = this._micCtx;
1088
+ this._micCtx = null;
1089
+ if (ctx && ctx.state !== 'closed')
1090
+ void ctx.close().catch(() => { });
1091
+ }
781
1092
  _teardownForRedial() {
782
1093
  const sessionId = this._closeTransport(new Error('Session reconnecting'));
783
1094
  // Free the robot-side slot: the relay refuses a second session
@@ -785,10 +1096,83 @@ export class ReachyMini extends EventTarget {
785
1096
  // own consent-freshness timeout, ~30 s) clears it. Fire and
786
1097
  // forget — _sendToServer never throws.
787
1098
  if (sessionId && this._token) {
788
- void this._sendToServer({ type: 'endSession', sessionId });
1099
+ void this._sendToServer({ type: 'endSession', sessionId, reason: 'client_redial' });
789
1100
  }
790
1101
  if (this._state === 'streaming')
791
1102
  this._state = 'connected';
1103
+ // The redial loop reconnects signaling itself (isSignalingDown).
1104
+ if (this._signalingDown) {
1105
+ this._clearSignalingRetry();
1106
+ this._signalingDown = false;
1107
+ this._state = 'disconnected';
1108
+ }
1109
+ }
1110
+ /**
1111
+ * The robot (or central on its behalf) ended a streaming session:
1112
+ * tear our side down and emit ONE `sessionStopped` carrying the
1113
+ * robot's reason (`stopSession()` would add a second, `user`, one).
1114
+ * No endSession goes back: the other side already ended it.
1115
+ */
1116
+ _endedByRobot(reason, message) {
1117
+ this._supervisor.cancelRedial();
1118
+ this._logSubscribers.clear();
1119
+ this._updateProgressSubscribers.clear();
1120
+ this._outgoingAudioTrack = null;
1121
+ this._closeTransport(new Error('Session ended by the robot'));
1122
+ if (this._state === 'streaming')
1123
+ this._state = 'connected';
1124
+ this._emit('sessionStopped', { reason, message });
1125
+ this._dropToDisconnectedIfSignalingDown();
1126
+ }
1127
+ /** Session over while signaling is down: surface the real state. */
1128
+ _dropToDisconnectedIfSignalingDown() {
1129
+ if (!this._signalingDown)
1130
+ return;
1131
+ this._clearSignalingRetry();
1132
+ this._signalingDown = false;
1133
+ if (this._state !== 'disconnected') {
1134
+ this._state = 'disconnected';
1135
+ this._emit('disconnected', { reason: 'SSE closed' });
1136
+ }
1137
+ }
1138
+ _clearSignalingRetry() {
1139
+ if (this._signalingRetryTimer !== null) {
1140
+ clearTimeout(this._signalingRetryTimer);
1141
+ this._signalingRetryTimer = null;
1142
+ }
1143
+ if (this._signalingDown && this._sseAbortController) {
1144
+ this._sseAbortController.abort();
1145
+ this._sseAbortController = null;
1146
+ }
1147
+ this._signalingRetryAttempt = 0;
1148
+ }
1149
+ /** Background signaling reconnect while a session keeps streaming. */
1150
+ _scheduleSignalingRetry() {
1151
+ if (this._signalingRetryTimer !== null)
1152
+ return;
1153
+ const delays = [1000, 2000, 4000, 8000, 15000];
1154
+ const delay = delays[Math.min(this._signalingRetryAttempt, delays.length - 1)];
1155
+ this._signalingRetryAttempt += 1;
1156
+ this._signalingRetryTimer = setTimeout(() => {
1157
+ this._signalingRetryTimer = null;
1158
+ if (!this._signalingDown || this._state !== 'streaming')
1159
+ return;
1160
+ this._openSignaling().catch(() => {
1161
+ if (this._signalingDown && this._state === 'streaming')
1162
+ this._scheduleSignalingRetry();
1163
+ });
1164
+ }, delay);
1165
+ }
1166
+ /**
1167
+ * Liveness of the peer link itself: data channel open, ICE up, and the
1168
+ * robot heard from recently (it answers the ~500 ms state poll).
1169
+ */
1170
+ _peerLinkLive() {
1171
+ const ice = this._pc?.iceConnectionState;
1172
+ return this._dcOpen
1173
+ && this._dc?.readyState === 'open'
1174
+ && (ice === 'connected' || ice === 'completed')
1175
+ && this._supervisor.dcInboundAgeMs < PEER_LINK_LIVE_MS;
792
1176
  }
793
1177
  // ─── Commands ────────────────────────────────────────────────────────
794
1178
  /**
@@ -1134,6 +1518,20 @@ export class ReachyMini extends EventTarget {
1134
1518
  setRobotName(name) {
1135
1519
  return this._slotRoundtrip('robot_name', { type: 'set_robot_name', name });
1136
1520
  }
1521
+ /**
1522
+ * Read the robot's anonymous telemetry choice. Resolves `null` when the
1523
+ * channel isn't open or the daemon predates the `get_telemetry` command.
1524
+ */
1525
+ getTelemetry() {
1526
+ return this._slotRoundtrip('telemetry', { type: 'get_telemetry' });
1527
+ }
1528
+ /**
1529
+ * Enable or disable telemetry on the robot, applied live. Disabling also
1530
+ * forgets the robot id. Resolves the stored choice, or `null` on error.
1531
+ */
1532
+ setTelemetry(enabled) {
1533
+ return this._slotRoundtrip('set_telemetry', { type: 'set_telemetry', enabled });
1534
+ }
1137
1535
  /**
1138
1536
  * Sign this robot out of Hugging Face: asks the daemon to delete its
1139
1537
  * stored HF token, which de-registers the robot from the central
@@ -1271,6 +1669,36 @@ export class ReachyMini extends EventTarget {
1271
1669
  this._micStream.getAudioTracks().forEach((t) => { t.enabled = !muted; });
1272
1670
  }
1273
1671
  }
1672
+ /**
1673
+ * Stream an audio track to the robot's speaker in real time (TTS output,
1674
+ * a WebAudio graph, the user's own mic for teleop…). Pass `null` to go
1675
+ * back to silence. The track survives auto-reconnects; the app keeps
1676
+ * ownership of it (the SDK never stops it).
1677
+ *
1678
+ * Resolves `true` once the track is on the wire, `false` when there is
1679
+ * no live session yet (it is then applied as soon as one starts) or when
1680
+ * the robot didn't offer two-way audio. Cleared by `stopSession()` /
1681
+ * `disconnect()`. `setMicMuted()` only mutes the SDK's placeholder, not
1682
+ * this track — stop or disable the track itself to go quiet.
1683
+ * For clips that must stay in sync with motion, prefer
1684
+ * `playMove(motion, { audioBlob })` or `uploadAudio` + `playUploadedAudio`.
1685
+ */
1686
+ async setOutgoingAudioTrack(track) {
1687
+ if (track && track.kind !== 'audio') {
1688
+ throw new TypeError(`setOutgoingAudioTrack: expected an audio track, got "${track.kind}"`);
1689
+ }
1690
+ this._outgoingAudioTrack = track;
1691
+ return this._applyOutgoingAudioTrack();
1692
+ }
1693
+ async _applyOutgoingAudioTrack() {
1694
+ const sender = this._pc?.getTransceivers()
1695
+ .find((t) => t.receiver.track.kind === 'audio')?.sender;
1696
+ if (!sender || !this._micSupported)
1697
+ return false;
1698
+ const fallback = this._micStream?.getAudioTracks()[0] ?? null;
1699
+ await sender.replaceTrack(this._outgoingAudioTrack ?? fallback);
1700
+ return true;
1701
+ }
1274
1702
  // ─── Video helper ────────────────────────────────────────────────────
1275
1703
  attachVideo(videoElement) {
1276
1704
  this._videoElement = videoElement;
@@ -1513,6 +1941,8 @@ export class ReachyMini extends EventTarget {
1513
1941
  async _sendToServer(message) {
1514
1942
  if (!this._token)
1515
1943
  throw new Error('No token — authenticate() first');
1944
+ const controller = new AbortController();
1945
+ const timer = setTimeout(() => controller.abort(), CENTRAL_REQUEST_TIMEOUT_MS);
1516
1946
  try {
1517
1947
  const res = await fetch(`${this._signalingUrl}/send`, {
1518
1948
  method: 'POST',
@@ -1521,6 +1951,7 @@ export class ReachyMini extends EventTarget {
1521
1951
  'Authorization': `Bearer ${this._token}`,
1522
1952
  },
1523
1953
  body: JSON.stringify(message),
1954
+ signal: controller.signal,
1524
1955
  });
1525
1956
  if (!res.ok) {
1526
1957
  let body = '';
@@ -1537,6 +1968,9 @@ export class ReachyMini extends EventTarget {
1537
1968
  log.error('signaling /send failed:', e);
1538
1969
  return null;
1539
1970
  }
1971
+ finally {
1972
+ clearTimeout(timer);
1973
+ }
1540
1974
  }
1541
1975
  _sendCommand(cmd) {
1542
1976
  if (!this._dc || this._dc.readyState !== 'open')
@@ -1633,6 +2067,8 @@ export class ReachyMini extends EventTarget {
1633
2067
  break;
1634
2068
  }
1635
2069
  case 'sessionStarted':
2070
+ if (msg.sessionId && this._retiredSessionIds.has(msg.sessionId))
2071
+ break;
1636
2072
  this._sessionId = msg.sessionId ?? null;
1637
2073
  break;
1638
2074
  case 'sessionRejected':
@@ -1647,6 +2083,10 @@ export class ReachyMini extends EventTarget {
1647
2083
  }
1648
2084
  }
1649
2085
  _handleEndSession(msg) {
2086
+ if (this._isOtherSession(msg.sessionId)) {
2087
+ log.info(`ignoring endSession for session ${msg.sessionId}: not the current one`);
2088
+ return;
2089
+ }
1650
2090
  const reason = msg.reason;
1651
2091
  const friendly = reason === 'robot_busy_local_app'
1652
2092
  ? 'Robot is busy: a local Python app is running'
@@ -1670,14 +2110,15 @@ export class ReachyMini extends EventTarget {
1670
2110
  this._pc.close();
1671
2111
  this._pc = null;
1672
2112
  }
1673
- if (this._micStream) {
1674
- this._micStream.getTracks().forEach((t) => t.stop());
1675
- this._micStream = null;
1676
- }
2113
+ this._releaseMicPlaceholder();
2114
+ this._robotAudioTrack = null;
1677
2115
  this._iceConnected = false;
1678
2116
  this._dcOpen = false;
1679
2117
  this._micMuted = true;
1680
2118
  this._micSupported = false;
2119
+ // Same bookkeeping as _closeTransport: this id is over.
2120
+ this._retireSession(this._sessionId);
2121
+ this._sessionId = null;
1681
2122
  const reject = this._sessionReject;
1682
2123
  this._sessionResolve = null;
1683
2124
  this._sessionReject = null;
@@ -1685,16 +2126,27 @@ export class ReachyMini extends EventTarget {
1685
2126
  return;
1686
2127
  }
1687
2128
  if (this._state === 'streaming') {
1688
- this._emit('sessionStopped', {
1689
- reason: reason || 'remote_end',
1690
- message: friendly,
1691
- });
1692
- this.stopSession().catch(() => { });
2129
+ // Without a reason this is central's own bookkeeping (our
2130
+ // signaling timed out and it evicted us), not the robot hanging
2131
+ // up: the robot gives a reason, or closes the data channel. The
2132
+ // session lives as long as the peer link does.
2133
+ if (!reason && this._peerLinkLive()) {
2134
+ log.info('central ended the session but the peer link is live; keeping it');
2135
+ this._staleSessionId = this._sessionId;
2136
+ this._sessionId = null; // stale on central
2137
+ this._emit('signalingSessionEnded', { reason: null });
2138
+ return;
2139
+ }
2140
+ this._endedByRobot(reason || 'remote_end', friendly);
1693
2141
  }
1694
2142
  }
1695
2143
  async _handlePeerMessage(msg) {
1696
2144
  if (!this._pc)
1697
2145
  return;
2146
+ // An offer or candidate for a session we closed (e.g. a dial whose
2147
+ // startSession reply was abandoned) must not land on the current pc.
2148
+ if (msg.sessionId && this._retiredSessionIds.has(msg.sessionId))
2149
+ return;
1698
2150
  try {
1699
2151
  if (msg.sdp) {
1700
2152
  const sdp = msg.sdp;
@@ -1710,6 +2162,13 @@ export class ReachyMini extends EventTarget {
1710
2162
  await this._pc.setRemoteDescription(new RTCSessionDescription(sdp));
1711
2163
  const answer = await this._pc.createAnswer();
1712
2164
  await this._pc.setLocalDescription(answer);
2165
+ // Re-dials build a fresh peer connection: carry the app's
2166
+ // outgoing audio over instead of reverting to the placeholder.
2167
+ if (this._outgoingAudioTrack) {
2168
+ // Best-effort: a failed swap must not keep the answer from going out.
2169
+ await this._applyOutgoingAudioTrack()
2170
+ .catch((e) => log.warn('re-applying outgoing audio failed:', e));
2171
+ }
1713
2172
  await this._sendToServer({
1714
2173
  type: 'peer',
1715
2174
  sessionId: this._sessionId,
@@ -1798,6 +2257,12 @@ export class ReachyMini extends EventTarget {
1798
2257
  this._pending.settleReplySlot('robot_name', data.status === 'error' ? null : (data.name ?? null));
1799
2258
  return;
1800
2259
  }
2260
+ if (data.command === 'get_telemetry' || data.command === 'set_telemetry') {
2261
+ this._pending.settleReplySlot(data.command === 'get_telemetry' ? 'telemetry' : 'set_telemetry', data.status === 'error'
2262
+ ? null
2263
+ : { enabled: !!data.enabled, disabled_by_env: !!data.disabled_by_env });
2264
+ return;
2265
+ }
1801
2266
  if (data.command === 'delete_hf_token') {
1802
2267
  this._pending.settleReplySlot('delete_hf_token', data.status !== 'error');
1803
2268
  return;