@mycadet/assistant 0.12.11 → 0.13.0

package/src/providers/speech-to-text/__tests__/cadet-cloud.test.ts

@@ -1,271 +0,0 @@
-import { beforeEach, describe, expect, mock, test } from "bun:test";
-
-import { SttError } from "../../../stt/types.js";
-import { describeSttFailure } from "../../voice-error-copy.js";
-
-let mockTranscribeResult: unknown;
-let mockClient: { cloudAssistantId: string } | null = null;
-
-mock.module("../../../cloud/cloud-speech.js", () => ({
-  managedSpeechTranscribe: async () => mockTranscribeResult,
-}));
-
-mock.module("../../../cloud/client.js", () => ({
-  CadetCloudClient: {
-    create: async () => mockClient,
-  },
-}));
-
-import {
-  cadetCloudSpeechAvailable,
-  cadetCloudTranscribe,
-  sttErrorFromCloudSpeech,
-} from "../cadet-cloud.js";
-
-describe("cadetCloudSpeechAvailable", () => {
-  test("true with a connected platform client", async () => {
-    mockClient = { cloudAssistantId: "asst-1" };
-    expect(await cadetCloudSpeechAvailable()).toBe(true);
-  });
-
-  test("false without a client or without an assistant ID", async () => {
-    mockClient = null;
-    expect(await cadetCloudSpeechAvailable()).toBe(false);
-    mockClient = { cloudAssistantId: "" };
-    expect(await cadetCloudSpeechAvailable()).toBe(false);
-  });
-});
-
-describe("cadetCloudTranscribe", () => {
-  beforeEach(() => {
-    mockClient = { cloudAssistantId: "asst-1" };
-  });
-
-  test("returns the transcription text", async () => {
-    mockTranscribeResult = {
-      ok: true,
-      value: { text: "hello", durationSeconds: 2 },
-    };
-    expect(await cadetCloudTranscribe(Buffer.from([1]), "audio/wav")).toEqual({
-      text: "hello",
-    });
-  });
-
-  test("throws a normalized SttError on failure", async () => {
-    mockTranscribeResult = {
-      ok: false,
-      kind: "platform-error",
-      status: 429,
-      message: "slow down",
-    };
-    await expect(
-      cadetCloudTranscribe(Buffer.from([1]), "audio/wav"),
-    ).rejects.toMatchObject({ name: "SttError", category: "rate-limit" });
-  });
-});
-
-describe("sttErrorFromCloudSpeech", () => {
-  const cases: Array<{
-    name: string;
-    failure: Record<string, unknown>;
-    category: string;
-    userFacing: boolean;
-    messageIncludes?: string;
-    messageExcludes?: string[];
-  }> = [
-    {
-      name: "unavailable → auth, user-facing reconnect copy",
-      failure: { ok: false, kind: "unavailable", message: "no connection" },
-      category: "auth",
-      userFacing: true,
-      messageIncludes: "no connection",
-    },
-    {
-      name: "insufficient_balance → provider-error, user-facing credit copy",
-      failure: {
-        ok: false,
-        kind: "platform-error",
-        status: 402,
-        code: "insufficient_balance",
-        message: "balance",
-      },
-      category: "provider-error",
-      userFacing: true,
-      messageIncludes: "Cadet credits",
-    },
-    // Platform-supplied `detail` present: real remediation, surfaced verbatim.
-    {
-      name: "401 with platform detail → auth, user-facing verbatim",
-      failure: {
-        ok: false,
-        kind: "platform-error",
-        status: 401,
-        detail: "Your session expired.",
-        message: "Your session expired.",
-      },
-      category: "auth",
-      userFacing: true,
-      messageIncludes: "session expired",
-    },
-    {
-      name: "429 with platform detail → rate-limit, user-facing verbatim",
-      failure: {
-        ok: false,
-        kind: "platform-error",
-        status: 429,
-        detail: "Too many requests, retry in 30s.",
-        message: "Too many requests, retry in 30s.",
-      },
-      category: "rate-limit",
-      userFacing: true,
-      messageIncludes: "retry in 30s",
-    },
-    {
-      name: "413 with platform detail → invalid-audio, user-facing verbatim",
-      failure: {
-        ok: false,
-        kind: "platform-error",
-        status: 413,
-        detail: "Audio exceeds the 25 MB limit.",
-        message: "Audio exceeds the 25 MB limit.",
-      },
-      category: "invalid-audio",
-      userFacing: true,
-      messageIncludes: "25 MB",
-    },
-    // No platform `detail`: the generic "(platform returned N)" fallback stays
-    // non-user-facing so describeSttFailure emits friendly category copy
-    // instead of leaking a raw HTTP status — except a bare auth status, whose
-    // friendly copy would be the wrong BYOK "check your API key" guidance, so it
-    // gets a sanitized cloud-connection message surfaced verbatim.
-    {
-      name: "401 without detail → auth, user-facing sanitized reconnect copy",
-      failure: {
-        ok: false,
-        kind: "platform-error",
-        status: 401,
-        message: "Cloud speech transcription failed (platform returned 401).",
-      },
-      category: "auth",
-      userFacing: true,
-      messageIncludes: "reconnect your Cadet account",
-      messageExcludes: ["API key", "platform returned"],
-    },
-    {
-      name: "403 without detail → auth, user-facing sanitized reconnect copy",
-      failure: {
-        ok: false,
-        kind: "platform-error",
-        status: 403,
-        message: "Cloud speech transcription failed (platform returned 403).",
-      },
-      category: "auth",
-      userFacing: true,
-      messageIncludes: "reconnect your Cadet account",
-      messageExcludes: ["API key", "platform returned"],
-    },
-    {
-      name: "429 without detail → rate-limit, not user-facing",
-      failure: {
-        ok: false,
-        kind: "platform-error",
-        status: 429,
-        message: "Cloud speech transcription failed (platform returned 429).",
-      },
-      category: "rate-limit",
-      userFacing: false,
-    },
-    {
-      name: "413 without detail → invalid-audio, not user-facing",
-      failure: {
-        ok: false,
-        kind: "platform-error",
-        status: 413,
-        message: "Cloud speech transcription failed (platform returned 413).",
-      },
-      category: "invalid-audio",
-      userFacing: false,
-    },
-    {
-      name: "502 without detail → provider-error, not user-facing",
-      failure: {
-        ok: false,
-        kind: "platform-error",
-        status: 502,
-        message: "Cloud speech transcription failed (platform returned 502).",
-      },
-      category: "provider-error",
-      userFacing: false,
-    },
-  ];
-
-  for (const {
-    name,
-    failure,
-    category,
-    userFacing,
-    messageIncludes,
-    messageExcludes,
-  } of cases) {
-    test(name, () => {
-      const err = sttErrorFromCloudSpeech(
-        failure as Parameters<typeof sttErrorFromCloudSpeech>[0],
-      );
-      expect(err).toBeInstanceOf(SttError);
-      expect(err.category).toBe(category as SttError["category"]);
-      // User-facing when the failure carries real remediation (or a sanitized
-      // managed-auth message); a bare non-auth status stays non-user-facing for
-      // friendly category rewrite.
-      expect(err.userFacing).toBe(userFacing);
-      if (messageIncludes) {
-        expect(err.message).toContain(messageIncludes);
-      }
-      for (const excluded of messageExcludes ?? []) {
-        expect(err.message).not.toContain(excluded);
-      }
-    });
-  }
-});
-
-describe("describeSttFailure over managed STT failures", () => {
-  test("surfaces a cloud-supplied detail verbatim", () => {
-    const err = sttErrorFromCloudSpeech({
-      ok: false,
-      kind: "platform-error",
-      status: 429,
-      detail: "Too many requests, retry in 30s.",
-      message: "Too many requests, retry in 30s.",
-    });
-    expect(describeSttFailure(err, "cadet")).toBe(
-      "Too many requests, retry in 30s.",
-    );
-  });
-
-  test("replaces a bare HTTP-status fallback with friendly category copy", () => {
-    const err = sttErrorFromCloudSpeech({
-      ok: false,
-      kind: "platform-error",
-      status: 429,
-      message: "Cloud speech transcription failed (platform returned 429).",
-    });
-    const copy = describeSttFailure(err, "cadet");
-    expect(copy).not.toContain("platform returned 429");
-    expect(copy).toContain("rate-limiting");
-  });
-
-  test("bare auth failure gets sanitized reconnect copy, not the BYOK rewrite", () => {
-    const err = sttErrorFromCloudSpeech({
-      ok: false,
-      kind: "platform-error",
-      status: 401,
-      message: "Cloud speech transcription failed (platform returned 401).",
-    });
-    const copy = describeSttFailure(err, "cadet");
-    // Managed STT holds no local key: the "check your API key in Settings →
-    // Voice" guidance is wrong, and the raw HTTP status must not leak.
-    expect(copy).toContain("reconnect your Cadet account");
-    expect(copy).not.toContain("API key");
-    expect(copy).not.toContain("Settings → Voice");
-    expect(copy).not.toContain("platform returned 401");
-  });
-});

