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

packages/speech-core/api.ts

@@ -0,0 +1,56 @@
+// Public speech-core plugin SDK facade. Re-export stable provider/config helpers
+// from the plugin-sdk alias so speech plugins do not import core internals.
+export {
+  asBoolean,
+  asFiniteNumber,
+  asObject,
+  assertOkOrThrowProviderError,
+  canonicalizeSpeechProviderId,
+  createProviderHttpError,
+  extractProviderErrorDetail,
+  extractProviderRequestId,
+  formatProviderErrorPayload,
+  formatProviderHttpErrorMessage,
+  getSpeechProvider,
+  listSpeechProviders,
+  normalizeApplyTextNormalization,
+  normalizeLanguageCode,
+  normalizeSeed,
+  normalizeSpeechProviderId,
+  normalizeTtsAutoMode,
+  parseTtsDirectives,
+  readResponseTextLimited,
+  requireInRange,
+  resolveEffectiveTtsConfig,
+  scheduleCleanup,
+  summarizeText,
+  trimToUndefined,
+  truncateErrorDetail,
+  TTS_AUTO_MODES,
+} from "openclaw/plugin-sdk/speech-core";
+export type {
+  ResolvedTtsConfig,
+  ResolvedTtsModelOverrides,
+  SpeechDirectiveTokenParseContext,
+  SpeechDirectiveTokenParseResult,
+  SpeechListVoicesRequest,
+  SpeechModelOverridePolicy,
+  SpeechProviderConfig,
+  SpeechProviderConfiguredContext,
+  SpeechProviderOverrides,
+  SpeechProviderPlugin,
+  SpeechProviderPreparedSynthesis,
+  SpeechProviderPrepareSynthesisContext,
+  SpeechProviderResolveConfigContext,
+  SpeechProviderResolveTalkConfigContext,
+  SpeechProviderResolveTalkOverridesContext,
+  SpeechSynthesisRequest,
+  SpeechSynthesisStreamRequest,
+  SpeechSynthesisStreamResult,
+  SpeechSynthesisTarget,
+  SpeechTelephonySynthesisRequest,
+  SpeechVoiceOption,
+  TtsConfigResolutionContext,
+  TtsDirectiveOverrides,
+  TtsDirectiveParseResult,
+} from "openclaw/plugin-sdk/speech-core";

packages/speech-core/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@openclaw/speech-core",
+  "version": "2026.5.31",
+  "private": true,
+  "description": "OpenClaw speech runtime package",
+  "type": "module",
+  "main": "./dist/runtime-api.mjs",
+  "types": "./dist/runtime-api.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/runtime-api.d.mts",
+      "import": "./dist/runtime-api.mjs",
+      "default": "./dist/runtime-api.mjs"
+    },
+    "./api": {
+      "types": "./dist/api.d.mts",
+      "import": "./dist/api.mjs",
+      "default": "./dist/api.mjs"
+    },
+    "./runtime-api": {
+      "types": "./dist/runtime-api.d.mts",
+      "import": "./dist/runtime-api.mjs",
+      "default": "./dist/runtime-api.mjs"
+    },
+    "./speaker": {
+      "types": "./dist/speaker.d.mts",
+      "import": "./dist/speaker.mjs",
+      "default": "./dist/speaker.mjs"
+    },
+    "./voice-models": {
+      "types": "./dist/voice-models.d.mts",
+      "import": "./dist/voice-models.mjs",
+      "default": "./dist/voice-models.mjs"
+    }
+  },
+  "dependencies": {
+    "openclaw": "workspace:*"
+  }
+}

packages/speech-core/runtime-api.ts

