Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

extensions/azure-speech/azure-speech.live.test.ts

@@ -0,0 +1,93 @@
+// Azure Speech tests cover azure speech plugin behavior.
+import {
+  registerProviderPlugin,
+  requireRegisteredProvider,
+} from "openclaw/plugin-sdk/plugin-test-runtime";
+import { isLiveTestEnabled } from "openclaw/plugin-sdk/test-env";
+import { describe, expect, it } from "vitest";
+import plugin from "./index.js";
+
+const AZURE_SPEECH_KEY =
+  process.env.AZURE_SPEECH_KEY?.trim() ??
+  process.env.AZURE_SPEECH_API_KEY?.trim() ??
+  process.env.SPEECH_KEY?.trim() ??
+  "";
+const AZURE_SPEECH_REGION =
+  process.env.AZURE_SPEECH_REGION?.trim() ?? process.env.SPEECH_REGION?.trim() ?? "";
+const LIVE = isLiveTestEnabled() && AZURE_SPEECH_KEY.length > 0 && AZURE_SPEECH_REGION.length > 0;
+const describeLive = LIVE ? describe : describe.skip;
+
+const registerAzureSpeechPlugin = () =>
+  registerProviderPlugin({
+    plugin,
+    id: "azure-speech",
+    name: "Azure Speech",
+  });
+
+describeLive("azure speech plugin live", () => {
+  it("lists voices through the registered speech provider", async () => {
+    const { speechProviders } = await registerAzureSpeechPlugin();
+    const provider = requireRegisteredProvider(speechProviders, "azure-speech");
+
+    const voices = await provider.listVoices?.({
+      providerConfig: {
+        apiKey: AZURE_SPEECH_KEY,
+        region: AZURE_SPEECH_REGION,
+      },
+    });
+
+    expect(voices?.length).toBeGreaterThan(100);
+    expect(voices?.some((voice) => voice.id === "en-US-JennyNeural")).toBe(true);
+  }, 120_000);
+
+  it("synthesizes MP3, native Ogg/Opus voice notes, and telephony audio", async () => {
+    const { speechProviders } = await registerAzureSpeechPlugin();
+    const provider = requireRegisteredProvider(speechProviders, "azure-speech");
+    const providerConfig = {
+      apiKey: AZURE_SPEECH_KEY,
+      region: AZURE_SPEECH_REGION,
+      voice: "en-US-JennyNeural",
+      lang: "en-US",
+    };
+
+    const audioFile = await provider.synthesize({
+      text: "OpenClaw Azure Speech text to speech integration test OK.",
+      cfg: { plugins: { enabled: true } } as never,
+      providerConfig,
+      target: "audio-file",
+      timeoutMs: 90_000,
+    });
+
+    expect(audioFile.outputFormat).toBe("audio-24khz-48kbitrate-mono-mp3");
+    expect(audioFile.fileExtension).toBe(".mp3");
+    expect(audioFile.voiceCompatible).toBe(false);
+    expect(audioFile.audioBuffer.byteLength).toBeGreaterThan(512);
+
+    const voiceNote = await provider.synthesize({
+      text: "OpenClaw Azure Speech voice note integration test OK.",
+      cfg: { plugins: { enabled: true } } as never,
+      providerConfig,
+      target: "voice-note",
+      timeoutMs: 90_000,
+    });
+
+    expect(voiceNote.outputFormat).toBe("ogg-24khz-16bit-mono-opus");
+    expect(voiceNote.fileExtension).toBe(".ogg");
+    expect(voiceNote.voiceCompatible).toBe(true);
+    expect(voiceNote.audioBuffer.byteLength).toBeGreaterThan(128);
+    expect(voiceNote.audioBuffer.subarray(0, 4).toString("ascii")).toBe("OggS");
+
+    const telephony = await provider.synthesizeTelephony?.({
+      text: "OpenClaw Azure Speech telephony check OK.",
+      cfg: { plugins: { enabled: true } } as never,
+      providerConfig,
+      timeoutMs: 90_000,
+    });
+    if (!telephony) {
+      throw new Error("Azure Speech telephony synthesis did not return audio");
+    }
+    expect(telephony.outputFormat).toBe("raw-8khz-8bit-mono-mulaw");
+    expect(telephony.sampleRate).toBe(8_000);
+    expect(telephony.audioBuffer.byteLength).toBeGreaterThan(512);
+  }, 180_000);
+});

extensions/azure-speech/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Azure Speech plugin entry. It registers the Azure text-to-speech provider for
+ * message voice output and voice-note generation.
+ */
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { buildAzureSpeechProvider } from "./speech-provider.js";
+
+/** Plugin entry for Azure Speech TTS. */
+export default definePluginEntry({
+  id: "azure-speech",
+  name: "Azure Speech",
+  description: "Bundled Azure Speech provider",
+  register(api) {
+    api.registerSpeechProvider(buildAzureSpeechProvider());
+  },
+});

extensions/azure-speech/openclaw.plugin.json

