@demigodmode/pi-web-agent 1.10.0 → 1.12.0

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;

package/dist/jiti-compat.js

@@ -0,0 +1,215 @@
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, relative, sep } from 'node:path';
+/**
+ * Works around two incompatibilities between pi's extension loader (a patched
+ * jiti) and jsdom's dependency tree:
+ *
+ *   1. jiti can't resolve the trailing-slash bare specifier require("punycode/")
+ *      used by tr46.
+ *   2. jiti wraps `module.exports = new Set(...)` (cssstyle) in a Proxy, which
+ *      breaks native Set methods on the exported value.
+ *
+ * Both files live in the shared `~/.pi/agent/npm/node_modules` tree, so
+ * installing or updating any *other* pi extension re-extracts them and reverts
+ * the patch. A postinstall hook alone therefore can't keep this healthy, which
+ * is why `ensureJitiCompat()` also runs on extension load, before jsdom is
+ * evaluated. See https://github.com/demigodmode/pi-web-agent/issues/34.
+ *
+ * scripts/patch-jiti-compat.mjs duplicates this logic for the postinstall
+ * hook. That hook runs before `npm run build`, so it cannot import dist/.
+ * Keep the two in sync.
+ */
+const requireFromHere = createRequire(import.meta.url);
+/**
+ * Write via a temp file + rename rather than in place. Two reasons, both of
+ * which bite harder now that this runs on every extension load instead of once
+ * per install:
+ *
+ *   - `writeFileSync` truncates first. A crash, a full disk, or an OOM kill
+ *     mid-write leaves a half-written file that still contains the marker
+ *     comment, so every later run would skip it as "already patched" and the
+ *     doctor would report a broken tree as healthy.
+ *   - Another Pi session can be `require`-ing the same file while we write it.
+ *     `rename` is atomic within a filesystem, so readers see the old file or
+ *     the new one, never a partial one.
+ *
+ * The rename also breaks a pnpm-style hardlink instead of writing through it
+ * into the shared content-addressable store.
+ */
+function writeFileAtomic(path, contents) {
+    const temp = `${path}.pi-web-agent-${process.pid}.tmp`;
+    try {
+        writeFileSync(temp, contents);
+        renameSync(temp, path);
+    }
+    catch (err) {
+        try {
+            if (existsSync(temp))
+                unlinkSync(temp);
+        }
+        catch {
+            // Best effort. Leaving a stray temp file is better than masking the
+            // original write failure.
+        }
+        throw err;
+    }
+}
+const defaultDeps = {
+    resolve: (specifier, fromFile) => (fromFile ? createRequire(fromFile) : requireFromHere).resolve(specifier),
+    existsSync,
+    readFileSync: (path) => readFileSync(path, 'utf8'),
+    writeFileSync: writeFileAtomic
+};
+const SET_SHIM_MARKER = 'pi/jiti workaround';
+const SET_SHIM = `
+// ${SET_SHIM_MARKER}: expose bound native Set methods as own properties so a
+// Proxy wrapper around this export does not break Set brand checks.
+for (const k of ["has", "add", "delete", "forEach", "keys", "values", "entries"]) {
+  module.exports[k] = Set.prototype[k].bind(module.exports);
+}
+module.exports[Symbol.iterator] = Set.prototype[Symbol.iterator].bind(module.exports);
+`;
+const PUNYCODE_SPECIFIER = 'require("punycode/")';
+const PUNYCODE_REPLACEMENT = 'require("punycode/punycode.js")';
+function findPackageRoot(deps, entryFile, packageName) {
+    let directory = dirname(entryFile);
+    for (;;) {
+        const manifestFile = join(directory, 'package.json');
+        if (deps.existsSync(manifestFile)) {
+            try {
+                const manifest = JSON.parse(deps.readFileSync(manifestFile));
+                if (manifest.name === packageName)
+                    return directory;
+            }
+            catch {
+                // An unreadable or malformed package.json on the way up is not our
+                // problem to report. Keep walking.
+            }
+        }
+        const parent = dirname(directory);
+        if (parent === directory) {
+            throw new Error(`could not find the ${packageName} package root from ${entryFile}`);
+        }
+        directory = parent;
+    }
+}
+/**
+ * Resolve the copies jsdom actually loads, not whichever copy happens to sit
+ * highest in the tree.
+ *
+ * `~/.pi/agent/npm/node_modules` is shared by every pi extension, so version
+ * conflicts routinely push a second copy of a package into a nested
+ * `node_modules`. Resolving `cssstyle` or `tr46` from *this* module can then
+ * find a hoisted copy that jsdom never requires: the patch lands on the wrong
+ * file, the load still fails, and the doctor reports a healthy tree because it
+ * checked the same wrong file. Walk the real import chain instead
+ * (jsdom -> cssstyle, jsdom -> whatwg-url -> tr46) and only fall back to a
+ * direct resolve when jsdom is not resolvable at all.
+ */
+function resolveFromJsdom(deps, specifier, via) {
+    try {
+        const jsdomEntry = deps.resolve('jsdom');
+        const importer = via ? deps.resolve(via, jsdomEntry) : jsdomEntry;
+        return deps.resolve(specifier, importer);
+    }
+    catch {
+        // jsdom (or the intermediate package) is not resolvable from here, e.g. a
+        // layout we do not recognize. Fall back to a plain resolve rather than
+        // giving up on the patch entirely.
+        return deps.resolve(specifier);
+    }
+}
+function tr46Entry(deps) {
+    return resolveFromJsdom(deps, 'tr46', 'whatwg-url');
+}
+function cssstyleTargets(deps) {
+    const packageRoot = findPackageRoot(deps, resolveFromJsdom(deps, 'cssstyle'), 'cssstyle');
+    return [
+        join(packageRoot, 'lib', 'allExtraProperties.js'),
+        join(packageRoot, 'lib', 'generated', 'allProperties.js'),
+        join(packageRoot, 'lib', 'generated', 'implementedProperties.js')
+    ].map((file) => ({
+        file,
+        label: `cssstyle/${relative(packageRoot, file).split(sep).join('/')}`
+    }));
+}
+/**
+ * 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 function ensureJitiCompat(deps = defaultDeps) {
+    const status = { pending: [], patched: [] };
+    try {
+        const file = tr46Entry(deps);
+        const contents = deps.readFileSync(file);
+        if (contents.includes(PUNYCODE_SPECIFIER)) {
+            deps.writeFileSync(file, contents.replaceAll(PUNYCODE_SPECIFIER, PUNYCODE_REPLACEMENT));
+            status.patched.push('tr46/index.js');
+        }
+    }
+    catch {
+        // A read-only install, a missing dependency, or a future dependency bump
+        // that changes the shape. Report it rather than blocking extension load.
+        status.pending.push('tr46/index.js');
+    }
+    try {
+        for (const { file, label } of cssstyleTargets(deps)) {
+            // Guard the read too: one unreadable file (EACCES, odd permissions) must
+            // not abandon the other two, which may be perfectly writable.
+            try {
+                if (!deps.existsSync(file))
+                    continue;
+                const contents = deps.readFileSync(file);
+                if (contents.includes(SET_SHIM_MARKER))
+                    continue;
+                if (!contents.includes('module.exports = new Set('))
+                    continue;
+                deps.writeFileSync(file, contents + SET_SHIM);
+                status.patched.push(label);
+            }
+            catch {
+                status.pending.push(label);
+            }
+        }
+    }
+    catch {
+        status.pending.push('cssstyle');
+    }
+    return status;
+}
+/**
+ * Read-only view of the same checks, for `/web-agent doctor`. Never throws and
+ * never writes.
+ */
+export function checkJitiCompat(deps = defaultDeps) {
+    const status = { pending: [], patched: [] };
+    try {
+        const contents = deps.readFileSync(tr46Entry(deps));
+        if (contents.includes(PUNYCODE_SPECIFIER))
+            status.pending.push('tr46/index.js');
+    }
+    catch {
+        status.pending.push('tr46/index.js');
+    }
+    try {
+        for (const { file, label } of cssstyleTargets(deps)) {
+            try {
+                if (!deps.existsSync(file))
+                    continue;
+                const contents = deps.readFileSync(file);
+                if (contents.includes(SET_SHIM_MARKER))
+                    continue;
+                if (contents.includes('module.exports = new Set('))
+                    status.pending.push(label);
+            }
+            catch {
+                status.pending.push(label);
+            }
+        }
+    }
+    catch {
+        status.pending.push('cssstyle');
+    }
+    return status;
+}

