@demigodmode/pi-web-agent 1.11.0 → 1.12.0

package/dist/backends/fallback-policy.js

@@ -0,0 +1,239 @@
+import { buildFetchPresentation } from '../presentation/fetch-presentation.js';
+import { buildSearchPresentation } from '../presentation/search-presentation.js';
+import { failureOf, shouldFallBack } from './failure.js';
+export const RETRY_BASE_MS = 500;
+export const RETRY_JITTER_MS = 250;
+const USER_FIXABLE_KINDS = new Set(['not_configured', 'auth_failed', 'quota_exhausted']);
+/** Only user-fixable failures keep the provider's message; everything else stays message-free. */
+function detailFor(failure, message) {
+    return message && USER_FIXABLE_KINDS.has(failure.kind) ? message : undefined;
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function retryDelay(deps) {
+    return RETRY_BASE_MS + Math.floor((deps.random ?? Math.random)() * RETRY_JITTER_MS);
+}
+function skipAttempt(backend, state) {
+    return {
+        backend,
+        outcome: 'skipped',
+        failure: state.failure,
+        skipReason: state.state,
+        ...(state.state === 'cooling_down' ? { cooldownUntil: state.until } : {}),
+        ...(state.detail ? { detail: state.detail } : {})
+    };
+}
+function skipMessage(backend, state) {
+    const base = state.state === 'cooling_down'
+        ? `${backend} is cooling down after ${state.failure.kind} until ${new Date(state.until).toISOString()}.`
+        : `${backend} is disabled for this session after ${state.failure.kind}.`;
+    return state.detail ? `${base} ${state.detail}` : base;
+}
+function failedAttempt(backend, failure, state, detail) {
+    return {
+        backend,
+        outcome: 'failed',
+        failure,
+        ...(state.state === 'cooling_down' ? { cooldownUntil: state.until } : {}),
+        ...(detail ? { detail } : {})
+    };
+}
+/**
+ * One provider under the #55 policy: skip when cooling down or disabled,
+ * retry exactly once on transient, record state. Never falls back itself.
+ */
+export function withSearchPolicy(name, search, deps, healthKey = name) {
+    return async (input) => {
+        const state = deps.health.get(healthKey);
+        if (state.state !== 'available') {
+            return {
+                status: 'error',
+                results: [],
+                metadata: { backend: name, cacheHit: false, attempts: [skipAttempt(name, state)] },
+                error: { code: 'BACKEND_UNAVAILABLE', message: skipMessage(name, state), failure: state.failure }
+            };
+        }
+        const attempts = [];
+        let result = await search(input);
+        let failure = failureOf(result);
+        if (failure?.kind === 'transient') {
+            attempts.push({ backend: name, outcome: 'retried', failure });
+            await (deps.sleep ?? defaultSleep)(retryDelay(deps));
+            result = await search(input);
+            failure = failureOf(result);
+        }
+        if (failure) {
+            const detail = detailFor(failure, result.error?.message);
+            attempts.push(failedAttempt(name, failure, deps.health.record(healthKey, failure, detail), detail));
+        }
+        else {
+            attempts.push({ backend: name, outcome: result.results.length > 0 ? 'results' : 'empty' });
+        }
+        return { ...result, metadata: { ...result.metadata, attempts: [...(result.metadata.attempts ?? []), ...attempts] } };
+    };
+}
+function unavailableMessage(attempts, messages = new Map()) {
+    const byProvider = new Map();
+    for (const attempt of attempts) {
+        if (attempt.outcome === 'failed' || attempt.outcome === 'skipped')
+            byProvider.set(attempt.backend, attempt);
+    }
+    const entries = [...byProvider.values()].sort((a, b) => {
+        const aUntil = a.cooldownUntil ?? Number.POSITIVE_INFINITY;
+        const bUntil = b.cooldownUntil ?? Number.POSITIVE_INFINITY;
+        return aUntil - bUntil;
+    });
+    const parts = entries.map((attempt) => {
+        const kind = attempt.failure?.kind ?? 'bad_response';
+        if (attempt.cooldownUntil !== undefined) {
+            return `${attempt.backend} ${kind} (available again at ${new Date(attempt.cooldownUntil).toISOString()})`;
+        }
+        // Keep the provider's own hint for problems the user has to fix, e.g. a missing key or base URL.
+        const hint = USER_FIXABLE_KINDS.has(kind)
+            ? attempt.detail ?? (attempt.outcome === 'failed' ? messages.get(attempt.backend) : undefined)
+            : undefined;
+        return hint ? `${attempt.backend} ${kind} (${hint})` : `${attempt.backend} ${kind}`;
+    });
+    return `No search backend is available: ${parts.join(', ')}.`;
+}
+/**
+ * A failed link's unavailable providers, from its own attempts: the last failed or skipped
+ * attempt per backend with that attempt's kind. A fanout link reports each provider, not the
+ * aggregate. Falls back to the aggregate only when the link carries no failed or skipped attempts.
+ */
+function unavailableFor(result, failure) {
+    const message = result.error?.message ?? failure.kind;
+    const byProvider = new Map();
+    for (const entry of result.metadata.coverage?.unavailable ?? []) {
+        byProvider.set(entry.provider, { ...entry, message });
+    }
+    const attempts = result.metadata.attempts ?? [];
+    const relevant = attempts.filter((a) => a.outcome === 'failed' || a.outcome === 'skipped');
+    if (relevant.length === 0) {
+        byProvider.set(result.metadata.backend, { provider: result.metadata.backend, kind: failure.kind, message });
+    }
+    for (const attempt of relevant) {
+        byProvider.delete(attempt.backend); // keep insertion order at the latest attempt
+        byProvider.set(attempt.backend, {
+            provider: attempt.backend,
+            kind: attempt.failure?.kind ?? failure.kind,
+            message: attempt.detail ?? message
+        });
+    }
+    return [...byProvider.values()];
+}
+/**
+ * Tries providers in order under the precedence in the #55 spec: terminal and
+ * bad_request failures stop the chain; a result or a valid empty response is
+ * returned; everything else falls back.
+ */
+export function chainSearch(providers, deps) {
+    return async (input) => {
+        const attempts = [];
+        const unavailable = [];
+        let lastFailure;
+        let firstBackend;
+        // Keep an earlier fanout's provenance (which providers were tried) when a later link answers.
+        let fanout;
+        for (const provider of providers) {
+            const result = await provider(input);
+            firstBackend ??= result.metadata.backend;
+            attempts.push(...(result.metadata.attempts ?? []));
+            fanout ??= result.metadata.fanout;
+            const failure = failureOf(result);
+            if (!failure) {
+                const first = unavailable[0];
+                const merged = {
+                    ...result,
+                    metadata: {
+                        ...result.metadata,
+                        ...(fanout && !result.metadata.fanout ? { fanout } : {}),
+                        attempts,
+                        ...(first
+                            ? {
+                                fallbackFrom: first.provider,
+                                fallbackReason: first.message,
+                                coverage: { partial: true, unavailable: unavailable.map(({ provider, kind }) => ({ provider, kind })) }
+                            }
+                            : {})
+                    }
+                };
+                return { ...merged, presentation: buildSearchPresentation(merged) };
+            }
+            if (!shouldFallBack(failure.kind)) {
+                const stopped = { ...result, metadata: { ...result.metadata, attempts } };
+                return { ...stopped, presentation: buildSearchPresentation(stopped) };
+            }
+            for (const entry of unavailableFor(result, failure)) {
+                const existing = unavailable.findIndex((u) => u.provider === entry.provider);
+                if (existing >= 0)
+                    unavailable.splice(existing, 1);
+                unavailable.push(entry);
+            }
+            lastFailure = failure;
+        }
+        const exhausted = {
+            status: 'error',
+            results: [],
+            metadata: { backend: firstBackend ?? 'duckduckgo', cacheHit: false, attempts },
+            error: {
+                code: 'SEARCH_BACKENDS_UNAVAILABLE',
+                message: unavailableMessage(attempts, new Map(unavailable.map((entry) => [entry.provider, entry.message]))),
+                failure: lastFailure ?? { kind: 'bad_response' }
+            }
+        };
+        return { ...exhausted, presentation: buildSearchPresentation(exhausted) };
+    };
+}
+/**
+ * Firecrawl under the policy, with the optional HTTP fallback. The HTTP fetcher
+ * talks to the model-chosen site, not a service, so it has no provider health.
+ */
+export function withFetchPolicy(primary, fallback, deps, healthKey = 'firecrawl') {
+    const finish = (result) => ({ ...result, presentation: buildFetchPresentation(result) });
+    return async (input) => {
+        const attempts = [];
+        const state = deps.health.get(healthKey);
+        let first;
+        if (state.state !== 'available') {
+            attempts.push(skipAttempt('firecrawl', state));
+            first = {
+                status: 'error',
+                url: input.url,
+                metadata: { method: 'firecrawl', cacheHit: false },
+                error: { code: 'BACKEND_UNAVAILABLE', message: skipMessage('firecrawl', state), failure: state.failure }
+            };
+        }
+        else {
+            first = await primary(input);
+            let failure = failureOf(first);
+            if (failure?.kind === 'transient') {
+                attempts.push({ backend: 'firecrawl', outcome: 'retried', failure });
+                await (deps.sleep ?? defaultSleep)(retryDelay(deps));
+                first = await primary(input);
+                failure = failureOf(first);
+            }
+            if (failure) {
+                const detail = detailFor(failure, first.error?.message);
+                attempts.push(failedAttempt('firecrawl', failure, deps.health.record(healthKey, failure, detail), detail));
+            }
+            else
+                attempts.push({ backend: 'firecrawl', outcome: first.status === 'ok' ? 'results' : 'empty' });
+        }
+        const failure = failureOf(first);
+        const fallBack = first.status === 'needs_headless' || (failure !== undefined && shouldFallBack(failure.kind));
+        if (!fallback || !fallBack) {
+            return finish({ ...first, metadata: { ...first.metadata, attempts } });
+        }
+        const second = await fallback(input);
+        attempts.push({ backend: 'http', outcome: second.status === 'ok' ? 'results' : 'failed', ...(second.error?.failure ? { failure: second.error.failure } : {}) });
+        return finish({
+            ...second,
+            metadata: {
+                ...second.metadata,
+                attempts,
+                fallbackFrom: 'firecrawl',
+                fallbackReason: first.error?.message ?? 'Firecrawl fetch failed.'
+            }
+        });
+    };
+}

package/dist/backends/provider-failure.d.ts

@@ -0,0 +1,21 @@
+import type { FailureInfo, SearchProviderName } from '../types.js';
+export type ClassifiedProvider = SearchProviderName | 'firecrawl';
+export type ResponseParts = {
+    status: number;
+    headers: Headers;
+    /** Parsed JSON body, or undefined when the body was empty or not JSON. */
+    json?: unknown;
+};
+export declare class BodyReadError extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+/**
+ * Reads a response body once, keeping status and headers alongside the parsed JSON.
+ * A body that can't be read (connection dropped mid-stream) throws BodyReadError: that's
+ * a transport failure, not a malformed response.
+ */
+export declare function readResponseParts(response: Response): Promise<ResponseParts & {
+    text: string;
+}>;
+export declare function classifyHttpFailure(provider: ClassifiedProvider, parts: ResponseParts, now?: number): FailureInfo;

package/dist/backends/provider-failure.js

@@ -0,0 +1,111 @@
+import { parseRetryAfter } from './failure.js';
+export class BodyReadError extends Error {
+    cause;
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause));
+        this.cause = cause;
+        this.name = 'BodyReadError';
+    }
+}
+/**
+ * Reads a response body once, keeping status and headers alongside the parsed JSON.
+ * A body that can't be read (connection dropped mid-stream) throws BodyReadError: that's
+ * a transport failure, not a malformed response.
+ */
+export async function readResponseParts(response) {
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch (error) {
+        throw new BodyReadError(error);
+    }
+    let json;
+    try {
+        json = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        json = undefined;
+    }
+    return { status: response.status, headers: response.headers, json, text };
+}
+// Source: https://exa.ai/docs/reference/error-codes
+const EXA_TAGS = {
+    RATE_LIMIT_EXCEEDED: 'rate_limited',
+    NO_MORE_CREDITS: 'quota_exhausted',
+    API_KEY_BUDGET_EXCEEDED: 'quota_exhausted',
+    TEAM_BUDGET_EXCEEDED: 'quota_exhausted',
+    INVALID_API_KEY: 'auth_failed',
+    FEATURE_DISABLED: 'auth_failed',
+    PROHIBITED_CONTENT: 'bad_request',
+    CONTENT_FILTER_ERROR: 'bad_request',
+    INVALID_REQUEST_BODY: 'bad_request',
+    INVALID_REQUEST: 'bad_request',
+    INVALID_NUM_RESULTS: 'bad_request'
+};
+/**
+ * Conservative defaults for undocumented responses. A 401 disables the provider
+ * (low risk: resets on config change); an undocumented 403 is treated as a bot
+ * wall; an undocumented 402 is not assumed to mean quota.
+ */
+function defaultKind(status) {
+    if (status === 429)
+        return 'rate_limited';
+    if (status === 401)
+        return 'auth_failed';
+    if (status === 403)
+        return 'blocked';
+    if (status === 400 || status === 422)
+        return 'bad_request';
+    if (status === 408 || status >= 500)
+        return 'transient';
+    return 'bad_response';
+}
+function stringField(json, field) {
+    if (!json || typeof json !== 'object')
+        return undefined;
+    const value = json[field];
+    return typeof value === 'string' ? value : undefined;
+}
+export function classifyHttpFailure(provider, parts, now = Date.now()) {
+    const { status } = parts;
+    let kind;
+    let providerCode;
+    if (provider === 'exa') {
+        const tag = stringField(parts.json, 'tag');
+        if (tag && EXA_TAGS[tag]) {
+            kind = EXA_TAGS[tag];
+            providerCode = tag;
+        }
+        else if (status === 402) {
+            kind = 'quota_exhausted'; // documented 402 meaning for Exa
+        }
+    }
+    else if (provider === 'firecrawl') {
+        // Source: https://docs.firecrawl.dev/api-reference/errors
+        if (status === 402)
+            kind = 'quota_exhausted';
+    }
+    else if (provider === 'youcom') {
+        // Source: https://you.com/docs/api-reference/search/v1-search (429 UNVERIFIED -> default)
+        // Documented for /v1/search; the client currently calls /v1/agents/search (#60).
+        if (status === 402)
+            kind = 'quota_exhausted';
+        else if (status === 403)
+            kind = 'auth_failed';
+    }
+    else if (provider === 'searxng') {
+        // Source: https://docs.searxng.org/dev/search_api.html (403 = format=json disabled in settings)
+        if (status === 403)
+            kind = 'auth_failed';
+    }
+    // brave, tavily, duckduckgo: defaults only (UNVERIFIED beyond 429; see research gate).
+    const resolved = kind ?? defaultKind(status);
+    const info = { kind: resolved, httpStatus: status, ...(providerCode ? { providerCode } : {}) };
+    if (resolved === 'rate_limited') {
+        const retryAfter = parseRetryAfter(parts.headers.get('retry-after'), now);
+        if (retryAfter !== undefined)
+            info.providerRetryAfterMs = retryAfter;
+    }
+    return info;
+}

