@lumavox/react 0.34.0 → 0.35.1

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 CHANGED
@@ -10,6 +10,9 @@ later; no other dependency.
10
10
  npm install @lumavox/react @lumavox/client
11
11
  ```
12
12
 
13
+ Install both, and upgrade them together: the hooks need the client at
14
+ exactly their own version, and npm refuses a mismatch.
15
+
13
16
  ```tsx
14
17
  import { createClient } from "@lumavox/client";
15
18
  import { AgentProvider, useAgent } from "@lumavox/react";
@@ -53,10 +56,11 @@ redial.
53
56
  |---|---|
54
57
  | `state` `ready` `turn` `caption` `relation` `queued` | the conversation's snapshot |
55
58
  | `session` | the session it opened, with its last messages |
56
- | `error` | `{ kind, message }`: the session, an `error` frame, the close, the microphone |
59
+ | `error` | `{ kind, message }`: the session, an `error` frame, the close, the microphone — with its cause beside it (`error`, `frame` or `close`) |
57
60
  | `speaking` `recording` | the adapter is playing; the recorder is open |
58
61
  | `interrupted` | the device has the audio — a call, Siri, another app |
59
- | `send` `note` `startAudio` `sendAudio` `endAudio` `cancel` `mute` `reconnect` `close` | the conversation's |
62
+ | `send` `note` `startAudio` `sendAudio` `endAudio` `cancel` `mute` `reconnect` `end` `close` | the conversation's — `end` has its report written, then closes |
63
+ | `setVolume(level)` | how loud the agent's voice plays, 0 to 1: `audio`'s own, for a slider |
60
64
  | `startRecording({ rate, transcribeOnly, speech, thoughts })` `stopRecording({ transcribeOnly, discard })` | through the `audio` adapter; a held turn's own voice and thinking, as `send`'s |
