dsh-web-search-pro 0.2.1 → 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

@@ -2,10 +2,11 @@
  * 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/wechat);
+ *  - `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, or was outside
- *    the checks allowed (xhs, zhihu, rdt, twitter, opencli sites, yt-dlp, wx-search-cli);
+ *    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
@@ -24,7 +25,14 @@ export declare const TWITTER_CLI_INSTALLS: {
 }[];
 /** 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/chains-spec.d.ts

@@ -4,12 +4,17 @@
  * ids exist and which platforms each can serve.
  * @module web-search-pro/cli/chains-spec
  */
-/** The default chain of each platform: first usable backend answers, empty or failing ones fall through in order. */
+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[];
-/** Platform -> site of the standalone OpenCLI (`opencli <site> search`). */
-export declare const OPENCLI_SITE_OF: Readonly<Record<string, 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). */
@@ -18,6 +23,8 @@ export declare const BROWSER_SEARCH_PLATFORMS: readonly string[];
 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;
@@ -32,6 +39,8 @@ 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.

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

@@ -7,10 +7,15 @@
 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 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;
@@ -21,10 +26,12 @@ export interface CliLegOptions {
     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'>, options?: CliLegOptions): Engine;
+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';
@@ -37,7 +44,7 @@ export interface SpecReadiness {
     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'>, options?: {
+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

@@ -8,10 +8,22 @@
  */
 import { runCli } from '../util.ts';
 import { type ProbeSubject } from './probe.ts';
-import { type CliAdapterSpec } from './spec.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. */
@@ -19,7 +31,8 @@ export interface OpencliSite {
     /** Whether the command drives the browser at all. */
     browser: boolean;
     hasLimit: boolean;
-    loginCommand?: string;
+    /** 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>;
@@ -34,5 +47,31 @@ export declare function listOpencliSites(options?: {
     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): CliAdapterSpec | undefined;
+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/runner.d.ts

@@ -5,14 +5,20 @@
  * @module web-search-pro/cli/runner
  */
 import type { WebSearchSource } from '@deepseek-ai/dsh-web';
-import { runCli } from '../util.ts';
+import { runCli, type CliResult } from '../util.ts';
 import { EngineError } from '../engine-error.ts';
-import { type CliAdapterSpec, type CliErrorCode, type CliOutputSpec, type CliSearchSpec, type FieldSource } from './spec.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. */
@@ -22,15 +28,29 @@ export declare function savedLoginPresent(spec: Pick<CliAdapterSpec, 'login'>, o
     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>): string | undefined;
+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;
 /**
@@ -42,15 +62,26 @@ 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): {
+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): WebSearchSource[];
+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): WebSearchSource[];
-/** 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). */
-export declare function buildArgv(search: Pick<CliSearchSpec, 'argv' | 'maxCount'>, input: {
+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[];
@@ -73,6 +104,14 @@ export interface CliRunOptions {
     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,

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

@@ -16,13 +16,38 @@ 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];
+/**
+ * The short honest tag shown next to a backend that was not verified with a real search ("detected and configured" is not "works"),
+ * or undefined for `live` and for backends that are not CLI specs.
+ */
+export declare function verificationTag(status: string): string | undefined;
+/** The verification word of a user-defined spec: it is unverified by definition and says so in every result it returns. */
+export declare const USER_DEFINED = "user-defined";
+/** The honest label a custom CLI's results and chain entries carry. */
+export declare const USER_DEFINED_TAG = "user-defined, not verified by the plugin (\u7528\u6237\u81EA\u5B9A\u4E49\uFF0C\u672A\u7ECF\u63D2\u4EF6\u9A8C\u8BC1)";
+/** Confidence of a custom CLI whose spec gives none: below the built-in sources (1), because nothing here checked its output. */
+export declare const DEFAULT_CUSTOM_CONFIDENCE = 0.5;
+/** Default and largest size of a whole-output result's text, in characters (`output.lines.maxChars`). */
+export declare const WHOLE_OUTPUT_DEFAULT_CHARS = 2000;
+export declare const WHOLE_OUTPUT_MAX_CHARS = 8000;
+/** Scheme of the stand-in link of a whole-output result (`cli://<id>?q=<query>`): not a web page, so nothing fetches it. */
+export declare const WHOLE_OUTPUT_SCHEME = "cli://";
 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. */
