@wibly/sdk 0.1.0

package/src/time.ts

@@ -0,0 +1,58 @@
+/**
+ * Server-time helpers (per Platform Spec §3.7.4).
+ *
+ * The Runtime stamps every server-emitted frame with its own clock
+ * (`ts` on the envelope). The SDK estimates the clock skew from the
+ * `pong` round-trip and exposes `serverNow()` so consumers can render
+ * timers without drifting against the source of truth.
+ *
+ * `recordEvent(eventId)` is the lightweight client-side marker hook —
+ * stores a `(eventId, clientTs)` row so a later test can assert
+ * ordering or latency. Not currently transmitted over the wire; B8a
+ * may extend it with a server-side echo.
+ */
+
+export type ServerTimeSource = {
+  /** Server time in unix ms, adjusted for measured clock skew. */
+  readonly serverNow: () => number;
+  /**
+   * Record a client-side observation. Returns the wall-clock ms at
+   * the moment of capture. Stored in an in-memory ring buffer for
+   * test / debug access via `recordedEvents()`.
+   */
+  readonly recordEvent: (eventId: string) => number;
+  readonly recordedEvents: () => readonly RecordedEvent[];
+  /** Internal: update the measured skew on a fresh pong. */
+  readonly updateSkew: (skewMs: number) => void;
+};
+
+export type RecordedEvent = {
+  readonly eventId: string;
+  readonly clientTs: number;
+};
+
+const EVENT_RING_CAP = 64;
+
+export const createServerTimeSource = (
+  opts: {
+    readonly now?: () => number;
+  } = {},
+): ServerTimeSource => {
+  const nowFn = opts.now ?? (() => Date.now());
+  let skew = 0;
+  const events: RecordedEvent[] = [];
+
+  return {
+    serverNow: () => nowFn() + skew,
+    recordEvent: (eventId) => {
+      const clientTs = nowFn();
+      events.push({ eventId, clientTs });
+      if (events.length > EVENT_RING_CAP) events.shift();
+      return clientTs;
+    },
+    recordedEvents: () => events.slice(),
+    updateSkew: (newSkew) => {
+      skew = newSkew;
+    },
+  };
+};

package/src/transport.ts

