benchgo-plugin 0.0.0-stage → 0.0.2

package/voice/src/calls.mjs

@@ -0,0 +1,37 @@
+import { randomUUID } from 'node:crypto';
+import { VoiceError } from './config.mjs';
+
+const TTL = 45000, MAX_DURATION = 30 * 60000;
+const identity = (value, name) => { if (typeof value !== 'string' || !value || value.length > 200 || /[\u0000-\u001f]/u.test(value)) throw new VoiceError(`Invalid ${name}`); return value; };
+/** Process-local ownership only. Media cancellation never grants/revokes Agent permissions. */
+export class CallLeases {
+  constructor({ now = Date.now } = {}) { this.now = now; this.sessions = new Map(); }
+  public(lease) { const { timer, controller, ...value } = lease; return value; }
+  remove(lease) { clearTimeout(lease.timer); lease.controller.abort(); this.sessions.delete(lease.sessionId); }
+  schedule(lease) {
+    clearTimeout(lease.timer);
+    lease.timer = setTimeout(() => this.remove(lease), Math.max(0, Math.min(lease.expiresAt, lease.maxEndsAt) - this.now()));
+    lease.timer.unref?.();
+  }
+  purge() { for (const lease of this.sessions.values()) if (Math.min(lease.expiresAt, lease.maxEndsAt) <= this.now()) this.remove(lease); }
+  start(input) {
+    this.purge(); const sessionId = identity(input.sessionId, 'sessionId'), deviceId = identity(input.deviceId, 'deviceId');
+    const existing = this.sessions.get(sessionId);
+    if (existing) { if (existing.deviceId !== deviceId) throw new VoiceError('This conversation already has an active call on another device', 409); return this.public(existing); }
+    if (this.sessions.size >= 16) throw new VoiceError('Active call limit reached', 429);
+    const startedAt = this.now();
+    const lease = { callId: randomUUID(), sessionId, deviceId, startedAt, expiresAt: startedAt + TTL, maxEndsAt: startedAt + MAX_DURATION, controller: new AbortController() };
+    this.sessions.set(sessionId, lease); this.schedule(lease); return this.public(lease);
+  }
+  owned(input) {
+    this.purge();
+    const sessionId = identity(input.sessionId, 'sessionId'), deviceId = identity(input.deviceId, 'deviceId'), callId = identity(input.callId, 'callId');
+    const lease = this.sessions.get(sessionId);
+    if (!lease || lease.deviceId !== deviceId || lease.callId !== callId) throw new VoiceError('Voice call expired or belongs to another device', 409);
+    return lease;
+  }
+  heartbeat(input) { const lease = this.owned(input); lease.expiresAt = Math.min(this.now() + TTL, lease.maxEndsAt); this.schedule(lease); return this.public(lease); }
+  end(input) { const lease = this.owned(input); this.remove(lease); return { ended: true }; }
+  media(callId) { this.purge(); const lease = [...this.sessions.values()].find(value => value.callId === callId); if (!lease) throw new VoiceError('Voice call has expired', 409); return lease.controller.signal; }
+  clear() { for (const lease of this.sessions.values()) this.remove(lease); }
+}

package/voice/src/config.mjs

