dsh-web-search-pro 0.2.0 → 0.2.1

package/lib/types/cli/spec.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Declarative CLI adapter spec (dev-plan M12): what a standalone command-line tool is, which of its commands the plugin
+ * may run, and how its output maps to search sources. Pure data plus validation, no Node imports, so the settings card
+ * (client bundle) validates `cliAdapters` with the very function the server uses.
+ *
+ * The read-only guarantee lives here and applies to built-in and user-defined specs alike:
+ *  - argv is an array of tokens, never a shell string (the runner spawns without a shell);
+ *  - a spec declares `allowedSubcommands`, and every command word its argv uses (the leading literal tokens before the
+ *    first flag or placeholder) must be in that list;
+ *  - no command word, declared subcommand or flag may match the global deny-list (login, post, delete*, like, ...,
+ *    and the flags that make a CLI read browser cookies or carry secrets in argv).
+ * @module web-search-pro/cli/spec
+ */
+export declare const OUTPUT_FORMATS: readonly ["json", "ndjson", "yaml", "text"];
+export type OutputFormat = typeof OUTPUT_FORMATS[number];
+/** How far a spec has been checked against the real tool (recorded in the spec and shown in `sources.status`). */
+export declare const CLI_VERIFICATIONS: readonly ["live", "contract-only", "docs-only"];
+export type CliVerification = typeof CLI_VERIFICATIONS[number];
+export declare const CLI_ERROR_CODES: readonly ["CLI_NOT_FOUND", "CLI_CONTRACT_MISMATCH", "CLI_NOT_LOGGED_IN", "ENGINE_EMPTY", "CLI_FAILED"];
+export type CliErrorCode = typeof CLI_ERROR_CODES[number];
+/** One piece of a joined field: a path, optionally with text put before / after the value. */
+export type JoinPart = string | {
+    path: string;
+    prefix?: string;
+    suffix?: string;
+};
+/** `{ template }` fills `{path}` placeholders from the item and yields nothing when one is empty; `when` makes it apply to one kind of item. */
+export interface TemplateSource {
+    template: string;
+    when?: {
+        path: string;
+        equals: string | number | boolean;
+    };
+}
+/**
+ * Where a field of a source comes from, for one parsed item:
+ *  - a dotted path (`data.title`, `items.0.url`);
+ *  - a list of paths and templates: the first non-empty one wins;
+ *  - `{ template }`: `{path}` placeholders over the item, dropped when any of them is empty;
+ *  - `{ join }`: the non-empty parts joined with `sep` (default ` | `);
+ *  - `{ epoch }`: a Unix timestamp (seconds) as an ISO date; `{ date }`: the date part (first 10 characters) of an ISO timestamp.
+ */
+export type FieldSource = string | readonly (string | TemplateSource)[] | TemplateSource | {
+    join: readonly JoinPart[];
+    sep?: string;
+} | {
+    epoch: string;
+} | {
+    date: string;
+};
+export interface CliOutputSpec {
+    format: OutputFormat;
+    /** json / yaml: dotted path of the item array; absent = the root array, else the first array-valued property. */
+    itemsPath?: string;
+    /** json / yaml: every entry must hold, else the output is a failure (a versioned envelope's `ok` and `schema_version`). */
+    expect?: readonly {
+        path: string;
+        equals: string | number | boolean;
+    }[];
+    /** Paths of the tool's own error text, read when `expect` fails (first non-empty one). */
+    errorPaths?: readonly string[];
+    /** text: how a line becomes an item (`tsv`: tab separated columns; `url-lines`: lines holding a URL, `url` + `title`). */
+    lines?: {
+        mode: 'tsv';
+        columns: readonly string[];
+    } | {
+        mode: 'url-lines';
+    };
+    fields: {
+        url: FieldSource;
+        title?: FieldSource;
+        snippet?: FieldSource;
+        publishedAt?: FieldSource;
+    };
+    /** Strip HTML tags from title and snippet. */
+    stripTags?: boolean;
+    /** Values read as "empty" (`None`). */
+    emptyValues?: readonly string[];
+    /** Longest snippet kept (default 400). */
+    snippetMax?: number;
+    /** Longest title kept (default 300). */
+    titleMax?: number;
+    /** Drop items without a title (a line that is not a result). */
+    requireTitle?: boolean;
+}
+export interface CliSearchSpec {
+    /** Arguments after the binary. `{query}` and `{count}` are the placeholders; a token may embed one (`ytsearch{count}:{query}`). */
+    argv: readonly string[];
+    /** Largest `{count}` sent (the search call's count is clamped to 1..maxCount). */
+    maxCount?: number;
+    output: CliOutputSpec;
+    /** Case-insensitive fragments of the tool's output that mean "no results" rather than a failure. */
+    emptyWhen?: readonly string[];
+    /** Case-insensitive fragments of the tool's output that mean "not logged in" (maps to CLI_NOT_LOGGED_IN). */
+    notLoggedInPatterns?: readonly string[];
+}
+export interface CliProbeSpec {
+    versionArgs: readonly string[];
+    /** `X.Y.Z` the detected version must reach. */
+    minVersion?: string;
+    helpArgs: readonly string[];
+    /** Fragments the help output must contain: the subcommands and flags that prove this is the tool the spec describes. */
+    mustContain: readonly string[];
+}
+export interface CliLoginSpec {
+    /** What the user runs themselves (`xhs login`); never run by the plugin. */
+    command: string;
+    /** Home-relative files that exist once the user has logged in. Only their existence is checked, never their content. */
+    savedCredentialPaths?: readonly string[];
+    /** The tool reads the browser's cookies by itself when it has no saved login: then it is never run without one. */
+    readsBrowserCookiesWithoutLogin?: boolean;
+}
+export interface CliAdapterSpec {
+    id: string;
+    /** Command names tried in order on PATH. */
+    bins: readonly string[];
+    /** What the package is called, which can differ from the command (`pip install pyzhihu-cli` runs `zhihu`). */
+    packageNote: string;
+    /** Platform ids the spec can serve (`search.run platform=`); a user spec's platform is `custom-cli:<id>`. */
+    platforms: readonly string[];
+    probe: CliProbeSpec;
+    /** Every command word the argv templates use. */
+    allowedSubcommands: readonly string[];
+    search: CliSearchSpec;
+    /** Per-platform overrides of `search` (gh serves github, github-issues and github-code with different commands). */
+    searches?: Readonly<Record<string, CliSearchSpec>>;
+    read?: CliSearchSpec;
+    env: {
+        required?: readonly string[];
+        passthrough?: readonly string[];
+        set?: Readonly<Record<string, string>>;
+    };
+    needsLogin: boolean;
+    login?: CliLoginSpec;
+    timeoutMs: number;
+    maxOutputBytes: number;
+    /** Built-ins only: how far the spec was checked. User-defined specs carry none (they are unverified by definition). */
+    verification?: {
+        status: CliVerification;
+        version?: string;
+        date?: string;
+        note?: string;
+    };
+}
+/** Command words that write, log in, or change local or remote state. Matched exactly, or as `<word>-...` / `<word>_...`. */
+export declare const DENIED_SUBCOMMANDS: readonly string[];
+/** Command words denied by prefix alone (`delete`, `delete-note`, `deleteNote`, `remove...`). */
+export declare const DENIED_PREFIXES: readonly string[];
+/** Flags (without leading dashes) that read browser cookies or carry credentials in argv. */
+export declare const DENIED_FLAGS: readonly string[];
+/** The command words of an argv: leading literal tokens before the first flag or placeholder token. */
+export declare function commandWords(argv: readonly string[]): string[];
+/** Problems of one argv template with respect to the read-only guard (empty = fine). */
+export declare function argvProblems(argv: readonly string[], allowed: readonly string[], where: string): string[];
+export interface CliSpecValidation {
+    ok: boolean;
+    errors: string[];
+    spec?: CliAdapterSpec;
+}
+/**
+ * Validate one adapter spec (built-in or user-defined). Never throws. A user-defined spec (`origin: 'user'`) may not carry a
+ * `verification` (it is unverified by definition) and its `platforms` are ignored: it is registered as `custom-cli:<id>`.
+ */
+export declare function validateCliAdapterSpec(raw: unknown, origin?: 'builtin' | 'user'): CliSpecValidation;
+/** Validate the `cliAdapters` setting: the valid specs by id and the problems of the rest (an invalid entry is ignored, never fatal). */
+export declare function resolveCliAdapters(input: unknown): {
+    specs: Map<string, CliAdapterSpec>;
+    diagnostics: string[];
+};
+/** Search spec of one platform: the platform's override, else the default. */
+export declare function searchSpecFor(spec: CliAdapterSpec, platform: string): CliSearchSpec;
+export declare function compareVersions(left: string, right: string): number;
+/** The first `X.Y.Z` (or `X.Y`) in a tool's version output. */
+export declare function parseVersion(output: string): string | undefined;
+/** `platformBackends`: ordered backend ids per platform. Pure shape check; ids are checked against the known backends by the caller. */
+export declare function platformBackendProblems(input: unknown): string[];

