@demigodmode/pi-web-agent 1.11.0 → 1.13.0

package/dist/backends/failure.d.ts

@@ -0,0 +1,11 @@
+import type { FailureInfo, FailureKind, ToolError } from '../types.js';
+/** Terminal failures never retry, never fall back, never escalate to headless (#55). */
+export declare function isTerminalFailure(failure: FailureInfo | undefined): boolean;
+export declare function shouldFallBack(kind: FailureKind): boolean;
+/** An error result's failure. Unclassified errors are treated as bad_response: fall back, no retry, no state. */
+export declare function failureOf(result: {
+    status: string;
+    error?: ToolError;
+}): FailureInfo | undefined;
+/** RFC 9110 Retry-After: delay-seconds (non-negative integer) or an HTTP-date. */
+export declare function parseRetryAfter(value: string | null | undefined, now: number): number | undefined;

package/dist/backends/failure.js

@@ -0,0 +1,34 @@
+const TERMINAL_KINDS = new Set(['config_global', 'guard_refused']);
+const NO_FALLBACK_KINDS = new Set(['bad_request', 'config_global', 'guard_refused']);
+/** Terminal failures never retry, never fall back, never escalate to headless (#55). */
+export function isTerminalFailure(failure) {
+    return failure !== undefined && TERMINAL_KINDS.has(failure.kind);
+}
+export function shouldFallBack(kind) {
+    return !NO_FALLBACK_KINDS.has(kind);
+}
+/** An error result's failure. Unclassified errors are treated as bad_response: fall back, no retry, no state. */
+export function failureOf(result) {
+    if (result.status !== 'error')
+        return undefined;
+    return result.error?.failure ?? { kind: 'bad_response' };
+}
+/** RFC 9110 Retry-After: delay-seconds (non-negative integer) or an HTTP-date. */
+export function parseRetryAfter(value, now) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed)) {
+        const ms = Number(trimmed) * 1000;
+        // A huge digit string overflows to Infinity; keep it finite (and JSON-safe) so the
+        // cooldown clamps to the maximum instead of falling back to the default.
+        return Number.isFinite(ms) ? Math.min(ms, Number.MAX_SAFE_INTEGER) : Number.MAX_SAFE_INTEGER;
+    }
+    // IMF-fixdate only (RFC 9110 preferred form). V8's Date.parse accepts things like "-5" or "abc 2099".
+    if (!/^[A-Za-z]{3}, \d{2} [A-Za-z]{3} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(trimmed))
+        return undefined;
+    const at = Date.parse(trimmed);
+    if (Number.isNaN(at) || at <= now)
+        return undefined;
+    return at - now;
+}

package/dist/backends/fallback-policy.d.ts

@@ -0,0 +1,31 @@
+import type { ResearchFetchInput, SearchProviderName, WebFetchResponse, WebSearchResponse } from '../types.js';
+import type { ProviderHealth } from './provider-health.js';
+export declare const RETRY_BASE_MS = 500;
+export declare const RETRY_JITTER_MS = 250;
+export type PolicyDeps = {
+    health: ProviderHealth;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+};
+type Search = (input: {
+    query: string;
+}) => Promise<WebSearchResponse>;
+type FetchPage = (input: ResearchFetchInput) => Promise<WebFetchResponse>;
+/**
+ * One provider under the #55 policy: skip when cooling down or disabled,
+ * retry exactly once on transient, record state. Never falls back itself.
+ */
+export declare function withSearchPolicy(name: SearchProviderName, search: Search, deps: PolicyDeps, healthKey?: string): Search;
+/**
+ * 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 declare function chainSearch(providers: Search[], deps: PolicyDeps): Search;
+/**
+ * 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 declare function withFetchPolicy(primary: FetchPage, fallback: FetchPage | undefined, deps: PolicyDeps, healthKey?: string): FetchPage;
+export {};

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,110 @@
+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)
+        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;