kiku-agent 1.3.2 → 1.3.4

package/server/agent/tools.js

@@ -16,11 +16,29 @@ import {
 } from './webSearch.js';
 import { readFile, readdir, stat, realpath } from 'node:fs/promises';
 import { join, relative, extname, resolve } from 'node:path';
-import { audioPlayer } from './audioPlayer.js';
+import { audioPlayer, resolveCatalogSong } from './audioPlayer.js';
 import { fetchYoutubeTranscript } from './youtubeTranscript.js';
 import { sanitizeToolArgs, sanitizeUrl } from './sanitizer.js';
 import { getGpuMetrics } from './gpuMetrics.js';
 import { levenshteinDistance, levenshteinSimilarity, levenshteinScore, CATEGORY_ALIASES } from './catalogEntityResolver.js';
+import { USER_ENV_PATH } from './envManager.js';
+import { planSearchRequest } from './searchQueryPlanner.js';
+import {
+  calculateHaversineDistance,
+  estimateWalkingTime,
+  estimateDrivingTime,
+  formatDistance,
+  findNearestLandmark,
+  buildOsmMapTag,
+  buildOsmUrl,
+  reverseGeocodeOsm,
+  searchLocationOsm,
+  cleanLocationQuery,
+  LANDMARK_REGISTRY,
+  detectIpLocation,
+  fetchRealtimeWeather,
+  scoreLocationConfidence
+} from './locationService.js';
 
 export function buildYouTubeSearchUrl(query) {
   return `https://www.youtube.com/results?search_query=${encodeURIComponent(query)}`;
@@ -50,11 +68,11 @@ export function formatCatalogTitle(primary, secondary) {
 }
 
 export const CATALOG_STOP_WORDS = new Set([
-  'the', 'from', 'what', 'are', 'is', 'about', 'drama', 'series', 'ost', 'song', 'songs', 'soundtrack', 'music', 'single', 'album', 'stage',
+  'the', 'of', 'from', 'what', 'are', 'is', 'about', 'drama', 'series', 'ost', 'song', 'songs', 'soundtrack', 'music', 'single', 'album', 'stage',
   'brand', 'brands', 'ambassador', 'endorsement', 'commercial', 'role', 'roles', 'character', 'characters', 'award', 'awards', 'category', 'video', 'mv', 'clip',
   'ju', 'jingyi', 'jujingyi', 'kiku', 'kikuuu', 'จวีจิ้งอี', 'จวี', 'จิ้งอี', 'เสี่ยวจวี', 'เสี่ยว', '鞠婧祎', '小鞠', '鞠',
   'เพลง', 'เพลงของ', 'ซีรีส์', 'ซีรีส์ของ', 'ละคร', 'เรื่อง', 'ผลงาน', 'อัลบั้ม', 'คอนเสิร์ต', 'บทบาท', 'ตัวละคร', 'แบรนด์', 'รางวัล', 'ผลงานล่าสุด', 'พรีเซนเตอร์',
-  'ค้นหา', 'หา', 'ดู', 'เปิด', 'ฟัง', 'โปรโมท', 'โปรโมต', 'การโปรโมท', 'การโปรโมต', 'โฆษณา', 'แคมเปญ', 'ข้อมูล', 'รายละเอียด', 'บน', 'ใน', 'ที่', 'กับ', 'ช่วย', 'อยาก', 'ให้', 'หน่อย', 'คือ', 'อะไร', 'บ้าง', 'ไหม', 'มั้ย', 'มี',
+  'ค้นหา', 'หา', 'ดู', 'เปิด', 'ฟัง', 'โปรโมท', 'โปรโมต', 'การโปรโมท', 'การโปรโมต', 'โฆษณา', 'แคมเปญ', 'ข้อมูล', 'รายละเอียด', 'บน', 'ใน', 'ที่', 'กับ', 'ช่วย', 'อยาก', 'ให้', 'หน่อย', 'คือ', 'อะไร', 'บ้าง', 'ไหม', 'มั้ย', 'มี', 'แนว', 'สไตล์', 'ประเภท', 'เกี่ยวกับ', 'เรื่องราว', 'แสดง', 'แสดงเป็น', 'รับบท', 'บท',
   'search', 'find', 'show', 'look', 'promo', 'promote', 'promoted', 'campaign', 'for', 'with', 'tell', 'me', 'please', 'can', 'you', 'info', 'details',
   '搜索', '查找', '看看', '播放', '在', '上的', '关于', '有什么', '吗', '呢',
   'bilibili', 'b站', 'youtube', 'weibo', 'douyin', 'spotify', 'qqmusic', 'iqiyi', 'youku', 'tencent'
@@ -79,10 +97,21 @@ export function createCatalogMatcher(query) {
   const raw = String(query).toLowerCase().trim();
   if (!raw) return () => true;
 
-  const allTokens = raw.split(/[^\p{L}\p{M}\p{N}]+/u).filter(t => t.length >= 2);
   const deDated = raw.replace(/ใหม่ล่าสุด|ล่าสุด|最新|latest|newest|recent/gi, ' ');
+  let cleaned = deDated;
+  for (const sw of CATALOG_STOP_WORDS) {
+    if (sw.length >= 2) {
+      if (/^[a-z0-9]+$/i.test(sw)) {
+        cleaned = cleaned.replace(new RegExp('\\b' + sw + '\\b', 'gi'), ' ');
+      } else if (cleaned.includes(sw)) {
+        cleaned = cleaned.split(sw).join(' ');
+      }
+    }
+  }
+
   const datedTokens = deDated.split(/[^\p{L}\p{M}\p{N}]+/u).filter(t => t.length >= 2);
-  const coreTokens = datedTokens.filter(t => !CATALOG_STOP_WORDS.has(t));
+  const strippedTokens = cleaned.split(/[^\p{L}\p{M}\p{N}]+/u).filter(t => t.length >= 2);
+  const coreTokens = (strippedTokens.length > 0 ? strippedTokens : datedTokens).filter(t => !CATALOG_STOP_WORDS.has(t));
 
   if (coreTokens.length === 0) {
     const broadMatcher = () => true;
@@ -188,6 +217,7 @@ const WEB_CACHE_TOOLS = new Set([
   'search_chinese_web',
   'search_bilibili',
   'search_web_images',
+  'search_location_map',
 ]);
 
 
@@ -293,6 +323,81 @@ export const toolsSchema = [
       }
     }
   },
+  {
+    type: "function",
+    function: {
+      name: "get_user_location",
+      description: "Resolve current user's local coordinates and nearby landmark using IP or client GPS. Use this ONLY when the user asks about their own current location (e.g. 'แถวนี้', 'ใกล้ฉัน', 'here'). Do NOT use this if the user specified a destination name (use search_location_map or get_weather instead).",
+      parameters: {
+        type: "object",
+        properties: {
+          reason: {
+            type: "string",
+            description: "Optional purpose or reason for requesting location (e.g. 'weather_forecast', 'current_weather', 'nearby_services', 'local_time')."
+          },
+          query: {
+            type: "string",
+            description: "Optional place name, district, or landmark to search or resolve coordinates for."
+          },
+          latitude: {
+            type: "number",
+            description: "Optional latitude coordinate to reverse geocode and match nearest landmarks."
+          },
+          longitude: {
+            type: "number",
+            description: "Optional longitude coordinate to reverse geocode and match nearest landmarks."
+          }
+        },
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "search_location_map",
+      description: "Search for geographic coordinates, formatted address, real-time weather, and interactive map tags [MAP_OSM:lat,lon,Name] of any named location, landmark, venue, concert hall, filming studio, or address. Use this when the user asks for maps, navigation, directions, or location information of places.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "The name of the location, venue, landmark, or address to search for (e.g. 'CentralWorld', 'Siam Paragon', '横店影视城', 'วัดพระแก้ว', 'ประตูท่าแพ')."
+          },
+          limit: {
+            type: "number",
+            description: "Maximum number of search results to return (default: 5, max: 10)."
+          }
+        },
+        required: ["query"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_weather",
+      description: "Get real-time weather forecast, temperature, humidity, precipitation, wind speed, and conditions for any named city, landmark, or current location. Call this whenever answering questions about weather, rain, temperature, or climate. If the user specifies a place (e.g. 'CentralWorld', 'เซ็นทรัลเวิลด์', 'Chiang Mai'), pass it in 'location'.",
+      parameters: {
+        type: "object",
+        properties: {
+          location: {
+            type: "string",
+            description: "City, province, district, or landmark name (e.g. 'เซ็นทรัลเวิลด์', 'CentralWorld', 'กรุงเทพ', 'เชียงใหม่', 'Bangkok', 'Tokyo', 'Shanghai'). If omitted, uses current user location."
+          },
+          latitude: {
+            type: "number",
+            description: "Optional latitude coordinate."
+          },
+          longitude: {
+            type: "number",
+            description: "Optional longitude coordinate."
+          }
+        },
+        required: []
+      }
+    }
+  },
   {
     type: "function",
     function: {
@@ -559,9 +664,12 @@ Searches raw text catalog across all unindexed cross-domain documents.`,
       parameters: {
         type: "object",
         properties: {
-          query: { type: "string", description: "Search query keyword" }
+          keywords: { type: "string", description: "Canonical search keywords with conversational filler removed" },
+          target_language: { type: "string", enum: ["zh", "th", "en", "ja", "ko"], description: "Preferred language for search results" },
+          domain_filter: { type: "array", items: { type: "string" }, description: "Optional hostnames to prioritize or restrict, e.g. ['weibo.com', 'bilibili.com']" },
+          query: { type: "string", description: "Deprecated compatibility alias for keywords" }
         },
-        required: ["query"]
+        required: []
       }
     }
   },
@@ -569,7 +677,7 @@ Searches raw text catalog across all unindexed cross-domain documents.`,
     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.",
+      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. Login-walled or JavaScript-heavy social pages (Weibo, Douyin, Xiaohongshu) may return no readable text; when that happens, retry the mobile-mirror URL and then search_chinese_web / search_news on the topic instead of giving up.",
       parameters: {
         type: "object",
         properties: {
@@ -583,13 +691,13 @@ Searches raw text catalog across all unindexed cross-domain documents.`,
     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.",
+      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. For third-party or general external APIs, use fetch_json instead.",
       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)" }
+          endpoint: { type: "string", description: "API endpoint path under /api/v1/ (e.g. 'profile', 'works', 'discography', 'mv', 'brands', 'timeline', 'awards', 'gallery', 'social', 'character-roles', 'fandom', 'quotes', 'stats', 'search'). Automatic aliases ('music' -> 'discography', 'commercial' -> 'brands', 'milestones' -> 'timeline', 'honors' -> 'awards') are supported." },
+          query: { type: "string", description: "Optional search/filter query parameter ('q')" },
+          baseUrl: { type: "string", description: "Optional override base URL (defaults to https://jujingyi-kikuuu.vercel.app/api/v1, or http://localhost:3000/api/v1 in local development)" }
         },
         required: ["endpoint"]
       }
@@ -682,10 +790,13 @@ Searches raw text catalog across all unindexed cross-domain documents.`,
       parameters: {
         type: "object",
         properties: {
-          query: { type: "string", description: "News search query, e.g. '鞠婧祎 最新' or 'Ju Jingyi news'" },
+          keywords: { type: "string", description: "Canonical news keywords, e.g. '鞠婧祎 最新'" },
+          target_language: { type: "string", enum: ["zh", "th", "en", "ja", "ko"] },
+          domain_filter: { type: "array", items: { type: "string" }, description: "Optional news or official-site hostnames" },
+          query: { type: "string", description: "Deprecated compatibility alias for keywords" },
           maxResults: { type: "number", description: "Max results (default 8, max 15)" }
         },
-        required: ["query"]
+        required: []
       }
     }
   },
@@ -712,11 +823,14 @@ Searches raw text catalog across all unindexed cross-domain documents.`,
       parameters: {
         type: "object",
         properties: {
-          term: { type: "string", description: "Encyclopedia term to look up, e.g. '鞠婧祎', 'Ju Jingyi', 'SNH48'" },
+          term: { type: "string", description: "Deprecated compatibility alias for keywords" },
+          keywords: { type: "string", description: "Canonical lookup term, e.g. '宋昕冉 SNH48'" },
+          query: { type: "string", description: "Deprecated compatibility alias for keywords" },
           language: { type: "string", enum: ["zh", "th", "en"], description: "Optional: force language. Defaults to auto-detect from the term." },
+          target_language: { type: "string", enum: ["zh", "th", "en", "ja", "ko"], description: "Preferred language for results when language is unset" },
           maxEntries: { type: "number", description: "Max encyclopedia entries to return (default 2, max 3)" }
         },
-        required: ["term"]
+        required: []
       }
     }
   },
@@ -728,10 +842,12 @@ Searches raw text catalog across all unindexed cross-domain documents.`,
       parameters: {
         type: "object",
         properties: {
-          term: { type: "string", description: "Song/album/artist search term, e.g. 'Ju Jingyi' or '叹云兮'" },
+          term: { type: "string", description: "Deprecated compatibility alias for keywords" },
+          keywords: { type: "string", description: "Canonical song/album/artist search term, e.g. 'Ju Jingyi 叹云兮'" },
+          query: { type: "string", description: "Deprecated compatibility alias for keywords" },
           maxResults: { type: "number", description: "Max results (default 8, max 20)" }
         },
-        required: ["term"]
+        required: []
       }
     }
   },
@@ -739,15 +855,18 @@ Searches raw text catalog across all unindexed cross-domain documents.`,
     type: "function",
     function: {
       name: "search_chinese_web",
-      description: "Search Chinese websites (Baidu first, then site-filtered DuckDuckGo across sina/sohu/weibo/bilibili/iqiyi/mgtv etc). Use for Chinese entertainment news, Weibo topics, and anything on Chinese portals. Requires KIKU_ENABLE_CN_WEB_TOOLS=true.",
+      description: "Search Chinese websites (Baidu first, then site-filtered DuckDuckGo across sina/sohu/weibo/bilibili/iqiyi/mgtv etc). Use for Chinese entertainment news, Weibo topics, and anything on Chinese portals. Enabled by default; set KIKU_ENABLE_CN_WEB_TOOLS=false to disable.",
       parameters: {
         type: "object",
         properties: {
-          query: { type: "string", description: "Chinese search query, e.g. '鞠婧祎 微博'" },
+          keywords: { type: "string", description: "Canonical Chinese search keywords, e.g. '鞠婧祎 微博'" },
+          target_language: { type: "string", enum: ["zh", "th", "en", "ja", "ko"] },
+          domain_filter: { type: "array", items: { type: "string" }, description: "Optional Chinese portal hostnames" },
+          query: { type: "string", description: "Deprecated compatibility alias for keywords" },
           maxResults: { type: "number", description: "Max results (default 8, max 15)" },
           site: { type: "string", description: "Optional domain hint to restrict fallback search, e.g. 'sina.com.cn'" }
         },
-        required: ["query"]
+        required: []
       }
     }
   },
@@ -755,14 +874,17 @@ Searches raw text catalog across all unindexed cross-domain documents.`,
     type: "function",
     function: {
       name: "search_bilibili",
-      description: "Search Bilibili videos via its public API (stage performances, MVs, fancams, interviews). Returns title, author, duration, play count, publish date and video URL. Requires KIKU_ENABLE_CN_WEB_TOOLS=true.",
+      description: "Search Bilibili videos via its public API (stage performances, MVs, fancams, interviews). Returns title, author, duration, play count, publish date and video URL. Enabled by default; set KIKU_ENABLE_CN_WEB_TOOLS=false to disable.",
       parameters: {
         type: "object",
         properties: {
-          keyword: { type: "string", description: "Bilibili search keyword, e.g. '鞠婧祎 舞台'" },
+          keyword: { type: "string", description: "Deprecated compatibility alias for keywords" },
+          keywords: { type: "string", description: "Canonical Bilibili search keywords, e.g. '宋昕冉 SNH48 舞台'" },
+          query: { type: "string", description: "Deprecated compatibility alias for keywords" },
+          target_language: { type: "string", enum: ["zh", "th", "en", "ja", "ko"] },
           maxResults: { type: "number", description: "Max results (default 8, max 20)" }
         },
-        required: ["keyword"]
+        required: []
       }
     }
   },
@@ -770,14 +892,17 @@ Searches raw text catalog across all unindexed cross-domain documents.`,
     type: "function",
     function: {
       name: "search_web_images",
-      description: "Search the web (Baidu Images & Chinese entertainment media portals) for photos, on-set stills (路透), red carpet appearances, and press images of Ju Jingyi. Returns direct image URLs, thumbnails, dimensions, and source article links. Requires KIKU_ENABLE_CN_WEB_TOOLS=true.",
+      description: "Search the web (Baidu Images & Chinese entertainment media portals) for photos, on-set stills (路透), red carpet appearances, and press images of Ju Jingyi. The query always includes 鞠婧祎 and results are filtered to artist-related images only. Returns direct image URLs, thumbnails, dimensions, and source article links. Enabled by default; set KIKU_ENABLE_CN_WEB_TOOLS=false to disable.",
       parameters: {
         type: "object",
         properties: {
-          query: { type: "string", description: "Image search keyword or topic, e.g. '鞠婧祎 路透', '万花世界 剧照', 'Ju Jingyi red carpet'" },
+          keywords: { type: "string", description: "Canonical image keywords or topic, e.g. '鞠婧祎 万花世界 路透'" },
+          target_language: { type: "string", enum: ["zh", "th", "en", "ja", "ko"] },
+          domain_filter: { type: "array", items: { type: "string" }, description: "Optional image-source hostnames" },
+          query: { type: "string", description: "Deprecated compatibility alias for keywords" },
           maxResults: { type: "number", description: "Max images to return (default 8, max 20)" }
         },
-        required: ["query"]
+        required: []
       }
     }
   },
@@ -866,6 +991,94 @@ Searches raw text catalog across all unindexed cross-domain documents.`,
       parameters: { type: "object", properties: {} }
     }
   },
