dsh-web-search-pro 0.2.0 → 0.2.3

package/lib/types/actions/types.d.ts

@@ -16,7 +16,9 @@ import type { Store } from '../store.ts';
 import type { EvidenceService } from '../pipeline/service.ts';
 import type { BrowserGetter } from '../browser-access.ts';
 import type { ProviderState } from '../provider.ts';
-export declare const ACTION_GROUPS: readonly ["search", "read", "history", "sources", "rules", "cache"];
+import type { OverlayStore } from '../overlay.ts';
+import type { PendingRestart } from '../restart.ts';
+export declare const ACTION_GROUPS: readonly ["search", "read", "history", "sources", "rules", "cache", "config"];
 export type ActionGroup = typeof ACTION_GROUPS[number];
 /**
  * One parameter node. A subset of the Host's tool parameter DSL, so the same
@@ -51,8 +53,10 @@ export interface OutputSchema {
  * - `none`: runs directly.
  * - `install`: runs an external installer (`sources.install`).
  * - `local-write`: changes or deletes locally stored data (cache, history rows, extraction rules).
+ * - `config`: changes the agent overlay (search order, confidence, platform chains); runs without asking, denied in read-only mode.
+ * - `run-program`: lets the plugin run a local program (a custom CLI spec); always asks the user, denied in read-only mode.
  */
