@demigodmode/pi-web-agent 1.10.0 → 1.12.0

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

@@ -16,6 +16,9 @@ type CommandDeps = {
         arch: string;
     };
     checkTypebox?: () => Promise<boolean>;
+    checkJitiCompat?: () => {
+        pending: string[];
+    };
     checkBackends?: (config: BackendConfig) => Promise<string[]>;
     getChangelog?: () => Promise<string | undefined>;
 };
@@ -33,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,10 +1,13 @@
-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 { 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';
 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 +32,11 @@ 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,
+        network: config.network
+            ? { ...config.network, ...(config.network.allowRanges ? { allowRanges: [...config.network.allowRanges] } : {}) }
+            : undefined
     };
 }
 function sameJson(left, right) {
@@ -47,6 +54,37 @@ 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
+ * 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 +125,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}`];
@@ -119,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;
@@ -143,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;
@@ -249,6 +290,26 @@ 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)
+        },
+        {
+            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']
         }
     ];
 }
@@ -421,6 +482,33 @@ 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;
+        }
+    }
+    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 {
@@ -485,6 +573,34 @@ 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: '' };
+        }
+    }
+    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) {
@@ -669,7 +785,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,7 +821,10 @@ 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),
+                    `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.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';
@@ -57,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();

package/dist/fetch/destination-policy.d.ts

@@ -0,0 +1,32 @@
+import { BlockedAddressError, UnverifiedDestinationError, type NetworkGuard } from './network-guard.js';
+export type Destination = {
+    action: 'connect';
+    host: string;
+    address: string;
+} | {
+    action: 'delegate';
+    host: string;
+} | {
+    action: 'refuse';
+    error: BlockedAddressError | UnverifiedDestinationError;
+};
+export type DestinationMode = {
+    /** An upstream proxy is configured. */
+    upstream: boolean;
+    /**
+     * The user explicitly trusts the upstream proxy to enforce private-address
+     * restrictions. Only meaningful with an upstream.
+     */
+    trustProxyDns?: boolean;
+};
+/**
+ * Turns one resolution into where a connection may go (spec revision 2).
+ *
+ * - blocked answers are refused in every mode
+ * - by default the connection goes to an address we checked, never a hostname
+ *   something else will resolve
+ * - with a trusted upstream the hostname is delegated, which also covers names
+ *   only that proxy can resolve
+ * - anything else unresolvable is refused
+ */
+export declare function decideDestination(host: string, guard: NetworkGuard, mode: DestinationMode): Promise<Destination>;

package/dist/fetch/destination-policy.js

@@ -0,0 +1,24 @@
+import { BlockedAddressError, UnverifiedDestinationError } from './network-guard.js';
+/**
+ * Turns one resolution into where a connection may go (spec revision 2).
+ *
+ * - blocked answers are refused in every mode
+ * - by default the connection goes to an address we checked, never a hostname
+ *   something else will resolve
+ * - with a trusted upstream the hostname is delegated, which also covers names
+ *   only that proxy can resolve
+ * - anything else unresolvable is refused
+ */
+export async function decideDestination(host, guard, mode) {
+    const resolution = await guard.resolveHost(host);
+    if (resolution.status === 'blocked') {
+        return { action: 'refuse', error: new BlockedAddressError(resolution.host, resolution.address) };
+    }
+    if (mode.upstream && mode.trustProxyDns) {
+        return { action: 'delegate', host: resolution.host };
+    }
+    if (resolution.status === 'unresolved') {
+        return { action: 'refuse', error: new UnverifiedDestinationError(resolution.host) };
+    }
+    return { action: 'connect', host: resolution.host, address: resolution.addresses[0] };
+}