dsh-web-search-pro 0.2.1 → 0.2.3

package/lib/types/overlay-types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The agent overlay, pure half: the shapes the overlay file, the `config.*` actions and the settings card's RPC channel carry, and
+ * the small helpers that name an overlay entry. The store that reads and writes the file is overlay.ts (Node); the card bundle
+ * includes only this file. No imports.
+ *
+ * The overlay is a small managed file next to the plugin's database. It sits on top of the configuration the user owns (the
+ * profile) and can hold only the settings an agent may change at run time: the engine order, the source priority and disabled
+ * lists, the confidence of a source, the backend chain of a platform, and custom CLI adapter specs. Everything else stays
+ * the user's: an agent cannot reach a key, a path, a switch or a budget through it.
+ * @module web-search-pro/overlay-types
+ */
+export declare const OVERLAY_VERSION = 1;
+export declare const OVERLAY_FILE = "overlay.json";
+/** The audit trail is cut to the newest entries, so the file stays small however long it lives. */
+export declare const MAX_AUDIT_ENTRIES = 50;
+export declare const MIN_REASON = 3;
+export declare const MAX_REASON = 300;
+/** What `config.reset` can drop. */
+export declare const RESET_SCOPES: readonly ["all", "order", "confidence", "cli", "platform"];
+export type ResetScope = typeof RESET_SCOPES[number];
+/** The overlaid values, in the shape of the configuration fields they sit on. Absent = the baseline applies. */
+export interface OverlayValues {
+    /** The whole `engines` list. */
+    engines?: string[];
+    sources?: {
+        priority?: string[];
+        disabled?: string[];
+        /** Per source or backend id. */
+        confidence?: Record<string, number>;
+    };
+    /** Per platform, the whole backend chain. */
+    platformBackends?: Record<string, string[]>;
+    /** Per id, the whole adapter spec (without its `id`, which is the key). */
+    cliAdapters?: Record<string, Record<string, unknown>>;
+}
+/** One line of the audit trail: what a key was before and after, as short text. */
+export interface AuditChange {
+    key: string;
+    before: string;
+    after: string;
+}
+export interface AuditEntry {
+    /** The revision this change produced. */
+    revision: number;
+    at: string;
+    /** `agent`: a `config.*` action. `user`: the settings card. */
+    actor: 'agent' | 'user';
+    action: string;
+    sessionId?: string;
+    reason: string;
+    changes: AuditChange[];
+}
+export type OverlayItemKind = 'engines' | 'priority' | 'disabled' | 'confidence' | 'platform' | 'cli';
+/** One overridden key, for the card and `config.inspect`. */
+export interface OverlayItem {
+    /** `engines`, `sources.priority`, `sources.disabled`, `sources.confidence.<id>`, `platformBackends.<platform>`, `cliAdapters.<id>`. */
+    key: string;
+    kind: OverlayItemKind;
+    /** The id, platform or adapter id the key is about. */
+    target?: string;
+    /** The overlaid value. */
+    value: unknown;
+    /** Short text of the overlaid value. */
+    summary: string;
+    /** Short text of what the baseline holds there, for the card. */
+    baseline: string;
+    /** The newest audit entry that touched this key (absent when it has rotated out of the trail). */
+    at?: string;
+    reason?: string;
+    actor?: AuditEntry['actor'];
+    sessionId?: string;
+}
+/** What the card reads over RPC (`overlay` endpoint) and `config.inspect` extends. */
+export interface OverlayView {
+    file: string;
+    revision: number;
+    updatedAt: string;
+    /** The overlay file loads and agrees with the baseline; false = it is being ignored as a whole. */
+    valid: boolean;
+    problem?: string;
+    items: OverlayItem[];
+    audit: AuditEntry[];
+}
+/** The keys an overlay holds, in a stable order. */
+export declare function overlayKeys(values: OverlayValues): string[];
+/** Kind and target of an overlay key; undefined for a name that is not one. */
+export declare function describeKey(key: string): {
+    kind: OverlayItemKind;
+    target?: string;
+} | undefined;
+export declare function clipText(text: string, max: number): string;
+/**
+ * Short text of a value for the audit trail and the card: a list is its items joined with `>` (order matters), a number is itself,
+ * a CLI spec is its command and search arguments (what the program is and what it is asked), nothing is `(none)`.
+ */
+export declare function summarizeValue(key: string, value: unknown, max?: number): string;
+/** `<bins[0]> <search.argv...>`: the command a custom CLI spec would run for a search, with the placeholders as written. */
+export declare function cliCommandLine(spec: Record<string, unknown>): string;