@@ -0,0 +1,139 @@
+import { mkdir, readFile, writeFile, rename, rm, chmod } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+
+export class VoiceError extends Error {
+  constructor(message, status = 400, code) { super(message); this.status = status; if (code) this.code = code; }
+}
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+// Portable multipart transcription is the default; native protocols are explicit.
+export const DEFAULT_TTS_SPEED = 1.2;
+const TTS_SPEED_MIN = 0.25, TTS_SPEED_MAX = 4;
+const defaults = () => ({ dictation: false, readAloud: false, call: false, asr: { baseURL: '', apiKey: '', model: 'stepaudio-2.5-asr', protocol: 'transcriptions-sse' }, tts: { baseURL: '', apiKey: '', model: 'stepaudio-2.5-tts', voice: '', speed: DEFAULT_TTS_SPEED } });
+const string = (value, label, limit) => {
+  if (typeof value !== 'string' || value.length > limit || /[\u0000-\u001f\u007f]/u.test(value)) throw new VoiceError(`Invalid ${label}`);
+  return value.trim();
+};
+function endpoint(value) {
+  value = string(value, 'baseURL', 2048);
+  if (!value) return '';
+  let url; try { url = new URL(value); } catch { throw new VoiceError('Invalid baseURL'); }
+  if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new VoiceError('baseURL must be an HTTP(S) API base without credentials, query or fragment');
+  return url.href.replace(/\/+$/u, '');
+}
+const sensitiveQuery = /api.?key|authorization|token|secret|password|credential|^key$|^bearer$/iu;
+/** Public routing metadata only: credentials belong exclusively in server headers. */
+export function validateRealtime(value, apiKey = '') {
+  if (!object(value) || Object.keys(value).some(key => !['url', 'query'].includes(key))) throw new VoiceError('Invalid realtime ASR configuration');
+  const result = { url: '', query: {} };
+  const parameter = (key, val) => {
+    if (!/^[a-zA-Z0-9_.~-]{1,80}$/u.test(key) || sensitiveQuery.test(key) || ['__proto__', 'prototype', 'constructor'].includes(key)) throw new VoiceError('Invalid realtime ASR query key');
+    const clean = string(val, 'realtime ASR query', 512);
+    if (apiKey && clean.includes(apiKey)) throw new VoiceError('Realtime ASR routing must not contain API credentials');
+    return clean;
+  };
+  if (value.url) {
+    const raw = string(value.url, 'realtime ASR URL', 2048);
+    let url; try { url = new URL(raw); } catch { throw new VoiceError('Invalid realtime ASR URL'); }
+    if (!['http:', 'https:', 'ws:', 'wss:'].includes(url.protocol) || url.username || url.password || url.hash) throw new VoiceError('Realtime ASR URL must be HTTP(S) or WS(S), without credentials or fragment');
+    for (const [key, val] of url.searchParams) parameter(key, val);
+    if (apiKey && decodeURIComponent(url.href).includes(apiKey)) throw new VoiceError('Realtime ASR routing must not contain API credentials');
+    result.url = url.href;
+  } else if (Object.hasOwn(value, 'url') && typeof value.url !== 'string') throw new VoiceError('Invalid realtime ASR URL');
+  if (Object.hasOwn(value, 'query')) {
+    if (!object(value.query) || Object.keys(value.query).length > 32) throw new VoiceError('Invalid realtime ASR query');
+    for (const [key, val] of Object.entries(value.query)) result.query[key] = parameter(key, val);
+  }
+  return result;
+}
+// Model IDs belong to the selected provider; an apparent alias may be a distinct route.
+export function normalizeTtsModel(model) {
+  return String(model || '').trim();
+}
+export function normalizeAsrModel(model) {
+  return String(model || '').trim();
+}
+export function isStepTtsModel(model) {
+  const value = normalizeTtsModel(model).toLowerCase();
+  return /^(?:stepaudio-(?:2\.5|3)-tts|stepfun-2\.5-tts|step-tts-(?:2|mini))$/u.test(value);
+}
+export function normalizeTtsSpeed(value) {
+  if (value === undefined) return DEFAULT_TTS_SPEED;
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < TTS_SPEED_MIN || value > TTS_SPEED_MAX || Math.round(value * 100) !== value * 100) throw new VoiceError('Invalid TTS speed');
+  return value;
+}
+export function updateConfig(current, patch) {
+  if (!object(patch)) throw new VoiceError('Expected config object');
+  if (Object.keys(patch).some(key => !['dictation', 'readAloud', 'call', 'asr', 'tts'].includes(key))) throw new VoiceError('Unknown config field');
+  const next = structuredClone(current);
+  if (next.tts && !Object.hasOwn(next.tts, 'speed')) next.tts.speed = DEFAULT_TTS_SPEED;
+  for (const key of ['dictation', 'readAloud', 'call']) if (Object.hasOwn(patch, key)) {
+    if (typeof patch[key] !== 'boolean') throw new VoiceError(`Invalid ${key}`);
+    next[key] = patch[key];
+  }
+  for (const kind of ['asr', 'tts']) if (Object.hasOwn(patch, kind)) {
+    if (!object(patch[kind])) throw new VoiceError(`Invalid ${kind}`);
+    for (const [key, value] of Object.entries(patch[kind])) {
+      // Read-only metadata may be round-tripped by settings forms.
+      if (['configured', 'apiKeyConfigured', 'apiKeyMasked'].includes(key)) continue;
+      if (!['providerId', 'baseURL', 'apiKey', 'model', 'protocol', ...(kind === 'tts' ? ['voice', 'speed'] : ['realtime'])].includes(key)) throw new VoiceError(`Unknown ${kind} field`);
+      if (key === 'realtime') { next.asr.realtime = validateRealtime(value); continue; }
+      if (kind === 'tts' && key === 'speed') { next.tts.speed = normalizeTtsSpeed(value); continue; }
+      if (key === 'protocol' && !(kind === 'tts' ? ['speech', 'step-speech'] : ['transcriptions', 'transcriptions-sse', 'mimo-sse', 'step-sse', 'step-websocket', 'openai-websocket']).includes(value)) throw new VoiceError(`Unknown ${kind.toUpperCase()} protocol`);
+      const normalized = key === 'baseURL' ? endpoint(value) : string(value, key, key === 'apiKey' ? 4096 : 200);
+      next[kind][key] = key === 'model' ? (kind === 'asr' ? normalizeAsrModel(normalized) : normalizeTtsModel(normalized)) : normalized;
+    }
+    const changedProvider = Object.hasOwn(patch[kind], 'providerId') && (current[kind].providerId || '') !== next[kind].providerId || Object.hasOwn(patch[kind], 'baseURL') && !next[kind].providerId && current[kind].baseURL !== next[kind].baseURL;
+    if (changedProvider) {
+      if (kind === 'asr' && !Object.hasOwn(patch.asr, 'realtime')) delete next.asr.realtime;
+      if (!Object.hasOwn(patch[kind], 'protocol')) next[kind].protocol = kind === 'asr' ? 'transcriptions-sse' : 'speech';
+      if (kind === 'tts' && !Object.hasOwn(patch.tts, 'voice')) next.tts.voice = '';
+    }
+    if (next[kind].providerId) { next[kind].apiKey = ''; next[kind].baseURL = ''; }
+    if (kind === 'asr' && next.asr.realtime) next.asr.realtime = validateRealtime(next.asr.realtime, next.asr.apiKey);
+  }
+  return next;
+}
+/** Upgrade pre-protocol settings once, rather than sending known speech models to an incompatible endpoint. */
+export function migrateLegacyConfig(value) {
+  const next = structuredClone(value);
+  if (next.asr?.model) next.asr.model = normalizeAsrModel(next.asr.model);
+  if (next.tts?.model) next.tts.model = normalizeTtsModel(next.tts.model);
+  if (next.asr && !Object.hasOwn(next.asr, 'protocol')) {
+    const model = String(next.asr.model || '').toLowerCase();
+    next.asr.protocol = /^stepaudio-.*-asr-stream$/u.test(model) ? 'step-websocket' : /^(?:mimo|stepaudio)-.*-asr(?:-max)?$/u.test(model) ? 'transcriptions-sse' : 'transcriptions';
+  }
+  if (next.tts && !Object.hasOwn(next.tts, 'protocol')) next.tts.protocol = isStepTtsModel(next.tts.model) ? 'step-speech' : 'speech';
+  return next;
+}
+export function publicConfig(config) {
+  return Object.fromEntries(Object.entries(config).map(([key, value]) => {
+    if (!['asr', 'tts'].includes(key)) return [key, value];
+    const { apiKey, ...safe } = value;
+    return [key, { ...safe, configured: !!((value.providerId || value.baseURL) && value.model), apiKeyConfigured: !!apiKey, apiKeyMasked: apiKey ? '••••••••' : '' }];
+  }));
+}
+export class VoiceConfig {
+  constructor({ dataDir = join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'voice') } = {}) {
+    this.directory = dataDir; this.path = join(dataDir, 'config.json'); this.value = defaults(); this.writes = Promise.resolve(); this.listeners = new Set();
+  }
+  async open() {
+    await mkdir(this.directory, { recursive: true, mode: 0o700 });
+    try { this.value = updateConfig(defaults(), migrateLegacyConfig(JSON.parse(await readFile(this.path, 'utf8')))); await chmod(this.path, 0o600); }
+    catch (error) { if (error.code !== 'ENOENT') throw new VoiceError('Voice configuration could not be loaded', 500); }
+    return this;
+  }
+  snapshot() { return publicConfig(this.value); }
+  subscribe(listener) { this.listeners.add(listener); return () => this.listeners.delete(listener); }
+  configure(patch) {
+    const operation = this.writes.then(async () => {
+      const next = updateConfig(this.value, patch);
+      const temp = `${this.path}.${randomUUID()}.tmp`;
+      try { await writeFile(temp, JSON.stringify(next, null, 2), { mode: 0o600 }); await rename(temp, this.path); }
+      finally { await rm(temp, { force: true }); }
+      this.value = next; for (const listener of this.listeners) listener(); return this.snapshot();
+    });
+    this.writes = operation.catch(() => {}); return operation;
+  }
+}