@@ -0,0 +1,401 @@
+/**
+ * WebSocket transport for the Studio SDK.
+ *
+ * Per chunk B7 build: "transport.ts — WebSocket connection with
+ * automatic reconnection, exponential backoff, idempotent retries
+ * (uses MessageIdSchema for client → server frames), and pong-based
+ * clock-skew estimation."
+ *
+ * The transport owns nothing semantic — no game state, no game-level
+ * retries, no slot composition. It owns the socket lifecycle, frame
+ * encoding / decoding, and the per-connection seq counter for
+ * outbound frames. Inbound frames are surfaced through an
+ * observer interface; the higher-level pieces (`client.ts`,
+ * `store.ts`) layer their own behaviour on top.
+ *
+ * **Reconnection.** On any non-clean close, the transport schedules
+ * a reconnect after a randomised backoff (1s · 2^attempt up to 30s,
+ * full jitter). On reconnect, the SDK re-issues `subscribe` with the
+ * latest `resumeFromSeq` from the store and re-sends every pending
+ * `submit`/`emit` whose envelope `id` has not been confirmed. The
+ * Runtime dedupes by `id` per the chunk-B0 idempotency rule.
+ *
+ * **Test seam.** `WebSocketFactory` lets callers inject a mock socket
+ * (the SDK tests in `tests/transport.test.ts` use a fake constructor;
+ * the chunk-B7 acceptance "Disconnecting and reconnecting the
+ * WebSocket restores state correctly (Runtime mocked at the
+ * WebSocket boundary)").
+ */
+
+import { newId } from '@wibly/internal-shared';
+import {
+  PROTOCOL_VERSION,
+  decode,
+  encode,
+  isServerMessageKind,
+  type ClientMessage,
+  type ClientMessageKind,
+  type Message,
+  type MessageId,
+  type ProtocolError,
+  type ServerMessage,
+  type SessionId,
+} from '@wibly/internal-protocol';
+
+export type WebSocketLike = {
+  readonly readyState: number;
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  onopen: ((ev?: unknown) => void) | null;
+  onclose: ((ev?: { code?: number; reason?: string } | undefined) => void) | null;
+  onerror: ((ev?: unknown) => void) | null;
+  onmessage: ((ev: { data: unknown }) => void) | null;
+};
+
+export type WebSocketFactory = (url: string) => WebSocketLike;
+
+const WS_OPEN = 1;
+const WS_CLOSING = 2;
+const WS_CLOSED = 3;
+
+export type TransportObserver = {
+  /** Invoked for every successfully decoded server frame. */
+  onServerMessage: (msg: ServerMessage) => void;
+  /** Invoked when a frame fails to decode. */
+  onDecodeError: (e: ProtocolError, raw: string) => void;
+  /** Invoked when the socket transitions to a new connection phase. */
+  onConnectionState: (
+    next: 'connecting' | 'open' | 'reconnecting' | 'closed',
+  ) => void;
+  /**
+   * Invoked once the socket has just opened — fires AFTER the
+   * transport has dispatched its own per-connection `subscribe`
+   * frame and re-flushed pending submits. Use this hook to wire
+   * any per-connection bootstrap that's not part of the protocol
+   * (logging, telemetry).
+   */
+  onReconnectReady: () => void;
+  /**
+   * Read the current `resumeFromSeq` to send on each new socket's
+   * automatic `subscribe`. Returning `undefined` triggers a
+   * full-state subscribe (the server replies with `snapshot`).
+   */
+  getResumeFromSeq: () => number | undefined;
+};
+
+export type TransportConfig = {
+  readonly url: string;
+  readonly sessionId: SessionId;
+  readonly factory?: WebSocketFactory;
+  readonly now?: () => number;
+  /**
+   * Schedule a callback after a delay. Replaces `setTimeout` so tests
+   * can simulate reconnect backoff deterministically.
+   */
+  readonly schedule?: (cb: () => void, ms: number) => () => void;
+  readonly random?: () => number;
+  /** Cap on backoff. Default 30_000ms (per Platform Spec §3.7.5). */
+  readonly maxBackoffMs?: number;
+  /** Base of the exponential backoff. Default 1_000ms. */
+  readonly baseBackoffMs?: number;
+  /** Maximum reconnect attempts before giving up. Default Infinity. */
+  readonly maxAttempts?: number;
+};
+
+export type Transport = {
+  readonly start: () => void;
+  readonly close: (code?: number, reason?: string) => void;
+  /**
+   * Send a client-side payload. The transport stamps `protocolVersion`,
+   * assigns a fresh outbound `seq`, and either dispatches immediately
+   * (when the socket is open) or queues until the next reconnect.
+   * Returns the envelope `id` so the caller can match a server
+   * acknowledgement / error frame against the pending request.
+   *
+   * The same `id` is re-sent on reconnect if the original send has
+   * not been confirmed (`confirmSend(id)`). This satisfies the
+   * idempotency contract from chunk B0.
+   *
+   * Never throws and never fails — buffered for retry while the
+   * socket is closed, dispatched immediately while open.
+   */
+  readonly send: <K extends ClientMessageKind>(
+    kind: K,
+    payload: Extract<ClientMessage, { kind: K }>['payload'],
+  ) => { readonly id: MessageId; readonly seq: number };
+  /**
+   * Mark a previously-sent client frame as confirmed. After
+   * confirmation the transport drops the frame from its retry buffer.
+   * The SDK calls this when the server emits a matching `state_diff`
+   * (for `submit`) or an `error` (for any client frame).
+   */
+  readonly confirmSend: (id: MessageId) => void;
+  /**
+   * Re-send the per-connection subscribe frame on demand. Used by
+   * the session when it detects a state-diff gap and needs the
+   * Runtime to emit a fresh snapshot.
+   */
+  readonly resubscribe: () => void;
+};
+
+const DEFAULT_FACTORY: WebSocketFactory = (url) => {
+  if (typeof WebSocket === 'undefined') {
+    throw new Error(
+      'sdk: no WebSocket factory available; pass `factory` for non-browser environments',
+    );
+  }
+  return new WebSocket(url) as unknown as WebSocketLike;
+};
+
+const DEFAULT_SCHEDULE: NonNullable<TransportConfig['schedule']> = (
+  cb,
+  ms,
+) => {
+  const handle = setTimeout(cb, ms);
+  return () => clearTimeout(handle);
+};
+
+/**
+ * Compute the next reconnect delay. `attempt` is 1-indexed:
+ *
+ *   attempt 1 → [0, base]
+ *   attempt 2 → [0, base * 2]
+ *   attempt 3 → [0, base * 4]
+ *   …
+ *
+ * Capped at `maxMs`. Full jitter (Polly recommended) keeps thundering
+ * herds away from the Runtime after a region blip.
+ */
+export const computeBackoffMs = (
+  attempt: number,
+  opts: {
+    readonly base: number;
+    readonly cap: number;
+    readonly random: () => number;
+  },
+): number => {
+  const ceiling = Math.min(opts.cap, opts.base * 2 ** (attempt - 1));
+  return Math.floor(opts.random() * ceiling);
+};
+
+export const createTransport = (
+  config: TransportConfig,
+  observer: TransportObserver,
+): Transport => {
+  const factory = config.factory ?? DEFAULT_FACTORY;
+  const schedule = config.schedule ?? DEFAULT_SCHEDULE;
+  const random = config.random ?? Math.random;
+  const now = config.now ?? Date.now;
+  const baseBackoffMs = config.baseBackoffMs ?? 1_000;
+  const maxBackoffMs = config.maxBackoffMs ?? 30_000;
+  const maxAttempts = config.maxAttempts ?? Infinity;
+
+  let socket: WebSocketLike | null = null;
+  let outboundSeq = 0;
+  let attempts = 0;
+  let cancelReconnect: (() => void) | null = null;
+  let closed = false;
+  let opened = false;
+
+  /**
+   * Pending outbound frames keyed by envelope id. We retain them
+   * until either (a) the server confirms (state_diff / error) or
+   * (b) the caller drops the session.
+   *
+   * This is a Map (insertion-ordered) so the re-send on reconnect
+   * preserves the original send order, which the Runtime needs to
+   * deduplicate against its own seq.
+   */
+  const pending = new Map<MessageId, ClientMessage>();
+
+  const trySend = (msg: ClientMessage): boolean => {
+    if (socket === null || socket.readyState !== WS_OPEN) {
+      return false;
+    }
+    socket.send(encode(msg));
+    return true;
+  };
+
+  const enqueueAndSend = (msg: ClientMessage): void => {
+    pending.set(msg.id, msg);
+    trySend(msg);
+  };
+
+  const flushPending = (): void => {
+    for (const msg of pending.values()) {
+      trySend(msg);
+    }
+  };
+
+  const scheduleReconnect = (): void => {
+    if (closed) return;
+    attempts += 1;
+    if (attempts > maxAttempts) {
+      observer.onConnectionState('closed');
+      closed = true;
+      return;
+    }
+    const delay = computeBackoffMs(attempts, {
+      base: baseBackoffMs,
+      cap: maxBackoffMs,
+      random,
+    });
+    observer.onConnectionState('reconnecting');
+    cancelReconnect = schedule(() => {
+      cancelReconnect = null;
+      open();
+    }, delay);
+  };
+
+  const sendSubscribe = (): void => {
+    const current = socket;
+    if (current === null || current.readyState !== WS_OPEN) return;
+    const resumeFromSeq = observer.getResumeFromSeq();
+    outboundSeq += 1;
+    const msg = {
+      protocolVersion: PROTOCOL_VERSION,
+      kind: 'subscribe' as const,
+      seq: outboundSeq,
+      id: newId('msg'),
+      ts: now(),
+      payload: {
+        sessionId: config.sessionId,
+        ...(resumeFromSeq !== undefined ? { resumeFromSeq } : {}),
+      },
+    } as unknown as ClientMessage;
+    current.send(encode(msg));
+  };
+
+  const open = (): void => {
+    if (closed) return;
+    observer.onConnectionState(opened ? 'reconnecting' : 'connecting');
+    socket = factory(config.url);
+
+    socket.onopen = (): void => {
+      opened = true;
+      observer.onConnectionState('open');
+      // 1. Subscribe is the first frame on every new socket.
+      sendSubscribe();
+      // 2. Replay any pending user frames (submit / emit) — the
+      //    Runtime dedupes by envelope id.
+      flushPending();
+      // 3. Tell the consumer the socket is hot.
+      observer.onReconnectReady();
+    };
+    socket.onmessage = (ev): void => {
+      const raw = typeof ev.data === 'string' ? ev.data : String(ev.data);
+      const decoded = decode(raw);
+      if (decoded.ok) {
+        if (isServerMessageKind(decoded.value.kind)) {
+          // A successfully-decoded server frame is the signal that
+          // the Runtime accepted our subscribe. Reset the backoff
+          // counter only here — a bare TCP open isn't enough; a
+          // misconfigured proxy / auth rejection can produce
+          // open-then-immediate-close loops which should still
+          // back off exponentially.
+          attempts = 0;
+          observer.onServerMessage(decoded.value as ServerMessage);
+        }
+        // A client-kind frame on the WS read path is a peer protocol
+        // bug; we drop it silently. The decoder validated the
+        // envelope, so this only happens if the Runtime echoes a
+        // client frame, which it never does.
+      } else {
+        observer.onDecodeError(decoded.error, raw);
+      }
+    };
+    socket.onerror = (): void => {
+      // Errors are surfaced as a close in browsers; reconnection
+      // happens in `onclose`. We intentionally do nothing here.
+    };
+    socket.onclose = (ev): void => {
+      socket = null;
+      if (closed) {
+        // The caller invoked `transport.close()`; that path already
+        // emitted `onConnectionState('closed')`, so do nothing here.
+        return;
+      }
+      // 1000 normal, 1005 no status — treat both as a polite close
+      // initiated by the peer (Runtime restart). We still reconnect
+      // because the SDK's contract is "stay subscribed".
+      void ev;
+      scheduleReconnect();
+    };
+  };
+
+  /**
+   * Resend the subscribe frame on demand. The session calls this
+   * when it detects a state-diff gap (`fromSeq` mismatch) and needs
+   * the Runtime to re-emit a fresh snapshot.
+   */
+  const resubscribe = (): void => {
+    sendSubscribe();
+  };
+
+  return {
+    start: () => {
+      if (closed) {
+        throw new Error('sdk transport: cannot start after close()');
+      }
+      if (socket !== null) return;
+      open();
+    },
+    close: (code, reason) => {
+      closed = true;
+      if (cancelReconnect !== null) {
+        cancelReconnect();
+        cancelReconnect = null;
+      }
+      const current = socket;
+      socket = null;
+      if (current !== null && current.readyState !== WS_CLOSED && current.readyState !== WS_CLOSING) {
+        current.close(code, reason);
+      }
+      observer.onConnectionState('closed');
+    },
+    send: (kind, payload) => {
+      const id = newId('msg');
+      outboundSeq += 1;
+      const msg = {
+        protocolVersion: PROTOCOL_VERSION,
+        kind,
+        seq: outboundSeq,
+        id,
+        ts: now(),
+        payload,
+      } as unknown as ClientMessage;
+      enqueueAndSend(msg);
+      return { id, seq: outboundSeq };
+    },
+    confirmSend: (id) => {
+      pending.delete(id);
+    },
+    resubscribe,
+  };
+};
+
+/**
+ * Internal helper exposed for the test suite. Surfaces the result of
+ * deciding what to do with an incoming `state_diff`'s seq vs the
+ * caller's `appliedSeq`. Kept here (rather than in `store.ts`) so the
+ * transport's reconnection flow can call into the same predicate.
+ */
+export const decideStateDiffAction = (
+  msg: ServerMessage,
+  appliedSeq: number,
+): 'apply' | 'ignore_stale' | 'request_resync' => {
+  if (msg.kind !== 'state_diff') return 'apply';
+  if (msg.payload.toSeq <= appliedSeq) return 'ignore_stale';
+  if (msg.payload.fromSeq === appliedSeq) return 'apply';
+  return 'request_resync';
+};
+
+// Re-export internal constants for the SDK tests.
+export const __test = {
+  WS_OPEN,
+  WS_CLOSING,
+  WS_CLOSED,
+  computeBackoffMs,
+};
+
+export type { Message };