@@ -0,0 +1,62 @@
+{
+  "id": "azure-speech",
+  "activation": {
+    "onStartup": false
+  },
+  "enabledByDefault": true,
+  "name": "Azure Speech",
+  "description": "Azure AI Speech text-to-speech (MP3, native Ogg/Opus voice notes, PCM telephony).",
+  "setup": {
+    "providers": [
+      {
+        "id": "azure-speech",
+        "envVars": ["AZURE_SPEECH_KEY", "AZURE_SPEECH_API_KEY", "SPEECH_KEY", "AZURE_SPEECH_REGION", "SPEECH_REGION"]
+      },
+      {
+        "id": "azure",
+        "envVars": ["AZURE_SPEECH_KEY", "AZURE_SPEECH_API_KEY", "SPEECH_KEY", "AZURE_SPEECH_REGION", "SPEECH_REGION"]
+      }
+    ]
+  },
+  "contracts": {
+    "speechProviders": ["azure-speech", "azure"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "description": "Azure Speech resource key. Falls back to AZURE_SPEECH_KEY, AZURE_SPEECH_API_KEY, or SPEECH_KEY."
+      },
+      "region": {
+        "type": "string",
+        "description": "Azure Speech resource region, for example eastus. Falls back to AZURE_SPEECH_REGION or SPEECH_REGION."
+      },
+      "endpoint": {
+        "type": "string",
+        "description": "Optional Azure Speech endpoint/base URL override."
+      },
+      "baseUrl": {
+        "type": "string",
+        "description": "Optional Azure Speech base URL override."
+      },
+      "voice": {
+        "type": "string",
+        "description": "Azure Speech voice ShortName (default en-US-JennyNeural)."
+      },
+      "lang": {
+        "type": "string",
+        "description": "SSML language code (default en-US)."
+      },
+      "outputFormat": {
+        "type": "string",
+        "description": "Azure Speech X-Microsoft-OutputFormat for audio-file output."
+      },
+      "voiceNoteOutputFormat": {
+        "type": "string",
+        "description": "Azure Speech X-Microsoft-OutputFormat for voice-note output."
+      }
+    }
+  }
+}

