dsh-web-search-pro 0.2.1 → 0.2.4

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

@@ -3,17 +3,43 @@
  * and the external CLI dependencies the plugin runs.
  * @module web-search-pro/actions/sources
  */
+import type { ProviderReport } from '../router.ts';
 import type { ResolvedConfig } from '../config.ts';
-import { type ActionDef } from './types.ts';
+import { type ActionDef, type OutputNode } from './types.ts';
+import type { OverlayStore } from '../overlay.ts';
+/** Settings changed in the configuration that the running plugin only reads at start-up (restart.ts). */
+export declare const PENDING_RESTART_SCHEMA: OutputNode;
+/** The state of the agent overlay in one line of data: revision, the overridden keys, and why it is ignored when it is. */
+export declare const OVERLAY_STATE_SCHEMA: OutputNode;
 /**
  * Whether the twitter platform backend can really run: the `twitter` command works (probed by detectDeps)
- * AND the backend is enabled in settings AND its credentials are in the environment (same gates as the engine).
+ * AND the backend is enabled in settings AND its credentials are available (same gates as the engine). `env` holds the values
+ * the router resolved (settings literal -> DSH credentials -> process environment); without it only the process environment is read.
  */
 export declare function twitterGate(cfg: Pick<ResolvedConfig, 'enableCliBackends' | 'agentReachEnabled'>, dep: {
     available: boolean;
     diagnostic?: string;
-}): {
+}, env?: Readonly<Record<string, string | undefined>>): {
     available: boolean;
     note?: string;
 };
+/**
+ * The "常用" (common) sources and whether each can run now. Without a key it is not in the default chain; the line says how to configure it.
+ * `providers` is the registry report; a stub router without one reports none.
+ */
+export declare function commonSources(providers: ProviderReport[] | undefined): {
+    common?: {
+        id: string;
+        label: string;
+        ready: boolean;
+        setup?: string;
+    }[];
+};
+/** Revision, overridden keys and validity of the agent overlay, for `sources.status`. */
+export declare function overlayState(overlay: OverlayStore): {
+    revision: number;
+    keys: string[];
+    valid: boolean;
+    problem?: string;
+};
 export declare const SOURCES_ACTIONS: ActionDef[];

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,