webfox 4.10.0 → 4.11.0

package/dist/document-schema.d.ts

@@ -8,14 +8,14 @@ export declare const DOCUMENT_SCHEMAS: {
     readonly search: Type.TObject<{
         schemaVersion: Type.TLiteral<1>;
         capability: Type.TLiteral<"search">;
-        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "keenable", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "tavily", "valyu", "youcom"]>;
+        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "keenable", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "sofya", "tavily", "valyu", "youcom"]>;
         status: Type.TEnum<["ok", "partial"]>;
         results: Type.TArray<Type.TUnion<[Type.TObject<{
             input: Type.TString;
             ok: Type.TLiteral<true>;
             value: Type.TObject<{
                 results: Type.TArray<Type.TObject<{
-                    title: Type.TString;
+                    title: Type.TOptional<Type.TString>;
                     url: Type.TString;
                     snippet: Type.TString;
                     score: Type.TOptional<Type.TNumber>;
@@ -35,7 +35,7 @@ export declare const DOCUMENT_SCHEMAS: {
     readonly contents: Type.TObject<{
         schemaVersion: Type.TLiteral<1>;
         capability: Type.TLiteral<"contents">;
-        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "keenable", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "tavily", "valyu", "youcom"]>;
+        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "keenable", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "sofya", "tavily", "valyu", "youcom"]>;
         status: Type.TEnum<["ok", "partial"]>;
         results: Type.TArray<Type.TUnion<[Type.TObject<{
             input: Type.TString;
@@ -59,13 +59,19 @@ export declare const DOCUMENT_SCHEMAS: {
     readonly answer: Type.TObject<{
         schemaVersion: Type.TLiteral<1>;
         capability: Type.TLiteral<"answer">;
-        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "keenable", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "tavily", "valyu", "youcom"]>;
+        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "keenable", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "sofya", "tavily", "valyu", "youcom"]>;
         status: Type.TEnum<["ok", "partial"]>;
         results: Type.TArray<Type.TUnion<[Type.TObject<{
             input: Type.TString;
             ok: Type.TLiteral<true>;
             value: Type.TObject<{
                 text: Type.TString;
+                sources: Type.TOptional<Type.TArray<Type.TUnion<[Type.TObject<{
+                    url: Type.TString;
+                    title: Type.TOptional<Type.TString>;
+                }>, Type.TObject<{
+                    title: Type.TString;
+                }>]>>>;
                 itemCount: Type.TOptional<Type.TInteger>;
                 metadata: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
             }>;
@@ -82,13 +88,19 @@ export declare const DOCUMENT_SCHEMAS: {
     readonly research: Type.TObject<{
         schemaVersion: Type.TLiteral<1>;
         capability: Type.TLiteral<"research">;
-        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "keenable", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "tavily", "valyu", "youcom"]>;
+        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "keenable", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "sofya", "tavily", "valyu", "youcom"]>;
         status: Type.TEnum<["ok", "partial"]>;
         results: Type.TArray<Type.TUnion<[Type.TObject<{
             input: Type.TString;
             ok: Type.TLiteral<true>;
             value: Type.TObject<{
                 text: Type.TString;
+                sources: Type.TOptional<Type.TArray<Type.TUnion<[Type.TObject<{
+                    url: Type.TString;
+                    title: Type.TOptional<Type.TString>;
+                }>, Type.TObject<{
+                    title: Type.TString;
+                }>]>>>;
                 itemCount: Type.TOptional<Type.TInteger>;
                 metadata: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
             }>;

package/dist/domain.d.ts

@@ -1,6 +1,6 @@
 export declare const CAPABILITIES: readonly ["search", "contents", "answer", "research"];
 export type Capability = (typeof CAPABILITIES)[number];
-export declare const PROVIDER_IDS: readonly ["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "keenable", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "tavily", "valyu", "youcom"];
+export declare const PROVIDER_IDS: readonly ["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "keenable", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "sofya", "tavily", "valyu", "youcom"];
 export type ProviderId = (typeof PROVIDER_IDS)[number];
 export declare const WEBFOX_ERROR_CODES: readonly ["INVALID_CONFIG", "INVALID_INPUT", "PROVIDER_UNAVAILABLE", "PROVIDER_FAILURE", "PARTIAL_BATCH", "TIMEOUT", "CANCELLED"];
 export type WebfoxErrorCode = (typeof WEBFOX_ERROR_CODES)[number];
@@ -19,7 +19,8 @@ export type InputResult<T> = {
     error: SerializedError;
 };
 export interface SearchResult {
-    title: string;
+    /** Omitted when the provider has no title; renderers fall back to the URL. */
+    title?: string;
     url: string;
     snippet: string;
     score?: number;
@@ -28,12 +29,23 @@ export interface SearchResult {
 export interface ContentsAnswer {
     /** Final fetched URL; association with the requested URL is in InputResult.input. */
     url: string;
+    /** Omitted when the page has no content; an empty page is still a result. */
     content?: string;
     summary?: unknown;
     metadata?: Record<string, unknown>;
 }
+/** A cited source with a nonblank URL, title, or both. */
+export type Source = {
+    url: string;
+    title?: string;
+} | {
+    title: string;
+};
 export interface TextAnswer {
+    /** Empty when the provider returned no text; an empty answer is still a result. */
     text: string;
+    sources?: Source[];
+    /** Number of sources, derived from `sources`. */
     itemCount?: number;
     metadata?: Record<string, unknown>;
 }

package/dist/durable.js

@@ -5,17 +5,17 @@ import {
 } from "./chunk-VVOQKYOP.js";
 import {
   renderTextDocument
-} from "./chunk-BTWECET5.js";
+} from "./chunk-6RQGO727.js";
 import {
   createWebfox
-} from "./chunk-3WBE6UEW.js";
+} from "./chunk-YILOS4E7.js";
 import "./chunk-WCTOYZVB.js";
-import "./chunk-TGULKHB5.js";
-import "./chunk-5FP7KNMC.js";
+import "./chunk-KMUCUJVN.js";
+import "./chunk-PVNWACMT.js";
 import "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES
-} from "./chunk-57OOEOXI.js";
+} from "./chunk-NENL6L6N.js";
 import "./chunk-U4BLULLV.js";
 
 // src/durable.ts

package/dist/index.js

@@ -6,20 +6,20 @@ import {
   resolveConfigPath,
   setCapabilityDefault,
   validateConfig
-} from "./chunk-3WBE6UEW.js";
+} from "./chunk-YILOS4E7.js";
 import "./chunk-WCTOYZVB.js";
 import {
   CONFIG_SCHEMA_URL
-} from "./chunk-TGULKHB5.js";
+} from "./chunk-KMUCUJVN.js";
 import {
   validateConfiguredOptions
-} from "./chunk-5FP7KNMC.js";
+} from "./chunk-PVNWACMT.js";
 import "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES,
   PROVIDER_IDS,
   WEBFOX_ERROR_CODES
-} from "./chunk-57OOEOXI.js";
+} from "./chunk-NENL6L6N.js";
 import {
   WebfoxError
 } from "./chunk-U4BLULLV.js";

package/dist/pi.js

@@ -4,21 +4,22 @@ import {
   webToolParameters
 } from "./chunk-VVOQKYOP.js";
 import {
+  emptyResultText,
   renderTextDocument
-} from "./chunk-BTWECET5.js";
+} from "./chunk-6RQGO727.js";
 import {
   createWebfox,
   resolveConfigPath
-} from "./chunk-3WBE6UEW.js";
+} from "./chunk-YILOS4E7.js";
 import "./chunk-WCTOYZVB.js";
-import "./chunk-TGULKHB5.js";
-import "./chunk-5FP7KNMC.js";
+import "./chunk-KMUCUJVN.js";
+import "./chunk-PVNWACMT.js";
 import "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES,
   PROVIDER_IDS,
   WEBFOX_ERROR_CODES
-} from "./chunk-57OOEOXI.js";
+} from "./chunk-NENL6L6N.js";
 import {
   WebfoxError
 } from "./chunk-U4BLULLV.js";
@@ -175,7 +176,7 @@ function searchDocument(value) {
     if (entry.ok === false)
       return isRecord2(entry.error) && typeof entry.error.message === "string";
     return entry.ok === true && isRecord2(entry.value) && Array.isArray(entry.value.results) && entry.value.results.every(
-      (result) => isRecord2(result) && typeof result.title === "string" && typeof result.url === "string" && typeof result.snippet === "string"
+      (result) => isRecord2(result) && (result.title === void 0 || typeof result.title === "string") && typeof result.url === "string" && typeof result.snippet === "string"
     );
   });
 }