+  {
+    type: "function",
+    function: {
+      name: "set_volume",
+      description: "Set the music playback volume level from 0 to 100 percent.",
+      parameters: {
+        type: "object",
+        properties: {
+          volume: {
+            type: "number",
+            description: "Volume percentage between 0 and 100."
+          }
+        },
+        required: ["volume"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "seek_music",
+      description: "Seek or jump playback to a specific timestamp (in seconds or mm:ss format).",
+      parameters: {
+        type: "object",
+        properties: {
+          seconds: {
+            type: "number",
+            description: "Target playback position in seconds (e.g. 90)."
+          },
+          position: {
+            type: "string",
+            description: "Target position in mm:ss format (e.g. '01:30')."
+          }
+        }
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "set_repeat_mode",
+      description: "Set playback repeat or loop mode ('one' to repeat single track, 'all' to repeat playlist, 'off' to disable repeat).",
+      parameters: {
+        type: "object",
+        properties: {
+          mode: {
+            type: "string",
+            enum: ["one", "all", "off"],
+            description: "Repeat mode: 'one', 'all', or 'off'."
+          }
+        },
+        required: ["mode"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "set_shuffle_mode",
+      description: "Enable or disable random shuffle playback.",
+      parameters: {
+        type: "object",
+        properties: {
+          enabled: {
+            type: "boolean",
+            description: "True to enable shuffle, false to disable."
+          }
+        },
+        required: ["enabled"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "toggle_video_mode",
+      description: "Toggle music video (MV) display view in the music player.",
+      parameters: {
+        type: "object",
+        properties: {
+          showVideo: {
+            type: "boolean",
+            description: "True to show video, false to hide video."
+          }
+        }
+      }
+    }
+  },
   {
     type: "function",
     function: {
@@ -924,12 +1137,11 @@ Searches raw text catalog across all unindexed cross-domain documents.`,
       parameters: {
         type: "object",
         properties: {
-          query: {
-            type: "string",
-            description: "Search query for YouTube."
-          }
+          query: { type: "string", description: "Deprecated compatibility alias for keywords" },
+          keywords: { type: "string", description: "Canonical YouTube search keywords, e.g. 'Ju Jingyi FIND THE WAY'" },
+          target_language: { type: "string", enum: ["zh", "th", "en", "ja", "ko"] }
         },
-        required: ["query"]
+        required: []
       }
     }
   },
@@ -1191,6 +1403,85 @@ Searches raw text catalog across all unindexed cross-domain documents.`,
   }
 ];
 
+export const TOOL_CAPABILITIES = {
+  get_current_datetime: ['temporal'],
+  get_user_location: ['system_location', 'temporal', 'external_retrieval'],
+  search_location_map: ['system_location', 'map_navigation', 'external_retrieval'],
+  get_weather: ['system_location', 'weather_forecast', 'external_retrieval'],
+  get_youtube_transcript: ['media_transcript', 'live_verification'],
+  get_profile_and_fandom: ['catalog_profile', 'biography'],
+  get_quotes: ['catalog_profile'],
+  search_works: ['catalog_works', 'filmography'],
+  get_work_detail: ['catalog_works', 'filmography'],
+  get_character_roles: ['catalog_works', 'filmography'],
+  search_discography: ['catalog_music', 'discography'],
+  get_music_videos: ['catalog_music', 'media'],
+  get_media_links: ['catalog_media'],
+  get_brand_endorsements: ['catalog_brands', 'commercial'],
+  get_career_timeline: ['catalog_timeline', 'biography'],
+  get_awards: ['catalog_awards', 'honors'],
+  get_social_feed: ['catalog_social'],
+  get_gallery_photos: ['catalog_gallery', 'images'],
+  global_search: ['catalog_omni', 'search'],
+  web_search: ['web_search', 'live_verification', 'external_retrieval'],
+  fetch_webpage: ['web_content', 'live_verification', 'external_retrieval'],
+  fetch_api: ['external_api'],
+  fetch_json: ['external_api'],
+  read_local_file: ['file_system'],
+  list_directory: ['file_system'],
+  screenshot_webpage: ['web_render', 'visual'],
+  web_extract: ['web_content', 'live_verification', 'external_retrieval'],
+  search_news: ['news', 'live_verification', 'temporal'],
+  fetch_rss: ['news', 'live_verification', 'temporal'],
+  search_encyclopedia: ['encyclopedia', 'live_verification'],
+  search_music_platforms: ['music_search', 'live_verification'],
+  search_chinese_web: ['chinese_web', 'live_verification', 'external_retrieval'],
+  search_bilibili: ['chinese_video', 'live_verification', 'media'],
+  search_web_images: ['images', 'live_verification'],
+  get_system_stats: ['system_telemetry'],
+  play_music: ['music_control', 'audio_playback'],
+  stop_music: ['music_control', 'audio_playback'],
+  mute_music: ['music_control', 'audio_playback'],
+  unmute_music: ['music_control', 'audio_playback'],
+  pause_music: ['music_control', 'audio_playback'],
+  resume_music: ['music_control', 'audio_playback'],
+  next_track: ['music_control', 'audio_playback'],
+  prev_track: ['music_control', 'audio_playback'],
+  set_volume: ['music_control', 'audio_playback'],
+  seek_music: ['music_control', 'audio_playback'],
+  set_repeat_mode: ['music_control', 'audio_playback'],
+  set_shuffle_mode: ['music_control', 'audio_playback'],
+  toggle_video_mode: ['music_control', 'video_playback'],
+  add_to_queue: ['music_control', 'queue_management'],
+  remove_from_queue: ['music_control', 'queue_management'],
+  clear_queue: ['music_control', 'queue_management'],
+  get_queue: ['music_control', 'queue_management'],
+  search_youtube: ['music_search', 'video_search'],
+  get_current_track: ['music_control', 'audio_status'],
+  get_music_status: ['music_control', 'audio_status'],
+  run_subagent: ['autonomous_agent'],
+  run_deep_research: ['autonomous_agent', 'research'],
+  verify_claim: ['fact_check', 'live_verification'],
+  suggest_topics: ['recommendation'],
+  manage_skill: ['skill_management'],
+  run_quiz: ['entertainment', 'quiz'],
+  get_api_key: ['system_auth'],
+  get_entertainment_metrics: ['industry_metrics'],
+  get_industry_index: ['industry_metrics'],
+  checkpoint_step: ['memory_checkpoint'],
+  record_failure: ['memory_failure'],
+  load_active_run: ['memory_context'],
+  record_dynamic_event: ['catalog_write']
+};
+
+for (const item of toolsSchema) {
+  const name = item.function?.name;
+  if (name && TOOL_CAPABILITIES[name]) {
+    item.capabilities = TOOL_CAPABILITIES[name];
+    if (item.function) item.function.capabilities = TOOL_CAPABILITIES[name];
+  }
+}
+
 
 const TOOL_DEFAULT_TIMEOUTS = {
   run_subagent: 180_000,
@@ -1211,9 +1502,10 @@ const TOOL_DEFAULT_TIMEOUTS = {
   search_web_images: 60_000,
 };
 
-const isCnWebEnabled = () => process.env.KIKU_ENABLE_CN_WEB_TOOLS === 'true';
+const CN_WEB_DISABLED_VALUES = new Set(['false', '0', 'off', 'no']);
+const isCnWebEnabled = () => !CN_WEB_DISABLED_VALUES.has((process.env.KIKU_ENABLE_CN_WEB_TOOLS ?? '').trim().toLowerCase());
 const cnWebDisabledMessage = (toolName) =>
-  `"${toolName}" is disabled. Set KIKU_ENABLE_CN_WEB_TOOLS=true to enable Chinese web tools (Baidu/Baike/Bilibili scraping — these sites use anti-bot protection and may be unreliable). Meanwhile use web_search, search_news, or search_encyclopedia.`;
+  `"${toolName}" is disabled because KIKU_ENABLE_CN_WEB_TOOLS="${(process.env.KIKU_ENABLE_CN_WEB_TOOLS ?? '').trim()}" is set in the environment. Remove that line (or set KIKU_ENABLE_CN_WEB_TOOLS=true) in your .env file — the package-root .env for repo checkouts, or ${USER_ENV_PATH} for global installs — to enable Chinese web tools (Baidu/Baike/Bilibili scraping — these sites use anti-bot protection and may be unreliable). Meanwhile use web_search, search_news, or search_encyclopedia.`;
 
 async function ensureLlmAvailable(client) {
   if (!client || typeof client.checkConnection !== 'function') return null;
@@ -1261,6 +1553,301 @@ export const toolHandlers = {
     };
   },
 
+  get_user_location: async (args = {}, options = {}) => {
+    const passedLoc = options.clientLocation || options.location || options.agent?.clientLocation;
+
+    if (passedLoc && passedLoc.denied) {
+      return {
+        status: "permission_denied_or_unavailable",
+        location_granted: false,
+        source: "client_denied",
+        message: "User declined to share geolocation coordinates. Continuing with fallback or asking user to specify city name."
+      };
+    }
+
+    const rawQuery = String(args.query || args.place || args.location || '').trim();
+    if (rawQuery && !passedLoc && typeof args.latitude !== 'number') {
+      const searchResults = await searchLocationOsm(rawQuery, options);
+      if (searchResults && searchResults.length > 0) {
+        const top = searchResults[0];
+        const nearest = findNearestLandmark(top.latitude, top.longitude);
+        const weather = await fetchRealtimeWeather(top.latitude, top.longitude, options);
+        const confidence = scoreLocationConfidence({
+          source: "osm_query_search",
+          accuracy: null
+        });
+
+        let summaryParts = [`Location resolved for "${rawQuery}": ${top.displayName} (${top.latitude.toFixed(4)}, ${top.longitude.toFixed(4)})`];
+        if (nearest) {
+          summaryParts.push(nearest.summaryTh);
+        }
+        if (weather && weather.summaryTh) {
+          summaryParts.push(weather.summaryTh);
+        }
+        summaryParts.push(top.mapTag);
+
+        return {
+          status: "success",
+          location_granted: true,
+          source: "osm_query_search",
+          query: rawQuery,
+          coordinates: { latitude: top.latitude, longitude: top.longitude },
+          latitude: top.latitude,
+          longitude: top.longitude,
+          formatted_address: top.displayName,
+          subdistrict: top.subdistrict,
+          district: top.district,
+          city: top.city || top.province || rawQuery,
+          province: top.province,
+          country: top.country,
+          postcode: top.postcode,
+          weather,
+          nearest_landmark: nearest,
+          confidence,
+          map_url: top.mapUrl,
+          map_tag: top.mapTag,
+          results: searchResults,
+          message: summaryParts.join('. ')
+        };
+      }
+    }
+
+    const hasExplicitCoords = typeof args.latitude === 'number' && typeof args.longitude === 'number';
+    const hasPassedCoords = passedLoc && (typeof passedLoc.latitude === 'number' || typeof passedLoc.lat === 'number');
+
+    if (hasExplicitCoords || hasPassedCoords) {
+      const lat = hasExplicitCoords ? Number(args.latitude) : Number(passedLoc.latitude ?? passedLoc.lat);
+      const lon = hasExplicitCoords ? Number(args.longitude) : Number(passedLoc.longitude ?? passedLoc.lon ?? passedLoc.lng);
+      const accuracy = passedLoc?.accuracy || null;
+      const tz = String(passedLoc?.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone || 'Asia/Bangkok');
+
+      const geo = await reverseGeocodeOsm(lat, lon, options);
+      const nearest = findNearestLandmark(lat, lon);
+      const weather = await fetchRealtimeWeather(lat, lon, options);
+
+      const city = String(geo?.city || passedLoc?.city || passedLoc?.locality || (nearest ? nearest.landmark.city : 'Bangkok'));
+      const country = String(geo?.country || passedLoc?.country || (nearest ? nearest.landmark.country : 'Thailand'));
+      const region = String(geo?.province || passedLoc?.region || passedLoc?.state || city);
+      const subdistrict = String(geo?.subdistrict || '');
+      const district = String(geo?.district || '');
+      const postcode = String(geo?.postcode || '');
+      const formattedAddress = String(geo?.displayName || `${district ? district + ', ' : ''}${city}, ${country}`);
+      const mapUrl = geo?.mapUrl || buildOsmUrl(lat, lon);
+      const mapTag = geo?.mapTag || buildOsmMapTag(lat, lon, district || city || 'Location');
+
+      let summaryParts = [`User location retrieved: ${formattedAddress} (${lat.toFixed(4)}, ${lon.toFixed(4)})`];
+      if (nearest) {
+        summaryParts.push(nearest.summaryTh);
+      }
+      if (weather && weather.summaryTh) {
+        summaryParts.push(weather.summaryTh);
+      }
+      summaryParts.push(mapTag);
+
+      return {
+        status: "success",
+        location_granted: true,
+        source: hasExplicitCoords ? "explicit_coordinates" : "client_location",
+        coordinates: { latitude: lat, longitude: lon },
+        latitude: lat,
+        longitude: lon,
+        accuracy,
+        formatted_address: formattedAddress,
+        subdistrict,
+        district,
+        city,
+        region,
+        province: geo?.province || region,
+        country,
+        country_code: geo?.countryCode || '',
+        postcode,
+        timezone: tz,
+        weather,
+        nearest_landmark: nearest,
+        confidence: scoreLocationConfidence({
+          source: hasExplicitCoords ? "explicit_coordinates" : "client_location",
+          accuracy
+        }),
+        map_url: mapUrl,
+        map_tag: mapTag,
+        message: summaryParts.join('. ')
+      };
+    }
+
+    const ipLoc = await detectIpLocation(options);
+    const lat = ipLoc.latitude;
+    const lon = ipLoc.longitude;
+    const fallbackNearest = findNearestLandmark(lat, lon);
+    const weather = await fetchRealtimeWeather(lat, lon, options);
+
+    let summaryParts = [`Location detected: ${ipLoc.city}, ${ipLoc.country} (${lat.toFixed(4)}, ${lon.toFixed(4)})`];
+    if (fallbackNearest) {
+      summaryParts.push(fallbackNearest.summaryTh);
+    }
+    if (weather && weather.summaryTh) {
+      summaryParts.push(weather.summaryTh);
+    }
+    const mapTag = buildOsmMapTag(lat, lon, ipLoc.city);
+    summaryParts.push(mapTag);
+
+    return {
+      status: "success",
+      location_granted: true,
+      is_estimated_location: true,
+      source: ipLoc.source,
+      reason: args.reason || "weather_forecast",
+      timezone: ipLoc.timezone,
+      estimated_city: ipLoc.city,
+      estimatedLocation: {
+        city: ipLoc.city,
+        region: ipLoc.region,
+        country: ipLoc.country,
+        latitude: lat,
+        longitude: lon,
+        timezone: ipLoc.timezone
+      },
+      latitude: lat,
+      longitude: lon,
+      city: ipLoc.city,
+      country: ipLoc.country,
+      weather,
+      nearest_landmark: fallbackNearest,
+      confidence: scoreLocationConfidence({
+        source: ipLoc.source,
+        accuracy: null
+      }),
+      map_url: buildOsmUrl(lat, lon),
+      map_tag: mapTag,
+      quickCityChoices: [
+        { nameTh: 'กรุงเทพมหานคร', nameEn: 'Bangkok', latitude: 13.7563, longitude: 100.5018 },
+        { nameTh: 'เชียงใหม่', nameEn: 'Chiang Mai', latitude: 18.7883, longitude: 98.9853 },
+        { nameTh: 'ภูเก็ต', nameEn: 'Phuket', latitude: 7.8804, longitude: 98.3923 },
+        { nameTh: 'ขอนแก่น', nameEn: 'Khon Kaen', latitude: 16.4419, longitude: 102.8360 },
+        { nameTh: 'พัทยา', nameEn: 'Pattaya', latitude: 12.9276, longitude: 100.8771 }
+      ],
+      message: summaryParts.join('. ')
+    };
+  },
+
+  get_weather: async (args = {}, options = {}) => {
+    let lat = null;
+    let lon = null;
+    let locationName = '';
+    let mapTag = '';
+    let isEstimated = false;
+
+    const query = String(args.location || args.place || args.city || '').trim();
+    if (query) {
+      const searchResults = await searchLocationOsm(query, options);
+      if (searchResults && searchResults.length > 0) {
+        const top = searchResults[0];
+        lat = top.latitude;
+        lon = top.longitude;
+        locationName = top.displayName;
+        mapTag = top.mapTag;
+      }
+    }
+
+    if (lat === null && typeof args.latitude === 'number' && typeof args.longitude === 'number') {
+      lat = Number(args.latitude);
+      lon = Number(args.longitude);
+      locationName = `พิกัด (${lat.toFixed(4)}, ${lon.toFixed(4)})`;
+      mapTag = buildOsmMapTag(lat, lon, locationName);
+    }
+
+    const clientLoc = options.clientLocation || options.location || options.agent?.clientLocation;
+    if (lat === null && clientLoc && typeof clientLoc.latitude === 'number') {
+      lat = Number(clientLoc.latitude);
+      lon = Number(clientLoc.longitude ?? clientLoc.lon);
+      locationName = String(clientLoc.city || clientLoc.formatted_address || 'Current Location');
+      mapTag = buildOsmMapTag(lat, lon, locationName);
+    }
+
+    if (lat === null) {
+      const ipLoc = await detectIpLocation(options);
+      lat = ipLoc.latitude;
+      lon = ipLoc.longitude;
+      locationName = `${ipLoc.city}, ${ipLoc.country}`;
+      mapTag = buildOsmMapTag(lat, lon, ipLoc.city);
+      isEstimated = true;
+    }
+
+    const weather = await fetchRealtimeWeather(lat, lon, options);
+    const nearest = findNearestLandmark(lat, lon);
+
+    return {
+      status: "success",
+      location: locationName,
+      latitude: lat,
+      longitude: lon,
+      is_estimated_location: isEstimated,
+      current_weather: weather,
+      nearest_landmark: nearest,
+      confidence: scoreLocationConfidence({
+        source: isEstimated ? 'ip_lookup' : (query ? 'osm_query_search' : 'explicit_coordinates'),
+        accuracy: null
+      }),
+      map_tag: mapTag,
+      message: weather ?
+        `สภาพอากาศ ณ ${locationName}: ${weather.summaryTh} ${nearest ? '(' + nearest.summaryTh + ')' : ''}. ${mapTag}` :
+        `ตำแหน่งที่ตั้ง: ${locationName}. ไม่สามารถดึงข้อมูลสภาพอากาศได้ในขณะนี้ ${mapTag}`
+    };
+  },
+
+  search_location_map: async (args = {}, options = {}) => {
+    const rawQuery = String(args.query || args.location || args.place || '').trim();
+    if (!rawQuery) {
+      return {
+        status: "error",
+        message: "Parameter 'query' is required to search for a location map."
+      };
+    }
+
+    const limit = Number(args.limit) > 0 ? Number(args.limit) : 5;
+    const results = await searchLocationOsm(rawQuery, { ...options, limit });
+
+    if (!results || results.length === 0) {
+      return {
+        status: "success",
+        count: 0,
+        query: rawQuery,
+        results: [],
+        message: `ไม่พบข้อมูลพิกัดสถานที่สำหรับ "${rawQuery}" บน OpenStreetMap กรุณาลองใช้ชื่อสถานที่หรือคำค้นหาอื่น`
+      };
+    }
+
+    const top = results[0];
+    const nearest = findNearestLandmark(top.latitude, top.longitude);
+    const weather = await fetchRealtimeWeather(top.latitude, top.longitude, options);
+
+    let summaryLines = [`พบพิกัดบน OpenStreetMap สำหรับ "${rawQuery}" ดังนี้:`];
+    results.forEach((r, idx) => {
+      summaryLines.push(`${idx + 1}. ${r.name} (${r.province || r.city || r.country}) [Lat: ${r.latitude.toFixed(4)}, Lon: ${r.longitude.toFixed(4)}]`);
+    });
+
+    summaryLines.push(`\nพิกัดหลัก: ${top.displayName}`);
+    if (nearest) {
+      summaryLines.push(`สถานที่ใกล้เคียง: ${nearest.summaryTh}`);
+    }
+    if (weather && weather.summaryTh) {
+      summaryLines.push(`สภาพอากาศ: ${weather.summaryTh}`);
+    }
+    summaryLines.push(`\nแผนที่ปักหมุด: ${top.mapTag}`);
+
+    return {
+      status: "success",
+      count: results.length,
+      query: rawQuery,
+      primaryLocation: top,
+      nearest_landmark: nearest,
+      weather,
+      results,
+      map_url: top.mapUrl,
+      map_tag: top.mapTag,
+      message: summaryLines.join('\n')
+    };
+  },
+
   get_youtube_transcript: async (args = {}) => fetchYoutubeTranscript(args),
 
   get_profile_and_fandom: async ({ section, query } = {}) => {
@@ -1366,8 +1953,8 @@ export const toolHandlers = {
         broadMatch = true;
       } else {
         results = results.filter(w => matcher(
-          w.titleTh, w.titleEn, w.titleCn, w.role, w.roleCn, w.synopsis,
-          ...(w.aliases || []), ...(w.keywords || [])
+          w.titleTh, w.titleEn, w.titleCn, w.role, w.roleCn, w.synopsis, w.category,
+          ...(w.highlights || []), ...(w.aliases || []), ...(w.keywords || [])
         ));
       }
     }
@@ -1380,8 +1967,8 @@ export const toolHandlers = {
       let relaxed = [...baseWorks];
       const fallbackMatcher = matcher || createCatalogMatcher(query);
       relaxed = relaxed.filter(w => fallbackMatcher(
-        w.titleTh, w.titleEn, w.titleCn, w.role, w.roleCn, w.synopsis,
-        ...(w.aliases || []), ...(w.keywords || [])
+        w.titleTh, w.titleEn, w.titleCn, w.role, w.roleCn, w.synopsis, w.category,
+        ...(w.highlights || []), ...(w.aliases || []), ...(w.keywords || [])
       ));
       if (relaxed.length > 0) {
         results = relaxed;
@@ -2112,7 +2699,10 @@ export const toolHandlers = {
     const matcher = createCatalogMatcher(query);
 
     const matchedWorks = worksData.filter(w =>
-      matcher(w.titleTh, w.titleEn, w.titleCn, w.role, w.roleCn)
+      matcher(
+        w.titleTh, w.titleEn, w.titleCn, w.role, w.roleCn, w.synopsis, w.category,
+        ...(w.highlights || []), ...(w.aliases || []), ...(w.keywords || [])
+      )
     ).slice(0, 4).map(w => ({
       title: `${w.titleTh} (${w.year}) - Role: ${w.role}`,
       trailerYouTubeSearch: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${w.titleCn || w.titleEn} Trailer`)
@@ -2167,8 +2757,15 @@ export const toolHandlers = {
     };
   },
 
-  web_search: async ({ query } = {}) => {
-    return await searchWeb(query);
+  web_search: async (args = {}) => {
+    const plan = planSearchRequest(args, { kind: 'web' });
+    if (!plan.originalQuery) return { status: 'error', message: 'query parameter is required (use keywords for new callers).' };
+    return await searchWeb(plan.keywords, undefined, {
+      originalQuery: plan.originalQuery,
+      targetLanguage: plan.targetLanguage,
+      allowedDomains: plan.domains,
+      queryPlan: plan,
+    });
   },
 
   fetch_webpage: async ({ url } = {}) => {
@@ -2176,41 +2773,96 @@ export const toolHandlers = {
   },
 
   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 originCheck = sanitizeUrl(base);
+    if (!endpoint) return { status: "error", message: "endpoint parameter is required (e.g. 'profile', 'works', 'discography', 'brands', 'timeline', 'awards')" };
+    const defaultBase = 'https://jujingyi-kikuuu.vercel.app/api/v1';
+    let rawBase = String(baseUrl || defaultBase).trim().replace(/\/+$/, '');
+    if (!rawBase.includes('/api/v1')) {
+      rawBase = `${rawBase}/api/v1`;
+    }
+    const originCheck = sanitizeUrl(rawBase, { allowLoopback: true });
     if (!originCheck.safe) {
       return { status: "error", message: `Unsafe API base URL: ${originCheck.reason}` };
     }
+
+    const isLocalOrigin = Boolean(originCheck.url && (
+      originCheck.url.hostname === 'localhost' ||
+      originCheck.url.hostname === '127.0.0.1' ||
+      originCheck.url.hostname.endsWith('.local')
+    ));
+
     const allowedOrigins = new Set([
       'https://jujingyi-kikuuu.vercel.app',
       ...(process.env.KIKU_API_ALLOWED_ORIGINS || '').split(',').map(value => value.trim()).filter(Boolean)
     ]);
-    if (!originCheck.url || !allowedOrigins.has(originCheck.url.origin)) {
+    if (!originCheck.url || (!isLocalOrigin && !allowedOrigins.has(originCheck.url.origin))) {
       return { status: 'error', message: 'API base origin is not allowlisted.' };
     }
-    const path = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
-    const target = new URL(`${base}/${endpoint.replace(/^\/+/, '')}`);
-    if (target.origin !== originCheck.url.origin || !target.pathname.startsWith('/api/v1/')) {
-      return { status: 'error', message: 'API endpoint must remain under /api/v1/.' };
+
+    let rawEndpoint = String(endpoint || '').trim();
+    if (/^https?:\/\//i.test(rawEndpoint)) {
+      try {
+        const parsedEndpoint = new URL(rawEndpoint);
+        if (parsedEndpoint.origin !== originCheck.url.origin && !isLocalOrigin) {
+          return { status: 'error', message: `API endpoint must point to ${originCheck.url.origin}. For general external APIs, use fetch_json(url=...) instead.` };
+        }
+        rawEndpoint = `${parsedEndpoint.pathname}${parsedEndpoint.search}`;
+      } catch {}
+    }
+
+    let cleanPath = rawEndpoint.replace(/^\/?api\/v1\/?/i, '').replace(/^\/+/, '');
+    const qIndex = cleanPath.indexOf('?');
+    let pathPart = qIndex >= 0 ? cleanPath.slice(0, qIndex) : cleanPath;
+    const queryPart = qIndex >= 0 ? cleanPath.slice(qIndex + 1) : '';
+
+    const ENDPOINT_ALIASES = {
+      'music': 'discography',
+      'songs': 'discography',
+      'tracks': 'discography',
+      'commercial': 'brands',
+      'endorsements': 'brands',
+      'milestones': 'timeline',
+      'history': 'timeline',
+      'honors': 'awards',
+      'drama': 'works',
+      'dramas': 'works',
+      'videos': 'mv',
+      'photos': 'gallery'
+    };
+
+    const firstSegment = pathPart.split('/')[0].toLowerCase();
+    if (ENDPOINT_ALIASES[firstSegment]) {
+      const rest = pathPart.slice(firstSegment.length);
+      pathPart = `${ENDPOINT_ALIASES[firstSegment]}${rest}`;
+    }
+
+    const finalPath = `/${pathPart}`;
+    const target = new URL(`${originCheck.url.origin}/api/v1${finalPath}`);
+
+    if (queryPart) {
+      const existingParams = new URLSearchParams(queryPart);
+      for (const [k, v] of existingParams.entries()) {
+        target.searchParams.set(k, v);
+      }
+    }
+    if (query) {
+      target.searchParams.set('q', query);
     }
-    if (query) target.searchParams.set('q', query);
 
     try {
-      const result = await fetchJson(target.href, { timeoutMs: 10000, maxResponseLength: 100000 });
+      const result = await fetchJson(target.href, { timeoutMs: 10000, maxResponseLength: 100000, allowLoopback: isLocalOrigin });
       if (result.status !== 'success') return result;
       const json = result.data;
       const data = json?.data || json;
       return {
         status: "success",
-        endpoint: path,
+        endpoint: finalPath,
         count: Array.isArray(data) ? data.length : undefined,
         data
       };
     } catch (err) {
       return {
         status: "error",
-        endpoint: path,
+        endpoint: finalPath,
         message: err.name === 'AbortError' ? 'API request timed out' : err.message
       };
     }
@@ -2220,42 +2872,59 @@ export const toolHandlers = {
     return await fetchJson(url, { method, headers, body });
   },
 
-  search_news: async ({ query, maxResults } = {}) => {
-    if (!query) return { status: 'error', message: 'query parameter is required.' };
-    return await searchNews(query, maxResults);
+  search_news: async (args = {}) => {
+    const plan = planSearchRequest(args, { kind: 'news' });
+    if (!plan.originalQuery) return { status: 'error', message: 'query parameter is required (use keywords for new callers).' };
+    return await searchNews(plan.keywords, args.maxResults, { queryPlan: plan });
   },
 
   fetch_rss: async ({ url, maxItems } = {}) => {
     return await fetchRssFeed(url, maxItems);
   },
 
-  search_encyclopedia: async ({ term, language, maxEntries } = {}) => {
-    if (!term) return { status: 'error', message: 'term parameter is required.' };
-    const lang = ['zh', 'th', 'en'].includes(language) ? language : detectLanguage(term);
-    return await searchEncyclopedia(term, lang, maxEntries);
+  search_encyclopedia: async (args = {}) => {
+    const plan = planSearchRequest({
+      keywords: args.keywords || args.term || args.query || '',
+      target_language: args.language || args.target_language,
+    });
+    if (!plan.originalQuery) return { status: 'error', message: 'term parameter is required (use keywords for new callers).' };
+    const term = plan.entities[0]?.native || plan.keywords || plan.originalQuery;
+    const lang = ['zh', 'th', 'en'].includes(args.language) ? args.language : detectLanguage(term);
+    return await searchEncyclopedia(term, lang, args.maxEntries);
   },
 
-  search_music_platforms: async ({ term, maxResults } = {}) => {
-    if (!term) return { status: 'error', message: 'term parameter is required.' };
-    return await searchMusicPlatforms(term, maxResults);
+  search_music_platforms: async (args = {}) => {
+    const plan = planSearchRequest({
+      keywords: args.keywords || args.term || args.query || '',
+      target_language: args.target_language,
+    });
+    if (!plan.originalQuery) return { status: 'error', message: 'term parameter is required (use keywords for new callers).' };
+    return await searchMusicPlatforms(plan.keywords || plan.originalQuery, args.maxResults);
   },
 
-  search_chinese_web: async ({ query, maxResults, site } = {}) => {
+  search_chinese_web: async (args = {}) => {
     if (!isCnWebEnabled()) return { status: 'error', gated: true, message: cnWebDisabledMessage('search_chinese_web') };
-    if (!query) return { status: 'error', message: 'query parameter is required.' };
-    return await searchChineseWeb(query, maxResults, { site });
+    const plan = planSearchRequest(args, { kind: 'chinese' });
+    if (!plan.originalQuery) return { status: 'error', message: 'query parameter is required (use keywords for new callers).' };
+    return await searchChineseWeb(plan.keywords, args.maxResults, {
+      site: args.site,
+      allowedDomains: plan.domains,
+      queryPlan: plan,
+    });
   },
 
-  search_bilibili: async ({ keyword, maxResults } = {}) => {
+  search_bilibili: async (args = {}) => {
     if (!isCnWebEnabled()) return { status: 'error', gated: true, message: cnWebDisabledMessage('search_bilibili') };
-    if (!keyword) return { status: 'error', message: 'keyword parameter is required.' };
-    return await searchBilibili(keyword, maxResults);
+    const plan = planSearchRequest(args, { kind: 'chinese' });
+    if (!plan.originalQuery) return { status: 'error', message: 'keyword parameter is required (use keywords for new callers).' };
+    return await searchBilibili(plan.keywords || plan.originalQuery, args.maxResults);
   },
 
-  search_web_images: async ({ query, maxResults } = {}) => {
+  search_web_images: async (args = {}) => {
     if (!isCnWebEnabled()) return { status: 'error', gated: true, message: cnWebDisabledMessage('search_web_images') };
-    if (!query) return { status: 'error', message: 'query parameter is required.' };
-    return await searchWebImages(query, maxResults);
+    const plan = planSearchRequest(args, { kind: 'image' });
+    if (!plan.originalQuery) return { status: 'error', message: 'query parameter is required (use keywords for new callers).' };
+    return await searchWebImages(plan.keywords, args.maxResults, { queryPlan: plan });
   },
 
   read_local_file: async ({ path: filePath, maxLines = 200 } = {}) => {
@@ -2420,56 +3089,147 @@ export const toolHandlers = {
 
   play_music: async (args) => {
     try {
-      const query = args.query || '';
+      const query = (args.query || '').trim();
+      if (!query) {
+        return { status: 'error', action: 'play', message: 'No song query provided. Tell me a Ju Jingyi song or OST name.' };
+      }
+      const catalogMatch = resolveCatalogSong(query);
+      const songInfo = catalogMatch ? catalogMatch : null;
+      const effectiveTitle = songInfo?.title || 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 };
+      const searchQuery = (!hasArtist && !isUrl) ? `Ju Jingyi ${effectiveTitle}` : effectiveTitle;
+      const youtubeUrl = songInfo?.youtubeId
+        ? buildYouTubeWatchUrl(songInfo.youtubeId)
+        : buildYouTubeSearchUrl(searchQuery);
+      let playMsg = '';
+      let localPlayback = false;
+      let playbackError = null;
+      try {
+        playMsg = await audioPlayer.play(searchQuery);
+        localPlayback = true;
+      } catch (err) {
+
+        playbackError = err?.message || 'Local audio unavailable';
+        playMsg = `Local audio unavailable (${playbackError}). Listen here: ${youtubeUrl}`;
+      }
+      return {
+        status: 'success',
+        action: 'play',
+        message: playMsg,
+        playing: effectiveTitle,
+        song: songInfo,
+        youtubeUrl,
+        localPlayback,
+        ...(playbackError ? { playbackError } : {})
+      };
     } catch (err) {
-      return { status: 'error', message: err.message };
+      return { status: 'error', action: 'play', message: err.message };
     }
   },
 
   stop_music: async () => {
-    const result = await audioPlayer.stop();
-    return { status: 'success', message: result };
+    const result = audioPlayer.stop();
+    return { status: 'success', action: 'stop', message: `[OK] ${result || 'Playback stopped'}` };
   },
 
   mute_music: async () => {
-    const result = await audioPlayer.mute();
-    return { status: 'success', message: result };
+    const result = audioPlayer.mute();
+
+    if (result && result.includes('No song')) {
+      return { status: 'error', action: 'mute', message: result };
+    }
+    return { status: 'success', action: 'mute', message: `[OK] ${result || 'Muted'}` };
   },
 
   unmute_music: async () => {
-    const result = await audioPlayer.unmute();
-    return { status: 'success', message: result };
+    const result = audioPlayer.unmute();
+    if (result && result.includes('No song')) {
+      return { status: 'error', action: 'unmute', message: result };
+    }
+    return { status: 'success', action: 'unmute', message: `[OK] ${result || 'Unmuted'}` };
   },
 
   pause_music: async () => {
-    const result = await audioPlayer.pause();
-    return { status: 'success', message: result };
+    const result = audioPlayer.pause();
+    if (result && (result.includes('No song') || result.includes('already paused'))) {
+      const isIdle = result.includes('No song');
+      return { status: isIdle ? 'error' : 'success', action: 'pause', message: result };
+    }
+    return { status: 'success', action: 'pause', message: `[OK] ${result || 'Playback paused'}` };
   },
 
   resume_music: async () => {
-    const result = await audioPlayer.resume();
-    return { status: 'success', message: result };
+    const result = audioPlayer.resume();
+    if (result && result.includes('No track')) {
+      return { status: 'error', action: 'resume', message: result };
+    }
+    return { status: 'success', action: 'resume', message: `[OK] ${result || 'Playback resumed'}` };
   },
 
   next_track: async () => {
-    const result = await audioPlayer.next();
-    return { status: 'success', message: result };
+    const result = audioPlayer.next();
+    if (result && (result.includes('No next track') || result.includes('No track') || result.includes('No song'))) {
+      return { status: 'error', action: 'next', message: result };
+    }
+    return { status: 'success', action: 'next', message: `[OK] ${result || 'Skipped to next track'}`, currentTrack: audioPlayer.currentTrack };
   },
 
   prev_track: async () => {
-    const result = await audioPlayer.prev();
-    return { status: 'success', message: result };
+    const result = audioPlayer.prev();
+    if (result && (result.includes('No previous track') || result.includes('No track') || result.includes('No song'))) {
+      return { status: 'error', action: 'prev', message: result };
+    }
+    return { status: 'success', action: 'prev', message: `[OK] ${result || 'Skipped to previous track'}`, currentTrack: audioPlayer.currentTrack };
+  },
+
+  set_volume: async (args) => {
+    const vol = Math.max(0, Math.min(100, Number(args?.volume) || 0));
+    const result = audioPlayer.setVolume(vol);
+    return { status: 'success', action: 'set_volume', volume: vol, message: result };
+  },
+
+  seek_music: async (args) => {
+    let targetSec = 0;
+    if (typeof args?.seconds === 'number') {
+      targetSec = Math.max(0, args.seconds);
+    } else if (typeof args?.position === 'string') {
+      const parts = args.position.split(':').map(Number);
+      if (parts.length === 2 && !isNaN(parts[0]) && !isNaN(parts[1])) {
+        targetSec = parts[0] * 60 + parts[1];
+      } else if (!isNaN(Number(args.position))) {
+        targetSec = Number(args.position);
+      }
+    }
+    const result = audioPlayer.seek(targetSec);
+    return { status: 'success', action: 'seek', seconds: targetSec, message: result };
+  },
+
+  set_repeat_mode: async (args) => {
+    const mode = String(args?.mode || 'off').toLowerCase().trim();
+    const result = audioPlayer.setRepeatMode(mode);
+    return { status: 'success', action: 'set_repeat', mode: audioPlayer.repeatMode, message: result };
+  },
+
+  set_shuffle_mode: async (args) => {
+    const enabled = args?.enabled !== undefined ? Boolean(args.enabled) : !audioPlayer.isShuffle;
+    const result = audioPlayer.setShuffleMode(enabled);
+    return { status: 'success', action: 'set_shuffle', enabled, message: result };
+  },
+
+  toggle_video_mode: async (args) => {
+    const show = args?.showVideo !== undefined ? Boolean(args.showVideo) : true;
+    return { status: 'success', action: 'toggle_video', isVideoOpen: show, message: `Video display mode: ${show ? 'shown' : 'hidden'}` };
   },
 
   add_to_queue: async (args) => {
-    const result = await audioPlayer.addToQueue(args.query);
-    return { status: 'success', message: result };
+    try {
+      const result = await audioPlayer.addToQueue(args.query);
+      return { status: 'success', message: result };
+    } catch (err) {
+      return { status: 'error', message: err?.message || 'Could not add track to queue' };
+    }
   },
 
   remove_from_queue: async (args) => {
@@ -2492,10 +3252,13 @@ export const toolHandlers = {
     return { status: 'success', queue };
   },
 
-  search_youtube: async (args) => {
+  search_youtube: async (args = {}) => {
     try {
-      const results = await audioPlayer.searchYouTube(args.query);
-      return { status: 'success', query: args.query, results };
+      const plan = planSearchRequest(args);
+      const query = plan.keywords || plan.originalQuery || args.query || '';
+      if (!query) return { status: 'error', message: 'query parameter is required (use keywords for new callers).' };
+      const results = await audioPlayer.searchYouTube(query);
+      return { status: 'success', query: plan.originalQuery || query, normalizedQuery: plan.keywords || query, results };
     } catch (err) {
       return { status: 'error', message: err.message };
     }
@@ -3056,5 +3819,23 @@ export const toolsRegistry = {
     schema: toolsSchema.find(t => t.function?.name === 'search_works')?.function,
     handler: toolHandlers.search_works,
   },
+  get_user_location: {
+    domain: 'location',
+    isCore: false,
+    schema: toolsSchema.find(t => t.function?.name === 'get_user_location')?.function,
+    handler: toolHandlers.get_user_location,
+  },
+  search_location_map: {
+    domain: 'location',
+    isCore: false,
+    schema: toolsSchema.find(t => t.function?.name === 'search_location_map')?.function,
+    handler: toolHandlers.search_location_map,
+  },
+  get_weather: {
+    domain: 'location',
+    isCore: false,
+    schema: toolsSchema.find(t => t.function?.name === 'get_weather')?.function,
+    handler: toolHandlers.get_weather,
+  },
 };