@demigodmode/pi-web-agent 1.9.0 → 1.11.0

package/dist/backends/factory.js

@@ -1,6 +1,10 @@
 import { createFirecrawlFetcher } from '../fetch/firecrawl-fetch.js';
+import { createHttpFetcher } from '../fetch/http-fetch.js';
+import { createProxyFetch, resolveProxyCredentials } from '../fetch/proxy-fetch.js';
+import { headlessFetch } from '../fetch/headless-fetch.js';
 import { createBraveSearchTool } from '../search/brave.js';
 import { createYouComSearchTool } from '../search/youcom.js';
+import { fetchDuckDuckGoHtml } from '../search/duckduckgo.js';
 import { createExaSearchTool } from '../search/exa.js';
 import { createTavilySearchTool } from '../search/tavily.js';
 import { createSearxngSearchTool } from '../search/searxng.js';
@@ -10,7 +14,7 @@ import { buildSearchPresentation } from '../presentation/search-presentation.js'
 import { createWebFetchHeadlessTool } from '../tools/web-fetch-headless.js';
 import { createWebFetchTool } from '../tools/web-fetch.js';
 import { createWebSearchTool } from '../tools/web-search.js';
-import { DEFAULT_BACKEND_CONFIG, usableSearchProviders } from './config.js';
+import { DEFAULT_BACKEND_CONFIG, isValidProxyUrl, stripProxyCredentials, usableSearchProviders } from './config.js';
 import { createSpecialContentResolver } from '../readers/resolver.js';
 import { createGithubReader } from '../readers/github-reader.js';
 import { createPdfReader } from '../readers/pdf-reader.js';
@@ -54,7 +58,10 @@ function withSearchFallback(primary, fallback, fallbackFrom) {
             metadata: {
                 ...second.metadata,
                 fallbackFrom,
-                fallbackReason: first.error?.message ?? `${fallbackFrom} search failed.`
+                fallbackReason: first.error?.message ?? `${fallbackFrom} search failed.`,
+                // Keep the primary's fanout provenance (which providers were tried/skipped) even though
+                // the answer came from the fallback backend.
+                ...(first.metadata.fanout ? { fanout: first.metadata.fanout } : {})
             }
         };
         return { ...result, presentation: buildSearchPresentation(result) };
