kiku-agent 1.0.6 → 1.0.8

package/server/agent/terminalImage.js

@@ -0,0 +1,248 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import jpeg from 'jpeg-js';
+
+const moduleDirectory = path.dirname(fileURLToPath(import.meta.url));
+export const DEFAULT_IMAGE_DIRECTORY = path.resolve(moduleDirectory, '../../src/assets/images');
+
+const RESET = '\x1b[0m';
+const foreground = (r, g, b) => `\x1b[38;2;${r};${g};${b}m`;
+const background = (r, g, b) => `\x1b[48;2;${r};${g};${b}m`;
+const QUADRANT_GLYPHS = [
+  ' ', '▘', '▝', '▀', '▖', '▌', '▞', '▛',
+  '▗', '▚', '▐', '▜', '▄', '▙', '▟', '█',
+];
+
+export function supportsTerminalImages({
+  env = process.env,
+  isTTY = process.stdout.isTTY,
+} = {}) {
+  const setting = String(env.KIKU_TUI_IMAGES || '').trim().toLowerCase();
+  if (['0', 'false', 'off', 'no'].includes(setting)) return false;
+  if (['1', 'true', 'on', 'yes'].includes(setting)) return true;
+  if (!isTTY || env.NO_COLOR !== undefined || String(env.TERM || '').toLowerCase() === 'dumb') return false;
+  return true;
+}
+
+const clampChannel = value => Math.max(0, Math.min(255, Math.round(value)));
+
+function sourceChannel(image, x, y, channel) {
+  const safeX = Math.max(0, Math.min(image.width - 1, x));
+  const safeY = Math.max(0, Math.min(image.height - 1, y));
+  return image.data[(safeY * image.width + safeX) * 4 + channel];
+}
+
+function sampleBilinear(image, x, y, targetWidth, targetHeight) {
+  const sourceX = ((x + 0.5) * image.width) / targetWidth - 0.5;
+  const sourceY = ((y + 0.5) * image.height) / targetHeight - 0.5;
+  const left = Math.floor(sourceX);
+  const top = Math.floor(sourceY);
+  const right = left + 1;
+  const bottom = top + 1;
+  const mixX = sourceX - left;
+  const mixY = sourceY - top;
+  const result = [];
+
+  for (let channel = 0; channel < 3; channel++) {
+    const topMix = sourceChannel(image, left, top, channel) * (1 - mixX)
+      + sourceChannel(image, right, top, channel) * mixX;
+    const bottomMix = sourceChannel(image, left, bottom, channel) * (1 - mixX)
+      + sourceChannel(image, right, bottom, channel) * mixX;
+    result.push(topMix * (1 - mixY) + bottomMix * mixY);
+  }
+  return result;
+}
+
+function resizeAndEnhance(image, targetWidth, targetHeight) {
+  const pixels = new Float32Array(targetWidth * targetHeight * 3);
+  for (let y = 0; y < targetHeight; y++) {
+    for (let x = 0; x < targetWidth; x++) {
+      const color = sampleBilinear(image, x, y, targetWidth, targetHeight);
+      const offset = (y * targetWidth + x) * 3;
+      pixels[offset] = color[0];
+      pixels[offset + 1] = color[1];
+      pixels[offset + 2] = color[2];
+    }
+  }
+
+  const enhanced = new Uint8Array(pixels.length);
+  const at = (x, y, channel) => {
+    const safeX = Math.max(0, Math.min(targetWidth - 1, x));
+    const safeY = Math.max(0, Math.min(targetHeight - 1, y));
+    return pixels[(safeY * targetWidth + safeX) * 3 + channel];
+  };
+
+  for (let y = 0; y < targetHeight; y++) {
+    for (let x = 0; x < targetWidth; x++) {
+      const offset = (y * targetWidth + x) * 3;
+      const sharpened = [0, 1, 2].map(channel => {
+        const center = at(x, y, channel);
+        const neighbourAverage = (
+          at(x - 1, y, channel) + at(x + 1, y, channel)
+          + at(x, y - 1, channel) + at(x, y + 1, channel)
+        ) / 4;
+        return center * 1.18 - neighbourAverage * 0.18;
+      });
+      const luminance = sharpened[0] * 0.2126 + sharpened[1] * 0.7152 + sharpened[2] * 0.0722;
+      for (let channel = 0; channel < 3; channel++) {
+        const saturated = luminance + (sharpened[channel] - luminance) * 1.06;
+        enhanced[offset + channel] = clampChannel((saturated - 128) * 1.03 + 128);
+      }
+    }
+  }
+  return enhanced;
+}
+
+function colorDistance(left, right) {
+  const red = left[0] - right[0];
+  const green = left[1] - right[1];
+  const blue = left[2] - right[2];
+  return red * red + green * green + blue * blue;
+}
+
+function averageColors(colors, fallback) {
+  if (colors.length === 0) return fallback;
+  const sum = colors.reduce((total, color) => [
+    total[0] + color[0],
+    total[1] + color[1],
+    total[2] + color[2],
+  ], [0, 0, 0]);
+  return sum.map(value => clampChannel(value / colors.length));
+}
+
+function encodeQuadrants(colors) {
+  let first = colors[0];
+  let second = colors[1];
+  let furthestDistance = -1;
+  for (let left = 0; left < colors.length; left++) {
+    for (let right = left + 1; right < colors.length; right++) {
+      const distance = colorDistance(colors[left], colors[right]);
+      if (distance > furthestDistance) {
+        furthestDistance = distance;
+        first = colors[left];
+        second = colors[right];
+      }
+    }
+  }
+
+  let assignments = [0, 0, 0, 0];
+  for (let iteration = 0; iteration < 3; iteration++) {
+    assignments = colors.map(color => colorDistance(color, second) < colorDistance(color, first) ? 1 : 0);
+    first = averageColors(colors.filter((_, index) => assignments[index] === 0), first);
+    second = averageColors(colors.filter((_, index) => assignments[index] === 1), second);
+  }
+
+  const mask = assignments.reduce((value, assignment, index) => value | (assignment << index), 0);
+  return {
+    glyph: QUADRANT_GLYPHS[mask],
+    foregroundColor: second,
+    backgroundColor: first,
+  };
+}
+
+export function renderJpegToAnsi(buffer, {
+  columns = process.stdout.columns || 80,
+  rows = process.stdout.rows || 24,
+  maxWidth = 60,
+  maxRows = 20,
+  indent = '  ',
+} = {}) {
+  const image = jpeg.decode(buffer, { useTArray: true, formatAsRGBA: true });
+  if (!image?.width || !image?.height) throw new Error('Unable to decode gallery image');
+
+  const indentWidth = Array.from(indent).length;
+  const availableWidth = Math.max(8, Math.floor(columns) - indentWidth - 2);
+  let targetWidth = Math.max(8, Math.min(Math.floor(maxWidth), availableWidth, image.width));
+  const availableRows = Math.max(3, Math.min(Math.floor(maxRows), Math.floor(rows) - 7));
+  let targetPixelHeight = Math.max(2, Math.round((image.height / image.width) * targetWidth));
+  let targetRows = Math.ceil(targetPixelHeight / 2);
+
+  if (targetRows > availableRows) {
+    targetRows = availableRows;
+    targetPixelHeight = targetRows * 2;
+    targetWidth = Math.max(8, Math.min(targetWidth, Math.round((image.width / image.height) * targetPixelHeight)));
+  }
+
+  const sampledWidth = targetWidth * 2;
+  const resized = resizeAndEnhance(image, sampledWidth, targetPixelHeight);
+  const pixelAt = (x, y) => {
+    const offset = (y * sampledWidth + x) * 3;
+    return [resized[offset], resized[offset + 1], resized[offset + 2]];
+  };
+
+  const lines = [];
+  for (let row = 0; row < targetRows; row++) {
+    let line = indent;
+    const topY = Math.min(targetPixelHeight - 1, row * 2);
+    const bottomY = Math.min(targetPixelHeight - 1, row * 2 + 1);
+    for (let column = 0; column < targetWidth; column++) {
+      const leftX = column * 2;
+      const rightX = leftX + 1;
+      const cell = encodeQuadrants([
+        pixelAt(leftX, topY),
+        pixelAt(rightX, topY),
+        pixelAt(leftX, bottomY),
+        pixelAt(rightX, bottomY),
+      ]);
+      line += `${foreground(...cell.foregroundColor)}${background(...cell.backgroundColor)}${cell.glyph}`;
+    }
+    lines.push(`${line}${RESET}`);
+  }
+  return lines;
+}
+
+export function renderJpegFile(filePath, options = {}) {
+  return renderJpegToAnsi(readFileSync(filePath), options);
+}
+
+function discoverImages(directory) {
+  try {
+    return readdirSync(directory, { withFileTypes: true })
+      .filter(entry => entry.isFile() && /\.jpe?g$/i.test(entry.name))
+      .map(entry => path.join(directory, entry.name))
+      .sort((a, b) => a.localeCompare(b));
+  } catch {
+    return [];
+  }
+}
+
+export function createTerminalImageGallery({
+  directory = DEFAULT_IMAGE_DIRECTORY,
+  frequency = 3,
+  env = process.env,
+  isTTY = process.stdout.isTTY,
+  getColumns = () => process.stdout.columns || 80,
+  getRows = () => process.stdout.rows || 24,
+} = {}) {
+  const images = discoverImages(directory);
+  const enabled = images.length > 0 && supportsTerminalImages({ env, isTTY });
+  let imageIndex = 0;
+
+  return {
+    enabled,
+    imageCount: images.length,
+    maybeRender(completedQueries = 0, { force = false } = {}) {
+      const cadence = Math.max(1, Math.floor(frequency));
+      if (!enabled || (!force && (completedQueries <= 0 || completedQueries % cadence !== 0))) return [];
+
+      const currentIndex = imageIndex % images.length;
+      const filePath = images[currentIndex];
+      try {
+        const imageLines = renderJpegFile(filePath, {
+          columns: getColumns(),
+          rows: getRows(),
+        });
+        imageIndex++;
+        return [
+          '',
+          `  \x1b[1m\x1b[38;2;255;126;179m◆ KIKU MOMENT\x1b[0m \x1b[38;2;148;163;184m• Gallery ${currentIndex + 1}/${images.length}\x1b[0m`,
+          ...imageLines,
+          '',
+        ];
+      } catch {
+        return [];
+      }
+    },
+  };
+}

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(