kiku-agent 1.3.1 → 1.3.3

package/server/agent/audioPlayer.js

@@ -1,7 +1,10 @@
 import { spawn } from 'child_process';
-import { existsSync, unlinkSync, readdirSync, statSync } from 'node:fs';
+import { killProcessTreeSync } from './processManager.js';
+import { existsSync, unlinkSync, readdirSync, statSync, rmSync } from 'node:fs';
 import { join, dirname, basename } from 'node:path';
 import { ensureYouTubeCookies, getCookieStatus, isCookieFileValid } from './youtubeAuth.js';
+import { discographyData } from '../../src/data/discographyData.js';
+import { musicVideoData } from '../../src/data/musicVideoData.js';
 
 let _ffmpeg = null;
 async function loadFfmpeg() {
@@ -98,9 +101,23 @@ function ytDlpTry(query, opts) {
     let errBuf = '';
     proc.stdout.once('data', () => { gotData = true; resolve(proc); });
     proc.stderr.on('data', d => { errBuf += d.toString(); });
-    proc.on('error', e => { if (!gotData) { try { proc.kill('SIGKILL'); } catch {} reject(e); } });
+    proc.on('error', e => {
+      if (!gotData) {
+        try {
+          if (proc.pid) killProcessTreeSync(proc.pid);
+          proc.kill('SIGKILL');
+        } catch {}
+        reject(e);
+      }
+    });
     proc.on('close', code => {
-      if (!gotData) { try { proc.kill('SIGKILL'); } catch {} reject(new Error(errBuf.trim() || `yt-dlp exited with code ${code}`)); }
+      if (!gotData) {
+        try {
+          if (proc.pid) killProcessTreeSync(proc.pid);
+          proc.kill('SIGKILL');
+        } catch {}
+        reject(new Error(errBuf.trim() || `yt-dlp exited with code ${code}`));
+      }
     });
   });
 }
@@ -257,6 +274,9 @@ class AudioPlayer {
     this.isPlaying = false;
     this.isPaused = false;
     this.isMuted = false;
+    this.volume = 100;
+    this.repeatMode = 'off';
+    this.isShuffle = false;
     this.queue = [];
     this.currentIndex = -1;
     this._advancing = false;
@@ -274,11 +294,18 @@ class AudioPlayer {
       this.speaker = null;
     }
     if (this._ytDlpProc) {
-      try { this._ytDlpProc.kill('SIGKILL'); } catch {}
+      try {
+        if (this._ytDlpProc.pid) killProcessTreeSync(this._ytDlpProc.pid);
+        this._ytDlpProc.kill('SIGKILL');
+      } catch {}
       this._ytDlpProc = null;
     }
     if (this.ffmpegProcess) {
-      try { this.ffmpegProcess.kill('SIGKILL'); } catch {}
+      try {
+        const fPid = this.ffmpegProcess.pid || this.ffmpegProcess.ffmpegProc?.pid;
+        if (fPid) killProcessTreeSync(fPid);
+        this.ffmpegProcess.kill('SIGKILL');
+      } catch {}
       this.ffmpegProcess = null;
     }
     if (this.ytdlStream) {
@@ -300,6 +327,11 @@ class AudioPlayer {
           try { unlinkSync(join(dir, entry)); } catch {}
         }
       }
+      try {
+        if (basename(dir).startsWith('kiku-audio-')) {
+          rmSync(dir, { recursive: true, force: true });
+        }
+      } catch {}
     } catch {}
     this._tempFile = null;
   }