package/voice/src/media.mjs

@@ -0,0 +1,70 @@
+import { VoiceError, normalizeAsrModel } from './config.mjs';
+
+export const LIMITS = Object.freeze({ audioBytes: 2 * 1024 * 1024, audioSeconds: 15, jsonBytes: 32768, speechCharacters: 4000, speechBytes: 12 * 1024 * 1024, requestTimeout: 90000 });
+export async function readLimited(request, limit, signal = request.signal) {
+  if (Number(request.headers.get('content-length')) > limit) throw new VoiceError('Request is too large', 413);
+  if (!request.body) return new Uint8Array();
+  const reader = request.body.getReader(), chunks = []; let size = 0;
+  const abort = () => { reader.cancel().catch(() => {}); };
+  signal.addEventListener('abort', abort, { once: true }); if (signal.aborted) abort();
+  try {
+    while (true) {
+      signal.throwIfAborted();
+      const { done, value } = await reader.read(); signal.throwIfAborted(); if (done) break;
+      size += value.byteLength;
+      if (size > limit) { await reader.cancel(); throw new VoiceError('Request is too large', 413); }
+      chunks.push(value);
+    }
+  } finally { signal.removeEventListener('abort', abort); reader.releaseLock(); }
+  const output = new Uint8Array(size); let offset = 0;
+  for (const chunk of chunks) { output.set(chunk, offset); offset += chunk.byteLength; }
+  return output;
+}
+export async function readJson(request) {
+  if (!request.headers.get('content-type')?.toLowerCase().startsWith('application/json')) throw new VoiceError('Expected application/json', 415);
+  let value; try { value = JSON.parse(new TextDecoder().decode(await readLimited(request, LIMITS.jsonBytes))); }
+  catch (error) { if (error instanceof VoiceError || request.signal.aborted) throw error; throw new VoiceError('Invalid JSON'); }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new VoiceError('Expected JSON object');
+  return value;
+}
+export async function upstreamFailure(response, kind, signal) {
+  let code = '';
+  try {
+    if (response.headers.get('content-type')?.includes('application/json')) {
+      const raw = await readLimited(new Request('http://voice.internal', { method: 'POST', body: response.body, duplex: 'half', signal }), 8192);
+      const body = JSON.parse(new TextDecoder().decode(raw));
+      // Only a bounded machine code is safe to expose. Upstream messages may echo credentials or audio.
+      const candidate = body.error?.code; if (typeof candidate === 'string' && /^[a-zA-Z0-9_.-]{1,80}$/u.test(candidate)) code = candidate;
+    }
+  } catch {} finally { await response.body?.cancel().catch(() => {}); }
+  return new VoiceError(kind + ' service rejected the request (' + response.status + ')' + (code ? '; ' + code : ''), 502, code || kind.toLowerCase() + '_http_' + response.status);
+}
+export function validateWav(bytes) {
+  const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (buffer.length < 44 || buffer.toString('ascii', 0, 4) !== 'RIFF' || buffer.toString('ascii', 8, 12) !== 'WAVE' || buffer.readUInt32LE(4) + 8 !== buffer.length) throw new VoiceError('Expected a complete PCM WAV file');
+  let format, data;
+  for (let offset = 12; offset + 8 <= buffer.length;) {
+    const id = buffer.toString('ascii', offset, offset + 4), length = buffer.readUInt32LE(offset + 4), start = offset + 8;
+    if (start + length > buffer.length) throw new VoiceError('Malformed WAV chunk');
+    if (id === 'fmt ') {
+      if (length < 16) throw new VoiceError('Malformed WAV format');
+      format = { codec: buffer.readUInt16LE(start), channels: buffer.readUInt16LE(start + 2), rate: buffer.readUInt32LE(start + 4), alignment: buffer.readUInt16LE(start + 12), bits: buffer.readUInt16LE(start + 14) };
+    }
+    if (id === 'data') data = length;
+    offset = start + length + (length % 2);
+  }
+  if (!format || !data || format.codec !== 1 || format.channels !== 1 || format.bits !== 16 || format.alignment !== 2 || ![16000, 22050, 24000, 44100, 48000].includes(format.rate) || data % 2) throw new VoiceError('Audio must be mono PCM16 WAV (16–48 kHz)');
+  if (data / (format.rate * 2) > LIMITS.audioSeconds) throw new VoiceError('Audio segment exceeds 15 seconds', 413);
+  return format;
+}
+export async function transcribe(fetcher, config, bytes, signal) {
+  const body = new FormData();
+  body.set('file', new Blob([bytes], { type: 'audio/wav' }), 'segment.wav'); body.set('model', normalizeAsrModel(config.model)); body.set('response_format', 'json');
+  const upstream = await fetcher(`${config.baseURL}/audio/transcriptions`, { method: 'POST', headers: config.apiKey ? { authorization: `Bearer ${config.apiKey}` } : {}, body, signal, redirect: 'error' });
+  if (!upstream.ok) throw await upstreamFailure(upstream, 'ASR', signal);
+  const raw = await readLimited(new Request('http://voice.internal', { method: 'POST', body: upstream.body, duplex: 'half', signal }), 65536);
+  let result; try { result = JSON.parse(new TextDecoder().decode(raw)); } catch { throw new VoiceError('ASR service returned invalid JSON', 502); }
+  if (typeof result.text !== 'string' || result.text.length > 20000) throw new VoiceError('ASR service returned invalid transcription', 502);
+  signal.throwIfAborted();
+  return { text: result.text.trim() };
+}

