webfox 4.5.0 → 4.6.0

package/dist/{chunk-VI3473TU.js → chunk-5TNPVBAZ.js}

@@ -9,7 +9,7 @@ import {
 // package.json
 var package_default = {
   name: "webfox",
-  version: "4.5.0",
+  version: "4.6.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: [
@@ -107,15 +107,14 @@ var package_default = {
     openai: "^7.10.0",
     "parallel-web": "^1.3.3",
     picocolors: "^1.1.1",
-    typebox: "^1.3.6",
     "valyu-js": "^2.10.1",
     yaml: "^2.9.0"
   },
   devDependencies: {
     "@biomejs/biome": "^2.5.4",
-    "@earendil-works/pi-ai": "^0.85.1",
-    "@earendil-works/pi-coding-agent": "^0.85.1",
-    "@earendil-works/pi-tui": "^0.85.1",
+    "@earendil-works/pi-ai": "^0.99.0",
+    "@earendil-works/pi-coding-agent": "^0.99.0",
+    "@earendil-works/pi-tui": "^0.99.0",
     "@types/node": "^26.1.1",
     esbuild: "^0.28.1",
     typescript: "^7.0.2",
@@ -123,7 +122,8 @@ var package_default = {
   },
   peerDependencies: {
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    typebox: "*"
   },
   peerDependenciesMeta: {
     "@earendil-works/pi-coding-agent": {

package/dist/{chunk-D4HCJRBE.js → chunk-QXTTUDLI.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-WCTOYZVB.js";
 import {
   configurationSchema
-} from "./chunk-VI3473TU.js";
+} from "./chunk-5TNPVBAZ.js";
 import {
   effectiveOptions,
   optionSchema,

package/dist/cli.js

@@ -11,11 +11,11 @@ import {
   redactConfig,
   resolveConfigPath,
   setCapabilityDefault
-} from "./chunk-D4HCJRBE.js";
+} from "./chunk-QXTTUDLI.js";
 import "./chunk-WCTOYZVB.js";
 import {
   PACKAGE_VERSION
-} from "./chunk-VI3473TU.js";
+} from "./chunk-5TNPVBAZ.js";
 import {
   validateConfiguredOptions
 } from "./chunk-KH54YH7D.js";

package/dist/document-schema.d.ts

@@ -0,0 +1,114 @@
+import { Type, type Static } from "typebox";
+import { type AnswerDocument, type ContentsDocument, type ResearchDocument, type SearchDocument } from "./domain.js";
+/**
+ * JSON Schema of each capability's result document. This is the document the
+ * CLI prints with `--format json` and the library returns.
+ */
+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", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "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;
+                    url: Type.TString;
+                    snippet: Type.TString;
+                    score: Type.TOptional<Type.TNumber>;
+                    metadata: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+                }>>;
+            }>;
+        }>, Type.TObject<{
+            input: Type.TString;
+            ok: Type.TLiteral<false>;
+            error: Type.TObject<{
+                code: Type.TEnum<["INVALID_CONFIG", "INVALID_INPUT", "PROVIDER_UNAVAILABLE", "PROVIDER_FAILURE", "PARTIAL_BATCH", "TIMEOUT", "CANCELLED"]>;
+                message: Type.TString;
+                retryable: Type.TOptional<Type.TBoolean>;
+            }>;
+        }>]>>;
+    }>;
+    readonly contents: Type.TObject<{
+        schemaVersion: Type.TLiteral<1>;
+        capability: Type.TLiteral<"contents">;
+        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "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<{
+                url: Type.TString;
+                content: Type.TOptional<Type.TString>;
+                summary: Type.TOptional<Type.TUnknown>;
+                metadata: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+            }>;
+        }>, Type.TObject<{
+            input: Type.TString;
+            ok: Type.TLiteral<false>;
+            error: Type.TObject<{
+                code: Type.TEnum<["INVALID_CONFIG", "INVALID_INPUT", "PROVIDER_UNAVAILABLE", "PROVIDER_FAILURE", "PARTIAL_BATCH", "TIMEOUT", "CANCELLED"]>;
+                message: Type.TString;
+                retryable: Type.TOptional<Type.TBoolean>;
+            }>;
+        }>]>>;
+    }>;
+    readonly answer: Type.TObject<{
+        schemaVersion: Type.TLiteral<1>;
+        capability: Type.TLiteral<"answer">;
+        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "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;
+                itemCount: Type.TOptional<Type.TInteger>;
+                metadata: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+            }>;
+        }>, Type.TObject<{
+            input: Type.TString;
+            ok: Type.TLiteral<false>;
+            error: Type.TObject<{
+                code: Type.TEnum<["INVALID_CONFIG", "INVALID_INPUT", "PROVIDER_UNAVAILABLE", "PROVIDER_FAILURE", "PARTIAL_BATCH", "TIMEOUT", "CANCELLED"]>;
+                message: Type.TString;
+                retryable: Type.TOptional<Type.TBoolean>;
+            }>;
+        }>]>>;
+    }>;
+    readonly research: Type.TObject<{
+        schemaVersion: Type.TLiteral<1>;
+        capability: Type.TLiteral<"research">;
+        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "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;
+                itemCount: Type.TOptional<Type.TInteger>;
+                metadata: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+            }>;
+        }>, Type.TObject<{
+            input: Type.TString;
+            ok: Type.TLiteral<false>;
+            error: Type.TObject<{
+                code: Type.TEnum<["INVALID_CONFIG", "INVALID_INPUT", "PROVIDER_UNAVAILABLE", "PROVIDER_FAILURE", "PARTIAL_BATCH", "TIMEOUT", "CANCELLED"]>;
+                message: Type.TString;
+                retryable: Type.TOptional<Type.TBoolean>;
+            }>;
+        }>]>>;
+    }>;
+};
+type Same<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+type Assert<T extends true> = T;
+export type DocumentSchemaMatchesDomain = [
+    Assert<Same<Static<typeof DOCUMENT_SCHEMAS.search>, SearchDocument>>,
+    Assert<Same<Static<typeof DOCUMENT_SCHEMAS.contents>, ContentsDocument>>,
+    Assert<Same<Static<typeof DOCUMENT_SCHEMAS.answer>, AnswerDocument>>,
+    Assert<Same<Static<typeof DOCUMENT_SCHEMAS.research>, ResearchDocument>>
+];
+export {};

