@agentprojectcontext/apx 1.24.0 → 1.27.1

package/src/core/telegram-identity.js

@@ -0,0 +1,126 @@
+// Sender identity resolution for Telegram (and, by reuse, any future channel).
+//
+// The unit of identity is the PERSON, keyed by their stable platform user id
+// (Telegram `msg.from.id`) — never the chat_id (breaks in groups) nor the phone
+// (Telegram doesn't expose it). A person is the same across every channel/chat;
+// their role lives on the global contact entry. The per-channel `owner_user_id`
+// only marks who owns *that* channel and overrides the role to "owner" there.
+//
+// resolveSender() is pure (read-only). registerSender() has the side effect of
+// recording unknown senders and claiming the first private-chat sender as the
+// channel owner when none is set yet.
+
+import {
+  readConfig,
+  findContact,
+  findTelegramChannel,
+  upsertContact,
+  upsertTelegramChannel,
+} from "./config.js";
+
+function telegramDisplayName(from) {
+  const full = [from?.first_name, from?.last_name].filter(Boolean).join(" ").trim();
+  return full || from?.username || "unknown";
+}
+
+/**
+ * Resolve who the sender is, relative to a channel. Read-only.
+ * @returns {{userId, username, name, role, isOwner, isGroup, known, note}}
+ */
+export function resolveSender({ cfg, channelName, from, chatType }) {
+  const userId = from?.id ?? null;
+  const username = from?.username || "";
+  const channel = channelName ? findTelegramChannel(cfg, channelName) : null;
+  const contact = userId != null ? findContact(cfg, userId) : null;
+  const isGroup = chatType === "group" || chatType === "supergroup";
+  const isOwner =
+    channel?.owner_user_id != null &&
+    String(channel.owner_user_id) === String(userId);
+  const role = isOwner ? "owner" : contact?.role || "guest";
+  return {
+    userId,
+    username,
+    name: contact?.name || telegramDisplayName(from),
+    role,
+    isOwner,
+    isGroup,
+    known: !!contact || isOwner,
+    note: contact?.note || "",
+  };
+}
+
+/**
+ * Resolve the tool allowlist for a sender's role.
+ *  - owner → "*" (all tools)
+ *  - guest → [] (no tools; text only)
+ *  - a role defined in telegram.roles → its `tools` ("*" or an array)
+ *  - any other named role with no definition → "*" (an admin assigned it
+ *    deliberately; default permissive rather than silently muting it)
+ * Returns "*" or an array of tool names.
+ */
+export function resolveAllowedTools(cfg, sender) {
+  if (sender?.isOwner) return "*";
+  const def = cfg?.telegram?.roles?.[sender?.role];
+  if (def && def.tools !== undefined) return def.tools;
+  if (sender?.role === "guest") return [];
+  return "*";
+}
+
+/**
+ * Like resolveSender(), but records the sender if unrecognized.
+ *  - Private chat + channel has no owner yet → claim this sender as owner.
+ *  - Otherwise an unknown sender is recorded as a role-less guest.
+ *  - A known sender's last_seen is refreshed at most once per day.
+ *
+ * Persistence is done against a FRESH on-disk config (so concurrent edits from
+ * the web/CLI aren't clobbered and the file isn't ballooned with merged
+ * defaults). The in-memory `cfg.telegram` subtree is then refreshed so later
+ * messages in this daemon session see the change without a reload.
+ * Returns { sender, mutated }.
+ */
+export function registerSender({ cfg, channelName, from, chatType }) {
+  const userId = from?.id ?? null;
+
+  // Always refresh the in-memory telegram subtree from disk so role/owner
+  // edits made via CLI/web/API are honored on the very next message without a
+  // daemon reload. Telegram traffic is low-frequency, so a config read per
+  // inbound message is cheap. The helpers below mutate `disk` in place and
+  // persist; since cfg.telegram now references it, the session stays current.
+  const disk = readConfig();
+  cfg.telegram = disk.telegram;
+
+  const base = () => resolveSender({ cfg, channelName, from, chatType });
+  if (userId == null) return { sender: base(), mutated: false };
+
+  const channel = channelName ? findTelegramChannel(disk, channelName) : null;
+  const isPrivate = chatType === "private";
+  const existing = findContact(disk, userId);
+  const now = new Date().toISOString();
+  const username = from?.username || "";
+  const name = telegramDisplayName(from);
+
+  const ownerUnset =
+    channel && (channel.owner_user_id == null || channel.owner_user_id === "");
+
+  let kind = null; // "claim" | "guest" | "touch"
+  if (isPrivate && ownerUnset) kind = "claim";
+  else if (!existing) kind = "guest";
+  else if (existing.last_seen?.slice(0, 10) !== now.slice(0, 10)) kind = "touch";
+
+  if (!kind) return { sender: base(), mutated: false };
+
+  if (kind === "claim") {
+    upsertTelegramChannel(disk, channelName, { owner_user_id: userId });
+    upsertContact(disk, userId, {
+      name, username, role: "owner", first_seen: now, last_seen: now,
+    });
+  } else if (kind === "guest") {
+    upsertContact(disk, userId, {
+      name, username, role: "guest", first_seen: now, last_seen: now,
+    });
+  } else {
+    upsertContact(disk, userId, { last_seen: now });
+  }
+
+  return { sender: base(), mutated: true };
+}