package/lib/types/client/form-specs.d.ts

@@ -12,7 +12,7 @@
  */
 export type Json = Record<string, unknown>;
 /** Top-level config fields (one Host write each). */
-export type TopField = 'engines' | 'parallelEngines' | 'searchMaxResults' | 'timeoutMs' | 'fetchDefaultChars' | 'exaContentsPerUrlChars' | 'exaContentsTotalChars' | 'exaApiKeyEnv' | 'jinaApiKeyEnv' | 'githubTokenEnv' | 'bochaApiKeyEnv' | 'bochaBaseUrl' | 'bochaSummary' | 'searxngUrl' | 'openalexMailto' | 'enableCliBackends' | 'opencliEnabled' | 'agentReachEnabled' | 'providerId' | 'registerProvider' | 'toolSurface' | 'playwright' | 'ttlSeconds' | 'memoryCacheEntries' | 'rrfConstant' | 'freshnessBoost' | 'freshnessDays' | 'authorityBoost' | 'authorityDomains' | 'dbPath' | 'allowProxyFakeIp' | 'platformRules' | 'customPlatforms' | 'browserBindings' | 'verbose';
+export type TopField = 'engines' | 'parallelEngines' | 'searchMaxResults' | 'timeoutMs' | 'fetchDefaultChars' | 'exaContentsPerUrlChars' | 'exaContentsTotalChars' | 'exaApiKeyEnv' | 'jinaApiKeyEnv' | 'githubTokenEnv' | 'bochaApiKeyEnv' | 'bochaBaseUrl' | 'bochaSummary' | 'searxngUrl' | 'openalexMailto' | 'enableCliBackends' | 'opencliEnabled' | 'agentReachEnabled' | 'providerId' | 'registerProvider' | 'toolSurface' | 'playwright' | 'ttlSeconds' | 'memoryCacheEntries' | 'rrfConstant' | 'freshnessBoost' | 'freshnessDays' | 'authorityBoost' | 'authorityDomains' | 'dbPath' | 'allowProxyFakeIp' | 'platformRules' | 'customPlatforms' | 'browserBindings' | 'platformBackends' | 'cliAdapters' | 'verbose';
 /** Options inside `evidence` / `provider`, addressed by their dotted config path. */
 export type PathField = 'evidence.autoProviders' | 'evidence.sourcePolicy' | 'evidence.maxRounds' | 'evidence.maxQueries' | 'evidence.judge.mode' | 'evidence.hybridBorderline' | 'evidence.judge.provider' | 'evidence.maxJevQuestions' | 'evidence.judge.allowLlm' | 'evidence.judge.providers' | 'evidence.coverage.mode' | 'evidence.coverage.provider' | 'evidence.coverage.thresholds.weak' | 'evidence.coverage.thresholds.covered' | 'evidence.budget.perSearchInputTokens' | 'evidence.budget.dailyInputTokens' | 'evidence.budget.timezone' | 'evidence.budget.providers' | 'provider.evidence' | 'provider.deadlineMs' | 'sources.priority' | 'sources.disabled';
 /** One rubric override entry (`evidence.rubrics.<id>`) and one keyed-source field. */

