@elizaos/plugin-elizacloud 2.0.0-alpha.8 → 2.0.11-beta.7

package/src/lib/server-cloud-tts.ts

@@ -0,0 +1,301 @@
+/**
+ * Cloud TTS helpers — proxy to Eliza Cloud (`elizacloud.ai`).
+ *
+ * Pure / config-driven helpers (TTS API key resolution, base URL resolution,
+ * voice / model id normalization, compat header mirroring) live in
+ * `@elizaos/shared/elizacloud/server-cloud-tts` so host-layer packages can
+ * resolve cloud TTS configuration without reverse-importing this plugin.
+ *
+ * The HTTP request handler (`handleCloudTtsPreviewRoute`) stays here because
+ * it wires together the runtime route system.
+ */
+import type http from "node:http";
+import { sanitizeSpeechText } from "@elizaos/core";
+import {
+  _internalResolveCloudApiKey,
+  ELIZA_CLOUD_TTS_MAX_TEXT_CHARS,
+  resolveCloudProxyTtsModel,
+  resolveCloudTtsCandidateUrls,
+  resolveElizaCloudTtsVoiceId,
+  shouldRetryCloudTtsUpstream,
+  ttsDebug,
+  ttsDebugTextPreview,
+} from "@elizaos/shared";
+
+export {
+  __resetCloudBaseUrlCache,
+  ELIZA_CLOUD_TTS_MAX_TEXT_CHARS,
+  ensureCloudTtsApiKeyAlias,
+  mirrorCompatHeaders,
+  normalizeElizaCloudTtsModelId,
+  resolveCloudProxyTtsModel,
+  resolveCloudTtsBaseUrl,
+  resolveCloudTtsCandidateUrls,
+  resolveElevenLabsApiKeyForCloudMode,
+  resolveElizaCloudTtsVoiceId,
+  shouldRetryCloudTtsUpstream,
+} from "@elizaos/shared";
+
+/** Browser → API correlation (never forwarded to Eliza Cloud). */
+export function readTtsDebugClientHeaders(
+  req: Pick<http.IncomingMessage, "headers">,
+): {
+  messageId?: string;
+  clipSegment?: string;
+  hearingFull?: string;
+} {
+  const pick = (name: string): string | undefined => {
+    const raw = req.headers[name];
+    if (raw == null) return undefined;
+    const v = Array.isArray(raw) ? raw[0] : raw;
+    return typeof v === "string" && v.trim() ? v.trim() : undefined;
+  };
+  const decode = (enc: string | undefined): string | undefined => {
+    if (!enc) return undefined;
+    try {
+      return decodeURIComponent(enc);
+    } catch {
+      return enc;
+    }
+  };
+  return {
+    messageId: decode(pick("x-elizaos-tts-message-id")),
+    clipSegment: decode(pick("x-elizaos-tts-clip-segment")),
+    hearingFull: decode(pick("x-elizaos-tts-full-preview")),
+  };
+}
+
+function ttsClientDbgFields(
+  hdr: ReturnType<typeof readTtsDebugClientHeaders>,
+): Record<string, string> {
+  const o: Record<string, string> = {};
+  if (hdr.messageId) o.messageId = hdr.messageId;
+  if (hdr.clipSegment) o.clipSegment = hdr.clipSegment;
+  if (hdr.hearingFull) o.hearingFull = hdr.hearingFull;
+  return o;
+}
+
+function pickBodyString(
+  body: Record<string, unknown>,
+  camel: string,
+  snake: string,
+): unknown {
+  const a = body[camel];
+  if (typeof a === "string" && a.trim()) return a;
+  const b = body[snake];
+  if (typeof b === "string" && b.trim()) return b;
+  return undefined;
+}
+
+async function readRawRequestBody(req: http.IncomingMessage): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks);
+}
+
+function sendJsonResponse(
+  res: http.ServerResponse,
+  status: number,
+  body: unknown,
+): void {
+  if (res.headersSent) return;
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json; charset=utf-8");
+  res.end(JSON.stringify(body));
+}
+
+function sendJsonErrorResponse(
+  res: http.ServerResponse,
+  status: number,
+  message: string,
+): void {
+  sendJsonResponse(res, status, { error: message });
+}
+
+function forwardCloudTtsUpstreamError(
+  res: http.ServerResponse,
+  status: number,
+  bodyText: string,
+): void {
+  if (res.headersSent) return;
+  const trimmed = bodyText.trim();
+  if (
+    (trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+    (trimmed.startsWith("[") && trimmed.endsWith("]"))
+  ) {
+    try {
+      const parsed: unknown = JSON.parse(trimmed);
+      sendJsonResponse(res, status, parsed);
+      return;
+    } catch {
+      /* fall through */
+    }
+  }
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json; charset=utf-8");
+  res.end(
+    JSON.stringify({ error: trimmed || "Eliza Cloud TTS request failed" }),
+  );
+}
+
+export async function handleCloudTtsPreviewRoute(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+): Promise<boolean> {
+  const clientTtsDbg = readTtsDebugClientHeaders(req);
+  const dbgExtra = ttsClientDbgFields(clientTtsDbg);
+
+  const cloudApiKey = _internalResolveCloudApiKey();
+  if (!cloudApiKey) {
+    ttsDebug("server:cloud-tts:reject", {
+      reason: "no_api_key",
+      ...dbgExtra,
+    });
+    sendJsonErrorResponse(
+      res,
+      401,
+      "Eliza Cloud is not connected. Connect your Eliza Cloud account first.",
+    );
+    return true;
+  }
+
+  const rawBody = await readRawRequestBody(req);
+  let body: Record<string, unknown>;
+  try {
+    body = JSON.parse(rawBody.toString("utf8")) as Record<string, unknown>;
+  } catch {
+    sendJsonErrorResponse(res, 400, "Invalid JSON request body");
+    return true;
+  }
+
+  const text = sanitizeSpeechText(
+    typeof body.text === "string" ? body.text : "",
+  );
+  if (!text) {
+    sendJsonErrorResponse(res, 400, "Missing text");
+    return true;
+  }
+
+  if (text.length > ELIZA_CLOUD_TTS_MAX_TEXT_CHARS) {
+    sendJsonErrorResponse(
+      res,
+      400,
+      `Text too long. Maximum length is ${ELIZA_CLOUD_TTS_MAX_TEXT_CHARS} characters`,
+    );
+    return true;
+  }
+
+  const cloudModel = resolveCloudProxyTtsModel(
+    pickBodyString(body, "modelId", "model_id"),
+  );
+  const cloudVoice = resolveElizaCloudTtsVoiceId(
+    pickBodyString(body, "voiceId", "voice_id"),
+  );
+  const cloudUrls = resolveCloudTtsCandidateUrls();
+
+  const ttsPreview = ttsDebugTextPreview(text);
+  ttsDebug("server:cloud-tts:proxy", {
+    textChars: text.length,
+    preview: ttsPreview,
+    modelId: cloudModel,
+    voiceId: cloudVoice,
+    urlCandidates: cloudUrls.length,
+    ...dbgExtra,
+  });
+
+  try {
+    let lastStatus = 0;
+    let lastDetails = "unknown error";
+    let cloudResponse: Response | null = null;
+    for (let i = 0; i < cloudUrls.length; i++) {
+      const cloudUrl = cloudUrls[i];
+      if (cloudUrl === undefined) {
+        continue;
+      }
+      const attempt = await fetch(cloudUrl, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${cloudApiKey}`,
+          "x-api-key": cloudApiKey,
+          "Content-Type": "application/json",
+          Accept: "audio/mpeg",
+        },
+        body: JSON.stringify({
+          text,
+          voiceId: cloudVoice,
+          modelId: cloudModel,
+        }),
+      });
+
+      if (attempt.ok) {
+        cloudResponse = attempt;
+        ttsDebug("server:cloud-tts:upstream-ok", {
+          urlIndex: i,
+          status: attempt.status,
+          preview: ttsPreview,
+          ...dbgExtra,
+        });
+        break;
+      }
+
+      lastStatus = attempt.status;
+      lastDetails = await attempt.text().catch(() => "unknown error");
+      ttsDebug("server:cloud-tts:upstream-retry", {
+        urlIndex: i,
+        status: attempt.status,
+        preview: ttsPreview,
+        ...dbgExtra,
+      });
+
+      const hasMoreCandidates = i < cloudUrls.length - 1;
+      if (!hasMoreCandidates || !shouldRetryCloudTtsUpstream(attempt.status)) {
+        break;
+      }
+    }
+    if (!cloudResponse) {
+      ttsDebug("server:cloud-tts:reject", {
+        reason: "upstream_failed",
+        lastStatus,
+        preview: ttsPreview,
+        ...dbgExtra,
+      });
+      if (
+        lastStatus === 400 ||
+        lastStatus === 401 ||
+        lastStatus === 402 ||
+        lastStatus === 403 ||
+        lastStatus === 429
+      ) {
+        forwardCloudTtsUpstreamError(res, lastStatus, lastDetails);
+        return true;
+      }
+      sendJsonErrorResponse(
+        res,
+        502,
+        `Eliza Cloud TTS failed (${lastStatus || 502}): ${lastDetails}`,
+      );
+      return true;
+    }
+
+    const audioBuffer = Buffer.from(await cloudResponse.arrayBuffer());
+    ttsDebug("server:cloud-tts:success", {
+      bytes: audioBuffer.length,
+      preview: ttsPreview,
+      ...dbgExtra,
+    });
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "audio/mpeg");
+    res.setHeader("Cache-Control", "no-store");
+    res.end(audioBuffer);
+    return true;
+  } catch (err) {
+    sendJsonErrorResponse(
+      res,
+      502,
+      `Eliza Cloud TTS request failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return true;
+  }
+}

package/src/lib/state-paths.ts

@@ -0,0 +1,28 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  getElizaNamespace,
+  resolveStateDir,
+  resolveUserPath,
+} from "@elizaos/core";
+
+export { getElizaNamespace, resolveStateDir, resolveUserPath };
+
+export function resolveConfigPath(
+  env: NodeJS.ProcessEnv = process.env,
+  stateDirPath: string = resolveStateDir(env),
+): string {
+  const override = env.ELIZA_CONFIG_PATH?.trim();
+  if (override) return resolveUserPath(override);
+
+  const namespace = getElizaNamespace(env);
+  const primaryPath = path.join(stateDirPath, `${namespace}.json`);
+  if (fs.existsSync(primaryPath)) return primaryPath;
+
+  if (namespace !== "eliza") {
+    const legacyPath = path.join(stateDirPath, "eliza.json");
+    if (fs.existsSync(legacyPath)) return legacyPath;
+  }
+
+  return primaryPath;
+}

package/src/lib/tts-debug.ts

@@ -0,0 +1,5 @@
+/**
+ * TTS debug logging. Implementation moved to
+ * `@elizaos/shared/elizacloud/tts-debug`.
+ */
+export { isTtsDebugEnabled, ttsDebug, ttsDebugTextPreview } from "@elizaos/shared";

package/src/models/embeddings.ts

@@ -0,0 +1,298 @@
+import type { IAgentRuntime, TextEmbeddingParams } from "@elizaos/core";
+import {
+  logger,
+  ModelType,
+  timeInferenceSpan,
+  VECTOR_DIMS,
+} from "@elizaos/core";
+import { getSetting } from "../utils/config";
+import { emitModelUsageEvent } from "../utils/events";
+import { createCloudApiClient } from "../utils/sdk-client";
+
+const MAX_BATCH_SIZE = 100;
+
+// ── Bounded retry/backoff for the /embeddings round-trip ──────────────────
+// Embeddings are off the turn's critical path (queueEmbeddingGeneration is
+// fire-and-forget), so a stall here delays the embedding QUEUE, not a reply.
+// The old behaviour — one blind 30s (or full retry-after) sleep then a single
+// retry — could park the queue for 30s+ on a transient 429. Replaced with
+// bounded exponential backoff + jitter, a CAP on any single wait (so a large
+// server retry-after can't stall the queue indefinitely), and a per-request
+// client-side timeout (the endpoint had none, so a hung gateway hung the
+// queue forever).
+//
+// Handler retries are deliberately SMALL: the EmbeddingGenerationService
+// BatchQueue already wraps generateEmbedding in its own multi-attempt backoff,
+// so this layer absorbs only a single transient burst (one quick retry) and
+// defers sustained pressure to the queue — otherwise the two backoffs compound.
+const EMBED_MAX_ATTEMPTS = 2;
+const EMBED_BACKOFF_BASE_MS = 1_000;
+const EMBED_BACKOFF_CAP_MS = 8_000;
+const EMBED_REQUEST_TIMEOUT_MS = 60_000;
+
+/**
+ * Backoff before the next embedding attempt. Exponential (base·2^attempt) as a
+ * floor, honoring the server's `retry-after` when present, but never longer
+ * than {@link EMBED_BACKOFF_CAP_MS}; ±25% jitter spreads retries from a burst.
+ */
+function embeddingBackoffMs(attempt: number, retryAfterSec?: number): number {
+  const exp = EMBED_BACKOFF_BASE_MS * 2 ** attempt;
+  const serverHint =
+    typeof retryAfterSec === "number" && retryAfterSec > 0
+      ? retryAfterSec * 1000
+      : 0;
+  const base = Math.min(EMBED_BACKOFF_CAP_MS, Math.max(exp, serverHint));
+  return Math.round(base * (1 + Math.random() * 0.25));
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function extractRateLimitInfo(response: Response): {
+  remainingRequests?: number;
+  remainingTokens?: number;
+  limitRequests?: number;
+  limitTokens?: number;
+  resetRequests?: string;
+  resetTokens?: string;
+  retryAfter?: number;
+} {
+  return {
+    remainingRequests:
+      parseInt(response.headers.get("x-ratelimit-remaining-requests") || "", 10) || undefined,
+    remainingTokens:
+      parseInt(response.headers.get("x-ratelimit-remaining-tokens") || "", 10) || undefined,
+    limitRequests:
+      parseInt(response.headers.get("x-ratelimit-limit-requests") || "", 10) || undefined,
+    limitTokens: parseInt(response.headers.get("x-ratelimit-limit-tokens") || "", 10) || undefined,
+    resetRequests: response.headers.get("x-ratelimit-reset-requests") || undefined,
+    resetTokens: response.headers.get("x-ratelimit-reset-tokens") || undefined,
+    retryAfter: parseInt(response.headers.get("retry-after") || "", 10) || undefined,
+  };
+}
+
+function getEmbeddingConfig(runtime: IAgentRuntime) {
+  const embeddingModelName = getSetting(
+    runtime,
+    "ELIZAOS_CLOUD_EMBEDDING_MODEL",
+    "text-embedding-3-small"
+  );
+  const embeddingDimension = Number.parseInt(
+    getSetting(runtime, "ELIZAOS_CLOUD_EMBEDDING_DIMENSIONS", "1536") || "1536",
+    10
+  ) as (typeof VECTOR_DIMS)[keyof typeof VECTOR_DIMS];
+
+  if (!Object.values(VECTOR_DIMS).includes(embeddingDimension)) {
+    const errorMsg = `Invalid embedding dimension: ${embeddingDimension}. Must be one of: ${Object.values(VECTOR_DIMS).join(", ")}`;
+    logger.error(errorMsg);
+    throw new Error(errorMsg);
+  }
+
+  return { embeddingModelName, embeddingDimension };
+}
+
+/**
+ * The init probe vector. `runtime.ensureEmbeddingDimension()` calls the handler
+ * with `null` purely to learn the vector length; it only inspects `.length`, so
+ * a deterministic non-zero[0] marker vector is the correct, legitimate response.
+ * This is the ONLY place a synthetic vector is returned — every real failure
+ * throws so it can never be persisted as a corrupt embedding (Commandment 8).
+ */
+function createInitProbeVector(dimension: number): number[] {
+  const vector = Array(dimension).fill(0);
+  vector[0] = 0.1;
+  return vector;
+}
+
+export interface BatchEmbeddingParams {
+  texts: string[];
+}
+
+export async function handleTextEmbedding(
+  runtime: IAgentRuntime,
+  params: TextEmbeddingParams | string | null
+): Promise<number[]> {
+  const { embeddingDimension } = getEmbeddingConfig(runtime);
+
+  if (params === null) {
+    logger.debug("Creating test embedding for initialization");
+    return createInitProbeVector(embeddingDimension);
+  }
+
+  let text: string;
+  if (typeof params === "string") {
+    text = params;
+  } else if (typeof params === "object" && params.text) {
+    text = params.text;
+  } else {
+    // A malformed request is a programming error, not a recoverable runtime
+    // state. Throw instead of returning a marker vector that would silently
+    // corrupt the embedding store (Commandment 8).
+    throw new Error("Invalid input format for embedding: expected string or { text: string }");
+  }
+
+  if (!text.trim()) {
+    throw new Error("Cannot generate embedding for empty text");
+  }
+
+  const results = await handleBatchTextEmbedding(runtime, [text]);
+  return results[0];
+}
+
+export interface BatchEmbeddingResult {
+  embedding: number[];
+  index: number;
+  success: boolean;
+  error?: string;
+}
+
+export async function handleBatchTextEmbedding(
+  runtime: IAgentRuntime,
+  texts: string[]
+): Promise<number[][]> {
+  const { embeddingModelName, embeddingDimension } = getEmbeddingConfig(runtime);
+  const client = createCloudApiClient(runtime, true);
+
+  if (!texts || texts.length === 0) {
+    return [];
+  }
+
+  // Every text must be non-empty: an empty input cannot produce a meaningful
+  // vector, and a marker/zero vector would silently corrupt the store. Surface
+  // the bad input to the caller (Commandment 8) instead of papering over it.
+  const validTexts: { text: string; originalIndex: number }[] = [];
+  for (let i = 0; i < texts.length; i++) {
+    const text = texts[i]?.trim();
+    if (!text) {
+      throw new Error(`Cannot generate embedding for empty text at index ${i}`);
+    }
+    validTexts.push({ text, originalIndex: i });
+  }
+
+  const results: number[][] = new Array(texts.length);
+
+  for (let batchStart = 0; batchStart < validTexts.length; batchStart += MAX_BATCH_SIZE) {
+    const batchEnd = Math.min(batchStart + MAX_BATCH_SIZE, validTexts.length);
+    const batch = validTexts.slice(batchStart, batchEnd);
+    const batchTexts = batch.map((b) => b.text);
+
+    logger.info(
+      `[BatchEmbeddings] Processing batch ${Math.floor(batchStart / MAX_BATCH_SIZE) + 1}/${Math.ceil(validTexts.length / MAX_BATCH_SIZE)}: ${batch.length} texts`
+    );
+
+    try {
+      // Records a `cloud.embedding` span on the active per-turn timer when an
+      // embedding happens to be on a turn's critical path (most are queued /
+      // detached, so this is a no-op there — which is exactly what proves they
+      // don't add to turn latency). Retries transient throttling/5xx with
+      // bounded exponential backoff (see EMBED_* constants) instead of a single
+      // 30s blind sleep.
+      let response: Response | null = null;
+      for (let attempt = 0; attempt < EMBED_MAX_ATTEMPTS; attempt++) {
+        const resp = await timeInferenceSpan(
+          "cloud.embedding",
+          () =>
+            client.requestRaw("POST", "/embeddings", {
+              json: {
+                model: embeddingModelName,
+                input: batchTexts,
+              },
+              timeoutMs: EMBED_REQUEST_TIMEOUT_MS,
+            }),
+          { batch: batchTexts.length, attempt }
+        );
+
+        const rateLimitInfo = extractRateLimitInfo(resp);
+        if (
+          rateLimitInfo.remainingRequests !== undefined &&
+          rateLimitInfo.remainingRequests < 50
+        ) {
+          logger.warn(
+            `[BatchEmbeddings] Rate limit: ${rateLimitInfo.remainingRequests}/${rateLimitInfo.limitRequests} requests remaining`
+          );
+        }
+
+        const transient =
+          resp.status === 429 ||
+          resp.status === 502 ||
+          resp.status === 503 ||
+          resp.status === 504;
+        if (transient && attempt < EMBED_MAX_ATTEMPTS - 1) {
+          const delay = embeddingBackoffMs(attempt, rateLimitInfo.retryAfter);
+          logger.warn(
+            `[BatchEmbeddings] ${resp.status} (attempt ${attempt + 1}/${EMBED_MAX_ATTEMPTS}) — backing off ${delay}ms`
+          );
+          // Drain the body so the underlying connection can be reused.
+          await resp.text().catch(() => undefined);
+          await sleep(delay);
+          continue;
+        }
+        response = resp;
+        break;
+      }
+
+      // Type guard: the loop assigns `response` on its final iteration, so this
+      // is unreachable in practice.
+      if (!response) {
+        throw new Error("[BatchEmbeddings] No response after retry loop");
+      }
+
+      if (!response.ok) {
+        // Auth errors (401/403) are non-recoverable with the current key.
+        // Every other non-OK status is just as fatal for this batch — neither
+        // can produce real vectors. Throw in both cases so the router falls
+        // through to the next provider (e.g. local inference) instead of
+        // silently persisting marker/zero vectors that corrupt the embedding
+        // store. Commandment 8: don't hide broken pipelines behind fallbacks.
+        if (response.status === 401 || response.status === 403) {
+          throw new Error(
+            `[BatchEmbeddings] Authentication failed (${response.status}). ` +
+              `Check ELIZAOS_CLOUD_API_KEY or ELIZAOS_CLOUD_EMBEDDING_API_KEY — ` +
+              `the current key is not authorized for the embedding endpoint.`
+          );
+        }
+        throw new Error(
+          `[BatchEmbeddings] API error: ${response.status} ${response.statusText}`
+        );
+      }
+
+      const data = (await response.json()) as {
+        data?: Array<{ embedding: number[]; index: number }>;
+        usage?: { prompt_tokens: number; total_tokens: number };
+      };
+
+      if (!data?.data || !Array.isArray(data.data)) {
+        throw new Error("[BatchEmbeddings] API returned invalid response structure");
+      }
+
+      for (const item of data.data) {
+        const originalIndex = batch[item.index].originalIndex;
+        results[originalIndex] = item.embedding;
+      }
+
+      if (data.usage) {
+        const usage = {
+          inputTokens: data.usage.prompt_tokens,
+          outputTokens: 0,
+          totalTokens: data.usage.total_tokens,
+        };
+        emitModelUsageEvent(runtime, ModelType.TEXT_EMBEDDING, `batch:${batch.length}`, usage);
+      }
+
+      logger.debug(
+        `[BatchEmbeddings] Got ${batch.length} embeddings (${embeddingDimension}d)`
+      );
+    } catch (error) {
+      // Any failure in this batch (HTTP error, transport error, malformed body)
+      // means we have no real vectors for it. Log context and re-throw so the
+      // router can fall through to another provider; never persist marker/zero
+      // vectors that would corrupt the embedding store (Commandment 8).
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error(`[BatchEmbeddings] Batch failed: ${message}`);
+      throw error instanceof Error ? error : new Error(message);
+    }
+  }
+
+  return results;
+}