package/src/core/tools/index.js

@@ -0,0 +1,6 @@
+export * from "./registry.js";
+export { buildBrowserRouter } from "./browser.js";
+export { buildFetchRouter } from "./fetch.js";
+export { buildSearchRouter } from "./search.js";
+export { buildGlobRouter } from "./glob.js";
+export { buildGrepRouter } from "./grep.js";

package/src/core/voice/engines/elevenlabs.js

@@ -0,0 +1,96 @@
+// ElevenLabs TTS adapter.
+// API docs: https://elevenlabs.io/docs/api-reference/text-to-speech
+//
+// Config (~/.apx/config.json → voice.tts.elevenlabs):
+//   {
+//     "api_key": "sk_...",         // or env ELEVENLABS_API_KEY
+//     "model": "eleven_multilingual_v2",
+//     "voice_id": "EXAVITQu4vr4xnSDxMaL",   // default voice (Bella)
+//     "output_format": "mp3_44100_128"
+//   }
+//
+// Returns audio as mp3 by default.
+
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+const API_BASE = "https://api.elevenlabs.io/v1/text-to-speech";
+
+// Reasonable Spanish-friendly default voice (multilingual model handles it).
+const DEFAULT_VOICE_ID = "EXAVITQu4vr4xnSDxMaL";
+const DEFAULT_MODEL = "eleven_multilingual_v2";
+const DEFAULT_FORMAT = "mp3_44100_128";
+
+function getKey(config) {
+  return config.api_key || process.env.ELEVENLABS_API_KEY || "";
+}
+
+function formatToExt(fmt) {
+  if (!fmt) return "mp3";
+  if (fmt.startsWith("mp3")) return "mp3";
+  if (fmt.startsWith("pcm")) return "wav";
+  if (fmt.startsWith("ulaw")) return "ulaw";
+  if (fmt.startsWith("opus") || fmt.startsWith("ogg")) return "ogg";
+  return "mp3";
+}
+
+function formatToMime(fmt) {
+  const ext = formatToExt(fmt);
+  return {
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    ogg: "audio/ogg",
+    ulaw: "audio/basic",
+  }[ext] || "audio/mpeg";
+}
+
+export default {
+  id: "elevenlabs",
+
+  async isAvailable(config = {}) {
+    return Boolean(getKey(config));
+  },
+
+  async synthesize({ text, voice, outDir, config = {}, signal }) {
+    if (!text) throw new Error("elevenlabs: empty text");
+    const key = getKey(config);
+    if (!key) throw new Error("elevenlabs: no api_key (set ELEVENLABS_API_KEY or voice.tts.elevenlabs.api_key)");
+
+    const voiceId = voice || config.voice_id || DEFAULT_VOICE_ID;
+    const model = config.model || DEFAULT_MODEL;
+    const outputFormat = config.output_format || DEFAULT_FORMAT;
+
+    const url = `${API_BASE}/${encodeURIComponent(voiceId)}?output_format=${encodeURIComponent(outputFormat)}`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "xi-api-key": key,
+        "content-type": "application/json",
+        accept: "audio/mpeg",
+      },
+      body: JSON.stringify({
+        text,
+        model_id: model,
+      }),
+      signal,
+    });
+    if (!res.ok) {
+      const err = await res.text().catch(() => "");
+      throw new Error(`elevenlabs ${res.status}: ${err.slice(0, 300)}`);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+
+    fs.mkdirSync(outDir, { recursive: true });
+    const ext = formatToExt(outputFormat);
+    const audioPath = path.join(outDir, `elevenlabs-${randomUUID()}.${ext}`);
+    fs.writeFileSync(audioPath, buf);
+
+    return {
+      audio_path: audioPath,
+      duration_s: null,                  // ElevenLabs doesn't return duration in this endpoint
+      mime: formatToMime(outputFormat),
+      provider: "elevenlabs",
+    };
+  },
+};