@@ -0,0 +1,44 @@
+// Runtime speech API barrel for TTS preferences, synthesis, streaming, and test
+// helpers used by speech-capable plugins.
+export {
+  buildTtsSystemPromptHint,
+  getLastTtsAttempt,
+  getResolvedSpeechProviderConfig,
+  getTtsMaxLength,
+  getTtsPersona,
+  getTtsProvider,
+  isSummarizationEnabled,
+  isTtsEnabled,
+  isTtsProviderConfigured,
+  listSpeechVoices,
+  listTtsPersonas,
+  maybeApplyTtsToPayload,
+  resolveExplicitTtsOverrides,
+  resolveTtsAutoMode,
+  resolveTtsConfig,
+  resolveTtsPrefsPath,
+  resolveTtsProviderOrder,
+  setLastTtsAttempt,
+  setSummarizationEnabled,
+  setTtsAutoMode,
+  setTtsEnabled,
+  setTtsMaxLength,
+  setTtsPersona,
+  setTtsProvider,
+  synthesizeSpeech,
+  streamSpeech,
+  textToSpeech,
+  textToSpeechStream,
+  textToSpeechTelephony,
+  testApi as _test,
+  testApi,
+  type ResolvedTtsConfig,
+  type ResolvedTtsModelOverrides,
+  type TtsDirectiveOverrides,
+  type TtsDirectiveParseResult,
+  type TtsResult,
+  type TtsSynthesisResult,
+  type TtsSynthesisStreamResult,
+  type TtsStreamResult,
+  type TtsTelephonyResult,
+} from "./src/tts.js";

packages/speech-core/speaker.ts

@@ -0,0 +1,48 @@
+// Speaker-selection compatibility helpers for plugins that renamed voice fields
+// over time but still need one normalized config object.
+export type SpeakerSelectionConfig = Record<string, unknown>;
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+/** Populate canonical and legacy speaker voice fields together. */
+export function withSpeakerSelectionCompat(
+  config: SpeakerSelectionConfig | undefined,
+): SpeakerSelectionConfig {
+  const next: SpeakerSelectionConfig = config ? { ...config } : {};
+  const speakerVoice = readString(next.speakerVoice);
+  const speakerVoiceId = readString(next.speakerVoiceId);
+  const voice = readString(next.voice);
+  const voiceName = readString(next.voiceName);
+  const voiceId = readString(next.voiceId);
+  const canonicalVoice = speakerVoice ?? voice ?? voiceName;
+  const canonicalVoiceId = speakerVoiceId ?? voiceId;
+  if (canonicalVoice) {
+    next.speakerVoice = canonicalVoice;
+    next.voice = canonicalVoice;
+    next.voiceName = canonicalVoice;
+  }
+  if (canonicalVoiceId) {
+    next.speakerVoiceId = canonicalVoiceId;
+    next.voiceId = canonicalVoiceId;
+  }
+  return next;
+}
+
+/** Fill legacy speaker fields only when callers have not set them explicitly. */
+export function withSpeakerSelectionFallbackCompat(
+  config: SpeakerSelectionConfig | undefined,
+): SpeakerSelectionConfig {
+  const next: SpeakerSelectionConfig = config ? { ...config } : {};
+  const speakerVoice = readString(next.speakerVoice);
+  const speakerVoiceId = readString(next.speakerVoiceId);
+  if (speakerVoice) {
+    next.voice ??= speakerVoice;
+    next.voiceName ??= speakerVoice;
+  }
+  if (speakerVoiceId) {
+    next.voiceId ??= speakerVoiceId;
+  }
+  return next;
+}

packages/speech-core/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.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"
+  ]
+}

packages/speech-core/voice-models.ts

