kiku-agent 1.0.7 → 1.0.9

package/server/agent/commandFeatures.js

@@ -0,0 +1,517 @@
+import { executeTool } from './tools.js';
+import { allowlistedValue, boundedInteger, parseCommandInput } from './commandInput.js';
+import { C, printSolidPanel, sanitizeTerminalText } from './ui.js';
+
+const ENTITY_TYPES = ['all', 'work', 'song', 'role', 'brand', 'award', 'photo', 'stage'];
+const FAVORITE_TYPES = ENTITY_TYPES.filter(type => type !== 'all');
+const TYPE_ALIASES = Object.freeze({
+  drama: 'work', series: 'work', movie: 'work', works: 'work',
+  music: 'song', songs: 'song', ost: 'song',
+  character: 'role', characters: 'role',
+  brands: 'brand', awards: 'award', photos: 'photo', gallery: 'photo',
+  performance: 'stage', performances: 'stage', mv: 'stage',
+});
+const OFFICIAL_NEWS_HOSTS = new Set([
+  'weibo.com', 'www.weibo.com', 'm.weibo.cn', 'bilibili.com', 'www.bilibili.com',
+  'youtube.com', 'www.youtube.com', 'instagram.com', 'www.instagram.com',
+]);
+const OFFICIAL_NEWS_SIGNAL = /\b(?:official|studio)\b|工作室|官方/i;
+
+function parsedRequest(ctx) {
+  return ctx.parsed || parseCommandInput(ctx.rawInput || '');
+}
+
+function normalizeType(value, fallback = 'all') {
+  const normalized = TYPE_ALIASES[String(value || '').toLowerCase()] || String(value || '').toLowerCase();
+  return allowlistedValue(normalized, ENTITY_TYPES, fallback);
+}
+
+function clean(value, limit = 220) {
+  return sanitizeTerminalText(String(value ?? ''), limit);
+}
+
+function printMessage(title, message, color = C.amber) {
+  printSolidPanel({ title, lines: [`${color}${clean(message, 500)}${C.reset}`] });
+}
+
+function entityTitle(type, item) {
+  if (type === 'work') {
+    const primary = item.titleTh || item.titleEn || item.titleCn;
+    const secondary = item.titleEn && item.titleEn !== primary ? item.titleEn : item.titleCn && item.titleCn !== primary ? item.titleCn : '';
+    return secondary && !String(primary || '').toLowerCase().includes(String(secondary).toLowerCase()) ? `${primary} (${secondary})` : primary || 'Untitled work';
+  }
+  if (type === 'role') return item.roleCn ? `${item.role || item.roleCn} (${item.roleCn})` : item.role || 'Untitled role';
+  if (type === 'brand') return item.brand || item.brandNameEn || item.brandNameCn || item.name || 'Untitled brand';
+  return item.title || item.titleTh || item.titleEn || item.titleCn || item.name || 'Untitled';
+}
+
+function entityId(type, item, index) {
+  const raw = item.id || item.entityId || item.roleCn || item.role || item.brand || item.title || item.titleTh || `${type}-${index + 1}`;
+  return String(raw).trim().slice(0, 200);
+}
+
+function normalizeRecords(type, result) {
+  let records = [];
+  if (type === 'work') records = result?.works || [];
+  if (type === 'song') records = result?.songs || [];
+  if (type === 'role') records = result?.roles || [];
+  if (type === 'brand') records = result?.brands || [];
+  if (type === 'award') records = result?.awards || [];
+  if (type === 'photo') records = result?.photos || [];
+  if (type === 'stage') records = result?.videos || [];
+  return records.map((item, index) => {
+    const title = entityTitle(type, item);
+    const detail = type === 'work'
+      ? [item.role && `Role: ${item.role}`, item.platform, item.episodes && (typeof item.episodes === 'number' || /^\d+$/.test(String(item.episodes)) ? `${item.episodes} episodes` : item.episodes)].filter(Boolean).join(' • ')
+      : type === 'song'
+        ? [item.type, item.duration].filter(Boolean).join(' • ')
+        : type === 'role'
+          ? [item.workTitle, item.roleCn].filter(Boolean).join(' • ')
+          : type === 'brand'
+            ? [item.title, item.category].filter(Boolean).join(' • ')
+            : type === 'award'
+              ? [item.ceremony, item.category].filter(Boolean).join(' • ')
+              : type === 'photo'
+                ? item.category || ''
+                : [item.category, item.drama, item.duration].filter(Boolean).join(' • ');
+    return {
+      type,
+      entityId: entityId(type, item, index),
+      title: String(title),
+      year: Number(item.year) || null,
+      detail,
+      url: item.youtubeUrl || item.streamUrl || item.youtubeTrailerSearch || item.youtubeSearchUrl || null,
+      raw: item,
+    };
+  });
+}
+
+function toolRequest(type, query, options) {
+  if (type === 'work') return ['search_works', { query, year: options.year }];
+  if (type === 'song') return ['search_discography', { query, year: options.year, type: options.mood === 'calm' ? 'ost' : 'all' }];
+  if (type === 'role') return ['get_character_roles', { query }];
+  if (type === 'brand') return ['get_brand_endorsements', { query, year: options.year }];
+  if (type === 'award') return ['get_awards', { query, year: options.year, limit: options.limit }];
+  if (type === 'photo') return ['get_gallery_photos', { query, year: options.year, limit: options.limit }];
+  return ['get_music_videos', { query, category: options.mood === 'energetic' ? 'Stage Performance' : undefined }];
+}
+
+export async function findCatalogEntities(query, options = {}) {
+  const type = normalizeType(options.type, 'all');
+  const limit = boundedInteger(options.limit, 8, 1, 20);
+  const year = options.year === undefined ? undefined : boundedInteger(options.year, undefined, 2013, 2035);
+  const executor = options.executeTool || executeTool;
+  const types = type === 'all' ? FAVORITE_TYPES : [type];
+  const settled = await Promise.allSettled(types.map(async currentType => {
+    const [name, args] = toolRequest(currentType, String(query || '').trim(), { ...options, year, limit });
+    const result = await executor(name, args);
+    return normalizeRecords(currentType, result);
+  }));
+  const entities = settled.flatMap(entry => entry.status === 'fulfilled' ? entry.value : []);
+  const filtered = entities.filter(entity => {
+    if (year && entity.year && entity.year !== year) return false;
+    return true;
+  });
+  return filtered.slice(0, limit);
+}
+
+function entityLine(entity, index) {
+  const year = entity.year ? ` ${C.dim}(${entity.year})${C.reset}` : '';
+  const detail = entity.detail ? ` — ${clean(entity.detail, 180)}` : '';
+  return `${C.gold}[${index + 1}]${C.reset} ${C.bold}${C.cyberCyan}${clean(entity.title)}${C.reset}${year} ${C.slate}[${entity.type}]${C.reset}${detail}`;
+}
+
+async function handleFind(ctx) {
+  const parsed = parsedRequest(ctx);
+  const type = normalizeType(parsed.flags.type, 'all');
+  const year = parsed.flags.year === undefined ? undefined : boundedInteger(parsed.flags.year, undefined, 2013, 2035);
+  const limit = boundedInteger(parsed.flags.limit, 8, 1, 20);
+  const query = parsed.positionals.join(' ').trim();
+  if (!query && !year && type === 'all') {
+    printMessage('Find Command', 'Usage: /find <query> [--type work|song|role|brand|award|photo|stage] [--year YYYY] [--limit N]');
+    return 'HANDLED';
+  }
+  const entities = await findCatalogEntities(query, { type, year, limit, executeTool: ctx.executeTool });
+  const summary = entities.length ? await aiNarration(ctx, {
+    system: `You are the Kiku catalog guide. In ONE short sentence, tell the user why the top search result matches their query and what to notice about it. ${languageHint(ctx)} Mention only facts present in the data. Never invent facts, dates, or titles. No markdown.`,
+    user: JSON.stringify({ query, type, year, results: entities.slice(0, 3).map(e => ({ title: e.title, type: e.type, year: e.year, detail: e.detail })) }),
+    limit: 260,
+  }) : null;
+  printSolidPanel({
+    title: `Catalog Search • ${entities.length} result${entities.length === 1 ? '' : 's'}`,
+    lines: entities.length
+      ? [...entities.map(entityLine), ...(summary ? ['', `  ${C.slate}${summary}${C.reset}`] : [])]
+      : [`${C.dim}No matching catalog entries. Try another spelling, type, or year.${C.reset}`],
+  });
+  return 'HANDLED';
+}
+
+export function languageHint(ctx) {
+  const lang = ctx?.agent?.memory?.preferences?.language || null;
+  return lang === 'th' ? 'Answer in Thai.' : lang === 'zh' ? 'Answer in Chinese.' : lang === 'en' ? 'Answer in English.' : 'Answer in the same language as the surrounding UI (English is fine).';
+}
+
+export async function aiNarration(ctx, { system, user, limit = 400, multiline = false }) {
+  const client = ctx?.agent?.client;
+  if (!client || typeof client.chat !== 'function') return null;
+  try {
+    const res = await client.chat({
+      messages: [
+        { role: 'system', content: system },
+        { role: 'user', content: user },
+      ],
+      temperature: 0.5,
+      stream: false,
+    });
+    const raw = String(res?.content || '').trim();
+    if (!raw) return null;
+    if (multiline) {
+      return raw.split('\n').map(l => clean(l, limit)).filter(Boolean).join('\n');
+    }
+    return clean(raw, limit);
+  } catch {
+    return null;
+  }
+}
+
+async function aiDiscoverRationale(ctx, entity, { type, year, mood }) {
+  const item = { type, title: entity.title, year: entity.year || year || 'unknown', detail: entity.detail || 'no extra detail' };
+  const text = await aiNarration(ctx, {
+    system: `You are the Kiku fan-curator. Write ONE short, warm, factual sentence explaining why this Ju Jingyi catalog item is a good pick for the requested vibe. ${languageHint(ctx)} Mention only details present in the item. Never invent facts, dates, or titles. Max ~160 characters. Output only the sentence, no quotes, no markdown.`,
+    user: JSON.stringify({ mood, year, type, item }),
+    limit: 220,
+  });
+  return text ? `  ${C.slate}${text}${C.reset}` : null;
+}
+
+function comparableFields(entity) {
+  const raw = entity.raw || {};
+  return {
+    Type: entity.type,
+    Title: entity.title,
+    Year: entity.year || 'N/A',
+    Role: raw.role || raw.roleCn || 'N/A',
+    Category: raw.category || raw.type || 'N/A',
+    Platform: raw.platform || 'N/A',
+    Episodes: raw.episodes || 'N/A',
+    Duration: raw.duration || 'N/A',
+    Detail: entity.detail || 'N/A',
+  };
+}
+
+function comparisonSection(label, entity) {
+  const fields = comparableFields(entity);
+  if (entity.type === 'year') {
+    return [
+      `${C.bold}${C.cyberCyan}${label}  ${clean(entity.title)}${C.reset}`,
+      `   ${C.gold}Works:${C.reset} ${entity.raw.works || 0}  ${C.gold}Songs:${C.reset} ${entity.raw.songs || 0}  ${C.gold}Brands:${C.reset} ${entity.raw.brands || 0}  ${C.gold}Awards:${C.reset} ${entity.raw.awards || 0}`,
+    ];
+  }
+  const lines = [
+    `${C.bold}${C.cyberCyan}${label}  ${clean(entity.title)}${C.reset}`,
+    `   ${C.gold}Type:${C.reset} ${clean(fields.Type)}  ${C.gold}Year:${C.reset} ${clean(fields.Year)}`,
+  ];
+  for (const field of ['Role', 'Category', 'Platform', 'Episodes', 'Duration']) {
+    if (fields[field] !== 'N/A') lines.push(`   ${C.gold}${field}:${C.reset} ${clean(fields[field], 220)}`);
+  }
+  return lines;
+}
+
+function comparisonDifferences(left, right) {
+  if (left.type === 'year' && right.type === 'year') {
+    return ['works', 'songs', 'brands', 'awards'].map(field => `${C.gold}${field[0].toUpperCase()}${field.slice(1)}:${C.reset} ${left.raw[field] || 0} → ${right.raw[field] || 0}`);
+  }
+  const leftFields = comparableFields(left);
+  const rightFields = comparableFields(right);
+  return ['Year', 'Role', 'Category', 'Platform', 'Episodes', 'Duration']
+    .filter(field => leftFields[field] !== rightFields[field] && (leftFields[field] !== 'N/A' || rightFields[field] !== 'N/A'))
+    .map(field => `${C.gold}${field}:${C.reset} ${clean(leftFields[field], 100)} → ${clean(rightFields[field], 100)}`);
+}
+
+async function yearSummary(year, executor) {
+  const types = ['work', 'song', 'brand', 'award'];
+  const values = await Promise.all(types.map(type => findCatalogEntities('', { type, year, limit: 20, executeTool: executor })));
+  return {
+    type: 'year',
+    entityId: String(year),
+    title: String(year),
+    year,
+    detail: values.map((items, index) => `${types[index]}: ${items.length}`).join(' • '),
+    raw: Object.fromEntries(values.map((items, index) => [`${types[index]}s`, items.length])),
+  };
+}
+
+async function handleCompare(ctx) {
+  const parsed = parsedRequest(ctx);
+  const leftQuery = parsed.segments[0] || '';
+  const rightQuery = parsed.segments[1] || '';
+  if (!leftQuery || !rightQuery) {
+    printMessage('Compare Command', 'Usage: /compare <item-a> -- <item-b> [--type work|song|role|brand|award|photo|stage]');
+    return 'HANDLED';
+  }
+  const type = normalizeType(parsed.flags.type, 'all');
+  const leftYear = /^20\d{2}$/.test(leftQuery) ? Number(leftQuery) : null;
+  const rightYear = /^20\d{2}$/.test(rightQuery) ? Number(rightQuery) : null;
+  const [left, right] = leftYear && rightYear
+    ? await Promise.all([yearSummary(leftYear, ctx.executeTool), yearSummary(rightYear, ctx.executeTool)])
+    : await Promise.all([
+        findCatalogEntities(leftQuery, { type, limit: 1, executeTool: ctx.executeTool }).then(items => items[0]),
+        findCatalogEntities(rightQuery, { type, limit: 1, executeTool: ctx.executeTool }).then(items => items[0]),
+      ]);
+  if (!left || !right) {
+    printSolidPanel({ title: 'Compare', lines: [`${C.amber}Could not resolve both items. Use /find first, then compare the exact titles.${C.reset}`] });
+    return 'HANDLED';
+  }
+  const differences = comparisonDifferences(left, right);
+  const a = { title: left.title, type: left.type, year: left.year, fields: comparableFields(left) };
+  const b = { title: right.title, type: right.type, year: right.year, fields: comparableFields(right) };
+  const aiSummary = await aiNarration(ctx, {
+    system: `You are the Kiku comparisons editor. In ONE short paragraph, summarize how these two Ju Jingyi catalog items differ and what is notable about each. ${languageHint(ctx)} Mention only facts present in the data. Never invent facts, dates, or titles. Do not use markdown.`,
+    user: JSON.stringify({ a, b }),
+    limit: 420,
+  });
+  printSolidPanel({
+    title: 'Compare Catalog Entries',
+    lines: [
+      ...comparisonSection('A', left),
+      '',
+      ...comparisonSection('B', right),
+      '',
+      `${C.bold}${C.roseGlow}Differences${C.reset}`,
+      ...(differences.length ? differences : [`${C.dim}No differing comparable fields.${C.reset}`]),
+      ...(aiSummary ? ['', `  ${C.slate}${aiSummary}${C.reset}`] : []),
+    ],
+  });
+  return 'HANDLED';
+}
+
+async function handleFavorites(ctx) {
+  const parsed = parsedRequest(ctx);
+  const action = String(parsed.positionals[0] || 'list').toLowerCase();
+  const memory = ctx.agent?.memory;
+  if (!memory) throw new Error('Favorites require agent memory.');
+  if (action === 'list') {
+    const type = normalizeType(parsed.flags.type, 'all');
+    const favorites = memory.getFavorites(type);
+    printSolidPanel({
+      title: `Favorites • ${favorites.length}`,
+      lines: favorites.length
+        ? favorites.map((item, index) => `${C.gold}[${index + 1}]${C.reset} ${C.bold}${C.cyberCyan}${clean(item.title)}${C.reset} ${item.year ? `${C.dim}(${item.year})${C.reset}` : ''} ${C.slate}[${item.type}] ${item.id}${C.reset}`)
+        : [`${C.dim}No favorites saved. Use /favorites add <query>.${C.reset}`],
+    });
+    return 'HANDLED';
+  }
+  if (action === 'add') {
+    let values = parsed.positionals.slice(1);
+    const explicit = normalizeType(parsed.flags.type, 'all');
+    const rawPositionalType = String(values[0] || '').toLowerCase();
+    const hasPositionalType = FAVORITE_TYPES.includes(rawPositionalType) || Boolean(TYPE_ALIASES[rawPositionalType]);
+    const positionalType = hasPositionalType ? normalizeType(rawPositionalType, 'all') : 'all';
+    const type = explicit !== 'all' ? explicit : hasPositionalType ? positionalType : 'all';
+    if (hasPositionalType) values = values.slice(1);
+    const query = values.join(' ').trim();
+    if (!query) {
+      printMessage('Favorites Command', 'Usage: /favorites add [type] <query>');
+      return 'HANDLED';
+    }
+    const [entity] = await findCatalogEntities(query, { type, limit: 1, executeTool: ctx.executeTool });
+    if (!entity) {
+      printSolidPanel({ title: 'Favorites', lines: [`${C.amber}No matching catalog entry found for "${clean(query)}".${C.reset}`] });
+      return 'HANDLED';
+    }
+    const saved = memory.addFavorite(entity);
+    printSolidPanel({
+      title: saved.created ? 'Favorite Added' : 'Already in Favorites',
+      lines: [entityLine(saved.favorite, 0), `${C.dim}ID: ${saved.favorite.id}${C.reset}`],
+    });
+    return 'HANDLED';
+  }
+  if (action === 'remove' || action === 'delete' || action === 'del') {
+    const id = parsed.positionals[1] || '';
+    const removed = memory.removeFavorite(id);
+    console.log(`\n  ${removed ? C.emerald + '[OK] Favorite removed.' : C.amber + 'Favorite ID not found.'}${C.reset}\n`);
+    return 'HANDLED';
+  }
+  if (action === 'export') {
+    const format = allowlistedValue(parsed.positionals[1], ['json', 'markdown'], 'json');
+    const exported = await memory.exportFavorites(format);
+    printSolidPanel({ title: 'Favorites Exported', lines: [`${C.emerald}[OK] ${exported.count} items${C.reset}`, `${C.white}${clean(exported.filePath, 500)}${C.reset}`] });
+    return 'HANDLED';
+  }
+  if (action === 'suggest' || action === 'recommend') {
+    const favorites = memory.getFavorites();
+    const profile = favorites.map(f => ({ type: f.type, title: f.title, year: f.year, detail: f.detail }));
+    if (!profile.length) {
+      printSolidPanel({ title: 'Favorites Suggest', lines: [`${C.dim}No favorites yet — add some with /favorites add <query>, then ask me to suggest.${C.reset}`] });
+      return 'HANDLED';
+    }
+    const types = ['work', 'song', 'role', 'stage'];
+    const poolResults = await Promise.allSettled(types.map(type => findCatalogEntities('', { type, limit: 8, executeTool: ctx.executeTool })));
+    const pool = poolResults.flatMap(entry => entry.status === 'fulfilled' ? entry.value.map(e => ({ type: e.type, title: e.title, year: e.year, detail: e.detail })) : []);
+    const aiText = await aiNarration(ctx, {
+      system: `You are the Kiku personal curator. Based on the fan's saved favorites, recommend 3 catalog items from the available pool that best match their taste. ${languageHint(ctx)} Reply with a plain list, one per line, format exactly: "<title> — <short reason>". Mention only items present in the pool and only facts present in their detail. Never invent titles or facts. No markdown, no numbering prefix.`,
+      user: JSON.stringify({ profile, pool }),
+      limit: 220,
+      multiline: true,
+    });
+    const suggested = (aiText ? aiText.split('\n').map(l => l.trim()).filter(Boolean).slice(0, 3) : []);
+    printSolidPanel({
+      title: `Favorites Suggest • based on ${profile.length} favorite${profile.length === 1 ? '' : 's'}`,
+      lines: suggested.length
+        ? suggested.map((line, index) => {
+            const separatorIdx = line.indexOf(' — ') >= 0 ? line.indexOf(' — ') : line.indexOf(' - ');
+            if (separatorIdx >= 0) {
+              const title = clean(line.slice(0, separatorIdx), 80);
+              const reason = clean(line.slice(separatorIdx + 3), 220);
+              return `${C.gold}[${index + 1}]${C.reset} ${C.bold}${C.cyberCyan}${title}${C.reset} — ${C.slate}${reason}${C.reset}`;
+            }
+            return `${C.gold}[${index + 1}]${C.reset} ${C.white}${clean(line, 220)}${C.reset}`;
+          })
+        : [`${C.dim}No suggestions could be generated.${C.reset}`],
+    });
+    return 'HANDLED';
+  }
+  printMessage('Favorites Command', 'Usage: /favorites [list|add|remove|export|suggest]');
+  return 'HANDLED';
+}
+
+function safeNewsUrl(value) {
+  try {
+    const url = new URL(value);
+    if (!['http:', 'https:'].includes(url.protocol)) return null;
+    return url;
+  } catch {
+    return null;
+  }
+}
+
+function detectedDate(item) {
+  const text = `${item.title || ''} ${item.snippet || ''}`;
+  const match = text.match(/\b(20\d{2})[-/]([01]?\d)[-/]([0-3]?\d)\b/);
+  if (!match) return null;
+  const date = new Date(`${match[1]}-${String(match[2]).padStart(2, '0')}-${String(match[3]).padStart(2, '0')}T00:00:00Z`);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+async function handleNews(ctx) {
+  const parsed = parsedRequest(ctx);
+  const days = boundedInteger(parsed.flags.days, 7, 1, 90);
+  const officialOnly = parsed.flags['official-only'] === true || String(parsed.flags['official-only']).toLowerCase() === 'true';
+  const topic = parsed.positionals.join(' ').trim();
+  const now = new Date();
+  const cutoff = new Date(now.getTime() - days * 86_400_000);
+  const after = cutoff.toISOString().slice(0, 10);
+  const before = new Date(now.getTime() + 86_400_000).toISOString().slice(0, 10);
+  const query = `Ju Jingyi 鞠婧祎 ${topic || 'latest news'} after:${after} before:${before}${officialOnly ? ' official studio' : ''}`;
+  const executor = ctx.executeTool || executeTool;
+  const result = await executor('web_search', { query });
+  const seen = new Set();
+  const items = (result?.results || []).filter(item => {
+    const url = safeNewsUrl(item.url);
+    if (!url || seen.has(url.href)) return false;
+    if (officialOnly && (!OFFICIAL_NEWS_HOSTS.has(url.hostname.toLowerCase()) || !OFFICIAL_NEWS_SIGNAL.test(`${item.title || ''} ${item.snippet || ''} ${url.pathname}`))) return false;
+    const date = detectedDate(item);
+    if (date && date.getTime() < cutoff.getTime()) return false;
+    seen.add(url.href);
+    return true;
+  }).slice(0, 8);
+  const summary = items.length ? await aiNarration(ctx, {
+    system: `You are the Kiku news desk. In ONE short paragraph (2-3 sentences), summarize what these Ju Jingyi news results say this week. ${languageHint(ctx)} Synthesize only from the provided items. Never invent facts, dates, or sources. No markdown.`,
+    user: JSON.stringify({ topic, items: items.slice(0, 8).map((item, index) => ({ title: item.title, snippet: item.snippet, source: safeNewsUrl(item.url)?.hostname || item.source })) }),
+    limit: 420,
+  }) : null;
+  printSolidPanel({
+    title: `${officialOnly ? 'Official-source ' : ''}News Search • ${items.length} result${items.length === 1 ? '' : 's'} • requested ${days}-day window`,
+    lines: items.length
+      ? [...items.flatMap((item, index) => {
+          const url = safeNewsUrl(item.url);
+          const date = detectedDate(item);
+          return [
+            `${C.gold}[${index + 1}]${C.reset} ${C.bold}${C.cyberCyan}${clean(item.title)}${C.reset}`,
+            `    ${C.dim}${date ? date.toISOString().slice(0, 10) : 'date unavailable • recency unverified'} • ${clean(url?.hostname || item.source || 'source', 100)}${C.reset}`,
+            `    ${C.white}${clean(item.snippet, 260)}${C.reset}`,
+            `    ${C.slate}${clean(url?.href || '', 500)}${C.reset}`,
+          ];
+        }), ...(summary ? ['', `  ${C.slate}${summary}${C.reset}`] : [])]
+      : [`${C.dim}No matching ${officialOnly ? 'official ' : ''}news found. Try a wider date range or another topic.${C.reset}`],
+  });
+  return 'HANDLED';
+}
+
+function jobLine(job, index) {
+  const color = job.state === 'completed' ? C.emerald : job.state === 'failed' ? C.red : job.state === 'cancelled' ? C.amber : C.cyberCyan;
+  return `${C.gold}[${index + 1}]${C.reset} ${color}${job.state.toUpperCase()}${C.reset} ${C.bold}${clean(job.type, 30)}${C.reset} ${clean(job.label, 120)} ${C.dim}${job.id}${C.reset}`;
+}
+
+async function handleJobs(ctx) {
+  const parsed = parsedRequest(ctx);
+  const action = String(parsed.positionals[0] || 'list').toLowerCase();
+  if (action === 'list') {
+    const jobs = typeof ctx.agent?.getJobs === 'function' ? ctx.agent.getJobs() : [];
+    printSolidPanel({ title: `Agent Jobs • ${jobs.length}`, lines: jobs.length ? jobs.map(jobLine) : [`${C.dim}No tracked jobs yet.${C.reset}`] });
+    return 'HANDLED';
+  }
+  if (action === 'show') {
+    const id = parsed.positionals[1] || '';
+    const job = typeof ctx.agent?.getJob === 'function' ? ctx.agent.getJob(id) : null;
+    printSolidPanel({
+      title: job ? `Job • ${job.id}` : 'Job Not Found',
+      lines: job ? [jobLine(job, 0), `${C.gold}Started:${C.reset} ${clean(job.startedAt)}`, `${C.gold}Completed:${C.reset} ${clean(job.completedAt || 'N/A')}`, ...(job.error ? [`${C.red}Error: ${clean(job.error)}${C.reset}`] : [])] : [`${C.amber}No job found for that ID.${C.reset}`],
+    });
+    return 'HANDLED';
+  }
+  if (action === 'cancel') {
+    const id = parsed.positionals[1] || '';
+    const cancelled = /^job_[a-zA-Z0-9_]+$/.test(id) && typeof ctx.agent?.cancelJob === 'function' && ctx.agent.cancelJob(id);
+    console.log(`\n  ${cancelled ? C.emerald + '[OK] Job cancellation requested.' : C.amber + 'Running job not found.'}${C.reset}\n`);
+    return 'HANDLED';
+  }
+  if (action === 'clear') {
+    const count = typeof ctx.agent?.clearJobs === 'function' ? ctx.agent.clearJobs() : 0;
+    console.log(`\n  ${C.emerald}[OK] Cleared ${count} completed job${count === 1 ? '' : 's'}.${C.reset}\n`);
+    return 'HANDLED';
+  }
+  printMessage('Jobs Command', 'Usage: /jobs [list|show <id>|cancel <id>|clear]');
+  return 'HANDLED';
+}
+
+async function handleDiscover(ctx) {
+  const parsed = parsedRequest(ctx);
+  const requested = parsed.positionals[0] || parsed.flags.type || 'drama';
+  const type = normalizeType(requested, 'work');
+  if (type === 'all' || ['role', 'brand', 'award'].includes(type)) throw new Error('Discover type must be drama, song, stage, or photo.');
+  const year = parsed.flags.year === undefined ? undefined : boundedInteger(parsed.flags.year, undefined, 2013, 2035);
+  const mood = allowlistedValue(parsed.flags.mood, ['calm', 'romantic', 'energetic', 'dramatic', 'any'], 'any');
+  let entities = await findCatalogEntities('', { type, year, mood, limit: 20, executeTool: ctx.executeTool });
+  if (!entities.length && mood !== 'any') entities = await findCatalogEntities('', { type, year, limit: 20, executeTool: ctx.executeTool });
+  const random = typeof ctx.random === 'function' ? ctx.random : Math.random;
+  const entity = entities[Math.floor(random() * entities.length)];
+  const rationale = entity ? await aiDiscoverRationale(ctx, entity, { type, year, mood }) : null;
+  printSolidPanel({
+    title: `Discover • ${type}${year ? ` • ${year}` : ''}${mood !== 'any' ? ` • ${mood}` : ''}`,
+    lines: entity
+      ? [entityLine(entity, 0), ...(rationale ? [rationale] : []), ...(entity.url ? [`${C.slate}${clean(entity.url, 500)}${C.reset}`] : []), `${C.dim}Save it with /favorites add --type ${entity.type} "${clean(entity.title, 100)}"${C.reset}`]
+      : [`${C.dim}No matching catalog entry is available for these filters.${C.reset}`],
+  });
+  return 'HANDLED';
+}
+
+function safeHandler(handler) {
+  return async ctx => {
+    try {
+      return await handler(ctx);
+    } catch (error) {
+      printMessage('Command Error', `[COMMAND ERROR] ${error?.message || error}`, C.red);
+      return 'HANDLED';
+    }
+  };
+}
+
+export const featureCommandHandlers = Object.freeze({
+  '/find': safeHandler(handleFind),
+  '/compare': safeHandler(handleCompare),
+  '/favorites': safeHandler(handleFavorites),
+  '/news': safeHandler(handleNews),
+  '/jobs': safeHandler(handleJobs),
+  '/discover': safeHandler(handleDiscover),
+});

package/server/agent/commandInput.js

@@ -0,0 +1,113 @@
+const MAX_COMMAND_LENGTH = 1000;
+const MAX_TOKEN_LENGTH = 500;
+
+export function tokenizeCommandInput(input) {
+  const value = String(input || '').trim();
+  if (!value) return [];
+  if (value.length > MAX_COMMAND_LENGTH) throw new Error(`Command must be ${MAX_COMMAND_LENGTH} characters or fewer.`);
+
+  const tokens = [];
+  let current = '';
+  let quote = '';
+  let escaped = false;
+
+  for (const char of value) {
+    if (escaped) {
+      current += char;
+      if (current.length > MAX_TOKEN_LENGTH) throw new Error(`Command argument must be ${MAX_TOKEN_LENGTH} characters or fewer.`);
+      escaped = false;
+      continue;
+    }
+    if (char === '\\' && quote) {
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) {
+        quote = '';
+      } else {
+        current += char;
+        if (current.length > MAX_TOKEN_LENGTH) throw new Error(`Command argument must be ${MAX_TOKEN_LENGTH} characters or fewer.`);
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (/\s/u.test(char)) {
+      if (current) {
+        tokens.push(current);
+        current = '';
+      }
+      continue;
+    }
+    current += char;
+    if (current.length > MAX_TOKEN_LENGTH) throw new Error(`Command argument must be ${MAX_TOKEN_LENGTH} characters or fewer.`);
+  }
+
+  if (escaped) current += '\\';
+  if (quote) throw new Error('Command contains an unclosed quote.');
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+export function parseCommandInput(input) {
+  const tokens = tokenizeCommandInput(input);
+  const command = String(tokens.shift() || '').toLowerCase();
+  const flags = {};
+  const segments = [[]];
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === '--') {
+      if (segments.length === 1) segments.push([]);
+      continue;
+    }
+    if (token.startsWith('--') && token.length > 2) {
+      const rawFlag = token.slice(2);
+      const equalsIndex = rawFlag.indexOf('=');
+      if (equalsIndex !== -1) {
+        const key = rawFlag.slice(0, equalsIndex).toLowerCase();
+        const value = rawFlag.slice(equalsIndex + 1);
+        if (!key) throw new Error('Invalid command flag.');
+        flags[key] = value || true;
+        continue;
+      }
+      const key = rawFlag.toLowerCase();
+      const next = tokens[index + 1];
+      if (next && next !== '--' && !next.startsWith('--')) {
+        flags[key] = next;
+        index += 1;
+      } else {
+        flags[key] = true;
+      }
+      continue;
+    }
+    segments[segments.length - 1].push(token);
+  }
+
+  return {
+    command,
+    tokens,
+    flags,
+    positionals: segments.flat(),
+    segments: segments.map(segment => segment.join(' ').trim()),
+  };
+}
+
+export function boundedInteger(value, fallback, minimum, maximum) {
+  if (value === undefined || value === null || value === true || value === '') return fallback;
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < minimum || number > maximum) {
+    throw new Error(`Expected an integer from ${minimum} to ${maximum}.`);
+  }
+  return number;
+}
+
+export function allowlistedValue(value, allowed, fallback) {
+  if (value === undefined || value === null || value === true || value === '') return fallback;
+  const normalized = String(value).toLowerCase();
+  if (!allowed.includes(normalized)) throw new Error(`Expected one of: ${allowed.join(', ')}.`);
+  return normalized;
+}