@@ -87,52 +94,104 @@ export function createBackendSet(config = DEFAULT_BACKEND_CONFIG, deps = {}) {
     const createHttpFetch = deps.createHttpFetch ?? createWebFetchTool;
     const createFirecrawlFetch = deps.createFirecrawlFetch ?? createFirecrawlFetcher;
     const createHeadlessFetch = deps.createHeadlessFetch ?? createWebFetchHeadlessTool;
+    const makeProxyFetch = deps.createProxyFetch ?? createProxyFetch;
+    // A blank url is the "disable proxy" marker: treat it as no proxy at all.
+    const proxy = config.proxy && config.proxy.url.trim() !== '' ? config.proxy : undefined;
+    // A configured proxy whose url fails validation must not be silently ignored
+    // — that would send traffic direct to the websites. Every request errors out
+    // instead. No connectivity check is needed: the url itself is the problem.
+    if (proxy && !isValidProxyUrl(proxy.url)) {
+        const message = `backends.proxy.url (${proxy.url}) is not a valid http or https URL. ` +
+            'Web requests are blocked until it is fixed; set backends.proxy.url to "" to disable the proxy.';
+        return {
+            search: async () => {
+                const result = {
+                    status: 'error',
+                    results: [],
+                    metadata: { backend: config.search.provider, cacheHit: false },
+                    error: { code: 'BACKEND_CONFIG_INVALID', message }
+                };
+                return { ...result, presentation: buildSearchPresentation(result) };
+            },
+            fetchPage: async ({ url }) => {
+                const result = {
+                    status: 'error',
+                    url,
+                    metadata: { method: 'http', cacheHit: false },
+                    error: { code: 'BACKEND_CONFIG_INVALID', message }
+                };
+                return { ...result, presentation: buildFetchPresentation(result) };
+            },
+            headlessFetch: async ({ url }) => {
+                const result = {
+                    status: 'error',
+                    url,
+                    metadata: { method: 'headless', cacheHit: false },
+                    error: { code: 'BACKEND_CONFIG_INVALID', message }
+                };
+                return { ...result, presentation: buildFetchPresentation(result) };
+            }
+        };
+    }
+    // When a proxy is configured, every outbound HTTP request (search, fetch,
+    // readers, and doctor-style checks) goes through it; headless browser
+    // traffic gets the same proxy via Playwright launch options.
+    const fetchImpl = proxy ? makeProxyFetch(proxy) : fetch;
+    const proxyCredentials = proxy ? resolveProxyCredentials(proxy) : undefined;
+    const proxyBrowserOptions = proxy
+        ? {
+            server: stripProxyCredentials(proxy.url),
+            ...(proxyCredentials?.username !== undefined ? { username: proxyCredentials.username } : {}),
+            ...(proxyCredentials?.password !== undefined ? { password: proxyCredentials.password } : {})
+        }
+        : undefined;
+    const createDuckDuckGo = () => createDuckDuckGoSearch({ searchHtml: (query) => fetchDuckDuckGoHtml(query, { fetchImpl }) });
     function buildProviderSearch(name) {
         switch (name) {
             case 'searxng':
                 return config.search.baseUrl
-                    ? createSearxngSearch({ baseUrl: config.search.baseUrl, options: config.search.options })
+                    ? createSearxngSearch({ baseUrl: config.search.baseUrl, options: config.search.options, fetchImpl })
                     : invalidSearxngSearch();
             case 'brave':
-                return createBraveSearch({ apiKey: process.env.PI_WEB_AGENT_BRAVE_API_KEY });
+                return createBraveSearch({ apiKey: process.env.PI_WEB_AGENT_BRAVE_API_KEY, fetchImpl });
             case 'youcom':
-                return createYouComSearch({ apiKey: process.env.YDC_API_KEY });
+                return createYouComSearch({ apiKey: process.env.YDC_API_KEY, fetchImpl });
             case 'exa':
-                return createExaSearch({ apiKey: process.env.EXA_API_KEY });
+                return createExaSearch({ apiKey: process.env.EXA_API_KEY, fetchImpl });
             case 'tavily':
-                return createTavilySearch({ apiKey: process.env.TAVILY_API_KEY });
+                return createTavilySearch({ apiKey: process.env.TAVILY_API_KEY, fetchImpl });
             case 'duckduckgo':
             default:
-                return createDuckDuckGoSearch();
+                return createDuckDuckGo();
         }
     }
     let search = config.search.provider === 'searxng'
         ? config.search.baseUrl
-            ? createSearxngSearch({ baseUrl: config.search.baseUrl, options: config.search.options })
+            ? createSearxngSearch({ baseUrl: config.search.baseUrl, options: config.search.options, fetchImpl })
             : invalidSearxngSearch()
         : config.search.provider === 'brave'
-            ? createBraveSearch({ apiKey: process.env.PI_WEB_AGENT_BRAVE_API_KEY })
+            ? createBraveSearch({ apiKey: process.env.PI_WEB_AGENT_BRAVE_API_KEY, fetchImpl })
             : config.search.provider === 'youcom'
-                ? createYouComSearch({ apiKey: process.env.YDC_API_KEY })
+                ? createYouComSearch({ apiKey: process.env.YDC_API_KEY, fetchImpl })
                 : config.search.provider === 'exa'
-                    ? createExaSearch({ apiKey: process.env.EXA_API_KEY })
+                    ? createExaSearch({ apiKey: process.env.EXA_API_KEY, fetchImpl })
                     : config.search.provider === 'tavily'
-                        ? createTavilySearch({ apiKey: process.env.TAVILY_API_KEY })
-                        : createDuckDuckGoSearch();
+                        ? createTavilySearch({ apiKey: process.env.TAVILY_API_KEY, fetchImpl })
+                        : createDuckDuckGo();
     if (config.search.provider === 'searxng' && config.search.fallback === 'duckduckgo') {
-        search = withSearchFallback(search, createDuckDuckGoSearch(), 'searxng');
+        search = withSearchFallback(search, createDuckDuckGo(), 'searxng');
     }
     if (config.search.provider === 'brave' && config.search.fallback === 'duckduckgo') {
-        search = withSearchFallback(search, createDuckDuckGoSearch(), 'brave');
+        search = withSearchFallback(search, createDuckDuckGo(), 'brave');
     }
     if (config.search.provider === 'youcom' && config.search.fallback === 'duckduckgo') {
-        search = withSearchFallback(search, createDuckDuckGoSearch(), 'youcom');
+        search = withSearchFallback(search, createDuckDuckGo(), 'youcom');
     }
     if (config.search.provider === 'exa' && config.search.fallback === 'duckduckgo') {
-        search = withSearchFallback(search, createDuckDuckGoSearch(), 'exa');
+        search = withSearchFallback(search, createDuckDuckGo(), 'exa');
     }
     if (config.search.provider === 'tavily' && config.search.fallback === 'duckduckgo') {
-        search = withSearchFallback(search, createDuckDuckGoSearch(), 'tavily');
+        search = withSearchFallback(search, createDuckDuckGo(), 'tavily');
     }
     const fanoutConfig = config.search.fanout;
     if (fanoutConfig && fanoutConfig.mode !== 'off') {
@@ -149,14 +208,23 @@ export function createBackendSet(config = DEFAULT_BACKEND_CONFIG, deps = {}) {
             mode: fanoutConfig.mode
         });
     }
