orient-cli 0.2.1 → 0.3.0

package/dist/integrations/web-search/bridge.js

@@ -0,0 +1,298 @@
+/**
+ * Web search bridge (MIT, derived from mrkrsl/web-search-mcp)
+ * ============================================================
+ *
+ * ORIENT ships a default web-search layer that uses the same
+ * "scrape Bing / Brave / DuckDuckGo via playwright" pattern that
+ * https://github.com/mrkrsl/web-search-mcp@MIT implements as a
+ * standalone MCP server. We adopt that approach directly in
+ * TypeScript here instead of spawning the MCP server as a
+ * subprocess — it avoids (a) the MCP protocol overhead, (b) the
+ * extra install step, and (c) the dependency on an 8-month-stale
+ * upstream build. All three engine scrapers, the priority-order
+ * fallback, and the content extraction pattern are reimplemented
+ * from the upstream's published README + source layout.
+ *
+ * Upstream attribution: https://github.com/mrkrsl/web-search-mcp
+ * Upstream license: MIT
+ *
+ * Three operations match the upstream MCP tool surface:
+ *
+ *   - `search(query, { limit, includeContent })` — "full-web-search"
+ *     equivalent. Returns an array of `SearchResult` with optional
+ *     full page text content per result.
+ *
+ *   - `searchSummaries(query, { limit })` — "get-web-search-summaries"
+ *     equivalent. Returns the same shape but with content omitted
+ *     (faster, no second-pass fetch per URL).
+ *
+ *   - `getPageContent(url)` — "get-single-web-page-content"
+ *     equivalent. Direct content extraction for one URL the agent
+ *     already has.
+ *
+ * Environment variables honored (names match upstream):
+ *
+ *   MAX_CONTENT_LENGTH      — max chars returned per page (default 8000)
+ *   DEFAULT_TIMEOUT         — per-navigation timeout in ms   (default 20000)
+ *   BROWSER_HEADLESS        — "true" or "false"              (default true)
+ *   FORCE_MULTI_ENGINE_SEARCH — force fallback engines even on Bing hit
+ *
+ * Playwright is already a dependency of orient-cli (shipped for
+ * @playwright/cli and the notebooklm login flow), so importing
+ * `playwright` here adds zero additional install weight.
+ */
+// Lazy-import playwright so environments that don't have chromium
+// installed yet (e.g. right after npm install, before the postinstall
+// script has run) still let orient-cli start — they just fail the
+// tool call with a helpful error.
+async function loadPlaywright() {
+    // @ts-ignore — playwright is a regular dep; this import is lazy
+    // so the bridge file can be imported in builds that skipped the
+    // postinstall step.
+    const mod = await import("playwright");
+    return mod;
+}
+function readEnv() {
+    const num = (name, fallback) => {
+        const raw = process.env[name];
+        if (!raw)
+            return fallback;
+        const parsed = Number.parseInt(raw, 10);
+        return Number.isFinite(parsed) ? parsed : fallback;
+    };
+    const bool = (name, fallback) => {
+        const raw = process.env[name];
+        if (raw === undefined)
+            return fallback;
+        return raw.toLowerCase() === "true" || raw === "1";
+    };
+    return {
+        maxContentLength: num("MAX_CONTENT_LENGTH", 8000),
+        defaultTimeout: num("DEFAULT_TIMEOUT", 20000),
+        headless: bool("BROWSER_HEADLESS", true),
+        forceMulti: bool("FORCE_MULTI_ENGINE_SEARCH", false),
+    };
+}
+// ============================================================================
+// Browser management — one chromium process, reused across calls
+// ============================================================================
+let sharedBrowser = null;
+let sharedContext = null;
+async function getContext() {
+    if (sharedContext)
+        return sharedContext;
+    const env = readEnv();
+    const pw = await loadPlaywright();
+    sharedBrowser = await pw.chromium.launch({ headless: env.headless });
+    sharedContext = await sharedBrowser.newContext({
+        userAgent: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+        viewport: { width: 1280, height: 800 },
+    });
+    sharedContext.setDefaultNavigationTimeout(env.defaultTimeout);
+    return sharedContext;
+}
+export async function closeBrowser() {
+    if (sharedContext) {
+        await sharedContext.close().catch(() => undefined);
+        sharedContext = null;
+    }
+    if (sharedBrowser) {
+        await sharedBrowser.close().catch(() => undefined);
+        sharedBrowser = null;
+    }
+}
+// ============================================================================
+// Engine scrapers — each returns a page of SearchResult (no content)
+// ============================================================================
+async function searchBing(query, limit) {
+    const ctx = await getContext();
+    const page = await ctx.newPage();
+    try {
+        const url = `https://www.bing.com/search?q=${encodeURIComponent(query)}&count=${limit * 2}`;
+        await page.goto(url, { waitUntil: "domcontentloaded" });
+        // Bing result blocks live under li.b_algo with h2 > a, p.b_lineclamp or .b_caption for snippet.
+        const results = await page.$$eval("li.b_algo", (nodes, cap) => {
+            return nodes.slice(0, cap).map((node) => {
+                const a = node.querySelector("h2 a");
+                const snippetEl = node.querySelector("p.b_lineclamp2, p.b_lineclamp3, p.b_lineclamp4, .b_caption p") ||
+                    node.querySelector(".b_caption");
+                return {
+                    title: a?.textContent?.trim() ?? "",
+                    url: a?.href ?? "",
+                    snippet: (snippetEl?.textContent ?? "").trim(),
+                };
+            });
+        }, limit);
+        return results
+            .filter((r) => r.url.startsWith("http"))
+            .map((r) => ({ ...r, engine: "bing" }));
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+async function searchBrave(query, limit) {
+    const ctx = await getContext();
+    const page = await ctx.newPage();
+    try {
+        const url = `https://search.brave.com/search?q=${encodeURIComponent(query)}`;
+        await page.goto(url, { waitUntil: "domcontentloaded" });
+        const results = await page.$$eval("div.snippet, .snippet, [data-type='web']", (nodes, cap) => {
+            return nodes.slice(0, cap).map((node) => {
+                const a = node.querySelector("a");
+                const titleEl = node.querySelector(".title, h3, .snippet-title");
+                const snippetEl = node.querySelector(".snippet-description, .desc, p");
+                return {
+                    title: (titleEl?.textContent ?? a?.textContent ?? "").trim(),
+                    url: a?.href ?? "",
+                    snippet: (snippetEl?.textContent ?? "").trim(),
+                };
+            });
+        }, limit);
+        return results
+            .filter((r) => r.url.startsWith("http") && !r.url.includes("brave.com"))
+            .map((r) => ({ ...r, engine: "brave" }));
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+async function searchDuckDuckGo(query, limit) {
+    const ctx = await getContext();
+    const page = await ctx.newPage();
+    try {
+        // DuckDuckGo's HTML endpoint is the simplest to scrape — no JS.
+        const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+        await page.goto(url, { waitUntil: "domcontentloaded" });
+        const results = await page.$$eval("div.result", (nodes, cap) => {
+            return nodes.slice(0, cap).map((node) => {
+                const a = node.querySelector("a.result__a");
+                const snippetEl = node.querySelector(".result__snippet");
+                return {
+                    title: a?.textContent?.trim() ?? "",
+                    url: a?.href ?? "",
+                    snippet: (snippetEl?.textContent ?? "").trim(),
+                };
+            });
+        }, limit);
+        return results
+            .filter((r) => r.url.startsWith("http"))
+            .map((r) => ({ ...r, engine: "duckduckgo" }));
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+const ENGINE_IMPLS = {
+    bing: searchBing,
+    brave: searchBrave,
+    duckduckgo: searchDuckDuckGo,
+};
+// ============================================================================
+// Content extraction — run page.evaluate() to pull main-text from a URL
+// ============================================================================
+async function extractPageText(page, maxLength) {
+    const text = await page.evaluate(() => {
+        // Prefer semantic containers; fall back to <body>.
+        const selectors = [
+            "main",
+            "article",
+            "[role='main']",
+            "#content",
+            ".content",
+            ".post",
+            ".article",
+            "body",
+        ];
+        for (const sel of selectors) {
+            const el = document.querySelector(sel);
+            if (el && el.innerText?.length > 100) {
+                return el.innerText;
+            }
+        }
+        return document.body?.innerText ?? "";
+    });
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    return collapsed.length > maxLength ? `${collapsed.slice(0, maxLength)}…` : collapsed;
+}
+export async function getPageContent(url) {
+    const env = readEnv();
+    const ctx = await getContext();
+    const page = await ctx.newPage();
+    try {
+        await page.goto(url, { waitUntil: "domcontentloaded" });
+        const title = (await page.title().catch(() => "")) || "";
+        const content = await extractPageText(page, env.maxContentLength);
+        return { url, title, content };
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+// ============================================================================
+// Top-level search orchestration (engine priority + full-content fetch)
+// ============================================================================
+/**
+ * Run a web search with the priority-order fallback pattern mrkrsl/
+ * web-search-mcp established: try Bing first, fall through to Brave,
+ * fall through to DuckDuckGo. If `includeContent` is true, fetch full
+ * page text for each result in parallel (bounded to 5 concurrent).
+ */
+export async function search(query, options = {}) {
+    const env = readEnv();
+    const limit = options.limit ?? 5;
+    const includeContent = options.includeContent ?? false;
+    const engines = options.engines ?? ["bing", "brave", "duckduckgo"];
+    let results = [];
+    const errors = [];
+    for (const engine of engines) {
+        try {
+            const impl = ENGINE_IMPLS[engine];
+            results = await impl(query, limit);
+            if (results.length > 0 && !env.forceMulti)
+                break;
+            if (env.forceMulti && results.length >= limit)
+                break;
+        }
+        catch (err) {
+            errors.push({ engine, error: err.message });
+        }
+    }
+    if (results.length === 0) {
+        const detail = errors.map((e) => `${e.engine}: ${e.error}`).join(" | ");
+        throw new Error(`No engine returned results for "${query}"${detail ? ` (${detail})` : ""}`);
+    }
+    if (includeContent) {
+        // Fetch content in parallel, bounded.
+        const ctx = await getContext();
+        const fetchOne = async (result) => {
+            const page = await ctx.newPage();
+            try {
+                await page.goto(result.url, { waitUntil: "domcontentloaded" });
+                result.content = await extractPageText(page, env.maxContentLength);
+            }
+            catch {
+                result.content = "";
+            }
+            finally {
+                await page.close().catch(() => undefined);
+            }
+            return result;
+        };
+        const CONCURRENCY = 5;
+        const pending = [];
+        for (const r of results) {
+            pending.push(fetchOne(r));
+            if (pending.length >= CONCURRENCY) {
+                await Promise.all(pending.splice(0));
+            }
+        }
+        await Promise.all(pending);
+    }
+    return results;
+}
+/** Shortcut: search without full content fetch. */
+export async function searchSummaries(query, options = {}) {
+    return search(query, { ...options, includeContent: false });
+}
+//# sourceMappingURL=bridge.js.map

package/dist/integrations/web-search/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../../../src/integrations/web-search/bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAIH,kEAAkE;AAClE,sEAAsE;AACtE,kEAAkE;AAClE,kCAAkC;AAClC,KAAK,UAAU,cAAc;IAC5B,gEAAgE;IAChE,gEAAgE;IAChE,oBAAoB;IACpB,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;IACvC,OAAO,GAAG,CAAC;AACZ,CAAC;AA8BD,SAAS,OAAO;IACf,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,QAAgB,EAAU,EAAE;QACtD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,GAAG;YAAE,OAAO,QAAQ,CAAC;QAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACxC,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;IACpD,CAAC,CAAC;IACF,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,QAAiB,EAAW,EAAE;QACzD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAC;QACvC,OAAO,GAAG,CAAC,WAAW,EAAE,KAAK,MAAM,IAAI,GAAG,KAAK,GAAG,CAAC;IACpD,CAAC,CAAC;IACF,OAAO;QACN,gBAAgB,EAAE,GAAG,CAAC,oBAAoB,EAAE,IAAI,CAAC;QACjD,cAAc,EAAE,GAAG,CAAC,iBAAiB,EAAE,KAAK,CAAC;QAC7C,QAAQ,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC;QACxC,UAAU,EAAE,IAAI,CAAC,2BAA2B,EAAE,KAAK,CAAC;KACpD,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,iEAAiE;AACjE,+EAA+E;AAE/E,IAAI,aAAa,GAAmB,IAAI,CAAC;AACzC,IAAI,aAAa,GAA0B,IAAI,CAAC;AAEhD,KAAK,UAAU,UAAU;IACxB,IAAI,aAAa;QAAE,OAAO,aAAa,CAAC;IACxC,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,MAAM,EAAE,GAAG,MAAM,cAAc,EAAE,CAAC;IAClC,aAAa,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrE,aAAa,GAAG,MAAM,aAAa,CAAC,UAAU,CAAC;QAC9C,SAAS,EACR,uGAAuG;QACxG,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;KACtC,CAAC,CAAC;IACH,aAAa,CAAC,2BAA2B,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC9D,OAAO,aAAa,CAAC;AACtB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY;IACjC,IAAI,aAAa,EAAE,CAAC;QACnB,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACnD,aAAa,GAAG,IAAI,CAAC;IACtB,CAAC;IACD,IAAI,aAAa,EAAE,CAAC;QACnB,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACnD,aAAa,GAAG,IAAI,CAAC;IACtB,CAAC;AACF,CAAC;AAED,+EAA+E;AAC/E,qEAAqE;AACrE,+EAA+E;AAE/E,KAAK,UAAU,UAAU,CAAC,KAAa,EAAE,KAAa;IACrD,MAAM,GAAG,GAAG,MAAM,UAAU,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC;IACjC,IAAI,CAAC;QACJ,MAAM,GAAG,GAAG,iCAAiC,kBAAkB,CAAC,KAAK,CAAC,UAAU,KAAK,GAAG,CAAC,EAAE,CAAC;QAC5F,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC,CAAC;QACxD,gGAAgG;QAChG,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAChC,WAAW,EACX,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;YACd,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;gBACvC,MAAM,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,CAA6B,CAAC;gBACjE,MAAM,SAAS,GACd,IAAI,CAAC,aAAa,CAAC,8DAA8D,CAAC;oBAClF,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;gBAClC,OAAO;oBACN,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE;oBACnC,GAAG,EAAE,CAAC,EAAE,IAAI,IAAI,EAAE;oBAClB,OAAO,EAAE,CAAC,SAAS,EAAE,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;iBAC9C,CAAC;YACH,CAAC,CAAC,CAAC;QACJ,CAAC,EACD,KAAK,CACL,CAAC;QACF,OAAO,OAAO;aACZ,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;aACvC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,MAAe,EAAE,CAAC,CAAC,CAAC;IACnD,CAAC;YAAS,CAAC;QACV,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC3C,CAAC;AACF,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,KAAa,EAAE,KAAa;IACtD,MAAM,GAAG,GAAG,MAAM,UAAU,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC;IACjC,IAAI,CAAC;QACJ,MAAM,GAAG,GAAG,qCAAqC,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7E,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC,CAAC;QACxD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAChC,0CAA0C,EAC1C,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;YACd,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;gBACvC,MAAM,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAA6B,CAAC;gBAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,4BAA4B,CAAC,CAAC;gBACjE,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC,gCAAgC,CAAC,CAAC;gBACvE,OAAO;oBACN,KAAK,EAAE,CAAC,OAAO,EAAE,WAAW,IAAI,CAAC,EAAE,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;oBAC5D,GAAG,EAAE,CAAC,EAAE,IAAI,IAAI,EAAE;oBAClB,OAAO,EAAE,CAAC,SAAS,EAAE,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;iBAC9C,CAAC;YACH,CAAC,CAAC,CAAC;QACJ,CAAC,EACD,KAAK,CACL,CAAC;QACF,OAAO,OAAO;aACZ,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;aACvE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,OAAgB,EAAE,CAAC,CAAC,CAAC;IACpD,CAAC;YAAS,CAAC;QACV,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC3C,CAAC;AACF,CAAC;AAED,KAAK,UAAU,gBAAgB,CAAC,KAAa,EAAE,KAAa;IAC3D,MAAM,GAAG,GAAG,MAAM,UAAU,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC;IACjC,IAAI,CAAC;QACJ,gEAAgE;QAChE,MAAM,GAAG,GAAG,uCAAuC,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/E,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC,CAAC;QACxD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAChC,YAAY,EACZ,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;YACd,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;gBACvC,MAAM,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,aAAa,CAA6B,CAAC;gBACxE,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC;gBACzD,OAAO;oBACN,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE;oBACnC,GAAG,EAAE,CAAC,EAAE,IAAI,IAAI,EAAE;oBAClB,OAAO,EAAE,CAAC,SAAS,EAAE,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;iBAC9C,CAAC;YACH,CAAC,CAAC,CAAC;QACJ,CAAC,EACD,KAAK,CACL,CAAC;QACF,OAAO,OAAO;aACZ,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;aACvC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,YAAqB,EAAE,CAAC,CAAC,CAAC;IACzD,CAAC;YAAS,CAAC;QACV,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC3C,CAAC;AACF,CAAC;AAED,MAAM,YAAY,GAA+F;IAChH,IAAI,EAAE,UAAU;IAChB,KAAK,EAAE,WAAW;IAClB,UAAU,EAAE,gBAAgB;CAC5B,CAAC;AAEF,+EAA+E;AAC/E,wEAAwE;AACxE,+EAA+E;AAE/E,KAAK,UAAU,eAAe,CAAC,IAAU,EAAE,SAAiB;IAC3D,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;QACrC,mDAAmD;QACnD,MAAM,SAAS,GAAG;YACjB,MAAM;YACN,SAAS;YACT,eAAe;YACf,UAAU;YACV,UAAU;YACV,OAAO;YACP,UAAU;YACV,MAAM;SACN,CAAC;QACF,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;YAC7B,MAAM,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;YACvC,IAAI,EAAE,IAAK,EAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,EAAE,CAAC;gBACvD,OAAQ,EAAkB,CAAC,SAAS,CAAC;YACtC,CAAC;QACF,CAAC;QACD,OAAO,QAAQ,CAAC,IAAI,EAAE,SAAS,IAAI,EAAE,CAAC;IACvC,CAAC,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACnD,OAAO,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACvF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAW;IAC/C,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,MAAM,GAAG,GAAG,MAAM,UAAU,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC;IACjC,IAAI,CAAC;QACJ,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,CAAC,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACzD,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,gBAAgB,CAAC,CAAC;QAClE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAChC,CAAC;YAAS,CAAC;QACV,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC3C,CAAC;AACF,CAAC;AAED,+EAA+E;AAC/E,wEAAwE;AACxE,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,KAAa,EAAE,UAAyB,EAAE;IACtE,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;IACjC,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,KAAK,CAAC;IACvD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;IAEnE,IAAI,OAAO,GAAmB,EAAE,CAAC;IACjC,MAAM,MAAM,GAA6C,EAAE,CAAC;IAE5D,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC9B,IAAI,CAAC;YACJ,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;YAClC,OAAO,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YACnC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU;gBAAE,MAAM;YACjD,IAAI,GAAG,CAAC,UAAU,IAAI,OAAO,CAAC,MAAM,IAAI,KAAK;gBAAE,MAAM;QACtD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACxD,CAAC;IACF,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxE,MAAM,IAAI,KAAK,CAAC,mCAAmC,KAAK,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC7F,CAAC;IAED,IAAI,cAAc,EAAE,CAAC;QACpB,sCAAsC;QACtC,MAAM,GAAG,GAAG,MAAM,UAAU,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,KAAK,EAAE,MAAoB,EAAyB,EAAE;YACtE,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC;YACjC,IAAI,CAAC;gBACJ,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC,CAAC;gBAC/D,MAAM,CAAC,OAAO,GAAG,MAAM,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,gBAAgB,CAAC,CAAC;YACpE,CAAC;YAAC,MAAM,CAAC;gBACR,MAAM,CAAC,OAAO,GAAG,EAAE,CAAC;YACrB,CAAC;oBAAS,CAAC;gBACV,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAC3C,CAAC;YACD,OAAO,MAAM,CAAC;QACf,CAAC,CAAC;QAEF,MAAM,WAAW,GAAG,CAAC,CAAC;QACtB,MAAM,OAAO,GAAiC,EAAE,CAAC;QACjD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACzB,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;YAC1B,IAAI,OAAO,CAAC,MAAM,IAAI,WAAW,EAAE,CAAC;gBACnC,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YACtC,CAAC;QACF,CAAC;QACD,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,OAAO,CAAC;AAChB,CAAC;AAED,mDAAmD;AACnD,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,KAAa,EAAE,UAAiD,EAAE;IACvG,OAAO,MAAM,CAAC,KAAK,EAAE,EAAE,GAAG,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;AAC7D,CAAC"}

package/dist/integrations/web-search/web-search-extension.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Web-search extension for ORIENT CLI
+ * ====================================
+ *
+ * Registers three LLM-callable tools that the agent uses whenever it
+ * detects a query requires web information — anywhere from "what's
+ * the latest version of X" to full Research-phase grounding. Backed
+ * by the web-search bridge which reimplements mrkrsl/web-search-mcp
+ * directly in TypeScript against playwright.
+ *
+ * The agent is told about these tools via the standard ExtensionAPI
+ * tool registration surface. Pi's tool router handles the rest —
+ * when the LLM produces a tool call matching one of these names, the
+ * handler runs and the result lands in the next turn's context.
+ *
+ * Used by:
+ *   - All phases: the agent picks these up automatically when a
+ *     user message needs fresh web data.
+ *   - Tier 1 + Tier 2 Research: the orient-core extension tells
+ *     the agent to use `web_search` / `web_search_full` as its
+ *     primary research tool.
+ *   - Tier 3 Research: the 2-option picker lets the user pick
+ *     between this built-in path or the notebooklm-py path.
+ */
+import type { ExtensionAPI } from "@orient-cli/coding-agent";
+export default function webSearchExtension(pi: ExtensionAPI): Promise<void>;

package/dist/integrations/web-search/web-search-extension.js

@@ -0,0 +1,122 @@
+/**
+ * Web-search extension for ORIENT CLI
+ * ====================================
+ *
+ * Registers three LLM-callable tools that the agent uses whenever it
+ * detects a query requires web information — anywhere from "what's
+ * the latest version of X" to full Research-phase grounding. Backed
+ * by the web-search bridge which reimplements mrkrsl/web-search-mcp
+ * directly in TypeScript against playwright.
+ *
+ * The agent is told about these tools via the standard ExtensionAPI
+ * tool registration surface. Pi's tool router handles the rest —
+ * when the LLM produces a tool call matching one of these names, the
+ * handler runs and the result lands in the next turn's context.
+ *
+ * Used by:
+ *   - All phases: the agent picks these up automatically when a
+ *     user message needs fresh web data.
+ *   - Tier 1 + Tier 2 Research: the orient-core extension tells
+ *     the agent to use `web_search` / `web_search_full` as its
+ *     primary research tool.
+ *   - Tier 3 Research: the 2-option picker lets the user pick
+ *     between this built-in path or the notebooklm-py path.
+ */
+import { Type } from "@sinclair/typebox";
+import { closeBrowser, getPageContent, search, searchSummaries } from "./bridge.js";
+export default async function webSearchExtension(pi) {
+    pi.on("session_start", (_event, ctx) => {
+        ctx.ui.setStatus("web-search", "web-search ready (bing → brave → duckduckgo)");
+    });
+    pi.registerTool({
+        name: "web_search",
+        label: "Web Search",
+        description: "Search the web and return result titles, URLs, and snippets. Fast (~2s). Use when a single pass of results is enough to answer. Engines tried in order: Bing → Brave → DuckDuckGo.",
+        promptSnippet: "Search the web for up-to-date information.",
+        parameters: Type.Object({
+            query: Type.String({ description: "Search query" }),
+            limit: Type.Optional(Type.Number({ description: "Max results (default 5)" })),
+        }),
+        async execute(_toolCallId, params) {
+            try {
+                const results = await searchSummaries(params.query, { limit: params.limit ?? 5 });
+                const body = results
+                    .map((r, i) => `[${i + 1}] ${r.title}\n    ${r.url}\n    ${r.snippet}\n    (${r.engine})`)
+                    .join("\n\n");
+                return {
+                    content: [{ type: "text", text: body || "(no results)" }],
+                    details: null,
+                };
+            }
+            catch (err) {
+                return {
+                    content: [{ type: "text", text: `web_search failed: ${err.message}` }],
+                    details: null,
+                };
+            }
+        },
+    });
+    pi.registerTool({
+        name: "web_search_full",
+        label: "Web Search (Full Content)",
+        description: "Search the web AND fetch full page content for each result in one call. Slower (~10-20s per 5 results) but gives the agent everything it needs to ground an answer in source text. Use in the Research phase, for deep-dives, or when summaries aren't enough.",
+        promptSnippet: "Search the web and extract full content from each result.",
+        parameters: Type.Object({
+            query: Type.String({ description: "Search query" }),
+            limit: Type.Optional(Type.Number({ description: "Max results (default 3 — content fetch is expensive)" })),
+        }),
+        async execute(_toolCallId, params) {
+            try {
+                const results = await search(params.query, { limit: params.limit ?? 3, includeContent: true });
+                const body = results
+                    .map((r, i) => `[${i + 1}] ${r.title}\n    ${r.url}\n    ${r.snippet}\n    (${r.engine})\n\n    ${r.content ?? "(no content)"}`)
+                    .join("\n\n---\n\n");
+                return { content: [{ type: "text", text: body || "(no results)" }], details: null };
+            }
+            catch (err) {
+                return {
+                    content: [{ type: "text", text: `web_search_full failed: ${err.message}` }],
+                    details: null,
+                };
+            }
+        },
+    });
+    pi.registerTool({
+        name: "web_page_content",
+        label: "Fetch Page Content",
+        description: "Extract the main text content of a single URL the agent already knows about. Use when the agent has a link from an earlier message, a git log, or a prior search and needs the page body without running another search.",
+        promptSnippet: "Extract the main content of a URL.",
+        parameters: Type.Object({
+            url: Type.String({ description: "Absolute URL (https://...)" }),
+        }),
+        async execute(_toolCallId, params) {
+            try {
+                const result = await getPageContent(params.url);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Title: ${result.title}\nURL: ${result.url}\n\n${result.content}`,
+                        },
+                    ],
+                    details: null,
+                };
+            }
+            catch (err) {
+                return {
+                    content: [{ type: "text", text: `web_page_content failed: ${err.message}` }],
+                    details: null,
+                };
+            }
+        },
+    });
+    // The shared chromium process is cleaned up by Node's process-exit
+    // hook — pi's extension API doesn't expose a `session_end` event
+    // yet. See MIGRATION.md for the fork-level TODO to add one. In the
+    // meantime, chromium gets torn down when the orient process
+    // terminates, which is the common case.
+    process.on("exit", () => {
+        closeBrowser().catch(() => undefined);
+    });
+}
+//# sourceMappingURL=web-search-extension.js.map

package/dist/integrations/web-search/web-search-extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-search-extension.js","sourceRoot":"","sources":["../../../src/integrations/web-search/web-search-extension.ts"],"names":[],"mappings":"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"}

package/dist/orient/orient-extension.js

@@ -14,11 +14,13 @@ import { getTemplatesDir } from "../package-paths.js";
 import { createChangePacket, getActivePacket, getPacketDir, initOrient, listChangePackets, readPacketConfig, resolveActivePacketDir, setActivePacket, writePacketConfig, } from "./change-packet.js";
 import { appendClarificationLog, applyResolutions, buildClarifySelectOptions, CUSTOM_ANSWER_OPTION, formatClarifyPrompt, MAX_MARKERS_PER_SESSION, scanMarkers, } from "./clarify.js";
 import { decideClear, formatClearMessage } from "./clear-command.js";
+import { describeStatus as describeNotebookLMStatus, setupNotebookLM } from "../integrations/notebooklm/setup.js";
+import { NotebookLMBridge } from "../integrations/notebooklm/bridge.js";
 import { describeMode, readMode, writeMode } from "./mode.js";
 import { formatPhaseProgress, PHASES } from "./phases.js";
 import { buildExecuteReminder, buildPlanReminder, deletePlan, getPlanFilePath, readPlan, readState, renderStatus as renderPlanStatus, startPlanning, transitionToExecuting, transitionToPlanning, } from "./plan-execute.js";
 import { OrientStateMachine } from "./state-machine.js";
-import { buildTierSelectOptions, describeTierBudget, parseTierFromSelection, setDefaultTier, TIERS, } from "./tiers.js";
+import { buildTierSelectOptions, describeTierBudget, getEffectiveTier, parseTierFromSelection, setDefaultTier, TIERS, } from "./tiers.js";
 import { Phase } from "./types.js";
 import { decideWizardAction, optIntoOrientFramework, optOutOfOrientFramework } from "./wizard.js";
 export default function orientExtension(pi) {
@@ -290,8 +292,154 @@ export default function orientExtension(pi) {
                 // Load the skill for this phase (the agent will then guide the user)
                 ctx.ui.notify(`Entering ${phaseInfo.label} phase for "${active.name}"\n` +
                     `Use /skill:orient-${command.split(".")[1]} for detailed phase guidance.`, "info");
+                // ============================================================
+                // Research phase tier-aware backend selection
+                // ============================================================
+                //
+                // Tier 1 / Tier 2 — use the built-in web-search layer
+                // (web_search / web_search_full, backed by bing → brave →
+                // duckduckgo via playwright). The agent picks up those
+                // tools automatically through the web-search extension
+                // so we only need to confirm the phase was entered.
+                //
+                // Tier 3 — offer the user a choice between two research
+                // backends:
+                //   1. Built-in web search (same as tier 1/2, but the
+                //      Research skill tells the agent to run deeper
+                //      multi-query passes).
+                //   2. NotebookLM (notebooklm-py) for cited, grounded
+                //      answers against a persistent notebook — requires
+                //      a one-time Google sign-in via a headed Chromium
+                //      window (`notebooklm login`). Auto-installed at
+                //      orient-cli install time; auth is the only manual
+                //      step.
+                //
+                // The pick is persisted for the remainder of the packet
+                // so phase re-entries don't re-prompt.
+                if (phase === Phase.Research) {
+                    const tierredConfig = sm.getConfig();
+                    const tier = getEffectiveTier(tierredConfig, Phase.Research);
+                    if (tier === 1 || tier === 2) {
+                        ctx.ui.notify(`Research backend: built-in web search (tier ${tier}). The agent uses web_search / web_search_full directly.`, "info");
+                    }
+                    else if (tier === 3) {
+                        const existing = tierredConfig.researchBackend;
+                        let chosen = existing;
+                        if (!chosen) {
+                            const selection = await ctx.ui.select("Tier-3 Research backend", [
+                                "1 — Built-in web search (fast, free, no login, multi-engine scraping)",
+                                "2 — NotebookLM (cited answers, requires one-time Google sign-in)",
+                            ]);
+                            if (selection) {
+                                chosen = selection.trim().startsWith("2") ? "notebooklm" : "web-search";
+                            }
+                        }
+                        if (chosen === "notebooklm") {
+                            ctx.ui.notify("Tier-3 Research: NotebookLM backend selected.", "info");
+                            const ready = await ensureNotebookLMReady(ctx, "tier-3 Research / NotebookLM option");
+                            if (!ready) {
+                                ctx.ui.notify("Falling back to built-in web search for this session. Run /orient.research.setup once a display is available, then re-enter Research.", "warning");
+                                chosen = "web-search";
+                            }
+                        }
+                        else {
+                            ctx.ui.notify("Tier-3 Research: built-in web search selected. The agent will run multi-query passes via web_search_full and aggregate results into Research.md.", "info");
+                        }
+                        // Persist the choice on the packet config.
+                        const updated = {
+                            ...sm.getConfig(),
+                            researchBackend: chosen ?? "web-search",
+                        };
+                        writePacketConfig(active.dir, updated);
+                    }
+                }
+            },
+        });
+    }
+    // ========================================================================
+    // Research setup command + session_start status hint
+    // ========================================================================
+    //
+    // Users can also run the setup flow manually at any time via
+    // /orient.research.setup. This is useful (a) on a headless server
+    // where the auto-trigger skipped the login step, (b) when the user
+    // wants to pre-warm the install before hitting the Research phase,
+    // and (c) for re-authing when the Google cookies expire.
+    pi.registerCommand("orient.research.setup", {
+        description: "Install + authenticate notebooklm-py for tier-3 Research",
+        handler: async (_args, ctx) => {
+            await ensureNotebookLMReady(ctx, "manual setup");
+        },
+    });
+    // Surface the notebooklm status on session_start so users know
+    // whether tier-3 Research is ready before they hit the phase.
+    pi.on("session_start", async (_event, ctx) => {
+        try {
+            const status = await describeNotebookLMStatus();
+            ctx.ui.setStatus("notebooklm", status);
+        }
+        catch {
+            // Silent fall-through — status hint is decorative.
+        }
+    });
+    /**
+     * Consent-gated install + auth runner. Returns true iff notebooklm
+     * is ready after the flow (installed + authenticated). On failure
+     * returns false with a helpful notify() message — the caller can
+     * still use lower-tier research with pi's built-in tools.
+     */
+    async function ensureNotebookLMReady(ctx, reason) {
+        const bridge = new NotebookLMBridge();
+        const availability = await bridge.checkAvailability();
+        if (availability.installed && availability.authenticated) {
+            ctx.ui.notify(`NotebookLM already ready (${reason}).`, "info");
+            return true;
+        }
+        ctx.ui.notify([
+            `NotebookLM setup required (${reason}).`,
+            "",
+            "This will:",
+            "  1. pip install --user \"notebooklm-py[browser]\"",
+            "  2. python3 -m playwright install chromium (~170MB)",
+            "  3. notebooklm login — opens a Chromium window; sign in to Google",
+            "",
+            "Credentials persist at ~/.notebooklm/profiles/default/ — one-time per machine.",
+            "",
+            "Press ctrl+c now to abort, or wait — setup starts in ~2 seconds...",
+        ].join("\n"), "info");
+        // Optional confirmation if the fork exposes ctx.ui.confirm().
+        const confirmFn = ctx.ui.confirm;
+        if (typeof confirmFn === "function") {
+            const ok = await confirmFn("NotebookLM setup", "Install notebooklm-py and sign in to Google now?");
+            if (!ok) {
+                ctx.ui.notify("NotebookLM setup deferred. Tier-3 Research will run with pi's built-in tools only until you run /orient.research.setup.", "warning");
+                return false;
+            }
+        }
+        else {
+            // No confirm method — brief delay so the user can abort with
+            // ctrl+c if they change their mind.
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+        }
+        ctx.ui.notify("Running notebooklm-py setup... progress streams below.", "info");
+        const renderStep = (step) => {
+            const icons = {
+                pending: "○",
+                running: "⟳",
+                ok: "✓",
+                skipped: "-",
+                failed: "✗",
+            };
+            const detail = step.detail ? `  ${step.detail}` : "";
+            return `  ${icons[step.status]} ${step.label}${detail}`;
+        };
+        const result = await setupNotebookLM({
+            onProgress: (step) => {
+                ctx.ui.notify(renderStep(step), step.status === "failed" ? "warning" : "info");
             },
         });
+        ctx.ui.notify(result.message, result.success ? "info" : "warning");
+        return result.success;
     }
     // ========================================================================
     // ORIENT Tools (callable by the LLM agent)