dsh-web-search-pro 0.2.1 → 0.2.4

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/engines.d.ts

@@ -11,10 +11,27 @@ 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. */
@@ -29,6 +46,8 @@ export interface Engine {
     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>;
@@ -41,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). */
@@ -81,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;
@@ -100,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;

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;
 }

package/lib/types/fiber-config.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Where the live, resolved plugin configuration is read from.
+ *
+ * Cordis 4.0.x (DSH 0.2.0 / 0.2.1 lines): `fiber.config` is the RESOLVED object (schema defaults applied,
+ * `internal/config` hooks run) and there is no `effectiveConfig`. A volatile update swaps its fields in place.
+ *
+ * Cordis 4.1.x (DSH 0.2.2 line): `fiber.config` is the RAW input - no schema defaults, no hook results, and
+ * `undefined` for an entry that has no configuration. The resolved object handed to `apply` is published as
+ * `fiber.effectiveConfig` after every successful update. Reading `fiber.config` there skips defaults (nested
+ * ones included) and credential/hook resolution, which is why `?? {}` alone only fixes the crash.
+ *
+ * So: prefer `effectiveConfig`, fall back to `config` (4.0.x), and never hand `undefined` onward.
+ */
+export interface FiberConfigSource {
+    readonly effectiveConfig?: unknown;
+    readonly config?: unknown;
+}
+export declare function liveFiberConfig<T extends object>(fiber: FiberConfigSource | undefined): T;