kiku-agent 1.0.7 → 1.0.9

package/server/agent/tools.js

@@ -30,9 +30,16 @@ export function buildQqMusicSearchUrl(query) {
   return `https://y.qq.com/n/ryqq/search?w=${encodeURIComponent(query)}`;
 }
 
-export function buildYoukuSearchUrl(query) {
-  return `https://so.youku.com/search_video/q_${encodeURIComponent(query)}`;
-}
+export function buildYoukuSearchUrl(query) {
+  return `https://so.youku.com/search_video/q_${encodeURIComponent(query)}`;
+}
+
+export function formatCatalogTitle(primary, secondary) {
+  const first = String(primary || secondary || '').trim();
+  const second = String(secondary || '').trim();
+  if (!second || first.toLocaleLowerCase().includes(second.toLocaleLowerCase())) return first;
+  return `${first} (${second})`;
+}
 
 export class ToolCache {
   constructor(maxSize = 300, defaultTtlMs = 600_000) {
@@ -302,9 +309,11 @@ export const toolsSchema = [
       description: "Query awards and honors received by Ju Jingyi across music, television, and cultural influence.",
       parameters: {
         type: "object",
-        properties: {
-          category: { type: "string", description: "Category (Acting, Music, Honor)" },
-          year: { type: "number", description: "Year filter" }
+        properties: {
+          category: { type: "string", description: "Category (Acting, Music, Honor)" },
+          year: { type: "number", description: "Year filter" },
+          query: { type: "string", description: "Award title, ceremony, or category keyword" },
+          limit: { type: "number", description: "Maximum results from 1 to 20" }
         },
         required: []
       }
@@ -332,9 +341,11 @@ export const toolsSchema = [
       description: "Search visual photo gallery of Ju Jingyi (red carpet, photoshoot, drama stills).",
       parameters: {
         type: "object",
-        properties: {
-          category: { type: "string", description: "Category (fashion-magazine, red-carpet, drama-stills)" },
-          limit: { type: "number", description: "Number of photos (default 4)" }
+        properties: {
+          category: { type: "string", description: "Category (fashion-magazine, red-carpet, drama-stills)" },
+          query: { type: "string", description: "Photo title or category keyword" },
+          year: { type: "number", description: "Year filter" },
+          limit: { type: "number", description: "Number of photos from 1 to 20" }
         },
         required: []
       }
@@ -726,6 +737,30 @@ export const toolsSchema = [
         required: ["action"]
       }
     }
+  },
+  {
+    type: "function",
+    function: {
+      name: "run_quiz",
+      description: "Fetch the Ju Jingyi quiz challenge session and return all 15 questions with shuffled options for the user to answer interactively via /quiz command.",
+      parameters: {
+        type: "object",
+        properties: {
+          lang: { type: "string", enum: ["th", "en", "zh"], description: "Language for quiz questions (default: auto-detect from user preference)." }
+        }
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_api_key",
+      description: "Retrieve the stored Developer VIP API key for authenticated requests to the Ju Jingyi API.",
+      parameters: {
+        type: "object",
+        properties: {}
+      }
+    }
   }
 ];
 
@@ -829,7 +864,7 @@ export const toolHandlers = {
           youtubeTrailerSearch: buildYouTubeSearchUrl(`${titleSearch} Trailer Official`),
           youkuSearchUrl: buildYoukuSearchUrl(w.titleCn || w.titleEn),
           themeSong: w.themeSong ? {
-            title: `${w.themeSong.titleTh || ''} (${w.themeSong.titleCn || ''})`,
+            title: formatCatalogTitle(w.themeSong.titleTh, w.themeSong.titleCn),
             youtubeUrl: themeSongYtId ? buildYouTubeWatchUrl(themeSongYtId) : null,
             youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${w.themeSong.titleCn || w.themeSong.titleTh} OST`)
           } : null
@@ -875,7 +910,7 @@ export const toolHandlers = {
         synopsis: work.synopsis?.slice(0, 250) + (work.synopsis?.length > 250 ? '...' : ''),
         highlights: (work.highlights || []).slice(0, 3),
         themeSong: work.themeSong ? {
-          title: `${work.themeSong.titleTh || ''} (${work.themeSong.titleCn || ''})`,
+          title: formatCatalogTitle(work.themeSong.titleTh, work.themeSong.titleCn),
           youtubeUrl: themeSongYtId ? buildYouTubeWatchUrl(themeSongYtId) : null,
           youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${work.themeSong.titleCn || work.themeSong.titleTh} OST`)
         } : null
@@ -885,7 +920,7 @@ export const toolHandlers = {
 
   get_character_roles: async ({ query } = {}) => {
     const roles = worksData.map(w => ({
-      workTitle: `${w.titleTh} (${w.titleCn})`,
+      workTitle: formatCatalogTitle(w.titleTh, w.titleCn),
       year: w.year,
       role: w.role,
       roleCn: w.roleCn,
@@ -940,7 +975,7 @@ export const toolHandlers = {
       count: list.length,
       songs: list.slice(0, 8).map(s => ({
         id: s.id,
-        title: `${s.titleTh} (${s.titleCn})`,
+        title: formatCatalogTitle(s.titleTh, s.titleCn),
         titleEn: s.titleEn,
         year: s.year,
         type: s.work,
@@ -991,7 +1026,7 @@ export const toolHandlers = {
         const searchTitle = `Ju Jingyi 鞠婧祎 ${m.titleCn || m.titleTh} ${m.category === 'Stage-Performance' ? 'Stage Live' : 'Official MV'}`;
         return {
           id: m.id,
-          title: `${m.titleTh} (${m.titleCn})`,
+          title: formatCatalogTitle(m.titleTh, m.titleCn),
           category: m.category,
           year: m.releaseYear || m.year,
           drama: m.dramaName || null,
@@ -1021,7 +1056,7 @@ export const toolHandlers = {
       (m.dramaName && m.dramaName.toLowerCase().includes(q))
     ).map(m => ({
       type: m.category || 'MV',
-      title: `${m.titleTh} (${m.titleCn})`,
+      title: formatCatalogTitle(m.titleTh, m.titleCn),
       year: m.releaseYear || m.year,
       duration: m.duration,
       youtubeUrl: m.youtubeId ? buildYouTubeWatchUrl(m.youtubeId) : null,
@@ -1036,7 +1071,7 @@ export const toolHandlers = {
       (s.work && s.work.toLowerCase().includes(q))
     ).map(s => ({
       type: s.work || 'Song',
-      title: `${s.titleTh} (${s.titleCn})`,
+      title: formatCatalogTitle(s.titleTh, s.titleCn),
       year: s.year,
       duration: s.duration,
       youtubeUrl: s.youtubeUrl || (s.youtubeId ? buildYouTubeWatchUrl(s.youtubeId) : null),
@@ -1051,14 +1086,14 @@ export const toolHandlers = {
       (w.titleEn && w.titleEn.toLowerCase().includes(q))
     ).map(w => ({
       type: 'Drama / Series',
-      title: `${w.titleTh} (${w.titleCn})`,
+      title: formatCatalogTitle(w.titleTh, w.titleCn),
       year: w.year,
       platform: w.streamPlatform,
       streamUrl: w.streamUrl || null,
       youtubeTrailerSearch: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${w.titleCn || w.titleEn} Trailer Official`),
       youkuSearchUrl: buildYoukuSearchUrl(w.titleCn || w.titleEn),
       themeSong: w.themeSong ? {
-        title: `${w.themeSong.titleTh || ''} (${w.themeSong.titleCn || ''})`,
+        title: formatCatalogTitle(w.themeSong.titleTh, w.themeSong.titleCn),
         youtubeUrl: w.themeSong.youtubeId ? buildYouTubeWatchUrl(w.themeSong.youtubeId) : null,
         youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${w.themeSong.titleCn || w.themeSong.titleTh} OST`)
       } : null
@@ -1135,26 +1170,32 @@ export const toolHandlers = {
       count: eras.length,
       milestones: eras.slice(0, 6).map(e => ({
         period: e.period || e.year,
-        title: `${e.title} (${e.titleCn || ''})`,
+        title: formatCatalogTitle(e.title, e.titleCn),
         summary: e.summary?.slice(0, 150),
         youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${e.titleCn || e.title}`)
       }))
     };
   },
 
-  get_awards: async ({ category, year } = {}) => {
-    let list = Array.isArray(awardsData) ? awardsData : (awardsData.awards || []);
-    if (year) list = list.filter(a => a.year === Number(year));
-    if (category && category !== 'all') list = list.filter(a => a.category?.toLowerCase().includes(category.toLowerCase()));
-
-    return {
-      status: "success",
-      count: list.length,
-      awards: list.slice(0, 8).map(a => ({
-        year: a.year,
-        title: `${a.titleTh} (${a.titleCn})`,
-        ceremony: a.ceremony,
-        category: a.category,
+  get_awards: async ({ category, year, query, limit = 8 } = {}) => {
+    let list = Array.isArray(awardsData) ? awardsData : (awardsData.awards || []);
+    if (year) list = list.filter(a => a.year === Number(year));
+    if (category && category !== 'all') list = list.filter(a => a.category?.toLowerCase().includes(category.toLowerCase()));
+    if (query) {
+      const q = String(query).toLowerCase().trim();
+      list = list.filter(a => [a.titleTh, a.titleCn, a.titleEn, a.ceremony, a.category].filter(Boolean).join(' ').toLowerCase().includes(q));
+    }
+    const safeLimit = Math.min(Math.max(Number(limit) || 8, 1), 20);
+
+    return {
+      status: "success",
+      count: list.length,
+      awards: list.slice(0, safeLimit).map((a, index) => ({
+        id: a.id || `award-${a.year || 'unknown'}-${index + 1}`,
+        year: a.year,
+        title: `${a.titleTh || a.titleEn || a.titleCn || 'Award'}${a.titleCn && a.titleCn !== a.titleTh ? ` (${a.titleCn})` : ''}`,
+        ceremony: a.ceremony,
+        category: a.category,
         youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${a.titleCn || a.ceremony}`)
       }))
     };
@@ -1176,15 +1217,22 @@ export const toolHandlers = {
     };
   },
 
-  get_gallery_photos: async ({ category, limit = 4 } = {}) => {
-    let photos = Array.isArray(galleryData) ? galleryData : (galleryData.photos || []);
-    if (category && category !== 'all') photos = photos.filter(p => p.category?.toLowerCase().includes(category.toLowerCase()));
-
-    return {
-      status: "success",
-      count: Math.min(photos.length, Number(limit) || 4),
-      photos: photos.slice(0, Number(limit) || 4).map(p => ({
-        title: p.titleTh || p.titleCn,
+  get_gallery_photos: async ({ category, query, year, limit = 4 } = {}) => {
+    let photos = Array.isArray(galleryData) ? galleryData : (galleryData.photos || []);
+    if (category && category !== 'all') photos = photos.filter(p => p.category?.toLowerCase().includes(category.toLowerCase()));
+    if (query) {
+      const q = String(query).toLowerCase().trim();
+      photos = photos.filter(p => [p.titleTh, p.titleCn, p.titleEn, p.category, p.description].filter(Boolean).join(' ').toLowerCase().includes(q));
+    }
+    if (year) photos = photos.filter(p => Number(p.era || p.year) === Number(year));
+    const safeLimit = Math.min(Math.max(Number(limit) || 4, 1), 20);
+
+    return {
+      status: "success",
+      count: Math.min(photos.length, safeLimit),
+      photos: photos.slice(0, safeLimit).map((p, index) => ({
+        id: p.id || `photo-${p.era || p.year || 'unknown'}-${index + 1}`,
+        title: p.titleTh || p.titleCn,
         category: p.category,
         year: p.era || p.year
       }))
@@ -1220,7 +1268,7 @@ export const toolHandlers = {
     const mvs = getAllMusicVideos().filter(m =>
       matchesQuery(m.titleTh, m.titleCn, m.titlePinyin, m.dramaName, m.description)
     ).slice(0, 4).map(m => ({
-      title: `${m.titleTh} (${m.titleCn}) [${m.category}]`,
+      title: `${formatCatalogTitle(m.titleTh, m.titleCn)} [${m.category}]`,
       youtubeUrl: m.youtubeId ? buildYouTubeWatchUrl(m.youtubeId) : null,
       youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${m.titleCn || m.titleTh}`)
     }));
@@ -1616,7 +1664,69 @@ export const toolHandlers = {
         };
       }
     }
-  }
+  },
+
+  run_quiz: async ({ lang } = {}, options = {}) => {
+    let memory = options?.agent?.memory || options?.memory;
+    if (!memory) {
+      const { AgentMemory } = await import('./memory.js');
+      memory = new AgentMemory();
+      await memory.load();
+    }
+    const quizLang = ['th', 'en', 'zh'].includes(lang) ? lang : (memory.preferences?.language || 'en');
+    const { shuffleQuizQuestions } = await import('./quizData.js');
+    const { QUIZ_QUESTIONS, QUIZ_I18N, LETTER_LABELS } = await import('./quizData.js');
+    const i18n = QUIZ_I18N[quizLang] || QUIZ_I18N.en;
+    const shuffled = shuffleQuizQuestions(QUIZ_QUESTIONS);
+
+    let challengeToken = null;
+    try {
+      const baseUrl = options?.baseUrl || 'http://localhost:3000';
+      const res = await fetch(`${baseUrl}/api/v1/quiz/challenge`);
+      if (res.ok) {
+        const json = await res.json();
+        challengeToken = json.data?.challengeToken;
+      }
+    } catch {}
+
+    return {
+      status: 'success',
+      message: i18n.subtitle,
+      lang: quizLang,
+      challengeToken,
+      instructions: 'Present each question one by one. User answers with A/B/C/D or 1-4. After all 15, use POST /api/v1/keys/claim with challengeToken and answers array [{qIndex, answerIndex}].',
+      questions: shuffled.map((q, i) => ({
+        index: i,
+        question: q.q[quizLang] || q.q.en,
+        options: (q.options[quizLang] || q.options.en).map((opt, idx) => `${LETTER_LABELS[idx]}) ${opt}`),
+        hint: q.hint[quizLang] || q.hint.en,
+      }))
+    };
+  },
+
+  get_api_key: async (_args = {}, options = {}) => {
+    let memory = options?.agent?.memory || options?.memory;
+    if (!memory) {
+      const { AgentMemory } = await import('./memory.js');
+      memory = new AgentMemory();
+      await memory.load();
+    }
+    const key = memory.preferences?.vipKey;
+    if (key) {
+      return {
+        status: 'success',
+        apiKey: key,
+        tier: 'Developer VIP',
+        rateLimit: '1,000 requests/minute',
+        usage: `Header: X-API-Key: ${key}  |  Query: ?apiKey=${key}`
+      };
+    }
+    return {
+      status: 'info',
+      message: 'No VIP key stored. Run /quiz in the CLI to complete the challenge and claim one.',
+      apiKey: null
+    };
+  },
 };
 
 const toolSchemaByName = new Map(

package/server/agent/ui.js

@@ -228,13 +228,28 @@ export function wrapText(text, maxWidth = 72) {
   const lines = [];
   const rawParagraphs = text.split('\n');
 
+  const tokenize = para => {
+    const raw = para.split(/\s+/).filter(Boolean);
+    const tokens = [];
+    for (let i = 0; i < raw.length; i++) {
+      if (raw[i] === '•' && i + 1 < raw.length) {
+        tokens.push('• ' + raw[i + 1]);
+        i++;
+      } else {
+        tokens.push(raw[i]);
+      }
+    }
+    return tokens;
+  };
+
   for (const para of rawParagraphs) {
     if (!para.trim()) {
       lines.push('');
       continue;
     }
 
-    const words = para.split(/\s+/);
+    const words = tokenize(para);
+    const paraLines = [];
     let currentLine = '';
 
     for (const word of words) {
@@ -246,7 +261,7 @@ export function wrapText(text, maxWidth = 72) {
         currentLine = testLine;
       } else {
         if (currentLine) {
-          lines.push(currentLine);
+          paraLines.push(currentLine);
           currentLine = word;
         } else {
           let chunk = '';
@@ -254,7 +269,7 @@ export function wrapText(text, maxWidth = 72) {
             if (getStringDisplayWidth(chunk + ch) <= maxWidth) {
               chunk += ch;
             } else {
-              lines.push(chunk);
+              paraLines.push(chunk);
               chunk = ch;
             }
           }
@@ -262,9 +277,19 @@ export function wrapText(text, maxWidth = 72) {
         }
       }
     }
-    if (currentLine) {
-      lines.push(currentLine);
+    if (currentLine) paraLines.push(currentLine);
+
+    if (paraLines.length >= 2 && !/\s/.test(paraLines[paraLines.length - 1].trim())) {
+      const last = paraLines[paraLines.length - 1];
+      const prev = paraLines[paraLines.length - 2];
+      const candidate = prev + ' ' + last;
+      if (getStringDisplayWidth(candidate) <= maxWidth) {
+        paraLines[paraLines.length - 2] = candidate;
+        paraLines.pop();
+      }
     }
+
+    lines.push(...paraLines);
   }
   return lines;
 }
@@ -829,7 +854,7 @@ export function formatMarkdownLines(text, maxWidth = getFullWidth() - 8) {
   return result;
 }
 
-export function getWelcomeHeroLines() {
+export function getWelcomeHeroLines() {
   const p = C.sakura;
   const r = C.roseGlow;
   const g = C.gold;
@@ -841,7 +866,8 @@ export function getWelcomeHeroLines() {
   const b = C.bold;
   const d = C.dim;
   const rst = C.reset;
-  const boxWidth = Math.min(84, Math.max(50, getFullWidth() - 4));
+  const boxWidth = Math.min(84, Math.max(50, getFullWidth() - 4));
+  const compact = getFullWidth() < 120;
   const headerTitle = 'Suggested Topics & Queries';
   const topDashCount = Math.max(2, boxWidth - getStringDisplayWidth(headerTitle) - 6);
   const innerWidth = boxWidth - 2;
@@ -854,14 +880,28 @@ export function getWelcomeHeroLines() {
     return `  ${s}│${rst}  ${icon} ${tag}${rst}${' '.repeat(Math.max(0, tagWidth - getStringDisplayWidth(tag)))}  ${w}${text}${rst}${' '.repeat(pad)}${s}│${rst}`;
   };
 
-  return [
-    '',
-    `  ${p}██╗  ██╗██╗██╗  ██╗██╗   ██╗     █████╗ ██╗${rst}   ${b}${p}◆ Ju Jingyi • 鞠婧祎 • Mìjú Terminal Portal ◆${rst}`,
-    `  ${p}██║ ██╔╝██║██║ ██╔╝██║   ██║    ██╔══██╗██║${rst}   ${d}${s}Interactive Fan Knowledge Base & Autonomous Agent${rst}`,
-    `  ${r}█████═╝ ██║█████═╝ ██║   ██║    ███████║██║${rst}   ${d}${s}Filmography • Discography • Fashion & Awards${rst}`,
-    `  ${r}██╔═██╗ ██║██╔═██╗ ██║   ██║    ██╔══██╗██║${rst}   ${c}● Live Ready${rst} ${s}• Multilingual (CN / EN / TH)${rst}`,
-    `  ${p}██║ ╚██╗██║██║ ╚██╗╚██████╔╝    ██║  ██║██║${rst}`,
-    `  ${p}╚═╝  ╚═╝╚═╝╚═╝  ╚═╝ ╚═════╝     ╚═╝  ╚═╝╚═╝${rst}`,
+  const heroLines = compact ? [
+    `  ${b}${p}◆ Ju Jingyi • 鞠婧祎 • Mìjú Terminal Portal ◆${rst}`,
+    `  ${p}██╗  ██╗██╗██╗  ██╗██╗   ██╗     █████╗ ██╗${rst}`,
+    `  ${r}█████═╝ ██║█████═╝ ██║   ██║    ███████║██║${rst}`,
+  ] : [
+    `  ${p}██╗  ██╗██╗██╗  ██╗██╗   ██╗     █████╗ ██╗${rst}   ${b}${p}◆ Ju Jingyi • 鞠婧祎 • Mìjú Terminal Portal ◆${rst}`,
+    `  ${p}██║ ██╔╝██║██║ ██╔╝██║   ██║    ██╔══██╗██║${rst}   ${d}${s}Interactive Fan Knowledge Base & Autonomous Agent${rst}`,
+    `  ${r}█████═╝ ██║█████═╝ ██║   ██║    ███████║██║${rst}   ${d}${s}Filmography • Discography • Fashion & Awards${rst}`,
+    `  ${r}██╔═██╗ ██║██╔═██╗ ██║   ██║    ██╔══██╗██║${rst}   ${c}● Live Ready${rst} ${s}• Multilingual (CN / EN / TH)${rst}`,
+    `  ${p}██║ ╚██╗██║██║ ╚██╗╚██████╔╝    ██║  ██║██║${rst}`,
+    `  ${p}╚═╝  ╚═╝╚═╝╚═╝  ╚═╝ ╚═════╝     ╚═╝  ╚═╝╚═╝${rst}`,
+  ];
+  const shortcutLines = compact ? [
+    `  ${s}Shortcuts: ${b}${w}[Tab]${rst} ${s}Commands • ${b}${w}[↑/↓]${rst} ${s}History • ${b}${w}[F2]${rst} ${s}Details${rst}`,
+    `  ${b}${w}[PgUp/PgDn]${rst} ${s}Scroll • ${b}${w}[Ctrl+C]${rst} ${s}Exit${rst}`,
+  ] : [
+    `  ${s}Shortcuts: ${b}${w}[Tab]${rst} ${s}Autocomplete • ${b}${w}[↑/↓]${rst} ${s}History • ${b}${w}[PgUp/PgDn]${rst} ${s}Scroll • ${b}${w}[F2]${rst} ${s}Details • ${b}${w}[Ctrl+C]${rst} ${s}Exit${rst}`,
+  ];
+
+  return [
+    ...(compact ? [] : ['']),
+    ...heroLines,
     '',
     `  ${s}╭──${rst} ${b}${g}${headerTitle}${rst} ${s}${'─'.repeat(topDashCount)}╮${rst}`,
     padItem(p + '◆', '2026 Works', '"What are Ju Jingyi\'s 2026 upcoming dramas?"'),
@@ -870,7 +910,7 @@ export function getWelcomeHeroLines() {
     padItem(l + '◆', 'Tools / MCP', '"@search_works 2026, /mcp list, /stats, /help"'),
     `  ${s}╰${'─'.repeat(boxWidth)}╯${rst}`,
     '',
-    `  ${s}Shortcuts: ${b}${w}[Tab]${rst} ${s}Autocomplete • ${b}${w}[↑/↓]${rst} ${s}History • ${b}${w}[PgUp/PgDn]${rst} ${s}Scroll • ${b}${w}[F2]${rst} ${s}Details • ${b}${w}[Ctrl+C]${rst} ${s}Exit${rst}`,
+    ...shortcutLines,
     '',
   ];
 }
@@ -1040,7 +1080,7 @@ export function exitAlternateScreen() {
   }
 }
 
-export function getTuiViewportLayout(termRows = 24) {
+export function getTuiViewportLayout(termRows = 24) {
   const parsedRows = Number(termRows);
   const rows = Math.max(10, Number.isFinite(parsedRows) ? Math.floor(parsedRows) : 24);
   const viewportStartRow = 1;
@@ -1055,10 +1095,16 @@ export function getTuiViewportLayout(termRows = 24) {
     statusBarRow,
     promptRow,
     separatorRow,
-  };
-}
-
-export class VirtualScreenBuffer {
+  };
+}
+
+export function getNewOutputScrollOffset(addedLineCount, termRows = 24, currentOffset = 0) {
+  const added = Math.max(0, Number.isFinite(Number(addedLineCount)) ? Math.floor(Number(addedLineCount)) : 0);
+  if (currentOffset > 0) return currentOffset + added;
+  return Math.max(0, added - getTuiViewportLayout(termRows).viewportHeight);
+}
+
+export class VirtualScreenBuffer {
   constructor(width = 80, height = 24, writer = null) {
     this.width = Math.max(10, width);
     this.height = Math.max(5, height);

package/server/agent/updateManager.js

@@ -24,11 +24,14 @@ export class UpdateError extends Error {
 }
 
 function cleanOutput(value, maxLength = 400) {
-  return String(value || '')
+  const text = String(value || '')
     .replace(/\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1b\\))/g, '')
     .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '')
-    .trim()
-    .slice(0, maxLength);
+    .split('\n')
+    .map(line => line.replace(/^npm\s+(?:error|ERR!)\s*/i, '').trim())
+    .filter(Boolean)
+    .join(' ');
+  return text.slice(0, maxLength);
 }
 
 function parseSemver(value) {
@@ -281,6 +284,21 @@ export class UpdateManager {
     const spec = `${this.packageName}@${normalizedTarget}`;
     const result = await this.runner(['view', spec, '--json', '--prefer-online'], { timeoutMs: DEFAULT_TIMEOUT_MS });
     if (result.code !== 0) {
+      const errText = String(result.stderr || '');
+      if (/E404|404\s+No match found|No match found for version|not found|404\s+Not\s+Found/i.test(errText)) {
+        if (UPDATE_CHANNELS.includes(normalizedTarget)) {
+          throw new UpdateError(
+            `No release is currently available for channel "${normalizedTarget}" on npm. (Only "latest" is currently published).`,
+            'CHANNEL_NOT_FOUND',
+            { target: normalizedTarget, exitCode: result.code }
+          );
+        }
+        throw new UpdateError(
+          `Version or tag "${normalizedTarget}" was not found on the npm registry.`,
+          'RELEASE_NOT_FOUND',
+          { target: normalizedTarget, exitCode: result.code }
+        );
+      }
       throw new UpdateError(
         cleanOutput(result.stderr) || 'npm could not find the requested release.',
         'REGISTRY_LOOKUP_FAILED',