@mycadet/assistant 0.12.11 → 0.13.0

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

@@ -1,315 +0,0 @@
-/**
- * Managed realtime STT through the gateway's speech relay
- * (gateway → tunnel → Deepgram; tunnel contact is gateway-only).
- *
- * Composes {@link DeepgramRealtimeTranscriber} — both relay legs speak
- * Deepgram's live wire protocol verbatim, so all frame handling (Results
- * parsing, backpressure, finalize/flush serialization) is inherited, not
- * duplicated. This wrapper owns what is relay-specific:
- *
- * - Dialing the gateway (`/v1/speech/stt/stream`, `?key=` carries a
- *   daemon-minted service token, no `model` param — the model is pinned
- *   server-side).
- * - Surfacing `tunnel_error` control frames (tunnel's own, or synthesized
- *   by the gateway for upstream failures) as categorized SttErrors
- *   instead of generic socket failures.
- * - Transparent re-dial on tunnel's 30-minute session cap: live-voice
- *   reuses ONE streaming transcriber across utterance cycles (#37662), so
- *   a normal conversation can outlive the cap. Tunnel settles the in-flight
- *   utterance (trailing finals arrive before the close), then this wrapper
- *   opens a fresh relay session and continues without surfacing an error.
- */
-
-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 { DeepgramRealtimeTranscriber } from "./deepgram-realtime.js";
-
-const log = getLogger("cadet-cloud-realtime");
-
-const STT_STREAM_PATH = "/v1/speech/stt/stream";
-
-export interface CadetManagedRealtimeOptions {
-  /** Audio sample rate in Hz (default: 16000). */
-  sampleRate?: number;
-  /** BCP-47 language code, forwarded to the relay. */
-  language?: string;
-  /**
-   * Emit `final` events only at utterance boundaries (telephony mode).
-   * Note: tunnel's param allowlist has no `utterance_end_ms`, so boundaries
-   * come from Deepgram's endpointing (`speech_final`) alone.
-   */
-  utteranceBoundaryFinals?: boolean;
-}
-
-export class CadetManagedRealtimeTranscriber implements StreamingTranscriber {
-  readonly providerId = "cadet" as const;
-  readonly boundaryId = "daemon-streaming" as const;
-
-  private readonly connection: SpeechRelayConnection;
-  private readonly options: CadetManagedRealtimeOptions;
-
-  private onEvent: ((event: SttStreamServerEvent) => void) | null = null;
-  /** The current relay session; null while re-dialing after a session cap. */
-  private inner: DeepgramRealtimeTranscriber | 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 (withheld finals, outstanding finalizes) drains
-   * through first.
-   */
-  private redialOnClose = false;
-  private stopping = false;
-  private closedEmitted = false;
-
-  constructor(
-    connection: SpeechRelayConnection,
-    options: CadetManagedRealtimeOptions = {},
-  ) {
-    this.connection = connection;
-    this.options = options;
-  }
-
-  async start(onEvent: (event: SttStreamServerEvent) => void): Promise<void> {
-    if (this.onEvent) {
-      throw new Error("CadetManagedRealtimeTranscriber: 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 (the gateway replays its whole gate on non-upgrade
-      // requests, including tunnel's own).
-      const rejection = await probeTunnelRejection(this.probeUrl());
-      if (rejection) {
-        // Typed so the stream session preserves the mapped category —
-        // an auth/setup failure must not surface as a provider outage.
-        // `userFacing` keeps the mapped remediation (reconnect, top up
-        // credits) from being rewritten to BYOK "check your API key" copy.
-        const mapped = mapTunnelError(rejection);
-        throw new SttError(mapped.category, mapped.message, {
-          userFacing: true,
-        });
-      }
-      throw err;
-    }
-  }
-
-  sendAudio(audio: Buffer, mimeType: string): void {
-    // ponytail: audio arriving during a session-cap re-dial (sub-second) is
-    // dropped, mirroring the inner adapter's backpressure-drop semantics;
-    // buffer-and-replay if the gap ever proves audible.
-    this.inner?.sendAudio(audio, mimeType);
-  }
-
-  finalizeUtterance(): void {
-    if (this.inner) {
-      this.inner.finalizeUtterance();
-      return;
-    }
-    // No live session (re-dialing or closed) — nothing is buffered
-    // provider-side, so the flush is trivially complete.
-    this.emit({ type: "finalized" });
-  }
-
-  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<DeepgramRealtimeTranscriber> {
-    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 DeepgramRealtimeTranscriber(
-      this.connection.mintServiceToken(),
-      {
-        baseUrl: this.connection.wsBaseUrl,
-        path: STT_STREAM_PATH,
-        queryAuth: true,
-        omitModelParam: true,
-        sampleRate: this.options.sampleRate,
-        ...(this.options.language ? { language: this.options.language } : {}),
-        ...(this.options.utteranceBoundaryFinals
-          ? { utteranceBoundaryFinals: true }
-          : {}),
-        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 STT relay",
-    );
-  }
-
-  private handleInnerEvent(
-    source: DeepgramRealtimeTranscriber,
-    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: its close cleanup still flushes
-        // withheld boundary finals and settles outstanding finalizes, and
-        // those events must drain before the swap. 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;
-    }
-
-    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(
-      "Managed STT relay session hit tunnel's duration cap — re-dialing",
-    );
-    this.inner = null;
-    void (async () => {
-      try {
-        const inner = await this.dial();
-        if (this.stopping) {
-          inner.stop();
-          return;
-        }
-        this.inner = inner;
-        log.info("Managed STT relay re-dial complete — session continues");
-      } catch (err) {
-        if (this.stopping) {
-          return;
-        }
-        // Same diagnosis as start(): a rejected upgrade hides the relay's
-        // {code, detail} — mid-call credit exhaustion or a revoked
-        // connection must surface with its mapped message, not a generic
-        // transport error.
-        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 speech 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 realtime adapter",
-      );
-    }
-  }
-
-  private emitClosedOnce(): void {
-    this.emit({ type: "closed" });
-  }
-}

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

@@ -1,108 +0,0 @@
-/**
- * Cadet Cloud batch STT: transcription through the cloud's managed
- * speech endpoint (Cadet-held Deepgram key, billed to Cadet credits). No
- * provider API key exists on this machine — availability is the cloud
- * connection itself.
- */
-
-import {
-  type CloudSpeechResult,
-  managedSpeechAvailable,
-  managedSpeechTranscribe,
-} from "../../cloud/cloud-speech.js";
-import {
-  SttError,
-  type SttErrorCategory,
-  type SttTranscribeResult,
-} from "../../stt/types.js";
-
-type CloudSpeechFailure = Extract<CloudSpeechResult<never>, { ok: false }>;
-
-/**
- * Whether cloud speech can be used at all: a cloud connection with a
- * platform assistant ID. The credential-store lookup used for API-key
- * providers does not apply to `cadet`.
- */
-export async function cadetCloudSpeechAvailable(): Promise<boolean> {
-  return managedSpeechAvailable();
-}
-
-/**
- * Map a cloud-speech failure onto the normalized STT error categories.
- *
- * `insufficient_balance` gets a user-actionable message — the fix is topping
- * up Cadet credits, not editing provider config.
- *
- * Cloud speech has no provider API key on this machine, so the BYOK "check
- * your API key" rewrite never applies. A failure is flagged `userFacing` —
- * surfaced verbatim by `describeSttFailure` — when it carries actionable
- * remediation: a cloud reconnect (`unavailable`), a credit top-up
- * (`insufficient_balance`), or the cloud's own `detail` message. A failure
- * that fell back to a bare HTTP status (no `detail`) is left non-user-facing so
- * `describeSttFailure` emits friendly category copy instead of leaking the raw
- * status — except a bare auth status (401/403), which would be rewritten to the
- * wrong BYOK "check your API key" guidance, so it gets its own sanitized
- * cloud-connection message.
- */
-export function sttErrorFromCloudSpeech(failure: CloudSpeechFailure): SttError {
-  const hasDetail = failure.detail !== undefined;
-  const userFacing =
-    failure.kind === "unavailable" ||
-    failure.code === "insufficient_balance" ||
-    hasDetail;
-  const managed = (category: SttErrorCategory, message: string): SttError =>
-    new SttError(category, message, { userFacing });
-
-  if (failure.kind === "unavailable") {
-    return managed("auth", failure.message);
-  }
-  if (failure.code === "insufficient_balance") {
-    return managed(
-      "provider-error",
-      "Cadet credits are exhausted — add funds to your Cadet account to continue using managed transcription.",
-    );
-  }
-  switch (failure.status) {
-    case 401:
-    case 403:
-      // A bare auth failure must stay user-facing so describeSttFailure skips
-      // its BYOK "check your API key" rewrite — managed STT has no local key.
-      // `managed()` would be non-user-facing here (see `userFacing` above), so
-      // construct the sanitized cloud-connection message directly.
-      return hasDetail
-        ? managed("auth", failure.message)
-        : new SttError(
-            "auth",
-            "Cadet couldn't authenticate with the cloud while transcribing — reconnect your Cadet account, then retry.",
-            { userFacing: true },
-          );
-    case 429:
-      return managed("rate-limit", failure.message);
-    case 413:
-      return managed("invalid-audio", failure.message);
-    default:
-      return managed("provider-error", failure.message);
-  }
-}
-
-/**
- * Transcribe a complete audio buffer via the cloud. Throws {@link SttError}
- * on failure (already normalized — `normalizeSttError` passes it through).
- */
-export async function cadetCloudTranscribe(
-  audio: Buffer,
-  mimeType: string,
-  signal?: AbortSignal,
-  language?: string,
-): Promise<SttTranscribeResult> {
-  const result = await managedSpeechTranscribe({
-    audio,
-    mimeType,
-    signal,
-    language,
-  });
-  if (!result.ok) {
-    throw sttErrorFromCloudSpeech(result);
-  }
-  return { text: result.value.text };
-}

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

@@ -1,176 +0,0 @@
-/**
- * Shared plumbing for dialing the GATEWAY's cloud speech relay
- * (`/v1/speech/{stt,tts}/stream`): connection resolution, and mapping the
- * relay's error contract onto SttError categories.
- *
- * The daemon never dials tunnel itself — tunnel contact is gateway-only so
- * deterministic policy stays in a process the agent cannot rewrite. The
- * gateway route authenticates the daemon with a self-minted service JWT
- * (both processes share the HMAC signing key), attaches the Cadet
- * assistant API key on its own upstream leg to tunnel, and pipes Deepgram
- * wire frames verbatim. The gateway mirrors tunnel's error contract:
- * rejections are JSON `{code, detail}` bodies, and mid-session failures
- * are one `tunnel_error` text frame followed by an abnormal close.
- */
-
-import { getGatewayInternalBaseUrl } from "../../config/env.js";
-import { CURRENT_POLICY_EPOCH } from "../../runtime/auth/policy.js";
-import { mintToken } from "../../runtime/auth/token-service.js";
-import type { SttErrorCategory } from "../../stt/types.js";
-import { getLogger } from "../../util/logger.js";
-
-const log = getLogger("cadet-speech-relay");
-
-/**
- * The principal the gateway's speech-relay route accepts. Must match
- * DAEMON_SERVICE_SUB in gateway/src/http/routes/speech-relay-websocket.ts
- * — the packages don't share auth constants.
- */
-const DAEMON_SERVICE_SUB = "svc:daemon:self";
-
-/**
- * Per-dial token TTL. Deliberately short: the gateway validates at
- * upgrade time only, and every (re-)dial mints fresh — a session that
- * outlives its token (tunnel caps at 30 minutes) is fine, but a re-dial
- * must never reuse one.
- */
-const RELAY_TOKEN_TTL_SECONDS = 300;
-
-export interface SpeechRelayConnection {
-  /** ws(s) origin of the gateway for the relay WebSocket dial. */
-  wsBaseUrl: string;
-  /** http(s) origin of the gateway for diagnostic (non-upgrade) probes. */
-  httpBaseUrl: string;
-  /**
-   * Mint a fresh daemon service token for one dial. Called per
-   * connection attempt so session-cap re-dials never present an expired
-   * token.
-   */
-  mintServiceToken: () => string;
-}
-
-/**
- * Resolve everything needed to dial the gateway's speech relay, or null
- * when the daemon cannot mint a service token (signing key unavailable) —
- * the availability signal for the streaming resolver.
- */
-export async function resolveSpeechRelayConnection(): Promise<SpeechRelayConnection | null> {
-  const mintServiceToken = () =>
-    mintToken({
-      aud: "cadet-gateway",
-      sub: DAEMON_SERVICE_SUB,
-      // Least-privilege (ATL-1033): this token rides in the dial URL, so it
-      // must open nothing but the speech relay.
-      scope_profile: "speech_relay_v1",
-      policy_epoch: CURRENT_POLICY_EPOCH,
-      ttlSeconds: RELAY_TOKEN_TTL_SECONDS,
-    });
-  try {
-    // Fail here, not mid-dial, when the signing key is unavailable.
-    mintServiceToken();
-  } catch (err) {
-    log.warn(
-      { error: err instanceof Error ? err.message : String(err) },
-      "Cloud speech relay unavailable: cannot mint a gateway service token",
-    );
-    return null;
-  }
-  const httpBaseUrl = getGatewayInternalBaseUrl().replace(/\/+$/, "");
-  return {
-    httpBaseUrl,
-    wsBaseUrl: httpBaseUrl.replace(/^http/, "ws"),
-    mintServiceToken,
-  };
-}
-
-/** The relay's error contract: HTTP reject bodies and tunnel_error frames. */
-export interface TunnelErrorInfo {
-  code: string;
-  detail?: string;
-}
-
-/**
- * Map a relay error code onto an SttError category and a user-actionable
- * message. Codes are tunnel's contract plus the gateway route's own
- * (`missing_platform_connection`, `invalid_token`) — unknown codes degrade
- * to a provider error carrying the code for diagnosability.
- */
-export function mapTunnelError(error: TunnelErrorInfo): {
-  category: SttErrorCategory;
-  message: string;
-} {
-  switch (error.code) {
-    case "invalid_key":
-      return {
-        category: "auth",
-        message:
-          "The Cadet speech relay rejected this assistant's API key — the assistant's platform environment may not match the relay it is dialing (set TUNNEL_BASE_URL on the gateway to the matching environment, e.g. https://tunnel-staging.mycadet.ai for staging).",
-      };
-    case "missing_platform_connection":
-      return {
-        category: "auth",
-        message:
-          "Cloud speech needs a working Cadet Cloud connection — reconnect with 'assistant cloud connect'.",
-      };
-    case "invalid_token":
-      return {
-        category: "auth",
-        message:
-          "The assistant's cloud-speech session was rejected by its gateway — the services may be out of sync; restart the assistant.",
-      };
-    case "insufficient_balance":
-      return {
-        category: "provider-error",
-        message:
-          "Cloud speech is paused: your Cadet organization is out of credits. Top up credits to continue.",
-      };
-    case "provider_unreachable":
-    case "upstream_error":
-      return {
-        category: "provider-error",
-        message: `Cloud speech relay could not reach the speech provider (${error.code}).`,
-      };
-    default:
-      return {
-        category: "provider-error",
-        message: `Cloud speech relay error: ${error.code}${
-          error.detail ? ` — ${error.detail}` : ""
-        }`,
-      };
-  }
-}
-
-/**
- * Diagnose a failed WebSocket dial by replaying the request as a plain
- * HTTP GET. The gateway route runs its whole gate on non-upgrade requests
- * (token, stored credential, then tunnel's own gate via an upstream probe),
- * so a rejected upgrade reproduces as a JSON `{code, detail}` body; a
- * request that passes everything returns a 426 whose body is ignored here
- * (null → the original failure was transient/transport-level).
- *
- * The WebSocket API exposes no HTTP response details on a failed upgrade,
- * so this probe is the only way to distinguish "bad connection state"
- * from "gateway down".
- */
-export async function probeTunnelRejection(
-  httpUrl: string,
-): Promise<TunnelErrorInfo | null> {
-  try {
-    const res = await fetch(httpUrl, {
-      signal: AbortSignal.timeout(5_000),
-    });
-    if (res.ok || res.status === 426) {
-      return null;
-    }
-    const body = (await res.json()) as { code?: unknown; detail?: unknown };
-    if (typeof body.code !== "string") {
-      return null;
-    }
-    return {
-      code: body.code,
-      ...(typeof body.detail === "string" ? { detail: body.detail } : {}),
-    };
-  } catch {
-    return null;
-  }
-}