package/lib/types/client/locales.d.ts

@@ -72,6 +72,10 @@ export declare const zh: {
     readonly platformRulesHint: "按平台设置 item/title/link/text 选择器。";
     readonly customPlatforms: "自定义平台（JSON）";
     readonly customPlatformsHint: "按平台定义搜索 URL 与选择器；登录态请通过浏览器绑定引用 AuthProfile。";
+    readonly platformBackends: "平台后端顺序（JSON）";
+    readonly platformBackendsHint: "每个平台依次尝试的后端，如 {\"xiaohongshu\": [\"xhs\", \"opencli\", \"browser-opencli\"]}。id：各 CLI（xhs、rdt、zhihu、twitter、bili、yt-dlp、omnireach、wx-search-cli、gh、tanso）、opencli、browser-opencli、browser-search、rest、custom-cli:<id>。缺失或未登录的后端会被跳过并说明原因。";
+    readonly cliAdapters: "自定义 CLI 适配（JSON）";
+    readonly cliAdaptersHint: "按 id 定义只读 CLI 适配规格（argv 数组、输出字段、探测契约、allowedSubcommands）。写操作和读取浏览器 Cookie 的参数会被拒绝；无效条目被忽略并在 sources.status 说明。登录始终由你自己运行 CLI。";
     readonly browserBindings: "浏览器绑定（JSON）";
     readonly browserBindingsHint: "把平台绑定到 dsh-browser AuthProfile 与 RulePack。";
     readonly verbose: "详细诊断日志";

package/lib/types/client/validators.d.ts

@@ -48,3 +48,9 @@ export declare function evidenceIssues(ev: Json): Issue[];
 export declare function sourcesIssues(sources: Json): Issue[];
 /** Rubric override ids in a settings object that name no built-in rubric (the server ignores them). */
 export declare function unknownRubricIds(rubrics: unknown): string[];
+/**
+ * Problems of the CLI adapter settings, from the server's own functions: `cliAdapters` entries the server would ignore
+ * (read-only guard, bad argv, secrets in env) and `platformBackends` that name an unknown platform or a backend that
+ * cannot serve it.
+ */
+export declare function cliIssues(platformBackends: unknown, cliAdapters: unknown): Issue[];

package/lib/types/config.d.ts

@@ -214,6 +214,13 @@ export interface Config {
     customPlatforms?: Record<string, CustomPlatformSpec>;
     /** Per-platform binding to domain-scoped dsh-browser auth/rule profiles. */
     browserBindings?: Record<string, BrowserBinding>;
+    /**
+     * Ordered backend chain per platform (dev-plan M12): backend ids such as `xhs`, `opencli` (standalone OpenCLI), `browser-opencli`
+     * (dsh-browser), `browser-search`, `rest`, `gh`, `custom-cli:<id>`. A platform not listed uses its default chain.
+     */
+    platformBackends?: Record<string, string[]>;
+    /** User-defined CLI adapter specs by id (validated like the built-in ones; invalid entries are ignored with a diagnostic in sources.status). */
+    cliAdapters?: Record<string, Record<string, unknown>>;
     /** Snapshot options. The browser runtime itself (channel/headless/storageStatePath) is provided by the dsh-browser plugin via the `browser` service. */
     playwright: {
         /** Gate the playwright fallback backend in read.fetch. */
@@ -313,6 +320,8 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         authProfile: z<string, string, "plain">;
         rulePack: z<string, string, "plain">;
     }>>, string>>, "volatile">;
+    platformBackends: z<NoInfer<import("@deepseek-ai/cosmokit").Dict<string[], string>>, NoInfer<import("@deepseek-ai/cosmokit").Dict<string[], string>>, "volatile">;
+    cliAdapters: z<NoInfer<import("@deepseek-ai/cosmokit").Dict<import("@deepseek-ai/cosmokit").Dict<any, string>, string>>, NoInfer<import("@deepseek-ai/cosmokit").Dict<import("@deepseek-ai/cosmokit").Dict<any, string>, string>>, "volatile">;
     playwright: z<Schemastery.ObjectS<NoInfer<{
         enabled: z<boolean, boolean, "volatile-defined">;
         snapshotDir: z<string, string, "plain">;
@@ -771,6 +780,8 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         authProfile: z<string, string, "plain">;
         rulePack: z<string, string, "plain">;
     }>>, string>>, "volatile">;
+    platformBackends: z<NoInfer<import("@deepseek-ai/cosmokit").Dict<string[], string>>, NoInfer<import("@deepseek-ai/cosmokit").Dict<string[], string>>, "volatile">;
+    cliAdapters: z<NoInfer<import("@deepseek-ai/cosmokit").Dict<import("@deepseek-ai/cosmokit").Dict<any, string>, string>>, NoInfer<import("@deepseek-ai/cosmokit").Dict<import("@deepseek-ai/cosmokit").Dict<any, string>, string>>, "volatile">;
     playwright: z<Schemastery.ObjectS<NoInfer<{
         enabled: z<boolean, boolean, "volatile-defined">;
         snapshotDir: z<string, string, "plain">;

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,16 +10,23 @@ 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';
 export interface SearchOutcome {
     /** Provider-generated answer/summary text, when any. */
     content?: string;
     sources: WebSearchSource[];
     /** 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;
     /** Browser-service method this engine depends on (dsh-browser is optional). */
@@ -50,13 +57,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: {
@@ -140,13 +141,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/index.d.ts

@@ -114,6 +114,8 @@ declare const _default: {
             authProfile: import("@deepseek-ai/schemastery").default<string, string, "plain">;
             rulePack: import("@deepseek-ai/schemastery").default<string, string, "plain">;
         }>>, string>>, "volatile">;
+        platformBackends: import("@deepseek-ai/schemastery").default<NoInfer<import("@deepseek-ai/cosmokit").Dict<string[], string>>, NoInfer<import("@deepseek-ai/cosmokit").Dict<string[], string>>, "volatile">;
+        cliAdapters: import("@deepseek-ai/schemastery").default<NoInfer<import("@deepseek-ai/cosmokit").Dict<import("@deepseek-ai/cosmokit").Dict<any, string>, string>>, NoInfer<import("@deepseek-ai/cosmokit").Dict<import("@deepseek-ai/cosmokit").Dict<any, string>, string>>, "volatile">;
         playwright: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<NoInfer<{
             enabled: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
             snapshotDir: import("@deepseek-ai/schemastery").default<string, string, "plain">;
@@ -572,6 +574,8 @@ declare const _default: {
             authProfile: import("@deepseek-ai/schemastery").default<string, string, "plain">;
             rulePack: import("@deepseek-ai/schemastery").default<string, string, "plain">;
         }>>, string>>, "volatile">;
+        platformBackends: import("@deepseek-ai/schemastery").default<NoInfer<import("@deepseek-ai/cosmokit").Dict<string[], string>>, NoInfer<import("@deepseek-ai/cosmokit").Dict<string[], string>>, "volatile">;
+        cliAdapters: import("@deepseek-ai/schemastery").default<NoInfer<import("@deepseek-ai/cosmokit").Dict<import("@deepseek-ai/cosmokit").Dict<any, string>, string>>, NoInfer<import("@deepseek-ai/cosmokit").Dict<import("@deepseek-ai/cosmokit").Dict<any, string>, string>>, "volatile">;
         playwright: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<NoInfer<{
             enabled: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
             snapshotDir: import("@deepseek-ai/schemastery").default<string, string, "plain">;

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

@@ -17,6 +17,8 @@ export interface ProviderSource {
 /** 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[];
 }

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

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

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;

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

@@ -17,6 +17,7 @@ import type { BrowserMethod } from '../browser-access.ts';
 import type { ResolvedConfig } from '../config.ts';
 import type { CompiledQuery } from '../pipeline/compile.ts';
 import type { TaskSpec } from '../pipeline/types.ts';
+import type { ChainReport } from '../cli/chain.ts';
 export type Operation = 'search';
 /** `web`: a general search engine; `platform`: one site or community (addressable as `search.run platform=<route id>`). */
 export type ProviderKind = 'web' | 'platform';
@@ -126,6 +127,8 @@ export interface ProviderAdapter {
     /** Local readiness: declared services, keys, commands. No network, no login, no model call. */
     probeLocal(env: ProbeEnv): Readiness | Promise<Readiness>;
     create(deps: EngineDeps, config: ResolvedConfig): Engine;
+    /** Platforms with an ordered backend chain (dev-plan M12): the state of every leg for `sources.status`. Local, no search. */
+    chain?(env: ProbeEnv): Promise<ChainReport>;
     /** Optional native query compilation (constraints -> provider options); absent = the core compiler's rules / plain query. */
     compile?(task: Pick<TaskSpec, 'goal' | 'query' | 'needs' | 'constraints'>, now: Date): CompiledQuery;
 }

package/lib/types/router.d.ts

@@ -8,6 +8,7 @@ import type { WebSearchRequest, WebSearchResult } from '@deepseek-ai/dsh-web';
 import type { Store } from './store.ts';
 import type { ResolvedConfig } from './config.ts';
 import { type EngineSearchOptions } from './engines.ts';
+import type { ChainEntryReport, ChainReport } from './cli/chain.ts';
 import { type CostTier, type ProviderDescriptor, type Readiness, type ProviderRegistry } from './providers/index.ts';
 import { type RequestBudgetState } from './pipeline/ledger.ts';
 import { LruCache } from './memory-cache.ts';
@@ -61,6 +62,8 @@ export interface RouterSearchResult {
     availableCount?: number;
     /** Human-readable explanation of why the router fell back to `engine` (P1-1). */
     fallbackNote?: string;
+    /** Platform search: the backend of its chain that answered (`bili`, `browser-opencli`). */
+    backend?: string;
 }
 /** One provider as `sources.status` reports it: the registry descriptor plus local readiness by dimension. */
 export interface ProviderReport {
@@ -92,7 +95,10 @@ export interface ProviderReport {
     budget?: RequestBudgetState;
     /** Not verified against the live service (descriptor.verification). */
     unverified?: boolean;
+    /** Platforms with an ordered backend chain: each backend, in order, with its readiness or the reason it is skipped. */
+    chain?: ChainEntryReport[];
     readiness: Readiness & {
+        state?: ChainReport['state'];
         lastLocalCheck: string;
         lastRemoteSuccess?: string;
         lastError?: string;
@@ -115,6 +121,9 @@ export declare class SearchRouter {
     private syncedRevision;
     /** Custom platforms (settings `customPlatforms`) this router registered: key -> spec signature + unregister. A key the registry refused stays here with its problem so it is not retried on every call. */
     private readonly custom;
+    /** User-defined CLI adapters (settings `cliAdapters`) this router registered as `custom-cli:<id>` platforms, with the diagnostics of the entries it ignored. */
+    private readonly customCli;
+    private cliAdapterDiagnostics;
     /** Latest local probe per route id (read by providerStatuses for the credential dimension). */
     private readonly readiness;
     /** Last real call per route id: feeds the health dimension (never inferred from a local probe). */
@@ -128,6 +137,10 @@ export declare class SearchRouter {
      * with a provider already registered is not registered (a user platform never replaces a built-in source); see {@link customPlatformProblems}.
      */
     private syncCustomPlatforms;
+    /** The same for `cliAdapters`: valid specs become `custom-cli:<id>` platforms; an invalid entry is ignored and reported. */
+    private syncCustomCliAdapters;
+    /** Configuration problems of the CLI adapter layer for `sources.status`: ignored `cliAdapters` entries and `platformBackends` that name nothing usable. */
+    cliAdapterProblems(): string[];
     /** Custom platforms the registry could not take (key clash, bad key), for `sources.status`. */
     customPlatformProblems(): string[];
     /** Unregister what this router put into the registry (plugin unload). */

package/lib/types/util.d.ts

@@ -76,6 +76,10 @@ export interface CliResult {
     stdout: string;
     stderr: string;
     timedOut: boolean;
+    /** The command could not be started at all (not on PATH, not executable). */
+    spawnFailed?: boolean;
+    /** Output went past `maxOutput` and the rest was dropped. */
+    truncated?: boolean;
 }
 /**
  * Run an external CLI (opencli / bili / yt-dlp / agent-reach / npm).
@@ -85,7 +89,8 @@ export interface CliResult {
 export declare function runCli(bin: string, args: string[], opts?: {
     timeoutMs?: number;
     signal: AbortSignal | undefined;
-    env?: Record<string, string>;
+    env?: Record<string, string>; /** Run with exactly this environment instead of extending the process environment (credentials are not inherited). */
+    cleanEnv?: boolean;
     cwd?: string;
     maxOutput?: number;
     outputEncoding?: string;

package/lib/util.js

@@ -199,6 +199,8 @@ export function runCli(bin, args, opts = { signal: undefined }) {
         let stderrBytes = 0;
         let child;
         let settled = false;
+        let spawnFailed = false;
+        let truncated = false;
         const finish = (code, timedOut) => {
             if (settled)
                 return;
@@ -210,7 +212,7 @@ export function runCli(bin, args, opts = { signal: undefined }) {
             const encoding = opts.outputEncoding ?? 'utf-8';
             const stdout = new TextDecoder(encoding).decode(Buffer.concat(stdoutChunks, stdoutBytes));
             const stderr = new TextDecoder(encoding).decode(Buffer.concat(stderrChunks, stderrBytes));
-            resolve({ code, stdout, stderr, timedOut });
+            resolve({ code, stdout, stderr, timedOut, ...spawnFailed ? { spawnFailed } : {}, ...truncated ? { truncated } : {} });
         };
         const timer = opts.timeoutMs ? setTimeout(() => finish(-1, true), opts.timeoutMs) : undefined;
         const onAbort = () => {
@@ -219,12 +221,14 @@ export function runCli(bin, args, opts = { signal: undefined }) {
             finish(-1, false);
         };
         child = crossSpawn(bin, args, {
-            env: { ...process.env, ...opts.env },
+            env: opts.cleanEnv ? { ...opts.env } : { ...process.env, ...opts.env },
             cwd: opts.cwd,
             windowsHide: process.platform === 'win32',
         });
         child.stdout?.on('data', (d) => {
             const remaining = maxOutput - stdoutBytes;
+            if (d.length > remaining)
+                truncated = true;
             if (remaining <= 0)
                 return;
             const chunk = d.length <= remaining ? d : d.subarray(0, remaining);
@@ -239,7 +243,7 @@ export function runCli(bin, args, opts = { signal: undefined }) {
             stderrChunks.push(chunk);
             stderrBytes += chunk.length;
         });
-        child.on('error', () => finish(-1, false));
+        child.on('error', () => { spawnFailed = true; finish(-1, false); });
         child.on('close', (code) => finish(code ?? -1, false));
         if (opts.signal?.aborted)
             onAbort();