@bacnh85/pi-web 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.10.0 (2026-09-13)
+
+### Added
+
+- **`web_chat` tool** — one-off chat completion against any OpenAI-compatible
+  gateway (`WEB_CHAT_API_BASE_URL` + optional `WEB_CHAT_API_KEY`): a ChatGPT
+  web bridge, official OpenAI (`https://api.openai.com/v1`), or any web2api
+  gateway. Non-streaming `POST /chat/completions` with optional `model`/
+  `system`; timeout capped at 300 s. Error mapping: 401/403 key hint,
+  429 quota, 502 → "empty account pool" hint, 5xx server error.
+- `web_status` now reports `webChat` (configured/baseUrl/keyFound/source).
+
+Supersedes the removed `pi-chatgpt-web` package (free web-chat-only models):
+point `WEB_CHAT_API_BASE_URL` at the same gateway to keep using it.
+
+## 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

package/README.md

@@ -1,6 +1,6 @@
 # @bacnh85/pi-web
 
-Pi extension for **unified web search, content extraction, site crawling, page capture, Gemini web-tier research, and free upstream image generation**.
+Pi extension for **unified web search, content extraction, site crawling, page capture, Gemini web-tier research, free upstream image generation, and one-off gateway chat**.
 
 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.
 
@@ -38,6 +38,8 @@ Variables:
 | `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) |
+| `WEB_CHAT_API_BASE_URL` | No | — | `web_chat`: any OpenAI-compatible `/chat/completions` gateway (a ChatGPT web bridge, `https://api.openai.com/v1`, …) |
+| `WEB_CHAT_API_KEY` | No | — | Bearer key for the `web_chat` gateway |
 
 > (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.
@@ -290,6 +292,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).
@@ -306,6 +311,28 @@ non-human means", Z.ai alike). This tool therefore follows a risk ladder:
 Smoke test: `npx tsx extensions/scripts/gemini-smoke.ts "a red cube on white background" image`
 (or `… zai` for the Z.ai path).
 
+### `web_chat` — one-off gateway chat
+
+Single non-streaming chat completion against any OpenAI-compatible gateway —
+the in-session equivalent of "ask another model quickly" without switching
+your main provider:
+
+```
+web_chat(prompt="In one sentence: why is idempotency key needed here?")
+web_chat(prompt="Summarize", model="gpt-5.3-mini", system="Be terse")
+```
+
+Configure once in `~/.pi/agent/.env.local`, then restart pi:
+
+```bash
+WEB_CHAT_API_BASE_URL=https://api.openai.com/v1   # or any OpenAI-compatible gateway
+WEB_CHAT_API_KEY=sk-...                           # if the gateway needs a key
+```
+
+`web_status.webChat` shows configuration without printing secrets. Chat-only
+by design (no tool calling through gateways); for grounded research with
+sources use `web_research`, and `/model` switches your main model.
+
 ## Library structure
 
 | Module | Contents |

package/extensions/index.ts

@@ -38,6 +38,11 @@ import {
   imageRateSnapshot,
   type ImageProvider,
 } from "./lib/imageapi";