extensions/azure-speech/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@openclaw/azure-speech",
+  "version": "2026.6.11",
+  "private": true,
+  "description": "OpenClaw Azure Speech plugin",
+  "type": "module",
+  "devDependencies": {
+    "@openclaw/plugin-sdk": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

extensions/azure-speech/speech-provider.test.ts

@@ -0,0 +1,267 @@
+// Azure Speech tests cover speech provider plugin behavior.
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { azureSpeechTTSMock, listAzureSpeechVoicesMock } = vi.hoisted(() => ({
+  azureSpeechTTSMock: vi.fn(async () => Buffer.from("audio-bytes")),
+  listAzureSpeechVoicesMock: vi.fn(async () => [{ id: "en-US-JennyNeural", name: "Jenny" }]),
+}));
+
+vi.mock("./tts.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./tts.js")>();
+  return {
+    ...actual,
+    azureSpeechTTS: azureSpeechTTSMock,
+    listAzureSpeechVoices: listAzureSpeechVoicesMock,
+  };
+});
+
+import { buildAzureSpeechProvider } from "./speech-provider.js";
+
+describe("buildAzureSpeechProvider", () => {
+  const envKeys = [
+    "AZURE_SPEECH_KEY",
+    "AZURE_SPEECH_API_KEY",
+    "AZURE_SPEECH_REGION",
+    "AZURE_SPEECH_ENDPOINT",
+    "SPEECH_KEY",
+    "SPEECH_REGION",
+  ] as const;
+
+  beforeEach(() => {
+    for (const key of envKeys) {
+      vi.stubEnv(key, undefined);
+    }
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    azureSpeechTTSMock.mockClear();
+    listAzureSpeechVoicesMock.mockClear();
+    vi.restoreAllMocks();
+  });
+
+  afterAll(() => {
+    vi.doUnmock("./tts.js");
+    vi.resetModules();
+  });
+
+  it("reports configured only when key plus region or endpoint is available", () => {
+    const provider = buildAzureSpeechProvider();
+
+    expect(provider.isConfigured({ providerConfig: {}, timeoutMs: 30_000 })).toBe(false);
+    expect(provider.isConfigured({ providerConfig: { apiKey: "key" }, timeoutMs: 30_000 })).toBe(
+      false,
+    );
+    expect(
+      provider.isConfigured({
+        providerConfig: { apiKey: "key", region: "eastus" },
+        timeoutMs: 30_000,
+      }),
+    ).toBe(true);
+
+    vi.stubEnv("AZURE_SPEECH_KEY", "env-key");
+    vi.stubEnv("AZURE_SPEECH_REGION", "eastus");
+    expect(provider.isConfigured({ providerConfig: {}, timeoutMs: 30_000 })).toBe(true);
+  });
+
+  it("normalizes provider-owned config under canonical and alias keys", () => {
+    const provider = buildAzureSpeechProvider();
+    const canonical = provider.resolveConfig?.({
+      cfg: {} as never,
+      timeoutMs: 30_000,
+      rawConfig: {
+        providers: {
+          "azure-speech": {
+            apiKey: "key",
+            region: "eastus",
+            voice: "en-US-AriaNeural",
+            lang: "en-US",
+          },
+        },
+      },
+    });
+    const alias = provider.resolveConfig?.({
+      cfg: {} as never,
+      timeoutMs: 30_000,
+      rawConfig: {
+        providers: {
+          azure: {
+            apiKey: "alias-key",
+            endpoint: "https://westus.tts.speech.microsoft.com/cognitiveservices/v1",
+          },
+        },
+      },
+    });
+
+    expect(canonical).toEqual({
+      apiKey: "key",
+      region: "eastus",
+      endpoint: undefined,
+      baseUrl: "https://eastus.tts.speech.microsoft.com",
+      voice: "en-US-AriaNeural",
+      lang: "en-US",
+      outputFormat: "audio-24khz-48kbitrate-mono-mp3",
+      voiceNoteOutputFormat: "ogg-24khz-16bit-mono-opus",
+      timeoutMs: undefined,
+    });
+    expect(alias).toEqual({
+      apiKey: "alias-key",
+      region: undefined,
+      endpoint: "https://westus.tts.speech.microsoft.com/cognitiveservices/v1",
+      baseUrl: "https://westus.tts.speech.microsoft.com",
+      voice: "en-US-JennyNeural",
+      lang: "en-US",
+      outputFormat: "audio-24khz-48kbitrate-mono-mp3",
+      voiceNoteOutputFormat: "ogg-24khz-16bit-mono-opus",
+      timeoutMs: undefined,
+    });
+  });
+
+  it("parses provider-specific TTS directives", () => {
+    const provider = buildAzureSpeechProvider();
+    const policy = {
+      enabled: true,
+      allowText: true,
+      allowProvider: true,
+      allowVoice: true,
+      allowModelId: true,
+      allowVoiceSettings: true,
+      allowNormalization: true,
+      allowSeed: true,
+    };
+
+    expect(provider.parseDirectiveToken?.({ key: "azure_voice", value: "v", policy })).toEqual({
+      handled: true,
+      overrides: { voice: "v" },
+    });
+    expect(provider.parseDirectiveToken?.({ key: "azure_lang", value: "en-US", policy })).toEqual({
+      handled: true,
+      overrides: { lang: "en-US" },
+    });
+    expect(
+      provider.parseDirectiveToken?.({ key: "azure_output_format", value: "ogg", policy }),
+    ).toEqual({
+      handled: true,
+      overrides: { outputFormat: "ogg" },
+    });
+  });
+
+  it("uses native Ogg/Opus for voice-note output", async () => {
+    const provider = buildAzureSpeechProvider();
+    const result = await provider.synthesize({
+      text: "hello",
+      cfg: {} as never,
+      providerConfig: {
+        apiKey: "key",
+        region: "eastus",
+        voice: "en-US-JennyNeural",
+      },
+      providerOverrides: {
+        voice: "en-US-AriaNeural",
+        lang: "en-US",
+      },
+      target: "voice-note",
+      timeoutMs: 30_000,
+    });
+
+    expect(azureSpeechTTSMock).toHaveBeenCalledWith({
+      text: "hello",
+      apiKey: "key",
+      baseUrl: "https://eastus.tts.speech.microsoft.com",
+      endpoint: undefined,
+      region: "eastus",
+      voice: "en-US-AriaNeural",
+      lang: "en-US",
+      outputFormat: "ogg-24khz-16bit-mono-opus",
+      timeoutMs: 30_000,
+      maxBytes: 16 * 1024 * 1024,
+    });
+    expect(result).toEqual({
+      audioBuffer: Buffer.from("audio-bytes"),
+      outputFormat: "ogg-24khz-16bit-mono-opus",
+      fileExtension: ".ogg",
+      voiceCompatible: true,
+    });
+  });
+
+  it("honors voice and language overrides for telephony output", async () => {
+    const provider = buildAzureSpeechProvider();
+    const result = await provider.synthesizeTelephony?.({
+      text: "hello",
+      cfg: {} as never,
+      providerConfig: {
+        apiKey: "key",
+        region: "eastus",
+        voice: "en-US-JennyNeural",
+        lang: "en-US",
+      },
+      providerOverrides: {
+        voice: "en-US-AriaNeural",
+        lang: "es-US",
+      },
+      timeoutMs: 30_000,
+    });
+
+    expect(azureSpeechTTSMock).toHaveBeenCalledWith({
+      text: "hello",
+      apiKey: "key",
+      baseUrl: "https://eastus.tts.speech.microsoft.com",
+      endpoint: undefined,
+      region: "eastus",
+      voice: "en-US-AriaNeural",
+      lang: "es-US",
+      outputFormat: "raw-8khz-8bit-mono-mulaw",
+      timeoutMs: 30_000,
+      maxBytes: 16 * 1024 * 1024,
+    });
+    expect(result).toEqual({
+      audioBuffer: Buffer.from("audio-bytes"),
+      outputFormat: "raw-8khz-8bit-mono-mulaw",
+      sampleRate: 8_000,
+    });
+  });
+
+  it("applies the configured media byte cap to synthesis requests", async () => {
+    const provider = buildAzureSpeechProvider();
+
+    await provider.synthesize({
+      text: "hello",
+      cfg: {
+        agents: {
+          defaults: {
+            mediaMaxMb: 2,
+          },
+        },
+      } as never,
+      providerConfig: {
+        apiKey: "key",
+        region: "eastus",
+        voice: "en-US-JennyNeural",
+      },
+      target: "audio-file",
+      timeoutMs: 30_000,
+    });
+
+    expect(azureSpeechTTSMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        maxBytes: 2 * 1024 * 1024,
+      }),
+    );
+  });
+
+  it("lists voices through config or explicit request auth", async () => {
+    const provider = buildAzureSpeechProvider();
+    const voices = await provider.listVoices?.({
+      providerConfig: { apiKey: "key", region: "eastus" },
+    });
+
+    expect(voices).toEqual([{ id: "en-US-JennyNeural", name: "Jenny" }]);
+    expect(listAzureSpeechVoicesMock).toHaveBeenCalledWith({
+      apiKey: "key",
+      baseUrl: "https://eastus.tts.speech.microsoft.com",
+      endpoint: undefined,
+      region: "eastus",
+      timeoutMs: undefined,
+    });
+  });
+});

extensions/azure-speech/speech-provider.ts

