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

package/src/utils/config.ts

@@ -0,0 +1,193 @@
+import type { IAgentRuntime } from "@elizaos/core";
+import { logger } from "@elizaos/core";
+import { DEFAULT_ELIZA_CLOUD_TEXT_MODEL } from "@elizaos/core";
+
+export const DEFAULT_ELIZA_CLOUD_LARGE_MODEL = "zai-glm-4.7";
+
+function getEnvValue(key: string): string | undefined {
+  if (typeof process === "undefined") {
+    return undefined;
+  }
+  const value = process.env[key];
+  return value === undefined ? undefined : String(value);
+}
+
+export function getSetting(
+  runtime: IAgentRuntime,
+  key: string,
+  defaultValue?: string
+): string | undefined {
+  const value = runtime.getSetting(key);
+  if (value !== undefined && value !== null) {
+    return String(value);
+  }
+  return getEnvValue(key) ?? defaultValue;
+}
+
+export function isBrowser(): boolean {
+  return (
+    typeof globalThis !== "undefined" &&
+    typeof (globalThis as { document?: Document }).document !== "undefined"
+  );
+}
+
+export function isProxyMode(runtime: IAgentRuntime): boolean {
+  return isBrowser() && !!getSetting(runtime, "ELIZAOS_CLOUD_BROWSER_BASE_URL");
+}
+
+export function getBaseURL(runtime: IAgentRuntime): string {
+  const browserURL = getSetting(runtime, "ELIZAOS_CLOUD_BROWSER_BASE_URL");
+  const baseURL = (
+    isBrowser() && browserURL
+      ? browserURL
+      : getSetting(runtime, "ELIZAOS_CLOUD_BASE_URL", "https://www.elizacloud.ai/api/v1")
+  ) as string;
+  return baseURL;
+}
+
+export function getEmbeddingBaseURL(runtime: IAgentRuntime): string {
+  const embeddingURL = isBrowser()
+    ? getSetting(runtime, "ELIZAOS_CLOUD_BROWSER_EMBEDDING_URL") ||
+      getSetting(runtime, "ELIZAOS_CLOUD_BROWSER_BASE_URL")
+    : getSetting(runtime, "ELIZAOS_CLOUD_EMBEDDING_URL");
+  if (embeddingURL) {
+    logger.debug(`[ELIZAOS_CLOUD] Using specific embedding base URL: ${embeddingURL}`);
+    return embeddingURL;
+  }
+  logger.debug("[ELIZAOS_CLOUD] Falling back to general base URL for embeddings.");
+  return getBaseURL(runtime);
+}
+
+export function getApiKey(runtime: IAgentRuntime): string | undefined {
+  return getSetting(runtime, "ELIZAOS_CLOUD_API_KEY");
+}
+
+export function getEmbeddingApiKey(runtime: IAgentRuntime): string | undefined {
+  const embeddingApiKey = getSetting(runtime, "ELIZAOS_CLOUD_EMBEDDING_API_KEY");
+  if (embeddingApiKey) {
+    logger.debug("[ELIZAOS_CLOUD] Using specific embedding API key (present)");
+    return embeddingApiKey;
+  }
+  logger.debug("[ELIZAOS_CLOUD] Falling back to general API key for embeddings.");
+  return getApiKey(runtime);
+}
+
+export function getSmallModel(runtime: IAgentRuntime): string {
+  return (
+    getSetting(runtime, "ELIZAOS_CLOUD_SMALL_MODEL") ??
+    (getSetting(runtime, "SMALL_MODEL", DEFAULT_ELIZA_CLOUD_TEXT_MODEL) as string)
+  );
+}
+
+export function getNanoModel(runtime: IAgentRuntime): string {
+  return (
+    getSetting(runtime, "ELIZAOS_CLOUD_NANO_MODEL") ??
+    getSetting(runtime, "NANO_MODEL") ??
+    getSmallModel(runtime)
+  );
+}
+
+export function getMediumModel(runtime: IAgentRuntime): string {
+  return (
+    getSetting(runtime, "ELIZAOS_CLOUD_MEDIUM_MODEL") ??
+    getSetting(runtime, "MEDIUM_MODEL") ??
+    getSmallModel(runtime)
+  );
+}
+
+export function getLargeModel(runtime: IAgentRuntime): string {
+  return (
+    getSetting(runtime, "ELIZAOS_CLOUD_LARGE_MODEL") ??
+    (getSetting(runtime, "LARGE_MODEL", DEFAULT_ELIZA_CLOUD_LARGE_MODEL) as string)
+  );
+}
+
+export function getMegaModel(runtime: IAgentRuntime): string {
+  return (
+    getSetting(runtime, "ELIZAOS_CLOUD_MEGA_MODEL") ??
+    getSetting(runtime, "MEGA_MODEL") ??
+    getLargeModel(runtime)
+  );
+}
+
+export function getResponseHandlerModel(runtime: IAgentRuntime): string {
+  return (
+    getSetting(runtime, "ELIZAOS_CLOUD_RESPONSE_HANDLER_MODEL") ??
+    getSetting(runtime, "ELIZAOS_CLOUD_SHOULD_RESPOND_MODEL") ??
+    getSetting(runtime, "RESPONSE_HANDLER_MODEL") ??
+    getSetting(runtime, "SHOULD_RESPOND_MODEL") ??
+    getSmallModel(runtime)
+  );
+}
+
+export function getActionPlannerModel(runtime: IAgentRuntime): string {
+  return (
+    getSetting(runtime, "ELIZAOS_CLOUD_ACTION_PLANNER_MODEL") ??
+    getSetting(runtime, "ELIZAOS_CLOUD_PLANNER_MODEL") ??
+    getSetting(runtime, "ACTION_PLANNER_MODEL") ??
+    getSetting(runtime, "PLANNER_MODEL") ??
+    getLargeModel(runtime)
+  );
+}
+
+export function getResponseModel(runtime: IAgentRuntime): string {
+  return (
+    getSetting(runtime, "ELIZAOS_CLOUD_RESPONSE_MODEL") ??
+    getSetting(runtime, "RESPONSE_MODEL") ??
+    getLargeModel(runtime)
+  );
+}
+
+export function getImageDescriptionModel(runtime: IAgentRuntime): string {
+  return getSetting(runtime, "ELIZAOS_CLOUD_IMAGE_DESCRIPTION_MODEL", "gpt-5.4-mini") as string;
+}
+
+export function getImageGenerationModel(runtime: IAgentRuntime): string {
+  return (
+    getSetting(runtime, "ELIZAOS_CLOUD_IMAGE_GENERATION_MODEL", "google/gemini-2.5-flash-image") ??
+    "google/gemini-2.5-flash-image"
+  );
+}
+
+export function getResearchModel(runtime: IAgentRuntime): string {
+  return (
+    getSetting(runtime, "ELIZAOS_CLOUD_RESEARCH_MODEL") ??
+    (getSetting(runtime, "RESEARCH_MODEL", "o3-deep-research") as string)
+  );
+}
+
+export function getTTSModel(runtime: IAgentRuntime): string {
+  return getSetting(runtime, "ELIZAOS_CLOUD_TTS_MODEL", "gpt-5-mini-tts") as string;
+}
+
+export function getTranscriptionModel(runtime: IAgentRuntime): string {
+  return getSetting(
+    runtime,
+    "ELIZAOS_CLOUD_TRANSCRIPTION_MODEL",
+    "gpt-5-mini-transcribe"
+  ) as string;
+}
+
+export function getExperimentalTelemetry(runtime: IAgentRuntime): boolean {
+  const setting = getSetting(runtime, "ELIZAOS_CLOUD_EXPERIMENTAL_TELEMETRY", "false");
+  return String(setting).toLowerCase() === "true";
+}
+
+/**
+ * Resolve a client-side timeout (ms) for a cloud model round-trip from `envKey`,
+ * falling back to `defaultMs`. `0`/negative/non-numeric → undefined (opt out).
+ *
+ * cloud-sdk applies NO default timeout (a fetch with no signal hangs until the
+ * platform default), so turn-blocking calls (TTS/STT in a voice turn, deep
+ * research) need an explicit ceiling or a stalled gateway hangs the turn.
+ */
+export function resolveCloudTimeoutMs(
+  envKey: string,
+  defaultMs: number
+): number | undefined {
+  const raw = typeof process !== "undefined" ? process.env[envKey] : undefined;
+  if (raw === undefined || raw.trim() === "") return defaultMs;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed)) return defaultMs;
+  return parsed <= 0 ? undefined : parsed;
+}

