rterm-backend 3.0.8 → 3.0.9

package/bin/gybackend.cjs

@@ -369400,6 +369400,12 @@ var DEFAULT_BACKEND_SETTINGS = {
     serverUrl: "",
     enabled: true
   },
+  webIntel: {
+    restUrl: "",
+    enabled: true,
+    autoStart: true,
+    warmupOnInit: false
+  },
   gateway: {
     ws: {
       access: "localhost",
@@ -369456,6 +369462,7 @@ function pickBackendSnapshot(raw) {
     oncall: raw.oncall,
     cloud: raw.cloud,
     agentspan: raw.agentspan,
+    webIntel: raw.webIntel,
     gateway: raw.gateway,
     layout: raw.layout,
     recursionLimit: raw.recursionLimit,
@@ -369535,6 +369542,7 @@ function normalizeBackendSettings(settings) {
   next.oncall = normalizeOncallSettings(next.oncall);
   next.cloud = normalizeCloudSettings(next.cloud);
   next.agentspan = normalizeAgentspanSettings(next.agentspan);
+  next.webIntel = normalizeWebIntelSettings(next.webIntel);
   next.schemaVersion = BACKEND_SETTINGS_SCHEMA_VERSION;
   return next;
 }
@@ -369707,6 +369715,18 @@ function normalizeAgentspanSettings(raw) {
     enabled: src.enabled !== false
   };
 }
+function normalizeWebIntelSettings(raw) {
+  const src = isObject5(raw) ? raw : {};
+  const restUrl = typeof src.restUrl === "string" ? src.restUrl.trim() : "";
+  const token = typeof src.token === "string" && src.token.trim() ? src.token.trim() : void 0;
+  return {
+    ...restUrl ? { restUrl } : {},
+    ...token ? { token } : {},
+    enabled: src.enabled !== false,
+    autoStart: src.autoStart !== false,
+    warmupOnInit: src.warmupOnInit === true
+  };
+}
 function migrateBackendToV3(settings) {
   const next = { ...settings };
   delete next.language;
@@ -383902,7 +383922,7 @@ var PluginRegistry = class {
   }
   /** Build the default PluginContext for a record (registers into the record's
    * capability lists; exec/readLedger/log are delegated to the injected fns). */
-  static defaultContext(record2, exec, readLedger, log) {
+  static defaultContext(record2, exec, readLedger, log, spawnProcess, getSettings) {
     return {
       registerTool: (tool2) => {
         record2.tools.push(tool2);
@@ -383910,12 +383930,20 @@ var PluginRegistry = class {
       registerTrigger: (trigger) => {
         record2.triggers.push(trigger);
       },
-      registerPanel: (name, render3) => {
-        record2.panels.push({ name, render: render3 });
+      registerPanel: (nameOrDef, render3) => {
+        if (typeof nameOrDef === "string") {
+          if (typeof render3 === "function") record2.panels.push({ name: nameOrDef, render: render3 });
+        } else if (nameOrDef && typeof nameOrDef === "object" && typeof nameOrDef.render === "function") {
+          record2.panels.push({ name: nameOrDef.name, render: nameOrDef.render });
+        }
       },
       exec,
       readLedger,
-      log
+      log,
+      ...spawnProcess ? { spawnProcess } : {},
+      ...getSettings ? { getSettings, get settings() {
+        return getSettings();
+      } } : {}
     };
   }
 };
@@ -386407,7 +386435,19 @@ function createObservability(deps) {
           deps.onLog?.(line);
         } catch {
         }
-      }
+      },
+      // Real child_process spawn for sidecar daemons (web-intel's wigolo serve).
+      (command, args, opts) => {
+        const req = (0, import_node_module5.createRequire)(typeof __filename !== "undefined" ? __filename : import_meta7.url);
+        const cp = req("node:child_process");
+        return cp.spawn(command, args, {
+          env: opts?.env,
+          detached: opts?.detached ?? false,
+          stdio: opts?.stdio ?? "ignore"
+        });
+      },
+      // Live settings snapshot for plugins that read config blocks (webIntel, agentspan, …).
+      () => deps.settingsService?.getSettings?.() ?? {}
     ),
     onLog: deps.onLog
   });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rterm-backend",
-  "version": "3.0.8",
-  "description": "rterm-backend — the headless AI-native backend for RTerm (dual-published as neuralOS). run RTerm-as-a-service (AI agent, SSH/WinRM/Serial/local terminals, fleet orchestration, advanced automation, SRE observability, Netdata, AWS APerf, plugin system, governance/audit, Prometheus/OTel metrics export, secrets vault, on-call paging, AI cost budgets, GitOps, cloud inventory, APM/DEM/Infra/ETW ingestion, AgentSpan durable-agent bridge). The RTerm desktop app stays RTerm; neuralOS is the standalone backend daemon. Dual-published as rterm-backend. v3.0.5: terminal core (SSH auto-reconnect, WinRM persistent+streaming, serial break), chat user-message nav, reconnecting indicator, memory search/cap.",
+  "version": "3.0.9",
+  "description": "Headless AI-native backend for RTerm / neuralOS — v3.0.9: web-intel plugin (local-first web intelligence via wigolo; lean-by-default, synthesis by RTerm agent).",
   "main": "bin/gybackend.cjs",
   "bin": {
     "gybackend": "bin/gybackend.cjs",

package/plugins/web-intel/index.mjs

@@ -0,0 +1,381 @@
+/**
+ * web-intel plugin — local-first web intelligence for RTerm's agent via wigolo.
+ *
+ * Gives the agent first-class web tools it doesn't have: multi-engine search,
+ * clean-page fetch, site crawl, structured extract, similar-pages, cache,
+ * research, and page-watch → RTerm trigger automation. All local-first, keyless
+ * (search/fetch/crawl), and $0/query — the daemon runs on the same box.
+ *
+ * Synthesis uses RTerm's OWN agent, not a wigolo LLM — so there's NO LLM key to
+ * manage. `web_research` asks wigolo for the decomposed evidence + citations and
+ * RTerm's agent writes the cited answer from that brief.
+ *
+ * Lean by default: the daemon starts lazily with WIGOLO_NO_WARMUP=1 so the
+ * ~1.5 GB browser engine + on-device models are NOT downloaded at init (search/
+ * fetch/crawl work keyless without them). Set `warmupOnInit: true` to pre-fetch
+ * them in the background.
+ *
+ * Config (Settings → webIntel block, resolved from ctx.settings / env):
+ *   enabled       — master switch (default true)
+ *   restUrl       — wigolo daemon base URL (default http://127.0.0.1:3333)
+ *   token         — bearer token (optional; only if the daemon uses WIGOLO_API_TOKEN)
+ *   autoStart     — start the daemon on first use (default true)
+ *   warmupOnInit  — download the full browser engine + models in the background (default false = lean)
+ *
+ * The plugin never crashes RTerm when the daemon is down — every tool returns a
+ * clear {error, hint} result instead of throwing (the agentspan-bridge pattern).
+ */
+
+import { WigoloClient, DEFAULT_BASE_URL } from './wigoloClient.mjs'
+import { WigoloSidecar } from './sidecar.mjs'
+
+// ─── config resolution ──────────────────────────────────────────────────────
+
+/** Read the webIntel config block from RTerm settings (ctx.settings) or env. */
+export function resolveConfig(ctx = {}, env = process.env) {
+  const s = (typeof ctx.getSettings === 'function' ? ctx.getSettings() : ctx.settings) || {}
+  const block = s.webIntel || {}
+  return {
+    enabled: block.enabled !== false,
+    restUrl: String(block.restUrl || env.WIGOLO_REST_URL || DEFAULT_BASE_URL).trim().replace(/\/+$/, ''),
+    token: block.token || env.WIGOLO_API_TOKEN || undefined,
+    autoStart: block.autoStart !== false,
+    warmupOnInit: block.warmupOnInit === true,
+  }
+}
+
+/** Real fetch adapter (matches wigoloClient's expected {ok,status,text}). */
+async function realFetch(url, init) {
+  const res = await fetch(url, { method: init.method, headers: init.headers, body: init.body })
+  return { ok: res.ok, status: res.status, text: () => res.text() }
+}
+
+/** Build a configured WigoloClient from ctx (settings + vault). */
+export function buildClient(ctx = {}, fetchImpl) {
+  const cfg = resolveConfig(ctx)
+  const impl = typeof fetchImpl === 'function' ? fetchImpl : realFetch
+  return { client: new WigoloClient({ baseUrl: cfg.restUrl, token: cfg.token, fetchImpl: impl }), config: cfg }
+}
+
+// ─── formatting helpers (pure) ─────────────────────────────────────────────
+
+/** Normalize a search result set into compact rows for the agent + panel. */
+export function toResultRows(payload) {
+  const results = payload?.results ?? (Array.isArray(payload) ? payload : [])
+  if (!Array.isArray(results)) return []
+  return results.map((r) => ({
+    title: r.title ?? r.url,
+    url: r.url,
+    excerpt: (r.excerpt ?? r.description ?? '').slice(0, 240),
+    citation: r.citation_id ?? r.id,
+    score: r.evidence_score?.final ?? r.score,
+    freshness: payload?.freshness_signal?.published ?? r.published,
+  }))
+}
+
+/** Normalize a fetch/crawl result into a compact summary. */
+export function toPageSummary(payload) {
+  if (!payload || typeof payload !== 'object') return {}
+  const links = Array.isArray(payload.links) ? payload.links : []
+  return {
+    url: payload.url ?? payload.final_url,
+    title: payload.title,
+    markdown: typeof payload.markdown === 'string' ? payload.markdown.slice(0, 4000) : undefined,
+    linkCount: links.length,
+    links: links.slice(0, 20),
+    blocked: payload.blocked_by_challenge === true || payload.status === 'blocked',
+    sections: Array.isArray(payload.sections) ? payload.sections.length : undefined,
+  }
+}
+
+/** Normalize a research result: the evidence + citations RTerm's agent synthesizes from. */
+export function toResearchBrief(payload) {
+  if (!payload || typeof payload !== 'object') return { evidence: [] }
+  const evidence = payload.evidence ?? payload.results ?? payload.sources ?? []
+  const citations = payload.citations ?? []
+  return {
+    question: payload.question,
+    brief: payload.brief ?? payload.summary,
+    evidence: (Array.isArray(evidence) ? evidence : []).map((e) => ({
+      title: e.title ?? e.url,
+      url: e.url,
+      excerpt: (e.excerpt ?? e.snippet ?? '').slice(0, 300),
+      citation: e.citation_id ?? e.id,
+    })),
+    citations: Array.isArray(citations) ? citations : [],
+    note: 'Synthesis is done by the RTerm agent from this evidence — no LLM key needed.',
+  }
+}
+
+/** Map a watch list payload into rows. */
+export function toWatchRows(payload) {
+  const items = payload?.watches ?? payload?.items ?? (Array.isArray(payload) ? payload : [])
+  if (!Array.isArray(items)) return []
+  return items.map((w) => ({
+    id: w.id ?? w.watch_id,
+    url: w.url,
+    lastChecked: w.last_checked ?? w.checked_at,
+    changed: w.changed === true,
+    webhook: w.webhook,
+  }))
+}
+
+/** Fires when a watch reports a page change. */
+export function isPageChangedEvent(event) {
+  if (event?.source !== 'webintel') return false
+  return event?.changed === true || event?.kind === 'page_changed'
+}
+
+// ─── unreachable-daemon helper ─────────────────────────────────────────────
+
+async function guarded(fn, log) {
+  try {
+    return await fn()
+  } catch (e) {
+    const msg = e?.message ?? String(e)
+    log?.(`[web-intel] ${msg}`)
+    return { error: msg, hint: 'Is the wigolo daemon running? The web-intel plugin starts it on first use (npx -y wigolo serve), or run it yourself. Configure the URL in Settings → webIntel.' }
+  }
+}
+
+// ─── plugin entry ───────────────────────────────────────────────────────────
+
+export function register(ctx) {
+  const { registerTool, registerTrigger, registerPanel, log } = ctx
+  // Allow tests/runtimes to inject a fetch; default to the real one.
+  const { client, config } = buildClient(ctx, typeof ctx.fetchImpl === 'function' ? ctx.fetchImpl : undefined)
+
+  // Sidecar lifecycle (lazy, lean). Spawn is best-effort — in runtimes where a
+  // real child_process spawn is available the daemon starts on first use; in
+  // tests the spawnImpl is injected/mocked.
+  const sidecar = new WigoloSidecar({
+    spawnImpl: ctx.spawnProcess,
+    log,
+    config: { warmup: config.warmupOnInit, token: config.token },
+  })
+
+  async function ensureDaemon() {
+    if (!config.enabled) throw new Error('web-intel is disabled in Settings → webIntel')
+    // Probe the daemon; start it if it's down and autoStart is on.
+    const h = await client.health()
+    if (h.ok) return true
+    if (!config.autoStart) throw new Error(`wigolo daemon not reachable at ${config.restUrl} and autoStart is off`)
+    if (typeof ctx.spawnProcess !== 'function') {
+      throw new Error(`wigolo daemon not reachable at ${config.restUrl}. Start it: npx -y wigolo serve`)
+    }
+    await sidecar.start()
+    // Best-effort: wait briefly for it to come up, but never block hard.
+    const deadline = Date.now() + 8000
+    for (;;) {
+      const probe = await client.health()
+      if (probe.ok) break
+      if (Date.now() > deadline) throw new Error(`wigolo daemon did not become ready at ${config.restUrl} in time`)
+      await new Promise((r) => setTimeout(r, 300))
+    }
+    // Lean default: only pre-download the heavy models if the user opted in.
+    if (config.warmupOnInit) void sidecar.warmupInBackground()
+    return true
+  }
+
+  // Tool: webintel_health — is the daemon up + what's its status.
+  registerTool({
+    name: 'webintel_health',
+    description: 'Check the wigolo web-intelligence daemon status: reachable, lean vs full warmup, and whether it auto-started. Use this first if any web_* tool errors.',
+    params: {},
+    handler: async () => guarded(async () => {
+      const h = await client.health()
+      return {
+        restUrl: config.restUrl,
+        enabled: config.enabled,
+        autoStart: config.autoStart,
+        daemonUp: h.ok,
+        sidecar: sidecar.status(),
+        ...(h.ok ? { daemon: h.status } : { hint: 'Start it: npx -y wigolo serve (the plugin also auto-starts it on first use).' }),
+      }
+    }, log),
+  })
+
+  // Tool: web_search — multi-engine web search with ranked, citation-carrying results.
+  registerTool({
+    name: 'web_search',
+    description: 'Search the web (multi-engine, ranked, citation-carrying) for an ops question. Pass a query string or an array for parallel breadth. Returns ranked results with excerpts + citations the agent can quote. Keyless, $0.',
+    params: {
+      query: { type: ['string', 'array'], description: 'Search query (string) or array of queries for parallel breadth' },
+      timeRange: { type: 'string', description: "Optional time scope e.g. 'day'|'week'|'month'|'year'", optional: true },
+      domain: { type: 'string', description: 'Optional domain to scope the search to', optional: true },
+      maxResults: { type: 'number', description: 'Max results (default daemon setting)', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      await ensureDaemon()
+      if (!p?.query) return { error: 'web_search needs a query' }
+      const r = await client.search(p.query, {
+        ...(p.timeRange ? { time_range: p.timeRange } : {}),
+        ...(p.domain ? { domain: p.domain } : {}),
+        ...(typeof p.maxResults === 'number' ? { max_results: p.maxResults } : {}),
+      })
+      return { results: toResultRows(r), freshness: r?.freshness_signal }
+    }, log),
+  })
+
+  // Tool: web_fetch — fetch one URL as clean markdown (handles JS/SPA/anti-bot).
+  registerTool({
+    name: 'web_fetch',
+    description: 'Fetch one URL as clean markdown + metadata + links (tiered router escalates to a browser engine for JS/SPA/anti-bot pages). Use for a specific doc/advisory/page the agent needs to read.',
+    params: {
+      url: { type: 'string', description: 'The URL to fetch' },
+      section: { type: 'string', description: 'Optional single heading/section to extract', optional: true },
+      mode: { type: 'string', description: "Optional 'cache'|'default'|'stealth'", optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      await ensureDaemon()
+      if (!p?.url) return { error: 'web_fetch needs a url' }
+      const r = await client.fetch(p.url, {
+        ...(p.section ? { section: p.section } : {}),
+        ...(p.mode ? { mode: p.mode } : {}),
+      })
+      return toPageSummary(r)
+    }, log),
+  })
+
+  // Tool: web_crawl — multi-page crawl of a site (BFS/DFS/sitemap/map-only).
+  registerTool({
+    name: 'web_crawl',
+    description: 'Crawl a site (BFS/DFS/sitemap/map-only) with rate limits + robots.txt respect. Use to map a docs site or pull many pages. Returns per-page summaries + links.',
+    params: {
+      url: { type: 'string', description: 'Start URL' },
+      strategy: { type: 'string', description: "Optional 'bfs'|'dfs'|'sitemap'|'map'", optional: true },
+      maxPages: { type: 'number', description: 'Max pages to crawl', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      await ensureDaemon()
+      if (!p?.url) return { error: 'web_crawl needs a url' }
+      const r = await client.crawl(p.url, {
+        ...(p.strategy ? { strategy: p.strategy } : {}),
+        ...(typeof p.maxPages === 'number' ? { max_pages: p.maxPages } : {}),
+      })
+      const pages = Array.isArray(r?.pages) ? r.pages.map(toPageSummary) : [toPageSummary(r)]
+      return { startUrl: p.url, pageCount: pages.length, pages }
+    }, log),
+  })
+
+  // Tool: web_research — decompose a question into evidence + citations; RTerm's
+  // agent synthesizes the cited answer (NO LLM key needed).
+  registerTool({
+    name: 'web_research',
+    description: 'Research a question across the web: wigolo decomposes it, fans out sub-queries, fetches sources, and returns ranked evidence + citations. RTerm\'s agent then writes the cited answer from the brief — no LLM key needed. Use for current-doc-grounded answers (release notes, CVEs, errors, best practices).',
+    params: {
+      question: { type: 'string', description: 'The research question' },
+      maxSources: { type: 'number', description: 'Max sources to gather', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      await ensureDaemon()
+      if (!p?.question) return { error: 'web_research needs a question' }
+      const r = await client.research(p.question, {
+        ...(typeof p.maxSources === 'number' ? { max_sources: p.maxSources } : {}),
+      })
+      return toResearchBrief(r)
+    }, log),
+  })
+
+  // Tool: web_find_similar — pages similar to a URL/concept.
+  registerTool({
+    name: 'web_find_similar',
+    description: 'Find pages similar to a URL or concept (keyword + semantic + live web fusion). Use to find related advisories/docs.',
+    params: {
+      url: { type: 'string', description: 'The reference URL (or concept)', optional: true },
+      concept: { type: 'string', description: 'A concept to find similar pages for', optional: true },
+      maxResults: { type: 'number', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      await ensureDaemon()
+      const input = p?.url ?? p?.concept
+      if (!input) return { error: 'web_find_similar needs a url or concept' }
+      const r = await client.findSimilar(input, {
+        ...(typeof p.maxResults === 'number' ? { max_results: p.maxResults } : {}),
+      })
+      return { results: toResultRows(r) }
+    }, log),
+  })
+
+  // Tool: web_watch_add — watch a page for changes; fires webintel_page_changed.
+  registerTool({
+    name: 'web_watch_add',
+    description: 'Watch a page (vendor advisory, CVE, status page, doc) for changes. When it changes, the webintel_page_changed trigger fires so you can run a playbook or propose a change. Deliver to a webhook or poll.',
+    params: {
+      url: { type: 'string', description: 'The page URL to watch' },
+      interval: { type: 'string', description: "Optional check interval e.g. '1h'|'6h'|'1d'", optional: true },
+      webhook: { type: 'string', description: 'Optional webhook URL to deliver changes to', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      await ensureDaemon()
+      if (!p?.url) return { error: 'web_watch_add needs a url' }
+      const r = await client.watch('create', {
+        url: p.url,
+        ...(p.interval ? { interval: p.interval } : {}),
+        ...(p.webhook ? { webhook: p.webhook } : {}),
+      })
+      return { created: true, watch: r }
+    }, log),
+  })
+
+  // Tool: web_watch_list — list active page watches.
+  registerTool({
+    name: 'web_watch_list',
+    description: 'List active page watches (url, last-checked, changed flag).',
+    params: {},
+    handler: async () => guarded(async () => {
+      await ensureDaemon()
+      const r = await client.watch('list')
+      return { watches: toWatchRows(r) }
+    }, log),
+  })
+
+  // Tool: web_watch_remove — stop watching a page.
+  registerTool({
+    name: 'web_watch_remove',
+    description: 'Stop watching a page by watch id or URL.',
+    params: {
+      id: { type: 'string', description: 'The watch id (or URL)', optional: true },
+      url: { type: 'string', description: 'The watched URL', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      await ensureDaemon()
+      if (!p?.id && !p?.url) return { error: 'web_watch_remove needs an id or url' }
+      const r = await client.watch('remove', { ...(p.id ? { id: p.id } : {}), ...(p.url ? { url: p.url } : {}) })
+      return { removed: true, result: r }
+    }, log),
+  })
+
+  // Trigger: webintel_page_changed — fires when a watched page changes.
+  registerTrigger({
+    name: 'webintel_page_changed',
+    description: 'Fires when a watched page (web_watch_add) reports a change. Use for auto-remediation, CVE/vendor-advisory response, or doc-change playbooks.',
+    match: (event) => isPageChangedEvent(event),
+    action: 'propose-change',
+  })
+
+  // Panel: web-intel — watched pages + daemon status.
+  registerPanel({
+    name: 'web-intel',
+    title: 'Web Intelligence',
+    render: (data) => {
+      const watches = (Array.isArray(data?.watches) ? data.watches : [])
+        .map((w) => `<tr><td>${w.url ?? ''}</td><td>${w.changed ? 'changed' : '—'}</td><td>${w.lastChecked ?? ''}</td></tr>`)
+        .join('')
+      return `<div class="web-intel"><h3>Web Intelligence (wigolo)</h3><p>Daemon: ${config.restUrl} · warmup: ${config.warmupOnInit ? 'full' : 'lean'} · synthesis: RTerm agent (no LLM key)</p><h4>Watched pages</h4><table><thead><tr><th>URL</th><th>Changed</th><th>Last checked</th></tr></thead><tbody>${watches || '<tr><td colspan="3">No watches yet — web_watch_add to monitor a page.</td></tr>'}</tbody></table></div>`
+    },
+  })
+
+  log(`[web-intel] web-intel registered: 8 tools, 1 trigger, 1 panel (daemon=${config.restUrl}, warmup=${config.warmupOnInit ? 'full' : 'lean'})`)
+}
+
+export default {
+  register,
+  resolveConfig,
+  buildClient,
+  toResultRows,
+  toPageSummary,
+  toResearchBrief,
+  toWatchRows,
+  isPageChangedEvent,
+}

package/plugins/web-intel/plugin.json

@@ -0,0 +1,28 @@
+{
+  "name": "web-intel",
+  "version": "1.0.0",
+  "description": "Local-first web intelligence for RTerm's agent via wigolo — multi-engine web search, clean-page fetch, site crawl, structured extract, similar-pages, cache, research, and page-watch → RTerm trigger automation. Keyless search/fetch/crawl, $0/query, local-first. Synthesis uses RTerm's own agent (no LLM key needed). Lean by default: the daemon starts lazily with no browser-engine/model warmup (~1.5 GB stays opt-in).",
+  "entry": "index.mjs",
+  "tools": [
+    "webintel_health",
+    "web_search",
+    "web_fetch",
+    "web_crawl",
+    "web_research",
+    "web_find_similar",
+    "web_watch_add",
+    "web_watch_list",
+    "web_watch_remove"
+  ],
+  "triggers": [
+    "webintel_page_changed"
+  ],
+  "panels": [
+    "web-intel"
+  ],
+  "permissions": [
+    "exec",
+    "spawnProcess",
+    "readLedger:metrics"
+  ]
+}

package/plugins/web-intel/sidecar.mjs

@@ -0,0 +1,134 @@
+/**
+ * sidecar.mjs — manages the wigolo daemon lifecycle for RTerm's web-intel
+ * plugin: lazily start `wigolo serve` on first use, keep a stock RTerm install
+ * lean (no browser-engine/on-device-model download unless the user opts in),
+ * and report status. Pure + injectable: process spawning and health-probing are
+ * injected so it's fully unit-testable offline.
+ *
+ * Lean-by-default: we start the daemon with WIGOLO_NO_WARMUP=1 so the ~1.5 GB
+ * browser engine + on-device models are NOT downloaded at init — search/fetch/
+ * crawl work keyless without them. The heavier models download in the background
+ * on first use that actually needs them. `warmupOnInit: true` opts into the full
+ * upfront download (a background `wigolo init` run).
+ */
+
+export const DEFAULT_PORT = 3333
+export const DEFAULT_HOST = '127.0.0.1'
+
+/**
+ * Build the spawn plan for the wigolo daemon.
+ * @param {{ port?: number, host?: string, warmup?: boolean, token?: string }} cfg
+ * @returns {{ command: string, args: string[], env: Record<string,string> }}
+ */
+export function buildServePlan(cfg = {}) {
+  const port = cfg.port ?? DEFAULT_PORT
+  const host = cfg.host ?? DEFAULT_HOST
+  const env = { ...process.env }
+  // Lean by default: skip the browser-engine/model warmup unless explicitly on.
+  if (cfg.warmup !== true) env.WIGOLO_NO_WARMUP = '1'
+  if (cfg.token) env.WIGOLO_API_TOKEN = cfg.token
+  return {
+    command: 'npx',
+    args: ['-y', 'wigolo', 'serve', '--port', String(port), '--host', host],
+    env,
+  }
+}
+
+/** Build the background `wigolo init` plan (the full ~1.5 GB warmup). */
+export function buildInitPlan(cfg = {}) {
+  const env = { ...process.env }
+  if (cfg.token) env.WIGOLO_API_TOKEN = cfg.token
+  return { command: 'npx', args: ['-y', 'wigolo', 'init'], env }
+}
+
+export class WigoloSidecar {
+  /**
+   * @param {{
+   *   spawnImpl?: (cmd: string, args: string[], opts: object) => any,
+   *   healthImpl?: () => Promise<boolean>,
+   *   log?: (line: string) => void,
+   *   config?: { port?: number, host?: string, warmup?: boolean, token?: string, autoStart?: boolean },
+   *   now?: () => number,
+   * }} deps — all injectable; defaults are real (child_process + a health probe).
+   */
+  constructor(deps = {}) {
+    this.config = deps.config ?? {}
+    this.spawnImpl = deps.spawnImpl
+    this.healthImpl = deps.healthImpl
+    this.log = deps.log ?? (() => {})
+    this.now = deps.now ?? (() => Date.now())
+    this.process = null
+    this.startedAt = 0
+    this.lastError = undefined
+  }
+
+  /** Whether the daemon process is believed to be running. */
+  isRunning() {
+    return this.process != null
+  }
+
+  /** Start the daemon (idempotent). Returns the base URL it's expected on. */
+  async start() {
+    if (this.process) return this.baseUrl()
+    if (typeof this.spawnImpl !== 'function') {
+      this.lastError = 'no spawnImpl (sidecar spawn not available in this runtime)'
+      throw new Error(this.lastError)
+    }
+    const plan = buildServePlan(this.config)
+    this.log(`[web-intel] starting wigolo daemon: ${plan.command} ${plan.args.join(' ')}`)
+    try {
+      this.process = this.spawnImpl(plan.command, plan.args, {
+        env: plan.env,
+        detached: true,
+        stdio: 'ignore',
+      })
+      // Detach so the daemon outlives the plugin turn (it serves many agents).
+      this.process?.unref?.()
+      this.startedAt = this.now()
+      this.lastError = undefined
+    } catch (e) {
+      this.lastError = e?.message ?? String(e)
+      this.process = null
+      throw e
+    }
+    return this.baseUrl()
+  }
+
+  /** Kick off the full ~1.5 GB warmup in the background (opt-in). */
+  async warmupInBackground() {
+    if (typeof this.spawnImpl !== 'function') return false
+    const plan = buildInitPlan(this.config)
+    try {
+      const p = this.spawnImpl(plan.command, plan.args, { env: plan.env, detached: true, stdio: 'ignore' })
+      p?.unref?.()
+      this.log('[web-intel] background wigolo init (browser engine + models) started')
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /** Stop the daemon. */
+  async stop() {
+    if (!this.process) return
+    try { this.process.kill?.() } catch { /* best-effort */ }
+    this.process = null
+  }
+
+  /** Status snapshot for the health tool / panel. */
+  status() {
+    return {
+      running: this.isRunning(),
+      baseUrl: this.baseUrl(),
+      startedAt: this.startedAt || undefined,
+      lastError: this.lastError,
+      warmup: this.config.warmup === true ? 'full' : 'lean (no warmup)',
+    }
+  }
+
+  baseUrl() {
+    const host = this.config.host ?? DEFAULT_HOST
+    const port = this.config.port ?? DEFAULT_PORT
+    return `http://${host}:${port}`
+  }
+}

package/plugins/web-intel/wigoloClient.mjs

@@ -0,0 +1,145 @@
+/**
+ * wigoloClient.mjs — a minimal, dependency-free HTTP client for the wigolo web
+ * intelligence daemon (`wigolo serve`, default http://127.0.0.1:3333).
+ *
+ * wigolo exposes one REST route per tool: POST /v1/{search,fetch,crawl,cache,
+ * extract,find_similar,research,agent,diff,watch}, GET /health, GET /v1/tools.
+ * This client is pure + injectable (a `fetchImpl` is passed in) so it is fully
+ * unit-testable offline with a mocked fetch — no runtime network baked in.
+ *
+ * Auth: when the daemon is started with WIGOLO_API_TOKEN, every /v1 request
+ * needs `Authorization: Bearer <token>` (/health stays open). The client sends
+ * the header only when a token is provided.
+ */
+
+export const DEFAULT_BASE_URL = 'http://127.0.0.1:3333'
+
+/** Build request headers (adds the bearer token only when set). */
+export function buildHeaders(token) {
+  const h = { 'content-type': 'application/json', accept: 'application/json' }
+  if (token) h.authorization = `Bearer ${token}`
+  return h
+}
+
+/** Join a base URL + path safely (single slash). */
+export function joinUrl(base, path) {
+  const b = String(base || DEFAULT_BASE_URL).replace(/\/+$/, '')
+  const p = String(path || '').startsWith('/') ? String(path) : `/${path}`
+  return `${b}${p}`
+}
+
+async function parseBody(res) {
+  const text = await res.text()
+  if (!text) return null
+  try { return JSON.parse(text) } catch { return text }
+}
+
+export class WigoloApiError extends Error {
+  constructor(status, path, body) {
+    super(`wigolo ${status} ${path}: ${typeof body === 'string' ? body.slice(0, 300) : JSON.stringify(body)?.slice(0, 300)}`)
+    this.status = status
+    this.path = path
+    this.body = body
+  }
+}
+
+export class WigoloClient {
+  /**
+   * @param {{ baseUrl?: string, token?: string, fetchImpl: Function }} opts
+   *   fetchImpl(url, {method, headers, body}) -> Promise<{ok,status,text:()=>Promise<string>}>
+   */
+  constructor(opts = {}) {
+    if (typeof opts.fetchImpl !== 'function') throw new Error('WigoloClient needs a fetchImpl')
+    this.baseUrl = opts.baseUrl || DEFAULT_BASE_URL
+    this.token = opts.token
+    this.fetchImpl = opts.fetchImpl
+  }
+
+  async #post(path, payload) {
+    const res = await this.fetchImpl(joinUrl(this.baseUrl, path), {
+      method: 'POST',
+      headers: buildHeaders(this.token),
+      body: JSON.stringify(payload ?? {}),
+    })
+    const body = await parseBody(res)
+    if (!res.ok) throw new WigoloApiError(res.status, path, body)
+    return body
+  }
+
+  async #get(path) {
+    const res = await this.fetchImpl(joinUrl(this.baseUrl, path), {
+      method: 'GET',
+      headers: buildHeaders(this.token),
+    })
+    const body = await parseBody(res)
+    if (!res.ok) throw new WigoloApiError(res.status, path, body)
+    return body
+  }
+
+  /** Liveness + component status. Always open (no token). */
+  async health() {
+    try {
+      const body = await this.#get('/health')
+      return { ok: true, status: body }
+    } catch (e) {
+      return { ok: false, error: e?.message ?? String(e) }
+    }
+  }
+
+  /** List the daemon's tools (descriptions + endpoints). */
+  async tools() {
+    return this.#get('/v1/tools')
+  }
+
+  /** Multi-engine web search. `query` is a string or an array (parallel breadth). */
+  async search(query, opts = {}) {
+    return this.#post('/v1/search', { query, ...opts })
+  }
+
+  /** Fetch one URL as clean markdown (tiered router escalates to the browser engine). */
+  async fetch(url, opts = {}) {
+    return this.#post('/v1/fetch', { url, ...opts })
+  }
+
+  /** Multi-page crawl (BFS/DFS/sitemap/map-only). */
+  async crawl(url, opts = {}) {
+    return this.#post('/v1/crawl', { url, ...opts })
+  }
+
+  /** Structured extraction (tables, metadata, JSON-LD, named/custom schema). */
+  async extract(url, opts = {}) {
+    return this.#post('/v1/extract', { url, ...opts })
+  }
+
+  /** Pages similar to a URL/concept (keyword + semantic + live web fusion). */
+  async findSimilar(input, opts = {}) {
+    return this.#post('/v1/find_similar', typeof input === 'string' ? { url: input, ...opts } : { ...input, ...opts })
+  }
+
+  /** Query the local cache of everything already seen (keyword or hybrid semantic). */
+  async cache(opts = {}) {
+    return this.#post('/v1/cache', opts)
+  }
+
+  /** Decompose → fan out → fetch → return a structured brief + evidence.
+   * (Synthesis is done by the HOST agent, not wigolo's LLM — we pass no LLM key,
+   * so wigolo returns the raw brief + evidence and RTerm's agent writes the answer.) */
+  async research(question, opts = {}) {
+    return this.#post('/v1/research', { question, ...opts })
+  }
+
+  /** Autonomous gather loop (plan → search → fetch → extract) with a step log. */
+  async agent(goal, opts = {}) {
+    return this.#post('/v1/agent', { goal, ...opts })
+  }
+
+  /** Diff two page snapshots (or a page vs its last-seen cached version). */
+  async diff(input, opts = {}) {
+    return this.#post('/v1/diff', typeof input === 'string' ? { url: input, ...opts } : { ...input, ...opts })
+  }
+
+  /** Watch management: action=create|list|remove. */
+  async watch(action, opts = {}) {
+    return this.#post('/v1/watch', { action, ...opts })
+  }
+}