neoagent 2.3.1-beta.11 → 2.3.1-beta.111

package/server/services/runtime/manager.js

@@ -1,28 +1,51 @@
-const { HostExecutionBackend } = require('./backends/host');
+'use strict';
+
 const { LocalVmExecutionBackend } = require('./backends/local-vm');
-const { QemuVmManager } = require('./qemu');
-const { deriveCloudBrowserBackend, getRuntimeSettings } = require('./settings');
+const { DockerVMManager } = require('./docker-vm-manager');
+const { getRuntimeSettings } = require('./settings');
 const { ExtensionBrowserProvider } = require('../browser/extension/provider');
+const { AndroidController } = require('../android/controller');
+const { DesktopProvider } = require('../desktop/provider');
+
+// Resource defaults for Docker VMs (overridable via env).
+const DEFAULT_VM_MEMORY_MB = Number(process.env.NEOAGENT_VM_MEMORY_MB ?? 2048);
+const DEFAULT_VM_CPUS = Number(process.env.NEOAGENT_VM_CPUS ?? 2);
 
 class RuntimeManager {
   constructor(options = {}) {
     this.browserExtensionRegistry = options.browserExtensionRegistry || null;
-    this.hostBackend = new HostExecutionBackend({
-      cliExecutor: options.cliExecutor,
-      getBrowserProvider: options.getHostBrowserProvider,
-      getAndroidProvider: options.getHostAndroidProvider,
+    this.desktopCompanionRegistry = options.desktopCompanionRegistry || null;
+
+    const browserVmManager = options.browserVmManager || new DockerVMManager({
+      runtimeProfile: 'browser_cli',
+      image: 'mcr.microsoft.com/playwright:v1.44.0-focal',
+      memoryMb: DEFAULT_VM_MEMORY_MB,
+      cpus: DEFAULT_VM_CPUS,
     });
-    this.vmBackend = new LocalVmExecutionBackend({
-      vmManager: options.vmManager || new QemuVmManager(),
+    this.browserBackend = new LocalVmExecutionBackend({
+      runtimeProfile: 'browser_cli',
+      vmManager: browserVmManager,
       artifactStore: options.artifactStore,
     });
-    this.getExtensionBrowserProvider = options.getExtensionBrowserProvider || ((userId) => new ExtensionBrowserProvider({
-      registry: options.browserExtensionRegistry,
-      artifactStore: options.artifactStore,
-      userId,
-    }));
+
+    this.artifactStore = options.artifactStore || null;
+
+    this.getExtensionBrowserProvider = options.getExtensionBrowserProvider
+      || ((userId) => new ExtensionBrowserProvider({
+        registry: options.browserExtensionRegistry,
+        artifactStore: options.artifactStore,
+        userId,
+      }));
+
+    this.getDesktopCliProvider = options.getDesktopCliProvider
+      || ((userId) => new DesktopProvider({
+        registry: options.desktopCompanionRegistry,
+        artifactStore: options.artifactStore,
+        userId,
+      }));
   }
 
+
   getSettings(userId) {
     return getRuntimeSettings(userId);
   }
@@ -35,40 +58,73 @@ class RuntimeManager {
     );
   }
 
+  hasActiveDesktopCompanion(userId) {
+    return Boolean(
+      this.desktopCompanionRegistry
+      && typeof this.desktopCompanionRegistry.isConnected === 'function'
+      && this.desktopCompanionRegistry.isConnected(userId)
+    );
+  }
+
   resolveBackend(userId, requested) {
-    const settings = this.getSettings(userId);
-    const effective = requested || settings.runtime_backend;
-    if (effective === 'vm') return this.vmBackend;
-    return this.hostBackend;
+    void userId;
+    void requested;
+    return this.browserBackend;
   }
 
   async executeCommand(userId, command, options = {}) {
-    const backend = this.resolveBackend(userId, options.backend);
+    const backend = this.resolveBackend(userId, 'browser_cli');
     return backend.executeCommand(userId, command, options);
   }
 
+  hasVmForUser(userId, capability = 'browser') {
+    return Boolean(this.browserBackend?.vmManager?.hasVm?.(userId));
+  }
+
+  async killCommand(userId, pid, reason = 'aborted') {
+    return this.browserBackend.killCommand(userId, pid, reason);
+  }
+
+  async getCommandExecutorForUser(userId) {
+    return this.browserBackend.getCommandExecutorForUser(userId);
+  }
+
   async getBrowserProviderForUser(userId) {
     const settings = this.getSettings(userId);
     if (settings.browser_backend === 'extension' && this.hasActiveExtensionBrowser(userId)) {
       return this.getExtensionBrowserProvider(userId);
     }
-    const browserBackend = settings.browser_backend === 'extension'
-      ? deriveCloudBrowserBackend(settings)
-      : settings.browser_backend;
-    const backend = this.resolveBackend(userId, browserBackend === 'host' ? 'host' : browserBackend);
-    return backend.getBrowserProviderForUser(userId);
+    return this.browserBackend.getBrowserProviderForUser(userId);
   }
 
-  async getAndroidProviderForUser(userId) {
+  async getCliProviderForUser(userId) {
     const settings = this.getSettings(userId);
-    const backend = this.resolveBackend(userId, settings.android_backend);
-    return backend.getAndroidProviderForUser(userId);
+    if (settings.cli_backend === 'desktop' && this.hasActiveDesktopCompanion(userId)) {
+      return this.getDesktopCliProvider(userId);
+    }
+    return this.browserBackend.getCommandExecutorForUser(userId);
+  }
+
+  async getAndroidProviderForUser(userId) {
+    if (userId == null || String(userId).trim() === '') {
+      throw new Error('Android provider requires a user ID.');
+    }
+    return new AndroidController({
+      userId: String(userId).trim(),
+      artifactStore: this.artifactStore,
+    });
+  }
+
+  async isGuestAgentReadyForUser(userId, timeoutMs = 1000, capability = 'browser') {
+    if (typeof this.browserBackend?.isGuestAgentReadyForUser !== 'function') {
+      return false;
+    }
+    return this.browserBackend.isGuestAgentReadyForUser(userId, timeoutMs);
   }
 
   async shutdown() {
     await Promise.allSettled([
-      this.hostBackend.shutdown(),
-      this.vmBackend.shutdown(),
+      this.browserBackend?.shutdown?.(),
     ]);
   }
 }

package/server/services/runtime/settings.js

@@ -9,6 +9,7 @@ function createDefaultRuntimeSettings() {
     browser_backend: policy.runtimeDefaults.browser_backend,
     android_backend: policy.runtimeDefaults.android_backend,
     mcp_backend: policy.runtimeDefaults.mcp_backend,
+    cli_backend: policy.runtimeDefaults.cli_backend ?? 'vm',
   };
 }
 
@@ -19,11 +20,12 @@ function getEffectiveDefaults() {
 }
 
 const BASE_FALLBACK_SETTINGS = Object.freeze({
-  runtime_profile: 'trusted-host',
-  runtime_backend: 'host',
-  browser_backend: 'host',
+  runtime_profile: 'secure-vm',
+  runtime_backend: 'vm',
+  browser_backend: 'vm',
   android_backend: 'host',
   mcp_backend: 'host-remote',
+  cli_backend: 'vm',
 });
 
 const RUNTIME_SETTING_KEYS = Object.freeze(Object.keys(DEFAULT_RUNTIME_SETTINGS));
@@ -36,17 +38,13 @@ function normalizeChoice(value, allowed, fallback) {
 function deriveDefaultsForProfile(profile) {
   switch (profile) {
     case 'secure-vm':
-      return {
-        runtime_backend: 'vm',
-        browser_backend: 'vm',
-        android_backend: 'vm',
-      };
     case 'trusted-host':
     default:
       return {
-        runtime_backend: 'host',
-        browser_backend: 'host',
+        runtime_backend: 'vm',
+        browser_backend: 'vm',
         android_backend: 'host',
+        cli_backend: 'vm',
       };
   }
 }
@@ -56,29 +54,20 @@ function normalizeRuntimeSettings(raw = {}) {
   const defaults = getEffectiveDefaults();
   const profile = normalizeChoice(raw.runtime_profile, ['secure-vm', 'trusted-host'], defaults.runtime_profile);
   const derived = deriveDefaultsForProfile(profile);
-  const runtimeBackend = normalizeChoice(raw.runtime_backend, ['host', 'vm'], derived.runtime_backend);
-  const browserBackend = normalizeChoice(raw.browser_backend, ['host', 'vm', 'extension'], derived.browser_backend);
-  const androidBackend = normalizeChoice(raw.android_backend, ['host', 'vm'], derived.android_backend);
+  const runtimeBackend = normalizeChoice(raw.runtime_backend, ['vm'], derived.runtime_backend);
+  const browserBackend = normalizeChoice(raw.browser_backend, ['vm', 'extension'], derived.browser_backend);
+  const cliBackend = normalizeChoice(raw.cli_backend, ['vm', 'desktop'], derived.cli_backend ?? 'vm');
+  const androidBackend = 'host';
   return {
-    runtime_profile: profile,
-    runtime_backend: policy.allowHostRuntime ? runtimeBackend : (runtimeBackend === 'host' ? 'vm' : runtimeBackend),
-    browser_backend: policy.allowHostRuntime ? browserBackend : (browserBackend === 'host' ? 'vm' : browserBackend),
-    android_backend: policy.allowHostRuntime ? androidBackend : (androidBackend === 'host' ? 'vm' : androidBackend),
+    runtime_profile: profile === 'trusted-host' ? 'secure-vm' : profile,
+    runtime_backend: runtimeBackend,
+    browser_backend: browserBackend === 'extension' ? 'extension' : 'vm',
+    android_backend: androidBackend,
     mcp_backend: 'host-remote',
+    cli_backend: cliBackend === 'desktop' ? 'desktop' : 'vm',
   };
 }
 
-function deriveCloudBrowserBackend(raw = {}) {
-  const settings = normalizeRuntimeSettings(raw);
-  if (settings.browser_backend === 'host' || settings.browser_backend === 'vm') {
-    return settings.browser_backend;
-  }
-  if (settings.runtime_profile === 'secure-vm' || settings.runtime_backend === 'vm') {
-    return 'vm';
-  }
-  return 'host';
-}
-
 function parseStoredRuntimeValue(key, value) {
   if (typeof value !== 'string') {
     return value;
@@ -113,8 +102,11 @@ function validateRuntimeSettings(raw = {}) {
     if (settings.browser_backend !== 'vm' && settings.browser_backend !== 'extension') {
       issues.push('This deployment requires the VM browser backend or a paired browser extension backend.');
     }
-    if (settings.android_backend !== 'vm') {
-      issues.push('This deployment requires the VM Android backend.');
+    if (settings.android_backend !== 'host' && settings.android_backend !== 'vm') {
+      issues.push('This deployment requires a supported Android backend.');
+    }
+    if (settings.cli_backend !== 'vm' && settings.cli_backend !== 'desktop') {
+      issues.push('This deployment requires a supported CLI backend.');
     }
   }
 
@@ -165,7 +157,6 @@ function getRuntimeSettings(userId) {
 module.exports = {
   DEFAULT_RUNTIME_SETTINGS,
   RUNTIME_SETTING_KEYS,
-  deriveCloudBrowserBackend,
   ensureDefaultRuntimeSettings,
   getRuntimeSettings,
   normalizeRuntimeSettings,

package/server/services/runtime/validation.js

@@ -2,48 +2,34 @@
 
 const { getDeploymentPolicy } = require('../../utils/deployment');
 
-function validateGuestToken(token) {
-  const value = String(token || '').trim();
-  if (!value) {
-    return { valid: false, reason: 'NEOAGENT_VM_GUEST_TOKEN is missing.' };
-  }
-  if (value.length < 32) {
-    return { valid: false, reason: 'NEOAGENT_VM_GUEST_TOKEN must be at least 32 characters long.' };
-  }
-  if (/^(change|replace|set|your|example|sample|placeholder|token|secret)[-_a-z0-9]*$/i.test(value)) {
-    return { valid: false, reason: 'NEOAGENT_VM_GUEST_TOKEN looks like a placeholder value.' };
-  }
-  if (/change-this-guest-token-before-prod/i.test(value)) {
-    return { valid: false, reason: 'NEOAGENT_VM_GUEST_TOKEN is using the insecure example placeholder.' };
-  }
-  if (/^(.)\1+$/.test(value)) {
-    return { valid: false, reason: 'NEOAGENT_VM_GUEST_TOKEN must not be a repeated single character.' };
-  }
-  return { valid: true, reason: null };
-}
-
 function getRuntimeValidation(runtimeManager) {
   const policy = getDeploymentPolicy();
   const nodeEnvIsProd = String(process.env.NODE_ENV || '').trim().toLowerCase() === 'prod';
-  const vmReadiness = runtimeManager?.vmBackend?.vmManager?.getReadiness?.() || null;
-  const guestToken = String(runtimeManager?.vmBackend?.token || process.env.NEOAGENT_VM_GUEST_TOKEN || '').trim();
-  const guestTokenValidation = validateGuestToken(guestToken);
+  const browserVmReadiness = runtimeManager?.browserBackend?.vmManager?.getReadiness?.() || null;
+  const vmReadiness = browserVmReadiness || null;
   const issues = [];
 
   if (policy.profile === 'prod' || nodeEnvIsProd) {
-    if (!vmReadiness?.ready) {
-      issues.push('prod profile requires a configured local VM runtime (QEMU + base image).');
-    }
-    if (!guestTokenValidation.valid) {
-      issues.push(`prod profile requires a secure NEOAGENT_VM_GUEST_TOKEN. ${guestTokenValidation.reason}`);
+    if (!browserVmReadiness) {
+      issues.push('prod profile requires a working local VM runtime for browser/CLI.');
+    } else if (!browserVmReadiness.ready) {
+      if (!browserVmReadiness.qemuAvailable) {
+        issues.push(`prod profile requires QEMU (${browserVmReadiness.qemuBinary}) to be installed for browser/CLI.`);
+      }
+      if (!browserVmReadiness.baseImageExists && !browserVmReadiness.downloadConfigured) {
+        issues.push('prod profile requires a VM base image or a downloadable base image URL for browser/CLI.');
+      }
     }
   }
 
   return {
     ready: issues.length === 0,
     issues,
-    vm: vmReadiness,
-    guestTokenConfigured: guestTokenValidation.valid,
+    vm: {
+      browser: vmReadiness,
+      android: null,
+    },
+    guestTokenConfigured: true,
     policy,
   };
 }
@@ -59,5 +45,4 @@ function assertRuntimeValidation(runtimeManager) {
 module.exports = {
   assertRuntimeValidation,
   getRuntimeValidation,
-  validateGuestToken,
 };

package/server/services/social_video/adapters/base.js

@@ -0,0 +1,26 @@
+'use strict';
+
+class SocialVideoAdapter {
+  constructor(options = {}) {
+    this.platform = String(options.platform || 'unknown');
+    this.hosts = Array.isArray(options.hosts)
+      ? options.hosts.map((host) => String(host || '').toLowerCase()).filter(Boolean)
+      : [];
+    this.captionLanguages = Array.isArray(options.captionLanguages)
+      ? options.captionLanguages.map((value) => String(value || '').toLowerCase()).filter(Boolean)
+      : ['en', 'en-us'];
+  }
+
+  supportsHost(hostname) {
+    const host = String(hostname || '').toLowerCase();
+    return this.hosts.some((candidate) => host === candidate || host.endsWith(`.${candidate}`));
+  }
+
+  getCaptionLanguagePreferences() {
+    return [...this.captionLanguages];
+  }
+}
+
+module.exports = {
+  SocialVideoAdapter,
+};

package/server/services/social_video/adapters/index.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const { YouTubeAdapter } = require('./youtube');
+const { TikTokAdapter } = require('./tiktok');
+const { InstagramAdapter } = require('./instagram');
+const { XAdapter } = require('./x');
+
+const ADAPTERS = [
+  new YouTubeAdapter(),
+  new TikTokAdapter(),
+  new InstagramAdapter(),
+  new XAdapter(),
+];
+
+function getAdapterForPlatform(platform) {
+  const normalized = String(platform || '').trim().toLowerCase();
+  return ADAPTERS.find((adapter) => adapter.platform === normalized) || null;
+}
+
+function getSupportedAdapters() {
+  return [...ADAPTERS];
+}
+
+module.exports = {
+  getAdapterForPlatform,
+  getSupportedAdapters,
+};

package/server/services/social_video/adapters/instagram.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const { SocialVideoAdapter } = require('./base');
+
+class InstagramAdapter extends SocialVideoAdapter {
+  constructor() {
+    super({
+      platform: 'instagram',
+      hosts: ['instagram.com', 'www.instagram.com', 'm.instagram.com', 'instagr.am'],
+      captionLanguages: ['en', 'en-us'],
+    });
+  }
+}
+
+module.exports = {
+  InstagramAdapter,
+};

package/server/services/social_video/adapters/tiktok.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const { SocialVideoAdapter } = require('./base');
+
+class TikTokAdapter extends SocialVideoAdapter {
+  constructor() {
+    super({
+      platform: 'tiktok',
+      hosts: ['tiktok.com', 'www.tiktok.com', 'm.tiktok.com', 'vm.tiktok.com', 'vt.tiktok.com'],
+      captionLanguages: ['en', 'en-us'],
+    });
+  }
+}
+
+module.exports = {
+  TikTokAdapter,
+};

package/server/services/social_video/adapters/x.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const { SocialVideoAdapter } = require('./base');
+
+class XAdapter extends SocialVideoAdapter {
+  constructor() {
+    super({
+      platform: 'x',
+      hosts: ['x.com', 'twitter.com'],
+      captionLanguages: ['en', 'en-us'],
+    });
+  }
+}
+
+module.exports = {
+  XAdapter,
+};

package/server/services/social_video/adapters/youtube.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const { SocialVideoAdapter } = require('./base');
+
+class YouTubeAdapter extends SocialVideoAdapter {
+  constructor() {
+    super({
+      platform: 'youtube',
+      hosts: ['youtube.com', 'www.youtube.com', 'youtu.be'],
+      captionLanguages: ['en', 'en-us', 'en-gb'],
+    });
+  }
+}
+
+module.exports = {
+  YouTubeAdapter,
+};

package/server/services/social_video/captions.js

@@ -0,0 +1,187 @@
+'use strict';
+
+const MAX_VTT_BYTES = 2 * 1024 * 1024;
+const MAX_INPUT_BYTES = MAX_VTT_BYTES;
+
+function normalizeLanguageCode(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+function pickCaptionTrack(captionGroups = {}, preferredLanguages = []) {
+  const tracks = [];
+  for (const [language, items] of Object.entries(captionGroups || {})) {
+    if (!Array.isArray(items)) continue;
+    for (const item of items) {
+      if (!item || typeof item !== 'object') continue;
+      const url = String(item.url || '').trim();
+      if (!url) continue;
+      tracks.push({
+        language: normalizeLanguageCode(language),
+        url,
+        ext: normalizeLanguageCode(item.ext || ''),
+        name: String(item.name || '').trim(),
+      });
+    }
+  }
+  if (tracks.length === 0) return null;
+
+  const preferred = preferredLanguages.map(normalizeLanguageCode).filter(Boolean);
+  const preferredOrder = preferred.length > 0 ? preferred : ['en', 'en-us', 'en-gb'];
+  const preferredExt = ['vtt', 'webvtt', 'srt', 'json3'];
+
+  const scoreTrack = (track) => {
+    const langIdx = preferredOrder.findIndex((code) => track.language === code || track.language.startsWith(`${code}-`));
+    const langScore = langIdx === -1 ? 999 : langIdx;
+    const extIdx = preferredExt.findIndex((ext) => track.ext === ext);
+    const extScore = extIdx === -1 ? 999 : extIdx;
+    return (langScore * 100) + extScore;
+  };
+
+  return tracks
+    .map((track) => ({ track, score: scoreTrack(track) }))
+    .sort((left, right) => left.score - right.score)[0]?.track || null;
+}
+
+function stripTags(text) {
+  return String(text || '')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/\{\\an\d+\}/g, ' ')
+    .replace(/\[[^\]]+\]/g, ' ')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function inputByteLength(value) {
+  if (Buffer.isBuffer(value)) return value.byteLength;
+  return Buffer.byteLength(String(value || ''), 'utf8');
+}
+
+function stripXml(value) {
+  return String(value || '')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&amp;/gi, '&')
+    .replace(/&lt;/gi, '<')
+    .replace(/&gt;/gi, '>')
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function parseWebVttToText(vtt) {
+  if (inputByteLength(vtt) > MAX_VTT_BYTES) {
+    throw new Error(`parseWebVttToText input exceeds MAX_VTT_BYTES (${MAX_VTT_BYTES}).`);
+  }
+  const lines = String(vtt || '').split(/\r?\n/);
+  const chunks = [];
+  for (const line of lines) {
+    const clean = line.trim();
+    if (!clean) continue;
+    if (/^WEBVTT/i.test(clean)) continue;
+    if (/^NOTE\b/i.test(clean)) continue;
+    if (/^\d+$/.test(clean)) continue;
+    if (/^\d{2}:\d{2}:\d{2}[.,]\d{3}\s+-->/.test(clean) || /^\d{2}:\d{2}[.,]\d{3}\s+-->/.test(clean)) continue;
+    const normalized = stripTags(clean);
+    if (!normalized) continue;
+    if (chunks[chunks.length - 1] === normalized) continue;
+    chunks.push(normalized);
+  }
+  return chunks.join(' ').trim();
+}
+
+function parseSrtToText(srt) {
+  return parseWebVttToText(String(srt || '').replace(/,/g, '.'));
+}
+
+function parseJson3ToText(raw) {
+  if (inputByteLength(raw) > MAX_INPUT_BYTES) {
+    return '';
+  }
+  let payload;
+  try {
+    payload = JSON.parse(String(raw || ''));
+  } catch {
+    return '';
+  }
+  const events = Array.isArray(payload?.events) ? payload.events : [];
+  const parts = [];
+  for (const event of events) {
+    const segs = Array.isArray(event?.segs) ? event.segs : [];
+    const text = segs
+      .map((segment) => String(segment?.utf8 || '').trim())
+      .filter(Boolean)
+      .join(' ');
+    const normalized = stripTags(text);
+    if (!normalized) continue;
+    if (parts[parts.length - 1] === normalized) continue;
+    parts.push(normalized);
+  }
+  return parts.join(' ').trim();
+}
+
+function parseTtmlToText(raw) {
+  if (inputByteLength(raw) > MAX_INPUT_BYTES) {
+    return '';
+  }
+  const text = String(raw || '');
+  const parts = [];
+  const paragraphRe = /<p\b[^>]*>([\s\S]*?)<\/p>/gi;
+  let match = paragraphRe.exec(text);
+  while (match) {
+    const parsed = stripXml(match[1]);
+    if (parsed && parts[parts.length - 1] !== parsed) {
+      parts.push(parsed);
+    }
+    match = paragraphRe.exec(text);
+  }
+  if (parts.length > 0) {
+    return parts.join(' ').trim();
+  }
+  return stripXml(text);
+}
+
+function parseCaptionText(raw, extension = '') {
+  const ext = normalizeLanguageCode(extension);
+  if (ext === 'vtt' || ext === 'webvtt') {
+    return parseWebVttToText(raw);
+  }
+  if (ext === 'ttml') {
+    return parseTtmlToText(raw);
+  }
+  if (ext === 'srt') {
+    return parseSrtToText(raw);
+  }
+  if (ext === 'json3' || ext === 'json') {
+    return parseJson3ToText(raw);
+  }
+  if (/^\s*<tt\b/i.test(String(raw || '')) || /xmlns\s*=\s*["'][^"']*ttml/i.test(String(raw || ''))) {
+    return parseTtmlToText(raw);
+  }
+  return parseWebVttToText(raw);
+}
+
+function decideTranscriptPath(options = {}) {
+  if (options.forceStt) {
+    return { mode: 'stt', reason: 'forced' };
+  }
+  if (options.captionTrack) {
+    return { mode: 'captions', reason: 'captions_present' };
+  }
+  return { mode: 'stt', reason: 'captions_missing' };
+}
+
+module.exports = {
+  decideTranscriptPath,
+  normalizeLanguageCode,
+  parseCaptionText,
+  parseJson3ToText,
+  parseSrtToText,
+  parseTtmlToText,
+  parseWebVttToText,
+  pickCaptionTrack,
+  MAX_INPUT_BYTES,
+  MAX_VTT_BYTES,
+};