package/src/utils/events.ts

@@ -0,0 +1,65 @@
+import {
+  EventType,
+  type IAgentRuntime,
+  type ModelEventPayload,
+  type ModelTypeName,
+} from "@elizaos/core";
+import type { LanguageModelUsage } from "ai";
+
+/**
+ * Extra metadata that rides along with a {@link ModelEventPayload} so that
+ * downstream consumers (e.g. the waifu metering bridge) can attribute spend
+ * to a concrete model id and, when the cloud surfaces it, the authoritative
+ * post-markup USD cost it just debited from the org's credit balance.
+ *
+ * These are additive fields layered onto the standard payload — the core
+ * {@link ModelEventPayload} shape is unchanged for every other listener.
+ */
+export interface ModelUsageEventMeta {
+  /** Resolved provider model id, e.g. "anthropic/claude-opus-4.7". */
+  modelName?: string;
+  /**
+   * Authoritative USD cost the metered gateway charged for this call, when
+   * available (e.g. from a `usage.cost_usd` field or `X-Eliza-Cost-Usd`
+   * response header). Undefined when the cloud does not surface it; consumers
+   * then fall back to a token-based estimate.
+   */
+  costUsd?: number;
+}
+
+export type ModelUsageEventPayload = ModelEventPayload & ModelUsageEventMeta;
+
+export function emitModelUsageEvent(
+  runtime: IAgentRuntime,
+  type: ModelTypeName,
+  _prompt: string,
+  usage: Partial<LanguageModelUsage> & {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+  },
+  meta: ModelUsageEventMeta = {}
+) {
+  const inputTokens = Number(usage.inputTokens || 0);
+  const outputTokens = Number(usage.outputTokens || 0);
+  const totalTokens = Number(
+    usage.totalTokens != null ? usage.totalTokens : inputTokens + outputTokens
+  );
+
+  const payload: ModelUsageEventPayload = {
+    runtime,
+    source: "elizacloud",
+    type,
+    tokens: {
+      prompt: inputTokens,
+      completion: outputTokens,
+      total: totalTokens,
+    },
+    ...(meta.modelName ? { modelName: meta.modelName } : {}),
+    ...(typeof meta.costUsd === "number" && Number.isFinite(meta.costUsd)
+      ? { costUsd: meta.costUsd }
+      : {}),
+  };
+
+  runtime.emitEvent(EventType.MODEL_USED, payload);
+}

