@bacnh85/pi-web 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 0.9.0 (2026-09-13)
+
+### Added
+
+- **`web_image` tool** — image generation from text via free upstream
+  providers, all direct-to-upstream (no self-host services), with automatic
+  fallback: `gemini` (gemini.google.com web tier via `gemini-reverse`, guest
+  or cookie auth) → `zai` (official `api.z.ai` CogView-4 via `ZAI_API_KEY`)
+  → `custom` (any OpenAI-compatible `/images/generations` endpoint via
+  `WEB_IMAGE_API_BASE_URL`). `provider: "auto"` walks the chain and the
+  result reports every fallback attempt.
+- Results are saved as files (`out_dir`, default fresh temp dir) and returned
+  as **inline image blocks** so multimodal models see their own output;
+  `model`/`n` (1–4) parameters per call.
+- **Soft ToS guardrails** — per-provider `WEB_IMAGE_MIN_INTERVAL_MS`
+  (default 5000) and a `WEB_IMAGE_DAILY_CAP` (default 20/day) on the Gemini
+  web tier; successes-only counting, UTC-day reset, usage surfaced in
+  `web_status.imageProviders.rate`.
+- `web_status` now reports `imageProviders` (gemini/zai/custom config + rate
+  snapshot).
+- Smoke script: `image` and `zai` modes (prints saved paths + PNG magic-byte
+  check); ask/research modes now print **full answers and source URLs**
+  (previously sliced to a 200/400-char preview).
+
+## 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, Gemini web-tier research, and free upstream image generation**.
 
-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,20 @@ 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) |
+| `ZAI_API_KEY` | No (5) | — | Z.ai API key — enables the `web_image` `zai` provider (CogView-4 via the official `api.z.ai`); `Z_AI_API_KEY` also accepted |
+| `WEB_IMAGE_API_BASE_URL` | No | — | `web_image` `custom` provider: any OpenAI-compatible images endpoint (e.g. `https://api.openai.com/v1`) |
+| `WEB_IMAGE_API_KEY` | No | — | Bearer key for the `custom` endpoint |
+| `WEB_IMAGE_API_LABEL` | No | — | Display label for the `custom` endpoint (default: host name) |
+| `WEB_IMAGE_MIN_INTERVAL_MS` | No | `5000` | Min interval between `web_image` calls per provider |
+| `WEB_IMAGE_DAILY_CAP` | No | `20` | Daily soft cap for the Gemini **web tier** `web_image` provider (keyed APIs stay uncapped) |
 
 > (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.
+> (5) `web_image` works with zero config via Gemini guest mode (availability varies by region/account); `zai` activates when `ZAI_API_KEY` is present, `custom` when `WEB_IMAGE_API_BASE_URL` is set.
 
 Secrets are never printed; `web_status` reports only presence/source.
 
@@ -197,10 +207,105 @@ 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.
+
+### `web_image` — free upstream image generation
+
+Text → image with automatic provider fallback (all direct-to-upstream, no
+self-host services):
+
+```
+web_image(prompt="isometric cutaway of a container ship, technical illustration")
+web_image(prompt="...", provider="zai")                       # pin CogView-4 via api.z.ai
+web_image(prompt="...", model="cogview-4", n=2, out_dir="/tmp/imgs")
+```
+
+**Provider chain** (`provider: "auto"` tries in order; pin one to skip):
+
+| Provider | Upstream | Auth | Notes |
+|---|---|---|---|
+| `gemini` (default) | gemini.google.com web tier | none (guest) or `GEMINI_WEB_SECURE_1PSID` | free ≈ 20 images/day; availability varies by region/account |
+| `zai` | `https://api.z.ai/api/paas/v4` (official API) | `ZAI_API_KEY` | CogView-4 (`model` default), fully ToS-compliant |
+| `custom` | any OpenAI-compatible `/images/generations` endpoint | `WEB_IMAGE_API_KEY` | e.g. official OpenAI `https://api.openai.com/v1` |
+
+Results are saved to `out_dir` (default: fresh temp dir) and returned as file
+paths **plus inline image blocks** (multimodal models see the render
+immediately). `details` reports the winning provider, model, and fallback
+attempts.
+
+**Guardrails** (soft, in-memory): per-provider `WEB_IMAGE_MIN_INTERVAL_MS`
+(default 5 s) and a `WEB_IMAGE_DAILY_CAP` (default 20/day, applied to the
+Gemini web tier only — keyed APIs are billed upstream and stay uncapped).
+Counters reset on restart; `web_status.imageProviders.rate` shows usage.
+
+⚠️ **ToS reality (read once)**: *every* AI chatbot's terms prohibit automated
+access to its web UI (Google, OpenAI, xAI "unauthorized automated or
+non-human means", Z.ai alike). This tool therefore follows a risk ladder:
+
+1. **Official APIs** (`zai`, `custom`) — fully compliant; prefer them when a key exists.
+2. **Guest mode** (Gemini without a cookie) — no account at stake, lowest risk, Flash-tier.
+3. **Personal cookie** (Gemini authed) — your own account, single session, low volume; same accepted-risk stance as the web bridges: use a burner/low-value account, never a valued one. No account pools, no commercial use, keep volume human-scale.
+
+Smoke test: `npx tsx extensions/scripts/gemini-smoke.ts "a red cube on white background" image`
+(or `… zai` for the Z.ai path).
+
 ## Library structure
 
 | Module | Contents |

package/extensions/index.ts

@@ -1,5 +1,9 @@
 /// <reference path="./types.d.ts" />
 
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
@@ -21,6 +25,19 @@ import {
   formatUnifiedSearchResults,
 } from "./lib/format";
 import { searchWithDiagnostics } from "./lib/search";
+import {
+  loadGeminiWebConfig,
+  geminiAsk,
+  geminiResearch,
+  describeGeminiError,
+} from "./lib/gemini";
+import {
+  generateImageWithFallback,
+  loadImageApiConfig,
+  loadImageRateConfig,
+  imageRateSnapshot,
+  type ImageProvider,
+} from "./lib/imageapi";
 import { extractWithDiagnostics, type ExtractMode } from "./lib/extract";
 import { firecrawlRequest, type FirecrawlResult } from "./lib/firecrawl";
 import {
@@ -63,6 +80,19 @@ const engineSchema = {
   ], { default: "auto", description: "auto routes localhost/private/file URLs to local Chrome, the rest to the Crawl4AI daemon; local/daemon force one." })),
 };
 