-    const httpFetch = createHttpFetch();
+    // Keep the keyless Tavily safety net for the no-key DuckDuckGo default, even under fanout —
+    // it wraps whatever search ended up being (plain DDG or the fanout set) so a total failure
+    // still has somewhere to go. Opt out with PI_WEB_AGENT_DISABLE_KEYLESS_FALLBACK=1.
+    const keylessFallbackDisabled = process.env.PI_WEB_AGENT_DISABLE_KEYLESS_FALLBACK === '1';
+    const usingDuckDuckGoDefault = config.search.provider === 'duckduckgo' || !config.search.provider;
+    if (usingDuckDuckGoDefault && !keylessFallbackDisabled) {
+        search = withSearchFallback(search, createTavilySearch({ keyless: true, fetchImpl }), 'duckduckgo');
+    }
+    const httpFetch = createHttpFetch({ fetchPage: createHttpFetcher({ fetchImpl }) });
     let fetchPage = config.fetch.provider === 'firecrawl'
         ? config.fetch.baseUrl
             ? createHttpFetch({
                 fetchPage: createFirecrawlFetch({
                     baseUrl: config.fetch.baseUrl,
                     apiKey: config.fetch.apiKey ?? process.env.PI_WEB_AGENT_FIRECRAWL_API_KEY,
-                    options: config.fetch.options
+                    options: config.fetch.options,
+                    fetchImpl
                 })
             })
             : createHttpFetch({ fetchPage: invalidFirecrawlFetch() })
@@ -165,12 +233,13 @@ export function createBackendSet(config = DEFAULT_BACKEND_CONFIG, deps = {}) {
         fetchPage = withFetchFallback(fetchPage, httpFetch);
     }
     const fetchPageWithReaders = createSpecialContentResolver({
-        readers: [createGithubReader(), createPdfReader(), createYoutubeReader()],
+        readers: [createGithubReader({ fetchImpl }), createPdfReader({ fetchImpl }), createYoutubeReader({ fetchImpl })],
         fallback: fetchPage
     });
+    const headlessPage = (url) => proxyBrowserOptions ? headlessFetch(url, { proxy: proxyBrowserOptions }) : headlessFetch(url);
     return {
         search,
         fetchPage: fetchPageWithReaders,
-        headlessFetch: createHeadlessFetch()
+        headlessFetch: createHeadlessFetch({ fetchPage: headlessPage })
     };
 }

