dsh-web-search-pro 0.2.0 → 0.2.3

package/lib/types/default-chain.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The default engine order of a plain search, as a pure function: the router uses it to decide the order, and the settings
+ * card's status summary uses the same code to show the chain a search would try first, so the two cannot disagree.
+ * No imports: the client bundle includes this file.
+ * @module web-search-pro/default-chain
+ */
+/** The default `engines` list. A list equal to it is "not customised": the default rule for common ("常用") sources applies to it. */
+export declare const DEFAULT_ENGINES: readonly string[];
+export interface ChainInput {
+    /** The configured `engines` (route ids). */
+    engines: readonly string[];
+    /** `sources.priority` (route ids). */
+    priority?: readonly string[];
+    /** `sources.disabled` (route ids). */
+    disabled?: readonly string[];
+    /** Common ("常用") sources whose key resolves, best first. */
+    commonReady?: readonly string[];
+    /** `evidence.sourcePolicy === 'anonymous-only'`: a paid common source is never added. */
+    anonymousOnly?: boolean;
+}
+/**
+ * Order of the configured chain: `sources.disabled` removed, `sources.priority` ids that are in the list first, then the common
+ * sources whose key resolves (only while `engines` is the default list; a list the user wrote keeps its order and the position
+ * it gave a common source), then the rest. Throws when everything is disabled.
+ */
+export declare function effectiveChain(input: ChainInput): string[];
+/** One reason the effective chain differs from the `engines` list as written. */
+export type ChainReason = 
+/** `sources.disabled` removed these from the list. */
+{
+    kind: 'disabled';
+    ids: string[];
+}
+/** `sources.priority` moved these to the front. */
+ | {
+    kind: 'priority';
+    ids: string[];
+}
+/** The default rule put these ready common ("常用") sources in front of the list. */
+ | {
+    kind: 'common';
+    ids: string[];
+}
+/** `evidence.sourcePolicy: anonymous-only` kept these ready common sources out (they need a key). */
+ | {
+    kind: 'anonymous-only';
+    ids: string[];
+}
+/** The list is the user's own, so these ready common sources are not added (they keep their place only if the list names them). */
+ | {
+    kind: 'own-list';
+    ids: string[];
+};
+export interface ChainExplanation {
+    /** What a plain search would try, in order ({@link effectiveChain}); undefined when everything is disabled. */
+    chain: string[] | undefined;
+    reasons: ChainReason[];
+}
+/**
+ * {@link effectiveChain} plus why it differs from the list: the preview of the settings card says it in one sentence per reason, so
+ * a person who sees `deepseek` first in a list that does not begin with it knows which rule did that. Same inputs, same rule.
+ */
+export declare function explainChain(input: ChainInput): ChainExplanation;

package/lib/types/deps.d.ts

@@ -1,10 +1,10 @@
 /**
  * External dependency detection and install for the CLI/platform backends.
- * Most backends shell out to tools installed outside DSH (bili, yt-dlp,
- * twitter, and mcporter). This module reports which are present and how to
- * install them; the sources.deps / sources.install actions expose it to the model. Each entry probes
- * the command the backend actually executes (the twitter backend runs
- * `twitter`, so finding `agent-reach` on PATH says nothing about it).
+ * Backends shell out to tools installed outside DSH: the built-in CLI adapter specs (bili, yt-dlp, twitter, xhs, zhihu,
+ * rdt, omnireach, gh, wx-search-cli, tanso, the standalone opencli) plus the user's own `cliAdapters`, and mcporter. This
+ * module reports which are present, whether the command on PATH really has the contract the adapter needs (a same-named
+ * program with another contract is `incompatible`, never `detected`), and how to install them; the sources.deps /
+ * sources.install actions expose it to the model. Probes are local, cached with a TTL, and never run a search or a login.
  *
  * Install is intentionally a MODEL-FACING TOOL, not a browser settings button:
  * a browser button running winget/pip/npm would be arbitrary command execution
@@ -12,6 +12,9 @@
  * tool-permission/approval pipeline. The card points at this tool instead.
  * @module web-search-pro/deps
  */