+import {
+  chatgptChat,
+  describeChatApiError,
+  loadChatConfig,
+} from "./lib/chatapi";
 import { extractWithDiagnostics, type ExtractMode } from "./lib/extract";
 import { firecrawlRequest, type FirecrawlResult } from "./lib/firecrawl";
 import {
@@ -109,6 +114,7 @@ const WEB_ROUTING_GUIDANCE = `## Web Tool Routing (pi-web)
 - **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 GLM-Image → custom OpenAI-images endpoint; \`model\`/\`n\` params).
+- **web_chat** — one-off chat completion via an OpenAI-compatible gateway (\`WEB_CHAT_API_BASE_URL\`; non-streaming).
 - **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.`;
@@ -541,7 +547,7 @@ export default function piWebExtension(pi: ExtensionAPI) {
         { 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. 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." })),
+      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 +558,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,
@@ -574,7 +580,7 @@ export default function piWebExtension(pi: ExtensionAPI) {
         ...(result.urls.length
           ? [`Not saved (image host unreachable from this machine — open directly):`, ...result.urls.map((u) => `  ${u}`)]
           : []),
-        result.attempts.length ? `Fallback attempts: ${result.attempts.join(" | ")}` : null,
+        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 },
@@ -584,6 +590,51 @@ export default function piWebExtension(pi: ExtensionAPI) {
     },
   });
 
+  // ── web_chat ─────────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "web_chat",
+    label: "Web Chat (gateway)",
+    description:
+      "One-off chat completion via an OpenAI-compatible gateway (WEB_CHAT_API_BASE_URL — a ChatGPT web bridge, official OpenAI, or any web2api gateway). Non-streaming Q&A; not a provider — use /model to switch your main model.",
+    promptSnippet: "One-off chat via OpenAI-compatible gateway",
+    promptGuidelines: [
+      "Use for a quick one-off second opinion, classification, or short generation call. Grounded research with sources → web_research; switching your main chat model → /model.",
+    ],
+    parameters: Type.Object({
+      prompt: Type.String({ description: "The question or instruction." }),
+      model: Type.Optional(Type.String({ description: "Gateway model id (e.g. gpt-5.3-mini). Omit for the gateway default." })),
+      system: Type.Optional(Type.String({ description: "Optional system prompt." })),
+      ...sharedControlSchema,
+    }),
+    async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
+      const cwd = cwdFromContext(ctx);
+      const trusted = includeProjectEnv(ctx);
+      const config = loadChatConfig(cwd, trusted);
+      if (!config) {
+        throw new Error(
+          "web_chat is not configured. Set WEB_CHAT_API_BASE_URL (and optional WEB_CHAT_API_KEY) in ~/.pi/agent/.env.local — any OpenAI-compatible /chat/completions gateway works (a ChatGPT web bridge, https://api.openai.com/v1, …) — then restart pi.",
+        );
+      }
+      const timeoutMs = Math.min(Math.max((params.timeout_ms as number) ?? 120_000, 10_000), 300_000);
+      try {
+        const result = await chatgptChat({
+          baseUrl: config.baseUrl,
+          apiKey: config.apiKey,
+          prompt: params.prompt as string,
+          model: params.model as string | undefined,
+          system: params.system as string | undefined,
+          timeoutMs,
+          signal,
+        });
+        const text = `Model: ${result.model ?? "gateway default"}\n\n${result.text}`;
+        return { content: [{ type: "text" as const, text: truncateText(text) }], details: { model: result.model } };
+      } catch (err) {
+        if ((err as Error)?.name === "AbortError") throw err;
+        throw new Error(describeChatApiError(err));
+      }
+    },
+  });
+
   // ── web_status ───────────────────────────────────────────────────────
   pi.registerTool({
     name: "web_status",
@@ -639,6 +690,15 @@ export default function piWebExtension(pi: ExtensionAPI) {
             : { configured: false },
           rate: imageRateSnapshot(),
         },
+        webChat: (() => {
+          const cfg = loadChatConfig(cwd, trusted);
+          return {
+            configured: Boolean(cfg),
+            baseUrl: cfg?.baseUrl,
+            keyFound: Boolean(cfg?.apiKey),
+            source: cfg?.source ?? "not set",
+          };
+        })(),
         localChrome: { path: findChromeBinary() ?? "not found" },
       };
 

package/extensions/lib/chatapi.ts

@@ -0,0 +1,100 @@
+// Generic OpenAI-compatible chat client for web_chat — one-off Q&A against
+// any OpenAI-compatible /chat/completions gateway (WEB_CHAT_API_BASE_URL):
+// a ChatGPT web bridge, official OpenAI, or any web2api gateway.
+
+import { findEnvValue } from "./config";
+import { raceGuard } from "./gemini";
+import type { FetchLike } from "./imageapi";
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+export interface ChatConfig {
+  baseUrl: string;
+  apiKey?: string;
+  source: string;
+}
+
+export function loadChatConfig(cwd = process.cwd(), includeCwdEnv = false): ChatConfig | null {
+  const base = findEnvValue("WEB_CHAT_API_BASE_URL", cwd, includeCwdEnv);
+  if (!base.value) return null;
+  const key = findEnvValue("WEB_CHAT_API_KEY", cwd, includeCwdEnv);
+  return {
+    baseUrl: base.value.replace(/\/+$/, ""),
+    ...(key.value ? { apiKey: key.value } : {}),
+    source: base.source,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Error mapping
+// ---------------------------------------------------------------------------
+
+export class ChatApiError extends Error {
+  constructor(
+    public status: number,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export function describeChatApiError(err: unknown): string {
+  if (err instanceof ChatApiError) {
+    if (err.status === 401 || err.status === 403) return `gateway rejected the API key (HTTP ${err.status}): ${err.message}`;
+    if (err.status === 429) return `gateway rate limit/quota exhausted (HTTP 429): ${err.message}`;
+    if (err.status === 502) return `gateway returned 502 — likely an empty account pool (add an account via the gateway's admin panel): ${err.message}`;
+    if (err.status >= 500) return `gateway server error (HTTP ${err.status}): ${err.message}`;
+    return `gateway error (HTTP ${err.status}): ${err.message}`;
+  }
+  return err instanceof Error ? err.message : String(err);
+}
+
+// ---------------------------------------------------------------------------
+// Single non-streaming completion
+// ---------------------------------------------------------------------------
+
+export interface ChatResult {
+  text: string;
+  model?: string;
+}
+
+export async function chatgptChat(opts: {
+  baseUrl: string;
+  apiKey?: string;
+  prompt: string;
+  model?: string;
+  system?: string;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  fetchImpl?: FetchLike;
+}): Promise<ChatResult> {
+  const fetchImpl = opts.fetchImpl ?? (fetch as FetchLike);
+  const messages = [
+    ...(opts.system ? [{ role: "system", content: opts.system }] : []),
+    { role: "user", content: opts.prompt },
+  ];
+  const res = await raceGuard(
+    fetchImpl(`${opts.baseUrl.replace(/\/+$/, "")}/chat/completions`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...(opts.apiKey ? { Authorization: `Bearer ${opts.apiKey}` } : {}) },
+      body: JSON.stringify({ model: opts.model, messages, stream: false }),
+      signal: opts.signal,
+    }),
+    { signal: opts.signal, timeoutMs: opts.timeoutMs ?? 120_000, label: "web_chat" },
+  );
+  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 ChatApiError(res.status, String(msg));
+  }
+  const choices = Array.isArray(payload?.choices) ? (payload!.choices as Array<{ message?: { content?: unknown } }>) : [];
+  const text = String(choices[0]?.message?.content ?? "");
+  if (!text) throw new Error(`gateway returned an empty completion${opts.model ? ` (model ${opts.model})` : ""}`);
+  return { text, model: typeof payload?.model === "string" ? payload.model : opts.model };
+}

package/extensions/lib/imageapi.ts

@@ -308,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) {
@@ -356,8 +363,24 @@ export async function generateImageWithFallback(params: ImageChainParams): Promi
         });
       }
       imageRateRecord(provider);
