@bacnh85/pi-web 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.9.2 (2026-09-13)
+
+### Fixed
+
+Review hardening of the `web_image` fallback chain (3 review rounds):
+
+- **Cancellation semantics**: an aborted call now surfaces `AbortError`
+  immediately — before any provider client construction or fetch — instead of
+  walking the chain and reporting "all providers failed". An abort landing
+  mid-generation normalizes to `AbortError` with the in-flight provider error
+  preserved as `cause`; foreign abort-named errors from upstreams are recorded
+  as provider notes and the chain continues.
+- **`n` transparency**: when the gemini web tier returns fewer images than the
+  requested `n`, the result states it explicitly (`n` applies to the
+  `zai`/`custom` API providers; the gemini web tier returns its own count).
+  `out_dir` now resolves against the session cwd, not the process cwd.
+
+## 0.9.1 (2026-09-13)
+
+### Fixed
+
+- **`zai` default model is `glm-image`** (live-verified against
+  `api.z.ai/api/paas/v4/images/generations` — the endpoint rejects
+  `cogview-4`/`cogview-3-flash` with "Unknown Model"; GLM-Image returns
+  URL results).
+- **Failed image downloads no longer waste the generation** — some upstreams
+  return URL-only results and the CDN can be unreachable from the local
+  network (e.g. `mfile.z.ai` DNS-sinkholed). The tool now reports
+  "Not saved (image host unreachable…)" with the URL instead of failing the
+  provider; inline image blocks are still attached for saved files.
+
 ## 0.9.0 (2026-09-13)
 
 ### Added
@@ -7,7 +38,7 @@
 - **`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`)
+  or cookie auth) → `zai` (official `api.z.ai` GLM-Image 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.

package/README.md

@@ -32,7 +32,7 @@ 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 |
+| `ZAI_API_KEY` | No (5) | — | Z.ai API key — enables the `web_image` `zai` provider (GLM-Image 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) |
@@ -273,8 +273,8 @@ 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")
+web_image(prompt="...", provider="zai")                       # pin GLM-Image via api.z.ai
+web_image(prompt="...", model="glm-image", n=2, out_dir="/tmp/imgs")
 ```
 
 **Provider chain** (`provider: "auto"` tries in order; pin one to skip):
@@ -282,7 +282,7 @@ web_image(prompt="...", model="cogview-4", n=2, out_dir="/tmp/imgs")
 | 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 |
+| `zai` | `https://api.z.ai/api/paas/v4` (official API) | `ZAI_API_KEY` | GLM-Image (`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
@@ -290,6 +290,9 @@ paths **plus inline image blocks** (multimodal models see the render
 immediately). `details` reports the winning provider, model, and fallback
 attempts.
 
+`n` (1–4) applies to the API providers (`zai`/`custom`); the Gemini web tier
+returns its own image count (surfaced as a provider note when fewer than `n`).
+
 **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).

package/extensions/index.ts

