kiku-agent 1.2.0 → 1.3.0

package/server/agent/ingestionWorker.js

@@ -0,0 +1,339 @@
+import { classifySource, extractArticleDate } from './newsIntelligence.js';
+import { simhashText, hamming64 } from './websearch/extract.js';
+import {
+  addDynamicEntry,
+  getDynamicEntries,
+  validateCatalogEntry,
+  DEFAULT_DYNAMIC_CATALOG_PATH
+} from './dynamicCatalog.js';
+import { searchNews } from './webSearch.js';
+
+export const KNOWN_OFFICIAL_PLATFORMS = new Set([
+  'weibo', 'weibo.com', 'weibo.cn',
+  'douyin', 'douyin.com',
+  'bilibili', 'bilibili.com',
+  'youtube', 'youtube.com',
+  'instagram', 'instagram.com',
+  'xiaohongshu', 'xiaohongshu.com', 'xhs',
+  'tiktok', 'tiktok.com'
+]);
+
+export function isTrustedSource(source) {
+  if (!source || typeof source !== 'string') {
+    return { trusted: false, tier: 3, label: 'unknown' };
+  }
+  const sLower = source.toLowerCase().trim();
+
+  if (KNOWN_OFFICIAL_PLATFORMS.has(sLower)) {
+    return { trusted: true, tier: 1, label: 'official' };
+  }
+
+  if (/^https?:\/\//i.test(sLower)) {
+    const classified = classifySource(source);
+    return {
+      trusted: classified.tier <= 2,
+      tier: classified.tier,
+      label: classified.label
+    };
+  }
+
+  if (/(weibo|douyin|bilibili|youtube|instagram|xhs|xiaohongshu|tiktok|official|工作室)/i.test(sLower)) {
+    return { trusted: true, tier: 1, label: 'official' };
+  }
+  if (/(press|news|sohu|netease|sina|tencent|qq|thairath|sanook|kapook|pptv)/i.test(sLower)) {
+    return { trusted: true, tier: 2, label: 'press' };
+  }
+
+  return { trusted: false, tier: 3, label: 'community' };
+}
+
+export function computeEventSimHash(text) {
+  return simhashText(String(text || ''));
+}
+
+export function isDuplicateEvent(entry, existingList = [], { maxHamming = 8 } = {}) {
+  if (!entry || !Array.isArray(existingList) || existingList.length === 0) {
+    return false;
+  }
+
+  const entryText = `${entry.title || entry.brand || entry.brandNameEn || ''} ${entry.highlight || ''} ${entry.summary || ''}`.trim();
+  const entryHash = entryText ? computeEventSimHash(entryText) : null;
+
+  for (const existing of existingList) {
+    if (entry.id && existing.id && entry.id === existing.id) {
+      return true;
+    }
+
+    const entryBrand = (entry.brand || entry.brandNameEn || entry.brandNameCn || '').toLowerCase().trim();
+    const existingBrand = (existing.brand || existing.brandNameEn || existing.brandNameCn || '').toLowerCase().trim();
+    if (entryBrand && existingBrand && entryBrand === existingBrand && entry.year === existing.year) {
+      return true;
+    }
+
+    const entryTitle = (entry.title || entry.titleCn || entry.titleTh || entry.titleEn || '').toLowerCase().trim();
+    const existingTitle = (existing.title || existing.titleCn || existing.titleTh || existing.titleEn || '').toLowerCase().trim();
+    if (entryTitle && existingTitle && entryTitle === existingTitle && entry.year === existing.year) {
+      return true;
+    }
+
+    const eH = (entry.highlight || entry.summary || '').toLowerCase().trim();
+    const xH = (existing.highlight || existing.summary || '').toLowerCase().trim();
+    if (eH && xH && (eH.includes(xH) || xH.includes(eH))) {
+      return true;
+    }
+
+    if (entryHash != null) {
+      const existText = `${existing.title || existing.brand || existing.brandNameEn || ''} ${existing.highlight || ''} ${existing.summary || ''}`.trim();
+      if (existText) {
+        const existHash = computeEventSimHash(existText);
+        if (hamming64(entryHash, existHash) <= maxHamming) {
+          return true;
+        }
+      }
+    }
+  }
+
+  return false;
+}
+
+export async function extractStructuredEvent(text, { client = null } = {}) {
+  const rawText = String(text || '').trim();
+  if (!rawText) {
+    throw new Error('Event text cannot be empty');
+  }
+
+  if (client && typeof client.chatCompletion === 'function') {
+    try {
+      const prompt = `Extract a structured event for artist Ju Jingyi (鞠婧祎) from this text into JSON:
+Text: "${rawText}"
+
+Return ONLY a JSON object with:
+- category: one of ["brands", "timeline", "gallery", "works", "events"]
+- year: integer year (e.g. 2026)
+- date: ISO date string or "YYYY-MM-DD" if present
+- title: concise title of the event / work
+- titleCn: Chinese title or null
+- titleTh: Thai title or null
+- brand: brand name (if brand endorsement) or null
+- brandNameCn: Chinese brand name or null
+- brandNameEn: English brand name or null
+- role: role/title (e.g. "Brand Ambassador", "Lead Actress", "Performer")
+- highlight: key highlight sentence
+- summary: full description
+- imageUrl: image URL or null
+- source: origin platform or media outlet`;
+
+      const response = await client.chatCompletion({
+        messages: [{ role: 'user', content: prompt }],
+        temperature: 0.1,
+      });
+
+      const jsonStr = response?.choices?.[0]?.message?.content || '';
+      const match = jsonStr.match(/\{[\s\S]*\}/);
+      if (match) {
+        const parsed = JSON.parse(match[0]);
+        if (parsed && (parsed.title || parsed.brand || parsed.brandNameEn)) {
+          return parsed;
+        }
+      }
+    } catch {
+
+    }
+  }
+
+  const currentYear = new Date().getFullYear();
+  const dateInfo = extractArticleDate({ snippet: rawText, title: rawText });
+  const eventYear = dateInfo?.date ? dateInfo.date.getUTCFullYear() : currentYear;
+  let isoDate = dateInfo?.date ? dateInfo.date.toISOString().slice(0, 10) : null;
+
+  if (!isoDate) {
+    const THAI_MONTHS_MAP = {
+      'มกราคม': 1, 'กุมภาพันธ์': 2, 'มีนาคม': 3, 'เมษายน': 4, 'พฤษภาคม': 5, 'มิถุนายน': 6,
+      'กรกฎาคม': 7, 'สิงหาคม': 8, 'กันยายน': 9, 'ตุลาคม': 10, 'พฤศจิกายน': 11, 'ธันวาคม': 12,
+      'มค': 1, 'กพ': 2, 'มีค': 3, 'เมย': 4, 'พค': 5, 'มิย': 6, 'กค': 7, 'สค': 8, 'กย': 9, 'ตค': 10, 'พย': 11, 'ธค': 12,
+    };
+    const thMatch = rawText.match(/(?:วันที่\s*)?(\d{1,2})\s*(มกราคม|กุมภาพันธ์|มีนาคม|เมษายน|พฤษภาคม|มิถุนายน|กรกฎาคม|สิงหาคม|กันยายน|ตุลาคม|พฤศจิกายน|ธันวาคม|ม\.?ค\.?|ก\.?พ\.?|มี\.?ค\.?|เม\.?ย\.?|พ\.?ค\.?|มิ\.?ย\.?|ก\.?ค\.?|ส\.?ค\.?|ก\.?ย\.?|ต\.?ค\.?|พ\.?ย\.?|ธ\.?ค\.?)/i);
+    if (thMatch) {
+      const day = String(thMatch[1]).padStart(2, '0');
+      const mKey = thMatch[2].replace(/\./g, '');
+      const monthNum = THAI_MONTHS_MAP[mKey] || 1;
+      const month = String(monthNum).padStart(2, '0');
+      isoDate = `${eventYear}-${month}-${day}`;
+    } else {
+      isoDate = `${eventYear}-01-01`;
+    }
+  }
+
+  let category = 'events';
+  const isBrand = /(แบรนด์|พรีเซ็นเตอร์|โฆษณา|brand|ambassador|endorsement|CF|Commercial|代言|Lafang|拉芳|FRED|TuTuCare)/i.test(rawText);
+  const isGallery = /(ลุค|ชุดเดรส|ภาพ|รูปถ่าย|photoshoot|look|dress|gallery|fashion)/i.test(rawText);
+  const isWork = /(ซีรีส์|ละคร|เพลง|อัลบั้ม|ซิงเกิล|OST|drama|album|single|series|film)/i.test(rawText);
+  const isTimeline = /(milestone|เปิดตัว|ครบรอบ|debut|graduation|timeline)/i.test(rawText);
+
+  if (isBrand) category = 'brands';
+  else if (isWork) category = 'works';
+  else if (isGallery) category = 'gallery';
+  else if (isTimeline) category = 'timeline';
+
+  let brandNameEn = '';
+  let brandNameCn = '';
+  if (isBrand) {
+    if (/lafang|拉芳/i.test(rawText)) {
+      brandNameEn = 'Lafang';
+      brandNameCn = '拉芳';
+    } else if (/fred/i.test(rawText)) {
+      brandNameEn = 'FRED Paris';
+      brandNameCn = '斐登';
+    } else if (/tutucare/i.test(rawText)) {
+      brandNameEn = 'TuTuCare';
+      brandNameCn = '途途呵护';
+    } else {
+      const bMatch = rawText.match(/แบรนด์\s+([A-Za-z0-9\u4e00-\u9fa5]+)/i) || rawText.match(/brand\s+([A-Za-z0-9\u4e00-\u9fa5]+)/i);
+      if (bMatch) {
+        brandNameEn = bMatch[1];
+      }
+    }
+  }
+
+  let title = '';
+  const quoteMatch = rawText.match(/["“'「]([^"”'」]{3,50})["”'」]/);
+  if (quoteMatch) {
+    title = quoteMatch[1];
+  } else {
+    const firstSentence = rawText.split(/[.\n!?|]/)[0]?.trim();
+    title = firstSentence && firstSentence.length <= 80 ? firstSentence : `${brandNameEn || 'Ju Jingyi'} Event ${eventYear}`;
+  }
+
+  return {
+    category,
+    year: eventYear,
+    date: isoDate,
+    title,
+    titleCn: brandNameCn || null,
+    titleTh: title,
+    brand: brandNameEn || (isBrand ? title : null),
+    brandNameEn: brandNameEn || null,
+    brandNameCn: brandNameCn || null,
+    role: isBrand ? 'Brand Ambassador' : 'Artist',
+    highlight: rawText.slice(0, 200).trim(),
+    summary: rawText,
+    source: 'extracted_text'
+  };
+}
+
+export async function ingestRawEvent(text, {
+  category = null,
+  source = 'manual',
+  trustTier = null,
+  client = null,
+  catalogPath = DEFAULT_DYNAMIC_CATALOG_PATH
+} = {}) {
+  try {
+    const trustInfo = isTrustedSource(source);
+    const finalTrustTier = trustTier != null ? Number(trustTier) : trustInfo.tier;
+
+    if (finalTrustTier > 2 && !trustInfo.trusted && trustTier == null) {
+      return {
+        status: 'rejected',
+        reason: 'Untrusted source (Tier 3 community/unverified). Provide explicit trustTier to override.',
+        source,
+        tier: finalTrustTier
+      };
+    }
+
+    const structured = await extractStructuredEvent(text, { client });
+    const targetCategory = category || structured.category || 'events';
+
+    const entryToSave = {
+      ...structured,
+      source: source || structured.source || 'manual',
+      trustTier: finalTrustTier
+    };
+
+    const existing = getDynamicEntries(targetCategory, null, catalogPath);
+    if (isDuplicateEvent(entryToSave, existing)) {
+      return {
+        status: 'duplicate',
+        message: `Event already exists in dynamic catalog category "${targetCategory}".`,
+        entry: entryToSave
+      };
+    }
+
+    const saved = addDynamicEntry(targetCategory, entryToSave, {
+      catalogPath,
+      trustTier: finalTrustTier,
+      source
+    });
+
+    return {
+      status: 'success',
+      message: `Successfully ingested event into category "${targetCategory}".`,
+      entry: saved
+    };
+  } catch (err) {
+    return {
+      status: 'error',
+      message: `Ingestion failed: ${err.message}`
+    };
+  }
+}
+
+export async function runIngestionScan({
+  topic = 'Ju Jingyi 鞠婧祎',
+  fetcher = null,
+  client = null,
+  catalogPath = DEFAULT_DYNAMIC_CATALOG_PATH,
+  minTrustTier = 2,
+  maxItems = 8
+} = {}) {
+  let items = [];
+  if (typeof fetcher === 'function') {
+    items = await fetcher(topic);
+  } else {
+    const res = await searchNews(topic, maxItems);
+    items = res?.results || [];
+  }
+
+  let totalScanned = items.length;
+  let ingestedCount = 0;
+  let skippedDuplicates = 0;
+  let skippedUntrusted = 0;
+  const entries = [];
+
+  for (const item of items) {
+    const url = item.url || '';
+    const trust = isTrustedSource(url);
+
+    if (trust.tier > minTrustTier) {
+      skippedUntrusted++;
+      continue;
+    }
+
+    const combinedText = `${item.title || ''}\n${item.snippet || ''}`.trim();
+    if (!combinedText) continue;
+
+    const res = await ingestRawEvent(combinedText, {
+      source: url || item.source || 'news_scan',
+      trustTier: trust.tier,
+      client,
+      catalogPath
+    });
+
+    if (res.status === 'success') {
+      ingestedCount++;
+      entries.push(res.entry);
+    } else if (res.status === 'duplicate') {
+      skippedDuplicates++;
+    } else if (res.status === 'rejected') {
+      skippedUntrusted++;
+    }
+  }
+
+  return {
+    totalScanned,
+    ingestedCount,
+    skippedDuplicates,
+    skippedUntrusted,
+    entries
+  };
+}

