@staticn0va/wigolo 0.1.0 → 0.1.1

package/dist/fetch/router.js

@@ -1,89 +1,193 @@
-import { getConfig } from '../config.js';
-import { createLogger } from '../logger.js';
-import { contentAppearsEmpty } from './content-check.js';
-import { getAuthOptions } from './auth.js';
-export class SmartRouter {
-    httpClient;
-    browserPool;
-    domainMap = new Map();
-    constructor(httpClient, browserPool) {
-        this.httpClient = httpClient;
-        this.browserPool = browserPool;
+import { getConfig } from "../config.js";
+import { createLogger } from "../logger.js";
+import { contentAppearsEmpty } from "./content-check.js";
+import { getAuthOptions } from "./auth.js";
+import { fetchWithPlaywright, shouldEscalate } from "./playwright-tier.js";
+class SmartRouter {
+  domainMap = /* @__PURE__ */ new Map();
+  httpClient;
+  browserPool;
+  httpFetcher;
+  playwrightFetcher;
+  constructor(httpClientOrOptions, browserPool) {
+    if (browserPool !== void 0) {
+      this.httpClient = httpClientOrOptions;
+      this.browserPool = browserPool;
+    } else if (httpClientOrOptions && typeof httpClientOrOptions === "object" && ("httpClient" in httpClientOrOptions || "browserPool" in httpClientOrOptions || "httpFetcher" in httpClientOrOptions || "playwrightFetcher" in httpClientOrOptions)) {
+      const opts = httpClientOrOptions;
+      if (!opts.httpFetcher && !opts.httpClient) {
+        throw new Error("SmartRouter: must provide either httpFetcher or httpClient in options");
+      }
+      this.httpClient = opts.httpClient;
+      this.browserPool = opts.browserPool;
+      this.httpFetcher = opts.httpFetcher ?? this.makeDefaultHttpFetcher();
+      this.playwrightFetcher = opts.playwrightFetcher ?? fetchWithPlaywright;
+      return;
+    } else {
+      this.httpClient = httpClientOrOptions;
     }
-    async fetch(url, options = {}) {
-        const { renderJs = 'auto', useAuth = false, headers, screenshot } = options;
-        const config = getConfig();
-        const logger = createLogger('fetch');
-        const threshold = config.browserFallbackThreshold;
-        const domain = new URL(url).hostname;
-        // Always Playwright for auth or explicit override
-        if (renderJs === 'always' || useAuth) {
-            const authOptions = useAuth ? (getAuthOptions() ?? {}) : {};
-            logger.debug('routing to playwright', { url, reason: useAuth ? 'auth' : 'render_js=always' });
-            return this.browserPool.fetchWithBrowser(url, { headers, screenshot, ...authOptions });
-        }
-        // HTTP only, no fallback
-        if (renderJs === 'never') {
-            logger.debug('routing to http (never)', { url });
-            const result = await this.httpClient.fetch(url, { headers });
-            this.ensureStats(domain);
-            return this.toRawFetchResult(result);
-        }
-        // auto: check if domain is already marked for Playwright
-        const stats = this.ensureStats(domain);
-        if (stats.preferPlaywright) {
-            logger.debug('routing to playwright (domain marked)', { url, domain });
-            return this.browserPool.fetchWithBrowser(url, { headers, screenshot });
-        }
-        // Try HTTP first
-        try {
-            const result = await this.httpClient.fetch(url, { headers });
-            // Check for SPA shell / empty content
-            if (contentAppearsEmpty(result.html)) {
-                logger.info('SPA shell detected, marking domain for playwright', { url, domain });
-                stats.preferPlaywright = true;
-                return this.browserPool.fetchWithBrowser(url, { headers, screenshot });
-            }
-            return this.toRawFetchResult(result);
-        }
-        catch (err) {
-            stats.failureCount++;
-            logger.warn('http fetch failed', {
-                url,
-                domain,
-                failureCount: stats.failureCount,
-                error: err instanceof Error ? err.message : String(err),
-            });
-            if (stats.failureCount >= threshold) {
-                logger.info('failure threshold reached, marking domain for playwright', { url, domain, threshold });
-                stats.preferPlaywright = true;
-                return this.browserPool.fetchWithBrowser(url, { headers, screenshot });
-            }
-            throw err;
+    this.httpFetcher = this.makeDefaultHttpFetcher();
+    this.playwrightFetcher = fetchWithPlaywright;
+  }
+  makeDefaultHttpFetcher() {
+    return async (url, opts) => {
+      if (!this.httpClient) {
+        throw new Error("SmartRouter: httpClient not configured");
+      }
+      const r = await this.httpClient.fetch(url, opts);
+      return { url: r.url, html: r.html, text: "" };
+    };
+  }
+  async fetch(url, options = {}) {
+    const { renderJs = "auto", useAuth = false, headers, screenshot, actions, mode, conditionalHeaders } = options;
+    const config = getConfig();
+    const logger = createLogger("fetch");
+    const threshold = config.browserFallbackThreshold;
+    const domain = new URL(url).hostname;
+    if (mode === "stealth") {
+      logger.debug("routing to stealth (static then escalate)", { url });
+      const staticResult = await this.httpFetcher(url, { headers });
+      this.ensureStats(domain);
+      if (!shouldEscalate(staticResult.text)) {
+        return {
+          url: staticResult.url,
+          finalUrl: staticResult.url,
+          html: staticResult.html,
+          contentType: "text/html",
+          statusCode: 200,
+          method: "http",
+          headers: {}
+        };
+      }
+      try {
+        const pw = await this.playwrightFetcher(url);
+        return {
+          url: staticResult.url,
+          finalUrl: staticResult.url,
+          html: pw.html,
+          contentType: "text/html",
+          statusCode: 200,
+          method: "playwright",
+          headers: {},
+          escalated: true
+        };
+      } catch (err) {
+        if (err instanceof Error && err.message === "playwright_not_installed") {
+          const hint = err.hint ?? "npx playwright install chromium";
+          return {
+            error: "playwright_not_installed",
+            error_reason: "Stealth mode requested but Playwright chromium is not installed",
+            stage: "fetch",
+            hint
+          };
         }
+        return {
+          error: "playwright_fetch_failed",
+          error_reason: err instanceof Error ? err.message : String(err),
+          stage: "fetch",
+          hint: "Stealth fetch failed; check network or retry"
+        };
+      }
     }
-    getDomainStats(domain) {
-        return this.domainMap.get(domain);
+    if (mode === "cache") {
+      if (actions && actions.length > 0) {
+        logger.warn("mode=cache ignores browser actions; switch to default/stealth to execute them", {
+          url,
+          actionCount: actions.length
+        });
+      }
+      logger.debug("routing to http (cache)", { url });
+      if (!this.httpClient) throw new Error("SmartRouter: httpClient not configured");
+      const result = await this.httpClient.fetch(url, {
+        headers,
+        timeoutMs: config.fastTimeoutMs,
+        conditionalHeaders
+      });
+      this.ensureStats(domain);
+      const raw = this.toRawFetchResult(result);
+      raw.jsRequired = result.statusCode === 304 ? false : contentAppearsEmpty(result.html);
+      return raw;
     }
-    ensureStats(domain) {
-        let stats = this.domainMap.get(domain);
-        if (!stats) {
-            stats = { failureCount: 0, preferPlaywright: false };
-            this.domainMap.set(domain, stats);
-        }
-        return stats;
+    if (actions && actions.length > 0) {
+      if (!this.browserPool) throw new Error("SmartRouter: browserPool not configured");
+      const authOptions = useAuth ? await getAuthOptions() ?? {} : {};
+      logger.debug("routing to playwright", { url, reason: "actions present" });
+      return this.browserPool.fetchWithBrowser(url, { headers, screenshot, actions, ...authOptions });
     }
-    toRawFetchResult(result) {
-        return {
-            url: result.url,
-            finalUrl: result.finalUrl,
-            html: result.html,
-            contentType: result.contentType,
-            statusCode: result.statusCode,
-            method: 'http',
-            headers: result.headers,
-            rawBuffer: result.rawBuffer,
-        };
+    if (renderJs === "always" || useAuth) {
+      if (!this.browserPool) throw new Error("SmartRouter: browserPool not configured");
+      const authOptions = useAuth ? await getAuthOptions() ?? {} : {};
+      logger.debug("routing to playwright", { url, reason: useAuth ? "auth" : "render_js=always" });
+      return this.browserPool.fetchWithBrowser(url, { headers, screenshot, ...authOptions });
+    }
+    if (renderJs === "never") {
+      if (!this.httpClient) throw new Error("SmartRouter: httpClient not configured");
+      logger.debug("routing to http (never)", { url });
+      const result = await this.httpClient.fetch(url, { headers, conditionalHeaders });
+      this.ensureStats(domain);
+      return this.toRawFetchResult(result);
+    }
+    const stats = this.ensureStats(domain);
+    if (stats.preferPlaywright) {
+      if (!this.browserPool) throw new Error("SmartRouter: browserPool not configured");
+      logger.debug("routing to playwright (domain marked)", { url, domain });
+      return this.browserPool.fetchWithBrowser(url, { headers, screenshot });
+    }
+    try {
+      if (!this.httpClient) throw new Error("SmartRouter: httpClient not configured");
+      const result = await this.httpClient.fetch(url, { headers, conditionalHeaders });
+      if (result.statusCode === 304) {
+        return this.toRawFetchResult(result);
+      }
+      if (contentAppearsEmpty(result.html)) {
+        if (!this.browserPool) throw new Error("SmartRouter: browserPool not configured");
+        logger.info("SPA shell detected, marking domain for playwright", { url, domain });
+        stats.preferPlaywright = true;
+        return this.browserPool.fetchWithBrowser(url, { headers, screenshot });
+      }
+      return this.toRawFetchResult(result);
+    } catch (err) {
+      stats.failureCount++;
+      logger.warn("http fetch failed", {
+        url,
+        domain,
+        failureCount: stats.failureCount,
+        error: err instanceof Error ? err.message : String(err)
+      });
+      if (stats.failureCount >= threshold) {
+        if (!this.browserPool) throw new Error("SmartRouter: browserPool not configured");
+        logger.info("failure threshold reached, marking domain for playwright", { url, domain, threshold });
+        stats.preferPlaywright = true;
+        return this.browserPool.fetchWithBrowser(url, { headers, screenshot });
+      }
+      throw err;
+    }
+  }
+  getDomainStats(domain) {
+    return this.domainMap.get(domain);
+  }
+  ensureStats(domain) {
+    let stats = this.domainMap.get(domain);
+    if (!stats) {
+      stats = { failureCount: 0, preferPlaywright: false };
+      this.domainMap.set(domain, stats);
     }
+    return stats;
+  }
+  toRawFetchResult(result) {
+    return {
+      url: result.url,
+      finalUrl: result.finalUrl,
+      html: result.html,
+      contentType: result.contentType,
+      statusCode: result.statusCode,
+      method: "http",
+      headers: result.headers,
+      rawBuffer: result.rawBuffer
+    };
+  }
 }
+export {
+  SmartRouter
+};
 //# sourceMappingURL=router.js.map

package/dist/fetch/router.js.map

@@ -1 +1 @@
-{"version":3,"file":"router.js","sourceRoot":"","sources":["../../src/fetch/router.ts"],"names":[],"mappings":"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"}
+{"version":3,"sources":["../../src/fetch/router.ts"],"sourcesContent":["import { getConfig } from '../config.js';\nimport { createLogger } from '../logger.js';\nimport { contentAppearsEmpty } from './content-check.js';\nimport { getAuthOptions } from './auth.js';\nimport { fetchWithPlaywright, shouldEscalate } from './playwright-tier.js';\nimport type { RawFetchResult, BrowserAction, Mode, StageError } from '../types.js';\n\nexport interface RouterFetchOptions {\n  renderJs?: 'auto' | 'always' | 'never';\n  useAuth?: boolean;\n  headers?: Record<string, string>;\n  screenshot?: boolean;\n  actions?: BrowserAction[];\n  force_refresh?: boolean;\n  mode?: Mode;\n  /**\n   * Conditional-GET headers. When set, the HTTP path sends them with the\n   * request and a 304 response is returned as RawFetchResult with\n   * statusCode=304 + html=''. Routes that always escalate to Playwright\n   * (renderJs=always, useAuth, actions) ignore these headers.\n   */\n  conditionalHeaders?: {\n    ifNoneMatch?: string;\n    ifModifiedSince?: string;\n  };\n}\n\nexport interface HttpClient {\n  fetch(\n    url: string,\n    options?: {\n      headers?: Record<string, string>;\n      timeoutMs?: number;\n      conditionalHeaders?: {\n        ifNoneMatch?: string;\n        ifModifiedSince?: string;\n      };\n    },\n  ): Promise<{\n    url: string;\n    finalUrl: string;\n    html: string;\n    contentType: string;\n    statusCode: number;\n    headers: Record<string, string>;\n    rawBuffer?: Buffer;\n  }>;\n}\n\nexport interface BrowserPoolInterface {\n  fetchWithBrowser(\n    url: string,\n    options?: { headers?: Record<string, string>; storageStatePath?: string; userDataDir?: string; screenshot?: boolean; actions?: BrowserAction[]; cdpUrl?: string },\n  ): Promise<RawFetchResult>;\n}\n\nexport type HttpFetcher = (\n  url: string,\n  options?: { headers?: Record<string, string>; timeoutMs?: number },\n) => Promise<{ url: string; html: string; text: string }>;\n\nexport type PlaywrightFetcher = (\n  url: string,\n  options?: { timeoutMs?: number },\n) => Promise<{ html: string; text: string }>;\n\nexport interface SmartRouterOptions {\n  httpClient?: HttpClient;\n  browserPool?: BrowserPoolInterface;\n  httpFetcher?: HttpFetcher;\n  playwrightFetcher?: PlaywrightFetcher;\n}\n\ninterface DomainStats {\n  failureCount: number;\n  preferPlaywright: boolean;\n}\n\nexport class SmartRouter {\n  private readonly domainMap = new Map<string, DomainStats>();\n  private readonly httpClient?: HttpClient;\n  private readonly browserPool?: BrowserPoolInterface;\n  private readonly httpFetcher: HttpFetcher;\n  private readonly playwrightFetcher: PlaywrightFetcher;\n\n  constructor(httpClient: HttpClient, browserPool: BrowserPoolInterface);\n  constructor(options: SmartRouterOptions);\n  constructor(\n    httpClientOrOptions: HttpClient | SmartRouterOptions,\n    browserPool?: BrowserPoolInterface,\n  ) {\n    if (browserPool !== undefined) {\n      this.httpClient = httpClientOrOptions as HttpClient;\n      this.browserPool = browserPool;\n    } else if (\n      httpClientOrOptions &&\n      typeof httpClientOrOptions === 'object' &&\n      ('httpClient' in httpClientOrOptions ||\n        'browserPool' in httpClientOrOptions ||\n        'httpFetcher' in httpClientOrOptions ||\n        'playwrightFetcher' in httpClientOrOptions)\n    ) {\n      const opts = httpClientOrOptions as SmartRouterOptions;\n      if (!opts.httpFetcher && !opts.httpClient) {\n        throw new Error('SmartRouter: must provide either httpFetcher or httpClient in options');\n      }\n      this.httpClient = opts.httpClient;\n      this.browserPool = opts.browserPool;\n      this.httpFetcher = opts.httpFetcher ?? this.makeDefaultHttpFetcher();\n      this.playwrightFetcher = opts.playwrightFetcher ?? fetchWithPlaywright;\n      return;\n    } else {\n      // Backwards-compat: single HttpClient positional (unusual but safe)\n      this.httpClient = httpClientOrOptions as HttpClient;\n    }\n    this.httpFetcher = this.makeDefaultHttpFetcher();\n    this.playwrightFetcher = fetchWithPlaywright;\n  }\n\n  private makeDefaultHttpFetcher(): HttpFetcher {\n    return async (url, opts) => {\n      if (!this.httpClient) {\n        throw new Error('SmartRouter: httpClient not configured');\n      }\n      const r = await this.httpClient.fetch(url, opts);\n      return { url: r.url, html: r.html, text: '' };\n    };\n  }\n\n  async fetch(url: string, options: RouterFetchOptions & { mode: 'stealth' }): Promise<RawFetchResult | StageError>;\n  async fetch(url: string, options?: RouterFetchOptions): Promise<RawFetchResult>;\n  async fetch(\n    url: string,\n    options: RouterFetchOptions = {},\n  ): Promise<RawFetchResult | StageError> {\n    const { renderJs = 'auto', useAuth = false, headers, screenshot, actions, mode, conditionalHeaders } = options;\n    const config = getConfig();\n    const logger = createLogger('fetch');\n    const threshold = config.browserFallbackThreshold;\n    const domain = new URL(url).hostname;\n\n    // Stealth mode: static fetch first, escalate to Playwright when content is thin.\n    if (mode === 'stealth') {\n      logger.debug('routing to stealth (static then escalate)', { url });\n      const staticResult = await this.httpFetcher(url, { headers });\n      this.ensureStats(domain);\n      if (!shouldEscalate(staticResult.text)) {\n        return {\n          url: staticResult.url,\n          finalUrl: staticResult.url,\n          html: staticResult.html,\n          contentType: 'text/html',\n          statusCode: 200,\n          method: 'http',\n          headers: {},\n        };\n      }\n      try {\n        const pw = await this.playwrightFetcher(url);\n        return {\n          url: staticResult.url,\n          finalUrl: staticResult.url,\n          html: pw.html,\n          contentType: 'text/html',\n          statusCode: 200,\n          method: 'playwright',\n          headers: {},\n          escalated: true,\n        };\n      } catch (err) {\n        if (err instanceof Error && err.message === 'playwright_not_installed') {\n          const hint = (err as Error & { hint?: string }).hint ?? 'npx playwright install chromium';\n          return {\n            error: 'playwright_not_installed',\n            error_reason: 'Stealth mode requested but Playwright chromium is not installed',\n            stage: 'fetch',\n            hint,\n          };\n        }\n        return {\n          error: 'playwright_fetch_failed',\n          error_reason: err instanceof Error ? err.message : String(err),\n          stage: 'fetch',\n          hint: 'Stealth fetch failed; check network or retry',\n        };\n      }\n    }\n\n    // Cache mode: HTTP-only with tight timeout, never escalates to a browser.\n    if (mode === 'cache') {\n      if (actions && actions.length > 0) {\n        logger.warn('mode=cache ignores browser actions; switch to default/stealth to execute them', {\n          url,\n          actionCount: actions.length,\n        });\n      }\n      logger.debug('routing to http (cache)', { url });\n      if (!this.httpClient) throw new Error('SmartRouter: httpClient not configured');\n      const result = await this.httpClient.fetch(url, {\n        headers,\n        timeoutMs: config.fastTimeoutMs,\n        conditionalHeaders,\n      });\n      this.ensureStats(domain);\n      const raw = this.toRawFetchResult(result);\n      // Don't probe content of a 304 — body is empty by spec, not a SPA shell.\n      raw.jsRequired = result.statusCode === 304 ? false : contentAppearsEmpty(result.html);\n      return raw;\n    }\n\n    // Actions always force Playwright --- actions need a live browser page\n    if (actions && actions.length > 0) {\n      if (!this.browserPool) throw new Error('SmartRouter: browserPool not configured');\n      const authOptions = useAuth ? (await getAuthOptions() ?? {}) : {};\n      logger.debug('routing to playwright', { url, reason: 'actions present' });\n      return this.browserPool.fetchWithBrowser(url, { headers, screenshot, actions, ...authOptions });\n    }\n\n    // Always Playwright for auth or explicit override\n    if (renderJs === 'always' || useAuth) {\n      if (!this.browserPool) throw new Error('SmartRouter: browserPool not configured');\n      const authOptions = useAuth ? (await getAuthOptions() ?? {}) : {};\n      logger.debug('routing to playwright', { url, reason: useAuth ? 'auth' : 'render_js=always' });\n      return this.browserPool.fetchWithBrowser(url, { headers, screenshot, ...authOptions });\n    }\n\n    // HTTP only, no fallback\n    if (renderJs === 'never') {\n      if (!this.httpClient) throw new Error('SmartRouter: httpClient not configured');\n      logger.debug('routing to http (never)', { url });\n      const result = await this.httpClient.fetch(url, { headers, conditionalHeaders });\n      this.ensureStats(domain);\n      return this.toRawFetchResult(result);\n    }\n\n    // auto: check if domain is already marked for Playwright\n    const stats = this.ensureStats(domain);\n\n    if (stats.preferPlaywright) {\n      if (!this.browserPool) throw new Error('SmartRouter: browserPool not configured');\n      logger.debug('routing to playwright (domain marked)', { url, domain });\n      return this.browserPool.fetchWithBrowser(url, { headers, screenshot });\n    }\n\n    // Try HTTP first\n    try {\n      if (!this.httpClient) throw new Error('SmartRouter: httpClient not configured');\n      const result = await this.httpClient.fetch(url, { headers, conditionalHeaders });\n\n      // 304 = unchanged: pass through; never escalate to a browser.\n      if (result.statusCode === 304) {\n        return this.toRawFetchResult(result);\n      }\n\n      // Check for SPA shell / empty content\n      if (contentAppearsEmpty(result.html)) {\n        if (!this.browserPool) throw new Error('SmartRouter: browserPool not configured');\n        logger.info('SPA shell detected, marking domain for playwright', { url, domain });\n        stats.preferPlaywright = true;\n        return this.browserPool.fetchWithBrowser(url, { headers, screenshot });\n      }\n\n      return this.toRawFetchResult(result);\n    } catch (err) {\n      stats.failureCount++;\n      logger.warn('http fetch failed', {\n        url,\n        domain,\n        failureCount: stats.failureCount,\n        error: err instanceof Error ? err.message : String(err),\n      });\n\n      if (stats.failureCount >= threshold) {\n        if (!this.browserPool) throw new Error('SmartRouter: browserPool not configured');\n        logger.info('failure threshold reached, marking domain for playwright', { url, domain, threshold });\n        stats.preferPlaywright = true;\n        return this.browserPool.fetchWithBrowser(url, { headers, screenshot });\n      }\n\n      throw err;\n    }\n  }\n\n  getDomainStats(domain: string): DomainStats | undefined {\n    return this.domainMap.get(domain);\n  }\n\n  private ensureStats(domain: string): DomainStats {\n    let stats = this.domainMap.get(domain);\n    if (!stats) {\n      stats = { failureCount: 0, preferPlaywright: false };\n      this.domainMap.set(domain, stats);\n    }\n    return stats;\n  }\n\n  private toRawFetchResult(\n    result: Awaited<ReturnType<HttpClient['fetch']>>,\n  ): RawFetchResult {\n    return {\n      url: result.url,\n      finalUrl: result.finalUrl,\n      html: result.html,\n      contentType: result.contentType,\n      statusCode: result.statusCode,\n      method: 'http',\n      headers: result.headers,\n      rawBuffer: result.rawBuffer,\n    };\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.js

@@ -1,22 +1,102 @@
 #!/usr/bin/env node
-import { parseCommand } from './cli/index.js';
-import { runWarmup } from './cli/warmup.js';
-import { runDaemon } from './cli/daemon.js';
-import { runHealthCheck } from './cli/health.js';
-import { startServer } from './server.js';
+import { parseCommand } from "./cli/index.js";
+import { runWarmup } from "./cli/warmup.js";
+import { runDaemon } from "./cli/daemon.js";
+import { runHealthCheck } from "./cli/health.js";
+import { runDoctor } from "./cli/doctor.js";
+import { runShell } from "./cli/shell.js";
+import { runAuth } from "./cli/auth.js";
+import { runPluginCommand } from "./cli/plugin.js";
+import { runInit } from "./cli/init.js";
+import { runUninstall } from "./cli/uninstall.js";
+import { runSetupMcp } from "./cli/setup-mcp.js";
+import { runStatus } from "./cli/status.js";
+import { runBackfill } from "./cli/backfill.js";
+import { printHelp, printVersion, printUnknownCommand } from "./cli/help.js";
+import { getConfig } from "./config.js";
+import { startServer } from "./server.js";
 const { command, args } = parseCommand(process.argv.slice(2));
 switch (command) {
-    case 'warmup':
-        await runWarmup(args);
-        break;
-    case 'serve':
-        runDaemon(args);
-        break;
-    case 'health':
-        runHealthCheck();
-        break;
-    case 'mcp':
-        await startServer();
-        break;
+  case "warmup":
+    await runWarmup(args);
+    process.exit(0);
+    break;
+  case "serve":
+    runDaemon(args);
+    break;
+  case "health": {
+    const exitCode = await runHealthCheck();
+    process.exit(exitCode);
+    break;
+  }
+  case "doctor": {
+    const code = await runDoctor(getConfig().dataDir);
+    process.exit(code);
+    break;
+  }
+  case "auth": {
+    const authCode = await runAuth(args);
+    process.exit(authCode);
+    break;
+  }
+  case "shell":
+    await runShell(args);
+    break;
+  case "plugin":
+    runPluginCommand(args);
+    break;
+  case "init": {
+    const initCode = await runInit(args);
+    process.exit(initCode);
+    break;
+  }
+  case "uninstall": {
+    const uninstallCode = await runUninstall(args);
+    process.exit(uninstallCode);
+    break;
+  }
+  case "setup": {
+    const code = await runSetupMcp(args);
+    process.exit(code);
+    break;
+  }
+  case "status": {
+    const code = await runStatus(args);
+    process.exit(code);
+    break;
+  }
+  case "backfill": {
+    const code = await runBackfill(args);
+    process.exit(code);
+    break;
+  }
+  case "help":
+    printHelp();
+    process.exit(0);
+    break;
+  case "version":
+    printVersion();
+    process.exit(0);
+    break;
+  case "unknown":
+    printUnknownCommand(args[0] ?? "");
+    process.exit(1);
+    break;
+  case "mcp": {
+    const config = getConfig();
+    try {
+      const { tryConnectDaemon } = await import("./daemon/proxy.js");
+      const report = await tryConnectDaemon(config.daemonPort, config.daemonHost);
+      if (report) {
+        process.stderr.write(
+          `[wigolo] Daemon detected at ${config.daemonHost}:${config.daemonPort} (status: ${report.status}). Full proxy deferred to v2.1; starting local server.
+`
+        );
+      }
+    } catch {
+    }
+    await startServer();
+    break;
+  }
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9D,QAAQ,OAAO,EAAE,CAAC;IAChB,KAAK,QAAQ;QACX,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;QACtB,MAAM;IAER,KAAK,OAAO;QACV,SAAS,CAAC,IAAI,CAAC,CAAC;QAChB,MAAM;IAER,KAAK,QAAQ;QACX,cAAc,EAAE,CAAC;QACjB,MAAM;IAER,KAAK,KAAK;QACR,MAAM,WAAW,EAAE,CAAC;QACpB,MAAM;AACV,CAAC"}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { parseCommand } from './cli/index.js';\nimport { runWarmup } from './cli/warmup.js';\nimport { runDaemon } from './cli/daemon.js';\nimport { runHealthCheck } from './cli/health.js';\nimport { runDoctor } from './cli/doctor.js';\nimport { runShell } from './cli/shell.js';\nimport { runAuth } from './cli/auth.js';\nimport { runPluginCommand } from './cli/plugin.js';\nimport { runInit } from './cli/init.js';\nimport { runUninstall } from './cli/uninstall.js';\nimport { runSetupMcp } from './cli/setup-mcp.js';\nimport { runStatus } from './cli/status.js';\nimport { runBackfill } from './cli/backfill.js';\nimport { printHelp, printVersion, printUnknownCommand } from './cli/help.js';\nimport { getConfig } from './config.js';\nimport { startServer } from './server.js';\n\nconst { command, args } = parseCommand(process.argv.slice(2));\n\nswitch (command) {\n  case 'warmup':\n    await runWarmup(args);\n    // Explicit exit for clean teardown — ensures all child subprocesses\n    // (reranker, embedding) are reaped before Node returns.\n    process.exit(0);\n    break;\n\n  case 'serve':\n    runDaemon(args);\n    break;\n\n  case 'health': {\n    const exitCode = await runHealthCheck();\n    process.exit(exitCode);\n    break;\n  }\n\n  case 'doctor': {\n    const code = await runDoctor(getConfig().dataDir);\n    process.exit(code);\n    break;\n  }\n\n  case 'auth': {\n    const authCode = await runAuth(args);\n    process.exit(authCode);\n    break;\n  }\n\n  case 'shell':\n    await runShell(args);\n    break;\n\n  case 'plugin':\n    runPluginCommand(args);\n    break;\n\n  case 'init': {\n    const initCode = await runInit(args);\n    process.exit(initCode);\n    break;\n  }\n\n  case 'uninstall': {\n    const uninstallCode = await runUninstall(args);\n    process.exit(uninstallCode);\n    break;\n  }\n\n  case 'setup': {\n    const code = await runSetupMcp(args);\n    process.exit(code);\n    break;\n  }\n\n  case 'status': {\n    const code = await runStatus(args);\n    process.exit(code);\n    break;\n  }\n\n  case 'backfill': {\n    const code = await runBackfill(args);\n    process.exit(code);\n    break;\n  }\n\n  case 'help':\n    printHelp();\n    process.exit(0);\n    break;\n\n  case 'version':\n    printVersion();\n    process.exit(0);\n    break;\n\n  case 'unknown':\n    printUnknownCommand(args[0] ?? '');\n    process.exit(1);\n    break;\n\n  case 'mcp': {\n    const config = getConfig();\n\n    try {\n      const { tryConnectDaemon } = await import('./daemon/proxy.js');\n      const report = await tryConnectDaemon(config.daemonPort, config.daemonHost);\n      if (report) {\n        process.stderr.write(\n          `[wigolo] Daemon detected at ${config.daemonHost}:${config.daemonPort} ` +\n          `(status: ${report.status}). Full proxy deferred to v2.1; starting local server.\\n`,\n        );\n      }\n    } catch {\n      // Daemon proxy module may not be available -- fall through to local server\n    }\n\n    await startServer();\n    break;\n  }\n}\n"],"mappings":";AAEA,SAAS,oBAAoB;AAC7B,SAAS,iBAAiB;AAC1B,SAAS,iBAAiB;AAC1B,SAAS,sBAAsB;AAC/B,SAAS,iBAAiB;AAC1B,SAAS,gBAAgB;AACzB,SAAS,eAAe;AACxB,SAAS,wBAAwB;AACjC,SAAS,eAAe;AACxB,SAAS,oBAAoB;AAC7B,SAAS,mBAAmB;AAC5B,SAAS,iBAAiB;AAC1B,SAAS,mBAAmB;AAC5B,SAAS,WAAW,cAAc,2BAA2B;AAC7D,SAAS,iBAAiB;AAC1B,SAAS,mBAAmB;AAE5B,MAAM,EAAE,SAAS,KAAK,IAAI,aAAa,QAAQ,KAAK,MAAM,CAAC,CAAC;AAE5D,QAAQ,SAAS;AAAA,EACf,KAAK;AACH,UAAM,UAAU,IAAI;AAGpB,YAAQ,KAAK,CAAC;AACd;AAAA,EAEF,KAAK;AACH,cAAU,IAAI;AACd;AAAA,EAEF,KAAK,UAAU;AACb,UAAM,WAAW,MAAM,eAAe;AACtC,YAAQ,KAAK,QAAQ;AACrB;AAAA,EACF;AAAA,EAEA,KAAK,UAAU;AACb,UAAM,OAAO,MAAM,UAAU,UAAU,EAAE,OAAO;AAChD,YAAQ,KAAK,IAAI;AACjB;AAAA,EACF;AAAA,EAEA,KAAK,QAAQ;AACX,UAAM,WAAW,MAAM,QAAQ,IAAI;AACnC,YAAQ,KAAK,QAAQ;AACrB;AAAA,EACF;AAAA,EAEA,KAAK;AACH,UAAM,SAAS,IAAI;AACnB;AAAA,EAEF,KAAK;AACH,qBAAiB,IAAI;AACrB;AAAA,EAEF,KAAK,QAAQ;AACX,UAAM,WAAW,MAAM,QAAQ,IAAI;AACnC,YAAQ,KAAK,QAAQ;AACrB;AAAA,EACF;AAAA,EAEA,KAAK,aAAa;AAChB,UAAM,gBAAgB,MAAM,aAAa,IAAI;AAC7C,YAAQ,KAAK,aAAa;AAC1B;AAAA,EACF;AAAA,EAEA,KAAK,SAAS;AACZ,UAAM,OAAO,MAAM,YAAY,IAAI;AACnC,YAAQ,KAAK,IAAI;AACjB;AAAA,EACF;AAAA,EAEA,KAAK,UAAU;AACb,UAAM,OAAO,MAAM,UAAU,IAAI;AACjC,YAAQ,KAAK,IAAI;AACjB;AAAA,EACF;AAAA,EAEA,KAAK,YAAY;AACf,UAAM,OAAO,MAAM,YAAY,IAAI;AACnC,YAAQ,KAAK,IAAI;AACjB;AAAA,EACF;AAAA,EAEA,KAAK;AACH,cAAU;AACV,YAAQ,KAAK,CAAC;AACd;AAAA,EAEF,KAAK;AACH,iBAAa;AACb,YAAQ,KAAK,CAAC;AACd;AAAA,EAEF,KAAK;AACH,wBAAoB,KAAK,CAAC,KAAK,EAAE;AACjC,YAAQ,KAAK,CAAC;AACd;AAAA,EAEF,KAAK,OAAO;AACV,UAAM,SAAS,UAAU;AAEzB,QAAI;AACF,YAAM,EAAE,iBAAiB,IAAI,MAAM,OAAO,mBAAmB;AAC7D,YAAM,SAAS,MAAM,iBAAiB,OAAO,YAAY,OAAO,UAAU;AAC1E,UAAI,QAAQ;AACV,gBAAQ,OAAO;AAAA,UACb,+BAA+B,OAAO,UAAU,IAAI,OAAO,UAAU,aACzD,OAAO,MAAM;AAAA;AAAA,QAC3B;AAAA,MACF;AAAA,IACF,QAAQ;AAAA,IAER;AAEA,UAAM,YAAY;AAClB;AAAA,EACF;AACF;","names":[]}

package/dist/instructions.d.ts

@@ -0,0 +1,31 @@
+/**
+ * LLM knowledge layer for wigolo.
+ *
+ * Two layers. They do different jobs and must not repeat each other:
+ *
+ *   Layer 1 — WIGOLO_INSTRUCTIONS: server-level STRATEGY. Injected into the
+ *   LLM system prompt once per session by compatible MCP clients. Answers
+ *   "when do I reach for wigolo? which of its tools fits this situation?".
+ *
+ *   Layer 2 — TOOL_DESCRIPTIONS: per-tool TACTICS. Seen every time the LLM is
+ *   picking a tool. Answers "what does this tool do, which parameters matter,
+ *   what does the output look like?".
+ *
+ * Parameter schemas (types, enums, required/optional) belong on the JSON
+ * Schema, not here. Installation/configuration is for humans, not LLMs.
+ */
+export declare const WIGOLO_INSTRUCTIONS = "Wigolo is a local-first web access layer: search, fetch, crawl, cache, extract, find_similar, research, agent. Results persist in a local knowledge cache across sessions.\n\n## Host-LLM synthesis (read this first)\n\nWigolo returns *structured evidence* \u2014 YOU write the final answer.\n\n- `search` \u2192 evidence (title/url/excerpt/score/citation_id/source_span) + citations. Quote [N] or {citation_id}.\n- `format: 'answer'|'stream_answer'` \u2192 LLM synthesis when sampling supported; else evidence fallback.\n- `research` \u2192 `brief` with topics/highlights/key_findings/sections; use `sections.overview.cross_references` for corroborated findings, `sections.gaps` for coverage limits.\n- `find_similar` \u2192 `cold_start` string when local signals weak. Pass to user verbatim.\n- `extract mode: \"structured\"` \u2192 tables + definitions + jsonld + chart_hints + key_value_pairs in one call.\n- Common knobs: `max_tokens_out` caps output (cl100k-base); `include_full_markdown: true` restores full body; `citation_format`: `'numbered'`|`'json'`|`'anthropic_tags'`.\n\n## When to use which tool\n\n- `search` \u2014 info on a topic, no URL yet. Pass a string or array of 3-5 keyword variants for breadth.\n- `fetch` \u2014 you already have a URL.\n- `crawl` \u2014 many pages from one site (docs, wikis). `strategy: \"sitemap\"` is fastest for doc sites; `\"map\"` for URL-only discovery.\n- `cache` \u2014 check the local store before going to the network.\n- `extract` \u2014 specific data points (tables, metadata, schema-shaped fields) rather than a whole page.\n- `find_similar` \u2014 \"more like this\" given a URL or concept.\n- `research` \u2014 multi-step investigation: decomposition, parallel search, synthesis. Set `depth` to control thoroughness.\n- `agent` \u2014 natural-language data gathering across sources, optional `schema` for structured output.\n\n## Scope and freshness\n\n- Library/framework/SDK queries: **always pass `include_domains`** with the official site (e.g. `[\"react.dev\", \"nextjs.org\"]`). Unscoped queries return noise. Skip scoping for error strings, news, and broad exploration.\n- News, prices, status, release notes \u2192 `force_refresh: true` to bypass cache. Docs and reference pages \u2192 let the cache work.\n\nFor routing tables, performance budgets, auth flows, and other usage detail, read the resource `wigolo://docs/usage`.";
+export declare const WIGOLO_INSTRUCTIONS_FULL = "# Wigolo Usage Guide\n\nWigolo is a local-first web access layer: search the open web, fetch pages, crawl sites, extract structured data, find related content, run multi-step research, and execute agent-driven data gathering. All results land in a local knowledge cache that persists across sessions.\n\n## Host-LLM synthesis pattern (read this first)\n\nWigolo has no internal LLM. It returns *structured evidence* so YOU (the host LLM) write the final answer. Fold structure into your reply:\n\n- `search` \u2192 evidence (title/url/section_heading/excerpt/score/citation_id/source_span) + citations. Quote [N] or {citation_id}.\n- `format: 'answer'|'stream_answer'` \u2192 LLM synthesis when sampling supported; else evidence fallback.\n- `max_tokens_out` caps total output (cl100k-base, ~5-15% drift on non-OpenAI). `include_full_markdown: true` restores full body. `citation_format`: `'numbered'`|`'json'`|`'anthropic_tags'`.\n- `research` \u2192 `brief` with `topics`, `highlights`, `key_findings`, `sections` when sampling unavailable. Use `sections.overview.cross_references` for corroborated findings, `sections.gaps` for coverage limits, `sections.comparison` for entity-vs-entity analysis. `query_type` indicates decomposition strategy used.\n- `find_similar` \u2192 `cold_start` string when local signals are weak. Pass to user verbatim.\n- `extract` `mode: \"structured\"` \u2192 tables + definitions + jsonld + chart_hints + key_value_pairs in one call.\n- `fetch` metadata \u2192 `og_type`, `canonical_url`, `og_image` when present.\n\n## When to use which tool\n\n- `search` -- you need information on a topic but do not have a URL yet. Pass a query string or an array of 3-5 semantically varied keyword forms for broader coverage.\n- `fetch` -- you already have a specific URL to read.\n- `crawl` -- you need multiple pages from the same site (docs, wikis, references).\n- `cache` -- you want to know if the content is already on disk from an earlier read.\n- `extract` -- you need specific data points (tables, metadata, schema-shaped fields) rather than a whole page as markdown.\n- `find_similar` -- you have a URL or concept and want related content from the cache or web. Useful for \"more like this\" discovery.\n- `research` -- you have a complex question that needs multi-step investigation: question decomposition, parallel search, source synthesis into a report. Set `depth` to control thoroughness.\n- `agent` -- you need to gather structured or unstructured data from multiple sources based on a natural-language prompt. Provides full step transparency.\n\n## Routing by intent\n\n| Intent | Tool | Key parameters |\n|--------|------|----------------|\n| Documentation lookup | `search` | `include_domains: [\"react.dev\", \"nextjs.org\"]` -- scope to the project's official site, do not rely on `category: \"docs\"` alone |\n| Error debugging | `search` | exact error string as query, `category: \"code\"` (no domain scoping -- errors appear everywhere) |\n| Library research | `crawl` | seed URL of docs site, `strategy: \"sitemap\"`, then `cache` for later queries |\n| Related content | `find_similar` | `url` of a known good page, or `concept` as free text |\n| Evidence excerpt | `search` | default output; cite [N] or {citation_id} from each evidence item |\n| Direct answer | `search` | `format: \"answer\"` if client supports sampling, else falls back to evidence |\n| Comprehensive research | `research` | `depth: \"comprehensive\"`, optional `include_domains` to scope |\n| Data gathering | `agent` | natural-language `prompt`, optional `schema` for structured output |\n| Structured extraction | `extract` | `mode: \"structured\"` (tables + dl + JSON-LD + chart hints + kv pairs), or `mode: \"schema\"` with a JSON Schema |\n| Site inventory | `crawl` | `strategy: \"map\"` for URL-only discovery, no content fetched |\n\n## Rapidly changing content\n\nFor news, prices, status pages, or release notes, bypass the cache with `force_refresh: true`:\n\n  search({ query: \"...\", force_refresh: true })\n  fetch({ url: \"...\", force_refresh: true })\n\nFor docs, tutorials, and reference pages, let the cache work -- much faster.\n\n## Check the cache before going to the network\n\nBefore every `search` or `fetch`, consider a `cache` call. Pages read this session or earlier return instantly with full markdown -- no network. `research` and `agent` check the cache internally.\n\n## Multi-query search strategy\n\nFor broad queries, pass an array of 3-5 semantically varied keyword forms rather than one natural-language question. Example: instead of \"how does React handle state management\", pass `[\"react state management\", \"useState useReducer\", \"react hooks state\", \"react context vs redux\"]`. Sub-queries are deduplicated automatically.\n\n## Pick the right strategy\n\n- For docs sites, prefer `crawl` with `strategy: \"sitemap\"` -- faster and more complete than BFS.\n- For URL discovery only, use `crawl` with `strategy: \"map\"` -- URLs only, no content. Follow with targeted `fetch` calls.\n- For structured data (prices, specs, table rows), use `extract` with `mode: \"schema\"` or `mode: \"tables\"`. Use `fetch` only when you want the whole page as markdown.\n- For multi-source synthesis, use `research` instead of chaining `search` + `fetch` manually.\n- For natural-language data gathering, use `agent` with optional `schema`.\n- `crawl` accepts regex `include_patterns` and `exclude_patterns` to stay inside a section of a large site.\n\n## Scope searches by domain\n\nFor library/framework/SDK queries, **always pass `include_domains`** with official sites. Unscoped queries return generic noise. `category: \"docs\"` alone returns generic portals -- pair with `include_domains` or omit. Skip domain scoping for error strings, broad exploration, and news.\n\n## Performance\n\n- `max_results: 3` for focused lookups; `5` default; `10+` only for broad research.\n- `max_tokens_out` caps total response size (cl100k-base BPE); prefer this over `max_chars` for budget-aware agents. When both are set, `max_tokens_out` wins.\n- `max_content_chars: 3000` remains a legitimate per-page budget \u2014 smart-truncates each result's markdown at a paragraph/heading boundary with a `[... content truncated]` marker.\n- `fetch` with `section: \"Heading Name\"` returns content under that heading -- cheaper than the whole page.\n- Repeated fetches of the same URL are free (local cache).\n- `research` with `depth: \"quick\"` (~15s) suits most factual questions; reserve `\"comprehensive\"` for deep investigation.\n- `agent` respects `max_pages` (default 10) and `max_time_ms` (default 60s).\n\n## Extras\n\n- Localhost URLs (`localhost:3000`, `127.0.0.1:8080`) work for local dev servers.\n- `use_auth: true` on `fetch`/`crawl` reuses browser session for logged-in pages.\n- `cache` supports full-text search syntax (`AND`, `OR`, `NOT`, `\"phrase\"`).\n- `research`/`agent` use MCP sampling when supported; fall back to structured data for host-LLM synthesis.";
+export declare const WIGOLO_DOCS_URI = "wigolo://docs/usage";
+export declare const TOOL_DESCRIPTIONS: {
+    readonly fetch: "Fetch a single URL and return clean markdown. Use when you have a specific URL to read. Automatically detects if JavaScript rendering is needed.\n\nKey parameters:\n- section: extract content under a specific heading (e.g., section: \"API Reference\") -- faster than reading the whole page\n- max_content_chars: smart-truncate markdown at a paragraph/heading boundary with a `[... content truncated]` marker (e.g., 3000 for compact context). Preferred over max_chars for AI agents.\n- max_tokens_out: token-budget cap on total output (cl100k-base BPE). Takes precedence over max_chars when both are set.\n- include_full_markdown: default false. Set true to include the full markdown body in addition to evidence excerpts.\n- citation_format: 'numbered' (default) | 'json' | 'anthropic_tags'.\n- use_auth: true to use stored browser session for authenticated/private pages\n- render_js: \"auto\" (default, detects JS need), \"always\" (force browser), \"never\" (HTTP only, fastest)\n- headers: custom HTTP headers if needed\n- force_refresh: true to bypass cache and fetch fresh content from the network\n- mode: 'cache' | 'default' (default) | 'stealth'. cache=HTTP-only, accepts stale cache up to 24h. stealth=full browser render + freshness.\n\nReturns title, markdown, links, images, metadata (og_image, og_type, canonical_url, keywords). Cached locally; repeat fetches are instant. Localhost URLs work.";
+    readonly search: "Search the web and return scored evidence excerpts (title/url/section_heading/excerpt/score/citation_id/source_span) plus citations. Default shape is evidence-only — no full markdown body.\n\nKey parameters:\n- query: string or string[] array (3-5 keyword variants; deduplicated automatically)\n- include_domains/exclude_domains: scope to specific sites. ALWAYS scope library/framework queries.\n- category: \"general\" | \"news\" | \"code\" | \"docs\" | \"papers\" — coarse filter, pair with include_domains.\n- from_date/to_date: ISO YYYY-MM-DD for time-bounded queries\n- max_results: default 5; use 3 for focused, 10+ for research\n- format: omit for default evidence shape. 'answer'/'stream_answer' = sampling synthesis (falls back to evidence). Retired values 'full'/'context'/'highlights' reject with a migration error.\n- max_tokens_out: token-budget cap on total output (cl100k-base; wins over max_chars).\n- include_full_markdown: true to restore full markdown body alongside evidence (default false).\n- citation_format: 'numbered' (default) | 'json' | 'anthropic_tags'.\n- max_content_chars: smart-truncate per-page markdown at paragraph boundary (e.g., 3000)\n- force_refresh: true to bypass all caches\n- mode: 'cache' | 'default' (default) | 'stealth'. cache=single-engine, no rerank, 24h-stale cache. stealth=multi-query expansion + full-body top-K.\n\nQuote [N] or {citation_id} from the evidence list.";
+    readonly crawl: "Crawl a website starting from a URL and return content from multiple pages. Use for indexing documentation sites, wikis, or any multi-page resource.\n\nKey parameters:\n- strategy: \"bfs\" (breadth-first, default), \"dfs\" (depth-first), \"sitemap\" (use sitemap.xml -- fastest for doc sites), \"map\" (URL discovery only, no content -- fastest for scoping a site)\n- max_depth: how many links deep to follow (default 2)\n- max_pages: maximum pages to fetch (default 20)\n- include_patterns/exclude_patterns: regex filters on URLs\n- max_tokens_out: token-budget cap on total output (cl100k-base; wins over max_chars).\n- include_full_markdown: default false — pages return evidence excerpts; set true for full bodies.\n- citation_format: 'numbered' (default) | 'json' | 'anthropic_tags'.\n\nReturns an array of pages with title, evidence, and depth. Content is deduplicated across pages. All pages are cached for later cache queries.";
+    readonly cache: "Search previously fetched content without hitting the network. Use before searching the web -- if relevant content was already fetched or crawled, this returns it instantly.\n\nKey parameters:\n- query: full-text search over cached markdown and titles (supports AND, OR, NOT, \"phrase match\")\n- url_pattern: glob filter on URLs (e.g., \"*example.com*\")\n- since: ISO date -- only results cached after this date\n- stats: true to get cache size, entry count, oldest/newest dates\n- clear: true to delete matching entries\n\nReturns matching cached pages with full markdown content. Cache persists across sessions locally.";
+    readonly extract: "Extract structured data from a URL or raw HTML. Use when you need specific data points, tables, or metadata rather than full page markdown.\n\nKey parameters:\n- mode: \"selector\" (CSS selector -> text), \"tables\" (HTML tables only), \"metadata\" (title/author/date/description/og_* + JSON-LD), \"schema\" (JSON Schema -> heuristic field extraction), \"structured\" (ONE-SHOT: tables + <dl> definitions + JSON-LD + chart hints from SVG/figure + microdata/data-attr/grid key-value pairs)\n- css_selector: required for mode=\"selector\" -- any valid CSS selector\n- schema: for mode=\"schema\", a JSON Schema object describing the fields to extract\n- multiple: true to return array of all matches (mode=\"selector\" only)\n\nPrefer mode=\"structured\" over chaining multiple extract calls — it returns every structured pattern on the page in one response:\n  { tables, definitions, jsonld, chart_hints, key_value_pairs }\n\nchart_hints surfaces SVG titles, aria-labels, and figcaptions — host LLMs use these to describe data visualizations even when the underlying data is rendered by JavaScript.\n\nFor mode=\"tables\", returns array of table objects with headers and row data. For mode=\"schema\", pass { price: \"string\", name: \"string\" } and get structured fields extracted from the page.";
+    readonly find_similar: "Find content related to a URL or concept. Use when you have a known-good page or topic and want to discover similar resources from the cache or web.\n\nKey parameters:\n- url: a URL to find content similar to. The page's content and embeddings are used for similarity matching.\n- concept: free-text description of what you want similar content for. Use when you do not have a specific URL.\n- max_results: number of similar items to return (default 5)\n- include_cached: true (default) to search the local cache first, false to skip cache and search the web only\n- threshold: minimum similarity score (0-1, default 0.5)\n- max_tokens_out: token-budget cap on total output (cl100k-base; wins over max_chars).\n- include_full_markdown: default false — results return evidence excerpts; set true for full bodies.\n- citation_format: 'numbered' (default) | 'json' | 'anthropic_tags'.\n\nProvide either url or concept. Results fuse three signals via 3-way RRF: keyword match, semantic embeddings, and (if local hits sparse) live web search. Each result carries `match_signals` with `embedding_rank`, `fts5_rank`, and `fused_score`.\n\nThe response may include a `cold_start` string when local signals are weak. Pass this verbatim to the user.\n\nReturns results array, method used (\"hybrid\" | \"embedding\" | \"fts5\" | \"search\"), cache_hits, search_hits, embedding_available, and total_time_ms.";
+    readonly research: "Run multi-step research on a complex question. Decomposes the question into sub-queries, searches in parallel, fetches top sources, and synthesizes a report with citations.\n\nKey parameters:\n- question: the research question to investigate\n- depth: \"quick\" (~15s, 2 sub-queries, 5-8 sources), \"standard\" (~40s, 4 sub-queries, 10-15 sources, default), \"comprehensive\" (~80s, 7 sub-queries, 20-25 sources)\n- max_sources: override the default source count for the chosen depth\n- include_domains/exclude_domains: scope research to specific sites\n- schema: optional JSON Schema -- structures the report to extract matching fields\n- stream: true to receive progress notifications as each phase completes\n- max_tokens_out: token-budget cap on total output (cl100k-base; wins over max_chars).\n- include_full_markdown: default false — sources return evidence excerpts; set true for full bodies.\n- citation_format: 'numbered' (default) | 'json' | 'anthropic_tags'.\n\nReturns report (markdown with [N] citations), citations array, sources, sub_queries, depth, total_time_ms, sampling_supported, and brief (topics, highlights, key_findings, sections.overview/comparison/gaps).";
+    readonly agent: "Execute a natural-language data gathering task. Plans search queries and URLs from a prompt, executes them in parallel, and synthesizes results. Full step transparency.\n\nKey parameters:\n- prompt: natural-language description of what data to gather (e.g., \"find pricing for the top 5 CRM tools\")\n- urls: optional array of specific URLs to include in the gathering\n- schema: optional JSON Schema -- if provided, extracts structured data matching the schema from each page and merges results\n- max_pages: maximum pages to fetch (default 10)\n- max_time_ms: maximum execution time in milliseconds (default 60000)\n- stream: true to receive progress notifications as each step completes\n- max_tokens_out: token-budget cap on total output (cl100k-base; wins over max_chars).\n- include_full_markdown: default false — pages return evidence excerpts; set true for full bodies.\n- citation_format: 'numbered' (default) | 'json' | 'anthropic_tags'.\n\nPipeline: (1) plan, (2) execute search+fetch in parallel within budget, (3) optional schema extraction, (4) synthesize. The steps array exposes every action with timing.\n\nUses MCP requestSampling for planning and synthesis. Without sampling support, uses keyword extraction.\n\nReturns result, sources array, pages_fetched count, steps array, total_time_ms, sampling_supported.";
+};
+export type ToolName = keyof typeof TOOL_DESCRIPTIONS;
+//# sourceMappingURL=instructions.d.ts.map

package/dist/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,eAAO,MAAM,mBAAmB,41EA6BwF,CAAC;AAIzH,eAAO,MAAM,wBAAwB,k3NAuF0E,CAAC;AAEhH,eAAO,MAAM,eAAe,wBAAwB,CAAC;AAErD,eAAO,MAAM,iBAAiB;;;;;;;;;CA6HpB,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,iBAAiB,CAAC"}