@@ -231,17 +232,21 @@ function renderSearchResult(details, fallback, theme) {
           return;
         }
         if (!entry.value.results.length)
-          append(theme.fg("toolOutput", "No results found."));
+          append(theme.fg("toolOutput", emptyResultText("search")));
         entry.value.results.forEach((result, resultIndex) => {
           if (resultIndex) lines.push("");
           const number = `${resultIndex + 1}. `;
           const indent = " ".repeat(number.length);
-          append(
-            theme.fg("toolOutput", plainText(result.title)),
-            theme.fg("accent", number)
-          );
-          append(link(result.url, theme), indent);
-          if (result.snippet)
+          if (result.title === void 0)
+            append(link(result.url, theme), theme.fg("accent", number));
+          else {
+            append(
+              theme.fg("toolOutput", plainText(result.title)),
+              theme.fg("accent", number)
+            );
+            append(link(result.url, theme), indent);
+          }
+          if (result.snippet.trim())
             append(theme.fg("toolOutput", plainText(result.snippet)), indent);
         });
       });
@@ -372,7 +377,7 @@ var metadata = Type.Record(Type.String(), Type.Unknown(), {
 });
 var searchResult = Type.Object(
   {
-    title: Type.String(),
+    title: Type.Optional(Type.String({ minLength: 1 })),
     url: Type.String(),
     snippet: Type.String(),
     score: Type.Optional(Type.Number()),
@@ -392,6 +397,20 @@ var contentsAnswer = Type.Object(
 var textAnswer = Type.Object(
   {
     text: Type.String(),
+    sources: Type.Optional(
+      Type.Array(
+        Type.Union([
+          Type.Object(
+            {
+              url: Type.String({ minLength: 1 }),
+              title: Type.Optional(Type.String({ minLength: 1 }))
+            },
+            closed
+          ),
+          Type.Object({ title: Type.String({ minLength: 1 }) }, closed)
+        ])
+      )
+    ),
     itemCount: Type.Optional(Type.Integer()),
     metadata: Type.Optional(metadata)
   },

package/dist/providers/contract.d.ts

@@ -4,10 +4,19 @@ export interface SearchResponse {
     provider: ProviderId;
     results: SearchResult[];
 }
+/** A provider citation; the runtime trims fields and drops blank entries. */
+export interface SourceInput {
+    url?: string;
+    title?: string;
+}
+/**
+ * Answer and research output. Return the provider's text as-is, even when
+ * empty, and its citations as `sources`; presentation belongs to the renderer.
+ */
 export interface ToolOutput {
     provider: ProviderId;
     text: string;
-    itemCount?: number;
+    sources?: SourceInput[];
     metadata?: Record<string, unknown>;
 }
 export interface ResearchJob {
@@ -84,6 +93,7 @@ export interface ProviderConfigMap {
     perplexity: import("./perplexity/types.js").Perplexity;
     serpbase: import("./serpbase/types.js").SerpBase;
     serper: import("./serper/types.js").Serper;
+    sofya: import("./sofya/types.js").Sofya;
     tavily: import("./tavily/types.js").Tavily;
     valyu: import("./valyu/types.js").Valyu;
     youcom: import("./youcom/types.js").Youcom;

package/dist/providers/registry.d.ts

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

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

@@ -0,0 +1,8 @@
+import type { ProviderContext, ProviderRequest, SearchResponse, ToolOutput } from "../contract.js";
+import type { Sofya } from "./types.js";
+export declare const adapter: {
+    search(request: ProviderRequest<"search">, config: Sofya, context: ProviderContext): Promise<SearchResponse>;
+    contents(request: ProviderRequest<"contents">, config: Sofya, context: ProviderContext): Promise<import("../../contents.js").IndexedContentsResponse>;
+    answer(request: ProviderRequest<"answer">, config: Sofya, context: ProviderContext): Promise<ToolOutput>;
+    research(request: ProviderRequest<"research">, config: Sofya, context: ProviderContext): Promise<ToolOutput>;
+};

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

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

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

@@ -0,0 +1,4 @@
+import type { Provider } from "../contract.js";
+export interface Sofya extends Provider {
+    baseUrl?: string;
+}

package/dist/render.d.ts

@@ -1,5 +1,11 @@
-import type { WebDocument } from "./domain.js";
-/** Presentation is deliberately outside the application/runtime. */
+import type { Capability, SearchResult, Source, WebDocument } from "./domain.js";
+/**
+ * Presentation is deliberately outside the application/runtime: providers
+ * return empty results as data, and only renderers decide how they look.
+ */
+export declare function emptyResultText(capability: Capability): string;
+/** Label a search result or source by its title, falling back to its URL. */
+export declare function resultLabel(result: SearchResult | Source): string;
 export declare function renderTextDocument(document: WebDocument, { includeErrors }?: {
     includeErrors?: boolean;
 }): string;

package/docs/provider.md

@@ -340,6 +340,33 @@ Supports search. Set `SERPER_API_KEY`.
 web search "Node.js release notes" --provider serper
 ```
 
+## Sofya
+
+Supports search, page extraction, answers, and research. Set `SOFYA_API_KEY`,
+or configure `providers.sofya.credentials.api` with a credential source. No
+defaults change unless you select Sofya.
+
+```sh
+web search "Node.js release notes" --provider sofya --freshness month
+web contents https://nodejs.org/en/blog --provider sofya
+web answer "What is the latest Node.js LTS?" --provider sofya
+web research "State of WebAssembly outside the browser" --provider sofya
+web config default search sofya
+```
+
+Search caps `maxResults` at 20 and defaults to `search_depth: "snippets"`;
+`basic` also reads each page and returns its text in `metadata.content`. Native
+options include `topic` (`general` or `news`), `freshness` (`day`, `week`,
+`month`, `year`, or a `YYYY-MM-DD:YYYY-MM-DD` range), and
+`include_domains`/`exclude_domains`. Answers come from a search with
+`include_answer` and report Sofya's `altered_query` or `relaxed_query` in
+metadata. Contents accepts `include_raw_html`. Research accepts `topic`,
+`freshness`, and `max_sources` (5-30) and usually takes 20-60 seconds.
+
+Sofya calls can take up to 60 seconds, so search, contents, and answers have a
+90-second overall deadline by default. An explicit CLI `--timeout`, library
+`timeoutMs`, or YAML `execution.timeoutMs` takes precedence.
+
 ## You.com
 
 Supports search. Set `YDC_API_KEY`; the library, CLI, and Pi extension use the

package/examples/custom/README.md

@@ -32,10 +32,16 @@ Payloads and responses:
 
 | Capability | Input | Response |
 | --- | --- | --- |
-| Search | `{ "query": "...", "maxResults": 5 }` | `{ "results": [{ "title": "...", "url": "https://...", "snippet": "..." }] }` |
+| Search | `{ "query": "...", "maxResults": 5 }` | `{ "results": [{ "title": "...", "url": "https://...", "snippet": "..." }] }` (`title` is optional) |
 | Contents | `{ "urls": ["https://..."] }` | `{ "answers": [{ "inputIndex": 0, "url": "https://...", "content": "..." }] }` |
-| Answer | `{ "query": "..." }` | `{ "text": "..." }` |
-| Research | `{ "input": "..." }` | `{ "text": "..." }` |
+| Answer | `{ "query": "..." }` | `{ "text": "...", "sources": [{ "url": "https://...", "title": "..." }] }` |
+| Research | `{ "input": "..." }` | `{ "text": "...", "sources": [{ "url": "https://...", "title": "..." }] }` |
+
+Return results as data and leave presentation to webfox. Empty results are
+valid: return no search results, an empty `text`, or a page without `content`
+instead of placeholder text. Omit titles you don't have rather than repeating
+the URL. `sources` is optional; webfox drops sources that have neither a `url`
+nor a `title`.
 
 Contents answers must cover every request index exactly once. `inputIndex`
 associates a response with the requested URL; `url` can hold a redirected URL.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webfox",
-  "version": "4.10.0",
+  "version": "4.11.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": [

package/dist/chunk-BTWECET5.js

@@ -1,31 +0,0 @@
-// src/render.ts
-function renderTextDocument(document, { includeErrors = true } = {}) {
-  return document.results.map((entry, index) => {
-    const heading = document.results.length > 1 ? `## ${index + 1}. ${entry.input}` : "";
-    if (!entry.ok)
-      return includeErrors ? [heading, `Error: ${entry.error.message}`].filter(Boolean).join("\n\n") : void 0;
-    let body;
-    if ("results" in entry.value)
-      body = entry.value.results.length ? entry.value.results.map(
-        (result, i) => `${i + 1}. ${result.title}
-   ${result.url}
-   ${result.snippet.replaceAll("\n", "\n   ")}`
-      ).join("\n\n") : "No results found.";
-    else if ("text" in entry.value) body = entry.value.text;
-    else body = renderContents(entry.value);
-    return [heading, body].filter(Boolean).join("\n\n");
-  }).filter((part) => part !== void 0).join("\n\n");
-}
-function renderContents(answer) {
-  return [
-    `## ${answer.url}`,
-    answer.content,
-    answer.summary === void 0 ? void 0 : `### Summary
-
-${typeof answer.summary === "string" ? answer.summary : JSON.stringify(answer.summary, null, 2)}`
-  ].filter(Boolean).join("\n\n");
-}
-
-export {
-  renderTextDocument
-};