package/dist/commands/web-agent-config.d.ts

@@ -16,6 +16,9 @@ type CommandDeps = {
         arch: string;
     };
     checkTypebox?: () => Promise<boolean>;
+    checkJitiCompat?: () => {
+        pending: string[];
+    };
     checkBackends?: (config: BackendConfig) => Promise<string[]>;
     getChangelog?: () => Promise<string | undefined>;
 };

package/dist/commands/web-agent-config.js

@@ -1,10 +1,12 @@
-import { DEFAULT_BACKEND_CONFIG, mergeBackendConfigLayers, validateBackendConfig, usableSearchProviders } from '../backends/config.js';
+import { DEFAULT_BACKEND_CONFIG, isValidProxyUrl, mergeBackendConfigLayers, stripProxyCredentials, validateBackendConfig, usableSearchProviders } from '../backends/config.js';
 import { checkBackendHealth } from '../backends/doctor.js';
 import { DynamicBorder, getSettingsListTheme } from '@earendil-works/pi-coding-agent';
 import { Container, Input, SelectList, SettingsList, Text } from '@earendil-works/pi-tui';
 import { DEFAULT_PRESENTATION_CONFIG, mergePresentationConfigLayers, resolvePresentationMode } from '../presentation/config.js';
 import { loadPresentationConfigLayers, resetPresentationConfigScope, saveBackendConfigScope, savePresentationConfigScope } from '../presentation/config-store.js';
 import { resolveBrowserExecutable } from '../fetch/browser-resolution.js';
+import { createProxyFetch } from '../fetch/proxy-fetch.js';
+import { checkJitiCompat } from '../jiti-compat.js';
 import { getLatestChangelogEntry } from '../changelog-notice.js';
 const PRESENTATION_TOOL_NAMES = ['web_explore'];
 function parseScopeToken(token) {
@@ -29,7 +31,8 @@ function cloneBackendConfig(config) {
             ...config.fetch,
             options: config.fetch.options ? { ...config.fetch.options } : undefined
         },
-        headless: { ...config.headless }
+        headless: { ...config.headless },
+        proxy: config.proxy ? { ...config.proxy } : undefined
     };
 }
 function sameJson(left, right) {
@@ -47,6 +50,21 @@ export function validateBackendUrl(value) {
         return { ok: false, message: 'Invalid URL. Include http:// or https://.' };
     }
 }
+/**
+ * The extension re-applies this patch on load, so `pending` here means the
+ * patch could not be written (read-only install, permissions, or a dependency
+ * whose shape changed). Point at the manual script in that case: it is the
+ * same recovery step people have been finding by digging through issue #34.
+ */
+function formatJitiCompatLine(status) {
+    if (status.pending.length === 0)
+        return 'jsdom compat patch: ok';
+    return [
+        `jsdom compat patch: needed (${status.pending.join(', ')})`,
+        'Run: node ~/.pi/agent/npm/node_modules/@demigodmode/pi-web-agent/scripts/patch-jiti-compat.mjs',
+        'then restart Pi.'
+    ].join('\n');
+}
 async function defaultCheckTypebox() {
     try {
         await import('typebox');
@@ -87,8 +105,11 @@ function formatBackendSummary(config = DEFAULT_BACKEND_CONFIG) {
     return [
         searchSuffix ? `${searchBase} ${searchSuffix}` : searchBase,
         fetchSuffix ? `${fetchBase} ${fetchSuffix}` : fetchBase,
-        `headless: ${config.headless.provider}`
-    ].join('\n');
+        `headless: ${config.headless.provider}`,
+        config.proxy ? `proxy: ${stripProxyCredentials(config.proxy.url)}` : undefined
+    ]
+        .filter(Boolean)
+        .join('\n');
 }
 function formatConfigSummary(config) {
     const lines = [`defaultMode: ${config.defaultMode}`];
@@ -249,6 +270,12 @@ function buildBackendSettingsItems(scope, backends, theme, onUrlEditorOpenChange
             label: 'Firecrawl API key',
             currentValue: 'env var',
             values: ['env var']
+        },
+        {
+            id: 'backend:proxy:url',
+            label: 'Proxy URL',
+            currentValue: backends.proxy ? stripProxyCredentials(backends.proxy.url) : 'not set',
+            submenu: createBackendUrlEditor(theme, 'HTTP proxy URL', 'http://127.0.0.1:7890', onUrlEditorOpenChange)
         }
     ];
 }