package/lib/types/overlay.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The agent overlay: the settings an agent may change at run time without hand-editing the configuration.
+ *
+ * The profile configuration stays the user's baseline. The overlay is a small managed file next to the plugin's database
+ * (`$DSH_HOME/data/web-search-pro/overlay.json`, or beside `dbPath` when the user moved it) that `dynamic()` merges on top of the
+ * baseline on every read, so every consumer sees the change at once, with no watcher and no restart. It holds only what
+ * overlay-types.ts lists (engine order, source priority / disabled, confidence, platform backend chains, custom CLI specs),
+ * carries a revision for optimistic locking, a checksum, and an audit trail cut to {@link MAX_AUDIT_ENTRIES} entries.
+ *
+ * The same functions validate a change before it is written and the whole file when it is loaded: a file that does not parse,
+ * fails its checksum, holds a value the validators refuse, or no longer agrees with the baseline (a chain naming a CLI the user
+ * removed) is ignored as a whole and reported, never half applied. Validation reuses the functions the settings card and
+ * `sources.status` use (`cliIssues`, `sourcesIssues`, the CLI spec validator, the source id rules).
+ *
+ * Adding or replacing only: the overlay never deletes a baseline entry. Taking a baseline CLI out of service is
+ * `sources.disabled`; removing a CLI the overlay added is `config.remove_cli`.
+ * @module web-search-pro/overlay
+ */
+import type { ResolvedConfig } from './config.ts';
+import { MAX_AUDIT_ENTRIES, OVERLAY_FILE, OVERLAY_VERSION, type AuditChange, type AuditEntry, type OverlayItem, type OverlayValues, type OverlayView, type ResetScope } from './overlay-types.ts';
+export { MAX_AUDIT_ENTRIES, OVERLAY_FILE, OVERLAY_VERSION };
+export interface Overlay {
+    version: 1;
+    revision: number;
+    updatedAt: string;
+    values: OverlayValues;
+    audit: AuditEntry[];
+}
+export declare function emptyOverlay(): Overlay;
+export declare function checksumOf(overlay: Pick<Overlay, 'version' | 'revision' | 'updatedAt' | 'values' | 'audit'>): string;
+/** `<dir of dbPath>/overlay.json`: the overlay sits beside the database, wherever the user put it. */
+export declare function overlayFileFor(dbPath: string): string;
+/** The baseline with the overlay merged on top. Never mutates its inputs. */
+export declare function mergeOverlay(base: ResolvedConfig, values: OverlayValues): ResolvedConfig;
+/** Where the effective value of an overlay key comes from, and what it is. */
+export declare function effectiveValueOf(config: ResolvedConfig, key: string): unknown;
+/** The id rules of the sources the baseline knows; supplied by the router (`registry.routeId(id) !== undefined`). */
+export type KnownSource = (id: string) => boolean;
+/** Problems the overlay values add to what the baseline already has (the user's own mistakes are not the overlay's to answer for). */
+export declare function overlayErrors(base: ResolvedConfig, values: OverlayValues, known: KnownSource): string[];
+/**
+ * Every problem with the `id` / `spec` of a `config.upsert_cli` call, one message each ([] when the call is valid). The single
+ * source of these rules: {@link OverlayStore.apply} refuses a change that has any, and the action's `precheck` asks it before the
+ * user is, so an unusable spec never reaches an approval prompt. It reads no state, so it never depends on the overlay file.
+ */
+export declare function cliSpecProblems(id: unknown, spec: unknown): string[];
+/** Reason rule shared by every write: a real sentence, not a placeholder. */
+export declare function checkReason(reason: unknown): string;
+export type OverlayChange = {
+    kind: 'order';
+    engines?: unknown;
+    priority?: unknown;
+    disabled?: unknown;
+    platform?: unknown;
+    backends?: unknown;
+} | {
+    kind: 'confidence';
+    id: unknown;
+    value: unknown;
+} | {
+    kind: 'upsertCli';
+    id: unknown;
+    spec: unknown;
+} | {
+    kind: 'removeCli';
+    id: unknown;
+} | {
+    kind: 'reset';
+    scope: ResetScope;
+    id?: unknown;
+}
+/** The settings card: drop these keys (one or several), or everything when `keys` is `'all'`. */
+ | {
+    kind: 'revoke';
+    keys: readonly string[] | 'all';
+};
+export interface ChangeMeta {
+    actor: 'agent' | 'user';
+    /** The action name (`config.set_order`) or the card's button. */
+    action: string;
+    reason: string;
+    sessionId?: string;
+    /** When given, the change only applies if the overlay is still at this revision. */
+    expectedRevision?: number;
+}
+export interface AppliedChange {
+    /** False when the change left the overlay as it was (nothing was written, the revision is unchanged). */
+    changed: boolean;
+    revision: number;
+    keys: string[];
+    changes: AuditChange[];
+    audit?: AuditEntry;
+}
+export interface OverlayStoreOptions {
+    file: string;
+    /** The configuration the user owns (the profile), re-read on every call. */
+    baseline: () => ResolvedConfig;
+    known: KnownSource;
+    /** Changes whenever the answer of `known` can have changed (the router's registry revision), so a cached verdict is not kept past it. */
+    knownSignature?: () => string;
+    now?: () => Date;
+}
+export declare class OverlayStore {
+    private readonly options;
+    private overlay;
+    private signature;
+    private loadProblem;
+    private compat;
+    constructor(options: OverlayStoreOptions);
+    get file(): string;
+    private stat;
+    /** Re-read the file when its mtime or size changed. No watcher: every read of the effective config asks. */
+    private refresh;
+    private reload;
+    private readFile;
+    /** Strict parse: unknown keys, wrong types, a failed checksum or any value the validators refuse reject the whole file. */
+    private parse;
+    /** Why the overlay is being ignored, if it is: a broken file, or values that no longer agree with the baseline. */
+    get problem(): string | undefined;
+    private incompatibility;
+    /** The loaded overlay (an empty one while the file is missing or ignored). */
+    current(): Overlay;
+    /** The configuration as the plugin runs it: the baseline with the overlay on top, or the baseline alone while the overlay is ignored. */
+    effective(): ResolvedConfig;
+    baselineConfig(): ResolvedConfig;
+    /** The overlaid keys with the newest audit entry that touched each, for the card and `config.inspect`. */
+    items(): OverlayItem[];
+    view(limit?: number): OverlayView;
+    /** Compute the values a change leads to without writing anything. Throws {@link ActionArgError} for an invalid change. */
+    private plan;
+    /** Drop empty containers, and entries equal to the baseline (an override that changes nothing is not one). */
+    private normalize;
+    /**
+     * Plan, validate and write a change: re-reads the file first, checks the revision, validates the merged result with the
+     * server's own functions, writes atomically (0600) and appends the audit entry. A failed change leaves the file as it was.
+     */
+    apply(change: OverlayChange, meta: ChangeMeta): AppliedChange;
+    private write;
+    /** Move an unreadable file aside (kept for inspection) so a fresh overlay can start. */
+    private quarantine;
+}