@@ -0,0 +1,325 @@
+/**
+ * Azure Speech provider descriptor. It reads config/env defaults, parses speech
+ * directives, lists voices, and calls the Azure TTS runtime helper.
+ */
+import { normalizeResolvedSecretInputString } from "openclaw/plugin-sdk/secret-input";
+import type {
+  SpeechDirectiveTokenParseContext,
+  SpeechProviderConfig,
+  SpeechProviderOverrides,
+  SpeechProviderPlugin,
+} from "openclaw/plugin-sdk/speech-core";
+import { asFiniteNumber, asObject, trimToUndefined } from "openclaw/plugin-sdk/speech-core";
+import {
+  azureSpeechTTS,
+  DEFAULT_AZURE_SPEECH_AUDIO_FORMAT,
+  DEFAULT_AZURE_SPEECH_LANG,
+  DEFAULT_AZURE_SPEECH_TELEPHONY_FORMAT,
+  DEFAULT_AZURE_SPEECH_VOICE,
+  DEFAULT_AZURE_SPEECH_VOICE_NOTE_FORMAT,
+  inferAzureSpeechFileExtension,
+  isAzureSpeechVoiceCompatible,
+  listAzureSpeechVoices,
+  normalizeAzureSpeechBaseUrl,
+} from "./tts.js";
+
+const DEFAULT_GENERATED_AUDIO_MAX_BYTES = 16 * 1024 * 1024;
+
+type AzureSpeechProviderConfig = {
+  apiKey?: string;
+  region?: string;
+  endpoint?: string;
+  baseUrl?: string;
+  voice: string;
+  lang: string;
+  outputFormat: string;
+  voiceNoteOutputFormat: string;
+  timeoutMs?: number;
+};
+
+type AzureSpeechProviderOverrides = {
+  voice?: string;
+  lang?: string;
+  outputFormat?: string;
+};
+
+function readAzureSpeechEnvApiKey(): string | undefined {
+  return (
+    trimToUndefined(process.env.AZURE_SPEECH_KEY) ??
+    trimToUndefined(process.env.AZURE_SPEECH_API_KEY) ??
+    trimToUndefined(process.env.SPEECH_KEY)
+  );
+}
+
+function readAzureSpeechEnvRegion(): string | undefined {
+  return (
+    trimToUndefined(process.env.AZURE_SPEECH_REGION) ?? trimToUndefined(process.env.SPEECH_REGION)
+  );
+}
+
+function readAzureSpeechEnvEndpoint(): string | undefined {
+  return trimToUndefined(process.env.AZURE_SPEECH_ENDPOINT);
+}
+
+function resolveAzureSpeechConfigRecord(
+  rawConfig: Record<string, unknown>,
+): Record<string, unknown> | undefined {
+  const providers = asObject(rawConfig.providers);
+  return (
+    asObject(providers?.["azure-speech"]) ??
+    asObject(providers?.azure) ??
+    asObject(rawConfig["azure-speech"]) ??
+    asObject(rawConfig.azure)
+  );
+}
+
+function normalizeAzureSpeechProviderConfig(
+  rawConfig: Record<string, unknown>,
+): AzureSpeechProviderConfig {
+  const raw = resolveAzureSpeechConfigRecord(rawConfig);
+  const region = trimToUndefined(raw?.region) ?? readAzureSpeechEnvRegion();
+  const endpoint = trimToUndefined(raw?.endpoint) ?? readAzureSpeechEnvEndpoint();
+  const baseUrl = normalizeAzureSpeechBaseUrl({
+    baseUrl: trimToUndefined(raw?.baseUrl),
+    endpoint,
+    region,
+  });
+  return {
+    apiKey: normalizeResolvedSecretInputString({
+      value: raw?.apiKey,
+      path: "messages.tts.providers.azure-speech.apiKey",
+    }),
+    region,
+    endpoint,
+    baseUrl,
+    voice: trimToUndefined(raw?.voice ?? raw?.voiceId) ?? DEFAULT_AZURE_SPEECH_VOICE,
+    lang: trimToUndefined(raw?.lang ?? raw?.languageCode) ?? DEFAULT_AZURE_SPEECH_LANG,
+    outputFormat: trimToUndefined(raw?.outputFormat) ?? DEFAULT_AZURE_SPEECH_AUDIO_FORMAT,
+    voiceNoteOutputFormat:
+      trimToUndefined(raw?.voiceNoteOutputFormat) ?? DEFAULT_AZURE_SPEECH_VOICE_NOTE_FORMAT,
+    timeoutMs: asFiniteNumber(raw?.timeoutMs),
+  };
+}
+
+function readAzureSpeechProviderConfig(config: SpeechProviderConfig): AzureSpeechProviderConfig {
+  const defaults = normalizeAzureSpeechProviderConfig({});
+  const region = trimToUndefined(config.region) ?? defaults.region;
+  const endpoint = trimToUndefined(config.endpoint) ?? defaults.endpoint;
+  const baseUrl = normalizeAzureSpeechBaseUrl({
+    baseUrl: trimToUndefined(config.baseUrl) ?? defaults.baseUrl,
+    endpoint,
+    region,
+  });
+  return {
+    apiKey: trimToUndefined(config.apiKey) ?? defaults.apiKey,
+    region,
+    endpoint,
+    baseUrl,
+    voice: trimToUndefined(config.voice ?? config.voiceId) ?? defaults.voice,
+    lang: trimToUndefined(config.lang ?? config.languageCode) ?? defaults.lang,
+    outputFormat: trimToUndefined(config.outputFormat) ?? defaults.outputFormat,
+    voiceNoteOutputFormat:
+      trimToUndefined(config.voiceNoteOutputFormat) ?? defaults.voiceNoteOutputFormat,
+    timeoutMs: asFiniteNumber(config.timeoutMs) ?? defaults.timeoutMs,
+  };
+}
+
+function readAzureSpeechOverrides(
+  overrides: SpeechProviderOverrides | undefined,
+): AzureSpeechProviderOverrides {
+  if (!overrides) {
+    return {};
+  }
+  return {
+    voice: trimToUndefined(overrides.voice ?? overrides.voiceId),
+    lang: trimToUndefined(overrides.lang ?? overrides.languageCode),
+    outputFormat: trimToUndefined(overrides.outputFormat),
+  };
+}
+
+function parseDirectiveToken(ctx: SpeechDirectiveTokenParseContext): {
+  handled: boolean;
+  overrides?: SpeechProviderOverrides;
+} {
+  switch (ctx.key) {
+    case "voice":
+    case "voiceid":
+    case "voice_id":
+    case "azure_voice":
+    case "azurevoice":
+    case "azure_speech_voice":
+      if (!ctx.policy.allowVoice) {
+        return { handled: true };
+      }
+      return { handled: true, overrides: { ...ctx.currentOverrides, voice: ctx.value } };
+    case "lang":
+    case "language":
+    case "language_code":
+    case "languagecode":
+    case "azure_lang":
+    case "azure_language":
+      if (!ctx.policy.allowVoiceSettings) {
+        return { handled: true };
+      }
+      return { handled: true, overrides: { ...ctx.currentOverrides, lang: ctx.value } };
+    case "output_format":
+    case "outputformat":
+    case "azure_format":
+    case "azure_output_format":
+      if (!ctx.policy.allowVoiceSettings) {
+        return { handled: true };
+      }
+      return { handled: true, overrides: { ...ctx.currentOverrides, outputFormat: ctx.value } };
+    default:
+      return { handled: false };
+  }
+}
+
+function resolveApiKey(config: AzureSpeechProviderConfig): string | undefined {
+  return config.apiKey ?? readAzureSpeechEnvApiKey();
+}
+
+function resolveTimeoutMs(config: AzureSpeechProviderConfig, timeoutMs: number): number {
+  return config.timeoutMs ?? timeoutMs;
+}
+
+function resolveGeneratedAudioMaxBytes(req: {
+  cfg: { agents?: { defaults?: { mediaMaxMb?: number } } };
+}): number {
+  const configured = req.cfg.agents?.defaults?.mediaMaxMb;
+  if (typeof configured === "number" && Number.isFinite(configured) && configured > 0) {
+    return Math.floor(configured * 1024 * 1024);
+  }
+  return DEFAULT_GENERATED_AUDIO_MAX_BYTES;
+}
+
+/** Build the Azure Speech provider descriptor for the speech-core runtime. */
+export function buildAzureSpeechProvider(): SpeechProviderPlugin {
+  return {
+    id: "azure-speech",
+    label: "Azure Speech",
+    aliases: ["azure"],
+    autoSelectOrder: 30,
+    resolveConfig: ({ rawConfig }) => normalizeAzureSpeechProviderConfig(rawConfig),
+    parseDirectiveToken,
+    resolveTalkConfig: ({ baseTtsConfig, talkProviderConfig }) => {
+      const base = normalizeAzureSpeechProviderConfig(baseTtsConfig);
+      const apiKey =
+        talkProviderConfig.apiKey === undefined
+          ? undefined
+          : normalizeResolvedSecretInputString({
+              value: talkProviderConfig.apiKey,
+              path: "talk.providers.azure-speech.apiKey",
+            });
+      const region = trimToUndefined(talkProviderConfig.region);
+      const endpoint = trimToUndefined(talkProviderConfig.endpoint ?? talkProviderConfig.baseUrl);
+      const baseUrl = normalizeAzureSpeechBaseUrl({
+        baseUrl: trimToUndefined(talkProviderConfig.baseUrl),
+        endpoint,
+        region: region ?? base.region,
+      });
+      return {
+        ...base,
+        ...(apiKey === undefined ? {} : { apiKey }),
+        ...(region === undefined ? {} : { region }),
+        ...(endpoint === undefined ? {} : { endpoint }),
+        ...(baseUrl === undefined ? {} : { baseUrl }),
+        ...(trimToUndefined(talkProviderConfig.voiceId) == null
+          ? {}
+          : { voice: trimToUndefined(talkProviderConfig.voiceId) }),
+        ...(trimToUndefined(talkProviderConfig.languageCode) == null
+          ? {}
+          : { lang: trimToUndefined(talkProviderConfig.languageCode) }),
+        ...(trimToUndefined(talkProviderConfig.outputFormat) == null
+          ? {}
+          : { outputFormat: trimToUndefined(talkProviderConfig.outputFormat) }),
+      };
+    },
+    resolveTalkOverrides: ({ params }) => ({
+      ...(trimToUndefined(params.voiceId) == null
+        ? {}
+        : { voice: trimToUndefined(params.voiceId) }),
+      ...(trimToUndefined(params.languageCode) == null
+        ? {}
+        : { lang: trimToUndefined(params.languageCode) }),
+      ...(trimToUndefined(params.outputFormat) == null
+        ? {}
+        : { outputFormat: trimToUndefined(params.outputFormat) }),
+    }),
+    listVoices: async (req) => {
+      const config = req.providerConfig
+        ? readAzureSpeechProviderConfig(req.providerConfig)
+        : undefined;
+      const apiKey = req.apiKey ?? (config ? resolveApiKey(config) : readAzureSpeechEnvApiKey());
+      if (!apiKey) {
+        throw new Error("Azure Speech API key missing");
+      }
+      return listAzureSpeechVoices({
+        apiKey,
+        baseUrl: req.baseUrl ?? config?.baseUrl,
+        endpoint: config?.endpoint,
+        region: config?.region ?? readAzureSpeechEnvRegion(),
+        timeoutMs: config?.timeoutMs,
+      });
+    },
+    isConfigured: ({ providerConfig }) => {
+      const config = readAzureSpeechProviderConfig(providerConfig);
+      return Boolean(resolveApiKey(config) && (config.baseUrl || config.region || config.endpoint));
+    },
+    synthesize: async (req) => {
+      const config = readAzureSpeechProviderConfig(req.providerConfig);
+      const overrides = readAzureSpeechOverrides(req.providerOverrides);
+      const apiKey = resolveApiKey(config);
+      if (!apiKey) {
+        throw new Error("Azure Speech API key missing");
+      }
+      const outputFormat =
+        overrides.outputFormat ??
+        (req.target === "voice-note" ? config.voiceNoteOutputFormat : config.outputFormat);
+      const audioBuffer = await azureSpeechTTS({
+        text: req.text,
+        apiKey,
+        baseUrl: config.baseUrl,
+        endpoint: config.endpoint,
+        region: config.region,
+        voice: overrides.voice ?? config.voice,
+        lang: overrides.lang ?? config.lang,
+        outputFormat,
+        timeoutMs: resolveTimeoutMs(config, req.timeoutMs),
+        maxBytes: resolveGeneratedAudioMaxBytes(req),
+      });
+      return {
+        audioBuffer,
+        outputFormat,
+        fileExtension: inferAzureSpeechFileExtension(outputFormat),
+        voiceCompatible: isAzureSpeechVoiceCompatible(outputFormat),
+      };
+    },
+    synthesizeTelephony: async (req) => {
+      const config = readAzureSpeechProviderConfig(req.providerConfig);
+      const overrides = readAzureSpeechOverrides(req.providerOverrides);
+      const apiKey = resolveApiKey(config);
+      if (!apiKey) {
+        throw new Error("Azure Speech API key missing");
+      }
+      const sampleRate = 8_000;
+      const audioBuffer = await azureSpeechTTS({
+        text: req.text,
+        apiKey,
+        baseUrl: config.baseUrl,
+        endpoint: config.endpoint,
+        region: config.region,
+        voice: overrides.voice ?? config.voice,
+        lang: overrides.lang ?? config.lang,
+        outputFormat: DEFAULT_AZURE_SPEECH_TELEPHONY_FORMAT,
+        timeoutMs: resolveTimeoutMs(config, req.timeoutMs),
+        maxBytes: resolveGeneratedAudioMaxBytes(req),
+      });
+      return {
+        audioBuffer,
+        outputFormat: DEFAULT_AZURE_SPEECH_TELEPHONY_FORMAT,
+        sampleRate,
+      };
+    },
+  };
+}