@@ -108,7 +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_image** — text→image generation via free upstreams (auto: Gemini web → Z.ai GLM-Image → 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.`;
@@ -529,8 +529,8 @@ export default function piWebExtension(pi: ExtensionAPI) {
     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)",
+      "Generate images from text via free upstream providers, with fallback: Gemini web (gemini.google.com, guest or cookie auth), Z.ai official API (GLM-Image 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 GLM-Image)",
     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.",
     ],
@@ -540,8 +540,8 @@ export default function piWebExtension(pi: ExtensionAPI) {
         [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." })),
+      model: Type.Optional(Type.String({ description: "Provider-specific model (e.g. glm-image, 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 (applies to zai/custom; the gemini web tier returns its own count)." })),
       out_dir: Type.Optional(Type.String({ description: "Directory for saved images (default: fresh temp dir)." })),
       ...sharedControlSchema,
     }),
@@ -552,7 +552,7 @@ export default function piWebExtension(pi: ExtensionAPI) {
       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))
+        ? path.resolve(cwd, String(params.out_dir))
         : await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-web-image-"));
       const result = await generateImageWithFallback({
         prompt,
@@ -571,13 +571,16 @@ export default function piWebExtension(pi: ExtensionAPI) {
         `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,
+        ...(result.urls.length
+          ? [`Not saved (image host unreachable from this machine — open directly):`, ...result.urls.map((u) => `  ${u}`)]
+          : []),
+        result.attempts.length ? `Provider notes: ${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 } };
+      return { content, details: { provider: result.provider, model: result.model, paths: result.paths, urls: result.urls, attempts: result.attempts } };
     },
   });
 

package/extensions/lib/imageapi.ts

@@ -1,5 +1,5 @@
 // Generic OpenAI-compatible images client + fallback chain for web_image.
-// Serves the `zai` preset (official api.z.ai, CogView-4) and any `custom`
+// Serves the `zai` preset (official api.z.ai, GLM-Image) and any `custom`
 // OpenAI-images endpoint — direct-to-upstream plain fetch, no self-host.
 
 import fs from "node:fs";
@@ -18,7 +18,7 @@ import {
 // Config
 // ---------------------------------------------------------------------------
 
-export const ZAI_PRESET = { baseUrl: "https://api.z.ai/api/paas/v4", defaultModel: "cogview-4" } as const;
+export const ZAI_PRESET = { baseUrl: "https://api.z.ai/api/paas/v4", defaultModel: "glm-image" } as const;
 
 export interface ImageApiConfig {
   zai?: { apiKey: string; source: string };
@@ -155,6 +155,8 @@ export interface FetchLike {
 
 export interface ApiImageResult {
   paths: string[];
+  /** Image URLs that could not be downloaded (e.g. CDN unreachable) — the generation still happened. */
+  urls: string[];
   model?: string;
 }
 
@@ -212,17 +214,25 @@ export async function apiGenerateImage(opts: {
   if (!items.length) throw new Error(`upstream returned no image data (model ${opts.model ?? "default"})`);
   fs.mkdirSync(opts.outDir, { recursive: true });
   const paths: string[] = [];
+  const urls: 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));
+      // A failed download must not waste the generation: surface the URL.
+      try {
+        paths.push(await downloadImage(fetchImpl, item.url, opts.outDir, i, opts.signal, opts.timeoutMs));
+      } catch (err) {
+        urls.push(item.url);
+        void err;
+      }
     } else {
       throw new Error(`image item ${i} had neither b64_json nor url`);
     }
   }
-  return { paths, model: typeof payload?.model === "string" ? payload.model : opts.model };
+  if (!paths.length && !urls.length) throw new Error(`upstream returned no image data (model ${opts.model ?? "default"})`);
+  return { paths, urls, model: typeof payload?.model === "string" ? payload.model : opts.model };
 }
 
 function writeB64(outDir: string, b64: string, i: number): string {
@@ -267,6 +277,7 @@ export interface ImageChainResult {
   provider: ImageProvider;
   model?: string;
   paths: string[];
+  urls: string[];
   attempts: string[];
 }
 
@@ -297,6 +308,13 @@ export async function generateImageWithFallback(params: ImageChainParams): Promi
   const chain = chainFor(params.provider);
   const attempts: string[] = [];
   for (const provider of chain) {
+    // Cancelled calls skip fallback entirely — before any provider client
+    // construction or fetch invocation.
+    if (params.signal?.aborted) {
+      const abortErr = new Error("web_image aborted");
+      abortErr.name = "AbortError";
+      throw abortErr;
+    }
     const configured =
       provider === "gemini" ? true : provider === "zai" ? Boolean(params.apiConfig.zai) : Boolean(params.apiConfig.custom);
     if (!configured) {
@@ -309,7 +327,7 @@ export async function generateImageWithFallback(params: ImageChainParams): Promi
       continue;
     }
     try {
-      let result: { paths: string[]; model?: string };
+      let result: { paths: string[]; urls?: string[]; model?: string };
       if (provider === "gemini") {
         result = await geminiGenerateImage(params.prompt, {
           config: params.geminiConfig,
@@ -345,8 +363,24 @@ export async function generateImageWithFallback(params: ImageChainParams): Promi
         });
       }
       imageRateRecord(provider);
-      return { provider, model: result.model, paths: result.paths, attempts };
+      if (provider === "gemini" && params.n && params.n > 1 && result.paths.length < params.n) {
+        attempts.push(`gemini: n=${params.n} requested — the gemini web tier returns its own image count (${result.paths.length}); n applies to zai/custom`);
+      }
+      return { provider, model: result.model, paths: result.paths, urls: result.urls ?? [], attempts };
     } catch (err) {
+      // Cancellation is not a provider failure: rethrow so aborted tool calls
+      // surface as AbortError instead of an "all providers failed" listing —
+      // even when a genuine provider error (AuthError, a failed save, …) was
+      // the error in flight when the abort landed.
+      if (params.signal?.aborted) {
+        if ((err as Error)?.name === "AbortError") throw err;
+        // cause keeps the in-flight provider error for diagnostics.
+        const abortErr = new Error("web_image aborted", { cause: err });
+        abortErr.name = "AbortError";
+        throw abortErr;
+      }
+      // A foreign AbortError-named error (not from the caller's signal) is a
+      // provider failure like any other — record it and keep the chain going.
       attempts.push(`${provider}: ${provider === "gemini" ? describeGeminiError(err) : describeImageApiError(err)}`);
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-web",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "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",

package/skills/pi-web/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pi-web
-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.
+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 GLM-Image), 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
@@ -18,7 +18,7 @@ Use the **9 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_image` | Generate images from a text prompt | Gemini web (guest/cookie) → Z.ai GLM-Image (`ZAI_API_KEY`) → custom OpenAI-images endpoint |
 | `web_status` | Check provider configuration and health | — |
 
 ## Decision Tree
@@ -62,8 +62,8 @@ What do you need?
 │
 ├── 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
+│     ├─ default: provider=auto (Gemini web → Z.ai GLM-Image → custom endpoint)
+│     └─ pin/model: provider=zai model=glm-image, or any custom OpenAI-images endpoint
 │
 └── Check what web tools are configured
     → web_status