package/dist/backends/provider-health.d.ts

@@ -0,0 +1,29 @@
+import type { FailureInfo } from '../types.js';
+export declare const DEFAULT_COOLDOWN_MS = 60000;
+export declare const MIN_COOLDOWN_MS = 1000;
+export declare const MAX_COOLDOWN_MS: number;
+export type ProviderHealthState = {
+    state: 'available';
+} | {
+    state: 'cooling_down';
+    until: number;
+    failure: FailureInfo;
+    detail?: string;
+} | {
+    state: 'disabled';
+    failure: FailureInfo;
+    detail?: string;
+};
+export type ProviderHealth = {
+    get(key: string): ProviderHealthState;
+    record(key: string, failure: FailureInfo, detail?: string): ProviderHealthState;
+};
+/** The applied cooldown. The provider's own value stays in failure.providerRetryAfterMs. */
+export declare function cooldownFor(failure: FailureInfo): number;
+/**
+ * Per backend set. The set is rebuilt on any effective config change, so fixed
+ * credentials or new endpoints take effect without restarting Pi.
+ */
+export declare function createProviderHealth({ now }?: {
+    now?: () => number;
+}): ProviderHealth;

package/dist/backends/provider-health.js

@@ -0,0 +1,49 @@
+export const DEFAULT_COOLDOWN_MS = 60_000;
+export const MIN_COOLDOWN_MS = 1000;
+export const MAX_COOLDOWN_MS = 15 * 60_000;
+/** The applied cooldown. The provider's own value stays in failure.providerRetryAfterMs. */
+export function cooldownFor(failure) {
+    const raw = failure.providerRetryAfterMs;
+    if (raw === undefined || Number.isNaN(raw))
+        return DEFAULT_COOLDOWN_MS;
+    return Math.min(MAX_COOLDOWN_MS, Math.max(MIN_COOLDOWN_MS, raw));
+}
+/**
+ * Per backend set. The set is rebuilt on any effective config change, so fixed
+ * credentials or new endpoints take effect without restarting Pi.
+ */
+export function createProviderHealth({ now = Date.now } = {}) {
+    const states = new Map();
+    function get(key) {
+        const current = states.get(key);
+        if (!current)
+            return { state: 'available' };
+        if (current.state === 'cooling_down' && current.until <= now()) {
+            states.delete(key);
+            return { state: 'available' };
+        }
+        return current;
+    }
+    function record(key, failure, detail) {
+        const current = get(key);
+        if (current.state === 'disabled')
+            return current;
+        switch (failure.kind) {
+            case 'rate_limited': {
+                const next = { state: 'cooling_down', until: now() + cooldownFor(failure), failure };
+                states.set(key, next);
+                return next;
+            }
+            case 'quota_exhausted':
+            case 'auth_failed':
+            case 'not_configured': {
+                const next = { state: 'disabled', failure, ...(detail ? { detail } : {}) };
+                states.set(key, next);
+                return next;
+            }
+            default:
+                return current;
+        }
+    }
+    return { get, record };
+}

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

