@bacnh85/pi-web 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # 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

package/README.md

@@ -1,6 +1,6 @@
 # @bacnh85/pi-web
 
-Pi extension for **unified web search, content extraction, site crawling, page capture, and Gemini web-tier research**.
+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. `web_research` adds AI-synthesized research with citations via your gemini.google.com session.
 
@@ -32,11 +32,18 @@ Variables:
 | `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.
 
@@ -259,6 +266,46 @@ Troubleshooting:
   (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";
 
@@ -27,6 +31,13 @@ import {
   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 {
@@ -69,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)
 // ---------------------------------------------------------------------------
@@ -84,6 +108,7 @@ const WEB_ROUTING_GUIDANCE = `## Web Tool Routing (pi-web)
 - **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.`;
@@ -499,6 +524,63 @@ export default function piWebExtension(pi: ExtensionAPI) {
     },
   });
 
+  // ── 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",
@@ -519,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");
 
@@ -543,10 +627,15 @@ 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) };
-        })(),
+        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

@@ -40,12 +40,29 @@ export interface GeminiResearchLike {
   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 = (
@@ -171,7 +188,8 @@ export async function withGeminiClient<T>(
 // 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>(
+// 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> {
@@ -337,3 +355,53 @@ export async function geminiResearch(
     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.8.0",
-  "description": "Pi extension for web search, page extraction, Firecrawl scraping/crawling, Crawl4AI headless browser crawling, and Gemini web-tier research.",
+  "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": {
@@ -23,7 +23,10 @@
     "scraping",
     "crawling",
     "gemini",
-    "deep-research"
+    "deep-research",
+    "image-generation",
+    "zai",
+    "cogview"
   ],
   "scripts": {
     "test": "cd extensions && npx mocha"

package/skills/pi-web/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: pi-web
-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.
+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 **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.
+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
 
@@ -18,6 +18,7 @@ Use the **8 unified tools** from the `pi-web` extension for all web-related task
 | `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
@@ -59,6 +60,11 @@ What do you need?
 │     ├─ 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
 ```