package/lib/types/pipeline/candidates.d.ts

@@ -13,6 +13,13 @@ export interface ProviderSource {
     title?: string | null;
     snippet?: string | null;
     publishedAt?: string | null;
+    rerankScore?: number | null;
+    authority?: number | null;
+    /** The user-defined CLI that returned the row (`custom-cli:echo`) and the label it carries. */
+    via?: string | null;
+    tag?: string | null;
+    /** The source's confidence (0..1) when it is below 1 (see confidence.ts). */
+    confidence?: number | null;
 }
 /** One provider's ordered result list for one query (index 0 = rank 1). */
 export interface ProviderOutput {
@@ -29,6 +36,16 @@ export interface MergeOptions {
 export declare function candidateIdOf(canonical: string): string;
 /** Fold snippet `next` into `current`: drop repeats, keep the longer of near-duplicates, join complements within `cap`. */
 export declare function mergeSnippets(current: string, next: string | null | undefined, cap?: number): string;
+/**
+ * What a result says about where it came from, for the exit: the custom CLIs that returned it (`via`) with their honest label (`tag`),
+ * and `confidence` = the best confidence among the providers that returned it, only when it is below 1 (a URL a full-confidence
+ * source also returned is as sure as that source). Empty for a result of built-in sources only.
+ */
+export declare function provenanceOf(candidate: Pick<Candidate, 'contributions' | 'origin'>): {
+    via?: string;
+    tag?: string;
+    confidence?: number;
+};
 /**
  * Merge provider outputs into candidates keyed by canonical URL, in first-seen
  * order (outputs in the given order, sources by rank). Sources without a URL

package/lib/types/pipeline/compile.d.ts

@@ -15,6 +15,9 @@
  *  - keyed sources (dev-plan M7c): Tavily / Linkup / Baidu Qianfan / Zhipu take domain lists (`options.sites`, capped at what
  *    each documents) and a date lower bound (`options.since`); Brave / Serper (Google) take `site:` / `-site:` / `-term`
  *    operators in the query; whatever a source does not document stays for local verification;
+ *  - deepseek (DeepSeek Search API): `site:a OR site:b` / `-site:` / `-term` for HARD site / exclude_site / exclude_term and
+ *    `after:YYYY-MM-DD` for a HARD time_window whose lower bound is understood, all in the query text (the API documents them as
+ *    query operators); `originalQuestion` carries the task goal (or the first critical need) for the API's `ori_question`;
  *  - github*: the natural-language query returns nothing on repository search
  *    (E1: 0 of 20), so it is replaced by a short keyword query;
  *  - everything else: the plain query.
@@ -52,6 +55,7 @@ export interface CompiledQuery {
         since?: string;
         lang?: 'zh' | 'en';
         sites?: CompiledSites;
+        originalQuestion?: string;
     };
     /** Broader variants to try, in order, when the provider answers ENGINE_EMPTY for `query` (GitHub: fewer keywords). */
     fallbacks?: string[];
@@ -103,6 +107,13 @@ export declare function hardWindows(task: TaskLike, now: Date): {
  * sources get `site:` / `-site:` / `-term` in the query. Soft constraints are never pushed down.
  */
 export declare function compileKeyed(task: TaskLike, providerId: string, now: Date, caps: KeyedCaps): CompiledQuery;
+/**
+ * DeepSeek Search takes `site:` (several joined by `OR`), `-site:`, `-term`, `"phrase"`, `lang:`, `after:` and `before:` inside
+ * the query. Hard constraints become those operators (the engine keeps them whole when it has to cut a long query). An operator the
+ * query already spells is not repeated; a hard site when the query already restricts to other sites stays local (two `site:`
+ * restrictions would AND into nothing).
+ */
+export declare function compileDeepSeek(task: TaskLike, providerId: string, now: Date): CompiledQuery;
 export declare const GITHUB_MAX_TERMS = 5;
 /**
  * Short keyword query for repository search: entities, then must_terms, then a

package/lib/types/pipeline/confidence.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Source confidence (0..1): how far the user trusts what one source returns. It is an input of rank fusion and a label on results,
+ * nothing else: it never removes a result, never changes what a source is asked, and every built-in source has confidence 1, so
+ * with the defaults the fused order is exactly what it was before confidence existed.
+ *
+ *   factor(c) = 1 - STRENGTH · (1 - c)           c in [0, 1]; undefined = 1; the factor is always in [1 - STRENGTH, 1]
+ *   rrf(d)    = Σ_provider factor(c_provider) / (k + bestRank_provider(d))       (fusion.ts)
+ *   bonus(d)  = bonus(d) · max_provider factor(c_provider)                       a URL only a doubted source returned earns less of the tie-break bonuses
+ *
+ * A source of confidence c therefore ranks as if its list began ((k + 1) / factor - (k + 1)) positions lower: at k = 60 about 7
+ * positions for c = 0.5 and about 16 for c = 0. Results several sources agree on lose almost nothing, a result only a doubted
+ * source has sinks towards the tail, and {@link guaranteeSeats} makes sure its best one is still within the list that is shown.
+ * Pure and free of imports: the settings card and the tests read it too.
+ * @module web-search-pro/pipeline/confidence
+ */
+/** How much confidence 0 takes off the contribution of a source (0.2 = a fifth). */
+export declare const CONFIDENCE_STRENGTH = 0.2;
+/** Confidence of a source nothing is known about: the built-in ones. */
+export declare const FULL_CONFIDENCE = 1;
+/** A confidence as a number in [0, 1]; anything else (missing, NaN) is full confidence. */
+export declare function clampConfidence(value: number | undefined): number;
+/** The multiplier of a source's rank-fusion contribution, in [1 - STRENGTH, 1]; exactly 1 for confidence 1 or none. */
+export declare function confidenceFactor(confidence: number | undefined): number;
+/** A contribution of one provider to a candidate; `confidence` is present only when it is below 1. */
+export interface WeightedContribution {
+    providerId: string;
+    confidence?: number;
+}
+/**
+ * Keep the best result of every doubted source within the first `size` results. A source whose confidence is below 1 and which
+ * answered, but has none of its results in the window, gets its best-ranked result moved to the end of the window (at most
+ * `size - 1` such seats, so the window never consists of nothing else). The order of everything else is kept. With no confidence
+ * below 1 anywhere the list comes back unchanged.
+ */
+export declare function guaranteeSeats<T>(ranked: readonly T[], size: number, contributions: (item: T) => readonly WeightedContribution[]): T[];

package/lib/types/pipeline/fusion.d.ts

@@ -4,7 +4,7 @@
  *   rrf(d)   = Σ_provider 1 / (k + bestRank_provider(d))     one term per provider
  *   norm(d)  = rrf(d) / (nProviders / (k + 1))               in [0, 1]; 1 = rank 1 everywhere
  *   score(d) = norm(d) + bonus(d)                            bonus added ONCE per URL
- *   bonus(d) = (freshnessBoost·fresh(d) + authorityBoost·authority(d)) · unit
+ *   bonus(d) = (freshnessBoost·fresh(d) + authorityBoost·authority(d) + signalBoost·signal(d)) · unit
  *   unit     = 1 / (nProviders · (k + 2))                    one top-rank step of one provider, on the normalised scale
  *
  * `freshnessBoost` / `authorityBoost` (config, 0..1) are therefore FRACTIONS OF
@@ -13,10 +13,25 @@
  * positions. They break ties and near-ties; they cannot lift a rank-10 result
  * over a rank-1 result of the same provider. A URL returned by several
  * providers gets one bonus, not one per hit.
+ *
+ * `signal(d)` is the provider's OWN quality grade when it gives one (DeepSeek Search: `rerank_score` 0..3, which already folds
+ * relevance, authority and freshness together, and `authority` 0..4): 0.7·rerank/3 + 0.3·authority/4 over whichever of the two
+ * the URL has (the best seen over providers, see candidates.ts), 0 for a URL no provider graded. `signalBoost` (default
+ * {@link PROVIDER_SIGNAL_BOOST}) is, like the others, a fraction of ONE top-rank step: with the default boosts the three
+ * bonuses together can never reach one rank position (0.2 + 0.25 + 0.3 = 0.75). A provider that grades its own results already
+ * orders them, so the signal mostly arbitrates between providers; it never lifts a rank-10 result over a rank-1 one.
+ *
+ * Source confidence (confidence.ts) scales each provider's RRF term by `factor(c)` in [0.8, 1] and the bonus of a URL by the best factor
+ * among the providers that returned it; a provider without a confidence, which is every built-in source, has factor exactly 1 and the
+ * scores are what they were without it.
  * @module web-search-pro/pipeline/fusion
  */
 import type { Candidate } from './types.ts';
 export declare const AUTHORITY_DOMAINS_BUILTIN: readonly string[];
+/** Default weight of the provider's own quality signal (fraction of one top-rank step); see the module comment. */
+export declare const PROVIDER_SIGNAL_BOOST = 0.3;
+/** Share of the provider signal that comes from `rerank_score` (the rest is `authority`, when the URL has one). */
+export declare const RERANK_SIGNAL_WEIGHT = 0.7;
 export interface FusionOptions {
     /** RRF smoothing constant (config rrfConstant). */
     k: number;
@@ -26,6 +41,8 @@ export interface FusionOptions {
     freshnessDays: number;
     /** Fraction of one top-rank step for an authority host (0..1). */
     authorityBoost: number;
+    /** Fraction of one top-rank step for a result the provider itself graded best (0..1; default {@link PROVIDER_SIGNAL_BOOST}); 0 turns the signal off. */
+    signalBoost?: number;
     /** Extra authority domains; the built-in list and .edu/.gov/.org always apply. */
     authorityDomains: readonly string[];
     /** Providers that took part (answered, even with few results). Defaults to the distinct providers in the candidates. */
@@ -42,6 +59,11 @@ export interface RankedCandidate {
     normalized: number;
     bonus: number;
 }
+/**
+ * The provider's own quality grade of a candidate in 0..1: `rerank_score` / 3 weighted 0.7 and `authority` / 4 weighted 0.3; with
+ * only one of them present that one alone; 0 when the candidate has none. Out-of-range values are clamped.
+ */
+export declare function providerSignal(candidate: Pick<Candidate, 'signals'>): number;
 /** Best (lowest) rank per provider: one RRF term per provider per URL. */
 export declare function bestRanks(candidate: Pick<Candidate, 'contributions'>): Map<string, number>;
 export declare function isAuthorityHost(host: string, extraDomains?: readonly string[]): boolean;

package/lib/types/pipeline/render.d.ts

@@ -10,8 +10,24 @@ export interface RenderSource {
     title?: string;
     snippet?: string;
     publishedAt?: string;
+    rerankScore?: number;
+    authority?: number;
     lowConfidence?: boolean;
+    via?: string;
+    confidence?: number;
+    tag?: string;
 }
+/**
+ * `[rerank 2.4/3, authority 3/4]`: the provider's own grades of a source (DeepSeek Search); for a custom CLI or a source the user gave a
+ * confidence below 1 also `via custom-cli:echo, confidence 0.5` and the honest label (user-defined, not verified). Empty when there is none of it.
+ */
+export declare function qualityTag(s: {
+    rerankScore?: number;
+    authority?: number;
+    via?: string;
+    confidence?: number;
+    tag?: string;
+}): string;
 /** Marker for a source / excerpt whose page only passed the S4 floor, not the relevance gate (dev-plan §3.1). */
 export declare const LOW_RELEVANCE = " (low relevance)";
 /** One line under the header (dev-plan M3b): "covered" is a lexical judgement, and a missing passage proves nothing. */

package/lib/types/pipeline/run.d.ts

@@ -44,7 +44,8 @@ export interface ProviderCall {
 export type ProviderOutcome = {
     state: 'ok';
     sources: readonly ProviderSource[]; /** The backend of a platform chain that answered. */
-    backend?: string;
+    backend?: string; /** The engine's own remarks (a query it had to cut, results it dropped); they reach the pack notes. */
+    notes?: readonly string[];
 }
 /** `detail` carries the provider's own explanation of an empty answer (e.g. a login hint), when it gave one. */
  | {

package/lib/types/pipeline/sources-spec.d.ts

@@ -1,5 +1,5 @@
 /**
- * Validation of the user's source preferences (`sources.priority`, `sources.disabled`, `sources.budget`), with no Node
+ * Validation of the user's source preferences (`sources.priority`, `sources.disabled`, `sources.budget`, `sources.confidence`), with no Node
  * imports so the settings panel validates them with the code the server uses; the request counters live in ./ledger.ts.
  * @module web-search-pro/pipeline/sources-spec
  */
@@ -13,11 +13,14 @@ export interface SourcesInput {
     priority?: readonly string[];
     disabled?: readonly string[];
     budget?: Record<string, SourceBudgetInput>;
+    /** Confidence (0..1) per source or platform-backend id; absent = 1 for a built-in source, the spec's own for a custom CLI. */
+    confidence?: Record<string, number>;
 }
 export interface SourcesResolved {
     priority: string[];
     disabled: string[];
     budget: Record<string, SourceBudgetInput>;
+    confidence: Record<string, number>;
     /** Entries ignored, each saying why (surfaced by `sources.status` and the settings card). */
     diagnostics: string[];
 }
@@ -25,4 +28,4 @@ export interface SourcesResolved {
  * Validate the preferences; invalid entries are dropped and reported, never thrown. `known` (optional) tells whether an
  * id is a registered provider: unknown ids are reported and dropped, so a typo cannot silently disable nothing.
  */
-export declare function resolveSources(input: SourcesInput | undefined, known?: (id: string) => boolean): SourcesResolved;
+export declare function resolveSources(input: SourcesInput | undefined, known?: (id: string) => boolean, knownBackend?: (id: string) => boolean): SourcesResolved;

package/lib/types/pipeline/types.d.ts

@@ -43,12 +43,27 @@ export interface TaskSpec {
     constraints: Constraint[];
     budget: BudgetProfile;
 }
+export interface CandidateSignals {
+    /** Provider relevance / authority / freshness rank score, 0..3. */
+    rerankScore?: number;
+    /** Provider source-authority grade, 0..4. */
+    authority?: number;
+}
 /** One provider hit for a candidate. `rank` is 1-based within that provider's result list. */
 export interface Contribution {
     providerId: string;
     rank: number;
     /** The exact query sent to the provider (may be a compiled variant). */
     query: string;
+    /** The source's confidence (0..1), present only when it is below 1: a custom CLI, or a source the user set `sources.confidence` for. */
+    confidence?: number;
+}
+/** Where a result of a user-defined source came from: shown with the result and never merged away. */
+export interface CandidateOrigin {
+    /** Ids of the custom CLIs that returned the URL (`custom-cli:echo`). */
+    via: string[];
+    /** The honest label of these sources: user-defined, not verified by the plugin. */
+    tag: string;
 }
 export type Satisfied = 'yes' | 'no' | 'unknown';
 export interface ConstraintCheck {
@@ -81,8 +96,15 @@ export interface Candidate {
     title: string;
     snippet: string;
     publishedAt?: string;
+    /**
+     * The providers' own quality signals for this URL (best seen over all providers that gave one): DeepSeek Search's `rerank_score`
+     * (0..3) and `authority` (0..4). Source metadata, and one small fusion signal (fusion.ts); absent for providers that give none.
+     */
+    signals?: CandidateSignals;
     /** Every (provider, rank, query) that returned this URL. */
     contributions: Contribution[];
+    /** Set when a user-defined CLI returned the URL. */
+    origin?: CandidateOrigin;
     checks?: ConstraintCheck[];
     gate?: GateVerdict;
 }
@@ -110,6 +132,12 @@ export interface PageBlock {
     providers: string[];
     /** The candidate only passed the S4 floor, not the relevance gate. */
     lowConfidence?: true;
+    /** Custom CLI that returned the page's URL, the label it carries, and the best confidence among the sources that returned it (below 1 only). */
+    origin?: {
+        via?: string;
+        tag?: string;
+        confidence?: number;
+    };
     block: Block;
 }
 /** `grade` is 0..3 (rule: integer buckets; Jev: the level expectation). `rank` is a finer tie-breaker. */
@@ -138,6 +166,10 @@ export interface EvidenceItem {
     source: string;
     /** The page's candidate failed the relevance gate and was kept only by the floor. */
     lowConfidence?: true;
+    /** The custom CLI(s) that returned the page, the best confidence among its sources (below 1 only) and the honest label. */
+    via?: string;
+    confidence?: number;
+    tag?: string;
 }
 export type GapReason = 'no_candidates' | 'no_page_content' | 'weak_support' | 'budget';
 export interface Gap {
@@ -230,7 +262,12 @@ export interface EvidencePack {
         title?: string;
         snippet?: string;
         publishedAt?: string;
+        rerankScore?: number;
+        authority?: number;
         lowConfidence?: true;
+        via?: string;
+        confidence?: number;
+        tag?: string;
     }[];
     engine: string;
     enginesTried: string[];