webfox 4.5.0 → 4.7.0

package/README.md

@@ -244,6 +244,95 @@ Ask Pi: **Search the web for the latest Node.js release notes.**
 Add `contents`, `answer`, or `research` defaults for more tools.
 Restart Pi after changing defaults.
 
+### Compose web calls with codemode
+
+With Pi 0.99 or later, you can use its built-in `codemode` tool to chain web
+calls, run independent calls in parallel, and filter results before they reach
+the model. In `~/.pi/agent/settings.json` or your project's `.pi/settings.json`,
+add:
+
+```json
+{
+  "defaultTools": ["+codemode"]
+}
+```
+
+This keeps your existing tools and adds codemode. Webfox tools remain directly
+callable; you don't need an MCP server or another extension. In codemode, calls
+such as `tools.web_search(...)` return structured result objects, not text.
+Scripts receive complete results even when the direct tool output is truncated.
+Only the output you emit with `text(...)` or `return` reaches the model.
+
+Ask Pi: **Use codemode to search for Node.js and Bun cancellation, fetch up to
+five unique pages, and return a short excerpt from each.** Pi can run a script
+like this, provided you have configured both `search` and `contents` defaults:
+
+```js
+const search = await tools.web_search({
+  queries: ["Node.js cancellation", "Bun cancellation"],
+  maxResults: 3,
+});
+
+// Keep failed inputs visible while using the successful results.
+for (const entry of search.results) {
+  if (!entry.ok) text({ input: entry.input, error: entry.error });
+}
+
+const urls = [...new Set(
+  search.results.flatMap(entry =>
+    entry.ok ? entry.value.results.map(hit => hit.url) : []
+  )
+)].slice(0, 5);
+
+if (!urls.length) exit();
+
+const pages = await tools.web_contents({ urls });
+text(pages.results.map(entry =>
+  entry.ok
+    ? { url: entry.value.url, excerpt: entry.value.content?.slice(0, 3000) }
+    : { url: entry.input, error: entry.error }
+));
+```
+
+For independent tasks, await every call with `Promise.allSettled`. This example
+requires an `answer` default and keeps one rejected call from discarding the
+other call's result:
+
+```js
+const answers = await Promise.allSettled([
+  tools.web_answer({ queries: ["What is an AbortSignal?"] }),
+  tools.web_answer({ queries: ["How does Bun handle cancellation?"] }),
+]);
+
+for (const answer of answers) {
+  if (answer.status === "fulfilled") text(answer.value);
+  else text({ error: String(answer.reason) });
+}
+```
+
+A Webfox document with `status: "partial"` still resolves: check each result's
+`ok` field before accessing `value`. Invalid arguments and blocked tool calls
+reject instead. Nested calls still pass through Pi's validation and permission
+hooks.
+
+To return less data, select the fields you need rather than emit a whole
+document. For example, this returns only titles and source URLs:
+
+```js
+const search = await tools.web_search({ queries: ["Node.js release notes"] });
+text(search.results.flatMap(entry =>
+  entry.ok
+    ? entry.value.results.map(({ title, url }) => ({ title, url }))
+    : [{ input: entry.input, error: entry.error }]
+));
+```
+
+Webfox tools belong to the `web` namespace, which you can search from scripts
+with `await searchTools("search", { namespace: "web" })`. To route all callable
+tools through scripts, set `"codemode": { "mode": "only" }` in Pi's settings
+alongside `defaultTools`. This setting affects all callable tools, not only
+Webfox.
+
 ## 📚 Use with TypeScript
 
 ```ts
@@ -266,6 +355,25 @@ The client also provides `contents`, `answer`, and `research`. See the
 [library reference](./docs/reference.md#typescript-library) for request controls,
 configuration, progress, and errors.
 
+## 🧬 Use with Pi Durable
+
+A custom Pi Durable host can install the web tools directly:
+
+```ts
+import { createWebfoxExtension } from "webfox/durable";
+
+registry.install(createWebfoxExtension({ cwd: process.cwd() }));
+```
+
+The adapter uses the shared Webfox configuration and provider-specific schemas.
+Each call follows its conversation's execution environment, streams progress,
+and preserves partial failures. Large text results are saved to private files.
+Interrupted requests are not replayed automatically, since providers may charge
+for them. Cancelling a request may not cancel a provider's already-running job.
+
+The adapter requires Pi Durable 1.0. It does not install a CLI, register standard
+Pi renderers, or provide codemode's structured-result interface.
+
 ## 🩺 Troubleshooting
 
 - **No provider selected:** Pass `--provider <id>` or save a default with

package/dist/{adapter-BQUN3ME2.js → adapter-IDKJASTU.js}

@@ -2,11 +2,11 @@ import {
   SERPBASE_MODES,
   serpbaseProvider,
   validateOptions
-} from "./chunk-KH54YH7D.js";
-import "./chunk-GPACLYNT.js";
+} from "./chunk-NOBEWI5W.js";
 import {
   trimSnippet
 } from "./chunk-X6ZBIHZC.js";
+import "./chunk-GPACLYNT.js";
 import {
   WebfoxError,
   httpError

package/dist/{chunk-D4HCJRBE.js → chunk-3LK52VNJ.js}

@@ -6,14 +6,14 @@ import {
 } from "./chunk-WCTOYZVB.js";
 import {
   configurationSchema
-} from "./chunk-VI3473TU.js";
+} from "./chunk-MLRWLHC2.js";
 import {
   effectiveOptions,
   optionSchema,
   providers,
   selectProvider,
   validateConfiguredOptions
-} from "./chunk-KH54YH7D.js";
+} from "./chunk-NOBEWI5W.js";
 import {
   cancelProcessGroup,
   killProcessGroup

package/dist/{chunk-VI3473TU.js → chunk-MLRWLHC2.js}

@@ -1,7 +1,7 @@
 import {
   optionSchema,
   providers
-} from "./chunk-KH54YH7D.js";
+} from "./chunk-NOBEWI5W.js";
 import {
   CAPABILITIES
 } from "./chunk-GPACLYNT.js";
@@ -9,7 +9,7 @@ import {
 // package.json
 var package_default = {
   name: "webfox",
-  version: "4.5.0",
+  version: "4.7.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: [
@@ -82,10 +82,14 @@ var package_default = {
       types: "./dist/pi.d.ts",
       import: "./dist/pi.js"
     },
+    "./durable": {
+      types: "./dist/durable.d.ts",
+      import: "./dist/durable.js"
+    },
     "./config.schema.json": "./dist/config.schema.json"
   },
   scripts: {
-    build: "rm -rf dist && esbuild index=src/index.ts cli=src/cli.ts pi=src/pi.ts generate-schema=scripts/generate-schema.ts --bundle --splitting --format=esm --platform=node --target=node22 --packages=external --outdir=dist && node dist/generate-schema.js && biome format --write src/config.schema.json >&2 && rm dist/generate-schema.js && tsc --project tsconfig.build.json && cp src/config.schema.json dist/config.schema.json && chmod +x dist/cli.js",
+    build: "rm -rf dist && esbuild index=src/index.ts cli=src/cli.ts pi=src/pi.ts durable=src/durable.ts generate-schema=scripts/generate-schema.ts --bundle --splitting --format=esm --platform=node --target=node22 --packages=external --outdir=dist && node dist/generate-schema.js && biome format --write src/config.schema.json >&2 && rm dist/generate-schema.js && tsc --project tsconfig.build.json && cp src/config.schema.json dist/config.schema.json && chmod +x dist/cli.js",
     prepare: "npm run build",
     prepack: "npm run build",
     check: "tsc --noEmit",
@@ -107,25 +111,31 @@ 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/chord": "^1.0.0",
+    "@earendil-works/pi-ai": "^1.0.0",
+    "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@earendil-works/pi-durable": "^1.0.0",
+    "@earendil-works/pi-tui": "^1.0.0",
     "@types/node": "^26.1.1",
     esbuild: "^0.28.1",
     typescript: "^7.0.2",
     vitest: "^4.1.10"
   },
   peerDependencies: {
+    "@earendil-works/pi-durable": "^1.0.0",
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    typebox: "*"
   },
   peerDependenciesMeta: {
+    "@earendil-works/pi-durable": {
+      optional: true
+    },
     "@earendil-works/pi-coding-agent": {
       optional: true
     },

package/dist/{chunk-KH54YH7D.js → chunk-NOBEWI5W.js}

@@ -1991,7 +1991,7 @@ var serpbaseProvider = defineProvider({
       retrySafe: true
     }
   },
-  load: async () => (await import("./adapter-BQUN3ME2.js")).adapter
+  load: async () => (await import("./adapter-IDKJASTU.js")).adapter
 });
 
 // src/providers/serper/definition.ts

package/dist/chunk-VVOQKYOP.js

@@ -0,0 +1,112 @@
+// src/tool-definition.ts
+import { Type } from "typebox";
+function webToolParameters(inspection) {
+  const capability = inspection.capability;
+  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 }), {
+      minItems: 1,
+      maxItems: 10
+    }),
+    ...capability === "search" ? { maxResults: Type.Optional(Type.Integer({ minimum: 1 })) } : {}
+  };
+  return Type.Object(
+    {
+      ...fields,
+      ...inspection.optionSchema ? {
+        options: Type.Optional(
+          inspection.optionSchema
+        )
+      } : {}
+    },
+    { additionalProperties: false }
+  );
+}
+var descriptions = {
+  search: "Search up to ten queries and return titles, URLs, and snippets in input order.",
+  contents: "Fetch and extract readable contents from web URLs.",
+  answer: "Answer up to ten questions using web-grounded evidence.",
+  research: "Run foreground multi-step web research and return the final report."
+};
+
+// src/pi-validation.ts
+import { stripVTControlCharacters } from "node:util";
+import { Check, Errors } from "typebox/value";
+function isSchema(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function alternatives(schema) {
+  return ["anyOf", "oneOf", "allOf"].flatMap(
+    (key) => Array.isArray(schema[key]) ? schema[key].filter(isSchema) : []
+  );
+}
+function acceptsPath(schema, path) {
+  if (schema === true) return true;
+  if (!isSchema(schema)) return false;
+  if (!path.length) return true;
+  if (alternatives(schema).some((branch) => acceptsPath(branch, path)))
+    return true;
+  const [key, ...rest] = path;
+  if (schema.type === "array") return acceptsPath(schema.items, rest);
+  if (schema.properties && Object.hasOwn(schema.properties, key))
+    return acceptsPath(schema.properties[key], rest);
+  if (isSchema(schema.patternProperties)) {
+    for (const [pattern, child] of Object.entries(schema.patternProperties))
+      if (new RegExp(pattern).test(key) && acceptsPath(child, rest))
+        return true;
+  }
+  if (schema.additionalProperties === false) return false;
+  if (schema.type && schema.type !== "object") return false;
+  if (alternatives(schema).length && !schema.properties && schema.additionalProperties === void 0)
+    return false;
+  return schema.additionalProperties === void 0 || acceptsPath(schema.additionalProperties, rest);
+}
+function displayPath(path) {
+  return path.map((part, index) => {
+    const safe = stripVTControlCharacters(part);
+    if (/^[a-zA-Z_][\w-]*$/.test(safe)) return `${index ? "." : ""}${safe}`;
+    if (/^\d+$/.test(safe)) return `[${safe}]`;
+    return `[${JSON.stringify(safe)}]`;
+  }).join("");
+}
+function locations(schema, name, path = []) {
+  if (!isSchema(schema)) return [];
+  const found = alternatives(schema).flatMap(
+    (branch) => locations(branch, name, path)
+  );
+  if (isSchema(schema.properties)) {
+    for (const [key, child] of Object.entries(schema.properties)) {
+      const next = [...path, key];
+      if (key === name) found.push(next);
+      found.push(...locations(child, name, next));
+    }
+  }
+  return found;
+}
+function prepareToolArguments(schema, args) {
+  if (Check(schema, args)) return args;
+  const messages = /* @__PURE__ */ new Set();
+  for (const error of Errors(schema, args)) {
+    if (error.keyword !== "additionalProperties") continue;
+    const names = error.params.additionalProperties;
+    if (!Array.isArray(names)) continue;
+    const parent = error.instancePath.split("/").slice(1).map((part) => part.replaceAll("~1", "/").replaceAll("~0", "~"));
+    for (const name of names) {
+      if (typeof name !== "string") continue;
+      const path = [...parent, name];
+      if (acceptsPath(schema, path)) continue;
+      const targets = [...new Set(locations(schema, name).map(displayPath))];
+      const suggestion = targets.length === 1 ? ` Use ${targets[0]} instead.` : " Check the tool's parameter schema.";
+      messages.add(`Invalid parameter: ${displayPath(path)}.${suggestion}`);
+      if (messages.size === 3) break;
+    }
+    if (messages.size === 3) break;
+  }
+  if (messages.size) throw new Error([...messages].join("\n"));
+  return args;
+}
+
+export {
+  webToolParameters,
+  descriptions,
+  prepareToolArguments
+};

package/dist/cli.js

@@ -11,14 +11,14 @@ import {
   redactConfig,
   resolveConfigPath,
   setCapabilityDefault
-} from "./chunk-D4HCJRBE.js";
+} from "./chunk-3LK52VNJ.js";
 import "./chunk-WCTOYZVB.js";
 import {
   PACKAGE_VERSION
-} from "./chunk-VI3473TU.js";
+} from "./chunk-MLRWLHC2.js";
 import {
   validateConfiguredOptions
-} from "./chunk-KH54YH7D.js";
+} from "./chunk-NOBEWI5W.js";
 import "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES,

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/durable.d.ts

@@ -0,0 +1,8 @@
+import { type Extension } from "@earendil-works/pi-durable";
+import { type WebfoxClient, type CreateWebfoxOptions } from "./index.js";
+export interface DurableWebfoxOptions extends CreateWebfoxOptions {
+    /** Supply a client for an embedded host or deterministic tests. */
+    client?: WebfoxClient;
+}
+/** Install alongside CodingTools. Every call uses the conversation's current environment. */
+export declare function createWebfoxExtension(options?: DurableWebfoxOptions): Extension;

package/dist/durable.js

@@ -0,0 +1,124 @@
+import {
+  descriptions,
+  prepareToolArguments,
+  webToolParameters
+} from "./chunk-VVOQKYOP.js";
+import {
+  renderTextDocument
+} from "./chunk-BTWECET5.js";
+import {
+  createWebfox
+} from "./chunk-3LK52VNJ.js";
+import "./chunk-WCTOYZVB.js";
+import "./chunk-MLRWLHC2.js";
+import "./chunk-NOBEWI5W.js";
+import "./chunk-ZVTVERW5.js";
+import {
+  CAPABILITIES
+} from "./chunk-GPACLYNT.js";
+import "./chunk-U4BLULLV.js";
+
+// src/durable.ts
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  truncateHead,
+  withFileMutationQueue
+} from "@earendil-works/pi-coding-agent";
+import {
+  defineExtension,
+  defineTool
+} from "@earendil-works/pi-durable";
+function createWebfoxExtension(options = {}) {
+  const clients = /* @__PURE__ */ new Map();
+  const clientFor = (cwd) => {
+    if (options.client) return options.client;
+    let client = clients.get(cwd);
+    if (!client) {
+      client = createWebfox({ ...options, cwd });
+      clients.set(cwd, client);
+    }
+    return client;
+  };
+  const initialCwd = options.cwd ?? process.cwd();
+  const initial = clientFor(initialCwd);
+  const inspections = CAPABILITIES.map(
+    (capability) => initial.inspectCapability(capability)
+  ).filter((inspection) => inspection.provider);
+  return defineExtension({
+    name: "webfox",
+    tools: inspections.map((inspection) => {
+      const capability = inspection.capability;
+      const parameters = webToolParameters(inspection);
+      return defineTool({
+        name: `web_${capability}`,
+        description: [
+          descriptions[capability],
+          ...inspection.promptGuidelines ?? [],
+          "Output is limited to 2000 lines or 50 KiB; complete results are saved to a private file when truncated."
+        ].join("\n"),
+        parameters,
+        // Web requests may incur charges. A crash reports interruption rather than silently charging again.
+        replay: "unsafe",
+        prepareArguments: (args) => prepareToolArguments(parameters, args),
+        async execute(args, api, context) {
+          const client = clientFor(
+            api.env?.cwd ?? (await api.agent(context)).cwd ?? initialCwd
+          );
+          const request = {
+            provider: inspection.provider,
+            signal: context.abortSignal,
+            options: args.options,
+            onProgress: (event) => api.output(`${event.message}
+`)
+          };
+          const result = capability === "search" ? await client.search({
+            ...request,
+            queries: args.queries,
+            maxResults: args.maxResults
+          }) : capability === "contents" ? await client.contents({
+            ...request,
+            urls: args.urls
+          }) : capability === "answer" ? await client.answer({
+            ...request,
+            queries: args.queries
+          }) : await client.research({
+            ...request,
+            input: args.input
+          });
+          const truncated = truncateHead(renderTextDocument(result));
+          let body = truncated.content;
+          let fullOutputPath;
+          if (truncated.truncated) {
+            fullOutputPath = join(
+              await mkdtemp(join(tmpdir(), "web-")),
+              "result.json"
+            );
+            await withFileMutationQueue(
+              fullOutputPath,
+              () => writeFile(fullOutputPath, JSON.stringify(result), {
+                mode: 384
+              })
+            );
+            body += `
+
+Full results: ${fullOutputPath}`;
+          }
+          return {
+            content: [{ type: "text", text: body }],
+            isError: result.status === "partial",
+            details: {
+              status: result.status,
+              capability,
+              ...fullOutputPath ? { fullOutputPath } : {}
+            }
+          };
+        }
+      });
+    })
+  });
+}
+export {
+  createWebfoxExtension
+};

package/dist/index.js

@@ -6,14 +6,14 @@ import {
   resolveConfigPath,
   setCapabilityDefault,
   validateConfig
-} from "./chunk-D4HCJRBE.js";
+} from "./chunk-3LK52VNJ.js";
 import "./chunk-WCTOYZVB.js";
 import {
   CONFIG_SCHEMA_URL
-} from "./chunk-VI3473TU.js";
+} from "./chunk-MLRWLHC2.js";
 import {
   validateConfiguredOptions
-} from "./chunk-KH54YH7D.js";
+} from "./chunk-NOBEWI5W.js";
 import "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES,

package/dist/pi.js

@@ -1,16 +1,23 @@
+import {
+  descriptions,
+  prepareToolArguments,
+  webToolParameters
+} from "./chunk-VVOQKYOP.js";
 import {
   renderTextDocument
 } from "./chunk-BTWECET5.js";
 import {
   createWebfox,
   resolveConfigPath
-} from "./chunk-D4HCJRBE.js";
+} from "./chunk-3LK52VNJ.js";
 import "./chunk-WCTOYZVB.js";
-import "./chunk-VI3473TU.js";
-import "./chunk-KH54YH7D.js";
+import "./chunk-MLRWLHC2.js";
+import "./chunk-NOBEWI5W.js";
 import "./chunk-ZVTVERW5.js";
 import {
-  CAPABILITIES
+  CAPABILITIES,
+  PROVIDER_IDS,
+  WEBFOX_ERROR_CODES
 } from "./chunk-GPACLYNT.js";
 import {
   WebfoxError
@@ -24,7 +31,6 @@ import {
   truncateHead,
   withFileMutationQueue
 } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
 
 // src/pi-render.ts
 import { stripVTControlCharacters as stripVTControlCharacters3 } from "node:util";
@@ -186,11 +192,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 +215,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 +310,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) {
@@ -340,83 +346,6 @@ function renderWebResult(result, options, theme, isError, capability) {
   };
 }
 
-// src/pi-validation.ts
-import { stripVTControlCharacters as stripVTControlCharacters4 } from "node:util";
-import { Check, Errors } from "typebox/value";
-function isSchema(value) {
-  return !!value && typeof value === "object" && !Array.isArray(value);
-}
-function alternatives(schema) {
-  return ["anyOf", "oneOf", "allOf"].flatMap(
-    (key) => Array.isArray(schema[key]) ? schema[key].filter(isSchema) : []
-  );
-}
-function acceptsPath(schema, path) {
-  if (schema === true) return true;
-  if (!isSchema(schema)) return false;
-  if (!path.length) return true;
-  if (alternatives(schema).some((branch) => acceptsPath(branch, path)))
-    return true;
-  const [key, ...rest] = path;
-  if (schema.type === "array") return acceptsPath(schema.items, rest);
-  if (schema.properties && Object.hasOwn(schema.properties, key))
-    return acceptsPath(schema.properties[key], rest);
-  if (isSchema(schema.patternProperties)) {
-    for (const [pattern, child] of Object.entries(schema.patternProperties))
-      if (new RegExp(pattern).test(key) && acceptsPath(child, rest))
-        return true;
-  }
-  if (schema.additionalProperties === false) return false;
-  if (schema.type && schema.type !== "object") return false;
-  if (alternatives(schema).length && !schema.properties && schema.additionalProperties === void 0)
-    return false;
-  return schema.additionalProperties === void 0 || acceptsPath(schema.additionalProperties, rest);
-}
-function displayPath(path) {
-  return path.map((part, index) => {
-    const safe = stripVTControlCharacters4(part);
-    if (/^[a-zA-Z_][\w-]*$/.test(safe)) return `${index ? "." : ""}${safe}`;
-    if (/^\d+$/.test(safe)) return `[${safe}]`;
-    return `[${JSON.stringify(safe)}]`;
-  }).join("");
-}
-function locations(schema, name, path = []) {
-  if (!isSchema(schema)) return [];
-  const found = alternatives(schema).flatMap(
-    (branch) => locations(branch, name, path)
-  );
-  if (isSchema(schema.properties)) {
-    for (const [key, child] of Object.entries(schema.properties)) {
-      const next = [...path, key];
-      if (key === name) found.push(next);
-      found.push(...locations(child, name, next));
-    }
-  }
-  return found;
-}
-function prepareToolArguments(schema, args) {
-  if (Check(schema, args)) return args;
-  const messages = /* @__PURE__ */ new Set();
-  for (const error of Errors(schema, args)) {
-    if (error.keyword !== "additionalProperties") continue;
-    const names = error.params.additionalProperties;
-    if (!Array.isArray(names)) continue;
-    const parent = error.instancePath.split("/").slice(1).map((part) => part.replaceAll("~1", "/").replaceAll("~0", "~"));
-    for (const name of names) {
-      if (typeof name !== "string") continue;
-      const path = [...parent, name];
-      if (acceptsPath(schema, path)) continue;
-      const targets = [...new Set(locations(schema, name).map(displayPath))];
-      const suggestion = targets.length === 1 ? ` Use ${targets[0]} instead.` : " Check the tool's parameter schema.";
-      messages.add(`Invalid parameter: ${displayPath(path)}.${suggestion}`);
-      if (messages.size === 3) break;
-    }
-    if (messages.size === 3) break;
-  }
-  if (messages.size) throw new Error([...messages].join("\n"));
-  return args;
-}
-
 // src/pi-diagnostics.ts
 import { homedir } from "node:os";
 import { sep } from "node:path";
@@ -435,6 +364,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,34 +483,27 @@ 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 }), {
-        minItems: 1,
-        maxItems: 10
-      }),
-      ...capability === "search" ? { maxResults: Type.Optional(Type.Integer({ minimum: 1 })) } : {}
-    };
-    const parameters = Type.Object(
-      {
-        ...fields,
-        ...inspection.optionSchema ? {
-          options: Type.Optional(
-            inspection.optionSchema
-          )
-        } : {}
-      },
-      { additionalProperties: false }
-    );
+    const parameters = webToolParameters(inspection);
     pi.registerTool({
       name: `web_${capability}`,
+      namespace: {
+        name: "web",
+        description: "Search, extract pages, answer, and research the web."
+      },
       label: `Web ${capability[0].toUpperCase()}${capability.slice(1)}`,
       // 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."
+        "Model-facing text is truncated to 2000 lines or 50 KiB; full results are saved to a file when truncated. Codemode scripts receive complete structured results."
       ].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 +551,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 +563,7 @@ function webExtension(pi) {
           );
           await withFileMutationQueue(
             fullOutputPath,
-            () => writeFile(fullOutputPath, JSON.stringify(result), { mode: 384 })
+            () => writeFile(fullOutputPath, json, { mode: 384 })
           );
           body += `
 
