webfox 4.2.2 → 4.3.0

package/dist/index.js

@@ -6,18 +6,20 @@ import {
   resolveConfigPath,
   setCapabilityDefault,
   validateConfig
-} from "./chunk-ZBD4DRCY.js";
+} from "./chunk-5H6OAJCS.js";
 import "./chunk-WCTOYZVB.js";
 import {
-  CONFIG_SCHEMA_URL,
+  CONFIG_SCHEMA_URL
+} from "./chunk-4SX4TI7A.js";
+import {
   validateConfiguredOptions
-} from "./chunk-FMYKJ7JC.js";
+} from "./chunk-VYMIR35R.js";
 import "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES,
   PROVIDER_IDS,
   WEBFOX_ERROR_CODES
-} from "./chunk-WVHMWLKU.js";
+} from "./chunk-GPACLYNT.js";
 import {
   WebfoxError
 } from "./chunk-U4BLULLV.js";

package/dist/pi.js

@@ -1,16 +1,17 @@
 import {
   renderTextDocument
-} from "./chunk-QRHDXM2L.js";
+} from "./chunk-BTWECET5.js";
 import {
   createWebfox,
   resolveConfigPath
-} from "./chunk-ZBD4DRCY.js";
+} from "./chunk-5H6OAJCS.js";
 import "./chunk-WCTOYZVB.js";
-import "./chunk-FMYKJ7JC.js";
+import "./chunk-4SX4TI7A.js";
+import "./chunk-VYMIR35R.js";
 import "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES
-} from "./chunk-WVHMWLKU.js";
+} from "./chunk-GPACLYNT.js";
 import {
   WebfoxError
 } from "./chunk-U4BLULLV.js";