package/voice/src/plugin.mjs

@@ -0,0 +1,10 @@
+import { VoiceConfig } from './config.mjs';
+import { mountWeb } from './web.mjs';
+
+export const name = 'voice';
+export async function apply(ctx, config = {}) {
+  const store = await new VoiceConfig(config).open();
+  ctx.provide('voice', store);
+  ctx.effect(() => () => store.writes);
+  ctx.inject(['connection'], child => { mountWeb(child, store, { providers: config.providers }); });
+}

package/voice/src/realtime-protocols.mjs

@@ -0,0 +1,30 @@
+import { VoiceError } from './config.mjs';
+
+// Wire formats depend on the selected protocol, never a provider identity.
+const protocols = {
+  'step-websocket': {
+    path: '/realtime/asr/stream', query: {}, requiresItemId: false,
+    ready: type => type === 'session.created' || type === 'session.updated',
+    session: model => ({ audio: { input: {
+      format: { type: 'pcm', codec: 'pcm_s16le', rate: 24000, bits: 16, channel: 1 },
+      transcription: { model, language: 'zh', full_rerun_on_commit: true, enable_itn: true },
+      turn_detection: null,
+    } } }),
+    partial: (event, previous) => typeof event.text === 'string' ? event.text : previous,
+  },
+  'openai-websocket': {
+    path: '/realtime', query: { intent: 'transcription' }, requiresItemId: true,
+    // Initial session.created does not acknowledge our transcription settings.
+    ready: type => type === 'session.updated',
+    session: model => ({ type: 'transcription', audio: { input: {
+      format: { type: 'audio/pcm', rate: 24000 }, transcription: { model }, turn_detection: null,
+    } } }),
+    partial: (event, previous) => typeof event.delta === 'string' ? previous + event.delta : previous,
+  },
+};
+
+export function realtimeProtocol(protocol = 'openai-websocket') {
+  const adapter = Object.hasOwn(protocols, protocol) ? protocols[protocol] : undefined;
+  if (!adapter) throw new VoiceError('Select a supported native realtime ASR protocol', 400);
+  return adapter;
+}