package/src/core/voice/engines/gemini.js

@@ -0,0 +1,148 @@
+// Gemini TTS adapter.
+// At the time of writing the Gemini TTS surface is gated and not stable across
+// SDK versions: some models (gemini-2.5-flash-preview-tts) expose synthesize
+// via the v1beta REST surface, others require Vertex. To keep APX engine-
+// agnostic, this adapter performs a best-effort call against the documented
+// REST shape, but flags itself as not-implemented when the response does not
+// include inline audio data.
+//
+// Config (~/.apx/config.json → voice.tts.gemini):
+//   { "api_key": "...", "model": "gemini-2.5-flash-preview-tts", "voice": "Kore",
+//     "style": "habla en tono alegre y enérgico" }
+//
+// `style` is an optional natural-language instruction describing HOW the voice
+// should speak. Gemini single-speaker TTS controls delivery by prefixing the
+// text with such an instruction, so we prepend "<style>: <text>" before
+// synthesizing. A per-call `style` arg overrides the saved config.style.
+//
+// If you need a guaranteed-working Gemini TTS path today, prefer ElevenLabs or
+// OpenAI engines and revisit this once Google stabilises the API.
+
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+const DEFAULT_MODEL = "gemini-2.5-flash-preview-tts";
+
+function getKey(config, parentEnginesCfg) {
+  return (
+    config.api_key ||
+    parentEnginesCfg?.gemini?.api_key ||
+    process.env.GEMINI_API_KEY ||
+    ""
+  );
+}
+
+export default {
+  id: "gemini",
+
+  async isAvailable(config = {}, parentEnginesCfg) {
+    // Marked "available" if a key exists — but synthesize() may still throw
+    // not-implemented if the SDK surface changes. Selector will fall back.
+    return Boolean(getKey(config, parentEnginesCfg));
+  },
+
+  async synthesize({ text, voice, style, outDir, config = {}, signal, parentEnginesCfg }) {
+    if (!text) throw new Error("gemini-tts: empty text");
+    const key = getKey(config, parentEnginesCfg);
+    if (!key) throw new Error("gemini-tts: no api_key (set GEMINI_API_KEY or engines.gemini.api_key)");
+
+    const model = config.model || DEFAULT_MODEL;
+    const voiceName = voice || config.voice || "Kore";
+
+    // Speaking-style instruction: per-call `style` wins over saved config.style.
+    const styleHint = (style ?? config.style ?? "").trim();
+    const promptText = styleHint ? `${styleHint}: ${text}` : text;
+
+    const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:generateContent?key=${encodeURIComponent(key)}`;
+    const body = {
+      contents: [{ parts: [{ text: promptText }] }],
+      generationConfig: {
+        responseModalities: ["AUDIO"],
+        speechConfig: {
+          voiceConfig: {
+            prebuiltVoiceConfig: { voiceName },
+          },
+        },
+      },
+    };
+
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal,
+    });
+    if (!res.ok) {
+      const err = await res.text().catch(() => "");
+      throw new Error(`gemini-tts: not implemented for this account/model (status ${res.status}). Details: ${err.slice(0, 200)}`);
+    }
+    const json = await res.json().catch(() => ({}));
+    // The REST surface returns inlineData.data (base64) + mimeType.
+    const parts = json?.candidates?.[0]?.content?.parts || [];
+    const audioPart = parts.find((p) => p.inlineData?.data || p.inline_data?.data);
+    const inline = audioPart?.inlineData || audioPart?.inline_data;
+    if (!inline?.data) {
+      throw new Error("gemini-tts: not implemented (response did not include inline audio data)");
+    }
+    const mime = inline.mimeType || inline.mime_type || "audio/wav";
+    const rawBuf = Buffer.from(inline.data, "base64");
+
+    // Gemini commonly returns mime like "audio/L16;codec=pcm;rate=24000" —
+    // raw signed 16-bit little-endian PCM with no RIFF header. macOS afplay
+    // and most other players won't decode it. Wrap it in a WAV container if
+    // the mime signals PCM; pass through anything that's already a container.
+    const isRawPcm = /audio\/L16|audio\/pcm|codec=pcm/i.test(mime);
+    const isOgg   = /audio\/ogg/i.test(mime);
+    const isMpeg  = /audio\/mpeg/i.test(mime);
+
+    let buf = rawBuf;
+    let ext = "wav";
+    let outMime = mime;
+    if (isMpeg)      { ext = "mp3"; outMime = "audio/mpeg"; }
+    else if (isOgg)  { ext = "ogg"; outMime = "audio/ogg"; }
+    else if (isRawPcm || !/audio\/wav|audio\/x-wav/i.test(mime)) {
+      // Default any unknown / L16 mime to wrapped WAV.
+      const rateMatch = /rate=(\d+)/i.exec(mime || "");
+      const sampleRate = rateMatch ? parseInt(rateMatch[1], 10) : 24000;
+      buf = wrapPcmAsWav(rawBuf, { sampleRate, channels: 1, bitsPerSample: 16 });
+      ext = "wav";
+      outMime = "audio/wav";
+    }
+
+    fs.mkdirSync(outDir, { recursive: true });
+    const audioPath = path.join(outDir, `gemini-${randomUUID()}.${ext}`);
+    fs.writeFileSync(audioPath, buf);
+
+    return {
+      audio_path: audioPath,
+      duration_s: null,
+      mime: outMime,
+      provider: "gemini",
+    };
+  },
+};
+
+// Build a minimal 44-byte RIFF/WAVE header for signed PCM and prepend it to
+// `pcm`. Used when an engine (today: Gemini) returns raw L16 PCM bytes that
+// players can't decode without a container.
+function wrapPcmAsWav(pcm, { sampleRate = 24000, channels = 1, bitsPerSample = 16 } = {}) {
+  const byteRate = sampleRate * channels * (bitsPerSample / 8);
+  const blockAlign = channels * (bitsPerSample / 8);
+  const dataSize = pcm.length;
+  const header = Buffer.alloc(44);
+  header.write("RIFF", 0, "ascii");
+  header.writeUInt32LE(36 + dataSize, 4);
+  header.write("WAVE", 8, "ascii");
+  header.write("fmt ", 12, "ascii");
+  header.writeUInt32LE(16, 16);          // PCM fmt chunk size
+  header.writeUInt16LE(1, 20);           // audio format = PCM
+  header.writeUInt16LE(channels, 22);
+  header.writeUInt32LE(sampleRate, 24);
+  header.writeUInt32LE(byteRate, 28);
+  header.writeUInt16LE(blockAlign, 32);
+  header.writeUInt16LE(bitsPerSample, 34);
+  header.write("data", 36, "ascii");
+  header.writeUInt32LE(dataSize, 40);
+  return Buffer.concat([header, pcm]);
+}

package/src/core/voice/engines/index.js

@@ -0,0 +1,144 @@
+// TTS engine registry. Mirrors the LLM engine selector at src/core/engines/.
+//
+// Two selection modes (config.voice.tts.mode):
+//   "chain"  — ordered fallback router. Walk the engine order (config.voice.tts
+//              .order, falling back to AUTO_PREFERENCE) skipping engines turned
+//              off (config.voice.tts.<id>.enabled === false) and pick the first
+//              one whose isAvailable() returns true. "mock" is always kept as
+//              the final guaranteed fallback.
+//   "single" — use exactly config.voice.tts.provider, no fallback. Lets you keep
+//              several engines configured but only ever use the chosen one by
+//              default (the others stay available for explicit overrides).
+//
+// An explicit `provider` argument to synthesize()/selectTtsEngine() always wins
+// (used by the "Probar voz" tester to force a specific engine).
+//
+// Backward compat: when `mode` is absent it's derived from `provider`
+// (provider set & not "auto" → single; otherwise chain), so existing configs
+// keep working unchanged.
+
+import piper from "./piper.js";
+import elevenlabs from "./elevenlabs.js";
+import openai from "./openai.js";
+import gemini from "./gemini.js";
+import mock from "./mock.js";
+
+const ADAPTERS = { piper, elevenlabs, openai, gemini, mock };
+export const TTS_ENGINE_IDS = Object.keys(ADAPTERS);
+
+export const AUTO_PREFERENCE = ["piper", "elevenlabs", "openai", "gemini", "mock"];
+
+export function getTtsAdapter(provider) {
+  const a = ADAPTERS[provider];
+  if (!a) {
+    throw new Error(
+      `unknown TTS provider "${provider}". Known: ${TTS_ENGINE_IDS.join(", ")}`
+    );
+  }
+  return a;
+}
+
+function ttsConfig(globalConfig) {
+  return globalConfig?.voice?.tts || {};
+}
+
+function providerConfig(globalConfig, provider) {
+  return ttsConfig(globalConfig)?.[provider] || {};
+}
+
+function isEnabled(ttsCfg, id) {
+  return ttsCfg?.[id]?.enabled !== false;
+}
+
+/** Effective routing mode for the chain/single decision. */
+export function resolveMode(ttsCfg) {
+  if (ttsCfg?.mode === "chain" || ttsCfg?.mode === "single") return ttsCfg.mode;
+  const p = ttsCfg?.provider;
+  return p && p !== "auto" ? "single" : "chain";
+}
+
+/**
+ * Full engine order for chain mode: the user's custom order first (only known
+ * ids), then any remaining AUTO_PREFERENCE engines. Includes disabled engines
+ * so the UI can render + reorder every row; filtering happens at selection time.
+ */
+export function resolveChainOrder(ttsCfg) {
+  const custom = Array.isArray(ttsCfg?.order)
+    ? ttsCfg.order.filter((id) => TTS_ENGINE_IDS.includes(id))
+    : [];
+  const rest = AUTO_PREFERENCE.filter((id) => !custom.includes(id));
+  const full = [...custom, ...rest];
+  // Guarantee mock is present as the ultimate fallback.
+  if (!full.includes("mock")) full.push("mock");
+  return full;
+}
+
+/**
+ * Resolve which engine should handle a synthesize() call.
+ * Returns { provider, adapter, engineConfig }.
+ */
+export async function selectTtsEngine({ globalConfig, provider }) {
+  const ttsCfg = ttsConfig(globalConfig);
+
+  // 1. Explicit override (tester / API caller) always wins.
+  if (provider && provider !== "auto") {
+    const adapter = getTtsAdapter(provider);
+    return { provider, adapter, engineConfig: providerConfig(globalConfig, provider) };
+  }
+
+  const mode = resolveMode(ttsCfg);
+
+  // 2. Single mode: use the configured engine verbatim, no fallback.
+  if (mode === "single") {
+    const id = ttsCfg?.provider;
+    if (id && id !== "auto") {
+      const adapter = getTtsAdapter(id);
+      return { provider: id, adapter, engineConfig: providerConfig(globalConfig, id) };
+    }
+    // Misconfigured single mode (no concrete provider) → fall through to chain.
+  }
+
+  // 3. Chain mode: probe the (enabled) order, first available wins.
+  for (const id of resolveChainOrder(ttsCfg)) {
+    if (id !== "mock" && !isEnabled(ttsCfg, id)) continue;
+    const adapter = ADAPTERS[id];
+    const cfg = providerConfig(globalConfig, id);
+    try {
+      if (await adapter.isAvailable(cfg, globalConfig?.engines)) {
+        return { provider: id, adapter, engineConfig: cfg };
+      }
+    } catch { /* probe failures fall through */ }
+  }
+  // mock is always available, but guard anyway.
+  return {
+    provider: "mock",
+    adapter: mock,
+    engineConfig: providerConfig(globalConfig, "mock"),
+  };
+}
+
+/**
+ * Discover which engines are configured/available right now. Pure read of
+ * config + cheap probes; safe to call frequently.
+ */
+export async function listAvailableTtsEngines(globalConfig) {
+  const ttsCfg = ttsConfig(globalConfig);
+  const out = [];
+  for (const id of TTS_ENGINE_IDS) {
+    const adapter = ADAPTERS[id];
+    const cfg = providerConfig(globalConfig, id);
+    let available = false;
+    try {
+      available = await adapter.isAvailable(cfg, globalConfig?.engines);
+    } catch { available = false; }
+    out.push({
+      id,
+      available,
+      // `enabled` is a routing flag, not real config — exclude it from the
+      // "configured" heuristic so toggling on/off doesn't fake-mark an engine.
+      configured: Object.keys(cfg).filter((k) => k !== "enabled").length > 0,
+      enabled: isEnabled(ttsCfg, id),
+    });
+  }
+  return out;
+}

package/src/core/voice/engines/mock.js

@@ -0,0 +1,59 @@
+// Mock TTS engine. Writes a tiny placeholder WAV (silent) so callers get a real
+// playable file without external dependencies. Used in tests and as a fallback
+// when no real engine is configured.
+//
+// The "audio" produced is a minimally valid 8 kHz mono PCM-16 WAV with `n_ms`
+// milliseconds of silence so duration_s is meaningful. Total size grows with
+// text length so different inputs produce different files (handy in tests).
+
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+function buildSilentWav(ms) {
+  const sampleRate = 8000;
+  const numSamples = Math.max(1, Math.floor((sampleRate * ms) / 1000));
+  const byteRate = sampleRate * 2;       // 16-bit mono
+  const dataSize = numSamples * 2;
+  const buf = Buffer.alloc(44 + dataSize);
+  buf.write("RIFF", 0);
+  buf.writeUInt32LE(36 + dataSize, 4);
+  buf.write("WAVE", 8);
+  buf.write("fmt ", 12);
+  buf.writeUInt32LE(16, 16);             // PCM chunk size
+  buf.writeUInt16LE(1, 20);              // PCM format
+  buf.writeUInt16LE(1, 22);              // mono
+  buf.writeUInt32LE(sampleRate, 24);
+  buf.writeUInt32LE(byteRate, 28);
+  buf.writeUInt16LE(2, 32);              // block align
+  buf.writeUInt16LE(16, 34);             // bits per sample
+  buf.write("data", 36);
+  buf.writeUInt32LE(dataSize, 40);
+  // samples already zero-filled by Buffer.alloc → silence
+  return buf;
+}
+
+export default {
+  id: "mock",
+
+  async isAvailable() {
+    return true;
+  },
+
+  async synthesize({ text, outDir, format = "wav" }) {
+    if (!text) throw new Error("mock-tts: empty text");
+    // Roughly 60 ms per character — gives test assertions something to check.
+    const durationMs = Math.max(100, Math.min(60_000, text.length * 60));
+    const wav = buildSilentWav(durationMs);
+    const filename = `mock-${randomUUID()}.${format === "wav" ? "wav" : "wav"}`;
+    fs.mkdirSync(outDir, { recursive: true });
+    const audioPath = path.join(outDir, filename);
+    fs.writeFileSync(audioPath, wav);
+    return {
+      audio_path: audioPath,
+      duration_s: durationMs / 1000,
+      mime: "audio/wav",
+      provider: "mock",
+    };
+  },
+};

package/src/core/voice/engines/openai.js

@@ -0,0 +1,82 @@
+// OpenAI TTS adapter (tts-1 / tts-1-hd).
+// Docs: https://platform.openai.com/docs/api-reference/audio/createSpeech
+//
+// Reuses engines.openai.api_key from ~/.apx/config.json. Per-engine voice
+// config (~/.apx/config.json → voice.tts.openai) can override model/voice.
+
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+const API_URL = "https://api.openai.com/v1/audio/speech";
+const DEFAULT_MODEL = "tts-1";
+const DEFAULT_VOICE = "alloy";          // alloy|echo|fable|onyx|nova|shimmer
+
+function getKey(config, parentEnginesCfg) {
+  return (
+    config.api_key ||
+    parentEnginesCfg?.openai?.api_key ||
+    process.env.OPENAI_API_KEY ||
+    ""
+  );
+}
+
+function mimeFor(format) {
+  return {
+    mp3: "audio/mpeg",
+    opus: "audio/ogg",
+    aac: "audio/aac",
+    flac: "audio/flac",
+    wav: "audio/wav",
+    pcm: "audio/L16",
+  }[format] || "audio/mpeg";
+}
+
+export default {
+  id: "openai",
+
+  async isAvailable(config = {}, parentEnginesCfg) {
+    return Boolean(getKey(config, parentEnginesCfg));
+  },
+
+  async synthesize({ text, voice, outDir, config = {}, format, signal, parentEnginesCfg }) {
+    if (!text) throw new Error("openai-tts: empty text");
+    const key = getKey(config, parentEnginesCfg);
+    if (!key) throw new Error("openai-tts: no api_key (set OPENAI_API_KEY or engines.openai.api_key)");
+
+    const model = config.model || DEFAULT_MODEL;
+    const chosenVoice = voice || config.voice || DEFAULT_VOICE;
+    const responseFormat = format || config.format || "mp3";
+
+    const res = await fetch(API_URL, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${key}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        model,
+        voice: chosenVoice,
+        input: text,
+        response_format: responseFormat,
+      }),
+      signal,
+    });
+    if (!res.ok) {
+      const err = await res.text().catch(() => "");
+      throw new Error(`openai-tts ${res.status}: ${err.slice(0, 300)}`);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+
+    fs.mkdirSync(outDir, { recursive: true });
+    const audioPath = path.join(outDir, `openai-${randomUUID()}.${responseFormat}`);
+    fs.writeFileSync(audioPath, buf);
+
+    return {
+      audio_path: audioPath,
+      duration_s: null,
+      mime: mimeFor(responseFormat),
+      provider: "openai",
+    };
+  },
+};