@finalai/final-agent-provider 0.6.2 → 0.7.0

package/dist/modules/channels/voice.mjs

@@ -0,0 +1,851 @@
+import {
+  defineChannel,
+  packageRef,
+  principalRefSchema
+} from "@finalai/agent-provider";
+import * as z from "zod";
+import { bytesToBase64 } from "@finalai/agent-provider/sandbox/bytes";
+import { recordingRawLimit, recordingWav } from "./voice-recording.mjs";
+import {
+  abortable,
+  channelBaseUrl,
+  confirmOAuth,
+  createQueue,
+  decisionChoices,
+  decisionSummary,
+  decisionAnswer,
+  textOf,
+  turnStatus,
+  parseJson,
+  personFor,
+  responseJson,
+  startOAuth,
+  takeOAuth
+} from "./channel-utils.mjs";
+const configSchema = z.object({
+  baseUrl: z.string().url().optional(),
+  oauthAuthorizeUrl: z.string().url().optional(),
+  oauthTokenUrl: z.string().url().optional(),
+  oauthUserInfoUrl: z.string().url().optional(),
+  oauthClientId: z.string().url().optional(),
+  oauthResource: z.string().url().optional(),
+  voice: z.string().optional()
+});
+const userInfoSchema = z.object({ sub: z.string(), organizationId: z.string(), displayName: z.string() }).transform((value) => ({
+  id: value.sub,
+  tenant: value.organizationId,
+  displayName: value.displayName
+}));
+const startSchema = z.object({
+  type: z.literal("start"),
+  encoding: z.literal("linear16"),
+  sampleRate: z.literal(16e3),
+  principal: principalRefSchema,
+  recording: z.boolean().default(false)
+});
+const runVoiceConnection = async (options) => {
+  const { ctx, socket } = options;
+  const failed = new AbortController();
+  const signal = AbortSignal.any([socket.signal, failed.signal]);
+  const send = (data) => {
+    if (!signal.aborted) socket.send(data);
+  };
+  const connectionKey = crypto.randomUUID();
+  const trace = (stage, detail = {}) => {
+    const metadata = { connectionId: connectionKey, at: Date.now(), ...detail };
+    send(JSON.stringify({ type: "trace", stage, ...metadata }));
+    ctx.log(`voice.${stage}`, metadata);
+  };
+  let activeSpeech = null;
+  let activeRefusal = null;
+  let refusalPlayback = null;
+  let playbackGeneration = 0;
+  const speakRefusal = async (message, refusalSignal = signal) => {
+    const preceding = refusalPlayback;
+    const finished = Promise.withResolvers();
+    refusalPlayback = finished.promise;
+    const speech = new AbortController();
+    activeRefusal?.abort();
+    activeRefusal = speech;
+    activeSpeech?.abort();
+    const playbackVersion = ++playbackGeneration;
+    send(JSON.stringify({ type: "speech.start" }));
+    const outputSignal = AbortSignal.any([refusalSignal, speech.signal]);
+    try {
+      await preceding;
+      const text = async function* () {
+        yield message;
+      };
+      for await (const frame of abortable(
+        ctx.media.synthesize(text(), {
+          voice: options.voice,
+          encoding: options.encoding,
+          sampleRate: options.sampleRate,
+          signal: outputSignal
+        }),
+        outputSignal
+      )) {
+        if (playbackVersion !== playbackGeneration || outputSignal.aborted) break;
+        send(frame);
+      }
+    } finally {
+      speech.abort();
+      if (activeRefusal === speech) activeRefusal = null;
+      finished.resolve();
+      if (refusalPlayback === finished.promise) refusalPlayback = null;
+    }
+  };
+  const person = await personFor(ctx, options.principal);
+  const route = await ctx.places.resolve(options.place);
+  if (typeof person !== "string" && (person.refused !== "unlinked" || route.kind !== "connected" || route.policy.audience !== "anyone")) {
+    send(JSON.stringify({ type: "linked", linkUrl: person.linkUrl, message: person.message }));
+    await speakRefusal(person.message);
+    socket.close(1008, "Account link required");
+    return;
+  }
+  const from = typeof person === "string" ? person : void 0;
+  const conversation = await (async () => {
+    try {
+      return route.kind === "connected" ? route.conversation : route.defaults == null || from == null ? null : await ctx.places.connect(options.place, { by: from, create: route.defaults.create });
+    } catch {
+      return null;
+    }
+  })();
+  if (conversation == null) {
+    const message = "This call could not connect to a chat. Check your access in Final.";
+    send(JSON.stringify({ type: "notice", message }));
+    await speakRefusal(message, AbortSignal.any([signal, AbortSignal.timeout(1e4)]));
+    send(JSON.stringify({ type: "speech.end", final: true }));
+    socket.close(1e3);
+    return;
+  }
+  const recordingEnabled = options.recording !== false;
+  const recordingLimit = recordingEnabled ? recordingRawLimit(options.encoding) : null;
+  if (recordingEnabled)
+    send(
+      JSON.stringify({
+        type: "recording.notice",
+        message: "Your transcript and recording are saved to this chat."
+      })
+    );
+  const audio = createQueue();
+  const transcriptionStopped = new AbortController();
+  const transcriptionSignal = AbortSignal.any([signal, transcriptionStopped.signal]);
+  let terminalRefusal = false;
+  let microphoneInputClosed = false;
+  const closeAudio = () => {
+    microphoneInputClosed = true;
+    audio.close();
+  };
+  const microphoneEnded = new AbortController();
+  const microphoneLifecycle = { onEnd: null, stopObservation: null };
+  const utterances = createQueue();
+  let queuedAudioBytes = 0;
+  const transcriptionAudio = async function* () {
+    for await (const frame of audio.stream) {
+      queuedAudioBytes -= frame.byteLength;
+      yield frame;
+    }
+  };
+  let recording = [];
+  let recordingSize = 0;
+  let segment = 0;
+  let generation = 0;
+  let activeTurn = false;
+  const turnLifecycle = {
+    accepting: null,
+    activeId: null
+  };
+  let audioStarted = false;
+  let userSpeaking = false;
+  let utteranceNumber = 0;
+  let decision = null;
+  const pendingDecisions = /* @__PURE__ */ new Map();
+  const clearDecisions = () => {
+    pendingDecisions.clear();
+    decision = null;
+  };
+  const fail = (cause) => {
+    if (signal.aborted) return;
+    ctx.log("voice connection failed", {
+      error: cause instanceof Error ? cause.message : "stream failed"
+    });
+    send(
+      JSON.stringify({ type: "error", message: "The voice connection failed. Please reconnect." })
+    );
+    socket.close(1011, "Voice connection failed");
+    failed.abort();
+    closeAudio();
+    utterances.close();
+  };
+  let upload = null;
+  const attachRecording = async (part, deadline) => {
+    deadline?.throwIfAborted();
+    if (part.encoded == null) {
+      part.encoded = bytesToBase64(
+        recordingWav({
+          chunks: part.chunks,
+          bytes: part.bytes,
+          encoding: options.encoding,
+          sampleRate: options.sampleRate
+        })
+      );
+      part.chunks = [];
+    }
+    const result = await ctx.conversation(conversation).attach({
+      from,
+      label: `Voice recording, part ${part.index}`,
+      origin: { place: options.place },
+      idempotencyKey: `${options.place.id}:${connectionKey}:recording:${part.index}`,
+      content: [{ type: "audio", data: part.encoded, mimeType: "audio/wav" }]
+    });
+    if ("refused" in result) throw new Error(result.message);
+  };
+  const beginRecordingUpload = (deadline) => {
+    if (recordingSize === 0) return;
+    const part = {
+      chunks: recording,
+      bytes: recordingSize,
+      index: ++segment,
+      encoded: null
+    };
+    recording = [];
+    recordingSize = 0;
+    upload = {
+      segment: part,
+      result: attachRecording(part, deadline).then(
+        () => ({ ok: true }),
+        (error) => ({ error })
+      )
+    };
+  };
+  const settleRecordingUpload = async (retry, deadline) => {
+    const pending = upload;
+    if (pending == null) return;
+    const stop = deadline ?? signal;
+    const interrupted = Promise.withResolvers();
+    const abortUpload = () => interrupted.reject(
+      stop.reason instanceof Error ? stop.reason : new Error("Recording upload interrupted.")
+    );
+    stop.addEventListener("abort", abortUpload, { once: true });
+    if (stop.aborted) abortUpload();
+    let result;
+    try {
+      result = await Promise.race([pending.result, interrupted.promise]);
+      if ("error" in result) {
+        if (!retry) throw result.error;
+        await Promise.race([attachRecording(pending.segment, deadline), interrupted.promise]);
+      }
+    } finally {
+      stop.removeEventListener("abort", abortUpload);
+    }
+    if (upload === pending) upload = null;
+  };
+  const rotateRecording = async () => {
+    await settleRecordingUpload(true);
+    signal.throwIfAborted();
+    beginRecordingUpload();
+  };
+  const finishRecording = async () => {
+    const deadline = new AbortController();
+    const expired = Promise.withResolvers();
+    const timer = setTimeout(() => {
+      const cause = new Error("Recording cleanup timed out.");
+      deadline.abort(cause);
+      expired.reject(cause);
+    }, 1e4);
+    const finish = async () => {
+      let failure = null;
+      try {
+        await settleRecordingUpload(true, deadline.signal);
+      } catch (cause) {
+        failure = cause instanceof Error ? cause : new Error("Recording attachment failed.");
+        upload = null;
+      }
+      if (recordingSize > 0 && !deadline.signal.aborted) {
+        try {
+          beginRecordingUpload(deadline.signal);
+          await settleRecordingUpload(true, deadline.signal);
+        } catch (cause) {
+          failure ??= cause instanceof Error ? cause : new Error("Recording attachment failed.");
+        }
+      }
+      if (failure != null) throw failure;
+    };
+    try {
+      await Promise.race([finish(), expired.promise]);
+    } finally {
+      clearTimeout(timer);
+      deadline.abort();
+    }
+  };
+  const reportRefusal = async (message, options2 = {}) => {
+    if (terminalRefusal) return;
+    const recoverable = options2.recoverable !== false && (from == null || await ctx.people.identify(from).then(
+      (principal) => principal != null,
+      () => false
+    ));
+    if (terminalRefusal) return;
+    if (recoverable) {
+      send(JSON.stringify({ type: "error", message, recoverable: true }));
+      await speakRefusal(message);
+      return;
+    }
+    terminalRefusal = true;
+    closeAudio();
+    transcriptionStopped.abort();
+    utterances.close();
+    activeSpeech?.abort();
+    microphoneLifecycle.stopObservation?.();
+    send(JSON.stringify({ type: "notice", message }));
+    await speakRefusal(message, AbortSignal.any([signal, AbortSignal.timeout(1e4)]));
+  };
+  const requestCancellation = async (turnId) => {
+    try {
+      const result = await ctx.turns.cancel({ conversation, by: from, turnId });
+      if ("refused" in result) await reportRefusal(result.message);
+      else if (!result.accepted)
+        await reportRefusal(
+          "No running turn could be interrupted from this connection. Check Final if work is still running."
+        );
+    } catch {
+      await reportRefusal("The turn could not be interrupted. Try stopping it in Final.");
+    }
+  };
+  const cancel = async (withdrawDecision = false) => {
+    playbackGeneration += 1;
+    activeSpeech?.abort();
+    send(JSON.stringify({ type: "speech.start" }));
+    if (turnLifecycle.accepting != null) {
+      turnLifecycle.accepting.interrupted = true;
+      generation += 1;
+      return;
+    }
+    if (activeTurn && (decision == null || withdrawDecision)) {
+      clearDecisions();
+      generation += 1;
+      microphoneLifecycle.stopObservation?.();
+      const target = turnLifecycle.activeId;
+      if (target != null) await requestCancellation(target);
+    }
+  };
+  const answerDecision = async (text) => {
+    if (decision == null) return false;
+    const normalized = text.trim().toLowerCase().replace(/[.!?]$/g, "");
+    const isDecisionAnswer = ["yes", "no", "approve", "deny"].includes(normalized);
+    if (pendingDecisions.size > 1) {
+      if (isDecisionAnswer || [...pendingDecisions.values()].some(
+        (pending) => decisionAnswer(pending.choices, normalized) != null
+      )) {
+        await speakRefusal("Multiple actions need approval. Answer them in Final.");
+        return true;
+      }
+      return false;
+    }
+    if (from == null) {
+      if (!isDecisionAnswer) return false;
+      await speakRefusal("This action needs approval in Final.");
+      return true;
+    }
+    const choice = decisionAnswer(decision.choices, normalized);
+    if (choice == null) {
+      if (!["yes", "no", "approve", "deny"].includes(normalized)) return false;
+      await speakRefusal("Choose the exact option in Final.");
+      return true;
+    }
+    const decisionId = decision.id;
+    try {
+      const result = await ctx.decisions.resolve({
+        decisionId,
+        outcome: choice.outcome,
+        by: from
+      });
+      if ("refused" in result) await reportRefusal(result.message);
+      else {
+        pendingDecisions.delete(decisionId);
+        decision = pendingDecisions.values().next().value ?? null;
+        if (!result.resolved) await reportRefusal("This decision is no longer waiting in Final.");
+      }
+    } catch {
+      await reportRefusal(
+        "The approval could not be answered. Please try again or answer in Final."
+      );
+    }
+    return true;
+  };
+  const speak = async (text, version, correlation) => {
+    let firstAudio = true;
+    for await (const sentence of abortable(text, signal)) {
+      while (refusalPlayback != null) await refusalPlayback;
+      if (version !== generation || signal.aborted) break;
+      const playbackVersion = playbackGeneration;
+      const single = async function* () {
+        yield sentence;
+      };
+      const speech = new AbortController();
+      activeSpeech = speech;
+      const speechSignal = AbortSignal.any([signal, speech.signal]);
+      try {
+        for await (const frame of abortable(
+          ctx.media.synthesize(single(), {
+            voice: options.voice,
+            encoding: options.encoding,
+            sampleRate: options.sampleRate,
+            signal: speechSignal
+          }),
+          speechSignal
+        )) {
+          if (version !== generation || playbackVersion !== playbackGeneration) break;
+          if (firstAudio) {
+            firstAudio = false;
+            trace("first.audio.out", correlation);
+          }
+          send(frame);
+        }
+      } catch (cause) {
+        if (!speechSignal.aborted) throw cause;
+      } finally {
+        speech.abort();
+        if (activeSpeech === speech) activeSpeech = null;
+      }
+    }
+  };
+  const work = (async () => {
+    for await (const utterance of abortable(utterances.stream, signal)) {
+      if (terminalRefusal) break;
+      const version = ++generation;
+      const { text, key, finalAt } = utterance;
+      const origin = {
+        place: options.place,
+        ref: {
+          externalKey: key,
+          connectionId: connectionKey,
+          utterance: key,
+          utteranceFinalAt: finalAt
+        }
+      };
+      const accepting = { interrupted: false };
+      turnLifecycle.accepting = accepting;
+      const posted = from == null ? await ctx.conversation(conversation).input({
+        content: [{ type: "text", text }],
+        origin,
+        idempotencyKey: key,
+        waitForAcceptance: true,
+        principal: options.principal,
+        label: `From ${options.principal.displayName ?? options.principal.id} in ${options.place.title ?? options.place.kind}`
+      }) : await ctx.conversation(conversation).post({
+        from,
+        content: [{ type: "text", text }],
+        origin,
+        idempotencyKey: key,
+        waitForAcceptance: true
+      });
+      if (turnLifecycle.accepting === accepting) turnLifecycle.accepting = null;
+      if (signal.aborted || terminalRefusal) return;
+      if (accepting.interrupted || version !== generation) {
+        if (!("refused" in posted) && posted.turnId != null) {
+          trace("post.accepted", { utterance: key, turnId: posted.turnId });
+          await requestCancellation(posted.turnId);
+        }
+        continue;
+      }
+      if ("refused" in posted) {
+        await reportRefusal(posted.message, { recoverable: false });
+        continue;
+      }
+      if (posted.turnId == null) {
+        const message = "I couldn't start a voice reply for this request. Check the chat in Final.";
+        await reportRefusal(message);
+        continue;
+      }
+      trace("post.accepted", { utterance: key, turnId: posted.turnId });
+      activeTurn = true;
+      turnLifecycle.activeId = posted.turnId;
+      const sentences = createQueue();
+      const output = speak(sentences.stream, version, {
+        utterance: key,
+        turnId: posted.turnId
+      }).catch(fail);
+      const observation = new AbortController();
+      const observationSignal = AbortSignal.any([signal, observation.signal]);
+      const stopObservation = () => observation.abort();
+      microphoneLifecycle.stopObservation = stopObservation;
+      const microphoneEnd = () => {
+        if (decision == null) return;
+        sentences.push("Continue this approval in Final.");
+        observation.abort();
+      };
+      microphoneLifecycle.onEnd = microphoneEnd;
+      let hasReply = false;
+      let buffer = "";
+      let first = true;
+      const streamed = /* @__PURE__ */ new Set();
+      const completed = /* @__PURE__ */ new Set();
+      try {
+        for await (const event of abortable(
+          ctx.observe(conversation, { turnId: posted.turnId, signal: observationSignal }),
+          observationSignal
+        )) {
+          if (version !== generation) break;
+          if (event.type === "message.delta") {
+            if (first) {
+              first = false;
+              trace("first.delta", { utterance: key, turnId: posted.turnId });
+            }
+            if (event.data.delta.type !== "text" || typeof event.data.delta.text !== "string")
+              continue;
+            if (event.data.delta.text.length > 0) streamed.add(event.data.messageId);
+            if (event.data.delta.text.trim().length > 0) hasReply = true;
+            buffer += event.data.delta.text;
+            let boundary;
+            while ((boundary = /[!?](?:\s|$)|(?<!\d)\.(?:\s|$)|\.\s/.exec(buffer)) != null) {
+              const end = boundary.index + boundary[0].length;
+              sentences.push(buffer.slice(0, end));
+              buffer = buffer.slice(end);
+            }
+          } else if (event.type === "message.completed") {
+            const id = event.data.message.id;
+            if (!completed.has(id)) {
+              if (!streamed.has(id)) buffer += textOf(event.data.message.content);
+              if (buffer.trim().length > 0) {
+                hasReply = true;
+                sentences.push(buffer);
+              }
+              buffer = "";
+              completed.add(id);
+            }
+          } else if (event.type === "decision.created") {
+            const choices = from == null || microphoneEnded.signal.aborted ? [] : decisionChoices(event.data.request);
+            decision = { id: event.data.decisionId, choices };
+            pendingDecisions.set(decision.id, decision);
+            sentences.push(
+              `${decisionSummary(event.data.request)} ${pendingDecisions.size > 1 ? "Multiple actions need approval. Answer them in Final." : from == null ? "This action needs approval in Final." : choices.length === 0 ? "I've sent that to you in Final." : choices.filter((choice) => choice.answer === "approve").length === 1 && choices.filter((choice) => choice.answer === "deny").length <= 1 ? `Your options are ${choices.map((choice) => choice.label).join(" or ")}. Do you approve this action? Say yes or no.` : "Choose an option in Final."}`
+            );
+            if (microphoneEnded.signal.aborted) break;
+          } else if (event.type === "decision.resolved") {
+            pendingDecisions.delete(event.data.decisionId);
+            decision = pendingDecisions.values().next().value ?? null;
+          } else if (event.type === "turn.completed") {
+            turnLifecycle.activeId = null;
+            for (const message of event.data.messages ?? []) {
+              if (!streamed.has(message.id) && !completed.has(message.id)) {
+                const text2 = textOf(message.content);
+                if (text2.trim().length > 0) {
+                  hasReply = true;
+                  sentences.push(text2);
+                }
+                completed.add(message.id);
+              }
+            }
+            if (streamed.size === 0 && completed.size === 0 && event.data.content != null) {
+              const text2 = textOf(event.data.content);
+              if (text2.trim().length > 0) {
+                hasReply = true;
+                sentences.push(text2);
+              }
+            }
+            if (buffer.trim().length > 0) {
+              sentences.push(buffer);
+              buffer = "";
+            }
+            const status = turnStatus(event.data);
+            if (status != null) sentences.push(status);
+            else if (!hasReply)
+              sentences.push("The turn finished without a spoken reply. Open Final for details.");
+            clearDecisions();
+            break;
+          }
+        }
+        if (version === generation && buffer.trim().length > 0) sentences.push(buffer);
+      } finally {
+        clearDecisions();
+        observation.abort();
+        if (microphoneLifecycle.stopObservation === stopObservation)
+          microphoneLifecycle.stopObservation = null;
+        if (microphoneLifecycle.onEnd === microphoneEnd) microphoneLifecycle.onEnd = null;
+        sentences.close();
+        await output;
+        activeTurn = false;
+        if (turnLifecycle.activeId === posted.turnId) turnLifecycle.activeId = null;
+        send(JSON.stringify({ type: "speech.end", final: false }));
+      }
+    }
+  })().catch(fail);
+  const transcription = (async () => {
+    try {
+      for await (const transcript of abortable(
+        ctx.media.transcribe(transcriptionAudio(), {
+          encoding: options.encoding,
+          sampleRate: options.sampleRate,
+          endpointing: true,
+          signal: transcriptionSignal
+        }),
+        transcriptionSignal
+      )) {
+        send(JSON.stringify({ type: "transcript", ...transcript }));
+        if (!transcript.final && transcript.text.trim().length > 0 && !userSpeaking) {
+          userSpeaking = true;
+          await cancel();
+        }
+        if (transcript.final && transcript.text.trim().length === 0) userSpeaking = false;
+        if (transcript.final && transcript.text.trim().length > 0) {
+          const key = `${options.place.id}:${connectionKey}:${++utteranceNumber}`;
+          const finalAt = Date.now();
+          trace("utterance.final", { utterance: key, at: finalAt });
+          if (!userSpeaking && (activeTurn || turnLifecycle.accepting != null) && decision == null)
+            await cancel();
+          userSpeaking = false;
+          if (!await answerDecision(transcript.text) && !terminalRefusal) {
+            if (decision != null) await cancel(true);
+            utterances.push({ text: transcript.text, key, finalAt });
+          }
+        }
+      }
+    } finally {
+      utterances.close();
+      if (!microphoneInputClosed && !signal.aborted)
+        fail(new Error("The transcription stream ended unexpectedly."));
+      microphoneEnded.abort();
+      microphoneLifecycle.onEnd?.();
+    }
+  })().catch(fail);
+  const aborted = Promise.withResolvers();
+  const abort = () => {
+    aborted.resolve();
+    closeAudio();
+    utterances.close();
+    generation += 1;
+  };
+  signal.addEventListener("abort", abort, { once: true });
+  if (signal.aborted) abort();
+  let cleanupFailure = null;
+  try {
+    for await (const frame of abortable(
+      socket.messages,
+      AbortSignal.any([signal, microphoneEnded.signal])
+    )) {
+      if (terminalRefusal) break;
+      if (frame instanceof Uint8Array) {
+        if (queuedAudioBytes + frame.byteLength > 2 * 1024 * 1024) {
+          fail(new Error("Microphone audio exceeded the pending transcription limit."));
+          break;
+        }
+        if (recordingLimit != null) {
+          for (let offset = 0; offset < frame.byteLength; ) {
+            const length = Math.min(frame.byteLength - offset, recordingLimit - recordingSize);
+            recording.push(frame.slice(offset, offset + length));
+            recordingSize += length;
+            offset += length;
+            if (recordingSize === recordingLimit) await rotateRecording();
+          }
+        }
+        if (!audioStarted) {
+          audioStarted = true;
+          trace("audio.in");
+        }
+        queuedAudioBytes += frame.byteLength;
+        audio.push(frame);
+        continue;
+      }
+      const control = z.object({ type: z.string() }).safeParse(parseJson(frame));
+      if (control.success && control.data.type === "cancel") await cancel(true);
+      if (control.success && control.data.type === "stop") {
+        closeAudio();
+        break;
+      }
+    }
+    closeAudio();
+    await Promise.race([transcription, aborted.promise]);
+    await Promise.race([work, aborted.promise]);
+  } catch (cause) {
+    fail(cause);
+  } finally {
+    signal.removeEventListener("abort", abort);
+    abort();
+    if (signal.aborted) {
+      await Promise.race([Promise.all([transcription, work]), aborted.promise]);
+    } else await Promise.all([transcription, work]);
+    try {
+      await finishRecording();
+    } catch (cause) {
+      if (signal.aborted)
+        cleanupFailure = cause instanceof Error ? cause : new Error("Recording attachment failed.");
+      else fail(cause);
+    }
+    if (!signal.aborted) {
+      send(JSON.stringify({ type: "speech.end", final: true }));
+      socket.close(1e3);
+    }
+  }
+  if (cleanupFailure != null) throw cleanupFailure;
+};
+const oauthClient = async (ctx, config) => {
+  if (config.oauthClientId != null) return config.oauthClientId;
+  const saved = z.string().url().safeParse(await ctx.store.get("voice-oauth-client"));
+  if (saved.success) return saved.data;
+  const endpoint = new URL(
+    "/oauth2/register",
+    config.oauthAuthorizeUrl ?? "https://api.final.ai/oauth2/authorize"
+  );
+  const result = z.object({ client_id: z.string().url() }).parse(
+    await responseJson(
+      await ctx.credentials.fetch(endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          client_name: "Final Voice Channel",
+          redirect_uris: [`${channelBaseUrl(config)}/b/${ctx.binding.id}/oauth/callback`],
+          grant_types: ["authorization_code", "refresh_token"],
+          response_types: ["code"],
+          token_endpoint_auth_method: "none"
+        })
+      })
+    )
+  );
+  await ctx.store.set("voice-oauth-client", result.client_id);
+  return result.client_id;
+};
+const voiceChannel = (options = {}) => {
+  const config = configSchema.parse(options);
+  return defineChannel({
+    name: "voice",
+    config,
+    installed: packageRef("@finalai/final-agent-provider/channels/voice"),
+    credentials: { app: null },
+    identity: {
+      kind: "redirect",
+      start: async (args, ctx) => startOAuth(
+        {
+          ...args,
+          authorizeUrl: config.oauthAuthorizeUrl ?? "https://api.final.ai/oauth2/authorize",
+          clientId: await oauthClient(ctx, config),
+          redirectUri: `${channelBaseUrl(config)}/b/${ctx.binding.id}/oauth/callback`,
+          scope: "offline_access",
+          pkce: true,
+          extra: { resource: config.oauthResource ?? "https://api.final.ai/v1/connectors/mcp" }
+        },
+        ctx
+      )
+    },
+    places: {
+      kinds: ["live"],
+      defaults: () => ({ create: "direct-with-agent", replies: "origin", audience: "members" })
+    },
+    receive: async () => ({ ignored: true, reason: "voice-uses-stream" }),
+    routes: [
+      {
+        method: "GET",
+        path: "/oauth/callback",
+        handler: async (ctx) => {
+          const saved = await takeOAuth(ctx.request, ctx);
+          if (saved == null)
+            return new Response("Invalid or expired link request", { status: 400 });
+          const token = z.object({ access_token: z.string() }).parse(
+            await responseJson(
+              await ctx.credentials.fetch(
+                config.oauthTokenUrl ?? "https://api.final.ai/oauth2/token",
+                {
+                  method: "POST",
+                  body: new URLSearchParams({
+                    client_id: await oauthClient(ctx, config),
+                    resource: config.oauthResource ?? "https://api.final.ai/v1/connectors/mcp",
+                    grant_type: "authorization_code",
+                    code: saved.code,
+                    redirect_uri: saved.redirectUri,
+                    ...saved.verifier == null ? {} : { code_verifier: saved.verifier }
+                  })
+                }
+              )
+            )
+          );
+          const principal = userInfoSchema.parse(
+            await responseJson(
+              await ctx.credentials.fetch(
+                config.oauthUserInfoUrl ?? "https://api.final.ai/oauth2/userinfo",
+                {
+                  headers: { authorization: `Bearer ${token.access_token}` }
+                }
+              )
+            )
+          );
+          return confirmOAuth(
+            { ticket: saved.ticket, expected: saved.principal, actual: principal },
+            ctx
+          );
+        }
+      },
+      {
+        method: "WS",
+        path: "/stream",
+        handler: async (ctx) => {
+          const token = ctx.request.headers.get("authorization")?.replace(/^Bearer /, "") ?? new URL(ctx.request.url).searchParams.get("access_token");
+          if (token == null && ctx.authenticatedPrincipal == null)
+            return new Response("A Final OAuth token is required.", { status: 401 });
+          let authenticated = ctx.authenticatedPrincipal;
+          if (authenticated == null && token != null) {
+            try {
+              authenticated = userInfoSchema.parse(
+                await responseJson(
+                  await ctx.credentials.fetch(
+                    config.oauthUserInfoUrl ?? "https://api.final.ai/oauth2/userinfo",
+                    {
+                      headers: { authorization: `Bearer ${token}` }
+                    }
+                  )
+                )
+              );
+            } catch {
+              return new Response("Invalid Final identity", { status: 401 });
+            }
+          }
+          const principal = principalRefSchema.safeParse(authenticated);
+          if (!principal.success) return new Response("Invalid Final identity", { status: 401 });
+          ctx.socket.accept();
+          const iterator = ctx.socket.messages[Symbol.asyncIterator]();
+          const initial = await iterator.next();
+          const start = startSchema.safeParse(
+            typeof initial.value === "string" ? parseJson(initial.value) : null
+          );
+          if (!start.success || start.data.principal.id !== principal.data.id || start.data.principal.tenant !== principal.data.tenant) {
+            ctx.socket.close(1008, "The speaker does not match the authenticated account.");
+            return;
+          }
+          const remaining = {
+            [Symbol.asyncIterator]: () => iterator
+          };
+          await runVoiceConnection({
+            ctx,
+            socket: {
+              ...ctx.socket,
+              signal: ctx.socket.signal,
+              messages: remaining,
+              accept: (args) => ctx.socket.accept(args),
+              send: (data) => ctx.socket.send(data),
+              close: (code, reason) => ctx.socket.close(code, reason)
+            },
+            principal: principal.data,
+            place: {
+              kind: "live",
+              id: crypto.randomUUID(),
+              ...principal.data.tenant == null ? {} : { tenant: principal.data.tenant },
+              parent: {
+                kind: "person",
+                id: principal.data.id,
+                ...principal.data.tenant == null ? {} : { tenant: principal.data.tenant }
+              }
+            },
+            encoding: start.data.encoding,
+            sampleRate: start.data.sampleRate,
+            voice: config.voice,
+            recording: start.data.recording
+          });
+        }
+      }
+    ]
+  });
+};
+export {
+  runVoiceConnection,
+  voiceChannel
+};
+//# sourceMappingURL=voice.mjs.map