package/src/utils/helpers.ts

@@ -0,0 +1,107 @@
+import { logger } from "@elizaos/core";
+import { JSONParseError } from "ai";
+import type { ImageDescriptionResult } from "../types";
+
+export function getJsonRepairFunction(): (params: {
+  text: string;
+  error: unknown;
+}) => Promise<string | null> {
+  return async ({ text, error }: { text: string; error: unknown }) => {
+    try {
+      if (error instanceof JSONParseError) {
+        const cleanedText = text.replace(/```json\n|\n```|```/g, "");
+        JSON.parse(cleanedText);
+        return cleanedText;
+      }
+      return null;
+    } catch (jsonError) {
+      const message = jsonError instanceof Error ? jsonError.message : String(jsonError);
+      logger.warn(`Failed to repair JSON text: ${message}`);
+      return null;
+    }
+  };
+}
+
+export function detectAudioMimeType(buffer: Buffer): string {
+  if (buffer.length < 12) {
+    return "application/octet-stream";
+  }
+
+  if (
+    buffer[0] === 0x52 &&
+    buffer[1] === 0x49 &&
+    buffer[2] === 0x46 &&
+    buffer[3] === 0x46 &&
+    buffer[8] === 0x57 &&
+    buffer[9] === 0x41 &&
+    buffer[10] === 0x56 &&
+    buffer[11] === 0x45
+  ) {
+    return "audio/wav";
+  }
+
+  if (
+    (buffer[0] === 0x49 && buffer[1] === 0x44 && buffer[2] === 0x33) || // ID3
+    (buffer[0] === 0xff && (buffer[1] & 0xe0) === 0xe0) // MPEG sync
+  ) {
+    return "audio/mpeg";
+  }
+
+  if (buffer[0] === 0x4f && buffer[1] === 0x67 && buffer[2] === 0x67 && buffer[3] === 0x53) {
+    return "audio/ogg";
+  }
+
+  if (buffer[0] === 0x66 && buffer[1] === 0x4c && buffer[2] === 0x61 && buffer[3] === 0x43) {
+    return "audio/flac";
+  }
+
+  if (buffer[4] === 0x66 && buffer[5] === 0x74 && buffer[6] === 0x79 && buffer[7] === 0x70) {
+    return "audio/mp4";
+  }
+
+  if (buffer[0] === 0x1a && buffer[1] === 0x45 && buffer[2] === 0xdf && buffer[3] === 0xa3) {
+    return "audio/webm";
+  }
+
+  logger.warn("Could not detect audio format from buffer, using generic binary type");
+  return "application/octet-stream";
+}
+
+export async function webStreamToNodeStream(webStream: ReadableStream<Uint8Array>) {
+  try {
+    const { Readable } = await import("node:stream");
+    const reader = webStream.getReader();
+
+    return new Readable({
+      async read() {
+        try {
+          const { done, value } = await reader.read();
+          if (done) {
+            this.push(null);
+          } else {
+            this.push(value);
+          }
+        } catch (error) {
+          this.destroy(error as Error);
+        }
+      },
+      destroy(error, callback) {
+        reader.cancel().finally(() => callback(error));
+      },
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error(`Failed to load node:stream module: ${message}`);
+    throw new Error(
+      `Cannot convert stream: node:stream module unavailable. This feature requires a Node.js environment.`
+    );
+  }
+}
+
+export function parseImageDescriptionResponse(responseText: string): ImageDescriptionResult {
+  const titleMatch = responseText.match(/title[:\s]+(.+?)(?:\n|$)/i);
+  const title = titleMatch?.[1]?.trim() || "Image Analysis";
+  const description = responseText.replace(/title[:\s]+(.+?)(?:\n|$)/i, "").trim();
+
+  return { title, description };
+}

package/src/utils/responses-output.ts

@@ -0,0 +1,115 @@
+type JsonRecord = Record<string, unknown>;
+
+function asRecord(value: unknown): JsonRecord | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value as JsonRecord;
+}
+
+function normalizeContentItems(value: unknown): unknown[] {
+  if (Array.isArray(value)) return value;
+  if (typeof value === "string") return [{ type: "text", text: value }];
+  return value && typeof value === "object" ? [value] : [];
+}
+
+function extractTextFromContentItem(value: unknown): string[] {
+  if (typeof value === "string") {
+    return [value];
+  }
+
+  const record = asRecord(value);
+  if (!record) return [];
+
+  const text =
+    typeof record.text === "string"
+      ? record.text
+      : typeof record.output_text === "string"
+        ? record.output_text
+        : typeof record.content === "string"
+          ? record.content
+          : "";
+  const type = typeof record.type === "string" ? record.type : undefined;
+
+  if (text && (!type || type === "output_text" || type === "text")) {
+    return [text];
+  }
+
+  return [];
+}
+
+function extractTextFromOutputItem(value: unknown): string[] {
+  const record = asRecord(value);
+  if (!record) return [];
+
+  const directContent = normalizeContentItems(record.content);
+  if (directContent.length > 0) {
+    return directContent.flatMap(extractTextFromContentItem);
+  }
+
+  const nestedMessage = asRecord(record.message);
+  if (nestedMessage) {
+    return normalizeContentItems(nestedMessage.content).flatMap(extractTextFromContentItem);
+  }
+
+  const type = typeof record.type === "string" ? record.type : undefined;
+  const text =
+    typeof record.text === "string"
+      ? record.text
+      : typeof record.output_text === "string"
+        ? record.output_text
+        : "";
+  if (text && (type === "output_text" || type === "text")) {
+    return [text];
+  }
+
+  return [];
+}
+
+function extractTextFromChoice(value: unknown): string[] {
+  const record = asRecord(value);
+  if (!record) return [];
+
+  if (typeof record.text === "string" && record.text) {
+    return [record.text];
+  }
+
+  const message = asRecord(record.message);
+  if (!message) {
+    return [];
+  }
+
+  return normalizeContentItems(message.content).flatMap(extractTextFromContentItem);
+}
+
+/**
+ * Recover text from Responses-style payloads, tolerating both the documented
+ * `output_text` field and the common structured `output` item variants.
+ *
+ * Cloud responses sometimes carry the same body in BOTH `output_text` AND
+ * `output[]`/`choices[]`. Joining segments in that case duplicates the model
+ * output downstream (caller sees `…json{…}\n``````json{…}…`), which then
+ * trips JSON.parse with "Unrecognized token '`'" because of the run of
+ * backticks where the two copies meet. Prefer the first non-empty source
+ * instead of joining.
+ */
+export function extractResponsesOutputText(data: unknown): string {
+  const record = asRecord(data);
+  if (!record) return "";
+
+  if (typeof record.output_text === "string" && record.output_text.trim()) {
+    return record.output_text;
+  }
+
+  if (Array.isArray(record.output)) {
+    const fromOutput = record.output.flatMap(extractTextFromOutputItem).join("");
+    if (fromOutput.trim()) return fromOutput;
+  }
+
+  if (Array.isArray(record.choices)) {
+    const fromChoices = record.choices.flatMap(extractTextFromChoice).join("");
+    if (fromChoices.trim()) return fromChoices;
+  }
+
+  return "";
+}

package/src/utils/sdk-client.ts

@@ -0,0 +1,41 @@
+import { CloudApiClient, ElizaCloudClient } from "@elizaos/cloud-sdk";
+import type { IAgentRuntime } from "@elizaos/core";
+import {
+  getApiKey,
+  getBaseURL,
+  getEmbeddingApiKey,
+  getEmbeddingBaseURL,
+  isBrowser,
+} from "./config";
+
+function trimTrailingSlash(value: string): string {
+  return value.replace(/\/+$/, "");
+}
+
+function apiBaseToSiteBaseUrl(apiBaseUrl: string): string {
+  const trimmed = trimTrailingSlash(apiBaseUrl);
+  return trimmed.endsWith("/api/v1") ? trimmed.slice(0, -"/api/v1".length) : trimmed;
+}
+
+function apiKeyForRuntime(runtime: IAgentRuntime, embedding = false): string | undefined {
+  if (isBrowser()) return undefined;
+  return embedding ? getEmbeddingApiKey(runtime) : getApiKey(runtime);
+}
+
+export function createCloudApiClient(runtime: IAgentRuntime, embedding = false): CloudApiClient {
+  const baseUrl = embedding ? getEmbeddingBaseURL(runtime) : getBaseURL(runtime);
+  return new ElizaCloudClient({
+    apiBaseUrl: trimTrailingSlash(baseUrl),
+    baseUrl: apiBaseToSiteBaseUrl(baseUrl),
+    apiKey: apiKeyForRuntime(runtime, embedding),
+  }).v1;
+}
+
+export function createElizaCloudClient(runtime: IAgentRuntime): ElizaCloudClient {
+  const apiBaseUrl = trimTrailingSlash(getBaseURL(runtime));
+  return new ElizaCloudClient({
+    apiBaseUrl,
+    baseUrl: apiBaseToSiteBaseUrl(apiBaseUrl),
+    apiKey: apiKeyForRuntime(runtime),
+  });
+}