webfox 4.1.0 → 4.2.0

package/README.md

@@ -174,7 +174,7 @@ or, on Windows, `APPDATA`. Override it with `WEBFOX_CONFIG` or `--config <path>`
 For example:
 
 ```yaml
-$schema: https://unpkg.com/webfox@4.0.1/dist/config.schema.json
+$schema: https://unpkg.com/webfox@latest/dist/config.schema.json
 defaults:
   search:
     provider: brave
@@ -252,6 +252,9 @@ configuration, progress, and errors.
   `web config default <capability> <provider>`.
 - **Missing credentials:** Run `web providers <id>` to check the required key
   names, or see the [provider guide](./docs/provider.md).
+- **Invalid configuration in pi:** Pi continues to start, but Webfox registers
+  no tools and reports the error (on stderr in print and JSON modes). Fix the
+  configuration, then restart Pi or run `/reload` to load the extension again.
 - **No pi tools:** Select default providers in the shared configuration and
   restart pi. Installing the extension or setting keys alone isn't enough.
 

package/dist/{chunk-7BXAXZPA.js → chunk-CIZXLW6C.js}

@@ -8,7 +8,7 @@ import {
 // package.json
 var package_default = {
   name: "webfox",
-  version: "4.1.0",
+  version: "4.2.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: [
@@ -138,7 +138,7 @@ var package_default = {
 // src/package-metadata.ts
 var PACKAGE_NAME = package_default.name;
 var PACKAGE_VERSION = package_default.version;
-var CONFIG_SCHEMA_URL = `https://unpkg.com/${PACKAGE_NAME}@${PACKAGE_VERSION}/dist/config.schema.json`;
+var CONFIG_SCHEMA_URL = `https://unpkg.com/${PACKAGE_NAME}@latest/dist/config.schema.json`;
 
 // src/configuration/planning.ts
 import { Check, Errors } from "typebox/value";

package/dist/{chunk-2DWEBTPX.js → chunk-KC6K6LCQ.js}