-export type ApprovalClass = 'none' | 'install' | 'local-write';
+export type ApprovalClass = 'none' | 'install' | 'local-write' | 'config' | 'run-program';
 export interface ActionExample {
     args: Record<string, unknown>;
     note?: string;
@@ -74,9 +78,15 @@ export interface ActionServices {
     providerState?: () => ProviderState;
     /** Default characters one text exit may return (config `fetchDefaultChars`). */
     outputCap: () => number;
+    /** The agent overlay (run-time settings an agent may change); absent where the host of the actions has none (`config.*` then reports it). */
+    overlay?: OverlayStore;
+    /** Settings changed in the configuration that the running plugin only reads at start-up. */
+    pendingRestart?: () => PendingRestart[];
 }
 export interface ActionContext extends ActionServices {
     signal: AbortSignal;
+    /** The session the call belongs to (recorded in the overlay audit trail); undefined outside a session. */
+    sessionId?: string;
 }
 export interface ActionDef {
     /** `group.action`. */
@@ -103,6 +113,12 @@ export interface ActionDef {
     unavailable?(env: {
         browserReady: boolean;
     }): string | undefined;
+    /**
+     * Checks beyond the parameter schema that need no state and run no side effect, one message per problem ([] when fine).
+     * Run on the schema-validated arguments by `runAction` before `execute`, and by the approval hook before the user is asked,
+     * so a call that would be refused as INVALID_ARGS never becomes an approval prompt. Keep it a pure function of `args`.
+     */
+    precheck?(args: Record<string, any>): string[];
     execute(args: Record<string, any>, ctx: ActionContext): Promise<unknown>;
     /** The result as the text the model reads. */
     render(result: any, args: Record<string, any>): string;
@@ -117,6 +133,16 @@ export declare class ActionNotFoundError extends Error {
     readonly hint?: string | undefined;
     constructor(message: string, hint?: string | undefined);
 }
+/** Raised when something the call needs is not set up here (a broken overlay file, say); mapped to CAPABILITY_UNAVAILABLE. */
+export declare class ActionUnavailableError extends Error {
+    readonly hint?: string | undefined;
+    constructor(message: string, hint?: string | undefined);
+}
+/** Raised when a write is refused because the stored state moved on since the caller read it (revision mismatch); mapped to ACTION_FAILED with the hint to read again. */
+export declare class ActionConflictError extends Error {
+    readonly hint?: string | undefined;
+    constructor(message: string, hint?: string | undefined);
+}
 export declare const ERROR_CODES: readonly ["INVALID_ARGS", "UNKNOWN_ACTION", "CAPABILITY_UNAVAILABLE", "POLICY_DENIED", "DEADLINE", "CANCELLED", "NOT_FOUND", "ACTION_FAILED"];
 export type ErrorCode = typeof ERROR_CODES[number];
 export interface ActionErrorBody {

package/lib/types/browser-access.d.ts

@@ -42,3 +42,20 @@ export declare function browserState(browser: BrowserService | undefined): {
     state: 'ready' | 'incomplete' | 'legacy' | 'missing';
     reason?: string;
 };
+/** What a launch of the browser would do on this machine, as dsh-browser reports it (0.2.2+ `status().browser`). */
+export interface BrowserLaunchReadiness {
+    ready: boolean;
+    /** Which browser a launch will use (`playwright-chromium`, `system-browser`, ...). */
+    source?: string;
+    /** Where it is. */
+    path?: string;
+    /** The one command (or step) that fixes `ready: false`, in dsh-browser's own words. */
+    advice?: string;
+}
+/**
+ * Whether the browser service can actually launch a browser. The service being present only means the plugin is loaded: a new user
+ * has no Playwright Chromium, and whether a system Chrome stands in is dsh-browser's decision. It is asked, never guessed, and
+ * only a dsh-browser that reports it (`status().browser`) is believed; any other answer (older plugin, a failing status call)
+ * is `undefined`, which callers treat as unknown and say nothing about.
+ */
+export declare function browserLaunchReadiness(browser: BrowserService | undefined): Promise<BrowserLaunchReadiness | undefined>;

package/lib/types/catalog/recommend.d.ts

@@ -60,6 +60,10 @@ export interface Suggestion {
     /** First counter-example of the entry. */
     notFor?: string;
     verified: boolean;
+    /** "常用": the plugin's recommended source (it leads once its key is configured). */
+    common?: boolean;
+    /** The CLI backend this source runs through, when its adapter was not verified with a real search (`twitter: contract-only — …`). */
+    backend?: string;
     sourceFamily?: string;
 }
 export interface Recommendation {

package/lib/types/catalog/schema.d.ts

@@ -62,6 +62,8 @@ export interface CatalogEntry {
     invoke?: string;
     /** Curation order among equals (lower first, default 50). */
     rank?: number;
+    /** "常用": the plugin's recommended source. Once its key is configured it leads the recommendations, and `search.recommend` marks it. Mirrors the provider descriptor's `common`. */
+    common?: boolean;
     /** Short install or configuration text. */
     install: string;
     license: string;

package/lib/types/cli/builtin-specs.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The built-in CLI adapter specs (dev-plan M12). Every argv, flag and output field was derived from the tool's own
+ * `--help` (and, where the help does not show the output shape, from the installed package source or the upstream
+ * README), and `verification` records how far each was checked:
+ *  - `live`: a real read-only search was run and its output parsed (bili, gh, omnireach, yt-dlp, wx-search-cli, xhs; the standalone
+ *    opencli for the twitter and zhihu sites, see opencli-sites.ts; and Exa through mcporter, which is not a spec);
+ *  - `contract-only`: help and version probed on a real install, output shape taken from the tool's own source,
+ *    README or documented output option, because a search needs the user's login or reads browser cookies
+ *    (zhihu, rdt, twitter, the other opencli sites);
+ *  - `docs-only`: not installed here; derived from the upstream README (tanso).
+ * Fixtures for the contract-only and docs-only parsers are marked "constructed from help/docs" in test/fixtures/cli.
+ * @module web-search-pro/cli/builtin-specs
+ */
+import { type CliAdapterSpec, type CliSearchSpec } from './spec.ts';
+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;
+}[];
+export declare const TWITTER_CLI_INSTALLS: {
+    installer: string;
+    command: string;
+}[];
+/** The date of the checks recorded below. */
+export declare const SPEC_CHECK_DATE = "2026-10-06";
+/** The omnireach sources that need neither a key, a login nor a browser (the others are `heavy` / booster tiers or need a URL query). */
+export declare const OMNIREACH_KEYLESS_SOURCES = "hackernews,youtube,github,wechat,bilibili";
+/** The `wechat` platform's two tools and the multi-source `omnireach` platform come from the same specs; ids are the backend ids. */
+export declare const BUILTIN_CLI_SPECS: readonly CliAdapterSpec[];
+/**
+ * How far the adapter of a command (by its first bin name) was verified: a built-in spec's own record, and for the standalone
+ * OpenCLI that of the site of `platform` (`live` for twitter and zhihu), else `contract-only`.
+ */
+export declare function cliVerificationOf(bin: string, platform?: string): string | undefined;
+export declare const builtinSpecById: (id: string) => CliAdapterSpec | undefined;
+export type { CliSearchSpec };

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

@@ -0,0 +1,83 @@
+/**
+ * Platform backend chains (dev-plan M12): every platform provider resolves an ORDERED chain of backends - a standalone CLI
+ * spec (xhs, rdt, zhihu, twitter, bili, yt-dlp, omnireach, gh, ...), the standalone OpenCLI (`opencli`), the dsh-browser
+ * OpenCLI bridge (`browser-opencli`), dsh-browser's rendered search page (`browser-search`), or the plugin's REST client
+ * (`rest`). The order is configurable (`platformBackends`). A backend that is missing, incompatible or not logged in is
+ * skipped with its reason; the provider is unavailable only when the whole chain is, and its error names what to install
+ * or run. Readiness is local: no search, no login.
+ * @module web-search-pro/cli/chain
+ */
+import { type Engine, type EngineDeps } from '../engines.ts';
+import type { ResolvedConfig } from '../config.ts';
+import { CHAIN_PLATFORMS, DEFAULT_CHAINS } from './chains-spec.ts';
+import { type CliAdapterSpec } from './spec.ts';
+export type BackendKind = 'cli' | 'opencli' | 'browser-opencli' | 'browser-search' | 'rest' | 'custom-cli';
+export { DEFAULT_CHAINS, CHAIN_PLATFORMS };
+export interface LegReadiness {
+    ready: boolean;
+    installation: 'missing' | 'detected' | 'incompatible' | 'not_required';
+    version?: string;
+    credential?: 'not_required' | 'missing' | 'configured';
+    reason?: string;
+    /** Why it is skipped (absent when ready). */
+    code?: 'disabled' | 'cli_missing' | 'cli_incompatible' | 'not_logged_in' | 'browser_missing' | 'unsupported';
+}
+export interface ChainLeg {
+    /** Backend id as written in `platformBackends`. */
+    id: string;
+    kind: BackendKind;
+    label: string;
+    engine: Engine;
+    readiness(): Promise<LegReadiness>;
+    /** How far this backend's contract was checked (`live`, `contract-only`, `docs-only`, `unverified`). */
+    verification: string;
+}
+export interface ChainResolution {
+    legs: ChainLeg[];
+    /** Problems of the configuration (an unknown or foreign backend id), for `sources.status`. */
+    diagnostics: string[];
+}
+export interface ChainContext {
+    deps: EngineDeps;
+    config: ResolvedConfig;
+}
+/** All specs a chain may use: the built-ins by id and the user's `cliAdapters` as `custom-cli:<id>`. */
+export declare function allSpecs(config: Pick<ResolvedConfig, 'cliAdapters'>): {
+    specs: Map<string, CliAdapterSpec>;
+    diagnostics: string[];
+};
+/** The chain of one platform: the configured (`platformBackends`) or default order, each id turned into a leg or into a diagnostic. */
+export declare function resolveChain(platform: string, ctx: ChainContext): ChainResolution;
+export interface ChainEntryReport {
+    id: string;
+    kind: BackendKind;
+    label: string;
+    order: number;
+    state: 'ready' | 'skipped';
+    installation?: string;
+    version?: string;
+    credential?: string;
+    reason?: string;
+    verification: string;
+}
+/**
+ * What a chain can do right now, one word for the text and the structured fields alike:
+ * `ready` (a backend can run and its login is satisfied or not needed), `login_unverified` (a backend can run but its login
+ * cannot be checked locally: a browser session, a keyring), `needs_login` (nothing can run and at least one backend lacks its
+ * login or credential), `unavailable` (nothing can run: not installed, incompatible, disabled).
+ */
+export type ChainState = 'ready' | 'login_unverified' | 'needs_login' | 'unavailable';
+export interface ChainReport {
+    entries: ChainEntryReport[];
+    available: boolean;
+    state: ChainState;
+    /** The first ready leg, or the best state among the skipped ones. */
+    installation: 'missing' | 'detected' | 'incompatible' | 'not_required';
+    credential?: 'not_required' | 'missing' | 'configured';
+    /** Why nothing can run: every skip reason in chain order. */
+    reason?: string;
+    diagnosticCode?: string;
+    diagnostics: string[];
+}
+/** Local readiness of a whole chain (one probe per leg, cached). */
+export declare function chainReport(platform: string, ctx: ChainContext): Promise<ChainReport>;

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

@@ -0,0 +1,48 @@
+/**
+ * The static facts of the platform backend chains (dev-plan M12), free of Node imports so the settings card validates
+ * `platformBackends` with the same code the server resolves it with: the default chain of each platform, which backend
+ * ids exist and which platforms each can serve.
+ * @module web-search-pro/cli/chains-spec
+ */
+import { OPENCLI_SITE_OF } from './opencli-sites.ts';
+/**
+ * The default chain of each platform: first usable backend answers, empty or failing ones fall through in order. The platforms
+ * that need a login (xiaohongshu, reddit, twitter, zhihu) try the standalone OpenCLI first: it reads the login of the user's
+ * own day-to-day Chrome through the OpenCLI Browser Bridge, so nothing is logged in by the plugin. The standalone CLIs
+ * (xhs, rdt, twitter, zhihu) stay as the optional fallback for users who logged them in themselves.
+ */
+export declare const DEFAULT_CHAINS: Readonly<Record<string, readonly string[]>>;
+/** Platforms whose provider is a chain (everything in the default table). */
+export declare const CHAIN_PLATFORMS: readonly string[];
+export { OPENCLI_SITE_OF };
+/** Platforms the dsh-browser OpenCLI bridge has a site adapter for (pinned to engines.ts by a test). */
+export declare const BROWSER_OPENCLI_PLATFORMS: readonly string[];
+/** Platforms with a built-in rendered-search-page spec in dsh-browser's searchResults (pinned to platform-search.ts by a test). */
+export declare const BROWSER_SEARCH_PLATFORMS: readonly string[];
+/** Platforms the plugin's own REST client serves. */
+export declare const REST_PLATFORMS: readonly string[];
+/** Backend ids that are not CLI specs. */
+export declare const FIXED_BACKENDS: readonly ["opencli", "browser-opencli", "browser-search", "rest"];
+/** Whether `id` names a platform backend: a built-in CLI spec, a fixed backend, or a custom CLI (`custom-cli:<id>`). */
+export declare function isBackendId(id: string): boolean;
+export interface BackendServing {
+    ok: boolean;
+    why?: string;
+}
+/**
+ * Whether backend `id` can serve `platform`. `specPlatforms` maps a CLI spec id (built-in, or `custom-cli:<id>` of the user)
+ * to the platforms it lists; a user spec serves any platform its chain names.
+ */
+export declare function backendServes(id: string, platform: string, specPlatforms: ReadonlyMap<string, readonly string[]>): BackendServing;
+/** The CLI specs a chain may name: the built-ins by id and the user's valid `cliAdapters` as `custom-cli:<id>`. */
+export declare function specPlatformsOf(cliAdapters: unknown): {
+    platforms: Map<string, readonly string[]>;
+    diagnostics: string[];
+};
+/** The declared platforms of the user's CLI adapters that no backend chain exists for (the spec would serve nothing there). */
+export declare function customCliPlatformIssues(cliAdapters: unknown): string[];
+/**
+ * Every problem of the `platformBackends` setting (shape, unknown platform, unknown or foreign backend id) given the
+ * `cliAdapters` setting. The settings card and `sources.status` both call this.
+ */
+export declare function platformBackendIssues(platformBackends: unknown, cliAdapters: unknown): string[];

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

@@ -0,0 +1,50 @@
+/**
+ * The Engine of a CLI adapter spec (dev-plan M12): one search leg that probes the command's contract (cached), then runs
+ * the spec through the shared runner. `available()` is synchronous and local (settings gates plus the probe cache);
+ * every failure reaches the caller as a structured error naming what to install or run.
+ * @module web-search-pro/cli/engine
+ */
+import type { Engine, EngineDeps } from '../engines.ts';
+import { CliAdapterError } from './runner.ts';
+import { type CliProbeResult } from './probe.ts';
+import { type CliAdapterSpec } from './spec.ts';
+import type { runCli } from '../util.ts';
+/** Why a spec is switched off by settings, or undefined when it may run. */
+export declare function disabledBySettings(spec: Pick<CliAdapterSpec, 'id'>, deps: Pick<EngineDeps, 'enableCli' | 'agentReachEnabled'>): string | undefined;
+/**
+ * The environment a spec's credential variables are read from: the process environment overlaid with the values the router
+ * resolved (settings literal -> DSH credentials -> process environment). Undefined = the process environment as it is.
+ */
+export declare function specEnv(deps: Pick<EngineDeps, 'cliEnv'>): NodeJS.ProcessEnv | undefined;
+export interface CliLegOptions {
+    /** Engine id (default: the spec id). */
+    id?: string;
+    label?: string;
+    /** Test seam: replaces the process runner; the contract probe is then skipped (the caller controls the command). */
+    run?: typeof runCli;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    /** The credentials are checked by the caller (the legacy twitter engine). */
+    skipCredentialGate?: boolean;
+    /** A user-defined spec: every row it returns says which CLI it came from and that nothing here verified it. */
+    userDefined?: boolean;
+}
+/** The probe verdict as the structured error a search would raise, or undefined when the command is usable. */
+export declare function probeError(spec: Pick<CliAdapterSpec, 'bins' | 'packageNote'>, probe: CliProbeResult): CliAdapterError | undefined;
+export declare function cliSpecEngine(spec: CliAdapterSpec, platform: string, deps: Pick<EngineDeps, 'enableCli' | 'agentReachEnabled' | 'cliEnv'>, options?: CliLegOptions): Engine;
+export interface SpecReadiness {
+    ready: boolean;
+    installation: 'missing' | 'detected' | 'incompatible';
+    version?: string;
+    path?: string;
+    /** Absent when the tool needs a login that cannot be checked from here (a keyring, a browser session). */
+    credential?: 'not_required' | 'missing' | 'configured';
+    /** Why it cannot run, naming what to install or run. */
+    reason?: string;
+    code: 'ok' | 'disabled' | 'cli_missing' | 'cli_incompatible' | 'not_logged_in';
+}
+/** Local readiness of one spec: settings, contract probe, then the credentials it needs. Never runs a search. */
+export declare function specReadiness(spec: CliAdapterSpec, deps: Pick<EngineDeps, 'enableCli' | 'agentReachEnabled' | 'cliEnv'>, options?: {
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}): Promise<SpecReadiness>;

package/lib/types/cli/opencli-sites.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The static facts of the standalone OpenCLI sites the plugin searches (free of Node imports, so the catalog and the chain
+ * specs can read them): which site serves which platform, how each site's `search` rows map to sources, and how far each
+ * mapping was verified. The spec generation itself (src/cli/opencli.ts) reads the live command table.
+ * @module web-search-pro/cli/opencli-sites
+ */
+import type { CliAdapterSpec, CliOutputSpec } from './spec.ts';
+/** Platform -> site of the standalone OpenCLI (`opencli <site> search`). */
+export declare const OPENCLI_SITE_OF: Readonly<Record<string, string>>;
+export declare const GENERIC_OUTPUT: CliOutputSpec;
+/**
+ * The output mapping of the sites the plugin knows by their real columns. All four print a JSON array of flat rows under `-f json`.
+ *  - twitter, zhihu: MEASURED (opencli 1.8.8, 2026-10-27, fixtures live-opencli-*). twitter rows are `id, author (handle), bio, text,
+ *    created_at (X API format), likes (number), views (string), url (https://x.com/i/status/<id>), has_media, media_urls, ...`; the
+ *    title and meta line follow the standalone twitter backend (text, then author · likes · views · time). zhihu rows are
+ *    `rank, title, type, author, votes, url` and carry no excerpt and no time.
+ *  - xiaohongshu, reddit: NOT MEASURED. The only runs failed (login wall; an HTML page instead of JSON), so the mapping is the
+ *    documented columns of clis/xiaohongshu/search.js (`rank, title, author, likes, published_at (date from the note id), url`,
+ *    the url is a signed search_result link) and clis/reddit/search.js (`id, title, subreddit (r/x), author, score, comments, url,
+ *    created_utc (epoch seconds), selftext, ...`), read from the source of 1.8.8.
+ */
+export declare const SITE_OUTPUT: Readonly<Record<string, CliOutputSpec>>;
+/** How far the search of one OpenCLI site was checked (`live`, `contract-only`). */
+export declare function opencliSiteVerification(site: string): NonNullable<CliAdapterSpec['verification']>;

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

@@ -0,0 +1,77 @@
+/**
+ * Standalone OpenCLI (dev-plan M12): the `opencli` command the user installed themselves, which drives their own Chrome
+ * through its Browser Bridge, independent of the dsh-browser plugin. It has one command per site and the plugin only
+ * calls `<site> search`, and only for sites that `opencli list -f json` itself reports with a read-access `search`
+ * command taking a positional query (the catalog is the tool's own, so a site without search, such as douyin or v2ex,
+ * is never assumed to have one). The list is a local call: no browser, no login.
+ * @module web-search-pro/cli/opencli
+ */
+import { runCli } from '../util.ts';
+import { type ProbeSubject } from './probe.ts';
+import { type CliAdapterSpec, type CliErrorCodesSpec } from './spec.ts';
+import { opencliSiteVerification } from './opencli-sites.ts';
+export { OPENCLI_SITE_OF } from './chains-spec.ts';
+export { opencliSiteVerification };
+/** The command that proves this is the OpenCLI whose `list` output the adapter understands. Verified on 1.8.8. */
+export declare const OPENCLI_PROBE: ProbeSubject;
+/**
+ * The browser options every browser-backed site command of OpenCLI accepts (read from `opencli <site> search --help` and
+ * dist/src/execution.js of 1.8.8): the command runs in a background window (no focus is taken from the user's Chrome), with an
+ * ephemeral site session whose tab is released when it finishes. These are also its defaults; the plugin passes them
+ * explicitly so a changed `OPENCLI_WINDOW` / `OPENCLI_SITE_SESSION` environment cannot bring a window to the front, and only
+ * when the command itself lists the three options (a command without a browser rejects unknown options).
+ */
+export declare const OPENCLI_SILENT_ARGS: readonly string[];
+/** The probe of one site's search command: it must list the three silent browser options (`opencli <site> search --help`). Local, cached, no browser. */
+export declare function opencliSiteProbe(site: string): ProbeSubject;
+export interface OpencliSite {
+    site: string;
+    /** `cookie` sites use the user's logged-in Chrome; `public` sites need no login. */
+    strategy: string;
+    /** Whether the command drives the browser at all. */
+    browser: boolean;
+    hasLimit: boolean;
+    /** The site's domain as the command table gives it (`www.zhihu.com`), for the "log in to ..." hint. */
+    domain?: string;
+}
+/** Sites with a read `search` command taking a positional query, from the JSON of `opencli list -f json`. Pure. */
+export declare function parseOpencliList(json: string): Map<string, OpencliSite>;
+export declare function clearOpencliCache(): void;
+/** The searchable sites of the installed OpenCLI (cached 5 minutes); `undefined` when the command cannot be listed. */
+export declare function listOpencliSites(options?: {
+    run?: typeof runCli;
+    ttlMs?: number;
+    now?: () => number;
+    force?: boolean;
+}): Promise<{
+    sites?: Map<string, OpencliSite>;
+    problem?: string;
+}>;
+/**
+ * The failure format of OpenCLI 1.8.8 (dist/src/errors.js `toEnvelope`, printed as YAML on stderr whatever `-f` says):
+ * `ok: false` / `error: { code, message, help?, exitCode }`. Codes, from that file and the site adapters:
+ *  - AUTH_REQUIRED (exit 77): the Chrome has no login for the site -> not logged in (measured on xiaohongshu);
+ *  - LOGIN_WALL (77), SECURITY_BLOCK, RATE_LIMITED, FORBIDDEN: an HTML page where JSON was expected, a risk-control block -> blocked;
+ *    UNKNOWN with a JSON parse error on an HTML body (`Unexpected token '<'`) is the same thing from an adapter that does not
+ *    check (measured on reddit through a proxy);
+ *  - EMPTY_RESULT (66), NO_DATA, EMPTY_RESPONSE: nothing found; BROWSER_CONNECT (69): no Chrome / bridge; TIMEOUT (75);
+ *  - ARGUMENT, INVALID_ARGUMENT, ...: the arguments of this adapter are not accepted by that version.
+ * Anything else (COMMAND_EXEC, FETCH_ERROR, HTTP_ERROR, ...) keeps OpenCLI's own message.
+ */
+export declare const OPENCLI_ERROR_CODES: CliErrorCodesSpec;
+/** The spec that runs `opencli <site> search` for one platform, or undefined when the generated spec is invalid (a site named like a write command). */
+export declare function opencliSearchSpec(platform: string, entry: OpencliSite, options?: {
+    silent?: boolean;
+}): CliAdapterSpec | undefined;
+export interface OpencliSearchPlan {
+    spec?: CliAdapterSpec;
+    entry?: OpencliSite;
+    problem?: string;
+    hint?: string;
+    silent: boolean;
+}
+/**
+ * Everything a search of one platform through the standalone OpenCLI needs, checked locally (the command table and the site's
+ * `--help`, never a search): the site's entry, whether its command takes the silent browser options, and the generated spec.
+ */
+export declare function planOpencliSearch(platform: string, site: string): Promise<OpencliSearchPlan>;

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

@@ -0,0 +1,53 @@
+/**
+ * Contract probes of CLI adapter specs (dev-plan M12, design §4.3 / §4.4): local only, cached with a TTL. A probe finds
+ * the command on PATH and runs ONLY the spec's version and help commands, then checks the contract the spec needs: a
+ * minimum version and the subcommands / flags that must appear in the help text. A same-named program with another
+ * contract is `incompatible`, not `detected`. A probe never runs a search and never logs in.
+ * @module web-search-pro/cli/probe
+ */
+import { runCli } from '../util.ts';
+import { type CliAdapterSpec } from './spec.ts';
+export type CliInstallation = 'missing' | 'detected' | 'incompatible';
+export interface CliProbeResult {
+    state: CliInstallation;
+    /** The command name that matched. */
+    bin?: string;
+    /** Where it was found. */
+    path?: string;
+    version?: string;
+    /** Why it is incompatible or missing. */
+    reason?: string;
+    checkedAt: number;
+}
+/** What a probe needs of a spec: where the command is, how it is checked, and the environment it runs in. */
+export type ProbeSubject = Pick<CliAdapterSpec, 'id' | 'bins' | 'probe' | 'packageNote' | 'env'>;
+export interface CliProbeOptions {
+    run?: typeof runCli;
+    /** Cache lifetime; default 60 s. */
+    ttlMs?: number;
+    /** Skip the cache (an explicit "check again"). */
+    force?: boolean;
+    now?: () => number;
+}
+export declare function clearProbeCache(): void;
+/** The executable `cmd` resolves to on PATH (no process is spawned; Windows tries PATHEXT). */
+export declare function findOnPath(cmd: string, env?: NodeJS.ProcessEnv): string | undefined;
+/** The cached probe of a spec, when one is fresh (no spawn: `Engine.available()` is synchronous). */
+export declare function cachedProbe(spec: ProbeSubject, ttlMs?: number, now?: () => number): CliProbeResult | undefined;
+export interface ContractInput {
+    code: number;
+    output: string;
+}
+/**
+ * Decide whether version and help output satisfy a spec's contract. Pure (the fixtures tests call it directly).
+ * The version command may fail or print nothing unless the spec asks for a minimum version.
+ */
+export declare function evaluateCliContract(spec: Pick<CliAdapterSpec, 'probe'>, bin: string, version: ContractInput, help: ContractInput): {
+    state: 'detected' | 'incompatible';
+    version?: string;
+    reason?: string;
+};
+/** Probe one spec (cached; concurrent calls for the same spec share one run). */
+export declare function probeCli(spec: ProbeSubject, options?: CliProbeOptions): Promise<CliProbeResult>;
+/** Probe many specs with a small concurrency bound (a settings refresh must not spawn dozens of processes at once). */
+export declare function probeAll(specs: readonly ProbeSubject[], options?: CliProbeOptions, concurrency?: number): Promise<Map<string, CliProbeResult>>;

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

@@ -0,0 +1,126 @@
+/**
+ * The runner of CLI adapter specs (dev-plan M12): spawns the tool without a shell, decodes its output as UTF-8, caps
+ * time and size, maps the output to search sources and every failure to a structured error. It never logs or echoes
+ * environment values (error text is scrubbed of any value of a variable the spec names) and never runs a login.
+ * @module web-search-pro/cli/runner
+ */
+import type { WebSearchSource } from '@deepseek-ai/dsh-web';
+import { runCli, type CliResult } from '../util.ts';
+import { EngineError } from '../engine-error.ts';
+import { type CliAdapterSpec, type CliErrorCode, type CliErrorCodesSpec, type CliOutputSpec, type CliSearchSpec, type FieldSource } from './spec.ts';
+/** A structured failure of a CLI adapter: `code` is one of {@link CliErrorCode}; `hint` says what the user can do. */
+export declare class CliAdapterError extends EngineError {
+    readonly hint?: string | undefined;
+    constructor(message: string, code: CliErrorCode, hint?: string | undefined, retryable?: boolean);
+}
+/**
+ * A NO_PROXY list with its IPv6 entries written without brackets (`[::1]` / `[::1]:8080` -> `::1`). Python's httpx (omnireach, and
+ * any tool built on it) refuses a bracketed entry with "Invalid port: ':1]'" and the whole search fails; the DSH Host sets
+ * `NO_PROXY` with `[::1]`, which a plain terminal does not (found live 2026-10-26). Every tool that takes NO_PROXY accepts the bare form.
+ */
+export declare function normalizeNoProxy(list: string): string;
+/** The environment a spec's command runs with: the base set, what the spec lists, and the fixed UTF-8 / `env.set` values. */
+export declare function buildCliEnv(spec: Pick<CliAdapterSpec, 'env'>, source?: NodeJS.ProcessEnv): Record<string, string>;
+/** Names of the credential variables a spec relies on that are not set. */
+export declare function missingEnv(spec: Pick<CliAdapterSpec, 'env'>, source?: NodeJS.ProcessEnv): string[];
+/** The home-relative saved-login files of a spec that exist (existence only; the content is never read). */
+export declare function savedLoginPresent(spec: Pick<CliAdapterSpec, 'login'>, opts?: {
+    home?: string;
+    exists?: (file: string) => boolean;
+}): boolean | undefined;
+/** Credential variables the plugin also resolves from its own settings / DSH credentials (config literal -> credentials ref -> environment). */
+export declare const SETTINGS_BACKED_ENV: Readonly<Record<string, string>>;
+/** What the user must do to log in: the tool's own command run by them, or the environment variables they set. Never run by the plugin. */
+export declare function loginHint(spec: Pick<CliAdapterSpec, 'bins' | 'login' | 'env'>): string;
+export declare function getPath(root: unknown, dotted: string): unknown;
+export declare function resolveField(source: FieldSource | undefined, item: unknown, empty?: ReadonlySet<string>, now?: number): string | undefined;
+/**
+ * Whether the whole stdout of a text-mode command is a JSON object / array or a YAML mapping / sequence document: the tool then
+ * printed a structured format the text parsers must not guess at (twitter-cli prints YAML when piped, issue #38).
+ */
+export declare function structuredKind(text: string): 'JSON' | 'YAML' | undefined;
+/**
+ * Parse a tool's stdout into the items its output spec describes. A broken payload is CLI_CONTRACT_MISMATCH (the tool is not
+ * what the spec says); a payload that says it failed (`expect` not met) is CLI_FAILED with the tool's own message.
+ */
+export declare function parseCliItems(spec: Pick<CliAdapterSpec, 'bins'>, output: CliOutputSpec, stdout: string): unknown[];
+/** The failure payload (`ok: false`, `error: { code, message }`) a tool prints on stderr or stdout: JSON, or a YAML document after any notices. */
+export declare function parseFailurePayload(text: string): unknown;
+/**
+ * A failed command run (non-zero exit) as the structured error its own code and message call for, or undefined when the
+ * spec lists no codes or the output carries nothing readable (the generic handling then applies).
+ */
+export declare function mapToolFailure(codes: CliErrorCodesSpec | undefined, result: Pick<CliResult, 'code' | 'stdout' | 'stderr'>, spec: Pick<CliAdapterSpec, 'bins' | 'login' | 'env'>, redact?: (text: string) => string): CliAdapterError | EngineError | undefined;
+/** The tool's own error text from a parsed json / yaml payload (`errorPaths`), when it carries one. */
+export declare function payloadError(output: CliOutputSpec, stdout: string): string | undefined;
+/**
+ * Strip markup from a field. Highlight tags (`<em>备案</em>`) vanish without leaving a space (Chinese words must not be split),
+ * block-level tags become a space, entities are decoded.
+ */
+export declare function stripMarkup(input: string): string;
+/**
+ * Map parsed items to sources by the output spec: http(s) URLs only, snippets and titles capped, tags stripped when asked.
+ * `skipped` counts the items (objects) that had no usable link, so the caller can say so instead of silently returning fewer.
+ */
+export declare function mapCliItemsDetailed(output: CliOutputSpec, items: readonly unknown[], count: number, now?: number): {
+    sources: WebSearchSource[];
+    skipped: number;
+};
+export declare function mapCliItems(output: CliOutputSpec, items: readonly unknown[], count: number, now?: number): WebSearchSource[];
+/**
+ * The result of a `lines: { mode: 'whole' }` command: the whole stdout as ONE source. The text is cut at `maxChars` with a note that
+ * says how much was shown; the title is "<id>: <query>"; the link is the stand-in `cli://<id>?q=<query>` (it is no web page, so the
+ * evidence pipeline lists it but never fetches it). Undefined when the tool printed nothing.
+ */
+export declare function wholeOutputSource(spec: Pick<CliAdapterSpec, 'id'>, output: CliOutputSpec, query: string, stdout: string): WebSearchSource | undefined;
+/** Parse and map in one go (what the fixtures tests call). */
+export declare function parseCliOutput(spec: Pick<CliAdapterSpec, 'bins'>, search: CliSearchSpec, stdout: string, count?: number, now?: number): WebSearchSource[];
+/** Split a query into words; double quotes keep a phrase in one word (`a "b c" d` -> `a`, `b c`, `d`) and are dropped. */
+export declare function splitTerms(query: string): string[];
+/**
+ * Fill the placeholders of an argv template. A value that would read as a flag gets a leading space (the tool then takes it as the query)
+ * unless a `--` precedes it. A `{terms}` token becomes one token per word of the query.
+ */
+export declare function buildArgv(search: Pick<CliSearchSpec, 'argv' | 'maxCount' | 'overfetch'>, input: {
+    query: string;
+    count: number;
+}): string[];
+export interface CliRunInput {
+    query: string;
+    count: number;
+    signal?: AbortSignal | undefined;
+}
+export interface CliRunOptions {
+    /** Platform being searched (selects `spec.searches[platform]`). */
+    platform?: string;
+    /** `search` (default) or `read`. */
+    operation?: 'search' | 'read';
+    /** Resolved command (a path or the bin name); default `spec.bins[0]`. */
+    bin?: string;
+    /** Test seams. */
+    run?: typeof runCli;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    exists?: (file: string) => boolean;
+    /** The caller checks the credentials itself (the legacy twitter engine): skip the pre-run credential gate. */
+    skipCredentialGate?: boolean;
+    /** Test seam: the clock `{ time }` fields read relative texts (`3小时前`) against. */
+    now?: number;
+    /** Sees what the command printed (secrets redacted) before it is interpreted: the settings card's trial shows the tool's own words. */
+    observe?: (result: {
+        code: number;
+        stdout: string;
+        stderr: string;
+    }) => void;
+}
+/**
+ * Run one spec command for a query and return its sources. Throws {@link CliAdapterError} (CLI_NOT_FOUND,
+ * CLI_CONTRACT_MISMATCH, CLI_NOT_LOGGED_IN, CLI_FAILED), ENGINE_EMPTY for a valid empty answer, ENGINE_TIMEOUT, or the
+ * abort reason when the caller's signal fires. Nothing is run when the spec's credentials are missing.
+ */
+export declare function runCliSearch(spec: CliAdapterSpec, input: CliRunInput, options?: CliRunOptions): Promise<WebSearchSource[]>;
+/** {@link runCliSearch} that also reports how many results had no usable link and were skipped. */
+export declare function runCliSearchDetailed(spec: CliAdapterSpec, input: CliRunInput, options?: CliRunOptions): Promise<{
+    sources: WebSearchSource[];
+    skipped: number;
+}>;