package/src/providers/speech-to-text/__tests__/cadet-speech-relay-connection.test.ts

@@ -1,126 +0,0 @@
-import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
-
-let mockMintResult: string | null = "minted-token";
-
-mock.module("../../../runtime/auth/token-service.js", () => ({
-  mintToken: (params: { aud: string; sub: string }) => {
-    if (mockMintResult === null) {
-      throw new Error("signing key unavailable");
-    }
-    return `${mockMintResult}:${params.aud}:${params.sub}`;
-  },
-}));
-
-import {
-  mapTunnelError,
-  probeTunnelRejection,
-  resolveSpeechRelayConnection,
-} from "../cadet-speech-relay-connection.js";
-
-describe("resolveSpeechRelayConnection", () => {
-  const originalEnv = process.env.GATEWAY_INTERNAL_URL;
-
-  beforeEach(() => {
-    mockMintResult = "minted-token";
-    delete process.env.GATEWAY_INTERNAL_URL;
-  });
-
-  afterEach(() => {
-    if (originalEnv === undefined) {
-      delete process.env.GATEWAY_INTERNAL_URL;
-    } else {
-      process.env.GATEWAY_INTERNAL_URL = originalEnv;
-    }
-  });
-
-  test("resolves the gateway origin and a per-dial token minter", async () => {
-    process.env.GATEWAY_INTERNAL_URL = "http://gateway:7822/";
-
-    const connection = await resolveSpeechRelayConnection();
-    expect(connection).not.toBeNull();
-    expect(connection!.httpBaseUrl).toBe("http://gateway:7822");
-    expect(connection!.wsBaseUrl).toBe("ws://gateway:7822");
-    // The token targets the gateway audience with the daemon service sub.
-    expect(connection!.mintServiceToken()).toBe(
-      "minted-token:cadet-gateway:svc:daemon:self",
-    );
-  });
-
-  test("returns null when the signing key is unavailable", async () => {
-    mockMintResult = null;
-    expect(await resolveSpeechRelayConnection()).toBeNull();
-  });
-});
-
-describe("mapTunnelError", () => {
-  test("maps the relay contract's codes onto categories", () => {
-    expect(mapTunnelError({ code: "invalid_key" })).toMatchObject({
-      category: "auth",
-      message: expect.stringContaining("TUNNEL_BASE_URL"),
-    });
-    expect(
-      mapTunnelError({ code: "missing_platform_connection" }),
-    ).toMatchObject({
-      category: "auth",
-      message: expect.stringContaining("cloud connect"),
-    });
-    expect(mapTunnelError({ code: "invalid_token" })).toMatchObject({
-      category: "auth",
-      message: expect.stringContaining("restart the assistant"),
-    });
-    expect(mapTunnelError({ code: "insufficient_balance" })).toMatchObject({
-      category: "provider-error",
-      message: expect.stringContaining("credits"),
-    });
-    expect(mapTunnelError({ code: "provider_unreachable" }).category).toBe(
-      "provider-error",
-    );
-    expect(mapTunnelError({ code: "upstream_error" }).category).toBe(
-      "provider-error",
-    );
-    expect(
-      mapTunnelError({ code: "novel_code", detail: "what" }),
-    ).toMatchObject({
-      category: "provider-error",
-      message: expect.stringContaining("novel_code"),
-    });
-  });
-});
-
-describe("probeTunnelRejection", () => {
-  const originalFetch = globalThis.fetch;
-
-  afterEach(() => {
-    globalThis.fetch = originalFetch;
-  });
-
-  test("returns the JSON rejection body", async () => {
-    globalThis.fetch = (async () =>
-      new Response(JSON.stringify({ code: "invalid_key", detail: "nope" }), {
-        status: 401,
-      })) as unknown as typeof fetch;
-
-    expect(await probeTunnelRejection("http://gateway.test/x")).toEqual({
-      code: "invalid_key",
-      detail: "nope",
-    });
-  });
-
-  test("returns null on the gateway's gate-passed 426", async () => {
-    globalThis.fetch = (async () =>
-      new Response(
-        JSON.stringify({ code: "upgrade_required", detail: "connect via WS" }),
-        { status: 426 },
-      )) as unknown as typeof fetch;
-
-    expect(await probeTunnelRejection("http://gateway.test/x")).toBeNull();
-  });
-
-  test("returns null when the probe itself fails", async () => {
-    globalThis.fetch = (async () => {
-      throw new Error("refused");
-    }) as unknown as typeof fetch;
-
-    expect(await probeTunnelRejection("http://gateway.test/x")).toBeNull();
-  });
-});