package/voice/src/realtime-socket.mjs

@@ -0,0 +1,86 @@
+import { randomBytes } from 'node:crypto';
+import { VoiceError } from './config.mjs';
+
+const integer = value => Number.isSafeInteger(value) && value >= 0 && value <= 0xffffffff;
+const reason = error => error instanceof VoiceError ? error.message : 'Realtime voice transport failed';
+/** Carrier auth admits the owner/device; a one-use ticket binds its ASR lease. */
+export function createRealtimeSockets(realtime) {
+  const tickets = new Map(), sockets = new Set();
+  let disposed = false;
+  const issue = (id, callId) => {
+    for (const [key, value] of tickets) if (value.expires < Date.now()) tickets.delete(key);
+    const ticket = randomBytes(32).toString('base64url');
+    tickets.set(ticket, { id, callId, expires: Date.now() + 10000 });
+    return ticket;
+  };
+  const accept = ws => {
+    if (disposed) { ws.terminate(); return; }
+    sockets.add(ws);
+    let session, reader, epoch = 0, resetting = false, ended = false;
+    const send = value => {
+      if (ended || ws.readyState !== 1) return;
+      if (ws.bufferedAmount > 65536) { ws.terminate(); return; }
+      ws.send(JSON.stringify(value));
+    };
+    const stop = () => {
+      if (ended) return; ended = true; clearTimeout(attachTimer); sockets.delete(ws);
+      void reader?.cancel().catch(() => {});
+      if (session) realtime.close(session.id);
+    };
+    const fail = error => { send({ type: 'error', error: reason(error) }); ws.close(1008, 'Voice transport rejected'); stop(); };
+    const attachTimer = setTimeout(() => { ws.terminate(); stop(); }, 10000); attachTimer.unref?.();
+    ws.on('error', stop); ws.on('close', stop);
+    ws.on('message', (raw, binary) => {
+      try {
+        if (ended) return;
+        if (binary) {
+          if (!session || raw.length < 14 || raw.length > 972 || raw.length % 2) throw new VoiceError('Invalid PCM voice frame');
+          const generation = raw.readUInt32LE(0), utteranceId = raw.readUInt32LE(4), sequence = raw.readUInt32LE(8);
+          if (generation !== epoch || resetting) return;
+          const accepted = realtime.append(session.id, session.callId, raw.subarray(12), utteranceId);
+          send({ type: 'ack', epoch, sequence, accepted: accepted !== false });
+          return;
+        }
+        if (raw.length > 2048) throw new VoiceError('Voice control message too large');
+        const input = JSON.parse(String(raw));
+        if (!input || typeof input !== 'object' || Array.isArray(input)) throw new VoiceError('Invalid voice control');
+        if (!session) {
+          if (input.type !== 'attach' || typeof input.ticket !== 'string') throw new VoiceError('Attach the voice session first');
+          const ticket = tickets.get(input.ticket); tickets.delete(input.ticket);
+          if (!ticket || ticket.expires < Date.now() || ticket.id !== input.id || ticket.callId !== (input.callId || '')) throw new VoiceError('Voice connection ticket expired', 401);
+          session = realtime.get(ticket.id, ticket.callId);
+          const emit = session.emit; session.emit = event => emit({ ...event, epoch });
+          reader = realtime.events(session.id, session.callId).getReader(); clearTimeout(attachTimer);
+          const previous = session.onClose;
+          session.onClose = () => { previous?.(); if (!ended) { send({ type: 'closed' }); ws.close(1000); stop(); } };
+          send({ type: 'ready', epoch });
+          void (async () => {
+            try {
+              while (!ended) {
+                const { value, done } = await reader.read(); if (done) break;
+                const event = JSON.parse(new TextDecoder().decode(value));
+                if (!resetting && event.epoch === epoch) send(event);
+              }
+            } catch (error) { if (!ended) fail(error); }
+          })();
+          return;
+        }
+        if (!integer(input.epoch)) throw new VoiceError('Invalid voice generation');
+        if (input.type === 'clear') {
+          if (input.epoch <= epoch) return;
+          if (resetting) throw new VoiceError('Voice reset already pending');
+          epoch = input.epoch; resetting = true;
+          void realtime.reset(session.id, session.callId).then(() => { resetting = false; send({ type: 'ready', epoch }); }, error => { if (!ended) fail(error); });
+          return;
+        }
+        if (input.epoch !== epoch) return;
+        if (resetting) throw new VoiceError('Voice reset is not ready');
+        if (input.type !== 'commit' || !integer(input.utteranceId) || !input.utteranceId) throw new VoiceError('Invalid voice control');
+        if (!session.bytes) { send({ type: 'final', epoch, utteranceId: input.utteranceId, text: '' }); return; }
+        realtime.commit(session.id, session.callId, input.utteranceId);
+      } catch (error) { fail(error); }
+    });
+  };
+  const clear = () => { tickets.clear(); for (const ws of sockets) ws.terminate(); sockets.clear(); };
+  return { issue, accept, clear, dispose() { disposed = true; clear(); } };
+}