+// Saved image file → inline image block (the 0.6.2 vision-loop lesson: the
+// generating model should see its own output).
+async function toImageBlock(file: string): Promise<{ type: "image"; data: string; mimeType: string }> {
+  const data = (await fs.promises.readFile(file)).toString("base64");
+  const lower = file.toLowerCase();
+  const mimeType = lower.endsWith(".jpg") || lower.endsWith(".jpeg")
+    ? "image/jpeg"
+    : lower.endsWith(".webp")
+      ? "image/webp"
+      : "image/png";
+  return { type: "image" as const, data, mimeType };
+}
+
 // ---------------------------------------------------------------------------
 // Always-on routing guidance (injected only when a web_* tool is active)
 // ---------------------------------------------------------------------------
@@ -77,6 +107,8 @@ 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_image** — text→image generation via free upstreams (auto: Gemini web → Z.ai CogView-4 → custom OpenAI-images endpoint; \`model\`/\`n\` params).
 - **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 +472,115 @@ 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_image ────────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "web_image",
+    label: "Web Image Generation",
+    description:
+      "Generate images from text via free upstream providers, with fallback: Gemini web (gemini.google.com, guest or cookie auth), Z.ai official API (CogView-4 via ZAI_API_KEY), or any custom OpenAI-compatible images endpoint (WEB_IMAGE_API_BASE_URL). Returns saved file paths plus the images inline.",
+    promptSnippet: "Generate images via free upstreams (Gemini web, Z.ai CogView)",
+    promptGuidelines: [
+      "Use for image GENERATION from a text prompt. provider auto falls back gemini → zai → custom. Capturing an EXISTING page is web_screenshot, not this.",
+    ],
+    parameters: Type.Object({
+      prompt: Type.String({ description: "Image description." }),
+      provider: Type.Optional(Type.Union(
+        [Type.Literal("auto"), Type.Literal("gemini"), Type.Literal("zai"), Type.Literal("custom")],
+        { default: "auto", description: "auto = gemini → zai (if ZAI_API_KEY) → custom (if WEB_IMAGE_API_BASE_URL); pin one to skip fallback." },
+      )),
+      model: Type.Optional(Type.String({ description: "Provider-specific model (e.g. cogview-4, or a Gemini image-capable model id). Omit for the provider default." })),
+      n: Type.Optional(Type.Number({ default: 1, description: "Number of images, 1-4." })),
+      out_dir: Type.Optional(Type.String({ description: "Directory for saved images (default: fresh temp dir)." })),
+      ...sharedControlSchema,
+    }),
+    async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
+      const cwd = cwdFromContext(ctx);
+      const trusted = includeProjectEnv(ctx);
+      const prompt = params.prompt as string;
+      const n = Math.min(Math.max(Math.trunc((params.n as number) ?? 1) || 1, 1), 4);
+      const timeoutMs = Math.min(Math.max((params.timeout_ms as number) ?? 180_000, 10_000), 600_000);
+      const outDir = params.out_dir
+        ? path.resolve(String(params.out_dir))
+        : await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-web-image-"));
+      const result = await generateImageWithFallback({
+        prompt,
+        model: params.model as string | undefined,
+        n,
+        outDir,
+        provider: (params.provider as "auto" | ImageProvider) ?? "auto",
+        geminiConfig: loadGeminiWebConfig(cwd, trusted),
+        apiConfig: loadImageApiConfig(cwd, trusted),
+        rateConfig: loadImageRateConfig(cwd, trusted),
+        timeoutMs,
+        signal,
+      });
+      const blocks = await Promise.all(result.paths.map(toImageBlock));
+      const text = [
+        `Provider: ${result.provider}${result.model ? ` (${result.model})` : ""}`,
+        `Saved: ${result.paths.length} image(s)`,
+        ...result.paths.map((p) => `  ${p}`),
+        result.attempts.length ? `Fallback attempts: ${result.attempts.join(" | ")}` : null,
+      ].filter(Boolean).join("\n");
+      const content: Array<{ type: "text"; text: string } | { type: "image"; data: string; mimeType: string }> = [
+        { type: "text" as const, text },
+        ...blocks,
+      ];
+      return { content, details: { provider: result.provider, model: result.model, paths: result.paths, attempts: result.attempts } };
+    },
+  });
+
   // ── web_status ───────────────────────────────────────────────────────
   pi.registerTool({
     name: "web_status",
@@ -460,6 +601,8 @@ export default function piWebExtension(pi: ExtensionAPI) {
       const fireUrl = findEnvValue("FIRECRAWL_API_URL", cwd, trusted);
       const c4aiUrl = findEnvValue("CRAWL4AI_API_URL", cwd, trusted);
       const c4aiToken = findEnvValue("CRAWL4AI_API_TOKEN", cwd, trusted);
+      const geminiCfg = loadGeminiWebConfig(cwd, trusted);
+      const imageApiCfg = loadImageApiConfig(cwd, trusted);
 
       const { isAgyInstalled } = await import("./lib/agy");
 
@@ -484,6 +627,15 @@ export default function piWebExtension(pi: ExtensionAPI) {
           apiTokenSource: c4aiToken.value ? c4aiToken.source : "not set",
         },
         agy: { installed: isAgyInstalled() },
+        geminiWeb: { configured: Boolean(geminiCfg.psid), cookieSource: geminiCfg.psidSource, proxy: Boolean(geminiCfg.proxy) },
+        imageProviders: {
+          gemini: { configured: Boolean(geminiCfg.psid), guestPossible: true },
+          zai: { configured: Boolean(imageApiCfg.zai) },
+          custom: imageApiCfg.custom
+            ? { configured: true, label: imageApiCfg.custom.label }
+            : { configured: false },
+          rate: imageRateSnapshot(),
+        },
         localChrome: { path: findChromeBinary() ?? "not found" },
       };
 

package/extensions/lib/gemini.ts

@@ -0,0 +1,407 @@
+// 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 GeminiImageLike {
+  save(opts?: { path?: string; filename?: string }): Promise<string>;
+  url?: string;
+  alt?: string;
+}
+
+export interface GeminiImageOutputLike {
+  text?: string | null;
+  model?: string;
+  images?: GeminiImageLike[];
+  generated_images?: GeminiImageLike[];
+}
+
+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>;
+  // Optional so pre-0.9 fake clients (ask+research only) keep compiling.
+  newChat?(opts?: { model?: string }): {
+    generateContent(o: { prompt: string }): Promise<GeminiImageOutputLike>;
+  };
+}
+
+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).
+// Shared with lib/imageapi.ts (same abort semantics for plain fetch calls).
+export 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),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Image generation (free web tier): prompt → GeneratedImage.save() paths
+// ---------------------------------------------------------------------------
+
+export interface GeminiImageResult {
+  paths: string[];
+  model?: string;
+  guest: boolean;
+  text: string;
+}
+
+export async function geminiGenerateImage(
+  prompt: string,
+  opts: {
+    config: GeminiWebConfig;
+    outDir: string;
+    model?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    factory?: GeminiClientFactory;
+  },
+): Promise<GeminiImageResult> {
+  const out = await raceGuard(
+    withGeminiClient(
+      opts.config,
+      async (client) => {
+        if (typeof client.newChat !== "function") {
+          throw new Error("gemini-reverse client exposes no newChat (unexpected package shape)");
+        }
+        const chat = client.newChat(opts.model ? { model: opts.model } : undefined);
+        return chat.generateContent({ prompt });
+      },
+      opts.factory,
+    ),
+    { signal: opts.signal, timeoutMs: opts.timeoutMs ?? 180_000, label: "web_image gemini" },
+  );
+  const images = out?.generated_images ?? out?.images ?? [];
+  const text = String(out?.text ?? "");
+  if (!images.length) {
+    throw new Error(
+      text
+        ? `Gemini replied with text but no images: ${text.slice(0, 200)} — image generation is likely unavailable for this account/region (it is for some Google accounts); try provider=zai (ZAI_API_KEY) or provider=custom.`
+        : "Gemini returned no images — generation may be unavailable for this account/region (guest mode may not support it; set GEMINI_WEB_SECURE_1PSID).",
+    );
+  }
+  const paths: string[] = [];
+  for (const img of images) paths.push(await img.save({ path: opts.outDir }));
+  return { paths, model: out?.model, guest: !opts.config.psid, text };
+}

package/extensions/lib/imageapi.ts

@@ -0,0 +1,354 @@
+// Generic OpenAI-compatible images client + fallback chain for web_image.
+// Serves the `zai` preset (official api.z.ai, CogView-4) and any `custom`
+// OpenAI-images endpoint — direct-to-upstream plain fetch, no self-host.
+
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { findEnvValue } from "./config";
+import {
+  describeGeminiError,
+  geminiGenerateImage,
+  raceGuard,
+  type GeminiClientFactory,
+  type GeminiWebConfig,
+} from "./gemini";
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+export const ZAI_PRESET = { baseUrl: "https://api.z.ai/api/paas/v4", defaultModel: "cogview-4" } as const;
+
+export interface ImageApiConfig {
+  zai?: { apiKey: string; source: string };
+  custom?: { baseUrl: string; apiKey?: string; label: string; source: string };
+}
+
+export function loadImageApiConfig(cwd = process.cwd(), includeCwdEnv = false): ImageApiConfig {
+  const zaiKey = findEnvValue("ZAI_API_KEY", cwd, includeCwdEnv);
+  const zaiFound = zaiKey.value ? zaiKey : findEnvValue("Z_AI_API_KEY", cwd, includeCwdEnv);
+  const base = findEnvValue("WEB_IMAGE_API_BASE_URL", cwd, includeCwdEnv);
+  const key = findEnvValue("WEB_IMAGE_API_KEY", cwd, includeCwdEnv);
+  const label = findEnvValue("WEB_IMAGE_API_LABEL", cwd, includeCwdEnv);
+  const cfg: ImageApiConfig = {};
+  if (zaiFound.value) cfg.zai = { apiKey: zaiFound.value, source: zaiFound.source };
+  if (base.value) {
+    cfg.custom = {
+      baseUrl: base.value.replace(/\/+$/, ""),
+      ...(key.value ? { apiKey: key.value } : {}),
+      label: label.value || hostOf(base.value),
+      source: base.source,
+    };
+  }
+  return cfg;
+}
+
+function hostOf(url: string): string {
+  try {
+    return new URL(url).host;
+  } catch {
+    return url;
+  }
+}
+
+export interface ImageRateConfig {
+  minIntervalMs: number;
+  dailyCap: number; // applies to the gemini web tier only — keyed APIs stay uncapped
+}
+
+export function loadImageRateConfig(cwd = process.cwd(), includeCwdEnv = false): ImageRateConfig {
+  const interval = findEnvValue("WEB_IMAGE_MIN_INTERVAL_MS", cwd, includeCwdEnv);
+  const cap = findEnvValue("WEB_IMAGE_DAILY_CAP", cwd, includeCwdEnv);
+  const intervalNum = Number(interval.value);
+  const capNum = Number(cap.value);
+  return {
+    minIntervalMs: interval.value && Number.isFinite(intervalNum) ? Math.max(0, Math.trunc(intervalNum)) : 5000,
+    dailyCap: cap.value && Number.isFinite(capNum) ? Math.max(1, Math.trunc(capNum)) : 20,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Soft rate guardrails (in-memory, reset on restart). Successful generations
+// only — failures don't consume quota.
+// ---------------------------------------------------------------------------
+
+interface RateState {
+  lastAt: number;
+  day: string;
+  count: number;
+}
+
+const rate = new Map<string, RateState>();
+let nowMs = () => Date.now();
+
+/** @internal test hooks */
+export function __setImageRateClock(fn: () => number): void {
+  nowMs = fn;
+}
+
+/** @internal test hooks */
+export function __resetImageRate(): void {
+  rate.clear();
+  nowMs = () => Date.now();
+}
+
+const utcDay = (ts: number) => new Date(ts).toISOString().slice(0, 10);
+
+function msUntilUtcRoll(ts: number): number {
+  const d = new Date(ts);
+  return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() + 1) - ts;
+}
+
+export type RateVerdict = { ok: true } | { ok: false; reason: string; retryAfterMs: number };
+
+export function imageRateCheck(provider: "gemini" | "zai" | "custom", rateCfg: ImageRateConfig): RateVerdict {
+  const state = rate.get(provider);
+  const ts = nowMs();
+  if (state && rateCfg.minIntervalMs > 0) {
+    const elapsed = ts - state.lastAt;
+    if (elapsed < rateCfg.minIntervalMs) {
+      return {
+        ok: false,
+        reason: `min interval ${rateCfg.minIntervalMs}ms between calls (elapsed ${elapsed}ms, WEB_IMAGE_MIN_INTERVAL_MS)`,
+        retryAfterMs: rateCfg.minIntervalMs - elapsed,
+      };
+    }
+  }
+  if (provider === "gemini" && state && state.day === utcDay(ts) && state.count >= rateCfg.dailyCap) {
+    return {
+      ok: false,
+      reason: `daily soft cap reached (${rateCfg.dailyCap}/day, WEB_IMAGE_DAILY_CAP)`,
+      retryAfterMs: msUntilUtcRoll(ts),
+    };
+  }
+  return { ok: true };
+}
+
+export function imageRateRecord(provider: "gemini" | "zai" | "custom", count = 1): void {
+  const ts = nowMs();
+  const day = utcDay(ts);
+  const prev = rate.get(provider);
+  const sameDay = prev?.day === day;
+  rate.set(provider, { lastAt: ts, day, count: (sameDay ? prev!.count : 0) + count });
+}
+
+export function imageRateSnapshot(): Record<string, { count: number; day: string; msSinceLast: number }> {
+  const ts = nowMs();
+  const out: Record<string, { count: number; day: string; msSinceLast: number }> = {};
+  for (const [provider, s] of rate) {
+    out[provider] = { count: s.day === utcDay(ts) ? s.count : 0, day: s.day, msSinceLast: Math.max(0, ts - s.lastAt) };
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Single-provider OpenAI-images call (POST {base}/images/generations)
+// ---------------------------------------------------------------------------
+
+export interface FetchLike {
+  (
+    url: string,
+    init?: { method?: string; headers?: Record<string, string>; body?: string; signal?: AbortSignal },
+  ): Promise<{ ok: boolean; status: number; statusText?: string; json(): Promise<unknown>; arrayBuffer(): Promise<ArrayBuffer> }>;
+}
+
+export interface ApiImageResult {
+  paths: string[];
+  model?: string;
+}
+
+export class ImageApiError extends Error {
+  constructor(
+    public status: number,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export function describeImageApiError(err: unknown): string {
+  if (err instanceof ImageApiError) {
+    if (err.status === 401 || err.status === 403) return `upstream rejected the API key (HTTP ${err.status}): ${err.message}`;
+    if (err.status === 429) return `upstream rate limit/quota exhausted (HTTP 429): ${err.message}`;
+    if (err.status >= 500) return `upstream server error (HTTP ${err.status}): ${err.message}`;
+    return `upstream error (HTTP ${err.status}): ${err.message}`;
+  }
+  return err instanceof Error ? err.message : String(err);
+}
+
+export async function apiGenerateImage(opts: {
+  baseUrl: string;
+  apiKey?: string;
+  model?: string;
+  prompt: string;
+  n?: number;
+  outDir: string;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  fetchImpl?: FetchLike;
+}): Promise<ApiImageResult> {
+  const fetchImpl = opts.fetchImpl ?? (fetch as FetchLike);
+  const url = `${opts.baseUrl.replace(/\/+$/, "")}/images/generations`;
+  const res = await raceGuard(
+    fetchImpl(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...(opts.apiKey ? { Authorization: `Bearer ${opts.apiKey}` } : {}) },
+      body: JSON.stringify({ model: opts.model, prompt: opts.prompt, n: opts.n ?? 1 }),
+      signal: opts.signal,
+    }),
+    { signal: opts.signal, timeoutMs: opts.timeoutMs ?? 180_000, label: "web_image api" },
+  );
+  const payload = (await res.json().catch(() => null)) as Record<string, unknown> | null;
+  if (!res.ok) {
+    const errObj = payload?.error as { message?: string } | undefined;
+    const msg =
+      errObj?.message ??
+      (typeof payload?.message === "string" ? payload.message : undefined) ??
+      (payload ? JSON.stringify(payload).slice(0, 300) : res.statusText ?? "");
+    throw new ImageApiError(res.status, String(msg));
+  }
+  const items = Array.isArray(payload?.data) ? (payload!.data as Array<Record<string, unknown>>) : [];
+  if (!items.length) throw new Error(`upstream returned no image data (model ${opts.model ?? "default"})`);
+  fs.mkdirSync(opts.outDir, { recursive: true });
+  const paths: string[] = [];
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i];
+    if (typeof item?.b64_json === "string" && item.b64_json) {
+      paths.push(writeB64(opts.outDir, item.b64_json, i));
+    } else if (typeof item?.url === "string" && item.url) {
+      paths.push(await downloadImage(fetchImpl, item.url, opts.outDir, i, opts.signal, opts.timeoutMs));
+    } else {
+      throw new Error(`image item ${i} had neither b64_json nor url`);
+    }
+  }
+  return { paths, model: typeof payload?.model === "string" ? payload.model : opts.model };
+}
+
+function writeB64(outDir: string, b64: string, i: number): string {
+  const file = path.join(outDir, `pi-web-image-${randomUUID().slice(0, 8)}-${i}.png`);
+  fs.writeFileSync(file, Buffer.from(b64, "base64"));
+  return file;
+}
+
+async function downloadImage(
+  fetchImpl: FetchLike,
+  url: string,
+  outDir: string,
+  i: number,
+  signal?: AbortSignal,
+  timeoutMs?: number,
+): Promise<string> {
+  const res = await raceGuard(fetchImpl(url, { method: "GET", signal }), {
+    signal,
+    timeoutMs: timeoutMs ?? 120_000,
+    label: "web_image download",
+  });
+  if (!res.ok) throw new ImageApiError(res.status, `image download failed (HTTP ${res.status})`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  const file = path.join(outDir, `pi-web-image-${randomUUID().slice(0, 8)}-${i}${extFor(url)}`);
+  fs.writeFileSync(file, buf);
+  return file;
+}
+
+function extFor(url: string): string {
+  const m = /\.(png|jpe?g|webp|gif)(\?|$)/i.exec(url);
+  const ext = (m?.[1] ?? "png").toLowerCase();
+  return `.${ext === "jpeg" ? "jpg" : ext}`;
+}
+
+// ---------------------------------------------------------------------------
+// Fallback chain: gemini (free web tier) → zai (official API) → custom
+// ---------------------------------------------------------------------------
+
+export type ImageProvider = "gemini" | "zai" | "custom";
+
+export interface ImageChainResult {
+  provider: ImageProvider;
+  model?: string;
+  paths: string[];
+  attempts: string[];
+}
+
+export interface ImageChainParams {
+  prompt: string;
+  model?: string;
+  n?: number;
+  outDir: string;
+  provider: "auto" | ImageProvider;
+  geminiConfig: GeminiWebConfig;
+  apiConfig: ImageApiConfig;
+  rateConfig: ImageRateConfig;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  /** @internal test injection */
+  geminiFactory?: GeminiClientFactory;
+  /** @internal test injection */
+  fetchImpl?: FetchLike;
+}
+
+function chainFor(provider: "auto" | ImageProvider): ImageProvider[] {
+  // Auto includes ALL providers: unconfigured ones contribute "not configured
+  // (set …)" hints to the aggregated error instead of vanishing silently.
+  return provider === "auto" ? ["gemini", "zai", "custom"] : [provider];
+}
+
+export async function generateImageWithFallback(params: ImageChainParams): Promise<ImageChainResult> {
+  const chain = chainFor(params.provider);
+  const attempts: string[] = [];
+  for (const provider of chain) {
+    const configured =
+      provider === "gemini" ? true : provider === "zai" ? Boolean(params.apiConfig.zai) : Boolean(params.apiConfig.custom);
+    if (!configured) {
+      attempts.push(`${provider}: not configured${provider === "zai" ? " (set ZAI_API_KEY)" : " (set WEB_IMAGE_API_BASE_URL)"}`);
+      continue;
+    }
+    const rate = imageRateCheck(provider, params.rateConfig);
+    if (!rate.ok) {
+      attempts.push(`${provider}: skipped — ${rate.reason}`);
+      continue;
+    }
+    try {
+      let result: { paths: string[]; model?: string };
+      if (provider === "gemini") {
+        result = await geminiGenerateImage(params.prompt, {
+          config: params.geminiConfig,
+          outDir: params.outDir,
+          model: params.model,
+          timeoutMs: params.timeoutMs,
+          signal: params.signal,
+          factory: params.geminiFactory,
+        });
+      } else if (provider === "zai") {
+        result = await apiGenerateImage({
+          baseUrl: ZAI_PRESET.baseUrl,
+          apiKey: params.apiConfig.zai!.apiKey,
+          model: params.model ?? ZAI_PRESET.defaultModel,
+          prompt: params.prompt,
+          n: params.n,
+          outDir: params.outDir,
+          timeoutMs: params.timeoutMs,
+          signal: params.signal,
+          fetchImpl: params.fetchImpl,
+        });
+      } else {
+        result = await apiGenerateImage({
+          baseUrl: params.apiConfig.custom!.baseUrl,
+          apiKey: params.apiConfig.custom!.apiKey,
+          model: params.model,
+          prompt: params.prompt,
+          n: params.n,
+          outDir: params.outDir,
+          timeoutMs: params.timeoutMs,
+          signal: params.signal,
+          fetchImpl: params.fetchImpl,
+        });
+      }
+      imageRateRecord(provider);
+      return { provider, model: result.model, paths: result.paths, attempts };
+    } catch (err) {
+      attempts.push(`${provider}: ${provider === "gemini" ? describeGeminiError(err) : describeImageApiError(err)}`);
+    }
+  }
+  throw new Error(`All image providers failed:\n${attempts.map((a) => `- ${a}`).join("\n")}`);
+}

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.9.0",
+  "description": "Pi extension for web search, page extraction, Firecrawl scraping/crawling, Crawl4AI headless browser crawling, Gemini web-tier research, and free upstream image generation.",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -21,7 +21,12 @@
     "firecrawl",
     "crawl4ai",
     "scraping",
-    "crawling"
+    "crawling",
+    "gemini",
+    "deep-research",
+    "image-generation",
+    "zai",
+    "cogview"
   ],
   "scripts": {
     "test": "cd extensions && npx mocha"
@@ -44,6 +49,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, Gemini web-tier research, and free upstream image generation 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), image generation from text (Gemini web, Z.ai CogView-4), 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, generating/creating an image, 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 **9 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,8 @@ 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_image` | Generate images from a text prompt | Gemini web (guest/cookie) → Z.ai CogView-4 (`ZAI_API_KEY`) → custom OpenAI-images endpoint |
 | `web_status` | Check provider configuration and health | — |
 
 ## Decision Tree
@@ -53,6 +55,16 @@ 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)
+│
+├── Generate an image from a text prompt (NOT capturing an existing page)
+│   → web_image
+│     ├─ default: provider=auto (Gemini web → Z.ai CogView-4 → custom endpoint)
+│     └─ pin/model: provider=zai model=cogview-4, or any custom OpenAI-images endpoint
+│
 └── Check what web tools are configured
     → web_status
 ```