@@ -569,8 +571,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,17 +589,7 @@ 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.",
-  contents: "Fetch and extract readable contents from web URLs.",
-  answer: "Answer up to ten questions using web-grounded evidence.",
-  research: "Run foreground multi-step web research and return the final report."
-};
 export {
   webExtension as default
 };

package/dist/tool-definition.d.ts

@@ -0,0 +1,4 @@
+import { type TObject } from "typebox";
+import type { Capability, WebfoxClient } from "./index.js";
+export declare function webToolParameters(inspection: ReturnType<WebfoxClient["inspectCapability"]>): TObject;
+export declare const descriptions: Record<Capability, string>;

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.7.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": [
@@ -73,10 +73,14 @@
       "types": "./dist/pi.d.ts",
       "import": "./dist/pi.js"
     },
+    "./durable": {
+      "types": "./dist/durable.d.ts",
+      "import": "./dist/durable.js"
+    },
     "./config.schema.json": "./dist/config.schema.json"
   },
   "scripts": {
-    "build": "rm -rf dist && esbuild index=src/index.ts cli=src/cli.ts pi=src/pi.ts generate-schema=scripts/generate-schema.ts --bundle --splitting --format=esm --platform=node --target=node22 --packages=external --outdir=dist && node dist/generate-schema.js && biome format --write src/config.schema.json >&2 && rm dist/generate-schema.js && tsc --project tsconfig.build.json && cp src/config.schema.json dist/config.schema.json && chmod +x dist/cli.js",
+    "build": "rm -rf dist && esbuild index=src/index.ts cli=src/cli.ts pi=src/pi.ts durable=src/durable.ts generate-schema=scripts/generate-schema.ts --bundle --splitting --format=esm --platform=node --target=node22 --packages=external --outdir=dist && node dist/generate-schema.js && biome format --write src/config.schema.json >&2 && rm dist/generate-schema.js && tsc --project tsconfig.build.json && cp src/config.schema.json dist/config.schema.json && chmod +x dist/cli.js",
     "prepare": "npm run build",
     "prepack": "npm run build",
     "check": "tsc --noEmit",
@@ -98,25 +102,31 @@
     "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/chord": "^1.0.0",
+    "@earendil-works/pi-ai": "^1.0.0",
+    "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@earendil-works/pi-durable": "^1.0.0",
+    "@earendil-works/pi-tui": "^1.0.0",
     "@types/node": "^26.1.1",
     "esbuild": "^0.28.1",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
+    "@earendil-works/pi-durable": "^1.0.0",
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
+    "@earendil-works/pi-durable": {
+      "optional": true
+    },
     "@earendil-works/pi-coding-agent": {
       "optional": true
     },