@@ -499,7 +500,12 @@ function webExtension(pi) {
     pi.registerTool({
       name: `web_${capability}`,
       label: `Web ${capability[0].toUpperCase()}${capability.slice(1)}`,
-      description: `${descriptions[capability]} Output is truncated to 2000 lines or 50 KiB; full results are saved to a file when truncated.`,
+      // Keep provider guidance with the tool schema, including with custom system prompts.
+      description: [
+        descriptions[capability],
+        ...inspection.promptGuidelines ?? [],
+        "Output is truncated to 2000 lines or 50 KiB; full results are saved to a file when truncated."
+      ].join("\n"),
       parameters,
       prepareArguments(args) {
         return prepareToolArguments(parameters, args);

package/dist/providers/contract.d.ts

@@ -81,6 +81,7 @@ export interface ProviderConfigMap {
     openai: import("./openai/types.js").OpenAI;
     parallel: import("./parallel/types.js").Parallel;
     perplexity: import("./perplexity/types.js").Perplexity;
+    serpbase: import("./serpbase/types.js").SerpBase;
     serper: import("./serper/types.js").Serper;
     tavily: import("./tavily/types.js").Tavily;
     valyu: import("./valyu/types.js").Valyu;

package/dist/providers/definition.d.ts

@@ -3,11 +3,15 @@ import type { CredentialSource, ProviderConfiguration } from "../configuration/t
 import type { ProviderConfigMap, ProviderContext, ProviderRequest, ProviderResult } from "./contract.js";
 import type { ProviderCredentialMetadata } from "./metadata.js";
 export interface CapabilityDefinition {
+    /** Overall deadline when neither the request nor execution configuration sets one. */
+    defaultTimeoutMs?: number;
     options?: Record<string, unknown>;
     limits?: {
         maxResults?: number;
     };
     promptGuidelines?: readonly string[];
+    /** Allowed option keys per mode; switching modes drops incompatible inherited defaults. */
+    modeOptionKeys?: Readonly<Record<string, readonly string[]>>;
     /** Whether the entire operation may be repeated after a transient failure. */
     retrySafe: boolean;
 }

package/dist/providers/registry.d.ts

@@ -10,6 +10,7 @@ export declare const providers: {
     readonly openai: import("./definition.js").ProviderDefinitionFor<"openai">;
     readonly parallel: import("./definition.js").ProviderDefinitionFor<"parallel">;
     readonly perplexity: import("./definition.js").ProviderDefinitionFor<"perplexity">;
+    readonly serpbase: import("./definition.js").ProviderDefinitionFor<"serpbase">;
     readonly serper: import("./definition.js").ProviderDefinitionFor<"serper">;
     readonly tavily: import("./definition.js").ProviderDefinitionFor<"tavily">;
     readonly valyu: import("./definition.js").ProviderDefinitionFor<"valyu">;

package/dist/providers/serpbase/adapter.d.ts

@@ -0,0 +1,5 @@
+import type { ProviderContext, ProviderRequest, SearchResponse } from "../contract.js";
+import { type SerpBase } from "./types.js";
+export declare const adapter: {
+    search(request: ProviderRequest<"search">, config: SerpBase, context: ProviderContext): Promise<SearchResponse>;
+};

package/dist/providers/serpbase/definition.d.ts

@@ -0,0 +1 @@
+export declare const serpbaseProvider: import("../definition.js").ProviderDefinitionFor<"serpbase">;

package/dist/providers/serpbase/types.d.ts

@@ -0,0 +1,37 @@
+import type { Provider } from "../contract.js";
+export declare const SERPBASE_MODES: {
+    readonly search: {
+        readonly path: "search";
+        readonly result: "organic";
+        readonly options: readonly ["hl", "gl", "page", "device"];
+    };
+    readonly images: {
+        readonly path: "images";
+        readonly result: "images";
+        readonly options: readonly ["hl", "gl", "page"];
+    };
+    readonly news: {
+        readonly path: "news";
+        readonly result: "news";
+        readonly options: readonly ["hl", "gl", "page"];
+    };
+    readonly videos: {
+        readonly path: "videos";
+        readonly result: "videos";
+        readonly options: readonly ["hl", "gl", "page"];
+    };
+    readonly maps: {
+        readonly path: "maps/search";
+        readonly result: "places";
+        readonly options: readonly ["hl", "gl", "page", "lat", "lng", "zoom"];
+    };
+    readonly "maps-detail": {
+        readonly path: "maps/detail";
+        readonly result: "place";
+        readonly options: readonly ["hl", "gl"];
+    };
+};
+export type SerpBaseMode = keyof typeof SERPBASE_MODES;
+export interface SerpBase extends Provider {
+    baseUrl?: string;
+}

package/docs/provider.md

@@ -152,6 +152,108 @@ Supports search, grounded answers, and research. Set `PERPLEXITY_API_KEY`.
 web answer "What is MCP?" --provider perplexity
 ```
 
+## SerpBase
+
+Supports all six Google endpoints through the existing `search` capability and
+Pi's `web_search` tool. Set `SERPBASE_API_KEY`, or configure
+`providers.serpbase.credentials.api` with a credential source. No defaults change
+unless you select SerpBase.
+
+```sh
+web search "Node.js release notes" --provider serpbase --gl us --hl en --device pc
+web config default search serpbase
+```
+
+Choose a mode with `--mode` in the CLI or `options.mode` in the library and Pi:
+
+| Mode | Input | Results and controls |
+| --- | --- | --- |
+| `search` (default) | Search text | Organic results; `device` is `default`, `pc`, or `mobile`. |
+| `images` | Search text | Image URLs, source pages, and thumbnails. |
+| `news` | Search text | Articles, publishers, and published-time text. |
+| `videos` | Search text | Videos, sources, durations, and published-time text. |
+| `maps` | Place search text | Places, addresses, ratings, and feature IDs; optional `lat`, `lng`, and `zoom`. |
+| `maps-detail` | Feature IDs from `maps` | One place's details per input, including contact information and hours when available. |
+
+SerpBase has a 120-second overall deadline by default because some endpoints can
+exceed the usual 30-second search deadline. An explicit CLI `--timeout`, library
+`timeoutMs`, or YAML `execution.timeoutMs` takes precedence. This deadline includes
+all inputs and retries; it isn't a separate allowance per request. Other providers
+keep their existing defaults.
+
+Every mode accepts `hl` (language, default `en`) and `gl` (country, default `us`).
+All modes except `maps-detail` accept `page` (1-based, default `1`). Maps Search
+requires `lat` and `lng` together. `zoom` requires coordinates, ranges from `1` to
+`21`, and defaults to `14` upstream when coordinates are supplied. Device
+selection applies only to organic search; `default` lets SerpBase choose.
+
+```sh
+web search "architecture diagrams" --provider serpbase --mode images
+web search "Node.js releases" --provider serpbase --mode news
+web search "Node.js tutorials" --provider serpbase --mode videos
+web search "coffee" --provider serpbase --mode maps --lat 52.52 --lng 13.405 --zoom 14
+```
+
+For place enrichment, copy a `feature_id` from a Maps result and pass it as the
+search input. Don't use a place name, `place_id`, CID, or Maps URL:
+
+```sh
+web search '0x...:0x...' --provider serpbase --mode maps-detail
+```
+
+Replace the placeholder with an actual returned ID. The model follows the same
+sequence using the same tool, with one feature ID per `queries` entry:
+
+```json
+{
+  "queries": ["0x...:0x..."],
+  "options": { "mode": "maps-detail" }
+}
+```
+
+Save provider-specific defaults under `providers.serpbase.options.search`:
+
+```yaml
+providers:
+  serpbase:
+    options:
+      search:
+        gl: de
+        hl: de
+        device: pc
+```
+
+Changing modes drops incompatible inherited defaults. For example, a request
+with `mode: images` doesn't inherit the configured `device: pc`. Explicitly
+supplying incompatible options is an error, not a silently ignored setting.
+Coordinate dependencies are checked after merging defaults and request options.
+
+Each input fetches only the selected page or place, preserving result order.
+`maxResults` trims that page locally; it doesn't increase the upstream page size
+or fetch additional pages. Use `--page 2` to request another page explicitly.
+Requests can incur charges, including retries after transient failures. See the
+[SerpBase API reference](https://serpbase.dev/docs) for per-endpoint pricing.
+
+Text and model-visible output include actionable fields: image/source URLs,
+news/video sources and time text, and place feature IDs, addresses, contact
+information, ratings, and hours when returned. Images aren't downloaded. Published
+times and opening status are upstream observations, not independently verified.
+Ambiguous clock-like video times are labeled `Time (upstream)`, not publication
+dates or inferred durations. The known Google navigation-logo artifact is
+excluded from image results; other results retain their upstream order.
+
+JSON output retains original ranks, aliases, sitelinks, media fields, and place
+data in `metadata`, alongside the selected `mode`. Ranks are page-relative, not
+calculated absolute positions. `metadata.searchContext` includes the returned
+page, query, request ID, charged credits, and rich SERP modules when available.
+Context is attached to results, so an empty results list has no context metadata.
+Rich modules aren't mixed into the primary result ordering.
+
+The provider uses the JSON API directly, without an SDK dependency.
+`providers.serpbase.baseUrl` can replace the API origin for a compatible proxy;
+webfox appends the selected endpoint, such as `/google/images` or
+`/google/maps/detail`.
+
 ## Serper
 
 Supports search. Set `SERPER_API_KEY`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webfox",
-  "version": "4.2.2",
+  "version": "4.3.0",
   "description": "Search the web, extract pages, get grounded answers, and run deep research with the web CLI, a TypeScript library, and a pi extension. Bring your own providers and API keys.",
   "type": "module",
   "files": [