@bacnh85/pi-web 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.8.0 (2026-09-13)
+
+### Added
+
+- **`web_research` tool** — AI-synthesized web research via Gemini's web tier
+  (gemini.google.com), cookie-authed with `__Secure-1PSID`.
+  `mode: "ask"` returns a quick grounded answer with extracted source links
+  (works in guest mode without any cookie, Flash-only);
+  `mode: "research"` runs Gemini **Deep Research** — an autonomous agent that
+  browses the web for minutes and returns a comprehensive report (requires the
+  cookie and a Gemini Advanced subscription; default timeout 10 min, cap 30).
+- New `lib/gemini.ts` wrapper over the `gemini-reverse` npm package (lazy
+  dynamic import, injectable client for tests, one AuthError retry that
+  re-absorbs rotated Set-Cookies). Sources are extracted from markdown links
+  in the answer/report text (the web protocol exposes no structured citations).
+- `web_status` now reports `geminiWeb` (configured/cookieSource/proxy).
+- Env config: `GEMINI_WEB_SECURE_1PSID` (required for authed/research mode),
+  optional `GEMINI_WEB_PROXY` (escape hatch if Google blocks the IP).
+- **Header-cap fix (authed mode)** — Google ships ~25 KB of response headers on
+  Gemini pages (giant `content-security-policy`), over Node's default 16 KB
+  parser cap; the wrapper injects a per-request `maxHeaderSize` for
+  gemini.google.com hosts only (lazy, no global flag needed).
+
 ## 0.7.1 (2026-09-12)
 
 ### Fixed

package/README.md

@@ -1,8 +1,8 @@
 # @bacnh85/pi-web
 
-Pi extension for **unified web search, content extraction, site crawling, and page capture**.
+Pi extension for **unified web search, content extraction, site crawling, page capture, and Gemini web-tier research**.
 
-Auto-selects the best backend from SearXNG (self-hosted), Brave Search, Firecrawl, Crawl4AI, and agy (Gemini/Claude, when installed) — so agents don't have to know which backend to use. Search selection is adaptive: broad discovery prefers self-hosted SearXNG, while precision-sensitive searches and inline content prefer Brave.
+Auto-selects the best backend from SearXNG (self-hosted), Brave Search, Firecrawl, Crawl4AI, and agy (Gemini/Claude, when installed) — so agents don't have to know which backend to use. Search selection is adaptive: broad discovery prefers self-hosted SearXNG, while precision-sensitive searches and inline content prefer Brave. `web_research` adds AI-synthesized research with citations via your gemini.google.com session.
 
 ## Install
 
@@ -30,10 +30,13 @@ Variables:
 | `FIRECRAWL_API_KEY` | No (2) | — | Required for hosted Firecrawl |
 | `CRAWL4AI_API_URL` | No | `http://127.0.0.1:11235` | Self-hosted Crawl4AI |
 | `CRAWL4AI_API_TOKEN` | No (3) | — | Required if Crawl4AI auth enabled |
+| `GEMINI_WEB_SECURE_1PSID` | No (4) | — | `__Secure-1PSID` cookie from gemini.google.com — enables authed `web_research` (Deep Research) |
+| `GEMINI_WEB_PROXY` | No | — | Proxy URL for Gemini web calls (escape hatch if Google blocks the IP) |
 
 > (1) At least one search backend (SearXNG, Brave, or Firecrawl) must be configured for `web_search`.
 > (2) Required for hosted Firecrawl; optional for self-hosted instances without auth.
 > (3) Required for Crawl4AI v0.9+ default config.
+> (4) Without it `web_research mode=ask` still works in guest mode (Flash-only); `mode=research` errors with setup steps.
 
 Secrets are never printed; `web_status` reports only presence/source.
 
@@ -197,10 +200,65 @@ Typical output:
     "health": { "status": "healthy", "version": "0.5.0", ... }
   },
   "agy": { "installed": true },
