@dialt/sdk 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.24.0
+
+- `DialtClient` is now the canonical browser client name; `ConverseClient` remains as a deprecated source-compatible alias.
+- New sessions send `mode.kind: 'dialt'`; legacy `converse` input is still accepted and normalized.
+
 ## 0.23.0
 
 - The package is now published as `@dialt/sdk`; `@trelis/converse` is deprecated.

package/README.md

@@ -12,7 +12,7 @@ Keep your persistent `ck_…` API key on your backend. Exchange it for a scoped
 with `POST /api/v1/session-keys`, then connect from a user gesture:
 
 ```js
-import { ConverseClient } from '@dialt/sdk';
+import { DialtClient } from '@dialt/sdk';
 
 const credential = await fetch('/voice/session', {
   method: 'POST',
@@ -22,11 +22,11 @@ const credential = await fetch('/voice/session', {
   return response.json();
 });
 
-const client = new ConverseClient({
+const client = new DialtClient({
   url: 'wss://dialt.com/ws',
   sessionId: credential.session_id,
   apiKey: credential.api_key,
-  mode: { kind: 'converse' },
+  mode: { kind: 'dialt' },
 });
 
 startButton.addEventListener('click', async () => {
@@ -113,7 +113,7 @@ token. To preserve the same bounded resume opportunity across a full page reload
 opaque state in tab-scoped storage and import it into the replacement client:
 
 ```js
