bosun 0.36.2 → 0.36.4

package/voice-relay.mjs

@@ -0,0 +1,1194 @@
+/**
+ * voice-relay.mjs — Multi-provider voice relay for real-time voice sessions.
+ *
+ * Supports:
+ *   - OpenAI Realtime API (WebRTC) — direct API key
+ *   - Azure OpenAI Realtime API (WebRTC) — API key + endpoint
+ *   - Claude/Gemini provider mode (Tier 2 speech fallback + provider vision)
+ *   - Tier 2 fallback (browser STT → executor → browser TTS)
+ *   - Direct JavaScript action dispatch (voice model returns JSON, Bosun executes)
+ *
+ * @module voice-relay
+ */
+
+import { loadConfig } from "./config.mjs";
+import { execPrimaryPrompt, getPrimaryAgentName } from "./primary-agent.mjs";
+import { resolveVoiceOAuthToken } from "./voice-auth-manager.mjs";
+
+// ── Module-scope state ──────────────────────────────────────────────────────
+let _voiceConfig = null;   // cached resolved config
+let _configLoadedAt = 0;   // timestamp of last config load
+
+const CONFIG_TTL_MS = 30_000; // re-read config every 30s
+
+const OPENAI_REALTIME_URL = "https://api.openai.com/v1/realtime";
+const OPENAI_REALTIME_MODEL = "gpt-realtime-1.5"; // Released 2026-02-23; replaces gpt-4o-realtime-preview
+const OPENAI_RESPONSES_URL = "https://api.openai.com/v1/responses";
+const OPENAI_DEFAULT_VISION_MODEL = "gpt-4.1-mini";
+
+const AZURE_API_VERSION = "2025-04-01-preview";
+const ANTHROPIC_MESSAGES_URL = "https://api.anthropic.com/v1/messages";
+const ANTHROPIC_API_VERSION = "2023-06-01";
+const CLAUDE_DEFAULT_MODEL = "claude-3-7-sonnet-latest";
+const CLAUDE_DEFAULT_VISION_MODEL = "claude-3-7-sonnet-latest";
+const GEMINI_GENERATE_CONTENT_URL = "https://generativelanguage.googleapis.com/v1beta/models";
+const GEMINI_DEFAULT_MODEL = "gemini-2.5-pro";
+const GEMINI_DEFAULT_VISION_MODEL = "gemini-2.5-flash";
+
+const VALID_EXECUTORS = new Set([
+  "codex-sdk",
+  "copilot-sdk",
+  "claude-sdk",
+  "gemini-sdk",
+  "opencode-sdk",
+]);
+
+const VALID_AGENT_MODES = new Set([
+  "ask",
+  "agent",
+  "plan",
+  "code",
+  "architect",
+]);
+
+const VALID_VOICE_PROVIDERS = new Set([
+  "openai",
+  "azure",
+  "claude",
+  "gemini",
+  "fallback",
+]);
+
+const DEFAULT_VOICE_FAILOVER = Object.freeze({
+  enabled: true,
+  maxAttempts: 2,
+});
+
+function parseFailoverInt(rawValue, fallback) {
+  const parsed = Number.parseInt(String(rawValue ?? ""), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return parsed;
+}
+
+function normalizeVoiceProviderEntry(entry) {
+  if (typeof entry === "string") {
+    const provider = String(entry || "").trim().toLowerCase();
+    if (!VALID_VOICE_PROVIDERS.has(provider)) return null;
+    return {
+      provider,
+      model: null,
+      visionModel: null,
+      voiceId: null,
+      azureDeployment: null,
+    };
+  }
+
+  if (!entry || typeof entry !== "object") return null;
+  const provider = String(entry.provider || "").trim().toLowerCase();
+  if (!VALID_VOICE_PROVIDERS.has(provider)) return null;
+
+  const model = String(entry.model || "").trim() || null;
+  const visionModel = String(entry.visionModel || "").trim() || null;
+  const voiceId = String(entry.voiceId || "").trim() || null;
+  const azureDeployment = String(entry.azureDeployment || "").trim() || null;
+
+  return {
+    provider,
+    model,
+    visionModel,
+    voiceId,
+    azureDeployment,
+  };
+}
+
+function normalizeVoiceProviderChain(rawProviders, primaryProvider) {
+  const dedup = new Set();
+  const chain = [];
+  const pushEntry = (entry) => {
+    const normalized = normalizeVoiceProviderEntry(entry);
+    if (!normalized) return;
+    if (dedup.has(normalized.provider)) return;
+    dedup.add(normalized.provider);
+    chain.push(normalized);
+  };
+
+  if (Array.isArray(rawProviders)) {
+    rawProviders.forEach(pushEntry);
+  } else if (typeof rawProviders === "string" && rawProviders.trim()) {
+    rawProviders
+      .split(",")
+      .map((item) => item.trim())
+      .filter(Boolean)
+      .forEach((provider) => pushEntry({ provider }));
+  }
+
+  if (primaryProvider && VALID_VOICE_PROVIDERS.has(primaryProvider)) {
+    if (!dedup.has(primaryProvider)) {
+      chain.unshift({
+        provider: primaryProvider,
+        model: null,
+        visionModel: null,
+        voiceId: null,
+        azureDeployment: null,
+      });
+    }
+  }
+
+  return chain;
+}
+
+function getProviderChainWithCredentialFallbacks(chain, credentialState = {}) {
+  const dedup = new Set();
+  const providers = [];
+  const pushProvider = (provider) => {
+    if (!provider || dedup.has(provider)) return;
+    if (!VALID_VOICE_PROVIDERS.has(provider)) return;
+    dedup.add(provider);
+    providers.push(provider);
+  };
+
+  chain.forEach((entry) => pushProvider(entry.provider));
+
+  if (credentialState.azureAvailable) pushProvider("azure");
+  if (credentialState.openaiAvailable) pushProvider("openai");
+  if (credentialState.claudeAvailable) pushProvider("claude");
+  if (credentialState.geminiAvailable) pushProvider("gemini");
+  pushProvider("fallback");
+
+  return providers;
+}
+
+function shouldFailoverRealtimeError(err) {
+  const message = String(err?.message || "");
+  const statusMatch = message.match(/\((\d{3})\)/);
+  const status = statusMatch ? Number.parseInt(statusMatch[1], 10) : null;
+  if (status && (status === 401 || status === 403 || status === 408 || status === 409 || status === 429 || status >= 500)) {
+    return true;
+  }
+  if (/ECONNRESET|ETIMEDOUT|network|fetch failed|connection|connect/i.test(message)) {
+    return true;
+  }
+  return false;
+}
+
+function redactSecretLikeText(value) {
+  let sanitized = String(value || "");
+  sanitized = sanitized.replace(/\b(sk|rk|pk)-[A-Za-z0-9_-]{10,}\b/g, "$1-***REDACTED***");
+  sanitized = sanitized.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}\b/gi, "Bearer ***REDACTED***");
+  sanitized = sanitized.replace(
+    /("?(?:api[_-]?key|access[_-]?token|client[_-]?secret|authorization)"?\s*[:=]\s*"?)([^",\s}{\]]+)/gi,
+    "$1***REDACTED***",
+  );
+  return sanitized;
+}
+
+async function buildProviderErrorDetails(response, fallback = "unknown") {
+  const raw = await response.text().catch(() => fallback);
+  return redactSecretLikeText(raw || fallback);
+}
+
+function sanitizeVoiceCallContext(context = {}) {
+  const rawSessionId = String(context?.sessionId || "").trim();
+  const rawExecutor = String(context?.executor || "").trim().toLowerCase();
+  const rawMode = String(context?.mode || "").trim().toLowerCase();
+  const rawModel = String(context?.model || "").trim();
+
+  return {
+    sessionId: rawSessionId || null,
+    executor: VALID_EXECUTORS.has(rawExecutor) ? rawExecutor : null,
+    mode: VALID_AGENT_MODES.has(rawMode) ? rawMode : null,
+    model: rawModel || null,
+  };
+}
+
+function buildSessionScopedInstructions(baseInstructions, callContext = {}) {
+  const context = sanitizeVoiceCallContext(callContext);
+  if (!context.sessionId && !context.executor && !context.mode && !context.model) {
+    return baseInstructions;
+  }
+
+  const suffix = [
+    "",
+    "## Bosun Voice Call Context",
+    `Active chat session id: ${context.sessionId || "none"}.`,
+    context.executor
+      ? `Preferred executor for delegated work: ${context.executor}.`
+      : "Preferred executor for delegated work: use configured default.",
+    context.mode
+      ? `Preferred delegation mode: ${context.mode}.`
+      : "Preferred delegation mode: use configured default.",
+    context.model
+      ? `Preferred model override: ${context.model}.`
+      : "Preferred model override: none.",
+    "",
+    "## Required Behavior",
+    "- For every user turn in this call, invoke delegate_to_agent exactly once before any final spoken answer.",
+    "- For coding, repo, task, debugging, automation, or workspace requests, call delegate_to_agent before finalizing your response.",
+    "- Preserve user intent when delegating. Do not paraphrase away technical detail.",
+    "- Keep responses concise after receiving delegate_to_agent output.",
+  ].join("\n");
+
+  return `${baseInstructions}${suffix}`;
+}
+
+function resolveToolChoice(toolDefinitions, callContext = {}) {
+  const context = sanitizeVoiceCallContext(callContext);
+  const hasDelegateTool = Array.isArray(toolDefinitions)
+    && toolDefinitions.some((tool) => tool?.name === "delegate_to_agent");
+  if (context.sessionId && hasDelegateTool) {
+    return {
+      type: "function",
+      name: "delegate_to_agent",
+    };
+  }
+  return "auto";
+}
+
+function extractModelResponseText(payload) {
+  if (!payload || typeof payload !== "object") return "";
+  if (typeof payload.output_text === "string" && payload.output_text.trim()) {
+    return payload.output_text.trim();
+  }
+
+  const output = Array.isArray(payload.output) ? payload.output : [];
+  for (const item of output) {
+    const content = Array.isArray(item?.content) ? item.content : [];
+    for (const part of content) {
+      if (typeof part?.text === "string" && part.text.trim()) {
+        return part.text.trim();
+      }
+    }
+  }
+
+  const choices = Array.isArray(payload.choices) ? payload.choices : [];
+  for (const choice of choices) {
+    const text = String(choice?.message?.content || "").trim();
+    if (text) return text;
+  }
+
+  return "";
+}
+
+function parseImageDataUrl(dataUrl) {
+  const raw = String(dataUrl || "").trim();
+  const match = raw.match(
+    /^data:(image\/(?:jpeg|jpg|png|webp));base64,([A-Za-z0-9+/=]+)$/i,
+  );
+  if (!match) {
+    throw new Error("Invalid frame format (expected data:image/*;base64,...)");
+  }
+  return {
+    mimeType: String(match[1] || "").toLowerCase(),
+    base64Data: String(match[2] || ""),
+    dataUrl: raw,
+  };
+}
+
+function extractClaudeResponseText(payload) {
+  if (!payload || typeof payload !== "object") return "";
+  const content = Array.isArray(payload.content) ? payload.content : [];
+  const text = content
+    .filter((part) => part?.type === "text")
+    .map((part) => String(part?.text || "").trim())
+    .filter(Boolean)
+    .join("\n")
+    .trim();
+  if (text) return text;
+  return "";
+}
+
+function extractGeminiResponseText(payload) {
+  if (!payload || typeof payload !== "object") return "";
+  const candidates = Array.isArray(payload.candidates) ? payload.candidates : [];
+  for (const candidate of candidates) {
+    const parts = Array.isArray(candidate?.content?.parts)
+      ? candidate.content.parts
+      : [];
+    const text = parts
+      .map((part) => String(part?.text || "").trim())
+      .filter(Boolean)
+      .join("\n")
+      .trim();
+    if (text) return text;
+  }
+  return "";
+}
+
+async function analyzeVisionWithOpenAI(dataUrl, model, prompt, contextText, cfg) {
+  const response = await fetch(OPENAI_RESPONSES_URL, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${cfg.openaiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      model,
+      temperature: 0.2,
+      max_output_tokens: 220,
+      input: [
+        {
+          role: "user",
+          content: [
+            {
+              type: "input_text",
+              text: `${prompt}\n\n${contextText}`,
+            },
+            {
+              type: "input_image",
+              image_url: dataUrl,
+              detail: "high",
+            },
+          ],
+        },
+      ],
+    }),
+  });
+  if (!response.ok) {
+    const errText = await buildProviderErrorDetails(response, "unknown");
+    throw new Error(`Vision request failed (${response.status}): ${errText}`);
+  }
+  const payload = await response.json();
+  const summary = extractModelResponseText(payload);
+  if (!summary) {
+    throw new Error("Vision model returned an empty summary");
+  }
+  return {
+    summary,
+    provider: "openai",
+    model,
+  };
+}
+
+async function analyzeVisionWithAzure(dataUrl, model, prompt, contextText, cfg) {
+  const endpoint = cfg.azureEndpoint.replace(/\/+$/, "");
+  const url = `${endpoint}/openai/responses?api-version=${AZURE_API_VERSION}`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "api-key": cfg.azureKey,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      model,
+      temperature: 0.2,
+      max_output_tokens: 220,
+      input: [
+        {
+          role: "user",
+          content: [
+            {
+              type: "input_text",
+              text: `${prompt}\n\n${contextText}`,
+            },
+            {
+              type: "input_image",
+              image_url: dataUrl,
+              detail: "high",
+            },
+          ],
+        },
+      ],
+    }),
+  });
+  if (!response.ok) {
+    const errText = await buildProviderErrorDetails(response, "unknown");
+    throw new Error(`Azure vision request failed (${response.status}): ${errText}`);
+  }
+  const payload = await response.json();
+  const summary = extractModelResponseText(payload);
+  if (!summary) {
+    throw new Error("Azure vision model returned an empty summary");
+  }
+  return {
+    summary,
+    provider: "azure",
+    model,
+  };
+}
+
+async function analyzeVisionWithClaude(frame, model, prompt, contextText, cfg) {
+  const response = await fetch(ANTHROPIC_MESSAGES_URL, {
+    method: "POST",
+    headers: {
+      "x-api-key": cfg.claudeKey,
+      "anthropic-version": ANTHROPIC_API_VERSION,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      model,
+      temperature: 0.2,
+      max_tokens: 260,
+      messages: [
+        {
+          role: "user",
+          content: [
+            { type: "text", text: `${prompt}\n\n${contextText}` },
+            {
+              type: "image",
+              source: {
+                type: "base64",
+                media_type: frame.mimeType,
+                data: frame.base64Data,
+              },
+            },
+          ],
+        },
+      ],
+    }),
+  });
+  if (!response.ok) {
+    const errText = await buildProviderErrorDetails(response, "unknown");
+    throw new Error(`Claude vision request failed (${response.status}): ${errText}`);
+  }
+  const payload = await response.json();
+  const summary = extractClaudeResponseText(payload);
+  if (!summary) {
+    throw new Error("Claude vision model returned an empty summary");
+  }
+  return {
+    summary,
+    provider: "claude",
+    model,
+  };
+}
+
+async function analyzeVisionWithGemini(frame, model, prompt, contextText, cfg) {
+  const apiKey = String(cfg.geminiKey || "").trim();
+  const endpoint =
+    `${GEMINI_GENERATE_CONTENT_URL}/${encodeURIComponent(model)}:generateContent?key=${encodeURIComponent(apiKey)}`;
+  const response = await fetch(endpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      contents: [
+        {
+          role: "user",
+          parts: [
+            { text: `${prompt}\n\n${contextText}` },
+            {
+              inlineData: {
+                mimeType: frame.mimeType,
+                data: frame.base64Data,
+              },
+            },
+          ],
+        },
+      ],
+      generationConfig: {
+        temperature: 0.2,
+        maxOutputTokens: 220,
+      },
+    }),
+  });
+  if (!response.ok) {
+    const errText = await buildProviderErrorDetails(response, "unknown");
+    throw new Error(`Gemini vision request failed (${response.status}): ${errText}`);
+  }
+  const payload = await response.json();
+  const summary = extractGeminiResponseText(payload);
+  if (!summary) {
+    throw new Error("Gemini vision model returned an empty summary");
+  }
+  return {
+    summary,
+    provider: "gemini",
+    model,
+  };
+}
+
+// ── Voice provider detection ────────────────────────────────────────────────
+
+/**
+ * Resolve voice configuration from bosun config + env.
+ * Returns { provider, model, openaiKey, azureKey, azureEndpoint, azureDeployment,
+ *           claudeKey, geminiKey, voiceId, turnDetection, instructions,
+ *           fallbackMode, delegateExecutor, enabled, visionModel }
+ */
+export function getVoiceConfig(forceReload = false) {
+  if (!forceReload && _voiceConfig && (Date.now() - _configLoadedAt < CONFIG_TTL_MS)) {
+    return _voiceConfig;
+  }
+
+  const cfg = loadConfig();
+  const voice = cfg.voice || {};
+
+  // Provider priority: config > env > key autodetect.
+  // "auto" resolves to azure/openai/claude/gemini/fallback based on available credentials.
+  const rawProvider = String(
+    voice.provider || process.env.VOICE_PROVIDER || "auto",
+  )
+    .trim()
+    .toLowerCase();
+
+  // API keys
+  const openaiOAuthToken =
+    String(voice.openaiAccessToken || "").trim()
+    || resolveVoiceOAuthToken("openai", forceReload)?.token
+    || "";
+  const openaiKey = voice.openaiApiKey
+    || process.env.OPENAI_REALTIME_API_KEY
+    || process.env.OPENAI_API_KEY
+    || "";
+
+  const azureOAuthToken =
+    String(voice.azureAccessToken || "").trim()
+    || resolveVoiceOAuthToken("azure", forceReload)?.token
+    || "";
+  const azureKey = voice.azureApiKey
+    || process.env.AZURE_OPENAI_REALTIME_API_KEY
+    || process.env.AZURE_OPENAI_API_KEY
+    || "";
+
+  const azureEndpoint = voice.azureEndpoint
+    || process.env.AZURE_OPENAI_REALTIME_ENDPOINT
+    || process.env.AZURE_OPENAI_ENDPOINT
+    || "";
+
+  const azureDeployment = voice.azureDeployment
+    || process.env.AZURE_OPENAI_REALTIME_DEPLOYMENT
+    || "gpt-realtime-1.5";
+
+  const claudeOAuthToken =
+    String(voice.claudeAccessToken || "").trim()
+    || resolveVoiceOAuthToken("claude", forceReload)?.token
+    || "";
+  const claudeKey = voice.claudeApiKey
+    || process.env.ANTHROPIC_API_KEY
+    || "";
+
+  const geminiOAuthToken =
+    String(voice.geminiAccessToken || "").trim()
+    || resolveVoiceOAuthToken("gemini", forceReload)?.token
+    || "";
+  const geminiKey = voice.geminiApiKey
+    || process.env.GEMINI_API_KEY
+    || process.env.GOOGLE_API_KEY
+    || "";
+
+  const openaiAvailable = Boolean(openaiOAuthToken || openaiKey);
+  const azureAvailable = Boolean((azureOAuthToken || azureKey) && azureEndpoint);
+  const claudeAvailable = Boolean(claudeKey || claudeOAuthToken);
+  const geminiAvailable = Boolean(geminiKey || geminiOAuthToken);
+
+  const autoProvider =
+    azureAvailable
+      ? "azure"
+      : (openaiAvailable
+          ? "openai"
+          : (claudeAvailable
+              ? "claude"
+              : (geminiAvailable ? "gemini" : "fallback")));
+
+  const provider = rawProvider === "auto" ? autoProvider : rawProvider;
+
+  const providerChain = normalizeVoiceProviderChain(
+    voice.providers || process.env.VOICE_PROVIDERS || [],
+    provider,
+  );
+  const providerChainWithFallbacks = getProviderChainWithCredentialFallbacks(providerChain, {
+    openaiAvailable,
+    azureAvailable,
+    claudeAvailable,
+    geminiAvailable,
+  });
+
+  const realtimeCandidates = providerChain
+    .filter((entry) => entry.provider === "openai" || entry.provider === "azure")
+    .map((entry) => ({ ...entry }));
+  if (!realtimeCandidates.length && (provider === "openai" || provider === "azure")) {
+    realtimeCandidates.push({
+      provider,
+      model: null,
+      visionModel: null,
+      voiceId: null,
+      azureDeployment: null,
+    });
+  }
+
+  const failoverEnabledRaw =
+    voice?.failover?.enabled ?? process.env.VOICE_FAILOVER_ENABLED;
+  const failoverEnabled =
+    failoverEnabledRaw == null
+      ? DEFAULT_VOICE_FAILOVER.enabled
+      : !["0", "false", "no", "off"].includes(
+          String(failoverEnabledRaw).trim().toLowerCase(),
+        );
+  const failoverMaxAttempts = parseFailoverInt(
+    voice?.failover?.maxAttempts ?? process.env.VOICE_FAILOVER_MAX_ATTEMPTS,
+    DEFAULT_VOICE_FAILOVER.maxAttempts,
+  );
+
+  const diagnostics = [];
+  if (
+    process.env.OPENAI_REALTIME_API_KEY
+    && process.env.OPENAI_API_KEY
+    && process.env.OPENAI_REALTIME_API_KEY !== process.env.OPENAI_API_KEY
+  ) {
+    diagnostics.push(
+      "Both OPENAI_REALTIME_API_KEY and OPENAI_API_KEY are set; realtime key takes precedence.",
+    );
+  }
+  if (/^sk-test-/i.test(String(openaiKey || ""))) {
+    diagnostics.push(
+      "OpenAI realtime key appears to be a test/placeholder value (sk-test-*).",
+    );
+  }
+  const defaultModel =
+    provider === "claude"
+      ? CLAUDE_DEFAULT_MODEL
+      : provider === "gemini"
+        ? GEMINI_DEFAULT_MODEL
+        : OPENAI_REALTIME_MODEL;
+  const model = voice.model || process.env.VOICE_MODEL || defaultModel;
+  const voiceId = voice.voiceId || process.env.VOICE_ID || "alloy";
+  const turnDetection =
+    voice.turnDetection || process.env.VOICE_TURN_DETECTION || "server_vad";
+  const defaultVisionModel =
+    provider === "claude"
+      ? CLAUDE_DEFAULT_VISION_MODEL
+      : provider === "gemini"
+        ? GEMINI_DEFAULT_VISION_MODEL
+        : OPENAI_DEFAULT_VISION_MODEL;
+  const visionModel =
+    voice.visionModel || process.env.VOICE_VISION_MODEL || defaultVisionModel;
+  const fallbackMode =
+    voice.fallbackMode || process.env.VOICE_FALLBACK_MODE || "browser";
+  const delegateExecutor =
+    voice.delegateExecutor ||
+    process.env.VOICE_DELEGATE_EXECUTOR ||
+    cfg.primaryAgent ||
+    "codex-sdk";
+  const enabled =
+    voice.enabled != null
+      ? voice.enabled !== false
+      : !["0", "false", "no", "off"].includes(
+          String(process.env.VOICE_ENABLED || "")
+            .trim()
+            .toLowerCase(),
+        );
+
+  const instructions = voice.instructions || `You are Bosun, a helpful voice assistant for the VirtEngine development platform.
+You help developers manage tasks, steer coding agents, monitor builds, and navigate the workspace.
+Be concise and conversational. When users ask about code or tasks, use the available tools.
+For complex operations like writing code or creating PRs, delegate to the appropriate agent.`;
+
+  _voiceConfig = Object.freeze({
+    provider,
+    providerChain,
+    providerChainWithFallbacks,
+    realtimeCandidates,
+    failover: {
+      enabled: failoverEnabled,
+      maxAttempts: failoverMaxAttempts,
+    },
+    model,
+    openaiKey,
+    openaiOAuthToken,
+    azureKey,
+    azureOAuthToken,
+    azureEndpoint,
+    azureDeployment,
+    claudeKey,
+    claudeOAuthToken,
+    geminiKey,
+    geminiOAuthToken,
+    voiceId,
+    turnDetection,
+    visionModel,
+    instructions,
+    fallbackMode,
+    delegateExecutor,
+    enabled,
+    diagnostics,
+  });
+  _configLoadedAt = Date.now();
+  return _voiceConfig;
+}
+
+/**
+ * Check if any voice tier is available.
+ */
+export function isVoiceAvailable() {
+  const cfg = getVoiceConfig();
+  if (!cfg.enabled) return { available: false, tier: null, reason: "Voice disabled in config" };
+
+  const realtimeProvider = cfg.realtimeCandidates.find((candidate) => {
+    if (candidate.provider === "openai") {
+      return Boolean(cfg.openaiOAuthToken || cfg.openaiKey);
+    }
+    if (candidate.provider === "azure") {
+      return Boolean((cfg.azureOAuthToken || cfg.azureKey) && cfg.azureEndpoint);
+    }
+    return false;
+  });
+  if (realtimeProvider) {
+    return { available: true, tier: 1, provider: realtimeProvider.provider };
+  }
+
+  if (cfg.provider === "claude" && (cfg.claudeKey || cfg.claudeOAuthToken)) {
+    return { available: true, tier: 2, provider: "claude" };
+  }
+  if (cfg.provider === "gemini" && (cfg.geminiKey || cfg.geminiOAuthToken)) {
+    return { available: true, tier: 2, provider: "gemini" };
+  }
+  if (cfg.fallbackMode === "disabled") {
+    return {
+      available: false,
+      tier: null,
+      reason: `Voice provider "${cfg.provider}" is not configured and fallback is disabled`,
+    };
+  }
+  // Tier 2 fallback available when enabled
+  return { available: true, tier: 2, provider: "fallback" };
+}
+
+/**
+ * Create an ephemeral token for OpenAI Realtime API (WebRTC).
+ * Returns { token, expiresAt, model, voiceId, provider }
+ */
+export async function createEphemeralToken(toolDefinitions = [], callContext = {}) {
+  const cfg = getVoiceConfig();
+  const candidates = cfg.realtimeCandidates.filter((entry) => {
+    if (entry.provider === "openai") return Boolean(cfg.openaiOAuthToken || cfg.openaiKey);
+    if (entry.provider === "azure") return Boolean((cfg.azureOAuthToken || cfg.azureKey) && cfg.azureEndpoint);
+    return false;
+  });
+
+  if (!candidates.length) {
+    throw new Error(
+      `Realtime WebRTC token is unavailable for provider "${cfg.provider}". ` +
+      "Use VOICE_PROVIDER=openai|azure and configure OAuth/API credentials for Tier 1 realtime voice.",
+    );
+  }
+
+  const maxAttempts = cfg.failover.enabled
+    ? Math.min(Math.max(cfg.failover.maxAttempts, 1), candidates.length)
+    : 1;
+
+  let lastError = null;
+  for (let index = 0; index < maxAttempts; index++) {
+    const candidate = candidates[index];
+    try {
+      if (candidate.provider === "azure") {
+        return await createAzureEphemeralToken(cfg, toolDefinitions, callContext, candidate);
+      }
+      return await createOpenAIEphemeralToken(cfg, toolDefinitions, callContext, candidate);
+    } catch (err) {
+      lastError = err;
+      const canRetry = cfg.failover.enabled && index + 1 < maxAttempts && shouldFailoverRealtimeError(err);
+      if (!canRetry) break;
+    }
+  }
+
+  throw lastError || new Error("Failed to create realtime token");
+}
+
+async function createOpenAIEphemeralToken(cfg, toolDefinitions = [], callContext = {}, candidate = {}) {
+  const credential = String(cfg.openaiOAuthToken || cfg.openaiKey || "").trim();
+  if (!credential) {
+    throw new Error("OpenAI voice credential not configured (OAuth token or API key required)");
+  }
+
+  const context = sanitizeVoiceCallContext(callContext);
+  const instructions = buildSessionScopedInstructions(cfg.instructions, context);
+  const model = String(candidate?.model || cfg.model || OPENAI_REALTIME_MODEL).trim() || OPENAI_REALTIME_MODEL;
+  const voiceId = String(candidate?.voiceId || cfg.voiceId || "alloy").trim() || "alloy";
+
+  const sessionConfig = {
+    model,
+    voice: voiceId,
+    instructions,
+    tool_choice: resolveToolChoice(toolDefinitions, context),
+    turn_detection: {
+      type: cfg.turnDetection,
+      ...(cfg.turnDetection === "server_vad" ? {
+        threshold: 0.5,
+        prefix_padding_ms: 300,
+        silence_duration_ms: 500,
+      } : {}),
+      ...(cfg.turnDetection === "semantic_vad" ? {
+        eagerness: "medium",
+      } : {}),
+    },
+    input_audio_transcription: { model: "gpt-4o-mini-transcribe" },
+    tools: toolDefinitions,
+  };
+
+  const response = await fetch(`${OPENAI_REALTIME_URL}/sessions`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${credential}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(sessionConfig),
+  });
+
+  if (!response.ok) {
+    const errorText = await buildProviderErrorDetails(response, "unknown");
+    throw new Error(`OpenAI Realtime session failed (${response.status}): ${errorText}`);
+  }
+
+  const data = await response.json();
+  return {
+    token: data.client_secret?.value || data.token,
+    expiresAt: data.client_secret?.expires_at || (Date.now() / 1000 + 60),
+    model,
+    voiceId,
+    provider: "openai",
+    sessionConfig,
+    callContext: context,
+  };
+}
+
+/**
+ * Create an ephemeral token for Azure OpenAI Realtime API.
+ */
+async function createAzureEphemeralToken(cfg, toolDefinitions = [], callContext = {}, candidate = {}) {
+  if ((!cfg.azureKey && !cfg.azureOAuthToken) || !cfg.azureEndpoint) {
+    throw new Error("Azure OpenAI Realtime not configured (need endpoint + key)");
+  }
+
+  const context = sanitizeVoiceCallContext(callContext);
+  const instructions = buildSessionScopedInstructions(cfg.instructions, context);
+  const endpoint = cfg.azureEndpoint.replace(/\/+$/, "");
+  const deployment =
+    String(candidate?.azureDeployment || cfg.azureDeployment || "").trim()
+    || "gpt-realtime-1.5";
+  const voiceId = String(candidate?.voiceId || cfg.voiceId || "alloy").trim() || "alloy";
+  const url = `${endpoint}/openai/realtime/sessions?api-version=${AZURE_API_VERSION}&deployment=${deployment}`;
+
+  const headers = {
+    "Content-Type": "application/json",
+  };
+  if (cfg.azureOAuthToken) {
+    headers.Authorization = `Bearer ${cfg.azureOAuthToken}`;
+  } else {
+    headers["api-key"] = cfg.azureKey;
+  }
+
+  const sessionConfig = {
+    model: deployment,
+    voice: voiceId,
+    instructions,
+    tool_choice: resolveToolChoice(toolDefinitions, context),
+    turn_detection: {
+      type: cfg.turnDetection,
+      ...(cfg.turnDetection === "server_vad" ? {
+        threshold: 0.5,
+        prefix_padding_ms: 300,
+        silence_duration_ms: 500,
+      } : {}),
+    },
+    input_audio_transcription: { model: "whisper-1" },
+    tools: toolDefinitions,
+  };
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(sessionConfig),
+  });
+
+  if (!response.ok) {
+    const errorText = await buildProviderErrorDetails(response, "unknown");
+    throw new Error(`Azure Realtime session failed (${response.status}): ${errorText}`);
+  }
+
+  const data = await response.json();
+  return {
+    token: data.client_secret?.value || data.token,
+    expiresAt: data.client_secret?.expires_at || (Date.now() / 1000 + 60),
+    model: deployment,
+    voiceId,
+    provider: "azure",
+    sessionConfig,
+    azureEndpoint: endpoint,
+    azureDeployment: deployment,
+    callContext: context,
+  };
+}
+
+/**
+ * Analyze a camera/screen frame and return a concise summary.
+ * @param {string} frameDataUrl - data URL (image/jpeg|png|webp)
+ * @param {object} options - { source, context, prompt }
+ * @returns {Promise<{ summary: string, provider: string, model: string }>}
+ */
+export async function analyzeVisionFrame(frameDataUrl, options = {}) {
+  const frame = parseImageDataUrl(frameDataUrl);
+  const dataUrl = frame.dataUrl;
+
+  const cfg = getVoiceConfig();
+  const source = String(options?.source || "screen").trim().toLowerCase() || "screen";
+  const callContext = sanitizeVoiceCallContext(options?.context || {});
+  const model =
+    String(
+      options?.model
+      || options?.visionModel
+      || cfg.visionModel
+      || process.env.VOICE_VISION_MODEL
+      || OPENAI_DEFAULT_VISION_MODEL,
+    ).trim();
+  const prompt = String(options?.prompt || "").trim()
+    || "Summarize what is visible in this live frame for a coding assistant. Focus on code, terminal output, errors, UI labels, and actionable context.";
+
+  const contextText = [
+    `Frame source: ${source}.`,
+    `Bound chat session: ${callContext.sessionId || "none"}.`,
+    callContext.executor ? `Preferred executor: ${callContext.executor}.` : "",
+    callContext.mode ? `Preferred mode: ${callContext.mode}.` : "",
+    callContext.model ? `Preferred model override: ${callContext.model}.` : "",
+    "Respond in 1-3 concise sentences. Include likely next action if obvious.",
+  ]
+    .filter(Boolean)
+    .join("\n");
+
+  const preferredProviders = [];
+  const pushProvider = (value) => {
+    const provider = String(value || "").trim().toLowerCase();
+    if (!provider || preferredProviders.includes(provider)) return;
+    preferredProviders.push(provider);
+  };
+  pushProvider(cfg.provider);
+  if (cfg.openaiKey) pushProvider("openai");
+  if (cfg.azureKey && cfg.azureEndpoint) pushProvider("azure");
+  if (cfg.claudeKey) pushProvider("claude");
+  if (cfg.geminiKey) pushProvider("gemini");
+
+  let lastError = null;
+  for (const provider of preferredProviders) {
+    try {
+      if (provider === "openai" && cfg.openaiKey) {
+        return await analyzeVisionWithOpenAI(
+          dataUrl,
+          model,
+          prompt,
+          contextText,
+          cfg,
+        );
+      }
+      if (provider === "azure" && cfg.azureKey && cfg.azureEndpoint) {
+        return await analyzeVisionWithAzure(
+          dataUrl,
+          model,
+          prompt,
+          contextText,
+          cfg,
+        );
+      }
+      if (provider === "claude" && cfg.claudeKey) {
+        return await analyzeVisionWithClaude(
+          frame,
+          model,
+          prompt,
+          contextText,
+          cfg,
+        );
+      }
+      if (provider === "gemini" && cfg.geminiKey) {
+        return await analyzeVisionWithGemini(
+          frame,
+          model,
+          prompt,
+          contextText,
+          cfg,
+        );
+      }
+    } catch (err) {
+      lastError = err;
+    }
+  }
+
+  if (lastError) {
+    throw new Error(`Vision request failed: ${lastError.message}`);
+  }
+
+  throw new Error(
+    "Vision unavailable: configure OPENAI, Azure, Anthropic, or Gemini voice credentials",
+  );
+}
+
+/**
+ * Execute a voice tool call server-side.
+ * Returns { result: string, error?: string }
+ */
+export async function executeVoiceTool(toolName, toolArgs, context = {}) {
+  try {
+    // Import voice-tools lazily to avoid circular deps
+    const { executeToolCall } = await import("./voice-tools.mjs");
+    return await executeToolCall(toolName, toolArgs, context);
+  } catch (err) {
+    console.error(`[voice-relay] tool execution error (${toolName}):`, err.message);
+    return { result: null, error: err.message };
+  }
+}
+
+/**
+ * Get the full tool definitions array for voice sessions.
+ */
+export async function getVoiceToolDefinitions(options = {}) {
+  try {
+    const { getToolDefinitions } = await import("./voice-tools.mjs");
+    const allTools = getToolDefinitions();
+    const delegateOnly = options?.delegateOnly === true;
+    if (!delegateOnly) return allTools;
+    return allTools.filter((tool) => tool?.name === "delegate_to_agent");
+  } catch (err) {
+    console.error("[voice-relay] failed to load voice tool definitions:", err.message);
+    return [];
+  }
+}
+
+/**
+ * Get the WebRTC connection URL for the client.
+ */
+export function getRealtimeConnectionInfo() {
+  const cfg = getVoiceConfig();
+  const candidate = cfg.realtimeCandidates.find((entry) => {
+    if (entry.provider === "openai") return Boolean(cfg.openaiOAuthToken || cfg.openaiKey);
+    if (entry.provider === "azure") return Boolean((cfg.azureOAuthToken || cfg.azureKey) && cfg.azureEndpoint);
+    return false;
+  });
+  if (!candidate) {
+    return {
+      provider: cfg.provider,
+      url: null,
+      model: cfg.model,
+      tier: 2,
+    };
+  }
+
+  if (candidate.provider === "azure") {
+    const endpoint = cfg.azureEndpoint.replace(/\/+$/, "");
+    const deployment =
+      String(candidate?.azureDeployment || cfg.azureDeployment || "").trim()
+      || "gpt-realtime-1.5";
+    return {
+      provider: "azure",
+      url: `${endpoint}/openai/realtime?api-version=${AZURE_API_VERSION}&deployment=${deployment}`,
+      model: deployment,
+    };
+  }
+  const model = String(candidate?.model || cfg.model || OPENAI_REALTIME_MODEL).trim() || OPENAI_REALTIME_MODEL;
+  return {
+    provider: "openai",
+    url: `${OPENAI_REALTIME_URL}?model=${model}`,
+    model,
+  };
+}
+
+// ── Voice action dispatch (direct JavaScript, no MCP bridge) ────────────────
+
+/**
+ * Dispatch a voice action intent through the action dispatcher.
+ * The voice model returns JSON action objects; Bosun processes them
+ * directly via JavaScript and returns structured results.
+ *
+ * @param {Object} intent — { action, params, id? }
+ * @param {Object} context — { sessionId, executor, mode, model }
+ * @returns {Promise<Object>} Structured result
+ */
+export async function dispatchVoiceActionIntent(intent, context = {}) {
+  try {
+    const { dispatchVoiceAction } = await import("./voice-action-dispatcher.mjs");
+    return await dispatchVoiceAction(intent, context);
+  } catch (err) {
+    console.error("[voice-relay] action dispatch error:", err.message);
+    return {
+      ok: false,
+      action: intent?.action || "",
+      data: null,
+      error: err.message,
+      durationMs: 0,
+    };
+  }
+}
+
+/**
+ * Dispatch multiple voice action intents.
+ * @param {Array} intents
+ * @param {Object} context
+ * @returns {Promise<Array>}
+ */
+export async function dispatchVoiceActionIntents(intents, context = {}) {
+  try {
+    const { dispatchVoiceActions } = await import("./voice-action-dispatcher.mjs");
+    return await dispatchVoiceActions(intents, context);
+  } catch (err) {
+    console.error("[voice-relay] batch action dispatch error:", err.message);
+    return [];
+  }
+}
+
+/**
+ * Get the action manifest for voice prompt injection.
+ * @returns {string}
+ */
+export async function getVoiceActionManifest() {
+  try {
+    const { getVoiceActionPromptSection } = await import("./voice-action-dispatcher.mjs");
+    return getVoiceActionPromptSection();
+  } catch (err) {
+    console.error("[voice-relay] action manifest error:", err.message);
+    return "";
+  }
+}
+
+/**
+ * List all available voice actions.
+ * @returns {Promise<string[]>}
+ */
+export async function listVoiceActions() {
+  try {
+    const { listAvailableActions } = await import("./voice-action-dispatcher.mjs");
+    return listAvailableActions();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Build the full voice agent prompt by resolving the voice prompt template
+ * and injecting the action manifest.
+ *
+ * @param {Object} options — { compact?, customInstructions? }
+ * @returns {Promise<string>}
+ */
+export async function buildVoiceAgentPrompt(options = {}) {
+  const cfg = getVoiceConfig();
+  let baseInstructions = cfg.instructions || "";
+
+  // Try to load the customizable voice prompt from the prompt library
+  try {
+    const { resolveAgentPrompts, renderPromptTemplate, getDefaultPromptTemplate } = await import("./agent-prompts.mjs");
+    const promptKey = options.compact ? "voiceAgentCompact" : "voiceAgent";
+
+    // Try workspace prompt first, fall back to default
+    let template = "";
+    try {
+      const resolved = resolveAgentPrompts(null, process.cwd(), {});
+      template = resolved.prompts?.[promptKey] || "";
+    } catch {
+      template = getDefaultPromptTemplate(promptKey) || "";
+    }
+
+    if (template) {
+      const manifest = await getVoiceActionManifest();
+      baseInstructions = renderPromptTemplate(template, {
+        VOICE_ACTION_MANIFEST: manifest,
+      });
+    }
+  } catch {
+    // Fall back to config instructions
+  }
+
+  // Allow custom instructions override
+  if (options.customInstructions) {
+    baseInstructions = String(options.customInstructions);
+  }
+
+  return baseInstructions;
+}
+