@@ -11,7 +11,7 @@ import {
   providers,
   selectProvider,
   validateConfiguredOptions
-} from "./chunk-7BXAXZPA.js";
+} from "./chunk-CIZXLW6C.js";
 import {
   cancelProcessGroup,
   killProcessGroup
@@ -69,7 +69,13 @@ function readFailure(error, options, path) {
   if (error instanceof WebfoxError) throw error;
   throw new WebfoxError(
     "INVALID_CONFIG",
-    `Could not read configuration: ${path}. Check the path and file permissions.`
+    `Could not read configuration: ${path}. Check the path and file permissions.`,
+    {
+      configuration: {
+        source: path,
+        issues: ["Could not read file. Check the path and permissions."]
+      }
+    }
   );
 }
 function parseConfigDocument(text, source = "config.yaml") {
@@ -91,7 +97,15 @@ function parseConfigDocument(text, source = "config.yaml") {
   } catch {
     throw new WebfoxError(
       "INVALID_CONFIG",
-      `Invalid YAML in ${source}. Use one YAML 1.2 document with unique keys, with string keys and finite numbers, without aliases or explicit tags.`
+      `Invalid YAML in ${source}. Use one YAML 1.2 document with unique keys, with string keys and finite numbers, without aliases or explicit tags.`,
+      {
+        configuration: {
+          source,
+          issues: [
+            "Invalid YAML. Use YAML 1.2 without duplicate keys, aliases, or explicit tags."
+          ]
+        }
+      }
     );
   }
 }
@@ -105,14 +119,30 @@ function parseConfig(text, source = "config.yaml") {
 function validateConfig(value, source = "configuration") {
   const schema = configurationSchema;
   if (!Check(schema, value)) {
-    const detail = Errors(schema, value).slice(0, 3).map((error) => `${error.instancePath || "/"}: ${error.message}`).join("; ");
+    const errors = Errors(schema, value);
+    const detail = errors.slice(0, 3).map((error) => `${error.instancePath || "/"}: ${error.message}`).join("; ");
     throw new WebfoxError(
       "INVALID_CONFIG",
-      `Invalid ${source}: ${detail}. Provider options belong under providers.<id>.options.<capability>.`
+      `Invalid ${source}: ${detail}. Provider options belong under providers.<id>.options.<capability>.`,
+      { configuration: { source, issues: configurationIssues(errors) } }
     );
   }
   return structuredClone(value);
 }
+function configurationIssues(errors) {
+  const issues = /* @__PURE__ */ new Map();
+  for (const error of errors) {
+    if (error.keyword === "additionalProperties") continue;
+    const path = error.instancePath || "/";
+    if (issues.has(path)) continue;
+    const unknownKey = error.keyword === "boolean" && error.schemaPath.endsWith("/additionalProperties");
+    const key = path.slice(1).split("/").map((part) => part.replaceAll("~1", "/").replaceAll("~0", "~")).join(".");
+    const message = unknownKey ? `Unknown key: ${key}` : error.keyword === "enum" || error.keyword === "const" ? `${path}: unsupported value` : `${path}: ${error.message}`;
+    issues.set(path, message);
+    if (issues.size === 3) break;
+  }
+  return issues.size ? [...issues.values()] : ["Invalid configuration structure."];
+}
 function redactConfig(config) {
   const visit2 = (entry) => {
     if (Array.isArray(entry)) return entry.map(visit2);
@@ -645,26 +675,29 @@ function createWebfox(options = {}) {
           }
         };
       const definition = selectProvider(config, capability, selected);
-      return outward.value({
+      const defaults = outward.value({
+        options: effectiveOptions(
+          config,
+          definition,
+          capability,
+          {},
+          "defaults"
+        ),
+        ...capability === "search" ? { maxResults: config.defaults?.search?.maxResults ?? 5 } : {}
+      });
+      return {
         capability,
         provider: selected,
         configured: configured(definition, capability),
+        // Static provider schemas contain no credentials. Redacting property
+        // names such as maximum_number_of_tokens would invalidate the schema.
         optionSchema: optionSchema(
           definition,
           capability,
           "defaults"
         ),
-        defaults: {
-          options: effectiveOptions(
-            config,
-            definition,
-            capability,
-            {},
-            "defaults"
-          ),
-          ...capability === "search" ? { maxResults: config.defaults?.search?.maxResults ?? 5 } : {}
-        }
-      });
+        defaults
+      };
     }
   };
 }

package/dist/cli.js

@@ -11,12 +11,12 @@ import {
   redactConfig,
   resolveConfigPath,
   setCapabilityDefault
-} from "./chunk-2DWEBTPX.js";
+} from "./chunk-KC6K6LCQ.js";
 import "./chunk-WCTOYZVB.js";
 import {
   PACKAGE_VERSION,
   validateConfiguredOptions
-} from "./chunk-7BXAXZPA.js";
+} from "./chunk-CIZXLW6C.js";
 import "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES,

package/dist/config.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://unpkg.com/webfox@4.1.0/dist/config.schema.json",
+  "$id": "https://unpkg.com/webfox@latest/dist/config.schema.json",
   "title": "webfox configuration",
   "type": "object",
   "additionalProperties": false,

package/dist/errors.d.ts

@@ -4,11 +4,19 @@ export declare class WebfoxError extends Error {
     readonly options: {
         cause?: unknown;
         retryable?: boolean;
+        configuration?: {
+            source: string;
+            issues: string[];
+        };
     };
     readonly name = "WebfoxError";
     constructor(code: WebfoxErrorCode, message: string, options?: {
         cause?: unknown;
         retryable?: boolean;
+        configuration?: {
+            source: string;
+            issues: string[];
+        };
     });
     toJSON(): SerializedError;
 }

package/dist/index.js