+      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,7 +1,7 @@
 {
   "name": "@bacnh85/pi-web",
-  "version": "0.9.1",
-  "description": "Pi extension for web search, page extraction, Firecrawl scraping/crawling, Crawl4AI headless browser crawling, Gemini web-tier research, and free upstream image generation.",
+  "version": "0.10.0",
+  "description": "Pi extension for web search, page extraction, Firecrawl scraping/crawling, Crawl4AI headless browser crawling, Gemini web-tier research, free upstream image generation, and one-off gateway chat.",
   "type": "module",
   "license": "MIT",
   "publishConfig": {

package/skills/pi-web/SKILL.md

@@ -1,11 +1,11 @@
 ---
 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 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.
+description: Web search, content extraction, site crawling, page capture, Gemini web-tier research, free upstream image generation, and one-off gateway chat 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), one-off ChatGPT/gateway chat, 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, asking another model, scraping/extracting content from a URL, or capturing a page.
 ---
 
 # pi-web — Unified Web Tools
 
-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.
+Use the **10 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
 
@@ -19,6 +19,7 @@ Use the **9 unified tools** from the `pi-web` extension for all web-related task
 | `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 GLM-Image (`ZAI_API_KEY`) → custom OpenAI-images endpoint |
+| `web_chat` | One-off chat via an OpenAI-compatible gateway | `WEB_CHAT_API_BASE_URL` (ChatGPT web bridge, official OpenAI, …) |
 | `web_status` | Check provider configuration and health | — |
 
 ## Decision Tree
@@ -65,6 +66,9 @@ What do you need?
 │     ├─ default: provider=auto (Gemini web → Z.ai GLM-Image → custom endpoint)
 │     └─ pin/model: provider=zai model=glm-image, or any custom OpenAI-images endpoint
 │
+├── One-off chat with another model (second opinion, classification)
+│   → web_chat (WEB_CHAT_API_BASE_URL gateway; non-streaming; no tools)
+│
 └── Check what web tools are configured
     → web_status
 ```