package/dist/index.js

@@ -6,11 +6,11 @@ import {
   resolveConfigPath,
   setCapabilityDefault,
   validateConfig
-} from "./chunk-D4HCJRBE.js";
+} from "./chunk-QXTTUDLI.js";
 import "./chunk-WCTOYZVB.js";
 import {
   CONFIG_SCHEMA_URL
-} from "./chunk-VI3473TU.js";
+} from "./chunk-5TNPVBAZ.js";
 import {
   validateConfiguredOptions
 } from "./chunk-KH54YH7D.js";

package/dist/pi.js

@@ -4,13 +4,15 @@ import {
 import {
   createWebfox,
   resolveConfigPath
-} from "./chunk-D4HCJRBE.js";
+} from "./chunk-QXTTUDLI.js";
 import "./chunk-WCTOYZVB.js";
-import "./chunk-VI3473TU.js";
+import "./chunk-5TNPVBAZ.js";
 import "./chunk-KH54YH7D.js";
 import "./chunk-ZVTVERW5.js";
 import {
-  CAPABILITIES
+  CAPABILITIES,
+  PROVIDER_IDS,
+  WEBFOX_ERROR_CODES
 } from "./chunk-GPACLYNT.js";
 import {
   WebfoxError
@@ -24,7 +26,7 @@ import {
   truncateHead,
   withFileMutationQueue
 } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
+import { Type as Type2 } from "typebox";
 
 // src/pi-render.ts
 import { stripVTControlCharacters as stripVTControlCharacters3 } from "node:util";
@@ -186,11 +188,11 @@ function link(url, theme) {
   return label;
 }
 function renderSearchResult(details, fallback, theme) {
-  const document = isRecord2(details) && searchDocument(details.result) ? details.result : void 0;
+  const document2 = isRecord2(details) && searchDocument(details.result) ? details.result : void 0;
   return {
     render(width) {
       if (width <= 0) return [];
-      if (!document) {
+      if (!document2) {
         const text = plainText(fallback).split("\n").map((line) => {
           const urlLine = /^(\s*)(https?:\/\/\S+)(\s*)$/.exec(line);
           return urlLine ? urlLine[1] + link(urlLine[2], theme) + urlLine[3] : theme.fg("toolOutput", line);
@@ -209,9 +211,9 @@ function renderSearchResult(details, fallback, theme) {
           )
         );
       };
-      document.results.forEach((entry, index) => {
+      document2.results.forEach((entry, index) => {
         if (index) lines.push("");
-        if (document.results.length > 1) {
+        if (document2.results.length > 1) {
           append(
             theme.fg(
               "mdHeading",
@@ -304,8 +306,8 @@ var WebCall = class {
 };
 function renderWebResult(result, options, theme, isError, capability) {
   const text = result.content.filter((part) => part.type === "text").map((part) => part.text ?? "").join("\n");
-  const metadata = result.details;
-  const isSearch = (capability ?? metadata?.capability ?? metadata?.result?.capability) === "search";
+  const metadata2 = result.details;
+  const isSearch = (capability ?? metadata2?.capability ?? metadata2?.result?.capability) === "search";
   const body = () => isSearch ? renderSearchResult(result.details, text, theme) : new Markdown(text, 0, 0, getMarkdownTheme());
   const rows = statusRows(result.details);
   if (rows?.length) {
@@ -435,6 +437,85 @@ function configurationDiagnostic(error) {
   ].join("\n");
 }
 
+// src/document-schema.ts
+import { Type } from "typebox";
+var closed = { additionalProperties: false };
+var metadata = Type.Record(Type.String(), Type.Unknown(), {
+  description: "Provider-specific fields."
+});
+var searchResult = Type.Object(
+  {
+    title: Type.String(),
+    url: Type.String(),
+    snippet: Type.String(),
+    score: Type.Optional(Type.Number()),
+    metadata: Type.Optional(metadata)
+  },
+  closed
+);
+var contentsAnswer = Type.Object(
+  {
+    url: Type.String({ description: "Final URL after redirects." }),
+    content: Type.Optional(Type.String()),
+    summary: Type.Optional(Type.Unknown()),
+    metadata: Type.Optional(metadata)
+  },
+  closed
+);
+var textAnswer = Type.Object(
+  {
+    text: Type.String(),
+    itemCount: Type.Optional(Type.Integer()),
+    metadata: Type.Optional(metadata)
+  },
+  closed
+);
+var serializedError = Type.Object(
+  {
+    code: Type.Enum(WEBFOX_ERROR_CODES),
+    message: Type.String(),
+    retryable: Type.Optional(Type.Boolean())
+  },
+  closed
+);
+function inputResult(value) {
+  const input = Type.String({
+    description: "The query, URL, or brief this entry answers."
+  });
+  return Type.Union([
+    Type.Object({ input, ok: Type.Literal(true), value }, closed),
+    Type.Object(
+      { input, ok: Type.Literal(false), error: serializedError },
+      closed
+    )
+  ]);
+}
+function document(capability, value) {
+  return Type.Object(
+    {
+      schemaVersion: Type.Literal(1),
+      capability: Type.Literal(capability),
+      provider: Type.Enum(PROVIDER_IDS),
+      status: Type.Enum(["ok", "partial"], {
+        description: "`partial` when at least one input failed."
+      }),
+      results: Type.Array(inputResult(value), {
+        description: "One entry per input, in input order."
+      })
+    },
+    closed
+  );
+}
+var DOCUMENT_SCHEMAS = {
+  search: document(
+    "search",
+    Type.Object({ results: Type.Array(searchResult) }, closed)
+  ),
+  contents: document("contents", contentsAnswer),
+  answer: document("answer", textAnswer),
+  research: document("research", textAnswer)
+};
+
 // src/pi.ts
 function webExtension(pi) {
   const clients = /* @__PURE__ */ new Map();
@@ -475,18 +556,18 @@ function webExtension(pi) {
   for (const inspection of selected) {
     const capability = inspection.capability;
     const provider = inspection.provider;
-    const fields = capability === "contents" ? { urls: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }) } : capability === "research" ? { input: Type.String({ minLength: 1 }) } : {
-      queries: Type.Array(Type.String({ minLength: 1 }), {
+    const fields = capability === "contents" ? { urls: Type2.Array(Type2.String({ minLength: 1 }), { minItems: 1 }) } : capability === "research" ? { input: Type2.String({ minLength: 1 }) } : {
+      queries: Type2.Array(Type2.String({ minLength: 1 }), {
         minItems: 1,
         maxItems: 10
       }),
-      ...capability === "search" ? { maxResults: Type.Optional(Type.Integer({ minimum: 1 })) } : {}
+      ...capability === "search" ? { maxResults: Type2.Optional(Type2.Integer({ minimum: 1 })) } : {}
     };
-    const parameters = Type.Object(
+    const parameters = Type2.Object(
       {
         ...fields,
         ...inspection.optionSchema ? {
-          options: Type.Optional(
+          options: Type2.Optional(
             inspection.optionSchema
           )
         } : {}
@@ -503,6 +584,12 @@ function webExtension(pi) {
         "Output is truncated to 2000 lines or 50 KiB; full results are saved to a file when truncated."
       ].join("\n"),
       parameters,
+      // Let permission extensions and tool loadouts treat web access as a
+      // read-only call that reaches the open web.
+      annotations: { readOnlyHint: true, openWorldHint: true },
+      // Programmatic callers such as codemode scripts receive the result
+      // document itself instead of parsing the rendered text.
+      outputSchema: DOCUMENT_SCHEMAS[capability],
       prepareArguments(args) {
         return prepareToolArguments(parameters, args);
       },
@@ -550,6 +637,7 @@ function webExtension(pi) {
           queries: params.queries,
           maxResults: params.maxResults
         }) : capability === "answer" ? await client.answer({ ...request, queries: params.queries }) : capability === "contents" ? await client.contents({ ...request, urls: params.urls }) : await client.research({ ...request, input: params.input });
+        const json = JSON.stringify(result);
         const text = renderTextDocument(result);
         const truncated = truncateHead(text);
         let body = truncated.content;
@@ -561,7 +649,7 @@ function webExtension(pi) {
           );
           await withFileMutationQueue(
             fullOutputPath,
-            () => writeFile(fullOutputPath, JSON.stringify(result), { mode: 384 })
+            () => writeFile(fullOutputPath, json, { mode: 384 })
           );
           body += `
 
@@ -569,8 +657,11 @@ Full results: ${fullOutputPath}`;
         }
         return {
           content: [{ type: "text", text: body }],
+          // Pi keeps this out of the model's context and the session, so the
+          // text truncation above does not apply. Scripts get every result.
+          structuredContent: JSON.parse(json),
+          isError: result.status === "partial",
           details: {
-            webProviderResult: true,
             status: result.status,
             webInputStatus: true,
             capability,
@@ -584,10 +675,6 @@ Full results: ${fullOutputPath}`;
       }
     });
   }
-  pi.on("tool_result", (event) => {
-    if (event.details && typeof event.details === "object" && "webProviderResult" in event.details && event.details.webProviderResult === true && "status" in event.details && event.details.status === "partial")
-      return { isError: true };
-  });
 }
 var descriptions = {
   search: "Search up to ten queries and return titles, URLs, and snippets in input order.",

package/docs/reference.md

@@ -179,3 +179,10 @@ extension forwards cancellation and progress, marks partial results as errors,
 and truncates tool output at 2,000 lines or 50 KiB, with full results saved to a
 temporary file. It needs no globally installed `web` command and starts no
 background research jobs.
+
+Each tool declares the [JSON result document](./cli-experience.md#json-results)
+as its output schema and returns that document as structured content. Scripts
+that call the tools through Pi's codemode receive it as an object instead of
+parsing text, including the completed inputs of a partial result. Structured
+content is never truncated, and Pi neither sends it to the model nor stores it
+in the session.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webfox",
-  "version": "4.5.0",
+  "version": "4.6.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": [
@@ -98,15 +98,14 @@
     "openai": "^7.10.0",
     "parallel-web": "^1.3.3",
     "picocolors": "^1.1.1",
-    "typebox": "^1.3.6",
     "valyu-js": "^2.10.1",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.4",
-    "@earendil-works/pi-ai": "^0.85.1",
-    "@earendil-works/pi-coding-agent": "^0.85.1",
-    "@earendil-works/pi-tui": "^0.85.1",
+    "@earendil-works/pi-ai": "^0.99.0",
+    "@earendil-works/pi-coding-agent": "^0.99.0",
+    "@earendil-works/pi-tui": "^0.99.0",
     "@types/node": "^26.1.1",
     "esbuild": "^0.28.1",
     "typescript": "^7.0.2",
@@ -114,7 +113,8 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {