@full-self-developing/fsd 1.0.0

package/extensions/volcengine/tts.ts

@@ -0,0 +1,266 @@
+import * as crypto from "node:crypto";
+import { fetchWithSsrFGuard } from "openclaw/plugin-sdk/ssrf-runtime";
+
+export type VolcengineTtsEncoding = "ogg_opus" | "mp3" | "pcm" | "wav";
+
+type VolcengineTTSParams = {
+  text: string;
+  apiKey?: string;
+  appId?: string;
+  token?: string;
+  voice?: string;
+  cluster?: string;
+  resourceId?: string;
+  appKey?: string;
+  baseUrl?: string;
+  speedRatio?: number;
+  volumeRatio?: number;
+  pitchRatio?: number;
+  emotion?: string;
+  encoding?: VolcengineTtsEncoding;
+  timeoutMs?: number;
+};
+
+const DEFAULT_SEED_VOICE = "en_female_anna_mars_bigtts";
+const DEFAULT_LEGACY_VOICE = "zh_female_xiaohe_uranus_bigtts";
+const DEFAULT_CLUSTER = "volcano_tts";
+const DEFAULT_SEED_TTS_RESOURCE_ID = "seed-tts-1.0";
+const DEFAULT_SEED_TTS_APP_KEY = "aGjiRDfUWi";
+const BYTEPLUS_SEED_TTS_URL =
+  "https://voice.ap-southeast-1.bytepluses.com/api/v3/tts/unidirectional";
+const VOLCENGINE_LEGACY_TTS_URL = "https://openspeech.bytedance.com/api/v1/tts";
+
+type VolcengineTtsResponse = {
+  code?: number;
+  message?: string;
+  data?: string;
+};
+
+function parseJsonObject(text: string, providerName: string): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("expected JSON object");
+    }
+    return parsed as Record<string, unknown>;
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(`${providerName} TTS: failed to parse response JSON: ${detail}`, {
+      cause: err,
+    });
+  }
+}
+
+function toTtsResponse(parsed: Record<string, unknown>): VolcengineTtsResponse {
+  const header =
+    parsed.header && typeof parsed.header === "object" && !Array.isArray(parsed.header)
+      ? (parsed.header as Record<string, unknown>)
+      : undefined;
+  return {
+    code:
+      typeof parsed.code === "number"
+        ? parsed.code
+        : typeof header?.code === "number"
+          ? header.code
+          : undefined,
+    message:
+      typeof parsed.message === "string"
+        ? parsed.message
+        : typeof header?.message === "string"
+          ? header.message
+          : undefined,
+    data: typeof parsed.data === "string" ? parsed.data : undefined,
+  };
+}
+
+function parseLegacyTtsResponse(text: string): VolcengineTtsResponse {
+  return toTtsResponse(parseJsonObject(text, "Volcengine"));
+}
+
+function parseSeedTtsFrames(text: string): VolcengineTtsResponse[] {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return [];
+  }
+
+  try {
+    return [toTtsResponse(parseJsonObject(trimmed, "BytePlus Seed Speech"))];
+  } catch {
+    // The HTTP API streams JSON frames; Response.text() preserves line breaks.
+  }
+
+  const frames: VolcengineTtsResponse[] = [];
+  for (const line of trimmed.split(/\r?\n/)) {
+    const item = line.trim();
+    if (!item) {
+      continue;
+    }
+    const json = item.startsWith("data:") ? item.slice("data:".length).trim() : item;
+    frames.push(toTtsResponse(parseJsonObject(json, "BytePlus Seed Speech")));
+  }
+  return frames;
+}
+
+function hostnameAllowlist(url: string): string[] {
+  return [new URL(url).hostname];
+}
+
+function seedAudioFormat(encoding: VolcengineTtsEncoding): "ogg_opus" | "mp3" | "pcm" {
+  return encoding === "wav" ? "pcm" : encoding;
+}
+
+async function seedSpeechTTS(params: VolcengineTTSParams & { apiKey: string }): Promise<Buffer> {
+  const {
+    text,
+    apiKey,
+    voice = DEFAULT_SEED_VOICE,
+    resourceId = DEFAULT_SEED_TTS_RESOURCE_ID,
+    appKey = DEFAULT_SEED_TTS_APP_KEY,
+    baseUrl = BYTEPLUS_SEED_TTS_URL,
+    speedRatio = 1.0,
+    emotion,
+    encoding = "ogg_opus",
+    timeoutMs = 30_000,
+  } = params;
+  const audioFormat = seedAudioFormat(encoding);
+
+  const payload = JSON.stringify({
+    user: { uid: "openclaw" },
+    req_params: {
+      text,
+      speaker: voice,
+      audio_params: {
+        format: audioFormat,
+        sample_rate: 24_000,
+      },
+      ...(speedRatio !== 1.0 ? { speed_ratio: speedRatio } : {}),
+      ...(emotion ? { emotion } : {}),
+    },
+  });
+
+  const { response, release } = await fetchWithSsrFGuard({
+    url: baseUrl,
+    init: {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Connection: "keep-alive",
+        "X-Api-Key": apiKey,
+        "X-Api-Resource-Id": resourceId,
+        "X-Api-App-Key": appKey,
+      },
+      body: payload,
+    },
+    timeoutMs,
+    policy: { hostnameAllowlist: hostnameAllowlist(baseUrl) },
+    auditContext: "volcengine.tts",
+  });
+
+  try {
+    const frames = parseSeedTtsFrames(await response.text());
+    const chunks: Buffer[] = [];
+    for (const frame of frames) {
+      if (frame.code === 0) {
+        if (frame.data) {
+          chunks.push(Buffer.from(frame.data, "base64"));
+        }
+        continue;
+      }
+      if (frame.code === 20000000) {
+        continue;
+      }
+      throw new Error(
+        `BytePlus Seed Speech TTS error ${frame.code ?? response.status}: ${
+          frame.message ?? "unknown"
+        }`,
+      );
+    }
+
+    if (!response.ok || chunks.length === 0) {
+      throw new Error(`BytePlus Seed Speech TTS error ${response.status}: no audio data`);
+    }
+
+    return Buffer.concat(chunks);
+  } finally {
+    await release();
+  }
+}
+
+async function legacyVolcengineTTS(
+  params: VolcengineTTSParams & { appId: string; token: string },
+): Promise<Buffer> {
+  const {
+    text,
+    appId,
+    token,
+    voice = DEFAULT_LEGACY_VOICE,
+    cluster = DEFAULT_CLUSTER,
+    baseUrl = VOLCENGINE_LEGACY_TTS_URL,
+    speedRatio = 1.0,
+    volumeRatio = 1.0,
+    pitchRatio = 1.0,
+    emotion,
+    encoding = "ogg_opus",
+    timeoutMs = 30_000,
+  } = params;
+
+  const payload = JSON.stringify({
+    app: { appid: appId, token, cluster },
+    user: { uid: "openclaw" },
+    audio: {
+      voice_type: voice,
+      encoding,
+      speed_ratio: speedRatio,
+      volume_ratio: volumeRatio,
+      pitch_ratio: pitchRatio,
+      ...(emotion ? { emotion } : {}),
+    },
+    request: {
+      reqid: crypto.randomUUID(),
+      text,
+      text_type: "plain",
+      operation: "query",
+    },
+  });
+
+  const { response, release } = await fetchWithSsrFGuard({
+    url: baseUrl,
+    init: {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer;${token}`,
+      },
+      body: payload,
+    },
+    timeoutMs,
+    policy: { hostnameAllowlist: hostnameAllowlist(baseUrl) },
+    auditContext: "volcengine.tts",
+  });
+
+  try {
+    const body = parseLegacyTtsResponse(await response.text());
+    if (!response.ok || body.code !== 3000 || !body.data) {
+      throw new Error(
+        `Volcengine TTS error ${body.code ?? response.status}: ${body.message ?? "unknown"}`,
+      );
+    }
+    return Buffer.from(body.data, "base64");
+  } finally {
+    await release();
+  }
+}
+
+export async function volcengineTTS(params: VolcengineTTSParams): Promise<Buffer> {
+  if (params.apiKey) {
+    return seedSpeechTTS({ ...params, apiKey: params.apiKey });
+  }
+
+  if (params.appId && params.token) {
+    return legacyVolcengineTTS({ ...params, appId: params.appId, token: params.token });
+  }
+
+  throw new Error(
+    "Volcengine TTS credentials missing. Set a BytePlus Seed Speech API key or legacy AppID/token.",
+  );
+}

package/extensions/voyage/embedding-batch.ts

@@ -0,0 +1,315 @@
+import { createInterface } from "node:readline";
+import { Readable } from "node:stream";
+import {
+  applyEmbeddingBatchOutputLine,
+  buildBatchHeaders,
+  buildEmbeddingBatchGroupOptions,
+  EMBEDDING_BATCH_ENDPOINT,
+  extractBatchErrorMessage,
+  formatUnavailableBatchError,
+  normalizeBatchBaseUrl,
+  postJsonWithRetry,
+  resolveBatchCompletionFromStatus,
+  resolveCompletedBatchResult,
+  runEmbeddingBatchGroups,
+  throwIfBatchTerminalFailure,
+  type EmbeddingBatchExecutionParams,
+  type EmbeddingBatchStatus,
+  type BatchCompletionResult,
+  type ProviderBatchOutputLine,
+  uploadBatchJsonlFile,
+  withRemoteHttpResponse,
+} from "openclaw/plugin-sdk/memory-core-host-engine-embeddings";
+import type { VoyageEmbeddingClient } from "./embedding-provider.js";
+
+/**
+ * Voyage Batch API Input Line format.
+ * See: https://docs.voyageai.com/docs/batch-inference
+ */
+type VoyageBatchRequest = {
+  custom_id: string;
+  body: {
+    input: string | string[];
+  };
+};
+
+type VoyageBatchStatus = EmbeddingBatchStatus;
+type VoyageBatchOutputLine = ProviderBatchOutputLine;
+
+const VOYAGE_BATCH_ENDPOINT = EMBEDDING_BATCH_ENDPOINT;
+const VOYAGE_BATCH_COMPLETION_WINDOW = "12h";
+const VOYAGE_BATCH_MAX_REQUESTS = 50000;
+
+type VoyageBatchDeps = {
+  now: () => number;
+  sleep: (ms: number) => Promise<void>;
+  postJsonWithRetry: typeof postJsonWithRetry;
+  uploadBatchJsonlFile: typeof uploadBatchJsonlFile;
+  withRemoteHttpResponse: typeof withRemoteHttpResponse;
+};
+
+function resolveVoyageBatchDeps(overrides: Partial<VoyageBatchDeps> | undefined): VoyageBatchDeps {
+  return {
+    now: overrides?.now ?? Date.now,
+    sleep:
+      overrides?.sleep ??
+      (async (ms: number) => await new Promise((resolve) => setTimeout(resolve, ms))),
+    postJsonWithRetry: overrides?.postJsonWithRetry ?? postJsonWithRetry,
+    uploadBatchJsonlFile: overrides?.uploadBatchJsonlFile ?? uploadBatchJsonlFile,
+    withRemoteHttpResponse: overrides?.withRemoteHttpResponse ?? withRemoteHttpResponse,
+  };
+}
+
+async function assertVoyageResponseOk(res: Response, context: string): Promise<void> {
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`${context}: ${res.status} ${text}`);
+  }
+}
+
+function buildVoyageBatchRequest<T>(params: {
+  client: VoyageEmbeddingClient;
+  path: string;
+  onResponse: (res: Response) => Promise<T>;
+}) {
+  const baseUrl = normalizeBatchBaseUrl(params.client);
+  return {
+    url: `${baseUrl}/${params.path}`,
+    ssrfPolicy: params.client.ssrfPolicy,
+    init: {
+      headers: buildBatchHeaders(params.client, { json: true }),
+    },
+    onResponse: params.onResponse,
+  };
+}
+
+async function submitVoyageBatch(params: {
+  client: VoyageEmbeddingClient;
+  requests: VoyageBatchRequest[];
+  agentId: string;
+  deps: VoyageBatchDeps;
+}): Promise<VoyageBatchStatus> {
+  const baseUrl = normalizeBatchBaseUrl(params.client);
+  const inputFileId = await params.deps.uploadBatchJsonlFile({
+    client: params.client,
+    requests: params.requests,
+    errorPrefix: "voyage batch file upload failed",
+  });
+
+  // 2. Create batch job using Voyage Batches API
+  return await params.deps.postJsonWithRetry<VoyageBatchStatus>({
+    url: `${baseUrl}/batches`,
+    headers: buildBatchHeaders(params.client, { json: true }),
+    ssrfPolicy: params.client.ssrfPolicy,
+    body: {
+      input_file_id: inputFileId,
+      endpoint: VOYAGE_BATCH_ENDPOINT,
+      completion_window: VOYAGE_BATCH_COMPLETION_WINDOW,
+      request_params: {
+        model: params.client.model,
+        input_type: "document",
+      },
+      metadata: {
+        source: "clawdbot-memory",
+        agent: params.agentId,
+      },
+    },
+    errorPrefix: "voyage batch create failed",
+  });
+}
+
+async function fetchVoyageBatchStatus(params: {
+  client: VoyageEmbeddingClient;
+  batchId: string;
+  deps: VoyageBatchDeps;
+}): Promise<VoyageBatchStatus> {
+  return await params.deps.withRemoteHttpResponse(
+    buildVoyageBatchRequest({
+      client: params.client,
+      path: `batches/${params.batchId}`,
+      onResponse: async (res) => {
+        await assertVoyageResponseOk(res, "voyage batch status failed");
+        return (await res.json()) as VoyageBatchStatus;
+      },
+    }),
+  );
+}
+
+async function readVoyageBatchError(params: {
+  client: VoyageEmbeddingClient;
+  errorFileId: string;
+  deps: VoyageBatchDeps;
+}): Promise<string | undefined> {
+  try {
+    return await params.deps.withRemoteHttpResponse(
+      buildVoyageBatchRequest({
+        client: params.client,
+        path: `files/${params.errorFileId}/content`,
+        onResponse: async (res) => {
+          await assertVoyageResponseOk(res, "voyage batch error file content failed");
+          const text = await res.text();
+          if (!text.trim()) {
+            return undefined;
+          }
+          const lines = text
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => JSON.parse(line) as VoyageBatchOutputLine);
+          return extractBatchErrorMessage(lines);
+        },
+      }),
+    );
+  } catch (err) {
+    return formatUnavailableBatchError(err);
+  }
+}
+
+async function waitForVoyageBatch(params: {
+  client: VoyageEmbeddingClient;
+  batchId: string;
+  wait: boolean;
+  pollIntervalMs: number;
+  timeoutMs: number;
+  debug?: (message: string, data?: Record<string, unknown>) => void;
+  initial?: VoyageBatchStatus;
+  deps: VoyageBatchDeps;
+}): Promise<BatchCompletionResult> {
+  const start = params.deps.now();
+  let current: VoyageBatchStatus | undefined = params.initial;
+  while (true) {
+    const status =
+      current ??
+      (await fetchVoyageBatchStatus({
+        client: params.client,
+        batchId: params.batchId,
+        deps: params.deps,
+      }));
+    const state = status.status ?? "unknown";
+    if (state === "completed") {
+      return resolveBatchCompletionFromStatus({
+        provider: "voyage",
+        batchId: params.batchId,
+        status,
+      });
+    }
+    await throwIfBatchTerminalFailure({
+      provider: "voyage",
+      status: { ...status, id: params.batchId },
+      readError: async (errorFileId) =>
+        await readVoyageBatchError({
+          client: params.client,
+          errorFileId,
+          deps: params.deps,
+        }),
+    });
+    if (!params.wait) {
+      throw new Error(`voyage batch ${params.batchId} still ${state}; wait disabled`);
+    }
+    if (params.deps.now() - start > params.timeoutMs) {
+      throw new Error(`voyage batch ${params.batchId} timed out after ${params.timeoutMs}ms`);
+    }
+    params.debug?.(`voyage batch ${params.batchId} ${state}; waiting ${params.pollIntervalMs}ms`);
+    await params.deps.sleep(params.pollIntervalMs);
+    current = undefined;
+  }
+}
+
+export async function runVoyageEmbeddingBatches(
+  params: {
+    client: VoyageEmbeddingClient;
+    agentId: string;
+    requests: VoyageBatchRequest[];
+    deps?: Partial<VoyageBatchDeps>;
+  } & EmbeddingBatchExecutionParams,
+): Promise<Map<string, number[]>> {
+  const deps = resolveVoyageBatchDeps(params.deps);
+  return await runEmbeddingBatchGroups({
+    ...buildEmbeddingBatchGroupOptions(params, {
+      maxRequests: VOYAGE_BATCH_MAX_REQUESTS,
+      debugLabel: "memory embeddings: voyage batch submit",
+    }),
+    runGroup: async ({ group, groupIndex, groups, byCustomId }) => {
+      const batchInfo = await submitVoyageBatch({
+        client: params.client,
+        requests: group,
+        agentId: params.agentId,
+        deps,
+      });
+      if (!batchInfo.id) {
+        throw new Error("voyage batch create failed: missing batch id");
+      }
+      const batchId = batchInfo.id;
+
+      params.debug?.("memory embeddings: voyage batch created", {
+        batchId: batchInfo.id,
+        status: batchInfo.status,
+        group: groupIndex + 1,
+        groups,
+        requests: group.length,
+      });
+
+      const completed = await resolveCompletedBatchResult({
+        provider: "voyage",
+        status: batchInfo,
+        wait: params.wait,
+        waitForBatch: async () =>
+          await waitForVoyageBatch({
+            client: params.client,
+            batchId,
+            wait: params.wait,
+            pollIntervalMs: params.pollIntervalMs,
+            timeoutMs: params.timeoutMs,
+            debug: params.debug,
+            initial: batchInfo,
+            deps,
+          }),
+      });
+
+      const baseUrl = normalizeBatchBaseUrl(params.client);
+      const errors: string[] = [];
+      const remaining = new Set(group.map((request) => request.custom_id));
+
+      await deps.withRemoteHttpResponse({
+        url: `${baseUrl}/files/${completed.outputFileId}/content`,
+        ssrfPolicy: params.client.ssrfPolicy,
+        init: {
+          headers: buildBatchHeaders(params.client, { json: true }),
+        },
+        onResponse: async (contentRes) => {
+          if (!contentRes.ok) {
+            const text = await contentRes.text();
+            throw new Error(`voyage batch file content failed: ${contentRes.status} ${text}`);
+          }
+
+          if (!contentRes.body) {
+            return;
+          }
+          const reader = createInterface({
+            input: Readable.fromWeb(
+              contentRes.body as unknown as import("stream/web").ReadableStream,
+            ),
+            terminal: false,
+          });
+
+          for await (const rawLine of reader) {
+            if (!rawLine.trim()) {
+              continue;
+            }
+            const line = JSON.parse(rawLine) as VoyageBatchOutputLine;
+            applyEmbeddingBatchOutputLine({ line, remaining, errors, byCustomId });
+          }
+        },
+      });
+
+      if (errors.length > 0) {
+        throw new Error(`voyage batch ${batchInfo.id} failed: ${errors.join("; ")}`);
+      }
+      if (remaining.size > 0) {
+        throw new Error(
+          `voyage batch ${batchInfo.id} missing ${remaining.size} embedding responses`,
+        );
+      }
+    },
+  });
+}

package/extensions/voyage/embedding-provider.ts

@@ -0,0 +1,90 @@
+import {
+  fetchRemoteEmbeddingVectors,
+  normalizeEmbeddingModelWithPrefixes,
+  resolveRemoteEmbeddingBearerClient,
+  type MemoryEmbeddingProvider,
+  type MemoryEmbeddingProviderCreateOptions,
+} from "openclaw/plugin-sdk/memory-core-host-engine-embeddings";
+import type { SsrFPolicy } from "openclaw/plugin-sdk/ssrf-runtime";
+
+export type VoyageEmbeddingClient = {
+  baseUrl: string;
+  headers: Record<string, string>;
+  ssrfPolicy?: SsrFPolicy;
+  model: string;
+};
+
+export const DEFAULT_VOYAGE_EMBEDDING_MODEL = "voyage-4-large";
+const DEFAULT_VOYAGE_BASE_URL = "https://api.voyageai.com/v1";
+const VOYAGE_MAX_INPUT_TOKENS: Record<string, number> = {
+  "voyage-3": 32000,
+  "voyage-3-lite": 16000,
+  "voyage-code-3": 32000,
+};
+
+function normalizeVoyageModel(model: string): string {
+  return normalizeEmbeddingModelWithPrefixes({
+    model,
+    defaultModel: DEFAULT_VOYAGE_EMBEDDING_MODEL,
+    prefixes: ["voyage/"],
+  });
+}
+
+export async function createVoyageEmbeddingProvider(
+  options: MemoryEmbeddingProviderCreateOptions,
+): Promise<{ provider: MemoryEmbeddingProvider; client: VoyageEmbeddingClient }> {
+  const client = await resolveVoyageEmbeddingClient(options);
+  const url = `${client.baseUrl.replace(/\/$/, "")}/embeddings`;
+
+  const embed = async (
+    input: string[],
+    input_type?: "query" | "document",
+    signal?: AbortSignal,
+  ): Promise<number[][]> => {
+    if (input.length === 0) {
+      return [];
+    }
+    const body: { model: string; input: string[]; input_type?: "query" | "document" } = {
+      model: client.model,
+      input,
+    };
+    if (input_type) {
+      body.input_type = input_type;
+    }
+
+    return await fetchRemoteEmbeddingVectors({
+      url,
+      headers: client.headers,
+      ssrfPolicy: client.ssrfPolicy,
+      signal,
+      body,
+      errorPrefix: "voyage embeddings failed",
+    });
+  };
+
+  return {
+    provider: {
+      id: "voyage",
+      model: client.model,
+      maxInputTokens: VOYAGE_MAX_INPUT_TOKENS[client.model],
+      embedQuery: async (text, options) => {
+        const [vec] = await embed([text], "query", options?.signal);
+        return vec ?? [];
+      },
+      embedBatch: async (texts, options) => embed(texts, "document", options?.signal),
+    },
+    client,
+  };
+}
+
+async function resolveVoyageEmbeddingClient(
+  options: MemoryEmbeddingProviderCreateOptions,
+): Promise<VoyageEmbeddingClient> {
+  const { baseUrl, headers, ssrfPolicy } = await resolveRemoteEmbeddingBearerClient({
+    provider: "voyage",
+    options,
+    defaultBaseUrl: DEFAULT_VOYAGE_BASE_URL,
+  });
+  const model = normalizeVoyageModel(options.model);
+  return { baseUrl, headers, ssrfPolicy, model };
+}

package/extensions/voyage/index.ts

@@ -0,0 +1,11 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { voyageMemoryEmbeddingProviderAdapter } from "./memory-embedding-adapter.js";
+
+export default definePluginEntry({
+  id: "voyage",
+  name: "Voyage Embeddings",
+  description: "Bundled Voyage memory embedding provider plugin",
+  register(api) {
+    api.registerMemoryEmbeddingProvider(voyageMemoryEmbeddingProviderAdapter);
+  },
+});