+/**
+ * One piece of a joined field: a path, optionally with text put before / after the value, a `{ template }` over the item (dropped
+ * when a placeholder is empty), or a `{ time }` path whose text is read as a time (see {@link FieldSource}) and dropped when it is not one.
+ */
 export type JoinPart = string | {
     path: string;
     prefix?: string;
     suffix?: string;
+} | {
+    template: string;
+} | {
+    time: 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 {
@@ -38,7 +63,11 @@ export interface TemplateSource {
  *  - 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.
+ *  - `{ epoch }`: a Unix timestamp (seconds) as an ISO date; `{ date }`: the date part (first 10 characters) of an ISO timestamp;
+ *  - `{ time }`: a time text the tool prints (ISO, the X API's `created_at`, `2026-10-27`, `08-26`, `3小时前`, `昨天 10:20`, ...) as an
+ *    ISO date or timestamp, and nothing when the text is none of the exactly known formats (see cli/time-text.ts).
+ * A dotted path may hold a `key=value` segment that picks the first element of an array with that field value
+ * (`note_card.corner_tag_info.type=publish_time.text`).
  */
 export type FieldSource = string | readonly (string | TemplateSource)[] | TemplateSource | {
     join: readonly JoinPart[];
@@ -47,6 +76,8 @@ export type FieldSource = string | readonly (string | TemplateSource)[] | Templa
     epoch: string;
 } | {
     date: string;
+} | {
+    time: string;
 };
 export interface CliOutputSpec {
     format: OutputFormat;
@@ -59,19 +90,32 @@ export interface CliOutputSpec {
     }[];
     /** 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`). */
+    /**
+     * text: how a line becomes an item (`tsv`: tab separated columns; `url-lines`: lines holding a URL, `url` + `title`; `whole`: the
+     * whole stdout is ONE result, for a tool that prints just a block of text: its text capped at `maxChars` (default
+     * {@link WHOLE_OUTPUT_DEFAULT_CHARS}) with a note when it was cut, the title "<id>: <query>" and the link `cli://<id>?q=<query>`).
+     */
     lines?: {
         mode: 'tsv';
         columns: readonly string[];
     } | {
         mode: 'url-lines';
+    } | {
+        mode: 'whole';
+        maxChars?: number;
     };
-    fields: {
-        url: FieldSource;
+    /** Required (with `url`) for every mode except `whole`, which maps nothing. */
+    fields?: {
+        url?: FieldSource;
         title?: FieldSource;
         snippet?: FieldSource;
         publishedAt?: FieldSource;
     };
+    /** Items whose `path` equals the value are not results at all and are not counted as skipped (xhs: `model_type` is `hot_query` for the suggestion cards its result list also carries). */
+    skipWhen?: {
+        path: string;
+        equals: string | number | boolean;
+    };
     /** Strip HTML tags from title and snippet. */
     stripTags?: boolean;
     /** Values read as "empty" (`None`). */
@@ -83,16 +127,54 @@ export interface CliOutputSpec {
     /** Drop items without a title (a line that is not a result). */
     requireTitle?: boolean;
 }
+/**
+ * How a tool reports a failed command in its machine-readable format (a YAML / JSON payload on stderr, else stdout), and what
+ * each of its error codes means. A listed code is mapped to a structured plugin error; a code that is not listed keeps the
+ * tool's own message (`<tool> search failed: [CODE] message`).
+ */
+export interface CliErrorCodesSpec {
+    /** Dotted path of the tool's error code in the failure payload (`error.code`). */
+    codePath: string;
+    /** Dotted path of its message (`error.message`). */
+    messagePath?: string;
+    /** Codes that mean "not logged in" (CLI_NOT_LOGGED_IN). */
+    notLoggedIn?: readonly string[];
+    /** Exit codes that mean "not logged in" when the output carries no readable code. */
+    notLoggedInExit?: readonly number[];
+    /** Codes that mean "no results" (ENGINE_EMPTY). */
+    empty?: readonly string[];
+    /** Codes that mean the site answered with a web page or blocked the request: risk control, IP block, login wall (CLI_FAILED, said so). */
+    blocked?: readonly string[];
+    /** Case-insensitive fragments of the tool's message that mean the same (a JSON parse error on an HTML page: `Unexpected token '<'`). */
+    blockedPatterns?: readonly string[];
+    /** Codes that mean the tool cannot reach its browser (CLI_FAILED, not retryable). */
+    unavailable?: readonly string[];
+    /** Codes that mean a timeout (ENGINE_TIMEOUT). */
+    timeout?: readonly string[];
+    /** Codes that mean the tool rejected its arguments (CLI_CONTRACT_MISMATCH: the adapter does not match this version). */
+    usage?: readonly string[];
+}
 export interface CliSearchSpec {
-    /** Arguments after the binary. `{query}` and `{count}` are the placeholders; a token may embed one (`ytsearch{count}:{query}`). */
+    /**
+     * Arguments after the binary. `{query}` and `{count}` are the placeholders; a token may embed one (`ytsearch{count}:{query}`).
+     * A token that is exactly `{terms}` expands to the query split into one argv token per word (double quotes keep a phrase together):
+     * for tools that join their positional arguments themselves and would otherwise quote a one-token query as an exact phrase (`gh search`).
+     */
     argv: readonly string[];
     /** Largest `{count}` sent (the search call's count is clamped to 1..maxCount). */
     maxCount?: number;
+    /**
+     * Extra results asked of the tool beyond the count (`{count}` becomes count + overfetch), for tools whose list can hold entries the
+     * mapper must drop (bili: courses and series without a link). The mapper still returns at most `count`.
+     */
+    overfetch?: 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[];
+    /** The tool's structured error codes (checked before the fragments above). */
+    errorCodes?: CliErrorCodesSpec;
 }
 export interface CliProbeSpec {
     versionArgs: readonly string[];
@@ -101,10 +183,14 @@ export interface CliProbeSpec {
     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[];
+    /** Appended to the reason when `mustContain` is not met (which version is known to have the contract, for example). */
+    contractHint?: string;
 }
 export interface CliLoginSpec {
     /** What the user runs themselves (`xhs login`); never run by the plugin. */
-    command: string;
+    command?: string;
+    /** What the user does, in words, when the tool takes its login from somewhere the plugin cannot run (the login of the user's own Chrome): shown instead of a command. One of `command` / `hint` is required. */
+    hint?: 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. */
@@ -116,8 +202,15 @@ export interface CliAdapterSpec {
     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>`. */
+    /**
+     * Platform ids the spec serves: the platforms whose backend chain it may sit in (`platformBackends.<platform>`). A user spec is
+     * also a platform of its own, `custom-cli:<id>`, and may list none when it is a general `engine`.
+     */
     platforms: readonly string[];
+    /** User specs only: also a general search engine, listed in `engines` as `custom-cli:<id>` (fused and de-duplicated with the others). */
+    engine?: boolean;
+    /** User specs only: 0..1, default {@link DEFAULT_CUSTOM_CONFIDENCE}. `sources.confidence.custom-cli:<id>` overrides it. */
+    confidence?: number;
     probe: CliProbeSpec;
     /** Every command word the argv templates use. */
     allowedSubcommands: readonly string[];

package/lib/types/cli/time-text.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Conservative parsing of the time texts CLI tools print (a field source `{ time }` of the adapter spec): an exact format is
+ * turned into an ISO date or timestamp, anything else gives nothing, so a result never carries a guessed time. Pure; the clock is
+ * a parameter. Chinese relative and calendar texts are read in China time (UTC+8), which is what the sites print.
+ *  - ISO 8601 (`2026-10-27T08:38:08Z`, with or without a zone offset or fraction) -> normalized timestamp;
+ *  - the `created_at` of the X API (`Tue Oct 27 08:38:08 +0000 2026`) -> timestamp;
+ *  - `YYYY-MM-DD` -> that date; `MM-DD` -> the latest such date that is not after today (a date in the future means last year);
+ *  - `N分钟前` / `N小时前` -> timestamp (now minus N); `N天前` -> date; `昨天 HH:MM` -> timestamp (China time).
+ * @module web-search-pro/cli/time-text
+ */
+/** The text as an ISO date (`YYYY-MM-DD`) or timestamp, or undefined when it is not one of the formats above. */
+export declare function normalizeTimeText(raw: string, now?: number): string | undefined;