-const storageKey = 'converse-resume-state';
+const storageKey = 'dialt-resume-state';
 const clientOptions = {
   url: 'wss://dialt.com/ws',
   sessionId: credential.session_id,
@@ -128,7 +128,7 @@ try {
   sessionStorage.removeItem(storageKey);
 }
 
-const client = new ConverseClient(clientOptions);
+const client = new DialtClient(clientOptions);
 if (savedResumeState !== null) {
   try {
     client.importResumeState(savedResumeState);
@@ -159,11 +159,11 @@ Text sessions use the ordinary Dialt model, instructions, tools and events witho
 microphone or audio pipeline:
 
 ```js
-const textClient = new ConverseClient({
+const textClient = new DialtClient({
   url: 'wss://dialt.com/ws',
   sessionId: credential.session_id,
   apiKey: credential.api_key,
-  mode: { kind: 'converse', modality: 'text' },
+  mode: { kind: 'dialt', modality: 'text' },
 });
 await textClient.connect();
 textClient.sendText('What is the weather like?');
@@ -199,7 +199,7 @@ arrives), `"long"` for agent or batch jobs; leave it out and Dialt learns from o
 
 ```js
 mode: {
-  kind: "converse",
+  kind: "dialt",
   tools: [{
     name: "lookup_order",
     description: "Look up an order by ID.",
@@ -216,7 +216,7 @@ anything the caller should not wait on — declare the tool as a background job:
 
 ```js
 mode: {
-  kind: "converse",
+  kind: "dialt",
   tools: [{
     name: "run_task",
     description: "Run a long coding task and report when done.",
@@ -271,7 +271,7 @@ an explicit user request to cancel pending work; hosts should stop that call pro
 Experimental: the API is stable, but this transport is newly shipped and still being hardened on
 real networks; `ws` remains the default and recommended fallback.
 
-Pass `transport: 'webrtc'` to `ConverseClient` to carry the call over WebRTC (UDP) instead of the
+Pass `transport: 'webrtc'` to `DialtClient` to carry the call over WebRTC (UDP) instead of the
 default WebSocket — more resilient to jitter and packet loss on weak networks. `ws` remains the
 default. Safari/WebKit falls back to `ws` automatically. See the
 [browser guide's WebRTC section](https://dialt.com/docs/api/browser/#webrtc).
@@ -284,7 +284,7 @@ Dialt service, its models, or its server-side implementation.
 ### Ambience: background music and the thinking sound
 
 ```js
-const client = new ConverseClient({ url, sessionId, apiKey, mode, ambience: 'thinking' });
+const client = new DialtClient({ url, sessionId, apiKey, mode, ambience: 'thinking' });
 client.setAmbience('continuous');   // switch live; 'off' | 'thinking' | 'continuous'
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dialt/sdk",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "type": "module",
   "description": "Browser SDK for the Dialt realtime voice and text API",
   "license": "Apache-2.0",

package/src/ambience.js

@@ -385,7 +385,7 @@ export class AmbienceBed {
 // --- controller ------------------------------------------------------------------------------
 
 /** Drives one AmbienceBed on the client's player from the session's events. Owned by
- *  ConverseClient (its `ambience` option); apps interact through `client.setAmbience(mode)`.
+ *  DialtClient (its `ambience` option); apps interact through `client.setAmbience(mode)`.
  *
  *  Holds facts only - mode, whether a reply has played this session, whether Dialt is working
  *  and whether the thinking threshold has elapsed - and derives the bed's envelope target from

package/src/index.js

@@ -95,7 +95,7 @@ function sendOneShotFrame(kind, frame, { url, WebSocketImpl = globalThis.WebSock
 }
 
 // Post-session feedback (thumbs + optional comment + device/browser tags). The server files it
-// next to the session's recording, so pass the ConverseClient's sessionId.
+// next to the session's recording, so pass the DialtClient's sessionId.
 export function sendFeedback({ url, sessionId, rating, text, device, browser, apiKey,
   WebSocketImpl, timeoutMs } = {}) {
   if (!url || !sessionId) return Promise.reject(new Error('url and sessionId are required'));
@@ -125,7 +125,7 @@ export function sendClientError({ url, sessionId, detail, context, apiKey,
   return sendOneShotFrame('client_error', frame, { url, WebSocketImpl, timeoutMs });
 }
 
-const CONVERSE_MODE_FIELDS = new Set([
+const DIALT_MODE_FIELDS = new Set([
   'kind', 'modality', 'voice', 'instructions', 'tools', 'web_search', 'end_call', 'flow', 'greeting',
   'temperature', 'silence_nudge_s', 'silence_end_s', 'tool_choice', 'background_audio',
 ]);
@@ -147,17 +147,18 @@ function validatedToolChoice(value) {
 }
 const RELAY_MODE_FIELDS = new Set(['kind', 'provider', 'model', 'voice', 'web_search']);
 
-function validatedMode(value = { kind: 'converse' }) {
+function validatedMode(value = { kind: 'dialt' }) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     throw new TypeError('mode must be an object');
   }
   const mode = { ...value };
+  if (mode.kind === 'converse') mode.kind = 'dialt';
   for (const [key, item] of Object.entries(mode)) {
     if (item === undefined) delete mode[key];
   }
-  const allowed = mode.kind === 'converse' ? CONVERSE_MODE_FIELDS
+  const allowed = mode.kind === 'dialt' ? DIALT_MODE_FIELDS
     : mode.kind === 'relay' ? RELAY_MODE_FIELDS : null;
-  if (!allowed) throw new TypeError('mode.kind must be converse or relay');
+  if (!allowed) throw new TypeError('mode.kind must be dialt or relay');
   const extra = Object.keys(mode).find((key) => !allowed.has(key));
   if (extra) throw new TypeError(`unexpected ${mode.kind} mode field: ${extra}`);
   const optionalString = (key) => {
@@ -173,9 +174,9 @@ function validatedMode(value = { kind: 'converse' }) {
   optionalString('voice');
   optionalBoolean('web_search');
   mode.web_search ??= false;
-  if (mode.kind === 'converse') {
+  if (mode.kind === 'dialt') {
     if (mode.modality !== undefined && mode.modality !== 'voice' && mode.modality !== 'text') {
-      throw new TypeError('converse modality must be voice or text');
+      throw new TypeError('dialt modality must be voice or text');
     }
     mode.modality ??= 'voice';
     optionalString('instructions');
@@ -185,20 +186,20 @@ function validatedMode(value = { kind: 'converse' }) {
     optionalBoolean('flow');
     optionalBoolean('background_audio');
     if (Object.hasOwn(mode, 'tools') && !Array.isArray(mode.tools)) {
-      throw new TypeError('converse tools must be an array');
+      throw new TypeError('dialt tools must be an array');
     }
     if (Object.hasOwn(mode, 'tool_choice')) {
       if (!Array.isArray(mode.tools) || !mode.tools.length) {
-        throw new TypeError('converse tool_choice requires a non-empty tools list');
+        throw new TypeError('dialt tool_choice requires a non-empty tools list');
       }
       mode.tool_choice = validatedToolChoice(mode.tool_choice);
     }
     if (mode.greeting != null && mode.greeting !== false && typeof mode.greeting !== 'string') {
-      throw new TypeError('converse greeting must be a string or false');
+      throw new TypeError('dialt greeting must be a string or false');
     }
     if (Object.hasOwn(mode, 'temperature') && (typeof mode.temperature !== 'number'
         || !Number.isFinite(mode.temperature))) {
-      throw new TypeError('converse temperature must be a finite number');
+      throw new TypeError('dialt temperature must be a finite number');
     }
     // Per-session override of the broker's two-stage silence policy (env defaults: 10s/20s) — e.g.
     // a benchmark harness with long simulated-user think-time. Omit either field to keep the
@@ -207,12 +208,12 @@ function validatedMode(value = { kind: 'converse' }) {
     for (const key of ['silence_nudge_s', 'silence_end_s']) {
       if (Object.hasOwn(mode, key) && (typeof mode[key] !== 'number'
           || !Number.isFinite(mode[key]) || mode[key] <= 0)) {
-        throw new TypeError(`converse ${key} must be a positive finite number`);
+        throw new TypeError(`dialt ${key} must be a positive finite number`);
       }
     }
     if (Object.hasOwn(mode, 'silence_nudge_s') && Object.hasOwn(mode, 'silence_end_s')
         && mode.silence_end_s <= mode.silence_nudge_s) {
-      throw new TypeError('converse silence_end_s must be greater than silence_nudge_s');
+      throw new TypeError('dialt silence_end_s must be greater than silence_nudge_s');
     }
   } else {
     if (typeof mode.provider !== 'string' || !mode.provider.trim()) {
@@ -246,9 +247,9 @@ function connectMarks() {
   return { marks, mark };
 }
 
-export class ConverseClient extends EventTarget {
+export class DialtClient extends EventTarget {
   constructor({ url, sessionId = createSessionId(), player, apiKey,
-    mode = { kind: 'converse' }, user, timezone, rawAssist = false,
+    mode = { kind: 'dialt' }, user, timezone, rawAssist = false,
     WebSocketImpl = globalThis.WebSocket,
     echoCancellerFactory = () => new EchoCanceller(),
     autoReconnect = true, reconnectBaseMs = 500, reconnectMaxMs = 5000,
@@ -277,7 +278,7 @@ export class ConverseClient extends EventTarget {
       // the engine, not the browser app, since iOS forces every browser onto WebKit. The track
       // arrives; Web Audio gets silence. Anyone revisiting this should re-run that probe before
       // writing code, not after.
-      console.warn('[converse] webrtc transport is not yet supported on WebKit — using ws');
+      console.warn('[dialt] webrtc transport is not yet supported on WebKit - using ws');
       transport = 'ws';
     }
     this.url = toWebSocketUrl(url);
@@ -298,7 +299,7 @@ export class ConverseClient extends EventTarget {
     ambienceOpts.mode ??= 'thinking';
     const ambienceOnWs = transport === 'ws';
     if (!ambienceOnWs && ambienceGiven && ambienceOpts.mode !== 'off') {
-      console.warn('[converse] ambience is not available on the webrtc transport (use mode.background_audio); disabled');
+      console.warn('[dialt] ambience is not available on the webrtc transport (use mode.background_audio); disabled');
     }
     this.ambience = new Ambience({ player: this.player, enabled: ambienceOnWs, ...ambienceOpts });
     this.apiKey = apiKey || null;
@@ -823,7 +824,7 @@ export class ConverseClient extends EventTarget {
   // Shared start-frame construction (mode/temperature/greeting/rawAssist) for both transports.
   _buildStartFrame() {
     let mode = validatedMode(this._mode);
-    if (mode.kind === 'converse') {
+    if (mode.kind === 'dialt') {
       if (this._temperature != null) mode.temperature = this._temperature;
       if (this._noGreeting) mode.greeting = false;
       if (mode.background_audio && this.transport !== 'webrtc') {
@@ -833,15 +834,15 @@ export class ConverseClient extends EventTarget {
         // been downgraded for us: WebKit silently falls back to ws (see the constructor), so a
         // caller who asked for webrtc + background_audio would otherwise lose the whole session
         // on iOS instead of just the music.
-        console.warn('[converse] background_audio requires the webrtc transport — disabled');
+        console.warn('[dialt] background_audio requires the webrtc transport - disabled');
         delete mode.background_audio;
       }
     }
     mode = validatedMode(mode);
-    const textModality = mode.kind === 'converse' && mode.modality === 'text';
+    const textModality = mode.kind === 'dialt' && mode.modality === 'text';
     // Voice is the established wire default. Keep it internally for client-side guards, but omit
     // it from the frame so this SDK remains voice-compatible with pre-text Dialt servers.
-    if (mode.kind === 'converse' && mode.modality === 'voice') delete mode.modality;
+    if (mode.kind === 'dialt' && mode.modality === 'voice') delete mode.modality;
     const start = {
       type: 'start',
       session_id: this.sessionId,
@@ -850,7 +851,7 @@ export class ConverseClient extends EventTarget {
     if (!textModality) {
       start.audio = { sr: SAMPLE_RATE, output_encoding: 'pcm16' };
     } else if (this.transport !== 'ws') {
-      throw new TypeError('converse text modality requires the ws transport');
+      throw new TypeError('dialt text modality requires the ws transport');
     }
     if (this.apiKey) start.api_key = this.apiKey;
     if (this._resumeToken) start.resume_token = this._resumeToken;
@@ -1330,7 +1331,7 @@ export class ConverseClient extends EventTarget {
     try { fn(); } catch (err) {
       if (!this._ambienceWarned) {
         this._ambienceWarned = true;
-        console.warn('[converse] ambience error (disabled for this session):', err);
+        console.warn('[dialt] ambience error (disabled for this session):', err);
       }
       try { this.ambience.setMode('off'); } catch { /* already off */ }
     }
@@ -1563,7 +1564,7 @@ export class ConverseClient extends EventTarget {
    *  changes nothing; a mid-session `setTools` resets tool_choice to `"auto"`. */
   setToolChoice(toolChoice, { oneShot = false } = {}) {
     const validated = validatedToolChoice(toolChoice);
-    if (!oneShot && this._mode.kind === 'converse'
+    if (!oneShot && this._mode.kind === 'dialt'
         && Array.isArray(this._mode.tools) && this._mode.tools.length) {
       // Durable restrictions fold into the replayed mode (like setVoice) so an auto-reconnect
       // re-applies them; a one-shot is turn-scoped and deliberately does not survive. A mode
@@ -1580,7 +1581,7 @@ export class ConverseClient extends EventTarget {
   setVoice(voice) {
     // Relay providers bind their voice when the upstream session is constructed and do not support
     // this control. Dialt reconnects replay the selected voice.
-    if (this._mode.kind !== 'converse') return;
+    if (this._mode.kind !== 'dialt') return;
     this._mode = Object.freeze(validatedMode({ ...this._mode, voice }));
     this._sendControl({ type: 'set_voice', voice });
   }
@@ -1796,3 +1797,6 @@ export class ConverseClient extends EventTarget {
     return detail;
   }
 }
+
+/** @deprecated Use DialtClient. */
+export const ConverseClient = DialtClient;

package/src/mic.js

@@ -25,7 +25,7 @@ export class CaptureAbortedError extends Error {
 // distorts levels — so an app that hand-rolls getUserMedia({audio:true}) silently degrades the
 // loop. Frames come out as 16 kHz 512-sample Float32 via an AudioWorklet resampler.
 // `processing:false` opens the mic fully raw (AEC+NS+AGC off): used for the optional raw ablation
-// track, and by ConverseClient.startMic on WebKit where the SDK's own AEC3 cancels instead.
+// track, and by DialtClient.startMic on WebKit where the SDK's own AEC3 cancels instead.
 export class MicCapture {
   constructor({ onFrame, processing = true, workletUrl, deviceId } = {}) {
     this.onFrame = onFrame;

package/src/webrtc.js

@@ -1,14 +1,14 @@
-// WebRTC transport support for ConverseClient — see serving/broker_webrtc.py's module docstring
+// WebRTC transport support for DialtClient - see serving/broker_webrtc.py's module docstring
 // for the full wire contract this mirrors. Two independent pieces live here:
 //
 //   TrackFeeder  — turns mic frames (whatever startMic()/pushMicFrame() would otherwise ws.send()
 //                  as PCM16) into a real outbound MediaStreamTrack, by re-injecting them through an
 //                  AudioWorkletNode into a MediaStreamAudioDestinationNode. RTCPeerConnection.
 //                  addTrack() needs a live MediaStreamTrack before the offer/ICE-gather/answer
-//                  exchange even happens — and that exchange has to complete before ConverseClient
+//                  exchange even happens - and that exchange has to complete before DialtClient
 //                  knows whether the app will call startMic() at all (connect() resolves first) —
 //                  so this feeder's track is always what negotiates the offer's audio m-line.
-//                  Once startMic() runs (the normal path: no forced SDK-side AEC), ConverseClient
+//                  Once startMic() runs (the normal path: no forced SDK-side AEC), DialtClient
 //                  replaceTrack()s the sender straight onto the real getUserMedia device track —
 //                  zero added JS hops/latency, no renegotiation needed — and this feeder goes idle.
 //                  It stays the ACTIVE uplink only for callers with no MicCapture at all (custom
@@ -23,7 +23,7 @@
 //                   round-trip, acceptable latency for a single-hop broker-terminated call), and
 //                   later applies the server's answer.
 //
-// Both are deliberately dumb/mockable: ConverseClient owns all protocol semantics (start frame,
+// Both are deliberately dumb/mockable: DialtClient owns all protocol semantics (start frame,
 // ready/bye handling, reconnection policy); this module only knows WebRTC plumbing.
 
 import { addWorkletModule, defaultWorkletModuleUrls } from './worklet-url.js';
@@ -157,7 +157,7 @@ export class WebRtcSession {
   }
 
   /** Returns the RTCRtpSender so the caller can later replaceTrack() a real capture device's
-   *  track in directly (see ConverseClient.startMic) without renegotiating. */
+   *  track in directly (see DialtClient.startMic) without renegotiating. */
   addAudioTrack(track) {
     return this.pc.addTrack(track);
   }