@sylphx/lookout 0.1.0

package/src/crawl.ts

@@ -0,0 +1,204 @@
+/**
+ * Depth-limited same-origin crawl — light advanced tool (not a full wigolo crawler).
+ */
+import { webFetch } from './fetch.ts';
+import { assertSafeUrl } from './ssrf.ts';
+import { decodeEntities } from './search.ts';
+import { checkRobotsAllowed } from './robots.ts';
+import { parseSitemapXml } from './sitemap.ts';
+
+export type CrawlPage = {
+  url: string;
+  status?: number;
+  ok: boolean;
+  title?: string;
+  description?: string;
+  textExcerpt?: string;
+  links: string[];
+  error?: string;
+};
+
+export type CrawlResult = {
+  ok: boolean;
+  seed: string;
+  maxDepth: number;
+  maxPages: number;
+  pages: CrawlPage[];
+  warnings: string[];
+  route: string;
+};
+
+export function extractTitle(html: string): string | undefined {
+  const m = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+  return m ? decodeEntities(m[1]?.replace(/<[^>]+>/g, '').trim() ?? '') : undefined;
+}
+
+export function extractDescription(html: string): string | undefined {
+  const og = html.match(
+    /<meta[^>]+property=["']og:description["'][^>]+content=["']([^"']+)["'][^>]*>/i,
+  ) || html.match(
+    /<meta[^>]+content=["']([^"']+)["'][^>]+property=["']og:description["'][^>]*>/i,
+  );
+  if (og?.[1]) return decodeEntities(og[1].trim());
+  const md = html.match(
+    /<meta[^>]+name=["']description["'][^>]+content=["']([^"']+)["'][^>]*>/i,
+  ) || html.match(
+    /<meta[^>]+content=["']([^"']+)["'][^>]+name=["']description["'][^>]*>/i,
+  );
+  return md?.[1] ? decodeEntities(md[1].trim()) : undefined;
+}
+
+export function extractTextExcerpt(html: string, max = 400): string | undefined {
+  const body = html.replace(/<script[\s\S]*?<\/script>/gi, ' ').replace(/<style[\s\S]*?<\/style>/gi, ' ');
+  const text = decodeEntities(body.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim());
+  if (!text) return undefined;
+  return text.slice(0, max);
+}
+
+function extractLinks(html: string, base: string): string[] {
+  const out: string[] = [];
+  const re = /href=["']([^"'#]+)["']/gi;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(html)) !== null) {
+    try {
+      const abs = new URL(m[1] ?? '', base).toString();
+      out.push(abs.split('#')[0] ?? abs);
+    } catch {
+      // ignore
+    }
+  }
+  return [...new Set(out)];
+}
+
+export async function webCrawl(
+  seed: string,
+  options: { maxDepth?: number; maxPages?: number; respectRobots?: boolean; useSitemap?: boolean } = {},
+): Promise<CrawlResult> {
+  const maxDepth = Math.min(options.maxDepth ?? 1, 3);
+  const maxPages = Math.min(options.maxPages ?? 10, 25);
+  const warnings: string[] = [];
+  const seedCheck = assertSafeUrl(seed);
+  if (!seedCheck.ok) {
+    return {
+      ok: false,
+      seed,
+      maxDepth,
+      maxPages,
+      pages: [],
+      warnings: [seedCheck.message],
+      route: 'crawl_light',
+    };
+  }
+  const origin = seedCheck.url.origin;
+  const respectRobots = options.respectRobots !== false;
+  if (respectRobots) {
+    const robots = await checkRobotsAllowed(seedCheck.url.toString(), { respectRobots: true });
+    if (!robots.allowed) {
+      return {
+        ok: false,
+        seed,
+        maxDepth: Math.min(options.maxDepth ?? 1, 3),
+        maxPages: Math.min(options.maxPages ?? 10, 25),
+        pages: [],
+        warnings: [robots.warning ?? 'robots.txt disallows seed'],
+        route: 'crawl_light',
+      };
+    }
+    if (robots.warning) {
+      // missing robots.txt is fail-open with warning recorded later if we had a warnings push before loop
+    }
+  }
+  const queue: { url: string; depth: number }[] = [{ url: seedCheck.url.toString(), depth: 0 }];
+  const seen = new Set<string>();
+  const pages: CrawlPage[] = [];
+
+  if (options.useSitemap) {
+    const sitemapUrl = `${origin}/sitemap.xml`;
+    try {
+      const sm = await webFetch(sitemapUrl, { timeoutMs: 8_000, maxBytes: 500_000 });
+      if (sm.ok && sm.body) {
+        const locs = parseSitemapXml(sm.body, Math.max(0, maxPages - 1));
+        let added = 0;
+        for (const loc of locs) {
+          try {
+            const u = new URL(loc);
+            if (u.origin === origin) {
+              queue.push({ url: u.toString(), depth: 0 });
+              added += 1;
+            }
+          } catch {
+            // ignore
+          }
+        }
+        warnings.push(`sitemap.xml seeded ${added} same-origin URLs`);
+      } else {
+        warnings.push(`sitemap.xml unavailable (${sm.message ?? sm.code ?? sm.status})`);
+      }
+    } catch (e) {
+      warnings.push(e instanceof Error ? e.message : 'sitemap_fetch_error');
+    }
+  }
+
+  while (queue.length && pages.length < maxPages) {
+    const { url, depth } = queue.shift()!;
+    if (seen.has(url)) continue;
+    seen.add(url);
+    const safety = assertSafeUrl(url);
+    if (!safety.ok) {
+      pages.push({ url, ok: false, links: [], error: safety.message });
+      continue;
+    }
+    if (safety.url.origin !== origin) {
+      warnings.push(`skipped off-origin ${url}`);
+      continue;
+    }
+    if (respectRobots) {
+      const robots = await checkRobotsAllowed(url, { respectRobots: true });
+      if (!robots.allowed) {
+        pages.push({
+          url,
+          ok: false,
+          links: [],
+          error: robots.warning ?? 'robots.txt disallow',
+        });
+        warnings.push(robots.warning ?? `robots disallow ${url}`);
+        continue;
+      }
+    }
+    const fetched = await webFetch(url, { timeoutMs: 12_000, maxBytes: 800_000 });
+    const links = fetched.body ? extractLinks(fetched.body, fetched.finalUrl) : [];
+    pages.push({
+      url: fetched.finalUrl,
+      status: fetched.status,
+      ok: fetched.ok,
+      title: fetched.body ? extractTitle(fetched.body) : undefined,
+      description: fetched.body ? extractDescription(fetched.body) : undefined,
+      textExcerpt: fetched.body ? extractTextExcerpt(fetched.body) : undefined,
+      links: links.slice(0, 50),
+      error: fetched.ok ? undefined : fetched.message,
+    });
+    if (depth < maxDepth && fetched.ok) {
+      for (const link of links) {
+        if (pages.length + queue.length >= maxPages) break;
+        try {
+          const u = new URL(link);
+          if (u.origin === origin && !seen.has(u.toString())) {
+            queue.push({ url: u.toString(), depth: depth + 1 });
+          }
+        } catch {
+          // ignore
+        }
+      }
+    }
+  }
+
+  return {
+    ok: pages.some((p) => p.ok),
+    seed,
+    maxDepth,
+    maxPages,
+    pages,
+    warnings,
+    route: 'crawl_light',
+  };
+}

package/src/doctor.ts

@@ -0,0 +1,73 @@
+import { existsSync } from 'node:fs';
+import { ADVANCED_TOOLS, CORE_TOOLS, LookoutEngine } from './engine.ts';
+import { defaultCacheDir } from './cache.ts';
+import { assertSafeUrl } from './ssrf.ts';
+
+export type DoctorReport = {
+  ok: boolean;
+  product: string;
+  version: string;
+  checks: { name: string; status: 'ok' | 'warn' | 'fail'; message: string }[];
+};
+
+export function runDoctor(version = '0.1.0'): DoctorReport {
+  const checks: DoctorReport['checks'] = [];
+  checks.push({
+    name: 'core_tools',
+    status: CORE_TOOLS.length === 4 ? 'ok' : 'fail',
+    message: `core: ${CORE_TOOLS.join(', ')}; advanced: ${ADVANCED_TOOLS.join(', ')}`,
+  });
+  const cacheDir = defaultCacheDir();
+  checks.push({
+    name: 'cache_dir',
+    status: 'ok',
+    message: `cache dir ${cacheDir} (created on first use)`,
+  });
+  const maxAge = process.env.LOOKOUT_CACHE_MAX_AGE_MS?.trim();
+  checks.push({
+    name: 'cache_max_age_env',
+    status: 'ok',
+    message: maxAge ? `LOOKOUT_CACHE_MAX_AGE_MS=${maxAge}` : 'LOOKOUT_CACHE_MAX_AGE_MS unset (cache entries not age-limited)',
+  });
+  const ua = process.env.LOOKOUT_USER_AGENT?.trim();
+  checks.push({
+    name: 'user_agent_env',
+    status: 'ok',
+    message: ua ? `LOOKOUT_USER_AGENT set (${ua.slice(0, 48)})` : 'LOOKOUT_USER_AGENT unset (default Lookout UA)',
+  });
+  const fetchTimeout = process.env.LOOKOUT_FETCH_TIMEOUT_MS?.trim();
+  const fetchMax = process.env.LOOKOUT_FETCH_MAX_BYTES?.trim();
+  checks.push({
+    name: 'fetch_limits_env',
+    status: 'ok',
+    message: `timeout=${fetchTimeout || 'default'} maxBytes=${fetchMax || 'default'}`,
+  });
+  const ssrf = assertSafeUrl('http://127.0.0.1/');
+  checks.push({
+    name: 'ssrf_blocks_loopback',
+    status: ssrf.ok ? 'fail' : 'ok',
+    message: ssrf.ok ? 'loopback incorrectly allowed' : 'loopback denied',
+  });
+  const eng = new LookoutEngine({ cacheDir: cacheDir });
+  checks.push({
+    name: 'engine_construct',
+    status: eng ? 'ok' : 'fail',
+    message: 'LookoutEngine ready',
+  });
+  // runtime
+  checks.push({
+    name: 'runtime',
+    status: typeof fetch === 'function' ? 'ok' : 'fail',
+    message: typeof fetch === 'function' ? 'global fetch available' : 'fetch missing',
+  });
+  const ok = checks.every((c) => c.status !== 'fail');
+  return { ok, product: 'Lookout', version, checks };
+}
+
+export function formatDoctorReport(r: DoctorReport): string {
+  const lines = [`Lookout doctor — ${r.ok ? 'OK' : 'FAIL'} (v${r.version})`];
+  for (const c of r.checks) {
+    lines.push(`  [${c.status.toUpperCase()}] ${c.name}: ${c.message}`);
+  }
+  return lines.join('\n');
+}

package/src/engine.ts

@@ -0,0 +1,427 @@
+import { LookoutCache, cacheKey, defaultCacheDir } from './cache.ts';
+import { extractFromHtml } from './extract.ts';
+import { webFetch } from './fetch.ts';
+import { checkRobotsAllowed } from './robots.ts';
+import { webSearch, filterHitsByHosts } from './search.ts';
+import { webCrawl } from './crawl.ts';
+import { webResearch } from './research.ts';
+
+export type ToolEnvelope = {
+  status: 'ok' | 'error';
+  tool: string;
+  answer?: unknown;
+  evidence?: unknown;
+  warnings: string[];
+  route?: string;
+  code?: string;
+  message?: string;
+};
+
+export type EngineOptions = {
+  cacheDir?: string;
+};
+
+export class LookoutEngine {
+  readonly cache: LookoutCache;
+
+  constructor(options: EngineOptions = {}) {
+    this.cache = new LookoutCache(options.cacheDir ?? defaultCacheDir());
+  }
+
+  
+  private cacheMaxAgeMs(): number | undefined {
+    const raw = process.env.LOOKOUT_CACHE_MAX_AGE_MS?.trim();
+    if (!raw) return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+  }
+
+  async handle(tool: string, input: Record<string, unknown> = {}): Promise<ToolEnvelope> {
+    switch (tool) {
+      case 'web_search':
+        return this.search(input);
+      case 'web_fetch':
+        return this.fetch(input);
+      case 'web_extract':
+        return this.extract(input);
+      case 'web_cache':
+        return this.cacheTool(input);
+      case 'web_research':
+        return this.research(input);
+      case 'web_crawl':
+        return this.crawl(input);
+      default:
+        return {
+          status: 'error',
+          tool,
+          warnings: [],
+          code: 'UNKNOWN_TOOL',
+          message: `Unknown tool: ${tool}`,
+        };
+    }
+  }
+
+  private async search(input: Record<string, unknown>): Promise<ToolEnvelope> {
+    const queryRaw = input.query ?? input.q;
+    const queries = Array.isArray(queryRaw)
+      ? queryRaw.map(String)
+      : queryRaw
+        ? [String(queryRaw)]
+        : [];
+    if (!queries.length) {
+      return {
+        status: 'error',
+        tool: 'web_search',
+        warnings: [],
+        code: 'INVALID_INPUT',
+        message: 'web_search requires query (string or string[])',
+      };
+    }
+    const useCache = input.useCache !== false;
+    const allHits = [];
+    const warnings: string[] = [];
+    const engines = [];
+    for (const q of queries) {
+      const key = cacheKey(['search', q]);
+      if (useCache) {
+        const cached = this.cache.get(key, { maxAgeMs: this.cacheMaxAgeMs() });
+        if (cached) {
+          const parsed = JSON.parse(cached.body) as Awaited<ReturnType<typeof webSearch>>;
+          allHits.push(...parsed.hits.map((h) => ({ ...h, fromCache: true })));
+          warnings.push(...parsed.warnings.map((w) => `[cache] ${w}`));
+          engines.push(...parsed.engines);
+          continue;
+        }
+      }
+      const result = await webSearch(q);
+      this.cache.put({
+        key,
+        kind: 'search',
+        query: q,
+        body: JSON.stringify(result),
+        meta: { engines: result.engines },
+      });
+      allHits.push(...result.hits);
+      warnings.push(...result.warnings);
+      engines.push(...result.engines);
+    }
+    const includeHosts = Array.isArray(input.hostsInclude)
+      ? input.hostsInclude.map(String)
+      : input.hostInclude
+        ? [String(input.hostInclude)]
+        : [];
+    const excludeHosts = Array.isArray(input.hostsExclude)
+      ? input.hostsExclude.map(String)
+      : input.hostExclude
+        ? [String(input.hostExclude)]
+        : [];
+    let hits = allHits;
+    const filterWarnings: string[] = [];
+    if (includeHosts.length || excludeHosts.length) {
+      const before = hits.length;
+      hits = filterHitsByHosts(hits, { include: includeHosts, exclude: excludeHosts });
+      filterWarnings.push(
+        `host_filter kept ${hits.length}/${before} (include=${includeHosts.join(',') || '*'}; exclude=${excludeHosts.join(',') || 'none'})`,
+      );
+    }
+    return {
+      status: hits.length ? 'ok' : 'error',
+      tool: 'web_search',
+      answer: {
+        queries,
+        hits,
+        engines,
+        hostsInclude: includeHosts.length ? includeHosts : undefined,
+        hostsExclude: excludeHosts.length ? excludeHosts : undefined,
+      },
+      warnings: [...warnings, ...filterWarnings],
+      route: 'local_adapters',
+      code: hits.length ? undefined : 'NO_HITS',
+      message: hits.length ? undefined : 'No search hits from local adapters',
+    };
+  }
+
+  private async fetch(input: Record<string, unknown>): Promise<ToolEnvelope> {
+    const url = String(input.url ?? '');
+    if (!url) {
+      return {
+        status: 'error',
+        tool: 'web_fetch',
+        warnings: [],
+        code: 'INVALID_INPUT',
+        message: 'web_fetch requires url',
+      };
+    }
+    const useCache = input.useCache !== false;
+    const respectRobots = input.respectRobots === true; // default off for fetch (crawl defaults on)
+    const key = cacheKey(['fetch', url, respectRobots ? 'robots' : 'norobots']);
+    if (useCache) {
+      const cached = this.cache.get(key, { maxAgeMs: this.cacheMaxAgeMs() });
+      if (cached) {
+        return {
+          status: 'ok',
+          tool: 'web_fetch',
+          answer: { ...JSON.parse(cached.body), fromCache: true },
+          warnings: ['served_from_cache'],
+          route: 'cache',
+        };
+      }
+    }
+    if (respectRobots) {
+      const robots = await checkRobotsAllowed(url, { respectRobots: true });
+      if (!robots.allowed) {
+        return {
+          status: 'error',
+          tool: 'web_fetch',
+          warnings: [robots.warning ?? 'robots.txt disallow'],
+          code: 'ROBOTS_DISALLOW',
+          message: robots.warning ?? 'Blocked by robots.txt',
+          route: 'robots.txt',
+        };
+      }
+    }
+    const result = await webFetch(url, {
+      maxBytes: typeof input.maxBytes === 'number' ? input.maxBytes : undefined,
+      timeoutMs: typeof input.timeoutMs === 'number' ? input.timeoutMs : undefined,
+    });
+    if (result.ok && result.body) {
+      this.cache.put({
+        key,
+        kind: 'fetch',
+        url: result.finalUrl,
+        contentType: result.contentType,
+        body: JSON.stringify(result),
+      });
+    }
+    // cite span: first 240 chars of body
+    const excerpt = result.body?.slice(0, 240) ?? '';
+    const spans = excerpt
+      ? [{ text: excerpt, start: 0, end: excerpt.length, kind: 'body_prefix' }]
+      : [];
+    return {
+      status: result.ok ? 'ok' : 'error',
+      tool: 'web_fetch',
+      answer: { ...result, spans },
+      warnings: result.warnings,
+      route: result.route,
+      code: result.code,
+      message: result.message,
+    };
+  }
+
+  private async extract(input: Record<string, unknown>): Promise<ToolEnvelope> {
+    let html = typeof input.html === 'string' ? input.html : undefined;
+    let url = typeof input.url === 'string' ? input.url : undefined;
+    if (!html && url) {
+      const fetched = await this.fetch({ url, useCache: input.useCache });
+      if (fetched.status !== 'ok') return { ...fetched, tool: 'web_extract' };
+      const body = (fetched.answer as { body?: string })?.body;
+      html = body;
+      url = (fetched.answer as { finalUrl?: string })?.finalUrl ?? url;
+      if (!input.contentType) {
+        const ct = (fetched.answer as { contentType?: string })?.contentType;
+        if (ct) input = { ...input, contentType: ct };
+      }
+    }
+    if (!html) {
+      return {
+        status: 'error',
+        tool: 'web_extract',
+        warnings: [],
+        code: 'INVALID_INPUT',
+        message: 'web_extract requires html or url',
+      };
+    }
+    // JSON bodies: light local extract without HTML DOM
+    const looksJson =
+      (typeof input.contentType === 'string' && input.contentType.includes('application/json')) ||
+      /^\s*[\[{]/.test(html);
+    if (looksJson && !/<html[\s>]/i.test(html) && !/<body[\s>]/i.test(html)) {
+      let parsed: unknown = null;
+      try {
+        parsed = JSON.parse(html);
+      } catch {
+        // keep as text
+      }
+      const text = typeof parsed === 'string' ? parsed : JSON.stringify(parsed ?? html).slice(0, 4000);
+      return {
+        status: 'ok',
+        tool: 'web_extract',
+        answer: {
+          ok: true,
+          url,
+          textExcerpt: text,
+          headings: [],
+          links: [],
+          jsonLd: parsed && typeof parsed === 'object' ? [parsed] : [],
+          tables: [],
+          spans: text
+            ? [{ text: text.slice(0, 240), start: 0, end: Math.min(240, text.length), kind: 'json_excerpt' }]
+            : [],
+          route: 'json_body',
+          warnings: parsed ? [] : ['json_parse_failed_used_raw_text'],
+        },
+        warnings: parsed ? [] : ['json_parse_failed_used_raw_text'],
+        route: 'json_body',
+      };
+    }
+    const ct = typeof input.contentType === 'string' ? input.contentType : '';
+    if ((ct.includes('text/plain') || ct.includes('text/markdown')) && !/<html[\s>]/i.test(html) && !/<body[\s>]/i.test(html)) {
+      const text = html.slice(0, 4000);
+      return {
+        status: 'ok',
+        tool: 'web_extract',
+        answer: {
+          ok: true,
+          url,
+          textExcerpt: text,
+          headings: [],
+          links: [],
+          jsonLd: [],
+          tables: [],
+          spans: text
+            ? [{ text: text.slice(0, 240), start: 0, end: Math.min(240, text.length), kind: 'text_excerpt' }]
+            : [],
+          route: ct.includes('markdown') ? 'text_markdown' : 'text_plain',
+          warnings: [],
+        },
+        warnings: [],
+        route: ct.includes('markdown') ? 'text_markdown' : 'text_plain',
+      };
+    }
+    const extracted = extractFromHtml(html, url);
+    return {
+      status: 'ok',
+      tool: 'web_extract',
+      answer: extracted,
+      warnings: extracted.warnings,
+      route: extracted.route,
+    };
+  }
+
+
+  
+  private async research(input: Record<string, unknown>): Promise<ToolEnvelope> {
+    const query = typeof input.query === 'string' ? input.query : Array.isArray(input.query) ? input.query.join(' ') : '';
+    if (!query.trim()) {
+      return {
+        status: 'error',
+        tool: 'web_research',
+        code: 'INVALID_INPUT',
+        message: 'web_research requires query',
+        warnings: [],
+      };
+    }
+    const maxPages = typeof input.maxPages === 'number' ? input.maxPages : undefined;
+    const hostsInclude = Array.isArray(input.hostsInclude)
+      ? input.hostsInclude.map(String)
+      : input.hostInclude
+        ? [String(input.hostInclude)]
+        : [];
+    const hostsExclude = Array.isArray(input.hostsExclude)
+      ? input.hostsExclude.map(String)
+      : input.hostExclude
+        ? [String(input.hostExclude)]
+        : [];
+    const result = await webResearch(query, {
+      maxPages,
+      hostsInclude: hostsInclude.length ? hostsInclude : undefined,
+      hostsExclude: hostsExclude.length ? hostsExclude : undefined,
+    });
+    return {
+      status: 'ok',
+      tool: 'web_research',
+      answer: {
+        ...result,
+        hostsInclude: hostsInclude.length ? hostsInclude : undefined,
+        hostsExclude: hostsExclude.length ? hostsExclude : undefined,
+      },
+      evidence: result.pages.flatMap((p) =>
+        (p.spans ?? []).map((s) => ({ url: p.url, kind: s.kind, text: s.text })),
+      ),
+      warnings: result.warnings,
+      route: result.route,
+    };
+  }
+
+  private async crawl(input: Record<string, unknown>): Promise<ToolEnvelope> {
+    const url = String(input.url ?? input.seed ?? '');
+    if (!url) {
+      return {
+        status: 'error',
+        tool: 'web_crawl',
+        warnings: [],
+        code: 'INVALID_INPUT',
+        message: 'web_crawl requires url',
+      };
+    }
+    const result = await webCrawl(url, {
+      maxDepth: typeof input.maxDepth === 'number' ? input.maxDepth : undefined,
+      maxPages: typeof input.maxPages === 'number' ? input.maxPages : undefined,
+    });
+    return {
+      status: result.ok ? 'ok' : 'error',
+      tool: 'web_crawl',
+      answer: result,
+      warnings: result.warnings,
+      route: result.route,
+      code: result.ok ? undefined : 'CRAWL_FAILED',
+    };
+  }
+
+  private cacheTool(input: Record<string, unknown>): ToolEnvelope {
+    const op = String(input.op ?? input.operation ?? 'query');
+    if (op === 'stats') {
+      return {
+        status: 'ok',
+        tool: 'web_cache',
+        answer: this.cache.stats(),
+        warnings: [],
+        route: 'cache',
+      };
+    }
+    if (op === 'clear') {
+      return {
+        status: 'ok',
+        tool: 'web_cache',
+        answer: this.cache.clear(),
+        warnings: [],
+        route: 'cache',
+      };
+    }
+    if (op === 'prune') {
+      const maxAgeMs =
+        typeof input.maxAgeMs === 'number'
+          ? input.maxAgeMs
+          : this.cacheMaxAgeMs() ?? 86_400_000;
+      return {
+        status: 'ok',
+        tool: 'web_cache',
+        answer: { ...this.cache.pruneExpired(maxAgeMs), maxAgeMs },
+        warnings: [],
+        route: 'cache',
+      };
+    }
+    const q = String(input.query ?? '');
+    const limit = typeof input.limit === 'number' ? input.limit : 20;
+    const results = this.cache.query(q, limit).map((r) => ({
+      key: r.key,
+      kind: r.kind,
+      createdAt: r.createdAt,
+      url: r.url,
+      query: r.query,
+      contentType: r.contentType,
+      preview: r.body.slice(0, 200),
+    }));
+    return {
+      status: 'ok',
+      tool: 'web_cache',
+      answer: { results, dir: this.cache.dir },
+      warnings: [],
+      route: 'cache',
+    };
+  }
+}
+
+export const CORE_TOOLS = ['web_search', 'web_fetch', 'web_extract', 'web_cache'] as const;
+export const ADVANCED_TOOLS = ['web_crawl', 'web_research'] as const;