@@ -347,6 +379,11 @@ class AudioPlayer {
 
           if (!downloaded) {
             console.error('  [WARNING] yt-dlp could not download a playable audio source.');
+            try {
+              if (basename(tmpDir).startsWith('kiku-audio-')) {
+                rmSync(tmpDir, { recursive: true, force: true });
+              }
+            } catch {}
             tempFile = null;
           }
         } catch (err) {
@@ -376,7 +413,8 @@ class AudioPlayer {
 
         this.speaker = speaker;
 
-        const volumeFilter = this.isMuted ? 'volume=0' : 'volume=1';
+        const volFactor = (Math.max(0, Math.min(100, Number(this.volume) || 0)) / 100).toFixed(2);
+        const volumeFilter = this.isMuted ? 'volume=0' : `volume=${volFactor}`;
 
         const ffmpeg = await loadFfmpeg();
         let ff = ffmpeg(tempFile);
@@ -415,7 +453,11 @@ class AudioPlayer {
         this.isPaused = false;
         resolve();
       } catch (err) {
+        if (!this._tempFile && tempFile) {
+          this._tempFile = tempFile;
+        }
         this._cleanup();
+        this._cleanupTempFile();
         this.isPlaying = false;
         this.isPaused = false;
         this._advancing = false;
@@ -466,13 +508,29 @@ class AudioPlayer {
   }
 
   next() {
+    if (this.isShuffle && this.queue.length > 1) {
+      let rand = Math.floor(Math.random() * this.queue.length);
+      if (rand === this.currentIndex) rand = (rand + 1) % this.queue.length;
+      this._cleanup();
+      this.currentIndex = rand;
+      this.currentTrack = this.queue[this.currentIndex];
+      this._playPromise = this._createStream(this.currentTrack).catch(() => {});
+      return `Playing next track [${this.currentIndex + 1}/${this.queue.length}]: ${this.currentTrack}`;
+    }
     if (this.currentIndex < this.queue.length - 1) {
       this._cleanup();
       this.currentIndex++;
       this.currentTrack = this.queue[this.currentIndex];
-      this._playPromise = this._createStream(this.currentTrack);
+      this._playPromise = this._createStream(this.currentTrack).catch(() => {});
       return `Playing next track [${this.currentIndex + 1}/${this.queue.length}]: ${this.currentTrack}`;
     }
+    if (this.repeatMode === 'all' && this.queue.length > 0) {
+      this._cleanup();
+      this.currentIndex = 0;
+      this.currentTrack = this.queue[0];
+      this._playPromise = this._createStream(this.currentTrack).catch(() => {});
+      return `Playing next track [1/${this.queue.length}]: ${this.currentTrack}`;
+    }
     return 'No next track in queue';
   }
 
@@ -481,7 +539,14 @@ class AudioPlayer {
       this._cleanup();
       this.currentIndex--;
       this.currentTrack = this.queue[this.currentIndex];
-      this._playPromise = this._createStream(this.currentTrack);
+      this._playPromise = this._createStream(this.currentTrack).catch(() => {});
+      return `Playing previous track [${this.currentIndex + 1}/${this.queue.length}]: ${this.currentTrack}`;
+    }
+    if (this.repeatMode === 'all' && this.queue.length > 0) {
+      this._cleanup();
+      this.currentIndex = this.queue.length - 1;
+      this.currentTrack = this.queue[this.currentIndex];
+      this._playPromise = this._createStream(this.currentTrack).catch(() => {});
       return `Playing previous track [${this.currentIndex + 1}/${this.queue.length}]: ${this.currentTrack}`;
     }
     return 'No previous track in queue';
@@ -555,7 +620,7 @@ class AudioPlayer {
     if (this._tempFile) {
       this._replayFromTemp();
     } else {
-      this._playPromise = this._createStream(this.currentTrack);
+      this._playPromise = this._createStream(this.currentTrack).catch(() => {});
     }
     const pos = formatSeconds(this._currentOffsetSeconds);
     return `Resumed: ${this.currentTrack} (from ${pos})`;
@@ -587,6 +652,49 @@ class AudioPlayer {
     return `Unmuted: ${this.currentTrack}`;
   }
 
+  setVolume(volume) {
+    const v = Math.max(0, Math.min(100, Number(volume) || 0));
+    this.volume = v;
+    if (v > 0 && this.isMuted) this.isMuted = false;
+    if (this._playbackStartedAt > 0 && !this.isPaused) {
+      this._currentOffsetSeconds += (Date.now() - this._playbackStartedAt) / 1000;
+      this._playbackStartedAt = Date.now();
+    }
+    if (this._tempFile && !this.isPaused) {
+      this._replayFromTemp();
+    }
+    return `Volume set to ${v}%`;
+  }
+
+  seek(seconds) {
+    const sec = Math.max(0, Number(seconds) || 0);
+    this._currentOffsetSeconds = sec;
+    this._playbackStartedAt = this.isPaused ? 0 : Date.now();
+    if (this._tempFile && !this.isPaused) {
+      this._replayFromTemp();
+    }
+    return `Seeked to ${formatSeconds(sec)}`;
+  }
+
+  setRepeatMode(mode) {
+    const m = String(mode || '').toLowerCase().trim();
+    if (['one', 'all', 'off'].includes(m)) {
+      this.repeatMode = m;
+    } else if (m === 'repeat_one' || m === 'single') {
+      this.repeatMode = 'one';
+    } else if (m === 'repeat_all' || m === 'loop') {
+      this.repeatMode = 'all';
+    } else {
+      this.repeatMode = this.repeatMode === 'off' ? 'all' : (this.repeatMode === 'all' ? 'one' : 'off');
+    }
+    return `Repeat mode: ${this.repeatMode}`;
+  }
+
+  setShuffleMode(enabled) {
+    this.isShuffle = enabled !== undefined ? Boolean(enabled) : !this.isShuffle;
+    return `Shuffle mode: ${this.isShuffle ? 'on' : 'off'}`;
+  }
+
   _replayFromTemp() {
     this._startTempPlayback().catch((err) => {
       console.error('Replay error:', err.message);
@@ -606,7 +714,11 @@ class AudioPlayer {
       this.speaker = null;
     }
     if (this.ffmpegProcess) {
-      try { this.ffmpegProcess.kill('SIGKILL'); } catch {}
+      try {
+        const fPid = this.ffmpegProcess.pid || this.ffmpegProcess.ffmpegProc?.pid;
+        if (fPid) killProcessTreeSync(fPid);
+        this.ffmpegProcess.kill('SIGKILL');
+      } catch {}
       this.ffmpegProcess = null;
     }
 
@@ -618,7 +730,8 @@ class AudioPlayer {
     });
     this.speaker = speaker;
 
-    const volumeFilter = this.isMuted ? 'volume=0' : 'volume=1';
+    const volFactor = (Math.max(0, Math.min(100, Number(this.volume) || 0)) / 100).toFixed(2);
+    const volumeFilter = this.isMuted ? 'volume=0' : `volume=${volFactor}`;
 
     this._intentionalStop = false;
     const ffmpeg = await loadFfmpeg();
@@ -715,10 +828,20 @@ class AudioPlayer {
   }
 
   getFullState() {
+    let currentPos = this._currentOffsetSeconds;
+    if (!this.isPaused && this._playbackStartedAt > 0) {
+      currentPos += (Date.now() - this._playbackStartedAt) / 1000;
+    }
     return {
       isPlaying: this.isPlaying,
       isPaused: this.isPaused,
+      isMuted: this.isMuted,
+      volume: this.volume,
+      repeatMode: this.repeatMode,
+      isShuffle: this.isShuffle,
       currentTrack: this.currentTrack,
+      currentTime: Math.floor(currentPos),
+      currentTimeFormatted: formatSeconds(currentPos),
       queue: this.queue,
       currentIndex: this.currentIndex,
       queueLength: this.queue.length
@@ -727,15 +850,219 @@ class AudioPlayer {
 
   _autoNext() {
     if (this._advancing) return;
+    const playNext = (track) => {
+      this._createStream(track).catch(() => {});
+    };
+    if (this.repeatMode === 'one' && this.currentTrack) {
+      this._advancing = true;
+      playNext(this.currentTrack);
+      return;
+    }
+    if (this.isShuffle && this.queue.length > 1) {
+      let rand = Math.floor(Math.random() * this.queue.length);
+      if (rand === this.currentIndex) rand = (rand + 1) % this.queue.length;
+      this._advancing = true;
+      this.currentIndex = rand;
+      this.currentTrack = this.queue[this.currentIndex];
+      playNext(this.currentTrack);
+      return;
+    }
     if (this.queue.length > 0 && this.currentIndex < this.queue.length - 1) {
       this._advancing = true;
       this.currentIndex++;
       this.currentTrack = this.queue[this.currentIndex];
-      this._createStream(this.currentTrack);
+      playNext(this.currentTrack);
+    } else if (this.repeatMode === 'all' && this.queue.length > 0) {
+      this._advancing = true;
+      this.currentIndex = 0;
+      this.currentTrack = this.queue[0];
+      playNext(this.currentTrack);
     } else {
       this.currentTrack = null;
     }
   }
 }
 
+export function resolveCatalogSong(query = '') {
+  const q = String(query || '').trim().toLowerCase();
+  if (!q) return null;
+  const isRandom = q === 'random' || q === 'สุ่ม' || q === 'สุ่มเพลง' || q === 'เพลงอะไรก็ได้';
+  if (isRandom) {
+    const list = musicVideoData.filter(m => m.youtubeId);
+    if (list.length > 0) {
+      const picked = list[Math.floor(Math.random() * list.length)];
+      return {
+        id: picked.id,
+        title: picked.titleCn || picked.titleTh || picked.titleEn,
+        titleTh: picked.titleTh || '',
+        titleCn: picked.titleCn || '',
+        titleEn: picked.titleEn || '',
+        youtubeId: picked.youtubeId,
+        duration: picked.duration || '',
+        category: picked.category || 'Single',
+        dramaName: picked.dramaName || ''
+      };
+    }
+  }
+
+  const cleanQ = q
+    .replace(/(?:เพลง|ข้ามเพลง|เล่นเพลง|เปิดเพลง|ฟังเพลง|ost|mv|เพลงประกอบ|ซิงเกิล|โซโล่|จวีจิ้งอี|ju jingyi|kiku)/gi, '')
+    .trim();
+  const searchTerms = [q, cleanQ].filter(Boolean);
+
+  for (const item of musicVideoData) {
+    if (!item.youtubeId) continue;
+    const th = (item.titleTh || '').toLowerCase();
+    const cn = (item.titleCn || '').toLowerCase();
+    const en = (item.titleEn || '').toLowerCase();
+    const py = (item.titlePinyin || '').toLowerCase();
+    const drama = (item.dramaName || '').toLowerCase();
+    const aliases = (item.aliases || []).map(a => String(a).toLowerCase());
+    const keywords = (item.keywords || []).map(k => String(k).toLowerCase());
+    const hit = (term) => (field) => {
+      if (!field) return false;
+      if (field.includes(term)) return true;
+      return field.length >= 2 && term.includes(field);
+    };
+    for (const term of searchTerms) {
+      const matchTerm = hit(term);
+      if (
+        matchTerm(cn) ||
+        matchTerm(th) ||
+        matchTerm(en) ||
+        matchTerm(py) ||
+        matchTerm(drama) ||
+        aliases.some(matchTerm) ||
+        keywords.some(matchTerm)
+      ) {
+        return {
+          id: item.id,
+          title: item.titleCn || item.titleTh || item.titleEn,
+          titleTh: item.titleTh || '',
+          titleCn: item.titleCn || '',
+          titleEn: item.titleEn || '',
+          youtubeId: item.youtubeId,
+          duration: item.duration || '',
+          category: item.category || 'Single',
+          dramaName: item.dramaName || ''
+        };
+      }
+    }
+  }
+
+  if (isRandom || cleanQ === '' || cleanQ === 'เพลง') {
+    const list = musicVideoData.filter(m => m.youtubeId);
+    if (list.length > 0) {
+      const picked = list[Math.floor(Math.random() * list.length)];
+      return {
+        id: picked.id,
+        title: picked.titleCn || picked.titleTh || picked.titleEn,
+        titleTh: picked.titleTh || '',
+        titleCn: picked.titleCn || '',
+        titleEn: picked.titleEn || '',
+        youtubeId: picked.youtubeId,
+        duration: picked.duration || '',
+        category: picked.category || 'Single',
+        dramaName: picked.dramaName || ''
+      };
+    }
+  }
+
+  const discoList = Array.isArray(discographyData)
+    ? discographyData
+    : Object.values(discographyData || {}).filter(Array.isArray).flat();
+
+  for (const song of discoList) {
+    if (!song.youtubeId) continue;
+    const th = (song.titleTh || '').toLowerCase();
+    const cn = (song.titleCn || '').toLowerCase();
+    const en = (song.titleEn || '').toLowerCase();
+    const album = (song.album || song.work || '').toLowerCase();
+    const aliases = (song.aliases || []).map(a => String(a).toLowerCase());
+    const keywords = (song.keywords || []).map(k => String(k).toLowerCase());
+    for (const term of searchTerms) {
+      if (
+        (cn && cn.includes(term)) ||
+        (th && th.includes(term)) ||
+        (en && en.includes(term)) ||
+        (album && album.includes(term)) ||
+        aliases.some(a => a.includes(term)) ||
+        keywords.some(k => k.includes(term))
+      ) {
+        return {
+          id: song.id,
+          title: song.titleCn || song.titleTh || song.titleEn,
+          titleTh: song.titleTh || '',
+          titleCn: song.titleCn || '',
+          titleEn: song.titleEn || '',
+          youtubeId: song.youtubeId,
+          duration: song.trackDuration || song.duration || '',
+          category: song.category || song.type || 'Single',
+          dramaName: song.work || song.album || ''
+        };
+      }
+    }
+  }
+
+  return null;
+}
+
+export function evaluateMusicControlIntent(query = '') {
+  const text = String(query || '').trim().toLowerCase();
+  if (!text) return null;
+
+  const actions = [
+    { action: 'pause', tool: 'pause_music', regex: /(?:หยุดเพลง|พักเพลง|pause|\bhold\b|暂停)/i, weight: 5 },
+    { action: 'resume', tool: 'resume_music', regex: /(?:เล่นต่อ|resume|继续)/i, weight: 5 },
+    { action: 'stop', tool: 'stop_music', regex: /(?:ปิดเพลง|เลิกฟังเพลง|stop\s*music|停止)/i, weight: 5 },
+    { action: 'next', tool: 'next_track', regex: /(?:ข้ามเพลง|เพลงถัดไป|next\s*track|next\s*song|下一首)/i, weight: 5 },
+    { action: 'prev', tool: 'prev_track', regex: /(?:เพลงก่อนหน้า|เพลงที่แล้ว|prev\s*track|previous\s*song|上一首)/i, weight: 5 },
+    { action: 'mute', tool: 'mute_music', regex: /(?:ปิดเสียง|\bmute\b|静音)/i, weight: 5 },
+    { action: 'unmute', tool: 'unmute_music', regex: /(?:เปิดเสียง|\bunmute\b|取消静音)/i, weight: 5 },
+    { action: 'set_volume', tool: 'set_volume', regex: /(?:ปรับเสียง|เพิ่มเสียง|ลดเสียง|\bvolume\b|音量)/i, weight: 4 },
+    { action: 'seek', tool: 'seek_music', regex: /(?:กรอเพลง|วินาทีที่|นาทีที่|\bseek\b|快进)/i, weight: 4 },
+    { action: 'set_repeat', tool: 'set_repeat_mode', regex: /(?:วนซ้ำ|\brepeat\b|\bloop\b|循环)/i, weight: 4 },
+    { action: 'set_shuffle', tool: 'set_shuffle_mode', regex: /(?:สุ่มเพลง|\bshuffle\b|随机)/i, weight: 4 },
+    { action: 'toggle_video', tool: 'toggle_video_mode', regex: /(?:เปิด\s*mv|ดู\s*mv|สลับ\s*mv|toggle_video)/i, weight: 4 },
+    { action: 'play', tool: 'play_music', regex: /(?:เล่นเพลง|เปิดเพลง|ฟังเพลง|play\s*song|放歌|听歌)/i, weight: 3 },
+  ];
+
+  let best = null;
+  let maxScore = 0;
+
+  for (const item of actions) {
+    if (item.regex.test(text)) {
+      if (item.weight > maxScore) {
+        maxScore = item.weight;
+        best = item;
+      }
+    }
+  }
+
+  if (!best) return null;
+
+  const result = { action: best.action, tool: best.tool, score: maxScore };
+
+  if (best.action === 'set_volume') {
+    const volMatch = text.match(/(?:ระดับ|volume|เสียง)?\s*(\d{1,3})\s*%?/);
+    if (volMatch) {
+      result.volume = Math.max(0, Math.min(100, Number(volMatch[1])));
+    }
+  }
+
+  if (best.action === 'seek') {
+    const secMatch = text.match(/(\d{1,4})\s*(?:วินาที|sec|s)/);
+    if (secMatch) {
+      result.seconds = Number(secMatch[1]);
+    } else {
+      const minSecMatch = text.match(/(\d{1,2}):(\d{2})/);
+      if (minSecMatch) {
+        result.seconds = Number(minSecMatch[1]) * 60 + Number(minSecMatch[2]);
+      }
+    }
+  }
+
+  return result;
+}
+
 export const audioPlayer = new AudioPlayer();

package/server/agent/autoContext.js

@@ -0,0 +1,193 @@
+import { computeVramEstimate } from './vramService.js';
+
+export const MODEL_FOLLOW_CTX_CEILING = 131072;
+export const MODEL_FOLLOW_CTX_FLOOR = 4096;
+export const MODEL_FOLLOW_CTX_FALLBACK = 32768;
+export const MODEL_FOLLOW_CTX_LADDER = Object.freeze([131072, 65536, 32768, 16384, 8192, 4096]);
+
+const FIT_ZONES = new Set(['GREEN', 'YELLOW']);
+
+function toPositiveInt(value) {
+  const n = Math.floor(Number(value));
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+export function parseAutoContextFlag(value, defaultValue = false) {
+  if (value === undefined || value === null || value === '') return defaultValue;
+  if (typeof value === 'boolean') return value;
+  const text = String(value).trim().toLowerCase();
+  if (['true', '1', 'yes', 'on', 'auto'].includes(text)) return true;
+  if (['false', '0', 'no', 'off'].includes(text)) return false;
+  return defaultValue;
+}
+
+export function resolveModelFollowContext({
+  modelMaxContext = null,
+  loadedContext = null,
+  ceiling = MODEL_FOLLOW_CTX_CEILING,
+  floor = MODEL_FOLLOW_CTX_FLOOR,
+  fallback = MODEL_FOLLOW_CTX_FALLBACK,
+} = {}) {
+  const max = toPositiveInt(modelMaxContext);
+  const loaded = toPositiveInt(loadedContext);
+  const hi = Math.min(toPositiveInt(ceiling) || MODEL_FOLLOW_CTX_CEILING, MODEL_FOLLOW_CTX_CEILING);
+  const lo = Math.max(toPositiveInt(floor) || MODEL_FOLLOW_CTX_FLOOR, 1024);
+  const base = toPositiveInt(fallback) || MODEL_FOLLOW_CTX_FALLBACK;
+
+  const usable = Math.min(max ?? loaded ?? base, hi);
+  const target = Math.max(usable, lo);
+  return {
+    target,
+    modelMax: max,
+    loaded,
+    ceiling: hi,
+    floor: lo,
+    cappedByCeiling: (max ?? loaded ?? base) > hi,
+    raisedToFloor: usable < lo,
+    source: max ? 'model-max' : (loaded ? 'loaded-context' : 'fallback'),
+  };
+}
+
+function ladderCandidates(modelMax, ceiling, floor) {
+  const hi = Math.min(
+    toPositiveInt(modelMax) || MODEL_FOLLOW_CTX_FALLBACK,
+    toPositiveInt(ceiling) || MODEL_FOLLOW_CTX_CEILING,
+    MODEL_FOLLOW_CTX_CEILING,
+  );
+  const lo = Math.max(toPositiveInt(floor) || MODEL_FOLLOW_CTX_FLOOR, 1024);
+  const picks = MODEL_FOLLOW_CTX_LADDER.filter(ctx => ctx <= hi && ctx >= lo);
+  if (picks.length === 0) picks.push(Math.max(lo, Math.min(hi, MODEL_FOLLOW_CTX_FALLBACK)));
+  return { picks, hi, lo };
+}
+
+export async function pickFittingLoadContext({
+  model,
+  quant = null,
+  modelMax = null,
+  ceiling = MODEL_FOLLOW_CTX_CEILING,
+  floor = MODEL_FOLLOW_CTX_FLOOR,
+  estimateFn = computeVramEstimate,
+} = {}) {
+  const { picks, hi, lo } = ladderCandidates(modelMax, ceiling, floor);
+  let firstChecked = null;
+  for (const ctx of picks) {
+    let zone = null;
+    try {
+      const est = await estimateFn({ model, quant, contextLength: ctx, includeHardware: true });
+      zone = est?.classification?.zone || est?.predictiveClassification?.zone || null;
+    } catch {
+      zone = null;
+    }
+    if (!firstChecked) firstChecked = { ctx, zone };
+    if (zone && FIT_ZONES.has(String(zone).toUpperCase())) {
+      return { ctx, zone, cappedByCeiling: hi < (toPositiveInt(modelMax) || hi), modelMax: toPositiveInt(modelMax), vramGuarded: true };
+    }
+    if (!zone || String(zone).toUpperCase() === 'UNKNOWN') {
+      if (ctx <= MODEL_FOLLOW_CTX_FALLBACK) {
+        return { ctx, zone: zone || 'UNKNOWN', cappedByCeiling: false, modelMax: toPositiveInt(modelMax), vramGuarded: false };
+      }
+    }
+  }
+  const floorCtx = picks[picks.length - 1] ?? lo;
+  return { ctx: floorCtx, zone: firstChecked?.zone || 'UNKNOWN', cappedByCeiling: false, modelMax: toPositiveInt(modelMax), vramGuarded: false };
+}
+
+function sameModel(a, b) {
+  if (!a || !b) return false;
+  const norm = (v) => String(v).trim().toLowerCase();
+  return norm(a) === norm(b) || norm(a).includes(norm(b)) || norm(b).includes(norm(a));
+}
+
+export async function ensureModelContextFollow({
+  model,
+  quant = null,
+  requestedContext = null,
+  ceiling = MODEL_FOLLOW_CTX_CEILING,
+  floor = MODEL_FOLLOW_CTX_FLOOR,
+  probeFn,
+  loadFn,
+  unloadFn = null,
+  estimateFn = computeVramEstimate,
+} = {}) {
+  if (typeof probeFn !== 'function' || typeof loadFn !== 'function') {
+    throw new Error('ensureModelContextFollow requires probeFn and loadFn');
+  }
+  const requested = toPositiveInt(requestedContext);
+
+  const probeCurrent = async () => {
+    try {
+      return await probeFn();
+    } catch {
+      return null;
+    }
+  };
+
+  let probe = await probeCurrent();
+  let probeMatches = Boolean(probe?.reachable && sameModel(probe?.loadedModel, model));
+  let modelMax = probeMatches ? toPositiveInt(probe?.modelMaxContextLength) : null;
+  let loaded = probeMatches ? toPositiveInt(probe?.loadedContextLength) : null;
+
+  let performedLoad = false;
+  if (!probeMatches) {
+    const loadRes = await loadFn({ contextLength: requested });
+    performedLoad = true;
+    if (!loadRes?.ok && !loadRes?.modelLoaded && !loadRes?.alreadyRunning) {
+      return { ok: false, reason: loadRes?.reason || 'Model load failed', performedLoad, reloadedForFollow: false };
+    }
+    probe = await probeCurrent();
+    probeMatches = Boolean(probe?.reachable && sameModel(probe?.loadedModel, model));
+    modelMax = probeMatches ? toPositiveInt(probe?.modelMaxContextLength) : modelMax;
+    loaded = probeMatches ? toPositiveInt(probe?.loadedContextLength) : loaded;
+  }
+
+  if (!modelMax && !loaded) {
+    const follow = resolveModelFollowContext({ loadedContext: requested, ceiling, floor });
+    return {
+      ok: true,
+      performedLoad,
+      reloadedForFollow: false,
+      loadedContextLength: loaded,
+      modelMaxContextLength: null,
+      followContext: requested || follow.target,
+      followReason: 'model-max-unknown',
+    };
+  }
+
+  const fit = await pickFittingLoadContext({ model, quant, modelMax, ceiling, floor, estimateFn });
+  let reloadedForFollow = false;
+  if (fit.ctx > (loaded || 0)) {
+    if (typeof unloadFn === 'function') {
+      try { await unloadFn(); } catch {}
+    }
+    const reloadRes = await loadFn({ contextLength: fit.ctx });
+    reloadedForFollow = true;
+    if (!reloadRes?.ok && !reloadRes?.modelLoaded && !reloadRes?.alreadyRunning) {
+      return {
+        ok: false,
+        reason: reloadRes?.reason || 'Follow-up reload failed',
+        performedLoad,
+        reloadedForFollow,
+        loadedContextLength: loaded,
+        modelMaxContextLength: modelMax,
+        followContext: fit.ctx,
+        followReason: 'reload-failed',
+      };
+    }
+    probe = await probeCurrent();
+    if (probe && sameModel(probe?.loadedModel, model)) {
+      loaded = toPositiveInt(probe?.loadedContextLength) || loaded;
+      modelMax = toPositiveInt(probe?.modelMaxContextLength) || modelMax;
+    }
+  }
+
+  return {
+    ok: true,
+    performedLoad,
+    reloadedForFollow,
+    loadedContextLength: loaded,
+    modelMaxContextLength: modelMax,
+    followContext: fit.ctx,
+    followZone: fit.zone || null,
+    followReason: reloadedForFollow ? 'reloaded-to-model-max' : 'already-optimal',
+  };
+}