package/src/voice.ts

@@ -0,0 +1,67 @@
+/**
+ * Voice (TTS) helpers (per chunk B7 build: "voice.ts — TTS playback
+ * binding. Plays an audio response from the Gateway as a `<audio>`
+ * stream. Tone-down for accessibility (subtitle fallback) lives
+ * here.").
+ *
+ * Like inference, the SDK does NOT call the Gateway directly — voice
+ * lines are emitted via the Runtime so the same auth + metering +
+ * audit path applies. Chunk B8a wires the Runtime-side handler; the
+ * SDK's `voice.speak` returns `runtime_not_wired` until then.
+ *
+ * The chunk-B7 surface is the *playback* helper (a tiny wrapper that
+ * decodes the base64 audio and feeds it to an `<audio>` element)
+ * plus the wire shape — the SDK isn't holding the ElevenLabs key.
+ *
+ * Accessibility: `speak` accepts an optional `caption` field. If
+ * present, the SDK fires a `voice.caption` event on the bus (which
+ * the host shell renders as a transcript line) regardless of whether
+ * audio playback succeeds. This is the "subtitle fallback" the spec
+ * calls out.
+ */
+
+import type { Result } from '@wibly/internal-shared';
+
+import type { SdkError } from './errors.js';
+
+export type SpeakInput = {
+  readonly personaId: string;
+  readonly text: string;
+  readonly options?: {
+    readonly voiceId?: string;
+    readonly modelId?: string;
+    readonly qualityTier?: 'preview' | 'standard' | 'high';
+  };
+  /**
+   * Caption text rendered through the SDK's `voice.caption` event.
+   * Defaults to `text` if omitted. Pass `null` to suppress the
+   * caption (debug only — production should always show a subtitle).
+   */
+  readonly caption?: string | null;
+};
+
+export type SpeakSuccess = {
+  readonly audioBase64: string;
+  readonly contentType: string;
+  readonly durationMs: number;
+};
+
+export type SessionVoice = {
+  readonly speak: (input: SpeakInput) => Promise<Result<SpeakSuccess, SdkError>>;
+};
+
+export const VOICE_EVENT_PREFIX = 'voice.' as const;
+
+/** Approximate playback duration for a base64-encoded audio chunk.
+ *
+ * MP3 at 22.05 kHz mono averages ~16 bytes per second of audio in
+ * the encoded form for our typical bitrate; the estimate is good
+ * enough for fade-out timing and `aria-live` scheduling. Production
+ * playback should call `audio.duration` once the element loads, but
+ * this gives the SDK a useful number before then.
+ */
+export const estimateAudioDurationMs = (audioBase64: string): number => {
+  // base64 inflates by ~4/3; the underlying bytes are what we want.
+  const rawBytes = Math.floor((audioBase64.length * 3) / 4);
+  return Math.round((rawBytes / 16) * 1000);
+};