dsh-web-search-pro 0.2.0 → 0.2.3

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,10 +13,19 @@ 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 {
     providerId: string;
+    /** The backend of a platform chain that answered (display only). */
+    backend?: string;
     query: string;
     sources: readonly ProviderSource[];
 }
@@ -27,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

@@ -43,7 +43,9 @@ export interface ProviderCall {
 }
 export type ProviderOutcome = {
     state: 'ok';
-    sources: readonly ProviderSource[];
+    sources: readonly ProviderSource[]; /** The backend of a platform chain that answered. */
+    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[];

package/lib/types/providers/deepseek.d.ts

@@ -0,0 +1,130 @@
+/**
+ * DeepSeek Search and Fetch API (https://api-docs.deepseek.com/guides/search/, online since 2026-10-17): the "常用" (common) source of
+ * this plugin. Contract: `POST {base}/search` and `POST {base}/fetch`, `Authorization: Bearer <DeepSeek API key>`, JSON; the base is
+ * `https://api.deepseek.com/v1/tools`.
+ *
+ *  - Search request: `query` (1-128 characters, with the operators `site:` `-site:` `-term` `"phrase"` `lang:` `after:` `before:`),
+ *    `count` (1-50, default 10), `ori_question` (optional, the caller's original question, at most 128), `localization` (not sent),
+ *    `need_content` (default false: `content` stays empty, we never ask for it). Response: `results[]` of `rerank_score` (0-3),
+ *    `title`, `url`, `snippet` (about 100-200 characters, for display), `summary` (about 600-800 characters, written for a model),
+ *    `content`, `site_name`, `site_icon`, `date` (RFC 3339 or null), `authority` (0-4, -1 unknown). An empty array is "no results".
+ *  - Fetch request `url` (at most 8192 characters, http/https, no credentials); response `title` and `content` (Markdown).
+ *  - Errors are OpenAI-shaped `{ error: { message, type, param, code } }`: 400, 401, 402 (balance), 403 (Fetch refused by the security
+ *    policy), 404 (Fetch could not get usable content), 408, 413, 429, 500, 504. Both APIs are read-only: 408 / 429 / 5xx are retried
+ *    after a wait, every other 4xx is not.
+ *  - Billing: $0.75 per 1,000 SUCCESSFUL requests, for each endpoint. Only a 200 that yields a result is billed (empty results, failures
+ *    and timeouts are not), and `count` does not change the price. Calls made through DeepSeek Harness / Claude Code / Codex server-side
+ *    tools are free until 2026-11-01 00:00 Beijing time; the docs do not say whether a plugin calling the API directly is inside that
+ *    window, so this plugin treats every call as billed. Limits per account: Search 100 QPS, Fetch 25 QPS plus a per-domain limit.
+ *
+ * Field mapping: `summary` (else `snippet`) -> `snippet` (the long excerpt the evidence pipeline gates and scores on), `date` ->
+ * `publishedAt`, `rerank_score` -> `rerankScore`, `authority` -> `authority` (source metadata; one small fusion signal, fusion.ts).
+ * The host's own `deepseek-search-api` provider maps only snippet and date.
+ * @module web-search-pro/providers/deepseek
+ */
+import { EngineError, type Engine, type EngineDeps, type EngineSource } from '../engines.ts';
+import { type ProviderResponse } from './http.ts';
+import type { ProviderAdapter, ProviderDescriptor } from './registry.ts';
+export declare const DEEPSEEK_ROUTE_ID = "deepseek";
+export declare const DEEPSEEK_LABEL = "DeepSeek Search";
+export declare const DEEPSEEK_DEFAULT_BASE = "https://api.deepseek.com/v1/tools";
+export declare const DEEPSEEK_SEARCH_PATH = "/search";
+export declare const DEEPSEEK_FETCH_PATH = "/fetch";
+export declare const DEEPSEEK_KEY_ENV = "DEEPSEEK_API_KEY";
+/** Longest `query` / `ori_question` the API takes, in characters. */
+export declare const DEEPSEEK_QUERY_CHARS = 128;
+export declare const DEEPSEEK_MAX_COUNT = 50;
+export declare const DEEPSEEK_DEFAULT_COUNT = 10;
+/** The long excerpt kept per result (the API's `summary` is about 600-800 characters). */
+export declare const DEEPSEEK_SNIPPET_CHARS = 1000;
+/** Longest URL the Fetch API takes. */
+export declare const DEEPSEEK_FETCH_URL_CHARS = 8192;
+/** Usage-ledger provider names: requests counted, tokens n/a, price unknown to the plugin. */
+export declare const DEEPSEEK_USAGE_SEARCH = "deepseek-search";
+export declare const DEEPSEEK_USAGE_FETCH = "deepseek-fetch";
+/** One try plus at most two retries of a 408 / 429 / 5xx answer. */
+export declare const DEEPSEEK_MAX_ATTEMPTS = 3;
+export declare const DEEPSEEK_RETRY_BASE_MS = 800;
+/** A wait longer than this (a `Retry-After` of a minute) is not slept through: the failure carries it as the cooldown instead. */
+export declare const DEEPSEEK_RETRY_WAIT_CAP_MS = 8000;
+export interface FittedQuery {
+    query: string;
+    cut: boolean;
+    from: number;
+}
+/**
+ * The query as the API takes it: whitespace collapsed, at most 128 characters. A longer query keeps every operator token (a
+ * `site:` restriction or an exclusion is what the caller asked for) and `OR` between site operators, and loses the tail of the free
+ * text, at a word boundary when it has words and by character when it does not (Chinese). The caller says so in the result notes.
+ */
+export declare function fitQuery(raw: string): FittedQuery;
+/** `ori_question`: whitespace collapsed and cut to 128 characters; undefined when nothing remains or it adds nothing to the query. */
+export declare function originalQuestion(raw: string | undefined, query: string): string | undefined;
+export interface DeepSeekSearchBody {
+    query: string;
+    count: number;
+    need_content: false;
+    ori_question?: string;
+}
+export declare function deepseekSearchBody(query: string, count: number, question?: string): DeepSeekSearchBody;
+/** Map `results[]`: summary (else snippet) as the excerpt, date -> publishedAt, rerank_score / authority as metadata. Rows without an http(s) URL are dropped. */
+export declare function mapDeepSeekResults(results: readonly unknown[], count: number): EngineSource[];
+/** Parse a 2xx Search body; an empty `results` array is ENGINE_EMPTY (the service works, nothing matched, and nothing was billed). */
+export declare function parseDeepSeekSearch(json: unknown, count: number): EngineSource[];
+/** Statuses the docs say to wait and retry: 408, 429 and 5xx. */
+export declare const isRetryableStatus: (status: number) => boolean;
+/**
+ * The error message of an OpenAI-shaped body, safe to show: the key (should it ever be echoed) and credential-looking values are
+ * redacted and the length is capped. The service's `request_id` (what DeepSeek support asks for) is returned apart, so a message can
+ * end with it instead of burying the cause.
+ */
+export declare function errorParts(json: unknown, key: string | undefined): {
+    text: string;
+    id?: string;
+};
+/** {@link errorParts} as one string: `message (request_id …)`. */
+export declare function detailOf(json: unknown, key: string | undefined): string;
+/**
+ * Status -> error contract for Search. 401 / 403 are `ENGINE_AUTH`; 402 is `ENGINE_QUOTA` with the balance wording (never retried,
+ * no cooldown: waiting does not refill a balance); 429 is `ENGINE_RATE_LIMIT` carrying `Retry-After`; 408 is a retryable
+ * `ENGINE_TIMEOUT`; 400 / 404 / 413 are bad requests (not retryable); 5xx is a retryable `ENGINE_ERROR`. Never contains the key.
+ */
+export declare function deepseekFailure(label: string, status: number, headers: Headers, json: unknown, key?: string): EngineError;
+/** Abort-aware wait. */
+export declare function defaultSleep(ms: number, signal?: AbortSignal): Promise<void>;
+type Transport = Pick<EngineDeps, 'allowProxyFakeIp' | 'fetchImpl' | 'lookup' | 'sleep'>;
+/** Wait before retry number `attempt` (1-based): the service's `Retry-After` when it gave one, else 0.8 s, 1.6 s. Undefined = not worth waiting (stop). */
+export declare function retryWaitMs(res: Pick<ProviderResponse, 'headers'>, attempt: number): number | undefined;
+/**
+ * One POST with the documented retry policy: a 408 / 429 / 5xx answer is retried after a wait (at most {@link DEEPSEEK_MAX_ATTEMPTS}
+ * tries in all, never longer than {@link DEEPSEEK_RETRY_WAIT_CAP_MS} per wait); every other answer is returned at once. Retries are
+ * safe: both APIs are read-only and failed requests are not billed. Returns the final response (which may still be an error).
+ */
+export declare function postWithRetry(label: string, url: string, key: string, body: unknown, transport: Transport, signal: AbortSignal | undefined): Promise<ProviderResponse>;
+export declare function deepseekEngine(deps: EngineDeps): Engine;
+/** A Fetch API failure. `code` names what DeepSeek did; none of them describes the TARGET page's own HTTP status. */
+export declare class DeepSeekFetchError extends Error {
+    readonly code: 'DEEPSEEK_FETCH_DENIED' | 'DEEPSEEK_FETCH_NO_CONTENT' | 'DEEPSEEK_FETCH_AUTH' | 'DEEPSEEK_FETCH_QUOTA' | 'DEEPSEEK_FETCH_RATE_LIMIT' | 'DEEPSEEK_FETCH_ERROR';
+    readonly retryable: boolean;
+    constructor(message: string, code: 'DEEPSEEK_FETCH_DENIED' | 'DEEPSEEK_FETCH_NO_CONTENT' | 'DEEPSEEK_FETCH_AUTH' | 'DEEPSEEK_FETCH_QUOTA' | 'DEEPSEEK_FETCH_RATE_LIMIT' | 'DEEPSEEK_FETCH_ERROR', retryable?: boolean);
+}
+/**
+ * Status -> error for Fetch. 403 and 404 are DeepSeek's own verdicts (security policy; no usable content), and the message opens by
+ * saying so: it is not the target page's HTTP status. The request id comes last.
+ */
+export declare function deepseekFetchFailure(status: number, headers: Headers, json: unknown, key?: string): DeepSeekFetchError;
+export interface DeepSeekFetchAccess extends Transport {
+    apiKey: string;
+    /** Endpoint base, default {@link DEEPSEEK_DEFAULT_BASE}. */
+    baseUrl?: string;
+    usage?: EngineDeps['usage'];
+}
+export interface DeepSeekPage {
+    title?: string;
+    text: string;
+}
+/** Read one page as Markdown through the Fetch API. Throws {@link DeepSeekFetchError} (or an EngineError for transport problems). */
+export declare function deepseekFetchPage(url: string, access: DeepSeekFetchAccess, signal?: AbortSignal): Promise<DeepSeekPage>;
+export declare const DEEPSEEK_DESCRIPTOR: ProviderDescriptor;
+export declare const deepseekAdapter: ProviderAdapter;
+export {};

package/lib/types/providers/http.d.ts

@@ -27,7 +27,8 @@ export interface ProviderResponse {
     text: string;
 }
 export interface ProviderRequest {
-    deps: EngineDeps;
+    /** Only the transport settings are read (SSRF-safe HTTP path and the test seams). */
+    deps: Pick<EngineDeps, 'allowProxyFakeIp' | 'fetchImpl' | 'lookup'>;
     signal?: AbortSignal | undefined;
     headers?: Record<string, string>;
     method?: 'GET' | 'POST';

package/lib/types/providers/keyed-meta.d.ts

@@ -6,3 +6,8 @@
 /** Default environment variable names of each keyed source's API key, first one preferred (route id -> names). */
 export declare const KEYED_SOURCE_ENVS: Readonly<Record<string, readonly string[]>>;
 export declare const KEYED_SOURCE_IDS: readonly string[];
+/**
+ * The "常用" (common) sources: a test pins this list to the registry descriptors that set `common: true`. Data only, for the
+ * settings panel (client bundle), which cannot import the descriptors.
+ */
+export declare const COMMON_SOURCE_IDS: readonly string[];

package/lib/types/providers/platforms.d.ts

@@ -1,8 +1,8 @@
 /**
  * Platform search backends as registry providers (dev-plan M8b): one provider per site or community, with the same
  * descriptor + adapter shape as the web engines, so a platform is planned, probed, cooled down, singleflighted,
- * persisted and reported exactly like any other source. A platform with several backends (twitter: OpenCLI, then
- * twitter-cli) is ONE provider with an internal ordered chain. User `customPlatforms` become providers too
+ * persisted and reported exactly like any other source. A platform with several backends (twitter: twitter-cli, standalone
+ * OpenCLI, dsh-browser OpenCLI) is ONE provider with an internal ordered chain, resolved by src/cli/chain.ts (dev-plan M12). User `customPlatforms` become providers too
  * ({@link customPlatformAdapter}); the router registers and unregisters them as the settings change.
  * The legacy platform ids that already were web providers (github, bilibili, v2ex, youtube, arxiv, pubmed) are
  * declared in builtin.ts and carry `kind: 'platform'` as well.
@@ -10,9 +10,15 @@
  */
 import { type Engine } from '../engines.ts';
 import type { CustomPlatformSpec } from '../config.ts';
-import type { ProviderAdapter } from './registry.ts';
+import { type CliAdapterSpec } from '../cli/spec.ts';
+import type { ProviderAdapter, ProviderDescriptor } from './registry.ts';
 /** Chain `engines` into one provider: the first available leg that answers wins; empty and failing legs fall through in order. */
 export declare function chainEngine(id: string, label: string, chain: readonly Engine[]): Engine;
+/**
+ * A platform provider whose backends are an ordered chain (`resolveChain`): the engine is the chain, the local probe is the
+ * readiness of every leg (cached contract probes, no search, no login), and `chain` reports each leg for `sources.status`.
+ */
+export declare function chainProvider(platformId: string, d: ProviderDescriptor): ProviderAdapter;
 export declare const platformAdapters: readonly ProviderAdapter[];
 /** Registry id of a custom platform: its key when that is a valid id, else a stable hash of it (the key stays the route alias). */
 export declare function customProviderId(key: string): string;
@@ -23,3 +29,9 @@ export declare function customKeyProblem(key: string): string | undefined;
  * reaches the next call even before the router re-registers the provider.
  */
 export declare function customPlatformAdapter(key: string, spec: CustomPlatformSpec): ProviderAdapter;
+/** Registry id and route id of a user-defined CLI adapter: `custom-cli:<id>` (also its backend id in `platformBackends`). */
+export declare const customCliProviderId: (id: string) => string;
+/** A user-defined CLI adapter as a platform provider whose chain is the adapter itself (an edit of `platformBackends` can still reorder it). */
+export declare function customCliAdapter(id: string, spec: CliAdapterSpec): ProviderAdapter;
+/** A user spec as validated for registration: the problem text, or undefined when it can be registered. */
+export declare function customCliProblem(id: string, raw: unknown): string | undefined;