@@ -6,12 +6,12 @@ import {
   resolveConfigPath,
   setCapabilityDefault,
   validateConfig
-} from "./chunk-2DWEBTPX.js";
+} from "./chunk-KC6K6LCQ.js";
 import "./chunk-WCTOYZVB.js";
 import {
   CONFIG_SCHEMA_URL,
   validateConfiguredOptions
-} from "./chunk-7BXAXZPA.js";
+} from "./chunk-CIZXLW6C.js";
 import "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES,

package/dist/pi-diagnostics.d.ts

@@ -0,0 +1,2 @@
+import type { WebfoxError } from "./errors.js";
+export declare function configurationDiagnostic(error: WebfoxError): string;

package/dist/pi.js

@@ -2,15 +2,18 @@ import {
   renderTextDocument
 } from "./chunk-QRHDXM2L.js";
 import {
-  createWebfox
-} from "./chunk-2DWEBTPX.js";
+  createWebfox,
+  resolveConfigPath
+} from "./chunk-KC6K6LCQ.js";
 import "./chunk-WCTOYZVB.js";
-import "./chunk-7BXAXZPA.js";
+import "./chunk-CIZXLW6C.js";
 import "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES
 } from "./chunk-WVHMWLKU.js";
-import "./chunk-U4BLULLV.js";
+import {
+  WebfoxError
+} from "./chunk-U4BLULLV.js";
 
 // src/pi.ts
 import { mkdtemp, writeFile } from "node:fs/promises";
@@ -417,6 +420,24 @@ function prepareToolArguments(schema, args) {
   return args;
 }
 
+// src/pi-diagnostics.ts
+import { homedir } from "node:os";
+import { sep } from "node:path";
+function configurationDiagnostic(error) {
+  const diagnostic = error.options.configuration;
+  const source = diagnostic?.source ?? resolveConfigPath();
+  const home = homedir() + sep;
+  const path = source.startsWith(home) ? `~/${source.slice(home.length)}` : source;
+  const issues = diagnostic?.issues ?? [error.message];
+  return [
+    "Webfox disabled \u2014 invalid configuration",
+    `  ${path}`,
+    ...issues.map((issue) => `  ${issue}`),
+    "",
+    "Fix the configuration, then /reload."
+  ].join("\n");
+}
+
 // src/pi.ts
 function webExtension(pi) {
   const clients = /* @__PURE__ */ new Map();
@@ -428,10 +449,24 @@ function webExtension(pi) {
     }
     return client;
   };
-  const initial = clientFor(process.cwd());
-  const selected = CAPABILITIES.filter(
-    (capability) => initial.inspectCapability(capability).provider
-  );
+  let selected;
+  try {
+    const initial = clientFor(process.cwd());
+    selected = CAPABILITIES.map(
+      (capability) => initial.inspectCapability(capability)
+    ).filter((inspection) => inspection.provider);
+  } catch (error) {
+    if (!(error instanceof WebfoxError) || !["INVALID_CONFIG", "INVALID_INPUT", "PROVIDER_UNAVAILABLE"].includes(
+      error.code
+    ))
+      throw error;
+    const message = configurationDiagnostic(error);
+    pi.on("session_start", (_event, context) => {
+      if (context.hasUI) context.ui.notify(message, "error");
+      else console.error(message);
+    });
+    return;
+  }
   if (!selected.length)
     pi.on("session_start", (_event, context) => {
       if (context.hasUI)
@@ -440,8 +475,8 @@ function webExtension(pi) {
           "warning"
         );
     });
-  for (const capability of selected) {
-    const inspection = initial.inspectCapability(capability);
+  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 }), {

package/example-config.yaml

@@ -1,4 +1,4 @@
-$schema: https://unpkg.com/webfox@4.0.1/dist/config.schema.json
+$schema: https://unpkg.com/webfox@latest/dist/config.schema.json
 defaults:
   search:
     provider: brave

package/package.json

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