dsh-web-search-pro 0.2.1 → 0.2.3

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

@@ -0,0 +1,19 @@
+/**
+ * The trial run of a custom CLI spec (settings card, "Try it"): what a search with the draft spec would do, shown before it is saved.
+ * It is a real run, not a simulation: the spec is validated by the rule every spec goes through (the read-only guard, no shell, no
+ * credentials in argv), the command is probed (version and help only), then ONE search for the sample query runs through the same
+ * runner with the spec's own timeout and output cap. The first results and the tool's own words come back; secrets are redacted,
+ * a login is never run, and nothing is stored.
+ * @module web-search-pro/cli/trial
+ */
+import { type runCli } from '../util.ts';
+import type { TrialResult } from '../rpc-types.ts';
+export interface TrialOptions {
+    /** `enableCliBackends`: with it off no custom command runs, trial or search. */
+    enabled: boolean;
+    signal?: AbortSignal;
+    /** Test seams. */
+    run?: typeof runCli;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function trialCli(id: string, rawSpec: unknown, query: string, options: TrialOptions): Promise<TrialResult>;

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

@@ -1,2 +1,18 @@
+/**
+ * The Web Search Pro settings card, as the Plugins page renders it.
+ *
+ * The page owns the card frame (its title, disclosure and artwork come from the slot registration), so this component renders
+ * only what goes inside: the one-liner for `view: 'summary'`, and for `view: 'page'` a status summary, twelve groups (only
+ * "Common" open) and a save bar that stays in view.
+ *
+ *   Common · Search order · Sources · Custom CLI · Reading and evidence · Scoring model · Built-in web tool route ·
+ *   Runtime and backends · Network and cache · Ranking weights · Agent changes · Advanced: text mode and raw JSON
+ *
+ * Each group is its own module (`group-*.tsx`) built from the controls in `ui-kit.tsx`: the Host's own switches, buttons,
+ * badges, dialogs and help bubbles, plus the few controls the Host has no component for. Every public config field has
+ * exactly one entry in the groups (test/settings-card-render.test.ts counts them); the text of the last group is a view of
+ * the same fields, not a second place they live.
+ * @module web-search-pro/client/SettingsCard
+ */
 import type { SettingsCardProps } from './index.ts';
-export declare function SettingsCard(props: SettingsCardProps): string | import("react").JSX.Element | null;
+export declare function SettingsCard(props: SettingsCardProps): import("react").JSX.Element;

package/lib/types/client/agent-mark.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The mark beside a setting that an agent changed with `config.*`: "Changed by agent", whose tooltip says what the agent set, what the
+ * configuration holds, why and when, and (outside the cramped list rows) the two buttons that settle it: adopt the value into the
+ * configuration, or revoke it. The data is the plugin's overlay, read once over the card's RPC channel when the panel opens and again
+ * on the refresh button (see group-agent.tsx).
+ * @module web-search-pro/client/agent-mark
+ */
+import type { OverlayItem } from '../overlay-types.ts';
+import type { Card } from './field-rows.tsx';
+/** The overlay item of a key in the card's state, or undefined. */
+export declare function useOverlayItem(card: Card, key: string): OverlayItem | undefined;
+/** One sentence for the tooltip: the value the agent set, the one in the configuration, the reason, who and when. */
+export declare function agentTip(t: Card['t'], item: OverlayItem): string;
+/**
+ * `compact` shows the tag only (list rows have no room for buttons; the "Agent changes" group holds them); otherwise the tag is followed
+ * by "Adopt into configuration" and "Revoke".
+ */
+export declare function AgentMark({ card, itemKey, compact }: {
+    card: Card;
+    itemKey: string;
+    compact?: boolean;
+}): import("react").JSX.Element | null;

package/lib/types/client/card-frame.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The frame around the groups: the status summary on top (with the warnings dialog) and the save bar at the bottom.
+ *
+ * The Host's `SettingsForm` offers one save button below the controls. This card needs the bar to stay in view while a long
+ * page scrolls, to say how many edits are waiting, and to offer "Discard", so the frame is built here; the behaviors a
+ * settings form has are kept: it says so when the settings are not served or read-only, and it drops the staged edits when
+ * the page is left.
+ * @module web-search-pro/client/card-frame
+ */
+import { type ReactNode } from 'react';
+import { type ChainInput } from '../default-chain.ts';
+import { type Card } from './field-rows.tsx';
+import type { WebSearchCardState } from './form.ts';
+/** What the default chain rule reads from the staged settings: the list, the preferences, the ready common sources, the policy. */
+export declare function chainInputOf(snapshot: Pick<WebSearchCardState, 'fields' | 'credentials'>): ChainInput;
+/** The chain a plain search would try, from the staged settings; undefined when the draft leaves nothing to try. */
+export declare function chainOf(snapshot: Pick<WebSearchCardState, 'fields' | 'credentials'>): string[] | undefined;
+/**
+ * The chain a plain search tries once the agent's changes (engines, priority, disabled of the overlay) are on top of the staged settings,
+ * by the same rule; undefined while the agent changed none of the three, an empty list when it would leave nothing to try.
+ */
+export declare function agentChainOf(snapshot: Pick<WebSearchCardState, 'fields' | 'credentials' | 'server'>): string[] | undefined;
+/** Everything the warnings badge counts: what the validation says about a field, and the rubric problems. */
+export declare function warningsOf(snapshot: WebSearchCardState, t: Card['t']): string[];
+export declare function SummaryBar({ card }: {
+    card: Card;
+}): import("react").JSX.Element;
+export declare function SaveBar({ card }: {
+    card: Card;
+}): import("react").JSX.Element;
+/** The page frame: nothing but a notice while the settings are not served; the staged edits are dropped when the page is left. */
+export declare function Frame({ card, children }: {
+    card: Card;
+    children: ReactNode;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,97 @@
+/**
+ * The form side of the custom CLI editor: a `cliAdapters` entry (the JSON spec) as the fields of the edit dialog and back. Two
+ * views of one object: the form writes the keys it has controls for onto a copy of the spec and leaves every other key as it
+ * was (searches, read, env, login, errorCodes, a field mapping that is not a plain path), and the JSON box edits the whole spec.
+ * Validation is `validateCliAdapterSpec`, the function the server registers specs with; its messages are sorted to the field they
+ * are about. `allowedSubcommands` is derived from the command words of the argv templates, never typed.
+ * Pure: no Host, no DOM.
+ * @module web-search-pro/client/cli-form
+ */
+import { WHOLE_OUTPUT_DEFAULT_CHARS, type OutputFormat } from '../cli/spec.ts';
+type Json = Record<string, unknown>;
+/** The result fields the form maps, in display order; each takes a dotted path into one item of the tool's output. */
+export declare const FIELD_KEYS: readonly ["url", "title", "snippet", "publishedAt"];
+export type FieldKey = typeof FIELD_KEYS[number];
+/** How a plain text tool's lines become items (`whole` is a switch of its own). */
+export declare const LINE_MODES: readonly ["url-lines", "tsv"];
+export type LineMode = typeof LINE_MODES[number];
+export interface CliForm {
+    /** The key in `cliAdapters` (`custom-cli:<id>` everywhere else). */
+    id: string;
+    /** The command: a name on PATH, never a path. */
+    bin: string;
+    /** The argument template, one token per entry; `{query}`, `{count}` and `{terms}` are filled in. */
+    argv: string[];
+    format: OutputFormat;
+    /** Text output only: the whole stdout is one result (no field mapping). */
+    whole: boolean;
+    wholeMax: string;
+    /** json / yaml: dotted path of the result array (empty = the root array or the first array found). */
+    itemsPath: string;
+    linesMode: LineMode;
+    /** tsv: the column names, comma separated. */
+    columns: string;
+    /** A plain dotted path per result field; a mapping that is more than a path is kept as it is and listed in `complex`. */
+    fields: Record<FieldKey, string>;
+    complex: FieldKey[];
+    timeoutMs: string;
+    maxOutputBytes: string;
+    /** The purposes: a general search engine, and/or the platforms whose backend chain it may sit in. */
+    engine: boolean;
+    platforms: string[];
+    /** Empty = the default (0.5). */
+    confidence: string;
+    packageNote: string;
+    /** The probe: the help command (space separated) and the fragments its output must contain. */
+    helpArgs: string;
+    mustContain: string[];
+}
+/** The spec a new entry starts from: a JSON-printing tool mapped url / title / snippet. The form fills the command in. */
+export declare function newSpec(): Json;
+/** The example of the dialog: `echo`, whose whole output is the result (no field mapping), a way to see the pieces work without a real tool. */
+export declare function echoSpec(): Json;
+/** The form fields of a spec (plain or not): everything the dialog shows, as text. */
+export declare function specToForm(id: string, raw: unknown): CliForm;
+/** The command words the argv templates of a spec use, in order, without repeats: what `allowedSubcommands` must list. */
+export declare function derivedSubcommands(spec: Json): string[];
+/**
+ * The spec the form describes, built on `base` (the entry as it was: every key the form has no control for is kept). Nothing is
+ * validated here; a value that is not what its box wants is written as typed so `validateCliAdapterSpec` names it.
+ */
+export declare function formToSpec(form: CliForm, base?: Json): Json;
+/** The names of the dialog's fields that an error message can be about. */
+export type ErrorField = 'id' | 'bin' | 'argv' | 'format' | 'itemsPath' | 'lines' | 'fields' | FieldKey | 'timeoutMs' | 'maxOutputBytes' | 'platforms' | 'engine' | 'confidence' | 'packageNote' | 'probe' | 'general';
+/** Sort the validator's messages (`cliAdapters.<id>.<path>: ...`) to the dialog field they are about. */
+export declare function errorsByField(id: string, errors: readonly string[]): Partial<Record<ErrorField, string[]>>;
+export interface CliCheck {
+    spec: Json;
+    /** The validator's messages (empty = valid). */
+    errors: string[];
+    byField: Partial<Record<ErrorField, string[]>>;
+    ok: boolean;
+}
+/** Build the spec of a form and validate it the way the server does; `taken` are the ids of the other entries (a new id may not repeat one). */
+export declare function checkForm(form: CliForm, base: Json, taken?: readonly string[]): CliCheck;
+/** Validate a spec (the JSON view): the server's function, plus the one rule only the editor has (an id is not used twice). */
+export declare function checkSpec(id: string, spec: Json, taken?: readonly string[]): CliCheck;
+/** The confidence the entry has: its own, else the default. */
+export declare const confidenceOfForm: (form: CliForm) => number;
+export { WHOLE_OUTPUT_DEFAULT_CHARS };
+/** The JSON text of a spec as the dialog's raw box prints it. */
+export declare const specText: (spec: Json) => string;
+/** The spec a raw JSON text holds, or the reason it is not one. */
+export declare function parseSpecText(text: string): {
+    spec: Json;
+} | {
+    error: string;
+};
+/** The `cliAdapters` object of the staged text (empty text = no entries); undefined when it is not an object. */
+export declare function adaptersOf(text: string): Json | undefined;
+/**
+ * The `cliAdapters` text with entry `id` set to `spec` (a new key goes last), or removed when `spec` is undefined. The other
+ * entries are kept as they were. The object with no entries comes back as the empty text, which the form model stores as "not set".
+ * Undefined when the current text is not an object (the raw JSON box has to be fixed first).
+ */
+export declare function withAdapter(text: string, id: string, spec: Json | undefined): string | undefined;
+/** A free id for a copy or a new entry: `base`, `base-2`, `base-3`, ... */
+export declare function freeId(base: string, taken: readonly string[]): string;

package/lib/types/client/field-docs.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The comment printed in front of every key of the text view ("Advanced: text mode"), in the language of the card: what the
+ * setting is for, its allowed values or range, its default, and the risk when there is one. Comment lines start with `#`, so
+ * the text stays valid YAML and a round trip never reads a comment as data. Pure (it imports only config-groups.ts): the text view and the
+ * tests read it, and the client bundle includes it. Nothing here names a secret value: keys are only ever referenced by name.
+ * @module web-search-pro/client/field-docs
+ */
+export type DocLang = 'en' | 'zh';
+/** The doc of a config field in a language; undefined only for a field the card does not know. */
+export declare function fieldDoc(field: string, lang?: DocLang | string): string | undefined;
+/** The docs of the groups of keys and the header of the text view. */
+export declare function textViewDocs(lang?: DocLang | string): {
+    header: readonly string[];
+    group: Readonly<Record<string, string>>;
+};

package/lib/types/client/field-keys.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Which dictionary entry names a field, which fields carry a `?` text of their own, and the facts about the sources the
+ * card lists. Pure data (no imports): the rows, the text view and the tests all read it.
+ * @module web-search-pro/client/field-keys
+ */
+import { type ConfigGroupId } from '../config-groups.ts';
+export declare function labelKey(field: string): string;
+/** The fields whose dictionary has a `<key>Help` text (a longer explanation behind the `?`). */
+export declare const WITH_HELP: ReadonlySet<string>;
+/** `?` text applies to the generic budget keys too. */
+export declare const hasHelp: (field: string) => boolean;
+/** Dictionary key of the sentence saying why a start-up-only field needs a plugin restart (restart.ts lists the fields). */
+export declare function restartWhyKey(field: string): string;
+export type SourceTier = 'paid' | 'free-quota' | 'anonymous';
+/** One source the "Sources" list shows and its edit dialog is made of. */
+export interface SourceDef {
+    id: string;
+    name: string;
+    tier: SourceTier;
+    /** "常用": the plugin's recommended source (pinned to the registry descriptors by a test). */
+    common?: boolean;
+    /** The write-only key of the source (`CredentialId`), and the field naming the credential / variable it is stored under. */
+    credential?: string;
+    envField?: string;
+    defaultEnv?: string;
+    baseUrlField?: string;
+    /** Other fields the dialog holds, in order. */
+    extra?: readonly string[];
+    /** The request budget of the source (`sources.budget.<id>.total|daily`). */
+    budget?: boolean;
+}
+export declare const SOURCE_DEFS: readonly SourceDef[];
+/** Fields of a source dialog in display order (the key itself is a credential, not a field). */
+export declare function sourceFields(def: SourceDef): string[];
+/** Fields shown as JSON objects, each in its own dialog: the field, the group it sits in. */
+export declare const JSON_FIELDS: readonly {
+    field: string;
+    group: 'judge' | 'runtime' | 'platform' | 'advanced';
+}[];
+/** Group of the text view of any field: the group of its top-level key (see config-groups.ts, the one list of the layout). */
+export declare function textGroupOf(field: string): ConfigGroupId;

package/lib/types/client/field-rows.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Rows for the configuration fields the groups edit, wired to the card's staged form state.
+ *
+ * One component per control kind (switch, select, text, number, list of ids). Each is the single entry of its field: it renders
+ * `data-wsp-field="<field>"`, which test/settings-card-render.test.ts counts, and it reads the label, the one-line hint and the
+ * optional `?` text from the dictionary by the field's name (`<key>`, `<key>Hint`, `<key>Help`, see field-keys.ts).
+ * @module web-search-pro/client/field-rows
+ */
+import type { SettingsCardProps } from './index.ts';
+import type { CardFieldState, WebSearchCardState } from './form.ts';
+import { fill } from './fill.ts';
+import { type RowLabels, type SelectOption } from './ui-kit.tsx';
+export type Card = SettingsCardProps;
+export type Translator = Card['t'];
+export type LabelKey = Parameters<Translator>[0];
+export { fill };
+export declare function rowLabels(t: Translator): RowLabels;
+/** The id of a field's control, tied to its label. */
+export declare const controlId: (field: string) => string;
+/** The units a number field is written with. */
+declare const UNIT_KEYS: {
+    readonly ms: "unitMs";
+    readonly sec: "unitSeconds";
+    readonly chars: "unitChars";
+    readonly count: "unitCount";
+    readonly tokens: "unitTokens";
+    readonly days: "unitDays";
+    readonly rounds: "unitCount";
+};
+export type Unit = keyof typeof UNIT_KEYS;
+export interface FieldProps {
+    card: Card;
+    /** The setting field this row is the entry of. */
+    field: string;
+    /** Replaces the dictionary hint. */
+    hint?: string;
+    placeholder?: string;
+    /** Replaces the dictionary label. */
+    label?: string;
+    /** A short warning badge beside the label. */
+    risk?: string;
+    /** Hide the "overridden" badge and reset: for fields whose "default" is a computed one. */
+    code?: boolean;
+}
+/** How many of these fields carry an override: the number a group's badge shows. */
+export declare function useOverriddenCount(card: Card, fields: readonly string[]): number;
+/** The staged state of a field. */
+export declare const stateOf: (snapshot: WebSearchCardState, field: string) => CardFieldState | undefined;
+export declare function useField(card: Card, field: string): {
+    state: CardFieldState;
+    disabled: boolean;
+    edit: (text: string) => void;
+    reset: () => void;
+};
+/** A boolean field as a switch. */
+export declare function SwitchRow(props: FieldProps): import("react").JSX.Element;
+/** An enumerated field as a drop-down. */
+export declare function SelectRow(props: FieldProps & {
+    options: readonly SelectOption[];
+}): import("react").JSX.Element;
+/** A free-text field. */
+export declare function TextRow(props: FieldProps): import("react").JSX.Element;
+/** A number field with its unit written after the input. */
+export declare function NumberRow(props: FieldProps & {
+    unit?: Unit;
+}): import("react").JSX.Element;
+declare const parseList: (text: string) => string[];
+/** A comma-separated list (engine ids, domains) as removable chips with an add box. */
+export declare function ListRow(props: FieldProps): import("react").JSX.Element;
+export { parseList };

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

@@ -0,0 +1,2 @@
+/** Fill `{name}` placeholders of a dictionary entry. */
+export declare const fill: (text: string, values: Record<string, string | number>) => string;

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

@@ -12,7 +12,7 @@
  */
 export type Json = Record<string, unknown>;
 /** Top-level config fields (one Host write each). */
-export type TopField = 'engines' | 'parallelEngines' | 'searchMaxResults' | 'timeoutMs' | 'fetchDefaultChars' | 'exaContentsPerUrlChars' | 'exaContentsTotalChars' | 'exaApiKeyEnv' | 'jinaApiKeyEnv' | 'githubTokenEnv' | 'bochaApiKeyEnv' | 'bochaBaseUrl' | 'bochaSummary' | 'searxngUrl' | 'openalexMailto' | 'enableCliBackends' | 'opencliEnabled' | 'agentReachEnabled' | 'providerId' | 'registerProvider' | 'toolSurface' | 'playwright' | 'ttlSeconds' | 'memoryCacheEntries' | 'rrfConstant' | 'freshnessBoost' | 'freshnessDays' | 'authorityBoost' | 'authorityDomains' | 'dbPath' | 'allowProxyFakeIp' | 'platformRules' | 'customPlatforms' | 'browserBindings' | 'platformBackends' | 'cliAdapters' | 'verbose';
+export type TopField = 'engines' | 'parallelEngines' | 'searchMaxResults' | 'timeoutMs' | 'fetchDefaultChars' | 'exaContentsPerUrlChars' | 'exaContentsTotalChars' | 'exaApiKeyEnv' | 'jinaApiKeyEnv' | 'githubTokenEnv' | 'twitterAuthTokenEnv' | 'twitterCt0Env' | 'bochaApiKeyEnv' | 'bochaBaseUrl' | 'bochaSummary' | 'deepseekFetch' | 'searxngUrl' | 'openalexMailto' | 'enableCliBackends' | 'opencliEnabled' | 'agentReachEnabled' | 'providerId' | 'registerProvider' | 'toolSurface' | 'playwright' | 'ttlSeconds' | 'memoryCacheEntries' | 'rrfConstant' | 'freshnessBoost' | 'freshnessDays' | 'authorityBoost' | 'authorityDomains' | 'dbPath' | 'allowProxyFakeIp' | 'platformRules' | 'customPlatforms' | 'browserBindings' | 'platformBackends' | 'cliAdapters' | 'verbose';
 /** Options inside `evidence` / `provider`, addressed by their dotted config path. */
 export type PathField = 'evidence.autoProviders' | 'evidence.sourcePolicy' | 'evidence.maxRounds' | 'evidence.maxQueries' | 'evidence.judge.mode' | 'evidence.hybridBorderline' | 'evidence.judge.provider' | 'evidence.maxJevQuestions' | 'evidence.judge.allowLlm' | 'evidence.judge.providers' | 'evidence.coverage.mode' | 'evidence.coverage.provider' | 'evidence.coverage.thresholds.weak' | 'evidence.coverage.thresholds.covered' | 'evidence.budget.perSearchInputTokens' | 'evidence.budget.dailyInputTokens' | 'evidence.budget.timezone' | 'evidence.budget.providers' | 'provider.evidence' | 'provider.deadlineMs' | 'sources.priority' | 'sources.disabled';
 /** One rubric override entry (`evidence.rubrics.<id>`) and one keyed-source field. */
@@ -20,7 +20,9 @@ export type RubricField = `evidence.rubrics.${string}`;
 export type KeyedField = `keyedSources.${string}.apiKeyEnv` | `keyedSources.${string}.baseUrl`;
 /** One axis of one source's request budget (`sources.budget.<id>.total|daily`). */
 export type BudgetField = `sources.budget.${string}.${'total' | 'daily'}`;
-export type SettingField = TopField | PathField | RubricField | KeyedField | BudgetField;
+/** The confidence of one source or platform backend (`sources.confidence.<id>`): the ids are open, so these fields are made on demand. */
+export type ConfidenceField = `sources.confidence.${string}`;
+export type SettingField = TopField | PathField | RubricField | KeyedField | BudgetField | ConfidenceField;
 export type RootKey = 'evidence' | 'provider' | 'keyedSources' | 'sources';
 export type FieldWrite = {
     kind: 'set';
@@ -89,8 +91,11 @@ export declare const DEFAULTS: {
     };
     readonly toolSurface: "indexed";
     readonly bochaApiKeyEnv: "BOCHA_SEARCH_API_KEY";
+    readonly twitterAuthTokenEnv: "TWITTER_AUTH_TOKEN";
+    readonly twitterCt0Env: "TWITTER_CT0";
     readonly bochaBaseUrl: "https://api.bocha.cn";
     readonly bochaSummary: true;
+    readonly deepseekFetch: false;
 };
 /** Top-level fields, in display order. */
 export declare const FIELD_SPECS: readonly FieldSpec[];
@@ -105,11 +110,15 @@ export declare const KEYED_SPECS: readonly PathSpec[];
 /** The sources the card has a request budget for: Bocha and the keyed sources (any registered id works in settings.yaml). */
 export declare const BUDGETED_SOURCES: readonly string[];
 export declare const BUDGET_SPECS: readonly PathSpec[];
+/** `sources.confidence.<id>`: a number 0..1; empty = the default (1 for a built-in source, the spec's own for a custom CLI). */
+export declare const confidenceSpec: (id: string) => PathSpec;
+export declare const confidenceField: (id: string) => ConfidenceField;
+export declare const CONFIDENCE_PREFIX = "sources.confidence.";
 /** The spec of a rubric override entry: the whole object as one JSON draft, which the rubric editor builds field by field. */
 export declare const rubricSpec: (id: string) => PathSpec;
 export declare const rubricField: (id: string) => RubricField;
 /** Fields that a Host write can never take as text (credentials go through the credentials remote). */
-export declare const CREDENTIAL_IDS: readonly ["exa", "jina", "github", "bocha", ...`keyed:${string}`[]];
+export declare const CREDENTIAL_IDS: readonly ["exa", "jina", "github", "bocha", "twitter-auth-token", "twitter-ct0", ...`keyed:${string}`[]];
 export type CredentialId = typeof CREDENTIAL_IDS[number];
 /** The settings field holding the credentials ref / environment variable name of each credential, and its default name. */
 export declare function credentialRef(id: CredentialId): {

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

@@ -2,7 +2,8 @@ import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
 import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
 import { type RubricKind } from '../pipeline/rubrics-spec.ts';
 import type { Context } from './context-types.ts';
-import { BUDGET_SPECS, CREDENTIAL_IDS, FIELD_SPECS, KEYED_SPECS, PATH_SPECS, type CredentialId, type SettingField } from './form-specs.ts';
+import { BUDGET_SPECS, CREDENTIAL_IDS, FIELD_SPECS, KEYED_SPECS, PATH_SPECS, type CredentialId, type FieldSpec, type SettingField } from './form-specs.ts';
+import { type OverlayView, type StatusView, type TrialRequest, type TrialResult } from '../rpc-types.ts';
 export { BUDGET_SPECS, CREDENTIAL_IDS, FIELD_SPECS, KEYED_SPECS, PATH_SPECS };
 export type { CredentialId, SettingField };
 export interface CardFieldState {
@@ -45,10 +46,42 @@ export interface RubricCardState {
     invalid: boolean;
     problems: string[];
 }
+/** What the card knows of the agent overlay (the settings an agent changed with `config.*`), read over the RPC channel. */
+export interface OverlayCardState {
+    loading: boolean;
+    /** The channel answered with an error, or there is none. */
+    failed: boolean;
+    /** An adopt or revoke is running: the buttons wait. */
+    busy: boolean;
+    /** The last adopt / revoke that did not go through, as a dictionary key with its `{why}`. */
+    error?: {
+        key: 'agentAdoptFailed' | 'agentAdoptHalf' | 'agentRevokeFailed';
+        why?: string;
+    };
+    view?: OverlayView;
+}
+/** What the card knows from the running plugin over its private RPC channel (rpc-types.ts); empty where the Host has no transport. */
+export interface ServerState {
+    /** The Host has the transport: live readiness and "Try it" are possible. */
+    available: boolean;
+    loading: boolean;
+    failed: boolean;
+    status?: StatusView;
+    /** The trial run of a custom CLI draft: idle, running, or the last outcome. */
+    trial: {
+        state: 'idle' | 'running' | 'done' | 'failed';
+        id?: string;
+        result?: TrialResult;
+        error?: string;
+    };
+    overlay: OverlayCardState;
+}
 export interface WebSearchCardState {
     available: boolean;
     writable: boolean;
     dirty: boolean;
+    /** How many staged edits a save would write: fields whose draft differs from what is stored, plus pending secrets. */
+    changes: number;
     invalid: boolean;
     saving: boolean;
     failed: boolean;
@@ -57,9 +90,16 @@ export interface WebSearchCardState {
     /** Ids the judge / coverage provider controls offer: the presets plus the valid custom entries of the draft. */
     providerChoices: string[];
     rubrics: RubricCardState[];
+    /** Settings read only when the plugin starts (restart.ts) that have an edit waiting to be saved: a save would not take effect until a restart. */
+    restartTouched: string[];
     /** Overrides in settings that name no built-in rubric. */
     unknownRubrics: string[];
+    server: ServerState;
 }
+/** Every field spec of the form model, in display order. */
+export declare const ALL_SPECS: readonly FieldSpec[];
+/** The specs of the dynamic fields among `fields` (the text view prints them next to the fixed ones). */
+export declare function dynamicSpecsOf(fields: Readonly<Record<string, unknown>>): FieldSpec[];
 export declare class WebSearchSettingsController {
     private readonly scope;
     private readonly ctx;
@@ -75,7 +115,26 @@ export declare class WebSearchSettingsController {
     private credentialGeneration;
     private credentialRefSignature;
     private credentialStates;
+    private server;
+    private trialGeneration;
     constructor(scope: ConfigForm<Record<string, unknown>>, ctx: Context);
+    /** The Host's RPC client, read when it is used (the service may arrive after the card was registered); undefined where there is none. */
+    private rpc;
+    /** Ask the plugin what is ready now (the same local probes as `sources.status`). Silent when the Host has no transport. */
+    refreshStatus(): Promise<void>;
+    private setOverlay;
+    /** Read what the agent overlay holds (once when the panel opens, and on the refresh button). Silent where the Host has no transport. */
+    refreshOverlay(): Promise<void>;
+    /** Drop overlay entries (keys, or `'all'`) as the user. The plugin audits it; the card shows the overlay as it is afterwards. */
+    revokeOverlay(keys: readonly string[] | 'all', adopted?: boolean): Promise<boolean>;
+    /**
+     * "Adopt into configuration": write the overlay item's value into the profile with the Host's atomic `mutate` (the same call the save bar
+     * makes, at the leaf the item is about), and only when that landed ask the plugin to drop the entry. A failed write leaves both as they were.
+     */
+    adoptOverlay(key: string): Promise<boolean>;
+    /** Run one search of a custom CLI draft (rpc-types.ts `trial`). The outcome lands in `server.trial`. */
+    runTrial(request: TrialRequest): Promise<void>;
+    clearTrial(): void;
     inject(): {
         hooks: {
             webSearchPro: SnapshotStore<WebSearchCardState>;
@@ -89,6 +148,12 @@ export declare class WebSearchSettingsController {
         save: () => void;
         discard: () => void;
         refreshCredentials: () => void;
+        refreshStatus: () => void;
+        refreshOverlay: () => void;
+        revokeOverlay: (keys: readonly string[] | "all") => void;
+        adoptOverlay: (key: string) => void;
+        runTrial: (request: TrialRequest) => void;
+        clearTrial: () => void;
     };
     snapshot(): WebSearchCardState;
     edit(field: SettingField, text: string): void;
@@ -107,6 +172,12 @@ export declare class WebSearchSettingsController {
     refreshCredentials(): Promise<void>;
     dispose(): void;
     private project;
+    /** The start-up-only settings (restart.ts) whose staged edit differs from what is stored. */
+    private restartTouched;
+    /** `playwright` is one JSON field; only its `snapshotDir` is a start-up setting (`enabled` is live). */
+    private snapshotDirTouched;
+    /** Staged fields that differ from what is stored (a pending reset counts only when something is stored). */
+    private changedFields;
     private decorate;
     private projectRubrics;
     /** The state of one control from the staged draft, else from the Host section. */
@@ -117,11 +188,18 @@ export declare class WebSearchSettingsController {
      * evidence settings the draft would produce are then checked with the server's own validators.
      */
     private analyze;
+    /**
+     * The Host ops of a top-level field. A container the schema does not declare volatile as a whole (`playwright`: its keys are)
+     * is written key by key; every other field is one `set` or one `unset`.
+     */
+    private topOps;
     private opsOf;
     private credentialPlan;
     private writeCredential;
     /** The credentials ref / environment variable name each key is read from, from the saved settings (else the default). */
     private credentialRefs;
+    /** The `sources.confidence.<id>` fields that hold a value now or in the draft: the card shows these ids with their values. */
+    private dynamicFields;
     private spec;
     private resolvedRoot;
     private sectionValue;

package/lib/types/client/group-advanced.d.ts

@@ -0,0 +1,9 @@
+/**
+ * "Advanced: text mode": the settings as one commented YAML text, to read or copy. It is a view of the controls (it prints
+ * the staged state, secrets excluded), not a second place the settings live. Every key has a comment in front of it.
+ * @module web-search-pro/client/group-advanced
+ */
+import { type Card } from './field-rows.tsx';
+export declare function AdvancedGroup({ card }: {
+    card: Card;
+}): import("react").JSX.Element;

package/lib/types/client/group-agent.d.ts

@@ -0,0 +1,20 @@
+/**
+ * "Agent changes": what an agent changed with the `config.*` actions, kept apart from the user's configuration. The plugin keeps those
+ * changes in a managed overlay file that takes effect at once and never edits the profile; this group lists every entry with the reason
+ * and time the agent gave, the newest audit records, and for each entry two buttons: "Adopt into configuration" (write the value into
+ * the profile with the card's atomic write, then drop the overlay entry) and "Revoke" (drop it). "Revoke all" empties the overlay, which
+ * also repairs a file the plugin had to ignore. The card reads the overlay once when it opens and on the refresh button.
+ * @module web-search-pro/client/group-agent
+ */
+import type { OverlayItem } from '../overlay-types.ts';
+import { type Card } from './field-rows.tsx';
+/** One overlay entry: what it is, the value the agent set against the one in the configuration, why and when, and the two buttons. */
+export declare function AgentItem({ card, item, busy, items }: {
+    card: Card;
+    item: OverlayItem;
+    busy: boolean;
+    items: readonly OverlayItem[];
+}): import("react").JSX.Element;
+export declare function AgentGroup({ card }: {
+    card: Card;
+}): import("react").JSX.Element;

package/lib/types/client/group-cli.d.ts

@@ -0,0 +1,52 @@
+/**
+ * "Custom CLI": the command-line tools the user adds, as a list (id, command, purpose, confidence, whether the spec is valid) and one
+ * edit dialog per tool. The dialog is a form over the same spec the JSON box holds ("View JSON" at the bottom): editing either side
+ * rewrites the other, every problem is the server's own message shown by the control it is about, "Done" puts the spec into the
+ * draft (only when it is valid), and "Try it" runs the draft once through the plugin. The entries live inside `cliAdapters`.
+ * @module web-search-pro/client/group-cli
+ */
+import { type CliCheck, type CliForm } from './cli-form.ts';
+import { type Card } from './field-rows.tsx';
+type Json = Record<string, unknown>;
+/** What the dialog holds: the spec (the source of truth), the form fields read from it, the JSON box text, and the trial's sample query. */
+export interface CliDraft {
+    mode: 'new' | 'edit';
+    id: string;
+    spec: Json;
+    form: CliForm;
+    jsonText: string;
+    jsonError?: string;
+    query: string;
+}
+export declare function draftOf(mode: 'new' | 'edit', id: string, spec: Json): CliDraft;
+/** The draft after a form edit: the spec is rebuilt from the fields on top of the spec as it was, the JSON text follows. */
+export declare function editForm(draft: CliDraft, patch: Partial<CliForm>): CliDraft;
+/** A new entry's id; an existing one cannot be renamed (copy it instead). */
+export declare function editId(draft: CliDraft, id: string): CliDraft;
+/** The draft after the JSON box changed: a text that parses becomes the spec and the form is read from it; one that does not leaves both alone. */
+export declare function editJson(draft: CliDraft, text: string): CliDraft;
+/** What the form of one custom CLI shows and edits; presentational (the dialog and the render test both mount it). */
+export declare function CliBody({ card, draft, check, disabled, onForm, onId, onJson, onQuery, onTrial }: {
+    card: Card;
+    draft: CliDraft;
+    check: CliCheck;
+    disabled: boolean;
+    onForm: (patch: Partial<CliForm>) => void;
+    onId: (id: string) => void;
+    onJson: (text: string) => void;
+    onQuery: (text: string) => void;
+    onTrial: () => void;
+}): import("react").JSX.Element;
+export declare function CliDialog({ card, initial, taken, onClose }: {
+    card: Card;
+    initial: CliDraft;
+    taken: readonly string[];
+    onClose: () => void;
+}): import("react").JSX.Element;
+export declare function CliList({ card }: {
+    card: Card;
+}): import("react").JSX.Element;
+export declare function CliGroup({ card }: {
+    card: Card;
+}): import("react").JSX.Element;
+export {};

package/lib/types/client/group-common.d.ts

@@ -0,0 +1,12 @@
+/**
+ * "Common": what nearly everyone touches, open by default (every other group starts closed): the default engine chain with the
+ * order a search would really try, the result count, parallel fusion, the tool surface, the proxy fake-IP switch, and the
+ * DeepSeek Search source (常用) with its page-reading switch.
+ * @module web-search-pro/client/group-common
+ */
+import { type Card } from './field-rows.tsx';
+/** The names of the common group's fields, in order. */
+export declare const COMMON_FIELDS: readonly ["searchMaxResults", "parallelEngines", "toolSurface", "allowProxyFakeIp", "deepseekFetch"];
+export declare function CommonGroup({ card }: {
+    card: Card;
+}): import("react").JSX.Element;

package/lib/types/client/group-judge.d.ts

@@ -0,0 +1,17 @@
+/**
+ * "Scoring model": the optional model judge (mode, provider, coverage judge, usage caps), its custom providers as a JSON list,
+ * and the judge prompts (rubrics) as a list: a row each (name, active version, default or overridden) and an edit dialog that
+ * puts the built-in text beside your override. The dialog edits the same staged entry the rest of the card writes on save.
+ * @module web-search-pro/client/group-judge
+ */
+import { BUILTIN_RUBRIC_IDS } from '../pipeline/rubrics-spec.ts';
+import { type Card } from './field-rows.tsx';
+/** The controls of one rubric override: each is a view of the one staged entry; the built-in text sits beside it. */
+export declare function RubricForm({ card, id }: {
+    card: Card;
+    id: string;
+}): import("react").JSX.Element;
+export { BUILTIN_RUBRIC_IDS };
+export declare function JudgeGroup({ card }: {
+    card: Card;
+}): import("react").JSX.Element;