@@ -0,0 +1,271 @@
+// Voice model catalog helpers shared by TTS and realtime voice plugins.
+import { parseModelCatalogRef } from "@openclaw/model-catalog-core/model-catalog-refs";
+
+export type VoiceModelCapability = "tts" | "realtime_transcription" | "realtime_voice";
+
+/** Capability flags advertised by a voice model catalog entry. */
+export type VoiceModelCapabilities = Partial<Record<VoiceModelCapability, true>>;
+
+/** Provider/model override parsed from config. */
+export type VoiceModelRef = {
+  provider: string;
+  model: string;
+  timeoutMs?: number;
+};
+
+/** Static provider metadata used to validate configured voice model refs. */
+export type VoiceModelProvider = {
+  id: string;
+  aliases?: readonly string[];
+  label?: string;
+  defaultModel?: string | null;
+  models?: readonly string[];
+};
+
+/** Synthesized voice model catalog row exposed to provider/model selection. */
+export type VoiceModelCatalogEntry = {
+  kind: "voice";
+  provider: string;
+  model: string;
+  source: "static";
+  capabilities: VoiceModelCapabilities;
+  label?: string;
+  default?: boolean;
+  modes?: readonly string[];
+};
+
+/** Ordered provider candidate, optionally with a concrete voice model override. */
+export type VoiceProviderCandidate = {
+  provider: string;
+  voiceModel?: VoiceModelRef;
+};
+
+type VoiceModelConfig =
+  | string
+  | {
+      primary?: unknown;
+      fallbacks?: unknown;
+      timeoutMs?: unknown;
+    };
+
+function normalizeString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function normalizeLowercaseString(value: unknown): string | undefined {
+  return normalizeString(value)?.toLowerCase();
+}
+
+function normalizeTimeoutMs(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+    ? Math.floor(value)
+    : undefined;
+}
+
+function parseVoiceModelRef(value: unknown): VoiceModelRef | undefined {
+  const parsed = typeof value === "string" ? parseModelCatalogRef(value) : null;
+  return parsed ? { provider: parsed.provider, model: parsed.modelId } : undefined;
+}
+
+function sameProvider(left: string | undefined, right: string | undefined): boolean {
+  const normalizedLeft = normalizeLowercaseString(left);
+  return Boolean(normalizedLeft && normalizedLeft === normalizeLowercaseString(right));
+}
+
+/** Match provider ids case-insensitively across canonical id and aliases. */
+export function providerMatchesId(provider: VoiceModelProvider, providerId?: string): boolean {
+  return (
+    sameProvider(provider.id, providerId) ||
+    (provider.aliases ?? []).some((alias) => sameProvider(alias, providerId))
+  );
+}
+
+/** Find the provider metadata for a configured provider id or alias. */
+export function findVoiceModelProvider<T extends VoiceModelProvider>(params: {
+  providers: readonly T[];
+  providerId?: string;
+}): T | undefined {
+  return params.providers.find((provider) => providerMatchesId(provider, params.providerId));
+}
+
+/** Return true when a provider advertises the requested model. */
+export function voiceProviderSupportsModel(
+  provider: VoiceModelProvider | undefined,
+  model: unknown,
+): boolean {
+  if (!provider) {
+    return false;
+  }
+  const normalizedModel = normalizeString(model);
+  return [provider.defaultModel, ...(provider.models ?? [])].some(
+    (candidate) => normalizeString(candidate) === normalizedModel,
+  );
+}
+
+/** Parse primary/fallback voice model refs from config. */
+export function resolveVoiceModelRefs(config: unknown): VoiceModelRef[] {
+  const voiceModel = config as VoiceModelConfig | undefined;
+  if (typeof voiceModel === "string") {
+    const parsed = parseVoiceModelRef(voiceModel);
+    return parsed ? [parsed] : [];
+  }
+  if (typeof voiceModel !== "object" || voiceModel === null || Array.isArray(voiceModel)) {
+    return [];
+  }
+  const timeoutMs = normalizeTimeoutMs(voiceModel.timeoutMs);
+  const refs: VoiceModelRef[] = [];
+  const addRef = (value: unknown) => {
+    const parsed = parseVoiceModelRef(value);
+    if (parsed) {
+      refs.push({ ...parsed, ...(timeoutMs === undefined ? {} : { timeoutMs }) });
+    }
+  };
+  addRef(voiceModel.primary);
+  if (Array.isArray(voiceModel.fallbacks)) {
+    for (const fallback of voiceModel.fallbacks) {
+      addRef(fallback);
+    }
+  }
+  return refs;
+}
+
+/** Resolve configured voice model refs that are supported by known providers. */
+export function resolveSupportedVoiceModelRefs(params: {
+  config: unknown;
+  providers: readonly VoiceModelProvider[];
+  providerId?: string;
+}): VoiceModelRef[] {
+  return resolveVoiceModelRefs(params.config).flatMap((ref) => {
+    const provider = findVoiceModelProvider({
+      providers: params.providers,
+      providerId: ref.provider,
+    });
+    if (!provider || (params.providerId && !providerMatchesId(provider, params.providerId))) {
+      return [];
+    }
+    return voiceProviderSupportsModel(provider, ref.model)
+      ? [{ ...ref, provider: provider.id }]
+      : [];
+  });
+}
+
+/** Build ordered provider candidates from primary provider plus voice-model fallbacks. */
+export function resolveVoiceProviderCandidates(params: {
+  primaryProvider: string;
+  providers: readonly VoiceModelProvider[];
+  voiceModelConfig?: unknown;
+}): VoiceProviderCandidate[] {
+  const primary =
+    findVoiceModelProvider({ providers: params.providers, providerId: params.primaryProvider })
+      ?.id ?? params.primaryProvider;
+  const candidates: VoiceProviderCandidate[] = [];
+  const seenProviders = new Set<string>();
+  const addCandidate = (candidate: VoiceProviderCandidate) => {
+    candidates.push(candidate);
+    seenProviders.add(candidate.provider);
+  };
+  const refs = resolveSupportedVoiceModelRefs({
+    config: params.voiceModelConfig,
+    providers: params.providers,
+  });
+  const primaryRefs = refs.filter((ref) => ref.provider === primary);
+  for (const voiceModel of primaryRefs) {
+    addCandidate({ provider: primary, voiceModel });
+  }
+  if (primaryRefs.length === 0) {
+    addCandidate({ provider: primary });
+  }
+  for (const voiceModel of refs) {
+    if (voiceModel.provider !== primary) {
+      addCandidate({ provider: voiceModel.provider, voiceModel });
+    }
+  }
+  for (const provider of params.providers) {
+    if (!seenProviders.has(provider.id)) {
+      addCandidate({ provider: provider.id });
+    }
+  }
+  return candidates;
+}
+
+/** Resolve only the primary provider candidate for direct synthesis paths. */
+export function resolvePrimaryVoiceProviderCandidate(params: {
+  primaryProvider: string;
+  providers: readonly VoiceModelProvider[];
+  voiceModelConfig?: unknown;
+}): VoiceProviderCandidate {
+  const provider =
+    findVoiceModelProvider({ providers: params.providers, providerId: params.primaryProvider })
+      ?.id ?? params.primaryProvider;
+  const voiceModel = resolveSupportedVoiceModelRefs({
+    config: params.voiceModelConfig,
+    providers: params.providers,
+    providerId: provider,
+  })[0];
+  return voiceModel ? { provider, voiceModel } : { provider };
+}
+
+/** Read provider config by configured id, canonical id, or alias. */
+export function getVoiceProviderConfig<TConfig extends Record<string, unknown>>(params: {
+  providerConfigs: Record<string, TConfig | undefined>;
+  provider: VoiceModelProvider;
+  configuredProviderId?: string;
+}): TConfig {
+  const candidates = [
+    normalizeString(params.configuredProviderId),
+    params.provider.id,
+    ...(params.provider.aliases ?? []),
+  ].filter((key): key is string => Boolean(key));
+  const configuredKeys = Object.keys(params.providerConfigs);
+  for (const candidate of candidates) {
+    if (Object.hasOwn(params.providerConfigs, candidate)) {
+      return params.providerConfigs[candidate] ?? ({} as TConfig);
+    }
+    const normalizedCandidate = normalizeLowercaseString(candidate);
+    const matchingKey = configuredKeys.find(
+      (key) => normalizeLowercaseString(key) === normalizedCandidate,
+    );
+    if (matchingKey) {
+      return params.providerConfigs[matchingKey] ?? ({} as TConfig);
+    }
+  }
+  return {} as TConfig;
+}
+
+/** Convert provider metadata into static voice catalog entries. */
+export function synthesizeVoiceModelCatalogEntries(params: {
+  provider: VoiceModelProvider;
+  capabilities: VoiceModelCapabilities;
+  modes?: readonly string[];
+}): VoiceModelCatalogEntry[] {
+  const seen = new Set<string>();
+  const models = [params.provider.defaultModel, ...(params.provider.models ?? [])].flatMap(
+    (entry) => {
+      const model = normalizeString(entry);
+      if (!model || seen.has(model)) {
+        return [];
+      }
+      seen.add(model);
+      return [model];
+    },
+  );
+  return models.map((model) => {
+    const entry: VoiceModelCatalogEntry = {
+      kind: "voice",
+      provider: params.provider.id,
+      model,
+      source: "static",
+      capabilities: params.capabilities,
+    };
+    if (params.provider.label) {
+      entry.label = params.provider.label;
+    }
+    if (model === params.provider.defaultModel) {
+      entry.default = true;
+    }
+    if (params.modes) {
+      entry.modes = params.modes;
+    }
+    return entry;
+  });
+}