+  "geminiWeb": { "configured": true, "cookieSource": "process.env", "proxy": false },
   "localChrome": { "path": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" }
 }
 ```
 
+### `web_research` — Gemini web-tier research
+
+AI-synthesized research through your gemini.google.com session (powered by the
+[`gemini-reverse`](https://github.com/rynn-k/Gemini-Reverse) client, lazy-loaded).
+
+```
+web_research(query="compare the top 3 cloud providers' AI offerings", mode="research", timeout_ms=600000)
+```
+
+- **`mode: "ask"`** (default) — quick grounded answer (Gemini auto-grounds with
+  Google Search). Works **without any cookie** in guest mode (Flash-only).
+  Sent as a temporary chat so your Gemini history stays clean.
+- **`mode: "research"`** — full Gemini **Deep Research**: plan → autonomous web
+  browsing (minutes) → cited report. Requires the cookie **and a Gemini
+  Advanced subscription** on the account. Default timeout 600 s, cap 1 800 000.
+
+Both modes return the text plus **Sources** — URLs extracted from the
+answer/report markdown (the web protocol exposes no structured citations field).
+
+Setup (authed mode):
+
+1. Sign in at [gemini.google.com](https://gemini.google.com/).
+2. `F12` → **Application** → **Cookies** → `https://gemini.google.com`.
+3. Copy the `__Secure-1PSID` value into `~/.pi/agent/.env.local`:
+
+   ```bash
+   GEMINI_WEB_SECURE_1PSID=your-cookie-value
+   # optional, if Google blocks your IP:
+   # GEMINI_WEB_PROXY=http://host:port
+   ```
+4. Restart pi; `web_status` shows `geminiWeb.configured: true`.
+
+Live verification script (also proves the header-cap patch end-to-end — an
+authed failure would surface `HPE_HEADER_OVERFLOW`):
+
+```bash
+npx tsx extensions/scripts/gemini-smoke.ts "test query"            # ask (authed or guest)
+npx tsx extensions/scripts/gemini-smoke.ts "topic" research        # Deep Research
+```
+
+⚠️ **Unofficial, at your own risk.** Cookie auth uses your real Google session
+against gemini.google.com's internal web API and may not comply with Google's
+ToS; the protocol can break when Google changes it. `ask` mode errors map to
+actionable steps (expired cookie → re-copy; IP block → set `GEMINI_WEB_PROXY`).
+
+Troubleshooting:
+
+- *"cookie expired or invalid"* — re-copy `__Secure-1PSID` (it rotates).
+- *"temporarily blocked this IP"* — set `GEMINI_WEB_PROXY`.
+- *research mode: "Unknown API error: 1184"* — on this account Deep Research
+  was rejected; usually means no Gemini Advanced subscription on the account
+  (Deep Research is Advanced-only), or Google changed the protocol. `ask`
+  mode is unaffected.
+
 ## Library structure
 
 | Module | Contents |

package/extensions/index.ts

@@ -21,6 +21,12 @@ import {
   formatUnifiedSearchResults,
 } from "./lib/format";
 import { searchWithDiagnostics } from "./lib/search";
+import {
+  loadGeminiWebConfig,
+  geminiAsk,
+  geminiResearch,
+  describeGeminiError,
+} from "./lib/gemini";
 import { extractWithDiagnostics, type ExtractMode } from "./lib/extract";
 import { firecrawlRequest, type FirecrawlResult } from "./lib/firecrawl";
 import {
@@ -77,6 +83,7 @@ const WEB_ROUTING_GUIDANCE = `## Web Tool Routing (pi-web)
 - **web_map** — discover site URLs (Firecrawl Map).
 - **web_crawl** — multi-page crawl: \`mode: "light"\` (Firecrawl, url) or \`mode: "full"\` (Crawl4AI, urls[]).
 - **web_screenshot** / **web_pdf** — page capture (Crawl4AI).
+- **web_research** — AI-synthesized research via Gemini web (mode "ask" = grounded answer, guest OK; mode "research" = Deep Research report, needs cookie + Gemini Advanced, takes minutes).
 - **web_status** — provider config + health.
 
 Rules: Firecrawl Search is weak on domain-specific queries — prefer SearXNG/Brave; Firecrawl Scrape fails on bot-protected sites — use Crawl4AI (\`mode: "full"\`) then agy (\`mode: "agy"\`); cite source URLs.`;
@@ -440,6 +447,58 @@ export default function piWebExtension(pi: ExtensionAPI) {
     },
   });
 
