Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import type { AsrEvent, AsrProvider, AudioTrace } from './types';
type BufferedChunk = {
chunk: ArrayBuffer;
trace?: AudioTrace;
};
/**
* BufferedAsrProvider decorates any AsrProvider so audio can be appended while
* the provider's start()/connect handshake is still in flight.
*
* Why this exists: capture and the ASR connection are started concurrently to
* hide connect latency, but several providers silently drop appendAudio calls
* until their handshake settles (e.g. a fallback provider whose appendAudio is
* a no-op until the inner provider is chosen). Every consumer that parallelises
* capture and connect would otherwise have to hand-roll the same buffering,
* replay-in-order, and abandon-mid-handshake logic — which is exactly the class
* of race bugs this wrapper removes:
*
* - appendAudio before the handshake settles is buffered locally and replayed
* in order once start() resolves, so nothing spoken during connect is lost.
* - stop() while the handshake is in flight does NOT block on it (a cancel must
* stay instant); it discards the buffer and tears the inner provider down as
* soon as the handshake settles, so a just-opened socket is not leaked until
* the server times it out.
* - A run abandoned mid-handshake (stop() before start() settled) is never
* revived: the settled handshake neither marks the provider ready nor replays
* buffered audio into a torn-down run.
* - flushAudio() waits for the in-flight handshake to settle first, so an early
* stop still submits the audio buffered during connect instead of stranding a
* short utterance as empty text.
*
* The wrapper is restartable: each start() begins a fresh run. A stale
* continuation from a previous run (an abandoned handshake that settles after
* the next run already started) is ignored via a run token, and the new run
* first waits for that handshake to settle and closes its connection before
* opening its own, so an abandoned socket never outlives the run switch.
*/
export class BufferedAsrProvider implements AsrProvider {
private readonly inner: AsrProvider;
private buffer: BufferedChunk[] = [];
private ready = false;
private aborted = false;
private startPromise: Promise<void> | null = null;
private startSettled = false;
private runToken = 0;
// True while a new run is draining a previous run's still-in-flight
// handshake (waiting for it to settle, then closing its connection). The
// teardown of that abandoned socket emits normal 'disconnected'/'error'
// events; forwarding them would make the consumer believe the NEW run's
// transport just died before its own socket even opened.
private drainingPriorRun = false;
constructor(inner: AsrProvider) {
this.inner = inner;
}
/**
* recover is only exposed when the inner provider currently exposes it: some
* providers assign recover dynamically (e.g. after a fallback chain picks its
* active candidate), and callers feature-detect with `typeof asr.recover`.
* Unconditionally defining it here would make a recovery attempt "succeed"
* as a no-op and mask a dead transport.
*/
get recover(): (() => Promise<void>) | undefined {
const innerRecover = this.inner.recover;
if (typeof innerRecover !== 'function') return undefined;
return () => innerRecover.call(this.inner);
}
start(): Promise<void> {
this.runToken += 1;
const token = this.runToken;
this.buffer = [];
this.ready = false;
this.aborted = false;
// A previous run's handshake may still be in flight (stop() during connect,
// immediately followed by a fresh start()). Its own continuation bails out
// on the token mismatch, so the new run must first wait for it to settle
// and close the connection it opened — otherwise the abandoned socket
// leaks until a server/client timeout instead of being torn down
// deterministically.
const priorStartPromise = this.startPromise && !this.startSettled ? this.startPromise : null;
this.startSettled = false;
this.startPromise = (async () => {
if (priorStartPromise) {
this.drainingPriorRun = true;
await priorStartPromise.catch(() => undefined);
await this.inner.stop().catch(() => undefined);
// On supersession, the newer run's continuation owns (and clears) the
// muting — it necessarily saw this still-unsettled promise as ITS prior.
if (token !== this.runToken) return;
this.drainingPriorRun = false;
}
try {
await this.inner.start();
} catch (error) {
if (token === this.runToken) {
this.startSettled = true;
this.buffer = [];
}
throw error;
}
if (token !== this.runToken) return;
if (this.aborted) {
// The run was abandoned while the handshake was in flight. The inner
// socket only just opened (stop()'s own inner.stop() ran before there
// was anything to close), so close it now instead of leaking the
// connection, and never replay buffered audio into a torn-down run.
//
// startSettled stays false until this teardown COMPLETES: a retry that
// starts while the abandoned stop is still in flight must treat this
// run as its drainable prior (and wait for it) — otherwise its fresh
// inner.start() would race the old close, which can reset the new
// socket on providers whose stop() awaits async teardown.
this.buffer = [];
await this.inner.stop().catch(() => undefined);
if (token === this.runToken) this.startSettled = true;
return;
}
this.startSettled = true;
this.ready = true;
const buffered = this.buffer;
this.buffer = [];
for (const entry of buffered) this.inner.appendAudio(entry.chunk, entry.trace);
})();
return this.startPromise;
}
appendAudio(chunk: ArrayBuffer, trace?: AudioTrace): void {
if (this.aborted) return;
if (this.ready) {
this.inner.appendAudio(chunk, trace);
return;
}
this.buffer.push({ chunk, trace });
}
async flushAudio(): Promise<void> {
// Wait for the in-flight handshake so audio buffered during connect is
// replayed (by the start() continuation) before the flush is issued.
if (this.startPromise) await this.startPromise.catch(() => undefined);
if (!this.ready || this.aborted) return;
await this.inner.flushAudio();
}
async stop(): Promise<void> {
this.aborted = true;
this.buffer = [];
// With the handshake still in flight, do NOT block on it — a cancel must
// return immediately. The start() continuation observes `aborted` when the
// handshake settles and tears the inner provider down there.
if (this.startPromise && !this.startSettled) return;
await this.inner.stop();
}
async dispose(): Promise<void> {
await this.inner.dispose?.();
}
onEvent(callback: (event: AsrEvent) => void): void {
this.inner.onEvent((event) => {
// Drop events emitted while draining a previous run's abandoned
// handshake (see drainingPriorRun) — they describe the old socket's
// teardown, not the current run's transport.
if (this.drainingPriorRun) return;
callback(event);
});
}
}