kiku-agent 1.0.0 → 1.0.4

package/server/agent/tools.js

@@ -1,1528 +1,1679 @@
-import { profileData } from '../../src/data/profileData.js';
-import { worksData } from '../../src/data/worksData.js';
-import { discographyData } from '../../src/data/discographyData.js';
-import { musicVideoData } from '../../src/data/musicVideoData.js';
-import { brandsData } from '../../src/data/brandsData.js';
-import { socialUpdatesData } from '../../src/data/socialUpdatesData.js';
-import { galleryData } from '../../src/data/galleryData.js';
-import { awardsData } from '../../src/data/awardsData.js';
-import { timelineData } from '../../src/data/timelineData.js';
-import { searchWeb, fetchWebpage, fetchJson, screenshotWebpage, webExtract } from './webSearch.js';
-import { readFile, readdir, stat } from 'node:fs/promises';
-import { join, relative, extname, resolve } from 'node:path';
-import { audioPlayer } from './audioPlayer.js';
-import { sanitizeToolArgs } from './sanitizer.js';
-
-export function buildYouTubeSearchUrl(query) {
-  return `https://www.youtube.com/results?search_query=${encodeURIComponent(query)}`;
-}
-
-export function buildYouTubeWatchUrl(videoId) {
-  return videoId ? `https://www.youtube.com/watch?v=${videoId}` : null;
-}
-
-export function buildBilibiliSearchUrl(query) {
-  return `https://search.bilibili.com/all?keyword=${encodeURIComponent(query)}`;
-}
-
-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)}`;
-}
-
-function getCleanDiscography() {
-  const map = new Map();
-  const allTracks = [
-    ...(discographyData.latestReleases || []),
-    ...(discographyData.ostList || []),
-    ...(discographyData.singles || [])
-  ];
-
-  for (const track of allTracks) {
-    const key = track.titleCn || track.titleTh;
-    if (!map.has(key)) {
-      const ytId = track.youtubeId || null;
-      const searchTerms = `Ju Jingyi 鞠婧祎 ${track.titleCn || track.titleTh || track.titleEn || ''}`;
-      map.set(key, {
-        id: track.id,
-        titleTh: track.titleTh,
-        titleCn: track.titleCn,
-        titleEn: track.titleEn || '',
-        year: track.year,
-        work: track.work || "Solo Single",
-        duration: track.duration || track.trackDuration || '',
-        theme: track.theme || "Pop / Ballad",
-        youtubeId: ytId,
-        youtubeUrl: track.youtubeUrl || buildYouTubeWatchUrl(ytId),
-        youtubeSearchUrl: buildYouTubeSearchUrl(searchTerms),
-        qqMusicSearchUrl: buildQqMusicSearchUrl(`鞠婧祎 ${track.titleCn || track.titleTh}`),
-        bilibiliSearchUrl: buildBilibiliSearchUrl(`鞠婧祎 ${track.titleCn || track.titleTh}`)
-      });
-    }
-  }
-
-  return Array.from(map.values()).sort((a, b) => (b.year || 0) - (a.year || 0));
-}
-
-function getAllMusicVideos() {
-  if (Array.isArray(musicVideoData)) {
-    return musicVideoData;
-  }
-  return [
-    ...(musicVideoData.officialMvs || []).map(m => ({ ...m, category: 'Official MV' })),
-    ...(musicVideoData.stagePerformances || []).map(m => ({ ...m, category: 'Stage Performance' }))
-  ];
-}
-
-export const toolsSchema = [
-  {
-    type: "function",
-    function: {
-      name: "get_profile_and_fandom",
-      description: "Get Ju Jingyi's biographical profile, Chinese/English/Thai names, birthday, birthplace, Miju (蜜橘) fan community, official slogan, and socials.",
-      parameters: {
-        type: "object",
-        properties: {},
-        required: []
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "get_quotes",
-      description: "Retrieve inspiring quotes and famous statements made by Ju Jingyi (with Thai translation and Chinese text).",
-      parameters: {
-        type: "object",
-        properties: {
-          tag: { type: "string", description: "Optional tag (mindset, growth, acting, fandom)" }
-        },
-        required: []
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "search_works",
-      description: "Search Ju Jingyi's filmography (TV dramas, web series, movies, and 2026/2025 upcoming projects) with official streaming links and YouTube trailer search links.",
-      parameters: {
-        type: "object",
-        properties: {
-          query: { type: "string", description: "Search keyword for drama title or character name." },
-          year: { type: "number", description: "Specific release year (e.g. 2026, 2025, 2024, 2023). Leave empty to get newest." },
-          category: { type: "string", description: "Category filter (e.g. 'series', 'movie', 'upcoming')." },
-          featuredOnly: { type: "boolean", description: "Filter only featured major hit dramas." }
-        },
-        required: []
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "get_work_detail",
-      description: "Get full details of a specific drama or film by ID or title (synopsis, role, OST with YouTube links, episode count, platform, rating).",
-      parameters: {
-        type: "object",
-        properties: {
-          workIdOrTitle: { type: "string", description: "ID or title of drama (e.g. 'veil-of-shadows', 'in-blossom', 'legend-of-white-snake')" }
-        },
-        required: ["workIdOrTitle"]
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "get_character_roles",
-      description: "List and search famous fictional character roles portrayed by Ju Jingyi in dramas and movies (e.g. Yang Caiwei, Lu Wuyi, Bai Suzhen, Han Yunxi).",
-      parameters: {
-        type: "object",
-        properties: {
-          query: { type: "string", description: "Optional role name or drama title keyword" }
-        },
-        required: []
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "search_discography",
-      description: "Search Ju Jingyi's songs, singles, and OST drama soundtracks. Returns verified direct YouTube watch links (https://www.youtube.com/watch?v=...), real YouTube search queries (https://www.youtube.com/results?search_query=...), and music streaming links.",
-      parameters: {
-        type: "object",
-        properties: {
-          query: { type: "string", description: "Song title keyword (Thai, Chinese, or English)" },
-          year: { type: "number", description: "Release year" },
-          type: { type: "string", enum: ["all", "ost", "single"] }
-        },
-        required: []
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "get_music_videos",
-      description: "Retrieve music videos (MV), stage performances, and dance practices with verified direct YouTube links and YouTube search query URLs.",
-      parameters: {
-        type: "object",
-        properties: {
-          category: { type: "string", description: "Category (Official MV, Stage Performance, OST, Single)" },
-          query: { type: "string", description: "Keyword matching title, song, or event" }
-        },
-        required: []
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "get_media_links",
-      description: "Get direct YouTube video watch links (watch?v=...), official YouTube search queries (results?search_query=...), Bilibili links, and streaming URLs for any Ju Jingyi song, MV, live stage, or drama trailer.",
-      parameters: {
-        type: "object",
-        properties: {
-          query: { type: "string", description: "Song, drama, stage, or MV name (e.g. 'FIND THE WAY', 'Rain Love', 'Hong Zhao Yuan', 'In Blossom', 'Veil of Shadows', 'Luo Hua Cheng Ni')" },
-          category: { type: "string", enum: ["all", "mv", "stage", "ost", "single", "trailer"], description: "Optional media type filter" }
-        },
-        required: ["query"]
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "get_brand_endorsements",
-      description: "Retrieve brand endorsements, commercial ambassadorships, luxury fashion, and beauty partnerships of Ju Jingyi.",
-      parameters: {
-        type: "object",
-        properties: {
-          isGlobal: { type: "boolean", description: "Filter for Global Brand Ambassador roles" },
-          year: { type: "number", description: "Year of endorsement (e.g. 2026, 2025, 2024). Leave empty for latest." },
-          category: { type: "string", description: "Category filter (Luxury, Beauty, FMCG, Tech)" },
-          query: { type: "string", description: "Brand name keyword or search term" }
-        },
-        required: []
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "get_career_timeline",
-      description: "Explore Ju Jingyi's career milestones and chronological eras (SNH48 Era, Solo Studio, Breakthrough Dramas, Present).",
-      parameters: {
-        type: "object",
-        properties: {
-          year: { type: "number", description: "Year filter (2013-2026)" },
-          era: { type: "string", description: "Era keyword" }
-        },
-        required: []
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "get_awards",
-      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" }
-        },
-        required: []
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "get_social_feed",
-      description: "Get recent social media updates from Weibo and Douyin.",
-      parameters: {
-        type: "object",
-        properties: {
-          platform: { type: "string", enum: ["all", "weibo", "douyin"] },
-          limit: { type: "number", description: "Number of posts (default 4)" }
-        },
-        required: []
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "get_gallery_photos",
-      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)" }
-        },
-        required: []
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "global_search",
-      description: "Universal search across ALL Ju Jingyi entities (works, songs, roles, brands, awards, videos) with YouTube and media links.",
-      parameters: {
-        type: "object",
-        properties: {
-          query: { type: "string", description: "Search term to match across all collections" }
-        },
-        required: ["query"]
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "web_search",
-      description: "Search the LIVE internet for real-time news, recent updates, social media trends, Weibo topics, or external info about Ju Jingyi and entertainment topics.",
-      parameters: {
-        type: "object",
-        properties: {
-          query: { type: "string", description: "Search query keyword" }
-        },
-        required: ["query"]
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "fetch_webpage",
-      description: "Fetch and read the text content of a specific public web page URL. Returns extracted text — read the content field carefully and extract specific facts (names, dates, titles, descriptions) for your answer. NOTE: This cannot read SPA/React sites — use fetch_api for jujingyi-kikuuu.vercel.app.",
-      parameters: {
-        type: "object",
-        properties: {
-          url: { type: "string", description: "The full http/https URL of the web page to read" }
-        },
-        required: ["url"]
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "fetch_api",
-      description: "Query the Ju Jingyi Official REST API (jujingyi-kikuuu.vercel.app/api/v1) for structured JSON data. Use this instead of fetch_webpage when the user shares a link to the platform site, or when you need live/verified data from the official API.",
-      parameters: {
-        type: "object",
-        properties: {
-          endpoint: { type: "string", description: "API endpoint path (e.g. 'profile', 'works', 'music', 'commercial', 'milestones', 'honors', 'social', 'search', 'stats', 'quotes', 'fandom', 'character-roles', 'gallery')" },
-          query: { type: "string", description: "Optional search/filter query parameter" },
-          baseUrl: { type: "string", description: "Optional override base URL (defaults to https://jujingyi-kikuuu.vercel.app/api/v1)" }
-        },
-        required: ["endpoint"]
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "fetch_json",
-      description: "Fetch data from any REST API or JSON endpoint. Returns parsed JSON data with status code, headers, and content. Use for public APIs, weather, translation, definitions, or any JSON-based service.",
-      parameters: {
-        type: "object",
-        properties: {
-          url: { type: "string", description: "The full HTTP/HTTPS URL of the JSON API endpoint" },
-          method: { type: "string", enum: ["GET", "POST", "PUT", "PATCH", "DELETE"], description: "HTTP method (default GET)" },
-          headers: { type: "object", description: "Optional custom headers as key-value pairs" },
-          body: { description: "Optional request body (for POST/PUT/PATCH). Can be a JSON object or string." }
-        },
-        required: ["url"]
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "read_local_file",
-      description: "Read the contents of a local file in the project directory. Use for reading source code, config files, data files, markdown docs, etc. Returns the text content with file metadata.",
-      parameters: {
-        type: "object",
-        properties: {
-          path: { type: "string", description: "Relative file path from project root (e.g. 'package.json', 'src/App.jsx', 'README.md')" },
-          maxLines: { type: "number", description: "Maximum number of lines to read (default 200). Use for large files." }
-        },
-        required: ["path"]
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "list_directory",
-      description: "List files and subdirectories in a project directory. Use to explore project structure, find files, or understand codebase layout.",
-      parameters: {
-        type: "object",
-        properties: {
-          path: { type: "string", description: "Relative directory path from project root (e.g. 'src', 'server/agent', '.')" },
-          recursive: { type: "boolean", description: "If true, list recursively (max 3 levels deep). Default false." }
-        },
-        required: []
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "screenshot_webpage",
-      description: "Take a screenshot of a webpage using Chrome headless. Returns base64 PNG image data. Requires Google Chrome installed. Use for visual verification of pages, layouts, or UI elements.",
-      parameters: {
-        type: "object",
-        properties: {
-          url: { type: "string", description: "The full HTTP/HTTPS URL to screenshot" },
-          width: { type: "number", description: "Viewport width in pixels (default 1280)" },
-          height: { type: "number", description: "Viewport height in pixels (default 800)" }
-        },
-        required: ["url"]
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "web_extract",
-      description: "Auto-crawl: search the web AND fetch+extract content from top results in one call. Returns structured page data (meta, headings, paragraphs, links, images) from each result. Use when you need comprehensive info from multiple sources on a topic.",
-      parameters: {
-        type: "object",
-        properties: {
-          query: { type: "string", description: "Search query to find and extract content about" },
-          maxResults: { type: "number", description: "Max pages to fetch (default 3, max 5). More = slower but more comprehensive." },
-          allowedDomains: { type: "array", items: { type: "string" }, description: "Only fetch from these domains (e.g. ['wikipedia.org', 'youtube.com']). Empty = all domains." }
-        },
-        required: ["query"]
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "get_system_stats",
-      description: "Get high-level summary metrics of the entire Ju Jingyi database.",
-      parameters: {
-        type: "object",
-        properties: {},
-        required: []
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "play_music",
-      description: "Play a specific song, OST, or music video audio directly in the user's terminal.",
-      parameters: {
-        type: "object",
-        properties: {
-          query: {
-            type: "string",
-            description: "The name of the song and artist (e.g., 'Ju Jingyi FIND THE WAY', 'In Blossom OST Ju Jingyi')"
-          }
-        },
-        required: ["query"]
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "stop_music",
-      description: "Stop the currently playing music.",
-      parameters: { type: "object", properties: {} }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "mute_music",
-      description: "Mute the currently playing music.",
-      parameters: { type: "object", properties: {} }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "unmute_music",
-      description: "Unmute the currently playing music.",
-      parameters: { type: "object", properties: {} }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "pause_music",
-      description: "Pause the currently playing music.",
-      parameters: { type: "object", properties: {} }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "resume_music",
-      description: "Resume paused music.",
-      parameters: { type: "object", properties: {} }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "next_track",
-      description: "Skip to the next track in the queue.",
-      parameters: { type: "object", properties: {} }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "prev_track",
-      description: "Go back to the previous track in the queue.",
-      parameters: { type: "object", properties: {} }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "add_to_queue",
-      description: "Add a song to the playback queue.",
-      parameters: {
-        type: "object",
-        properties: {
-          query: {
-            type: "string",
-            description: "The name of the song and artist to queue."
-          }
-        },
-        required: ["query"]
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "remove_from_queue",
-      description: "Remove a song from the queue by index.",
-      parameters: {
-        type: "object",
-        properties: {
-          index: {
-            type: "number",
-            description: "0-based index of the song in the queue to remove."
-          }
-        },
-        required: ["index"]
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "clear_queue",
-      description: "Clear the entire playback queue and stop music.",
-      parameters: { type: "object", properties: {} }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "get_queue",
-      description: "Get the current playback queue list.",
-      parameters: { type: "object", properties: {} }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "search_youtube",
-      description: "Search YouTube for music videos or audio and return top results.",
-      parameters: {
-        type: "object",
-        properties: {
-          query: {
-            type: "string",
-            description: "Search query for YouTube."
-          }
-        },
-        required: ["query"]
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "get_current_track",
-      description: "Get information about the currently playing or paused track.",
-      parameters: { type: "object", properties: {} }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "get_music_status",
-      description: "Get full music player status including playing state, current track, and queue info.",
-      parameters: { type: "object", properties: {} }
-    }
-  }
-];
-
-export const toolHandlers = {
-  get_profile_and_fandom: async () => {
-    const d = profileData.details || {};
-    return {
-      status: "success",
-      profile: {
-        nameTh: profileData.nameTh,
-        nameCn: profileData.nameCn,
-        nameEn: profileData.nameEn,
-        nickname: profileData.nickname,
-        birthDate: d.birthDate,
-        birthPlace: d.birthPlace,
-        height: d.height,
-        bloodType: d.bloodType,
-        zodiac: d.zodiac,
-        education: d.education,
-        debutDate: d.debutDate,
-        graduationDate: d.graduationDate,
-        currentStatus: d.currentStatus,
-        hobbies: d.hobbies,
-        favoriteFoods: d.favoriteFoods,
-        talentsSummary: d.talentsSummary,
-        fandomName: d.fandomName || "มี่จวี (Miju / 蜜橘)",
-        fandomColor: d.fandomColorName || "ฟ้าคริสตัล & ชมพูซากุระ",
-        slogan: profileData.motto || "保持热爱，奔赴山海",
-        youtubeSearchUrl: buildYouTubeSearchUrl("Ju Jingyi 鞠婧祎")
-      }
-    };
-  },
-
-  get_quotes: async ({ tag } = {}) => {
-    let quotes = profileData.quotes || [];
-    if (tag) {
-      const qLower = tag.toLowerCase();
-      quotes = quotes.filter(q => 
-        (q.tag && q.tag.toLowerCase().includes(qLower)) ||
-        (q.textTh && q.textTh.toLowerCase().includes(qLower)) ||
-        (q.textCn && q.textCn.includes(tag))
-      );
-    }
-    return {
-      status: "success",
-      count: quotes.length,
-      quotes: quotes.slice(0, 5).map(q => ({
-        textTh: q.textTh,
-        textCn: q.textCn,
-        tag: q.tag,
-        context: q.context
-      }))
-    };
-  },
-
-  search_works: async ({ query, year, category, featuredOnly } = {}) => {
-    let results = [...worksData];
-
-    if (year) results = results.filter(w => w.year === Number(year));
-    if (category && category !== 'all') results = results.filter(w => w.category === category);
-
-    const genericArtistKeywords = ['ju jingyi', 'jujingyi', 'จวีจิ้งอี', 'kiku', 'เสี่ยวจวี', 'kikuuu', 'ศิลปิน', 'ดารา', 'งานล่าสุด', 'ผลงานล่าสุด', 'ล่าสุด', 'latest', 'newest', 'recent', 'upcoming', 'ละคร'];
-    const isGenericArtistQuery = query && genericArtistKeywords.some(k => query.toLowerCase().trim() === k);
-
-    if (query && !isGenericArtistQuery) {
-      const q = query.toLowerCase().trim();
-      results = results.filter(w => 
-        (w.titleTh && w.titleTh.toLowerCase().includes(q)) ||
-        (w.titleEn && w.titleEn.toLowerCase().includes(q)) ||
-        (w.titleCn && w.titleCn.includes(query)) ||
-        (w.role && w.role.toLowerCase().includes(q)) ||
-        (w.roleCn && w.roleCn.includes(query))
-      );
-    }
-
-    if (featuredOnly && results.some(w => !!w.featured)) {
-      results = results.filter(w => !!w.featured);
-    }
-
-    results.sort((a, b) => (b.year || 0) - (a.year || 0));
-
-    return {
-      status: "success",
-      count: results.length,
-      works: results.slice(0, 6).map(w => {
-        const titleSearch = `Ju Jingyi 鞠婧祎 ${w.titleCn || w.titleEn || w.titleTh}`;
-        const themeSongYtId = w.themeSong?.youtubeId || null;
-        return {
-          id: w.id,
-          titleTh: w.titleTh,
-          titleCn: w.titleCn,
-          titleEn: w.titleEn,
-          year: w.year,
-          category: w.category,
-          role: w.role,
-          roleCn: w.roleCn,
-          episodes: w.episodes,
-          rating: w.rating,
-          platform: w.streamPlatform,
-          streamUrl: w.streamUrl || null,
-          youtubeTrailerSearch: buildYouTubeSearchUrl(`${titleSearch} Trailer Official`),
-          youkuSearchUrl: buildYoukuSearchUrl(w.titleCn || w.titleEn),
-          themeSong: w.themeSong ? {
-            title: `${w.themeSong.titleTh || ''} (${w.themeSong.titleCn || ''})`,
-            youtubeUrl: themeSongYtId ? buildYouTubeWatchUrl(themeSongYtId) : null,
-            youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${w.themeSong.titleCn || w.themeSong.titleTh} OST`)
-          } : null
-        };
-      })
-    };
-  },
-
-  get_work_detail: async ({ workIdOrTitle }) => {
-    if (!workIdOrTitle) return { status: "error", message: "workIdOrTitle parameter is required." };
-    const q = workIdOrTitle.toLowerCase().trim();
-    const work = worksData.find(w => 
-      w.id.toLowerCase() === q ||
-      w.titleTh.toLowerCase().includes(q) ||
-      (w.titleEn && w.titleEn.toLowerCase().includes(q)) ||
-      (w.titleCn && w.titleCn.includes(workIdOrTitle))
-    );
-
-    if (!work) {
-      return { status: "not_found", message: `No work found for "${workIdOrTitle}".` };
-    }
-
-    const titleSearch = `Ju Jingyi 鞠婧祎 ${work.titleCn || work.titleEn || work.titleTh}`;
-    const themeSongYtId = work.themeSong?.youtubeId || null;
-
-    return {
-      status: "success",
-      work: {
-        id: work.id,
-        titleTh: work.titleTh,
-        titleCn: work.titleCn,
-        titleEn: work.titleEn,
-        year: work.year,
-        category: work.category,
-        role: work.role,
-        episodes: work.episodes,
-        rating: work.rating,
-        platform: work.streamPlatform,
-        streamUrl: work.streamUrl || null,
-        youtubeTrailerSearch: buildYouTubeSearchUrl(`${titleSearch} Trailer Official`),
-        youkuSearchUrl: buildYoukuSearchUrl(work.titleCn || work.titleEn),
-        bilibiliSearchUrl: buildBilibiliSearchUrl(`鞠婧祎 ${work.titleCn}`),
-        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 || ''})`,
-          youtubeUrl: themeSongYtId ? buildYouTubeWatchUrl(themeSongYtId) : null,
-          youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${work.themeSong.titleCn || work.themeSong.titleTh} OST`)
-        } : null
-      }
-    };
-  },
-
-  get_character_roles: async ({ query } = {}) => {
-    const roles = worksData.map(w => ({
-      workTitle: `${w.titleTh} (${w.titleCn})`,
-      year: w.year,
-      role: w.role,
-      roleCn: w.roleCn,
-      youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${w.roleCn || w.role} ${w.titleCn}`)
-    }));
-
-    let filtered = roles;
-    const genericArtistKeywords = ['ju jingyi', 'jujingyi', 'จวีจิ้งอี', 'kiku', 'เสี่ยวจวี', 'kikuuu'];
-    const isGeneric = query && genericArtistKeywords.some(k => query.toLowerCase().trim() === k);
-
-    if (query && !isGeneric) {
-      const q = query.toLowerCase().trim();
-      filtered = roles.filter(r => 
-        (r.role && r.role.toLowerCase().includes(q)) ||
-        (r.roleCn && r.roleCn.includes(query)) ||
-        (r.workTitle && r.workTitle.toLowerCase().includes(q))
-      );
-    }
-
-    filtered.sort((a, b) => (b.year || 0) - (a.year || 0));
-
-    return {
-      status: "success",
-      count: filtered.length,
-      roles: filtered.slice(0, 8)
-    };
-  },
-
-  search_discography: async ({ query, year, type } = {}) => {
-    let list = getCleanDiscography();
-
-    if (year) list = list.filter(s => s.year === Number(year));
-    if (type === 'ost') list = list.filter(s => s.work && s.work !== "Solo Single");
-    if (type === 'single') list = list.filter(s => !s.work || s.work === "Solo Single");
-
-    const genericArtistKeywords = ['ju jingyi', 'jujingyi', 'จวีจิ้งอี', 'kiku', 'เสี่ยวจวี', 'kikuuu', 'เพลง', 'เพลงทั้งหมด', 'เพลงใหม่', 'music', 'song', 'songs'];
-    const isGeneric = query && genericArtistKeywords.some(k => query.toLowerCase().trim() === k);
-
-    if (query && !isGeneric) {
-      const q = query.toLowerCase().trim();
-      list = list.filter(s => 
-        (s.titleTh && s.titleTh.toLowerCase().includes(q)) ||
-        (s.titleCn && s.titleCn.includes(query)) ||
-        (s.titleEn && s.titleEn.toLowerCase().includes(q)) ||
-        (s.work && s.work.toLowerCase().includes(q))
-      );
-    }
-
-    return {
-      status: list.length > 0 ? "success" : "not_found",
-      message: list.length > 0 ? undefined : `No matching discography entries for "${query || 'this filter'}".`,
-      count: list.length,
-      songs: list.slice(0, 8).map(s => ({
-        id: s.id,
-        title: `${s.titleTh} (${s.titleCn})`,
-        titleEn: s.titleEn,
-        year: s.year,
-        type: s.work,
-        duration: s.duration,
-        youtubeUrl: s.youtubeUrl || (s.youtubeId ? buildYouTubeWatchUrl(s.youtubeId) : null),
-        youtubeSearchUrl: s.youtubeSearchUrl || buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${s.titleCn || s.titleTh}`),
-        qqMusicSearchUrl: s.qqMusicSearchUrl || buildQqMusicSearchUrl(`鞠婧祎 ${s.titleCn || s.titleTh}`),
-        bilibiliSearchUrl: s.bilibiliSearchUrl || buildBilibiliSearchUrl(`鞠婧祎 ${s.titleCn || s.titleTh}`)
-      }))
-    };
-  },
-
-  get_music_videos: async ({ category, query } = {}) => {
-    const allMVs = getAllMusicVideos();
-
-    let results = allMVs;
-    if (category) {
-      const catLower = category.toLowerCase();
-      results = results.filter(m => {
-        const mCat = (m.category || '').toLowerCase();
-        if (catLower.includes('mv') || catLower.includes('official')) return mCat.includes('mv') || mCat === 'single' || mCat === 'ost';
-        if (catLower.includes('stage') || catLower.includes('performance')) return mCat.includes('stage');
-        if (catLower.includes('ost')) return mCat === 'ost';
-        if (catLower.includes('single')) return mCat === 'single';
-        return mCat.includes(catLower);
-      });
-    }
-    
-    const genericArtistKeywords = ['ju jingyi', 'jujingyi', 'จวีจิ้งอี', 'kiku', 'เสี่ยวจวี', 'kikuuu', 'mv', 'music video', 'วิดีโอ', 'คลิป'];
-    const isGeneric = query && genericArtistKeywords.some(k => query.toLowerCase().trim() === k);
-    
-    if (query && !isGeneric) {
-      const q = query.toLowerCase().trim();
-      results = results.filter(m => 
-        (m.titleTh && m.titleTh.toLowerCase().includes(q)) || 
-        (m.titleCn && m.titleCn.includes(query)) ||
-        (m.titlePinyin && m.titlePinyin.toLowerCase().includes(q)) ||
-        (m.dramaName && m.dramaName.toLowerCase().includes(q)) ||
-        (m.description && m.description.toLowerCase().includes(q))
-      );
-    }
-
-    return {
-      status: "success",
-      count: results.length,
-      videos: results.slice(0, 8).map(m => {
-        const ytId = m.youtubeId || null;
-        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})`,
-          category: m.category,
-          year: m.releaseYear || m.year,
-          drama: m.dramaName || null,
-          duration: m.duration || null,
-          description: m.description || null,
-          isFeatured: !!m.isFeatured,
-          youtubeUrl: ytId ? buildYouTubeWatchUrl(ytId) : null,
-          youtubeSearchUrl: buildYouTubeSearchUrl(searchTitle),
-          bilibiliSearchUrl: buildBilibiliSearchUrl(`鞠婧祎 ${m.titleCn || m.titleTh}`)
-        };
-      })
-    };
-  },
-
-  get_media_links: async ({ query, category } = {}) => {
-    if (!query) return { status: "error", message: "query parameter is required." };
-    const q = query.toLowerCase().trim();
-
-    const mvs = getAllMusicVideos();
-    const disc = getCleanDiscography();
-    const works = worksData;
-
-    const matchedVideos = mvs.filter(m => 
-      (m.titleTh && m.titleTh.toLowerCase().includes(q)) ||
-      (m.titleCn && m.titleCn.includes(query)) ||
-      (m.titlePinyin && m.titlePinyin.toLowerCase().includes(q)) ||
-      (m.dramaName && m.dramaName.toLowerCase().includes(q))
-    ).map(m => ({
-      type: m.category || 'MV',
-      title: `${m.titleTh} (${m.titleCn})`,
-      year: m.releaseYear || m.year,
-      duration: m.duration,
-      youtubeUrl: m.youtubeId ? buildYouTubeWatchUrl(m.youtubeId) : null,
-      youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${m.titleCn || m.titleTh} ${m.category === 'Stage-Performance' ? 'Stage' : 'Official MV'}`),
-      bilibiliSearchUrl: buildBilibiliSearchUrl(`鞠婧祎 ${m.titleCn || m.titleTh}`)
-    }));
-
-    const matchedSongs = disc.filter(s =>
-      (s.titleTh && s.titleTh.toLowerCase().includes(q)) ||
-      (s.titleCn && s.titleCn.includes(query)) ||
-      (s.titleEn && s.titleEn.toLowerCase().includes(q)) ||
-      (s.work && s.work.toLowerCase().includes(q))
-    ).map(s => ({
-      type: s.work || 'Song',
-      title: `${s.titleTh} (${s.titleCn})`,
-      year: s.year,
-      duration: s.duration,
-      youtubeUrl: s.youtubeUrl || (s.youtubeId ? buildYouTubeWatchUrl(s.youtubeId) : null),
-      youtubeSearchUrl: s.youtubeSearchUrl || buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${s.titleCn || s.titleTh}`),
-      qqMusicSearchUrl: s.qqMusicSearchUrl || buildQqMusicSearchUrl(`鞠婧祎 ${s.titleCn || s.titleTh}`),
-      bilibiliSearchUrl: s.bilibiliSearchUrl || buildBilibiliSearchUrl(`鞠婧祎 ${s.titleCn || s.titleTh}`)
-    }));
-
-    const matchedWorks = works.filter(w =>
-      (w.titleTh && w.titleTh.toLowerCase().includes(q)) ||
-      (w.titleCn && w.titleCn.includes(query)) ||
-      (w.titleEn && w.titleEn.toLowerCase().includes(q))
-    ).map(w => ({
-      type: 'Drama / Series',
-      title: `${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 || ''})`,
-        youtubeUrl: w.themeSong.youtubeId ? buildYouTubeWatchUrl(w.themeSong.youtubeId) : null,
-        youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${w.themeSong.titleCn || w.themeSong.titleTh} OST`)
-      } : null
-    }));
-
-    const generalYouTubeSearch = buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${query}`);
-    const generalBilibiliSearch = buildBilibiliSearchUrl(`鞠婧祎 ${query}`);
-
-    return {
-      status: "success",
-      query,
-      fallbackYouTubeSearch: generalYouTubeSearch,
-      fallbackBilibiliSearch: generalBilibiliSearch,
-      results: {
-        musicVideos: matchedVideos.slice(0, 5),
-        songs: matchedSongs.slice(0, 5),
-        works: matchedWorks.slice(0, 3)
-      }
-    };
-  },
-
-  get_brand_endorsements: async ({ isGlobal, category, year, query } = {}) => {
-    let list = Array.isArray(brandsData) ? [...brandsData] : [...(brandsData.brandList || brandsData.brands || [])];
-
-    if (typeof isGlobal === 'boolean') list = list.filter(b => !!b.isGlobal === isGlobal);
-    if (year) list = list.filter(b => b.year === Number(year));
-    if (category) list = list.filter(b => (b.category && b.category.toLowerCase().includes(category.toLowerCase())) || (b.tier && b.tier.toLowerCase().includes(category.toLowerCase())));
-
-    const genericArtistKeywords = ['ju jingyi', 'jujingyi', 'จวีจิ้งอี', 'kiku', 'เสี่ยวจวี', 'kikuuu', 'แบรนด์', 'พรีเซนเตอร์', 'brand', 'ambassador', 'endorsement', 'commercial'];
-    const isGeneric = query && genericArtistKeywords.some(k => query.toLowerCase().trim() === k);
-
-    if (query && !isGeneric) {
-      const q = query.toLowerCase().trim();
-      const numYear = Number(q);
-      if (!isNaN(numYear) && numYear >= 2013 && numYear <= 2030) {
-        list = list.filter(b => b.year === numYear);
-      } else {
-        list = list.filter(b => 
-          (b.brandNameEn && b.brandNameEn.toLowerCase().includes(q)) ||
-          (b.brandNameCn && b.brandNameCn.includes(query)) ||
-          (b.title && b.title.toLowerCase().includes(q)) ||
-          (b.category && b.category.toLowerCase().includes(q)) ||
-          (b.highlight && b.highlight.toLowerCase().includes(q)) ||
-          (b.tier && b.tier.toLowerCase().includes(q)) ||
-          (b.name && b.name.toLowerCase().includes(q))
-        );
-      }
-    }
-
-    list.sort((a, b) => (b.year || 0) - (a.year || 0));
-
-    return {
-      status: "success",
-      count: list.length,
-      brands: list.slice(0, 8).map(b => ({
-        brand: `${b.brandNameEn || b.brand || b.name} (${b.brandNameCn || ''})`,
-        year: b.year,
-        title: b.title || (b.isGlobal ? 'Global Brand Ambassador' : 'Brand Ambassador'),
-        category: b.category,
-        isGlobal: !!b.isGlobal,
-        highlight: b.highlight || '',
-        youtubeCommercialSearch: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${b.brandNameEn || b.brandNameCn} CF Commercial`)
-      }))
-    };
-  },
-
-  get_career_timeline: async ({ year, era } = {}) => {
-    let eras = Array.isArray(timelineData) ? timelineData : (timelineData.eras || []);
-    if (year) eras = eras.filter(e => e.year == year || (e.period && e.period.includes(String(year))));
-    if (era) eras = eras.filter(e => e.title?.toLowerCase().includes(era.toLowerCase()) || e.era?.includes(era));
-
-    return {
-      status: "success",
-      count: eras.length,
-      milestones: eras.slice(0, 6).map(e => ({
-        period: e.period || e.year,
-        title: `${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,
-        youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${a.titleCn || a.ceremony}`)
-      }))
-    };
-  },
-
-  get_social_feed: async ({ platform, limit = 4 } = {}) => {
-    let posts = socialUpdatesData.cards || [];
-    if (platform && platform !== 'all') posts = posts.filter(p => p.platform?.toLowerCase() === platform.toLowerCase());
-
-    return {
-      status: "success",
-      count: Math.min(posts.length, Number(limit) || 4),
-      posts: posts.slice(0, Number(limit) || 4).map(p => ({
-        platform: p.platform,
-        date: p.date,
-        content: p.content?.slice(0, 120) + '...',
-        likes: p.likes
-      }))
-    };
-  },
-
-  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,
-        category: p.category,
-        year: p.era || p.year
-      }))
-    };
-  },
-
-  global_search: async ({ query }) => {
-    if (!query) return { status: "error", message: "Query parameter is required." };
-    const q = query.toLowerCase();
-    const ignoredTerms = new Set(['the', 'from', 'what', 'are', 'drama', 'ost', 'song', 'songs', 'soundtrack', 'music']);
-    const terms = q.split(/[^\p{L}\p{N}]+/u).filter(term => term.length > 2 && !ignoredTerms.has(term));
-    const matchesQuery = (...values) => {
-      const haystack = values.filter(Boolean).join(' ').toLowerCase();
-      return haystack.includes(q) || (terms.length > 0 && terms.every(term => haystack.includes(term)));
-    };
-
-    const matchedWorks = worksData.filter(w =>
-      matchesQuery(w.titleTh, w.titleEn, w.titleCn, w.role, w.roleCn)
-    ).slice(0, 4).map(w => ({
-      title: `${w.titleTh} (${w.year}) - Role: ${w.role}`,
-      trailerYouTubeSearch: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${w.titleCn || w.titleEn} Trailer`)
-    }));
-
-    const disc = getCleanDiscography();
-    const matchedSongs = disc.filter(s =>
-      matchesQuery(s.titleTh, s.titleEn, s.titleCn, s.work, s.role)
-    ).slice(0, 4).map(s => ({
-      title: `${s.titleTh} (${s.year})`,
-      youtubeUrl: s.youtubeUrl || null,
-      youtubeSearchUrl: s.youtubeSearchUrl
-    }));
-
-    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}]`,
-      youtubeUrl: m.youtubeId ? buildYouTubeWatchUrl(m.youtubeId) : null,
-      youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${m.titleCn || m.titleTh}`)
-    }));
-
-    const brands = Array.isArray(brandsData) ? (brandsData.brandList || []) : (brandsData.brands || []);
-    const matchedBrands = brands.filter(b =>
-      matchesQuery(b.brandNameEn, b.brandNameCn, b.name, b.title)
-    ).slice(0, 4).map(b => `${b.brandNameEn || b.name} (${b.year}) - ${b.title}`);
-
-    const count = matchedWorks.length + matchedSongs.length + mvs.length + matchedBrands.length;
-    return {
-      status: count > 0 ? "success" : "not_found",
-      message: count > 0 ? undefined : `No local catalog matches for "${query}". Use web_search for external results.`,
-      query,
-      count,
-      results: {
-        musicVideos: mvs,
-        works: matchedWorks,
-        songs: matchedSongs,
-        brands: matchedBrands,
-        youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${query}`)
-      }
-    };
-  },
-
-  web_search: async ({ query } = {}) => {
-    return await searchWeb(query);
-  },
-
-  fetch_webpage: async ({ url } = {}) => {
-    return await fetchWebpage(url);
-  },
-
-  fetch_api: async ({ endpoint, query, baseUrl } = {}) => {
-    if (!endpoint) return { status: "error", message: "endpoint parameter is required (e.g. 'profile', 'works', 'search')" };
-    const base = (baseUrl || 'https://jujingyi-kikuuu.vercel.app/api/v1').replace(/\/$/, '');
-    const path = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
-    let url = `${base}${path}`;
-    if (query) url += `?q=${encodeURIComponent(query)}`;
-
-    try {
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), 10000);
-      const res = await fetch(url, {
-        headers: { 'Accept': 'application/json', 'User-Agent': 'KikuAgent/1.0' },
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-
-      if (!res.ok) {
-        return { status: "error", message: `HTTP ${res.status} from ${url}` };
-      }
-
-      const json = await res.json();
-
-      const data = json.data || json;
-      return {
-        status: "success",
-        endpoint: path,
-        count: Array.isArray(data) ? data.length : undefined,
-        data
-      };
-    } catch (err) {
-      return {
-        status: "error",
-        endpoint: path,
-        message: err.name === 'AbortError' ? 'API request timed out' : err.message
-      };
-    }
-  },
-
-  fetch_json: async ({ url, method, headers, body } = {}) => {
-    return await fetchJson(url, { method, headers, body });
-  },
-
-  read_local_file: async ({ path: filePath, maxLines = 200 } = {}) => {
-    if (!filePath) return { status: 'error', message: 'path parameter is required.' };
-    try {
-      const projectRoot = process.cwd();
-      const resolved = resolve(projectRoot, filePath);
-      const relativePath = relative(projectRoot, resolved);
-
-      if (relativePath.startsWith('..') || relativePath.includes('..')) {
-        return { status: 'error', message: 'Path must be within the project directory.' };
-      }
-
-      const fileStat = await stat(resolved);
-      if (!fileStat.isFile()) {
-        return { status: 'error', message: `"${filePath}" is not a file.` };
-      }
-
-      if (fileStat.size > 500000) {
-        return { status: 'error', message: `File too large (${Math.round(fileStat.size / 1024)}KB). Use maxLines to read a portion.` };
-      }
-
-      const content = await readFile(resolved, 'utf-8');
-      const lines = content.split('\n');
-      const totalLines = lines.length;
-      const truncated = totalLines > maxLines;
-      const readContent = truncated ? lines.slice(0, maxLines).join('\n') : content;
-
-      return {
-        status: 'success',
-        path: relativePath,
-        sizeBytes: fileStat.size,
-        totalLines,
-        linesRead: Math.min(totalLines, maxLines),
-        truncated,
-        content: truncated ? readContent + `\n\n... [Showing first ${maxLines} of ${totalLines} lines]` : readContent
-      };
-    } catch (err) {
-      if (err.code === 'ENOENT') {
-        return { status: 'error', message: `File not found: "${filePath}"` };
-      }
-      return { status: 'error', message: err.message };
-    }
-  },
-
-  list_directory: async ({ path: dirPath = '.', recursive = false } = {}) => {
-    try {
-      const projectRoot = process.cwd();
-      const resolved = resolve(projectRoot, dirPath);
-      const relativePath = relative(projectRoot, resolved);
-
-      if (relativePath.startsWith('..') || relativePath.includes('..')) {
-        return { status: 'error', message: 'Path must be within the project directory.' };
-      }
-
-      async function listDir(dir, depth = 0) {
-        if (depth > (recursive ? 3 : 0)) return [];
-        const entries = await readdir(dir, { withFileTypes: true });
-        const items = [];
-
-        for (const entry of entries) {
-          if (entry.name.startsWith('.') && entry.name !== '.env.example') continue;
-          if (entry.name === 'node_modules' || entry.name === '.git') continue;
-          if (entry.name === 'dist' || entry.name === 'build') continue;
-
-          const entryPath = join(dir, entry.name);
-          const entryRelative = relative(projectRoot, entryPath);
-
-          if (entry.isDirectory()) {
-            items.push({ name: entry.name, type: 'directory', path: entryRelative });
-            if (recursive && depth < 3) {
-              const children = await listDir(entryPath, depth + 1);
-              items.push(...children);
-            }
-          } else {
-            const fileStat = await stat(entryPath).catch(() => null);
-            items.push({
-              name: entry.name,
-              type: 'file',
-              path: entryRelative,
-              sizeBytes: fileStat?.size || 0
-            });
-          }
-        }
-
-        items.sort((a, b) => {
-          if (a.type !== b.type) return a.type === 'directory' ? -1 : 1;
-          return a.name.localeCompare(b.name);
-        });
-
-        return items;
-      }
-
-      const items = await listDir(resolved);
-      return {
-        status: 'success',
-        path: relativePath || '.',
-        count: items.length,
-        items
-      };
-    } catch (err) {
-      if (err.code === 'ENOENT') {
-        return { status: 'error', message: `Directory not found: "${dirPath}"` };
-      }
-      return { status: 'error', message: err.message };
-    }
-  },
-
-  screenshot_webpage: async ({ url, width, height } = {}) => {
-    return await screenshotWebpage(url, { width, height });
-  },
-
-  web_extract: async ({ query, maxResults, allowedDomains } = {}) => {
-    return await webExtract(query, { maxResults, allowedDomains });
-  },
-
-  get_system_stats: async () => {
-    const disc = getCleanDiscography();
-    const brands = brandsData?.brandList || brandsData?.brands || (Array.isArray(brandsData) ? brandsData : []);
-    const awards = Array.isArray(awardsData) ? awardsData : (awardsData?.awards || []);
-    const timeline = Array.isArray(timelineData) ? timelineData : (timelineData?.eras || []);
-    const mvs = getAllMusicVideos();
-
-    return {
-      status: "success",
-      stats: {
-        artistName: profileData.nameTh,
-        artistNameCn: profileData.nameCn,
-        totalWorks: worksData.length,
-        totalUniqueSongs: disc.length,
-        totalMusicVideosAndStages: mvs.length,
-        brandEndorsements: brands.length,
-        totalAwards: awards.length,
-        timelineMilestones: timeline.length,
-        activeYears: "2013 - Present (2026)",
-        featured2026Works: ["Veil of Shadows (月鳞绮纪)", "The Eternal Fragrance (千香)", "Wanhua Sin (万华世界)"],
-        youtubeOfficialHub: buildYouTubeSearchUrl("Ju Jingyi 鞠婧祎")
-      }
-    };
-  },
-
-  play_music: async (args) => {
-    try {
-      const query = args.query || '';
-
-      const hasArtist = /jujingyi|จวีจิ้งอี|鞠婧祎/i.test(query);
-      const isUrl = /^https?:\/\//.test(query);
-      const searchQuery = (!hasArtist && !isUrl) ? `Ju Jingyi ${query}` : query;
-      const result = await audioPlayer.play(searchQuery);
-      return { status: 'success', message: result, playing: args.query };
-    } catch (err) {
-      return { status: 'error', message: err.message };
-    }
-  },
-
-  stop_music: async () => {
-    const result = await audioPlayer.stop();
-    return { status: 'success', message: result };
-  },
-
-  mute_music: async () => {
-    const result = await audioPlayer.mute();
-    return { status: 'success', message: result };
-  },
-
-  unmute_music: async () => {
-    const result = await audioPlayer.unmute();
-    return { status: 'success', message: result };
-  },
-
-  pause_music: async () => {
-    const result = await audioPlayer.pause();
-    return { status: 'success', message: result };
-  },
-
-  resume_music: async () => {
-    const result = await audioPlayer.resume();
-    return { status: 'success', message: result };
-  },
-
-  next_track: async () => {
-    const result = await audioPlayer.next();
-    return { status: 'success', message: result };
-  },
-
-  prev_track: async () => {
-    const result = await audioPlayer.prev();
-    return { status: 'success', message: result };
-  },
-
-  add_to_queue: async (args) => {
-    const result = await audioPlayer.addToQueue(args.query);
-    return { status: 'success', message: result };
-  },
-
-  remove_from_queue: async (args) => {
-    const result = await audioPlayer.removeFromQueue(args.index);
-    return { status: 'success', message: result };
-  },
-
-  clear_queue: async () => {
-    const result = await audioPlayer.clearQueue();
-    return { status: 'success', message: result };
-  },
-
-  get_queue: async () => {
-    const queue = audioPlayer.getQueue();
-    return { status: 'success', queue };
-  },
-
-  search_youtube: async (args) => {
-    try {
-      const results = await audioPlayer.searchYouTube(args.query);
-      return { status: 'success', query: args.query, results };
-    } catch (err) {
-      return { status: 'error', message: err.message };
-    }
-  },
-
-  get_current_track: async () => {
-    const state = audioPlayer.getFullState();
-    return { status: 'success', ...state };
-  },
-
-  get_music_status: async () => {
-    const state = audioPlayer.getFullState();
-    return { status: 'success', ...state };
-  }
-};
-
-const toolSchemaByName = new Map(
-  toolsSchema.map(tool => [tool.function.name, tool.function.parameters || { type: 'object', properties: {} }])
-);
-
-function coerceToolValue(value, schema = {}) {
-  if (value == null || !schema.type) return { ok: true, value };
-
-  if (schema.type === 'string') {
-    if (typeof value === 'string') return { ok: true, value };
-    if (['number', 'boolean'].includes(typeof value)) return { ok: true, value: String(value), coerced: true };
-    return { ok: false };
-  }
-  if (schema.type === 'number' || schema.type === 'integer') {
-    const parsed = typeof value === 'number' ? value : Number(value);
-    if (!Number.isFinite(parsed)) return { ok: false };
-    return { ok: true, value: schema.type === 'integer' ? Math.trunc(parsed) : parsed, coerced: typeof value !== 'number' };
-  }
-  if (schema.type === 'boolean') {
-    if (typeof value === 'boolean') return { ok: true, value };
-    if (value === 'true' || value === '1' || value === 1) return { ok: true, value: true, coerced: true };
-    if (value === 'false' || value === '0' || value === 0) return { ok: true, value: false, coerced: true };
-    return { ok: false };
-  }
-  if (schema.type === 'array') {
-    if (!Array.isArray(value)) return { ok: false };
-    const converted = [];
-    for (const item of value) {
-      const checked = coerceToolValue(item, schema.items || {});
-      if (!checked.ok) return { ok: false };
-      converted.push(checked.value);
-    }
-    return { ok: true, value: converted };
-  }
-  if (schema.type === 'object') return { ok: !!value && typeof value === 'object' && !Array.isArray(value), value };
-  return { ok: true, value };
-}
-
-export function prepareToolArguments(toolName, rawArgs = {}) {
-  const schema = toolSchemaByName.get(toolName);
-  if (!schema) {
-    return { safe: false, args: {}, warnings: [], error: `Unknown tool "${toolName}".` };
-  }
-
-  let parsedArgs = rawArgs;
-  if (typeof rawArgs === 'string') {
-    const trimmed = rawArgs.trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '');
-    if (!trimmed) parsedArgs = {};
-    else {
-      try { parsedArgs = JSON.parse(trimmed); }
-      catch (error) {
-        return { safe: false, args: {}, warnings: [], error: `Invalid JSON arguments: ${error.message}` };
-      }
-    }
-  }
-
-  if (!parsedArgs || typeof parsedArgs !== 'object' || Array.isArray(parsedArgs)) {
-    return { safe: false, args: {}, warnings: [], error: 'Tool arguments must be a JSON object.' };
-  }
-
-  const properties = schema.properties || {};
-  const required = new Set(schema.required || []);
-  const validated = {};
-  const warnings = [];
-
-  for (const requiredName of required) {
-    if (parsedArgs[requiredName] == null || parsedArgs[requiredName] === '') {
-      return { safe: false, args: {}, warnings, error: `Missing required argument "${requiredName}".` };
-    }
-  }
-
-  for (const [name, value] of Object.entries(parsedArgs)) {
-    const propertySchema = properties[name];
-    if (!propertySchema) {
-      warnings.push(`Unknown argument "${name}" was ignored`);
-      continue;
-    }
-    const checked = coerceToolValue(value, propertySchema);
-    if (!checked.ok) {
-      return { safe: false, args: {}, warnings, error: `Argument "${name}" must be ${propertySchema.type || 'valid'}.` };
-    }
-    if (propertySchema.enum && !propertySchema.enum.includes(checked.value)) {
-      return { safe: false, args: {}, warnings, error: `Argument "${name}" must be one of: ${propertySchema.enum.join(', ')}.` };
-    }
-    if (checked.coerced) warnings.push(`Argument "${name}" was converted to ${propertySchema.type}`);
-    validated[name] = checked.value;
-  }
-
-  const sanitizedResult = sanitizeToolArgs(toolName, validated);
-  if (!sanitizedResult.safe) {
-    return { safe: false, args: {}, warnings: [...warnings, ...sanitizedResult.warnings], error: sanitizedResult.warnings.join('; ') };
-  }
-  return { safe: true, args: sanitizedResult.sanitized, warnings: [...warnings, ...sanitizedResult.warnings], error: null };
-}
-
-export function normalizeToolResult(toolName, result) {
-  if (result == null) return { status: 'error', message: `Tool "${toolName}" returned no result.` };
-  if (typeof result !== 'object' || Array.isArray(result)) return { status: 'success', data: result };
-
-  const normalized = { ...result };
-  if (!normalized.status) normalized.status = normalized.error ? 'error' : 'success';
-  if (normalized.error && !normalized.message) normalized.message = String(normalized.error);
-  if (normalized.status === 'success' && (normalized.count === 0 || normalized.returnedCount === 0)) {
-    normalized.status = 'not_found';
-    if (!normalized.message) normalized.message = 'No matching data found.';
-  }
-  return normalized;
-}
-
-export async function executeTool(toolName, args = {}, options = {}) {
-  const handler = toolHandlers[toolName];
-  if (!handler) {
-    return {
-      status: "error",
-      message: `Unknown tool "${toolName}". Available tools: ${Object.keys(toolHandlers).join(', ')}`
-    };
-  }
-
-  try {
-    const prepared = prepareToolArguments(toolName, args);
-    if (!prepared.safe) {
-      return {
-        status: 'error',
-        message: `Input rejected: ${prepared.error}`,
-        validationWarnings: prepared.warnings,
-      };
-    }
-
-    const configuredTimeout = Number(options.timeoutMs ?? process.env.KIKU_TOOL_TIMEOUT_MS ?? 45_000);
-    const timeoutMs = Number.isFinite(configuredTimeout) && configuredTimeout > 0 ? configuredTimeout : 45_000;
-    let timeoutId;
-    const timeoutPromise = new Promise((_, reject) => {
-      timeoutId = setTimeout(() => reject(new Error(`Timed out after ${timeoutMs}ms`)), timeoutMs);
-    });
-    let result;
-    try {
-      result = await Promise.race([Promise.resolve(handler(prepared.args)), timeoutPromise]);
-    } finally {
-      clearTimeout(timeoutId);
-    }
-
-    const normalized = normalizeToolResult(toolName, result);
-    if (prepared.warnings.length > 0) {
-      normalized.validationWarnings = prepared.warnings;
-    }
-    return normalized;
-  } catch (err) {
-    return {
-      status: "error",
-      message: `Failed executing tool "${toolName}": ${err.message}`
-    };
-  }
-}
+import { profileData } from '../../src/data/profileData.js';
+import { worksData } from '../../src/data/worksData.js';
+import { discographyData } from '../../src/data/discographyData.js';
+import { musicVideoData } from '../../src/data/musicVideoData.js';
+import { brandsData } from '../../src/data/brandsData.js';
+import { socialUpdatesData } from '../../src/data/socialUpdatesData.js';
+import { galleryData } from '../../src/data/galleryData.js';
+import { awardsData } from '../../src/data/awardsData.js';
+import { timelineData } from '../../src/data/timelineData.js';
+import { searchWeb, fetchWebpage, fetchJson, screenshotWebpage, webExtract } from './webSearch.js';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, relative, extname, resolve } from 'node:path';
+import { audioPlayer } from './audioPlayer.js';
+import { sanitizeToolArgs } from './sanitizer.js';
+import { getGpuMetrics } from './gpuMetrics.js';
+
+export function buildYouTubeSearchUrl(query) {
+  return `https://www.youtube.com/results?search_query=${encodeURIComponent(query)}`;
+}
+
+export function buildYouTubeWatchUrl(videoId) {
+  return videoId ? `https://www.youtube.com/watch?v=${videoId}` : null;
+}
+
+export function buildBilibiliSearchUrl(query) {
+  return `https://search.bilibili.com/all?keyword=${encodeURIComponent(query)}`;
+}
+
+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)}`;
+}
+
+function getCleanDiscography() {
+  const map = new Map();
+  const allTracks = [
+    ...(discographyData.latestReleases || []),
+    ...(discographyData.ostList || []),
+    ...(discographyData.singles || [])
+  ];
+
+  for (const track of allTracks) {
+    const key = track.titleCn || track.titleTh;
+    if (!map.has(key)) {
+      const ytId = track.youtubeId || null;
+      const searchTerms = `Ju Jingyi 鞠婧祎 ${track.titleCn || track.titleTh || track.titleEn || ''}`;
+      map.set(key, {
+        id: track.id,
+        titleTh: track.titleTh,
+        titleCn: track.titleCn,
+        titleEn: track.titleEn || '',
+        year: track.year,
+        work: track.work || "Solo Single",
+        duration: track.duration || track.trackDuration || '',
+        theme: track.theme || "Pop / Ballad",
+        youtubeId: ytId,
+        youtubeUrl: track.youtubeUrl || buildYouTubeWatchUrl(ytId),
+        youtubeSearchUrl: buildYouTubeSearchUrl(searchTerms),
+        qqMusicSearchUrl: buildQqMusicSearchUrl(`鞠婧祎 ${track.titleCn || track.titleTh}`),
+        bilibiliSearchUrl: buildBilibiliSearchUrl(`鞠婧祎 ${track.titleCn || track.titleTh}`)
+      });
+    }
+  }
+
+  return Array.from(map.values()).sort((a, b) => (b.year || 0) - (a.year || 0));
+}
+
+function getAllMusicVideos() {
+  if (Array.isArray(musicVideoData)) {
+    return musicVideoData;
+  }
+  return [
+    ...(musicVideoData.officialMvs || []).map(m => ({ ...m, category: 'Official MV' })),
+    ...(musicVideoData.stagePerformances || []).map(m => ({ ...m, category: 'Stage Performance' }))
+  ];
+}
+
+export const toolsSchema = [
+  {
+    type: "function",
+    function: {
+      name: "get_profile_and_fandom",
+      description: "Get Ju Jingyi's biographical profile, Chinese/English/Thai names, birthday, birthplace, Miju (蜜橘) fan community, official slogan, and socials.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_quotes",
+      description: "Retrieve inspiring quotes and famous statements made by Ju Jingyi (with Thai translation and Chinese text).",
+      parameters: {
+        type: "object",
+        properties: {
+          tag: { type: "string", description: "Optional tag (mindset, growth, acting, fandom)" }
+        },
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "search_works",
+      description: "Search Ju Jingyi's filmography (TV dramas, web series, movies, and 2026/2025 upcoming projects) with official streaming links and YouTube trailer search links.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Search keyword for drama title or character name." },
+          year: { type: "number", description: "Specific release year (e.g. 2026, 2025, 2024, 2023). Leave empty to get newest." },
+          category: { type: "string", description: "Category filter (e.g. 'series', 'movie', 'upcoming')." },
+          featuredOnly: { type: "boolean", description: "Filter only featured major hit dramas." }
+        },
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_work_detail",
+      description: "Get full details of a specific drama or film by ID or title (synopsis, role, OST with YouTube links, episode count, platform, rating).",
+      parameters: {
+        type: "object",
+        properties: {
+          workIdOrTitle: { type: "string", description: "ID or title of drama (e.g. 'veil-of-shadows', 'in-blossom', 'legend-of-white-snake')" }
+        },
+        required: ["workIdOrTitle"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_character_roles",
+      description: "List and search famous fictional character roles portrayed by Ju Jingyi in dramas and movies (e.g. Yang Caiwei, Lu Wuyi, Bai Suzhen, Han Yunxi).",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Optional role name or drama title keyword" }
+        },
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "search_discography",
+      description: "Search Ju Jingyi's songs, singles, and OST drama soundtracks. Returns verified direct YouTube watch links (https://www.youtube.com/watch?v=...), real YouTube search queries (https://www.youtube.com/results?search_query=...), and music streaming links.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Song title keyword (Thai, Chinese, or English)" },
+          year: { type: "number", description: "Release year" },
+          type: { type: "string", enum: ["all", "ost", "single"] }
+        },
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_music_videos",
+      description: "Retrieve music videos (MV), stage performances, and dance practices with verified direct YouTube links and YouTube search query URLs.",
+      parameters: {
+        type: "object",
+        properties: {
+          category: { type: "string", description: "Category (Official MV, Stage Performance, OST, Single)" },
+          query: { type: "string", description: "Keyword matching title, song, or event" }
+        },
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_media_links",
+      description: "Get direct YouTube video watch links (watch?v=...), official YouTube search queries (results?search_query=...), Bilibili links, and streaming URLs for any Ju Jingyi song, MV, live stage, or drama trailer.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Song, drama, stage, or MV name (e.g. 'FIND THE WAY', 'Rain Love', 'Hong Zhao Yuan', 'In Blossom', 'Veil of Shadows', 'Luo Hua Cheng Ni')" },
+          category: { type: "string", enum: ["all", "mv", "stage", "ost", "single", "trailer"], description: "Optional media type filter" }
+        },
+        required: ["query"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_brand_endorsements",
+      description: "Retrieve brand endorsements, commercial ambassadorships, luxury fashion, and beauty partnerships of Ju Jingyi.",
+      parameters: {
+        type: "object",
+        properties: {
+          isGlobal: { type: "boolean", description: "Filter for Global Brand Ambassador roles" },
+          year: { type: "number", description: "Year of endorsement (e.g. 2026, 2025, 2024). Leave empty for latest." },
+          category: { type: "string", description: "Category filter (Luxury, Beauty, FMCG, Tech)" },
+          query: { type: "string", description: "Brand name keyword or search term" }
+        },
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_career_timeline",
+      description: "Explore Ju Jingyi's career milestones and chronological eras (SNH48 Era, Solo Studio, Breakthrough Dramas, Present).",
+      parameters: {
+        type: "object",
+        properties: {
+          year: { type: "number", description: "Year filter (2013-2026)" },
+          era: { type: "string", description: "Era keyword" }
+        },
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_awards",
+      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" }
+        },
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_social_feed",
+      description: "Get recent social media updates from Weibo and Douyin.",
+      parameters: {
+        type: "object",
+        properties: {
+          platform: { type: "string", enum: ["all", "weibo", "douyin"] },
+          limit: { type: "number", description: "Number of posts (default 4)" }
+        },
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_gallery_photos",
+      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)" }
+        },
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "global_search",
+      description: "Universal search across ALL Ju Jingyi entities (works, songs, roles, brands, awards, videos) with YouTube and media links.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Search term to match across all collections" }
+        },
+        required: ["query"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "web_search",
+      description: "Search the LIVE internet for real-time news, recent updates, social media trends, Weibo topics, or external info about Ju Jingyi and entertainment topics.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Search query keyword" }
+        },
+        required: ["query"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "fetch_webpage",
+      description: "Fetch and read the text content of a specific public web page URL. Returns extracted text — read the content field carefully and extract specific facts (names, dates, titles, descriptions) for your answer. NOTE: This cannot read SPA/React sites — use fetch_api for jujingyi-kikuuu.vercel.app.",
+      parameters: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "The full http/https URL of the web page to read" }
+        },
+        required: ["url"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "fetch_api",
+      description: "Query the Ju Jingyi Official REST API (jujingyi-kikuuu.vercel.app/api/v1) for structured JSON data. Use this instead of fetch_webpage when the user shares a link to the platform site, or when you need live/verified data from the official API.",
+      parameters: {
+        type: "object",
+        properties: {
+          endpoint: { type: "string", description: "API endpoint path (e.g. 'profile', 'works', 'music', 'commercial', 'milestones', 'honors', 'social', 'search', 'stats', 'quotes', 'fandom', 'character-roles', 'gallery')" },
+          query: { type: "string", description: "Optional search/filter query parameter" },
+          baseUrl: { type: "string", description: "Optional override base URL (defaults to https://jujingyi-kikuuu.vercel.app/api/v1)" }
+        },
+        required: ["endpoint"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "fetch_json",
+      description: "Fetch data from any REST API or JSON endpoint. Returns parsed JSON data with status code, headers, and content. Use for public APIs, weather, translation, definitions, or any JSON-based service.",
+      parameters: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "The full HTTP/HTTPS URL of the JSON API endpoint" },
+          method: { type: "string", enum: ["GET", "POST", "PUT", "PATCH", "DELETE"], description: "HTTP method (default GET)" },
+          headers: { type: "object", description: "Optional custom headers as key-value pairs" },
+          body: { description: "Optional request body (for POST/PUT/PATCH). Can be a JSON object or string." }
+        },
+        required: ["url"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "read_local_file",
+      description: "Read the contents of a local file in the project directory. Use for reading source code, config files, data files, markdown docs, etc. Returns the text content with file metadata.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "Relative file path from project root (e.g. 'package.json', 'src/App.jsx', 'README.md')" },
+          maxLines: { type: "number", description: "Maximum number of lines to read (default 200). Use for large files." }
+        },
+        required: ["path"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "list_directory",
+      description: "List files and subdirectories in a project directory. Use to explore project structure, find files, or understand codebase layout.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "Relative directory path from project root (e.g. 'src', 'server/agent', '.')" },
+          recursive: { type: "boolean", description: "If true, list recursively (max 3 levels deep). Default false." }
+        },
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "screenshot_webpage",
+      description: "Take a screenshot of a webpage using Chrome headless. Returns base64 PNG image data. Requires Google Chrome installed. Use for visual verification of pages, layouts, or UI elements.",
+      parameters: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "The full HTTP/HTTPS URL to screenshot" },
+          width: { type: "number", description: "Viewport width in pixels (default 1280)" },
+          height: { type: "number", description: "Viewport height in pixels (default 800)" }
+        },
+        required: ["url"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "web_extract",
+      description: "Auto-crawl: search the web AND fetch+extract content from top results in one call. Returns structured page data (meta, headings, paragraphs, links, images) from each result. Use when you need comprehensive info from multiple sources on a topic.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Search query to find and extract content about" },
+          maxResults: { type: "number", description: "Max pages to fetch (default 3, max 5). More = slower but more comprehensive." },
+          allowedDomains: { type: "array", items: { type: "string" }, description: "Only fetch from these domains (e.g. ['wikipedia.org', 'youtube.com']). Empty = all domains." }
+        },
+        required: ["query"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_system_stats",
+      description: "Get high-level summary metrics of the entire Ju Jingyi database.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "play_music",
+      description: "Play a specific song, OST, or music video audio directly in the user's terminal.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "The name of the song and artist (e.g., 'Ju Jingyi FIND THE WAY', 'In Blossom OST Ju Jingyi')"
+          }
+        },
+        required: ["query"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "stop_music",
+      description: "Stop the currently playing music.",
+      parameters: { type: "object", properties: {} }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "mute_music",
+      description: "Mute the currently playing music.",
+      parameters: { type: "object", properties: {} }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "unmute_music",
+      description: "Unmute the currently playing music.",
+      parameters: { type: "object", properties: {} }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "pause_music",
+      description: "Pause the currently playing music.",
+      parameters: { type: "object", properties: {} }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "resume_music",
+      description: "Resume paused music.",
+      parameters: { type: "object", properties: {} }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "next_track",
+      description: "Skip to the next track in the queue.",
+      parameters: { type: "object", properties: {} }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "prev_track",
+      description: "Go back to the previous track in the queue.",
+      parameters: { type: "object", properties: {} }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "add_to_queue",
+      description: "Add a song to the playback queue.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "The name of the song and artist to queue."
+          }
+        },
+        required: ["query"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "remove_from_queue",
+      description: "Remove a song from the queue by index.",
+      parameters: {
+        type: "object",
+        properties: {
+          index: {
+            type: "number",
+            description: "0-based index of the song in the queue to remove."
+          }
+        },
+        required: ["index"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "clear_queue",
+      description: "Clear the entire playback queue and stop music.",
+      parameters: { type: "object", properties: {} }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_queue",
+      description: "Get the current playback queue list.",
+      parameters: { type: "object", properties: {} }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "search_youtube",
+      description: "Search YouTube for music videos or audio and return top results.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "Search query for YouTube."
+          }
+        },
+        required: ["query"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_current_track",
+      description: "Get information about the currently playing or paused track.",
+      parameters: { type: "object", properties: {} }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_music_status",
+      description: "Get full music player status including playing state, current track, and queue info.",
+      parameters: { type: "object", properties: {} }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "run_subagent",
+      description: "Spawn an isolated research subagent with dedicated tool calling capabilities to investigate a specific Ju Jingyi research task or subtopic and return an evidence report.",
+      parameters: {
+        type: "object",
+        properties: {
+          task: { type: "string", description: "The specific research task or question to delegate to the subagent." }
+        },
+        required: ["task"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "run_deep_research",
+      description: "Run multi-worker research orchestrator (3 parallel subagents: local catalog, live web sources, and independent verifier) to comprehensively research a complex question and synthesize a cited answer.",
+      parameters: {
+        type: "object",
+        properties: {
+          question: { type: "string", description: "The complex question requiring multi-angle research." }
+        },
+        required: ["question"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "verify_claim",
+      description: "Verify a claim, rumor, cast leak, or unconfirmed news about Ju Jingyi across official catalog and web corroboration, returning a strict verdict (VERIFIED, UNVERIFIED, CONFLICTING, or FALSE) with sources.",
+      parameters: {
+        type: "object",
+        properties: {
+          claim: { type: "string", description: "The statement, rumor, or claim to verify." }
+        },
+        required: ["claim"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "manage_skill",
+      description: "Learn or manage persistent response skills and persona preferences for Kiku AI (e.g. learning 'ตอบภาษาไทยแบบสั้นกระชับ', listing skills, toggling on/off, removing or clearing skills).",
+      parameters: {
+        type: "object",
+        properties: {
+          action: {
+            type: "string",
+            enum: ["learn", "list", "remove", "clear", "enable", "disable"],
+            description: "The skill action to perform."
+          },
+          instruction: {
+            type: "string",
+            description: "The response instruction to learn (required for 'learn')."
+          },
+          skillId: {
+            type: "string",
+            description: "The ID of the skill to remove (required for 'remove')."
+          }
+        },
+        required: ["action"]
+      }
+    }
+  }
+];
+
+export const toolHandlers = {
+  get_profile_and_fandom: async () => {
+    const d = profileData.details || {};
+    return {
+      status: "success",
+      profile: {
+        nameTh: profileData.nameTh,
+        nameCn: profileData.nameCn,
+        nameEn: profileData.nameEn,
+        nickname: profileData.nickname,
+        birthDate: d.birthDate,
+        birthPlace: d.birthPlace,
+        height: d.height,
+        bloodType: d.bloodType,
+        zodiac: d.zodiac,
+        education: d.education,
+        debutDate: d.debutDate,
+        graduationDate: d.graduationDate,
+        currentStatus: d.currentStatus,
+        hobbies: d.hobbies,
+        favoriteFoods: d.favoriteFoods,
+        talentsSummary: d.talentsSummary,
+        fandomName: d.fandomName || "มี่จวี (Miju / 蜜橘)",
+        fandomColor: d.fandomColorName || "ฟ้าคริสตัล & ชมพูซากุระ",
+        slogan: profileData.motto || "保持热爱，奔赴山海",
+        youtubeSearchUrl: buildYouTubeSearchUrl("Ju Jingyi 鞠婧祎")
+      }
+    };
+  },
+
+  get_quotes: async ({ tag } = {}) => {
+    let quotes = profileData.quotes || [];
+    if (tag) {
+      const qLower = tag.toLowerCase();
+      quotes = quotes.filter(q => 
+        (q.tag && q.tag.toLowerCase().includes(qLower)) ||
+        (q.textTh && q.textTh.toLowerCase().includes(qLower)) ||
+        (q.textCn && q.textCn.includes(tag))
+      );
+    }
+    return {
+      status: "success",
+      count: quotes.length,
+      quotes: quotes.slice(0, 5).map(q => ({
+        textTh: q.textTh,
+        textCn: q.textCn,
+        tag: q.tag,
+        context: q.context
+      }))
+    };
+  },
+
+  search_works: async ({ query, year, category, featuredOnly } = {}) => {
+    let results = [...worksData];
+
+    if (year) results = results.filter(w => w.year === Number(year));
+    if (category && category !== 'all') results = results.filter(w => w.category === category);
+
+    const genericArtistKeywords = ['ju jingyi', 'jujingyi', 'จวีจิ้งอี', 'kiku', 'เสี่ยวจวี', 'kikuuu', 'ศิลปิน', 'ดารา', 'งานล่าสุด', 'ผลงานล่าสุด', 'ล่าสุด', 'latest', 'newest', 'recent', 'upcoming', 'ละคร'];
+    const isGenericArtistQuery = query && genericArtistKeywords.some(k => query.toLowerCase().trim() === k);
+
+    if (query && !isGenericArtistQuery) {
+      const q = query.toLowerCase().trim();
+      results = results.filter(w => 
+        (w.titleTh && w.titleTh.toLowerCase().includes(q)) ||
+        (w.titleEn && w.titleEn.toLowerCase().includes(q)) ||
+        (w.titleCn && w.titleCn.includes(query)) ||
+        (w.role && w.role.toLowerCase().includes(q)) ||
+        (w.roleCn && w.roleCn.includes(query))
+      );
+    }
+
+    if (featuredOnly && results.some(w => !!w.featured)) {
+      results = results.filter(w => !!w.featured);
+    }
+
+    results.sort((a, b) => (b.year || 0) - (a.year || 0));
+
+    return {
+      status: "success",
+      count: results.length,
+      works: results.slice(0, 6).map(w => {
+        const titleSearch = `Ju Jingyi 鞠婧祎 ${w.titleCn || w.titleEn || w.titleTh}`;
+        const themeSongYtId = w.themeSong?.youtubeId || null;
+        return {
+          id: w.id,
+          titleTh: w.titleTh,
+          titleCn: w.titleCn,
+          titleEn: w.titleEn,
+          year: w.year,
+          category: w.category,
+          role: w.role,
+          roleCn: w.roleCn,
+          episodes: w.episodes,
+          rating: w.rating,
+          platform: w.streamPlatform,
+          streamUrl: w.streamUrl || null,
+          youtubeTrailerSearch: buildYouTubeSearchUrl(`${titleSearch} Trailer Official`),
+          youkuSearchUrl: buildYoukuSearchUrl(w.titleCn || w.titleEn),
+          themeSong: w.themeSong ? {
+            title: `${w.themeSong.titleTh || ''} (${w.themeSong.titleCn || ''})`,
+            youtubeUrl: themeSongYtId ? buildYouTubeWatchUrl(themeSongYtId) : null,
+            youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${w.themeSong.titleCn || w.themeSong.titleTh} OST`)
+          } : null
+        };
+      })
+    };
+  },
+
+  get_work_detail: async ({ workIdOrTitle }) => {
+    if (!workIdOrTitle) return { status: "error", message: "workIdOrTitle parameter is required." };
+    const q = workIdOrTitle.toLowerCase().trim();
+    const work = worksData.find(w => 
+      w.id.toLowerCase() === q ||
+      w.titleTh.toLowerCase().includes(q) ||
+      (w.titleEn && w.titleEn.toLowerCase().includes(q)) ||
+      (w.titleCn && w.titleCn.includes(workIdOrTitle))
+    );
+
+    if (!work) {
+      return { status: "not_found", message: `No work found for "${workIdOrTitle}".` };
+    }
+
+    const titleSearch = `Ju Jingyi 鞠婧祎 ${work.titleCn || work.titleEn || work.titleTh}`;
+    const themeSongYtId = work.themeSong?.youtubeId || null;
+
+    return {
+      status: "success",
+      work: {
+        id: work.id,
+        titleTh: work.titleTh,
+        titleCn: work.titleCn,
+        titleEn: work.titleEn,
+        year: work.year,
+        category: work.category,
+        role: work.role,
+        episodes: work.episodes,
+        rating: work.rating,
+        platform: work.streamPlatform,
+        streamUrl: work.streamUrl || null,
+        youtubeTrailerSearch: buildYouTubeSearchUrl(`${titleSearch} Trailer Official`),
+        youkuSearchUrl: buildYoukuSearchUrl(work.titleCn || work.titleEn),
+        bilibiliSearchUrl: buildBilibiliSearchUrl(`鞠婧祎 ${work.titleCn}`),
+        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 || ''})`,
+          youtubeUrl: themeSongYtId ? buildYouTubeWatchUrl(themeSongYtId) : null,
+          youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${work.themeSong.titleCn || work.themeSong.titleTh} OST`)
+        } : null
+      }
+    };
+  },
+
+  get_character_roles: async ({ query } = {}) => {
+    const roles = worksData.map(w => ({
+      workTitle: `${w.titleTh} (${w.titleCn})`,
+      year: w.year,
+      role: w.role,
+      roleCn: w.roleCn,
+      youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${w.roleCn || w.role} ${w.titleCn}`)
+    }));
+
+    let filtered = roles;
+    const genericArtistKeywords = ['ju jingyi', 'jujingyi', 'จวีจิ้งอี', 'kiku', 'เสี่ยวจวี', 'kikuuu'];
+    const isGeneric = query && genericArtistKeywords.some(k => query.toLowerCase().trim() === k);
+
+    if (query && !isGeneric) {
+      const q = query.toLowerCase().trim();
+      filtered = roles.filter(r => 
+        (r.role && r.role.toLowerCase().includes(q)) ||
+        (r.roleCn && r.roleCn.includes(query)) ||
+        (r.workTitle && r.workTitle.toLowerCase().includes(q))
+      );
+    }
+
+    filtered.sort((a, b) => (b.year || 0) - (a.year || 0));
+
+    return {
+      status: "success",
+      count: filtered.length,
+      roles: filtered.slice(0, 8)
+    };
+  },
+
+  search_discography: async ({ query, year, type } = {}) => {
+    let list = getCleanDiscography();
+
+    if (year) list = list.filter(s => s.year === Number(year));
+    if (type === 'ost') list = list.filter(s => s.work && s.work !== "Solo Single");
+    if (type === 'single') list = list.filter(s => !s.work || s.work === "Solo Single");
+
+    const genericArtistKeywords = ['ju jingyi', 'jujingyi', 'จวีจิ้งอี', 'kiku', 'เสี่ยวจวี', 'kikuuu', 'เพลง', 'เพลงทั้งหมด', 'เพลงใหม่', 'music', 'song', 'songs'];
+    const isGeneric = query && genericArtistKeywords.some(k => query.toLowerCase().trim() === k);
+
+    if (query && !isGeneric) {
+      const q = query.toLowerCase().trim();
+      list = list.filter(s => 
+        (s.titleTh && s.titleTh.toLowerCase().includes(q)) ||
+        (s.titleCn && s.titleCn.includes(query)) ||
+        (s.titleEn && s.titleEn.toLowerCase().includes(q)) ||
+        (s.work && s.work.toLowerCase().includes(q))
+      );
+    }
+
+    return {
+      status: list.length > 0 ? "success" : "not_found",
+      message: list.length > 0 ? undefined : `No matching discography entries for "${query || 'this filter'}".`,
+      count: list.length,
+      songs: list.slice(0, 8).map(s => ({
+        id: s.id,
+        title: `${s.titleTh} (${s.titleCn})`,
+        titleEn: s.titleEn,
+        year: s.year,
+        type: s.work,
+        duration: s.duration,
+        youtubeUrl: s.youtubeUrl || (s.youtubeId ? buildYouTubeWatchUrl(s.youtubeId) : null),
+        youtubeSearchUrl: s.youtubeSearchUrl || buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${s.titleCn || s.titleTh}`),
+        qqMusicSearchUrl: s.qqMusicSearchUrl || buildQqMusicSearchUrl(`鞠婧祎 ${s.titleCn || s.titleTh}`),
+        bilibiliSearchUrl: s.bilibiliSearchUrl || buildBilibiliSearchUrl(`鞠婧祎 ${s.titleCn || s.titleTh}`)
+      }))
+    };
+  },
+
+  get_music_videos: async ({ category, query } = {}) => {
+    const allMVs = getAllMusicVideos();
+
+    let results = allMVs;
+    if (category) {
+      const catLower = category.toLowerCase();
+      results = results.filter(m => {
+        const mCat = (m.category || '').toLowerCase();
+        if (catLower.includes('mv') || catLower.includes('official')) return mCat.includes('mv') || mCat === 'single' || mCat === 'ost';
+        if (catLower.includes('stage') || catLower.includes('performance')) return mCat.includes('stage');
+        if (catLower.includes('ost')) return mCat === 'ost';
+        if (catLower.includes('single')) return mCat === 'single';
+        return mCat.includes(catLower);
+      });
+    }
+    
+    const genericArtistKeywords = ['ju jingyi', 'jujingyi', 'จวีจิ้งอี', 'kiku', 'เสี่ยวจวี', 'kikuuu', 'mv', 'music video', 'วิดีโอ', 'คลิป'];
+    const isGeneric = query && genericArtistKeywords.some(k => query.toLowerCase().trim() === k);
+    
+    if (query && !isGeneric) {
+      const q = query.toLowerCase().trim();
+      results = results.filter(m => 
+        (m.titleTh && m.titleTh.toLowerCase().includes(q)) || 
+        (m.titleCn && m.titleCn.includes(query)) ||
+        (m.titlePinyin && m.titlePinyin.toLowerCase().includes(q)) ||
+        (m.dramaName && m.dramaName.toLowerCase().includes(q)) ||
+        (m.description && m.description.toLowerCase().includes(q))
+      );
+    }
+
+    return {
+      status: "success",
+      count: results.length,
+      videos: results.slice(0, 8).map(m => {
+        const ytId = m.youtubeId || null;
+        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})`,
+          category: m.category,
+          year: m.releaseYear || m.year,
+          drama: m.dramaName || null,
+          duration: m.duration || null,
+          description: m.description || null,
+          isFeatured: !!m.isFeatured,
+          youtubeUrl: ytId ? buildYouTubeWatchUrl(ytId) : null,
+          youtubeSearchUrl: buildYouTubeSearchUrl(searchTitle),
+          bilibiliSearchUrl: buildBilibiliSearchUrl(`鞠婧祎 ${m.titleCn || m.titleTh}`)
+        };
+      })
+    };
+  },
+
+  get_media_links: async ({ query, category } = {}) => {
+    if (!query) return { status: "error", message: "query parameter is required." };
+    const q = query.toLowerCase().trim();
+
+    const mvs = getAllMusicVideos();
+    const disc = getCleanDiscography();
+    const works = worksData;
+
+    const matchedVideos = mvs.filter(m => 
+      (m.titleTh && m.titleTh.toLowerCase().includes(q)) ||
+      (m.titleCn && m.titleCn.includes(query)) ||
+      (m.titlePinyin && m.titlePinyin.toLowerCase().includes(q)) ||
+      (m.dramaName && m.dramaName.toLowerCase().includes(q))
+    ).map(m => ({
+      type: m.category || 'MV',
+      title: `${m.titleTh} (${m.titleCn})`,
+      year: m.releaseYear || m.year,
+      duration: m.duration,
+      youtubeUrl: m.youtubeId ? buildYouTubeWatchUrl(m.youtubeId) : null,
+      youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${m.titleCn || m.titleTh} ${m.category === 'Stage-Performance' ? 'Stage' : 'Official MV'}`),
+      bilibiliSearchUrl: buildBilibiliSearchUrl(`鞠婧祎 ${m.titleCn || m.titleTh}`)
+    }));
+
+    const matchedSongs = disc.filter(s =>
+      (s.titleTh && s.titleTh.toLowerCase().includes(q)) ||
+      (s.titleCn && s.titleCn.includes(query)) ||
+      (s.titleEn && s.titleEn.toLowerCase().includes(q)) ||
+      (s.work && s.work.toLowerCase().includes(q))
+    ).map(s => ({
+      type: s.work || 'Song',
+      title: `${s.titleTh} (${s.titleCn})`,
+      year: s.year,
+      duration: s.duration,
+      youtubeUrl: s.youtubeUrl || (s.youtubeId ? buildYouTubeWatchUrl(s.youtubeId) : null),
+      youtubeSearchUrl: s.youtubeSearchUrl || buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${s.titleCn || s.titleTh}`),
+      qqMusicSearchUrl: s.qqMusicSearchUrl || buildQqMusicSearchUrl(`鞠婧祎 ${s.titleCn || s.titleTh}`),
+      bilibiliSearchUrl: s.bilibiliSearchUrl || buildBilibiliSearchUrl(`鞠婧祎 ${s.titleCn || s.titleTh}`)
+    }));
+
+    const matchedWorks = works.filter(w =>
+      (w.titleTh && w.titleTh.toLowerCase().includes(q)) ||
+      (w.titleCn && w.titleCn.includes(query)) ||
+      (w.titleEn && w.titleEn.toLowerCase().includes(q))
+    ).map(w => ({
+      type: 'Drama / Series',
+      title: `${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 || ''})`,
+        youtubeUrl: w.themeSong.youtubeId ? buildYouTubeWatchUrl(w.themeSong.youtubeId) : null,
+        youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${w.themeSong.titleCn || w.themeSong.titleTh} OST`)
+      } : null
+    }));
+
+    const generalYouTubeSearch = buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${query}`);
+    const generalBilibiliSearch = buildBilibiliSearchUrl(`鞠婧祎 ${query}`);
+
+    return {
+      status: "success",
+      query,
+      fallbackYouTubeSearch: generalYouTubeSearch,
+      fallbackBilibiliSearch: generalBilibiliSearch,
+      results: {
+        musicVideos: matchedVideos.slice(0, 5),
+        songs: matchedSongs.slice(0, 5),
+        works: matchedWorks.slice(0, 3)
+      }
+    };
+  },
+
+  get_brand_endorsements: async ({ isGlobal, category, year, query } = {}) => {
+    let list = Array.isArray(brandsData) ? [...brandsData] : [...(brandsData.brandList || brandsData.brands || [])];
+
+    if (typeof isGlobal === 'boolean') list = list.filter(b => !!b.isGlobal === isGlobal);
+    if (year) list = list.filter(b => b.year === Number(year));
+    if (category) list = list.filter(b => (b.category && b.category.toLowerCase().includes(category.toLowerCase())) || (b.tier && b.tier.toLowerCase().includes(category.toLowerCase())));
+
+    const genericArtistKeywords = ['ju jingyi', 'jujingyi', 'จวีจิ้งอี', 'kiku', 'เสี่ยวจวี', 'kikuuu', 'แบรนด์', 'พรีเซนเตอร์', 'brand', 'ambassador', 'endorsement', 'commercial'];
+    const isGeneric = query && genericArtistKeywords.some(k => query.toLowerCase().trim() === k);
+
+    if (query && !isGeneric) {
+      const q = query.toLowerCase().trim();
+      const numYear = Number(q);
+      if (!isNaN(numYear) && numYear >= 2013 && numYear <= 2030) {
+        list = list.filter(b => b.year === numYear);
+      } else {
+        list = list.filter(b => 
+          (b.brandNameEn && b.brandNameEn.toLowerCase().includes(q)) ||
+          (b.brandNameCn && b.brandNameCn.includes(query)) ||
+          (b.title && b.title.toLowerCase().includes(q)) ||
+          (b.category && b.category.toLowerCase().includes(q)) ||
+          (b.highlight && b.highlight.toLowerCase().includes(q)) ||
+          (b.tier && b.tier.toLowerCase().includes(q)) ||
+          (b.name && b.name.toLowerCase().includes(q))
+        );
+      }
+    }
+
+    list.sort((a, b) => (b.year || 0) - (a.year || 0));
+
+    return {
+      status: "success",
+      count: list.length,
+      brands: list.slice(0, 8).map(b => ({
+        brand: `${b.brandNameEn || b.brand || b.name} (${b.brandNameCn || ''})`,
+        year: b.year,
+        title: b.title || (b.isGlobal ? 'Global Brand Ambassador' : 'Brand Ambassador'),
+        category: b.category,
+        isGlobal: !!b.isGlobal,
+        highlight: b.highlight || '',
+        youtubeCommercialSearch: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${b.brandNameEn || b.brandNameCn} CF Commercial`)
+      }))
+    };
+  },
+
+  get_career_timeline: async ({ year, era } = {}) => {
+    let eras = Array.isArray(timelineData) ? timelineData : (timelineData.eras || []);
+    if (year) eras = eras.filter(e => e.year == year || (e.period && e.period.includes(String(year))));
+    if (era) eras = eras.filter(e => e.title?.toLowerCase().includes(era.toLowerCase()) || e.era?.includes(era));
+
+    return {
+      status: "success",
+      count: eras.length,
+      milestones: eras.slice(0, 6).map(e => ({
+        period: e.period || e.year,
+        title: `${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,
+        youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${a.titleCn || a.ceremony}`)
+      }))
+    };
+  },
+
+  get_social_feed: async ({ platform, limit = 4 } = {}) => {
+    let posts = socialUpdatesData.cards || [];
+    if (platform && platform !== 'all') posts = posts.filter(p => p.platform?.toLowerCase() === platform.toLowerCase());
+
+    return {
+      status: "success",
+      count: Math.min(posts.length, Number(limit) || 4),
+      posts: posts.slice(0, Number(limit) || 4).map(p => ({
+        platform: p.platform,
+        date: p.date,
+        content: p.content?.slice(0, 120) + '...',
+        likes: p.likes
+      }))
+    };
+  },
+
+  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,
+        category: p.category,
+        year: p.era || p.year
+      }))
+    };
+  },
+
+  global_search: async ({ query }) => {
+    if (!query) return { status: "error", message: "Query parameter is required." };
+    const q = query.toLowerCase();
+    const ignoredTerms = new Set(['the', 'from', 'what', 'are', 'drama', 'ost', 'song', 'songs', 'soundtrack', 'music']);
+    const terms = q.split(/[^\p{L}\p{N}]+/u).filter(term => term.length > 2 && !ignoredTerms.has(term));
+    const matchesQuery = (...values) => {
+      const haystack = values.filter(Boolean).join(' ').toLowerCase();
+      return haystack.includes(q) || (terms.length > 0 && terms.every(term => haystack.includes(term)));
+    };
+
+    const matchedWorks = worksData.filter(w =>
+      matchesQuery(w.titleTh, w.titleEn, w.titleCn, w.role, w.roleCn)
+    ).slice(0, 4).map(w => ({
+      title: `${w.titleTh} (${w.year}) - Role: ${w.role}`,
+      trailerYouTubeSearch: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${w.titleCn || w.titleEn} Trailer`)
+    }));
+
+    const disc = getCleanDiscography();
+    const matchedSongs = disc.filter(s =>
+      matchesQuery(s.titleTh, s.titleEn, s.titleCn, s.work, s.role)
+    ).slice(0, 4).map(s => ({
+      title: `${s.titleTh} (${s.year})`,
+      youtubeUrl: s.youtubeUrl || null,
+      youtubeSearchUrl: s.youtubeSearchUrl
+    }));
+
+    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}]`,
+      youtubeUrl: m.youtubeId ? buildYouTubeWatchUrl(m.youtubeId) : null,
+      youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${m.titleCn || m.titleTh}`)
+    }));
+
+    const brands = Array.isArray(brandsData) ? (brandsData.brandList || []) : (brandsData.brands || []);
+    const matchedBrands = brands.filter(b =>
+      matchesQuery(b.brandNameEn, b.brandNameCn, b.name, b.title)
+    ).slice(0, 4).map(b => `${b.brandNameEn || b.name} (${b.year}) - ${b.title}`);
+
+    const count = matchedWorks.length + matchedSongs.length + mvs.length + matchedBrands.length;
+    return {
+      status: count > 0 ? "success" : "not_found",
+      message: count > 0 ? undefined : `No local catalog matches for "${query}". Use web_search for external results.`,
+      query,
+      count,
+      results: {
+        musicVideos: mvs,
+        works: matchedWorks,
+        songs: matchedSongs,
+        brands: matchedBrands,
+        youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${query}`)
+      }
+    };
+  },
+
+  web_search: async ({ query } = {}) => {
+    return await searchWeb(query);
+  },
+
+  fetch_webpage: async ({ url } = {}) => {
+    return await fetchWebpage(url);
+  },
+
+  fetch_api: async ({ endpoint, query, baseUrl } = {}) => {
+    if (!endpoint) return { status: "error", message: "endpoint parameter is required (e.g. 'profile', 'works', 'search')" };
+    const base = (baseUrl || 'https://jujingyi-kikuuu.vercel.app/api/v1').replace(/\/$/, '');
+    const path = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
+    let url = `${base}${path}`;
+    if (query) url += `?q=${encodeURIComponent(query)}`;
+
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 10000);
+      const res = await fetch(url, {
+        headers: { 'Accept': 'application/json', 'User-Agent': 'KikuAgent/1.0' },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+
+      if (!res.ok) {
+        return { status: "error", message: `HTTP ${res.status} from ${url}` };
+      }
+
+      const json = await res.json();
+
+      const data = json.data || json;
+      return {
+        status: "success",
+        endpoint: path,
+        count: Array.isArray(data) ? data.length : undefined,
+        data
+      };
+    } catch (err) {
+      return {
+        status: "error",
+        endpoint: path,
+        message: err.name === 'AbortError' ? 'API request timed out' : err.message
+      };
+    }
+  },
+
+  fetch_json: async ({ url, method, headers, body } = {}) => {
+    return await fetchJson(url, { method, headers, body });
+  },
+
+  read_local_file: async ({ path: filePath, maxLines = 200 } = {}) => {
+    if (!filePath) return { status: 'error', message: 'path parameter is required.' };
+    try {
+      const projectRoot = process.cwd();
+      const resolved = resolve(projectRoot, filePath);
+      const relativePath = relative(projectRoot, resolved);
+
+      if (relativePath.startsWith('..') || relativePath.includes('..')) {
+        return { status: 'error', message: 'Path must be within the project directory.' };
+      }
+
+      const fileStat = await stat(resolved);
+      if (!fileStat.isFile()) {
+        return { status: 'error', message: `"${filePath}" is not a file.` };
+      }
+
+      if (fileStat.size > 500000) {
+        return { status: 'error', message: `File too large (${Math.round(fileStat.size / 1024)}KB). Use maxLines to read a portion.` };
+      }
+
+      const content = await readFile(resolved, 'utf-8');
+      const lines = content.split('\n');
+      const totalLines = lines.length;
+      const truncated = totalLines > maxLines;
+      const readContent = truncated ? lines.slice(0, maxLines).join('\n') : content;
+
+      return {
+        status: 'success',
+        path: relativePath,
+        sizeBytes: fileStat.size,
+        totalLines,
+        linesRead: Math.min(totalLines, maxLines),
+        truncated,
+        content: truncated ? readContent + `\n\n... [Showing first ${maxLines} of ${totalLines} lines]` : readContent
+      };
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        return { status: 'error', message: `File not found: "${filePath}"` };
+      }
+      return { status: 'error', message: err.message };
+    }
+  },
+
+  list_directory: async ({ path: dirPath = '.', recursive = false } = {}) => {
+    try {
+      const projectRoot = process.cwd();
+      const resolved = resolve(projectRoot, dirPath);
+      const relativePath = relative(projectRoot, resolved);
+
+      if (relativePath.startsWith('..') || relativePath.includes('..')) {
+        return { status: 'error', message: 'Path must be within the project directory.' };
+      }
+
+      async function listDir(dir, depth = 0) {
+        if (depth > (recursive ? 3 : 0)) return [];
+        const entries = await readdir(dir, { withFileTypes: true });
+        const items = [];
+
+        for (const entry of entries) {
+          if (entry.name.startsWith('.') && entry.name !== '.env.example') continue;
+          if (entry.name === 'node_modules' || entry.name === '.git') continue;
+          if (entry.name === 'dist' || entry.name === 'build') continue;
+
+          const entryPath = join(dir, entry.name);
+          const entryRelative = relative(projectRoot, entryPath);
+
+          if (entry.isDirectory()) {
+            items.push({ name: entry.name, type: 'directory', path: entryRelative });
+            if (recursive && depth < 3) {
+              const children = await listDir(entryPath, depth + 1);
+              items.push(...children);
+            }
+          } else {
+            const fileStat = await stat(entryPath).catch(() => null);
+            items.push({
+              name: entry.name,
+              type: 'file',
+              path: entryRelative,
+              sizeBytes: fileStat?.size || 0
+            });
+          }
+        }
+
+        items.sort((a, b) => {
+          if (a.type !== b.type) return a.type === 'directory' ? -1 : 1;
+          return a.name.localeCompare(b.name);
+        });
+
+        return items;
+      }
+
+      const items = await listDir(resolved);
+      return {
+        status: 'success',
+        path: relativePath || '.',
+        count: items.length,
+        items
+      };
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        return { status: 'error', message: `Directory not found: "${dirPath}"` };
+      }
+      return { status: 'error', message: err.message };
+    }
+  },
+
+  screenshot_webpage: async ({ url, width, height } = {}) => {
+    return await screenshotWebpage(url, { width, height });
+  },
+
+  web_extract: async ({ query, maxResults, allowedDomains } = {}) => {
+    return await webExtract(query, { maxResults, allowedDomains });
+  },
+
+  get_system_stats: async () => {
+    const disc = getCleanDiscography();
+    const brands = brandsData?.brandList || brandsData?.brands || (Array.isArray(brandsData) ? brandsData : []);
+    const awards = Array.isArray(awardsData) ? awardsData : (awardsData?.awards || []);
+    const timeline = Array.isArray(timelineData) ? timelineData : (timelineData?.eras || []);
+    const mvs = getAllMusicVideos();
+    const gpu = await getGpuMetrics().catch(() => ({ available: false }));
+
+    return {
+      status: "success",
+      stats: {
+        artistName: profileData.nameTh,
+        artistNameCn: profileData.nameCn,
+        totalWorks: worksData.length,
+        totalUniqueSongs: disc.length,
+        totalMusicVideosAndStages: mvs.length,
+        brandEndorsements: brands.length,
+        totalAwards: awards.length,
+        timelineMilestones: timeline.length,
+        activeYears: "2013 - Present (2026)",
+        featured2026Works: ["Veil of Shadows (月鳞绮纪)", "The Eternal Fragrance (千香)", "Wanhua Sin (万华世界)"],
+        youtubeOfficialHub: buildYouTubeSearchUrl("Ju Jingyi 鞠婧祎"),
+        gpu: gpu.available ? gpu.primary : { available: false }
+      }
+    };
+  },
+
+  play_music: async (args) => {
+    try {
+      const query = args.query || '';
+
+      const hasArtist = /jujingyi|จวีจิ้งอี|鞠婧祎/i.test(query);
+      const isUrl = /^https?:\/\//.test(query);
+      const searchQuery = (!hasArtist && !isUrl) ? `Ju Jingyi ${query}` : query;
+      const result = await audioPlayer.play(searchQuery);
+      return { status: 'success', message: result, playing: args.query };
+    } catch (err) {
+      return { status: 'error', message: err.message };
+    }
+  },
+
+  stop_music: async () => {
+    const result = await audioPlayer.stop();
+    return { status: 'success', message: result };
+  },
+
+  mute_music: async () => {
+    const result = await audioPlayer.mute();
+    return { status: 'success', message: result };
+  },
+
+  unmute_music: async () => {
+    const result = await audioPlayer.unmute();
+    return { status: 'success', message: result };
+  },
+
+  pause_music: async () => {
+    const result = await audioPlayer.pause();
+    return { status: 'success', message: result };
+  },
+
+  resume_music: async () => {
+    const result = await audioPlayer.resume();
+    return { status: 'success', message: result };
+  },
+
+  next_track: async () => {
+    const result = await audioPlayer.next();
+    return { status: 'success', message: result };
+  },
+
+  prev_track: async () => {
+    const result = await audioPlayer.prev();
+    return { status: 'success', message: result };
+  },
+
+  add_to_queue: async (args) => {
+    const result = await audioPlayer.addToQueue(args.query);
+    return { status: 'success', message: result };
+  },
+
+  remove_from_queue: async (args) => {
+    const result = await audioPlayer.removeFromQueue(args.index);
+    return { status: 'success', message: result };
+  },
+
+  clear_queue: async () => {
+    const result = await audioPlayer.clearQueue();
+    return { status: 'success', message: result };
+  },
+
+  get_queue: async () => {
+    const queue = audioPlayer.getQueue();
+    return { status: 'success', queue };
+  },
+
+  search_youtube: async (args) => {
+    try {
+      const results = await audioPlayer.searchYouTube(args.query);
+      return { status: 'success', query: args.query, results };
+    } catch (err) {
+      return { status: 'error', message: err.message };
+    }
+  },
+
+  get_current_track: async () => {
+    const state = audioPlayer.getFullState();
+    return { status: 'success', ...state };
+  },
+
+  get_music_status: async () => {
+    const state = audioPlayer.getFullState();
+    return { status: 'success', ...state };
+  },
+
+  run_subagent: async ({ task }, options = {}) => {
+    if (options?.agent?.runSubagent) {
+      const result = await options.agent.runSubagent(task, { signal: options.signal });
+      return { status: "success", task, answer: result.answer, toolCalls: result.toolCalls, iterations: result.iterations };
+    }
+    const { LMStudioClient } = await import('./llmClient.js');
+    const { ResearchSubagent } = await import('./subagent.js');
+    const client = options?.client || new LMStudioClient();
+    const subagent = new ResearchSubagent({ client });
+    const result = await subagent.run(task, { signal: options?.signal });
+    return { status: "success", task, answer: result.answer, toolCalls: result.toolCalls, iterations: result.iterations };
+  },
+
+  run_deep_research: async ({ question }, options = {}) => {
+    if (options?.agent?.runResearch) {
+      const result = await options.agent.runResearch(question, { signal: options.signal });
+      return { status: "success", question, answer: result.answer, sources: result.sources, reports: result.reports };
+    }
+    const { LMStudioClient } = await import('./llmClient.js');
+    const { ResearchOrchestrator } = await import('./research.js');
+    const client = options?.client || new LMStudioClient();
+    const orchestrator = new ResearchOrchestrator({ client });
+    const result = await orchestrator.run(question, { signal: options?.signal });
+    return { status: "success", question, answer: result.answer, sources: result.sources, reports: result.reports };
+  },
+
+  verify_claim: async ({ claim }, options = {}) => {
+    if (options?.agent?.runResearch) {
+      const result = await options.agent.runResearch(claim, { mode: 'verify', signal: options.signal });
+      return { status: "success", claim, answer: result.answer, sources: result.sources, reports: result.reports };
+    }
+    const { LMStudioClient } = await import('./llmClient.js');
+    const { ResearchOrchestrator } = await import('./research.js');
+    const client = options?.client || new LMStudioClient();
+    const orchestrator = new ResearchOrchestrator({ client });
+    const result = await orchestrator.run(claim, { mode: 'verify', signal: options?.signal });
+    return { status: "success", claim, answer: result.answer, sources: result.sources, reports: result.reports };
+  },
+
+  manage_skill: async ({ action, instruction, skillId }, options = {}) => {
+    let memory = options?.agent?.memory || options?.memory;
+    if (!memory) {
+      const { AgentMemory } = await import('./memory.js');
+      memory = new AgentMemory();
+      await memory.load();
+    }
+    switch (action) {
+      case 'learn': {
+        if (!instruction) return { status: 'error', message: 'Instruction is required for action "learn".' };
+        const skill = memory.addUserSkill(instruction);
+        return { status: 'success', message: `Learned response skill "${skill.id}".`, skill };
+      }
+      case 'remove': {
+        if (!skillId) return { status: 'error', message: 'skillId is required for action "remove".' };
+        const removed = memory.removeUserSkill(skillId);
+        return removed ? { status: 'success', message: `Skill ${skillId} removed.` } : { status: 'error', message: `Skill ${skillId} not found.` };
+      }
+      case 'clear': {
+        memory.clearUserSkills();
+        return { status: 'success', message: 'All learned response skills cleared.' };
+      }
+      case 'enable': {
+        memory.setPreference('skillsEnabled', true);
+        return { status: 'success', message: 'Learned response skills enabled.' };
+      }
+      case 'disable': {
+        memory.setPreference('skillsEnabled', false);
+        return { status: 'success', message: 'Learned response skills disabled.' };
+      }
+      case 'list':
+      default: {
+        return {
+          status: 'success',
+          enabled: memory.preferences.skillsEnabled !== false,
+          skills: memory.preferences.userSkills || []
+        };
+      }
+    }
+  }
+};
+
+const toolSchemaByName = new Map(
+  toolsSchema.map(tool => [tool.function.name, tool.function.parameters || { type: 'object', properties: {} }])
+);
+
+function coerceToolValue(value, schema = {}) {
+  if (value == null || !schema.type) return { ok: true, value };
+
+  if (schema.type === 'string') {
+    if (typeof value === 'string') return { ok: true, value };
+    if (['number', 'boolean'].includes(typeof value)) return { ok: true, value: String(value), coerced: true };
+    return { ok: false };
+  }
+  if (schema.type === 'number' || schema.type === 'integer') {
+    const parsed = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(parsed)) return { ok: false };
+    return { ok: true, value: schema.type === 'integer' ? Math.trunc(parsed) : parsed, coerced: typeof value !== 'number' };
+  }
+  if (schema.type === 'boolean') {
+    if (typeof value === 'boolean') return { ok: true, value };
+    if (value === 'true' || value === '1' || value === 1) return { ok: true, value: true, coerced: true };
+    if (value === 'false' || value === '0' || value === 0) return { ok: true, value: false, coerced: true };
+    return { ok: false };
+  }
+  if (schema.type === 'array') {
+    if (!Array.isArray(value)) return { ok: false };
+    const converted = [];
+    for (const item of value) {
+      const checked = coerceToolValue(item, schema.items || {});
+      if (!checked.ok) return { ok: false };
+      converted.push(checked.value);
+    }
+    return { ok: true, value: converted };
+  }
+  if (schema.type === 'object') return { ok: !!value && typeof value === 'object' && !Array.isArray(value), value };
+  return { ok: true, value };
+}
+
+export function prepareToolArguments(toolName, rawArgs = {}) {
+  const schema = toolSchemaByName.get(toolName);
+  if (!schema) {
+    return { safe: false, args: {}, warnings: [], error: `Unknown tool "${toolName}".` };
+  }
+
+  let parsedArgs = rawArgs;
+  if (typeof rawArgs === 'string') {
+    const trimmed = rawArgs.trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '');
+    if (!trimmed) parsedArgs = {};
+    else {
+      try { parsedArgs = JSON.parse(trimmed); }
+      catch (error) {
+        return { safe: false, args: {}, warnings: [], error: `Invalid JSON arguments: ${error.message}` };
+      }
+    }
+  }
+
+  if (!parsedArgs || typeof parsedArgs !== 'object' || Array.isArray(parsedArgs)) {
+    return { safe: false, args: {}, warnings: [], error: 'Tool arguments must be a JSON object.' };
+  }
+
+  const properties = schema.properties || {};
+  const required = new Set(schema.required || []);
+  const validated = {};
+  const warnings = [];
+
+  for (const requiredName of required) {
+    if (parsedArgs[requiredName] == null || parsedArgs[requiredName] === '') {
+      return { safe: false, args: {}, warnings, error: `Missing required argument "${requiredName}".` };
+    }
+  }
+
+  for (const [name, value] of Object.entries(parsedArgs)) {
+    const propertySchema = properties[name];
+    if (!propertySchema) {
+      warnings.push(`Unknown argument "${name}" was ignored`);
+      continue;
+    }
+    const checked = coerceToolValue(value, propertySchema);
+    if (!checked.ok) {
+      return { safe: false, args: {}, warnings, error: `Argument "${name}" must be ${propertySchema.type || 'valid'}.` };
+    }
+    if (propertySchema.enum && !propertySchema.enum.includes(checked.value)) {
+      return { safe: false, args: {}, warnings, error: `Argument "${name}" must be one of: ${propertySchema.enum.join(', ')}.` };
+    }
+    if (checked.coerced) warnings.push(`Argument "${name}" was converted to ${propertySchema.type}`);
+    validated[name] = checked.value;
+  }
+
+  const sanitizedResult = sanitizeToolArgs(toolName, validated);
+  if (!sanitizedResult.safe) {
+    return { safe: false, args: {}, warnings: [...warnings, ...sanitizedResult.warnings], error: sanitizedResult.warnings.join('; ') };
+  }
+  return { safe: true, args: sanitizedResult.sanitized, warnings: [...warnings, ...sanitizedResult.warnings], error: null };
+}
+
+export function normalizeToolResult(toolName, result) {
+  if (result == null) return { status: 'error', message: `Tool "${toolName}" returned no result.` };
+  if (typeof result !== 'object' || Array.isArray(result)) return { status: 'success', data: result };
+
+  const normalized = { ...result };
+  if (!normalized.status) normalized.status = normalized.error ? 'error' : 'success';
+  if (normalized.error && !normalized.message) normalized.message = String(normalized.error);
+  if (normalized.status === 'success' && (normalized.count === 0 || normalized.returnedCount === 0)) {
+    normalized.status = 'not_found';
+    if (!normalized.message) normalized.message = 'No matching data found.';
+  }
+  return normalized;
+}
+
+export async function executeTool(toolName, args = {}, options = {}) {
+  const handler = toolHandlers[toolName];
+  if (!handler) {
+    return {
+      status: "error",
+      message: `Unknown tool "${toolName}". Available tools: ${Object.keys(toolHandlers).join(', ')}`
+    };
+  }
+
+  try {
+    const prepared = prepareToolArguments(toolName, args);
+    if (!prepared.safe) {
+      return {
+        status: 'error',
+        message: `Input rejected: ${prepared.error}`,
+        validationWarnings: prepared.warnings,
+      };
+    }
+
+    const configuredTimeout = Number(options.timeoutMs ?? process.env.KIKU_TOOL_TIMEOUT_MS ?? 45_000);
+    const timeoutMs = Number.isFinite(configuredTimeout) && configuredTimeout > 0 ? configuredTimeout : 45_000;
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+      timeoutId = setTimeout(() => reject(new Error(`Timed out after ${timeoutMs}ms`)), timeoutMs);
+    });
+    let result;
+    try {
+      result = await Promise.race([Promise.resolve(handler(prepared.args, options)), timeoutPromise]);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+
+    const normalized = normalizeToolResult(toolName, result);
+    if (prepared.warnings.length > 0) {
+      normalized.validationWarnings = prepared.warnings;
+    }
+    return normalized;
+  } catch (err) {
+    return {
+      status: "error",
+      message: `Failed executing tool "${toolName}": ${err.message}`
+    };
+  }
+}