@@ -421,6 +448,14 @@ export function applySettingsValue(state, id, newValue) {
             delete currentBackends.fetch.baseUrl;
         }
     }
+    if (id === 'backend:proxy:url') {
+        if (newValue.trim()) {
+            currentBackends.proxy = { ...currentBackends.proxy, url: newValue.trim() };
+        }
+        else {
+            delete currentBackends.proxy;
+        }
+    }
     nextDrafts[nextScope] = currentDraft;
     nextBackendDrafts[nextScope] = currentBackends;
     return {
@@ -485,6 +520,17 @@ export function collapseBackendConfigToOverride(config, inheritedConfig) {
     if (!sameJson(config.headless, inheritedConfig.headless)) {
         override.headless = { ...config.headless };
     }
+    if (!sameJson(config.proxy, inheritedConfig.proxy)) {
+        if (config.proxy) {
+            const { password: _password, ...proxy } = config.proxy;
+            override.proxy = { ...proxy };
+        }
+        else if (inheritedConfig.proxy) {
+            // The proxy was cleared at this scope; record an explicit disable so it
+            // overrides a proxy set in a lower (e.g. global) layer.
+            override.proxy = { url: '' };
+        }
+    }
     return override;
 }
 export function handleSettingsShortcut(data) {
@@ -669,7 +715,12 @@ export function registerWebAgentConfigCommands(pi, deps = {}) {
         arch: process.arch
     };
     const checkTypebox = deps.checkTypebox ?? defaultCheckTypebox;
-    const checkBackends = deps.checkBackends ?? ((config) => checkBackendHealth(config));
+    const checkCompat = deps.checkJitiCompat ?? checkJitiCompat;
+    const checkBackends = deps.checkBackends ?? ((config) => checkBackendHealth(config, {
+        // An invalid proxy url is reported by validateBackendConfig below; never
+        // build a proxy agent from it (no connectivity check is attempted).
+        fetchImpl: config.proxy && isValidProxyUrl(config.proxy.url) ? createProxyFetch(config.proxy) : fetch
+    }));
     const getChangelog = deps.getChangelog ?? (() => getLatestChangelogEntry());
     pi.registerCommand('web-agent', {
         description: 'Open settings or manage pi-web-agent presentation config',
@@ -700,6 +751,7 @@ export function registerWebAgentConfigCommands(pi, deps = {}) {
                     'pi-web-agent: loaded',
                     `runtime: node ${runtime.nodeVersion} ${runtime.platform} ${runtime.arch}`,
                     `typebox: ${typeboxOk ? 'ok' : 'missing'}`,
+                    formatJitiCompatLine(checkCompat()),
                     formatBackendSummary(backendConfig),
                     backendIssues.length > 0 ? `backend config: warning\n${backendIssues.join('\n')}` : 'backend config: ok',
                     ...backendHealth

package/dist/extension.d.ts

@@ -1,2 +1,3 @@
+import './jiti-compat-run.js';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 export default function extension(pi: ExtensionAPI): void;

package/dist/extension.js

@@ -1,3 +1,5 @@
+// Keep first: re-applies the jsdom/jiti compat patch before jsdom loads (#34).
+import './jiti-compat-run.js';
 import { DEFAULT_BACKEND_CONFIG } from './backends/config.js';
 import { Type } from 'typebox';
 import { registerWebAgentConfigCommands } from './commands/web-agent-config.js';

package/dist/fetch/headless-fetch.d.ts

@@ -1,13 +1,20 @@
 import { type BrowserResolutionResult } from './browser-resolution.js';
 import type { WebFetchHeadlessResponse } from '../types.js';
-export declare function headlessFetch(url: string, { configuredPath, resolveBrowser, launchBrowser, now }?: {
+export type BrowserProxyOptions = {
+    server: string;
+    username?: string;
+    password?: string;
+};
+export declare function headlessFetch(url: string, { configuredPath, proxy, resolveBrowser, launchBrowser, now }?: {
     configuredPath?: string;
+    proxy?: BrowserProxyOptions;
     resolveBrowser?: (options?: {
         configuredPath?: string;
     }) => Promise<BrowserResolutionResult>;
     launchBrowser?: (options: {
         executablePath?: string;
         headless: true;
+        proxy?: BrowserProxyOptions;
     }) => Promise<{
         newContext: () => Promise<{
             newPage: () => Promise<any>;

package/dist/fetch/headless-fetch.js

@@ -7,7 +7,7 @@ function cleanupRenderedText(text) {
     cleaned = cleaned.replace(/\s+/g, ' ').trim();
     return cleaned;
 }
-export async function headlessFetch(url, { configuredPath, resolveBrowser = (options) => resolveBrowserExecutable({ configuredPath: options?.configuredPath }), launchBrowser = ({ executablePath, headless }) => chromium.launch(executablePath ? { executablePath, headless } : { headless }), now = () => Date.now() } = {}) {
+export async function headlessFetch(url, { configuredPath, proxy, resolveBrowser = (options) => resolveBrowserExecutable({ configuredPath: options?.configuredPath }), launchBrowser = ({ executablePath, headless, proxy }) => chromium.launch(executablePath ? { executablePath, headless, ...(proxy ? { proxy } : {}) } : { headless, ...(proxy ? { proxy } : {}) }), now = () => Date.now() } = {}) {
     const resolved = await resolveBrowser({ configuredPath });
     if (!resolved.ok && resolved.error.code === 'CONFIGURED_BROWSER_NOT_FOUND') {
         return {
@@ -19,8 +19,8 @@ export async function headlessFetch(url, { configuredPath, resolveBrowser = (opt
     }
     const browserName = resolved.ok ? resolved.browser : 'chromium';
     const launchOptions = resolved.ok
-        ? { executablePath: resolved.executablePath, headless: true }
-        : { headless: true };
+        ? { executablePath: resolved.executablePath, headless: true, ...(proxy ? { proxy } : {}) }
+        : { headless: true, ...(proxy ? { proxy } : {}) };
     let browser;
     let context;
     let page;

package/dist/fetch/proxy-fetch.d.ts

@@ -0,0 +1,22 @@
+import { type ProxyConfig } from '../backends/config.js';
+export type ProxyCredentials = {
+    username?: string;
+    password?: string;
+};
+export type ProxyFetchOptions = {
+    /** TLS options for the tunneled connection to the origin (https targets). */
+    tls?: {
+        rejectUnauthorized?: boolean;
+    };
+};
+/**
+ * Resolve proxy credentials from the config, falling back to environment
+ * variables so secrets can stay out of config files (same policy as API keys).
+ */
+export declare function resolveProxyCredentials(proxy: ProxyConfig, env?: NodeJS.ProcessEnv): ProxyCredentials;
+/**
+ * Build a fetch implementation that routes all traffic through the configured
+ * HTTP/HTTPS proxy. Uses undici (the engine behind Node's global fetch) with a
+ * ProxyAgent dispatcher while keeping the standard fetch API surface.
+ */
+export declare function createProxyFetch(proxy: ProxyConfig, options?: ProxyFetchOptions): typeof fetch;

package/dist/fetch/proxy-fetch.js

@@ -0,0 +1,46 @@
+import { fetch as undiciFetch, ProxyAgent } from 'undici';
+import { stripProxyCredentials } from '../backends/config.js';
+/**
+ * Resolve proxy credentials from the config, falling back to environment
+ * variables so secrets can stay out of config files (same policy as API keys).
+ */
+export function resolveProxyCredentials(proxy, env = process.env) {
+    const username = proxy.username ?? env.PI_WEB_AGENT_PROXY_USERNAME;
+    const password = proxy.password ?? env.PI_WEB_AGENT_PROXY_PASSWORD;
+    return {
+        username: username?.trim() ? username : undefined,
+        password: password ? password : undefined
+    };
+}
+/**
+ * Build a fetch implementation that routes all traffic through the configured
+ * HTTP/HTTPS proxy. Uses undici (the engine behind Node's global fetch) with a
+ * ProxyAgent dispatcher while keeping the standard fetch API surface.
+ */
+export function createProxyFetch(proxy, options = {}) {
+    const credentials = resolveProxyCredentials(proxy);
+    const agent = new ProxyAgent({
+        // Never trust credentials embedded in the URL; they come from config fields
+        // or the PI_WEB_AGENT_PROXY_* env vars via resolveProxyCredentials.
+        uri: stripProxyCredentials(proxy.url),
+        // undici's `token` option is used verbatim as the Proxy-Authorization header
+        // value for both CONNECT tunnels and forwarded HTTP requests.
+        ...(credentials.username !== undefined
+            ? {
+                token: `Basic ${Buffer.from(credentials.password !== undefined
+                    ? `${credentials.username}:${credentials.password}`
+                    : `${credentials.username}:`).toString('base64')}`
+            }
+            : {}),
+        ...(options.tls ? { requestTls: { rejectUnauthorized: options.tls.rejectUnauthorized } } : {})
+    });
+    // undici's Request/Response types are structurally near-identical to Node's
+    // global fetch types but not nominatively identical, so the wrapper is cast
+    // to the standard fetch signature (runtime behavior is identical: Node's
+    // global fetch is built on this same undici engine).
+    const proxyFetch = (input, init) => undiciFetch(input, {
+        ...init,
+        dispatcher: agent
+    });
+    return proxyFetch;
+}

package/dist/jiti-compat-run.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/jiti-compat-run.js

@@ -0,0 +1,9 @@
+import { ensureJitiCompat } from './jiti-compat.js';
+// Side-effect-only module. It exists so `extension.ts` can run the compat
+// patch as its *first* import: ESM evaluates a module's dependency subtree,
+// including that module's body, before moving on to the next import. A plain
+// `ensureJitiCompat()` call in the extension body would run too late, after
+// jsdom (and therefore tr46/cssstyle) had already been evaluated.
+//
+// Keep this import first in extension.ts.
+ensureJitiCompat();

package/dist/jiti-compat.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Filesystem/resolver seam so tests can point this at a throwaway directory
+ * instead of the real `node_modules/tr46` and `node_modules/cssstyle`. All
+ * production call sites use the defaults (real `fs` + real module
+ * resolution) and never pass this in.
+ */
+export type JitiCompatDeps = {
+    /**
+     * Resolve `specifier` as `fromFile` would. Omitting `fromFile` resolves from
+     * this module, which is only correct when nothing else claims the package.
+     */
+    resolve: (specifier: string, fromFile?: string) => string;
+    existsSync: (path: string) => boolean;
+    readFileSync: (path: string) => string;
+    writeFileSync: (path: string, contents: string) => void;
+};
+export type JitiCompatStatus = {
+    /** Files that still need patching. Empty means the tree is healthy. */
+    pending: string[];
+    /** Files patched during this call. */
+    patched: string[];
+};
+/**
+ * Apply both patches if they are missing. Safe to call repeatedly: an already
+ * patched tree is a few `readFileSync` calls and no writes. Never throws.
+ */
+export declare function ensureJitiCompat(deps?: JitiCompatDeps): JitiCompatStatus;
+/**
+ * Read-only view of the same checks, for `/web-agent doctor`. Never throws and
+ * never writes.
+ */
+export declare function checkJitiCompat(deps?: JitiCompatDeps): JitiCompatStatus;