+  // ── web_research ─────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "web_research",
+    label: "Web Research (Gemini)",
+    description:
+      "AI-synthesized web research via Gemini (gemini.google.com web tier, cookie auth). Mode 'ask' returns a quick grounded answer with source links (works guest-mode, Flash only). Mode 'research' runs Gemini Deep Research — an autonomous agent browses the web for minutes and returns a comprehensive cited report (requires GEMINI_WEB_SECURE_1PSID cookie and a Gemini Advanced subscription).",
+    promptSnippet: "AI-synthesized research with citations",
+    promptGuidelines: [
+      "Use for AI-synthesized research with sources (mode ask = quick grounded answer; mode research = multi-minute Deep Research report). NOT for URL-list searches (web_search) or single-URL extraction (web_extract). Cite the returned source URLs.",
+    ],
+    parameters: Type.Object({
+      query: Type.String({ description: "Research question or topic." }),
+      mode: Type.Optional(Type.Union(
+        [Type.Literal("ask"), Type.Literal("research")],
+        { default: "ask", description: "ask = quick grounded answer (guest OK); research = full Deep Research report (cookie + Gemini Advanced required, takes minutes)." },
+      )),
+      model: Type.Optional(Type.String({ description: "Gemini model for ask mode (e.g. gemini-3-flash). Discovered from the account by default." })),
+      ...sharedControlSchema,
+    }),
+    async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
+      const config = loadGeminiWebConfig(cwdFromContext(ctx), includeProjectEnv(ctx));
+      const mode = (params.mode as string) || "ask";
+      const query = params.query as string;
+      try {
+        if (mode === "research") {
+          const timeoutMs = Math.min(Math.max((params.timeout_ms as number) ?? 600_000, 30_000), 1_800_000);
+          const result = await geminiResearch(query, { config, timeoutMs, signal });
+          const meta = [
+            "Mode: research (Gemini Deep Research)",
+            result.title ? `Title: ${result.title}` : null,
+            result.eta ? `ETA: ${result.eta}` : null,
+          ].filter(Boolean).join("\n");
+          const sources = result.sources.length ? result.sources.map((s, i) => `${i + 1}. ${s}`).join("\n") : "(none found in report text)";
+          const text = `${meta}\n\n${result.text}\n\n--- Sources (extracted from report) ---\n${sources}`;
+          return { content: [{ type: "text" as const, text: truncateText(text) }], details: { mode, ...result } };
+        }
+        const askTimeoutMs = Math.min(Math.max((params.timeout_ms as number) ?? 120_000, 30_000), 600_000);
+        const result = await geminiAsk(query, { config, model: params.model as string | undefined, timeoutMs: askTimeoutMs, signal });
+        const meta = [
+          "Mode: ask",
+          `Model: ${result.model ?? "unknown"}`,
+          result.guest ? "Guest mode (no cookie — Flash only; set GEMINI_WEB_SECURE_1PSID for full access)" : "Cookie auth",
+        ].join("\n");
+        const sources = result.sources.length ? result.sources.map((s, i) => `${i + 1}. ${s}`).join("\n") : "(none found in answer text)";
+        const text = `${meta}\n\n${result.text}\n\n--- Sources (extracted from answer) ---\n${sources}`;
+        return { content: [{ type: "text" as const, text: truncateText(text) }], details: { mode, ...result } };
+      } catch (err) {
+        throw new Error(describeGeminiError(err));
+      }
+    },
+  });
+
   // ── web_status ───────────────────────────────────────────────────────
   pi.registerTool({
     name: "web_status",
@@ -484,6 +543,10 @@ export default function piWebExtension(pi: ExtensionAPI) {
           apiTokenSource: c4aiToken.value ? c4aiToken.source : "not set",
         },
         agy: { installed: isAgyInstalled() },
+        geminiWeb: (() => {
+          const cfg = loadGeminiWebConfig(cwd, trusted);
+          return { configured: Boolean(cfg.psid), cookieSource: cfg.psidSource, proxy: Boolean(cfg.proxy) };
+        })(),
         localChrome: { path: findChromeBinary() ?? "not found" },
       };
 

package/extensions/lib/gemini.ts

@@ -0,0 +1,339 @@
+// Gemini web-tier (gemini.google.com) research backend, cookie-authed via the
+// __Secure-1PSID cookie. Thin wrapper over the `gemini-reverse` npm package
+// (CJS), lazily dynamic-imported so pi startup pays zero cost when unused.
+
+import http from "node:http";
+import https from "node:https";
+import { urlToHttpOptions } from "node:url";
+import { findEnvValue } from "./config";
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+export interface GeminiWebConfig {
+  psid?: string;
+  psidSource: string;
+  proxy?: string;
+}
+
+export function loadGeminiWebConfig(cwd = process.cwd(), includeCwdEnv = false): GeminiWebConfig {
+  const psid = findEnvValue("GEMINI_WEB_SECURE_1PSID", cwd, includeCwdEnv);
+  const proxy = findEnvValue("GEMINI_WEB_PROXY", cwd, includeCwdEnv);
+  return { psid: psid.value, psidSource: psid.value ? psid.source : "not set", proxy: proxy.value };
+}
+
+// ---------------------------------------------------------------------------
+// Minimal structural view of the gemini-reverse client (keeps tests injectable
+// and decouples us from upstream type drift).
+// ---------------------------------------------------------------------------
+
+export interface GeminiOutputLike {
+  text?: string | null;
+  model?: string;
+  candidates?: Array<{ text?: string | null }>;
+}
+
+export interface GeminiResearchLike {
+  text?: string | null;
+  plan?: { title?: string | null; eta_text?: string | null };
+  statuses?: Array<Record<string, unknown>>;
+}
+
+export interface GeminiClientLike {
+  ask(prompt: string, opts?: Record<string, unknown>): Promise<GeminiOutputLike>;
+  research(
+    prompt: string,
+    opts?: { wait?: boolean; pollInterval?: number; timeout?: number; onStatus?: (s: Record<string, unknown>) => void },
+  ): Promise<GeminiResearchLike>;
+}
+
+export type GeminiClientFactory = (
+  opts: { secure_1psid?: string; proxy?: string },
+) => GeminiClientLike | Promise<GeminiClientLike>;
+
+// Cached per config (psid|proxy) so a config change re-creates the client.
+let cached: { key: string; client: GeminiClientLike } | null = null;
+
+// Google ships ~25KB of response headers on every Gemini page (a 19.7KB
+// content-security-policy + 3.9KB reporting-endpoints) — over Node's default
+// 16KB parser cap, so the http parser rejects them (HPE_HEADER_OVERFLOW; the
+// same cap exists in undici, but gemini-reverse uses axios's node http adapter).
+// Node honors a per-request maxHeaderSize override, but axios doesn't forward
+// it — so lazily patch http.request/https.request to inject it for
+// gemini.google.com hosts only.
+// ponytail: process-wide patch, scoped to one hostname; if it ever misbehaves,
+// revert to launching pi with NODE_OPTIONS=--max-http-header-size=262144.
+
+/**
+ * Returns the request options to pass through with the cap injected when the
+ * target host is gemini.google.com, or null when the call must pass through
+ * untouched. Normalizes all http.request input forms (options object, string,
+ * URL) — string/URL forms become a fresh options object.
+ *
+ * @internal exported for tests
+ */
+export function injectGeminiHeaderCap(options: unknown): Record<string, unknown> | null {
+  let opts: Record<string, unknown>;
+  if (typeof options === "string") {
+    opts = urlToHttpOptions(new URL(options)) as Record<string, unknown>;
+  } else if (options instanceof URL) {
+    opts = urlToHttpOptions(options) as Record<string, unknown>;
+  } else if (options && typeof options === "object") {
+    opts = options as Record<string, unknown>;
+  } else {
+    return null;
+  }
+  const host = String(opts.hostname ?? opts.host ?? "").split(":")[0];
+  if (host !== "gemini.google.com" || opts.maxHeaderSize) return null;
+  opts.maxHeaderSize = 256 * 1024;
+  return opts;
+}
+
+let headerCapPatched = false;
+function patchHeaderCap(): void {
+  if (headerCapPatched) return;
+  headerCapPatched = true;
+  for (const mod of [http, https]) {
+    const real = mod.request as unknown as (...args: unknown[]) => unknown;
+    const patched = function (this: unknown, options: unknown, ...rest: unknown[]) {
+      try {
+        const override = injectGeminiHeaderCap(options);
+        if (override) return real.call(this, override, ...rest);
+      } catch { /* malformed input — let the real request surface the error */ }
+      return real.call(this, options, ...rest);
+    } as typeof mod.request;
+    mod.request = patched;
+  }
+}
+
+/** @internal exported for tests — resolves the real gemini-reverse module */
+export async function loadDefaultFactory(): Promise<GeminiClientFactory> {
+  patchHeaderCap();
+  const mod = (await import("gemini-reverse")) as unknown as Record<string, unknown>;
+  // CJS interop: named export usually works, but fall back to default.Gemini.
+  const Gemini = (mod.Gemini ?? (mod as { default?: Record<string, unknown> }).default?.Gemini) as
+    | (new (opts: Record<string, unknown>) => GeminiClientLike)
+    | undefined;
+  if (typeof Gemini !== "function") {
+    throw new Error("gemini-reverse: Gemini export not found (unexpected package shape)");
+  }
+  // ponytail: generous per-request cap (covers research); per-mode ask/research
+  // timeouts are enforced by raceGuard below.
+  return (opts) => new Gemini({ secure_1psid: opts.secure_1psid, proxy: opts.proxy ?? null, timeout: 1_800_000 });
+}
+
+async function getClient(config: GeminiWebConfig, factory?: GeminiClientFactory): Promise<GeminiClientLike> {
+  const key = `${config.psid ?? ""}|${config.proxy ?? ""}`;
+  if (cached?.key === key) return cached.client;
+  const make = factory ?? (await loadDefaultFactory());
+  const client = await make({ secure_1psid: config.psid, proxy: config.proxy });
+  cached = { key, client };
+  return client;
+}
+
+/** @internal test hook */
+export function __resetGeminiClientCache(): void {
+  cached = null;
+}
+
+function errorName(err: unknown): string {
+  const e = err as { name?: string; constructor?: { name?: string } } | null;
+  const name = e?.name;
+  // Subclasses that don't set this.name inherit the generic "Error" — prefer
+  // the constructor name in that case (how we detect upstream error classes).
+  if (name && name !== "Error") return name;
+  return e?.constructor?.name ?? name ?? "";
+}
+
+function isAuthError(err: unknown): boolean {
+  return errorName(err) === "AuthError";
+}
+
+// One AuthError retry: re-creating the client re-runs init, which absorbs the
+// rotated Set-Cookies (incl. __Secure-1PSIDTS) Google hands back.
+export async function withGeminiClient<T>(
+  config: GeminiWebConfig,
+  run: (client: GeminiClientLike) => Promise<T>,
+  factory?: GeminiClientFactory,
+): Promise<T> {
+  try {
+    return await run(await getClient(config, factory));
+  } catch (err) {
+    if (isAuthError(err) && config.psid) {
+      cached = null;
+      return run(await getClient(config, factory));
+    }
+    throw err;
+  }
+}
+
+// ponytail: gemini-reverse polls aren't cancellable — abort/timeout rejects the
+// tool call promptly, but the underlying client poll finishes/times out in the
+// background (ceiling; real cancellation needs upstream AbortSignal support).
+function raceGuard<T>(
+  promise: Promise<T>,
+  opts: { signal?: AbortSignal; timeoutMs?: number; label: string },
+): Promise<T> {
+  const { signal, timeoutMs, label } = opts;
+  if (!signal && !timeoutMs) return promise;
+  return new Promise<T>((resolve, reject) => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const onAbort = () => {
+      clearTimeout(timer);
+      const err = new Error(`${label} aborted`);
+      err.name = "AbortError";
+      reject(err);
+    };
+    const onTimeout = () => {
+      signal?.removeEventListener("abort", onAbort);
+      const err = new Error(`${label} timed out after ${timeoutMs}ms`);
+      err.name = "TimeoutError";
+      reject(err);
+    };
+    if (signal) {
+      if (signal.aborted) return onAbort();
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+    if (timeoutMs) timer = setTimeout(onTimeout, timeoutMs);
+    promise.then(
+      (v) => {
+        signal?.removeEventListener("abort", onAbort);
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        signal?.removeEventListener("abort", onAbort);
+        clearTimeout(timer);
+        reject(e);
+      },
+    );
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Source extraction (parsed web output has no structured citations field —
+// URLs are pulled from the answer/report markdown text)
+// ---------------------------------------------------------------------------
+
+const MD_LINK_RE = /\[[^\]]*\]\((https?:\/\/[^)\s]+)\)/g;
+const BARE_URL_RE = /https?:\/\/[^\s<>()\[\]{}"'`]+/g;
+
+export function extractSources(text: string, cap = 30): string[] {
+  if (!text) return [];
+  const seen = new Set<string>();
+  const sources: string[] = [];
+  const push = (raw: string) => {
+    const url = raw.replace(/[.,;:!?)\]]+$/, "");
+    if (!seen.has(url)) {
+      seen.add(url);
+      sources.push(url);
+    }
+  };
+  for (const m of text.matchAll(MD_LINK_RE)) push(m[1]);
+  for (const m of text.matchAll(BARE_URL_RE)) push(m[0]);
+  return sources.slice(0, cap);
+}
+
+// ---------------------------------------------------------------------------
+// Error mapping
+// ---------------------------------------------------------------------------
+
+export function describeGeminiError(err: unknown): string {
+  switch (errorName(err)) {
+    case "AuthError":
+      return "Gemini web cookie expired or invalid. Re-copy __Secure-1PSID from gemini.google.com (F12 → Application → Cookies) into GEMINI_WEB_SECURE_1PSID in ~/.pi/agent/.env.local, then restart pi.";
+    case "UsageLimitExceeded":
+      return "Gemini web usage limit reached. Try again later or pick a different model.";
+    case "TemporarilyBlocked":
+      return "Gemini web temporarily blocked this IP. Wait a while or set GEMINI_WEB_PROXY (e.g. http://host:port).";
+    case "ModelInvalid":
+      return "Gemini model unavailable for this account. Try another model or drop the model parameter.";
+    case "AbortError":
+    case "TimeoutError":
+      return err instanceof Error ? err.message : String(err);
+    default: {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (/Unknown API error/.test(msg)) {
+        return `Gemini web rejected the request (${msg}). In research mode this usually means the account lacks a Gemini Advanced subscription (Deep Research is Advanced-only) or the web protocol changed. mode=ask still works.`;
+      }
+      return `Gemini web error: ${msg}`;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface GeminiAskResult {
+  text: string;
+  model?: string;
+  guest: boolean;
+  sources: string[];
+}
+
+export async function geminiAsk(
+  query: string,
+  opts: { config: GeminiWebConfig; model?: string; timeoutMs?: number; signal?: AbortSignal; factory?: GeminiClientFactory },
+): Promise<GeminiAskResult> {
+  const out = await raceGuard(
+    withGeminiClient(
+      opts.config,
+      (client) => client.ask(query, { temporary: true, ...(opts.model ? { model: opts.model } : {}) }),
+      opts.factory,
+    ),
+    { signal: opts.signal, timeoutMs: opts.timeoutMs ?? 120_000, label: "web_research ask" },
+  );
+  const text = String(out?.text ?? out?.candidates?.[0]?.text ?? "");
+  return { text, model: out?.model, guest: !opts.config.psid, sources: extractSources(text) };
+}
+
+export interface GeminiResearchResult {
+  text: string;
+  title?: string | null;
+  eta?: string | null;
+  guest: boolean;
+  sources: string[];
+}
+
+export async function geminiResearch(
+  query: string,
+  opts: {
+    config: GeminiWebConfig;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    onStatus?: (s: Record<string, unknown>) => void;
+    factory?: GeminiClientFactory;
+  },
+): Promise<GeminiResearchResult> {
+  if (!opts.config.psid) {
+    throw new Error(
+      "Deep Research requires GEMINI_WEB_SECURE_1PSID (gemini.google.com cookie) in ~/.pi/agent/.env.local — guest mode does not support it. Deep Research also needs a Gemini Advanced subscription on the account.",
+    );
+  }
+  const timeoutMs = opts.timeoutMs ?? 600_000;
+  const result = await raceGuard(
+    withGeminiClient(
+      opts.config,
+      (client) =>
+        client.research(query, {
+          wait: true,
+          pollInterval: 10_000,
+          timeout: timeoutMs,
+          ...(opts.onStatus ? { onStatus: opts.onStatus } : {}),
+        }),
+      opts.factory,
+    ),
+    // +5s grace so the client's own poll-timeout (better semantics) fires first.
+    { signal: opts.signal, timeoutMs: timeoutMs + 5_000, label: "web_research research" },
+  );
+  const text = String(result?.text ?? "");
+  return {
+    text,
+    title: result?.plan?.title ?? null,
+    eta: result?.plan?.eta_text ?? null,
+    guest: false,
+    sources: extractSources(text),
+  };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bacnh85/pi-web",
-  "version": "0.7.1",
-  "description": "Pi extension for web search, page extraction, Firecrawl scraping/crawling, and Crawl4AI headless browser crawling.",
+  "version": "0.8.0",
+  "description": "Pi extension for web search, page extraction, Firecrawl scraping/crawling, Crawl4AI headless browser crawling, and Gemini web-tier research.",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -21,7 +21,9 @@
     "firecrawl",
     "crawl4ai",
     "scraping",
-    "crawling"
+    "crawling",
+    "gemini",
+    "deep-research"
   ],
   "scripts": {
     "test": "cd extensions && npx mocha"
@@ -44,6 +46,7 @@
   },
   "dependencies": {
     "@mozilla/readability": "^0.6.0",
+    "gemini-reverse": "^2.1.0",
     "jsdom": "^27.0.1",
     "turndown": "^7.2.2",
     "turndown-plugin-gfm": "^1.0.2"

package/skills/pi-web/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: pi-web
-description: Web search, content extraction, site crawling, and page capture via the pi-web extension. Use when the user needs current web search results, documentation lookup, factual research, source discovery, URL-to-markdown extraction, JSON extraction from websites, site URL discovery, site crawling, or page screenshots/PDFs. Use when the user mentions searching the web, finding docs, looking something up, researching, scraping/extracting content from a URL, or capturing a page.
+description: Web search, content extraction, site crawling, page capture, and Gemini web-tier research via the pi-web extension. Use when the user needs current web search results, documentation lookup, factual research, AI-synthesized research with sources (Gemini Deep Research), source discovery, URL-to-markdown extraction, JSON extraction from websites, site URL discovery, site crawling, or page screenshots/PDFs. Use when the user mentions searching the web, finding docs, looking something up, researching deeply, scraping/extracting content from a URL, or capturing a page.
 ---
 
 # pi-web — Unified Web Tools
 
-Use the **7 unified tools** from the `pi-web` extension for all web-related tasks. These tools automatically select the best backend from SearXNG, Brave Search, Firecrawl, Crawl4AI, and agy (when installed) — you don't need to know which backend to use. Search selection is adaptive: broad discovery prefers self-hosted SearXNG, while precision-sensitive queries and inline content prefer Brave.
+Use the **8 unified tools** from the `pi-web` extension for all web-related tasks. These tools automatically select the best backend from SearXNG, Brave Search, Firecrawl, Crawl4AI, and agy (when installed) — you don't need to know which backend to use. Search selection is adaptive: broad discovery prefers self-hosted SearXNG, while precision-sensitive queries and inline content prefer Brave.
 
 ## Quick Reference
 
@@ -17,6 +17,7 @@ Use the **7 unified tools** from the `pi-web` extension for all web-related task
 | `web_crawl` | Crawl multiple pages from a site | Light (Firecrawl) or Full (Crawl4AI) |
 | `web_screenshot` | Capture page screenshot as PNG | Crawl4AI daemon (public URLs) or local headless Chrome (localhost/LAN/file URLs — auto-detected) |
 | `web_pdf` | Generate page PDF | Crawl4AI daemon (public URLs) or local headless Chrome (localhost/LAN/file URLs — auto-detected) |
+| `web_research` | AI-synthesized research with sources | Gemini web tier: ask = grounded answer (guest OK); research = Deep Research report (cookie + Gemini Advanced) |
 | `web_status` | Check provider configuration and health | — |
 
 ## Decision Tree
@@ -53,6 +54,11 @@ What do you need?
 ├── Printable/archivable PDF of a page
 │   → web_pdf
 │
+├── AI-synthesized research with sources (synthesis, comparisons, reports)
+│   → web_research
+│     ├─ quick grounded answer: mode=ask (default; guest OK, Flash-only)
+│     └─ multi-minute Deep Research report: mode=research (needs cookie + Gemini Advanced)
+│
 └── Check what web tools are configured
     → web_status
 ```