@@ -36,7 +36,20 @@ export declare function validateBackendUrl(value: string): {
     ok: false;
     message: string;
 };
-export declare function createBackendUrlEditor(theme: any, label: string, placeholderUrl: string, onOpenChange?: (open: boolean) => void): (currentValue: string, done: (selectedValue?: string) => void) => Component;
+export declare function validateAllowRanges(value: string): {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function createBackendUrlEditor(theme: any, label: string, placeholderUrl: string, onOpenChange?: (open: boolean) => void, validate?: (value: string) => {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    message: string;
+}): (currentValue: string, done: (selectedValue?: string) => void) => Component;
 export declare function getInheritedConfigForScope(loaded: Awaited<LoadedPresentationConfig>, scope: PresentationScope): PresentationConfig;
 export declare function getScopeDisplayConfig(loaded: Awaited<LoadedPresentationConfig>, scope: PresentationScope): PresentationConfig;
 export declare function getInheritedBackendsForScope(loaded: Awaited<LoadedPresentationConfig>, scope: PresentationScope): BackendConfig;

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

@@ -1,5 +1,6 @@
 import { DEFAULT_BACKEND_CONFIG, isValidProxyUrl, mergeBackendConfigLayers, stripProxyCredentials, validateBackendConfig, usableSearchProviders } from '../backends/config.js';
 import { checkBackendHealth } from '../backends/doctor.js';
+import { parseCidr } from '../fetch/network-guard.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';
@@ -32,7 +33,10 @@ function cloneBackendConfig(config) {
             options: config.fetch.options ? { ...config.fetch.options } : undefined
         },
         headless: { ...config.headless },
-        proxy: config.proxy ? { ...config.proxy } : undefined
+        proxy: config.proxy ? { ...config.proxy } : undefined,
+        network: config.network
+            ? { ...config.network, ...(config.network.allowRanges ? { allowRanges: [...config.network.allowRanges] } : {}) }
+            : undefined
     };
 }
 function sameJson(left, right) {
@@ -50,6 +54,22 @@ export function validateBackendUrl(value) {
         return { ok: false, message: 'Invalid URL. Include http:// or https://.' };
     }
 }