+import { BILI_CLI_INSTALLS, BILI_CLI_REVISION, BILI_CLI_SOURCE, BILI_CLI_VERSION, TWITTER_CLI_INSTALLS } from './cli/builtin-specs.ts';
+import { type CliInstallation } from './cli/probe.ts';
+export { BILI_CLI_INSTALLS, BILI_CLI_REVISION, BILI_CLI_SOURCE, BILI_CLI_VERSION, TWITTER_CLI_INSTALLS };
 export interface DepInfo {
     id: string;
     label: string;
@@ -27,6 +30,10 @@ export interface DepInfo {
     version?: string;
     /** Why a command found on PATH is not compatible. */
     diagnostic?: string;
+    /** `missing` (not on PATH), `detected` (present with the contract the adapter needs), `incompatible` (present, wrong contract or too old). */
+    installation?: CliInstallation;
+    /** How far the adapter was checked against the real tool: `live`, `contract-only`, `docs-only` (absent: user-defined or not a CLI adapter). */
+    verification?: string;
     /** No backend of this plugin executes it; it is only an install helper, so its absence is not a gap. */
     optional?: boolean;
     installs: {
@@ -34,31 +41,26 @@ export interface DepInfo {
         command: string;
     }[];
 }
-export declare const BILI_CLI_VERSION = "0.6.2";
-export declare const BILI_CLI_REVISION = "489607468f967e0e11f3cdff6efc022d011e982a";
-export declare const BILI_CLI_SOURCE = "git+https://github.com/public-clis/bilibili-cli@489607468f967e0e11f3cdff6efc022d011e982a";
-export declare const BILI_CLI_INSTALLS: {
-    installer: string;
-    command: string;
-}[];
-interface DepProbeResult {
+interface ProbeResult {
     available: boolean;
     version?: string;
     diagnostic?: string;
 }
 /** Validate the public-clis bili command rather than trusting an ambiguous package name. */
-export declare function evaluateBiliCli(versionOutput: string, searchHelpOutput: string): DepProbeResult;
+export declare function evaluateBiliCli(versionOutput: string, searchHelpOutput: string): ProbeResult;
 /**
  * The twitter backend runs `twitter search <query> -n N` (twitter-cli). Another program that happens to be
  * called `twitter` must not pass: require a successful `search --help` that actually describes a search command.
  */
-export declare function evaluateTwitterCli(searchHelpOutput: string, exitCode: number): DepProbeResult;
-export declare const TWITTER_CLI_INSTALLS: {
-    installer: string;
-    command: string;
-}[];
-/** Detect all backends. */
-export declare function detectDeps(): Promise<DepInfo[]>;
+export declare function evaluateTwitterCli(searchHelpOutput: string, exitCode: number): ProbeResult;
+export declare const DEP_IDS: readonly string[];
+/** Detect every dependency: the spec-backed CLIs through their cached contract probes, the rest by presence on PATH. */
+export declare function detectDeps(options?: {
+    config?: {
+        cliAdapters?: unknown;
+    };
+    force?: boolean;
+}): Promise<DepInfo[]>;
 /** Run the install command for one backend + installer. */
 export declare function installDep(id: string, installer: string): Promise<{
     code: number;
@@ -66,5 +68,5 @@ export declare function installDep(id: string, installer: string): Promise<{
     stderr: string;
     timedOut: boolean;
 }>;
-export declare const DEP_IDS: string[];
-export {};
+/** The installer `sources.install` uses when none is named: the first one listed for the dependency. */
+export declare function defaultInstaller(id: string): string;

package/lib/types/engine-error.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The error every search engine and CLI adapter throws. Leaf module (no imports), so both engines.ts and the CLI adapter
+ * layer can extend it without an import cycle.
+ * @module web-search-pro/engine-error
+ */
+export declare class EngineError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number | undefined;
+    /** `retryAfterMs`: the service's own wait hint (Retry-After); the router uses it as the cooldown. */
+    constructor(message: string, code: string, retryable?: boolean, retryAfterMs?: number | undefined);
+}

package/lib/types/engines.d.ts

@@ -10,18 +10,44 @@ import type { BrowserService } from './browser-service.ts';
 import { type BrowserMethod } from './browser-access.ts';
 import type { CustomPlatformSpec } from './config.ts';
 import { type ExaSearchRequest } from './exa-client.ts';
+import { EngineError } from './engine-error.ts';
+/**
+ * A source row as an engine returns it: the host's `WebSearchSource` plus the provider's own quality signals, when it has any
+ * (DeepSeek Search: `rerank_score` 0..3 and `authority` 0..4). They travel with the row as source metadata and are one small
+ * fusion signal (pipeline/fusion.ts); no engine is required to set them.
+ */
+export interface EngineSource extends WebSearchSource {
+    /** The provider's relevance / authority / freshness rank score, 0..3 (higher is better). */
+    readonly rerankScore?: number;
+    /** The provider's source-authority grade, 0..4 (unknown = absent). */
+    readonly authority?: number;
+    /** The user-defined CLI that returned the row (`custom-cli:echo`): set by the adapter, shown with the result. */
+    readonly via?: string;
+    /** The honest label of a user-defined source ("user-defined, not verified by the plugin"). */
+    readonly tag?: string;
+    /** The source's confidence (0..1), below 1 only: set by the router from the spec / `sources.confidence`, never by an engine. */
+    readonly confidence?: number;
+}
 export interface SearchOutcome {
     /** Provider-generated answer/summary text, when any. */
     content?: string;
-    sources: WebSearchSource[];
+    sources: EngineSource[];
     /** Id of the concrete backend that answered (a platform provider with a fallback chain names the leg that ran). */
     via?: string;
+    /** The backend id of the platform chain that answered (`bili`, `browser-opencli`), for display and history. */
+    backend?: string;
+    /** Short notes for the caller: backends skipped on the way, results dropped. */
+    notes?: string[];
 }
 export interface Engine {
     id: string;
     label: string;
+    /** Backend id in a platform chain (`xhs`, `browser-opencli`); absent for plain engines. */
+    backend?: string;
     /** Cheap local availability check; must not do network I/O. */
     available(): boolean;
+    /** Why `available()` is false, when the engine knows (a platform chain quotes it in its fall-through note instead of "unavailable"). */
+    unavailableReason?(): string | undefined;
     /** Browser-service method this engine depends on (dsh-browser is optional). */
     needsBrowser?: BrowserMethod;
     search(query: string, count: number, signal?: AbortSignal, options?: EngineSearchOptions): Promise<SearchOutcome>;
@@ -34,6 +60,8 @@ export interface EngineSearchOptions {
         include?: string[];
         exclude?: string[];
     };
+    /** The caller's original question or need (DeepSeek Search `ori_question`, cut to 128 characters by the engine); absent = none sent. */
+    originalQuestion?: string;
     /** Lower bound of the publication date (ISO 8601), compiled from a hard time_window; the engine maps it to its native filter. */
     since?: string;
     /** Domain lists compiled from hard site / exclude_site constraints (keyed sources that take them as request fields). */
@@ -50,13 +78,7 @@ export interface EngineSearchOptions {
     /** Feed URL of the `rss` platform (it has no fixed endpoint). */
     url?: string;
 }
-export declare class EngineError extends Error {
-    readonly code: string;
-    readonly retryable: boolean;
-    readonly retryAfterMs?: number | undefined;
-    /** `retryAfterMs`: the service's own wait hint (Retry-After); the router uses it as the cooldown. */
-    constructor(message: string, code: string, retryable?: boolean, retryAfterMs?: number | undefined);
-}
+export { EngineError };
 /** One metered request of a non-model provider (Bocha search): counted in the usage ledger, tokens n/a, price unknown. */
 export interface UsageRecorder {
     record(entry: {
@@ -80,6 +102,8 @@ export interface EngineDeps {
     usage?: UsageRecorder;
     /** Test seam: replaces the global fetch of API clients that accept one. */
     fetchImpl?: typeof fetch;
+    /** Test seam: waits between retries of the engines that retry (DeepSeek); resolves early on abort. Default: a real timer. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
     /** Test seam: replaces the DNS lookup of the SSRF check. */
     lookup?: (hostname: string) => Promise<{
         address: string;
@@ -99,6 +123,11 @@ export interface EngineDeps {
     anysearchApiKey?: string;
     /** GitHub API token (config githubToken / $GITHUB_TOKEN / $GH_TOKEN). */
     githubToken?: string;
+    /**
+     * Credential variables of the CLI adapters by the name the tool reads (`TWITTER_AUTH_TOKEN`, `TWITTER_CT0`), resolved by the router:
+     * config literal -> credentials ref -> process environment. Handed to a command only through its environment, never in argv.
+     */
+    cliEnv?: Readonly<Record<string, string>>;
     enableCli: boolean;
     opencliEnabled: boolean;
     agentReachEnabled: boolean;
@@ -140,13 +169,19 @@ export declare function githubEngine(deps: EngineDeps): Engine;
 export declare function githubCodeEngine(deps: EngineDeps): Engine;
 export declare function githubIssuesEngine(deps: EngineDeps): Engine;
 export declare function bilibiliEngine(deps: EngineDeps): Engine;
-/** Exact argv contract supported by public-clis/bilibili-cli v0.6.2+. */
+/** Exact argv contract supported by public-clis/bilibili-cli v0.6.2+ (the `bili` spec). */
 export declare function biliSearchArgs(query: string, count: number): string[];
-/** Parse and validate bili-cli's versioned JSON envelope. */
+/** Parse and validate bili-cli's versioned JSON envelope (the `bili` spec). */
 export declare function parseBilibiliSearchOutput(output: string): WebSearchSource[];
 export declare function v2exEngine(allowProxyFakeIp?: boolean): Engine;
 export declare function youtubeEngine(deps: EngineDeps, cli?: typeof runCli): Engine;
+/** Platforms the dsh-browser OpenCLI bridge has a site adapter for (platform -> adapter name). */
+export declare const OPENCLI_PLATFORMS: Record<string, string>;
 export declare function opencliEngine(platform: string, deps: EngineDeps): Engine;
+/**
+ * The legacy `agentreach-twitter` engine, now a thin view of the `twitter` CLI spec (the platform chain uses the spec
+ * directly; this keeps the old engine id and its install message). Credentials are checked by `available()`.
+ */
 export declare function agentReachEngine(platform: string, deps: EngineDeps): Engine;
 export declare function arxivEngine(allowProxyFakeIp?: boolean): Engine;
 export declare function pubmedEngine(allowProxyFakeIp?: boolean): Engine;

package/lib/types/fetch.d.ts

@@ -8,7 +8,8 @@ import type { ResolvedConfig } from './config.ts';
 import type { BrowserService } from './browser-service.ts';
 import { type BrowserGetter } from './browser-access.ts';
 import type { ExtractRule } from './extract.ts';
-export type FetchMode = 'auto' | 'jina' | 'http' | 'playwright';
+import { type DeepSeekFetchAccess } from './providers/deepseek.ts';
+export type FetchMode = 'auto' | 'jina' | 'http' | 'playwright' | 'deepseek';
 export interface FetchOptions {
     mode: FetchMode;
     signal: AbortSignal | undefined;
@@ -63,7 +64,7 @@ export declare function detectShellPage(text: string): boolean;
 export type PageClass = 'content' | 'shell' | 'login_wall' | 'captcha' | 'js_shell' | 'error';
 /** One backend attempt of a fetch, in order (recorded in the result and in the stored fetch detail). */
 export interface FetchAttempt {
-    source: 'jina' | 'http' | 'playwright';
+    source: 'jina' | 'http' | 'playwright' | 'deepseek';
     class: PageClass;
     chars?: number;
     detail?: string;
@@ -82,14 +83,20 @@ export declare function classifyPage(text: string, meta?: {
 export declare function normalizeUrl(raw: string): string;
 /** All rules: user (DB) first, then built-ins; user rules win on ties. */
 export declare function mergedRules(store: Store): ExtractRule[];
+/**
+ * The DeepSeek Fetch API access for a call: key, endpoint, ledger. Resolved per call by the router (settings literal -> DSH credentials ->
+ * process environment); undefined = no key. Test seams (`fetchImpl`, `lookup`, `sleep`) ride along on the returned object.
+ */
+export type DeepSeekFetchAccessProvider = () => Promise<Pick<DeepSeekFetchAccess, 'apiKey' | 'baseUrl' | 'usage' | 'fetchImpl' | 'lookup' | 'sleep' | 'allowProxyFakeIp'> | undefined>;
 export declare class FetchService {
     private readonly store;
     private readonly config;
+    private readonly deepseek?;
     private readonly memory;
     /** In-flight de-duplication of identical non-fresh fetches (C3). */
     private readonly flights;
     private readonly getBrowser;
-    constructor(store: Store, config: ResolvedConfig | (() => ResolvedConfig), browser?: BrowserService | BrowserGetter);
+    constructor(store: Store, config: ResolvedConfig | (() => ResolvedConfig), browser?: BrowserService | BrowserGetter, deepseek?: DeepSeekFetchAccessProvider | undefined);
     private cfg;
     /** True when the optional browser can render right now (enabled in config and the service has render()). */
     private canRender;
@@ -98,5 +105,7 @@ export declare class FetchService {
     private runFetch;
     private fetchJina;
     private fetchHttp;
+    /** One page through the DeepSeek Fetch API. 403 / 404 are DeepSeek's own verdicts (see `DeepSeekFetchError`), never the target page's status. */
+    private fetchDeepSeek;
     private fetchPlaywright;
 }