package/server/agent/lanDiscovery.js

@@ -0,0 +1,369 @@
+import net from 'node:net';
+import os from 'node:os';
+import { isPrivateIPv4 } from './sanitizer.js';
+
+export const DEFAULT_LLM_PORTS = Object.freeze([1234, 8000, 11434, 8080]);
+
+const CACHE_TTL_MS = 60_000;
+
+const SERVER_TYPE_LABELS = Object.freeze({
+  lmstudio: 'LM Studio',
+  vllm: 'vLLM',
+  ollama: 'Ollama',
+  'openai-compatible': 'OpenAI-Compatible',
+});
+
+export function mapServerTypeToProvider(serverType) {
+  if (serverType === 'lmstudio') return 'lmstudio';
+  if (serverType === 'vllm') return 'vllm';
+  return 'custom';
+}
+
+function parseIpv4(host) {
+  const parts = String(host || '').split('.');
+  if (parts.length !== 4) return null;
+  const octets = parts.map(p => Number(p));
+  if (octets.some(n => !Number.isInteger(n) || n < 0 || n > 255)) return null;
+  return octets;
+}
+
+export function getLanCandidateSubnets(interfaces = os.networkInterfaces()) {
+  const seen = new Set();
+  const subnets = [];
+  for (const [name, addresses] of Object.entries(interfaces || {})) {
+    for (const entry of addresses || []) {
+      if (!entry || entry.internal || entry.family !== 'IPv4') continue;
+      const octets = parseIpv4(entry.address);
+      if (!octets || octets[0] === 127) continue;
+      if (octets[0] === 169 && octets[1] === 254) continue;
+      if (!isPrivateIPv4(entry.address)) continue;
+      const cidr = `${octets[0]}.${octets[1]}.${octets[2]}.0/24`;
+      if (seen.has(cidr)) continue;
+      seen.add(cidr);
+      subnets.push({ cidr, interfaceName: name, address: entry.address });
+    }
+  }
+  return subnets;
+}
+
+export function expandCidrToHosts(cidr) {
+  const base = String(cidr || '').split('/')[0];
+  const octets = parseIpv4(base);
+  if (!octets) throw new Error(`Invalid CIDR "${cidr}"`);
+  const hosts = [];
+  for (let last = 1; last <= 254; last++) {
+    hosts.push(`${octets[0]}.${octets[1]}.${octets[2]}.${last}`);
+  }
+  return hosts;
+}
+
+export const DEFAULT_MAX_SCAN_HOSTS = 4096;
+
+function ipv4ToUint32(octets) {
+  return ((octets[0] << 24) | (octets[1] << 16) | (octets[2] << 8) | octets[3]) >>> 0;
+}
+
+function uint32ToIp(value) {
+  return `${(value >>> 24) & 255}.${(value >>> 16) & 255}.${(value >>> 8) & 255}.${value & 255}`;
+}
+
+export function expandTargets(specs, { maxHosts = DEFAULT_MAX_SCAN_HOSTS } = {}) {
+  const list = Array.isArray(specs) ? specs : String(specs || '').split(',');
+  const out = [];
+  const seen = new Set();
+  let planned = 0;
+
+  const pushIp = value => {
+    const ip = uint32ToIp(value);
+    if (!seen.has(ip)) {
+      seen.add(ip);
+      out.push(ip);
+    }
+  };
+
+  for (const raw of list) {
+    const spec = String(raw || '').trim();
+    if (!spec) continue;
+
+    if (spec.includes('/')) {
+      const [base, prefixStr] = spec.split('/');
+      const octets = parseIpv4(base);
+      const prefix = Number(prefixStr);
+      if (!octets || !Number.isInteger(prefix) || prefix < 8 || prefix > 32) {
+        throw new Error(`Invalid CIDR "${spec}" (expected a.b.c.d/8..32)`);
+      }
+      const network = prefix === 0 ? 0 : (ipv4ToUint32(octets) & (0xffffffff << (32 - prefix))) >>> 0;
+      const size = 2 ** (32 - prefix);
+      const usable = prefix <= 30 ? size - 2 : size;
+      planned += usable;
+      if (planned > maxHosts) {
+        throw new Error(`Scan target limit exceeded (>${maxHosts} hosts). Narrow the range or raise KIKU_LAN_SCAN_MAX_HOSTS.`);
+      }
+      const first = prefix <= 30 ? network + 1 : network;
+      const last = prefix <= 30 ? network + size - 2 : network + size - 1;
+      for (let ip = first; ip <= last; ip++) pushIp(ip >>> 0);
+    } else if (spec.includes('-')) {
+      const [startStr, endStr] = spec.split('-');
+      const startOctets = parseIpv4(startStr);
+      const endOctets = parseIpv4(endStr);
+      if (!startOctets || !endOctets) {
+        throw new Error(`Invalid IP range "${spec}" (expected a.b.c.d-e.f.g.h)`);
+      }
+      const start = ipv4ToUint32(startOctets);
+      const end = ipv4ToUint32(endOctets);
+      if (end < start) throw new Error(`Invalid IP range "${spec}" (start is after end)`);
+      const count = end - start + 1;
+      planned += count;
+      if (planned > maxHosts) {
+        throw new Error(`Scan target limit exceeded (>${maxHosts} hosts). Narrow the range or raise KIKU_LAN_SCAN_MAX_HOSTS.`);
+      }
+      for (let ip = start; ip <= end; ip++) pushIp(ip >>> 0);
+    } else {
+      const octets = parseIpv4(spec);
+      if (!octets) throw new Error(`Invalid IP address "${spec}"`);
+      planned += 1;
+      pushIp(ipv4ToUint32(octets));
+    }
+  }
+
+  return out;
+}
+
+function assertAllPrivate(hosts) {
+  const offenders = hosts.filter(h => {
+    const octets = parseIpv4(h);
+    if (!octets) return true;
+    if (octets[0] === 127) return false;
+    return !isPrivateIPv4(h);
+  });
+  if (offenders.length > 0) {
+    throw new Error(`LAN discovery only scans private network ranges (RFC1918). Rejected: ${offenders.slice(0, 5).join(', ')}`);
+  }
+}
+
+function abortError() {
+  const error = new Error('LAN scan cancelled');
+  error.name = 'AbortError';
+  return error;
+}
+
+function defaultTcpProbe(host, port, timeoutMs, signal) {
+  return new Promise(resolve => {
+    if (signal?.aborted) {
+      resolve(false);
+      return;
+    }
+    const socket = new net.Socket();
+    let settled = false;
+    const onAbort = () => done(false);
+    const done = result => {
+      if (settled) return;
+      settled = true;
+      signal?.removeEventListener('abort', onAbort);
+      socket.destroy();
+      resolve(result);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => done(true));
+    socket.once('timeout', () => done(false));
+    socket.once('error', () => done(false));
+    signal?.addEventListener('abort', onAbort, { once: true });
+    socket.connect(port, host);
+  });
+}
+
+export async function classifyModelsEndpoint({ host, port, timeoutMs = 2500, signal, fetchImpl = fetch }) {
+  const started = performance.now();
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  const fetchSignal = signal ? AbortSignal.any([timeoutSignal, signal]) : timeoutSignal;
+  const record = {
+    host,
+    port,
+    url: `http://${host}:${port}/v1`,
+    reachable: false,
+    serverType: 'openai-compatible',
+    serverName: SERVER_TYPE_LABELS['openai-compatible'],
+    models: [],
+    modelCount: 0,
+    authRequired: false,
+    latencyMs: null,
+  };
+
+  let modelsPayload = null;
+  try {
+    const res = await fetchImpl(`http://${host}:${port}/v1/models`, {
+      headers: { Accept: 'application/json' },
+      signal: fetchSignal,
+    });
+    if (res.status === 401 || res.status === 403) {
+      record.reachable = true;
+      record.authRequired = true;
+      record.latencyMs = Math.round(performance.now() - started);
+      return record;
+    }
+    if (res.ok) {
+      const json = await res.json().catch(() => null);
+      if (json && Array.isArray(json.data)) {
+        record.reachable = true;
+        modelsPayload = json;
+        record.models = json.data.map(m => m?.id).filter(Boolean);
+      }
+    }
+  } catch {
+    return record;
+  }
+
+  const ownedBy = (modelsPayload?.data || []).map(m => String(m?.owned_by || '').toLowerCase()).join(' ');
+  if (ownedBy.includes('lmstudio')) record.serverType = 'lmstudio';
+  else if (ownedBy.includes('vllm')) record.serverType = 'vllm';
+  else {
+    try {
+      const tagsRes = await fetchImpl(`http://${host}:${port}/api/tags`, {
+        headers: { Accept: 'application/json' },
+        signal: fetchSignal,
+      });
+      if (tagsRes.ok) {
+        const tags = await tagsRes.json().catch(() => null);
+        if (tags && Array.isArray(tags.models)) {
+          record.reachable = true;
+          record.serverType = 'ollama';
+          if (record.models.length === 0) {
+            record.models = tags.models.map(m => m?.name || m?.model).filter(Boolean);
+          }
+        }
+      }
+    } catch {}
+  }
+
+  if (record.reachable && record.serverType === 'openai-compatible') {
+    try {
+      const v0Res = await fetchImpl(`http://${host}:${port}/api/v0/models`, {
+        headers: { Accept: 'application/json' },
+        signal: fetchSignal,
+      });
+      if (v0Res.ok) {
+        const v0 = await v0Res.json().catch(() => null);
+        if (v0 && Array.isArray(v0.data)) {
+          record.serverType = 'lmstudio';
+          if (record.models.length === 0) {
+            record.models = v0.data.map(m => m?.id).filter(Boolean);
+          }
+        }
+      }
+    } catch {}
+  }
+
+  if (record.reachable && record.serverType === 'openai-compatible') {
+    try {
+      const versionRes = await fetchImpl(`http://${host}:${port}/version`, {
+        headers: { Accept: 'application/json' },
+        signal: fetchSignal,
+      });
+      if (versionRes.ok) {
+        const version = await versionRes.json().catch(() => null);
+        if (version && version.version) {
+          record.serverType = 'vllm';
+        }
+      }
+    } catch {}
+  }
+
+  record.serverName = SERVER_TYPE_LABELS[record.serverType] || record.serverType;
+  record.modelCount = record.models.length;
+  record.latencyMs = Math.round(performance.now() - started);
+  return record;
+}
+
+async function runPool(items, concurrency, worker, signal) {
+  const results = [];
+  let cursor = 0;
+  const lanes = Array.from({ length: Math.max(1, Math.min(concurrency, items.length)) }, async () => {
+    while (cursor < items.length) {
+      if (signal?.aborted) throw abortError();
+      const index = cursor++;
+      results[index] = await worker(items[index], index);
+    }
+  });
+  await Promise.all(lanes);
+  return results;
+}
+
+let scanCache = null;
+
+export function clearLanScanCache() {
+  scanCache = null;
+}
+
+export async function scanLan({
+  ports = DEFAULT_LLM_PORTS,
+  timeoutMs = 900,
+  probeTimeoutMs = 2500,
+  concurrency = 128,
+  subnets = null,
+  extraHosts = [],
+  maxHosts = Number(process.env.KIKU_LAN_SCAN_MAX_HOSTS) || DEFAULT_MAX_SCAN_HOSTS,
+  connector = defaultTcpProbe,
+  prober = classifyModelsEndpoint,
+  now = Date.now,
+  force = false,
+  signal = null,
+} = {}) {
+  if (signal?.aborted) throw abortError();
+  const portList = [...new Set((Array.isArray(ports) ? ports : DEFAULT_LLM_PORTS).map(Number))].filter(
+    p => Number.isInteger(p) && p >= 1 && p <= 65535
+  );
+  if (portList.length === 0) throw new Error('At least one valid port is required');
+
+  const subnetList = subnets && subnets.length > 0 ? subnets : getLanCandidateSubnets().map(s => s.cidr);
+  const detectedHosts = expandTargets(subnetList, { maxHosts });
+  const hostList = [...new Set(['127.0.0.1', ...detectedHosts, ...extraHosts.map(String)])];
+  assertAllPrivate(hostList);
+
+  const cacheKey = JSON.stringify({ ports: portList, hosts: hostList });
+  if (!force && scanCache && scanCache.key === cacheKey && now() - scanCache.at < CACHE_TTL_MS) {
+    return { ...scanCache.result, cached: true };
+  }
+
+  const targets = [];
+  for (const host of hostList) {
+    for (const port of portList) {
+      targets.push({ host, port });
+    }
+  }
+
+  const started = now();
+  const openTargets = [];
+  await runPool(targets, concurrency, async ({ host, port }) => {
+    const isOpen = await connector(host, port, timeoutMs, signal);
+    if (isOpen) openTargets.push({ host, port });
+  }, signal);
+  openTargets.sort((a, b) => a.host.localeCompare(b.host, undefined, { numeric: true }) || a.port - b.port);
+  if (signal?.aborted) throw abortError();
+
+  const endpoints = await runPool(openTargets, Math.min(concurrency, 16), async ({ host, port }) => {
+    try {
+      return await prober({ host, port, timeoutMs: probeTimeoutMs, signal });
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      return { host, port, url: `http://${host}:${port}/v1`, reachable: false, serverType: 'openai-compatible', serverName: 'OpenAI-Compatible', models: [], modelCount: 0, authRequired: false, latencyMs: null };
+    }
+  }, signal);
+
+  const found = endpoints
+    .filter(e => e && e.reachable)
+    .sort((a, b) => (a.latencyMs ?? 9e9) - (b.latencyMs ?? 9e9) || a.host.localeCompare(b.host, undefined, { numeric: true }));
+
+  const result = {
+    scannedAt: new Date(started).toISOString(),
+    subnets: subnetList,
+    hostsScanned: hostList.length,
+    ports: portList,
+    targetsScanned: targets.length,
+    openPorts: openTargets.length,
+    durationMs: now() - started,
+    endpoints: found,
+  };
+
+  scanCache = { key: cacheKey, at: now(), result };
+  return { ...result, cached: false };
+}