@inkibra/voice-sdk 0.1.0 → 0.2.0

package/dist/server.js

@@ -1,391 +1,746 @@
-// src/server.ts
-var liveVoicePcmFormat = {
-  encoding: "pcm_s16le",
-  sampleRate: 24000,
-  channels: 1
-};
-var defaultApiBaseUrl = "https://inkibra-voice.inkibra.workers.dev";
-var defaultEndpoint = "wss://inkibra-voice.inkibra.workers.dev/v1/live";
-
-class LiveVoiceServerSession {
+// src/control.ts
+class ControlClient {
+  endpoint;
+  callbacks;
   socket;
-  audio;
-  tools;
-  closed;
-  resolveClosed;
-  listeners = new Map;
-  stopped = false;
-  prepared;
-  started;
-  currentPhase;
-  acceptingInput = false;
-  constructor(socket, audio, tools) {
+  sessionToken;
+  snapshotValue;
+  waits = new Map;
+  executions = new Map;
+  requestCounter = 0;
+  prepared = false;
+  preparing;
+  starting;
+  started = false;
+  terminal = false;
+  constructor(endpoint, callbacks) {
+    this.endpoint = endpoint;
+    this.callbacks = callbacks;
+  }
+  ratingUrl(sessionId) {
+    const url = new URL(this.endpoint);
+    url.protocol = url.protocol === "wss:" ? "https:" : url.protocol === "ws:" ? "http:" : url.protocol;
+    return `${url.origin}/v1/sessions/${encodeURIComponent(sessionId)}/rating`;
+  }
+  setCallbacks(callbacks) {
+    this.callbacks = callbacks;
+  }
+  get currentSnapshot() {
+    return this.snapshotValue;
+  }
+  retainedTaskIds() {
+    return [...this.executions.keys()];
+  }
+  async open(options) {
+    if (!options.token)
+      throw new Error("A Live Voice token is required.");
+    if (this.terminal)
+      throw new Error("This participant has been disposed or stopped.");
+    if (this.waits.has("open"))
+      throw new Error("A connection is already opening.");
+    this.closeSocket("replaced", false);
+    this.sessionToken = options.token;
+    this.callbacks.onConnection("connecting");
+    const url = new URL(`${this.endpoint.replace(/\/$/u, "")}/${encodeURIComponent(options.sessionId ?? crypto.randomUUID())}`);
+    url.searchParams.set("token", options.token);
+    const socket = new WebSocket(url);
     this.socket = socket;
-    this.audio = audio;
-    this.tools = tools;
-    this.closed = new Promise((resolve) => {
-      this.resolveClosed = resolve;
+    const opening = this.exchange("open", 15000, () => {
+      const send = () => {
+        if (this.socket !== socket)
+          return;
+        this.send({
+          type: "session.open",
+          protocolVersion: 2,
+          mode: options.mode,
+          ...options.sessionId ? { sessionId: options.sessionId } : {},
+          ...options.participantId ? { participantId: options.participantId } : {},
+          tools: Object.entries(options.tools ?? {}).map(([name, tool]) => ({ name, description: tool.description, parameters: tool.parameters })),
+          ...options.developer === undefined ? {} : { developer: options.developer },
+          ...options.mediaMode ? { mediaMode: options.mediaMode } : {},
+          retainedTaskIds: options.retainedTaskIds ?? this.retainedTaskIds()
+        });
+      };
+      if (socket.readyState === WebSocket.OPEN)
+        send();
+      else
+        socket.addEventListener("open", send, { once: true });
+    });
+    socket.addEventListener("message", (event) => {
+      if (this.socket === socket)
+        this.onMessage(event.data);
+    });
+    socket.addEventListener("close", (event) => {
+      if (this.socket === socket)
+        this.closeSocket(event.reason || "Connection lost", false);
+    });
+    socket.addEventListener("error", () => {
+      if (this.socket !== socket)
+        return;
+      this.callbacks.onConnection("error", "Live Voice WebSocket failed.");
+      this.closeSocket("Live Voice WebSocket failed.", false);
     });
-  }
-  static async connect(options) {
-    validateAudioFormat(options.audio.format);
-    const credentials = await resolveSessionCredentials(options);
-    const socket = new WebSocket(withSessionToken(`${credentials.endpoint.replace(/\/$/u, "")}/${crypto.randomUUID()}`, credentials.token));
-    const session = new LiveVoiceServerSession(socket, options.audio, options.tools ?? {});
-    session.bindSocket();
-    session.emit("connection", { state: "connecting" });
-    await waitForOpen(socket);
     try {
-      await session.prepare();
+      return await opening;
     } catch (error) {
-      session.finish(error instanceof Error ? error.message : String(error));
+      if (this.socket === socket)
+        this.closeSocket("Connection opening failed", false);
       throw error;
     }
+  }
+  async prepare() {
+    if (this.prepared)
+      return;
+    if (this.preparing)
+      return this.preparing;
+    this.preparing = this.exchange("prepare", 90000, () => this.send({ type: "session.prepare", protocolVersion: 2 })).then(() => {
+      this.prepared = true;
+    });
     try {
-      await options.audio.start({
-        input: (pcm) => session.writeInput(pcm),
-        receipt: (receipt) => session.sendReceipt(receipt),
-        close: (reason) => session.finish(reason),
-        error: (error) => {
-          session.emit("error", { code: "AUDIO_TRANSPORT_ERROR", message: error.message });
-          session.finish(error.message);
-        }
-      });
-    } catch (error) {
-      session.finish(error instanceof Error ? error.message : String(error));
-      throw error;
+      await this.preparing;
+    } finally {
+      this.preparing = undefined;
     }
-    const started = new Promise((resolve, reject) => {
-      session.started = { resolve, reject };
-    });
-    socket.send(JSON.stringify({
-      type: "session.start",
-      developer: {
-        prompt: options.prompt ?? "",
-        conversation: options.conversation,
-        tools: Object.entries(options.tools ?? {}).map(([name, tool]) => ({
-          type: "function",
-          name,
-          description: tool.description,
-          parameters: tool.parameters
-        }))
-      }
-    }));
+  }
+  async start(options = {}) {
+    if (this.started)
+      return;
+    if (this.starting)
+      return this.starting;
+    const socket = this.socket;
+    this.starting = (async () => {
+      await this.prepare();
+      if (!socket || this.socket !== socket)
+        throw new Error("Connection changed during startup.");
+      await this.exchange("start", 90000, () => this.send({ type: "session.start", mediaMode: options.mediaMode }));
+      this.started = true;
+      this.callbacks.onConnection("live");
+    })();
     try {
-      await started;
-    } catch (error) {
-      session.finish(error instanceof Error ? error.message : String(error));
-      throw error;
+      await this.starting;
+    } finally {
+      this.starting = undefined;
     }
-    session.acceptingInput = true;
-    session.emit("connection", { state: "live" });
-    return session;
   }
-  on(event, handler) {
-    const handlers = this.listeners.get(event) ?? new Set;
-    handlers.add(handler);
-    this.listeners.set(event, handlers);
-    return () => handlers.delete(handler);
+  async stop() {
+    if (this.snapshotValue?.status === "stopped") {
+      this.closeSocket("stopped", true);
+      return;
+    }
+    try {
+      await this.exchange("stop", 5000, () => this.send({ type: "session.stop" }));
+    } finally {
+      this.closeSocket("stopped", true);
+    }
   }
-  get phase() {
-    return this.currentPhase;
+  async detach() {
+    if (!this.socket)
+      return;
+    try {
+      await this.exchange("detach", 5000, () => this.send({ type: "participant.detach" }));
+    } finally {
+      this.closeSocket("detached", false);
+    }
   }
-  stop() {
-    this.finish("stopped", true);
+  closeSocket(reason = "closed", terminal = true) {
+    const socket = this.socket;
+    this.socket = undefined;
+    this.prepared = false;
+    this.started = false;
+    this.terminal ||= terminal;
+    const error = new Error(reason);
+    for (const wait of this.waits.values())
+      wait.reject(error);
+    this.waits.clear();
+    if (terminal)
+      for (const execution of this.executions.values()) {
+        execution.controller.abort(error);
+        for (const wait of execution.pending.values())
+          wait.reject(error);
+        execution.pending.clear();
+      }
+    if (socket) {
+      if (this.snapshotValue?.participantId === "owner" && this.snapshotValue.status === "running") {
+        this.snapshotValue = { ...this.snapshotValue, status: "suspended", floor: { owner: "USER", assistantAudible: false } };
+      }
+      if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING)
+        socket.close(1000, reason.slice(0, 100));
+      this.callbacks.onConnection("closed", reason);
+    }
   }
   dispose() {
-    this.stop();
-    this.listeners.clear();
-  }
-  bindSocket() {
-    this.socket.addEventListener("message", (event) => this.onMessage(event.data));
-    this.socket.addEventListener("close", () => this.finish("Live Voice connection closed."));
-    this.socket.addEventListener("error", () => {
-      const error = new Error("Live Voice WebSocket failed.");
-      this.prepared?.reject(error);
-      this.emit("error", { code: "CONNECTION_ERROR", message: error.message });
-      this.finish(error.message);
-    });
+    if (this.socket?.readyState === WebSocket.OPEN)
+      this.send({ type: this.snapshotValue?.participantId === "owner" ? "session.stop" : "participant.detach" });
+    this.closeSocket("disposed", true);
   }
-  prepare() {
-    const promise = new Promise((resolve, reject) => {
-      this.prepared = { resolve, reject };
-    });
-    this.socket.send(JSON.stringify({ type: "session.prepare", protocolVersion: 1 }));
-    return promise;
+  reconnect(options) {
+    return this.open({ ...options, token: options.token ?? this.sessionToken ?? "", mode: "reconnect", retainedTaskIds: this.retainedTaskIds() });
+  }
+  async requestTask(operation, taskId, resolution) {
+    const requestId = String(++this.requestCounter);
+    return await this.exchange(`task:${requestId}`, 15000, () => this.send({ type: "task.request", requestId, operation, ...taskId ? { taskId } : {}, ...resolution ? { resolution } : {} }));
+  }
+  playUiCue(cue) {
+    this.send({ type: "cue.request", cue });
+  }
+  send(message) {
+    if (this.socket?.readyState !== WebSocket.OPEN)
+      throw new Error("Session is not connected.");
+    if (message instanceof Uint8Array) {
+      this.socket.send(message.buffer instanceof ArrayBuffer ? message : message.slice());
+    } else
+      this.socket.send(serialize(message));
+  }
+  async exchange(key, timeoutMs, send) {
+    if (this.waits.has(key))
+      throw new Error(`Operation already pending: ${key}`);
+    const wait = deferred();
+    this.waits.set(key, wait);
+    const timer = setTimeout(() => wait.reject(new Error(`Live Voice ${key} acknowledgement timed out.`)), timeoutMs);
+    try {
+      send();
+      return await wait.promise;
+    } finally {
+      clearTimeout(timer);
+      this.waits.delete(key);
+    }
   }
   onMessage(raw) {
     if (typeof raw !== "string")
       return;
     let message;
     try {
-      message = JSON.parse(raw);
+      const value = JSON.parse(raw);
+      if (!value || typeof value !== "object" || Array.isArray(value))
+        return;
+      message = value;
     } catch {
       return;
     }
     const type = String(message.type ?? "");
-    if (type === "session.prepared") {
-      this.prepared?.resolve();
-      this.prepared = undefined;
+    if (type === "session.opened") {
+      const snapshot = message.snapshot;
+      if (!snapshot || typeof snapshot.sessionId !== "string" || typeof snapshot.connectionId !== "string" || typeof snapshot.participantId !== "string" || !Number.isSafeInteger(snapshot.sequence) || !Array.isArray(snapshot.tasks) || !snapshot.transcript || !snapshot.floor) {
+        this.waits.get("open")?.reject(new Error("Session opened without a valid snapshot."));
+        return;
+      }
+      this.snapshotValue = snapshot;
+      this.callbacks.onSnapshot?.(snapshot);
+      this.waits.get("open")?.resolve(snapshot);
+      for (const execution of this.executions.values())
+        for (const pending of execution.pending.values())
+          this.socket?.send(pending.serialized);
+      this.callbacks.onConnection("ready");
       return;
     }
-    if (type === "session.prepare_failed") {
-      const error = new Error(String(message.message ?? "Session preparation failed."));
-      this.prepared?.reject(error);
-      this.prepared = undefined;
+    if (type === "session.open_failed" || type === "session.prepare_failed" || type === "session.start_failed") {
+      const key = type === "session.open_failed" ? "open" : type === "session.prepare_failed" ? "prepare" : "start";
+      this.waits.get(key)?.reject(new Error(String(message.message ?? type)));
       return;
     }
-    if (type === "session.started") {
-      this.started?.resolve();
-      this.started = undefined;
+    if (type === "session.prepared") {
+      this.waits.get("prepare")?.resolve();
       return;
     }
-    if (type === "public.event") {
-      this.acceptPublicEvent(String(message.name ?? "unknown"), asRecord(message.payload), Number.isFinite(Number(message.atMs)) ? Number(message.atMs) : undefined);
+    if (type === "session.started") {
+      if (this.snapshotValue)
+        this.snapshotValue = { ...this.snapshotValue, status: "running" };
+      this.waits.get("start")?.resolve();
       return;
     }
-    if (type === "tool.call") {
-      this.executeTool({
-        callId: String(message.callId ?? ""),
-        name: String(message.name ?? ""),
-        input: asRecord(message.input)
-      });
+    if (type === "session.stopped") {
+      if (this.snapshotValue)
+        this.snapshotValue = { ...this.snapshotValue, status: "stopped", phase: undefined, floor: { owner: "USER", assistantAudible: false }, transcript: { turns: [] }, tasks: this.snapshotValue.tasks.map((task) => ({ taskId: task.taskId, participantId: task.participantId, status: task.status, createdAt: task.createdAt, updatedAt: task.updatedAt })) };
+      this.waits.get("stop")?.resolve();
+      if (this.snapshotValue?.participantId === "owner")
+        this.closeSocket("stopped", true);
+      else if (this.snapshotValue)
+        this.callbacks.onSnapshot?.(this.snapshotValue);
       return;
     }
-    if (type === "session.limit") {
-      this.emit("limit", {
-        reason: String(message.reason ?? "SESSION_LIMIT"),
-        ...Number.isFinite(Number(message.durationSeconds)) ? { durationSeconds: Number(message.durationSeconds) } : {}
-      });
+    if (type === "participant.detached") {
+      this.waits.get("detach")?.resolve();
       return;
     }
-    if (type === "output.block") {
-      this.audio.output({ type: "block-foreground", generationId: String(message.generationId ?? "") });
+    if (type === "public.event") {
+      if (!message.payload || typeof message.payload !== "object" || Array.isArray(message.payload))
+        return;
+      const event = { name: String(message.name), payload: message.payload, ...typeof message.sequence === "number" ? { sequence: message.sequence } : {}, ...typeof message.atMs === "number" ? { atMs: message.atMs } : {} };
+      if (event.sequence !== undefined && this.snapshotValue && event.sequence <= this.snapshotValue.sequence)
+        return;
+      if (this.snapshotValue) {
+        const snapshot = { ...this.snapshotValue, sequence: event.sequence ?? this.snapshotValue.sequence };
+        if (event.name === "task.update" && isTask(event.payload))
+          snapshot.tasks = [...snapshot.tasks.filter((task) => task.taskId !== event.payload.taskId), event.payload];
+        if (event.name === "transcript.canonical" && Array.isArray(event.payload.turns))
+          snapshot.transcript = { turns: event.payload.turns };
+        if (event.name === "floor" && (event.payload.owner === "USER" || event.payload.owner === "ASSISTANT") && typeof event.payload.assistantAudible === "boolean")
+          snapshot.floor = { owner: event.payload.owner, assistantAudible: event.payload.assistantAudible };
+        if (event.name === "phase" && typeof event.payload.phase === "string")
+          snapshot.phase = event.payload.phase;
+        if (event.name === "session.status" && ["created", "running", "suspended", "stopped"].includes(String(event.payload.status))) {
+          snapshot.status = event.payload.status;
+          if (snapshot.status === "suspended" || snapshot.status === "stopped")
+            snapshot.floor = { owner: "USER", assistantAudible: false };
+        }
+        this.snapshotValue = snapshot;
+      }
+      this.callbacks.onPublicEvent(event);
+      if (event.name === "task.update" && isTask(event.payload))
+        this.callbacks.onTaskUpdate?.(event.payload);
       return;
     }
-    if (type === "output.audio" && typeof message.delta === "string") {
-      this.audio.output({
-        type: "enqueue",
-        generationId: String(message.generationId ?? ""),
-        lane: message.queue === "reaction" ? "REACTION" : "FOREGROUND",
-        pcm: base64Bytes(message.delta),
-        mode: message.mode === "play" ? "play" : "buffer",
-        gain: clamp01(Number(message.gain ?? 1))
-      });
+    if (type === "task.execute" && isTask(message.task)) {
+      this.execute(message.task);
       return;
     }
-    if (type === "output.release") {
-      this.audio.output({ type: "release", generationId: String(message.generationId ?? ""), gain: clamp01(Number(message.gain ?? 1)) });
+    if (type === "task.cancel") {
+      this.executions.get(String(message.taskId))?.controller.abort();
       return;
     }
-    if (type === "output.cancel") {
-      this.audio.output({ type: "cancel", generationId: String(message.generationId ?? "") });
+    if (type === "task.ack" || type === "task.error") {
+      const execution = this.executions.get(String(message.taskId));
+      const pending = execution?.pending.get(Number(message.sequence));
+      if (!execution || !pending)
+        return;
+      execution.pending.delete(Number(message.sequence));
+      if (type === "task.ack")
+        pending.resolve();
+      else {
+        execution.rejected = true;
+        pending.reject(new Error(String(message.message ?? "Task update rejected.")));
+      }
       return;
     }
-    if (type === "output.done") {
-      this.audio.output({
-        type: "done",
-        generationId: String(message.generationId ?? ""),
-        lane: message.queue === "reaction" ? "REACTION" : "FOREGROUND"
-      });
+    if (type === "task.response") {
+      const pending = this.waits.get(`task:${String(message.requestId)}`);
+      if (message.error)
+        pending?.reject(new Error(String(message.error.message ?? "Task request failed.")));
+      else
+        pending?.resolve(message.result);
       return;
     }
-    this.emit("unknown", { message });
-  }
-  writeInput(pcm) {
-    if (this.stopped || !this.acceptingInput || this.socket.readyState !== WebSocket.OPEN)
-      return;
-    if (pcm.byteLength % 2 !== 0) {
-      this.emit("error", { code: "INVALID_AUDIO_FRAME", message: "PCM16 input must contain complete 16-bit samples." });
+    if (type === "session.limit") {
+      this.callbacks.onSessionLimit?.(String(message.reason ?? "SESSION_LIMIT"), typeof message.durationSeconds === "number" ? message.durationSeconds : undefined);
       return;
     }
-    this.socket.send(pcm);
-  }
-  sendReceipt(receipt) {
-    if (this.stopped || this.socket.readyState !== WebSocket.OPEN)
-      return;
-    this.socket.send(JSON.stringify({ type: "output.receipt", ...receipt }));
+    this.callbacks.onUnknown?.(message);
   }
-  async executeTool(call) {
-    if (!call.callId || !call.name || this.socket.readyState !== WebSocket.OPEN)
-      return;
-    this.emit("tool.call", call);
-    const tool = this.tools[call.name];
-    if (!tool) {
-      const error = `No server handler is registered for tool ${call.name}`;
-      this.socket.send(JSON.stringify({ type: "tool.result", callId: call.callId, ok: false, error }));
-      this.emit("tool.result", { ...call, ok: false, error });
+  async execute(task) {
+    if (this.terminal || this.executions.has(task.taskId))
       return;
-    }
+    const entry = { controller: new AbortController, nextSequence: 1, rejected: false, pending: new Map };
+    this.executions.set(task.taskId, entry);
+    const publish = async (update) => {
+      if (this.terminal || entry.rejected)
+        throw new Error("Task update channel is closed.");
+      const sequence = entry.nextSequence;
+      const serialized = serialize({ type: "task.update", taskId: task.taskId, sequence, ...update });
+      entry.nextSequence++;
+      const wait = deferred();
+      entry.pending.set(sequence, { ...wait, serialized });
+      if (this.socket?.readyState === WebSocket.OPEN && !this.waits.has("open"))
+        this.socket.send(serialized);
+      await wait.promise;
+    };
+    const context = {
+      taskId: task.taskId,
+      sourceUserTurnId: task.sourceUserTurnId,
+      signal: entry.controller.signal,
+      progress: async (progress) => {
+        if (progress.fraction !== undefined && (!Number.isFinite(progress.fraction) || progress.fraction < 0 || progress.fraction > 1))
+          throw new Error("Task progress fraction must be between 0 and 1.");
+        await publish({ status: "running", progress });
+      },
+      partial: (value) => publish({ status: "running", partial: value })
+    };
     try {
-      const output = await tool.execute(call.input);
-      this.socket.send(JSON.stringify({ type: "tool.result", callId: call.callId, ok: true, output: output ?? null }));
-      this.emit("tool.result", { ...call, ok: true, output });
+      await publish({ status: "running" });
+      if (!this.callbacks.onTaskExecute)
+        throw new Error(`No handler is registered for task ${task.taskId}.`);
+      const output = await this.callbacks.onTaskExecute(task, context);
+      await publish({ status: "succeeded", output: output ?? null });
     } catch (error) {
+      if (this.terminal)
+        return;
       const message = error instanceof Error ? error.message : String(error);
-      this.socket.send(JSON.stringify({ type: "tool.result", callId: call.callId, ok: false, error: message }));
-      this.emit("tool.result", { ...call, ok: false, error: message });
+      if (entry.rejected) {
+        this.callbacks.onPublicEvent({ name: "error", payload: { code: "TASK_UPDATE_REJECTED", message } });
+        return;
+      }
+      const cancelled = entry.controller.signal.aborted && (error === entry.controller.signal.reason || error instanceof Error && error.name === "AbortError");
+      try {
+        await publish({ status: cancelled ? "cancelled" : "failed", error: message });
+      } catch (failure) {
+        if (!this.terminal)
+          this.callbacks.onPublicEvent({ name: "error", payload: { code: "TASK_UPDATE_FAILED", message: failure instanceof Error ? failure.message : String(failure) } });
+      }
+    }
+  }
+}
+function isTask(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const task = value;
+  return typeof task.taskId === "string" && typeof task.participantId === "string" && typeof task.status === "string";
+}
+function serialize(value) {
+  return JSON.stringify(value, (_key, item) => {
+    if (typeof item === "function" || typeof item === "symbol" || typeof item === "bigint" || typeof item === "number" && !Number.isFinite(item))
+      throw new Error("Task data must be JSON serializable.");
+    return item;
+  });
+}
+function deferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((onResolve, onReject) => {
+    resolve = onResolve;
+    reject = onReject;
+  });
+  return { promise, resolve, reject };
+}
+
+// src/participant.ts
+var defaultEndpoint = "wss://inkibra-voice.inkibra.workers.dev/v1/live";
+
+class LiveVoiceParticipant {
+  client;
+  tools;
+  developer;
+  connectedToken;
+  listeners = new Map;
+  lifetime = deferred();
+  closed = this.lifetime.promise;
+  constructor(options, client) {
+    this.client = client ?? new ControlClient(options.endpoint ?? defaultEndpoint, { onConnection: () => {}, onPublicEvent: () => {} });
+    this.tools = options.tools ?? {};
+    this.connectedToken = options.token;
+    this.developer = { prompt: options.prompt ?? "", ...options.conversation ? { conversation: options.conversation } : {} };
+    this.client.setCallbacks({
+      onConnection: (state, detail) => this.connectionChanged(state, detail),
+      onSnapshot: (snapshot) => this.emit("snapshot", snapshot),
+      onPublicEvent: (event) => this.acceptEvent(event),
+      onUnknown: (message) => this.unknownMessage(message),
+      onSessionLimit: (reason, durationSeconds) => this.emit("limit", { reason, durationSeconds }),
+      onTaskExecute: (task, context) => {
+        const tool = task.name ? this.tools[task.name] : undefined;
+        if (!tool || !task.input)
+          throw new Error(`No handler or invocation data for task ${task.taskId}.`);
+        return tool.execute(task.input, context);
+      }
+    });
+  }
+  get snapshot() {
+    const snapshot = this.client.currentSnapshot;
+    if (!snapshot)
+      throw new Error("Participant has not opened.");
+    return snapshot;
+  }
+  get sessionId() {
+    return this.snapshot.sessionId;
+  }
+  get participantId() {
+    return this.snapshot.participantId;
+  }
+  get connectionId() {
+    return this.snapshot.connectionId;
+  }
+  get phase() {
+    return this.snapshot.phase;
+  }
+  on(event, handler) {
+    let listeners = this.listeners.get(event);
+    if (!listeners) {
+      listeners = new Set;
+      this.listeners.set(event, listeners);
     }
+    listeners.add(handler);
+    return () => {
+      listeners.delete(handler);
+    };
+  }
+  async rateSession(rating) {
+    const response = await fetch(this.client.ratingUrl(this.sessionId), {
+      method: "POST",
+      headers: { authorization: `Bearer ${this.connectedToken}`, "content-type": "application/json" },
+      body: JSON.stringify(rating)
+    });
+    const result = await response.json();
+    if (!response.ok)
+      throw new Error(typeof result.error === "string" ? result.error : `Unable to submit rating (${response.status}).`);
+    if (!result.rating || typeof result.rating !== "object" || !Array.isArray(result.storedFields))
+      throw new Error("Rating response was invalid.");
+    return result;
+  }
+  async reconnect(options = {}) {
+    if (options.token)
+      this.connectedToken = options.token;
+    return await this.client.reconnect({ token: this.connectedToken, sessionId: this.sessionId, participantId: this.participantId, tools: this.tools });
+  }
+  dispose() {
+    this.client.dispose();
+    this.lifetime.resolve();
+  }
+  finish() {
+    this.lifetime.resolve();
+  }
+  connectionChanged(state, detail) {
+    this.emit("connection", { state, detail });
+    if (state === "closed" && this.client.currentSnapshot?.status === "stopped")
+      this.finish();
   }
-  acceptPublicEvent(name, payload, atMs) {
+  unknownMessage(message) {
+    this.emit("unknown", { message });
+  }
+  emit(event, value) {
+    for (const listener of this.listeners.get(event) ?? [])
+      listener(value);
+  }
+  taskApi() {
+    return {
+      list: () => this.client.requestTask("list"),
+      get: (taskId) => this.client.requestTask("get", taskId),
+      cancel: (taskId) => this.client.requestTask("cancel", taskId)
+    };
+  }
+  attachmentTaskApi() {
+    return { ...this.taskApi(), reconcile: (taskId, resolution) => this.client.requestTask("reconcile", taskId, resolution) };
+  }
+  acceptEvent(event) {
+    const { name, payload } = event;
+    if (name === "session.status") {
+      this.emit("snapshot", this.snapshot);
+      return;
+    }
+    if (name === "task.update" && typeof payload.taskId === "string") {
+      this.emit("task.update", payload);
+      return;
+    }
     if (name === "transcript.instantaneous" && typeof payload.text === "string") {
-      this.emit("transcript.instantaneous", { text: payload.text });
+      this.emit(name, { text: payload.text });
       return;
     }
     if (name === "transcript.canonical" && Array.isArray(payload.turns)) {
-      const turns = [];
-      for (const value of payload.turns) {
-        if (!value || typeof value !== "object" || Array.isArray(value))
-          continue;
-        const turn = value;
-        const role = turn.role;
-        if (typeof turn.id !== "string" || role !== "user" && role !== "assistant" || typeof turn.text !== "string")
-          continue;
-        turns.push({
-          id: turn.id,
-          role,
-          text: turn.text,
-          ...typeof turn.truncated === "boolean" ? { truncated: turn.truncated } : {}
-        });
-      }
-      this.emit("transcript.canonical", { turns });
+      this.emit(name, { turns: this.snapshot.transcript.turns });
       return;
     }
-    if (name === "floor" && (payload.owner === "USER" || payload.owner === "ASSISTANT") && typeof payload.assistantAudible === "boolean") {
-      this.emit("floor", { owner: payload.owner, assistantAudible: payload.assistantAudible });
+    if (name === "floor") {
+      this.emit(name, this.snapshot.floor);
       return;
     }
     if (name === "phase" && typeof payload.phase === "string") {
-      const event = {
-        phase: payload.phase,
-        source: payload.source === "floor" ? "floor" : "initial",
-        ...typeof payload.previousPhase === "string" ? { previousPhase: payload.previousPhase } : {}
-      };
-      this.currentPhase = event.phase;
-      this.emit("phase", event);
+      this.emit(name, { phase: payload.phase, source: payload.source === "floor" ? "floor" : "initial", ...typeof payload.previousPhase === "string" ? { previousPhase: payload.previousPhase } : {} });
       return;
     }
     if (name === "quick-reaction" && typeof payload.reaction === "string" && (payload.status === "prepared" || payload.status === "playing" || payload.status === "completed" || payload.status === "cancelled")) {
-      this.emit("quick-reaction", { reaction: payload.reaction, status: payload.status });
+      this.emit(name, { reaction: payload.reaction, status: payload.status });
       return;
     }
-    if (name === "assistant.energy" && Number.isFinite(Number(payload.current)) && Array.isArray(payload.predictions)) {
-      const predictions = [];
-      let valid = true;
-      for (const value of payload.predictions) {
-        if (!value || typeof value !== "object" || Array.isArray(value)) {
-          valid = false;
-          break;
-        }
-        const prediction = value;
-        const startMs = Number(prediction.startMs);
-        const endMs = Number(prediction.endMs);
-        const energy = Number(prediction.energy);
-        if (!Number.isFinite(startMs) || startMs < 0 || !Number.isFinite(endMs) || endMs <= startMs || !Number.isFinite(energy)) {
-          valid = false;
-          break;
-        }
-        predictions.push({ startMs, endMs, energy: clamp01(energy) });
-      }
-      if (valid) {
-        this.emit("assistant.energy", { current: clamp01(Number(payload.current)), predictions });
-        return;
-      }
-    }
     if (name === "error" && typeof payload.code === "string" && typeof payload.message === "string") {
-      this.emit("error", { code: payload.code, message: payload.message });
+      this.emit(name, { code: payload.code, message: payload.message });
       return;
     }
-    this.emit("unknown", { message: { type: "public.event", name, payload, ...atMs === undefined ? {} : { atMs } } });
+    this.unknownMessage({ type: "public.event", ...event });
   }
-  emit(event, value) {
-    for (const handler of this.listeners.get(event) ?? [])
-      handler(value);
+}
+
+// src/server.ts
+var liveVoicePcmFormat = { encoding: "pcm_s16le", sampleRate: 24000, channels: 1 };
+
+class LiveVoiceServerSession extends LiveVoiceParticipant {
+  audio;
+  tasks = this.taskApi();
+  mediaWanted = false;
+  audioActive = false;
+  audioEpoch = 0;
+  starting;
+  audioStopping;
+  constructor(options, client, audio) {
+    super(options, client);
+    this.audio = audio;
+    if (audio.format.encoding !== "pcm_s16le" || audio.format.sampleRate !== 24000 || audio.format.channels !== 1)
+      throw new Error("Audio transports must expose mono PCM16LE at 24 kHz.");
+  }
+  async start() {
+    this.mediaWanted = true;
+    if (this.starting)
+      return this.starting;
+    if (this.audioActive && this.snapshot.status === "running")
+      return;
+    this.starting = this.startMedia();
+    try {
+      await this.starting;
+    } finally {
+      this.starting = undefined;
+    }
+  }
+  async startMedia() {
+    await this.client.prepare();
+    await this.audioStopping;
+    const connectionId = this.connectionId;
+    const epoch = ++this.audioEpoch;
+    this.audioActive = true;
+    const current = () => this.audioActive && epoch === this.audioEpoch && connectionId === this.connectionId;
+    try {
+      await this.audio.start({
+        input: (pcm) => {
+          if (!current())
+            return;
+          if (pcm.byteLength % 2 !== 0)
+            throw new Error("PCM16 input must contain whole samples.");
+          this.client.send(pcm);
+        },
+        receipt: (receipt) => {
+          if (current())
+            this.client.send({ type: "output.receipt", ...receipt });
+        },
+        close: (reason) => {
+          if (current())
+            this.client.closeSocket(reason ?? "Audio transport closed", false);
+        },
+        error: (error) => {
+          if (!current())
+            return;
+          this.emit("error", { code: "AUDIO_TRANSPORT", message: error.message });
+          this.client.closeSocket("Audio transport failed", false);
+        }
+      });
+      if (!current())
+        throw new Error("Connection changed during audio startup.");
+      await this.client.start({ mediaMode: "server" });
+    } catch (error) {
+      await this.stopAudio();
+      throw error;
+    }
+  }
+  async stop() {
+    this.mediaWanted = false;
+    try {
+      await this.client.stop();
+    } finally {
+      await this.stopAudio();
+      this.finish();
+    }
+  }
+  async rate(rating) {
+    return this.rateSession(rating);
+  }
+  async reconnect(options = {}) {
+    this.client.closeSocket("reconnecting", false);
+    await this.starting?.catch(() => {});
+    await this.stopAudio();
+    await super.reconnect(options);
+    if (this.mediaWanted)
+      await this.start();
+    return this.snapshot;
+  }
+  dispose() {
+    this.mediaWanted = false;
+    super.dispose();
+    this.stopAudio().catch((error) => this.emit("error", { code: "AUDIO_STOP", message: String(error) }));
+  }
+  connectionChanged(state, detail) {
+    if (state === "closed" || state === "error")
+      this.stopAudio().catch((error) => this.emit("error", { code: "AUDIO_STOP", message: String(error) }));
+    super.connectionChanged(state, detail);
+  }
+  stopAudio() {
+    if (!this.audioActive)
+      return this.audioStopping ?? Promise.resolve();
+    this.audioEpoch++;
+    this.audioActive = false;
+    this.audioStopping = Promise.resolve().then(() => this.audio.stop());
+    return this.audioStopping;
   }
-  finish(reason, notifyServer = false) {
-    if (this.stopped)
+  unknownMessage(message) {
+    if (typeof message.type !== "string" || !message.type.startsWith("output.")) {
+      super.unknownMessage(message);
       return;
-    this.stopped = true;
-    const ended = new Error(reason ?? "Session ended.");
-    this.prepared?.reject(ended);
-    this.prepared = undefined;
-    this.started?.reject(ended);
-    this.started = undefined;
-    if (notifyServer && this.socket.readyState === WebSocket.OPEN)
-      this.socket.send(JSON.stringify({ type: "session.stop" }));
-    if (this.socket.readyState === WebSocket.OPEN || this.socket.readyState === WebSocket.CONNECTING)
-      this.socket.close(1000, reason ?? "stopped");
-    this.audio.stop();
-    this.emit("connection", { state: "closed", ...reason ? { detail: reason } : {} });
-    this.resolveClosed();
+    }
+    if (!this.audioActive)
+      return;
+    const generationId = String(message.generationId ?? "");
+    const lane = message.queue === "reaction" ? "REACTION" : "FOREGROUND";
+    const value = Number(message.gain ?? 1);
+    const gain = Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 1;
+    let command;
+    if (message.type === "output.block")
+      command = { type: "block-foreground", generationId };
+    else if (message.type === "output.release")
+      command = { type: "release", generationId, gain };
+    else if (message.type === "output.cancel")
+      command = { type: "cancel", generationId };
+    else if (message.type === "output.done")
+      command = { type: "done", generationId, lane };
+    else if (message.type === "output.audio" && typeof message.delta === "string") {
+      const binary = atob(message.delta);
+      const pcm = new Uint8Array(binary.length);
+      for (let index = 0;index < binary.length; index++)
+        pcm[index] = binary.charCodeAt(index);
+      command = { type: "enqueue", generationId, lane, pcm, mode: message.mode === "play" ? "play" : "buffer", gain };
+    } else {
+      super.unknownMessage(message);
+      return;
+    }
+    const epoch = this.audioEpoch;
+    Promise.resolve().then(() => {
+      if (epoch === this.audioEpoch && this.audioActive)
+        return this.audio.output(command);
+    }).catch((error) => {
+      if (epoch !== this.audioEpoch)
+        return;
+      this.emit("error", { code: "AUDIO_OUTPUT", message: String(error) });
+      this.client.closeSocket("Audio output failed", false);
+    });
+  }
+}
+
+class LiveVoiceServerAttachment extends LiveVoiceParticipant {
+  tasks = this.attachmentTaskApi();
+  async detach() {
+    try {
+      await this.client.detach();
+    } finally {
+      this.finish();
+    }
   }
 }
 
 class LiveVoiceServer {
-  static connect(options) {
-    return LiveVoiceServerSession.connect(options);
+  static async create(options) {
+    const credentials = await resolveCredentials(options);
+    const endpoint = options.endpoint ?? credentials.endpoint ?? defaultEndpoint;
+    const client = new ControlClient(endpoint, { onConnection: () => {}, onPublicEvent: () => {} });
+    const session = new LiveVoiceServerSession({ ...options, token: credentials.token, endpoint }, client, options.audio);
+    await client.open({ token: credentials.token, mode: "create", participantId: "owner", mediaMode: "server", tools: options.tools, developer: { prompt: options.prompt ?? "", ...options.conversation ? { conversation: options.conversation } : {} } });
+    return session;
+  }
+  static async attach(options) {
+    const credentials = await resolveCredentials(options);
+    const endpoint = options.endpoint ?? credentials.endpoint ?? defaultEndpoint;
+    const client = new ControlClient(endpoint, { onConnection: () => {}, onPublicEvent: () => {} });
+    const attachment = new LiveVoiceServerAttachment({ ...options, token: credentials.token, endpoint }, client);
+    await client.open({ token: credentials.token, mode: "attach", sessionId: options.sessionId, participantId: options.participantId, tools: options.tools });
+    return attachment;
   }
 }
-async function resolveSessionCredentials(options) {
+async function resolveCredentials(options) {
   if (Boolean(options.token) === Boolean(options.apiKey))
-    throw new Error("Supply exactly one of token or apiKey.");
+    throw new Error("Provide exactly one of token or apiKey.");
   if (options.token)
-    return { token: options.token, endpoint: options.endpoint ?? defaultEndpoint };
-  const apiBaseUrl = (options.apiBaseUrl ?? defaultApiBaseUrl).replace(/\/$/u, "");
-  const response = await fetch(`${apiBaseUrl}/v1/sessions`, {
-    method: "POST",
-    headers: { authorization: `Bearer ${options.apiKey}`, "content-type": "application/json" },
-    body: JSON.stringify(options.voice ? { voice: options.voice } : {})
-  });
+    return { token: options.token };
+  const base = (options.apiBaseUrl ?? "https://inkibra-voice.inkibra.workers.dev").replace(/\/$/u, "");
+  const path = options.sessionId ? `/v1/sessions/${encodeURIComponent(options.sessionId)}/attachment-tokens` : "/v1/sessions";
+  const body = options.sessionId ? { participantId: options.participantId, observe: true, tools: Object.keys(options.tools ?? {}) } : options.voice ? { voice: options.voice } : {};
+  const response = await fetch(`${base}${path}`, { method: "POST", headers: { authorization: `Bearer ${options.apiKey}`, "content-type": "application/json" }, body: JSON.stringify(body) });
   const result = await response.json();
   if (!response.ok || typeof result.token !== "string")
-    throw new Error(String(result.error ?? `Unable to create Live Voice session (${response.status}).`));
-  return {
-    token: result.token,
-    endpoint: options.endpoint ?? (typeof result.realtimeUrl === "string" ? result.realtimeUrl : defaultEndpoint)
-  };
-}
-function validateAudioFormat(format) {
-  if (!format)
-    throw new Error("Audio transports must declare their SDK-facing PCM format.");
-  if (format.encoding !== liveVoicePcmFormat.encoding || format.sampleRate !== liveVoicePcmFormat.sampleRate || format.channels !== liveVoicePcmFormat.channels) {
-    throw new Error("Audio transports must expose mono PCM16LE at 24 kHz.");
-  }
-}
-function waitForOpen(socket) {
-  if (socket.readyState === WebSocket.OPEN)
-    return Promise.resolve();
-  return new Promise((resolve, reject) => {
-    const opened = () => finish();
-    const failed = () => finish(new Error("Live Voice WebSocket failed while connecting."));
-    const finish = (error) => {
-      socket.removeEventListener("open", opened);
-      socket.removeEventListener("error", failed);
-      if (error)
-        reject(error);
-      else
-        resolve();
-    };
-    socket.addEventListener("open", opened, { once: true });
-    socket.addEventListener("error", failed, { once: true });
-  });
-}
-function withSessionToken(value, token) {
-  const url = new URL(value);
-  url.searchParams.set("token", token);
-  return url.toString();
-}
-function base64Bytes(encoded) {
-  const binary = atob(encoded);
-  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
-}
-function clamp01(value) {
-  return Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 1;
-}
-function asRecord(value) {
-  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    throw new Error(String(result.error ?? `Unable to authorize Live Voice session (${response.status}).`));
+  return { token: result.token, endpoint: typeof result.realtimeUrl === "string" ? result.realtimeUrl : undefined };
 }
 export {
+  LiveVoiceServerAttachment,
   LiveVoiceServerSession,
   LiveVoiceServer as default,
   liveVoicePcmFormat