extensions/azure-speech/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.package-boundary.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": [
+    "./**/*.test.ts",
+    "./dist/**",
+    "./node_modules/**",
+    "./src/test-support/**",
+    "./src/**/*test-helpers.ts",
+    "./src/**/*test-harness.ts",
+    "./src/**/*test-support.ts"
+  ]
+}

extensions/azure-speech/tts.test.ts

@@ -0,0 +1,177 @@
+// Azure Speech tests cover tts plugin behavior.
+import { installPinnedHostnameTestHooks } from "openclaw/plugin-sdk/test-env";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  azureSpeechTTS,
+  buildAzureSpeechSsml,
+  inferAzureSpeechFileExtension,
+  isAzureSpeechVoiceCompatible,
+  listAzureSpeechVoices,
+  normalizeAzureSpeechBaseUrl,
+} from "./tts.js";
+
+describe("azure speech tts", () => {
+  installPinnedHostnameTestHooks();
+
+  function createStreamingAudioResponse(params: {
+    chunkCount: number;
+    chunkSize: number;
+    byte: number;
+  }): { response: Response; getReadCount: () => number } {
+    let reads = 0;
+    const stream = new ReadableStream<Uint8Array>({
+      pull(controller) {
+        if (reads >= params.chunkCount) {
+          controller.close();
+          return;
+        }
+        reads += 1;
+        controller.enqueue(new Uint8Array(params.chunkSize).fill(params.byte));
+      },
+    });
+    return {
+      response: new Response(stream, {
+        status: 200,
+        headers: { "Content-Type": "audio/mpeg" },
+      }),
+      getReadCount: () => reads,
+    };
+  }
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("escapes SSML text and attributes", () => {
+    expect(
+      buildAzureSpeechSsml({
+        text: `Tom & "Jerry" <tag>`,
+        voice: `en-US-JennyNeural" xml:lang="evil`,
+        lang: `en-US" bad="1`,
+      }),
+    ).toBe(
+      `<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" ` +
+        `xml:lang="en-US&quot; bad=&quot;1">` +
+        `<voice name="en-US-JennyNeural&quot; xml:lang=&quot;evil">` +
+        `Tom &amp; "Jerry" &lt;tag&gt;</voice></speak>`,
+    );
+  });
+
+  it("normalizes region and endpoint routing", () => {
+    expect(normalizeAzureSpeechBaseUrl({ region: "eastus" })).toBe(
+      "https://eastus.tts.speech.microsoft.com",
+    );
+    expect(
+      normalizeAzureSpeechBaseUrl({
+        endpoint: "https://eastus.tts.speech.microsoft.com/cognitiveservices/v1/",
+      }),
+    ).toBe("https://eastus.tts.speech.microsoft.com");
+    expect(normalizeAzureSpeechBaseUrl({ baseUrl: "https://custom.example.com/" })).toBe(
+      "https://custom.example.com",
+    );
+  });
+
+  it("maps Azure output formats to attachment metadata", () => {
+    expect(inferAzureSpeechFileExtension("audio-24khz-48kbitrate-mono-mp3")).toBe(".mp3");
+    expect(inferAzureSpeechFileExtension("ogg-24khz-16bit-mono-opus")).toBe(".ogg");
+    expect(inferAzureSpeechFileExtension("riff-24khz-16bit-mono-pcm")).toBe(".wav");
+    expect(inferAzureSpeechFileExtension("raw-8khz-8bit-mono-mulaw")).toBe(".pcm");
+    expect(isAzureSpeechVoiceCompatible("ogg-24khz-16bit-mono-opus")).toBe(true);
+    expect(isAzureSpeechVoiceCompatible("webm-24khz-16bit-mono-opus")).toBe(false);
+  });
+
+  it("posts SSML to the region endpoint with Azure Speech headers", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(new Response(Buffer.from("mp3"), { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const result = await azureSpeechTTS({
+      text: "hello",
+      apiKey: "speech-key",
+      region: "eastus",
+      voice: "en-US-JennyNeural",
+      lang: "en-US",
+      outputFormat: "audio-24khz-48kbitrate-mono-mp3",
+      timeoutMs: 1234,
+    });
+
+    expect(result).toEqual(Buffer.from("mp3"));
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://eastus.tts.speech.microsoft.com/cognitiveservices/v1");
+    expect(init.method).toBe("POST");
+    const headers = new Headers(init.headers);
+    expect(headers.get("Ocp-Apim-Subscription-Key")).toBe("speech-key");
+    expect(headers.get("Content-Type")).toBe("application/ssml+xml");
+    expect(headers.get("X-Microsoft-OutputFormat")).toBe("audio-24khz-48kbitrate-mono-mp3");
+    expect(init.body).toContain(`<voice name="en-US-JennyNeural">hello</voice>`);
+    expect(init.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it("caps streamed audio responses instead of buffering oversized TTS output", async () => {
+    const streamed = createStreamingAudioResponse({
+      chunkCount: 20,
+      chunkSize: 1024,
+      byte: 121,
+    });
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(streamed.response));
+
+    await expect(
+      azureSpeechTTS({
+        text: "hello",
+        apiKey: "speech-key",
+        region: "eastus",
+        voice: "en-US-JennyNeural",
+        lang: "en-US",
+        outputFormat: "audio-24khz-48kbitrate-mono-mp3",
+        timeoutMs: 1234,
+        maxBytes: 2048,
+      }),
+    ).rejects.toThrow("Azure Speech TTS audio response exceeds 2048 bytes");
+
+    expect(streamed.getReadCount()).toBeLessThan(20);
+  });
+
+  it("lists voices with timeout and filters deprecated entries", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify([
+          {
+            ShortName: "en-US-JennyNeural",
+            DisplayName: "Jenny",
+            Locale: "en-US",
+            Gender: "Female",
+            Status: "GA",
+            VoiceTag: { VoicePersonalities: ["Warm"] },
+          },
+          { ShortName: "en-US-OldNeural", DisplayName: "Old", Status: "Deprecated" },
+          { ShortName: "en-US-RetiredNeural", DisplayName: "Retired", IsDeprecated: true },
+        ]),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      ),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    const voices = await listAzureSpeechVoices({
+      apiKey: "speech-key",
+      baseUrl: "https://custom.example.com",
+      timeoutMs: 4321,
+    });
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://custom.example.com/cognitiveservices/voices/list");
+    expect(new Headers(init.headers).get("Ocp-Apim-Subscription-Key")).toBe("speech-key");
+    expect(init.signal).toBeInstanceOf(AbortSignal);
+    expect(voices).toEqual([
+      {
+        id: "en-US-JennyNeural",
+        name: "Jenny",
+        description: "Warm",
+        locale: "en-US",
+        gender: "Female",
+        personalities: ["Warm"],
+      },
+    ]);
+  });
+});

extensions/azure-speech/tts.ts

@@ -0,0 +1,240 @@
+/**
+ * Azure Speech REST helpers. They normalize endpoints, build SSML, list voices,
+ * and synthesize speech with response-size and SSRF guards.
+ */
+import {
+  assertOkOrThrowProviderError,
+  readProviderJsonResponse,
+} from "openclaw/plugin-sdk/provider-http";
+import { readResponseWithLimit } from "openclaw/plugin-sdk/response-limit-runtime";
+import type { SpeechVoiceOption } from "openclaw/plugin-sdk/speech-core";
+import { trimToUndefined } from "openclaw/plugin-sdk/speech-core";
+import {
+  fetchWithSsrFGuard,
+  ssrfPolicyFromHttpBaseUrlAllowedHostname,
+} from "openclaw/plugin-sdk/ssrf-runtime";
+
+/** Default Azure Speech neural voice. */
+export const DEFAULT_AZURE_SPEECH_VOICE = "en-US-JennyNeural";
+/** Default Azure Speech language. */
+export const DEFAULT_AZURE_SPEECH_LANG = "en-US";
+/** Default full-audio output format. */
+export const DEFAULT_AZURE_SPEECH_AUDIO_FORMAT = "audio-24khz-48kbitrate-mono-mp3";
+/** Default voice-note output format. */
+export const DEFAULT_AZURE_SPEECH_VOICE_NOTE_FORMAT = "ogg-24khz-16bit-mono-opus";
+/** Default telephony output format. */
+export const DEFAULT_AZURE_SPEECH_TELEPHONY_FORMAT = "raw-8khz-8bit-mono-mulaw";
+const DEFAULT_AZURE_SPEECH_MAX_BYTES = 16 * 1024 * 1024;
+
+type AzureSpeechVoiceEntry = {
+  ShortName?: string;
+  DisplayName?: string;
+  LocalName?: string;
+  Locale?: string;
+  Gender?: string;
+  Status?: string;
+  IsDeprecated?: boolean | string;
+  VoiceTag?: {
+    VoicePersonalities?: string[];
+    TailoredScenarios?: string[];
+  };
+};
+
+/** Resolve and normalize the Azure Speech base URL from endpoint or region. */
+export function normalizeAzureSpeechBaseUrl(params: {
+  baseUrl?: string;
+  endpoint?: string;
+  region?: string;
+}): string | undefined {
+  const configured = trimToUndefined(params.baseUrl) ?? trimToUndefined(params.endpoint);
+  if (configured) {
+    return configured.replace(/\/+$/, "").replace(/\/cognitiveservices\/v1$/i, "");
+  }
+  const region = trimToUndefined(params.region);
+  return region ? `https://${region}.tts.speech.microsoft.com` : undefined;
+}
+
+function azureSpeechUrl(params: {
+  baseUrl?: string;
+  endpoint?: string;
+  region?: string;
+  path: "/cognitiveservices/v1" | "/cognitiveservices/voices/list";
+}): string {
+  const baseUrl = normalizeAzureSpeechBaseUrl(params);
+  if (!baseUrl) {
+    throw new Error("Azure Speech region or endpoint missing");
+  }
+  return `${baseUrl}${params.path}`;
+}
+
+function escapeXmlText(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function escapeXmlAttr(value: string): string {
+  return escapeXmlText(value).replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+
+/** Build escaped SSML for one Azure Speech synthesis request. */
+export function buildAzureSpeechSsml(params: {
+  text: string;
+  voice: string;
+  lang?: string;
+}): string {
+  const lang = trimToUndefined(params.lang) ?? DEFAULT_AZURE_SPEECH_LANG;
+  return (
+    `<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" ` +
+    `xml:lang="${escapeXmlAttr(lang)}">` +
+    `<voice name="${escapeXmlAttr(params.voice)}">${escapeXmlText(params.text)}</voice>` +
+    `</speak>`
+  );
+}
+
+/** Infer the generated audio file extension from Azure output format. */
+export function inferAzureSpeechFileExtension(outputFormat: string): string {
+  const normalized = outputFormat.toLowerCase();
+  if (normalized.includes("mp3")) {
+    return ".mp3";
+  }
+  if (normalized.startsWith("ogg-")) {
+    return ".ogg";
+  }
+  if (normalized.startsWith("webm-")) {
+    return ".webm";
+  }
+  if (normalized.startsWith("riff-")) {
+    return ".wav";
+  }
+  if (normalized.startsWith("raw-")) {
+    return ".pcm";
+  }
+  if (normalized.startsWith("amr-")) {
+    return ".amr";
+  }
+  return ".audio";
+}
+
+/** Return whether an Azure output format is voice-note compatible. */
+export function isAzureSpeechVoiceCompatible(outputFormat: string): boolean {
+  const normalized = outputFormat.toLowerCase();
+  return normalized.startsWith("ogg-") && normalized.includes("opus");
+}
+
+function formatVoiceDescription(entry: AzureSpeechVoiceEntry): string | undefined {
+  const parts = [
+    ...(entry.VoiceTag?.TailoredScenarios ?? []),
+    ...(entry.VoiceTag?.VoicePersonalities ?? []),
+  ].filter((value) => trimToUndefined(value) !== undefined);
+  return parts.length > 0 ? parts.join(", ") : undefined;
+}
+
+function isDeprecatedVoice(entry: AzureSpeechVoiceEntry): boolean {
+  if (entry.IsDeprecated === true) {
+    return true;
+  }
+  if (typeof entry.IsDeprecated === "string" && entry.IsDeprecated.toLowerCase() === "true") {
+    return true;
+  }
+  const status = trimToUndefined(entry.Status)?.toLowerCase();
+  return status === "deprecated" || status === "retired" || status === "disabled";
+}
+
+/** List non-deprecated voices from the Azure Speech voices API. */
+export async function listAzureSpeechVoices(params: {
+  apiKey: string;
+  baseUrl?: string;
+  endpoint?: string;
+  region?: string;
+  timeoutMs?: number;
+}): Promise<SpeechVoiceOption[]> {
+  const url = azureSpeechUrl({ ...params, path: "/cognitiveservices/voices/list" });
+  const { response, release } = await fetchWithSsrFGuard({
+    url,
+    init: {
+      method: "GET",
+      headers: {
+        "Ocp-Apim-Subscription-Key": params.apiKey,
+      },
+    },
+    timeoutMs: params.timeoutMs,
+    policy: ssrfPolicyFromHttpBaseUrlAllowedHostname(url),
+    auditContext: "azure-speech.voices",
+  });
+
+  try {
+    await assertOkOrThrowProviderError(response, "Azure Speech voices API error");
+    const voices = await readProviderJsonResponse<AzureSpeechVoiceEntry[]>(
+      response,
+      "azure-speech.voices",
+    );
+    return Array.isArray(voices)
+      ? voices
+          .filter((voice) => !isDeprecatedVoice(voice))
+          .map((voice) => ({
+            id: trimToUndefined(voice.ShortName) ?? "",
+            name: trimToUndefined(voice.DisplayName) ?? trimToUndefined(voice.LocalName),
+            description: formatVoiceDescription(voice),
+            locale: trimToUndefined(voice.Locale),
+            gender: trimToUndefined(voice.Gender),
+            personalities: voice.VoiceTag?.VoicePersonalities?.filter(
+              (value): value is string => trimToUndefined(value) !== undefined,
+            ),
+          }))
+          .filter((voice) => voice.id.length > 0)
+      : [];
+  } finally {
+    await release();
+  }
+}
+
+/** Synthesize text to audio bytes using Azure Speech TTS. */
+export async function azureSpeechTTS(params: {
+  text: string;
+  apiKey: string;
+  baseUrl?: string;
+  endpoint?: string;
+  region?: string;
+  voice?: string;
+  lang?: string;
+  outputFormat?: string;
+  timeoutMs?: number;
+  maxBytes?: number;
+}): Promise<Buffer> {
+  const voice = trimToUndefined(params.voice) ?? DEFAULT_AZURE_SPEECH_VOICE;
+  const outputFormat = trimToUndefined(params.outputFormat) ?? DEFAULT_AZURE_SPEECH_AUDIO_FORMAT;
+  const url = azureSpeechUrl({ ...params, path: "/cognitiveservices/v1" });
+  const { response, release } = await fetchWithSsrFGuard({
+    url,
+    init: {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/ssml+xml",
+        "Ocp-Apim-Subscription-Key": params.apiKey,
+        "X-Microsoft-OutputFormat": outputFormat,
+        "User-Agent": "OpenClaw",
+      },
+      body: buildAzureSpeechSsml({
+        text: params.text,
+        voice,
+        lang: params.lang,
+      }),
+    },
+    timeoutMs: params.timeoutMs,
+    policy: ssrfPolicyFromHttpBaseUrlAllowedHostname(url),
+    auditContext: "azure-speech.tts",
+  });
+
+  try {
+    await assertOkOrThrowProviderError(response, "Azure Speech TTS API error");
+    return await readResponseWithLimit(
+      response,
+      params.maxBytes ?? DEFAULT_AZURE_SPEECH_MAX_BYTES,
+      {
+        onOverflow: ({ maxBytes }) =>
+          new Error(`Azure Speech TTS audio response exceeds ${maxBytes} bytes`),
+      },
+    );
+  } finally {
+    await release();
+  }
+}