@micdrop/server 2.9.0 → 2.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1,7 +1,7 @@
1
1
  import { EventEmitter } from 'eventemitter3';
2
2
  import { Writable, PassThrough, Readable } from 'stream';
3
3
  import { z } from 'zod';
4
- import WebSocket, { WebSocket as WebSocket$1 } from 'ws';
4
+ import WebSocket, { WebSocket as WebSocket$1, RawData, ClientOptions } from 'ws';
5
5
 
6
6
  declare class Logger {
7
7
  name: string;
@@ -153,11 +153,34 @@ declare abstract class Agent<Options extends AgentOptions = AgentOptions, Events
153
153
  logger?: Logger;
154
154
  conversation: MicdropConversation;
155
155
  tools: Tool[];
156
+ private answerController?;
157
+ /**
158
+ * @deprecated Read the signal given to `generateAnswer` instead. Still
159
+ * bumped by every answer and every cancel, for agents written before it.
160
+ */
156
161
  protected answerCount: number;
157
- protected answering: boolean;
158
162
  constructor(options: Options);
159
- protected abstract generateAnswer(stream: PassThrough): Promise<void>;
160
- abstract cancel(): void;
163
+ /**
164
+ * Writes the answer to the stream, and records it in the conversation.
165
+ *
166
+ * The signal is aborted when the answer is cancelled or replaced by the next
167
+ * one. From then on nothing may be written nor recorded: hand it to the
168
+ * request, and check it before a retry and before adding a message.
169
+ */
170
+ protected abstract generateAnswer(stream: PassThrough, signal: AbortSignal): Promise<void>;
171
+ /** Whether an answer is being generated */
172
+ get isAnswering(): boolean;
173
+ /** @deprecated Read `isAnswering` instead */
174
+ protected get answering(): boolean;
175
+ /** @deprecated The answer is over once its stream ends or it is cancelled */
176
+ protected set answering(_value: boolean);
177
+ /**
178
+ * Stops the answer being generated, by aborting its signal.
179
+ *
180
+ * An agent overriding it to stop more than the signal does calls
181
+ * `super.cancel()`.
182
+ */
183
+ cancel(): void;
161
184
  answer(): Readable;
162
185
  addUserMessage(text: string, metadata?: MicdropAnswerMetadata): void;
163
186
  addAssistantMessage(text: string, metadata?: MicdropAnswerMetadata): void;
@@ -207,7 +230,7 @@ declare class FallbackAgent extends Agent {
207
230
  message: string;
208
231
  metadata: MicdropAnswerMetadata | undefined;
209
232
  };
210
- protected generateAnswer(stream: PassThrough): Promise<void>;
233
+ protected generateAnswer(stream: PassThrough, signal: AbortSignal): Promise<void>;
211
234
  cancel(): void;
212
235
  destroy(): void;
213
236
  private pipeAnswer;
@@ -223,7 +246,6 @@ declare class MockAgent extends Agent {
223
246
  private i;
224
247
  constructor();
225
248
  protected generateAnswer(stream: PassThrough): Promise<void>;
226
- cancel(): void;
227
249
  }
228
250
 
229
251
  /** What a classifier reads: a text, or JSON with named fields */
@@ -496,11 +518,16 @@ declare class FallbackSTT extends STT {
496
518
  private readonly options;
497
519
  private stt;
498
520
  private sttIndex;
521
+ private pending;
499
522
  constructor(options: FallbackSTTOptions);
500
523
  transcribe(audioStream: Readable): void;
501
524
  destroy(): void;
502
525
  private startNextSTT;
503
526
  private onTranscript;
527
+ /**
528
+ * Hands every utterance still waiting to the next STT, one stream each so
529
+ * each gets its own transcript. One still being spoken keeps going there.
530
+ */
504
531
  private onFailed;
505
532
  }
506
533
 
@@ -523,19 +550,29 @@ declare class FallbackTTS extends TTS {
523
550
  private readonly options;
524
551
  private tts;
525
552
  private ttsIndex;
553
+ private current?;
526
554
  constructor(options: FallbackTTSOptions);
527
555
  speak(textStream: Readable): void;
528
556
  cancel(): void;
529
557
  destroy(): void;
530
558
  private startNextTTS;
531
559
  private onAudio;
560
+ /**
561
+ * Hands the unspoken text to the next TTS. An utterance whose text is still
562
+ * being written goes on there, so its end is spoken too.
563
+ */
532
564
  private onFailed;
533
565
  }
534
566
 
567
+ /**
568
+ * Plays the same recorded chunks for any answer, to run a call without a
569
+ * voice provider. The files hold raw PCM 16 bits at 16 kHz.
570
+ */
535
571
  declare class MockTTS extends TTS {
536
572
  private audioFilePaths;
573
+ private generation;
537
574
  constructor(audioFilePaths: string[]);
538
- speak(textStream: Readable): PassThrough;
575
+ speak(textStream: Readable): void;
539
576
  cancel(): void;
540
577
  }
541
578
 
@@ -724,6 +761,8 @@ declare class MicdropServer extends EventEmitter<MicdropServerEvents> {
724
761
  logger?: Logger;
725
762
  private startTime;
726
763
  private lastMessageSpeeched?;
764
+ private cancelRound;
765
+ private assistantMessages;
727
766
  private ownConversation;
728
767
  private operationQueue;
729
768
  private isProcessingQueue;
@@ -731,6 +770,7 @@ declare class MicdropServer extends EventEmitter<MicdropServerEvents> {
731
770
  private userSpeechChunks;
732
771
  private turnComplete?;
733
772
  private heldTurnTimer?;
773
+ private turnRound;
734
774
  constructor(socket: WebSocket$1, config: MicdropConfig);
735
775
  /** Everything said so far, whether an agent or the server keeps it */
736
776
  get conversation(): MicdropConversation;
@@ -772,7 +812,14 @@ declare class MicdropServer extends EventEmitter<MicdropServerEvents> {
772
812
  private sendFirstMessage;
773
813
  answer(): void;
774
814
  private _answer;
775
- /** Sends the answer to the client as it is written, ahead of the voice */
815
+ /**
816
+ * Sends the answer to the client as it is written, ahead of the voice.
817
+ *
818
+ * The stream reaches here a moment after the agent wrote it, so the agent
819
+ * can record the complete message first, which the client then shows. A
820
+ * partial answer arriving after it would show the answer twice, so the
821
+ * forwarding stops once the message is sent.
822
+ */
776
823
  private forwardPartialAnswer;
777
824
  /**
778
825
  * Classifies the turn that just ended, with the one before, and keeps the
@@ -849,12 +896,162 @@ declare class SharedInstances<T> {
849
896
  * instead of loading the model twice.
850
897
  */
851
898
  load(key: unknown, create: () => Promise<T>): Promise<T>;
899
+ /** The instance for this key, loaded or being loaded, without loading it. */
900
+ get(key: unknown): Promise<T> | undefined;
852
901
  /** Whether an instance is loaded, or being loaded, for this key. */
853
902
  has(key: unknown): boolean;
903
+ /**
904
+ * Forgets the instance for this key, so the next call loads a new one. For
905
+ * an instance that broke, a crashed worker for instance. Releasing what it
906
+ * holds is left to the caller.
907
+ */
908
+ delete(key: unknown): void;
854
909
  /** Drops every instance, so the next call loads again. */
855
910
  clear(): void;
856
911
  }
857
912
 
913
+ /**
914
+ * Where a {@link ReconnectingSocket} stands.
915
+ *
916
+ * - `idle`: not connected yet, `connect()` has not been called
917
+ * - `connecting`: an attempt is under way, the first one or a retry
918
+ * - `open`: connected, and done with its handshake if it has one
919
+ * - `reconnecting`: the connection dropped, a new attempt waits for its delay
920
+ * - `failed`: every retry failed, `connect()` starts over
921
+ * - `destroyed`: closed for good
922
+ */
923
+ type ReconnectingSocketStatus = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'failed' | 'destroyed';
924
+ interface ReconnectingSocketOptions {
925
+ /**
926
+ * Address to connect to, or a function giving it for each attempt, for a
927
+ * session URL or a token that has to be fresh.
928
+ */
929
+ url: string | (() => string | Promise<string>);
930
+ /** Options of the `ws` client, headers included */
931
+ clientOptions?: ClientOptions;
932
+ /** How long an attempt may take, handshake included, 5000 ms by default */
933
+ connectionTimeout?: number;
934
+ /** How long to wait before a new attempt, 1000 ms by default */
935
+ retryDelay?: number;
936
+ /** How many attempts in a row may fail before giving up, 3 by default */
937
+ maxRetry?: number;
938
+ /**
939
+ * Sets the session up before the connection counts as open, for a protocol
940
+ * that takes nothing else until then. See {@link ReconnectingSocketHandshake}.
941
+ */
942
+ handshake?: ReconnectingSocketHandshake;
943
+ /** Sends a message on a regular basis, to keep an idle connection open */
944
+ keepAlive?: {
945
+ /** Interval between two messages, in milliseconds */
946
+ interval: number;
947
+ message: string | (() => string);
948
+ };
949
+ /** Receives the log lines, the `log` method of the owner usually */
950
+ log?: (...message: any[]) => void;
951
+ }
952
+ /**
953
+ * What a connection does between the socket opening and the session being
954
+ * ready.
955
+ *
956
+ * Everything runs in the tick of the message it reads, so the connection is
957
+ * open before the next message arrives and none is lost in between.
958
+ */
959
+ interface ReconnectingSocketHandshake {
960
+ /** Sends what opens the session, as soon as the socket opens */
961
+ start?(socket: WebSocket): void;
962
+ /**
963
+ * Reads the messages that come before the session is ready, which are not
964
+ * emitted as `Message`, and returns true on the one saying it is. Throwing
965
+ * fails the attempt, for a session the server refused.
966
+ *
967
+ * Without it, the connection opens right after `start`, and proves itself
968
+ * like one without a handshake: by a first message, or by staying open.
969
+ */
970
+ read?(data: RawData, isBinary: boolean): boolean;
971
+ }
972
+ interface ReconnectingSocketEvents {
973
+ /** The status changed */
974
+ StatusChange: [ReconnectingSocketStatus];
975
+ /**
976
+ * The connection is open. A reconnection is the moment to send again what
977
+ * the previous connection did not finish.
978
+ */
979
+ Open: [{
980
+ reconnected: boolean;
981
+ }];
982
+ Message: [RawData, boolean];
983
+ /** The connection dropped, `reconnecting` or `failed` follows */
984
+ Close: [number, string];
985
+ /** Every retry failed */
986
+ Failed: [Error];
987
+ }
988
+ /**
989
+ * A WebSocket to a provider that reconnects on its own.
990
+ *
991
+ * Every connection a provider holds goes through the same states, and they
992
+ * live here, in one place: one attempt at a time, a failure counted once
993
+ * whatever the socket reports about it, a retry budget, and a `ready()` that
994
+ * settles whatever happens. A socket left behind by a reconnection is silenced,
995
+ * so it never acts on the one that replaced it.
996
+ *
997
+ * The owner keeps what belongs to its protocol: what to send again on
998
+ * `Open`, and what the messages mean.
999
+ */
1000
+ declare class ReconnectingSocket extends EventEmitter<ReconnectingSocketEvents> {
1001
+ private readonly options;
1002
+ private _status;
1003
+ private socket?;
1004
+ private everOpened;
1005
+ private retryCount;
1006
+ private proofTimer?;
1007
+ private attemptId;
1008
+ private retryTimer?;
1009
+ private keepAliveTimer?;
1010
+ private waiters;
1011
+ constructor(options: ReconnectingSocketOptions);
1012
+ get status(): ReconnectingSocketStatus;
1013
+ /** Whether a message sent now goes out */
1014
+ get isOpen(): boolean;
1015
+ /**
1016
+ * Opens the connection. Called again after `failed`, it starts over with a
1017
+ * full retry budget, and does nothing in any other status.
1018
+ */
1019
+ connect(): void;
1020
+ /**
1021
+ * Waits for the connection to be open.
1022
+ * @returns True once open, false if it failed or was destroyed meanwhile
1023
+ */
1024
+ ready(): Promise<boolean>;
1025
+ /**
1026
+ * Sends a message if the connection is open
1027
+ * @returns False when it did not go out
1028
+ */
1029
+ send(data: string | Buffer): boolean;
1030
+ /**
1031
+ * Drops the connection and opens a new one right away, for a provider that
1032
+ * can only stop what it is doing by closing. It costs no retry, and the new
1033
+ * connection is not a reconnection.
1034
+ */
1035
+ restart(): void;
1036
+ /** Closes the connection for good */
1037
+ destroy(): void;
1038
+ private attempt;
1039
+ private onOpen;
1040
+ /** The connection works, the retry budget is whole again */
1041
+ private prove;
1042
+ private clearProofTimer;
1043
+ private onAttemptFailed;
1044
+ private scheduleRetry;
1045
+ /** Lets go of the current socket, which will never be heard from again */
1046
+ private drop;
1047
+ private startKeepAlive;
1048
+ private stopKeepAlive;
1049
+ private clearRetryTimer;
1050
+ private settleWaiters;
1051
+ private setStatus;
1052
+ private log;
1053
+ }
1054
+
858
1055
  declare function waitForParams<CallParams>(socket: WebSocket$1, validate: (params: any) => CallParams): Promise<CallParams>;
859
1056
 
860
- export { AUTO_END_CALL_PROMPT, AUTO_END_CALL_TOOL_NAME, AUTO_IGNORE_USER_NOISE_PROMPT, AUTO_IGNORE_USER_NOISE_TOOL_NAME, AUTO_SEMANTIC_TURN_PROMPT, AUTO_SEMANTIC_TURN_TOOL_NAME, Agent, type AgentEvents, type AgentOptions, type AudioMessage, Classifier, type ClassifierEvents, type ClassifierInput, type DeepPartial, type ExtractJsonOptions, type ExtractOptions, type ExtractTagOptions, FallbackAgent, type FallbackAgentOptions, FallbackSTT, type FallbackSTTOptions, FallbackTTS, type FallbackTTSOptions, Logger, type MicdropAnswerMetadata, type MicdropCallSummary, type MicdropClassification, type MicdropClassifierOptions, MicdropClientCommands, type MicdropConfig, type MicdropConversation, type MicdropConversationItem, type MicdropConversationMessage, type MicdropConversationToolCall, type MicdropConversationToolResult, MicdropError, MicdropErrorCode, MicdropRecorder, type MicdropRecorderEvents, MicdropServer, MicdropServerCommands, type MicdropServerEvents, type MicdropToolCall, type MicdropTurnInput, MockAgent, MockSTT, MockTTS, Pcm16Resampler, Realtime, type RealtimeEvents, type RealtimeOptions, STT, type STTEvents, SentenceSplitter, SentenceTTS, SharedInstances, TTS, type TTSEvents, type Tool, type TurnDetector, currentTurn, float32ToPcm16, getTurnClassification, handleError, pcm16ToFloat32, turnInput, waitForParams };
1057
+ export { AUTO_END_CALL_PROMPT, AUTO_END_CALL_TOOL_NAME, AUTO_IGNORE_USER_NOISE_PROMPT, AUTO_IGNORE_USER_NOISE_TOOL_NAME, AUTO_SEMANTIC_TURN_PROMPT, AUTO_SEMANTIC_TURN_TOOL_NAME, Agent, type AgentEvents, type AgentOptions, type AudioMessage, Classifier, type ClassifierEvents, type ClassifierInput, type DeepPartial, type ExtractJsonOptions, type ExtractOptions, type ExtractTagOptions, FallbackAgent, type FallbackAgentOptions, FallbackSTT, type FallbackSTTOptions, FallbackTTS, type FallbackTTSOptions, Logger, type MicdropAnswerMetadata, type MicdropCallSummary, type MicdropClassification, type MicdropClassifierOptions, MicdropClientCommands, type MicdropConfig, type MicdropConversation, type MicdropConversationItem, type MicdropConversationMessage, type MicdropConversationToolCall, type MicdropConversationToolResult, MicdropError, MicdropErrorCode, MicdropRecorder, type MicdropRecorderEvents, MicdropServer, MicdropServerCommands, type MicdropServerEvents, type MicdropToolCall, type MicdropTurnInput, MockAgent, MockSTT, MockTTS, Pcm16Resampler, Realtime, type RealtimeEvents, type RealtimeOptions, ReconnectingSocket, type ReconnectingSocketEvents, type ReconnectingSocketHandshake, type ReconnectingSocketOptions, type ReconnectingSocketStatus, STT, type STTEvents, SentenceSplitter, SentenceTTS, SharedInstances, TTS, type TTSEvents, type Tool, type TurnDetector, currentTurn, float32ToPcm16, getTurnClassification, handleError, pcm16ToFloat32, turnInput, waitForParams };
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import { EventEmitter } from 'eventemitter3';
2
2
  import { Writable, PassThrough, Readable } from 'stream';
3
3
  import { z } from 'zod';
4
- import WebSocket, { WebSocket as WebSocket$1 } from 'ws';
4
+ import WebSocket, { WebSocket as WebSocket$1, RawData, ClientOptions } from 'ws';
5
5
 
6
6
  declare class Logger {
7
7
  name: string;
@@ -153,11 +153,34 @@ declare abstract class Agent<Options extends AgentOptions = AgentOptions, Events
153
153
  logger?: Logger;
154
154
  conversation: MicdropConversation;
155
155
  tools: Tool[];
156
+ private answerController?;
157
+ /**
158
+ * @deprecated Read the signal given to `generateAnswer` instead. Still
159
+ * bumped by every answer and every cancel, for agents written before it.
160
+ */
156
161
  protected answerCount: number;
157
- protected answering: boolean;
158
162
  constructor(options: Options);
159
- protected abstract generateAnswer(stream: PassThrough): Promise<void>;
160
- abstract cancel(): void;
163
+ /**
164
+ * Writes the answer to the stream, and records it in the conversation.
165
+ *
166
+ * The signal is aborted when the answer is cancelled or replaced by the next
167
+ * one. From then on nothing may be written nor recorded: hand it to the
168
+ * request, and check it before a retry and before adding a message.
169
+ */
170
+ protected abstract generateAnswer(stream: PassThrough, signal: AbortSignal): Promise<void>;
171
+ /** Whether an answer is being generated */
172
+ get isAnswering(): boolean;
173
+ /** @deprecated Read `isAnswering` instead */
174
+ protected get answering(): boolean;
175
+ /** @deprecated The answer is over once its stream ends or it is cancelled */
176
+ protected set answering(_value: boolean);
177
+ /**
178
+ * Stops the answer being generated, by aborting its signal.
179
+ *
180
+ * An agent overriding it to stop more than the signal does calls
181
+ * `super.cancel()`.
182
+ */
183
+ cancel(): void;
161
184
  answer(): Readable;
162
185
  addUserMessage(text: string, metadata?: MicdropAnswerMetadata): void;
163
186
  addAssistantMessage(text: string, metadata?: MicdropAnswerMetadata): void;
@@ -207,7 +230,7 @@ declare class FallbackAgent extends Agent {
207
230
  message: string;
208
231
  metadata: MicdropAnswerMetadata | undefined;
209
232
  };
210
- protected generateAnswer(stream: PassThrough): Promise<void>;
233
+ protected generateAnswer(stream: PassThrough, signal: AbortSignal): Promise<void>;
211
234
  cancel(): void;
212
235
  destroy(): void;
213
236
  private pipeAnswer;
@@ -223,7 +246,6 @@ declare class MockAgent extends Agent {
223
246
  private i;
224
247
  constructor();
225
248
  protected generateAnswer(stream: PassThrough): Promise<void>;
226
- cancel(): void;
227
249
  }
228
250
 
229
251
  /** What a classifier reads: a text, or JSON with named fields */
@@ -496,11 +518,16 @@ declare class FallbackSTT extends STT {
496
518
  private readonly options;
497
519
  private stt;
498
520
  private sttIndex;
521
+ private pending;
499
522
  constructor(options: FallbackSTTOptions);
500
523
  transcribe(audioStream: Readable): void;
501
524
  destroy(): void;
502
525
  private startNextSTT;
503
526
  private onTranscript;
527
+ /**
528
+ * Hands every utterance still waiting to the next STT, one stream each so
529
+ * each gets its own transcript. One still being spoken keeps going there.
530
+ */
504
531
  private onFailed;
505
532
  }
506
533
 
@@ -523,19 +550,29 @@ declare class FallbackTTS extends TTS {
523
550
  private readonly options;
524
551
  private tts;
525
552
  private ttsIndex;
553
+ private current?;
526
554
  constructor(options: FallbackTTSOptions);
527
555
  speak(textStream: Readable): void;
528
556
  cancel(): void;
529
557
  destroy(): void;
530
558
  private startNextTTS;
531
559
  private onAudio;
560
+ /**
561
+ * Hands the unspoken text to the next TTS. An utterance whose text is still
562
+ * being written goes on there, so its end is spoken too.
563
+ */
532
564
  private onFailed;
533
565
  }
534
566
 
567
+ /**
568
+ * Plays the same recorded chunks for any answer, to run a call without a
569
+ * voice provider. The files hold raw PCM 16 bits at 16 kHz.
570
+ */
535
571
  declare class MockTTS extends TTS {
536
572
  private audioFilePaths;
573
+ private generation;
537
574
  constructor(audioFilePaths: string[]);
538
- speak(textStream: Readable): PassThrough;
575
+ speak(textStream: Readable): void;
539
576
  cancel(): void;
540
577
  }
541
578
 
@@ -724,6 +761,8 @@ declare class MicdropServer extends EventEmitter<MicdropServerEvents> {
724
761
  logger?: Logger;
725
762
  private startTime;
726
763
  private lastMessageSpeeched?;
764
+ private cancelRound;
765
+ private assistantMessages;
727
766
  private ownConversation;
728
767
  private operationQueue;
729
768
  private isProcessingQueue;
@@ -731,6 +770,7 @@ declare class MicdropServer extends EventEmitter<MicdropServerEvents> {
731
770
  private userSpeechChunks;
732
771
  private turnComplete?;
733
772
  private heldTurnTimer?;
773
+ private turnRound;
734
774
  constructor(socket: WebSocket$1, config: MicdropConfig);
735
775
  /** Everything said so far, whether an agent or the server keeps it */
736
776
  get conversation(): MicdropConversation;
@@ -772,7 +812,14 @@ declare class MicdropServer extends EventEmitter<MicdropServerEvents> {
772
812
  private sendFirstMessage;
773
813
  answer(): void;
774
814
  private _answer;
775
- /** Sends the answer to the client as it is written, ahead of the voice */
815
+ /**
816
+ * Sends the answer to the client as it is written, ahead of the voice.
817
+ *
818
+ * The stream reaches here a moment after the agent wrote it, so the agent
819
+ * can record the complete message first, which the client then shows. A
820
+ * partial answer arriving after it would show the answer twice, so the
821
+ * forwarding stops once the message is sent.
822
+ */
776
823
  private forwardPartialAnswer;
777
824
  /**
778
825
  * Classifies the turn that just ended, with the one before, and keeps the
@@ -849,12 +896,162 @@ declare class SharedInstances<T> {
849
896
  * instead of loading the model twice.
850
897
  */
851
898
  load(key: unknown, create: () => Promise<T>): Promise<T>;
899
+ /** The instance for this key, loaded or being loaded, without loading it. */
900
+ get(key: unknown): Promise<T> | undefined;
852
901
  /** Whether an instance is loaded, or being loaded, for this key. */
853
902
  has(key: unknown): boolean;
903
+ /**
904
+ * Forgets the instance for this key, so the next call loads a new one. For
905
+ * an instance that broke, a crashed worker for instance. Releasing what it
906
+ * holds is left to the caller.
907
+ */
908
+ delete(key: unknown): void;
854
909
  /** Drops every instance, so the next call loads again. */
855
910
  clear(): void;
856
911
  }
857
912
 
913
+ /**
914
+ * Where a {@link ReconnectingSocket} stands.
915
+ *
916
+ * - `idle`: not connected yet, `connect()` has not been called
917
+ * - `connecting`: an attempt is under way, the first one or a retry
918
+ * - `open`: connected, and done with its handshake if it has one
919
+ * - `reconnecting`: the connection dropped, a new attempt waits for its delay
920
+ * - `failed`: every retry failed, `connect()` starts over
921
+ * - `destroyed`: closed for good
922
+ */
923
+ type ReconnectingSocketStatus = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'failed' | 'destroyed';
924
+ interface ReconnectingSocketOptions {
925
+ /**
926
+ * Address to connect to, or a function giving it for each attempt, for a
927
+ * session URL or a token that has to be fresh.
928
+ */
929
+ url: string | (() => string | Promise<string>);
930
+ /** Options of the `ws` client, headers included */
931
+ clientOptions?: ClientOptions;
932
+ /** How long an attempt may take, handshake included, 5000 ms by default */
933
+ connectionTimeout?: number;
934
+ /** How long to wait before a new attempt, 1000 ms by default */
935
+ retryDelay?: number;
936
+ /** How many attempts in a row may fail before giving up, 3 by default */
937
+ maxRetry?: number;
938
+ /**
939
+ * Sets the session up before the connection counts as open, for a protocol
940
+ * that takes nothing else until then. See {@link ReconnectingSocketHandshake}.
941
+ */
942
+ handshake?: ReconnectingSocketHandshake;
943
+ /** Sends a message on a regular basis, to keep an idle connection open */
944
+ keepAlive?: {
945
+ /** Interval between two messages, in milliseconds */
946
+ interval: number;
947
+ message: string | (() => string);
948
+ };
949
+ /** Receives the log lines, the `log` method of the owner usually */
950
+ log?: (...message: any[]) => void;
951
+ }
952
+ /**
953
+ * What a connection does between the socket opening and the session being
954
+ * ready.
955
+ *
956
+ * Everything runs in the tick of the message it reads, so the connection is
957
+ * open before the next message arrives and none is lost in between.
958
+ */
959
+ interface ReconnectingSocketHandshake {
960
+ /** Sends what opens the session, as soon as the socket opens */
961
+ start?(socket: WebSocket): void;
962
+ /**
963
+ * Reads the messages that come before the session is ready, which are not
964
+ * emitted as `Message`, and returns true on the one saying it is. Throwing
965
+ * fails the attempt, for a session the server refused.
966
+ *
967
+ * Without it, the connection opens right after `start`, and proves itself
968
+ * like one without a handshake: by a first message, or by staying open.
969
+ */
970
+ read?(data: RawData, isBinary: boolean): boolean;
971
+ }
972
+ interface ReconnectingSocketEvents {
973
+ /** The status changed */
974
+ StatusChange: [ReconnectingSocketStatus];
975
+ /**
976
+ * The connection is open. A reconnection is the moment to send again what
977
+ * the previous connection did not finish.
978
+ */
979
+ Open: [{
980
+ reconnected: boolean;
981
+ }];
982
+ Message: [RawData, boolean];
983
+ /** The connection dropped, `reconnecting` or `failed` follows */
984
+ Close: [number, string];
985
+ /** Every retry failed */
986
+ Failed: [Error];
987
+ }
988
+ /**
989
+ * A WebSocket to a provider that reconnects on its own.
990
+ *
991
+ * Every connection a provider holds goes through the same states, and they
992
+ * live here, in one place: one attempt at a time, a failure counted once
993
+ * whatever the socket reports about it, a retry budget, and a `ready()` that
994
+ * settles whatever happens. A socket left behind by a reconnection is silenced,
995
+ * so it never acts on the one that replaced it.
996
+ *
997
+ * The owner keeps what belongs to its protocol: what to send again on
998
+ * `Open`, and what the messages mean.
999
+ */
1000
+ declare class ReconnectingSocket extends EventEmitter<ReconnectingSocketEvents> {
1001
+ private readonly options;
1002
+ private _status;
1003
+ private socket?;
1004
+ private everOpened;
1005
+ private retryCount;
1006
+ private proofTimer?;
1007
+ private attemptId;
1008
+ private retryTimer?;
1009
+ private keepAliveTimer?;
1010
+ private waiters;
1011
+ constructor(options: ReconnectingSocketOptions);
1012
+ get status(): ReconnectingSocketStatus;
1013
+ /** Whether a message sent now goes out */
1014
+ get isOpen(): boolean;
1015
+ /**
1016
+ * Opens the connection. Called again after `failed`, it starts over with a
1017
+ * full retry budget, and does nothing in any other status.
1018
+ */
1019
+ connect(): void;
1020
+ /**
1021
+ * Waits for the connection to be open.
1022
+ * @returns True once open, false if it failed or was destroyed meanwhile
1023
+ */
1024
+ ready(): Promise<boolean>;
1025
+ /**
1026
+ * Sends a message if the connection is open
1027
+ * @returns False when it did not go out
1028
+ */
1029
+ send(data: string | Buffer): boolean;
1030
+ /**
1031
+ * Drops the connection and opens a new one right away, for a provider that
1032
+ * can only stop what it is doing by closing. It costs no retry, and the new
1033
+ * connection is not a reconnection.
1034
+ */
1035
+ restart(): void;
1036
+ /** Closes the connection for good */
1037
+ destroy(): void;
1038
+ private attempt;
1039
+ private onOpen;
1040
+ /** The connection works, the retry budget is whole again */
1041
+ private prove;
1042
+ private clearProofTimer;
1043
+ private onAttemptFailed;
1044
+ private scheduleRetry;
1045
+ /** Lets go of the current socket, which will never be heard from again */
1046
+ private drop;
1047
+ private startKeepAlive;
1048
+ private stopKeepAlive;
1049
+ private clearRetryTimer;
1050
+ private settleWaiters;
1051
+ private setStatus;
1052
+ private log;
1053
+ }
1054
+
858
1055
  declare function waitForParams<CallParams>(socket: WebSocket$1, validate: (params: any) => CallParams): Promise<CallParams>;
859
1056
 
860
- export { AUTO_END_CALL_PROMPT, AUTO_END_CALL_TOOL_NAME, AUTO_IGNORE_USER_NOISE_PROMPT, AUTO_IGNORE_USER_NOISE_TOOL_NAME, AUTO_SEMANTIC_TURN_PROMPT, AUTO_SEMANTIC_TURN_TOOL_NAME, Agent, type AgentEvents, type AgentOptions, type AudioMessage, Classifier, type ClassifierEvents, type ClassifierInput, type DeepPartial, type ExtractJsonOptions, type ExtractOptions, type ExtractTagOptions, FallbackAgent, type FallbackAgentOptions, FallbackSTT, type FallbackSTTOptions, FallbackTTS, type FallbackTTSOptions, Logger, type MicdropAnswerMetadata, type MicdropCallSummary, type MicdropClassification, type MicdropClassifierOptions, MicdropClientCommands, type MicdropConfig, type MicdropConversation, type MicdropConversationItem, type MicdropConversationMessage, type MicdropConversationToolCall, type MicdropConversationToolResult, MicdropError, MicdropErrorCode, MicdropRecorder, type MicdropRecorderEvents, MicdropServer, MicdropServerCommands, type MicdropServerEvents, type MicdropToolCall, type MicdropTurnInput, MockAgent, MockSTT, MockTTS, Pcm16Resampler, Realtime, type RealtimeEvents, type RealtimeOptions, STT, type STTEvents, SentenceSplitter, SentenceTTS, SharedInstances, TTS, type TTSEvents, type Tool, type TurnDetector, currentTurn, float32ToPcm16, getTurnClassification, handleError, pcm16ToFloat32, turnInput, waitForParams };
1057
+ export { AUTO_END_CALL_PROMPT, AUTO_END_CALL_TOOL_NAME, AUTO_IGNORE_USER_NOISE_PROMPT, AUTO_IGNORE_USER_NOISE_TOOL_NAME, AUTO_SEMANTIC_TURN_PROMPT, AUTO_SEMANTIC_TURN_TOOL_NAME, Agent, type AgentEvents, type AgentOptions, type AudioMessage, Classifier, type ClassifierEvents, type ClassifierInput, type DeepPartial, type ExtractJsonOptions, type ExtractOptions, type ExtractTagOptions, FallbackAgent, type FallbackAgentOptions, FallbackSTT, type FallbackSTTOptions, FallbackTTS, type FallbackTTSOptions, Logger, type MicdropAnswerMetadata, type MicdropCallSummary, type MicdropClassification, type MicdropClassifierOptions, MicdropClientCommands, type MicdropConfig, type MicdropConversation, type MicdropConversationItem, type MicdropConversationMessage, type MicdropConversationToolCall, type MicdropConversationToolResult, MicdropError, MicdropErrorCode, MicdropRecorder, type MicdropRecorderEvents, MicdropServer, MicdropServerCommands, type MicdropServerEvents, type MicdropToolCall, type MicdropTurnInput, MockAgent, MockSTT, MockTTS, Pcm16Resampler, Realtime, type RealtimeEvents, type RealtimeOptions, ReconnectingSocket, type ReconnectingSocketEvents, type ReconnectingSocketHandshake, type ReconnectingSocketOptions, type ReconnectingSocketStatus, STT, type STTEvents, SentenceSplitter, SentenceTTS, SharedInstances, TTS, type TTSEvents, type Tool, type TurnDetector, currentTurn, float32ToPcm16, getTurnClassification, handleError, pcm16ToFloat32, turnInput, waitForParams };