package/src/providers/speech-to-text/cadet-cloud-flux-realtime.ts

@@ -1,309 +0,0 @@
-/**
- * Cloud Flux STT through the gateway's speech relay
- * (gateway -> tunnel -> Deepgram Flux; tunnel contact is gateway-only).
- *
- * Composes {@link DeepgramFluxRealtimeTranscriber} against the relay's
- * managed STT v2 endpoint with `contract=flux`, so Flux's own turn events
- * arrive verbatim. Without that opt-in tunnel translates them into the
- * released v1 Deepgram dialect, which drops `EagerEndOfTurn` and
- * `TurnResumed` entirely and leaves live voice with no provider turn end to
- * act on.
- *
- * This wrapper owns what is relay-specific, mirroring
- * `CadetManagedRealtimeTranscriber` on the v1 path:
- *
- * - Dialing the gateway (`/v2/speech/stt/stream`, `?key=` carries a
- *   daemon-minted service token, no `model` param since tunnel derives and
- *   prices the Flux model from `language`).
- * - Surfacing `tunnel_error` control frames as categorized SttErrors instead
- *   of generic socket failures.
- * - Transparent re-dial on tunnel's 30-minute session cap, so one live-voice
- *   session can outlive it.
- *
- * There is deliberately no `finalizeUtterance`: Flux commits turns itself,
- * and the interface makes the method optional so live voice feature-detects
- * its absence and never asks for a flush.
- */
-
-import {
-  type StreamingTranscriber,
-  SttError,
-  type SttStreamServerEvent,
-} from "../../stt/types.js";
-import { getLogger } from "../../util/logger.js";
-import {
-  mapTunnelError,
-  probeTunnelRejection,
-  type SpeechRelayConnection,
-  type TunnelErrorInfo,
-} from "./cadet-speech-relay-connection.js";
-import { DeepgramFluxRealtimeTranscriber } from "./deepgram-flux-realtime.js";
-
-const log = getLogger("cadet-cloud-flux-realtime");
-
-/** Managed STT v2: tunnel resolves this to Deepgram's Flux `/v2/listen`. */
-const STT_STREAM_PATH = "/v2/speech/stt/stream";
-
-export interface CadetManagedFluxRealtimeOptions {
-  /** Audio sample rate in Hz (default: 16000). */
-  sampleRate?: number;
-  /**
-   * BCP-47 language code (or `"multi"`), forwarded to the relay. This is
-   * how tunnel picks between `flux-general-en` and `flux-general-multi`, so
-   * it is the only lever over the Flux model from this side.
-   */
-  language?: string;
-}
-
-export class CadetManagedFluxRealtimeTranscriber implements StreamingTranscriber {
-  readonly providerId = "cadet-flux" as const;
-  readonly boundaryId = "daemon-streaming" as const;
-
-  private readonly connection: SpeechRelayConnection;
-  private readonly options: CadetManagedFluxRealtimeOptions;
-
-  private onEvent: ((event: SttStreamServerEvent) => void) | null = null;
-  /** The current relay session; null while re-dialing after a session cap. */
-  private inner: DeepgramFluxRealtimeTranscriber | null = null;
-  /**
-   * The most recent `tunnel_error` frame from the current session. Set just
-   * before tunnel closes the socket; consumed when the inner adapter turns
-   * that close into an error event.
-   */
-  private pendingRelayError: TunnelErrorInfo | null = null;
-  /**
-   * Set when the current session hit tunnel's duration cap: the swap to a
-   * fresh session is deferred to the capped session's `closed` event so its
-   * close cleanup drains through first.
-   */
-  private redialOnClose = false;
-  private stopping = false;
-  private closedEmitted = false;
-  // Consumers see one stream across relay reconnects, with one turn sequence.
-  private turnIndexOffset = 0;
-  private latestTurnIndex = -1;
-
-  constructor(
-    connection: SpeechRelayConnection,
-    options: CadetManagedFluxRealtimeOptions = {},
-  ) {
-    this.connection = connection;
-    this.options = options;
-  }
-
-  async start(onEvent: (event: SttStreamServerEvent) => void): Promise<void> {
-    if (this.onEvent) {
-      throw new Error(
-        "CadetManagedFluxRealtimeTranscriber: start() called twice",
-      );
-    }
-    this.onEvent = onEvent;
-    try {
-      const inner = await this.dial();
-      if (this.stopping) {
-        // stop() raced the initial dial: it saw no inner to tear down and
-        // already emitted closed, so the freshly opened relay session must
-        // not be kept (a leaked session keeps tunnel metering).
-        inner.stop();
-        return;
-      }
-      this.inner = inner;
-    } catch (err) {
-      // A failed WebSocket upgrade exposes no HTTP details; replay the
-      // request as a plain GET to recover the relay's {code, detail}
-      // rejection.
-      const rejection = await probeTunnelRejection(this.probeUrl());
-      if (rejection) {
-        const mapped = mapTunnelError(rejection);
-        throw new SttError(mapped.category, mapped.message, {
-          userFacing: true,
-        });
-      }
-      throw err;
-    }
-  }
-
-  sendAudio(audio: Buffer, mimeType: string): void {
-    // Audio arriving during a session-cap re-dial (sub-second) is dropped,
-    // mirroring the inner adapter's backpressure-drop semantics.
-    this.inner?.sendAudio(audio, mimeType);
-  }
-
-  stop(): void {
-    if (this.stopping) {
-      return;
-    }
-    this.stopping = true;
-    if (this.inner) {
-      this.inner.stop();
-      return;
-    }
-    // Mid-redial stop: there is no session to drain.
-    this.emitClosedOnce();
-  }
-
-  // -- Relay session management ------------------------------------------
-
-  private async dial(): Promise<DeepgramFluxRealtimeTranscriber> {
-    this.pendingRelayError = null;
-    // Fresh per dial: a session-cap re-dial happens ~30 minutes in, long
-    // after any previously minted token expired.
-    const inner = new DeepgramFluxRealtimeTranscriber(
-      this.connection.mintServiceToken(),
-      {
-        baseUrl: this.connection.wsBaseUrl,
-        path: STT_STREAM_PATH,
-        queryAuth: true,
-        omitModelParam: true,
-        nativeContract: true,
-        ...(this.options.sampleRate !== undefined
-          ? { sampleRate: this.options.sampleRate }
-          : {}),
-        ...(this.options.language ? { language: this.options.language } : {}),
-        onUnhandledFrame: (frame) => this.handleRelayFrame(frame),
-      },
-    );
-    await inner.start((event) => this.handleInnerEvent(inner, event));
-    return inner;
-  }
-
-  private probeUrl(): string {
-    const key = encodeURIComponent(this.connection.mintServiceToken());
-    return `${this.connection.httpBaseUrl}${STT_STREAM_PATH}?key=${key}`;
-  }
-
-  private handleRelayFrame(frame: Record<string, unknown>): void {
-    if (frame.type !== "tunnel_error" || typeof frame.code !== "string") {
-      return;
-    }
-    this.pendingRelayError = {
-      code: frame.code,
-      ...(typeof frame.detail === "string" ? { detail: frame.detail } : {}),
-    };
-    log.info(
-      { code: frame.code, detail: frame.detail },
-      "Received tunnel_error frame on managed Flux relay",
-    );
-  }
-
-  private handleInnerEvent(
-    source: DeepgramFluxRealtimeTranscriber,
-    event: SttStreamServerEvent,
-  ): void {
-    // Events from a superseded session (the one replaced by a re-dial) must
-    // not leak through: its close/error was already accounted for.
-    if (source !== this.inner) {
-      return;
-    }
-
-    if (event.type === "error") {
-      const relayError = this.pendingRelayError;
-      if (relayError?.code === "session_duration_exceeded") {
-        // Tunnel's 30-minute cap, not a failure. Swallow the error but keep
-        // the capped session current so its close cleanup drains first; the
-        // re-dial happens on its `closed` event.
-        this.redialOnClose = !this.stopping;
-        return;
-      }
-      if (relayError) {
-        const mapped = mapTunnelError(relayError);
-        this.emit({
-          type: "error",
-          category: mapped.category,
-          message: mapped.message,
-        });
-        return;
-      }
-      this.emit(event);
-      return;
-    }
-
-    if (event.type === "closed") {
-      if (this.redialOnClose && !this.stopping) {
-        this.redialOnClose = false;
-        this.beginRedial();
-        return;
-      }
-      this.emitClosedOnce();
-      return;
-    }
-
-    if (
-      (event.type === "turn-start" || event.type === "turn-end") &&
-      event.turnIndex !== undefined
-    ) {
-      const turnIndex = this.turnIndexOffset + event.turnIndex;
-      this.latestTurnIndex = Math.max(this.latestTurnIndex, turnIndex);
-      this.emit({ ...event, turnIndex });
-      return;
-    }
-    this.emit(event);
-  }
-
-  /**
-   * Replace the capped session with a fresh one. Detached: audio sent during
-   * the swap is dropped (see {@link sendAudio}); a dial failure is a real
-   * error and ends the stream.
-   */
-  private beginRedial(): void {
-    log.info("Cloud Flux relay session hit tunnel's duration cap, re-dialing");
-    this.inner = null;
-    this.turnIndexOffset = this.latestTurnIndex + 1;
-    void (async () => {
-      try {
-        const inner = await this.dial();
-        if (this.stopping) {
-          inner.stop();
-          return;
-        }
-        this.inner = inner;
-        log.info("Cloud Flux relay re-dial complete; session continues");
-      } catch (err) {
-        if (this.stopping) {
-          return;
-        }
-        const rejection = await probeTunnelRejection(this.probeUrl());
-        if (rejection) {
-          const mapped = mapTunnelError(rejection);
-          this.emit({
-            type: "error",
-            category: mapped.category,
-            message: mapped.message,
-          });
-        } else {
-          this.emit({
-            type: "error",
-            category: "provider-error",
-            message: `Cloud Flux relay re-dial failed after the session cap: ${
-              err instanceof Error ? err.message : String(err)
-            }`,
-          });
-        }
-        this.emitClosedOnce();
-      }
-    })();
-  }
-
-  // -- Event emission -----------------------------------------------------
-
-  private emit(event: SttStreamServerEvent): void {
-    if (!this.onEvent || this.closedEmitted) {
-      return;
-    }
-    if (event.type === "closed") {
-      this.closedEmitted = true;
-    }
-    try {
-      this.onEvent(event);
-    } catch (err) {
-      log.warn(
-        { error: err },
-        "Listener error in Cadet Cloud Flux realtime adapter",
-      );
-    }
-  }
-
-  private emitClosedOnce(): void {
-    this.emit({ type: "closed" });
-  }
-}