package/dist/orchestration/answer-synthesizer.js

@@ -15,6 +15,8 @@ function sentenceForReason(reason) {
             return 'readable sources include cautionary or possibly conflicting guidance';
         case 'bot-check':
             return 'some candidate sources showed bot-check or security verification pages';
+        case 'partial-search-coverage':
+            return 'some search backends were unavailable, so results may be incomplete';
     }
 }
 function joinReasons(reasons) {

package/dist/orchestration/evidence-quality.d.ts

@@ -1,5 +1,5 @@
 import type { ResearchEvidence, ResearchGap, ResearchLowValueOutcome } from './research-types.js';
-export type EvidenceCaveatReason = 'community-only' | 'low-diversity' | 'unreadable-direct-source' | 'unreadable-thread-source' | 'possible-conflict' | 'bot-check';
+export type EvidenceCaveatReason = 'community-only' | 'low-diversity' | 'unreadable-direct-source' | 'unreadable-thread-source' | 'possible-conflict' | 'bot-check' | 'partial-search-coverage';
 export type EvidenceQualityReport = {
     counts: {
         total: number;
@@ -20,8 +20,9 @@ export type EvidenceQualityReport = {
     };
     caveatReasons: EvidenceCaveatReason[];
 };
-export declare function analyzeEvidenceQuality({ evidence, gaps, lowValueOutcomes }: {
+export declare function analyzeEvidenceQuality({ evidence, gaps, lowValueOutcomes, partialSearchCoverage }: {
     evidence: ResearchEvidence[];
     gaps: ResearchGap[];
     lowValueOutcomes: ResearchLowValueOutcome[];
+    partialSearchCoverage?: boolean;
 }): EvidenceQualityReport;

package/dist/orchestration/evidence-quality.js

@@ -20,7 +20,7 @@ function addReason(reasons, reason, enabled) {
     if (enabled && !reasons.includes(reason))
         reasons.push(reason);
 }
-export function analyzeEvidenceQuality({ evidence, gaps, lowValueOutcomes }) {
+export function analyzeEvidenceQuality({ evidence, gaps, lowValueOutcomes, partialSearchCoverage = false }) {
     const official = evidence.filter((item) => item.sourceKind === 'official-docs' || item.sourceKind === 'official-api').length;
     const community = evidence.filter((item) => item.sourceKind === 'community').length;
     const thread = evidence.filter((item) => item.sourceKind === 'issue-thread' || item.sourceKind === 'official-discussion').length;
@@ -41,6 +41,7 @@ export function analyzeEvidenceQuality({ evidence, gaps, lowValueOutcomes }) {
     addReason(caveatReasons, 'unreadable-thread-source', hasUnreadableThreadSource);
     addReason(caveatReasons, 'possible-conflict', hasPossibleConflict);
     addReason(caveatReasons, 'bot-check', hasBotCheck);
+    addReason(caveatReasons, 'partial-search-coverage', partialSearchCoverage);
     return {
         counts: {
             total: evidence.length,

package/dist/orchestration/index.d.ts

@@ -19,6 +19,7 @@ export declare function createResearchWorkflow({ backendConfig, search, fetchPag
         evidence: import("./research-types.js").ResearchEvidence[];
         workerPass: import("./research-types.js").ResearchWorkerResult;
         metadata: {
+            attempts?: import("../types.js").Attempt[] | undefined;
             searchPasses: number;
             fetchedPages: number;
             headlessAttempts: number;
@@ -27,5 +28,27 @@ export declare function createResearchWorkflow({ backendConfig, search, fetchPag
             fanoutProviders: import("../types.js").SearchProviderName[] | undefined;
             fanoutSkipped: import("../types.js").SearchProviderName[] | undefined;
         };
+        terminalFailure?: undefined;
+    } | {
+        decision: import("./research-types.js").ResearchOrchestratorDecision;
+        evidence: never[];
+        workerPass: import("./research-types.js").ResearchWorkerResult;
+        metadata: {
+            attempts?: import("../types.js").Attempt[] | undefined;
+            searchPasses: number;
+            fetchedPages: number;
+            headlessAttempts: number;
+            exhaustedBudget: boolean;
+            caveatReasons: import("./evidence-quality.js").EvidenceCaveatReason[];
+            fanoutProviders: import("../types.js").SearchProviderName[] | undefined;
+            fanoutSkipped: import("../types.js").SearchProviderName[] | undefined;
+        };
+        terminalFailure: {
+            code: string;
+            message: string;
+        };
     }>;
+} & {
+    /** Releases the backend set this workflow created. Injected capabilities are left alone. */
+    close(): Promise<void>;
 };

package/dist/orchestration/index.js

@@ -2,14 +2,21 @@ import { createBackendSet } from '../backends/factory.js';
 import { createResearchOrchestrator } from './research-orchestrator.js';
 import { createResearchWorker } from './research-worker.js';
 export function createResearchWorkflow({ backendConfig, search, fetchPage, headlessFetch } = {}) {
-    const backends = createBackendSet(backendConfig);
+    // Only build (and own) a backend set when something wasn't injected.
+    const backends = search && fetchPage && headlessFetch ? undefined : createBackendSet(backendConfig);
     const resolvedSearch = search ?? backends.search;
     const resolvedFetchPage = fetchPage ?? backends.fetchPage;
     const resolvedHeadlessFetch = headlessFetch ?? backends.headlessFetch;
     const worker = createResearchWorker({ search: resolvedSearch, fetchPage: resolvedFetchPage });
-    return createResearchOrchestrator({
+    const orchestrator = createResearchOrchestrator({
         worker,
         fetchDirect: resolvedFetchPage,
         headlessFetch: resolvedHeadlessFetch
     });
+    return Object.assign(orchestrator, {
+        /** Releases the backend set this workflow created. Injected capabilities are left alone. */
+        async close() {
+            await backends?.close?.();
+        }
+    });
 }

package/dist/orchestration/research-orchestrator.d.ts

@@ -1,4 +1,4 @@
-import type { SearchProviderName, WebFetchHeadlessResponse, WebFetchResponse } from '../types.js';
+import type { Attempt, SearchProviderName, WebFetchHeadlessResponse, WebFetchResponse } from '../types.js';
 import type { ResearchEvidence, ResearchOrchestratorDecision, ResearchWorkerResult } from './research-types.js';
 import { type EvidenceCaveatReason } from './evidence-quality.js';
 export declare function createResearchOrchestrator({ worker, fetchDirect, headlessFetch }: {
@@ -23,6 +23,7 @@ export declare function createResearchOrchestrator({ worker, fetchDirect, headle
         evidence: ResearchEvidence[];
         workerPass: ResearchWorkerResult;
         metadata: {
+            attempts?: Attempt[] | undefined;
             searchPasses: number;
             fetchedPages: number;
             headlessAttempts: number;
@@ -31,5 +32,24 @@ export declare function createResearchOrchestrator({ worker, fetchDirect, headle
             fanoutProviders: SearchProviderName[] | undefined;
             fanoutSkipped: SearchProviderName[] | undefined;
         };
+        terminalFailure?: undefined;
+    } | {
+        decision: ResearchOrchestratorDecision;
+        evidence: never[];
+        workerPass: ResearchWorkerResult;
+        metadata: {
+            attempts?: Attempt[] | undefined;
+            searchPasses: number;
+            fetchedPages: number;
+            headlessAttempts: number;
+            exhaustedBudget: boolean;
+            caveatReasons: EvidenceCaveatReason[];
+            fanoutProviders: SearchProviderName[] | undefined;
+            fanoutSkipped: SearchProviderName[] | undefined;
+        };
+        terminalFailure: {
+            code: string;
+            message: string;
+        };
     }>;
 };

package/dist/orchestration/research-orchestrator.js

@@ -1,3 +1,4 @@
+import { failureOf, isTerminalFailure } from '../backends/failure.js';
 import { rankEvidence } from './evidence-ranker.js';
 import { planSearchQueries } from './query-planner.js';
 import { classifySourceProfile } from './source-profile.js';
@@ -79,7 +80,7 @@ function shouldRetryDirectWithHeadless(result, evidence) {
         return false;
     return classifySourceProfile(result.url).shouldPreferHeadlessWhenWeak;
 }
-function buildMetadata({ previousQueries, allEvidence, allGaps, allLowValueOutcomes, headlessAttempts, exhaustedBudget, caveatReasons = [], fanoutProviders, fanoutSkipped }) {
+function buildMetadata({ previousQueries, allEvidence, allGaps, allLowValueOutcomes, headlessAttempts, exhaustedBudget, caveatReasons = [], fanoutProviders, fanoutSkipped, attempts }) {
     return {
         searchPasses: previousQueries.length,
         fetchedPages: allEvidence.length + allGaps.length + allLowValueOutcomes.length,
@@ -87,7 +88,8 @@ function buildMetadata({ previousQueries, allEvidence, allGaps, allLowValueOutco
         exhaustedBudget,
         caveatReasons,
         fanoutProviders,
-        fanoutSkipped
+        fanoutSkipped,
+        ...(attempts && attempts.length > 0 ? { attempts } : {})
     };
 }
 function decisionForAnswer({ action, query, ranked, exhaustedBudget }) {
@@ -114,21 +116,33 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
             const suggestedHeadlessUrls = [];
             let headlessAttempts = 0;
             let lastPass;
+            let searchCoveragePartial = false;
             const fanoutProvidersSeen = new Set();
             const fanoutSkippedSeen = new Set();
+            // Search and fetch attempts from every pass and direct URL, for verbose provenance.
+            const runAttempts = [];
             function fanoutSnapshot() {
                 const providers = fanoutProvidersSeen.size ? [...fanoutProvidersSeen] : undefined;
                 const skipped = [...fanoutSkippedSeen].filter((p) => !fanoutProvidersSeen.has(p));
-                return { fanoutProviders: providers, fanoutSkipped: skipped.length ? skipped : undefined };
+                return { fanoutProviders: providers, fanoutSkipped: skipped.length ? skipped : undefined, attempts: [...runAttempts] };
             }
             if (fetchDirect) {
                 for (const url of extractDirectUrls(query).slice(0, 3)) {
                     const directResult = await fetchDirect({ url });
+                    if (directResult.metadata.attempts)
+                        runAttempts.push(...directResult.metadata.attempts);
                     const directEvidence = evidenceFromFetch(directResult);
                     if (directEvidence) {
                         allEvidence.push(directEvidence);
                         continue;
                     }
+                    if (isTerminalFailure(failureOf(directResult))) {
+                        allGaps.push({
+                            kind: 'fetch-failed',
+                            message: directResult.error?.message ?? `Direct URL fetch failed for ${directResult.url}`
+                        });
+                        continue;
+                    }
                     if (shouldRetryDirectWithHeadless(directResult, directEvidence)) {
                         if (headlessAttempts < DEFAULT_MAX_HEADLESS_ATTEMPTS) {
                             headlessAttempts++;
@@ -161,7 +175,8 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
                 const quality = analyzeEvidenceQuality({
                     evidence: ranked,
                     gaps: allGaps,
-                    lowValueOutcomes: allLowValueOutcomes
+                    lowValueOutcomes: allLowValueOutcomes,
+                    partialSearchCoverage: searchCoveragePartial
                 });
                 return {
                     decision: decisionForAnswer({ action: 'answer', query, ranked, exhaustedBudget: false }),
@@ -200,6 +215,21 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
                         maxFetches: DEFAULT_MAX_FETCHES_PER_PASS
                     });
                     lastPass = pass;
+                    if (pass.searchAttempts)
+                        runAttempts.push(...pass.searchAttempts);
+                    if (pass.fetchAttempts)
+                        runAttempts.push(...pass.fetchAttempts);
+                    if (pass.searchCoveragePartial)
+                        searchCoveragePartial = true;
+                    if (pass.terminalFailure) {
+                        return {
+                            decision: decisionForAnswer({ action: 'answer-with-caveat', query, ranked: [], exhaustedBudget: false }),
+                            evidence: [],
+                            workerPass: combinedWorkerPass({ lastPass, previousQueries, allGaps, allLowValueOutcomes, exhaustedBudget: false }),
+                            metadata: buildMetadata({ previousQueries, allEvidence, allGaps, allLowValueOutcomes, headlessAttempts, exhaustedBudget: false, ...fanoutSnapshot() }),
+                            terminalFailure: pass.terminalFailure
+                        };
+                    }
                     pass.fanoutProviders?.forEach((p) => fanoutProvidersSeen.add(p));
                     pass.fanoutSkipped?.forEach((p) => fanoutSkippedSeen.add(p));
                     allEvidence.push(...pass.evidence);
@@ -211,7 +241,8 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
                     const quality = analyzeEvidenceQuality({
                         evidence: ranked,
                         gaps: allGaps,
-                        lowValueOutcomes: allLowValueOutcomes
+                        lowValueOutcomes: allLowValueOutcomes,
+                        partialSearchCoverage: searchCoveragePartial
                     });
                     const decision = decideNextResearchStep({
                         evidence: ranked,
@@ -232,7 +263,8 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
                             const updatedQuality = analyzeEvidenceQuality({
                                 evidence: updatedRanked,
                                 gaps: allGaps,
-                                lowValueOutcomes: allLowValueOutcomes
+                                lowValueOutcomes: allLowValueOutcomes,
+                                partialSearchCoverage: searchCoveragePartial
                             });
                             const updatedDecision = decideNextResearchStep({
                                 evidence: updatedRanked,
@@ -328,7 +360,8 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
             const quality = analyzeEvidenceQuality({
                 evidence: ranked,
                 gaps: allGaps,
-                lowValueOutcomes: allLowValueOutcomes
+                lowValueOutcomes: allLowValueOutcomes,
+                partialSearchCoverage: searchCoveragePartial
             });
             return {
                 decision: decisionForAnswer({ action: 'answer-with-caveat', query, ranked, exhaustedBudget: true }),

package/dist/orchestration/research-types.d.ts

@@ -1,4 +1,4 @@
-import type { SearchProviderName } from '../types.js';
+import type { Attempt, SearchProviderName } from '../types.js';
 export type ResearchSourceKind = 'primary-content' | 'official-docs' | 'official-api' | 'official-discussion' | 'community' | 'issue-thread' | 'package-page' | 'other';
 export type ResearchMethod = 'search' | 'http' | 'headless' | 'firecrawl' | 'github' | 'pdf' | 'youtube';
 export type ResearchEvidence = {
@@ -27,6 +27,13 @@ export type ResearchWorkerResult = {
     exhaustedBudget: boolean;
     fanoutProviders?: SearchProviderName[];
     fanoutSkipped?: SearchProviderName[];
+    searchCoveragePartial?: boolean;
+    searchAttempts?: Attempt[];
+    fetchAttempts?: Attempt[];
+    terminalFailure?: {
+        code: string;
+        message: string;
+    };
 };
 export type ResearchRunMetadata = {
     searchPasses: number;
@@ -35,6 +42,11 @@ export type ResearchRunMetadata = {
     exhaustedBudget: boolean;
     fanoutProviders?: SearchProviderName[];
     fanoutSkipped?: SearchProviderName[];
+    searchCoveragePartial?: boolean;
+    terminalFailure?: {
+        code: string;
+        message: string;
+    };
 };
 export type ResearchOrchestratorDecision = {
     action: 'answer';