package/voice/src/realtime.mjs

@@ -0,0 +1,130 @@
+import { randomUUID } from 'node:crypto';
+import WebSocket from 'ws';
+import { VoiceError, validateRealtime } from './config.mjs';
+import { realtimeProtocol } from './realtime-protocols.mjs';
+
+export function realtimeEndpoint(config) {
+  const adapter = realtimeProtocol(config.protocol);
+  const settings = validateRealtime(config.realtime || {}, config.apiKey || '');
+  let endpoint;
+  try { endpoint = new URL(settings.url || String(config.baseURL || '').replace(/\/+$/u, '') + adapter.path); }
+  catch { throw new VoiceError('Invalid realtime ASR endpoint'); }
+  if (!['https:', 'http:', 'wss:', 'ws:'].includes(endpoint.protocol)) throw new VoiceError('Invalid realtime ASR endpoint');
+  endpoint.protocol = endpoint.protocol === 'https:' ? 'wss:' : endpoint.protocol === 'http:' ? 'ws:' : endpoint.protocol;
+  const supplied = new URLSearchParams(endpoint.search); endpoint.search = '';
+  // A complete explicit URL owns its query string; protocol defaults apply only
+  // when the endpoint is derived from the provider base URL.
+  if (!settings.url) for (const [key, value] of Object.entries(adapter.query)) endpoint.searchParams.set(key, value);
+  for (const [key, value] of supplied) endpoint.searchParams.set(key, value);
+  for (const [key, value] of Object.entries(settings.query)) endpoint.searchParams.set(key, value.replaceAll('{model}', String(config.model || '')));
+  // Validate expanded values too, so credentials never escape into URL logs.
+  validateRealtime({ url: endpoint.href, query: {} }, config.apiKey || '');
+  return endpoint;
+}
+
+/** One authenticated media socket owns each native ASR session. */
+export class RealtimeASR {
+  constructor({ socket = (url, options) => new WebSocket(url, options) } = {}) { this.socket = socket; this.sessions = new Map(); }
+  async connect(s) {
+    const epoch = ++s.socketEpoch;
+    s.ready = false; s.bytes = 0; s.utterance = 0; s.committing = false; s.text = ''; s.itemId = ''; s.retiredItems = new Set();
+    const adapter = realtimeProtocol(s.config.protocol);
+    const endpoint = realtimeEndpoint(s.config);
+    const ws = this.socket(endpoint.href, { headers: s.config.apiKey ? { authorization: 'Bearer ' + s.config.apiKey } : {}, followRedirects: false, maxPayload: 131072, handshakeTimeout: 10000 });
+    s.ws = ws; const current = () => !s.finished && s.socketEpoch === epoch;
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      const timer = setTimeout(() => finish(new VoiceError('Realtime ASR handshake timed out', 502)), 12000); timer.unref?.();
+      const finish = error => { if (settled) return; settled = true; clearTimeout(timer); s.signal.removeEventListener('abort', abort); if (s.cancelConnect === cancel) s.cancelConnect = null; error ? reject(error) : resolve(); };
+      const cancel = () => finish(s.signal.aborted ? new DOMException('Aborted', 'AbortError') : new VoiceError('Realtime ASR connection cancelled', 409)); s.cancelConnect = cancel;
+      const abort = () => finish(new DOMException('Aborted', 'AbortError')); s.signal.addEventListener('abort', abort, { once: true });
+      ws.on('open', () => {
+        if (!current()) return;
+        try { ws.send(JSON.stringify({ event_id: randomUUID(), type: 'session.update', session: adapter.session(s.config.model) })); }
+        catch { finish(new VoiceError('Realtime ASR session initialization failed', 502)); this.close(s.id); }
+      });
+      ws.on('message', raw => {
+        if (!current()) return;
+        let event; try { event = JSON.parse(String(raw)); if (!event || typeof event !== 'object' || Array.isArray(event)) throw Error(); } catch { finish(new VoiceError('Invalid realtime ASR event', 502)); s.emit({ type: 'error', error: 'Invalid realtime ASR event' }); this.close(s.id); return; }
+        if (adapter.ready(event.type)) { s.ready = true; finish(); return; }
+        if (event.type === 'error') {
+          const code = typeof event.error?.code === 'string' && /^[a-zA-Z0-9_.-]{1,80}$/u.test(event.error.code) ? event.error.code : 'upstream_error';
+          const error = new VoiceError('Realtime ASR service rejected the session (' + code + ')', 502, code); finish(error); s.emit({ type: 'error', error: error.message, code }); this.close(s.id); return;
+        }
+        // Epochs fence discarded sockets; item IDs fence delayed same-socket events.
+        if (!s.ready || !s.utterance) return;
+        const transcriptEvent = ['conversation.item.input_audio_transcription.delta', 'conversation.item.input_audio_transcription.completed', 'conversation.item.input_audio_transcription.failed'].includes(event.type);
+        if (event.type !== 'input_audio_buffer.committed' && !transcriptEvent) return;
+        if ((event.type === 'input_audio_buffer.committed' || event.type === 'conversation.item.input_audio_transcription.completed') && !s.committing) return;
+        const itemId = typeof event.item_id === 'string' && event.item_id.length <= 512 ? event.item_id : '';
+        if ((adapter.requiresItemId && !itemId) || (itemId && (s.retiredItems.has(itemId) || (s.itemId && itemId !== s.itemId)))) return;
+        if (itemId) s.itemId = itemId;
+        if (event.type === 'conversation.item.input_audio_transcription.delta') {
+          const text = adapter.partial(event, s.text);
+          if (text.length > 20000) { this.close(s.id); return; }
+          if (text !== s.text) { s.text = text; s.emit({ type: 'partial', text, utteranceId: s.utterance }); }
+        }
+        if (event.type === 'conversation.item.input_audio_transcription.completed') {
+          if (!s.committing) return;
+          if (typeof event.transcript !== 'string' || event.transcript.length > 20000) { this.close(s.id); return; }
+          s.emit({ type: 'final', text: event.transcript, utteranceId: s.utterance });
+          if (s.itemId) s.retiredItems.add(s.itemId);
+          s.committing = false; s.bytes = 0; s.utterance = 0; s.itemId = ''; s.text = '';
+          if (s.retiredItems.size > 4096) this.close(s.id);
+        }
+        if (event.type === 'conversation.item.input_audio_transcription.failed') {
+          s.emit({ type: 'error', error: 'Realtime ASR transcription failed', code: 'asr_transcription_failed' }); this.close(s.id);
+        }
+      });
+      ws.on('error', () => { if (!current()) return; finish(new VoiceError('Realtime ASR connection failed', 502)); s.emit({ type: 'error', error: 'Realtime ASR connection failed' }); this.close(s.id); });
+      ws.on('unexpected-response', (_request, response) => {
+        if (!current()) return; response.resume?.(); const status = Number(response.statusCode) || 502;
+        finish(new VoiceError('Realtime ASR handshake rejected (' + status + '); verify the configured realtime URL and protocol', 502, 'asr_handshake_' + status)); this.close(s.id);
+      });
+      ws.on('close', () => { if (!current()) return; finish(new VoiceError('Realtime ASR connection closed before ready', 502)); s.emit({ type: 'error', error: 'Realtime ASR connection closed' }); this.close(s.id); });
+      if (s.signal.aborted) abort();
+    });
+    s.signal.throwIfAborted();
+  }
+  async open(config, signal, callId = '') {
+    signal.throwIfAborted();
+    if (this.sessions.size >= 2) throw new VoiceError('Too many active realtime recognizers', 429);
+    const id = randomUUID(), s = { id, config, signal, callId, socketEpoch: 0, queue: [], consumer: null, finished: false, attached: false };
+    this.sessions.set(id, s);
+    s.emit = event => {
+      if (s.finished) return; const data = JSON.stringify(event) + String.fromCharCode(10);
+      if (s.consumer) { if (s.consumer.desiredSize <= 0) { this.close(id); return; } try { s.consumer.enqueue(new TextEncoder().encode(data)); } catch { this.close(id); } }
+      else { s.queue.push(data); if (s.queue.length > 128) this.close(id); }
+    };
+    s.abort = () => this.close(id); signal.addEventListener('abort', s.abort, { once: true });
+    s.timer = setTimeout(() => this.close(id), 30 * 60 * 1000); s.timer.unref?.();
+    try {
+      await this.connect(s); s.attachTimer = setTimeout(() => this.close(id), 10000); s.attachTimer.unref?.(); return id;
+    } catch (error) { this.close(id); throw error; }
+  }
+  get(id, callId) { const s = this.sessions.get(id); if (!s || s.finished || s.callId !== callId) throw new VoiceError('Realtime ASR session expired', 409); return s; }
+  events(id, callId) {
+    const s = this.get(id, callId); if (s.attached) throw new VoiceError('Realtime ASR stream already attached', 409); s.attached = true; clearTimeout(s.attachTimer);
+    return new ReadableStream({ start: controller => { s.consumer = controller; for (const data of s.queue.splice(0)) controller.enqueue(new TextEncoder().encode(data)); }, cancel: () => this.close(id) }, { highWaterMark: 64 });
+  }
+  append(id, callId, bytes, utteranceId) {
+    const s = this.get(id, callId); if (!s.ready) throw new VoiceError('Realtime ASR is resetting; wait for ready', 409);
+    if (!Number.isSafeInteger(utteranceId) || utteranceId < 1) throw new VoiceError('Invalid utterance');
+    if (!bytes.length || bytes.length % 2 || bytes.length > 24000) throw new VoiceError('Expected 1–12000 PCM16 samples');
+    if (s.committing || s.bytes && s.utterance !== utteranceId) throw new VoiceError('Previous utterance has not completed', 409);
+    if (s.bytes + bytes.length > 1440000) throw new VoiceError('Realtime ASR audio limit exceeded', 429);
+    // Congestion drops a frame instead of growing stale upstream audio.
+    if (s.ws.bufferedAmount > 12800) return false;
+    s.utterance = utteranceId; s.bytes += bytes.length; s.ws.send(JSON.stringify({ event_id: randomUUID(), type: 'input_audio_buffer.append', audio: Buffer.from(bytes).toString('base64') }));
+  }
+  commit(id, callId, utteranceId) { const s = this.get(id, callId); if (!s.ready || s.utterance !== utteranceId || !s.bytes || s.committing) throw new VoiceError('No pending ASR utterance', 409); s.committing = true; s.ws.send(JSON.stringify({ event_id: randomUUID(), type: 'input_audio_buffer.commit' })); }
+  async reset(id, callId) {
+    const s = this.get(id, callId); if (s.resetting) return s.resetting;
+    // Replace the connection to fence late events without vendor-specific clear acknowledgements.
+    ++s.socketEpoch; s.ready = false; const old = s.ws; try { old.close(); } catch {}
+    s.queue.length = 0; s.resetting = this.connect(s).catch(error => { s.emit({ type: 'error', error: error instanceof VoiceError ? error.message : 'Realtime ASR reset failed' }); this.close(id); throw error; }).finally(() => { s.resetting = null; });
+    return s.resetting;
+  }
+  close(id) { const s = this.sessions.get(id); if (!s) return; s.finished = true; s.cancelConnect?.(); ++s.socketEpoch; this.sessions.delete(id); clearTimeout(s.timer); clearTimeout(s.attachTimer); s.signal.removeEventListener('abort', s.abort); try { s.consumer?.close(); } catch {} try { s.ws?.close(); } catch {} s.onClose?.(); }
+  clear() { for (const id of [...this.sessions.keys()]) this.close(id); }
+}

package/voice/src/tts.mjs

@@ -0,0 +1,16 @@
+import { VoiceError, isStepTtsModel, normalizeTtsModel, normalizeTtsSpeed } from './config.mjs';
+
+/** Keep vendor extensions out of the standard OpenAI speech request. */
+export function speechRequest(config, text) {
+  const protocol = config.protocol || (isStepTtsModel(config.model) ? 'step-speech' : 'speech');
+  if (!['speech', 'step-speech'].includes(protocol)) throw new VoiceError('Unknown TTS protocol');
+  const step = protocol === 'step-speech';
+  return {
+    model: normalizeTtsModel(config.model),
+    voice: config.voice || (step ? 'cixingnansheng' : 'alloy'),
+    input: text,
+    response_format: 'pcm',
+    speed: normalizeTtsSpeed(config.speed),
+    ...(step ? { sample_rate: 24000, stream: true } : {}),
+  };
+}