61
65
  | `listen(options)` `stopListening()` `listening` `hearing` | hands-free: each utterance a turn, talking over the agent stopping it (`@lumavox/client`'s `listen`); `listen({ halfDuplex: true })` where echo cannot be cancelled — nothing heard while the agent speaks |
62
66
  | `newSession()` | a new conversation with the same agent |
@@ -95,3 +99,8 @@ Each returns `{ data, error, loading, refresh }`, with `error` a
95
99
  | `useRelation(agentId)` | live from an open `useAgent` under the same provider, else read once |
96
100
 
97
101
  MIT, copyright Lumavox.
102
+
103
+ ## Docs and releases
104
+
105
+ The guide: <https://docs.lumavox.ai/sdks/react>. What changed in each
106
+ release, and what you change: <https://docs.lumavox.ai/sdks/releases>.
package/dist/read.d.ts CHANGED
@@ -24,7 +24,15 @@ export declare function asPlatformError(error: unknown): PlatformError;
24
24
  * `load`, run on mount and whenever `key` changes — not while it is
25
25
  * `null` — and its answer as a `Read`. `set` changes `data` in place,
26
26
  * after a delete, say, without a read.
27
+ *
28
+ * **`whose` is whose data it is** — the client, and the thing read: when
29
+ * any of it changes, what was read belongs to another, and is gone at
30
+ * once, in the same render. Kept, one conversation's messages showed
31
+ * under the next while it loaded, and stayed when it failed; and after
32
+ * another person signed in, the last one's facts were still on screen. A
33
+ * `key` that changes under the same `whose` — the next page of a list —
34
+ * keeps what is shown until the new answer comes.
27
35
  */
28
- export declare function useRead<T>(key: string | null, load: () => Promise<T>): Read<T> & {
36
+ export declare function useRead<T>(key: string | null, load: () => Promise<T>, ...whose: unknown[]): Read<T> & {
29
37
  set(change: (data: T | null) => T | null): void;
30
38
  };
package/dist/read.js CHANGED
@@ -26,10 +26,24 @@ export function asPlatformError(error) {
26
26
  * `load`, run on mount and whenever `key` changes — not while it is
27
27
  * `null` — and its answer as a `Read`. `set` changes `data` in place,
28
28
  * after a delete, say, without a read.
29
+ *
30
+ * **`whose` is whose data it is** — the client, and the thing read: when
31
+ * any of it changes, what was read belongs to another, and is gone at
32
+ * once, in the same render. Kept, one conversation's messages showed
33
+ * under the next while it loaded, and stayed when it failed; and after
34
+ * another person signed in, the last one's facts were still on screen. A
35
+ * `key` that changes under the same `whose` — the next page of a list —
36
+ * keeps what is shown until the new answer comes.
29
37
  */
30
- export function useRead(key, load) {
31
- const [data, setData] = useState(null);
32
- const [error, setError] = useState(null);
38
+ export function useRead(key, load, ...whose) {
39
+ // Which owner this is, counted: what was read is shown only to its own.
40
+ const owner = useRef({ whose, n: 0 });
41
+ if (whose.length !== owner.current.whose.length ||
42
+ whose.some((part, at) => part !== owner.current.whose[at])) {
43
+ owner.current = { whose, n: owner.current.n + 1 };
44
+ }
45
+ const of = owner.current.n;
46
+ const [held, setHeld] = useState({ data: null, error: null, of });
33
47
  const [loading, setLoading] = useState(key !== null);
34
48
  const latest = useRef(0);
35
49
  const mounted = useRef(true);
@@ -37,18 +51,23 @@ export function useRead(key, load) {
37
51
  loader.current = load;
38
52
  const refresh = useCallback(async () => {
39
53
  const mine = ++latest.current;
54
+ const whoseNow = owner.current.n;
40
55
  setLoading(true);
41
56
  try {
42
57
  const answer = await loader.current();
43
58
  if (mounted.current && mine === latest.current) {
44
- setData(answer);
45
- setError(null);
59
+ setHeld({ data: answer, error: null, of: whoseNow });
46
60
  }
47
61
  }
48
62
  catch (failure) {
49
63
  // swallowed: it is the hook's `error`, the caller's to show.
50
64
  if (mounted.current && mine === latest.current) {
51
- setError(asPlatformError(failure));
65
+ const error = asPlatformError(failure);
66
+ setHeld((last) => ({
67
+ data: last.of === whoseNow ? last.data : null,
68
+ error,
69
+ of: whoseNow,
70
+ }));
52
71
  }
53
72
  }
54
73
  finally {
@@ -56,16 +75,36 @@ export function useRead(key, load) {
56
75
  setLoading(false);
57
76
  }
58
77
  }, []);
78
+ // biome-ignore lint/correctness/useExhaustiveDependencies(of): a new owner reads again, with the key it has.
59
79
  useEffect(() => {
60
80
  mounted.current = true;
61
81
  if (key !== null)
62
82
  void refresh();
83
+ else {
84
+ // Nothing to read: a read still out is no longer wanted.
85
+ latest.current += 1;
86
+ setLoading(false);
87
+ }
63
88
  return () => {
64
89
  mounted.current = false;
65
90
  };
66
- }, [key, refresh]);
91
+ }, [key, refresh, of]);
67
92
  const set = useCallback((change) => {
68
- setData((current) => change(current));
93
+ setHeld((last) => {
94
+ const now = owner.current.n;
95
+ return {
96
+ data: change(last.of === now ? last.data : null),
97
+ error: last.of === now ? last.error : null,
98
+ of: now,
99
+ };
100
+ });
69
101
  }, []);
70
- return { data, error, loading, refresh, set };
102
+ const mine = held.of === of;
103
+ return {
104
+ data: mine ? held.data : null,
105
+ error: mine ? held.error : null,
106
+ loading,
107
+ refresh,
108
+ set,
109
+ };
71
110
  }
@@ -26,6 +26,26 @@
26
26
  * that reply — or, with `halfDuplex`, nothing is heard while it speaks.
27
27
  * Push-to-talk waits while it listens, and it ends with the
28
28
  * conversation.
29
+ * - **The microphone's calls go one after another** (`lane`): a start
30
+ * never overlaps the start or the stop before it, and each leaves the
31
+ * microphone either this hook's or closed before the next begins —
32
+ * released while it opened, it is given back first. Press, release,
33
+ * press again was a second recorder over the first, and on a phone the
34
+ * one nothing could stop, until the app restarted (sdks 0.34.1).
35
+ * - **A player may come later**: the person turns voice on, and the app
36
+ * passes its `audio` then. `onAudio` is set on the live conversation's
37
+ * handlers as a player comes and taken off as it goes, so speech is
38
+ * asked for from the next turn — never paid for unheard, and never a
39
+ * reply silent with a player there, as it was for the conversation's
40
+ * life while this was decided once, at connect. `speech` and `thoughts`
41
+ * are each turn's as the options are when it is sent.
42
+ * - **A failed open is tried again by `reconnect()`** — the screen opened
43
+ * offline, a 5xx: there was no conversation for it to call, and so
44
+ * nothing to do but leave the screen.
45
+ * - **The microphone closes with the conversation**: `end()`, `close()`
46
+ * and a close for good stop hands-free and a recording, and neither
47
+ * opens on a conversation that is closed. None of the four microphone
48
+ * controls rejects: an adapter's failure is `error`, kind `audio`.
29
49
  */
30
50
  import { type AgentAudio, type Client, type CloseInfo, type ConnectOptions, type Conversation, type ConversationHandlers, type ErrorFrame, type ListenOptions, type PlatformError, type SendOptions, type SessionDetail, type Snapshot, type StartAudioOptions, type TranscriptOutcome, type TurnOptions, type TurnOutcome } from "@lumavox/client";
31
51
  /** Whom to talk to; `null` for nobody yet — nothing is opened. */
@@ -88,7 +108,7 @@ export interface StopRecordingOptions {
88
108
  transcribeOnly?: boolean;
89
109
  /** The turn's: what the app says about the moment (`SendOptions.context`). */
90
110
  context?: SendOptions["context"];
91
- /** Throw it away: the recording is cancelled, and so is a turn running. */
111
+ /** Throw it away: nothing of it is transcribed. A turn running goes on — `cancel()` stops one. */
92
112
  discard?: boolean;
93
113
  }
94
114
  export interface AgentControls extends Snapshot {
@@ -131,6 +151,12 @@ export interface AgentControls extends Snapshot {
131
151
  stopListening(): Promise<void>;
132
152
  cancel(): void;
133
153
  mute(): void;
154
+ /**
155
+ * How loud the agent's voice plays, from 0 to 1 of how it was made: the
156
+ * audio's own `setVolume`, for a slider. Kept from reply to reply, and
157
+ * nothing with an audio that has none.
158
+ */
159
+ setVolume(level: number): void;
134
160
  reconnect(): void;
135
161
  /** A new conversation with the same agent. */
136
162
  newSession(): void;
package/dist/use-agent.js CHANGED
@@ -26,8 +26,28 @@
26
26
  * that reply — or, with `halfDuplex`, nothing is heard while it speaks.
27
27
  * Push-to-talk waits while it listens, and it ends with the
28
28
  * conversation.
29
+ * - **The microphone's calls go one after another** (`lane`): a start
30
+ * never overlaps the start or the stop before it, and each leaves the
31
+ * microphone either this hook's or closed before the next begins —
32
+ * released while it opened, it is given back first. Press, release,
33
+ * press again was a second recorder over the first, and on a phone the
34
+ * one nothing could stop, until the app restarted (sdks 0.34.1).
35
+ * - **A player may come later**: the person turns voice on, and the app
36
+ * passes its `audio` then. `onAudio` is set on the live conversation's
37
+ * handlers as a player comes and taken off as it goes, so speech is
38
+ * asked for from the next turn — never paid for unheard, and never a
39
+ * reply silent with a player there, as it was for the conversation's
40
+ * life while this was decided once, at connect. `speech` and `thoughts`
41
+ * are each turn's as the options are when it is sent.
42
+ * - **A failed open is tried again by `reconnect()`** — the screen opened
43
+ * offline, a 5xx: there was no conversation for it to call, and so
44
+ * nothing to do but leave the screen.
45
+ * - **The microphone closes with the conversation**: `end()`, `close()`
46
+ * and a close for good stop hands-free and a recording, and neither
47
+ * opens on a conversation that is closed. None of the four microphone
48
+ * controls rejects: an adapter's failure is `error`, kind `audio`.
29
49
  */
30
- import { listen as listenOn, RECORDING_RATES, } from "@lumavox/client";
50
+ import { listen as listenOn, MAX_AUDIO_BYTES, RECORDING_RATES, } from "@lumavox/client";
31
51
  import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
32
52
  import { useClient, useLive } from "./provider.js";
33
53
  import { asPlatformError } from "./read.js";
@@ -38,6 +58,7 @@ const PASSED = [
38
58
  "onTurnStart",
39
59
  "onHeard",
40
60
  "onHeardPartial",
61
+ "onBargeIn",
41
62
  "onKnowledge",
42
63
  "onMemories",
43
64
  "onMood",
@@ -80,6 +101,10 @@ const notOpen = {
80
101
  reason: "closed",
81
102
  message: "The conversation is not open.",
82
103
  };
104
+ /** What `error` says when hands-free stopped by itself: the microphone did not open again after the device took the audio. */
105
+ const STOPPED_ITSELF = "Hands-free stopped: the microphone did not open again. Start it again.";
106
+ const NOT_CLOSED = "Could not close the microphone.";
107
+ const NOT_OPENED = "Could not open the microphone.";
83
108
  export function useAgent(target, options = {}) {
84
109
  const client = useClient(options.client);
85
110
  const live = useLive();
@@ -100,8 +125,68 @@ export function useAgent(target, options = {}) {
100
125
  /** The reply's frames still arriving after a stop are not played. */
101
126
  const silenced = useRef(false);
102
127
  const capture = useRef(null);
103
- /** Hands-free, once `listen` opened it; `starting` while it opens. */
128
+ /** The handlers the live conversation was given: `onAudio` comes and goes on them with a player. */
129
+ const wiredNow = useRef(null);
130
+ /** A reply's frame, through the adapter the app has now. */
131
+ const play = useCallback((frame) => {
132
+ const audio = latest.current.audio;
133
+ if (audio && !silenced.current) {
134
+ audio.play(frame.pcm, frame);
135
+ setSpeaking(true);
136
+ }
137
+ latest.current.onAudio?.(frame);
138
+ }, []);
139
+ /** The open failed, and which try it was: `reconnect()` runs the next. */
140
+ const failedOpen = useRef(false);
141
+ const [attempt, setAttempt] = useState(0);
142
+ const tries = useRef(0);
143
+ /** Hands-free, on or opening: the `listen` that asked. */
104
144
  const handsFree = useRef(null);
145
+ /** The adapter's microphone calls, one after another (the header says why). */
146
+ const lane = useRef(Promise.resolve());
147
+ const inLane = useCallback((work) => {
148
+ const run = lane.current.then(work);
149
+ lane.current = run.catch(() => {
150
+ // swallowed: the caller has it; the lane only waits for it to end.
151
+ });
152
+ return run;
153
+ }, []);
154
+ /** The adapter's microphone closed, in its turn: a failure is `error`, never a rejection. */
155
+ const closeMic = useCallback(async (work) => {
156
+ try {
157
+ await inLane(work);
158
+ }
159
+ catch (failure) {
160
+ // swallowed: it is the hook's `error`, the caller's to show.
161
+ setError({ kind: "audio", message: NOT_CLOSED, error: failure });
162
+ }
163
+ }, [inLane]);
164
+ /** Hands-free and a recording, let go: the conversation is over, or the screen is. */
165
+ const letGo = useCallback(() => {
166
+ const engine = handsFree.current?.engine;
167
+ // One still opening finds itself gone, and closes what it opened.
168
+ handsFree.current = null;
169
+ setListening(false);
170
+ setHearing(false);
171
+ if (engine)
172
+ void closeMic(() => engine.stop());
173
+ const open = capture.current;
174
+ if (!open)
175
+ return;
176
+ capture.current = null;
177
+ setRecording(false);
178
+ const { audio, started } = open;
179
+ open.cancelled = open.over = true;
180
+ if (started)
181
+ void closeMic(() => audio.stopCapture());
182
+ else {
183
+ // Still opening: told at once, so an adapter of this SDK's opens
184
+ // nothing; another's is given back by the press itself, in its turn.
185
+ audio.stopCapture().catch(() => {
186
+ // swallowed: nothing was open yet to fail to close.
187
+ });
188
+ }
189
+ }, [closeMic]);
105
190
  const sessionId = target && "sessionId" in target ? target.sessionId : null;
106
191
  const agentId = target && "agentId" in target ? target.agentId : null;
107
192
  const resume = target && "agentId" in target ? target.resume : undefined;
@@ -110,6 +195,12 @@ export function useAgent(target, options = {}) {
110
195
  /** `newSession()`: a new conversation with this agent, for this target. */
111
196
  const [fresh, setFresh] = useState(null);
112
197
  const renewal = fresh?.key === targetKey ? fresh : null;
198
+ // A `newSession()` is its target's, while it is the target: kept past
199
+ // it, coming back to that session or agent opened yet another new
200
+ // conversation, every time, and never the one asked for.
201
+ useEffect(() => {
202
+ setFresh((last) => (last && last.key !== targetKey ? null : last));
203
+ }, [targetKey]);
113
204
  const hush = useCallback(() => {
114
205
  silenced.current = true;
115
206
  latest.current.audio?.stop();
@@ -118,6 +209,8 @@ export function useAgent(target, options = {}) {
118
209
  useEffect(() => {
119
210
  let alive = true;
120
211
  let made = null;
212
+ tries.current = attempt;
213
+ failedOpen.current = false;
121
214
  setError(null);
122
215
  setFailed(false);
123
216
  setSession(null);
@@ -174,19 +267,36 @@ export function useAgent(target, options = {}) {
174
267
  const wire = () => {
175
268
  const handlers = {};
176
269
  for (const name of PASSED) {
177
- handlers[name] = (value) => latest.current[name]?.(value);
270
+ handlers[name] = (value) => {
271
+ // The hook's own close — the screen gone, another target, a
272
+ // StrictMode remount — is not the conversation's news: told as
273
+ // `onState("closed")`, an app that leaves the screen on a close
274
+ // left it at once.
275
+ if (!alive)
276
+ return;
277
+ latest.current[name]?.(value);
278
+ };
178
279
  }
179
280
  const wired = handlers;
180
281
  wired.onTurnStart = (frame) => {
282
+ if (!alive)
283
+ return;
181
284
  silenced.current = false;
182
285
  setError(null);
183
286
  latest.current.onTurnStart?.(frame);
184
287
  };
185
288
  wired.onError = (frame) => {
289
+ if (!alive)
290
+ return;
186
291
  setError({ kind: "frame", message: frame.message, frame });
187
292
  latest.current.onError?.(frame);
188
293
  };
189
294
  wired.onClose = (close) => {
295
+ if (!alive)
296
+ return;
297
+ // Closed for good with the screen still up: no microphone stays
298
+ // open on a conversation that takes nothing.
299
+ letGo();
190
300
  setError({
191
301
  kind: "closed",
192
302
  message: close.reason || `The conversation closed (${close.code}).`,
@@ -194,17 +304,11 @@ export function useAgent(target, options = {}) {
194
304
  });
195
305
  latest.current.onClose?.(close);
196
306
  };
197
- // Only when something plays it: with no `onAudio`, no speech is asked for.
198
- if (latest.current.audio || latest.current.onAudio) {
199
- wired.onAudio = (frame) => {
200
- const audio = latest.current.audio;
201
- if (audio && !silenced.current) {
202
- audio.play(frame.pcm, frame);
203
- setSpeaking(true);
204
- }
205
- latest.current.onAudio?.(frame);
206
- };
207
- }
307
+ // Only while something plays it: with no `onAudio`, no speech is
308
+ // asked for. Set and taken off again as a player comes and goes.
309
+ if (latest.current.audio || latest.current.onAudio)
310
+ wired.onAudio = play;
311
+ wiredNow.current = wired;
208
312
  return wired;
209
313
  };
210
314
  open().catch((failure) => {
@@ -213,6 +317,7 @@ export function useAgent(target, options = {}) {
213
317
  return;
214
318
  const error = asPlatformError(failure);
215
319
  opening.current = false;
320
+ failedOpen.current = true;
216
321
  setFailed(true);
217
322
  setError({ kind: "session", message: error.message, error });
218
323
  settleWaiting(null);
@@ -220,28 +325,37 @@ export function useAgent(target, options = {}) {
220
325
  return () => {
221
326
  alive = false;
222
327
  opening.current = false;
223
- const free = handsFree.current;
224
- handsFree.current = null;
225
- if (free && free !== "starting")
226
- void free.stop();
227
- setListening(false);
228
- setHearing(false);
229
- const open = capture.current;
230
- if (open) {
231
- open.cancelled = open.over = true;
232
- capture.current = null;
233
- void latest.current.audio?.stopCapture();
234
- }
328
+ letGo();
235
329
  latest.current.audio?.stop();
236
330
  made?.close();
237
331
  if (current.current === made)
238
332
  current.current = null;
239
333
  settleWaiting(null);
240
334
  setConversation(null);
241
- setRecording(false);
242
335
  setSpeaking(false);
243
336
  };
244
- }, [client, sessionId, agentId, resume, title, renewal]);
337
+ }, [
338
+ client,
339
+ sessionId,
340
+ agentId,
341
+ resume,
342
+ title,
343
+ renewal,
344
+ attempt,
345
+ letGo,
346
+ play,
347
+ ]);
348
+ // A player given, or taken away, after the conversation connected.
349
+ const plays = Boolean(options.audio || options.onAudio);
350
+ useEffect(() => {
351
+ const wired = conversation && wiredNow.current;
352
+ if (!wired)
353
+ return;
354
+ if (plays)
355
+ wired.onAudio = play;
356
+ else
357
+ delete wired.onAudio;
358
+ }, [plays, play, conversation]);
245
359
  // The agent stopped speaking when the adapter's queue plays out.
246
360
  const audio = options.audio;
247
361
  useEffect(() => audio?.onDrained(() => setSpeaking(false)), [audio]);
@@ -263,13 +377,22 @@ export function useAgent(target, options = {}) {
263
377
  return Promise.resolve(null);
264
378
  return new Promise((resolve) => waiting.current.push(resolve));
265
379
  }, []);
380
+ /** A turn's `speech` and `thoughts` as the options are now, unless the turn says its own. */
381
+ const turnNow = useCallback((turn) => {
382
+ const { speech, thoughts } = latest.current;
383
+ return {
384
+ ...(speech === undefined ? {} : { speech }),
385
+ ...(thoughts === undefined ? {} : { thoughts }),
386
+ ...turn,
387
+ };
388
+ }, []);
266
389
  const controls = useMemo(() => ({
267
390
  send(text, turn) {
268
391
  hush();
269
392
  const now = current.current;
270
393
  if (now)
271
- return now.send(text, turn);
272
- return connected().then((c) => (c ? c.send(text, turn) : notOpen));
394
+ return now.send(text, turnNow(turn));
395
+ return connected().then((c) => c ? c.send(text, turnNow(turn)) : notOpen);
273
396
  },
274
397
  startAudio: (start) => current.current?.startAudio(start) ?? null,
275
398
  note: (text, noteOptions) => current.current?.note(text, noteOptions) ?? false,
@@ -279,55 +402,104 @@ export function useAgent(target, options = {}) {
279
402
  : Promise.resolve(notOpen)),
280
403
  async startRecording(record = {}) {
281
404
  const recorder = latest.current.audio;
282
- const c = current.current;
283
- if (!recorder || !c || capture.current || handsFree.current) {
405
+ if (!recorder ||
406
+ capture.current ||
407
+ handsFree.current ||
408
+ (!current.current && !opening.current)) {
284
409
  return false;
285
410
  }
286
- if (!record.transcribeOnly)
287
- hush();
288
411
  const mine = {
412
+ audio: recorder,
289
413
  started: false,
290
414
  cancelled: false,
291
415
  over: false,
292
416
  early: [],
417
+ bytes: 0,
293
418
  };
294
419
  capture.current = mine;
295
420
  setRecording(true);
296
- let granted;
297
- try {
298
- ({ rate: granted } = await recorder.startCapture((pcm) => {
299
- if (mine.over)
300
- return;
301
- if (mine.started)
302
- c.sendAudio(pcm);
303
- else
304
- mine.early.push(pcm);
305
- }, { rate: record.rate ?? 16000 }));
306
- }
307
- catch (failure) {
308
- // swallowed: it is the hook's `error`, the caller's to show.
309
- if (capture.current === mine)
421
+ // A press before the conversation exists waits for it, as a
422
+ // `send` does: it answered `false`, with nothing to say why.
423
+ const c = current.current ?? (await connected());
424
+ if (!c || c.state === "closed" || mine.cancelled) {
425
+ mine.over = true;
426
+ if (capture.current === mine) {
310
427
  capture.current = null;
428
+ setRecording(false);
429
+ }
430
+ return false;
431
+ }
432
+ if (!record.transcribeOnly)
433
+ hush();
434
+ /** A recording that takes no more: its microphone is closed now, not at the release. */
435
+ const cut = () => {
436
+ if (mine.over)
437
+ return;
311
438
  mine.over = true;
312
439
  setRecording(false);
440
+ void closeMic(() => recorder.stopCapture());
441
+ const full = mine.bytes > MAX_AUDIO_BYTES;
442
+ // Full, what was said until then is the turn the release sends;
443
+ // dropped with the connection, there is nothing left to send.
444
+ if (!full && capture.current === mine)
445
+ capture.current = null;
313
446
  setError({
314
447
  kind: "audio",
315
- message: "Could not open the microphone.",
316
- error: failure,
448
+ message: full
449
+ ? "The recording reached the 10 MB one may carry: what was said until then is sent."
450
+ : "The recording was lost with the connection.",
451
+ error: null,
452
+ });
453
+ };
454
+ /** The rate it opened at, and whether the socket takes it; `null`, released while it opened. */
455
+ let opened;
456
+ try {
457
+ opened = await inLane(async () => {
458
+ // Released before its turn came: no microphone is opened.
459
+ if (mine.cancelled)
460
+ return null;
461
+ const { rate } = await recorder.startCapture((pcm) => {
462
+ if (mine.over)
463
+ return;
464
+ if (!mine.started)
465
+ mine.early.push(pcm);
466
+ else {
467
+ mine.bytes += pcm.byteLength;
468
+ if (!c.sendAudio(pcm))
469
+ cut();
470
+ }
471
+ }, { rate: record.rate ?? 16000 });
472
+ const taken = RECORDING_RATES.includes(rate);
473
+ if (taken && !mine.cancelled)
474
+ return { rate, taken };
475
+ // Released while it opened, or at a rate the socket does not
476
+ // take: given back here, in this press's turn, before the next
477
+ // press opens it.
478
+ mine.over = true;
479
+ await recorder.stopCapture();
480
+ return mine.cancelled ? null : { rate, taken };
317
481
  });
318
- return false;
319
482
  }
320
- if (mine.cancelled) {
321
- // Released while it opened: give the microphone back.
483
+ catch (failure) {
484
+ // swallowed: it is the hook's `error`, the caller's to show.
322
485
  mine.over = true;
323
- await recorder.stopCapture();
486
+ // Released, or the conversation gone, meanwhile: nothing to show,
487
+ // and the press after it has the hook's slot.
488
+ if (mine.cancelled)
489
+ return false;
490
+ if (capture.current === mine)
491
+ capture.current = null;
492
+ setRecording(false);
493
+ setError({ kind: "audio", message: NOT_OPENED, error: failure });
324
494
  return false;
325
495
  }
326
- if (!RECORDING_RATES.includes(granted)) {
327
- capture.current = null;
328
- mine.over = true;
496
+ if (!opened)
497
+ return false;
498
+ const granted = opened.rate;
499
+ if (!opened.taken) {
500
+ if (capture.current === mine)
501
+ capture.current = null;
329
502
  setRecording(false);
330
- await recorder.stopCapture();
331
503
  setError({
332
504
  kind: "audio",
333
505
  message: `The microphone opened at ${granted} Hz, which cannot be transcribed: ${RECORDING_RATES.join(", ")}.`,
@@ -337,35 +509,44 @@ export function useAgent(target, options = {}) {
337
509
  }
338
510
  c.startAudio({
339
511
  rate: granted,
340
- ...(record.speech === undefined ? {} : { speech: record.speech }),
341
- ...(record.thoughts === undefined
342
- ? {}
343
- : { thoughts: record.thoughts }),
512
+ ...turnNow({
513
+ ...(record.speech === undefined ? {} : { speech: record.speech }),
514
+ ...(record.thoughts === undefined
515
+ ? {}
516
+ : { thoughts: record.thoughts }),
517
+ }),
344
518
  });
345
519
  mine.started = true;
346
- for (const pcm of mine.early.splice(0))
520
+ // What the last press could not do is not this one's to show.
521
+ setError((last) => (last?.kind === "audio" ? null : last));
522
+ for (const pcm of mine.early.splice(0)) {
523
+ mine.bytes += pcm.byteLength;
347
524
  c.sendAudio(pcm);
525
+ }
348
526
  return true;
349
527
  },
350
528
  async stopRecording(stop = {}) {
351
529
  const mine = capture.current;
352
- const recorder = latest.current.audio;
353
530
  capture.current = null;
354
531
  setRecording(false);
355
- if (!mine || !recorder)
532
+ if (!mine)
356
533
  return null;
357
534
  if (!mine.started) {
358
535
  mine.cancelled = true;
359
536
  return null;
360
537
  }
361
- // The recorder's last samples arrive before it settles.
362
- await recorder.stopCapture();
538
+ // The recorder's last samples arrive before it settles. One that
539
+ // will not close is `error`; the recording still ends below.
540
+ await closeMic(() => mine.audio.stopCapture());
363
541
  mine.over = true;
364
542
  const c = current.current;
365
543
  if (!c)
366
544
  return notOpen;
367
545
  if (stop.discard) {
368
- c.cancel();
546
+ // The recording alone: `cancel()` here stopped the reply a
547
+ // dictation was meant to play over, and dropped every message
548
+ // queued — on an interruption too.
549
+ c.discardAudio();
369
550
  return null;
370
551
  }
371
552
  if (stop.transcribeOnly)
@@ -376,44 +557,96 @@ export function useAgent(target, options = {}) {
376
557
  async listen(listenOptions = {}) {
377
558
  const audio = latest.current.audio;
378
559
  const c = current.current ?? (await connected());
379
- if (!audio || !c || capture.current || handsFree.current)
560
+ if (!audio ||
561
+ !c ||
562
+ c.state === "closed" ||
563
+ capture.current ||
564
+ handsFree.current) {
380
565
  return false;
381
- handsFree.current = "starting";
382
- const outcome = await listenOn(c, audio, {
383
- ...listenOptions,
384
- onState(state) {
385
- setHearing(state === "hearing");
386
- if (state === "stopped")
387
- setListening(false);
388
- listenOptions.onState?.(state);
389
- },
390
- onBargeIn(frame) {
391
- hush();
392
- listenOptions.onBargeIn?.(frame);
393
- },
394
- });
395
- // Stopped, unmounted or redialled while it opened: given back.
396
- if (handsFree.current !== "starting" || current.current !== c) {
397
- if (outcome.ok)
398
- await outcome.listening.stop();
566
+ }
567
+ const mine = { engine: null };
568
+ handsFree.current = mine;
569
+ /** Still the hook's hands-free, on the conversation it was asked for. */
570
+ const wanted = () => handsFree.current === mine && current.current === c;
571
+ let outcome;
572
+ try {
573
+ outcome = await inLane(async () => {
574
+ // Turned off before its turn came: no microphone is opened.
575
+ if (!wanted())
576
+ return null;
577
+ const answer = await listenOn(c, audio, {
578
+ ...turnNow(listenOptions),
579
+ onState(state) {
580
+ // Only the engine this hook holds moves its state: one
581
+ // given back as it opened says `stopped` to nobody here.
582
+ if (handsFree.current === mine && mine.engine) {
583
+ setHearing(state === "hearing");
584
+ if (state === "stopped") {
585
+ // It stopped itself — the conversation closed, or the
586
+ // microphone did not open again after the device took
587
+ // the audio: the controls are free for the next
588
+ // `listen`, which this ref refused until the screen
589
+ // was left.
590
+ handsFree.current = null;
591
+ setListening(false);
592
+ if (c.state !== "closed") {
593
+ setError({
594
+ kind: "audio",
595
+ message: STOPPED_ITSELF,
596
+ error: null,
597
+ });
598
+ }
599
+ }
600
+ }
601
+ listenOptions.onState?.(state);
602
+ },
603
+ onBargeIn(frame) {
604
+ hush();
605
+ listenOptions.onBargeIn?.(frame);
606
+ },
607
+ });
608
+ if (!answer.ok || wanted())
609
+ return answer;
610
+ // Stopped, unmounted or redialled while it opened: given back
611
+ // here, in this call's turn, before the next opens it.
612
+ await answer.listening.stop();
613
+ return null;
614
+ });
615
+ }
616
+ catch (failure) {
617
+ // swallowed: it is the hook's `error`, the caller's to show.
618
+ if (handsFree.current !== mine)
619
+ return false;
620
+ handsFree.current = null;
621
+ setError({ kind: "audio", message: NOT_OPENED, error: failure });
399
622
  return false;
400
623
  }
401
- if (!outcome.ok) {
624
+ // Turned off, or the screen or the conversation left, meanwhile:
625
+ // nothing to say, and the `listen` after it has the hook's slot.
626
+ if (handsFree.current !== mine)
627
+ return false;
628
+ if (!outcome?.ok) {
402
629
  handsFree.current = null;
403
- setError({ kind: "audio", message: outcome.reason, error: null });
630
+ if (outcome) {
631
+ setError({ kind: "audio", message: outcome.reason, error: null });
632
+ }
404
633
  return false;
405
634
  }
406
- handsFree.current = outcome.listening;
635
+ mine.engine = outcome.listening;
407
636
  setListening(true);
637
+ // Why hands-free was refused is not left showing while half-duplex
638
+ // listens: the docs' own fallback did.
639
+ setError((last) => (last?.kind === "audio" ? null : last));
408
640
  return true;
409
641
  },
410
642
  async stopListening() {
411
- const free = handsFree.current;
643
+ const engine = handsFree.current?.engine;
644
+ // One still opening finds itself gone, and closes what it opened.
412
645
  handsFree.current = null;
413
646
  setListening(false);
414
647
  setHearing(false);
415
- if (free && free !== "starting")
416
- await free.stop();
648
+ if (engine)
649
+ await closeMic(() => engine.stop());
417
650
  },
418
651
  cancel() {
419
652
  hush();
@@ -423,16 +656,27 @@ export function useAgent(target, options = {}) {
423
656
  hush();
424
657
  current.current?.mute();
425
658
  },
426
- reconnect: () => current.current?.reconnect(),
659
+ setVolume(level) {
660
+ latest.current.audio?.setVolume?.(level);
661
+ },
662
+ reconnect() {
663
+ if (current.current)
664
+ current.current.reconnect();
665
+ // No conversation to ask: the open itself failed, and runs again.
666
+ else if (failedOpen.current)
667
+ setAttempt(tries.current + 1);
668
+ },
427
669
  end() {
428
670
  hush();
671
+ letGo();
429
672
  current.current?.end();
430
673
  },
431
674
  close() {
432
675
  hush();
676
+ letGo();
433
677
  current.current?.close();
434
678
  },
435
- }), [connected, hush]);
679
+ }), [connected, hush, inLane, closeMic, letGo, turnNow]);
436
680
  // The device took the audio, or gave it back: an open recording is
437
681
  // thrown away, its speaker cut off mid-sentence.
438
682
  const { stopRecording } = controls;
package/dist/use-facts.js CHANGED
@@ -9,7 +9,7 @@ export function useFacts(client) {
9
9
  for await (const fact of c.facts.list())
10
10
  facts.push(fact);
11
11
  return facts;
12
- });
12
+ }, c);
13
13
  const { set } = read;
14
14
  const forget = useCallback(async (id) => {
15
15
  await c.facts.delete(id);
@@ -5,7 +5,9 @@ import { useRead } from "./read.js";
5
5
  export function useMemories(params = {}, client) {
6
6
  const c = useClient(client);
7
7
  const { agent_id, category, session_id, limit, cursor } = params;
8
- const read = useRead(JSON.stringify(["memories", agent_id, category, session_id, limit, cursor]), () => c.memories.page({ agent_id, category, session_id, limit, cursor }));
8
+ const read = useRead(JSON.stringify(["memories", agent_id, category, session_id, limit, cursor]), () => c.memories.page({ agent_id, category, session_id, limit, cursor }),
9
+ // A filter is another list; a cursor, the same list's next page.
10
+ c, agent_id, category, session_id);
9
11
  const { set } = read;
10
12
  const forget = useCallback(async (id) => {
11
13
  await c.memories.delete(id);
@@ -6,10 +6,13 @@ export function useRelation(agentId, client) {
6
6
  const c = useClient(client);
7
7
  const live = useLive();
8
8
  const conversation = useSyncExternalStore(useCallback((fn) => live?.subscribe(fn) ?? (() => { }), [live]), () => live?.get(agentId) ?? null, () => null);
9
- const fromSocket = useSyncExternalStore(conversation ? (fn) => conversation.subscribe(fn) : none, () => conversation?.snapshot.relation ?? null, () => null);
9
+ // One function while the conversation is the same: a new one on each
10
+ // render was a subscription dropped and made again on each.
11
+ const watch = useCallback((fn) => conversation?.subscribe(fn) ?? none(), [conversation]);
12
+ const fromSocket = useSyncExternalStore(watch, () => conversation?.snapshot.relation ?? null, () => null);
10
13
  const read = useRead(conversation ? null : `relation:${agentId}`, () => c.relations
11
14
  .page({ agent_id: agentId, limit: 1 })
12
- .then((page) => page.data[0] ?? null));
15
+ .then((page) => page.data[0] ?? null), c, agentId);
13
16
  if (conversation) {
14
17
  return {
15
18
  data: fromSocket,
@@ -1,11 +1,11 @@
1
- import { useCallback, useEffect, useRef, useState } from "react";
1
+ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
2
2
  import { useClient } from "./provider.js";
3
3
  import { asPlatformError, useRead } from "./read.js";
4
4
  /** One page of the person's conversations, most recent first. */
5
5
  export function useSessions(params = {}, client) {
6
6
  const c = useClient(client);
7
7
  const { limit, cursor } = params;
8
- const read = useRead(`${limit ?? ""}:${cursor ?? ""}`, () => c.sessions.page({ limit, cursor }));
8
+ const read = useRead(`${limit ?? ""}:${cursor ?? ""}`, () => c.sessions.page({ limit, cursor }), c);
9
9
  return {
10
10
  data: read.data?.data ?? null,
11
11
  error: read.error,
@@ -18,48 +18,65 @@ export function useSessions(params = {}, client) {
18
18
  export function useSession(id, params = {}, client) {
19
19
  const c = useClient(client);
20
20
  const { limit } = params;
21
- const read = useRead(id === null ? null : `${id}:${limit ?? ""}`, () => c.sessions.get(id, { limit }));
21
+ const read = useRead(id === null ? null : `${id}:${limit ?? ""}`, () => c.sessions.get(id, { limit }), c, id);
22
22
  const [older, setOlder] = useState([]);
23
23
  const [cursor, setCursor] = useState(null);
24
24
  const [loadingOlder, setLoadingOlder] = useState(false);
25
25
  const [olderError, setOlderError] = useState(null);
26
26
  const page = useRef(0);
27
- // A new first page starts the transcript again.
27
+ /** The older page being read: a second ask for it is the same read. */
28
+ const reading = useRef(null);
29
+ // A new first page starts the transcript again — and an older page
30
+ // still being read is no longer its: `loading` must not wait on it.
28
31
  useEffect(() => {
29
32
  page.current += 1;
33
+ reading.current = null;
30
34
  setOlder([]);
31
35
  setOlderError(null);
36
+ setLoadingOlder(false);
32
37
  setCursor(read.data?.messages.next_cursor ?? null);
33
38
  }, [read.data]);
34
- const loadOlder = useCallback(async () => {
39
+ const loadOlder = useCallback(() => {
35
40
  if (id === null || cursor === null)
36
- return;
41
+ return Promise.resolve();
42
+ // A list's "reached the top" fires twice: both read the same cursor,
43
+ // and the same page was put in front twice.
44
+ if (reading.current)
45
+ return reading.current;
37
46
  const mine = page.current;
38
47
  setLoadingOlder(true);
39
- try {
40
- const { messages } = await c.sessions.get(id, { limit, cursor });
41
- if (mine !== page.current)
42
- return;
43
- setOlder((held) => [...messages.data, ...held]);
44
- setCursor(messages.next_cursor);
45
- setOlderError(null);
46
- }
47
- catch (failure) {
48
- // swallowed: it is the hook's `error`, the caller's to show.
49
- if (mine === page.current)
50
- setOlderError(asPlatformError(failure));
51
- }
52
- finally {
53
- if (mine === page.current)
54
- setLoadingOlder(false);
55
- }
48
+ const run = (async () => {
49
+ try {
50
+ const { messages } = await c.sessions.get(id, { limit, cursor });
51
+ if (mine !== page.current)
52
+ return;
53
+ setOlder((held) => [...messages.data, ...held]);
54
+ setCursor(messages.next_cursor);
55
+ setOlderError(null);
56
+ }
57
+ catch (failure) {
58
+ // swallowed: it is the hook's `error`, the caller's to show.
59
+ if (mine === page.current)
60
+ setOlderError(asPlatformError(failure));
61
+ }
62
+ finally {
63
+ if (mine === page.current) {
64
+ reading.current = null;
65
+ setLoadingOlder(false);
66
+ }
67
+ }
68
+ })();
69
+ reading.current = run;
70
+ return run;
56
71
  }, [c, id, limit, cursor]);
72
+ const latest = read.data?.messages.data;
73
+ const messages = useMemo(() => [...older, ...(latest ?? [])], [older, latest]);
57
74
  return {
58
75
  data: read.data,
59
76
  error: olderError ?? read.error,
60
77
  loading: read.loading || loadingOlder,
61
78
  refresh: read.refresh,
62
- messages: [...older, ...(read.data?.messages.data ?? [])],
79
+ messages,
63
80
  hasOlder: cursor !== null,
64
81
  loadOlder,
65
82
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lumavox/react",
3
- "version": "0.34.0",
3
+ "version": "0.35.1",
4
4
  "description": "React and React Native hooks for Lumavox agents: a conversation that keeps itself connected, sessions, memory and relations, over @lumavox/client.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -10,6 +10,19 @@
10
10
  "sideEffects": false,
11
11
  "main": "./dist/index.js",
12
12
  "types": "./dist/index.d.ts",
13
+ "homepage": "https://docs.lumavox.ai/sdks/react",
14
+ "keywords": [
15
+ "lumavox",
16
+ "voice",
17
+ "agents",
18
+ "react",
19
+ "react-native",
20
+ "hooks"
21
+ ],
22
+ "publishConfig": {
23
+ "access": "public",
24
+ "tag": "next"
25
+ },
13
26
  "exports": {
14
27
  ".": {
15
28
  "@ino/source": "./src/index.ts",
@@ -28,14 +41,13 @@
28
41
  "test:unit": "vitest run",
29
42
  "typecheck": "tsc --noEmit && tsc --noEmit -p test"
30
43
  },
31
- "dependencies": {
32
- "@lumavox/client": "0.34.0"
33
- },
34
44
  "peerDependencies": {
45
+ "@lumavox/client": "0.35.1",
35
46
  "react": ">=18"
36
47
  },
37
48
  "devDependencies": {
38
49
  "@biomejs/biome": "2.6.4",
50
+ "@lumavox/client": "0.35.1",
39
51
  "@testing-library/react": "^16.3.3",
40
52
  "@types/node": "^24",
41
53
  "@types/react": "^19",