+function splitRanges(value) {
+    return value
+        .split(',')
+        .map((range) => range.trim())
+        .filter(Boolean);
+}
+export function validateAllowRanges(value) {
+    for (const range of splitRanges(value)) {
+        const cidr = parseCidr(range);
+        if (!cidr)
+            return { ok: false, message: `Not a valid CIDR range: ${range}` };
+        if (cidr.prefix === 0)
+            return { ok: false, message: `${range} allows every address. List specific ranges instead.` };
+    }
+    return { ok: true, value: splitRanges(value).join(', ') };
+}
 /**
  * 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
@@ -140,7 +160,7 @@ function buildPresentationSettingsItems(scope, config) {
         }))
     ];
 }
-export function createBackendUrlEditor(theme, label, placeholderUrl, onOpenChange) {
+export function createBackendUrlEditor(theme, label, placeholderUrl, onOpenChange, validate = validateBackendUrl) {
     return (currentValue, done) => {
         onOpenChange?.(true);
         const initialValue = currentValue && currentValue !== 'not set' ? currentValue : placeholderUrl;
@@ -164,7 +184,7 @@ export function createBackendUrlEditor(theme, label, placeholderUrl, onOpenChang
                 finish('');
                 return;
             }
-            const validated = validateBackendUrl(value);
+            const validated = validate(value);
             if (!validated.ok) {
                 showError(validated.message);
                 return;
@@ -276,6 +296,20 @@ function buildBackendSettingsItems(scope, backends, theme, onUrlEditorOpenChange
             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)
+        },
+        {
+            id: 'backend:network:allowRanges',
+            label: 'Network allow list',
+            currentValue: backends.network?.allowRanges?.length ? backends.network.allowRanges.join(', ') : 'not set',
+            submenu: createBackendUrlEditor(theme, 'Private ranges to allow, comma separated CIDRs, e.g. 198.18.0.0/15', 
+            // No prefilled example: pressing enter on an empty list must not quietly add an exception.
+            '', onUrlEditorOpenChange, validateAllowRanges)
+        },
+        {
+            id: 'backend:network:trustProxyDns',
+            label: 'Trust the upstream proxy to enforce private-address restrictions',
+            currentValue: backends.network?.trustProxyDns ? 'on' : 'off',
+            values: ['off', 'on']
         }
     ];
 }
@@ -456,6 +490,25 @@ export function applySettingsValue(state, id, newValue) {
             delete currentBackends.proxy;
         }
     }
+    if (id === 'backend:network:allowRanges') {
+        const ranges = splitRanges(newValue);
+        const next = { ...currentBackends.network };
+        if (ranges.length > 0) {
+            next.allowRanges = ranges;
+        }
+        else {
+            delete next.allowRanges;
+        }
+        if (Object.keys(next).length > 0) {
+            currentBackends.network = next;
+        }
+        else {
+            delete currentBackends.network;
+        }
+    }
+    if (id === 'backend:network:trustProxyDns') {
+        currentBackends.network = { ...currentBackends.network, trustProxyDns: newValue === 'on' };
+    }
     nextDrafts[nextScope] = currentDraft;
     nextBackendDrafts[nextScope] = currentBackends;
     return {
@@ -531,6 +584,23 @@ export function collapseBackendConfigToOverride(config, inheritedConfig) {
             override.proxy = { url: '' };
         }
     }
+    if (!sameJson(config.network, inheritedConfig.network)) {
+        if (config.network) {
+            override.network = {
+                ...config.network,
+                ...(config.network.allowRanges ? { allowRanges: [...config.network.allowRanges] } : {})
+            };
+            // Cleared at this scope: an explicit empty list overrides the parent's.
+            if (!config.network.allowRanges && inheritedConfig.network?.allowRanges)
+                override.network.allowRanges = [];
+        }
+        else if (inheritedConfig.network) {
+            override.network = {
+                ...(inheritedConfig.network.allowRanges ? { allowRanges: [] } : {}),
+                ...(inheritedConfig.network.trustProxyDns ? { trustProxyDns: false } : {})
+            };
+        }
+    }
     return override;
 }
 export function handleSettingsShortcut(data) {
@@ -753,6 +823,8 @@ export function registerWebAgentConfigCommands(pi, deps = {}) {
                     `typebox: ${typeboxOk ? 'ok' : 'missing'}`,
                     formatJitiCompatLine(checkCompat()),
                     formatBackendSummary(backendConfig),
+                    `network allow list: ${backendConfig.network?.allowRanges?.length ? backendConfig.network.allowRanges.join(', ') : 'none'}`,
+                    `trust upstream proxy for private addresses: ${backendConfig.network?.trustProxyDns ? 'on' : 'off'}`,
                     backendIssues.length > 0 ? `backend config: warning\n${backendIssues.join('\n')}` : 'backend config: ok',
                     ...backendHealth
                 ];

package/dist/extension.js

@@ -59,20 +59,64 @@ export default function extension(pi) {
     registerWebAgentConfigCommands(pi);
     const injectedWebExplore = pi.__webExploreTool;
     let cachedBackendKey;
+    let cachedWorkflow;
     let cachedWebExplore;
+    // Runs in flight per workflow, so a replaced workflow is never closed mid-run.
+    const activeRuns = new Map();
+    const retiring = new Set();
+    const closeWorkflow = (workflow) => {
+        retiring.delete(workflow);
+        void Promise.resolve(workflow.close?.()).catch(() => undefined);
+    };
+    const retire = (workflow) => {
+        if ((activeRuns.get(workflow) ?? 0) === 0) {
+            closeWorkflow(workflow);
+        }
+        else {
+            retiring.add(workflow);
+        }
+    };
+    const leased = (workflow) => ({
+        run: async (input) => {
+            activeRuns.set(workflow, (activeRuns.get(workflow) ?? 0) + 1);
+            try {
+                return await workflow.run(input);
+            }
+            finally {
+                const remaining = (activeRuns.get(workflow) ?? 1) - 1;
+                if (remaining > 0) {
+                    activeRuns.set(workflow, remaining);
+                }
+                else {
+                    activeRuns.delete(workflow);
+                    if (retiring.has(workflow))
+                        closeWorkflow(workflow);
+                }
+            }
+        }
+    });
     async function getConfiguredWebExplore() {
         if (injectedWebExplore)
             return injectedWebExplore;
         const backendConfig = await getEffectiveBackendConfig(pi);
         const backendKey = JSON.stringify(backendConfig);
         if (!cachedWebExplore || cachedBackendKey !== backendKey) {
+            if (cachedWorkflow)
+                retire(cachedWorkflow);
             cachedBackendKey = backendKey;
-            cachedWebExplore = createWebExploreTool({
-                explore: createResearchWorkflow({ backendConfig })
-            });
+            cachedWorkflow = createResearchWorkflow({ backendConfig });
+            cachedWebExplore = createWebExploreTool({ explore: leased(cachedWorkflow) });
         }
         return cachedWebExplore;
     }
+    pi.on('session_shutdown', async () => {
+        const workflow = cachedWorkflow;
+        cachedWorkflow = undefined;
+        cachedWebExplore = undefined;
+        cachedBackendKey = undefined;
+        if (workflow)
+            retire(workflow);
+    });
     pi.on('session_start', async (_event, ctx) => {
         try {
             const notice = await getUpdateChangelogNotice();